Unified Runtime Streaming Refactor Plan

Unified Runtime Streaming Refactor Plan

Objective

Deliver one shared streaming pipeline for main, subagent, and acp so all runtimes get identical coalescing, chunking, delivery ordering, and crash recovery behavior.

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

Single pipeline, runtime-specific adapters:

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.

Canonical event contract:

• 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.