@jini-ai/daemon 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
+
 ## 0.6.5 — 2026-10-14
 
 - Express 5 accepted: the optional `express` peer is now `^4.21.0 || ^5.0.0` (1442d875), so an Express 5 host no longer hits ERESOLVE.

package/dist/agent-executor/agent-env.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Deny-by-default agent subprocess environment: `BASELINE_AGENT_ENV_KEYS` resolved from
+ * `hostEnv`, plus this run's explicitly-delegated credential(s) — never a passthrough of
+ * `hostEnv` itself. Run launch reaches this when the caller omits `AgentExecutorRunInput.env`;
+ * supplying `env` bypasses this function for that launch (see its call site). Diagnostic bridge
+ * probes reuse this same baseline without adding delegated credentials.
+ */
+export declare function buildAgentEnv({ hostEnv }: {
+    hostEnv: NodeJS.ProcessEnv;
+}, { credentialEnv }?: {
+    credentialEnv?: Record<string, string> | undefined;
+}): Record<string, string>;
+//# sourceMappingURL=agent-env.d.ts.map

package/dist/agent-executor/agent-env.js

@@ -0,0 +1,39 @@
+/**
+ * Fixed baseline of host environment variables every spawned agent subprocess may see by
+ * default — resolved from the host's env one name at a time, never derived programmatically
+ * from `process.env` as a bag, so this can't silently widen. SEC-001's deny-by-default fix; see
+ * `AgentExecutorRunInput.env`'s doc for the full threat model.
+ */
+const BASELINE_AGENT_ENV_KEYS = [
+    'PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP', 'SHELL',
+    'LANG', 'LC_ALL', 'LC_CTYPE',
+    // `USER` is required for a spawned `claude` CLI to find its own login/credential state — with
+    // it omitted (even though `HOME` is present), `claude` fails fast with "Not logged in · Please
+    // run /login" despite real credentials existing on disk/keychain. Confirmed by bisection against
+    // a real authenticated `claude` install: `BASELINE_AGENT_ENV_KEYS` alone fails, adding back every
+    // `CLAUDE_CODE_*`/`CLAUDECODE` var still fails, `LOGNAME`/`SSH_AUTH_SOCK` alone still fail, but
+    // `USER` alone flips it to success. Login lookup requires the user identity
+    // as well as the home directory.
+    'USER',
+    'SystemRoot', 'windir', 'ComSpec', 'PATHEXT', // Windows-only; harmless no-ops elsewhere
+];
+/**
+ * Deny-by-default agent subprocess environment: `BASELINE_AGENT_ENV_KEYS` resolved from
+ * `hostEnv`, plus this run's explicitly-delegated credential(s) — never a passthrough of
+ * `hostEnv` itself. Run launch reaches this when the caller omits `AgentExecutorRunInput.env`;
+ * supplying `env` bypasses this function for that launch (see its call site). Diagnostic bridge
+ * probes reuse this same baseline without adding delegated credentials.
+ */
+export function buildAgentEnv({ hostEnv }, { credentialEnv } = {}) {
+    const result = {};
+    for (const key of BASELINE_AGENT_ENV_KEYS) {
+        const value = hostEnv[key];
+        if (typeof value === 'string')
+            result[key] = value;
+    }
+    for (const [key, value] of Object.entries(credentialEnv ?? {})) {
+        result[key] = value;
+    }
+    return result;
+}
+//# sourceMappingURL=agent-env.js.map

package/dist/agent-executor/contracts.d.ts

@@ -1,4 +1,5 @@
 import type { MessageAttachmentImage } from '../attachment-content.js';
+import type { probeMcpBridge } from './mcp-bridge-probe.js';
 import type { spawn as nodeSpawn, ChildProcess } from 'node:child_process';
 import type { Principal } from '@jini-ai/core';
 import type { RunAgentPayload, RunErrorPayload } from '@jini-ai/protocol';
