@jini-ai/daemon 0.6.17 → 0.6.22

package/dist/index.js

@@ -79,6 +79,7 @@
  */
 export * from './event-log.js';
 export * from './close-status.js';
+export * from './idle-monitor.js';
 export * from './run-lifecycle.js';
 export * from './ai-trace-lifecycle.js';
 export * from './tool-executor.js';

package/dist/legacy-data-migration.js

@@ -16,6 +16,7 @@
  * connection opens, so it can't race a concurrent open of the destination.
  */
 import * as nodeFilesystem from 'node:fs';
+import { redactSecrets } from '@jini-ai/core';
 import * as path from 'node:path';
 const DEFAULT_MARKER_FILE = '.migrated-from';
 /**
@@ -254,7 +255,8 @@ function stagePromoteAndMark({ plan, markerFile, payloadEntries, writeMarker },
 export function migrateLegacyDataDirSync(requiredArgs, optionalArgs = {}) {
     const options = { ...requiredArgs, ...optionalArgs };
     const fs = options.filesystem ?? nodeFilesystem;
-    const log = options.logger ?? { info: ({ message }) => console.log(`[jini-migrate] ${message}`) };
+    // Paths and payload names are host input, so the default sink redacts the complete diagnostic.
+    const log = options.logger ?? { info: ({ message }) => console.log(redactSecrets({ input: `[jini-migrate] ${message}` }, { redactPii: false })) };
     const markerFile = options.markerFile ?? DEFAULT_MARKER_FILE;
     const plan = planMigration({ legacyDir: options.legacyDir, dataDir: options.dataDir, markerFile }, fs);
     if ('status' in plan)

package/dist/remote-attachment-lookup.d.ts

@@ -18,6 +18,8 @@ export interface RemoteAttachmentLookupRequired {
     readonly token: string;
 }
 export interface RemoteAttachmentLookupOptional {
+    /** Explicit authenticated mount prefix. Omitted preserves the historical origin-root route. */
+    readonly pathPrefix?: string;
     /** Injectable `node:http.request`. */
     readonly request?: typeof http.request;
 }
