@jini-ai/daemon 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.6.8 — 2026-10-16
+
+- An unknown tool on the read-only gateway points to discovery, never a mutation 409 (75d37c32).
+
+## 0.6.7 — 2026-10-15
+
+- An unknown tool id is a `400 BAD_REQUEST`, not a redacted `500 INTERNAL_ERROR` (b4a3abad): `ToolExecutor` throws `ToolInputError` naming up to eight registered ids the unknown id prefixes (e.g. `content_read` → `content_read.menu`), and the delegated-tools route returns that message.
+
 ## 0.6.6 — 2026-10-14
 
 - A failed jini MCP bridge now says why (8bc0f07d): the run still stops at once, but a disposable credential-free copy of the bridge is spawned, sent MCP `initialize`, and its exit code + stderr tail (e.g. `ERR_MODULE_NOT_FOUND`) go into the `MCP_BRIDGE_UNAVAILABLE` message and `error.details`, emitted before the run's end event. `probeMcpBridge` is exported so hosts can run the same check at boot; `mcpJsonInjection.probeOnFailure: false` opts out. The baseline agent env moves to `agent-env.ts` so probe and launch share one allowlist.

package/dist/core/read-only-tools.d.ts

@@ -25,8 +25,8 @@ export interface ReadOnlyConstrainedPrincipal extends Principal {
     readonly toolAccess: 'read-only';
 }
 /**
- * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
- * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
+ * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes both
+ * refuse unsafe dispatch; unknown ids direct discovery because an unrestricted retry cannot run them.
  * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
  */
 export declare const defaultDaemonMessages: {
@@ -35,6 +35,10 @@ export declare const defaultDaemonMessages: {
         toolRefusalMessage: ({ toolId }: {
             toolId: string;
         }) => string;
+        unknownToolMessage: ({ toolId, candidates }: {
+            toolId: string;
+            candidates: readonly string[];
+        }) => string;
     };
 };
 /** Required host wording; absent metadata is always a refusal. */