@@ -312,6 +313,8 @@ export interface ContinuationOptions {
  * interface that defaults to *nothing* rather than a real implementation).
  */
 export interface McpJsonInjectionOptions {
+    /** Probe a reported bridge failure before emitting its error. @default true when injection is configured. */
+    readonly probeOnFailure?: boolean;
     /** Absolute path (or PATH-resolvable name) to the `jini-mcp` bin entry (`packages/mcp/src/bin/serve.ts`) this driver tells the spawned CLI to launch as its own MCP server subprocess. */
     readonly command: string;
     /** Extra argv for `command`. @default [] */
@@ -594,6 +597,8 @@ export interface CreateAgentExecutorOptions {
     readonly createCommandInvocation?: typeof createCommandInvocation;
     /** @default `node:child_process`'s `spawn` */
     readonly spawn?: typeof nodeSpawn;
+    /** Diagnostic bridge probe; independent of the agent spawn seam. @default the real MCP initialize probe. */
+    readonly probeMcpBridge?: typeof probeMcpBridge;
     /** @default the real `@jini-ai/agent-runtime` ACP session transport */
     readonly attachAcpSession?: typeof attachAcpSession;
     /**

package/dist/agent-executor/events.d.ts

@@ -1,3 +1,4 @@
+import type { probeMcpBridge } from './mcp-bridge-probe.js';
 import type { ModelCatalogSnapshot } from '@jini-ai/agent-runtime';
 import type { ChildProcess } from 'node:child_process';
 import { attachAcpSession, attachPiRpcSession, type AcpPermissionHandler, type RuntimeAgentDef } from '@jini-ai/agent-runtime';
@@ -56,6 +57,8 @@ interface WireChildLifecycleContext extends TerminateChildTreeDeps {
      * {@link MCP_BRIDGE_UNAVAILABLE} instead of letting it continue without the host's tools.
      */
     readonly expectsJiniBridge: boolean;
+    readonly bridgeProbeEntry: Parameters<typeof probeMcpBridge>[0]['entry'] | undefined;
+    readonly probeMcpBridge: typeof probeMcpBridge;
 }
 /**
  * Wires one spawned child's full observable lifecycle: raw stdout/stderr

package/dist/agent-executor/events.js

@@ -561,9 +561,25 @@ export function wireChildLifecycle(ctx) {
      */
     function stopForUnavailableBridge(initStatus, bridgeStatus) {
         bridgeUnavailable = true;
-        const message = bridgeUnavailableMessage(bridgeStatus);
         enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: initStatus } }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: { message, error: { code: MCP_BRIDGE_UNAVAILABLE, message } } } }));
+        enqueueEmit(async () => {
+            let probe;
+            if (ctx.bridgeProbeEntry) {
+                try {
+                    probe = await ctx.probeMcpBridge({ entry: ctx.bridgeProbeEntry });
+                }
+                catch {
+                    // A diagnostic failure must not suppress the original bridge error or the terminal event.
+                }
+            }
+            const message = bridgeUnavailableMessage(bridgeStatus, probe);
+            const details = probe ? {
+                exitCode: probe.exitCode, signal: probe.signal, stderrTail: probe.stderrTail, elapsedMs: probe.elapsedMs,
+            } : undefined;
+            await lifecycle.emit({ runId, input: { event: 'error', data: {
+                        message, error: { code: MCP_BRIDGE_UNAVAILABLE, message, ...(details ? { details } : {}) },
+                    } } });
+        });
         void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
     }
     /**

package/dist/agent-executor/index.d.ts

@@ -93,6 +93,7 @@ export { type SupportedStreamFormat, type AgentExecutorCompatibility, type Agent
 export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, selectAgentExecutorHostEnv, resolveLaunch, stagePromptFile, stageLogFile, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, prepareSystemPromptOverlayFileIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, createAgentExecutor, } from './launch.js';
 export { extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, applyAgentTranslationSideEffects, } from './event-translation.js';
 export { MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, resolveMcpBridgeForRun, writeMcpJsonIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, } from './mcp-bridge.js';
+export { probeMcpBridge, type McpBridgeProbeResult } from './mcp-bridge-probe.js';
 export { DEFAULT_BUFFERED_STDOUT_MAX_BYTES, runAcpDispatch, runPiRpcDispatch, } from './events.js';
 export { armHandoffWatcher, } from './handoff.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agent-executor/index.js

@@ -93,6 +93,7 @@ export { AgentExecutorError, } from './contracts.js';
 export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, selectAgentExecutorHostEnv, resolveLaunch, stagePromptFile, stageLogFile, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, prepareSystemPromptOverlayFileIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, createAgentExecutor, } from './launch.js';
 export { extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, applyAgentTranslationSideEffects, } from './event-translation.js';
 export { MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, resolveMcpBridgeForRun, writeMcpJsonIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, } from './mcp-bridge.js';
+export { probeMcpBridge } from './mcp-bridge-probe.js';
 export { DEFAULT_BUFFERED_STDOUT_MAX_BYTES, runAcpDispatch, runPiRpcDispatch, } from './events.js';
 export { armHandoffWatcher, } from './handoff.js';
 //# sourceMappingURL=index.js.map

package/dist/agent-executor/launch.d.ts

@@ -379,6 +379,6 @@ export declare function confirmChildSpawned({ input, deps }: {
  * @complexity `run()`'s own setup is O(1); steady-state cost is the chosen stream parser's.
  * @overallScore 100/100
  */
