@jini-ai/daemon 0.5.3 → 0.5.4

package/dist/session-coordination.d.ts

@@ -4,36 +4,51 @@ export interface ConversationRun {
     readonly conversationId: string;
     readonly runId: string;
 }
+/** In-process occupancy only: durable answer ownership belongs to the unfinished message.
+ * An empty tracker after restart does not prove a CLI child died; recovery must verify its saved
+ * identity before native resume, otherwise reconstruct under a fresh session. */
 export interface LiveRunTracker {
-    register(args: ConversationRun): void;
-    unregister(args: ConversationRun): void;
-    hasConcurrentLiveRun(args: ConversationRun): boolean;
-    concurrentLiveRunIds(args: ConversationRun): string[];
+    /** Register synchronously before awaiting, so another start observes this run as live. */
+    register(args: ConversationRun, optional?: Record<string, never>): void;
+    /** Idempotent removal; safe for a run that was never registered. */
+    unregister(args: ConversationRun, optional?: Record<string, never>): void;
+    /** Excludes runId itself; concurrent processes must not resume the same CLI transcript. */
+    hasConcurrentLiveRun(args: ConversationRun, optional?: Record<string, never>): boolean;
+    concurrentLiveRunIds(args: ConversationRun, optional?: Record<string, never>): string[];
+    /** Undefined after unregister; tool calls use this to resolve their conversation. */
     conversationIdForRun(args: {
         runId: string;
-    }): string | undefined;
+    }, optional?: Record<string, never>): string | undefined;
 }
-export declare function createLiveRunTracker(_args: Record<string, never>): LiveRunTracker;
+/** Fresh private maps keep daemon instances independent. */
+export declare function createLiveRunTracker(_args: Record<string, never>, _optional?: Record<string, never>): LiveRunTracker;
 export interface ConversationStartLock {
+    /** Serialize each conversation separately; undefined runs immediately. Rejection reaches only
+     * its caller and never poisons queued sections. Entries disappear once their queues drain. */
     run<T>(args: {
         conversationId: string | undefined;
         critical: () => Promise<T>;
-    }): Promise<T>;
-    trackedConversationCount(): number;
+    }, optional?: Record<string, never>): Promise<T>;
+    trackedConversationCount(required: Record<string, never>, optional?: Record<string, never>): number;
 }
-/** Serialize initialization only. Run execution belongs outside the critical section. */
-export declare function createConversationStartLock(_args: Record<string, never>): ConversationStartLock;
+/** Serialize the session-binding read/decide/write so simultaneous first turns cannot mint competing
+ * sessions and orphan a binding. Lock only initialization: holding it across execution would queue
+ * turns behind minutes of work instead of allowing an immediate concurrency refusal. In-process only. */
+export declare function createConversationStartLock(_args: Record<string, never>, _optional?: Record<string, never>): ConversationStartLock;
 /** Existing lifecycle port; no persistence is imported or implemented here. */
 export interface StoppingRunLifecycle {
     onCancelRequested(args: {
         runId: string;
         listener: () => void;
-    }): () => void;
+    }, optional?: Record<string, never>): () => void;
     waitForTerminal(args: {
         runId: string;
-    }): Promise<unknown>;
+    }, optional?: Record<string, never>): Promise<unknown>;
 }
 export declare const STOPPING_RUN_WAIT_MS = 20000;
+/** Wait only for cancelled peers: cancellation records intent before the CLI exits. Active peers
+ * can run for minutes and stay subject to the concurrency rule. Remove ended peers here because
+ * ordering against their own terminal cleanup is not guaranteed. The wait is bounded by timeoutMs. */
 export declare function waitForStoppingRuns({ tracker, lifecycle, scheduler, conversationId, runId }: {
     tracker: LiveRunTracker;
     lifecycle: StoppingRunLifecycle;
@@ -52,20 +67,22 @@ export interface FailingRunLifecycle {
                 message: string;
             };
         };
-    }): Promise<unknown>;
+    }, optional?: Record<string, never>): Promise<unknown>;
     finish(input: {
         runId: string;
         status: 'failed';
         code: null;
         signal: null;
         resumable: false;
-    }): Promise<unknown>;
+    }, optional?: Record<string, never>): Promise<unknown>;
 }
