@jini-ai/mcp 0.6.16 → 0.6.19

package/dist/server/http-tool-server.js

@@ -0,0 +1,272 @@
+/** SDK Streamable HTTP adapter for the existing tool host. Capabilities remain in host memory. */
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { CancelledNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { adaptSdkTransport } from './sdk-transport.js';
+import { createMcpToolServer } from './tool-server.js';
+/** Embeddings must gate CLI HTTP on retained-session support rather than a protocol probe. */
+export const MCP_HTTP_SESSION_MODE_SUPPORTED = true;
+const MAX_BODY_BYTES = 1_000_000;
+const MAX_REQUESTS = 16;
+/** Constant-time credential comparison after a length check. O(credential bytes). */
+function authorized({ request, token }, _options = {}) {
+    const actual = Buffer.from(request.headers.authorization ?? '');
+    const expected = Buffer.from(`Bearer ${token}`);
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+/** Read at most one bounded JSON document. The receive deadline ends before tool execution.
+ * Returns HTTP status on invalid/oversized input, without interpreting MCP messages. O(body bytes).
+ */
+async function readBody({ request }, _options = {}) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request.iterator({ destroyOnReturn: false })) {
+        const buffer = Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > MAX_BODY_BYTES)
+            return { status: 413 };
+        chunks.push(buffer);
+    }
+    try {
+        return { body: JSON.parse(Buffer.concat(chunks).toString('utf8')) };
+    }
+    catch {
+        return { status: 400 };
+    }
+}
+/** Bind a private loopback listener. Desktop requests use fresh stateless SDK transports;
+ * run listeners opt into one retained SDK session and the same host-owned dispatch contract. Auth precedes body parsing; browsers are always refused.
+ * @example const host = await startMcpHttpToolServer({ name, version, tools, resolveBaseUrl });
+ * @throws Listen/configuration errors; the embedding owns degraded startup and retries.
+ * @complexity O(body bytes + dispatched handler), with 16 requests and 1 MB per body maximum.
+ */
+export async function startMcpHttpToolServer(required, options = {}) {
+    const host = createMcpToolServer(required, options);
+    const token = randomBytes(32).toString('hex');
+    const pending = new Set();
+    const sessionTransport = options.sessionMode
+        ? new StreamableHTTPServerTransport({ sessionIdGenerator: randomUUID }) : undefined;
+    let sessionConnection;
+    let closing;
+    let stopped = false;
+    let retry;
+    const server = (options.createHttpServer ?? createServer)((request, response) => {
+        const work = handle(request, response).catch(() => {
+            options.warn?.('MCP HTTP request failed');
+            if (!response.headersSent)
+                response.writeHead(500).end();
+            else
+                response.destroy();
+        });
+        pending.add(work);
+        void work.finally(() => pending.delete(work));
+    });
+    server.headersTimeout = 5000;
+    server.requestTimeout = 15_000;
+    server.maxConnections = MAX_REQUESTS;
+    /** Gate admission before acquiring bytes or SDK state. O(1) plus a bounded body and tool work. */
+    async function handle(request, response) {
+        response.setHeader('Cache-Control', 'no-store');
+        if (request.headers.origin !== undefined || !authorized({ request, token })) {
+            response.writeHead(403, { Connection: 'close' }).end();
+            return;
+        }
+        if (request.url !== '/mcp') {
+            response.writeHead(404).end();
+            return;
+        }
+        const allowed = options.sessionMode ? ['POST', 'GET', 'DELETE'] : ['POST'];
+        if (!allowed.includes(request.method ?? '')) {
+            response.writeHead(405, { Allow: allowed.join(', ') }).end();
+            return;
+        }
+        if (stopped || pending.size >= MAX_REQUESTS) {
+            response.writeHead(503).end();
+            return;
+        }
+        await dispatch(request, response);
+    }
+    /** Dispose the SDK connection after response delivery, including failed/abandoned requests.
+     * The SDK owns initialize, notifications, validation, list and call; no handwritten dispatch.
+     */
+    async function dispatch(request, response) {
+        let body;
+        if (request.method === 'POST') {
+            // Bound slow authenticated senders too. This timer never limits tool execution.
+            const deadline = setTimeout(() => request.destroy(), 15_000);
+            deadline.unref();
+            let input;
+            try {
+                input = await readBody({ request });
+            }
+            finally {
+                clearTimeout(deadline);
+            }
+            if ('status' in input) {
+                response.writeHead(input.status, { Connection: 'close' }).end();
+                return;
+            }
+            body = input.body;
+        }
+        if (sessionTransport) {
+            sessionConnection ??= host.run({ transport: adaptSdkTransport({ transport: sessionTransport }) }).then(() => {
+                const onmessage = sessionTransport.onmessage;
+                sessionTransport.onmessage = (message, extra) => {
+                    onmessage?.(message, extra);
+                    // The SDK aborts the handler and suppresses its reply on cancellation. Use its
+                    // cancellable SSE response stream so the original POST can also finish draining.
+                    const cancellation = CancelledNotificationSchema.safeParse(message);
+                    if (cancellation.success && cancellation.data.params.requestId !== undefined) {
+                        sessionTransport.closeSSEStream(cancellation.data.params.requestId);
+                    }
+                };
+            });
+            await sessionConnection;
+            if (request.method === 'GET' && stopped) {
+                response.writeHead(503).end();
+                return;
+            }
+            await sessionTransport.handleRequest(request, response, body);
+            return;
+        }
+        // No sessionIdGenerator means stateless mode in the pinned SDK.
+        const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
+        try {
+            await host.run({ transport: adaptSdkTransport({ transport }) });
+            await transport.handleRequest(request, response, body);
+        }
+        finally {
+            await transport.close();
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => { server.removeListener('error', reject); resolve(); });
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('MCP HTTP listener has no TCP address');
+    const port = address.port;
+    /** Repair only the listener, retaining the exact URL/token and never replaying tool work. O(1). */
+    function repairListener() {
+        if (stopped || server.listening || retry)
+            return;
+        options.warn?.('MCP HTTP listener unavailable; retrying automatically');
+        retry = setTimeout(() => {
+            retry = undefined;
+            if (!stopped && !server.listening)
+                server.listen(port, '127.0.0.1');
+        }, 1000);
+        retry.unref();
+    }
+    server.on('error', repairListener);
+    server.on('close', repairListener);
+    return {
+        url: `http://127.0.0.1:${port}/mcp`, token,
+        close(_required, _optional = {}) {
+            stopped = true;
+            clearTimeout(retry);
+            closing ??= (async () => {
+                // End passive SSE first; otherwise server.close() would wait for the client forever.
+                // Active POST streams retain accepted work until completion or client cancellation.
+                sessionTransport?.closeStandaloneSSEStream();
+                const listenerClosed = new Promise((resolve, reject) => {
+                    server.close(error => error && error.code !== 'ERR_SERVER_NOT_RUNNING' ? reject(error) : resolve());
+                });
+                await Promise.all(pending);
+                await sessionConnection?.catch(() => { });
+                await sessionTransport?.close();
+                server.closeIdleConnections();
+                await listenerClosed;
+            })();
+            return closing;
+        },
+    };
+}
+/** Own one shared HTTP listener independently of site/window lifecycles. No I/O until capability()
+ * is called. Concurrent callers share a start; shutdown cancels retries and drains a pending bind.
+ * @example const runtime = createMcpHttpToolServerRuntime({ name, version, tools, resolveBaseUrl });
+ * @complexity O(1) state beyond the bounded HTTP listener and caller-supplied tool table.
+ */
+export function createMcpHttpToolServerRuntime(required, { start = startMcpHttpToolServer, ...options } = {}) {
+    let host;
+    let starting;
+    let retry;
+    let stopped = false;
+    let closing;
+    const listeners = new Set();
+    const subscriptions = new Set();
+    /** Single-flight bind; errors expose no capability or native error text. O(1) beyond bind. */
+    function ensureListener() {
+        if (stopped)
+            return Promise.resolve(undefined);
+        if (host)
+            return Promise.resolve(host);
+        if (starting)
+            return starting;
+        starting = start(required, options).then(async (handle) => {
+            if (stopped) {
+                await handle.close({});
+                return undefined;
+            }
+            host = handle;
+            for (const listener of listeners)
+                listener({ url: handle.url, token: handle.token });
+            return handle;
+        }).catch(() => {
+            if (!stopped) {
+                options.warn?.('MCP HTTP listener unavailable; retrying automatically');
+                retry ??= setTimeout(() => { retry = undefined; void ensureListener(); }, 1000);
+                retry.unref();
+            }
+            return undefined;
+        }).finally(() => { starting = undefined; });
+        return starting;
+    }
+    return {
+        subscribe({ listener }, _optional = {}) {
+            if (stopped)
+                return () => { };
+            let cancelled = false;
+            let deliveryRetry;
+            const unsubscribe = () => {
+                cancelled = true;
+                clearTimeout(deliveryRetry);
+                listeners.delete(deliver);
+                subscriptions.delete(unsubscribe);
+            };
+            /** Retry only capability delivery. A subscriber's error never changes the bound host. O(1). */
+            function deliver(capability) {
+                void Promise.resolve().then(() => { if (!cancelled)
+                    return listener(capability); }).catch(() => {
+                    if (cancelled)
+                        return;
+                    options.warn?.('MCP HTTP capability delivery unavailable; retrying automatically');
+                    deliveryRetry = setTimeout(() => deliver(capability), 1000);
+                    deliveryRetry.unref();
+                });
+            }
+            listeners.add(deliver);
+            subscriptions.add(unsubscribe);
+            if (host)
+                deliver({ url: host.url, token: host.token });
+            void ensureListener();
+            return unsubscribe;
+        },
+        async capability(_required, _optional = {}) {
+            const handle = await ensureListener();
+            return handle ? { url: handle.url, token: handle.token } : undefined;
+        },
+        close(_required, _optional = {}) {
+            stopped = true;
+            for (const unsubscribe of subscriptions)
+                unsubscribe();
+            listeners.clear();
+            clearTimeout(retry);
+            closing ??= (async () => { await starting; await host?.close({}); host = undefined; })();
+            return closing;
+        },
+    };
+}
+//# sourceMappingURL=http-tool-server.js.map

package/dist/server/index.d.ts

@@ -20,4 +20,6 @@ export * from './tools/tool-catalog-tools.js';
 export * from './tools/component-catalog-tools.js';
 export * from './resources/active-resource.js';
 export * from './resources/site-guide-resource.js';
+export * from './http-tool-server.js';
+export * from './run-tool-host.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.js

@@ -20,4 +20,6 @@ export * from './tools/tool-catalog-tools.js';
 export * from './tools/component-catalog-tools.js';
 export * from './resources/active-resource.js';
 export * from './resources/site-guide-resource.js';
+export * from './http-tool-server.js';
+export * from './run-tool-host.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,28 @@
+import type { McpToolServerRequiredArgs, McpToolServerOptions } from './tool-server.js';
+export interface RunToolHostInput {
+    readonly runId: string;
+    readonly resolveBaseUrl: () => Promise<string> | string;
+}
+export interface RunToolHostOptions {
+    readonly credential?: string;
+    readonly startupToolIds?: readonly string[];
+    readonly diagnosticToolIds?: readonly string[];
+    readonly messageRelayNonce?: string;
+    readonly delegatedToolTimeoutMs?: number;
+    readonly delegatedResultMarkers?: boolean;
+    readonly generateToolUseId?: (required: Record<string, never>) => string;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface RunToolHost {
+    readonly required: McpToolServerRequiredArgs;
+    readonly options: McpToolServerOptions;
+}
+/** Assemble one run's authenticated gateways, publication, resources, paging and relay.
+ * @param input - Trusted run identity and explicit daemon URL resolver.
+ * @param options - Explicit callback credential, launch metadata and optional I/O seams.
+ * @returns Transport-neutral arguments for the existing MCP host.
+ * @throws Invalid relay nonce or existing authenticated descriptor resolution errors.
+ * @complexity O(n + s) time/space and n sequential bounded GETs for n unique startup IDs and s schema bytes.
+ */
+export declare function assembleRunToolHost(input: RunToolHostInput, options?: RunToolHostOptions): Promise<RunToolHost>;
+//# sourceMappingURL=run-tool-host.d.ts.map

package/dist/server/run-tool-host.js

@@ -0,0 +1,103 @@
+/** The run MCP surface shared by stdio children and in-process HTTP listeners. No process defaults. */
+import { createCheckMessagesTool, messageRelayInstructions } from './message-relay.js';
+import { waitTool } from './tools/wait.js';
+import { RUN_TOOLS } from './tools/run-tools.js';
+import { describeToolTool, TOOL_CATALOG_TOOLS } from './tools/tool-catalog-tools.js';
+import { COMPONENT_CATALOG_TOOLS } from './tools/component-catalog-tools.js';
+import { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool } from './tools/delegated-tool.js';
+import { KERNEL_RESOURCES } from './resources/active-resource.js';
+import { createSiteGuideResource } from './resources/site-guide-resource.js';
+const SERVER_NAME = 'jini-mcp';
+const SERVER_VERSION = '0.0.0';
+const INSTRUCTIONS = 'Tools proxying this host\'s Jini daemon over loopback HTTP, scoped to the run that spawned this MCP server process. ' +
+    'Use execute_delegated_tool to invoke a Jini-registered tool (never an agent-vendor-specific tool name) against that run — ' +
+    'Registered operation calls use the daemon\'s deny-by-default ToolExecutor gate; ' +
+    'MCP-local names use their existing validated handlers. ' +
+    'Concrete operation tools accept their own arguments directly. describe_tool publishes a concrete definition; ' +
+    'refresh tools/list when supported, or use the delegated gateways as the compatibility fallback. ' +
+    'When the host provides site_guide, consult jini://site-guide or call site_guide with operation overview ' +
+    'through execute_readonly_delegated_tool; follow with explain for the relevant topic ids. ' +
+    'If the host does not provide site_guide, report that availability gap. ' +
+    'Use host tools first. For saved oversized tool results, call read_tool_result with the resultId and follow nextOffset. ' +
+    'For attachments, use the host attachment/image tool first or a native Read/image tool on the supplied path. ' +
+    'Never use Bash, shell commands or scripts to inspect attachments or saved tool results. ' +
+    'Between background job polls, honor poll_after_seconds with wait_for({seconds: <interval up to 60>}); repeat for longer intervals. ' +
+    'Never use Bash or shell sleep between polls. A provider wait tool is optional: describe its live schema before calling it.';
+/** Assemble one run's authenticated gateways, publication, resources, paging and relay.
+ * @param input - Trusted run identity and explicit daemon URL resolver.
+ * @param options - Explicit callback credential, launch metadata and optional I/O seams.
+ * @returns Transport-neutral arguments for the existing MCP host.
+ * @throws Invalid relay nonce or existing authenticated descriptor resolution errors.
+ * @complexity O(n + s) time/space and n sequential bounded GETs for n unique startup IDs and s schema bytes.
+ */
+export async function assembleRunToolHost(input, options = {}) {
+    const { runId } = input;
+    let resolved;
+    // Startup discovery and subsequent execution must use the same resolved daemon.
+    const resolveBaseUrl = () => resolved ??= Promise.resolve().then(input.resolveBaseUrl);
+    const delegatedGatewayOptions = definedOnly({ generateToolUseId: options.generateToolUseId,
+        delegatedToolTimeoutMs: options.delegatedToolTimeoutMs, delegatedResultMarkers: options.delegatedResultMarkers });
+    const messageRelay = relayForRun({ runId, nonce: options.messageRelayNonce });
+    const required = { name: SERVER_NAME, version: SERVER_VERSION, resolveBaseUrl,
+        tools: [...buildTools({ runId, delegatedGatewayOptions }), ...(messageRelay ? [createCheckMessagesTool(messageRelay)] : [])] };
+    // Absent credential => no authHeaders, preserving unauthenticated loopback hosts.
+    const serverOptions = {
+        resources: [...KERNEL_RESOURCES, createSiteGuideResource({ runId }, delegatedGatewayOptions)],
+        instructions: INSTRUCTIONS, resultPaging: true,
+        ...definedOnly({ authHeaders: options.credential ? { Authorization: `Bearer ${options.credential}` } : undefined,
+            fetchImpl: options.fetchImpl, diagnosticToolIds: options.diagnosticToolIds }),
+        ...(messageRelay ? { messageRelay, instructions: `${INSTRUCTIONS} ${messageRelayInstructions(messageRelay)}` } : {}),
+    };
+    const initialTools = await resolveStartupTools({ toolIds: options.startupToolIds ?? [], resolveBaseUrl, serverOptions });
+    return { required, options: { ...serverOptions, delegatedTools: { runId, ...delegatedGatewayOptions, initialTools } } };
+}
+/** A malformed trusted relay flag must fail before a client receives a partially enabled surface. */
+function relayForRun({ runId, nonce }) {
+    if (nonce === undefined)
+        return undefined;
+    if (!/^[a-f0-9]{48}$/u.test(nonce))
+        throw new Error('relay requires a 48-hex-character nonce');
+    return { runId, nonce };
+}
+// Drops `undefined` values so an absent dependency leaves no key at all — required under
+// `exactOptionalPropertyTypes`, and it keeps built option objects byte-identical to the
+// pre-injection shape when nothing is overridden.
+function definedOnly(entries) {
+    return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined));
+}
+function buildTools({ runId, delegatedGatewayOptions }) {
+    return [
+        ...RUN_TOOLS,
+        ...TOOL_CATALOG_TOOLS,
+        ...COMPONENT_CATALOG_TOOLS,
+        createExecuteDelegatedToolTool({ runId }, delegatedGatewayOptions),
+        // Hosted ALONGSIDE the unconstrained gateway, never instead of it. A client that gates on
+        // `readOnlyHint: true` can now reach the read half of the catalog at all; every other client
+        // sees both and picks by what its call actually does.
+        createExecuteReadonlyDelegatedToolTool({ runId }, delegatedGatewayOptions),
+        waitTool,
+    ];
+}
+/**
+ * Resolve each unique startup ID through the existing authenticated describe/publication owner.
+ * The temporary descriptor list seeds M1's bounded exposure; it is not an execution catalog.
+ * Failure aborts startup before any partially resolved list can reach the client.
+ * @returns Authoritative descriptors; no daemon I/O when startup IDs are absent.
+ * @throws The existing descriptor/daemon errors, reported by serve's stderr/exit boundary.
+ * @complexity O(n + s) space/time plus n sequential bounded GETs for n unique IDs and s schema bytes.
+ */
+async function resolveStartupTools({ toolIds, resolveBaseUrl, serverOptions }) {
+    if (toolIds.length === 0)
+        return [];
+    const descriptors = [];
+    const ctx = {
+        baseUrl: await resolveBaseUrl(),
+        fetchImpl: serverOptions.fetchImpl ?? fetch,
+        ...definedOnly({ authHeaders: serverOptions.authHeaders, diagnosticToolIds: serverOptions.diagnosticToolIds }),
+        publishTool: async ({ descriptor }) => { descriptors.push(descriptor); },
+    };
+    for (const id of new Set(toolIds))
+        await describeToolTool.handler({ args: { id }, ctx });
+    return descriptors;
+}
+//# sourceMappingURL=run-tool-host.js.map

