@jini-ai/daemon 0.5.3 → 0.6.0

package/dist/tool-recovery/redaction.js

@@ -0,0 +1,192 @@
+/**
+ * @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.
+ */
+/** 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 const TOOL_ERROR_ID_PATTERN = /\bERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}\b/;
+/**
+ * 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 function mintToolErrorId({ randomHex }, _optional = {}) {
+    const hex = randomHex({ bytes: 8 }).toUpperCase();
+    const groups = hex.match(/.{4}/g) ?? [];
+    return `ERR-${groups.join("-")}`;
+}
+/**
+ * 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 function readToolErrorId({ result }, _optional = {}) {
+    const id = result.errorId;
+    return typeof id === "string" ? id : 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 function isRedactedToolFailure({ result }, _optional = {}) {
+    return readToolErrorId({ result }, {}) !== undefined;
+}
+/** The unredacted reason for one delegated-route internal error, before {@link redactSecretShapes}. */
+function delegatedInternalErrorReason(context) {
+    if (context.status === "timed-out")
+        return `tool "${context.toolId}" timed out before it finished`;
+    if (context.status === "cancelled") {
+        return `tool "${context.toolId}" was cancelled before it finished (the run ended or the call was abandoned)`;
+    }
+    if (context.error instanceof Error && context.error.message.length > 0)
+        return context.error.message;
+    if (typeof context.error === "string" && context.error.length > 0)
+        return context.error;
+    return `tool "${context.toolId}" failed`;
+}
+/**
+ * `@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 function describeDelegatedInternalError({ context, ...deps }, _optional = {}) {
+    const { text, redactions } = deps.redactSecretShapes({ text: delegatedInternalErrorReason(context) });
+    const errorId = deps.mintErrorId();
+    safeOnFailure(deps.onFailure, {
+        errorId,
+        toolId: context.toolId,
+        runId: context.runId,
+        principalId: "(unresolved)",
+        executionId: `(none) correlationId=${context.correlationId}`,
+        redactions,
+        message: text,
+    });
+    return `Error ${errorId}: ${text}`;
+}
+/**
+ * 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 function delegatedToolErrorDisclosure(deps, _optional = {}) {
+    return {
+        isModelSafeToolFailure: ({ result }) => isRedactedToolFailure({ result }, {}),
+        describeInternalError: (context) => describeDelegatedInternalError({ context, ...deps }, {}),
+    };
+}
+/** Calls `onFailure`, containing a throw so a hostile or buggy sink can never turn a
+ *  redacted result into a thrown error — audit is observation, never a gate, the same rule
+ *  `tool-executor-audit.ts`'s `appendSafely` enforces for its own sink. */
+function safeOnFailure(onFailure, record) {
+    try {
+        onFailure(record);
+    }
+    catch {
+        // A failing observer must neither gate the result nor leak its own exception text.
+    }
+}
+/**
+ * Redacts one `failed` result per this file's Behavior table — the only place this file makes a
+ * decision; `withRedactedToolFailures` itself is pure plumbing around this.
+ *
+ * @complexity O(1) plus {@link redactSecretShapes}'s own O(text length) pass.
+ */
+function redactFailedResult(result, context, deps) {
+    if (result.errorKind === "validation") {
+        if (result.error === undefined)
+            return result;
+        return { ...result, error: deps.redactSecretShapes({ text: result.error }).text };
+    }
+    const mintErrorId = deps.mintErrorId;
+    const onFailure = deps.onFailure;
+    const { text, redactions } = deps.redactSecretShapes({ text: result.error ?? `tool "${context.toolId}" failed` });
+    const errorId = mintErrorId();
+    safeOnFailure(onFailure, {
+        errorId,
+        toolId: context.toolId,
+        runId: context.runId,
+        principalId: context.principalId,
+        executionId: result.executionId,
+        redactions,
+        message: text,
+    });
+    const redacted = { ...result, error: `Error ${errorId}: ${text}`, errorId };
+    return redacted;
+}
+/**
+ * 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 function withRedactedToolFailures({ inner, ...deps }, _optional = {}) {
+    return {
+        execute: async ({ principal, run, toolId, input }, { signal, emitSurface } = {}) => {
+            const result = await inner.execute({ principal, run, toolId, input }, { ...(signal === undefined ? {} : { signal }), ...(emitSurface === undefined ? {} : { emitSurface }) });
+            if (result.status !== "failed")
+                return result;
+            return redactFailedResult(result, { toolId, runId: run.id, principalId: principal.id }, deps);
+        },
+        resumeConfirmation: (args) => inner.resumeConfirmation(args),
+        cancel: (executionId) => inner.cancel(executionId),
+        getAuditRecord: (executionId) => inner.getAuditRecord(executionId),
+    };
+}
+//# sourceMappingURL=redaction.js.map

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

@@ -0,0 +1,69 @@
+/**
+ * @file The one place Tovu's `ToolExecutor` decorator stack is composed.
+ *
+ * The order of these three wrappers is load-bearing in two different directions, and it was
+ * previously spelled out only as an expression inside `agent-daemon-server.ts` — a module that boots
+ * Express, opens a database, and spawns agents, so nothing could exercise the composition without
+ * booting all of it. A security property that no test can reach is a security property that drifts:
+ * the read-only gateway's bypass (see `read-only-tool-constraint.ts`) lived precisely in the gap
+ * between "the route check is tested" and "the composition is not". This function closes that gap by
+ * being the composition, callable on its own.
+ *
+ * Innermost to outermost:
+ *
+ * 1. `withReadOnlyToolConstraint` — wraps the BARE executor, so every dispatch by every layer above
+ *    it, including a tool id no caller ever named, has to pass the read-only gate to reach a handler.
+ *    Anything further out would be bypassed by whatever sits beneath it.
+ * 2. `withRedactedToolFailures` (2026-09-16) — blanks secret-shaped values out of every `failed`
+ *    result and mints its `ERR-…` id, per the owner's "hide secrets only" ruling (see that file's own
+ *    header). Sits ABOVE the read-only gate so a read-only refusal (`status: 'denied'`, set by layer
+ *    1, never `'failed'`) is never touched by it, and BELOW `withToolAttemptAudit` so the audit sees
+ *    the finished `errorId` and can store it (`tool-executor-audit.ts`). It sits INSIDE
+ *    `withToolFailureRecovery` (layer 4) rather than outside it: recovery's own read-only-remedy
+ *    refusal message is set on the OUTER result, after this layer has already run, so that message is
+ *    never redacted either — only the original/remedy/retry calls recovery makes THROUGH `inner` pass
+ *    through this layer, each redacted on its own.
+ * 3. `withToolAttemptAudit` — appends `requested` BEFORE delegating, which is the only ordering that
+ *    records an unknown tool id or a throwing authorization (see that file's own doc). Sitting above
+ *    the constraint gate means a read-only refusal is itself audited as a denial. Skipped entirely
+ *    when the caller supplies no `toolAttemptAudit` — see {@link AssistantToolExecutorDeps}'s own doc.
+ * 4. `withToolFailureRecovery` — outermost, so the remedy call and the retry it can make each land as
+ *    their own audited attempt row. The opposite order would collapse all three into the one outer
+ *    "completed" row the audit records for the call the transport actually made, losing the remedy
+ *    tool's own attempt from the trail entirely.
+ *
+ * Composed the SAME way for both of Tovu's tool-dispatch surfaces: the agent daemon's delegated-tool
+ * route and BYOK's `byok-tool-surface.ts` (as of 2026-09-06 — previously BYOK hand-assembled its own
+ * second copy of this stack that never wrapped `withReadOnlyToolConstraint`, so a decorator known to
+ * apply to "every read-only gateway" in fact applied to only one of the two; see that file's own
+ * `executor` construction for the call site).
+ *
+ * Architectural role: `src/assistant` composition-layer adapter. Takes its collaborators as
+ * arguments and constructs no policy, sink, or registry of its own.
+ */
+import { type ToolExecutor } from "../tool-executor.js";
+import type { ToolRegistry } from "@jini-ai/core";
+import type { ToolAttemptAuditSink } from "../core/tool-audit.js";
+import type { SurfaceExchangeStore } from "../surface-exchanges.js";
+import { type ToolFailureRecoveryDeps } from "./recovery.js";
+import { type RedactedToolFailuresDeps } from "./redaction.js";
+export interface AssistantToolExecutorDeps extends Omit<ToolFailureRecoveryDeps, "registry"> {
+    readonly registry: ToolRegistry;
+    readonly surfaceExchanges: SurfaceExchangeStore;
+    readonly newExecutionId: () => string;
+    /** Optional sink is a real supported configuration; never require a dummy observer. */
+    readonly toolAttemptAudit?: {
+        readonly sink: ToolAttemptAuditSink;
+        readonly workspaceId: string;
+        readonly now: () => string;
+        readonly newAttemptId: () => string;
+        readonly onSinkError?: (error: unknown) => void;
+    };
+    readonly toolFailures: RedactedToolFailuresDeps;
+}
+/** One registry and innermost read-only gate protect original, remedy and retry alike.
+ * Redaction precedes observation; recovery is outermost so each actual attempt is audited.
+ * @complexity O(1) composition; each decorator owns its runtime cost.
+ */
+export declare function createAssistantToolExecutor(deps: AssistantToolExecutorDeps, _optional?: {}): ToolExecutor;
+//# sourceMappingURL=stack.d.ts.map

