Files

Tianyi Cui b84d4828a8 refactor(events): remove the agent/stream-chunk mirror of assistant/chunk

The loop recorded every model token delta as a durable `assistant/chunk`
session event AND emitted an identical live `agent/stream-chunk` Cordis event
one line later. Same StreamChunk, same turn/step; the emit added only the live
Agent handle, which the sole consumer discarded. This is the boundary-mirror
duplication the event-domain work removed for turn/step boundaries, applied to
the token stream — a follow-up the boundary RFC explicitly deferred.

The premise is settled: chunk persistence is authoritative (the proposal to
stop persisting chunks was rejected — replay/snapshots depend on it), so
`assistant/chunk` on `session/event` is the load-bearing token stream and
`agent/stream-chunk` is pure redundancy.

- Remove the `agent/stream-chunk` declaration + emit; drop the now-unused
  StreamChunk import from dsh-agent's types.
- Migrate `dsh-ui-stdio` (the only live consumer; ACP already reads
  assistant/chunk off session/event) to render assistant/chunk in its existing
  session/event listener. Consolidating to one listener also makes the
  inReasoning dim-SGR flag deterministic across chunk/boundary events (they no
  longer race across two listeners).
- Repoint the agent-loop tests (cancel/loop) and ui-stdio tests to the
  session/event assistant/chunk feed.
- New RFC (implemented/simplification/2026-07-02-remove-stream-chunk-mirror);
  amend the boundary RFC's retained-list entry to cross-link; update
  architecture, cookbook, event-domain-semantics, the ACP proposal, and the
  regenerated cordis catalog.

Snapshot goldens unchanged (ACP never used the mirror), confirming no
editor-facing transcript change.

2026-07-02 23:42:16 +08:00

4.0 KiB

Raw Blame History

RFC: Stop mirroring the token stream as an agent event

Status: implemented (accepted 2026-07-02)

Problem

The loop records every model token delta as a durable assistant/chunk session event AND emitted a parallel live agent/stream-chunk Cordis event carrying the identical data. In packages/core/agent-loop/src/loop.ts the two sat one line apart:

const chunkEvent = session.append('assistant/chunk', { turn, step, chunk })
chunkSeqs.push(chunkEvent.seq)
ctx.emit('agent/stream-chunk', agent, turn, step, chunk)   // ← the mirror

Durable: assistant/chunk: { turn, step, chunk }.
Live emit: agent/stream-chunk(agent, turn, step, chunk) — same StreamChunk, same turn/step.

The only thing the emit added over the session event was the live Agent handle, and the sole consumer discarded it (its handler signature was (_agent, _turn, _step, chunk)).

This is the same duplication the boundary-mirror removal eliminated for turn/step boundaries: a consumer had two sources of truth for one durable fact, and every change had to touch both. That RFC deferred the chunk stream ("assistant/chunk persistence remains load-bearing, so the chunk stream could later be evaluated as a mirror, but that is a separate decision") rather than bundling it in. This RFC is that separate decision.

The premise the deferral hinged on is settled: chunk persistence is authoritative and staying. The proposal to stop persisting chunks and keep only a transient live stream event was rejected — high-fidelity replay, partial failed streams, and snapshot replay all depend on the persisted assistant/chunk feed. So assistant/chunk on session/event is the durable, load-bearing token stream, and agent/stream-chunk is a pure redundant mirror of it.

Decision

Remove agent/stream-chunk from the agent event taxonomy. The token stream is read off session/event as assistant/chunk, the same feed persistence and replay already use — session/event is the single live transcript stream (assistant chunks, turn/step boundaries, tool activity, todos).

Consumers. The only production consumer that mattered — the ACP bridge (dsh-acp), the real editor-facing streaming surface — already renders assistant/chunk off session/event, never agent/stream-chunk, so it is unaffected. The stdio UI (dsh-ui-stdio, a disposable test REPL) was the sole live consumer; it already had a session/event listener (from the boundary migration), so its chunk rendering folded into that listener as an assistant/chunk case. Consolidating to one listener also removed a latent hazard: the inReasoning dim-SGR flag was previously shared across two separate listeners (agent/stream-chunk and session/event), so a chunk and a boundary racing on it had no defined order; a single listener over the append order makes the interleaving deterministic.

Scope

Removed: agent/stream-chunk.

Not touched:

assistant/chunk (the durable session event) — the authoritative token stream, kept exactly as-is. This RFC removes the LIVE MIRROR, not the persistence (the persistence-removal proposal was separately rejected — see above).
agent/steering — a live control signal with no durable twin, retained (its fate remains a separate future decision, per the boundary RFC).
agent/status, agent/error, agent/created/agent/disposed, agent/queued, agent/session-start — lifecycle/control events that are not transcript data and have no durable duplicate.

What we give up

A plugin can no longer observe token deltas from an Agent-first event. It subscribes to session/event and filters assistant/chunk (the Agent handle, if needed, is recovered from a session-id→agent map built from agent/created/agent/disposed, exactly as boundary consumers already do). No production consumer needed the live Agent at chunk time; this is the same acceptable trade the boundary-mirror removal made.

4.0 KiB Raw Blame History