@@ -25,5 +27,5 @@ export interface RemoteAttachmentLookupOptional {
  * Creates the remote lookup.
  * @complexity One loopback round trip per call; O(response bytes).
  */
-export declare function createRemoteAttachmentLookup({ baseUrl, token }: RemoteAttachmentLookupRequired, { request }?: RemoteAttachmentLookupOptional): AttachmentLookup;
+export declare function createRemoteAttachmentLookup({ baseUrl, token }: RemoteAttachmentLookupRequired, { request, pathPrefix }?: RemoteAttachmentLookupOptional): AttachmentLookup;
 //# sourceMappingURL=remote-attachment-lookup.d.ts.map

package/dist/remote-attachment-lookup.js

@@ -56,8 +56,8 @@ function unwrap({ status, body }) {
  * Creates the remote lookup.
  * @complexity One loopback round trip per call; O(response bytes).
  */
-export function createRemoteAttachmentLookup({ baseUrl, token }, { request = http.request } = {}) {
-    const url = new URL(ATTACHMENT_LOOKUP_ROUTE_PATH, baseUrl);
+export function createRemoteAttachmentLookup({ baseUrl, token }, { request = http.request, pathPrefix = '' } = {}) {
+    const url = new URL(`${pathPrefix.replace(/\/$/, '')}${ATTACHMENT_LOOKUP_ROUTE_PATH}`, baseUrl);
     const call = async (payload) => unwrap(await postJson({ url, token, payload }, { request }));
     return {
         resolveForRun: async ({ ref, runId }) => ((await call({ op: 'resolveForRun', ref, runId })) ?? undefined),

package/dist/routines/scheduler.js

@@ -20,6 +20,8 @@
  * faithful port, not a redesign, per the proposal's own warning against "casually reinventing"
  * the race-safe scheduled-slot claim below.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { nextRunAtForSchedule } from './schedule.js';
 function clearRoutinePlaceholderId(value) {
@@ -43,10 +45,10 @@ export class ScheduledRunPersistenceError extends Error {
         this.name = 'ScheduledRunPersistenceError';
     }
 }
-/** What a failed scheduled run logs: the underlying error's message when there is one. */
+/** Preserve the underlying failure (including its code) for the redacted log diagnostic. */
 function scheduledRunFailureDetail(error) {
     const cause = error instanceof ScheduledRunPersistenceError ? error.originalError : error;
-    return cause instanceof Error ? cause.message : cause;
+    return cause;
 }
 function isScheduledRunPersistenceError(error) {
     return error instanceof ScheduledRunPersistenceError;
@@ -141,7 +143,7 @@ export class RoutineService {
                 this.rescheduleOne({ routineId: routine.id });
             })
                 .catch((error) => {
-                console.error(`[@jini-ai/daemon] routine ${routine.id} scheduled run failed:`, scheduledRunFailureDetail(error));
+                console.error(`[@jini-ai/daemon] routine ${routine.id} scheduled run failed:`, redactSecrets({ input: inspect(scheduledRunFailureDetail(error)) }, { redactPii: false }));
                 if (isScheduledRunPersistenceError(error)) {
                     this.retryScheduledSlot(routine.id, fireAt);
                 }
@@ -249,7 +251,7 @@ export class RoutineService {
             discardError = err;
         }
         if (discardError != null) {
-            console.error(`[@jini-ai/daemon] routine ${attempt.routine.id} prepare cleanup failed:`, errorMessage(discardError));
+            console.error(`[@jini-ai/daemon] routine ${attempt.routine.id} prepare cleanup failed:`, redactSecrets({ input: inspect(discardError) }, { redactPii: false }));
         }
         run.projectId = clearRoutinePlaceholderId(run.projectId);
         run.conversationId = clearRoutinePlaceholderId(run.conversationId);

package/dist/routing-tool-executor.d.ts

@@ -23,7 +23,12 @@ export interface RoutingToolExecutorRequired {
 }
 /**
  * Creates the routing executor.
+ * @param required Local/remote executors and the owning registry's routing predicate.
+ * @param optional.acquireActivity Host busy lease, released on success or failure after real work.
+ * @returns One executor preserving the selected route's result/error and cancellation policy.
  * @complexity O(1) plus `isLocal`'s own cost per call.
  */
-export declare function createRoutingToolExecutor({ local, remote, isLocal }: RoutingToolExecutorRequired, _optional?: Record<string, never>): ToolExecutor;
+export declare function createRoutingToolExecutor({ local, remote, isLocal }: RoutingToolExecutorRequired, { acquireActivity }?: {
+    readonly acquireActivity?: () => () => void;
+}): ToolExecutor;
 //# sourceMappingURL=routing-tool-executor.d.ts.map

package/dist/routing-tool-executor.js

@@ -1,10 +1,23 @@
 /**
  * Creates the routing executor.
+ * @param required Local/remote executors and the owning registry's routing predicate.
+ * @param optional.acquireActivity Host busy lease, released on success or failure after real work.
+ * @returns One executor preserving the selected route's result/error and cancellation policy.
  * @complexity O(1) plus `isLocal`'s own cost per call.
  */
-export function createRoutingToolExecutor({ local, remote, isLocal }, _optional = {}) {
+export function createRoutingToolExecutor({ local, remote, isLocal }, { acquireActivity } = {}) {
     return {
-        execute: (args, optional) => (isLocal({ toolId: args.toolId }) ? local : remote).execute(args, optional),
+        async execute(args, optional) {
+            // HTTP disconnects/cancel requests may precede actual completion. The embedding's busy
+            // lease follows the real executor promise, including its approval wait and cleanup.
+            const release = acquireActivity?.();
+            try {
+                return await (isLocal({ toolId: args.toolId }) ? local : remote).execute(args, optional);
+            }
+            finally {
+                release?.();
+            }
+        },
         resumeConfirmation: (args) => local.resumeConfirmation(args),
         cancel: (args) => {
             local.cancel(args);

package/dist/run-lifecycle.d.ts

@@ -1,19 +1,3 @@
-/**
- * `RunLifecycle` — start/stream/cancel/resume a run keyed on an opaque
- * `contextRef` (extraction-plan §2.1: runs key on an opaque `contextRef`,
- * never a product-record identifier), generalized from OD's `design.runs` service
- * (`apps/daemon/src/runtimes/runs.ts` + the terminal-decision half of
- * `apps/daemon/src/runtimes/start-chat-run.ts`, `arch/server-startserver-endgame`
- * branch — see `archived provenance ledger` for exact line citations).
- *
- * Scope boundary: this module owns the run *state machine* and its event
- * log — create, transition, emit, replay, cancellation-intent propagation,
- * idempotent start/finish, resume. It does not spawn or signal a subprocess;
- * that is `@jini-ai/agent-runtime`'s job (extraction-plan task 7). A driver
- * (today: this package's tests; later: agent-runtime) calls `emit()` for
- * agent/stdout/stderr/error events, observes cancellation via
- * `onCancelRequested`, and calls `finish()` once it knows the real outcome.
- */
 import type { DelegatedResultCorrelation } from './delegated-result-correlation.js';
 import type { RunAgentPayload, RunCancelRequest, RunChunkPayload, RunErrorPayload, RunProtocolEvent, RunStartPayload, RunStatus } from '@jini-ai/protocol';
 import type { EventLog, EventLogEntry, EventLogReplayResult } from './event-log.js';

package/dist/run-lifecycle.js

@@ -1,3 +1,21 @@
+/**
+ * `RunLifecycle` — start/stream/cancel/resume a run keyed on an opaque
+ * `contextRef` (extraction-plan §2.1: runs key on an opaque `contextRef`,
+ * never a product-record identifier), generalized from OD's `design.runs` service
+ * (`apps/daemon/src/runtimes/runs.ts` + the terminal-decision half of
+ * `apps/daemon/src/runtimes/start-chat-run.ts`, `arch/server-startserver-endgame`
+ * branch — see `archived provenance ledger` for exact line citations).
+ *
+ * Scope boundary: this module owns the run *state machine* and its event
+ * log — create, transition, emit, replay, cancellation-intent propagation,
+ * idempotent start/finish, resume. It does not spawn or signal a subprocess;
+ * that is `@jini-ai/agent-runtime`'s job (extraction-plan task 7). A driver
+ * (today: this package's tests; later: agent-runtime) calls `emit()` for
+ * agent/stdout/stderr/error events, observes cancellation via
+ * `onCancelRequested`, and calls `finish()` once it knows the real outcome.
+ */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { RUN_PROTOCOL_VERSION, isTerminalRunState } from '@jini-ai/protocol';
 import { createInactivityWatchdog } from './close-status.js';
@@ -455,11 +473,11 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                 input.onInternalError(context);
             // eslint-disable-next-line no-console
             else
-                console.error(`[@jini-ai/daemon] internal error (${context.source}, runId=${context.runId})`, context.error);
+                console.error(`[@jini-ai/daemon] internal error (${context.source}, runId=${context.runId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
         }
         catch (sinkError) {
             // eslint-disable-next-line no-console
-            console.error(`[@jini-ai/daemon] internal error sink failed (${context.source}, runId=${context.runId})`, sinkError);
+            console.error(`[@jini-ai/daemon] internal error sink failed (${context.source}, runId=${context.runId})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
         }
     }
     /** Trims the oldest terminal records until `terminalRunOrder` is back at or under `maxTerminalRuns`. */
@@ -531,14 +549,14 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                 }
                 else {
                     // eslint-disable-next-line no-console
-                    console.error(`[@jini-ai/daemon] internal error (inactivity-timeout, runId=${runId})`, error);
+                    console.error(`[@jini-ai/daemon] internal error (inactivity-timeout, runId=${runId})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
                 }
             }
             catch (sinkError) {
                 // A diagnostic sink must not turn a contained timer failure into another unhandled
                 // rejection.
                 // eslint-disable-next-line no-console
-                console.error(`[@jini-ai/daemon] internal error sink failed (inactivity-timeout, runId=${runId})`, sinkError);
+                console.error(`[@jini-ai/daemon] internal error sink failed (inactivity-timeout, runId=${runId})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
             }
         }
     }
@@ -579,13 +597,13 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                 }
                 else {
                     // eslint-disable-next-line no-console
-                    console.error(`[@jini-ai/daemon] internal error (slow-run-notice, runId=${runId})`, error);
+                    console.error(`[@jini-ai/daemon] internal error (slow-run-notice, runId=${runId})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
                 }
             }
             catch (sinkError) {
                 // Same containment reasoning as `handleInactivityTimeout`'s own catch below it.
                 // eslint-disable-next-line no-console
-                console.error(`[@jini-ai/daemon] internal error sink failed (slow-run-notice, runId=${runId})`, sinkError);
+                console.error(`[@jini-ai/daemon] internal error sink failed (slow-run-notice, runId=${runId})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
             }
         }
     }

package/dist/surface-exchanges.d.ts

@@ -68,6 +68,8 @@ export type { SchedulerPort } from './scheduler.js';
 export declare const DEFAULT_SURFACE_IDLE_TTL_MS: number;
 /**
  * Hard ceiling on one exchange's total life, regardless of activity.
+ * Applies only without an executor lifetime. The historical paired-transport rationale below
+ * describes unleased callers; run-bound cards ignore both deadlines and end with their call.
  *
  * 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
@@ -92,7 +94,9 @@ export declare const DEFAULT_SURFACE_MAX_LIFETIME_MS: number;
  * @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.
+ * @complexity O(1) per receive, O(n) per accepted answer in active/retained exchanges, and O(t)
+ * per send to t observing tabs. Closed recovery entries are capped at 128. Unleased exchanges own
+ * two timers; run-bound exchanges own one cancellation subscription and no deadline timers.
  */
 export declare function createSurfaceExchangeStore(deps: {
     scheduler: SchedulerPort;

package/dist/surface-exchanges.js

@@ -1,4 +1,5 @@
 export { SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWER_PARAM, } from '@jini-ai/core';
+import { createSurfaceRestoration } from './surface-restoration.js';
 /**
  * How long an exchange may sit with nothing happening before it gives up.
  *
@@ -10,6 +11,8 @@ export { SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWE
 export const DEFAULT_SURFACE_IDLE_TTL_MS = 5 * 60 * 1000;
 /**
  * Hard ceiling on one exchange's total life, regardless of activity.
+ * Applies only without an executor lifetime. The historical paired-transport rationale below
+ * describes unleased callers; run-bound cards ignore both deadlines and end with their call.
  *
  * 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
@@ -29,6 +32,12 @@ class SurfaceExchangeEndedError extends Error {
     }
     terminal;
 }
+/** Run-bound cards use cancellation instead of a date; other callers retain both timed budgets. */
+function initialSurfaceDeadlines({ leased, nowMs, idleTtlMs, maxLifetimeMs }) {
+    if (leased)
+        return { idle: Number.POSITIVE_INFINITY, lifetime: Number.POSITIVE_INFINITY };
+    return { idle: nowMs + idleTtlMs, lifetime: nowMs + maxLifetimeMs };
+}
 /**
  * Creates an in-process store of open surface exchanges.
  *
@@ -42,13 +51,18 @@ class SurfaceExchangeEndedError extends Error {
  * @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.
+ * @complexity O(1) per receive, O(n) per accepted answer in active/retained exchanges, and O(t)
+ * per send to t observing tabs. Closed recovery entries are capped at 128. Unleased exchanges own
+ * two timers; run-bound exchanges own one cancellation subscription and no deadline timers.
  */
 export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_IDLE_TTL_MS, maxLifetimeMs = DEFAULT_SURFACE_MAX_LIFETIME_MS } = {}) {
     if (!Number.isFinite(idleTtlMs) || idleTtlMs <= 0 || !Number.isFinite(maxLifetimeMs) || maxLifetimeMs <= 0)
         throw new Error('surface deadlines must be finite and positive');
     const openExchanges = new Map();
-    return {
+    const restoration = createSurfaceRestoration({ clock: deps.clock, defaultChannel: deps.defaultChannel,
+        deliver: (required, optional) => store.deliver(required, optional) });
+    const store = {
+        restore: restoration.restore,
         open({ binding, emit }, _optional = {}) {
             // Waiting without a live emitter is a deadlock; reject before allocating any timers or ID.
             if (typeof emit !== 'function')
@@ -56,13 +70,20 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
             const id = deps.idGenerator.newId();
             if (!id || openExchanges.has(id))
                 throw new Error('surface exchange ID must be unique and nonempty');
+            const lifetime = emit.exchangeLifetime;
+            // Only the executor can supply this lease. Plain emitters (including bounded visitor
+            // confirmations) retain their existing deadlines. No card/tool needs its own TTL override.
+            const leased = lifetime !== undefined && lifetime.principalId === binding.principalId;
+            const recovery = leased ? restoration.track({ id, binding, lifetime }) : undefined;
             const inbox = [];
             const waiters = [];
             let terminal;
             let cancelIdle;
             let cancelLifetime;
-            const lifetimeDeadline = deps.clock.nowMs() + maxLifetimeMs;
-            let idleDeadline = deps.clock.nowMs() + idleTtlMs;
+            const deadlines = initialSurfaceDeadlines({ leased, nowMs: deps.clock.nowMs(), idleTtlMs, maxLifetimeMs });
+            const lifetimeDeadline = deadlines.lifetime;
+            let idleDeadline = deadlines.idle;
+            const closeOnAbort = () => end({ status: 'abandoned' });
             function end(reason) {
                 if (terminal)
                     return;
@@ -70,6 +91,8 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                 cancelIdle?.();
                 cancelLifetime?.();
                 openExchanges.delete(id);
+                lifetime?.signal.removeEventListener('abort', closeOnAbort);
+                recovery?.end();
                 while (waiters.length > 0)
                     waiters.shift()(reason);
             }
@@ -79,7 +102,7 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     end({ status: 'expired' });
             }
             function armIdle() {
-                if (terminal)
+                if (terminal || leased)
                     return;
                 cancelIdle?.();
                 idleDeadline = deps.clock.nowMs() + idleTtlMs;
@@ -87,7 +110,8 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
             }
             // Register only after both timers are installed, so scheduler failure leaves no discoverable exchange.
             try {
-                cancelLifetime = deps.scheduler.schedule({ delayMs: maxLifetimeMs, callback: () => end({ status: 'expired' }) });
+                if (!leased)
+                    cancelLifetime = deps.scheduler.schedule({ delayMs: maxLifetimeMs, callback: () => end({ status: 'expired' }) });
                 armIdle();
             }
             catch (error) {
@@ -102,6 +126,7 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     expireIfDue();
                     if (terminal)
                         return;
+                    recovery?.answered();
                     armIdle();
                     const waiter = waiters.shift();
                     if (waiter)
@@ -112,6 +137,11 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                         inbox.push(params);
                 },
             });
+            if (leased) {
+                lifetime.signal.addEventListener('abort', closeOnAbort, { once: true });
+                if (lifetime.signal.aborted)
+                    closeOnAbort();
+            }
             return {
                 id,
                 async send({ emission }, _optional = {}) {
@@ -119,7 +149,10 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     if (terminal)
                         throw new SurfaceExchangeEndedError({ id, terminal });
                     armIdle();
-                    await emit(emission);
+                    const sent = recovery === undefined ? emission : { ...emission, payload: { ...emission.payload,
+                            surfaceExchange: { exchangeId: id, toolId: binding.toolId, runId: lifetime.runId } } };
+                    await recovery?.send({ emission: sent });
+                    await emit(sent);
                 },
                 async receive(_args, _optional = {}) {
                     expireIfDue();
@@ -166,6 +199,7 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
         },
         size: () => openExchanges.size,
     };
+    return store;
 }
 /**
  * The one-shot case: send once, wait once, close.

package/dist/surface-restoration.d.ts

@@ -0,0 +1,38 @@
+import type { Clock } from '@jini-ai/core/primitives';
+import type { DeliverResult, SurfaceEmitter, SurfaceEmission, SurfaceExchangeBinding, SurfaceExchangeStore } from '@jini-ai/core';
+type Lifetime = NonNullable<SurfaceEmitter['exchangeLifetime']>;
+type Delivery = SurfaceExchangeStore['deliver'];
+/** Shared recovery owner for every exchange channel. The store supplies delivery; the executor
+ * supplies retry, so recovery cannot bypass authorization or invent a second handler.
+ * @complexity O(n) per open/restore/accepted answer in active entries plus at most 128 retained
+ * entries; O(t) per emission to t observing tabs.
+ */
+export declare function createSurfaceRestoration({ clock, defaultChannel, deliver }: {
+    clock: Clock;
+    defaultChannel: string;
+    deliver: Delivery;
+}, _options?: Record<string, never>): {
+    track: ({ id, binding, lifetime }: {
+        id: string;
+        binding: SurfaceExchangeBinding;
+        lifetime: Lifetime;
+    }) => {
+        send: ({ emission }: {
+            emission: SurfaceEmission;
+        }) => Promise<void>;
+        answered: () => void;
+        end: () => void;
+    };
+    restore: (required: {
+        exchangeId: string;
+        principalId: string;
+        emit: SurfaceEmitter;
+    }, optional?: {
+        toolId?: string;
+        channel?: import("@jini-ai/core").SurfaceAnswerChannel;
+        params?: Record<string, unknown>;
+        signal?: AbortSignal;
+    }) => Promise<DeliverResult>;
+};
+export {};
+//# sourceMappingURL=surface-restoration.d.ts.map

package/dist/surface-restoration.js

@@ -0,0 +1,152 @@
+/** Only unanswered public invocations survive a call. Bounded in count, with no timer
+ * keeping a process alive. Submitted secrets never enter this cache; late answers stay on the
+ * submitting request's stack until they can be delivered to the newly authorized call. */
+const MAX_RETAINED = 128;
+const unavailable = () => ({ ok: false, reason: 'unknown-or-closed' });
+/** Fan out display-only updates. Losing a tab must never replace the tool's authoritative result.
+ * @complexity O(t) in tabs observing this card. */
+async function broadcast({ entry, emission }) {
+    await Promise.allSettled([...entry.observers].map(observer => observer(emission)));
+}
+/** Strict binding survives expiry and every retry; restoration cannot weaken ordinary delivery. */
+function matches({ entry, principalId, toolId, channel, defaultChannel }) {
+    if (entry.binding.principalId !== principalId)
+        return false;
+    if (toolId !== undefined && entry.binding.toolId !== toolId)
+        return false;
+    return (entry.binding.channel ?? defaultChannel) === (channel ?? defaultChannel);
+}
+/** Subscribe until this request leaves or the shared work finishes. A departing tab cancels a
+ * replacement only when no other tab still observes it. It never cancels the original agent call.
+ * @complexity O(1) subscription state per request. */
+async function join({ entry, emit, work, signal }, { initial } = {}) {
+    let leave;
+    const aborted = new Promise(resolve => { leave = () => resolve(unavailable()); });
+    const observer = emission => emit(emission);
+    entry.observers.add(observer);
+    signal?.addEventListener('abort', leave, { once: true });
+    if (signal?.aborted)
+        leave();
+    try {
+        if (initial)
+            await emit(initial);
+        return await Promise.race([work, aborted]);
+    }
+    finally {
+        entry.observers.delete(observer);
+        signal?.removeEventListener('abort', leave);
+        if (entry.observers.size === 0)
+            entry.restartAbort?.abort();
+    }
+}
+/** Restart once, even if several tabs return together. The old scrollback handle survives an
+ * interrupted replacement; a received answer consumes both it and the replacement handle.
+ * @complexity O(t) per emitted frame, plus the original executor's cost.
+ */
+function restart({ entry }) {
+    if (entry.restarting)
+        return entry.restarting;
+    const controller = new AbortController();
+    entry.restartAbort = controller;
+    let identify;
+    entry.replacementReady = new Promise(resolve => { identify = resolve; });
+    delete entry.replacementId;
+    entry.restarting = Promise.resolve().then(async () => {
+        await entry.lifetime.retry({ signal: controller.signal, emit: async (emission) => {
+                entry.emission = emission;
+                const metadata = emission.payload['surfaceExchange'];
+                if (metadata?.exchangeId) {
+                    entry.replacementId = metadata.exchangeId;
+                    identify(metadata.exchangeId);
+                }
+                await broadcast({ entry, emission });
+            } });
+        return entry.replacementId === undefined ? unavailable() : { ok: true };
+    }).finally(() => {
+        identify(undefined); // Authorization/preparation can refuse before opening any replacement.
+        delete entry.restarting;
+        delete entry.restartAbort;
+    });
+    return entry.restarting;
+}
+/** Deliver a late answer only after a new, authorized exchange exists. The answer is not cached,
+ * reused as tool input or broadcast. A second tab cannot repeat an already consumed decision.
+ */
+async function deliverLate({ entry, principalId, params, deliver }, options) {
+    const exchangeId = await entry.replacementReady;
+    if (exchangeId === undefined || entry.answered || options?.signal?.aborted)
+        return;
+    deliver({ exchangeId, principalId, params }, options);
+}
+/** Shared recovery owner for every exchange channel. The store supplies delivery; the executor
+ * supplies retry, so recovery cannot bypass authorization or invent a second handler.
+ * @complexity O(n) per open/restore/accepted answer in active entries plus at most 128 retained
+ * entries; O(t) per emission to t observing tabs.
+ */
+export function createSurfaceRestoration({ clock, defaultChannel, deliver }, _options = {}) {
+    const entries = new Map();
+    function prune() {
+        const retained = [];
+        for (const [id, entry] of entries) {
+            if (entry.endedAt === undefined || entry.restarting)
+                continue;
+            retained.push(id);
+        }
+        for (const id of retained.slice(0, Math.max(0, retained.length - MAX_RETAINED)))
+            entries.delete(id);
+    }
+    function forgetAnswered({ id }) {
+        for (const [key, entry] of entries) {
+            if (key === id || entry.replacementId === id) {
+                entry.answered = true;
+                entries.delete(key);
+            }
+        }
+    }
+    function track({ id, binding, lifetime }) {
+        prune();
+        let finish;
+        const ended = new Promise(resolve => { finish = resolve; });
+        const entry = { binding: { ...binding }, lifetime, answered: false, observers: new Set(), finish, ended };
+        entries.set(id, entry);
+        return {
+            send: async ({ emission }) => {
+                entry.emission = emission;
+                await broadcast({ entry, emission });
+            },
+            answered: () => forgetAnswered({ id }),
+            end: () => {
+                entry.endedAt = clock.nowMs();
+                entry.finish();
+                // A synthetic/nested card cannot safely replay its outer tool. No emitted surface means
+                // nobody saw a card to return to; retaining that call would be speculative work.
+                if (!entry.emission || entry.answered || binding.toolId !== lifetime.toolId)
+                    entries.delete(id);
+                prune();
+            },
+        };
+    }
+    const restore = async ({ exchangeId, principalId, emit }, options = {}) => {
+        prune();
+        const entry = entries.get(exchangeId);
+        if (!entry)
+            return unavailable();
+        if (!matches({ entry, principalId, toolId: options.toolId, channel: options.channel, defaultChannel }))
+            return { ok: false, reason: 'binding-mismatch' };
+        if (options.signal?.aborted)
+            return unavailable();
+        if (entry.endedAt === undefined) {
+            if (options.params)
+                return deliver({ exchangeId, principalId, params: options.params }, options);
+            return join({ entry, emit, work: entry.ended.then(() => ({ ok: true })), signal: options.signal }, entry.emission ? { initial: entry.emission } : {});
+        }
+        const work = restart({ entry });
+        // Subscribe synchronously before the retry's microtask can emit the first card.
+        const observed = join({ entry, emit, work, signal: options.signal }, entry.replacementId && entry.emission ? { initial: entry.emission } : {});
+        if (options.params)
+            await deliverLate({ entry, principalId, params: options.params, deliver }, options);
+        return observed;
+    };
+    return { track, restore };
+}
+//# sourceMappingURL=surface-restoration.js.map

package/dist/tool-recovery/index.d.ts

@@ -5,4 +5,5 @@ export * from "./stack.js";
 export * from "./federated-refusal.js";
 export * from "./observability.js";
 export * from "./analytics.js";
+export * from './surface-lifetime.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tool-recovery/index.js

@@ -5,4 +5,5 @@ export * from "./stack.js";
 export * from "./federated-refusal.js";
 export * from "./observability.js";
 export * from "./analytics.js";
+export * from './surface-lifetime.js';
 //# sourceMappingURL=index.js.map

package/dist/tool-recovery/redaction.d.ts

@@ -77,6 +77,7 @@ export declare function isRedactedToolFailure({ result }: {
  * compiles against a published http-kit that predates `status`.
  */
 export interface DelegatedInternalErrorContext {
+    readonly recoveryMessage?: string;
     readonly source: string;
     readonly runId: string;
     readonly toolId: string;

package/dist/tool-recovery/redaction.js

@@ -97,7 +97,10 @@ function delegatedInternalErrorReason(context) {
  * @complexity O(reason length) for the redaction pass.
  */
 export function describeDelegatedInternalError({ context, ...deps }, _optional = {}) {
-    const { text, redactions } = deps.redactSecretShapes({ text: delegatedInternalErrorReason(context) });
+    let reason = delegatedInternalErrorReason(context);
+    if ((context.status === "timed-out" || context.status === "cancelled") && context.recoveryMessage)
+        reason = context.recoveryMessage;
+    const { text, redactions } = deps.redactSecretShapes({ text: reason });
     const errorId = deps.mintErrorId();
     safeOnFailure(deps.onFailure, {
         errorId,

package/dist/tool-recovery/stack.js

@@ -46,6 +46,7 @@ import { withReadOnlyToolConstraint } from "../core/read-only-tools.js";
 import { withToolAttemptAudit } from "../core/tool-audit.js";
 import { withToolFailureRecovery } from "./recovery.js";
 import { withRedactedToolFailures, readToolErrorId } from "./redaction.js";
+import { withSurfaceExchangeLifetime } from './surface-lifetime.js';
 /** The audit wrapper's options: only an error sink the caller actually supplied. */
 function auditOptions(audit) {
     return audit.onSinkError ? { onSinkError: audit.onSinkError } : {};
@@ -61,6 +62,6 @@ export function createAssistantToolExecutor(deps, _optional = {}) {
     const audited = deps.toolAttemptAudit
         ? withToolAttemptAudit({ inner: redacted, ...deps.toolAttemptAudit, readErrorId: readToolErrorId }, auditOptions(deps.toolAttemptAudit))
         : redacted;
-    return withToolFailureRecovery({ ...deps, inner: audited }, {});
+    return withSurfaceExchangeLifetime({ inner: withToolFailureRecovery({ ...deps, inner: audited }, {}) });
 }
 //# sourceMappingURL=stack.js.map

package/dist/tool-recovery/surface-lifetime.d.ts

@@ -0,0 +1,11 @@
+import type { ToolExecutor } from '../tool-executor.js';
+/** Bind every card type to the executing call, and make restoration re-enter this same stack.
+ * No submitted answer is captured here: input is the original model-supplied invocation only.
+ * @param required.inner The complete authorization, recovery and audit stack.
+ * @returns An executor with the same cancellation and audit ports.
+ * @complexity O(input size) to snapshot public arguments; O(1) lifecycle state per call.
+ */
+export declare function withSurfaceExchangeLifetime({ inner }: {
+    inner: ToolExecutor;
+}, _options?: Record<string, never>): ToolExecutor;
+//# sourceMappingURL=surface-lifetime.d.ts.map