Skip to main content

Experiments

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.

ACP Thread Bound AgentsBrowser Evaluate CDP Refactor