@jini-ai/mcp 0.1.2 → 0.3.1

package/dist/server/tool-protocol.js

@@ -10,10 +10,96 @@
  * JSON-serializable payload (wrapped as a successful MCP result) or throws
  * (wrapped as an `{isError:true}` MCP result). `./tool-server.js` is the thin
  * layer that wires this to a real `Server` + `StdioServerTransport`.
+ *
+ * ## The one exception to "wrapped as a successful MCP result"
+ *
+ * {@link okResult} used to JSON.stringify every non-string payload unconditionally, which is exactly
+ * right for the overwhelming majority of handlers (plain JSON — an id, a list, a count) but wrong
+ * for a handler whose payload IS already a well-formed MCP content envelope (`{content: [...]}` of
+ * recognized block types). Stringifying that flattens a typed `image` block into an inert
+ * base64-in-quotes string the client can no longer render or hand to a vision model — the exact bug
+ * `execute_delegated_tool` (`../tools/delegated-tool.js`) hit: `@jini-ai/daemon`'s
+ * `delegated-tool-bridge.ts` already keeps an image block in its returned `ToolExecutionResult.output`
+ * (it is model-safe per that package's `tool-result-surfaces.ts`), but this module still turned it
+ * back into text on the way out. {@link okResult} now recognizes that one shape — a `content` array
+ * whose every entry is a known, well-formed block (`text` or `image`) — and passes it through
+ * verbatim instead. Whitelist, not blacklist, mirroring `tool-result-surfaces.ts`'s own posture: a
+ * `content` array holding even one entry this module cannot verify falls back to the stringify path,
+ * so an unrecognized or malformed block is never silently forwarded as if it were valid protocol
+ * output.
  */
 import { sanitizeUntrustedText } from '@jini-ai/cli';
-/** Wraps a successful tool result as MCP `text` content, JSON-stringifying anything that isn't already a string. */
+import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker';
+/**
+ * Maps a tool context onto the `DaemonRequestOptions` every daemon call needs.
+ *
+ * **Use this instead of writing `{ fetchImpl: ctx.fetchImpl }` inline.** Both fields have to travel
+ * together on every call, and the failure mode when one is forgotten is not a compile error but a
+ * silent 401 from that one tool while every other tool keeps working — the kind of bug that reaches
+ * a user as "some of these tools just don't do anything". Routing every call site through one
+ * mapping means a newly added tool is authenticated by construction.
+ *
+ * @param ctx - The context handed to a tool or resource handler.
+ * @returns Options carrying the injected `fetch` and, when present, the auth headers.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export function daemonCallOptions(ctx) {
+    return {
+        fetchImpl: ctx.fetchImpl,
+        ...(ctx.authHeaders !== undefined ? { headers: { ...ctx.authHeaders } } : {}),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * One MCP content-block `type` this module will pass through verbatim rather than JSON-stringify.
+ * Deliberately narrow — see this module's own doc for why widening it is a considered whitelist
+ * addition, not a default. Each entry is checked structurally (not just by `type`), so a block that
+ * merely claims a recognized `type` but is missing/mistyping its required field(s) still falls back
+ * to the stringify path rather than being forwarded malformed.
+ */
+function isPassthroughContentBlock(block) {
+    if (!isRecord(block))
+        return false;
+    if (block['type'] === 'text')
+        return typeof block['text'] === 'string';
+    if (block['type'] === 'image')
+        return typeof block['data'] === 'string' && typeof block['mimeType'] === 'string';
+    return false;
+}
+/**
+ * True when `payload` is already a well-formed MCP content envelope safe to hand back to the client
+ * unchanged: a record whose `content` field is an array, and every entry in it is a recognized,
+ * well-formed block (see {@link isPassthroughContentBlock}). A payload that merely has an array
+ * FIELD named `content` for unrelated reasons (an ordinary JSON object happening to use that name)
+ * will not match unless every entry also happens to look like a content block — the same duck-typed
+ * convention `@jini-ai/daemon`'s `tool-result-media.ts`/`tool-result-surfaces.ts` already apply to
+ * this identical envelope shape one layer up, kept consistent here rather than reinvented.
+ */
+function isMcpContentEnvelope(payload) {
+    if (!isRecord(payload))
+        return false;
+    const content = payload['content'];
+    return Array.isArray(content) && content.every(isPassthroughContentBlock);
+}
+/**
+ * Wraps a successful tool result as an MCP `CallToolResult`.
+ *
+ * A payload that is already a well-formed MCP content envelope (see {@link isMcpContentEnvelope}) is
+ * returned with its `content` array verbatim, so a typed block inside it — an `image`, today — reaches
+ * the client as a real content block rather than flattened text (see this module's own doc for the
+ * bug this closes). Every other payload keeps the original behavior: a string passes through as one
+ * text block; anything else is JSON-stringified into one.
+ *
+ * @complexity O(n) in the number of content-array entries, only when `payload` already looks like an
+ * envelope; O(1) otherwise.
+ */
 export function okResult(payload) {
+    if (isMcpContentEnvelope(payload)) {
+        return { content: payload.content };
+    }
     const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
     return { content: [{ type: 'text', text }] };
 }
@@ -48,22 +134,68 @@ export function buildToolIndex(tools) {
     return index;
 }
 /**
- * `tools/call` dispatch: looks up `name` in `tools`, runs its handler against `rawArgs`, and
- * converts the outcome to a `CallToolResult` — an unknown tool name or a thrown error both
- * produce an `{isError:true}` result rather than rejecting, matching MCP's convention that tool
- * failures are protocol-level results, not JSON-RPC errors. A thrown error's message is passed
- * through {@link sanitizeUntrustedText} before it reaches the result: `handler` may re-throw text
- * that ultimately traces back to the daemon (untrusted network peer), and a caller-thrown
- * validation error is cheap to sanitize unconditionally rather than trying to prove which case
- * applies at each call site.
+ * The SDK's own edge-runtime-compatible (no `eval`/codegen) JSON Schema validator — the same
+ * mechanism `McpServer.registerTool()`'s high-level helper uses internally, borrowed here because
+ * `createMcpToolServer` is built on the SDK's low-level `Server.setRequestHandler` instead (see
+ * `tool-server.ts`'s module doc), which does not validate a tool's declared `inputSchema` against
+ * arguments before its handler runs. One provider instance is reused across every tool: it holds no
+ * per-schema state itself (see {@link compiledValidators} for the actual compiled-validator cache).
+ */
+const schemaValidatorProvider = new CfWorkerJsonSchemaValidator();
+/**
+ * Compiling a validator from a schema is real work `CfWorkerJsonSchemaValidator` does not cache
+ * internally (per its own doc), so it is cached here per `McpToolDef` instance — stable for a
+ * server's whole lifetime, since tool defs are created once at module load and never rebuilt.
+ */
+const compiledValidators = new WeakMap();
+function validatorForTool(tool) {
+    const cached = compiledValidators.get(tool);
+    if (cached)
+        return cached;
+    const validator = schemaValidatorProvider.getValidator(tool.inputSchema);
+    compiledValidators.set(tool, validator);
+    return validator;
+}
+/**
+ * `tools/call` dispatch: looks up `name` in `tools`, validates `rawArgs` against the tool's
+ * declared `inputSchema`, runs its handler, and converts the outcome to a `CallToolResult` — an
+ * unknown tool name, a schema violation, or a thrown error all produce an `{isError:true}` result
+ * rather than rejecting, matching MCP's convention that tool failures are protocol-level results,
+ * not JSON-RPC errors. Schema validation runs before every handler unconditionally: a caller (an
+ * agent, not this repo's own code) supplies `rawArgs`, so a handler must never be trusted to check
+ * its own declared contract on the untrusted-input path. Both a validation failure's message and a
+ * thrown error's message are passed through {@link sanitizeUntrustedText} before reaching the
+ * result: either can end up echoing caller- or daemon-supplied text, and it is cheaper to sanitize
+ * unconditionally than to prove which call site needs it.
  */
 export async function handleToolCall(name, rawArgs, tools, ctx) {
     const tool = tools.get(name);
     if (tool === undefined) {
         return errorResult(`unknown tool: ${name}`);
     }
+    const args = rawArgs ?? {};
+    // Validation gets its own error boundary, separate from the handler's below. The
+    // validator does not only return `{valid:false}` for a bad argument — `@cfworker/json-schema`
+    // *throws* for JavaScript values JSON cannot encode (an explicitly-`undefined` optional
+    // property yields `Instances of "undefined" type are not supported.`). Compiling the
+    // validator can throw too, on a malformed `inputSchema`. Either escaping would break this
+    // function's whole contract, that a schema violation is an `{isError:true}` result and never
+    // a rejection — and `handleToolCall` is exported, typed `Record<string, unknown>`, and
+    // callable directly by a host, so this is reachable and not merely theoretical.
+    let validatedArgs;
+    try {
+        const validation = validatorForTool(tool)(args);
+        if (!validation.valid) {
+            return errorResult(sanitizeUntrustedText(`invalid arguments for ${name}: ${validation.errorMessage}`));
+        }
+        validatedArgs = validation.data;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return errorResult(sanitizeUntrustedText(`invalid arguments for ${name}: ${message}`));
+    }
     try {
-        const result = await tool.handler(rawArgs ?? {}, ctx);
+        const result = await tool.handler(validatedArgs, ctx);
         return okResult(result);
     }
     catch (err) {

package/dist/server/tool-protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-protocol.js","sourceRoot":"","sources":["../../src/server/tool-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AA2BrD,oHAAoH;AACpH,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACtF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC;AAED,mMAAmM;AACnM,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,IAAY;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,wBAAwB,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAC,KAA4B;IACtD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC,CAAC,CAAC;AACN,CAAC;AAED,mOAAmO;AACnO,MAAM,UAAU,cAAc,CAAC,KAA4B;IACzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,OAA4C,EAC5C,KAAsC,EACtC,GAAmB;IAEnB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,WAAW,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QACtD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,WAAW,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,CAAC;AACH,CAAC"}
+{"version":3,"file":"tool-protocol.js","sourceRoot":"","sources":["../../src/server/tool-protocol.ts"],"names":[],"mappings":"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"}

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

@@ -77,6 +77,12 @@ export interface McpToolServerOptions {
     readonly idleMs?: number;
     /** Defaults to the global `fetch`; threaded into every tool call's {@link McpToolContext}. */
     readonly fetchImpl?: typeof fetch;
+    /**
+     * Headers attached to every daemon call this server's tools and resources make — in practice the
+     * bearer credential the spawning daemon issued for this run. Omit for a daemon whose `/api` surface
+     * does not require one; omitting is the pre-existing behavior.
+     */
+    readonly authHeaders?: Readonly<Record<string, string>>;
     /** Defaults to `process.stdin`; inject for tests (or an alternate stdio pair). */
     readonly stdin?: Readable;
     /** Defaults to `process.stdout`; inject for tests. */

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

@@ -1 +1 @@
-{"version":3,"file":"tool-server.d.ts","sourceRoot":"","sources":["../../src/server/tool-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-server.d.ts","sourceRoot":"","sources":["../../src/server/tool-server.ts"],"names":[],"mappings":"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"}

package/dist/server/tool-server.js

@@ -31,6 +31,7 @@ export function createMcpToolServer(options) {
             const ctx = {
                 baseUrl: String(resolvedBaseUrl).replace(/\/$/, ''),
                 fetchImpl: options.fetchImpl ?? fetch,
+                ...(options.authHeaders !== undefined ? { authHeaders: options.authHeaders } : {}),
             };
             let closeTransportForIdle = null;
             const idleExit = createMcpIdleExitController({

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

@@ -1 +1 @@
-{"version":3,"file":"tool-server.js","sourceRoot":"","sources":["../../src/server/tool-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-server.js","sourceRoot":"","sources":["../../src/server/tool-server.ts"],"names":[],"mappings":"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"}

package/dist/server/tools/component-catalog-tools.d.ts

@@ -0,0 +1,8 @@
+import { type McpToolDef } from '../tool-protocol.js';
+/** `search_components` -> `GET /api/components/search` (`packages/http-kit/src/component-catalog.ts`'s `componentCatalogSearchRoute`). */
+export declare const searchComponentsTool: McpToolDef;
+/** `describe_component` -> `GET /api/components/:id` (`packages/http-kit/src/component-catalog.ts`'s `componentCatalogDescribeRoute`). */
+export declare const describeComponentTool: McpToolDef;
+/** Both component-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */
+export declare const COMPONENT_CATALOG_TOOLS: readonly McpToolDef[];
+//# sourceMappingURL=component-catalog-tools.d.ts.map

package/dist/server/tools/component-catalog-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-catalog-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/component-catalog-tools.ts"],"names":[],"mappings":"AAaA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAkBxF,0IAA0I;AAC1I,eAAO,MAAM,oBAAoB,EAAE,UAkClC,CAAC;AAEF,0IAA0I;AAC1I,eAAO,MAAM,qBAAqB,EAAE,UAiBnC,CAAC;AAEF,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,EAAE,SAAS,UAAU,EAAkD,CAAC"}

package/dist/server/tools/component-catalog-tools.js

@@ -0,0 +1,71 @@
+/**
+ * @module @jini-ai/mcp/server/tools/component-catalog-tools
+ *
+ * `search_components` / `describe_component` — the agent-facing discovery half of the
+ * interactive-UI loop, proxying `@jini-ai/http-kit`'s `GET /api/components/search` /
+ * `GET /api/components/:id` exactly as `tool-catalog-tools.ts` proxies `tool-catalog.ts`.
+ *
+ * This does not tell the agent how to render anything, only what's registered and its
+ * `propsSchema` — an agent still composes an A2UI or MCP-UI message naming the id and props; the
+ * host resolves and mounts it. Finding a component id here grants nothing, same posture as the
+ * tool catalog's discovery-is-not-permission stance.
+ */
+import { getDaemonJson } from '../daemon-client.js';
+import { daemonCallOptions, requireString } from '../tool-protocol.js';
+const READ_ANNOTATIONS = {
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+/** `search_components` -> `GET /api/components/search` (`packages/http-kit/src/component-catalog.ts`'s `componentCatalogSearchRoute`). */
+export const searchComponentsTool = {
+    name: 'search_components',
+    description: 'Search the registered interactive-UI component catalog. Returns ranked {id, provider, capabilities, description, score} candidates only — no propsSchema, so this stays cheap to call broadly. Call describe_component on the 1-3 candidates that look right before composing an A2UI or MCP-UI message that names one. Describe what interaction or data shape you need, not a component class name — e.g. "tabular list of records the user can click into" rather than "table".',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Describe the interaction or data shape you need, in plain language — what the user should see and do, not a component name. Example: "let the user pick one date from a range" rather than "DatePicker". Required.',
+            },
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 25,
+                description: 'Max hits to return (1-25). Optional, defaults to 10.',
+            },
+        },
+        required: ['query'],
+        additionalProperties: false,
+    },
+    annotations: { ...READ_ANNOTATIONS, title: 'Search the interactive-UI component catalog' },
+    handler: async (args, ctx) => {
+        requireString(args.query, 'query');
+        const params = new URLSearchParams({ q: args.query });
+        if (typeof args.limit === 'number')
+            params.set('limit', String(args.limit));
+        const data = await getDaemonJson(ctx.baseUrl, `/api/components/search?${params.toString()}`, daemonCallOptions(ctx));
+        return data.hits;
+    },
+};
+/** `describe_component` -> `GET /api/components/:id` (`packages/http-kit/src/component-catalog.ts`'s `componentCatalogDescribeRoute`). */
+export const describeComponentTool = {
+    name: 'describe_component',
+    description: 'Get the full descriptor for one component id found via search_components — provider, capabilities, and propsSchema. Paid for only on the candidates that survive search.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: 'Component id returned by search_components. Required.' },
+        },
+        required: ['id'],
+        additionalProperties: false,
+    },
+    annotations: { ...READ_ANNOTATIONS, title: 'Describe an interactive-UI component' },
+    handler: async (args, ctx) => {
+        requireString(args.id, 'id');
+        return getDaemonJson(ctx.baseUrl, `/api/components/${encodeURIComponent(args.id)}`, daemonCallOptions(ctx));
+    },
+};
+/** Both component-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */
+export const COMPONENT_CATALOG_TOOLS = [searchComponentsTool, describeComponentTool];
+//# sourceMappingURL=component-catalog-tools.js.map

package/dist/server/tools/component-catalog-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-catalog-tools.js","sourceRoot":"","sources":["../../../src/server/tools/component-catalog-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAExF,MAAM,gBAAgB,GAAG;IACvB,YAAY,EAAE,IAAI;IAClB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACZ,CAAC;AAYX,0IAA0I;AAC1I,MAAM,CAAC,MAAM,oBAAoB,GAAe;IAC9C,IAAI,EAAE,mBAAmB;IACzB,WAAW,EACT,odAAod;IACtd,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,oNAAoN;aACvN;YACD,KAAK,EAAE;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,sDAAsD;aACpE;SACF;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE,EAAE,GAAG,gBAAgB,EAAE,KAAK,EAAE,6CAA6C,EAAE;IAC1F,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC3B,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACtD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,aAAa,CAC9B,GAAG,CAAC,OAAO,EACX,0BAA0B,MAAM,CAAC,QAAQ,EAAE,EAAE,EAC7C,iBAAiB,CAAC,GAAG,CAAC,CACvB,CAAC;QACF,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF,CAAC;AAEF,0IAA0I;AAC1I,MAAM,CAAC,MAAM,qBAAqB,GAAe;IAC/C,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EACT,0KAA0K;IAC5K,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uDAAuD,EAAE;SAC7F;QACD,QAAQ,EAAE,CAAC,IAAI,CAAC;QAChB,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE,EAAE,GAAG,gBAAgB,EAAE,KAAK,EAAE,sCAAsC,EAAE;IACnF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC3B,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,mBAAmB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9G,CAAC;CACF,CAAC;AAEF,uGAAuG;AACvG,MAAM,CAAC,MAAM,uBAAuB,GAA0B,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}

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

@@ -1,15 +1,87 @@
 import { type McpToolDef } from '../tool-protocol.js';
+/**
+ * Request deadline for one delegated tool call, 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
+ * on a *person*: a tool that raises an MCP-UI surface parks until the human answers it, and a human
+ * reading a dialog does not answer in fifteen seconds. Left at the default, every human-in-the-loop
+ * tool call fails at 15 s regardless of what the human eventually clicks.
+ *
+ * Six minutes is a *backstop*, not a budget. It assumes the host runs a tighter total-lifetime
+ * ceiling on the exchange itself, which ends the call with an explicit "no answer" outcome first;
+ * the extra headroom here just guarantees the exchange is always what gives up. Six minutes also
+ * stays inside every measured agent-CLI ceiling (Claude Code 30 min idle, Gemini CLI 10 min),
+ * which is what keeps this hop from becoming the binding constraint.
+ *
+ * A host whose exchange ceiling differs should override it via `delegatedToolTimeoutMs` rather
+ * than have its number encoded here — the engine has no way to know a given host's exchange
+ * policy, and hard-coding one host's value in generic engine source is what this default replaced.
+ *
+ * This is also, transitively, the hard cap on a multi-turn human conversation driven from one tool
+ * call: however many turns an exchange takes, they all happen inside this one request. Raising that
+ * ceiling starts here, not in the exchange store.
+ *
+ * The cost is real and accepted: a genuinely hung daemon now hangs this call for six minutes rather
+ * 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 interface CreateExecuteDelegatedToolToolOptions {
     /** The one run this MCP server process — and therefore this tool instance — is scoped to. */
     readonly runId: string;
     /** Generates each call's `toolUseId`. @default node:crypto randomUUID */
     readonly generateToolUseId?: () => 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.
+     *
+     * 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)
+     */
+    readonly delegatedToolTimeoutMs?: number;
 }
 /**
  * Builds the `execute_delegated_tool` tool def for one specific `runId`. A fresh MCP server
  * process (one per spawned `claude` run, see `../../bin/serve.js`) calls this once at startup;
  * every `tools/call` for the returned def's `name` during that process's lifetime executes
  * against the same run.
+ *
+ * Declares `readOnlyHint: false`, which is the truth about a gateway that reaches the entire
+ * registry — reads and writes alike. See {@link createExecuteReadonlyDelegatedToolTool} for what
+ * that costs under a host that gates on the annotation, and for the companion that answers it.
  */
 export declare function createExecuteDelegatedToolTool(options: CreateExecuteDelegatedToolToolOptions): McpToolDef;
+/**
+ * Builds the `execute_readonly_delegated_tool` companion for one specific `runId` — the same
+ * gateway, narrowed to tools whose registration declares them read-only, and annotated
+ * `readOnlyHint: true`.
+ *
+ * WHY IT EXISTS. `execute_delegated_tool` is the sole route from an externally-injected MCP client
+ * into this host's entire native tool catalog, and it correctly annotates itself
+ * `readOnlyHint: false`. A runtime that auto-denies any MCP tool lacking `readOnlyHint: true`
+ * (headless `codex exec`, observed) therefore kills 100% of delegated calls — reads included —
+ * before they leave the client process. Nothing reaches the daemon, so no execution row is written
+ * and no error surfaces; the model, given no grounding signal at all, narrates a tool call that
+ * never happened. Meanwhile `search_tools`/`describe_tool` work, so discovery succeeds and only
+ * execution silently dies, which is the worst possible shape for the failure.
+ *
+ * WHY IT ENFORCES RATHER THAN ASSERTS. MCP annotations are static per tool declaration — the
+ * protocol has no way to vary one per call — so a read-only surface can only be a SECOND
+ * declaration, never a mode of the first. And a tool that declared `readOnlyHint: true` while
+ * still reaching writes would be worse than the bug it fixes: it would launder a write past a
+ * caller's own safety gate, and that caller has no way to audit the claim. The check is therefore
+ * made where it can be a fact rather than a claim — the daemon, via
+ * `@jini-ai/http-kit`'s `requireReadOnly`, resolving the id against the live `ToolRegistry` and
+ * `@jini-ai/core`'s `isReadOnlyTool`. Refusal is deny-by-default: an id that is unregistered, or
+ * registered without a read-only classification, is refused with a message naming the tool and
+ * pointing at `execute_delegated_tool`.
+ *
+ * Flipping the existing tool's annotation instead was rejected for the same reason: it would lie to
+ * every caller, including the ones the annotation exists to protect.
+ */
+export declare function createExecuteReadonlyDelegatedToolTool(options: CreateExecuteDelegatedToolToolOptions): McpToolDef;
 //# sourceMappingURL=delegated-tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"delegated-tool.d.ts","sourceRoot":"","sources":["../../../src/server/tools/delegated-tool.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAOrE,MAAM,WAAW,qCAAqC;IACpD,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,qCAAqC,GAAG,UAAU,CAuDzG"}
+{"version":3,"file":"delegated-tool.d.ts","sourceRoot":"","sources":["../../../src/server/tools/delegated-tool.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAmCxF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,iCAAiC,QAAgB,CAAC;AAE/D,MAAM,WAAW,qCAAqC;IACpD,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;IAC1C;;;;;;;;;OASG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AA6FD;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,qCAAqC,GAAG,UAAU,CAYzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sCAAsC,CAAC,OAAO,EAAE,qCAAqC,GAAG,UAAU,CAgBjH"}