+/** Emit the refusal reason on the run stream so the chat can show and save it. Event delivery
+ * is best-effort; finishing remains mandatory even when the stream cannot accept the event. */
 export declare function failRunBeforeStart({ lifecycle, runId, message }: {
     lifecycle: FailingRunLifecycle;
     runId: string;
     message: string;
-}): Promise<void>;
+}, _optional?: Record<string, never>): Promise<void>;
 export interface AgentCapabilities {
     readonly resumesSessionViaCli?: boolean;
     readonly resumesSessionViaAcpLoad?: boolean;
@@ -74,42 +91,59 @@ export interface AgentCapabilities {
 export interface AgentCapabilityResolver {
     lookup(args: {
         agentId: string;
-    }): AgentCapabilities | undefined;
+    }, optional?: Record<string, never>): AgentCapabilities | undefined;
 }
+/** Use declared CLI-resume capabilities, never a hand-kept agent list. Capture-style CLIs mint
+ * their own ids; handing one a host id would persist a session that does not exist. ACP-only
+ * resume uses session/load rather than CLI flags. Unknown agents fail closed. */
 export declare function agentAcceptsHostMintedSessionId({ agentId, agents }: {
     agentId: string;
     agents: AgentCapabilityResolver;
-}): boolean;
+}, _optional?: Record<string, never>): boolean;
+/** CLI/ACP-resuming agents carry prior turns and may receive only the newest user message.
+ * Resolve capabilities synchronously through the port; no PATH probing is needed. */
 export declare function agentCarriesOwnMemory({ agentId, agents }: {
     agentId: string;
     agents: AgentCapabilityResolver;
-}): boolean;
+}, _optional?: Record<string, never>): boolean;
+/** Mint only a cold, conversation-scoped start for a host-id-capable agent. Persist and pass the
+ * same id before spawning: relying only on a terminal report can orphan a crashed first turn.
+ * A resume already has a binding; replacing it would fork the conversation. */
 export declare function resolveHostMintedSessionId(input: {
     conversationId: string | undefined;
     effectiveResumeSessionId: string | null;
     acceptsHostMintedSessionId: boolean;
     mint: () => string;
-}): string | null;
+}, _optional?: Record<string, never>): string | null;
+/** Return { newSessionId } when present, otherwise omit the key entirely for the run-input spread. */
 export declare function resolveNewSessionField({ hostMintedSessionId }: {
     hostMintedSessionId: string | null;
-}): {
+}, _optional?: Record<string, never>): {
     newSessionId?: string;
 };
+/** Return { resumeSessionId } when present, otherwise omit the key entirely for the run-input spread. */
 export declare function resolveResumeSessionField({ storedSessionId }: {
     storedSessionId: string | null;
-}): {
+}, _optional?: Record<string, never>): {
     resumeSessionId?: string;
 };
+/** Only a terminal end with a nonempty sessionRef establishes a session id to persist. */
 export declare function extractSessionRefFromEndEvent({ event }: {
     event: RunProtocolEvent;
-}): string | undefined;
+}, _optional?: Record<string, never>): string | undefined;
+/** Clear only an attempted resume whose terminal event reconfirms no session. The event cannot
+ * distinguish a dead session from an unrelated early failure: one cold turn costs less than
+ * retrying an unrecoverable id forever. A cold run has no stored binding to clear. */
 export declare function shouldClearSessionOnFailedResume({ event, attemptedResumeSessionId }: {
     event: RunProtocolEvent;
     attemptedResumeSessionId: string | null;
-}): boolean;
+}, _optional?: Record<string, never>): boolean;
+/** Refuse a forced cold start when a stored session, concurrent peer and memory-carrying agent
+ * coincide: the client may have sent only the latest prompt, so cold execution loses prior turns.
+ * A first turn or an agent receiving the full transcript has no such context to lose. */
 export declare function wouldForcedColdStartLoseConversationContext(input: {
     storedSessionId: string | null;
     hasConcurrentLiveRun: boolean;
     carriesOwnMemory: boolean;
-}): boolean;
+}, _optional?: Record<string, never>): boolean;
 //# sourceMappingURL=session-coordination.d.ts.map