@@ -43,6 +47,10 @@ export interface ReadOnlyToolMessages {
     toolRefusalMessage(required: {
         toolId: string;
     }): string;
+    unknownToolMessage(required: {
+        toolId: string;
+        candidates: readonly string[];
+    }): string;
 }
 export interface ReadOnlyToolCheckRequired {
     readonly toolId: string;
@@ -63,7 +71,7 @@ export declare function constrainPrincipalToReadOnlyTools({ principal }: {
 export declare function principalIsReadOnlyConstrained({ principal }: {
     principal: Principal;
 }, _optional?: Record<string, never>): boolean;
-/** @returns Required host wording for an unknown or non-read-only tool. */
+/** @returns Required host wording for a registered non-read-only tool. */
 export declare function readOnlyToolRefusalMessage({ toolId, messages }: {
     toolId: string;
     messages: ReadOnlyToolMessages;

package/dist/core/read-only-tools.js

@@ -1,13 +1,15 @@
 import { isReadOnlyTool } from '@jini-ai/core';
+import { toolCandidates } from './tool-candidates.js';
 /**
- * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
- * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
+ * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes both
+ * refuse unsafe dispatch; unknown ids direct discovery because an unrestricted retry cannot run them.
  * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
  */
 export const defaultDaemonMessages = {
     readOnly: {
         unverifiableMessage: 'this host cannot verify read-only tools — POST /api/delegated-tool-calls was mounted without DelegatedToolsHttpDeps.toolRegistry, so a requireReadOnly call cannot be checked and is refused',
         toolRefusalMessage: ({ toolId }) => `tool "${toolId}" is not registered as read-only — this gateway executes only tools whose registration declares readOnly; call it through execute_delegated_tool instead`,
+        unknownToolMessage: ({ toolId, candidates }) => `no tool "${toolId}" is registered; use search_tools${candidates.length > 0 ? ` — did you mean ${candidates.join(', ')}?` : ''}`,
     },
 };
 /** @returns A copied, attenuated principal; its roles are unchanged. */
@@ -20,7 +22,7 @@ export function constrainPrincipalToReadOnlyTools({ principal }, _optional = {})
 export function principalIsReadOnlyConstrained({ principal }, _optional = {}) {
     return 'toolAccess' in principal && principal.toolAccess === 'read-only';
 }
-/** @returns Required host wording for an unknown or non-read-only tool. */
+/** @returns Required host wording for a registered non-read-only tool. */
 export function readOnlyToolRefusalMessage({ toolId, messages }, _optional = {}) {
     return messages.toolRefusalMessage({ toolId });
 }
@@ -34,7 +36,10 @@ export function readOnlyToolRefusalMessage({ toolId, messages }, _optional = {})
 export function checkReadOnlyTool({ toolId, registry, messages }, _optional = {}) {
     if (registry === undefined)
         return messages.unverifiableMessage;
-    const descriptor = registry.list({}).find((candidate) => candidate.id === toolId);
+    const tools = registry.list({});
+    const descriptor = tools.find((candidate) => candidate.id === toolId);
+    if (!descriptor)
+        return messages.unknownToolMessage({ toolId, candidates: toolCandidates({ toolId, tools }) });
     if (isReadOnlyTool({ descriptor }))
         return null;
     return readOnlyToolRefusalMessage({ toolId, messages });

package/dist/core/tool-candidates.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDescriptor } from '@jini-ai/core';
+/** Registered prefix matches for unknown-tool diagnostics, in catalog order, capped at eight.
+ * @complexity O(n) time and space over n registered tools. */
+export declare function toolCandidates({ toolId, tools }: {
+    toolId: string;
+    tools: readonly Pick<ToolDescriptor, 'id'>[];
+}, _optional?: Record<string, never>): string[];
+//# sourceMappingURL=tool-candidates.d.ts.map

package/dist/core/tool-candidates.js

@@ -0,0 +1,6 @@
+/** Registered prefix matches for unknown-tool diagnostics, in catalog order, capped at eight.
+ * @complexity O(n) time and space over n registered tools. */
+export function toolCandidates({ toolId, tools }, _optional = {}) {
+    return tools.map((tool) => tool.id).filter((id) => id.startsWith(toolId)).slice(0, 8);
+}
+//# sourceMappingURL=tool-candidates.js.map

package/dist/delegated-tool-bridge.d.ts

@@ -33,8 +33,8 @@ export interface DelegatedToolInvocation {
 export interface DelegatedToolBridge {
     /**
      * Emits a canonical `tool_use`, executes through `ToolExecutor`, then emits
-     * exactly one matching `tool_result`. Unknown tool ids remain programmer or
-     * routing errors from `ToolExecutor` and are rethrown after their error
+     * exactly one matching `tool_result`. Unknown tool ids are input errors
+     * from `ToolExecutor` and are rethrown after their error
      * result is recorded.
      */
     execute(requiredArgs: Pick<DelegatedToolInvocation, "runId" | "toolUseId" | "toolId" | "principal" | "input">, optionalArgs?: Pick<DelegatedToolInvocation, "signal">): Promise<ToolExecutionResult>;

package/dist/http/delegated-tools.d.ts

@@ -1,5 +1,5 @@
 import type { Express } from 'express';
-import type { Principal, ToolRegistry } from '@jini-ai/core';
+import { type Principal, type ToolRegistry } from '@jini-ai/core';
 import { type RunLifecycle, type ToolExecutionResult, type ToolExecutor } from '../index.js';
 import { type AdapterContext } from '@jini-ai/http-kit';
 export interface DelegatedToolExecuteRequest {
@@ -81,7 +81,7 @@ export interface DelegatedToolsHttpDeps {
     /**
      * Host opt-in: the model-safe text to send in place of `'an internal error occurred'` for every
      * failure this route would otherwise answer with the SEC-005-redacted `500 INTERNAL_ERROR` — a
-     * thrown executor (e.g. an unknown tool id), a throwing `resolvePrincipal`, `timed-out`,
+     * thrown executor infrastructure failure, a throwing `resolvePrincipal`, `timed-out`,
      * `cancelled`, and a `failed` result `isModelSafeToolFailure` did not vouch for. Without it, those
      * reach the model as a bare "INTERNAL_ERROR" it can neither act on nor report.
      *
@@ -98,8 +98,8 @@ export interface DelegatedToolsHttpDeps {
  * `POST /api/delegated-tool-calls` — executes one delegated tool call against an already-started
  * run. Maps `ToolExecutionResult.status` to the HTTP response via `toolExecutionResultToApiResult`
  * above — mirroring `db-ops.ts`'s precedent for the identical status union rather than treating
- * every business outcome as a `200`. A genuinely unexpected throw (an unregistered `toolId` — a
- * routing/programming error per `ToolExecutor.execute`'s own contract — or a race where the run
+ * every business outcome as a `200`. An unregistered `toolId` throws `ToolInputError` and answers
+ * `400 BAD_REQUEST`. A genuinely unexpected throw (such as a race where the run
  * became terminal between this route's existence check and the bridge's first emitted event)
  * reaches the same SEC-005 redaction path.
  */

package/dist/http/delegated-tools.js

@@ -27,6 +27,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
+import { ToolInputError } from '@jini-ai/core';
 import { createDelegatedToolBridge } from '../index.js';
 import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
 import { validationError } from '@jini-ai/http-kit';
@@ -159,8 +160,8 @@ function toolExecutionResultToApiResult(deps, runId, toolId, result) {
  * `POST /api/delegated-tool-calls` — executes one delegated tool call against an already-started
  * run. Maps `ToolExecutionResult.status` to the HTTP response via `toolExecutionResultToApiResult`
  * above — mirroring `db-ops.ts`'s precedent for the identical status union rather than treating
- * every business outcome as a `200`. A genuinely unexpected throw (an unregistered `toolId` — a
- * routing/programming error per `ToolExecutor.execute`'s own contract — or a race where the run
+ * every business outcome as a `200`. An unregistered `toolId` throws `ToolInputError` and answers
+ * `400 BAD_REQUEST`. A genuinely unexpected throw (such as a race where the run
  * became terminal between this route's existence check and the bridge's first emitted event)
  * reaches the same SEC-005 redaction path.
  */
@@ -219,6 +220,9 @@ export const delegatedToolExecuteRoute = defineJsonRoute({
             return toolExecutionResultToApiResult(deps, input.runId, input.toolId, result);
         }
         catch (error) {
+            if (error instanceof ToolInputError) {
+                return err({ error: createApiError({ code: 'BAD_REQUEST', message: error.message }) });
+            }
             return err({ error: reportInternalError(deps, 'delegated-tool-execute', error, input.runId, input.toolId) });
         }
     }

package/dist/tool-executor.d.ts

@@ -83,7 +83,7 @@ export interface ToolExecutor {
      * @param emitSurface - Transport-supplied seam letting the handler push a human-only surface into
      * the run's event stream *before* this call settles. Omit for a caller with no run event stream;
      * see `@jini-ai/core`'s `SurfaceEmitter` for why a handler that waits on a human needs it.
-     * @throws If `toolId` isn't registered — a routing/programming error, distinct from the denial/confirmation-denial states `ToolExecutionResult.status` covers.
+     * @throws {ToolInputError} If `toolId` isn't registered, with up to eight registered prefix matches.
      */
     execute(args: {
         readonly principal: Principal;
@@ -125,7 +125,7 @@ export interface CreateToolExecutorOptions {
  * — the one and only caller of that internal export.
  * @param options.delegate - Transport-supplied authorize/confirm UI seam;
  * omit for a headless caller whose tools never need interactive gating.
- * @complexity `execute` is O(1) plus the handler's own cost; `resumeConfirmation`/`cancel`/`getAuditRecord` are O(1) map lookups.
+ * @complexity Known-id `execute` is O(1) plus the handler's own cost; unknown ids scan O(n) descriptors for hints. `resumeConfirmation`/`cancel`/`getAuditRecord` are O(1) map lookups.
  * @overallScore 100/100
  */
 export declare function createToolExecutor(requiredArgs: Pick<CreateToolExecutorOptions, "registry">, optionalArgs?: Pick<CreateToolExecutorOptions, "delegate" | "now">): ToolExecutor;

package/dist/tool-executor.js

@@ -48,6 +48,7 @@
 import { randomUUID } from 'node:crypto';
 import { ToolInputError, } from '@jini-ai/core';
 import { authorizeToolInvocation } from '@jini-ai/core/composition';
+import { toolCandidates } from './core/tool-candidates.js';
 /**
  * Enforces `maxOutputBytes` in BYTES, which is what the option is named for.
  *
@@ -81,7 +82,7 @@ function truncateOutput(output, maxOutputBytes) {
  * — the one and only caller of that internal export.
  * @param options.delegate - Transport-supplied authorize/confirm UI seam;
  * omit for a headless caller whose tools never need interactive gating.
- * @complexity `execute` is O(1) plus the handler's own cost; `resumeConfirmation`/`cancel`/`getAuditRecord` are O(1) map lookups.
+ * @complexity Known-id `execute` is O(1) plus the handler's own cost; unknown ids scan O(n) descriptors for hints. `resumeConfirmation`/`cancel`/`getAuditRecord` are O(1) map lookups.
  * @overallScore 100/100
  */
 export function createToolExecutor(requiredArgs, optionalArgs = {}) {
@@ -182,7 +183,9 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         // existence, never returns a handler, so this doesn't reopen the leak authorizeToolInvocation
         // closed — that gate still runs, still unconditionally, inside the call below.
         if (!registry.has({ toolId })) {
-            throw new Error(`ToolExecutor: unknown tool "${toolId}"`);
+            const candidates = toolCandidates({ toolId, tools: registry.list({}) });
+            const hint = candidates.length > 0 ? `; did you mean ${candidates.join(', ')}?` : '';
+            throw new ToolInputError({ message: `ToolExecutor: unknown tool "${toolId}"${hint}` });
         }
         const executionId = openAudit(principal, run, toolId);
         // Observes `signal` for this execution's ENTIRE remaining lifetime, not just the handler-run
@@ -216,7 +219,7 @@ export function createToolExecutor(requiredArgs, optionalArgs = {}) {
         // Recorded terminal and returned as `failed` with a fixed message. `failed` is the right state:
         // this execution ended, and it ended for an operational reason rather than a decision. The real
         // exception stays server-side. Deliberately narrower than the `unknown tool` throw above, which
-        // stays a throw because it is a routing/programming error, not an execution outcome.
+        // stays a typed input-error throw because no tool execution exists to settle.
         let resolved;
         try {
             resolved = await authorize(principal, run, toolId, input);

package/dist/tool-recovery/federated-refusal.js

@@ -1,8 +1,8 @@
 // Local federation forks moved to @jini-ai/mcp/federation (+ /stdio, /approvals); see development/DELETED-CODE.md.
 /**
  * `ToolExecutor.execute`'s own contract for an unregistered id (`@jini-ai/daemon`'s
- * `tool-executor.ts`): a thrown `Error` reading `unknown tool "<id>"`, with no code or subclass to
- * match on instead. Duplicated from `tool-executor-audit.ts`'s identical `isUnknownToolError` rather
+ * `tool-executor.ts`): a thrown `ToolInputError` (from `@jini-ai/core`) reading `unknown tool "<id>"`.
+ * This still matches on the message text, not the class. Duplicated from `tool-executor-audit.ts`'s identical `isUnknownToolError` rather
  * than imported: that file is a sibling one layer up with no dependency on `mcp-federation`, and
  * importing across that line for an 18-character regex is not worth the coupling. Both copies carry
  * the same MEDIUM message-text-coupling note that file's own doc records — if `@jini-ai/daemon`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/daemon",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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": {
@@ -139,17 +139,17 @@
     "@types/pg": "8.23.1",
     "express": "^4.21.0",
     "@types/express": "^4.17.21",
-    "@jini-ai/db": "0.3.4",
+    "@jini-ai/db": "0.3.5",
     "@jini-ai/http-kit": "0.4.2",
-    "@jini-ai/platform": "^0.5.7",
-    "@jini-ai/core": "^0.4.6",
     "@jini-ai/agent-runtime": "^0.4.11",
-    "@jini-ai/chat": "0.6.3",
+    "@jini-ai/chat": "0.6.6",
+    "@jini-ai/platform": "^0.5.9",
+    "@jini-ai/core": "^0.4.7",
     "@jini-ai/protocol": "^0.4.4"
   },
   "dependencies": {
-    "@jini-ai/protocol": "^0.4.4",
-    "@jini-ai/core": "^0.4.6"
+    "@jini-ai/core": "^0.4.7",
+    "@jini-ai/protocol": "^0.4.4"
   },
   "peerDependencies": {
     "node-pty": "^1.1.0",