> ## Documentation Index
> Fetch the complete documentation index at: https://cryptoclawdocs.termix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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