Unified Runtime Streaming Refactor Plan

Ziel

Eine gemeinsame Streaming-Pipeline für main, subagent und acp liefern, damit alle Runtimes identisches Koaleszenz-, Chunking-, Zustellungsreihenfolge- und Crash-Recovery-Verhalten erhalten.

Warum das existiert

Das aktuelle Verhalten verteilt sich auf mehrere runtime-spezifische Shaping-Pfade.
Formatierungs-/Koaleszenz-Bugs können in einem Pfad behoben werden, bleiben aber in anderen bestehen.
Zustellungskonsistenz, Duplikat-Unterdrückung und Recovery-Semantik sind schwerer nachvollziehbar.

Zielarchitektur

Einzelne Pipeline, runtime-spezifische Adapter:

Runtime-Adapter emittieren nur kanonische Events.
Gemeinsamer Stream-Assembler koalesziert und finalisiert Text-/Tool-/Status-Events.
Gemeinsamer Kanalprojektor wendet kanalspezifisches Chunking/Formatierung einmal an.
Gemeinsames Zustellungsbuch erzwingt idempotente Send/Replay-Semantik.
Ausgehender Kanaladapter führt Sends aus und zeichnet Zustellungs-Checkpoints auf.

Kanonischer Event-Vertrag:

turn_started
text_delta
block_final
tool_started
tool_finished
status
turn_completed
turn_failed
turn_cancelled

Arbeitspakete

1) Kanonischer Streaming-Vertrag

Striktes Event-Schema + Validierung im Kern definieren.
Adapter-Vertragstests hinzufügen, um sicherzustellen, dass jede Runtime kompatible Events emittiert.
Fehlerhafte Runtime-Events frühzeitig ablehnen und strukturierte Diagnose ausgeben.

2) Gemeinsamer Stream-Prozessor

Runtime-spezifische Koaleszierer-/Projektor-Logik durch einen Prozessor ersetzen.
Prozessor besitzt Text-Delta-Pufferung, Idle-Flush, Max-Chunk-Splitting und Completion-Flush.
ACP-/Main-/Subagent-Konfigurationsauflösung in einen Helper verschieben, um Drift zu verhindern.

3) Gemeinsame Kanalprojektion

Kanaladapter einfach halten: finalisierte Blöcke annehmen und senden.
Discord-spezifische Chunking-Eigenheiten nur in den Kanalprojektor verschieben.
Pipeline vor der Projektion kanalunabhängig halten.

4) Zustellungsbuch + Replay

Per-Turn-/Per-Chunk-Zustellungs-IDs hinzufügen.
Checkpoints vor und nach dem physischen Send aufzeichnen.
Bei Neustart ausstehende Chunks idempotent replien und Duplikate vermeiden.

5) Migration und Umstellung

Phase 1: Shadow-Modus (neue Pipeline berechnet Ausgabe, alter Pfad sendet; Vergleich).
Phase 2: Runtime-für-Runtime-Umstellung (acp, dann subagent, dann main oder umgekehrt nach Risiko).
Phase 3: Legacy-runtime-spezifischen Streaming-Code löschen.

Nicht-Ziele

Keine Änderungen am ACP-Policy/Berechtigungsmodell in diesem Refactoring.
Keine kanalspezifische Feature-Erweiterung außer Projektions-Kompatibilitätsfixes.
Kein Transport-/Backend-Redesign (acpx-Plugin-Vertrag bleibt wie gehabt, es sei denn für Event-Parität nötig).

Risiken und Gegenmaßnahmen

Risiko: Verhaltensregressionen in bestehenden Main-/Subagent-Pfaden. Gegenmaßnahme: Shadow-Modus-Diffing + Adapter-Vertragstests + Kanal-E2E-Tests.
Risiko: Doppelte Sends während der Crash-Recovery. Gegenmaßnahme: Dauerhafte Zustellungs-IDs + idempotentes Replay im Zustellungsadapter.
Risiko: Runtime-Adapter driften erneut auseinander. Gegenmaßnahme: Verpflichtende gemeinsame Vertragstest-Suite für alle Adapter.

Akzeptanzkriterien

Alle Runtimes bestehen die gemeinsamen Streaming-Vertragstests.
Discord ACP/Main/Subagent erzeugen äquivalentes Spacing-/Chunking-Verhalten für kleine Deltas.
Crash/Restart-Replay sendet keinen doppelten Chunk für dieselbe Zustellungs-ID.
Legacy-ACP-Projektor-/Koaleszierer-Pfad ist entfernt.
Streaming-Konfigurationsauflösung ist gemeinsam und runtime-unabhängig.