​

Unified Runtime Streaming Refactor Plan

​

Objective

​

Why this exists

• Current behavior is split across multiple runtime-specific shaping paths.
• Formatting/coalescing bugs can be fixed in one path but remain in others.
• Delivery consistency, duplicate suppression, and recovery semantics are harder to reason about.

​

Target architecture

1. Runtime adapters emit canonical events only.
2. Shared stream assembler coalesces and finalizes text/tool/status events.
3. Shared channel projector applies channel-specific chunking/formatting once.
4. Shared delivery ledger enforces idempotent send/replay semantics.
5. Outbound channel adapter executes sends and records delivery checkpoints.

• turn_started
• text_delta
• block_final
• tool_started
• tool_finished
• status
• turn_completed
• turn_failed
• turn_cancelled

​

Workstreams

​

1) Canonical streaming contract

• Define strict event schema + validation in core.
• Add adapter contract tests to guarantee each runtime emits compatible events.
• Reject malformed runtime events early and surface structured diagnostics.

​

2) Shared stream processor

• Replace runtime-specific coalescer/projector logic with one processor.
• Processor owns text delta buffering, idle flush, max-chunk splitting, and completion flush.
• Move ACP/main/subagent config resolution into one helper to prevent drift.

​

3) Shared channel projection

• Keep channel adapters dumb: accept finalized blocks and send.
• Move Discord-specific chunking quirks to channel projector only.
• Keep pipeline channel-agnostic before projection.

​

4) Delivery ledger + replay

• Add per-turn/per-chunk delivery IDs.
• Record checkpoints before and after physical send.
• On restart, replay pending chunks idempotently and avoid duplicates.

​

5) Migration and cutover

• Phase 1: shadow mode (new pipeline computes output but old path sends; compare).
• Phase 2: runtime-by-runtime cutover (acp, then subagent, then main or reverse by risk).
• Phase 3: delete legacy runtime-specific streaming code.

​

Non-goals

• No changes to ACP policy/permissions model in this refactor.
• No channel-specific feature expansion outside projection compatibility fixes.
• No transport/backend redesign (acpx plugin contract remains as-is unless needed for event parity).

​

Risks and mitigations

• Risk: behavioral regressions in existing main/subagent paths. Mitigation: shadow mode diffing + adapter contract tests + channel e2e tests.
• Risk: duplicate sends during crash recovery. Mitigation: durable delivery IDs + idempotent replay in delivery adapter.
• Risk: runtime adapters diverge again. Mitigation: required shared contract test suite for all adapters.

​

Acceptance criteria

• All runtimes pass shared streaming contract tests.
• Discord ACP/main/subagent produce equivalent spacing/chunking behavior for tiny deltas.
• Crash/restart replay sends no duplicate chunk for the same delivery ID.
• Legacy ACP projector/coalescer path is removed.
• Streaming config resolution is shared and runtime-independent.