-export declare function createAgentExecutor(requiredArgs: Pick<CreateAgentExecutorOptions, "lifecycle">, optionalArgs?: Pick<CreateAgentExecutorOptions, "runtimeState" | "codexDisablePlugins" | "piGracefulShutdownMs" | "hostEnv" | "getAgentDef" | "resolveAgentLaunch" | "resolveModelForLaunch" | "ensureAgentCapabilities" | "applyAgentLaunchEnv" | "createCommandInvocation" | "spawn" | "attachAcpSession" | "acpPermissionHandler" | "attachPiRpcSession" | "preparePromptFileForAgent" | "prepareAgentLogFile" | "listProcessSnapshots" | "collectProcessTreePids" | "stopProcesses" | "onCleanupFailure" | "journal" | "continuation" | "classifyFailure" | "mcpJsonInjection" | "claudeConfigDirIsolation" | "claudeConfigDirIsolationEnabled" | "bufferedStdoutMaxBytes" | "promptAugmenter">): AgentExecutor;
+export declare function createAgentExecutor(requiredArgs: Pick<CreateAgentExecutorOptions, "lifecycle">, optionalArgs?: Pick<CreateAgentExecutorOptions, "runtimeState" | "codexDisablePlugins" | "piGracefulShutdownMs" | "hostEnv" | "getAgentDef" | "resolveAgentLaunch" | "resolveModelForLaunch" | "ensureAgentCapabilities" | "applyAgentLaunchEnv" | "createCommandInvocation" | "spawn" | "probeMcpBridge" | "attachAcpSession" | "acpPermissionHandler" | "attachPiRpcSession" | "preparePromptFileForAgent" | "prepareAgentLogFile" | "listProcessSnapshots" | "collectProcessTreePids" | "stopProcesses" | "onCleanupFailure" | "journal" | "continuation" | "classifyFailure" | "mcpJsonInjection" | "claudeConfigDirIsolation" | "claudeConfigDirIsolationEnabled" | "bufferedStdoutMaxBytes" | "promptAugmenter">): AgentExecutor;
 export {};
 //# sourceMappingURL=launch.d.ts.map

package/dist/agent-executor/launch.js

@@ -1,3 +1,5 @@
+import { buildAgentEnv } from './agent-env.js';
+import { probeMcpBridge } from './mcp-bridge-probe.js';
 import { spawn as nodeSpawn, } from 'node:child_process';
 import { promises as fsPromises, } from 'node:fs';
 import { tmpdir, } from 'node:os';
@@ -95,47 +97,10 @@ function toStringEnvRecord(env) {
     }
     return result;
 }
