@jini-ai/daemon 0.5.3 → 0.6.0

package/dist/surface-exchanges.js

@@ -1,15 +1,58 @@
-export const SURFACE_EXCHANGE_ID_PARAM = '__exchangeId';
-export const SURFACE_DISMISSED_PARAM = '__dismissed';
-export const SURFACE_TYPED_ANSWER_PARAM = '__typedAnswer';
+export { SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWER_PARAM, } from '@jini-ai/core';
+/**
+ * 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 const DEFAULT_SURFACE_IDLE_TTL_MS = 5 * 60 * 1000;
+/**
+ * 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 const DEFAULT_SURFACE_MAX_LIFETIME_MS = 5.5 * 60 * 1000;
-/** In-process held calls. Inject a scheduler that unrefs its timers where appropriate. */
+/** Distinguishes an ended exchange from an emitter failure without matching error text. */
+class SurfaceExchangeEndedError extends Error {
+    constructor({ id, terminal }) {
+        super(`surface exchange ${id} has already ended`);
+        this.terminal = terminal;
+    }
+    terminal;
+}
+/**
+ * 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 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 {
-        open({ binding, emit }) {
+        open({ binding, emit }, _optional = {}) {
+            // Waiting without a live emitter is a deadlock; reject before allocating any timers or ID.
+            if (typeof emit !== 'function')
+                throw new Error('surface exchange requires an emitter');
             const id = deps.idGenerator.newId();
             if (!id || openExchanges.has(id))
                 throw new Error('surface exchange ID must be unique and nonempty');
@@ -62,20 +105,22 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     const waiter = waiters.shift();
                     if (waiter)
                         waiter({ status: 'received', params });
+                    // The human can answer while the handler composes its next send. Queue rather than
+                    // drop: dropping would deadlock the exchange on an answer already given.
                     else
                         inbox.push(params);
                 },
             });
             return {
                 id,
-                async send({ emission }) {
+                async send({ emission }, _optional = {}) {
                     expireIfDue();
                     if (terminal)
-                        throw new Error(`surface exchange ${id} has already ended`);
+                        throw new SurfaceExchangeEndedError({ id, terminal });
                     armIdle();
                     await emit(emission);
                 },
-                async receive(_args) {
+                async receive(_args, _optional = {}) {
                     expireIfDue();
                     // Preserve the original FIFO contract: already delivered answers precede terminal status.
                     const buffered = inbox.shift();
@@ -87,26 +132,31 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                         return terminal;
                     return new Promise(resolve => waiters.push(resolve));
                 },
-                close(_args) { end({ status: 'abandoned' }); },
+                close(_args, _optional = {}) { end({ status: 'abandoned' }); },
+                expiresAtMs() { return Math.min(idleDeadline, lifetimeDeadline); },
             };
         },
         deliver(requiredArgs, optionalArgs = {}) {
             const spec = { ...requiredArgs, ...optionalArgs };
             const entry = openExchanges.get(spec.exchangeId);
+            // Unknown and closed are the same situation to a human whose dialog is no longer waiting.
             if (!entry)
                 return { ok: false, reason: 'unknown-or-closed' };
             if ((spec.toolId !== undefined && entry.binding.toolId !== spec.toolId)
                 || (entry.binding.channel ?? deps.defaultChannel) !== (spec.channel ?? deps.defaultChannel)
-                || entry.binding.principalId !== spec.principalId)
+                || entry.binding.principalId !== spec.principalId) {
+                // A wrong-binding delivery must not consume a conversation the right human is still having.
                 return { ok: false, reason: 'binding-mismatch' };
+            }
             entry.accept(spec.params);
             return openExchanges.has(spec.exchangeId) ? { ok: true } : { ok: false, reason: 'unknown-or-closed' };
         },
-        findTypedAnswerTarget({ principalId, toolId }) {
+        findTypedAnswerTarget({ principalId, toolId }, _optional = {}) {
             let found;
             for (const [id, entry] of openExchanges) {
                 if (entry.binding.principalId !== principalId || entry.binding.toolId !== toolId)
                     continue;
+                // Two questions for the same human and tool are ambiguous; never guess which prose answers.
                 if (found !== undefined)
                     return undefined;
                 found = id;
@@ -116,19 +166,93 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
         size: () => openExchanges.size,
     };
 }
-export async function askOnce({ exchange, emission }) {
+/**
+ * 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 async function askOnce({ exchange, emission }, _optional = {}) {
     try {
-        await exchange.send({ emission });
-        return await exchange.receive({});
+        return await sendThenReceive({ exchange, emission });
     }
     finally {
         exchange.close({});
     }
 }
-export async function askThenReport({ exchange, confirmationEmission, handle }) {
+/**
+ * Sends a question and waits for its answer without closing the exchange.
+ * Expiry can precede the first send while a caller builds its dialog. Return that terminal result,
+ * never emit or consume a buffered confirmation on an ended exchange; emitter failures still throw.
+ * @complexity O(1) plus the emitter's cost; no additional buffering or timers.
+ */
+async function sendThenReceive({ exchange, emission }, _optional = {}) {
+    try {
+        await exchange.send({ emission });
+    }
+    catch (error) {
+        if (error instanceof SurfaceExchangeEndedError)
+            return error.terminal;
+        throw error;
+    }
+    return exchange.receive({});
+}
+/**
+ * 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 async function askThenReport({ exchange, confirmationEmission, handle }, _optional = {}) {
     try {
-        await exchange.send({ emission: confirmationEmission });
-        const { result, outcome } = await handle(await exchange.receive({}));
+        const { result, outcome } = await handle(await sendThenReceive({ exchange, emission: confirmationEmission }));
         if (outcome !== undefined) {
             try {
                 await exchange.send({ emission: outcome });
@@ -141,13 +265,36 @@ export async function askThenReport({ exchange, confirmationEmission, handle })
         exchange.close({});
     }
 }
-/** Typed prose is never consent; only an explicit literal decision grants approval. */
-export function classifyConfirmationAnswer({ answer }) {
+/**
+ * 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 function classifyConfirmationAnswer({ answer }, _optional = {}) {
     if (answer.status !== 'received')
         return { confirmed: false, reason: answer.status };
     return answer.params['decision'] === 'confirm' ? { confirmed: true } : { confirmed: false, reason: 'declined' };
 }
-export async function resolveConfirmationDecision(args) {
+/**
+ * {@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 async function resolveConfirmationDecision(args, _optional = {}) {
     return classifyConfirmationAnswer({ answer: await askOnce(args) });
 }
 //# sourceMappingURL=surface-exchanges.js.map

package/dist/tool-audit.d.ts

@@ -1,114 +1,2 @@
-import type { Principal, RunRef, SurfaceEmitter } from '@jini-ai/core';
-import type { ConfirmationDecision, ToolExecutionAuditRecord, ToolExecutionPhase, ToolExecutionResult, ToolExecutionStatus, ToolExecutor } from './tool-executor.js';
-/** The daemon vocabulary, plus attempts that never acquired an execution ID. */
-export type ToolAttemptPhase = Extract<ToolExecutionPhase, 'requested' | ToolExecutionStatus> | 'unknown-tool';
-export declare const TOOL_ATTEMPT_PHASES: readonly ["requested", "completed", "denied", "confirmation-denied", "timed-out", "cancelled", "failed", "unknown-tool"];
-export interface ToolAttemptEvent {
-    readonly attemptId: string;
-    readonly executionId: string | null;
-    readonly workspaceId: string;
-    readonly runId: string;
-    readonly toolId: string;
-    readonly principalId: string;
-    readonly phase: ToolAttemptPhase;
-    readonly at: string;
-    /** Value-free metadata; never raw input, query, output or error text. */
-    readonly detail?: string | null;
-}
-export interface ToolAttemptAuditSink {
-    append(requiredArgs: Pick<ToolAttemptEvent, "attemptId" | "executionId" | "workspaceId" | "runId" | "toolId" | "principalId" | "phase" | "at">, optionalArgs?: Pick<ToolAttemptEvent, "detail">): Promise<void>;
-}
-export interface ToolAuditDependencies {
-    readonly sink: ToolAttemptAuditSink;
-    readonly now: () => string;
-    readonly newAttemptId: () => string;
-}
-export interface ToolAuditOptions {
-    readonly onSinkError?: (error: unknown) => void;
-}
-export declare function describeInput({ input }: {
-    readonly input: unknown;
-}): string;
-export interface AuditedToolExecutor {
-    execute(args: {
-        principal: Principal;
-        run: RunRef;
-        toolId: string;
-        input: unknown;
-    }, options?: {
-        signal?: AbortSignal;
-        emitSurface?: SurfaceEmitter;
-    }): Promise<ToolExecutionResult>;
-    resumeConfirmation(args: {
-        executionId: string;
-        decision: ConfirmationDecision;
-    }): void;
-    cancel(args: {
-        executionId: string;
-    }): void;
-    getAuditRecord(args: {
-        executionId: string;
-    }): ToolExecutionAuditRecord | null;
-}
-/** Wraps the existing boundary without creating another executor or another phase vocabulary. */
-export declare function withToolAttemptAudit(deps: ToolAuditDependencies & {
-    readonly inner: ToolExecutor;
-    readonly workspaceId: string;
-    readonly readErrorId: (args: {
-        result: ToolExecutionResult;
-    }) => string | undefined;
-}, options?: ToolAuditOptions): AuditedToolExecutor;
-export declare function searchToolsAuditDetail({ query, limit, hits }: {
-    query: string;
-    limit: number | null;
-    hits: readonly {
-        id: string;
-    }[];
-}): string;
-export declare function describeToolAuditDetail({ id, entry }: {
-    id: string;
-    entry: unknown | null;
-}): string;
-export interface ToolCatalogAuditIdentity {
-    readonly workspaceId: string;
-    readonly runId: string;
-    readonly principalId: string;
-}
-export interface ToolCatalogAttemptEvent extends ToolCatalogAuditIdentity {
-    readonly toolId: string;
-    readonly detail: string;
-}
-export declare function appendToolCatalogAttempt(deps: ToolAuditDependencies & {
-    readonly event: ToolCatalogAttemptEvent;
-}, options?: ToolAuditOptions): void;
-/** Structural source port: no database or catalog-provider dependency. */
-export interface ToolCatalogAuditSource<Hit extends {
-    id: string;
-}, Entry> {
-    search(args: {
-        query: string;
-    }, options?: {
-        limit?: number;
-    }): readonly Hit[];
-    describe(args: {
-        id: string;
-    }): Entry | null;
-}
-export declare function withToolCatalogAudit<Hit extends {
-    id: string;
-}, Entry>(deps: ToolAuditDependencies & {
-    catalog: ToolCatalogAuditSource<Hit, Entry>;
-    identity: ToolCatalogAuditIdentity;
-    searchToolId: string;
-    describeToolId: string;
-}, options?: ToolAuditOptions): {
-    search({ query }: {
-        query: string;
-    }, { limit }?: {
-        limit?: number;
-    }): readonly Hit[];
-    describe({ id }: {
-        id: string;
-    }): Entry | null;
-};
+export * from './core/tool-audit.js';
 //# sourceMappingURL=tool-audit.d.ts.map

package/dist/tool-audit.js

@@ -1,95 +1,3 @@
-export const TOOL_ATTEMPT_PHASES = [
-    'requested', 'completed', 'denied', 'confirmation-denied', 'timed-out', 'cancelled', 'failed', 'unknown-tool',
-];
-function reportSinkError(error, options) {
-    // An observer's reporter is itself an observer: a throwing reporter cannot gate a tool.
-    try {
-        options.onSinkError?.(error);
-    }
-    catch { /* execution remains authoritative */ }
-}
-async function appendSafely(event, deps, options) {
-    try {
-        await deps.sink.append(event);
-    }
-    catch (error) {
-        reportSinkError(error, options);
-    }
-}
-export function describeInput({ input }) {
-    if (input === null || input === undefined)
-        return `input: ${String(input)}`;
-    if (Array.isArray(input))
-        return `input: an array of ${input.length}`;
-    if (typeof input !== 'object')
-        return `input: a ${typeof input}`;
-    try {
-        const parts = Object.entries(input).map(([key, value]) => Array.isArray(value) ? `${key}[${value.length}]` : key).sort();
-        return parts.length === 0 ? 'keys: none' : `keys: ${parts.join(', ')}`;
-    }
-    catch {
-        return 'input: an unreadable object';
-    }
-}
-/** Wraps the existing boundary without creating another executor or another phase vocabulary. */
-export function withToolAttemptAudit(deps, options = {}) {
-    return {
-        async execute({ principal, run, toolId, input }, { signal, emitSurface } = {}) {
-            const base = { attemptId: deps.newAttemptId(), workspaceId: deps.workspaceId, runId: run.id, toolId, principalId: principal.id };
-            await appendSafely({ ...base, executionId: null, phase: 'requested', at: deps.now(), detail: describeInput({ input }) }, deps, options);
-            let result;
-            try {
-                result = await deps.inner.execute({ principal, run, toolId, input }, {
-                    ...(signal === undefined ? {} : { signal }),
-                    ...(emitSurface === undefined ? {} : { emitSurface }),
-                });
-            }
-            catch (error) {
-                const phase = error instanceof Error && /unknown tool/i.test(error.message) ? 'unknown-tool' : 'failed';
-                await appendSafely({ ...base, executionId: null, phase, at: deps.now(), detail: error instanceof Error ? error.name : typeof error }, deps, options);
-                throw error;
-            }
-            let detail = result.truncated ? 'output truncated' : null;
-            // Host error-ID metadata is optional observation, never part of execution success.
-            if (detail === null) {
-                try {
-                    const id = deps.readErrorId({ result });
-                    if (id !== undefined)
-                        detail = `errorId=${id}`;
-                }
-                catch (error) {
-                    reportSinkError(error, options);
-                }
-            }
-            await appendSafely({ ...base, executionId: result.executionId, phase: result.status, at: deps.now(), detail }, deps, options);
-            return result;
-        },
-        resumeConfirmation: ({ executionId, decision }) => deps.inner.resumeConfirmation({ executionId: executionId, decision: decision }),
-        cancel: ({ executionId }) => deps.inner.cancel({ executionId }),
-        getAuditRecord: ({ executionId }) => deps.inner.getAuditRecord({ executionId: executionId }),
-    };
-}
-export function searchToolsAuditDetail({ query, limit, hits }) {
-    return JSON.stringify({ queryLength: query.length, limit, resultIds: hits.map(hit => hit.id), resultCount: hits.length });
-}
-export function describeToolAuditDetail({ id, entry }) {
-    return JSON.stringify({ id, found: entry !== null });
-}
-export function appendToolCatalogAttempt(deps, options = {}) {
-    void appendSafely({ ...deps.event, attemptId: deps.newAttemptId(), executionId: null, phase: 'completed', at: deps.now() }, deps, options);
-}
-export function withToolCatalogAudit(deps, options = {}) {
-    return {
-        search({ query }, { limit } = {}) {
-            const hits = deps.catalog.search({ query }, limit === undefined ? {} : { limit });
-            appendToolCatalogAttempt({ ...deps, event: { ...deps.identity, toolId: deps.searchToolId, detail: searchToolsAuditDetail({ query, limit: limit ?? null, hits }) } }, options);
-            return hits;
-        },
-        describe({ id }) {
-            const entry = deps.catalog.describe({ id });
-            appendToolCatalogAttempt({ ...deps, event: { ...deps.identity, toolId: deps.describeToolId, detail: describeToolAuditDetail({ id, entry }) } }, options);
-            return entry;
-        },
-    };
-}
+// Shared audit owner; used by standalone auditing and the recovery stack.
+export * from './core/tool-audit.js';
 //# sourceMappingURL=tool-audit.js.map

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

@@ -0,0 +1,132 @@
+/**
+ * @file The general tool-failure contract (2026-09-01): what ANY tool attaches to a failed outcome
+ * so a caller — human, agent, or an automated retry loop — has something to reason about instead of a
+ * bare status code with nothing behind it.
+ *
+ * ## Why this exists
+ *
+ * Hand-writing a bespoke recovery path per failure mode does not scale — there will always be more
+ * flaws, gaps, and provider quirks than anyone can anticipate and special-case individually. The
+ * leverage is not a smarter model reading a smarter error message; it is a SHARED SHAPE every tool's
+ * failure can be poured into, so one generic loop — read the failure, ask the human through a
+ * surface, apply the answer, retry once — can handle a failure mode nobody wrote code for, using the
+ * identical mechanism that already handles one somebody did.
+ *
+ * ## The four things a diagnostic carries
+ *
+ * 1. **What failed.** Deliberately NOT modeled in this shared contract — it is always domain-specific,
+ *    and forcing every failure mode into one generic "what failed" string or object would either
+ *    flatten real structure that needs to stay queryable (a concrete diagnostic's own fact fields —
+ *    see {@link AuthFailureDiagnostic}'s `schemeSent`/`usernameStored` in `features/custom-credentials/
+ *    credentialed-request.ts` for the worked example) or force a restructuring this file has no
+ *    business demanding of every domain that wants to adopt it. A concrete diagnostic type carries
+ *    its own facts as its own additional fields, declared alongside the two this contract does own.
+ * 2. **The best hypothesis why** — folded into {@link ToolFailureDiagnostic.hint}.
+ * 3. **What input or state would change the outcome** — also folded into `hint`, not a separate field;
+ *    see that property's own doc for why the two live together.
+ * 4. **Whether a registered tool can supply it** — {@link ToolFailureDiagnostic.remedyToolId}.
+ *
+ * ## Built from one worked example, not designed from zero
+ *
+ * `AuthFailureDiagnostic` is this contract's first instance, extracted AFTER it shipped and proved
+ * itself against a real incident — not designed up front from a guess at what failures might someday
+ * look like. See that type's own file header, "Authentication-failure diagnostics", for the incident
+ * and for the exact honesty contract every one of its fields is held to. This file generalizes its
+ * SHAPE, not its content: the fields that type adds (`schemeSent`, `usernameStored`) and the exact
+ * wording of its `hint` are unchanged by this extraction.
+ *
+ * ## The honesty contract every field is held to
+ *
+ * - **Silence is the default, not an afterthought.** Both fields below are optional, and absent
+ *   together far more often than present: a diagnostic type should fill them in for the ONE narrow
+ *   shape it can honestly speak to, and stay silent for every other shape — including shapes that
+ *   look superficially similar. Repeating advice that has already been tried and failed, or guessing
+ *   at a cause this diagnostic cannot actually tell apart from some other one, is a false lead, not
+ *   merely an unhelpful one.
+ * - **Never a claim.** `hint`, when present, is hedged ("may"/"might"/"could") — a hypothesis for a
+ *   human or agent to try, never an assertion of the real cause.
+ * - **Additive, never a replacement.** A diagnostic rides ALONGSIDE the tool's own real failure output
+ *   (a provider's response body, a thrown error's message) — it never suppresses or reinterprets it.
+ * - **`hint` and `remedyToolId` travel as a pair, never `remedyToolId` alone.** A tool id with nothing
+ *   explaining why it might help is a suggestion with no argument behind it, not a diagnostic. The
+ *   reverse is fine: `hint` with no `remedyToolId` simply means no registered tool can supply the fix
+ *   yet — the hypothesis is still worth surfacing to a human who can act on it by hand.
+ *
+ * ## The one-cycle guard
+ *
+ * `remedyToolId` is a POINTER — a tool id, nothing else. It carries no callback, no arguments, and no
+ * instruction to invoke it automatically. That is deliberate: the consuming loop (ask the human → apply
+ * the answer through the named tool → retry ONCE) owns the decision of whether and how to act on it,
+ * and owns the guard against a second cycle. A diagnostic that carried more than an id — an executable
+ * action, say — would let that guard slip into this file instead of staying where the actual retry
+ * happens, turning a bug in this contract into a genuine loop instead of a single bounded retry.
+ *
+ * ## Architectural role
+ *
+ * `contracts/core`, domain-agnostic — it names no post, page, credential, or other domain concept, so
+ * a failure mode in any feature can adopt it without this file growing a dependency on that feature.
+ */
+/**
+ * A tool-failure diagnostic's shared, domain-agnostic half. A concrete diagnostic type extends this
+ * with whatever structured facts its own failure mode requires (facet 1, "what failed" — see this
+ * file's header) as additional fields alongside the two declared here.
+ */
+export interface ToolFailureDiagnostic {
+    readonly setupToolId?: string;
+    readonly prefill?: Readonly<Record<string, string | number | boolean | null>>;
+    /**
+     * The best hypothesis for why the call failed, together with what input or state would change the
+     * outcome if that hypothesis is right (facets 2 and 3 of this file's header) — one hedged sentence,
+     * never a bare claim. Omitted entirely — not filled with a guess — whenever the failure could have
+     * more than one honest explanation from here. See this file's header, "The honesty contract every
+     * field is held to".
+     *
+     * Folded into one field rather than split into separate `hypothesis`/`remedy` fields: every diagnosis
+     * this contract has actually had to express so far is a single hedged sentence that names both in
+     * the same breath ("X may be why — saving Y may fix it"), and splitting a hedge into two structured
+     * fields would invite treating the "remedy" half as more certain than the hedge it depends on.
+     */
+    readonly hint?: string;
+    /**
+     * The id of an already-registered tool that could supply the fix `hint` describes, when one exists
+     * (facet 4 of this file's header) — a pointer only, never a callback; see this file's header, "The
+     * one-cycle guard". Present only alongside `hint` — never on its own.
+     */
+    readonly remedyToolId?: string;
+}
+/**
+ * Marks `diagnostic` as issued by the calling tool for a real failure, so the recovery loop
+ * (`assistant/tool-failure-recovery.ts`) may act on it. Returns the same object. Call it where the
+ * diagnostic is built, and return that object itself: a copy (spread, JSON round trip) is not issued.
+ *
+ * @complexity O(1).
+ */
+export declare function issueToolFailureDiagnostic<T extends ToolFailureDiagnostic>({ diagnostic }: {
+    diagnostic: T;
+}, _optional?: {}): T;
+/**
+ * True only for an object {@link issueToolFailureDiagnostic} marked.
+ *
+ * @complexity O(1).
+ */
+export declare function isIssuedToolFailureDiagnostic({ value }: {
+    value: unknown;
+}, _optional?: {}): boolean;
+/** Only card metadata travels through recovery; secret values belong to the parked card. */
+export declare function issueCredentialSetup(required: {
+    setupToolId: string;
+    prefill: Readonly<Record<string, string | number | boolean | null>>;
+    assertCredentialFreeField: (required: {
+        value: string;
+        field: string;
+    }, optional: Record<string, never>) => void;
+    containsSecret: (required: {
+        text: string;
+    }) => boolean;
+}, _optional?: {}): ToolFailureDiagnostic & {
+    setupToolId: string;
+    prefill: typeof required.prefill;
+    hint: string;
+    remedyToolId: string;
+};
+//# sourceMappingURL=diagnostics.d.ts.map