package/dist/session-coordination.js

@@ -1,4 +1,5 @@
-export function createLiveRunTracker(_args) {
+/** Fresh private maps keep daemon instances independent. */
+export function createLiveRunTracker(_args, _optional = {}) {
     const runs = new Map();
     const conversations = new Map();
     function unregister({ conversationId, runId }) {
@@ -30,16 +31,20 @@ export function createLiveRunTracker(_args) {
         conversationIdForRun: ({ runId }) => conversations.get(runId),
     };
 }
-/** Serialize initialization only. Run execution belongs outside the critical section. */
-export function createConversationStartLock(_args) {
+/** Serialize the session-binding read/decide/write so simultaneous first turns cannot mint competing
+ * sessions and orphan a binding. Lock only initialization: holding it across execution would queue
+ * turns behind minutes of work instead of allowing an immediate concurrency refusal. In-process only. */
+export function createConversationStartLock(_args, _optional = {}) {
     const tails = new Map();
     return {
         run({ conversationId, critical }) {
             if (conversationId === undefined)
                 return critical();
             const result = (tails.get(conversationId) ?? Promise.resolve()).then(critical);
+            // A newer section may own this key already; deleting its tail would allow a third to race it.
             const release = () => { if (tails.get(conversationId) === tail)
                 tails.delete(conversationId); };
+            // Both settlements release immediately and make the tail non-rejecting for the next section.
             const tail = result.then(release, release);
             tails.set(conversationId, tail);
             return result;
@@ -48,9 +53,13 @@ export function createConversationStartLock(_args) {
     };
 }
 export const STOPPING_RUN_WAIT_MS = 20_000;
+/** Wait only for cancelled peers: cancellation records intent before the CLI exits. Active peers
+ * can run for minutes and stay subject to the concurrency rule. Remove ended peers here because
+ * ordering against their own terminal cleanup is not guaranteed. The wait is bounded by timeoutMs. */
 export async function waitForStoppingRuns({ tracker, lifecycle, scheduler, conversationId, runId }, { timeoutMs = STOPPING_RUN_WAIT_MS } = {}) {
     const stopping = tracker.concurrentLiveRunIds({ conversationId, runId }).filter(id => {
         let cancelled = false;
+        // Subscription replays a past cancellation synchronously; immediate unsubscribe avoids leaks.
         try {
             lifecycle.onCancelRequested({ runId: id, listener: () => { cancelled = true; } })();
         }
@@ -72,40 +81,59 @@ export async function waitForStoppingRuns({ tracker, lifecycle, scheduler, conve
         cancelTimer?.();
     }
 }
-export async function failRunBeforeStart({ lifecycle, runId, message }) {
+/** Emit the refusal reason on the run stream so the chat can show and save it. Event delivery
+ * is best-effort; finishing remains mandatory even when the stream cannot accept the event. */
+export async function failRunBeforeStart({ lifecycle, runId, message }, _optional = {}) {
     try {
         await lifecycle.emit({ runId: runId, input: { event: 'error', data: { message } } });
     }
     catch { /* Finishing remains mandatory. */ }
     await lifecycle.finish({ runId, status: 'failed', code: null, signal: null, resumable: false });
 }
-export function agentAcceptsHostMintedSessionId({ agentId, agents }) {
+/** Use declared CLI-resume capabilities, never a hand-kept agent list. Capture-style CLIs mint
+ * their own ids; handing one a host id would persist a session that does not exist. ACP-only
+ * resume uses session/load rather than CLI flags. Unknown agents fail closed. */
+export function agentAcceptsHostMintedSessionId({ agentId, agents }, _optional = {}) {
     const def = agents.lookup({ agentId });
     return Boolean(def?.resumesSessionViaCli) && !def?.capturesSessionIdFromStream;
 }
-export function agentCarriesOwnMemory({ agentId, agents }) {
+/** CLI/ACP-resuming agents carry prior turns and may receive only the newest user message.
+ * Resolve capabilities synchronously through the port; no PATH probing is needed. */
+export function agentCarriesOwnMemory({ agentId, agents }, _optional = {}) {
     const def = agents.lookup({ agentId });
     return Boolean(def?.resumesSessionViaCli) || Boolean(def?.resumesSessionViaAcpLoad);
 }
-export function resolveHostMintedSessionId(input) {
+/** Mint only a cold, conversation-scoped start for a host-id-capable agent. Persist and pass the
+ * same id before spawning: relying only on a terminal report can orphan a crashed first turn.
+ * A resume already has a binding; replacing it would fork the conversation. */
+export function resolveHostMintedSessionId(input, _optional = {}) {
     return input.conversationId !== undefined && input.effectiveResumeSessionId === null && input.acceptsHostMintedSessionId ? input.mint() : null;
 }
-export function resolveNewSessionField({ hostMintedSessionId }) {
+/** Return { newSessionId } when present, otherwise omit the key entirely for the run-input spread. */
+export function resolveNewSessionField({ hostMintedSessionId }, _optional = {}) {
     return hostMintedSessionId !== null ? { newSessionId: hostMintedSessionId } : {};
 }
-export function resolveResumeSessionField({ storedSessionId }) {
+/** Return { resumeSessionId } when present, otherwise omit the key entirely for the run-input spread. */
+export function resolveResumeSessionField({ storedSessionId }, _optional = {}) {
     return storedSessionId !== null ? { resumeSessionId: storedSessionId } : {};
 }
-export function extractSessionRefFromEndEvent({ event }) {
+/** Only a terminal end with a nonempty sessionRef establishes a session id to persist. */
+export function extractSessionRefFromEndEvent({ event }, _optional = {}) {
     if (event.kind !== 'end')
         return undefined;
     const id = event.payload.sessionRef;
     return typeof id === 'string' && id.length > 0 ? id : undefined;
 }
-export function shouldClearSessionOnFailedResume({ event, attemptedResumeSessionId }) {
+/** Clear only an attempted resume whose terminal event reconfirms no session. The event cannot
+ * distinguish a dead session from an unrelated early failure: one cold turn costs less than
+ * retrying an unrecoverable id forever. A cold run has no stored binding to clear. */
+export function shouldClearSessionOnFailedResume({ event, attemptedResumeSessionId }, _optional = {}) {
     return attemptedResumeSessionId !== null && event.kind === 'end' && extractSessionRefFromEndEvent({ event }) === undefined;
 }
-export function wouldForcedColdStartLoseConversationContext(input) {
+/** Refuse a forced cold start when a stored session, concurrent peer and memory-carrying agent
+ * coincide: the client may have sent only the latest prompt, so cold execution loses prior turns.
+ * A first turn or an agent receiving the full transcript has no such context to lose. */
+export function wouldForcedColdStartLoseConversationContext(input, _optional = {}) {
     return input.storedSessionId !== null && input.hasConcurrentLiveRun && input.carriesOwnMemory;
 }
 //# sourceMappingURL=session-coordination.js.map

package/dist/store/event-log/sqlite.js

@@ -81,10 +81,10 @@ export function openSqliteEventLog(input, options = {}) {
     resolveMaxEntriesPerRun(options.maxEntriesPerRun);
     let db;
     try {
-        db = openSqliteConnection({ filePath: input.file, open(file, settings) {
-                db = input.open(file, settings);
+        db = openSqliteConnection({ filePath: input.file, open({ filePath }, settings) {
+                db = input.open(filePath, settings);
                 return db;
-            }, pragmas: ['journal_mode = WAL'] });
+            } }, { pragmas: ['journal_mode = WAL'] });
         const log = bindSqliteEventLog(db, options);
         let closed = false;
         return { ...log, async close(_args) { if (closed)

package/dist/surface-exchanges.d.ts

@@ -1,61 +1,99 @@
+/**
+ * @file A **surface exchange**: a two-way, multi-message conversation with a human, held open inside
+ * one agent tool call.
+ *
+ * ## What this is
+ *
+ * The agent calls a tool. The tool opens an exchange, sends something for a person to look at, and
+ * waits. The person answers. The tool may send again — a follow-up question, an updated component
+ * tree, a validation error — and wait again, any number of times. When it is done it closes the
+ * exchange and returns, and the human's answers are the tool call's ordinary result. The agent is
+ * still alive the whole time, which is what makes the transcript correct by construction rather than
+ * reconstructed afterwards (ADR-055 Decision 4).
+ *
+ * A one-shot ask — show a form, get one submission — is the degenerate case, expressed by
+ * {@link askOnce}. It is a helper over this, not a separate mechanism.
+ *
+ * ## Channel-agnostic on purpose
+ *
+ * Nothing here knows what a surface *is*. Outbound messages are `@jini-ai/core`'s
+ * {@link SurfaceEmission}, which names its own channel; inbound answers are plain records. That is
+ * what lets one exchange drive MCP-UI (an HTML surface answering by tool call), A2UI (`createSurface`
+ * → action → `updateComponents` → action, which is inherently multi-turn), the run protocol's own
+ * channel-neutral `surface_request`/`surface_response` pair, or a paradigm that does not exist yet.
+ * The transports differ; "hold the agent's call open and pass messages both ways" does not.
+ *
+ * ## The inbound buffer is a correctness requirement, not a nicety
+ *
+ * A message can arrive while the handler is between {@link SurfaceExchange.receive} calls — busy
+ * composing its next send. Without somewhere to put it, that message is dropped and the exchange
+ * deadlocks on an answer the human already gave. So deliveries queue. This is the one thing that is
+ * genuinely painful to retrofit onto a one-shot store, which is why it is here before there is a
+ * multi-turn channel wired to need it.
+ *
+ * ## Opening requires an emitter, so the other deadlock is unrepresentable
+ *
+ * The second deadlock is structural: a handler waiting for an answer to a message it never managed
+ * to send. The daemon reads surfaces out of a *completed* tool result, so the return value cannot
+ * carry a message the same call is waiting on — only `ToolExecutionContext.emitSurface` can.
+ * {@link SurfaceExchangeStore.open} therefore takes that emitter as a required argument. A handler
+ * with no emitter cannot open an exchange at all, and must fail closed without an interactive channel.
+ *
+ * ## Not a secret
+ *
+ * An exchange id is a **correlation handle**. It says which in-flight call a message belongs to and
+ * confers nothing — contrast the former token store, which minted a genuine secret because the
+ * delete it guards is a second tool call the model could otherwise make itself (ADR-055 Decision 3).
+ * Ids here are stored in the clear and compared with `===`. Copying that module's hashing and
+ * constant-time comparison would imply a security property this handle does not carry.
+ *
+ * The property this file IS responsible for is narrower: **a message resolves at most one waiting
+ * receive, on an exchange opened by the same tool for the same principal.**
+ *
+ */
 import type { Clock, IdGenerator } from '@jini-ai/core/primitives';
-import type { SurfaceEmission, SurfaceEmitter } from '@jini-ai/core';
+import type { SurfaceEmission, SurfaceAnswerChannel, SurfaceMessage, SurfaceExchangeConversation, SurfaceExchangeStore } from '@jini-ai/core';
+export { SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWER_PARAM, } from '@jini-ai/core';
+export type { SurfaceAnswerChannel, SurfaceExchangeBinding, SurfaceMessage, SurfaceDeliveryRejectionReason, DeliverResult, SurfaceExchange, SurfaceExchangeConversation, SurfaceDeliverySpec, SurfaceExchangeStore, SurfaceAskThenReport, } from '@jini-ai/core';
 import type { SchedulerPort } from './scheduler.js';
 export type { SchedulerPort } from './scheduler.js';
-export declare const SURFACE_EXCHANGE_ID_PARAM = "__exchangeId";
-export declare const SURFACE_DISMISSED_PARAM = "__dismissed";
-export declare const SURFACE_TYPED_ANSWER_PARAM = "__typedAnswer";
+/**
+ * How long an exchange may sit with nothing happening before it gives up.
+ *
+ * Per *turn*, not per exchange: it resets whenever a message is sent or received, so a long
+ * multi-turn conversation is not punished for taking several turns — only for a human who walked
+ * away. Long enough to read a dialog and decide, short enough that an abandoned tab does not hold a
+ * live agent subprocess open.
+ */
 export declare const DEFAULT_SURFACE_IDLE_TTL_MS: number;
+/**
+ * Hard ceiling on one exchange's total life, regardless of activity.
+ *
+ * Exists because the idle deadline alone is unbounded in aggregate — a human answering every four
+ * minutes could hold a call open indefinitely, and the call is not ours to hold: it is an HTTP
+ * request from the spawned agent's MCP server, which gives up after 6 minutes (`@jini-ai/mcp`'s
+ * delegated-tool deadline). Sized just inside that, so a stalled exchange returns an explicit result
+ * the model can read rather than having the transport time out underneath it.
+ *
+ * **This, not the idle deadline, is what caps a multi-turn conversation today.** Raising it means
+ * raising the transport deadline first; the two must move together or the ordering inverts.
+ */
 export declare const DEFAULT_SURFACE_MAX_LIFETIME_MS: number;
-export type SurfaceAnswerChannel = string;
-export interface SurfaceExchangeBinding {
-    readonly toolId: string;
-    readonly principalId: string;
-    readonly channel?: SurfaceAnswerChannel;
-}
-export type SurfaceMessage = {
-    status: 'received';
-    params: Record<string, unknown>;
-} | {
-    status: 'expired';
-} | {
-    status: 'abandoned';
-};
-export type SurfaceDeliveryRejectionReason = 'unknown-or-closed' | 'binding-mismatch';
-export type DeliverResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: SurfaceDeliveryRejectionReason;
-};
-export interface SurfaceExchange {
-    readonly id: string;
-    send(args: {
-        emission: SurfaceEmission;
-    }): Promise<void>;
-    receive(_args: Record<string, never>): Promise<SurfaceMessage>;
-    close(_args: Record<string, never>): void;
-}
-export interface SurfaceDeliverySpec {
-    exchangeId: string;
-    params: Record<string, unknown>;
-    principalId: string;
-    toolId?: string;
-    channel?: SurfaceAnswerChannel;
-}
-export interface SurfaceExchangeStore {
-    open(args: {
-        binding: SurfaceExchangeBinding;
-        emit: SurfaceEmitter;
-    }): SurfaceExchange;
-    deliver(requiredArgs: Pick<SurfaceDeliverySpec, "exchangeId" | "params" | "principalId">, optionalArgs?: Pick<SurfaceDeliverySpec, "toolId" | "channel">): DeliverResult;
-    findTypedAnswerTarget(args: {
-        principalId: string;
-        toolId: string;
-    }): string | undefined;
-    size(): number;
-}
-/** In-process held calls. Inject a scheduler that unrefs its timers where appropriate. */
+/**
+ * Creates an in-process store of open surface exchanges.
+ *
+ * In-process necessarily, not merely by choice: an open exchange is a suspended function call in
+ * this process's memory. It could not be shared across processes even if that were desirable.
+ * `mcp-ui-tool-calls-route.ts` is mounted on the same daemon the handlers run in, which is what makes
+ * delivery a direct call rather than another network hop.
+ *
+ * @param options.idleTtlMs - Per-turn inactivity deadline. See {@link DEFAULT_SURFACE_IDLE_TTL_MS}.
+ * @param options.maxLifetimeMs - Total lifetime ceiling. See {@link DEFAULT_SURFACE_MAX_LIFETIME_MS}.
+ * @param deps.idGenerator - Id source, injected so a test can assert a known value.
+ * @param deps.clock - Wall clock for {@link SurfaceExchange.expiresAtMs}. The injected scheduler owns
+ * the timers; the clock dates and checks their deadlines.
+ * @complexity O(1) per send/receive/deliver. Each exchange owns two `unref`'d timers.
+ */
 export declare function createSurfaceExchangeStore(deps: {
     scheduler: SchedulerPort;
     clock: Clock;
@@ -65,33 +103,141 @@ export declare function createSurfaceExchangeStore(deps: {
     idleTtlMs?: number;
     maxLifetimeMs?: number;
 }): SurfaceExchangeStore;
+/**
+ * The one-shot case: send once, wait once, close.
+ *
+ * Kept as a helper rather than a second mechanism, because "ask a question and get one answer" is
+ * genuinely just the shortest exchange. Anything that later needs a follow-up turn stops calling this
+ * and drives the exchange directly, with no change to the store, the route, or the transport.
+ */
 export declare function askOnce({ exchange, emission }: {
-    exchange: SurfaceExchange;
+    exchange: SurfaceExchangeConversation;
     emission: SurfaceEmission;
-}): Promise<SurfaceMessage>;
+}, _optional?: Record<string, never>): Promise<SurfaceMessage>;
+/**
+ * Like {@link askOnce}, but for a call whose answer triggers real work whose OUTCOME the human also
+ * needs to see — a publish, a delete, a credential save. `askOnce` alone cannot express this: it
+ * closes the exchange the instant an answer arrives, so a caller that awaited it and then tried to
+ * `exchange.send()` a result would find the exchange already dead (`send()` throws "already ended").
+ *
+ * ## The defect this exists to fix
+ *
+ * A confirmation surface's own script (`confirmation.ts`) sets its status text to "Done." the moment
+ * the confirming `tools/call` RESOLVES — and for a held-open exchange delivered through
+ * `mcp-ui-tool-calls-route.ts`'s Shape 1, that call resolves the instant the click is DELIVERED to
+ * the parked agent call (`{delivered: true}`, HTTP 202), which happens before the parked handler has
+ * done anything with the answer yet, let alone finished. "Done." therefore means "your click
+ * reached the server," never "the thing you asked for actually happened" — a 404, a rejected
+ * credential, and a genuine success all render the identical "Done." to the human. `handle` below is
+ * where a caller does the real work and decides what actually happened; the outcome emission this
+ * function sends afterward is what corrects the record.
+ *
+ * ## How the correction reaches the screen
+ *
+ * The outcome emission is expected to reuse the SAME `ui://` URI the confirmation was sent under.
+ * `McpUiSurfaceCard` (`@jini-ai/chat`) already collapses a stream to the newest resource per URI —
+ * "a stream may re-send an updated document for a surface already on screen (a confirmation that
+ * became a result), so the LAST event for each URI wins" (that component's own doc) — and
+ * `McpUiHost` keys its iframe by `` `${uri}:${documentText}` ``, so a new document forces a clean
+ * remount rather than leaving the confirmation's stale Confirm/Cancel buttons on screen. Neither of
+ * those needed a change for this to work; this function only needed to make the SECOND send possible.
+ *
+ * ## Why `handle` returns the outcome rather than the caller sending it separately
+ *
+ * Keeping the send here, not in the caller, is what makes the try/catch below unconditional: a
+ * caller could forget to wrap its own `exchange.send()`, but every caller of this function gets the
+ * protection for free. `outcome` is OPTIONAL in the return — a cancelled/expired/abandoned answer has
+ * nothing to correct (the confirmation's own script already reports "Dismissed." for a local cancel,
+ * and an exchange that ended via a timeout is already closed, so `send()` would throw anyway); a
+ * caller for that branch simply omits it.
+ *
+ * ## The one invariant this function protects
+ *
+ * `result` — what reaches the model — must NEVER depend on the outcome emission actually reaching a
+ * screen. A human who closed the tab, a `send()` racing a teardown, or any other failure in the
+ * human-visible half must be invisible to the tool's own JSON contract, which is why the outcome send
+ * is wrapped in its own `try`/`catch` rather than sharing `handle`'s.
+ *
+ * @param exchange - Opened the same way `askOnce` expects one.
+ * @param confirmationEmission - Sent once, exactly like `askOnce`'s own `emission` parameter.
+ * @param handle - Runs after the answer arrives (whatever it is — received, expired, abandoned).
+ *   Does the caller's real work and returns `result` (returned to THIS function's own caller,
+ *   ultimately the model) plus an optional `outcome` emission to report back to the human.
+ * @complexity O(1) plus whatever `handle` itself costs — this function adds one conditional send and
+ *   the same `close()` `askOnce` already pays.
+ */
 export declare function askThenReport<T>({ exchange, confirmationEmission, handle }: {
-    exchange: SurfaceExchange;
+    exchange: SurfaceExchangeConversation;
     confirmationEmission: SurfaceEmission;
     handle: (answer: SurfaceMessage) => Promise<{
         result: T;
         outcome?: SurfaceEmission;
     }>;
-}): Promise<T>;
+}, _optional?: Record<string, never>): Promise<T>;
+/**
+ * Whether the human confirmed, declined, or never answered at all — the fail-closed classification
+ * every confirm/cancel-shaped tool call needs (a delete, a commit, a publish, ...). Extracted after
+ * this exact logic had been copy-pasted at least 4 times (`features/post/tool-registrations.ts`'s
+ * `resolveDeleteDecision`, then `features/custom-credentials`, `features/source-control`, and
+ * `features/deployments/publish-agent-tools.ts`, each self-described as mirroring the first), with
+ * the SAME "fail closed, never read a missing/malformed decision as consent" fix required at every
+ * site (see `classifyConfirmationAnswer`'s own doc).
+ *
+ * `"declined"` covers an explicit non-`"confirm"` decision — a real Cancel click, and equally a
+ * missing, non-string, or unrecognised `decision` field, all fail-closed to the same outcome.
+ * `"expired"`/`"abandoned"` mirror {@link SurfaceMessage}'s own non-`"received"` statuses one-for-one
+ * (ADR-055 Decision 6: no-answer is a result, not a thrown error).
+ */
 export type ConfirmationOutcome = {
     confirmed: true;
 } | {
     confirmed: false;
     reason: 'declined' | 'expired' | 'abandoned';
 };
-/** Typed prose is never consent; only an explicit literal decision grants approval. */
+/**
+ * Classifies an already-received {@link SurfaceMessage} as confirmed or not.
+ *
+ * Pure and synchronous on purpose: a caller that already holds an `answer` from somewhere other than
+ * a fresh {@link askOnce} call — `askThenReport`'s own `handle` callback, for instance, which receives
+ * the message directly because a second `exchange.send()` still needs to happen afterward — can
+ * classify it without a second round trip. {@link resolveConfirmationDecision} below is the `askOnce`
+ * convenience built on top of this for callers that do not need that.
+ *
+ * Fail-closed is the entire contract: only a `params.decision` field that is literally the string
+ * `"confirm"` proceeds. A missing field, a non-string value, or any other string must never be read
+ * as consent for a destructive or externally-visible action.
+ *
+ * @complexity O(1).
+ */
 export declare function classifyConfirmationAnswer({ answer }: {
     answer: SurfaceMessage;
-}): ConfirmationOutcome;
+}, _optional?: Record<string, never>): ConfirmationOutcome;
+/**
+ * {@link askOnce} plus {@link classifyConfirmationAnswer} — the whole "ask, then fail-closed classify"
+ * sequence every confirm/cancel-shaped delete/commit/publish tool repeats. A caller still owns its own
+ * domain-specific result shape for each branch (see e.g. `features/post/tool-registrations.ts`'s own
+ * `resolveDeleteDecision`) — this only shares the parked-ask-and-classify mechanics, not the result,
+ * so each site's `deleted`/`committed`/`published`/... wording stays exactly what it was.
+ *
+ * @complexity O(1) plus whatever {@link askOnce} costs.
+ */
 export declare function resolveConfirmationDecision(args: {
-    exchange: SurfaceExchange;
+    exchange: SurfaceExchangeConversation;
     emission: SurfaceEmission;
-}): Promise<ConfirmationOutcome>;
+}, _optional?: Record<string, never>): Promise<ConfirmationOutcome>;
+/**
+ * Cross-domain machinery a surface-raising tool needs that is not a domain dependency at all.
+ *
+ * Kept separate from `tool-registrations.ts`'s `AssistantToolRegistryDeps` on purpose: that bag is
+ * "the same dependencies the admin HTTP routes are built from", which is what makes a tool call and
+ * the equivalent human click reach identical domain code. An exchange store is not part of that
+ * equivalence — it belongs to the assistant's transport, and only tools that talk to a human mid-call
+ * ever touch it. Declared in this module rather than alongside the registration wiring so a tool can
+ * name it without importing the file that imports the tool.
+ */
 export interface AssistantSurfaceDeps {
+    /** The handlers and callback route must share this same in-process store. Opening in one store
+     * and delivering to another leaves the human's answer unreachable until the deadline expires. */
     readonly surfaceExchanges: SurfaceExchangeStore;
 }
 //# sourceMappingURL=surface-exchanges.d.ts.map