mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-17 21:10:54 +00:00
a7d56e3554
* docs: add ACP thread-bound agents plan doc * docs: expand ACP implementation specification * feat(acp): route ACP sessions through core dispatch and lifecycle cleanup * feat(acp): add /acp commands and Discord spawn gate * ACP: add acpx runtime plugin backend * fix(subagents): defer transient lifecycle errors before announce * Agents: harden ACP sessions_spawn and tighten spawn guidance * Agents: require explicit ACP target for runtime spawns * docs: expand ACP control-plane implementation plan * ACP: harden metadata seeding and spawn guidance * ACP: centralize runtime control-plane manager and fail-closed dispatch * ACP: harden runtime manager and unify spawn helpers * Commands: route ACP sessions through ACP runtime in agent command * ACP: require persisted metadata for runtime spawns * Sessions: preserve ACP metadata when updating entries * Plugins: harden ACP backend registry across loaders * ACPX: make availability probe compatible with adapters * E2E: add manual Discord ACP plain-language smoke script * ACPX: preserve streamed spacing across Discord delivery * Docs: add ACP Discord streaming strategy * ACP: harden Discord stream buffering for thread replies * ACP: reuse shared block reply pipeline for projector * ACP: unify streaming config and adopt coalesceIdleMs * Docs: add temporary ACP production hardening plan * Docs: trim temporary ACP hardening plan goals * Docs: gate ACP thread controls by backend capabilities * ACP: add capability-gated runtime controls and /acp operator commands * Docs: remove temporary ACP hardening plan * ACP: fix spawn target validation and close cache cleanup * ACP: harden runtime dispatch and recovery paths * ACP: split ACP command/runtime internals and centralize policy * ACP: harden runtime lifecycle, validation, and observability * ACP: surface runtime and backend session IDs in thread bindings * docs: add temp plan for binding-service migration * ACP: migrate thread binding flows to SessionBindingService * ACP: address review feedback and preserve prompt wording * ACPX plugin: pin runtime dependency and prefer bundled CLI * Discord: complete binding-service migration cleanup and restore ACP plan * Docs: add standalone ACP agents guide * ACP: route harness intents to thread-bound ACP sessions * ACP: fix spawn thread routing and queue-owner stall * ACP: harden startup reconciliation and command bypass handling * ACP: fix dispatch bypass type narrowing * ACP: align runtime metadata to agentSessionId * ACP: normalize session identifier handling and labels * ACP: mark thread banner session ids provisional until first reply * ACP: stabilize session identity mapping and startup reconciliation * ACP: add resolved session-id notices and cwd in thread intros * Discord: prefix thread meta notices consistently * Discord: unify ACP/thread meta notices with gear prefix * Discord: split thread persona naming from meta formatting * Extensions: bump acpx plugin dependency to 0.1.9 * Agents: gate ACP prompt guidance behind acp.enabled * Docs: remove temp experiment plan docs * Docs: scope streaming plan to holy grail refactor * Docs: refactor ACP agents guide for human-first flow * Docs/Skill: add ACP feature-flag guidance and direct acpx telephone-game flow * Docs/Skill: add OpenCode and Pi to ACP harness lists * Docs/Skill: align ACP harness list with current acpx registry * Dev/Test: move ACP plain-language smoke script and mark as keep * Docs/Skill: reorder ACP harness lists with Pi first * ACP: split control-plane manager into core/types/utils modules * Docs: refresh ACP thread-bound agents plan * ACP: extract dispatch lane and split manager domains * ACP: centralize binding context and remove reverse deps * Infra: unify system message formatting * ACP: centralize error boundaries and session id rendering * ACP: enforce init concurrency cap and strict meta clear * Tests: fix ACP dispatch binding mock typing * Tests: fix Discord thread-binding mock drift and ACP request id * ACP: gate slash bypass and persist cleared overrides * ACPX: await pre-abort cancel before runTurn return * Extension: pin acpx runtime dependency to 0.1.11 * Docs: add pinned acpx install strategy for ACP extension * Extensions/acpx: enforce strict local pinned startup * Extensions/acpx: tighten acp-router install guidance * ACPX: retry runtime test temp-dir cleanup * Extensions/acpx: require proactive ACPX repair for thread spawns * Extensions/acpx: require restart offer after acpx reinstall * extensions/acpx: remove workspace protocol devDependency * extensions/acpx: bump pinned acpx to 0.1.13 * extensions/acpx: sync lockfile after dependency bump * ACPX: make runtime spawn Windows-safe * fix: align doctor-config-flow repair tests with default-account migration (#23580) (thanks @osolmaz)
97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
---
|
|
summary: "Holy grail refactor plan for one unified runtime streaming pipeline across main, subagent, and ACP"
|
|
owner: "onutc"
|
|
status: "draft"
|
|
last_updated: "2026-02-25"
|
|
title: "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.
|