@jini-ai/mcp 0.6.17 → 0.6.19

package/dist/server/tool-protocol.js

@@ -44,11 +44,11 @@
  * responsibility ( Decision 4), not this generic wrapper's.
  * See docs/decisions/DR-002-protocol-resource-boundary.md.
  */
-import { batchOutcomeFor } from '@jini-ai/core';
+import { batchOutcomeFor, normalizeToolInput, withNormalizationNotes } from '@jini-ai/core';
 import { sanitizeUntrustedText } from '@jini-ai/core/text';
 import { Validator } from '@cfworker/json-schema';
 import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
-import { argumentShapeMessage, isRecord, normalizeToolArguments } from './tool-arguments.js';
+import { argumentShapeMessage, isRecord, normalizeToolArguments, resolveMcpToolName, withArgumentContract } from './tool-arguments.js';
 import { safeDiagnostic } from './daemon-client.js';
 import { scopeNestedSchemaRefs } from './schema-ref-scope.js';
 /**
@@ -120,7 +120,9 @@ export function okResult({ payload }) {
     const flaggedError = typeof payload === 'object' && payload !== null && 'isError' in payload && payload.isError === true;
     const isError = flaggedError || outcome === 'partial_failure' || outcome === 'error';
     if (isMcpContentEnvelope(payload)) {
-        return { content: payload.content, ...(isError ? { isError: true } : {}) };
+        return { content: payload.content,
+            ...(isRecord(payload.structuredContent) ? { structuredContent: payload.structuredContent } : {}),
+            ...(isError ? { isError: true } : {}) };
     }
     // Compact on the wire: indentation made nested results ~2.5x larger for the model to read. A view
     // that shows a result to a person re-indents it at render time (`@jini-ai/chat`'s
@@ -182,6 +184,33 @@ function validatorForTool(tool) {
     compiledValidators.set(tool, validator);
     return validator;
 }
+/** Normalize registry-tool input through its existing owner before strict transport validation.
+ * MCP-local wrapper tools retain their own alias/folding contract. Domain hooks and permission
+ * checks remain in the daemon; this pass reads only the published schema.
+ * @returns A detached argument object and value-free normalization notes.
+ * @throws Input errors before any handler or daemon request.
+ * @complexity Core's bounded schema walks plus O(k) wrapper keys; no I/O.
+ */
+async function normalizeCallArguments({ tool, rawArgs }, _options = {}) {
+    const args = normalizeToolArguments({ tool, rawArgs });
+    if (!tool.argumentNormalization?.schemaInput)
+        return { args, notes: [] };
+    const normalized = await normalizeToolInput({ input: args, registration: { descriptor: { id: tool.name, inputSchema: tool.inputSchema } } });
+    if (!isRecord(normalized.input))
+        throw new Error('normalization must produce one input object');
+    return { args: normalized.input, notes: normalized.notes };
+}
+/** Format a refused normalization with the same bounded contract used by schema validation.
+ * Registry tools need the full contract to repair aliases; MCP-local wrapper diagnostics keep
+ * their established messages. No supplied argument values are added to the diagnostic.
+ * @returns An MCP error result; never executes a handler.
+ * @complexity O(s) for s schema bytes plus bounded text sanitization.
+ */
+function normalizationErrorResult({ tool, error, diagnosticToolIds }, _options = {}) {
+    const message = error instanceof Error ? error.message : String(error);
+    const diagnostic = tool.argumentNormalization?.schemaInput ? withArgumentContract({ message, inputSchema: wireInputSchema(tool) }) : message;
+    return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: diagnostic }, { diagnosticToolIds, maxLength: 4608 })}` });
+}
 /**
  * `tools/call` dispatch: looks up `name` in `tools`, normalizes aliases/wrapper input, then
  * validates the canonical arguments against the tool's
@@ -199,32 +228,33 @@ function validatorForTool(tool) {
 export async function handleToolCall({ name, tools, ctx }, { rawArgs } = {}) {
     const diagnosticToolIds = [...tools.keys(), ...(ctx.diagnosticToolIds ?? [])];
     ctx = { ...ctx, diagnosticToolIds };
-    const tool = tools.get(name);
+    const tool = tools.get(resolveMcpToolName({ name }, { isRegistered: candidate => tools.has(candidate) }));
     if (tool === undefined) {
         return errorResult({ message: `unknown tool: ${name}` });
     }
     // Normalization and schema validation share an error boundary; handlers run only afterward.
     // See docs/decisions/DR-005-proxy-argument-shapes.md.
     let validatedArgs;
+    let normalizationNotes;
     try {
-        const args = normalizeToolArguments({ tool, rawArgs: rawArgs ?? {} });
+        const { args, notes } = await normalizeCallArguments({ tool, rawArgs: rawArgs ?? {} });
         const validation = validatorForTool(tool).validate(args);
         if (!validation.valid) {
-            return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: argumentShapeMessage({ errors: validation.errors, inputSchema: wireInputSchema(tool) }) }, {
+            return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: argumentShapeMessage({ errors: validation.errors, inputSchema: wireInputSchema(tool) }, { includeContract: tool.argumentNormalization?.schemaInput === true }) }, {
                     diagnosticToolIds,
                     // A complete bounded contract must survive the default 500-character diagnostic cap.
                     maxLength: 4608,
                 })}` });
         }
         validatedArgs = args;