package/dist/server/sdk-transport.d.ts

@@ -1,11 +1,17 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { McpTransportLike } from './ports.js';
+type SdkTransportInput = Pick<Transport, 'start' | 'send' | 'close'> & {
+    onmessage?: Transport['onmessage'];
+    onclose?: Transport['onclose'];
+    onerror?: Transport['onerror'];
+};
 /** Internal boundary adapter; SDK callbacks keep their native signature behind the port. */
 export declare function adaptSdkTransport({ transport: sdk }: {
-    transport: Transport;
+    transport: SdkTransportInput;
 }): McpTransportLike;
 /** Resolves adapters to the underlying SDK transport; host ports stay structurally usable. */
 export declare function resolveSdkTransport({ transport }: {
     transport: McpTransportLike;
 }): Transport;
+export {};
 //# sourceMappingURL=sdk-transport.d.ts.map

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

@@ -17,12 +17,26 @@ export interface McpToolArgumentContract {
     readonly argumentNormalization?: {
         readonly aliases?: Readonly<Record<string, string>>;
         readonly foldIntoInput?: true;
+        /** Concrete registry tools reuse the core schema normalizer before MCP validation. */
+        readonly schemaInput?: true;
     };
 }
+/** Resolve this host's CLI decoration, preserving exact registered names and other servers.
+ * @param required - Model-visible name, possibly prefixed by the Jini MCP client.
+ * @param options - Exact-name lookup when a local tool index is available.
+ * @returns The exact name when registered, otherwise the undecorated Jini name.
+ * @complexity O(n) for n name characters; pure, no execution authority.
+ */
+export declare function resolveMcpToolName({ name }: {
+    name: string;
+}, { isRegistered }?: {
+    isRegistered?: (name: string) => boolean;
+}): string;
 /** True for a plain JSON object (not `null`, not an array). */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /**
- * Copies caller arguments into their canonical wrapper shape before schema validation.
+ * Copies caller arguments into their canonical wrapper shape before schema validation, reading a
+ * canonical integer string as the integer a top-level `integer` property declares.
  * @param requiredArgs - Tool contract and untrusted arguments; neither is mutated.
  * @param _options - Reserved normalization options.
  * @returns Canonical arguments; nested tool input is copied only when fields are folded.
@@ -33,15 +47,25 @@ export declare function normalizeToolArguments({ tool, rawArgs }: {
     tool: McpToolArgumentContract;
     rawArgs: unknown;
 }, _options?: Record<string, never>): Record<string, unknown>;
+/** Attach the complete bounded contract to a repair instruction without echoing input values.
+ * @returns The instruction plus schema, or a describe_tool instruction for a large schema.
+ * @complexity O(s) serialization time/space for s schema bytes; pure.
+ */
+export declare function withArgumentContract({ message, inputSchema }: {
+    message: string;
+    inputSchema?: unknown;
+}, _options?: Record<string, never>): string;
 /**
  * Formats structured validation errors as field-specific recovery instructions.
  * @param requiredArgs - Validator errors and, when available, the tool's complete wire input schema.
- * @param _options - Reserved formatting options.
- * @returns A field instruction plus a bounded contract for missing fields or malformed array items.
+ * @param options.includeContract - Include the contract for every registry-tool shape error.
+ * @returns A field instruction plus a bounded contract when requested or needed for missing fields/items.
  * @complexity O(e + p + s) for e errors, p path characters and s serialized schema bytes.
  */
 export declare function argumentShapeMessage({ errors, inputSchema }: {
     errors: readonly OutputUnit[];
     inputSchema?: unknown;
-}, _options?: Record<string, never>): string;
+}, { includeContract }?: {
+    includeContract?: boolean;
+}): string;
 //# sourceMappingURL=tool-arguments.d.ts.map