package/dist/tool-recovery/stack.js

@@ -0,0 +1,62 @@
+/**
+ * @file The one place Tovu's `ToolExecutor` decorator stack is composed.
+ *
+ * The order of these three wrappers is load-bearing in two different directions, and it was
+ * previously spelled out only as an expression inside `agent-daemon-server.ts` — a module that boots
+ * Express, opens a database, and spawns agents, so nothing could exercise the composition without
+ * booting all of it. A security property that no test can reach is a security property that drifts:
+ * the read-only gateway's bypass (see `read-only-tool-constraint.ts`) lived precisely in the gap
+ * between "the route check is tested" and "the composition is not". This function closes that gap by
+ * being the composition, callable on its own.
+ *
+ * Innermost to outermost:
+ *
+ * 1. `withReadOnlyToolConstraint` — wraps the BARE executor, so every dispatch by every layer above
+ *    it, including a tool id no caller ever named, has to pass the read-only gate to reach a handler.
+ *    Anything further out would be bypassed by whatever sits beneath it.
+ * 2. `withRedactedToolFailures` (2026-09-16) — blanks secret-shaped values out of every `failed`
+ *    result and mints its `ERR-…` id, per the owner's "hide secrets only" ruling (see that file's own
+ *    header). Sits ABOVE the read-only gate so a read-only refusal (`status: 'denied'`, set by layer
+ *    1, never `'failed'`) is never touched by it, and BELOW `withToolAttemptAudit` so the audit sees
+ *    the finished `errorId` and can store it (`tool-executor-audit.ts`). It sits INSIDE
+ *    `withToolFailureRecovery` (layer 4) rather than outside it: recovery's own read-only-remedy
+ *    refusal message is set on the OUTER result, after this layer has already run, so that message is
+ *    never redacted either — only the original/remedy/retry calls recovery makes THROUGH `inner` pass
+ *    through this layer, each redacted on its own.
+ * 3. `withToolAttemptAudit` — appends `requested` BEFORE delegating, which is the only ordering that
+ *    records an unknown tool id or a throwing authorization (see that file's own doc). Sitting above
+ *    the constraint gate means a read-only refusal is itself audited as a denial. Skipped entirely
+ *    when the caller supplies no `toolAttemptAudit` — see {@link AssistantToolExecutorDeps}'s own doc.
+ * 4. `withToolFailureRecovery` — outermost, so the remedy call and the retry it can make each land as
+ *    their own audited attempt row. The opposite order would collapse all three into the one outer
+ *    "completed" row the audit records for the call the transport actually made, losing the remedy
+ *    tool's own attempt from the trail entirely.
+ *
+ * Composed the SAME way for both of Tovu's tool-dispatch surfaces: the agent daemon's delegated-tool
+ * route and BYOK's `byok-tool-surface.ts` (as of 2026-09-06 — previously BYOK hand-assembled its own
+ * second copy of this stack that never wrapped `withReadOnlyToolConstraint`, so a decorator known to
+ * apply to "every read-only gateway" in fact applied to only one of the two; see that file's own
+ * `executor` construction for the call site).
+ *
+ * Architectural role: `src/assistant` composition-layer adapter. Takes its collaborators as
+ * arguments and constructs no policy, sink, or registry of its own.
+ */
+import { createToolExecutor } from "../tool-executor.js";
+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";
+/** One registry and innermost read-only gate protect original, remedy and retry alike.
+ * Redaction precedes observation; recovery is outermost so each actual attempt is audited.
+ * @complexity O(1) composition; each decorator owns its runtime cost.
+ */
+export function createAssistantToolExecutor(deps, _optional = {}) {
+    const guarded = withReadOnlyToolConstraint({ inner: createToolExecutor({ registry: deps.registry }),
+        registry: deps.registry, idGenerator: { newId: deps.newExecutionId }, messages: deps.readOnlyMessages }, {});
+    const redacted = withRedactedToolFailures({ inner: guarded, ...deps.toolFailures }, {});
+    const audited = deps.toolAttemptAudit
+        ? withToolAttemptAudit({ inner: redacted, ...deps.toolAttemptAudit, readErrorId: readToolErrorId }, deps.toolAttemptAudit.onSinkError ? { onSinkError: deps.toolAttemptAudit.onSinkError } : {})
+        : redacted;
+    return withToolFailureRecovery({ ...deps, inner: audited }, {});
+}
+//# sourceMappingURL=stack.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/daemon",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "The stateful agent daemon runtime: run lifecycle, durable event-log port, the tool-execution boundary, agent executor, terminal sessions, and routines.",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,15 @@
       "./tool-audit": "universal",
       "./surface-exchanges": "universal",
       "./session-coordination": "universal",
