Files

T

Tianyi Cui e6fad266a6 docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus

Define the in-file RFC contract in docs/rfc/README.md § The file format:
the header block (`# RFC: <title>` plus a dateless Status enum
cross-checked against the lifecycle folder), the per-lifecycle body
skeleton (a Problem opener everywhere; Proposal/Alternatives considered/
Acceptance criteria/Risks in proposed/; present-tense Decision/
Consequences with proposal-era headings banned in implemented/; the
frozen proposal shape in rejected/), and a mandatory Alternatives
considered section with a date-fenced grandfather comment for pre-format
RFCs whose alternatives are not reconstructible from the record.

Enforce it with a new doc-sync gate, scripts/verify-rfc-format.ts, and
normalize all 112 RFCs to it: ~15 Status-line spellings collapse to the
enum, 29 Context openers become Problem, the 39 legacy-format XXX debt
markers are resolved and banned from reappearing, proposal-era sections
in implemented RFCs are rewritten to shipped reality (including the
web/fs/subagent seam RFCs' migration plans and test checklists, closing
the doc-tiers deferred-work item on the web seam), every RFC gains an
Alternatives considered section or the grandfather comment, and the
bilingual pair is re-mirrored and re-recorded.

Move the generated index tables out of README.md into a fully generated
docs/rfc/INDEX.md — gen-rfc-index now writes the whole file, and
verify-rfc-classification checks its freshness and rejects index-shaped
rows in the curated README — which makes room for the format contract to
live in the README front door instead of a separate FORMAT.md.

The decision record, and the first RFC written in the new format, is
docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md.

2026-07-05 22:58:25 +08:00

4.5 KiB

Raw Blame History

RFC: Stop mirroring the token stream as an agent event

Status: implemented

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.

Alternatives considered

Remove the persistence and keep only a transient live stream — the inverse cut, rejected separately: high-fidelity replay, partial failed streams, and snapshot replay all depend on the persisted assistant/chunk feed. With that settled, the live emit is the redundant half of the pair.

Consequences

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.5 KiB Raw Blame History