package/dist/server/tool-arguments.js

@@ -1,3 +1,14 @@
+/** Resolve this host's CLI decoration, preserving exact registered names and other servers.
+ * @param required - Model-visible name, possibly prefixed by the Jini MCP client.
+ * @param options - Exact-name lookup when a local tool index is available.
+ * @returns The exact name when registered, otherwise the undecorated Jini name.
+ * @complexity O(n) for n name characters; pure, no execution authority.
+ */
+export function resolveMcpToolName({ name }, { isRegistered } = {}) {
+    if (isRegistered?.(name))
+        return name;
+    return name.startsWith('mcp__jini__') ? name.slice('mcp__jini__'.length) : name;
+}
 /** True for a plain JSON object (not `null`, not an array). */
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -18,6 +29,24 @@ function applyAliases({ args, aliases }) {
         delete args[alias];
     }
 }
+/** A canonical base-10 integer spelling: no sign, padding, leading zero, fraction or exponent. */
+const CANONICAL_INTEGER = /^(?:0|[1-9]\d{0,14})$/;
+/**
+ * Replaces each top-level argument that the schema types `integer` and the caller sent as a
+ * canonical integer string (`"8"`) with that number, in place. Models do send numbers as strings
+ * (Claude Code sent `search_tools {max_results: "8"}` and lost a turn to the refusal); anything
+ * else, including `"1.5"` or `"08"`, is left for schema validation to refuse.
+ * @complexity O(k) for k argument keys.
+ */
+function coerceIntegerStrings({ args, properties }) {
+    for (const [key, value] of Object.entries(args)) {
+        const property = properties[key];
+        if (typeof value !== 'string' || !isRecord(property) || property.type !== 'integer')
+            continue;
+        if (CANONICAL_INTEGER.test(value))
+            args[key] = Number(value);
+    }
+}
 /**
  * Moves `extraKeys` from the top level of `args` into its `input` object (created when absent), in place.
  * @throws Error when `input` is not a JSON object, or already holds one of the keys being folded.
@@ -51,7 +80,8 @@ function assertNoMisplacedInputKey({ args, schema }) {
         throw new Error(`move \`input.${misplaced}\` to top-level \`${misplaced}\``);
 }
 /**
- * Copies caller arguments into their canonical wrapper shape before schema validation.
+ * Copies caller arguments into their canonical wrapper shape before schema validation, reading a
+ * canonical integer string as the integer a top-level `integer` property declares.
  * @param requiredArgs - Tool contract and untrusted arguments; neither is mutated.
  * @param _options - Reserved normalization options.
  * @returns Canonical arguments; nested tool input is copied only when fields are folded.
@@ -64,6 +94,7 @@ export function normalizeToolArguments({ tool, rawArgs }, _options = {}) {
     const args = { ...rawArgs };
     const properties = tool.inputSchema.properties ?? {};
     applyAliases({ args, aliases: tool.argumentNormalization?.aliases ?? {} });
+    coerceIntegerStrings({ args, properties });
     const extraKeys = Object.keys(args).filter((key) => !Object.hasOwn(properties, key));
     if (tool.argumentNormalization?.foldIntoInput && extraKeys.length > 0) {
         foldExtraKeysIntoInput({ args, extraKeys });
@@ -107,25 +138,32 @@ function boundedToolInputSchema({ inputSchema }, _options = {}) {
     }
     return { inputSchema };
 }
+/** Attach the complete bounded contract to a repair instruction without echoing input values.
+ * @returns The instruction plus schema, or a describe_tool instruction for a large schema.
+ * @complexity O(s) serialization time/space for s schema bytes; pure.
+ */
+export function withArgumentContract({ message, inputSchema }, _options = {}) {
+    const hint = boundedToolInputSchema({ inputSchema });
+    const contract = hint.inputSchema === undefined ? hint.schemaNotice : `Input schema: ${JSON.stringify(hint.inputSchema)}`;
+    return contract ? `${message}; ${contract}` : message;
+}
 /**
  * Formats structured validation errors as field-specific recovery instructions.
  * @param requiredArgs - Validator errors and, when available, the tool's complete wire input schema.
- * @param _options - Reserved formatting options.
- * @returns A field instruction plus a bounded contract for missing fields or malformed array items.
+ * @param options.includeContract - Include the contract for every registry-tool shape error.
+ * @returns A field instruction plus a bounded contract when requested or needed for missing fields/items.
  * @complexity O(e + p + s) for e errors, p path characters and s serialized schema bytes.
  */
