Files

Tianyi Cui c6d2eeea6b refactor(events): remove the agent/steering mirror emit

agent/steering was the last transient mirror of a durable session event:
drainSteering appended the durable steering/message {turn, content, source}
and emitted the identical fact one line later. Zero production listeners
existed — every steering consumer (hook bridges, goldens, deriveMessages)
reads the durable event — and the one regression test subscriber asserted
a fact the log already records.

Remove the declaration (dsh-agent types + JSDoc list + README row), the
emit in drainSteering (its ctx parameter goes too), and the emit line in
the loop-pseudocode blocks (loop.ts module doc, architecture.md); the
cordis catalog is regenerated. The regression test now pins source
preservation on the durable steering/message event. Live-notification
needs keep their surviving homes: agent/queued at enqueue time,
session/event at drain time.

RFC: docs/rfc/implemented/simplification/2026-07-04-remove-agent-steering-mirror.md
(moved from proposed/, amended to shipped reality). The three implemented
RFCs that stated the retention — the boundary-mirror removal, the
stream-chunk removal, and event-domain-semantics — are amended to point
at that RFC as the record of the removal, per implemented/AGENTS.md.
The rejected retire-mid-turn-steering RFC keeps its frozen text (it
records the declined proposal); the steering capability itself —
steer(), the durable event, continuation forcing — is untouched.

2026-07-04 15:36:40 +08:00

4.1 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 — not touched by THIS decision (a control signal, not the token stream). Its durable twin is steering/message, and the mirror emit was removed by its own follow-up: Remove the agent/steering mirror emit.
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.1 KiB Raw Blame History