From cecc4c82c3890f35a798db804a33764286c0ae09 Mon Sep 17 00:00:00 2001 From: Ziya <199893125+ZiyaZhang@users.noreply.github.com> Date: Sun, 12 Jul 2026 19:34:22 -0700 Subject: [PATCH] rfc: drop the ACP surface binding, keep the mechanics surface-agnostic --- .../2026-07-08-interactive-side-sessions.md | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md b/docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md index 2ed5008356..79a40b66af 100644 --- a/docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md +++ b/docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md @@ -16,34 +16,33 @@ A **side session** is an ordinary live session forked from a source session at i - **Fork + attach composes existing primitives.** The child is created via `ctx.agents.create({ seed, meta })` with the parent's balanced completed-turn prefix (the same slice the fork subagent takes) and `parentSession`/`seedLength` lineage stamped in `meta`. No new core service and no session-store change, for the same reasons [the fork API RFC](../../implemented/feature/2026-06-30-session-store-fork-api.md) rejected a standalone fork service. - **Advisor framing rides the log, not the system prompt.** The rules ("you are a read-only side advisor; explain, do not mutate; refuse task continuation") are `inject()`ed as a `context/message` with source `{ kind: 'plugin', plugin: 'sidechat' }` immediately after creation. The child's system prompt stays byte-identical to the parent's, so the provider's prefix cache covers the inherited history. -- **Merge-back is one condense turn plus one injection.** `/merge` prompts the child for a bounded handback note (a hard length cap), then `inject()`s the note into the PARENT as a `context/message` with the same plugin source. The parent's next request sees it at its chronological position; replay and [reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) hold by construction; no new event type enters [the session vocabulary](../../../core-data-structures/session.md). -- **The v1 surface is the ACP bridge, with no new protocol capability.** The bridge intercepts `/side [question]` on a prompt: it stages the fork (bridge-local state, nothing appended to the source log) and the next `session/new` in the same workspace claims it, so the child appears to the editor as an ordinary second session under [multi-session](./2026-06-14-acp-multi-session.md). A plugin-sourced `context/message` renders as a visible message through the bridge's shared event translator, so the live stream and `session/load` replay derive the identical visible record from the same durable event — the handback's visibility is a projection of the log, never a live-only mirror. +- **Merge-back is one condense turn plus one injection.** The child is prompted for a bounded handback note (a hard length cap), which is then `inject()`ed into the PARENT as a `context/message` with the same plugin source. The parent's next request sees it at its chronological position; replay and [reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) hold by construction; no new event type enters [the session vocabulary](../../../core-data-structures/session.md). +- **The surface binding is deliberately unspecified.** How a user invokes the fork and the merge, and how a handback note is presented, are client concerns; while the harness speaks through protocols whose UI it does not control, this RFC pins only the surface-agnostic mechanics above and leaves presentation to the first surface the project owns. -v1 scope excludes: the stdio-agent surface (single-session readline today), rewind productization (mechanically the same fork-to-an-earlier-boundary, an entirely different product question), session tree views, a model-facing side-session tool, `forkName`/`mergedInto` metadata, and cross-connection persistence of a staged fork. +Scope also excludes: rewind productization (mechanically the same fork-to-an-earlier-boundary, an entirely different product question), session tree views, a model-facing side-session tool, and `forkName`/`mergedInto` metadata. ## Prototype -A bridge-level spike (branch `spike/side-sessions-b`) runs the full loop against the live adapter: `/side` staging with zero source-log writes, a claim that seeds the child with the full inherited prefix, a multi-turn advisor exchange that demonstrably uses parent history, and a merge-back the parent's next turn quotes correctly. +A spike (branch `spike/side-sessions-b`) validates the mechanics against the live adapter: a fork that leaves the source log untouched, a child seeded with the full inherited prefix, a multi-turn advisor exchange that demonstrably uses parent history, and a merge-back the parent's next turn quotes correctly. ## Alternatives considered - **Carry side conversations through the subagent seam.** Rejected: a subagent child is a model-driven run — the parent's model spawns it, drives it, and consumes its result as a tool result. A side session is user-driven, needs its own client-visible session and lifecycle, and must outlive any single parent turn. - **Persona via `system-prompt/assemble` section filtering.** Rejected as the default path: any system-prompt byte change invalidates the provider prefix cache from token 0, forfeiting the cheap fork that makes side sessions attractive on long histories. The filter seam remains available for deployments that prefer hard prompt separation over cache reuse. - **A dedicated `sidechat/*` event family for the handback.** Deferred: `context/message` with a mandatory plugin source already satisfies durability, provenance, and replay. A first-class event earns its catalog, persistence, and snapshot costs only if a UI needs to render handbacks as dedicated cards. -- **An ACP `session/fork` method now.** Deferred: the fork API RFC gates any ACP surface on transcript/snapshot coverage before the capability is advertised, and today's clients offer no fork affordance to call it from. Stage-and-claim ships the experience with zero protocol additions and can be replaced by the method transparently later. -- **A live-only transcript mirror for the handback.** Rejected in review: load replay deliberately ignores `context/message`, so a bridge-emitted `agent_message_chunk` would make the visible note vanish on `session/load` while the model still sees it. Rendering the durable `context/message` through the shared translator keeps live streaming and replay byte-identical. +- **Binding the proposal to a protocol surface now.** Rejected in review: the harness currently speaks through client-owned UIs it does not control, so any presentation contract written today would be speculative. The RFC pins the surface-agnostic mechanics and defers presentation to the first surface the project owns. +- **Surface-level mirroring of the handback.** Rejected in review: a visible record emitted outside the log vanishes on replay while the model still sees it. Whatever surface eventually renders the handback must derive its presentation from the durable `context/message`, so live and replayed views come from the same event. ## Acceptance criteria -- `/side` on a live ACP session appends nothing to that session's log; staging is bridge-local and consumed by exactly one claim. -- The claiming `session/new` yields a child seeded with the source's completed-turn prefix, with `parentSession` and `seedLength` in its header and a system prompt byte-identical to the parent's. -- `/merge` appends exactly one length-capped `context/message` to the parent with source `plugin: sidechat`; the parent's next request sees it, and `session/load` reproduces the visible handback note identically to the live stream — both derive from the same durable event. -- Parent and child stream concurrently without interleaving their `session/update` feeds (existing multi-session isolation). -- Coverage: bridge unit tests for the stage/claim/merge state machine over the in-memory transport, plus a keyless snapshot scenario exercising fork-claim and merge-back end to end. +- Forking a live session yields a child agent seeded with the source's balanced completed-turn prefix, with `parentSession` and `seedLength` in its header and a system prompt byte-identical to the parent's; the source log is untouched by the fork. +- The advisor framing is exactly one plugin-sourced `context/message` at the head of the child's appended history — never a system-prompt change. +- Merge-back appends exactly one length-capped `context/message` to the parent with source `plugin: sidechat`; the parent's next request sees it, and replay reproduces it at the same position. +- Parent and child run concurrently without cross-talk between their logs or streams. +- Coverage: unit tests for the fork/attach and merge-back mechanics; surface-level snapshot coverage lands with whichever surface first binds the feature. ## Risks -- **Read-only is advisory in v1.** The rules are injected context, not enforcement; a determined prompt can still drive mutating tools. The hard gate is a `tools/pre-execute` deny via [the interception seams](../../implemented/feature/2026-06-30-interception-seams.md), and the RFC's advisor framing is written so that gate can be added without changing the product surface. -- **The staged fork has one slot.** The next same-workspace `session/new` claims it even if the user meant an unrelated thread; the claim banner names the source session and the slot dies with the connection, but a mis-claim costs the user a discarded thread. -- **A compacted source forks its compacted view.** The child inherits the summary, not the original turns; the claim banner should disclose this once [compaction](../../implemented/feature/2026-06-18-compaction-capability-seam.md) ships in this path. -- **Handback notes spend parent tokens.** The length cap and one-note-per-`/merge` bound the cost, but a user who merges repeatedly accumulates notes; a future consolidation pass belongs to the compaction work, not this surface. +- **Read-only is advisory in v1.** The rules are injected context, not enforcement; a determined prompt can still drive mutating tools. The hard gate is a `tools/pre-execute` deny via [the interception seams](../../implemented/feature/2026-06-30-interception-seams.md), and the RFC's advisor framing is written so that gate can be added without changing the mechanics. +- **A compacted source forks its compacted view.** The child inherits the summary, not the original turns; whichever surface binds the feature should disclose this once [compaction](../../implemented/feature/2026-06-18-compaction-capability-seam.md) ships in this path. +- **Handback notes spend parent tokens.** The length cap and one-note-per-merge bound the cost, but a user who merges repeatedly accumulates notes; a future consolidation pass belongs to the compaction work, not here.