-export function argumentShapeMessage({ errors, inputSchema }, _options = {}) {
+export function argumentShapeMessage({ errors, inputSchema }, { includeContract = false } = {}) {
     // Keep the additionalProperties diagnostic ahead of its generic false-schema child.
     const error = errors.find((entry) => entry.keyword === 'required' || entry.keyword === 'additionalProperties' || entry.instanceLocation !== '#') ?? errors[0];
     if (error === undefined)
         return 'supply arguments matching the declared input schema';
     const path = pointerToFieldPath({ instanceLocation: error.instanceLocation });
     const message = namedFieldMessage({ error, path }) ?? `change \`${path || 'arguments'}\`: ${error.error}`;
-    // Missing fields and generic array-item errors otherwise force one guess per retry.
-    if (!errors.some(entry => ['required', 'items'].includes(entry.keyword)))
+    // Wrong keys also need the accepted names and units, not a sequence of remove/retry guesses.
+    if (!includeContract && !errors.some(entry => ['required', 'items'].includes(entry.keyword)))
         return message;
-    const hint = boundedToolInputSchema({ inputSchema });
-    const contract = hint.inputSchema === undefined ? hint.schemaNotice : `Input schema: ${JSON.stringify(hint.inputSchema)}`;
-    return contract ? `${message}; ${contract}` : message;
+    return withArgumentContract({ message, inputSchema });
 }
 //# sourceMappingURL=tool-arguments.js.map