@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/acpSession.js

@@ -1,1047 +0,0 @@
-/**
- * One ACP session: `session/new`, `session/prompt`, `session/cancel`, `session/update` routing, and
- * the buffered event/turn sinks the deleted `BridgeSession` SPI required.
- *
- * Built on the SDK's `ClientContext.buildSession(cwd)` / `ActiveSession` convenience wrapper rather
- * than raw `session/new`/`session/prompt` requests: `ActiveSession.prompt(...)` both sends
- * `session/prompt` *and* enqueues the eventual response as a `{kind: 'stop', ...}` message onto the
- * exact same internal queue `nextUpdate()` reads `{kind: 'session_update', ...}` messages from — so
- * one continuous `nextUpdate()` loop (see {@link runReadLoop}) sees every `session/update` in order
- * interleaved with the turn's own completion, with no separate `.onNotification('session/update', …)`
- * registration needed. That registration would not even be possible after the fact in the way this
- * class is constructed (`AcpConnection` is already past `ClientApp.connect()` by the time
- * `AcpSession.open` runs, and `acpClient.ts` documents that `connect()` copies its handler
- * table at connect time) — `buildSession`'s routing is installed unconditionally by the SDK itself,
- * independent of anything a caller registers via `connectAgent`'s `configure` hook.
- *
- * One responsibility lives here rather than in `sessionUpdateMapper.ts`, because this is the layer
- * with a turn's whole lifetime in view, not just one `session/update` at a time:
- *
- * - **`agent_message` synthesis** (see {@link flushMessageCompleted}). The server's
- *   `CoworkEngine` buffers `agent_message_chunk`/`agent_thought_chunk` text and only flushes it on a ~400ms gap
- *   between deltas or on an item-backed event — ending the turn does not flush it. Both deleted
- *   bridges closed every assistant message with `agent_message` (item-backed, so it *is* the
- *   flush); nothing in ACP's own vocabulary plays that role, so this class synthesizes it — once
- *   when the streaming `messageId` changes mid-turn, and once more at turn end. The same event is
- *   also what makes the server attach a turn's `usage_update` figures
- *   (`CoworkEngine.appendCoworkTimelineEvent`'s `MessageCompleted` branch reads and clears
- *   `latestUsageByRun`) — without it those figures are captured and then silently discarded.
- *
- * **`user_message_chunk` folding used to be the second one, and is gone.** It lived here as a
- * per-session accumulator, and `adoption.ts` carried a second copy of the same rule for replay —
- * two implementations that had already drifted (replay split a message on any interleaved event;
- * this one did not). Phase 7 moved the fold to `CoworkEngine`, which was already buffering
- * `agent_message_chunk` by exactly the ACP rule that governs all three chunk kinds (`ContentChunk`,
- * `types.gen.d.ts:3456`: same `messageId` = same message). Chunks now pass straight through, and
- * the server's turn-end / replay-end flush is what closes a message.
- */
-import { randomUUID } from 'node:crypto';
-import { methods } from '@agentclientprotocol/sdk';
-import { jsonRpcErrorCode } from './acpClient.js';
-import { settleUpdates } from './adoption.js';
-import { mapSessionUpdate, SessionMapperState } from './sessionUpdateMapper.js';
-import { flatChoicesOf, modesAlreadyRepresented, normalizeConfigOptions, SYNTHESIZED_MODES_CONFIG_ID } from './configOptions.js';
-/**
- * A few ACP adapters reply to `session/prompt` before their last `session/update` notifications
- * have arrived. Those trailing chunks have no following turn boundary to synthesize
- * `agent_message`, so the server would keep them buffered until the reader sent another message.
- * This short quiet period lets a burst remain one message while ensuring it is rendered on its own.
- */
-const LATE_MESSAGE_SETTLE_MS = 250;
-/**
- * Points the connection's diverted-update stream at the session that owns it.
- *
- * **Belongs here, not in `AcpAgents`.** Both ways a session comes into existence run through this
- * file, and only one of them goes through the agent registry — the first attempt bound from there
- * and every test that opens a session directly then saw *every* update diverted, because an unbound
- * connection cannot tell its own session from a child's and must assume the worse case. Binding
- * where the session is constructed makes "a session exists" and "the transport knows about it" the
- * same moment.
- *
- * An empty id means the agent named no session, so nothing is bound and every update keeps being
- * reported rather than silently handed to an SDK that would drop it.
- */
-function bindDivertedUpdates(connection, ownSessionId, session) {
-    if (ownSessionId.length === 0)
-        return;
-    connection.bindDraftUpdates(ownSessionId, (update) => session.applyDivertedUpdate(update));
-}
-/**
- * The steering extension's JSON-RPC method. **Not an ACP method** — `grep steer` over the pinned
- * SDK's `dist/schema/types.gen.d.ts` returns nothing. It is implemented by `claude-agent-acp`
- * (`acp-agent.js@0.76.0:164`), whose own comment calls it a *"Custom (extension) request method ...
- * Named `_session/steering` per the agreed ACP steering wire protocol"*; the leading underscore is
- * ACP's extension namespace. It is therefore reached through the untyped `request<Response, Params>
- * (method: string, …)` overload rather than `methods.agent.*`, and every caller must check
- * {@link AcpConnection.supportsSteering} first.
- */
-const STEER_METHOD = '_session/steering';
-/**
- * Narrow a `_session/steering` response onto {@link SteerOutcome}, or throw.
- *
- * The extension answers with one of three outcomes (`acp-agent.js@0.76.0:1737`, `:1751`, `:1779`):
- *
- * - `injected` — a turn was running and the message went into it.
- * - `promptRequired` (with `reason: "noRunningTurn"`) — no turn was running and we opted in, so the
- *   agent did nothing at all and the content stays host-owned.
- * - `startedNewTurn` — no turn was running and the client did *not* opt in, so the agent detached a
- *   `prompt()` of its own.
- *
- * **`startedNewTurn` throws rather than mapping to anything** (decision D13). We always send
- * `idleBehavior: "promptRequired"` ({@link AcpSession.steer}), so receiving it means the agent
- * ignored the opt-in — and what it handed back is a turn nobody awaits: it never enters our queue,
- * never lands an item, and never produces a `turn_done`, in a system that accounts by turn.
- * Absorbing it as "injected" would mark a message delivered to a turn we are not tracking;
- * absorbing it as "promptRequired" would submit the same message a second time. Neither is a
- * recovery, so this fails where the contract broke, loudly enough to name.
- *
- * An outcome nobody recognises throws for the same reason: silently reading it as `injected` would
- * record a delivery that may never have happened.
- */
-export function mapSteerOutcome(result) {
-    const outcome = result?.outcome;
-    if (outcome === 'injected')
-        return 'injected';
-    if (outcome === 'promptRequired')
-        return 'promptRequired';
-    if (outcome === 'startedNewTurn') {
-        throw new Error(`[acp] the agent answered ${STEER_METHOD} with 'startedNewTurn', a turn this client never ` +
-            "opted into and does not track: we always send _meta.steering.idleBehavior = 'promptRequired'.");
-    }
-    throw new Error(`[acp] unrecognised ${STEER_METHOD} outcome: ${JSON.stringify(outcome)}`);
-}
-/**
- * The value `registerPendingApproval`'s resolver receives when nobody is ever going to answer —
- * the session closed, the connection died, or the agent itself cancelled the request — rather
- * than a real user choice. `PermissionOptionId` is an unconstrained `string`, so a fixed literal
- * like `'deny'` risks colliding with an agent's own option id and turning "nobody answered" into
- * a fabricated selection (review finding: task-5, item 6). Randomized per process start and never
- * sent over the wire to any agent, so no real option id can ever equal it in practice.
- */
-const ABANDONED_ANSWER = `__acp_session_abandoned_${randomUUID()}__`;
-/** ACP's `StopReason` (`end_turn | max_tokens | max_turn_requests | refusal | cancelled`) → the wire's `TurnStopReason`. `'cancelled'` is handled by the caller (it forces `status: 'interrupted'` instead, which carries no `stopReason` — see {@link AcpSession.finishTurn}), so it never actually reaches this function; the arm is kept so the switch stays exhaustive over every literal `StopReason` can hold. */
-function mapStopReason(reason) {
-    switch (reason) {
-        case 'end_turn':
-            return 'end_turn';
-        case 'max_tokens':
-            return 'max_tokens';
-        case 'max_turn_requests':
-            return 'max_turns';
-        case 'refusal':
-            return 'refusal';
-    }
-}
-function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-/**
- * One `_session/steering` round trip, shared verbatim by {@link AcpSession.open} and
- * {@link AcpSession.attach} — the two differ only in where the session id comes from.
- *
- * The request shape is the extension's `parseSteerRequest` (`acp-agent.js@0.76.0:192-215`): a non-empty
- * `sessionId`, a non-empty `prompt` array of ACP `ContentBlock`s, and an optional
- * `_meta.steering.idleBehavior` whose **only** accepted value is `promptRequired` — anything else is
- * `invalidParams`. We always send it; see {@link mapSteerOutcome} for why.
- *
- * `blocks` is ACP's own `ContentBlock[]`, exactly like {@link AcpSession.prompt} — **this boundary
- * used to narrow it to a `string`, and that narrowing was ours, not the protocol's**. The extension
- * takes a `prompt` array and hands it to the same `promptToClaude(params)` a `session/prompt` goes
- * through, so an image steers as well as it prompts. While this parameter was a `string`, an image
- * attached to a message the reader chose to interject stopped dead here — split off into a queue row
- * of its own, leaving *"this is what I mean"* next to nothing.
- *
- * `priority` is the extension's `_meta.steering.priority`. **`undefined` means the caller is
- * deliberately naming none**, and that is not the same as picking the default: the adapter silently
- * ignores a value it does not recognise and only `next` is lossless, so a timing is only sent when
- * the adapter declared it accepts it. (The adapter's own comment about its internal
- * `STEER_PRIORITY_NOW` / `STEER_PRIORITY_LATER` constants — *"an internal Claude implementation
- * detail, not part of the wire contract"*, `acp-agent.js@0.76.0:181-188` — is about those
- * constants, not about `_meta`, which `parseSteerRequest` passes through whole. 0.76.0 picks the
- * priority itself (`:1762-1763`) and ignores `_meta.steering.priority`. This sentence used to
- * name a symbol `STEER_PRIORITY`; there is no such symbol in 0.76.0.)
- */
-async function steerRequest(connection, sessionId, blocks, priority) {
-    const result = await connection.connection.agent.request(STEER_METHOD, {
-        sessionId,
-        prompt: blocks,
-        _meta: { steering: { idleBehavior: 'promptRequired', ...(priority === undefined ? {} : { priority }) } },
-    });
-    return mapSteerOutcome(result);
-}
-/**
- * One `session/set_config_option` (`SetSessionConfigOptionRequest`, `types.gen.d.ts:5102-5132`) or
- * — for the daemon's synthesized {@link SYNTHESIZED_MODES_CONFIG_ID} — `session/set_mode`
- * (`SetSessionModeRequest`, `:5079`), shared by {@link AcpSession.open} and {@link AcpSession.attach}
- * the same way {@link steerRequest} is.
- *
- * Returns the normalized, full snapshot either way. `session/set_config_option`'s response carries
- * the agent's own full `configOptions` list (`SetSessionConfigOptionResponse`, `:2949-2964`; the
- * `configOptions` field itself at `:2953`) — which never carries the synthesized `acp:modes` entry,
- * so a synthesized entry from the last snapshot is carried across by hand. `session/set_mode`'s
- * response carries no list at all (`SetSessionModeResponse`, `:2934-2945`), so that snapshot is
- * built locally by applying `value` to the synthesized entry already in `current()`.
- *
- * `current` and `remember` are how the two construction paths ({@link AcpSession.open}'s closure
- * over its own `let snapshot`, {@link AcpSession.attach}'s over its own) each keep one mutable
- * "latest snapshot" cell without this function needing to know which kind of session it is serving.
- */
-function setConfigOptionRequest(connection, sessionId, current, remember) {
-    return async (configId, value) => {
-        const agent = connection.connection.agent;
-        if (configId === SYNTHESIZED_MODES_CONFIG_ID) {
-            if (typeof value !== 'string') {
-                throw new Error(`[acp] ${SYNTHESIZED_MODES_CONFIG_ID} takes a mode id (a string), got ${typeof value}`);
-            }
-            await agent.request(methods.agent.session.setMode, { sessionId, modeId: value });
-            const next = current().map((o) => (o.id === configId && o.type === 'select' ? { ...o, currentValue: value } : o));
-            remember(next);
-            return next;
-        }
-        const params = typeof value === 'boolean' ? { sessionId, configId, type: 'boolean', value } : { sessionId, configId, value };
-        const response = await agent.request(methods.agent.session.setConfigOption, params);
-        // The agent's reply has no `modes` field to normalize against — a synthesized entry, if there
-        // was one, survives only by being carried across from the last snapshot.
-        //
-        // Carried across under the *same* condition `normalizeConfigOptions` synthesizes under
-        // ({@link modesAlreadyRepresented}), not unconditionally: an agent that only starts declaring
-        // its own equivalent control *after* we synthesized one — it grew a `category: "mode"` option
-        // between the open and this set, or (pi's shape) it already offers the identical choice list
-        // under an id of its own — would otherwise get two pickers for one thing on the same session,
-        // its real one and our stale stand-in for it. The agent's own always wins.
-        const reNormalized = normalizeConfigOptions(response.configOptions, null);
-        const carried = current().find((o) => o.id === SYNTHESIZED_MODES_CONFIG_ID);
-        const carriedChoices = (carried ? flatChoicesOf(carried) : null) ?? [];
-        const synthesized = carried && !modesAlreadyRepresented(reNormalized, carriedChoices) ? carried : undefined;
-        const next = reNormalized.concat(synthesized ? [synthesized] : []);
-        remember(next);
-        return next;
-    };
-}
-/** `payload[key]` narrowed to `string`, or `null` — every messageId/text field this file reads off a mapped `WireEvent` goes through this rather than an `as` cast, since the payload is `Record<string, unknown>` by construction. */
-function stringField(payload, key) {
-    const value = payload[key];
-    return typeof value === 'string' ? value : null;
-}
-/**
- * The queue behind an attached session's `nextUpdate()`, standing in for the one the SDK's
- * `ActiveSession` keeps internally.
- *
- * Three producers feed it and they must interleave in arrival order: `session/update` notifications
- * (via {@link LiveUpdateSource}), the `session/prompt` response that ends a turn, and that same
- * request's rejection. `ActiveSession` routes all three onto one queue — which is what lets
- * {@link AcpSession.runReadLoop} be a single loop — so this reproduces that exactly rather than
- * giving the prompt result its own channel.
- *
- * {@link fail} is the `dispose()` half: it is permanent and drops anything still buffered, because
- * its only caller is a session that is closing. Leaving buffered updates readable there would emit
- * events for a session the manager has already retired.
- */
-class AttachedQueue {
-    items = [];
-    waiters = [];
-    failure = null;
-    push(value) {
-        this.settle({ ok: true, value });
-    }
-    /**
-     * A one-shot rejection — a failed `session/prompt`, not a dead queue. `runReadLoop` turns exactly
-     * this into a `failed` TurnResult and then keeps reading for the next prompt, mirroring how
-     * `ActiveSession.prompt()` routes its own rejection onto the same queue.
-     */
-    pushError(error) {
-        this.settle({ ok: false, error });
-    }
-    fail(error) {
-        if (this.failure)
-            return;
-        this.failure = { error };
-        this.items.length = 0;
-        for (const waiter of this.waiters.splice(0))
-            waiter.reject(error);
-    }
-    next() {
-        const head = this.items.shift();
-        if (head)
-            return head.ok ? Promise.resolve(head.value) : Promise.reject(head.error);
-        if (this.failure)
-            return Promise.reject(this.failure.error);
-        return new Promise((resolve, reject) => {
-            this.waiters.push({ resolve, reject });
-        });
-    }
-    settle(item) {
-        if (this.failure)
-            return;
-        const waiter = this.waiters.shift();
-        if (!waiter) {
-            this.items.push(item);
-            return;
-        }
-        if (item.ok)
-            waiter.resolve(item.value);
-        else
-            waiter.reject(item.error);
-    }
-}
-export class AcpSession {
-    session;
-    outbox = [];
-    /**
-     * This session's `toolCallId → name` memory, for the `tool_call_update`s ACP lets arrive with
-     * no `name` on them ("unchanged", not "unknown" — see {@link SessionMapperState}).
-     *
-     * Per instance, like every other cross-update field here, and for the same reason `inFlightTurns`
-     * is: one `AcpSession` is one ACP session, and a registry shared between two of them would let
-     * one session's tool call name a different session's update.
-     */
-    mapperState = new SessionMapperState();
-    eventSink = null;
-    turnSink = null;
-    draining = false;
-    /**
-     * Every turn this session has started and not yet reported a result for, oldest first.
-     *
-     * A list rather than a single `currentTurn`, because `session/prompt` is a request per turn and
-     * ACP places no bar on a second one going out while the first is still running — the SDK's
-     * `ActiveSession.prompt` enqueues a `{kind:'stop'}` message per call, so two prompts really do
-     * produce two completions on the read queue, in the order the agent answers them. Folding a
-     * second prompt into the first turn (`currentTurn ??=`) meant the second `stop` found no turn to
-     * finish and its result was dropped outright: the second turn's deltas arrived, but no
-     * `agent_message` ever flushed the server's delta buffer for them and no `turn_done` ever
-     * reached the run, which stayed parked on work that had already finished. Pinned by clause 7 of
-     * `contract.ts`.
-     *
-     * Strictly FIFO, which is an assumption worth naming: a stop message is matched to the *oldest*
-     * unfinished turn rather than to the prompt that produced it, because JSON-RPC ids live inside
-     * the SDK and never reach this class. Two overlapping turns that the agent answers out of order
-     * therefore swap results. Both results still arrive, which is what everything downstream needs;
-     * per-prompt attribution would need an id ACP does not put on `session/update` either.
-     */
-    inFlightTurns = [];
-    /** Timer which closes assistant text that an adapter sent after it had already ended the turn. */
-    lateMessageFlushTimer = null;
-    /**
-     * Whether a `session/prompt` round trip is outstanding on the agent **right now**.
-     *
-     * This is the turn's ground truth: {@link inFlightTurns} is pushed when the prompt goes out and
-     * shifted when the agent answers, so it says what the agent is doing rather than what anything
-     * else recorded about it. The daemon's own `TaskRegistry` bracket is bookkeeping over the same
-     * events and can outlive them (a steer on an idle session, a bracket never closed); this cannot.
-     */
-    get turnRunning() {
-        return this.inFlightTurns.length > 0;
-    }
-    /** Whether this session's stdio is still readable -- false once the read loop died. */
-    get readable() {
-        return this.readLoopDead === null;
-    }
-    closed = false;
-    connectionAborted = false;
-    /**
-     * Why {@link runReadLoop} stopped for good, or `null` while it is still reading. Set at all three
-     * of the loop's permanent exits, so the flag means exactly "no `stop` message can ever arrive
-     * again"; {@link prompt} is the reader.
-     *
-     * Without it, a prompt sent after the loop died was `session/prompt`-ed into a queue nobody reads:
-     * no `TurnResult`, no `turn_done`, no error card and no timeout, and every retry the user makes
-     * joins the same silence. Two of the consequences live outside this file, which is why no
-     * per-file review caught them:
-     *
-     * - `agentSessions.ts` adds the ref to `TaskRegistry`'s `agentTasks` on every `agent_prompt` and
-     *   only `onAgentTurnDone` takes it out again, so one hung prompt pins `canUpdate()` to `false`
-     *   for the rest of this process's life — the daemon refuses **every** self-update until that
-     *   session is explicitly closed or swept.
-     * - Each retry `touch()`es the session, so retrying keeps `lastActivityAt` fresh and `sweepIdle`
-     *   never reclaims it either.
-     *
-     * Deliberately a flag of its own rather than reusing {@link closed}: `close()` short-circuits its
-     * whole body on `closed`, so setting that here would skip `session/cancel` and `dispose()` on a
-     * session that was never actually closed.
-     */
-    readLoopDead = null;
-    /** Tracks the streaming assistant message for `agent_message` synthesis — see {@link flushMessageCompleted}. */
-    sawMessageContent = false;
-    currentMessageId = null;
-    /**
-     * `requestId` → the resolver for one outstanding `session/request_permission` round trip.
-     * `AcpSession` owns this map (rather than `permission.ts` keeping its own) purely so `close()`
-     * can settle every outstanding card the same way the deleted Claude Code bridge's
-     * `denyAllPending()` did — a request with no user left to answer it must not hang the agent
-     * process forever. `permission.ts` is the only thing that populates it, via
-     * {@link registerPendingApproval}; nothing in this file does.
-     */
-    pendingApprovals = new Map();
-    readLoopDone;
-    constructor(session, connectionSignal) {
-        this.session = session;
-        if (connectionSignal.aborted)
-            this.connectionAborted = true;
-        else
-            connectionSignal.addEventListener('abort', () => (this.connectionAborted = true), { once: true });
-        this.readLoopDone = this.runReadLoop();
-    }
-    /**
-     * Open a new ACP session via `session/new` and start driving it.
-     *
-     * `nativeSessionId` mirrors the deleted `AgentBridge.open()` contract verbatim: `null` when no
-     * usable id came back, **never** `''` — the server persists any non-null value it is given as an
-     * identity and later resumes from it, so an agent that technically returns an empty string must be
-     * degraded to `null` here rather than trusted at face value.
-     */
-    static async open(connection, options) {
-        const activeSession = await connection.connection.agent.buildSession(options.cwd).start();
-        // `NewSessionResponse` (`acp.d.ts:329`'s `newSessionResponse` getter) carries both halves
-        // `normalizeConfigOptions` needs: `configOptions` (`types.gen.d.ts:2546`) and `modes` (`:2542`).
-        const response = activeSession.newSessionResponse;
-        let snapshot = normalizeConfigOptions(response.configOptions, response.modes);
-        const drivenSession = {
-            sessionId: activeSession.sessionId,
-            // `ActiveSession.prompt`'s own parameter is already `string | ContentBlock | ContentBlock[]`
-            // (`acp.d.ts:338`) — it is this class's `DrivenSession` boundary that was narrow, not the SDK's.
-            prompt: (blocks) => activeSession.prompt(blocks),
-            nextUpdate: () => activeSession.nextUpdate(),
-            dispose: () => activeSession.dispose(),
-            // A notification (`ClientContext.notify`, not `.request`) — `session/cancel` cancels the whole
-            // prompt turn and expects no response, unlike `$/cancel_request`'s per-request
-            // `SendRequestOptions.cancellationSignal` mechanism.
-            cancel: () => connection.connection.agent.notify(methods.agent.session.cancel, { sessionId: activeSession.sessionId }),
-            steer: (blocks, priority) => steerRequest(connection, activeSession.sessionId, blocks, priority),
-            setConfigOption: setConfigOptionRequest(connection, activeSession.sessionId, () => snapshot, (next) => (snapshot = next)),
-        };
-        const session = new AcpSession(drivenSession, connection.connection.signal);
-        const nativeSessionId = activeSession.sessionId.length > 0 ? activeSession.sessionId : null;
-        bindDivertedUpdates(connection, activeSession.sessionId, session);
-        return { session, nativeSessionId, configOptions: snapshot };
-    }
-    /**
-     * Drive a session the agent has **already loaded** (`session/load`, see `adoption.ts`) instead of
-     * opening a new one — the path a reconnect and an adoption both take.
-     *
-     * ### Why this exists at all
-     *
-     * `agentSessions.ts` is handed a `nativeSessionId` on every reconnect, not only on adoption: the
-     * server persists the id and sends it back with `agent_open`. Answering that by opening a fresh
-     * `session/new` and replaying the old session's history as read-only display would throw away the
-     * agent's own context on every reconnect — the deleted Claude Code bridge really did resume, so
-     * that would be a regression, not an equivalent swap.
-     *
-     * ### Why it is hand-built rather than an SDK call
-     *
-     * The SDK offers no way to attach its `ActiveSession` to an already-loaded session: the class has a
-     * private constructor and the only thing that produces one is `SessionBuilder.start()`, which
-     * *is* `session/new` (`@agentclientprotocol/sdk/dist/acp.d.ts`). So the second construction path is
-     * this: the same {@link DrivenSession} surface, assembled from raw requests —
-     * `prompt` → `session/prompt`, `cancel` → the `session/cancel` notification, `nextUpdate` →
-     * {@link AttachedQueue} fed by `updates.listen(...)` plus the prompt's own completion, `dispose` →
-     * unsubscribe and fail the queue. Everything above this line — the read loop, the outbox, the
-     * `agent_message` synthesis, the pending-approval map — is shared verbatim with
-     * {@link AcpSession.open}; only how the four calls reach the agent differs.
-     *
-     * The caller is responsible for having already issued `session/load` for `sessionId` (and, when it
-     * wants that history, for having captured the replay it produced). Call `updates.listen` here
-     * rather than earlier so nothing is dropped in between: `ReplayCapture` withholds updates from a
-     * listener only while the id is armed, and it is disarmed by the `take()` that ends the replay.
-     *
-     * ### `initial.configOptions` is read lazily, not copied at construction
-     *
-     * `AcpAgents.startSession` (Task 3) must construct this session *before* issuing `session/load` —
-     * the session has to be subscribed to the live update stream before the replay begins — so the
-     * snapshot (which only exists once `session/load`'s response arrives, via `adoption.ts`'s
-     * `ReplaySessionParams.onLoaded`) is not there yet at the moment this runs. An eager
-     * `let snapshot = initial.configOptions` at construction time would therefore capture an empty
-     * array forever. `current()` instead re-reads `initial.configOptions` every time, until a real
-     * `setConfigOption` call produces a snapshot of its own — so a caller that populates `initial`
-     * (a mutable object) after construction is still seen.
-     */
-    static attach(connection, sessionId, updates, initial) {
-        const agent = connection.connection.agent;
-        const queue = new AttachedQueue();
-        // Counted, not just forwarded: `settleUpdates` below needs a growth signal for this session's
-        // live stream, the way the replay path uses `ReplayCapture.count`.
-        let delivered = 0;
-        const unsubscribe = updates.listen(sessionId, (update) => {
-            delivered += 1;
-            queue.push({ kind: 'session_update', update });
-        });
-        let snapshot = null;
-        const current = () => snapshot ?? initial.configOptions;
-        const driven = {
-            sessionId,
-            async prompt(blocks) {
-                try {
-                    const response = await agent.request(methods.agent.session.prompt, {
-                        sessionId,
-                        prompt: blocks,
-                    });
-                    // The response resolving does NOT mean this turn's own `session/update` notifications have
-                    // been dispatched — the SDK applies a response synchronously off the reader but hands a
-                    // notification to an un-awaited handler chain (see `settleUpdates`, which documents the
-                    // measurement). Without this drain, the `stop` below jumps the queue ahead of deltas the
-                    // reader had already pulled off the wire, and `agent_message`/`TurnResult` land
-                    // mid-message: the server's CoworkEngine closes the item on `agent_message`, so the
-                    // remaining text arrives orphaned, and an `agent_close` racing the early `turn_done` can
-                    // drop it outright (`AttachedQueue.fail` discards what is still buffered).
-                    //
-                    // Not a `settleUpdates` gap the SDK-routed path shares: `ActiveSession` is routed by a
-                    // *static* handler that runs first in the chain, which is why `AcpSession.open` never
-                    // needed this and `attach` does.
-                    await settleUpdates(sessionId, () => delivered);
-                    // Enqueued, not just returned: the read loop — not this caller — is what turns a completed
-                    // turn into a TurnResult, exactly as `ActiveSession.prompt()` does it.
-                    queue.push({ kind: 'stop', stopReason: response.stopReason });
-                    return { stopReason: response.stopReason };
-                }
-                catch (err) {
-                    // Same routing for the failure: `runReadLoop` reads it off the queue and reports a `failed`
-                    // turn. Rethrown as well so the shape matches `ActiveSession.prompt()` — `AcpSession.prompt`
-                    // swallows it with a `.catch(() => {})` precisely because the queue is the real channel.
-                    // Drained first for the same reason the success path is: an agent that streamed some of a
-                    // turn and *then* errored has the identical reordering hazard, and the failed TurnResult
-                    // must not overtake the text that preceded it.
-                    await settleUpdates(sessionId, () => delivered);
-                    queue.pushError(err);
-                    throw err;
-                }
-            },
-            nextUpdate: () => queue.next(),
-            cancel: () => agent.notify(methods.agent.session.cancel, { sessionId }),
-            steer: (blocks, priority) => steerRequest(connection, sessionId, blocks, priority),
-            setConfigOption: setConfigOptionRequest(connection, sessionId, current, (next) => (snapshot = next)),
-            dispose: () => {
-                unsubscribe();
-                queue.fail(new Error(`[acp] session ${sessionId} was disposed`));
-            },
-        };
-        const attached = new AcpSession(driven, connection.connection.signal);
-        bindDivertedUpdates(connection, sessionId, attached);
-        return attached;
-    }
-    // -------------------------------------------------------------------------------------------
-    // The surface `agentSessions.ts` drives (carried over from the deleted BridgeSession SPI)
-    // -------------------------------------------------------------------------------------------
-    /**
-     * Send one `session/prompt` turn. `blocks` is ACP's own `ContentBlock[]` (see {@link DrivenSession}
-     * for why this class no longer narrows it to a `string`) — a lone text block is what every caller
-     * sends today; an image block is only ever valid here for a session whose agent advertised
-     * `PromptCapabilities.image` (`AcpConnection.capabilities.promptImage`, surfaced to callers as
-     * `AcpAgentSession.supportsImageInput`), and enforcing that is the caller's job, not this method's.
-     */
-    prompt(blocks) {
-        // Checked ahead of `closed`, and the reason this branch exists at all: a session can outlive its
-        // read loop without anyone having closed it (a dead connection, an unmappable update), and then
-        // nothing but this call is left to end the turn. Registered as a turn and finished on the spot,
-        // rather than reported some other way, so that "one prompt, one terminal result" holds on this
-        // path exactly as it does on the live one — `agentSessions.ts` unblocks `TaskRegistry` and the
-        // server closes the round off `onTurnDone` and nothing else. See {@link readLoopDead}.
-        if (this.readLoopDead !== null) {
-            this.inFlightTurns.push({ interrupted: false });
-            this.finishTurn('failed', undefined, this.readLoopDead);
-            return;
-        }
-        if (this.closed) {
-            console.warn('[acp] dropping prompt for a session that is no longer running');
-            return;
-        }
-        // An adapter may have ended the preceding prompt before delivering its final chunks. Do not let
-        // those chunks borrow this prompt's completion marker: that makes the old answer appear only
-        // after the reader submits a new message.
-        this.flushLateMessageCompletion();
-        // One turn per prompt, always — see {@link inFlightTurns} for why an overlapping prompt must not
-        // fold into the turn already running.
-        this.inFlightTurns.push({ interrupted: false });
-        // The `.catch(() => {})` is not error handling — `ActiveSession.prompt()` already routes this
-        // same rejection onto the `nextUpdate()` queue internally (see the file doc comment), and
-        // `runReadLoop`'s catch branch is what turns it into a `TurnResult`. It exists only so the
-        // promise this call itself produces is never flagged as an unhandled rejection.
-        this.session.prompt(blocks).catch(() => { });
-    }
-    /**
-     * Inject a message into the turn that is currently running, instead of queueing it behind that
-     * turn as a second `session/prompt` would.
-     *
-     * **Injecting aborts.** The adapter's own comment (`acp-agent.js@0.76.0:1702-1704`): *"Pre-empting
-     * means ABORTING: the interrupted cycle emits a `result` of its own and the steered message runs
-     * as a second one, so the turn is marked (`Turn.steeredEchoes`) to settle at the SDK's `idle`
-     * instead of that result."* From this class's side that is invisible and must stay so: no
-     * {@link inFlightTurns} entry is pushed here, because steering does **not** create a turn — the
-     * one `stop` message still on its way belongs to the prompt that is already registered. Pushing
-     * one would leave a turn that nothing can ever finish.
-     *
-     * The steered message's own output arrives through `session/update` like any other, **not** in
-     * this response (`:1115-1116`), so the only thing a caller learns here is the disposition.
-     *
-     * Callers must have checked {@link AcpConnection.supportsSteering} — this is an extension, and an
-     * agent that never advertised it answers `Method not found`.
-     *
-     * `blocks` carries the **whole** message, images included, for the reason set out on
-     * {@link steerRequest}; `priority` is the delivery timing, `undefined` meaning the caller is
-     * naming none rather than picking one.
-     */
-    async steer(blocks, priority) {
-        if (this.closed)
-            throw new Error('[acp] cannot steer a session that is no longer running');
-        return this.session.steer(blocks, priority);
-    }
-    /**
-     * `session/set_config_option` — or, for the daemon's synthesized {@link SYNTHESIZED_MODES_CONFIG_ID},
-     * `session/set_mode` — and the resulting normalized snapshot; see {@link setConfigOptionRequest}.
-     */
-    async setConfigOption(configId, value) {
-        return this.session.setConfigOption(configId, value);
-    }
-    /**
-     * Resolve one pending `session/request_permission` round trip. Unknown/already-answered
-     * `requestId`s are silently ignored, matching the deleted Claude Code bridge's `answer()` — a
-     * platform relaying a stale answer must not throw.
-     */
-    answer(requestId, outcome) {
-        const resolve = this.pendingApprovals.get(requestId);
-        if (!resolve)
-            return;
-        this.pendingApprovals.delete(requestId);
-        resolve(outcome);
-    }
-    /**
-     * Register a pending `session/request_permission` round trip. `permission.ts` calls this from its
-     * `session/request_permission` handler and resolves the registered callback once the user (or
-     * `close()`) answers it; nothing in this file calls it.
-     */
-    registerPendingApproval(requestId, resolve) {
-        if (this.closed) {
-            // A permission request that reaches us after our own close() has nobody left to answer it —
-            // review finding (task-5, item 2): registering it anyway would park a card `close()`'s own
-            // drain already ran past, and the agent would wait forever for a response nothing will send.
-            // Resolve immediately with the same abandonment sentinel `close()`'s drain uses, instead of
-            // ever storing the entry.
-            resolve(ABANDONED_ANSWER);
-            return;
-        }
-        this.pendingApprovals.set(requestId, resolve);
-    }
-    /**
-     * Emit a wire event that did not come from `session/update` — `permission.ts` calls this from its
-     * `session/request_permission` handler to raise the `permission_request` card. Routed
-     * through the same buffered {@link outbox}/{@link drain} pair every mapped `session/update` event
-     * uses, rather than a separate channel, so a permission card lands in the exact same delivery
-     * order relative to other events (and is subject to the same registration-buffering guarantee: an
-     * event emitted before `onEvent` is registered is queued, not lost — see {@link drain}'s doc
-     * comment) instead of racing a second, independent path a consumer would have to merge itself.
-     */
-    emitEvent(event) {
-        if (this.closed) {
-            // Same reasoning as `registerPendingApproval` above: once closed, nothing is left reading the
-            // outbox on the other end that could still make sense of a fresh card.
-            return;
-        }
-        this.enqueue({ kind: 'event', event });
-    }
-    /**
-     * Applies one `session/update` the transport diverted before the SDK could destroy it.
-     *
-     * Two things arrive here and they differ only in addressing (see `draftInterceptor.ts` for the
-     * measurements): a draft variant on **this** session, and any update at all on a **child**
-     * session this client never opened. Both are mapped by the same mapper as everything else — this
-     * is not a second translation path, it is the same one reached by a different door.
-     *
-     * A child's events are tagged with {@link WireEvent.acpSessionId} so the server can route them to
-     * the projected child session; the frame itself still goes out on this session's ref and seq.
-     * They deliberately bypass {@link routeMappedEvent}'s message-boundary tracking: that accumulator
-     * synthesises `agent_message` for **this** session's turn, and feeding a child's chunks into it
-     * would end the parent's message on the child's boundaries.
-     *
-     * Never throws. Its caller is the stream, and an exception there would stall every later message
-     * on the connection, not just this one.
-     */
-    applyDivertedUpdate(diverted) {
-        const isChild = diverted.reason === 'foreign-session';
-        let events;
-        try {
-            events = mapSessionUpdate(diverted.update, this.mapperState);
-        }
-        catch (err) {
-            // An unmapped variant is a contract gap worth naming, not worth killing a session over. The
-            // agent, the session and the variant are what make it actionable.
-            console.warn(`[acp] dropped a diverted '${String(diverted.update.sessionUpdate)}' ` +
-                `for session ${diverted.sessionId}: ${err instanceof Error ? err.message : String(err)}`);
-            return;
-        }
-        for (const event of events) {
-            this.emitEvent(isChild ? { ...event, acpSessionId: diverted.sessionId } : event);
-        }
-    }
-    /**
-     * Cancel the current turn via `session/cancel` — a **notification**, not `$/cancel_request`
-     * (that method cancels one in-flight *request*, via `SendRequestOptions.cancellationSignal`, and is
-     * a different mechanism entirely from ending a whole prompt turn). The current turn is marked
-     * interrupted synchronously so the eventual `TurnResult` reports `'interrupted'` no matter what
-     * `stopReason` the agent's `session/prompt` response ends up carrying — including a `stopReason`
-     * that (incorrectly) claims the turn ended normally.
-     */
-    async interrupt() {
-        if (this.closed) {
-            console.warn('[acp] ignoring interrupt for a session that is no longer running');
-            return;
-        }
-        // Every in-flight turn, not just the newest: `session/cancel` cancels the session's prompt
-        // turn(s) wholesale, so a second overlapping turn must not come back reporting 'completed'
-        // after the user pressed Stop.
-        for (const turn of this.inFlightTurns)
-            turn.interrupted = true;
-        try {
-            await this.session.cancel();
-        }
-        catch (err) {
-            // Not rethrown: the turn is already marked interrupted above, so it will report
-            // 'interrupted' regardless of whether the agent ever heard the cancel — a failed notify means
-            // the agent may keep working, which is what the warning is for.
-            console.warn(`[acp] session/cancel notification failed: ${errorMessage(err)}`);
-        }
-    }
-    /**
-     * Idempotent: the first call sends `session/cancel`, denies every still-pending permission card,
-     * then disposes the underlying `ActiveSession` (which fails its update queue); the second call just
-     * awaits the same read-loop exit the first one triggered.
-     *
-     * `session/cancel` is sent **before** `dispose()`, deliberately: `ActiveSession.dispose()`'s own
-     * docstring says it does not close the session on the agent side, only local update routing. With
-     * `dispose()` alone, an in-flight prompt keeps the agent running tools and burning tokens until
-     * whatever holds this session's `AcpConnection` eventually kills the child process — harmless only
-     * while there is exactly one connection per session, which ACP does not guarantee in general. The
-     * cancel is wrapped in its own `try`/`catch` so a failed notify cannot skip or mask the
-     * deny-pending/dispose/read-loop shutdown that must happen regardless.
-     */
-    async close() {
-        if (!this.closed) {
-            this.closed = true;
-            this.cancelLateMessageCompletion();
-            this.drainPendingApprovals();
-            try {
-                await this.session.cancel();
-            }
-            catch (err) {
-                console.warn(`[acp] session/cancel notification failed during close: ${errorMessage(err)}`);
-            }
-            this.session.dispose();
-        }
-        await this.readLoopDone;
-    }
-    /**
-     * Resolve every still-pending permission request with {@link ABANDONED_ANSWER} and clear the map.
-     * Shared by `close()` (the request-time answer path `permission.ts` reads) and
-     * `runReadLoop`'s connection-abort branch — review finding (task-5, item 5): the child dying or the
-     * connection otherwise aborting out from under a pending permission left it undrained before, since
-     * only `close()` itself drained it and neither the read loop's own abort handling nor a dead
-     * connection ever calls `close()`.
-     */
-    drainPendingApprovals() {
-        for (const resolve of this.pendingApprovals.values())
-            resolve(ABANDONED_ANSWER);
-        this.pendingApprovals.clear();
-    }
-    onEvent(cb) {
-        this.eventSink = cb;
-        this.drain();
-    }
-    onTurnDone(cb) {
-        this.turnSink = cb;
-        this.drain();
-    }
-    // `backfill?()` is deliberately not implemented here: replaying an existing native session's
-    // history is `session/load`, which is `adoption.ts`'s job ("领养"), not this file's. Not
-    // `session/resume(replayFrom)`, as the plan text and an earlier version of this comment said —
-    // ACP v1's `session/resume` explicitly does *not* replay history, and `replayFrom` exists only
-    // under the experimental v2 entry point Global Constraint 1 forbids importing. `adoption.ts`'s
-    // "`session/resume` is deliberately NOT used here" section carries the full reading. A session
-    // with no adopted history simply has no `backfill` method, exactly like an unsupported bridge in
-    // the deleted SPI.
-    // -------------------------------------------------------------------------------------------
-    // session/update routing + turn completion
-    // -------------------------------------------------------------------------------------------
-    /**
-     * One continuous consumer of `ActiveSession.nextUpdate()`, for the session's whole lifetime (not
-     * just one turn): `session_update` messages become buffered wire events, `stop` messages finish the
-     * current turn. See the class doc comment for why a single loop is what makes a second
-     * `.onNotification('session/update', …)` registration unnecessary.
-     */
-    async runReadLoop() {
-        for (;;) {
-            let message;
-            try {
-                message = await this.session.nextUpdate();
-            }
-            catch (err) {
-                if (this.closed) {
-                    // Our own close() disposed the ActiveSession, which fails its queue — expected, not an
-                    // error. Every turn still in flight at that moment must still get a terminal result, or
-                    // the manager's onTurnDone would never fire for it. All of them, not just the oldest: the
-                    // queue is permanently failed, so no further stop message is ever coming for the rest.
-                    this.readLoopDead = errorMessage(err);
-                    this.finishAllTurns('interrupted', errorMessage(err));
-                    return;
-                }
-                // `ActiveSession.prompt()` routes its own rejection onto this same queue (see the class doc
-                // comment) — this is that one-shot rejection, not a permanently failed queue (only
-                // `dispose()`/connection-close does that), so the loop keeps running for the next prompt.
-                //
-                // **The one exit on this class where the agent itself answered**, and so the only one that
-                // may claim {@link TurnResult.agentRefused} — unless the connection is what died, in which
-                // case this same throw is a dead queue rather than a reply and the branch just below takes
-                // over. `connectionAborted` is read here rather than after `finishTurn` for no reason but
-                // ordering: both reads happen in the same synchronous run, so they see the same value (the
-                // branch below has always depended on that).
-                // `err` itself, not its message: this is the only frame in which the agent's JSON-RPC code
-                // still exists. `errorMessage(err)` on the same line is what destroyed it before.
-                this.finishTurn('failed', undefined, errorMessage(err), !this.connectionAborted, jsonRpcErrorCode(err));
-                if (this.connectionAborted) {
-                    // The connection died out from under us without our own close() ever running. Same
-                    // reasoning as the `this.closed` branch above: the queue is now permanently failed, so no
-                    // further stop message is ever coming for any turn still behind the one `finishTurn` above
-                    // just popped — review finding (task-11 fix round 1, finding 1): before the FIFO change a
-                    // single `finishTurn` above always cleared the *only* turn, so this branch never had a
-                    // second one left behind to orphan. And every *later* prompt needs the same treatment,
-                    // which is what {@link readLoopDead} gives it — finishing the turns open right now says
-                    // nothing about the retry the user sends ten seconds from now.
-                    this.readLoopDead = errorMessage(err);
-                    this.finishAllTurns('failed', errorMessage(err));
-                    // Nothing will drain pendingApprovals otherwise (review finding, task-5 item 5).
-                    this.drainPendingApprovals();
-                    return; // the connection itself is gone; further reads would just spin
-                }
-                continue;
-            }
-            if (message.kind === 'session_update') {
-                try {
-                    for (const event of mapSessionUpdate(message.update, this.mapperState))
-                        this.routeMappedEvent(event);
-                }
-                catch (err) {
-                    // The third permanent-failure exit, and the reason this mapping call is inside a `try` at
-                    // all: nothing thrown under `mapSessionUpdate` may escape `runReadLoop`. An uncaught throw
-                    // here rejects `readLoopDone`, strands every in-flight turn in `inFlightTurns` on a read
-                    // loop that no longer exists, and skips `drainPendingApprovals`, leaving the agent process
-                    // blocked forever on a permission card nobody will answer.
-                    //
-                    // What this branch is *not*: the handler for an unknown `sessionUpdate` variant. An
-                    // earlier version of this comment claimed it was, and a probe disproved it. Both paths
-                    // that feed this loop parse the notification through the SDK's `zSessionNotification`
-                    // first — `SessionUpdateRouter.handleMessage` for `open()`, `registerAppNotification` for
-                    // the `attach()`/replay handler — and `zSessionUpdate` is a closed union of literals. An
-                    // update naming a variant our pinned SDK does not know fails that parse inside the SDK's
-                    // own dispatch, which prints one `Error handling notification` line and carries on;
-                    // `mapSessionUpdate` is never called for it. Measured against a bare ndjson agent emitting
-                    // `{"sessionUpdate":"brand_new_v2_variant"}`: the surrounding deltas and the turn's own
-                    // completion all arrived normally and this branch never ran. (The tests that do run it
-                    // push into `attach`'s `LiveUpdateSource` directly, which is downstream of that parse.)
-                    //
-                    // So the exhaustiveness guard is unreachable in production today, and what actually
-                    // happens to a future agent's new update variant is that **it disappears silently** —
-                    // one SDK console line, and nothing in Axom at all: no wire event, no card, no diagnostic,
-                    // no record that the agent said anything. Nobody on this branch adjudicated that; it is
-                    // written down here because this is where a reader will come looking for it, and the place
-                    // to change it would be the SDK parse boundary, not this catch.
-                    //
-                    // The branch stays regardless: a throw from anywhere under `mapSessionUpdate` still has to
-                    // be contained, and it is treated as permanent rather than skipped because whatever made
-                    // one update unrepresentable is a property of a *kind* of update, so the next one of that
-                    // kind throws again. Same shutdown as the other two permanent-failure exits — finish every
-                    // turn with the shared cause, drain the approvals, stop reading.
-                    console.error(`[acp] unmappable session/update; ending this session's turns: ${errorMessage(err)}`);
-                    this.readLoopDead = errorMessage(err);
-                    this.finishAllTurns('failed', errorMessage(err));
-                    this.drainPendingApprovals();
-                    return;
-                }
-            }
-            else {
-                // ACP's own 'cancelled' stopReason additionally forces 'interrupted' even when this session's
-                // own interrupt() was never called (a defensive backstop, not the primary path — see
-                // `finishTurn`'s interrupted-flag handling for that).
-                const status = message.stopReason === 'cancelled' ? 'interrupted' : 'completed';
-                this.finishTurn(status, message.stopReason);
-            }
-        }
-    }
-    /**
-     * Routes one mapped `WireEvent` to the outbox, tracking `agent_message_chunk`/`agent_thought_chunk`
-     * on the way through so `agent_message` can be synthesized at the right moments — the one per-turn
-     * accumulator this class still owns instead of `sessionUpdateMapper.ts` (see the class doc comment).
-     *
-     * `user_message_chunk` is deliberately *not* special-cased: it goes to the outbox like any other
-     * event, and the server folds it.
-     */
-    routeMappedEvent(event) {
-        const isAssistantChunk = event.eventName === 'agent_message_chunk' || event.eventName === 'agent_thought_chunk';
-        if (isAssistantChunk) {
-            this.trackMessageBoundary(event);
-        }
-        this.enqueue({ kind: 'event', event });
-        // `finishTurn` has already consumed the normal boundary. If an adapter emits content after it,
-        // give the rest of that burst a short chance to arrive, then synthesize the missing boundary
-        // ourselves. Without this, CoworkEngine correctly buffers the delta but can only flush it when
-        // an unrelated later user message happens to append an item.
-        if (isAssistantChunk && !this.turnRunning)
-            this.scheduleLateMessageCompletion();
-    }
-    /**
-     * Notes that assistant content/thought is streaming, and — if a *different* `messageId` from the
-     * one currently tracked shows up mid-turn — flushes `agent_message` for the message that just
-     * ended before this chunk's own event reaches the outbox. Without this, two assistant messages in
-     * one turn (e.g. around a tool call) would flush together into the server's single delta buffer
-     * the moment they landed within its ~400ms gap window, reading as one run-on message.
-     */
-    trackMessageBoundary(event) {
-        const messageId = stringField(event.payload, 'messageId');
-        if (this.sawMessageContent && messageId !== null && this.currentMessageId !== null && messageId !== this.currentMessageId) {
-            this.flushMessageCompleted();
-        }
-        this.sawMessageContent = true;
-        if (messageId !== null)
-            this.currentMessageId = messageId;
-    }
-    /**
-     * Synthesizes the existing `agent_message` event — see the class doc comment for why this
-     * class, not `sessionUpdateMapper.ts`, is what emits it. A no-op when no content/thought has
-     * streamed since the last flush (a turn with only tool calls, or an already-flushed
-     * mid-turn message boundary), so this is always safe to call unconditionally.
-     */
-    flushMessageCompleted() {
-        if (!this.sawMessageContent)
-            return;
-        this.enqueue({ kind: 'event', event: { eventName: 'agent_message', payload: { messageId: this.currentMessageId ?? 'turn' } } });
-        this.sawMessageContent = false;
-        this.currentMessageId = null;
-    }
-    /** Debounce a late chunk burst into one synthetic `agent_message` marker. */
-    scheduleLateMessageCompletion() {
-        this.cancelLateMessageCompletion();
-        this.lateMessageFlushTimer = setTimeout(() => {
-            this.lateMessageFlushTimer = null;
-            if (!this.closed && !this.turnRunning)
-                this.flushMessageCompleted();
-        }, LATE_MESSAGE_SETTLE_MS);
-    }
-    /** Flush a late tail before its contents can be mistaken for a later prompt's answer. */
-    flushLateMessageCompletion() {
-        this.cancelLateMessageCompletion();
-        this.flushMessageCompleted();
-    }
-    cancelLateMessageCompletion() {
-        if (this.lateMessageFlushTimer === null)
-            return;
-        clearTimeout(this.lateMessageFlushTimer);
-        this.lateMessageFlushTimer = null;
-    }
-    /**
-     * Terminate every turn still in flight — for the one path (a permanently failed read queue) where
-     * no further stop message can arrive for any of them.
-     *
-     * `error` is the *shared* cause, handed to every turn rather than only to whichever one happened
-     * to be popped first: one dead queue fails N turns for exactly one reason, and `error` is the only
-     * field that carries it (`agentSessions.ts` records `error: r.error ?? null`; the engine's
-     * `ExternalAgentEventApplier.onTurnDone` substitutes a generic "external agent turn failed" when
-     * it is absent). Passing it on the `'interrupted'` call as well keeps every permanent-failure exit
-     * shaped the same; {@link finishTurn} is the single place that decides a result carries it, and it
-     * still attaches `error` to `failed` results only.
-     */
-    finishAllTurns(status, error) {
-        while (this.inFlightTurns.length > 0)
-            this.finishTurn(status, undefined, error);
-    }
-    /**
-     * @param agentRefused whether this failure is the agent's own answer rather than something this
-     * class synthesised for it — see {@link TurnResult.agentRefused}. Defaulted to `false` so that
-     * every existing exit keeps saying "cannot attribute this", and a new one has to opt in.
-     * @param errorCode the JSON-RPC code of that answer, when there was one. Recorded only under
-     * `agentRefused` — the single `if` below is what keeps the code and the attribution from ever
-     * disagreeing, rather than two conditions someone can later edit apart.
-     */
-    finishTurn(status, stopReason, error, agentRefused = false, errorCode) {
-        // The oldest unfinished turn, popped: one stop message (or one prompt rejection) ends exactly
-        // one turn, so a second overlapping turn keeps its own result instead of being swallowed.
-        const turn = this.inFlightTurns.shift();
-        if (!turn)
-            return;
-        // Must land before the TurnResult below. Unconditionally safe to call — a no-op when nothing
-        // was accumulated — so every path that can end a turn (a normal stop, an interrupt, a failed
-        // request, or close() mid-turn) goes through exactly this one place rather than each needing to
-        // remember to flush for itself. The user half of this pair is gone: a buffered user message is
-        // now the server's to close, at `CoworkEngine.endBridgeTurn`, which sees the same turn boundary.
-        this.flushMessageCompleted();
-        // A turn this session itself interrupted always reports 'interrupted', regardless of what the
-        // agent's own response claims — mirrors the deleted Claude Code bridge's finishTurn.
-        const resolved = turn.interrupted ? 'interrupted' : status;
-        const result = { status: resolved };
-        if (resolved === 'completed' && stopReason && stopReason !== 'cancelled') {
-            result.stopReason = mapStopReason(stopReason);
-        }
-        // Echoed on every finished turn, matching the deleted Claude Code bridge's TurnResult shape —
-        // ACP's session id is known synchronously from session/new and never renames mid-session the way
-        // Claude Code's occasionally does, but a manager built against the old contract may still expect
-        // this field to be populated whenever it is known, not only the first time.
-        if (this.session.sessionId.length > 0)
-            result.nativeSessionId = this.session.sessionId;
-        if (resolved === 'failed' && error)
-            result.error = error;
-        // Gated on `resolved`, not on the requested `status`: a turn this session interrupted reports
-        // 'interrupted' whatever the agent said, and attributing that to the agent would be a claim
-        // about a result it no longer owns.
-        if (resolved === 'failed' && agentRefused) {
-            result.agentRefused = true;
-            if (errorCode !== undefined)
-                result.errorCode = errorCode;
-        }
-        this.enqueue({ kind: 'turn', result });
-    }
-    enqueue(item) {
-        this.outbox.push(item);
-        this.drain();
-    }
-    /**
-     * Deliver from the head of the outbox for as long as the head's sink exists. Buffering
-     * `session/update` output that arrives before `onEvent`/`onTurnDone` are registered — and flushing
-     * it in order once they are — is a contract the deleted `BridgeSession` SPI's KDoc called out
-     * explicitly: events emitted with no sink registered are otherwise silently lost.
-     *
-     * Stopping at the first undeliverable entry (rather than skipping it) preserves relative order
-     * across the two-step registration a manager does (`onEvent` first, `onTurnDone` second, or vice
-     * versa): a turn result queued ahead of some events must still reach its sink before those events
-     * reach theirs, and a single shared queue drained strictly FIFO is what guarantees that.
-     */
-    drain() {
-        if (this.draining)
-            return;
-        this.draining = true;
-        try {
-            while (this.outbox.length > 0) {
-                const head = this.outbox[0];
-                if (head.kind === 'event') {
-                    const sink = this.eventSink;
-                    if (!sink)
-                        return;
-                    this.outbox.shift();
-                    this.deliver(() => sink(head.event));
-                }
-                else {
-                    const sink = this.turnSink;
-                    if (!sink)
-                        return;
-                    this.outbox.shift();
-                    this.deliver(() => sink(head.result));
-                }
-            }
-        }
-        finally {
-            this.draining = false;
-        }
-    }
-    /** A throwing sink is the consumer's bug; it must not abort the drain. */
-    deliver(call) {
-        try {
-            call();
-        }
-        catch (err) {
-            console.error(`[acp] sink threw: ${errorMessage(err)}`);
-        }
-    }
-}