dsh-ntr 0.3.2 → 0.3.3

package/lib/types/bridge.d.ts

@@ -6,7 +6,7 @@
  * Connection RPC channel (authenticated) into `BridgeManager`, which is the
  * only object allowed to spawn a configured command.
  */
-import { type InitializeResponse } from '@agentclientprotocol/sdk';
+import { type ContentBlock, type InitializeResponse } from '@agentclientprotocol/sdk';
 import { EventHub, PermissionLedger, Transcript } from './impl.ts';
 import type { AcpToolCallSnapshot, PendingPermissionView, RosterPresetRow } from './impl.ts';
 import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpReleaseCause, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, AcpIdleRelease, ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk } from './protocol.ts';
@@ -41,7 +41,30 @@ interface LiveSession {
     availableCommands?: SessionView['availableCommands'];
     plan?: unknown[];
     usage?: SessionView['usage'];
+    /**
+     * The plugin's own measurable burst aggregate over this ACP session's turns
+     * (see `src/tps.ts`). Persisted with the chat-session record so the dock's
+     * rate survives a host restart; absent until a turn contributes a measurable
+     * burst (>= 1 inter-chunk gap).
+     */
+    burst?: SessionView['burst'];
     running: boolean;
+    /**
+     * The HOST's prompt slot for this session: true from the moment a turn
+     * starts until the agent answers it (or the host aborts the turn, or the
+     * turn is discarded). Together with the {@link settled} gate — which STAYS
+     * claimed after an abort until the agent acknowledges the cancel — this is
+     * what `claimTurn` arbitrates, NOT `running`.
+     *
+     * The three are deliberately different:
+     * - an ambient wait keeps `running` true (the background drain is still the
+     *   session's work, so nothing may release the process) while this slot is
+     *   already FREE (the agent answered; only the drain keeps talking);
+     * - an aborted turn drops THIS flag at once (our face of the turn ends) but
+     *   leaves `settled` in place, so the next prompt still waits out
+     *   `turnSettleMs` for the agent instead of racing a concurrent prompt.
+     */
+    promptInFlight?: boolean;
     closed: boolean;
     /** The agent process died; the session awaits a `session/load` resume. */
     released: boolean;
@@ -151,8 +174,70 @@ interface LiveSession {
      * the controller's own `retire` when it still points at it.
      */
     turnController?: TurnStreamController;
+    /**
+     * A background turn the agent started on its OWN initiative (CodeBuddy's
+     * multitask drains: a sub-agent completion notice starts a run the client
+     * never asked for). Its first `session_info_update` announces the request id
+     * every later update of that run carries in `_meta`; a `session/prompt`
+     * answered instantly with no conversation request id was folded into this
+     * drain and its real answer arrives as the drain's updates.
+     *
+     * Only lifetime events clear it (close / release / resume / stop): a drain
+     * may outlive the turn that was steered into it, and clearing on a normal
+     * settle would misclassify the NEXT steered prompt.
+     */
+    ambient?: AmbientTurn;
+    /**
+     * Request ids whose `agent/notice` already went out, so a repeated
+     * announcement of the same background run is not logged twice.
+     */
+    ambientNotices?: Set<string>;
+    /**
+     * Background drains this session already STOPPED waiting on (an ambient wait
+     * that closed on silence, or a record that outlived `ambientStaleMs`). The
+     * record is gone from {@link ambient}, but the drain itself may still be
+     * running: a queued message or a long tool makes it speak again while the
+     * NEXT turn is on air. Without this list the late text would teach that turn
+     * the drain's id (`noteTurnRequestId` / `adoptTurnRequestId`) and fold the
+     * background run's answer into the user's answer (a double answer).
+     *
+     * An update or re-announcement carrying a listed id REVIVES it
+     * (`reviveAmbientId` + a rebuilt {@link ambient}): the run is alive, so its
+     * next steered prompt must receive the drain's text. Only while the record
+     * stays retired is its text transcript-only. Timestamps let the zero-output
+     * report recognise a prompt folded into a recently quieted drain
+     * (`hasRecentRetiredAmbient`). Bounded ({@link RETIRED_AMBIENT_MAX}), oldest
+     * evicted first; every lifecycle boundary clears the list
+     * (`clearAmbientState`).
+     */
+    retiredAmbients?: RetiredAmbient[];
     transcript: Transcript;
 }
+/** One unsolicited (background) turn the agent is running, as announced in `_meta`. */
+interface AmbientTurn {
+    /** `codebuddy.ai/requestId` of the drain; every update of the run carries it. */
+    requestId: string;
+    startedAt: number;
+    /**
+     * When this drain last showed any sign of life (announcement or an update
+     * carrying its request id). {@link BridgeTuning.ambientStaleMs} expires the
+     * record from here, so a drain that died silently does not capture a later
+     * normal turn as steered.
+     */
+    lastActivityAt: number;
+    /** Whether the drain already streamed prose (text or thought) into the transcript. */
+    sawOutput: boolean;
+}
+/** A drain id the session stopped waiting on, and when it was retired. */
+interface RetiredAmbient {
+    requestId: string;
+    /**
+     * When the wait was retired. `hasRecentRetiredAmbient` uses it to tell a
+     * prompt folded into a just-quieted drain from one that ended on its own;
+     * `adoptTurnRequestId` / `noteTurnRequestId` ignore the id at any age.
+     */
+    retiredAt: number;
+}
 /** Reliability tuning, threaded from `AcpPluginConfig` through the manager. */
 export interface BridgeTuning {
     startupTimeoutMs?: number;
@@ -247,6 +332,65 @@ export interface BridgeTuning {
      * probe-only process has no stake in. `0` disables it.
      */
     probeIdleTimeoutMs?: number;
+    /**
+     * How long an ambient wait (see `TurnStreamController.awaitAmbient`) stays
+     * open after the LAST session update before the turn closes itself.
+     *
+     * A drain's end is its silence — the SDK's schema rejects the `session_end`
+     * CodeBuddy never sends anyway — but "silence" must be measured in the
+     * agent's own cadence, not in a chat-app-paced one. Measured against
+     * CodeBuddy 2.179.0: the gaps between drain ticks (the
+     * `model_requesting`→`model_streaming` hand-off of a real model call) run
+     * 1.0–1.4s, so any window below that closes the turn BEFORE the answer
+     * exists. 10s leaves room for two slow hand-offs without holding the turn
+     * open for a drain that actually finished.
+     *
+     * Deliberately NOT keyed on an `agentPhase` idle flag: a drain goes idle
+     * between queued messages too, so that signal closes the turn in the middle
+     * of its own work.
+     */
+    ambientQuietMs?: number;
+    /**
+     * The hard ceiling on ONE ambient wait: a background run that keeps ticking
+     * for minutes without finishing must not hold the conversation's turn open
+     * forever. At the ceiling the turn says where the rest of the output will
+     * land and closes.
+     */
+    ambientMaxMs?: number;
+    /**
+     * The hard ceiling on the WORKER phase of a detached-worker hold (see
+     * `TurnStreamController.holdForBackgroundDispatch`): the turn dispatched one
+     * or more background workers through `Agent` tool calls, the agent answered
+     * the prompt, and at least one worker has not reported back yet. The worker
+     * phase has NO quiet window on purpose — measured against CodeBuddy 2.179.0,
+     * a detached worker's own updates are 13–24s apart while it is perfectly
+     * alive — so only EVERY known dispatch reporting (completed / failed) or
+     * this ceiling can end it; a drain announcement is recorded but arms no
+     * clock before then. Once they have all reported, the drain's own
+     * `ambientQuietMs` / `ambientMaxMs` windows take over.
+     *
+     * Default 600000 ms (10 minutes).
+     */
+    backgroundTaskMaxMs?: number;
+    /**
+     * How long a PARKED detached-worker hold may wait for the host to open the
+     * driver step that carries the worker's report. The prompt response landed
+     * between two steps (the host is about to execute the `Agent` card), and a
+     * host that never opens the continuation step must not hang the turn. The
+     * host normally opens it at once, so this is a safety bound, not a cadence —
+     * deliberately far larger than one model hand-off.
+     *
+     * Default 30000 ms (30 seconds).
+     */
+    backgroundParkedGraceMs?: number;
+    /**
+     * How long an announced background drain may go without ANY update before a
+     * later instant prompt stops treating itself as folded into it. A drain that
+     * went silent for minutes is over even though nothing told us; keeping the
+     * record would misclassify the next normal turn as steered. Checked lazily
+     * when a prompt response arrives (see `streamPrompt`), never on a timer.
+     */
+    ambientStaleMs?: number;
 }
 /**
  * Resolves the workspace root of one chat session (`dshSessionId` = DSH session
@@ -502,6 +646,11 @@ export declare class AgentBridge {
      * same session — forbidden by the protocol and rejected (or worse, mishandled)
      * by the agent. Waiting turns a protocol error into a short delay.
      *
+     * The gate is {@link LiveSession.promptInFlight} + the settle promise, NOT
+     * {@link LiveSession.running}: an ambient turn keeps `running` true for the
+     * whole drain while its prompt slot is already free, so `running` would
+     * refuse every message the user sends during a background task.
+     *
      * @param session - the session asking for the slot.
      * @returns whether the slot was claimed, and why not when it was not.
      */
@@ -511,9 +660,12 @@ export declare class AgentBridge {
         ok: false;
         reason: 'busy' | 'unsettled';
     }>;
+    /** Whether a turn currently holds the agent prompt slot (see `promptInFlight`). */
+    private promptSlotHeld;
     /**
-     * Mark the agent-side turn as in flight and hand back the settler its stream
-     * owner must call once the agent is actually done with it.
+     * Mark the agent-side turn as in flight — claim the agent prompt slot and
+     * open the settle gate — and hand back the settler its stream owner must
+     * call once the agent is actually done with it.
      *
      * @param session - the session whose turn is starting.
      * @returns the settler (idempotent; also used by connection loss).
@@ -522,7 +674,8 @@ export declare class AgentBridge {
     /**
      * Open a session's settle gate without owning its turn stream: the turn's
      * stream is gone (a resume, a release) but the next prompt still waits on
-     * this promise, and nothing is left that could ever resolve it.
+     * this promise, and nothing is left that could ever resolve it. The prompt
+     * slot itself goes with it: whatever held it is gone too.
      */
     private openSettleGate;
     view(): AgentView;
@@ -646,9 +799,25 @@ export declare class AgentBridge {
      * {@link BridgeTuning.staleCancelRetryDelayMs}, out-waiting the cleanup
      * window, bounded by {@link BridgeTuning.staleCancelMaxRetries}; a genuinely
      * requested cancel (`cancelRequestedAtTurn` still names this generation)
-     * returns as-is.
-     */
-    runPrompt(session: LiveSession, text: string, turnId: string): Promise<string>;
+     * returns as-is — checked BOTH before the delay and after it, so a second
+     * stop click inside the retry window does not resend the prompt the user
+     * just stopped.
+     *
+     * `turnGen` is the {@link LiveSession.turnSeq} this prompt was sent for. A
+     * stale-cancel resend is only allowed while that generation still owns the
+     * session: once a successor turn began (the cancel fallback finalized this
+     * one and the user moved on), resending would race a second `session/prompt`
+     * into the successor's turn. The late answer is returned as-is instead.
+     *
+     * The RESPONSE's `_meta` travels with the stop reason: it is the only place
+     * an agent says whether the prompt actually queued a conversation turn (see
+     * `CodebuddyMeta.conversationRequestId`), which decides whether an instant
+     * answer was the turn ending or a fold into a background drain.
+     */
+    runPrompt(session: LiveSession, prompt: string | ContentBlock[], turnId: string, turnGen: number): Promise<{
+        stopReason: string;
+        meta?: Record<string, unknown>;
+    }>;
     cancel(session: LiveSession): Promise<void>;
     /**
      * An agent that ignores the `session/cancel` notification must not wedge the
@@ -666,10 +835,19 @@ export declare class AgentBridge {
     private armCancelFallback;
     /**
      * Force the local end of one turn whose agent never acknowledged it: clear
-     * `running`, open the settle gate, and broadcast the turn end with `turnId:
-     * ''` (there is no agent response to attribute it to). Shared by the cancel
+     * `running`, open the settle gate, and end the turn. Shared by the cancel
      * fallback and the stall watchdog.
      *
+     * A live controller owns the turn's streaming face — its segment queue, its
+     * ambient clocks and its `turn/end` id. Ending the turn behind its back
+     * would leave the driver step parked on an open queue, and the controller's
+     * own timers would later broadcast a SECOND `turn/end` for a turn already
+     * closed. So when the session still points at a current controller, the
+     * force goes THROUGH it (`forceFinalize`), which runs the same closing work
+     * as a normal settle exactly once. Only a turn with no live controller (an
+     * `/acp`-RPC turn, or one already retired) falls back to the local broadcast
+     * with `turnId: ''` — there is no stream whose id could be named.
+     *
      * Generation-guarded: a turn that already ended — or that a later turn
      * superseded — is not this call's to finalize. Returns whether it acted; a
      * `false` means the caller was late and must leave the session alone.
@@ -1022,6 +1200,14 @@ interface SegmentState {
     activeToolCall: AcpToolCallSnapshot | undefined;
     /** Whether this segment opened at least one tool-call block. */
     hasCard: boolean;
+    /**
+     * The segment belongs to an ambient wait: the agent folded our prompt into a
+     * background drain it started itself. Tool traffic is recorded (so the
+     * transcript and any parked tool-output waiter get it) but opens NO card —
+     * a card would make the host loop execute a tool for a turn whose answer has
+     * not even started streaming yet.
+     */
+    ambient: boolean;
     finished: boolean;
 }
 /** How one segment's stream ends, in `StreamChunk.finish` terms. */
@@ -1071,13 +1257,111 @@ declare class TurnStreamController {
     private readonly rollbackFirstTurn;
     private segment;
     private settled;
+    /** Whether the turn's closing work already ran (see `closeTurn`). */
+    private closedTurn;
     private disposed;
     private readonly seenCalls;
     private readonly announcedKinds;
     /** Narrative lines (permission asks) that arrived while no segment was open. */
     private readonly pendingProse;
     sawVisibleBlock: boolean;
+    /**
+     * Whether THIS turn streamed its own prose (text or reasoning), i.e. an
+     * answer that is not the background drain's. Tool cards do not count — a
+     * drain that only ran tools delivered no words to the conversation.
+     */
+    private sawAgentProse;
+    /**
+     * Whether any `agent_message_chunk` text reached the plane. Reasoning does
+     * not count: a steer whose drain only thought is still a turn with no answer
+     * text, and must say so when it closes.
+     */
+    private sawVisibleText;
+    /**
+     * The CodeBuddy request id this turn has adopted as its own (from the
+     * prompt RESPONSE's `conversationRequestId`, or from the first update that
+     * named one). Used to keep a background drain's prose out of the user's
+     * answer; `undefined` means "unknown" and nothing is split (fail-open).
+     */
+    private turnRequestId?;
+    /**
+     * Updates the session's background drain already streamed while this turn's
+     * OWN request id was still unknown. They are NOT folded on arrival: a drain
+     * tick that lands before the prompt response could otherwise teach the turn
+     * the drain's id (`noteTurnRequestId`) and mix the drain's text into the
+     * user's answer. Withheld here (cursor already advanced — the transcript
+     * keeps a copy) until the response decides what this turn is:
+     * - a normal turn (response carries a conversation id) discards them — they
+     *   were never this turn's answer;
+     * - a steered turn flushes them into the segment, in order, once
+     *   `awaitAmbient` marks the segment ambient (tool cards suppressed).
+     */
+    private readonly pendingAmbientUpdates;
+    private pendingAmbientChars;
+    /**
+     * Whether the bounded buffer dropped at least one update. The flush then
+     * says so in the conversation instead of silently losing the front of the
+     * drain's output (constraint 29: ACP payloads are never dropped silently).
+     */
+    private pendingAmbientTruncated;
+    /** The ambient wait in progress, if the agent folded this prompt into a drain. */
+    private awaitingAmbient?;
+    /**
+     * The prompt response named no conversation turn while a drain this session
+     * retired RECENTLY may still be running without re-announcing. The turn still
+     * settles at once (a drain record that no update revived is not waited on),
+     * but its zero-output report says the turn may have been folded into that run
+     * instead of blaming the agent and suggesting a resend.
+     */
+    private recentRetiredDrain;
+    /** The outcome of a settle whose closing work is waiting one macrotask (see `settle`). */
+    private pendingOutcome?;
+    private closeScheduled;
     private cursorSeq;
+    /**
+     * Burst tracker for this turn, fed from the LIVE hub frames only. Segment
+     * replay must not touch it: every event is already counted once when it
+     * arrived, and replay would double the numerator and the gaps.
+     */
+    private readonly tps;
+    private tpsSeq;
+    private lastTpsPushAt;
+    /**
+     * The ambient quiet/ceiling windows, read once from the manager: they are
+     * deployment tuning, not per-tick facts, and small test values must be stable
+     * for the whole turn (see {@link BridgeTuning.ambientQuietMs} for the
+     * measured CodeBuddy tick cadence these defaults come from).
+     */
+    private readonly ambientTuning;
+    /**
+     * The detached workers this turn dispatched (see {@link BackgroundDispatch}),
+     * by `toolCallId`, recorded from the wire while the turn is still streaming —
+     * typically in the first step, before the prompt response lands. A turn may
+     * dispatch several, and the hold waits for ALL of them.
+     */
+    private readonly dispatches;
+    /** The detached-worker hold in progress, once a segment carries it. */
+    private backgroundHold?;
+    /**
+     * A hold parked because the prompt response landed while NO driver segment
+     * was open (the host is between steps, about to execute the Agent card). It
+     * begins when the next `startSegment` opens — or closes after a bounded
+     * grace so a host that never opens one does not hang the turn.
+     */
+    private pendingBackgroundHold?;
+    /**
+     * The hold's own windows, read once at construction like the ambient pair:
+     * `taskMaxMs` is the worker phase's ceiling, `graceMs` the parked hold's
+     * bounded wait for a driver step (see {@link BridgeTuning.backgroundTaskMaxMs}
+     * and {@link BridgeTuning.backgroundParkedGraceMs}).
+     */
+    private readonly backgroundTuning;
+    /**
+     * When this controller was built. Only a drain announced AFTER this moment
+     * may be adopted by the hold: an `ambient` record that predates the turn is
+     * some earlier run's, and folding its text would mix two answers.
+     */
+    private readonly constructedAt;
     constructor(manager: BridgeManager, hub: EventHub, session: LiveSession, turnId: string, 
     /** Releases the agent-side turn slot (the `beginTurn` settler; idempotent). */
     endTurn: () => void, rollbackFirstTurn: (session: LiveSession) => void);
@@ -1102,11 +1386,270 @@ declare class TurnStreamController {
     startSegment(): SegmentState;
     /** Finish the segment on air (if any). Used by cancel paths and teardown. */
     finishActive(reason: SegmentFinishReason): void;
+    /** Whether this turn already streamed prose of its own (not a drain's). */
+    get hasAgentProse(): boolean;
+    /**
+     * Keep the turn open for a background drain the agent folded our prompt into.
+     *
+     * THE SHAPE: the agent answered `session/prompt` at once (CodeBuddy returns
+     * `end_turn` in ~14ms when it merges the message into a drain it is already
+     * running) and the real answer streams afterwards under the DRAIN's request
+     * id. Closing on the response would cut the turn before its text exists —
+     * which is exactly the bug this state exists for. So:
+     *
+     * - the agent-side prompt slot is released (`endTurn`: the response HAS
+     *   landed) but the turn is NOT settled: `settled` means "the turn is over",
+     *   and it is not — no `turn/end`, no `running = false`, no segment close;
+     * - the segment keeps folding the session's updates, with cards suppressed
+     *   (see `SegmentState.ambient`): the host must not execute a background
+     *   tool for a turn whose answer has not begun;
+     * - any update on the session resets the quiet clock, and the drain's end is
+     *   its silence (a `session_end` is rejected by the SDK's schema and never
+     *   reaches us — never wait for one); a hard ceiling closes what never ends.
+     */
+    awaitAmbient(requestId: string, stopReason: string): void;
+    /**
+     * The prompt response named no conversation turn while a drain the session
+     * retired recently may still be running (and did not re-announce): the turn
+     * cannot be held open, but a zero-output report must not blame the agent.
+     * See `hasRecentRetiredAmbient` for the window.
+     */
+    noteRecentRetiredDrain(): void;
+    /**
+     * Whether this turn dispatched a detached worker whose answer is still
+     * outstanding. Read when the prompt response lands: such a turn is NOT over
+     * even though the agent answered it (see {@link holdForBackgroundDispatch}).
+     *
+     * Two ways a dispatch keeps the turn open:
+     * - it has not reported back yet (the worker is still running), or
+     * - it DID report — before the response, even — but it was structurally
+     *   detached and emitted worker updates: the drain that carries its report
+     *   is still coming.
+     * A synchronous `Agent` / `Task` call (completed, no `isBackground`, no
+     * worker updates) matches neither and closes normally.
+     */
+    get dispatchedDetachedWorker(): boolean;
+    /** The hold this turn is inside — adopted, or parked waiting for a step. */
+    private activeBackgroundHold;
+    /** Whether every KNOWN dispatch has reported (no dispatch at all counts as done). */
+    private allDispatchesCompleted;
+    /**
+     * Hold the turn open for the detached worker(s) its `Agent` tool calls
+     * dispatched — the second controlled ambient-family exception (constraint
+     * 23), not a new idle watchdog.
+     *
+     * THE SHAPE (measured against CodeBuddy 2.179.0, multitask on): the
+     * coordinator opens an `Agent` call that hands work to a background worker,
+     * says "已派…", and the `session/prompt` RESPONSE arrives normally while the
+     * worker keeps running. The worker's own updates (requestId B +
+     * `parentToolCallId`) never touch this session's message; when it finishes,
+     * the agent starts a background DRAIN (requestId A — the response's own
+     * `conversationRequestId`) whose steps carry the report and the final answer.
+     * Nothing tells the client the worker is running: no `session_end` (the SDK's
+     * schema rejects it) and an `agentPhase` idle tick even fires BETWEEN the
+     * worker and the drain. So the response cannot close the turn.
+     *
+     * The hold:
+     * - releases the agent-side prompt slot (`endTurn`: the response landed)
+     *   while keeping `running` and the driver step open;
+     * - marks the segment background, so EVERY tool call for the rest of the
+     *   hold — the workers', the drain's TaskOutput — stays transcript-only and
+     *   the final message carries text with no card in front of it;
+     * - waits in two phases: the worker phase only has the
+     *   {@link BridgeTuning.backgroundTaskMaxMs} ceiling (a detached worker goes
+     *   silent for tens of seconds while it works) and ends only when ALL known
+     *   dispatches reported, after which the drain phase uses the ambient
+     *   windows.
+     */
+    holdForBackgroundDispatch(stopReason: string, requestId?: string): void;
+    /** Give a (possibly parked) hold a driver segment: cards off for the rest of it. */
+    private adoptBackgroundHold;
+    /**
+     * The worker phase is over once EVERY known dispatch reported: the drain
+     * that carries their reports is (about to be) running, so the existing
+     * ambient windows take over, measured from HERE.
+     *
+     * An announced run is accepted immediately, but while any dispatch is still
+     * incomplete it only records the id and switches the hold's primary run —
+     * arming the quiet clock there would let a drain that spoke early cut the
+     * turn off before its other worker ever reports.
+     */
+    private startBackgroundDrain;
+    /**
+     * A dispatch that lands while the drain phase already began means the
+     * coordinator handed out NEW work: the worker phase is back, and with it the
+     * absence of a quiet window.
+     */
+    private enterBackgroundWorkerPhase;
+    /** Push the drain phase's quiet clock out: every update is evidence of work. */
+    private armBackgroundQuiet;
+    /**
+     * Any session update restarts the drain phase's quiet clock. Only an
+     * ADOPTED hold has one: a parked hold's wait belongs to its grace timer, and
+     * the worker phase never has a clock at all.
+     */
+    private noteBackgroundHoldActivity;
+    /** The drained run went quiet: the turn ends with the stop reason the response gave. */
+    private onBackgroundQuiet;
+    /** The hold outlived its ceiling (worker or drain): the run is still going. */
+    private onBackgroundHard;
+    /**
+     * No driver step opened inside the grace: the host is not coming back for
+     * this turn's Agent card. Close it the way a quiet ambient ending does — the
+     * deferral line, never the zero-output blame — and keep ONE drain record:
+     * the worker may still report into a run no turn is waiting on.
+     *
+     * A parked hold has NO segment by definition, so the chat plane has nowhere
+     * to put the deferral line: it goes to the settings log (`agent/notice`)
+     * instead of being parked on prose nobody will read.
+     */
+    private onBackgroundGraceExpired;
+    /**
+     * Close a detached-worker hold exactly once. A turn that folded NO answer
+     * text from its held runs says where the rest of the output will land (the
+     * deferral wording, never the silent-failure blame); the parent's interim
+     * acknowledgement does not count as that answer.
+     *
+     * Ownership of the drain ids at close (`releaseBackgroundHoldIds`): a quiet
+     * close retires every accepted id and drops the session record; a hard or
+     * grace close keeps exactly ONE record, because the run is provably still
+     * going and a later update or re-announcement must revive it normally.
+     */
+    private closeBackgroundHold;
+    /** Write a hold's deferral line into the settings log (`agent/notice`). */
+    private broadcastBackgroundDeferral;
+    /** Drop a hold's clocks. The hold object itself stays for its `retired` mark. */
+    private clearBackgroundHoldTimers;
+    /**
+     * Drop every hold clock (teardown / a forced ending). `retire` also gives up
+     * every accepted run id — a SUCCESSOR turn must never fold the abandoned
+     * hold's drain or worker text into its own answer.
+     */
+    private clearBackgroundHold;
+    /**
+     * Settle what happens to the session's drain records when a hold closes.
+     *
+     * `hard: false` (quiet close, cancel, teardown): the run is no longer waited
+     * on, so EVERY accepted id is retired — its late text stays transcript-only
+     * for whatever turn runs next — and the session record is dropped if it
+     * names one of them.
+     *
+     * `hard: true` (ceiling / parked grace): the run is provably still going.
+     * Exactly ONE record survives — the session's current drain if it has one,
+     * else the hold's primary run — with its activity clock refreshed; the other
+     * accepted ids are retired. A hold whose primary id had no session record
+     * CREATES one, so a successor's `noteTurnRequestId` cannot adopt that id.
+     * Every accepted id therefore ends up either retired or owned by
+     * `session.ambient`; never both unowned and unretired.
+     */
+    private releaseBackgroundHoldIds;
+    /**
+     * Fold the withheld drain updates that belong to this hold into its segment.
+     * The rest of the buffer was some OTHER run's text: it is dropped here (the
+     * transcript keeps it), never leaked into this turn's answer.
+     */
+    private flushBackgroundHoldUpdates;
+    /**
+     * Follow the detached-worker signals of one live update.
+     *
+     * Only CodeBuddy sends them (`codebuddyMetaOf` answers `undefined` for every
+     * other agent, so nothing here can fire for them):
+     * - an `Agent` / `Task` `tool_call` records the dispatch — the FIRST send
+     *   needs that CodeBuddy shape;
+     * - the SAME call re-sent with `isBackground: true`, or any update naming it
+     *   as its `parentToolCallId`, marks the work DETACHED;
+     * - that call reporting completed / failed is read BY ID: the real
+     *   completion frame carries NO `_meta` at all, so requiring the CodeBuddy
+     *   shape here would miss every real completion;
+     * - any update carrying `parentToolCallId` is the worker's OWN turn — it
+     *   proves the worker alive but never belongs to this session's answer;
+     * - an `unsolicitedTurn` announcement is the drain that carries the report.
+     */
+    private trackBackgroundDispatch;
+    /**
+     * A dispatch just reported: once the LAST one has, the drain phase starts.
+     * Until then the turn stays in its worker phase, with no quiet clock.
+     */
+    private noteDispatchProgress;
+    /** Any session update is evidence the drain still works: push the quiet clock out. */
+    private noteAmbientActivity;
+    /** The drain went quiet: the turn ends with the stop reason the response gave. */
+    private onAmbientQuiet;
+    /** The drain outlived the ceiling: say where the rest will land, then close. */
+    private onAmbientHard;
+    /**
+     * Close an ambient wait exactly once. A turn that produced no answer TEXT
+     * says so: the drain's output is in the ACP transcript view, and this
+     * bubble must not be empty (the zero-output report, reworded for a turn that
+     * was deferred rather than failed).
+     */
+    private finishAmbient;
+    /** Drop the ambient wait's clocks (the turn is being closed by someone else). */
+    private clearAmbientWait;
+    /**
+     * Withhold one background-drain update until the prompt response says what
+     * this turn is. The cursor advances past it anyway: it is already in the
+     * transcript, and replaying it into a later segment would emit it twice.
+     * Bounded (see `PENDING_AMBIENT_MAX_*`) — the transcript still keeps every
+     * entry the buffer drops.
+     */
+    private bufferAmbientUpdate;
+    /** Fold the withheld drain updates into the now-ambient segment, once, in order. */
+    private flushPendingAmbient;
+    /** Drop withheld drain updates: this turn is not the drain, or it is closing. */
+    private clearPendingAmbient;
     /** The agent settled its `session/prompt`. Ends the turn's streaming face. */
     settle(outcome: TurnSettle): void;
-    /** Cancelled by the user: finish the on-air segment and release the turn's slots. */
+    /**
+     * Force the local end of this turn — the cancel fallback and any watchdog
+     * that reached the controller. Runs the SAME closing work as a normal settle
+     * (`closeTurn`): the ambient clocks stop, the on-air segment closes (so the
+     * driver step parked on its queue ends), exactly one `turn/end` goes out
+     * with THIS turn's id, the session stops running and the prompt slot is
+     * released. Idempotent: a turn that already closed ignores the call.
+     */
+    forceFinalize(outcome: TurnSettle): void;
+    /**
+     * Run the deferred closing work now, when a driver step is about to open on
+     * an already settled turn: the continuation step must see the closed turn
+     * (and the session NOT left `running` across the macrotask boundary).
+     * Idempotent — the scheduled tick then finds nothing left to do.
+     */
+    private flushScheduledClose;
+    /**
+     * Fold the notifications that reached the transcript but not the segment:
+     * the tail a response raced past. Stops AT a cutting event without consuming
+     * it (same rule as `startSegment`) — its next segment is not this turn's.
+     */
+    private drainTail;
+    /**
+     * End the turn exactly once: burst metrics, ONE `turn/end`, the provisional
+     * lock, the closing text, the segment, the session flags, the prompt slot.
+     *
+     * `ambient.line` marks a controlled ambient ending: the given line closes
+     * the segment when the turn carried no answer text, instead of the generic
+     * zero-output warning (which would blame the agent for a turn the drain
+     * simply had not finished yet). `ambient.keepAmbient` says the ending was the
+     * CEILING, not silence: see the drain-record comment below.
+     */
+    private closeTurn;
+    /**
+     * Cancelled by the user: finish the on-air segment and release the turn's
+     * slots. An AMBIENT turn has already released the prompt slot (its response
+     * landed) and holds no segment the cancel fallback could close, so the
+     * cancel closes the turn itself with the cancelled stop.
+     */
     abortActiveSegment(): void;
-    /** Stop observing and release the manager's index. Idempotent. */
+    /**
+     * Stop observing and release the manager's index. Idempotent.
+     *
+     * The segment is CLOSED here (aborted) before unsubscribing: a driver step
+     * parked on its queue (`yield* segment.queue`) only ends when the queue
+     * closes, and a controller replaced by the conversation's next turn would
+     * otherwise leave that step hanging forever. An already finished segment is a
+     * no-op, and the session's flags are left alone — a superseded turn must not
+     * mark the newer turn's session idle.
+     */
     dispose(): void;
     /**
      * Stop observing and release the manager's index WITHOUT touching the
@@ -1118,7 +1661,19 @@ declare class TurnStreamController {
     private finishSegment;
     /** A segment opened on an already-settled turn: replay, then close it out. */
     private finishAfterSettle;
+    /**
+     * The "protocol says success, the bubble is empty" line. When a recently
+     * retired drain may have taken the prompt without re-announcing itself, say
+     * that instead of blaming the agent: the output exists in the transcript.
+     */
+    private zeroOutputLine;
     private onEvent;
+    /** Feed one live update into the turn's burst tracker. Never called by replay. */
+    private trackTps;
+    /** Throttled live aggregate so the dock's speed moves during a long turn. */
+    private pushLiveTps;
+    /** Close the turn's metrics: persist the measurable part, then broadcast it. */
+    private finalizeTps;
     /**
      * Put one narrative line into the turn's prose stream.
      *
@@ -1132,12 +1687,33 @@ declare class TurnStreamController {
     private recordWithoutSegment;
     /** Record a tool call's output (idempotent) and wake any waiter. */
     private noteToolRecord;
+    /**
+     * Whether this update belongs to a background drain — the one the session is
+     * waiting on, or one whose wait already closed (retired) but whose run can
+     * still speak.
+     */
+    private isAmbientOwned;
+    /** Learn this turn's own CodeBuddy request id from the first update naming one. */
+    private noteTurnRequestId;
+    /** Adopt the request id the prompt RESPONSE declared for this turn. */
+    adoptTurnRequestId(requestId: string): void;
+    /**
+     * Prose of the session's background drain while this turn runs on its OWN
+     * request id: it belongs to the background run, not to the user's answer.
+     * Fail-open by design — an unknown turn id splits nothing, and a turn that
+     * was itself folded into the drain keeps its prose.
+     */
+    private isForeignAmbientText;
     /**
      * The turn's whole fold, shared by live events and segment replay. Visible
      * non-tool events END a card-bearing segment instead of joining it — that is
      * the segmentation rule that puts each card between two assistant messages.
      * Returns whether the event was consumed into this segment: the cutting
      * event is left unconsumed (and thus behind the cursor) for the next one.
+     *
+     * `seq` is the update's transcript position when the caller has one: the
+     * detached-worker hold uses it to count only the answer text that arrived
+     * AFTER the hold began (a parked hold replays the parent's earlier ack).
      */
     private foldInto;
     private emitProse;
@@ -1254,6 +1830,28 @@ export declare class BridgeManager {
     private readonly turnStreams;
     /** The segmented turn a continuation step of one chat session must resume. */
     turnStreamFor(dshSessionId: string): TurnStreamController | undefined;
+    /**
+     * The ambient windows a turn's controller reads once at construction (see
+     * {@link BridgeTuning.ambientQuietMs}). Exposed as a plain snapshot so the
+     * controller never pokes at the manager's tuning object, and tests can tune
+     * the cadence through the constructor like every other window.
+     */
+    get ambientTuning(): {
+        quietMs: number;
+        maxMs: number;
+    };
+    /**
+     * The detached-worker hold's windows, read once at controller construction
+     * for the same reason as {@link ambientTuning}: `taskMaxMs` is the worker
+     * phase's only clock (see {@link BridgeTuning.backgroundTaskMaxMs}) and
+     * `graceMs` the bounded wait a PARKED hold gives the host to open its
+     * continuation step (see {@link BridgeTuning.backgroundParkedGraceMs}). The
+     * drain phase reuses {@link ambientTuning}.
+     */
+    get backgroundTuning(): {
+        taskMaxMs: number;
+        graceMs: number;
+    };
     /** Index a turn's controller, retiring whatever turn it supersedes. */
     rememberTurnStream(dshSessionId: string, controller: TurnStreamController): void;
     /** Drop a controller from the index (its own `dispose` calls back into this). */
@@ -1301,6 +1899,10 @@ export declare class BridgeManager {
      * sessions and headless deployments.
      */
     setSessionWorkspaceResolver(resolver?: SessionWorkspaceResolver): void;
+    /**
+     * Set the attachment service or context used to resolve image attachments in user prompts.
+     */
+    setAttachmentResolver(resolver?: unknown): void;
     /**
      * Wire the ACP-mode probe: given a DSH session id, report whether that
      * session runs the ACP agent preset. The host half reads it back from the
@@ -1592,6 +2194,12 @@ export declare class BridgeManager {
      * missing agent does not erase the choice it was made for.
      */
     private loadPersistedChoices;
+    /**
+     * Fold one settled ACP turn's measurable burst into the session aggregate and
+     * persist it. A turn with no measured inter-chunk gap contributes neither
+     * side: adding its tokens with zero time would inflate the session rate.
+     */
+    noteSessionBurst(session: LiveSession, outputTokens: number, burstMs: number): void;
     private persistAgents;
     /**
      * Restore chat session records from disk as PARKED sessions.
@@ -1878,7 +2486,7 @@ export declare class BridgeManager {
     startSession(agentId: string, cwd: string | undefined): Promise<{
         sessionId: string;
     }>;
-    prompt(sessionId: string, text: string): Promise<{
+    prompt(sessionId: string, prompt: string | ContentBlock[]): Promise<{
         turnId: string;
     }>;
     /** The late answer landed (or failed): the turn is no longer an orphan. */
@@ -2011,6 +2619,7 @@ export declare class BridgeManager {
     private forgetDshSession;
     private sessionWorkspaceResolver?;
     private acpModeResolver?;
+    private attachmentResolver?;
     /** Cached `chatSessionAcpMode` answers, keyed by DSH chat session id. */
     private readonly acpModeCache;
     /** In-flight cold reads behind `chatSessionAcpModeAnswer`, keyed by session id. */