@jini-ai/daemon 0.5.3 → 0.5.4

package/dist/tool-recovery/recovery.js

@@ -0,0 +1,419 @@
+import { isIssuedToolFailureDiagnostic } from "./diagnostics.js";
+import { askOnce, SURFACE_DISMISSED_PARAM, SURFACE_EXCHANGE_ID_PARAM, } from "../surface-exchanges.js";
+import { refuseNonReadOnlyDispatch } from "../core/read-only-tools.js";
+/**
+ * @file The CONSUMER of `contracts/core/tool-failure-diagnostics.ts`'s `ToolFailureDiagnostic`
+ * contract — the generic ask -> apply -> retry-once loop that contract's own header describes as the
+ * payoff for adopting it ("one generic loop ... can handle a failure mode nobody wrote code for, using
+ * the identical mechanism that already handles one somebody did"). Before this file, `hint`/
+ * `remedyToolId` were read by nobody but the MODEL, acting on prose in a tool's own catalog
+ * description (`custom_credential_verify`/`custom_credential_make_request`'s "ask the human ...
+ * retry ONCE" wording). This file makes the same recovery a real mechanism that runs whether or not
+ * the model happens to follow that prose.
+ *
+ * ## The seam: a `ToolExecutor` decorator, not a tool
+ *
+ * `withToolFailureRecovery` wraps `@jini-ai/daemon`'s `ToolExecutor` — the SAME kind of drop-in
+ * `tool-executor-audit.ts`'s `withToolAttemptAudit` already is, for the same reason: this is the one
+ * layer that (a) sees every completed tool result BEFORE it reaches the model, (b) is handed the
+ * live `emitSurface` a handler would use to raise a human-facing surface, and (c) can re-invoke a
+ * tool — the remedy, then the original again — with the SAME `principal`/`run`/`signal` the first
+ * call had. No domain module (a `tool-registrations.ts`) has all three: a domain handler sees only
+ * its OWN result, not another domain's `remedyToolId`. The tool-registration layer was considered and
+ * rejected for exactly that reason — `custom_credential_set_username` is a different domain from
+ * whatever OTHER tool a future diagnostic might name, and this loop has to work for a diagnostic
+ * nobody has written yet, not just this one.
+ *
+ * Composed OUTSIDE `withToolAttemptAudit` in `agent-daemon-server.ts` (audit wraps the bare executor;
+ * this wraps the audited one) so the remedy call and the retry are each their own audited attempt,
+ * not lost inside one outer "completed" row — see that file's own wiring comment.
+ *
+ * ## What triggers it
+ *
+ * Only a `status: 'completed'` execution (a handler that returned normally) is even inspected — a
+ * thrown error has no structured output to carry a diagnostic in, and `ToolFailureDiagnostic` was
+ * never meant to model that case (see that file's own header, facet 1). The completed output is
+ * walked (bounded, see {@link findActionableDiagnostic}) for the first plain object the tool ISSUED
+ * (`issueToolFailureDiagnostic` — so stored content shaped like a diagnostic never counts) carrying BOTH a
+ * string `hint` AND a string `remedyToolId`. `hint` with no `remedyToolId` is deliberately NOT
+ * actionable here — the general contract's own header says as much ("no registered tool can supply
+ * the fix yet ... still worth surfacing to a human who can act on it by hand"): a human reading the
+ * model's own report of the failure is that "by hand" path; this loop only exists for the case where
+ * a tool id names something IT can do about it.
+ *
+ * ## What it asks for, and why that can never be a secret
+ *
+ * The loop does not know what a `hint` means — it is prose. What it CAN know, structurally, is the
+ * remedy tool's own published {@link ToolDescriptor.inputSchema}: which fields it requires, and which
+ * of those the ORIGINAL failing call's input already supplies (by matching key name — e.g. both
+ * `custom_credential_make_request` and `custom_credential_set_username` name a `label`). Whatever is
+ * required but not already known is the ONE thing worth asking a human for — see
+ * {@link planRemedyCall}. This is deliberately narrow: more than one unknown field, or a field whose
+ * schema type isn't plain text, means this loop has no safe, generic way to ask for it, and it backs
+ * off entirely rather than invent a shape.
+ *
+ * That narrowness is what keeps a secret out of this loop's own text field, BY CONSTRUCTION, not by a
+ * rule someone has to remember: `custom_credential_set_token`'s entire schema is `{label}`, and
+ * `label` is already known from the original call — so `planRemedyCall` computes ZERO fields to ask
+ * for, and this loop calls it with nothing but the carried-forward `label`. The token itself, if that
+ * tool is ever named as a `remedyToolId`, would still only ever reach the server the way that tool's
+ * OWN handler already collects it (its own masked form, opened when THIS loop invokes it) — never
+ * through a field this loop rendered, and never through a model-issued call's params. See
+ * `credentialed-request.ts`'s header for the incident this reasoning was written against.
+ *
+ * ## The one-cycle guard — structural, not a counter
+ *
+ * `execute` below calls `inner.execute` up to three times (the original call, the remedy call, the
+ * retry) and NEVER calls itself or the wrapper it returns. There is therefore no code path by which a
+ * hint surfacing on the remedy call's own result, or on the retry's result, can trigger a second ask
+ * -> apply -> retry cycle: the scan-for-a-diagnostic step only ever runs once per external
+ * `execute()` invocation, because it is written exactly once, outside any loop or recursion. A future
+ * edit would have to ADD a call from inside this function back into itself to reintroduce a second
+ * cycle — it cannot happen by a counter being reset, a flag being missed, or any other stateful
+ * mistake, because no state is involved at all.
+ *
+ * ## What it never does
+ *
+ * - Never suppresses the original failure: every early return hands back `result` — the exact object
+ *   `inner.execute` produced for the original call, provider body and status included — untouched.
+ *   The one return that is not byte-identical still carries that exact `output`: a remedy refused
+ *   because this execution is read-only-constrained adds an `error` explaining that the recovery was
+ *   not attempted (see `read-only-tool-constraint.ts`), because returning the original silently would
+ *   be its own lie — "nothing was written" and "nothing was ever going to be tried" are different
+ *   facts, and the caller can only act on the second one if it is told.
+ * - Never runs a remedy that writes on behalf of a caller that asked for reads only. The dispatch
+ *   below would be refused by `withReadOnlyToolConstraint` in any case — that gate is the
+ *   enforcement, and it sits innermost precisely so it does not depend on this file remembering —
+ *   but this loop asks the same single question first so no human is ever prompted for an answer
+ *   that would then be thrown away.
+ * - Never invents an answer: a declined, dismissed, expired, or blank response to the recovery surface
+ *   is treated as "do not proceed," not as licence to guess.
+ * - Never adds cost to the overwhelmingly common no-hint case: the scan is one bounded, pure walk of
+ *   an already-in-memory value, no I/O, no surface, no second call.
+ *
+ * Architectural role: `src/assistant` composition-layer adapter, mirroring `tool-executor-audit.ts`'s
+ * own role — depends on the domain-agnostic surface-exchange contract and the kernel's own
+ * `ToolExecutor`/`ToolRegistry` shapes, never on any domain feature.
+ */
+/** Bounds {@link findActionableDiagnostic}'s walk of a handler's output — generous for any real tool
+ *  result in this codebase (a handful of fields, one or two levels of nesting) while keeping an
+ *  adversarially large or deep result cheap to give up on rather than a source of unbounded work. */
+const MAX_DIAGNOSTIC_SCAN_DEPTH = 6;
+const MAX_DIAGNOSTIC_SCAN_NODES = 500;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isActionableDiagnostic(value) {
+    return typeof value.hint === "string" && value.hint.length > 0 && typeof value.remedyToolId === "string" && value.remedyToolId.length > 0;
+}
+/**
+ * Whether a remedy tool's own COMPLETED result reports that it did not actually apply the fix. A
+ * `completed` execution status means only that the remedy tool ran without being denied or throwing —
+ * several human-gated write tools in this codebase report a decline, an expiry, or a validation
+ * failure as a normal `{saved: false, reason, ...}` RESULT rather than a non-completed status (see
+ * `custom_credential_set_token`, `external_mcp_*_save`, and the S3-compatible publish-credential save,
+ * each returning `{saved: true}` on success or `{saved: false, ...}` for every other outcome). This
+ * loop must not read `completed` as `succeeded` for any of them, or it would retry the original call
+ * as if the fix had been applied when it had not.
+ *
+ * @complexity O(1).
+ */
+function remedyReportedFailure(output) {
+    return isPlainObject(output) && (output["saved"] === false || output["created"] === false || output["cancelled"] === true || output["connected"] === false);
+}
+/** `true` once the bounded walk should stop descending — depth past {@link MAX_DIAGNOSTIC_SCAN_DEPTH}
+ *  or the node budget exhausted. Pulled out of {@link walkForDiagnostic} so that function's own guard
+ *  is a single call instead of a compound `||` condition. */
+function diagnosticScanLimitReached(depth, scanState) {
+    return depth > MAX_DIAGNOSTIC_SCAN_DEPTH || scanState.visited >= MAX_DIAGNOSTIC_SCAN_NODES;
+}
+/** The children {@link walkForDiagnostic} should recurse into for `value` — an object's own values, an
+ *  array's own elements, or `undefined` for anything else (a leaf, nothing to descend into). */
+function diagnosticScanChildren(value) {
+    if (isPlainObject(value))
+        return Object.values(value);
+    if (Array.isArray(value))
+        return value;
+    return undefined;
+}
+/**
+ * One step of the bounded walk for {@link findActionableDiagnostic} — checks `value` itself, then
+ * recurses into its children (via {@link diagnosticScanChildren}) until a match is found or the walk
+ * is exhausted.
+ *
+ * @complexity O(min(n, {@link MAX_DIAGNOSTIC_SCAN_NODES})) where n is the subtree's own node count.
+ */
+function walkForDiagnostic(value, depth, scanState) {
+    if (diagnosticScanLimitReached(depth, scanState))
+        return undefined;
+    scanState.visited += 1;
+    // Issued, not merely shaped like one: stored content a tool returns (a post's `bodyJson`, a
+    // widget's props) is plain JSON and can carry `{hint, remedyToolId}` too. Only a diagnostic the
+    // tool itself issued for a failure may raise the recovery dialog — see `issueToolFailureDiagnostic`.
+    if (isPlainObject(value) && isIssuedToolFailureDiagnostic({ value }, {}) && isActionableDiagnostic(value)) {
+        return value;
+    }
+    const children = diagnosticScanChildren(value);
+    if (!children)
+        return undefined;
+    for (const child of children) {
+        const found = walkForDiagnostic(child, depth + 1, scanState);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Walks a completed tool call's raw output for the first nested object carrying an actionable
+ * diagnostic (see {@link isActionableDiagnostic}) — domain-agnostic by construction: it knows nothing
+ * about `authDiagnostic`, credentials, or any other field name a concrete diagnostic type happens to
+ * nest itself under, only the two-field SHAPE the general contract defines.
+ *
+ * @param output - `ToolExecutionResult.output` from a `'completed'` execution.
+ * @returns The diagnostic, or `undefined` if none is found within the bounded walk.
+ * @complexity O(min(n, {@link MAX_DIAGNOSTIC_SCAN_NODES})) where n is the output's own node count.
+ */
+function findActionableDiagnostic(output) {
+    return walkForDiagnostic(output, 0, { visited: 0 });
+}
+function isJsonPrimitive(value) {
+    return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/** The remedy tool's own required-field list and property schemas, pulled out of its `inputSchema` —
+ *  or `undefined` if the tool isn't registered or its schema isn't object-shaped at all. Split out of
+ *  {@link planRemedyCall} so that function's own guard clauses read as one step per concern. */
+function resolveRemedySchemaShape(descriptor) {
+    if (!descriptor || !isPlainObject(descriptor.inputSchema))
+        return undefined;
+    const schema = descriptor.inputSchema;
+    const required = Array.isArray(schema["required"]) ? schema["required"].filter((k) => typeof k === "string") : [];
+    const properties = isPlainObject(schema["properties"]) ? schema["properties"] : {};
+    return { required, properties };
+}
+function resolveAskKey(required, knownInput) {
+    const missing = required.filter((key) => !(key in knownInput));
+    if (missing.length > 1)
+        return { ok: false };
+    return { ok: true, askKey: missing[0] };
+}
+/** Every required field except `askKey`, carried forward verbatim from `knownInput` — or `undefined`
+ *  if one of them isn't a JSON primitive (nothing safe to re-forward without guessing at its shape). */
+function buildCarryForward(input) {
+    const { required, askKey, knownInput } = input;
+    const carryForward = {};
+    for (const key of required) {
+        if (key === askKey)
+            continue;
+        const value = knownInput[key];
+        if (!isJsonPrimitive(value))
+            return undefined;
+        carryForward[key] = value;
+    }
+    return carryForward;
+}
+function isTextLikeSchemaType(type) {
+    return type === "string" || (Array.isArray(type) && type.every((t) => t === "string" || t === "null"));
+}
+/** Builds the one field this loop asks a human for, from `askKey`'s own schema entry — or `undefined`
+ *  if that schema isn't plain-text-shaped (this loop never invents how to render a number, boolean,
+ *  enum, or nested-object field). */
+function resolveAskFor(input) {
+    const { askKey, properties } = input;
+    const propSchema = properties[askKey];
+    if (!isPlainObject(propSchema) || !isTextLikeSchemaType(propSchema["type"]))
+        return undefined;
+    const description = propSchema["description"];
+    const prompt = typeof description === "string" && description.trim() !== "" ? description : askKey;
+    return { key: askKey, prompt };
+}
+/**
+ * Works out whether — and how — this loop can safely build a call to `remedyToolId`, from nothing but
+ * that tool's own published `inputSchema` and the ORIGINAL failing call's input. Returns `undefined`
+ * whenever the shape does not fit the one pattern this loop knows how to act on safely: this is the
+ * function that decides "not cleanly possible" for one diagnostic, without ever guessing past it.
+ *
+ * @param input.descriptor - The remedy tool's registry descriptor, or `undefined` if `remedyToolId`
+ *   is not actually registered (a diagnostic naming a tool that does not exist).
+ * @param input.originalInput - The input the ORIGINAL (failing) call was made with.
+ * @returns `undefined` if: the remedy tool isn't registered or has no object-shaped `inputSchema`;
+ *   more than one of its required fields is unknown (no single honest question covers all of them);
+ *   a required field already known is not a JSON primitive (nothing to safely re-forward); or the one
+ *   unknown field's own schema type is not plain-text-shaped (this loop never invents how to render an
+ *   unfamiliar field kind).
+ * @complexity O(k) in the remedy schema's own required-field count (small, fixed per tool).
+ */
+function planRemedyCall(input) {
+    const { remedyToolId, descriptor, originalInput } = input;
+    const shape = resolveRemedySchemaShape(descriptor);
+    if (!shape)
+        return undefined;
+    const knownInput = isPlainObject(originalInput) ? originalInput : {};
+    const missingField = resolveAskKey(shape.required, knownInput);
+    if (!missingField.ok)
+        return undefined;
+    const carryForward = buildCarryForward({ required: shape.required, askKey: missingField.askKey, knownInput });
+    if (!carryForward)
+        return undefined;
+    if (missingField.askKey === undefined)
+        return { remedyToolId, carryForward };
+    const askFor = resolveAskFor({ askKey: missingField.askKey, properties: shape.properties });
+    if (!askFor)
+        return undefined;
+    return { remedyToolId, carryForward, askFor };
+}
+/** Card schemas accept metadata only. Reject secret-shaped prefills before even asking. */
+function planCredentialSetup({ diagnostic, descriptor, deps }, _optional = {}) {
+    const shape = resolveRemedySchemaShape(descriptor);
+    if (!shape || diagnostic.setupToolId !== diagnostic.remedyToolId || !diagnostic.prefill)
+        return undefined;
+    const prefill = diagnostic.prefill;
+    for (const [key, value] of Object.entries(prefill)) {
+        if (!(key in shape.properties) || /token|secret|password|authorization|env|headers|body|key/i.test(key))
+            return undefined;
+        if (!isJsonPrimitive(value) || (typeof value === "string" && deps.containsSecret({ text: value })))
+            return undefined;
+        if (typeof value === "string") {
+            try {
+                deps.assertCredentialFreeField({ value, field: key }, {});
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    if (shape.required.some(key => !(key in prefill)))
+        return undefined;
+    return { remedyToolId: diagnostic.remedyToolId, carryForward: prefill };
+}
+/**
+ * Sends the recovery surface and waits for the human's answer — plain `askOnce`, matching
+ * `custom_credential_make_request`'s own DELETE-gate precedent (`resolveMakeRequestDeleteDecision`)
+ * rather than `askThenReport`: this loop's surface is an ask ABOUT what to try next, not a rendering
+ * of a secret's own submission state, so there is nothing here `askThenReport` was built to correct.
+ *
+ * @complexity O(1) plus whatever `askOnce` itself costs.
+ */
+async function resolveRecoveryDecision(exchange, ui, askForKey) {
+    const answer = await askOnce({ exchange, emission: { channel: "mcp-ui", payload: { resource: ui } } });
+    if (answer.status !== "received")
+        return { proceed: false };
+    if (answer.params[SURFACE_DISMISSED_PARAM] === true)
+        return { proceed: false };
+    if (askForKey === undefined)
+        return { proceed: true };
+    const raw = answer.params[askForKey];
+    const answerValue = typeof raw === "string" ? raw.trim() : "";
+    // Never invent an answer: a blank submission is treated as "do not proceed," not as a value to try.
+    if (answerValue === "")
+        return { proceed: false };
+    return { proceed: true, answerValue };
+}
+function resolveRecoveryGate(input) {
+    const { diagnostic, principal, originalInput, registry, result, deps } = input;
+    const readOnlyRefusal = refuseNonReadOnlyDispatch({ principal, toolId: diagnostic.remedyToolId, registry, messages: deps.readOnlyMessages }, {});
+    if (readOnlyRefusal !== null)
+        return { attempt: false, outcome: { ...result, error: deps.formatReadOnlyRemedyRefusal({ refusal: readOnlyRefusal }) } };
+    const descriptor = registry.list({}).find((d) => d.id === diagnostic.remedyToolId);
+    const plan = diagnostic.setupToolId
+        ? planCredentialSetup({ diagnostic, descriptor, deps }, {})
+        : planRemedyCall({ remedyToolId: diagnostic.remedyToolId, descriptor, originalInput });
+    if (!plan)
+        return { attempt: false, outcome: result };
+    return { attempt: true, plan };
+}
+/** Wires the recovery surface's exchange to close if the caller aborts mid-ask, delegates to
+ *  {@link resolveRecoveryDecision} for the actual answer, and always tears the listener back down —
+ *  pulled out of `execute` so the abort-wiring's own optional chaining does not count toward that
+ *  method's own complexity. */
+async function collectRecoveryDecision(input) {
+    const { exchange, ui, askForKey, signal } = input;
+    const closeOnAbort = () => exchange.close({});
+    signal?.addEventListener("abort", closeOnAbort, { once: true });
+    try {
+        return await resolveRecoveryDecision(exchange, ui, askForKey);
+    }
+    finally {
+        signal?.removeEventListener("abort", closeOnAbort);
+    }
+}
+/** The remedy tool's own input, built from the accepted {@link RemedyPlan}: the planned carry-forward
+ *  fields plus, when one was asked for and answered, the human's own value under that field's key —
+ *  never anything else from the delivered surface response (see this file's header, "What it never
+ *  does"). */
+function buildRemedyInput(plan, decision) {
+    const remedyInput = { ...plan.carryForward };
+    if (plan.askFor && decision.answerValue !== undefined)
+        remedyInput[plan.askFor.key] = decision.answerValue;
+    return remedyInput;
+}
+/**
+ * Wraps `inner` with the generic ask -> apply -> retry-once recovery loop described in this file's
+ * header. A drop-in `ToolExecutor` — every method other than `execute` delegates straight through,
+ * matching `tool-executor-audit.ts`'s own `withToolAttemptAudit` shape.
+ *
+ * @complexity The no-hint path (the overwhelming majority) is one `inner.execute` call plus one bounded
+ *   output scan — O(1) beyond `inner`'s own cost. The recovery path adds at most two further
+ *   `inner.execute` calls (the remedy, the retry) and one surface round trip.
+ */
+export function withToolFailureRecovery({ inner, ...deps }, _optional = {}) {
+    return {
+        execute: async (required, optional = {}) => {
+            const { principal, toolId, input } = required;
+            const { signal, emitSurface } = optional;
+            const result = await inner.execute(required, optional);
+            // SILENCE STAYS FREE: everything but a completed call whose output carries an actionable
+            // diagnostic returns `result` exactly as `inner` produced it — no extra work, no surface, no
+            // added latency. This is the overwhelmingly common case.
+            if (result.status !== "completed")
+                return result;
+            const diagnostic = findActionableDiagnostic(result.output);
+            if (!diagnostic)
+                return result;
+            // No channel to ask through (a headless/synthetic caller) — never guess, never suppress.
+            if (!emitSurface)
+                return result;
+            // A read-only execution may not be recovered by a remedy that writes, and this diagnostic's
+            // shape must fit the one pattern this loop can safely act on — see `resolveRecoveryGate` and
+            // `planRemedyCall`'s own docs for every reason either can decide not to proceed.
+            // `withReadOnlyToolConstraint` would refuse the dispatch below regardless — it is the
+            // enforcement, and it does not depend on this check — but a refusal discovered THERE arrives
+            // only after a human has already been asked to fill in a form whose answer is then thrown away.
+            const gate = resolveRecoveryGate({ diagnostic, principal, originalInput: input, registry: deps.registry, result, deps });
+            if (!gate.attempt)
+                return gate.outcome;
+            let remedyInput = { ...gate.plan.carryForward };
+            if (!diagnostic.setupToolId) {
+                const exchange = deps.surfaceExchanges.open({ binding: { toolId: deps.recoveryToolId, principalId: principal.id }, emit: emitSurface });
+                const ui = deps.buildRecoveryForm({ exchangeId: exchange.id, hint: diagnostic.hint, remedyToolId: diagnostic.remedyToolId, ...(gate.plan.askFor ? { askFor: gate.plan.askFor } : {}) }, {});
+                const decision = await collectRecoveryDecision({ exchange, ui, askForKey: gate.plan.askFor?.key, signal });
+                // Declined, dismissed, expired, or a blank answer — the ORIGINAL failure is still the truth.
+                if (!decision.proceed)
+                    return result;
+                remedyInput = buildRemedyInput(gate.plan, decision);
+            }
+            // Credential setup goes directly to the masked card; it supplies its own human decision.
+            // ---- STRUCTURAL ONE-CYCLE GUARD ----
+            // Both calls below go straight to `inner` — never back through this function or the object it
+            // returns. Whatever either one returns, including a fresh hint+remedyToolId of its own, is never
+            // fed back into the scan above: that scan is written exactly once, above this comment, and
+            // nothing here loops or recurses into it again. See this file's header.
+            const remedyResult = await inner.execute({ ...required, toolId: diagnostic.remedyToolId, input: remedyInput }, optional);
+            // The fix itself did not complete (denied, threw, timed out, ...) — nothing changed, so retrying
+            // the original would only reproduce the same failure. Return the ORIGINAL result, untouched.
+            if (remedyResult.status !== "completed")
+                return result;
+            // The remedy RAN, but its own result says the fix was never actually applied (a declined,
+            // expired, or invalid human-gated write) — see {@link remedyReportedFailure}. "Completed" is not
+            // "succeeded"; retrying here would only reproduce the same failure.
+            if (remedyReportedFailure(remedyResult.output))
+                return result;
+            // Retry the ORIGINAL call exactly once, with its exact original input. Whatever this returns —
+            // success or a fresh failure — is this wrapper's final answer.
+            return inner.execute(required, optional);
+        },
+        resumeConfirmation: (required) => inner.resumeConfirmation(required),
+        cancel: (required) => inner.cancel(required),
+        getAuditRecord: (required) => inner.getAuditRecord(required),
+    };
+}
+//# sourceMappingURL=recovery.js.map

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

@@ -0,0 +1,166 @@
+/**
+ * @file Blanks secret-shaped values out of a FAILED tool's error text and mints a durable, copyable
+ * error ID for the ones that need server-side follow-up — the 2026-09-16 owner decision ("hide
+ * secrets only"): a failed tool's error stays visible everywhere it already reaches (the model, the
+ * chat transcript, the tool card, admin BYOK, the daemon's delegated-tool route, the MCP-UI
+ * redemption endpoint, http-kit's server log), only a secret-shaped VALUE inside it never does.
+ *
+ * ## Position — see `tool-executor-stack.ts`'s own header
+ * Sits between `withReadOnlyToolConstraint` and `withToolAttemptAudit`, and INSIDE
+ * `withToolFailureRecovery` (which calls `inner` for the original call, the remedy, and the retry —
+ * each one redacted here). A read-only refusal is set by `withToolFailureRecovery` on the OUTER
+ * result, after this layer has already run, so it is never touched by it.
+ *
+ * ## Behavior by result
+ * | Result | Action |
+ * |---|---|
+ * | `failed` with `errorKind` `'internal'` or missing | Redact, mint an ID, prefix `Error <ID>: `, add `errorId`, report one {@link ToolFailureRecord} |
+ * | `failed` with `errorKind: 'validation'` | Redact only — no ID, no record. Byte-identical when nothing secret-shaped is present |
+ * | any other status | Returned as the SAME object, untouched |
+ * | inner throws | Rethrown untouched |
+ *
+ * A validation failure is the caller's own input problem: its message is already the full, safe
+ * reason, and nothing about it needs a server-side lookup — see `contracts/core/secret-redaction.ts`
+ * for why only the VALUE is ever blanked, never the surrounding text.
+ *
+ * Architectural role: `src/assistant` composition-layer adapter, same layer as
+ * `tool-executor-audit.ts` and `tool-failure-recovery.ts`. Depends only on the Tovu policy
+ * adapter over `@jini-ai/diagnostics/redaction/secrets-only` and `@jini-ai/daemon`'s `ToolExecutor` shape.
+ */
+import type { ToolExecutionResult, ToolExecutor } from "../tool-executor.js";
+/** Matches a minted error ID anywhere in a string — exported for tests and for a later chat-side
+ *  copy button (`ToolCard` matching this against `result.content`, tracked separately). */
+export declare const TOOL_ERROR_ID_PATTERN: RegExp;
+/**
+ * Mints one error ID: 64 bits of `crypto.randomBytes`, formatted `ERR-XXXX-XXXX-XXXX-XXXX`.
+ *
+ * @returns A string always matching {@link TOOL_ERROR_ID_PATTERN}.
+ * @complexity O(1).
+ */
+export declare function mintToolErrorId({ randomHex }: {
+    randomHex: (required: {
+        bytes: number;
+    }) => string;
+}, _optional?: {}): string;
+/** A `ToolExecutionResult` that may additionally carry the minted error ID — the ONLY field this
+ *  decorator ever adds. Every other field is `inner`'s own, untouched. */
+export type RedactedToolExecutionResult = ToolExecutionResult & {
+    readonly errorId?: string;
+};
+/**
+ * Reads the error ID this decorator attached, if any.
+ *
+ * @param result - Any `ToolExecutionResult`, redacted or not.
+ * @returns The ID, or `undefined` for a result this decorator never touched (not `failed`,
+ *   `errorKind: 'validation'`, or produced upstream of this layer).
+ * @complexity O(1).
+ */
+export declare function readToolErrorId({ result }: {
+    result: ToolExecutionResult;
+}, _optional?: {}): string | undefined;
+/**
+ * `@jini-ai/http-kit`'s `isModelSafeToolFailure` predicate for the delegated-tool route: `true` only
+ * for a failure this decorator already redacted and minted an ID for, so the model gets
+ * `Error <ID>: <reason>` instead of an opaque `INTERNAL_ERROR`. A failure without the ID never
+ * passed through this layer and keeps http-kit's SEC-005 redaction.
+ *
+ * @param result - The settled result the route is about to map.
+ * @returns Whether the route may show `result.error` to the model verbatim.
+ * @complexity O(1).
+ */
+export declare function isRedactedToolFailure({ result }: {
+    result: ToolExecutionResult;
+}, _optional?: {}): boolean;
+/**
+ * What `@jini-ai/http-kit`'s `describeInternalError` hands its describer — declared here,
+ * structurally, rather than imported as `DelegatedToolsInternalErrorContext`, so this module still
+ * compiles against a published http-kit that predates `status`.
+ */
+export interface DelegatedInternalErrorContext {
+    readonly source: string;
+    readonly runId: string;
+    readonly toolId: string;
+    /** http-kit's own id for this failure — the one its `[@jini-ai/http-kit] internal error` log line carries. */
+    readonly correlationId: string;
+    readonly error: unknown;
+    /** Set for a settled `timed-out`/`cancelled`/`failed` result; absent for a throw. */
+    readonly status?: string;
+}
+/**
+ * `@jini-ai/http-kit`'s `describeInternalError` for the agent daemon's delegated-tool route: the
+ * text a model gets in place of the bare `INTERNAL_ERROR: an internal error occurred` for every
+ * failure that route would otherwise redact whole — an unknown tool id (the executor throws), a
+ * throwing `resolvePrincipal`, a `timed-out` or `cancelled` result, and a `failed` result that never
+ * passed through {@link withRedactedToolFailures}. Same "hide secrets only" rule and the same
+ * `Error <ID>: <reason>` shape as that decorator, with one {@link ToolFailureRecord} per call.
+ *
+ * There is no execution or resolved principal to record for a throw, so the record carries
+ * http-kit's `correlationId` in `executionId` instead — the id that joins it to http-kit's own log
+ * line for the same failure.
+ *
+ * @param context - The failure as http-kit reports it.
+ * @param deps - Test seams; production passes nothing.
+ * @returns `Error <ID>: <redacted reason>`.
+ * @complexity O(reason length) for the redaction pass.
+ */
+export declare function describeDelegatedInternalError({ context, ...deps }: RedactedToolFailuresDeps & {
+    context: DelegatedInternalErrorContext;
+}, _optional?: {}): string;
+/**
+ * The two error-disclosure options the agent daemon spreads into `registerDelegatedToolRoutes`, as
+ * one value so the daemon and its tests wire the identical pair: a failure this layer already
+ * ID-tagged answers `422 TOOL_EXECUTION_FAILED`, and every other internal error answers `500` with
+ * {@link describeDelegatedInternalError}'s text.
+ *
+ * @param deps - Test seams forwarded to the describer; production passes nothing.
+ * @complexity O(1).
+ */
+export declare function delegatedToolErrorDisclosure(deps: RedactedToolFailuresDeps, _optional?: {}): {
+    readonly isModelSafeToolFailure: (required: {
+        result: ToolExecutionResult;
+    }) => boolean;
+    readonly describeInternalError: (context: DelegatedInternalErrorContext) => string;
+};
+/** The value-free server-side record for one internal failure — everything needed to find the
+ *  tool, run, principal, execution and full (already redacted) message under its ID, with no secret
+ *  value ever entering it. `message` is the text AFTER {@link redactSecretShapes}. */
+export interface ToolFailureRecord {
+    readonly errorId: string;
+    readonly toolId: string;
+    readonly runId: string;
+    readonly principalId: string;
+    readonly executionId: string;
+    readonly redactions: number;
+    readonly message: string;
+}
+export interface RedactedToolFailuresDeps {
+    /** Host ID source; inject a deterministic source in tests. */
+    readonly mintErrorId: () => string;
+    readonly redactSecretShapes: (required: {
+        text: string;
+    }) => {
+        text: string;
+        redactions: number;
+    };
+    /** Where a {@link ToolFailureRecord} is reported for every internal failure — the §3(b)
+     *  server-side record. Must not throw; a throwing sink is contained without logging its own
+     *  exception, never allowed to turn a redacted result into a thrown
+     *  error. */
+    readonly onFailure: (record: ToolFailureRecord) => void;
+}
+/**
+ * Wraps `inner` so every `failed` result it produces is redacted per this file's Behavior table
+ * before any caller — recovery, the BYOK map, the delegated-tool bridge, the MCP-UI route, or
+ * http-kit's log — ever sees it. Every other status, and every throw, passes through unchanged.
+ *
+ * @param inner - The executor to wrap. Its own decisions (status, `errorKind`, throwing) are never
+ *   second-guessed here — this layer only ever transforms an already-`failed` result's `error` text.
+ * @param deps - Test seams; production callers pass nothing and get the real minter and logger.
+ * @returns A drop-in `ToolExecutor`. `resumeConfirmation`, `cancel`, `getAuditRecord` delegate
+ *   straight through, matching `tool-failure-recovery.ts`'s and `tool-executor-audit.ts`'s own shape.
+ * @complexity O(1) beyond `inner`'s own cost and {@link redactFailedResult}'s.
+ */
+export declare function withRedactedToolFailures({ inner, ...deps }: RedactedToolFailuresDeps & {
+    inner: ToolExecutor;
+}, _optional?: {}): ToolExecutor;
+//# sourceMappingURL=redaction.d.ts.map