+        normalizationNotes = notes;
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: message }, { diagnosticToolIds })}` });
+        return normalizationErrorResult({ tool, error: err, diagnosticToolIds });
     }
     try {
         const result = await tool.handler({ args: validatedArgs, ctx: ctx });
-        return okResult({ payload: result });
+        return okResult({ payload: withNormalizationNotes({ output: result, notes: normalizationNotes }) });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/server/tool-result-pages.d.ts

@@ -0,0 +1,21 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpToolDef } from './tool-protocol.js';
+export interface ToolResultPages {
+    readonly tool: McpToolDef;
+    project(required: {
+        result: CallToolResult;
+    }, optional?: Record<string, never>): CallToolResult;
+    clear(required: Record<string, never>, optional?: Record<string, never>): void;
+}
+/** Keep large text in this MCP run rather than a CLI-owned spill file outside the site sandbox.
+ * Text is paged losslessly; image/resource blocks and result error flags pass through unchanged.
+ * @param _required No required configuration; one instance belongs to one server run.
+ * @param optional Optional opaque ID source for deterministic tests; defaults to randomUUID.
+ * @returns A projection, read-only read_tool_result tool, and explicit cleanup.
+ * @complexity O(n) projection for n result characters; at most 32 entries / 8M UTF-16 code units.
+ * @example const pages = createToolResultPages({}); pages.project({ result });
+ */
+export declare function createToolResultPages(_required: Record<string, never>, { generateId, }?: {
+    generateId?: () => string;
+}): ToolResultPages;
+//# sourceMappingURL=tool-result-pages.d.ts.map

package/dist/server/tool-result-pages.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+const INLINE_CHARS = 12000;
+const MAX_STORED_CHARS = 8_000_000;
+const MAX_RESULTS = 32;
+const SMALL_BLOCK_CHARS = 1024;
+/** Keep large text in this MCP run rather than a CLI-owned spill file outside the site sandbox.
+ * Text is paged losslessly; image/resource blocks and result error flags pass through unchanged.
+ * @param _required No required configuration; one instance belongs to one server run.
+ * @param optional Optional opaque ID source for deterministic tests; defaults to randomUUID.
+ * @returns A projection, read-only read_tool_result tool, and explicit cleanup.
+ * @complexity O(n) projection for n result characters; at most 32 entries / 8M UTF-16 code units.
+ * @example const pages = createToolResultPages({}); pages.project({ result });
+ */
+export function createToolResultPages(_required, { generateId = randomUUID, } = {}) {
+    const saved = new Map();
+    let storedChars = 0;
+    /** Evict oldest entries until the new result fits; all limits are per run. */
+    function save(text) {
+        while (saved.size >= MAX_RESULTS || storedChars + text.length > MAX_STORED_CHARS) {
+            const oldest = saved.keys().next().value;
+            storedChars -= saved.get(oldest).length;
+            saved.delete(oldest);
+        }
+        const id = generateId();
+        saved.set(id, text);
+        storedChars += text.length;
+        return id;
+    }
+    const tool = {
+        name: 'read_tool_result',
+        description: 'Read a page of a saved oversized tool result in this run. Use resultId from the tool response, offset (default 0), and limit (default 4000, max 8000). Returns one text block: JSON cursor metadata on its first line, then exact result text. Follow nextOffset until null. Unknown/evicted IDs fail; repeat the original tool with a narrower query. Never read CLI spill files with Bash.',
+        inputSchema: { type: 'object', required: ['resultId'], additionalProperties: false, properties: {
+                resultId: { type: 'string', minLength: 1 }, offset: { type: 'integer', minimum: 0 },
+                limit: { type: 'integer', minimum: 1, maximum: 8000 },
+            } },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        handler({ args }) {
+            const resultId = args['resultId'];
+            const text = saved.get(resultId);
+            if (text === undefined)
+                throw new Error('Saved result is unavailable in this run. Repeat the original tool call with a narrower query.');
+            const offset = args['offset'] ?? 0;
+            if (offset > text.length)
+                throw new RangeError('offset exceeds the saved result length.');
+            const end = Math.min(text.length, offset + (args['limit'] ?? 4000));
+            const cursor = { resultId, offset, nextOffset: end < text.length ? end : null, totalChars: text.length };
+            return { content: [{ type: 'text', text: `${JSON.stringify(cursor)}\n${text.slice(offset, end)}` }] };
+        },
+    };
+    return {
+        tool,
+        project({ result }) {
+            const texts = result.content.flatMap(block => block.type === 'text' ? [block.text] : []);
+            const totalChars = texts.reduce((sum, text) => sum + text.length, 0);
+            if (totalChars <= INLINE_CHARS)
+                return result;
+            // Keep small metadata blocks inline; page medium blocks too when their combined size spills.
+            const retained = texts.filter(text => text.length > SMALL_BLOCK_CHARS);
+            const retainedChars = retained.reduce((sum, text) => sum + text.length, 0);
+            // Admit one response atomically so its later blocks cannot evict its earlier block IDs.
+            if (retained.length > MAX_RESULTS || retainedChars > MAX_STORED_CHARS || totalChars - retainedChars > 4000)
+                return { isError: true, content: [{ type: 'text',
+                            text: 'Tool result exceeds the saved-result limit. Repeat the original tool call with a narrower query. Never use Bash to read CLI spill files.' }] };
+            return { ...result, content: result.content.map(block => {
+                    if (block.type !== 'text' || block.text.length <= SMALL_BLOCK_CHARS)
+                        return block;
+                    const resultId = save(block.text);
+                    return { ...block, text: `Saved tool result (${block.text.length} characters). Read it with read_tool_result(${JSON.stringify({ resultId, offset: 0 })}); follow nextOffset until null. Never use Bash or shell commands to read saved tool results.` };
+                }) };
+        },
+        clear() { saved.clear(); storedChars = 0; },
+    };
+}
+//# sourceMappingURL=tool-result-pages.js.map

package/dist/server/tool-server.d.ts

@@ -1,7 +1,8 @@
 /**
  * @module @jini-ai/mcp/server/tool-server
- * Generic stdio hosting for an explicit caller-supplied tool list. Construction validates unique
- * names synchronously without I/O; run resolves the daemon URL, connects and serves until closure.
+ * Transport-neutral hosting for an explicit tool list, with an optional stdio lifecycle.
+ * Construction validates unique names without I/O; run resolves the daemon URL and connects.
+ * An embedding owns its explicit transport; a stdio run serves until closure.
  * Tools capability is always advertised; resources only when nonempty resources are supplied.
  * Narrow object-shaped server/transport ports permit DI fakes without requiring SDK class instances
  * with nominal private fields; default adapters translate those contracts to the real SDK.
@@ -73,6 +74,8 @@ export interface McpToolServerRequiredArgs {
 export interface McpToolServerOptions extends StdioHostingOptions {
     /** Set only by relay-enabled spawns; native input engines incur no extra request or tool. */
     readonly messageRelay?: McpMessageRelay;
+    /** Keep oversized text in this run and advertise read_tool_result instead of CLI spill files. */
+    readonly resultPaging?: boolean;
     /** Opt in to bounded, per-run typed publication after describe_tool. */
     readonly delegatedTools?: McpDelegatedToolsOptions;
     /** Trusted daemon registration IDs carried into every error sanitizer. */
@@ -121,12 +124,15 @@ export interface McpToolServerHandle {
     /**
      * Resolves the daemon base URL, connects the MCP server to its transport, and holds the process
      * open until the client disconnects (stdin EOF) or the idle-exit window elapses. Resolves once
-     * the transport has closed.
+     * the transport has closed. With an explicit transport, connects and returns immediately;
+     * the embedding owns closure, without stdin or an idle-exit timer.
      */
-    run(required: Record<string, never>): Promise<void>;
+    run(required: {
+        transport?: McpTransportLike;
+    }): Promise<void>;
 }
 /**
- * Builds a stdio MCP server hosting `requiredArgs.tools` (and, optionally, `options.resources`).
+ * Builds an MCP tool host with a stdio lifecycle unless run() receives an explicit transport.
  * Construction is synchronous and cheap (validates tool-name uniqueness via
  * {@link buildToolIndex} and resource-uri uniqueness via {@link buildResourceIndex}); all I/O —
  * resolving the daemon URL, connecting the transport, serving requests — happens in the returned

package/dist/server/tool-server.js

@@ -7,6 +7,8 @@ import { createMcpIdleExitController } from '../client/client.js';
 import { buildResourceIndex, handleResourceRead, resourcesToList } from './resource-protocol.js';
 import { buildToolIndex, handleToolCall, toolsToList } from './tool-protocol.js';
 import { createTypedDelegatedToolTool } from './tools/delegated-tool.js';
+import { resolveMcpToolName } from './tool-arguments.js';
+import { createToolResultPages } from './tool-result-pages.js';
 import { prependRunUserMessages } from './message-relay.js';
 import { createStdioHosting, validateFrameLimit, wantsStdioHosting } from './stdio-hosting.js';
 /** Auto-exit an idle server after this long without tool activity. */
@@ -155,7 +157,7 @@ function createToolPublisher({ index, server, options }) {
     };
 }
 /**
- * Builds a stdio MCP server hosting `requiredArgs.tools` (and, optionally, `options.resources`).
+ * Builds an MCP tool host with a stdio lifecycle unless run() receives an explicit transport.
  * Construction is synchronous and cheap (validates tool-name uniqueness via
  * {@link buildToolIndex} and resource-uri uniqueness via {@link buildResourceIndex}); all I/O —
  * resolving the daemon URL, connecting the transport, serving requests — happens in the returned
@@ -169,20 +171,79 @@ export function createMcpToolServer(requiredArgs, options = {}) {
     const resourceIndex = buildResourceIndex({ resources });
     const createServer = options.createServer ?? defaultCreateServer;
     const createTransport = options.createTransport ?? defaultCreateTransport;
-    return {
-        async run(_required) {
-            const toolIndex = buildToolIndex({ tools: requiredArgs.tools });
-            let ctx = buildToolContext({ resolvedBaseUrl: await requiredArgs.resolveBaseUrl() }, options);
-            const server = createServer({
-                info: { name: requiredArgs.name, version: requiredArgs.version },
-                options: {
-                    capabilities: { tools: options.delegatedTools ? { listChanged: true } : {}, ...(resources.length > 0 ? { resources: {} } : {}) },
-                    ...(options.instructions !== undefined ? { instructions: options.instructions } : {}),
-                },
+    /** Install the shared tool/resource dispatch for either hosting lifecycle. O(tools + resources).
+     * Transport closure clears result pages; the returned cleanup also covers failed stdio closure.
+     */
+    async function connectHost({ transport, withActivity }) {
+        const resultPages = options.resultPaging ? createToolResultPages({}) : undefined;
+        const toolIndex = buildToolIndex({ tools: [...requiredArgs.tools, ...(resultPages ? [resultPages.tool] : [])] });
+        let ctx = buildToolContext({ resolvedBaseUrl: await requiredArgs.resolveBaseUrl() }, options);
+        const server = createServer({
+            info: { name: requiredArgs.name, version: requiredArgs.version },
+            options: {
+                capabilities: { tools: options.delegatedTools ? { listChanged: true } : {}, ...(resources.length > 0 ? { resources: {} } : {}) },
+                ...(options.instructions !== undefined ? { instructions: options.instructions } : {}),
+            },
+        });
+        const publishTool = createToolPublisher({ index: toolIndex, server, options: options.delegatedTools });
+        if (publishTool)
+            ctx = { ...ctx, publishTool };
+        server.setRequestHandler({
+            schema: ListToolsRequestSchema,
+            handler: withActivity(async () => ({ tools: toolsToList({ tools: [...toolIndex.values()] }) })),
+        });
+        server.setRequestHandler({
+            schema: CallToolRequestSchema,
+            handler: withActivity(async ({ request }, { extra } = {}) => {
+                const callContext = extra?.signal !== undefined ? { ...ctx, signal: extra.signal } : ctx;
+                let checkedMessages = resolveMcpToolName({ name: request.params.name }, { isRegistered: candidate => toolIndex.has(candidate) }) === 'check_messages';
+                const callLocalTool = async ({ name, input, requireReadOnly }, _optional = {}) => {
+                    const tool = toolIndex.get(resolveMcpToolName({ name }, { isRegistered: candidate => toolIndex.has(candidate) }));
+                    if (!tool)
+                        return undefined;
+                    if (requireReadOnly && tool.annotations?.readOnlyHint !== true) {
+                        throw new Error(`Tool "${name}" is not declared read-only; use execute_delegated_tool.`);
+                    }
+                    checkedMessages = tool.name === 'check_messages';
+                    // Keep nesting bounded: a local gateway's own handler receives the base context.
+                    return handleToolCall({ name, tools: toolIndex, ctx: callContext }, { rawArgs: input });
+                };
+                const result = await handleToolCall({ name: request.params.name, tools: toolIndex,
+                    ctx: { ...callContext, callLocalTool } }, { rawArgs: request.params.arguments });
+                // A delegated check must keep its trusted nonce and claim only once, just like a direct check.
+                const readableResult = checkedMessages ? result : (resultPages?.project({ result }) ?? result);
+                if (!options.messageRelay || checkedMessages)
+                    return readableResult;
+                return prependRunUserMessages({ result: readableResult, relay: options.messageRelay, ctx: callContext });
+            }),
+        });
+        if (resources.length > 0) {
+            server.setRequestHandler({
+                schema: ListResourcesRequestSchema,
+                handler: withActivity(async () => ({ resources: resourcesToList({ resources }) })),
+            });
+            server.setRequestHandler({
+                schema: ReadResourceRequestSchema,
+                handler: withActivity(async ({ request }) => handleResourceRead({ uri: request.params.uri, resources: resourceIndex, ctx })),
             });
-            const publishTool = createToolPublisher({ index: toolIndex, server, options: options.delegatedTools });
-            if (publishTool)
-                ctx = { ...ctx, publishTool };
+        }
+        try {
+            await server.connect({ transport });
+            const onclose = transport.onclose;
+            transport.onclose = () => { onclose?.(); resultPages?.clear({}); };
+            return () => resultPages?.clear({});
+        }
+        catch (error) {
+            resultPages?.clear({});
+            throw error;
+        }
+    }
+    return {
+        async run({ transport: externalTransport }) {
+            if (externalTransport) {
+                await connectHost({ transport: externalTransport, withActivity: handler => async (...args) => handler(...args) });
+                return;
+            }
             let closeTransportForIdle = null;
             const idleExit = createMcpIdleExitController({
                 idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
@@ -190,50 +251,13 @@ export function createMcpToolServer(requiredArgs, options = {}) {
             });
             const hosting = hostingForOptions(options);
             const withActivity = createActivityTracker({ idleExit, hosting });
-            server.setRequestHandler({
-                schema: ListToolsRequestSchema,
-                handler: withActivity(async () => ({ tools: toolsToList({ tools: [...toolIndex.values()] }) })),
-            });
-            server.setRequestHandler({
-                schema: CallToolRequestSchema,
-                handler: withActivity(async ({ request }, { extra } = {}) => {
-                    const callContext = extra?.signal !== undefined ? { ...ctx, signal: extra.signal } : ctx;
-                    let checkedMessages = request.params.name === 'check_messages';
-                    const callLocalTool = async ({ name, input, requireReadOnly }, _optional = {}) => {
-                        const tool = toolIndex.get(name);
-                        if (!tool)
-                            return undefined;
-                        if (requireReadOnly && tool.annotations?.readOnlyHint !== true) {
-                            throw new Error(`Tool "${name}" is not declared read-only; use execute_delegated_tool.`);
-                        }
-                        checkedMessages = name === 'check_messages';
-                        // Keep nesting bounded: a local gateway's own handler receives the base context.
-                        return handleToolCall({ name, tools: toolIndex, ctx: callContext }, { rawArgs: input });
-                    };
-                    const result = await handleToolCall({ name: request.params.name, tools: toolIndex,
-                        ctx: { ...callContext, callLocalTool } }, { rawArgs: request.params.arguments });
-                    // A delegated check must keep its trusted nonce and claim only once, just like a direct check.
-                    if (!options.messageRelay || checkedMessages)
-                        return result;
-                    return prependRunUserMessages({ result, relay: options.messageRelay, ctx: callContext });
-                }),
-            });
-            if (resources.length > 0) {
-                server.setRequestHandler({
-                    schema: ListResourcesRequestSchema,
-                    handler: withActivity(async () => ({ resources: resourcesToList({ resources }) })),
-                });
-                server.setRequestHandler({
-                    schema: ReadResourceRequestSchema,
-                    handler: withActivity(async ({ request }) => handleResourceRead({ uri: request.params.uri, resources: resourceIndex, ctx })),
-                });
-            }
             const transport = createHostedTransport({ createTransport, options, hosting });
+            let disposeHost;
             try {
                 closeTransportForIdle = () => {
                     void transport.close({}).catch(() => { });
                 };
-                await server.connect({ transport });
+                disposeHost = await connectHost({ transport, withActivity });
                 // `connect()` sets `transport.onmessage` to its own protocol-dispatch handler; wrap it so
                 // every inbound message also counts as activity for the idle-exit timer, without losing
                 // the SDK's own routing.
@@ -245,6 +269,7 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                 await waitForTransportClose({ transport, idleExit, hosting, stdin: options.stdin ?? process.stdin });
             }
             finally {
+                disposeHost?.();
                 idleExit.dispose({});
                 if (hosting)
                     void hosting.dispose();

package/dist/server/tools/delegated-tool.d.ts

@@ -1,7 +1,10 @@
 import { type ExposedToolDescriptor } from '@jini-ai/core';
 import { type McpToolDef } from '../tool-protocol.js';
 /**
- * Request deadline for one delegated tool call, overriding `daemon-client.ts`'s 15 s default.
+ * Superseded 2026-11-03: human reading time is bounded by the run, not a wall-clock budget.
+ * The historical reasoning below explains the former paired deadlines; it is not current policy.
+ *
+ * Historical rationale for the former bounded deadline, overriding `daemon-client.ts`'s 15 s default.
  *
  * That default is sized for "a slow tool call" — a tool doing work. It is the wrong shape for this
  * route, which is the one path in the system where a registered handler may legitimately be waiting
@@ -27,7 +30,7 @@ import { type McpToolDef } from '../tool-protocol.js';
  * than fifteen seconds. The daemon-side alternative does not exist to lean on — `ToolDescriptor.timeoutMs`
  * is unset on every registration today, so `ToolExecutor` arms no timer of its own.
  */
-export declare const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS: number;
+export declare const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS: null;
 export interface CreateExecuteDelegatedToolToolRequiredArgs {
     /** The one run this MCP server process — and therefore this tool instance — is scoped to. */
     readonly runId: string;
@@ -37,14 +40,12 @@ export interface CreateExecuteDelegatedToolToolOptions {
     /** Generates each call's `toolUseId`. @default node:crypto randomUUID */
     readonly generateToolUseId?: (required: Record<string, never>) => string;
     /**
-     * Request deadline for one delegated tool call, in milliseconds. Set this to match the host's
-     * own exchange total-lifetime ceiling plus headroom, so the exchange — not this request — is
-     * what ends a call the human never answers.
+     * Optional finite request deadline in milliseconds. Omit for a run-lifetime human wait.
      *
      * Must be a finite number greater than zero; anything else falls back to the default rather
      * than arming a nonsensical (or immediately-firing) timer.
      *
-     * @default DEFAULT_DELEGATED_TOOL_TIMEOUT_MS (6 min)
+     * @default DEFAULT_DELEGATED_TOOL_TIMEOUT_MS (no wall-clock deadline)
      */
     readonly delegatedToolTimeoutMs?: number;
     /** Emit v1 metadata only when the host has enabled daemon/runtime echo correlation. Default off. */

package/dist/server/tools/delegated-tool.js

@@ -39,6 +39,7 @@ import { parseMcpToolInputSchema } from '../adapters/protocol.js';
 import { randomUUID } from 'node:crypto';
 import { postDaemonJson } from '../daemon-client.js';
 import { daemonCallOptions, requireString } from '../tool-protocol.js';
+import { resolveMcpToolName } from '../tool-arguments.js';
 /** Shared by legacy gateways and concrete definitions for every MCP-capable agent CLI. */
 const APPROVAL_GUIDANCE = 'Never say an action has started until its tool result explicitly says it started. An approval-gated action waiting for Confirm has not started. While approval is pending, other writes are refused with awaiting_approval and started:false; reads may continue. Wait for the final result before reporting an outcome.';
 function isRecord(value) {
@@ -76,7 +77,10 @@ function unwrapMcpContentEnvelope(result) {
     return output;
 }
 /**
- * Request deadline for one delegated tool call, overriding `daemon-client.ts`'s 15 s default.
+ * Superseded 2026-11-03: human reading time is bounded by the run, not a wall-clock budget.
+ * The historical reasoning below explains the former paired deadlines; it is not current policy.
+ *
+ * Historical rationale for the former bounded deadline, overriding `daemon-client.ts`'s 15 s default.
  *
  * That default is sized for "a slow tool call" — a tool doing work. It is the wrong shape for this
  * route, which is the one path in the system where a registered handler may legitimately be waiting
@@ -102,7 +106,7 @@ function unwrapMcpContentEnvelope(result) {
  * than fifteen seconds. The daemon-side alternative does not exist to lean on — `ToolDescriptor.timeoutMs`
  * is unset on every registration today, so `ToolExecutor` arms no timer of its own.
  */
-export const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS = 6 * 60 * 1000;
+export const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS = null;
 /**
  * Builds one gateway def. Both exported factories call this; there is no second copy of the
  * request body, the timeout rule, or the unwrap.
@@ -167,7 +171,7 @@ function createDelegatedGateway(variant, { runId }, options) {
             const body = {
                 runId,
                 toolUseId,
-                toolId: toolId,
+                toolId: resolveMcpToolName({ name: toolId }, { isRegistered: candidate => ctx.diagnosticToolIds?.includes(candidate) ?? false }),
                 // The schema tells the model to omit `input` for a tool that takes none, but most tool
                 // handlers refuse an absent input ("input must be an object"). Sending `{}` makes the
                 // schema's promise true instead of costing a red failed call and a retry.
@@ -266,6 +270,7 @@ export function createTypedDelegatedToolTool({ runId, tool }, options = {}) {
         description: `${descriptor.description ?? descriptor.id} ${APPROVAL_GUIDANCE}`,
         // Parse to check the MCP boundary, but publish the original schema, including extensions.
         inputSchema: descriptor.inputSchema,
+        argumentNormalization: { schemaInput: true },
         annotations: { ...gateway.annotations, title: descriptor.id },
         handler: ({ args, ctx }) => gateway.handler({ args: { toolId: descriptor.id, input: args }, ctx }),
     };

package/dist/server/tools/wait.d.ts

@@ -0,0 +1,5 @@
+import type { McpToolDef } from '../tool-protocol.js';
+/** A bounded, cancellable pause shared by all MCP clients; no daemon call or shell process.
+ * Long poll intervals use several calls, allowing the agent to check messages between waits. */
+export declare const waitTool: McpToolDef;
+//# sourceMappingURL=wait.d.ts.map

package/dist/server/tools/wait.js

@@ -0,0 +1,17 @@
+import { setTimeout } from 'node:timers/promises';
+/** A bounded, cancellable pause shared by all MCP clients; no daemon call or shell process.
+ * Long poll intervals use several calls, allowing the agent to check messages between waits. */
+export const waitTool = {
+    name: 'wait_for',
+    description: 'Wait before polling a pending background job again. Pass seconds from poll_after_seconds, up to 60 per call; repeat for longer intervals. Returns waitedSeconds after the pause. Cancellation stops the timer. Use this instead of Bash or shell sleep. This tool does not check job status.',
+    inputSchema: { type: 'object', required: ['seconds'], additionalProperties: false,
+        properties: { seconds: { type: 'number', minimum: 0, maximum: 60 } } },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async handler({ args, ctx }) {
+        // handleToolCall validates the duration before this handler is reached.
+        const seconds = args['seconds'];
+        await setTimeout(seconds * 1000, undefined, { signal: ctx.signal });
+        return { waitedSeconds: seconds };
+    },
+};
+//# sourceMappingURL=wait.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "Model Context Protocol adapters: server config schema and IO, an MCP client, and agent-side MCP server installation.",
   "license": "Apache-2.0",
   "repository": {
@@ -85,16 +85,16 @@
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@jini-ai/platform": "^0.6.17",
-    "@jini-ai/core": "^0.6.17",
-    "@jini-ai/protocol": "^0.6.17"
+    "@jini-ai/core": "^0.6.19",
+    "@jini-ai/platform": "^0.6.19",
+    "@jini-ai/protocol": "^0.6.19"
   },
   "devDependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@jini-ai/core": "^0.6.17",
-    "@jini-ai/platform": "^0.6.17",
-    "@jini-ai/daemon": "^0.6.17"
+    "@jini-ai/daemon": "^0.6.19",
+    "@jini-ai/platform": "^0.6.19",
+    "@jini-ai/core": "^0.6.19"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",