@jini-ai/daemon 0.6.17 → 0.6.22

package/dist/http/delegated-tools.js

@@ -1,3 +1,4 @@
+import { inspect } from 'node:util';
 /**
  * @module delegated-tools
  *
@@ -27,7 +28,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
-import { batchOutcomeFor, ToolInputError } from '@jini-ai/core';
+import { redactSecrets, batchOutcomeFor, ToolInputError } from '@jini-ai/core';
 import { createDelegatedToolBridge } from '../index.js';
 import { defineJsonRoute, err, mountJsonRoute, ok, validationError } from '@jini-ai/http-kit';
 import * as readOnlyTools from '../core/read-only-tools.js';
@@ -44,8 +45,9 @@ function checkReadOnlyConstraint(deps, input) {
 }
 /** Logs the real failure server-side and returns the generic, correlation-id-bearing public error (SEC-005: never the raw exception). */
 function defaultInternalErrorSink(context) {
+    // Exceptions can echo credentials; inspect preserves stacks and codes before shared redaction.
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /**
  * The host's {@link DelegatedToolsHttpDeps.describeInternalError} text for `context`, or `undefined`
@@ -62,7 +64,7 @@ function describeSafely(deps, context) {
     }
     catch (error) {
         // eslint-disable-next-line no-console
-        console.error(`[@jini-ai/http-kit] describeInternalError threw (correlationId=${context.correlationId})`, error);
+        console.error(`[@jini-ai/http-kit] describeInternalError threw (correlationId=${context.correlationId})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
         return undefined;
     }
 }
@@ -128,7 +130,7 @@ function parseDelegatedToolExecute(input) {
  * vouches for this exact result via `deps.isModelSafeToolFailure` (it has already redacted the text
  * itself), in which case it is a `422 TOOL_EXECUTION_FAILED` carrying the host's text verbatim.
  */
-function toolExecutionResultToApiResult(deps, { runId, toolId, result }) {
+function toolExecutionResultToApiResult(deps, { runId, toolId, result, recoveryMessage }) {
     switch (result.status) {
         case 'completed': {
             const outcome = batchOutcomeFor({ output: result.output });
@@ -141,7 +143,7 @@ function toolExecutionResultToApiResult(deps, { runId, toolId, result }) {
             return err({ error: createApiError({ code: 'TOOL_OPERATION_DENIED', message: 'this operation was denied during confirmation' }) });
         case 'timed-out':
         case 'cancelled':
-            return err({ error: reportInternalError(deps, { source: 'delegated-tool-execute', error: result.status, runId, toolId, status: result.status }) });
+            return err({ error: reportInternalError(deps, { source: 'delegated-tool-execute', error: result.status, runId, toolId, ...(recoveryMessage ? { recoveryMessage } : {}), status: result.status }) });
         case 'failed':
             return err({ error: failedResultToApiError(deps, { runId, toolId, result }) });
         default: {
@@ -161,6 +163,21 @@ function failedResultToApiError(deps, { runId, toolId, result }) {
     }
     return reportInternalError(deps, { source: 'delegated-tool-execute', error: result.error ?? result.status, runId, toolId, status: 'failed' });
 }
+/** Read host-owned recovery facts once after interruption. The host supplies the deadline and
+ * permission-checked read; a failed read never replaces or retries the original operation.
+ * @complexity One optional bounded read; no extra work on successful executions.
+ */
+async function toolExecutionResultWithRecovery(deps, required) {
+    const { principal, runId, toolId, result } = required;
+    let recoveryMessage;
+    if (result.status === 'timed-out' || result.status === 'cancelled') {
+        try {
+            recoveryMessage = await deps.recoverInterruptedTool?.({ principal, runId, toolId, result });
+        }
+        catch { /* Recovery cannot change the interrupted write or expose its own failure. */ }
+    }
+    return toolExecutionResultToApiResult(deps, { runId, toolId, result, ...(recoveryMessage ? { recoveryMessage } : {}) });
+}
 /**
  * `POST /api/delegated-tool-calls` — executes one delegated tool call against an already-started
  * run. Maps `ToolExecutionResult.status` to the HTTP response via `toolExecutionResultToApiResult`
@@ -222,7 +239,7 @@ export const delegatedToolExecuteRoute = defineJsonRoute({
                 input: input.input,
                 ...(signal !== undefined ? { signal } : {}),
             });
-            return toolExecutionResultToApiResult(deps, { runId: input.runId, toolId: input.toolId, result });
+            return toolExecutionResultWithRecovery(deps, { principal, runId: input.runId, toolId: input.toolId, result });
         }
         catch (error) {
             if (error instanceof ToolInputError) {

package/dist/http/frontend-control.d.ts

@@ -1,39 +1,3 @@
-/**
- * @module frontend-control
- *
- * Assembles the three halves of agent-driven frontend control into one thing a host can wire up as
- * a config entry rather than a checklist.
- *
- * The parts already existed and none of them composed: `@jini-ai/daemon`'s `FrontendSessionRegistry`
- * addresses a run to a surface, this package's own frontend-session routes carry invocations to a
- * browser and answers back, and `createFrontendCapabilityRegistrations` projects a manifest into
- * gated tools. A host had to construct all three, keep them consistent, and remember to bind a run
- * when it started. Every one of those is a chance to get it subtly wrong, and one of them —
- * binding — is a security decision.
- *
- * **Moved here from `@jini-ai/server` (2026-07-31).** It never needed that package: its real
- * dependencies are `core`, `daemon`, `express` and this module's own siblings, all of which
- * `http-kit` already has. The only thing pinning it there was a *type-only* import of
- * `LocalNodeHttpExtension` — so a helper any Express host could use sat behind a package that also
- * pulls in `@jini-ai/sidecar` and `better-sqlite3`. The reference implementation hit exactly this
- * and hand-reimplemented the composition instead. `@jini-ai/server` re-exports it, so existing
- * imports keep working.
- *
- * **This facade never returns the registry**, and that is its most important property. The
- * registry's `invoke` executes a capability on a real user's screen with no policy check, no
- * confirmation, no timeout, and no audit record — it is safe only because the sole thing that can
- * reach it is a `ToolHandler` that `ToolExecutor` already gated. Handing a host the registry so it
- * could "wire something custom" would hand it a bypass, and a bypass that exists gets used. The
- * host gets an HTTP extension, a set of registrations, and a bind hook; none of them can execute a
- * capability directly.
- *
- * **The bind token is not a field on the run DTO.** A run is a neutral kernel noun and a browser
- * surface is not; putting `frontendBindToken` on `RunCreateRequest` would push a browser concept
- * into a protocol every consumer shares, to serve one transport. Instead the host supplies
- * {@link CreateFrontendControlOptions.resolveBindToken}, which reads the token out of whatever
- * envelope that host already uses — `contextRef` is an opaque host blob precisely so hosts can put
- * their own metadata in it. The engine stays neutral and the host keeps one place to look.
- */
 import type { Express } from 'express';
 import type { FrontendSessionOwner } from '../frontend-session-registry.js';
 import type { FrontendSessionsHttpDeps } from './frontend-sessions.js';

package/dist/http/frontend-control.js

@@ -1,8 +1,46 @@
+/**
+ * @module frontend-control
+ *
+ * Assembles the three halves of agent-driven frontend control into one thing a host can wire up as
+ * a config entry rather than a checklist.
+ *
+ * The parts already existed and none of them composed: `@jini-ai/daemon`'s `FrontendSessionRegistry`
+ * addresses a run to a surface, this package's own frontend-session routes carry invocations to a
+ * browser and answers back, and `createFrontendCapabilityRegistrations` projects a manifest into
+ * gated tools. A host had to construct all three, keep them consistent, and remember to bind a run
+ * when it started. Every one of those is a chance to get it subtly wrong, and one of them —
+ * binding — is a security decision.
+ *
+ * **Moved here from `@jini-ai/server` (2026-07-31).** It never needed that package: its real
+ * dependencies are `core`, `daemon`, `express` and this module's own siblings, all of which
+ * `http-kit` already has. The only thing pinning it there was a *type-only* import of
+ * `LocalNodeHttpExtension` — so a helper any Express host could use sat behind a package that also
+ * pulls in `@jini-ai/sidecar` and `better-sqlite3`. The reference implementation hit exactly this
+ * and hand-reimplemented the composition instead. `@jini-ai/server` re-exports it, so existing
+ * imports keep working.
+ *
+ * **This facade never returns the registry**, and that is its most important property. The
+ * registry's `invoke` executes a capability on a real user's screen with no policy check, no
+ * confirmation, no timeout, and no audit record — it is safe only because the sole thing that can
+ * reach it is a `ToolHandler` that `ToolExecutor` already gated. Handing a host the registry so it
+ * could "wire something custom" would hand it a bypass, and a bypass that exists gets used. The
+ * host gets an HTTP extension, a set of registrations, and a bind hook; none of them can execute a
+ * capability directly.
+ *
+ * **The bind token is not a field on the run DTO.** A run is a neutral kernel noun and a browser
+ * surface is not; putting `frontendBindToken` on `RunCreateRequest` would push a browser concept
+ * into a protocol every consumer shares, to serve one transport. Instead the host supplies
+ * {@link CreateFrontendControlOptions.resolveBindToken}, which reads the token out of whatever
+ * envelope that host already uses — `contextRef` is an opaque host blob precisely so hosts can put
+ * their own metadata in it. The engine stays neutral and the host keeps one place to look.
+ */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { createFrontendCapabilityRegistrations, createFrontendSessionRegistry, } from '../index.js';
 import { registerFrontendSessionRoutes } from './frontend-sessions.js';
 function defaultBindErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/server] could not bind run "${context.runId}" to a frontend surface`, context.error);
+    console.error(`[@jini-ai/server] could not bind run "${context.runId}" to a frontend surface`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /**
  * Builds the frontend-control bundle.

package/dist/http/frontend-sessions.js

@@ -28,6 +28,8 @@
  * composition root can make (it is the thing that starts runs), so it calls `registry.bindRun`
  * directly — see `@jini-ai/daemon`'s own module doc for why attach and bind are separate.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
 import { FrontendSessionCapacityError } from '../frontend-session-registry.js';
@@ -45,12 +47,12 @@ function reportInternalError(deps, source, error) {
             deps.onInternalError({ source, error });
         // eslint-disable-next-line no-console
         else
-            console.error(`[@jini-ai/http-kit] internal error (frontend-sessions:${source})`, error);
+            console.error(`[@jini-ai/http-kit] internal error (frontend-sessions:${source})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
     }
     catch (sinkError) {
         // A diagnostic sink must never turn a contained failure into an unhandled rejection of its own.
         // eslint-disable-next-line no-console
-        console.error(`[@jini-ai/http-kit] internal error sink failed (frontend-sessions:${source})`, sinkError);
+        console.error(`[@jini-ai/http-kit] internal error sink failed (frontend-sessions:${source})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
     }
 }
 /**

package/dist/http/index.d.ts

@@ -21,7 +21,7 @@ export type { RoutineDeleteResponse, RoutineHttpDeps, RoutineListResponse, Routi
 export { registerRoutineRoutes, routineCreateRoute, routineDeleteRoute, routineGetRoute, routineListRoute, routineRunNowRoute, routineRunsListRoute, routineUpdateRoute, } from './routines.js';
 export type { CreateDaemonDbToolRegistrationsOptions, DaemonDbHttpDeps, DaemonDbInternalErrorContext, DaemonDbOperations, DaemonDbStatusReport, DaemonDbTableInfo, DaemonDbToolRegistrations, DaemonDbVacuumResult, DbIntegrityIssue, DbIntegrityIssueKind, DbIntegrityReport, } from './db-ops.js';
 export { createDaemonDbToolRegistrations, daemonDbInspectRoute, daemonDbVacuumRoute, daemonDbVerifyRoute, DB_INSPECT_TOOL_ID, DB_VACUUM_TOOL_ID, DB_VERIFY_TOOL_ID, denyAllDaemonDbPolicy, registerDaemonDbRoutes, } from './db-ops.js';
-export type { ToolCatalogEntry, ToolCatalogHttpDeps, ToolCatalogQuery, ToolCatalogSearchHit, } from './tool-catalog.js';
+export type { ToolCatalogEntry, ToolCatalogDescribeOptions, ToolCatalogHttpDeps, ToolCatalogQuery, ToolCatalogSearchHit, } from './tool-catalog.js';
 export { registerToolCatalogRoutes, toolCatalogDescribeRoute, toolCatalogSearchRoute, } from './tool-catalog.js';
 export type { ComponentCatalogEntry, ComponentCatalogHttpDeps, ComponentCatalogQuery, ComponentCatalogSearchHit, } from './component-catalog.js';
 export { registerComponentCatalogRoutes, componentCatalogDescribeRoute, componentCatalogSearchRoute, } from './component-catalog.js';
@@ -58,4 +58,5 @@ export type { RemoteAttachmentLookupOptional, RemoteAttachmentLookupRequired } f
 export { createRemoteAttachmentLookup } from '../remote-attachment-lookup.js';
 export { createTavilyResearchProvider } from './research-tavily.adapter.js';
 export { createFrontendGuestScope } from './frontend-guest-scope.js';
+export { tryRestoreSurface } from './surface-restoration.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -31,4 +31,5 @@ export { ATTACHMENT_LOOKUP_ROUTE_PATH, registerAttachmentLookupRoutes } from './
 export { createRemoteAttachmentLookup } from '../remote-attachment-lookup.js';
 export { createTavilyResearchProvider } from './research-tavily.adapter.js';
 export { createFrontendGuestScope } from './frontend-guest-scope.js';
+export { tryRestoreSurface } from './surface-restoration.js';
 //# sourceMappingURL=index.js.map

package/dist/http/media.js

@@ -39,6 +39,8 @@
  * itself can throw before ever creating a task — an unregistered `toolId`-shaped programming
  * error, per `MediaDispatchEngine.generate`'s own contract).
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
 import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
@@ -49,7 +51,7 @@ const AUDIO_KINDS = new Set(['music', 'speech', 'sfx']);
 const SPEECH_FORMATS = new Set(['mp3', 'wav', 'flac', 'aac', 'opus']);
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 function reportInternalError(deps, source, error, taskId, ownerRef) {
     const correlationId = randomUUID();

package/dist/http/model-proxy.js

@@ -81,6 +81,8 @@
  * over routing for the five providers that already have a dedicated, more
  * specifically-typed path.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { runAnthropicToolTurn, runAzureToolTurn, runGoogleToolTurn, runOllamaToolTurn, runOpenAiToolTurn, } from '@jini-ai/agent-runtime';
 import { createApiError } from '@jini-ai/protocol';
@@ -92,7 +94,7 @@ import { err, ok } from '@jini-ai/http-kit';
 import { firstOptionalFieldError, isArray, isNumber, isRecord, isString, nonEmptyString, pickDefined, requiredFieldError, } from './model-proxy-fields.js';
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (model-proxy/${context.provider}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (model-proxy/${context.provider}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 const TOOLS_CHECK = ['tools', isArray, 'tools must be an array when provided'];
 const SYSTEM_CHECK = ['system', isString, 'system must be a string when provided'];
@@ -382,7 +384,7 @@ function reportCatchAllError(providerParam, onInternalError, error) {
     }
     else {
         // eslint-disable-next-line no-console
-        console.error(`[@jini-ai/http-kit] internal error (model-proxy/${providerParam || 'unknown'}, correlationId=${correlationId})`, error);
+        console.error(`[@jini-ai/http-kit] internal error (model-proxy/${providerParam || 'unknown'}, correlationId=${correlationId})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
     }
     return correlationId;
 }

package/dist/http/remote-run-events.js

@@ -22,6 +22,8 @@
  * would also present, and this route grants direct run-event-injection, a materially different
  * capability from what the general API token was designed to gate.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { createApiError, isTerminalRunState } from '@jini-ai/protocol';
 import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
@@ -31,7 +33,7 @@ import { sendApiError, statusForError } from '@jini-ai/http-kit';
 import { err, ok } from '@jini-ai/http-kit';
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (remote-run-events/${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (remote-run-events/${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 const DEFAULT_TOKEN_ENV_VAR = 'JINI_REMOTE_TOOL_BRIDGE_TOKEN';
 /**

package/dist/http/research.js

@@ -1,4 +1,3 @@
-import { redactSecrets } from '@jini-ai/core';
 /**
  * @module research
  *
@@ -95,6 +94,8 @@ import { redactSecrets } from '@jini-ai/core';
  * token out of any upstream error text before it is even logged, belt-and-braces alongside the
  * generic-message substitution.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { createTavilyResearchProvider } from './research-tavily.adapter.js';
 import { createApiError } from '@jini-ai/protocol';
@@ -103,7 +104,7 @@ import { defineJsonRoute, err, mountJsonRoute, ok, validationError } from '@jini
 const MAX_QUERY_LENGTH = 1000;
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (research/search, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (research/search, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /**
  * Default `ResearchHttpDeps.resolveCredentials`: reads `TAVILY_API_KEY` from the environment.

package/dist/http/runs.js

@@ -3,13 +3,15 @@
  * agent, tool, or product vocabulary: a host optionally supplies `onStarted`
  * to attach its chosen driver after the lifecycle has durably recorded start.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
 import { createSseChannel, defineJsonRoute, err, mountJsonRoute, ok, requestedAfterCursor, sendApiError, sendRawApiError, validationError, } from '@jini-ai/http-kit';
 /** Default sink when a host does not supply `onInternalError`: still observable, never silent. */
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /**
  * Logs the real failure server-side and returns the generic, correlation-id-bearing public error

package/dist/http/surface-restoration.d.ts

@@ -0,0 +1,17 @@
+import type { Response } from 'express';
+import type { SurfaceExchangeStore } from '@jini-ai/core';
+/** Stream a restored card through the existing authenticated callback route. Only the exchange
+ * handle is accepted: tool identity, principal and original arguments come from the shared store.
+ * Returns false without writing a response when another process may own the exchange.
+ * @complexity O(emitted bytes); no answer or credential is retained by this adapter.
+ */
+export declare function tryRestoreSurface({ res, store, exchangeId, principalId, toolId }: {
+    res: Response;
+    store: SurfaceExchangeStore;
+    exchangeId: string;
+    principalId: string;
+    toolId: string;
+}, { params }?: {
+    params?: Record<string, unknown>;
+}): Promise<boolean>;
+//# sourceMappingURL=surface-restoration.d.ts.map

package/dist/http/surface-restoration.js

@@ -0,0 +1,50 @@
+/** Stream a restored card through the existing authenticated callback route. Only the exchange
+ * handle is accepted: tool identity, principal and original arguments come from the shared store.
+ * Returns false without writing a response when another process may own the exchange.
+ * @complexity O(emitted bytes); no answer or credential is retained by this adapter.
+ */
+export async function tryRestoreSurface({ res, store, exchangeId, principalId, toolId }, { params } = {}) {
+    if (!store.restore)
+        return false;
+    const controller = new AbortController();
+    const onClose = () => { if (!res.writableFinished)
+        controller.abort(); };
+    res.on('close', onClose);
+    const write = (value) => {
+        if (res.destroyed)
+            return;
+        if (!res.headersSent)
+            res.status(200).set({ 'content-type': 'application/x-ndjson', 'cache-control': 'no-store' });
+        res.write(`${JSON.stringify(value)}\n`);
+    };
+    // The first card frame opens the response. Subsequent heartbeats keep Node fetch's idle-body
+    // limit from expiring a legitimate human wait at the proxy hop.
+    const heartbeat = setInterval(() => { if (res.headersSent)
+        write({ type: 'keepalive' }); }, 15_000);
+    heartbeat.unref();
+    try {
+        const result = await store.restore({ exchangeId, principalId, emit: async (emission) => {
+                write({ type: 'surface', emission });
+            } }, { toolId, signal: controller.signal, ...(params === undefined ? {} : { params }) });
+        if (!result.ok && result.reason === 'unknown-or-closed' && !res.headersSent)
+            return false;
+        if (!result.ok && !res.headersSent) {
+            res.status(409).json({ code: 'SURFACE_NOT_PENDING', reason: result.reason });
+            return true;
+        }
+        write({ type: 'restored', ...result });
+        res.end();
+        return true;
+    }
+    catch {
+        // Failure messages may contain host or credential details. Restoration never reports them.
+        write({ type: 'restored', ok: false });
+        res.end();
+        return true;
+    }
+    finally {
+        clearInterval(heartbeat);
+        res.off('close', onClose);
+    }
+}
+//# sourceMappingURL=surface-restoration.js.map

package/dist/http/terminals.js

@@ -25,6 +25,8 @@
  * - Adapts `deps.manager.attach`'s push/end sink to `sse.ts`'s generic SSE
  *   channel, the same way `runs.ts` adapts `RunLifecycle.stream`.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { TERMINAL_CREATE_TOOL_ID } from '../index.js';
 import { createApiError } from '@jini-ai/protocol';
@@ -38,7 +40,7 @@ import { isRecord, readOptionalNonEmptyString, readOptionalNumber, resolveResour
 import { err, ok } from '@jini-ai/http-kit';
 function defaultTerminalsInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /** Every one-off `terminal.create` tool call gets its own opaque `RunRef` — matching `db-ops.ts`'s `freshRun()`: these are single requests, not steps of a longer-lived agent run. */
 function freshRun() {

package/dist/http/tool-catalog.d.ts

@@ -36,6 +36,20 @@ export interface ToolCatalogEntry {
     readonly description: string;
     readonly inputSchema?: unknown;
     readonly source: string;
+    /**
+     * Set only on guidance entries that are not tools themselves (a retired-alias pointer, a
+     * namespace overview): every tool id the guidance points at. A read-only view shows guidance
+     * only when each target is a registered read-only tool, and hides guidance without targets.
+     */
+    readonly targetToolIds?: readonly string[];
+}
+/** Optional describe inputs. */
+export interface ToolCatalogDescribeOptions {
+    /**
+     * When set, the caller may use only these tool ids; guidance that lists tools (a namespace
+     * overview) should list only these. Never consulted for a registered tool's own entry.
+     */
+    readonly visibleToolIds?: ReadonlySet<string>;
 }
 /** Structurally identical to `@jini-ai/sqlite-chat`'s `searchToolCatalog`/`getToolCatalogEntry` — defined locally so this package incurs no `better-sqlite3` dependency. */
 export interface ToolCatalogQuery {
@@ -46,7 +60,7 @@ export interface ToolCatalogQuery {
     }) => readonly ToolCatalogSearchHit[];
     readonly describe: ({ id }: {
         readonly id: string;
-    }, _optional?: Record<string, never>) => ToolCatalogEntry | null;
+    }, optional?: ToolCatalogDescribeOptions) => ToolCatalogEntry | null;
 }
 export interface ToolCatalogHttpDeps {
     readonly catalog: ToolCatalogQuery;

package/dist/http/tool-execution-routes.d.ts

@@ -57,6 +57,8 @@ export interface ToolExecutionRoutesOptional {
     /** Defaults to {@link DEFAULT_TOOL_EXEC_MAX_BODY_BYTES}. */
     readonly maxBodyBytes?: number;
     readonly runWithContext?: RunWithToolContext;
+    /** Host-owned live-run/identity gate, after parsing and before either route dispatches. */
+    readonly authorizeRun?: RequestHandler;
 }
 /** The token + loopback gate; mounted before any body parser. Exported for hosts that need it on another path. */
 export declare function requireToolExecutionCaller(_required: Record<string, never>, { tokenEnvVar, env }?: Pick<ToolExecutionRoutesOptional, 'tokenEnvVar' | 'env'>): RequestHandler;
@@ -65,5 +67,5 @@ export declare function requireToolExecutionCaller(_required: Record<string, nev
  * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
  * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
  */
-export declare function registerToolExecutionRoutes({ app, executor, listToolsFor }: ToolExecutionRoutesRequired, { tokenEnvVar, env, maxBodyBytes, runWithContext }?: ToolExecutionRoutesOptional): void;
+export declare function registerToolExecutionRoutes({ app, executor, listToolsFor }: ToolExecutionRoutesRequired, { tokenEnvVar, env, maxBodyBytes, runWithContext, authorizeRun }?: ToolExecutionRoutesOptional): void;
 //# sourceMappingURL=tool-execution-routes.d.ts.map

package/dist/http/tool-execution-routes.js

@@ -172,10 +172,11 @@ function catalogHandler({ listToolsFor }) {
  * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
  * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
  */
-export function registerToolExecutionRoutes({ app, executor, listToolsFor }, { tokenEnvVar, env, maxBodyBytes = DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, runWithContext } = {}) {
+export function registerToolExecutionRoutes({ app, executor, listToolsFor }, { tokenEnvVar, env, maxBodyBytes = DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, runWithContext, authorizeRun } = {}) {
     const gate = requireToolExecutionCaller({}, { ...(tokenEnvVar === undefined ? {} : { tokenEnvVar }), ...(env === undefined ? {} : { env }) });
     const parser = express.json({ limit: maxBodyBytes });
-    app.post(TOOL_EXECUTIONS_ROUTE_PATH, gate, parser, executionHandler({ executor }, runWithContext === undefined ? {} : { runWithContext }), bodyParserFailure);
-    app.get(TOOL_CATALOG_ROUTE_PATH, gate, catalogHandler({ listToolsFor }));
+    const runGate = authorizeRun ? [authorizeRun] : [];
+    app.post(TOOL_EXECUTIONS_ROUTE_PATH, gate, parser, ...runGate, executionHandler({ executor }, runWithContext === undefined ? {} : { runWithContext }), bodyParserFailure);
+    app.get(TOOL_CATALOG_ROUTE_PATH, gate, ...runGate, catalogHandler({ listToolsFor }));
 }
 //# sourceMappingURL=tool-execution-routes.js.map

package/dist/http/xai.js

@@ -1,4 +1,3 @@
-import { redactSecrets } from '@jini-ai/core';
 /**
  * @module xai
  *
@@ -117,6 +116,8 @@ import { redactSecrets } from '@jini-ai/core';
  *    `@jini-ai/agent-runtime`'s already-shipped generic module, outside this file's own scope to alter
  *    without special-casing one provider's capitalization inside otherwise-generic code.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { beginOAuthPkce, clearStoredOAuthToken, completeOAuthPkce, getStoredOAuthToken, PendingAuthCache, resolveOAuthBearer, setStoredOAuthToken, startOAuthCallbackListener, validateBaseUrl, XAI_OAUTH_PROVIDER_CONFIG, XAI_OAUTH_REDIRECT_HOST, XAI_OAUTH_REDIRECT_PATH, XAI_OAUTH_REDIRECT_PORT, } from '@jini-ai/agent-runtime';
 import { createApiError } from '@jini-ai/protocol';
@@ -137,7 +138,7 @@ const DEFAULT_SEARCH_MODEL = 'grok-4.20-reasoning';
 const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (xai/${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (xai/${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /** Resolves every optional `XaiHttpDeps` field to a concrete value. Idempotent — calling this again on an already-resolved object (e.g. `registerXaiRoutes`'s own single resolution, passed through to each route's `handle`) is a harmless pass-through. See module doc on why stateful fields (`pending`/`listenerRef`) must be resolved once per registration, not once per request. */
 function resolveXaiHttpDeps(deps) {

package/dist/idle-monitor.d.ts

@@ -0,0 +1,29 @@
+import type { Clock } from '@jini-ai/core/primitives';
+import type { SchedulerPort } from './scheduler.js';
+/** A one-shot observation lifecycle; stopping permanently cancels further observations. */
+export interface IdleMonitor {
+    /** Idempotent; callbacks queued before cancellation become harmless. */
+    stop(): void;
+    /** Hold busy state through asynchronous work. Null means intake is fenced; releases are idempotent. */
+    acquire(required: Record<string, never>, optional?: Record<string, never>): (() => void) | null;
+}
+/**
+ * Observe host busy state immediately, scheduling polls at most 1s ahead; fire once after a full
+ * observed idle interval. Busy observations discard idle credit; the next idle
+ * observation starts a new interval. acquire() also records activity between observations.
+ * @param input Injected synchronous busy predicate, finite positive idleMs, clock and scheduler.
+ * @param options onIdle runs synchronously after the monitor has stopped; its errors propagate.
+ * @returns A permanent, idempotent stop handle. Owns at most one scheduled callback.
+ * @throws RangeError for a non-positive or non-finite idleMs, before scheduling.
+ * @complexity O(1) time per observation and O(1) retained space.
+ * @example createIdleMonitor({ isBusy, idleMs: 900_000, clock, scheduler }, { onIdle });
+ */
+export declare function createIdleMonitor({ isBusy, idleMs, clock, scheduler }: {
+    readonly isBusy: () => boolean;
+    readonly idleMs: number;
+    readonly clock: Clock;
+    readonly scheduler: SchedulerPort;
+}, { onIdle }: {
+    readonly onIdle: () => void;
+}): IdleMonitor;
+//# sourceMappingURL=idle-monitor.d.ts.map

package/dist/idle-monitor.js

@@ -0,0 +1,64 @@
+/**
+ * Observe host busy state immediately, scheduling polls at most 1s ahead; fire once after a full
+ * observed idle interval. Busy observations discard idle credit; the next idle
+ * observation starts a new interval. acquire() also records activity between observations.
+ * @param input Injected synchronous busy predicate, finite positive idleMs, clock and scheduler.
+ * @param options onIdle runs synchronously after the monitor has stopped; its errors propagate.
+ * @returns A permanent, idempotent stop handle. Owns at most one scheduled callback.
+ * @throws RangeError for a non-positive or non-finite idleMs, before scheduling.
+ * @complexity O(1) time per observation and O(1) retained space.
+ * @example createIdleMonitor({ isBusy, idleMs: 900_000, clock, scheduler }, { onIdle });
+ */
+export function createIdleMonitor({ isBusy, idleMs, clock, scheduler }, { onIdle }) {
+    if (!Number.isFinite(idleMs) || idleMs <= 0) {
+        throw new RangeError('idleMs must be finite and positive');
+    }
+    let stopped = false;
+    let active = 0;
+    let idleSince;
+    let cancelPending;
+    const stop = () => {
+        stopped = true;
+        cancelPending?.();
+        cancelPending = undefined;
+    };
+    // The host owns parking; this callback only observes state and reports idle.
+    const observe = () => {
+        if (stopped)
+            return;
+        const now = clock.nowMs();
+        if (active > 0 || isBusy())
+            idleSince = undefined;
+        else
+            idleSince ??= now;
+        const remainingMs = idleSince === undefined ? idleMs : idleMs - (now - idleSince);
+        if (remainingMs <= 0) {
+            stop();
+            onIdle();
+            return;
+        }
+        cancelPending = scheduler.schedule({ delayMs: Math.min(1_000, remainingMs), callback: observe });
+    };
+    observe();
+    return {
+        stop,
+        acquire(_required, _optional = {}) {
+            if (stopped)
+                return null;
+            active++;
+            idleSince = undefined;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                active--;
+                // A sub-poll request is still activity. Start its idle credit at completion, not at
+                // the previous observation, so frequent short calls cannot trigger a premature park.
+                if (active === 0)
+                    idleSince = clock.nowMs();
+            };
+        },
+    };
+}
+//# sourceMappingURL=idle-monitor.js.map

package/dist/image-prompt-delivery.d.ts

@@ -22,7 +22,7 @@ export interface ImagePromptDelivery {
 export declare function augmentPromptWithImageAttachments({ prompt, imagePaths }: {
     readonly prompt: string;
     readonly imagePaths: readonly string[];
-}): string;
+}, _optional?: Record<string, never>): string;
 /**
  * Directories a 'prompt-path' def's CLI must be allowed to read from so it
  * can actually open the files the augmented prompt just told it about — the

package/dist/image-prompt-delivery.js

@@ -45,13 +45,14 @@ import path from 'node:path';
  * @complexity O(n) in the number of images — one line rendered per path, no I/O.
  * @overallScore 100
  */
-export function augmentPromptWithImageAttachments({ prompt, imagePaths }) {
+export function augmentPromptWithImageAttachments({ prompt, imagePaths }, _optional = {}) {
     const list = imagePaths.map((imagePath, index) => `${index + 1}. ${imagePath}`).join('\n');
     const plural = imagePaths.length === 1;
     return (`${prompt}\n\n---\n` +
         `The user attached the following image ${plural ? 'file' : 'files'} to this message. ` +
-        `${plural ? 'It is a' : 'These are'} real file${plural ? '' : 's'} on disk — read ${plural ? 'it' : 'each one'} directly ` +
-        `(e.g. with your file-reading tool) before responding:\n${list}`);
+        `${plural ? 'It is a' : 'These are'} real file${plural ? '' : 's'} on disk — read ${plural ? 'it' : 'each one'} ` +
+        `with the host attachment/image tool first, or your native Read/image tool for this supplied path. ` +
+        `Never use Bash, a shell command or a script to inspect attachments:\n${list}`);
 }
 /**
  * Directories a 'prompt-path' def's CLI must be allowed to read from so it

package/dist/index.d.ts

@@ -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';