-      "./run-credentials": "node"
+      "./run-credentials": "node",
+      "./tool-recovery": "node"
+    },
+    "isolation": {
+      "shared": [
+        "src/tool-executor.ts",
+        "src/surface-exchanges.ts",
+        "src/scheduler.ts"
+      ]
     }
   },
   "type": "module",
@@ -97,6 +105,11 @@
       "types": "./dist/run-credentials.d.ts",
       "import": "./dist/run-credentials.js",
       "default": "./dist/run-credentials.js"
+    },
+    "./tool-recovery": {
+      "types": "./dist/tool-recovery/index.d.ts",
+      "import": "./dist/tool-recovery/index.js",
+      "default": "./dist/tool-recovery/index.js"
     }
   },
   "files": [
@@ -115,12 +128,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "dependencies": {
-    "@jini-ai/protocol": "^0.4.1",
-    "@jini-ai/agent-runtime": "^0.4.1",
-    "@jini-ai/platform": "^0.5.1",
-    "@jini-ai/core": "^0.4.1"
-  },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.9",
     "node-pty": "^1.1.0",
@@ -132,9 +139,17 @@
     "@types/pg": "8.23.1",
     "express": "^4.21.0",
     "@types/express": "^4.17.21",
-    "@jini-ai/http-kit": "0.4.0",
-    "@jini-ai/db": "0.3.0",
-    "@jini-ai/chat": "0.5.4"
+    "@jini-ai/db": "0.3.1",
+    "@jini-ai/http-kit": "0.4.1",
+    "@jini-ai/agent-runtime": "^0.4.4",
+    "@jini-ai/chat": "0.5.7",
+    "@jini-ai/core": "^0.4.2",
+    "@jini-ai/platform": "^0.5.2",
+    "@jini-ai/protocol": "^0.4.3"
+  },
+  "dependencies": {
+    "@jini-ai/core": "^0.4.2",
+    "@jini-ai/protocol": "^0.4.3"
   },
   "peerDependencies": {
     "node-pty": "^1.1.0",
@@ -144,7 +159,9 @@
     "@electric-sql/pglite": "0.5.8",
     "pg": "^8.23.0",
     "@jini-ai/http-kit": "^0.4.0",
-    "express": "^4.21.0"
+    "express": "^4.21.0",
+    "@jini-ai/agent-runtime": "^0.4.4",
+    "@jini-ai/platform": "^0.5.1"
   },
   "peerDependenciesMeta": {
     "node-pty": {
@@ -170,6 +187,12 @@
     },
     "express": {
       "optional": true
+    },
+    "@jini-ai/agent-runtime": {
+      "optional": true
+    },
+    "@jini-ai/platform": {
+      "optional": true
     }
   },
   "scripts": {