-/**
- * Fixed baseline of host environment variables every spawned agent subprocess may see by
- * default — resolved from the host's env one name at a time, never derived programmatically
- * from `process.env` as a bag, so this can't silently widen. SEC-001's deny-by-default fix; see
- * `AgentExecutorRunInput.env`'s doc for the full threat model.
- */
-const BASELINE_AGENT_ENV_KEYS = [
-    'PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP', 'SHELL',
-    'LANG', 'LC_ALL', 'LC_CTYPE',
-    // `USER` is required for a spawned `claude` CLI to find its own login/credential state — with
-    // it omitted (even though `HOME` is present), `claude` fails fast with "Not logged in · Please
-    // run /login" despite real credentials existing on disk/keychain. Confirmed by bisection against
-    // a real authenticated `claude` install: `BASELINE_AGENT_ENV_KEYS` alone fails, adding back every
-    // `CLAUDE_CODE_*`/`CLAUDECODE` var still fails, `LOGNAME`/`SSH_AUTH_SOCK` alone still fail, but
-    // `USER` alone flips it to success. Login lookup requires the user identity
-    // as well as the home directory.
-    'USER',
-    'SystemRoot', 'windir', 'ComSpec', 'PATHEXT', // Windows-only; harmless no-ops elsewhere
-];
-/**
- * Deny-by-default agent subprocess environment: `BASELINE_AGENT_ENV_KEYS` resolved from
- * `hostEnv`, plus this run's explicitly-delegated credential(s) — never a passthrough of
- * `hostEnv` itself. Only reached when the caller omits `AgentExecutorRunInput.env`; supplying
- * `env` bypasses this function entirely (see its call site).
- */
-function buildAgentEnv(hostEnv, credentialEnv) {
-    const result = {};
-    for (const key of BASELINE_AGENT_ENV_KEYS) {
-        const value = hostEnv[key];
-        if (typeof value === 'string')
-            result[key] = value;
-    }
-    for (const [key, value] of Object.entries(credentialEnv ?? {})) {
-        result[key] = value;
-    }
-    return result;
-}
 /** Snapshot only host configuration used by spawn and config staging; credentials stay per-run.
  * Returns an independent allowlisted record. @complexity O(1), fixed key list. */
 export function selectAgentExecutorHostEnv({ env }, { runtimeState } = {}) {
-    const selected = buildAgentEnv(env, undefined);
+    const selected = buildAgentEnv({ hostEnv: env });
     for (const key of ['CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'VELA_OPENCODE_BIN', 'AGENT_RUNTIME_HOME', 'AGENT_RUNTIME_RESOURCE_ROOT', 'VP_HOME', 'NPM_CONFIG_PREFIX', 'npm_config_prefix', 'APPDATA', 'LOCALAPPDATA', 'MISE_DATA_DIR', 'FNM_DIR']) {
         if (typeof env[key] === 'string')
             selected[key] = env[key];
@@ -239,7 +204,7 @@ export async function resolveImageDeliveryAndArgvBudget({ input, deps }) {
  * Pure.
  */
 export function resolveRunEnv({ input, hostEnv }) {
-    return input.env !== undefined ? toStringEnvRecord(input.env) : buildAgentEnv(hostEnv, input.credentialEnv);
+    return input.env !== undefined ? toStringEnvRecord(input.env) : buildAgentEnv({ hostEnv }, { credentialEnv: input.credentialEnv });
 }
 /** Phase 3b: launch-path resolution + binary-not-resolved guard. */
 export async function resolveLaunch({ input, deps }) {
@@ -979,6 +944,11 @@ export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
                 classifyFailure,
                 bufferedStdoutMaxBytes,
                 expectsJiniBridge: writtenMcpJsonPath !== undefined,
+                // probeMcpBridge itself strips the run credential and swaps in a diagnostic run id.
+                bridgeProbeEntry: mcpBridge?.kind === 'claude-mcp-json' && mcpJsonInjection?.probeOnFailure !== false
+                    ? mcpBridge.serverEntry
+                    : undefined,
+                probeMcpBridge: options.probeMcpBridge ?? probeMcpBridge,
             })
             : null;
         // Registered with the lifecycle wiring above, before the spawn-confirmation await, so a child

package/dist/agent-executor/mcp-bridge-probe.d.ts

@@ -0,0 +1,25 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+export interface McpBridgeProbeResult {
+    readonly ok: boolean;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stderrTail: string;
+    readonly elapsedMs: number;
+}
+/** Initialize a disposable bridge without a run credential; always reap it after the bounded probe.
+ * Spawn/errors/exits/timeouts return diagnostics rather than rejecting. Stderr retains 2000 bytes.
+ * @complexity O(n) in received bytes; stderr storage is bounded independently of child output.
+ */
+export declare function probeMcpBridge({ entry }: {
+    readonly entry: {
+        readonly command: string;
+        readonly args: readonly string[];
+        readonly env?: Readonly<Record<string, string>>;
+    };
+}, { spawn, baseEnv, timeoutMs, now }?: {
+    readonly spawn?: typeof nodeSpawn;
+    readonly baseEnv?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+}): Promise<McpBridgeProbeResult>;
+//# sourceMappingURL=mcp-bridge-probe.d.ts.map

package/dist/agent-executor/mcp-bridge-probe.js

@@ -0,0 +1,77 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { redactSecrets } from '@jini-ai/core';
+import { buildAgentEnv } from './agent-env.js';
+import { errorMessage, isRecord } from './values.js';
+/** Initialize a disposable bridge without a run credential; always reap it after the bounded probe.
+ * Spawn/errors/exits/timeouts return diagnostics rather than rejecting. Stderr retains 2000 bytes.
+ * @complexity O(n) in received bytes; stderr storage is bounded independently of child output.
+ */
+export async function probeMcpBridge({ entry }, { spawn = nodeSpawn, baseEnv = buildAgentEnv({ hostEnv: process.env }), timeoutMs = 15_000, now = Date.now } = {}) {
+    const startedAt = now();
+    const env = { ...baseEnv, ...entry.env, JINI_RUN_ID: 'bridge-probe' };
+    // Initialize needs no callback: never delegate a real run's authority to this diagnostic child.
+    delete env.JINI_DAEMON_TOKEN;
+    let child;
+    let lines;
+    let timer;
+    let stderr = Buffer.alloc(0);
+    const appendStderr = (chunk) => {
+        stderr = Buffer.concat([stderr, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]).subarray(-2000);
+    };
+    const result = (ok, exitCode = null, signal = null) => ({
+        ok, exitCode, signal,
+        stderrTail: redactSecrets({ input: stderr.toString('utf8') }, {
+            extraPatterns: [{ name: 'daemon_token', regex: /JINI_DAEMON_TOKEN\s*=\s*\S+/gi }],
+        }).trim(),
+        elapsedMs: now() - startedAt,
+    });
+    try {
+        child = spawn(entry.command, [...entry.args], { env, stdio: 'pipe' });
+        const bridge = child;
+        lines = bridge.stdout ? createInterface({ input: bridge.stdout, crlfDelay: Infinity }) : undefined;
+        return await new Promise((resolve) => {
+            const fail = (error) => {
+                appendStderr(`\n${errorMessage(error)}`);
+                resolve(result(false));
+            };
+            timer = setTimeout(() => resolve(result(false)), timeoutMs);
+            bridge.once('error', fail);
+            bridge.once('exit', (code, signal) => resolve(result(false, code, signal)));
+            bridge.once('close', (code, signal) => resolve(result(false, code, signal)));
+            bridge.stderr?.on('data', appendStderr);
+            bridge.stdin?.once('error', fail);
+            if (lines) {
+                lines.once('error', fail);
+                lines.on('line', (line) => {
+                    try {
+                        const reply = JSON.parse(line);
+                        if (isRecord(reply) && reply.id === 1 && Object.hasOwn(reply, 'result'))
+                            resolve(result(true));
+                    }
+                    catch {
+                        // Startup chatter is not an initialize response; keep waiting for the matching reply.
+                    }
+                });
+            }
+            bridge.stdin?.end(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {
+                    protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'jini-bridge-probe', version: '0' },
+                } })}\n`);
+        });
+    }
+    catch (error) {
+        appendStderr(`\n${errorMessage(error)}`);
+        return result(false);
+    }
+    finally {
+        clearTimeout(timer);
+        lines?.close();
+        try {
+            child?.kill('SIGKILL');
+        }
+        catch {
+            // A process already gone or refusing cleanup must not discard the original probe diagnostic.
+        }
+    }
+}
+//# sourceMappingURL=mcp-bridge-probe.js.map

package/dist/agent-executor/mcp-bridge.d.ts

@@ -1,3 +1,4 @@
+import type { McpBridgeProbeResult } from './mcp-bridge-probe.js';
 import type { AcpMcpServerInput, RuntimeAgentDef } from '@jini-ai/agent-runtime';
 import type { McpJsonInjectionOptions, McpJsonServerEntry, McpBridgeDelivery, PreparedCodexHome, PreparedClaudeConfigDir, ClaudeConfigDirIsolationOptions, FailBeforeSpawn } from './contracts.js';
 /** The run-error code a run gets when its CLI reports the injected `jini` bridge as anything but connected. */
@@ -16,7 +17,7 @@ export declare function unavailableJiniBridgeStatus({ rawEvent }: {
     readonly rawEvent: unknown;
 }): string | undefined;
 /** The user-readable reason a run stopped because its bridge did not connect. */
-export declare function bridgeUnavailableMessage(status: string): string;
+export declare function bridgeUnavailableMessage(status: string, probe?: McpBridgeProbeResult): string;
 /**
  * Builds this run's `mcpServers.jini` entry — pure and synchronous, so every field mapping is
  * directly assertable without touching the filesystem. The credential arrives already resolved:

package/dist/agent-executor/mcp-bridge.js

@@ -25,8 +25,13 @@ export function unavailableJiniBridgeStatus({ rawEvent }) {
     return status === 'connected' ? undefined : status;
 }
 /** The user-readable reason a run stopped because its bridge did not connect. */
-export function bridgeUnavailableMessage(status) {
-    return `The assistant's tools did not load (MCP bridge "${JINI_MCP_SERVER_KEY}" status: ${status}). The run was stopped instead of continuing without them.`;
+export function bridgeUnavailableMessage(status, probe) {
+    const message = `The assistant's tools did not load (MCP bridge "${JINI_MCP_SERVER_KEY}" status: ${status}). The run was stopped instead of continuing without them.`;
+    if (!probe || probe.ok)
+        return message;
+    const lines = probe.stderrTail.trim().split(/\r?\n/);
+    const reason = lines.find((line) => line.includes('Error')) ?? lines.at(-1);
+    return `${message} Bridge exited with code ${probe.exitCode}: ${reason}`;
 }
 /**
  * Builds this run's `mcpServers.jini` entry — pure and synchronous, so every field mapping is

package/dist/agent-executor.d.ts

@@ -6,5 +6,5 @@
  * wrappers or a second implementation would let tested and shipped behavior drift.
  * See agent-executor/index.ts for the driver contracts and invariants.
  */
-export { type SupportedStreamFormat, isSupportedStreamFormat, type AgentExecutorCompatibility, assessAgentExecutorCompatibility, isAgentExecutorSupported, type AgentRuntimeEventTranslation, extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, type AgentExecutorErrorCode, AgentExecutorError, type AgentExecutorRunInput, type AgentExecutor, type UserMessageDelivery, type CollectProcessTreePidsPort, type StopProcessesPort, type AgentCleanupFailurePhase, type AgentCleanupFailureContext, type ContinuationOptions, type McpJsonInjectionOptions, MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, type McpBridgeDelivery, buildMcpBridgeDelivery, type PreparedCodexHome, type PreparedClaudeConfigDir, type ClaudeConfigDirSeams, type ClaudeConfigDirIsolationOptions, resolveSourceClaudeConfigDir, type FailureClassificationContext, type ClassifyFailure, DEFAULT_BUFFERED_STDOUT_MAX_BYTES, applyAgentTranslationSideEffects, type CreateAgentExecutorOptions, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, selectAgentExecutorHostEnv, resolveLaunch, stagePromptFile, stageLogFile, resolveMcpBridgeForRun, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, type SystemPromptOverlayDelivery, resolveSystemPromptOverlayDelivery, buildRunArgs, writeMcpJsonIfNeeded, type PreparedSystemPromptOverlayFile, prepareSystemPromptOverlayFileIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, guardWindowsCommandLineBudget, type SpawnAgentChildProcessResult, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, armHandoffWatcher, runAcpDispatch, runPiRpcDispatch, createAgentExecutor, } from './agent-executor/index.js';
+export { type SupportedStreamFormat, isSupportedStreamFormat, type AgentExecutorCompatibility, assessAgentExecutorCompatibility, isAgentExecutorSupported, type AgentRuntimeEventTranslation, extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, type AgentExecutorErrorCode, AgentExecutorError, type AgentExecutorRunInput, type AgentExecutor, type UserMessageDelivery, type CollectProcessTreePidsPort, type StopProcessesPort, type AgentCleanupFailurePhase, type AgentCleanupFailureContext, type ContinuationOptions, type McpJsonInjectionOptions, MCP_BRIDGE_UNAVAILABLE, probeMcpBridge, type McpBridgeProbeResult, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, type McpBridgeDelivery, buildMcpBridgeDelivery, type PreparedCodexHome, type PreparedClaudeConfigDir, type ClaudeConfigDirSeams, type ClaudeConfigDirIsolationOptions, resolveSourceClaudeConfigDir, type FailureClassificationContext, type ClassifyFailure, DEFAULT_BUFFERED_STDOUT_MAX_BYTES, applyAgentTranslationSideEffects, type CreateAgentExecutorOptions, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, selectAgentExecutorHostEnv, resolveLaunch, stagePromptFile, stageLogFile, resolveMcpBridgeForRun, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, type SystemPromptOverlayDelivery, resolveSystemPromptOverlayDelivery, buildRunArgs, writeMcpJsonIfNeeded, type PreparedSystemPromptOverlayFile, prepareSystemPromptOverlayFileIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, guardWindowsCommandLineBudget, type SpawnAgentChildProcessResult, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, armHandoffWatcher, runAcpDispatch, runPiRpcDispatch, createAgentExecutor, } from './agent-executor/index.js';
 //# sourceMappingURL=agent-executor.d.ts.map

package/dist/agent-executor.js

@@ -6,5 +6,5 @@
  * wrappers or a second implementation would let tested and shipped behavior drift.
  * See agent-executor/index.ts for the driver contracts and invariants.
  */
-export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, AgentExecutorError, MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, DEFAULT_BUFFERED_STDOUT_MAX_BYTES, applyAgentTranslationSideEffects, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, selectAgentExecutorHostEnv, resolveLaunch, stagePromptFile, stageLogFile, resolveMcpBridgeForRun, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, writeMcpJsonIfNeeded, prepareSystemPromptOverlayFileIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, armHandoffWatcher, runAcpDispatch, runPiRpcDispatch, createAgentExecutor, } from './agent-executor/index.js';
+export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, AgentExecutorError, MCP_BRIDGE_UNAVAILABLE, probeMcpBridge, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, DEFAULT_BUFFERED_STDOUT_MAX_BYTES, applyAgentTranslationSideEffects, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, selectAgentExecutorHostEnv, resolveLaunch, stagePromptFile, stageLogFile, resolveMcpBridgeForRun, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, writeMcpJsonIfNeeded, prepareSystemPromptOverlayFileIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, armHandoffWatcher, runAcpDispatch, runPiRpcDispatch, createAgentExecutor, } from './agent-executor/index.js';
 //# sourceMappingURL=agent-executor.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

@@ -81,7 +81,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 +182,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 = registry.list({}).map((tool) => tool.id).filter((id) => id.startsWith(toolId)).slice(0, 8);
+            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 +218,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.5",
+  "version": "0.6.7",
   "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/http-kit": "0.4.2",
-    "@jini-ai/chat": "0.6.2",
-    "@jini-ai/core": "^0.4.6",
     "@jini-ai/agent-runtime": "^0.4.11",
-    "@jini-ai/platform": "^0.5.7",
+    "@jini-ai/chat": "0.6.5",
     "@jini-ai/protocol": "^0.4.4",
+    "@jini-ai/core": "^0.4.6",
+    "@jini-ai/platform": "^0.5.8",
+    "@jini-ai/http-kit": "0.4.2",
     "@jini-ai/db": "0.3.4"
   },
   "dependencies": {
-    "@jini-ai/core": "^0.4.6",
-    "@jini-ai/protocol": "^0.4.4"
+    "@jini-ai/protocol": "^0.4.4",
+    "@jini-ai/core": "^0.4.6"
   },
   "peerDependencies": {
     "node-pty": "^1.1.0",