@jini-ai/mcp 0.4.3 → 0.4.4

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

@@ -1,6 +1,60 @@
+/**
+ * @module @jini-ai/mcp/server/tool-protocol
+ *
+ * The pure, SDK-connection-free half of the MCP tool-hosting mechanism: the
+ * `McpToolDef` contract a caller registers tools against, `tools/list`
+ * projection, and `tools/call` dispatch (look up a tool by name, run its
+ * handler, wrap the result). None of this touches `@modelcontextprotocol/sdk`'s
+ * `Server`/transport classes or the network — a tool `handler` is just
+ * `({ args, ctx }) => value | Promise<value>` that either returns a
+ * 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. It is also how a **human-confirmation token reached model-visible
+ * text** in a separate, traced incident ( Decision 5): a `resource` block carrying the token
+ * fell to the same stringify path because an earlier version of this fix only recognized `text` and
+ * `image`, and `resource` was not yet in that hand-rolled allowlist.
+ *
+ * {@link okResult} now recognizes a `content` array whose every entry validates against the pinned
+ * `@modelcontextprotocol/sdk`'s own `ContentBlockSchema` — the same union the SDK itself defines
+ * `CallToolResultSchema.content` against — and passes such an envelope through verbatim instead of
+ * stringifying it. Deferring to the SDK's schema rather than re-implementing a per-type shape check
+ * here means every block type the pinned protocol version defines (`text`, `image`, `audio`,
+ * `resource`, `resource_link` as of `@modelcontextprotocol/sdk@^1.29.0`) is recognized automatically,
+ * and a future SDK upgrade that adds another block type is picked up the same way, without another
+ * hand-edit to this module. Whitelist, not blacklist: a `content` array holding even one entry that
+ * does not validate falls back to the stringify path, so a malformed block is never forwarded as if it
+ * were valid protocol output. What this does **not** guarantee: a block type the pinned SDK does not
+ * yet know about (a real future MCP protocol addition ahead of this dependency) still falls back to
+ * stringify until the SDK dependency itself is upgraded — this fix converts "remember to update this
+ * allowlist" into "remember to bump the SDK", not into an unconditional guarantee. It also does not
+ * (and cannot) judge intent: a handler that puts a secret inside an otherwise well-formed `text` block
+ * will still have it pass through as designed — withholding a value from the model is the handler's
+ * responsibility ( Decision 4), not this generic wrapper's.
+ * See docs/decisions/DR-002-protocol-resource-boundary.md.
+ */
+import { type ToolDescriptor } from '@jini-ai/core';
 import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import { type McpToolArgumentContract } from './tool-arguments.js';
 /** What every tool handler receives alongside its parsed arguments. */
 export interface McpToolContext {
+    /** Publishes a successfully described, host-owned descriptor in this server run only. */
+    readonly publishTool?: (required: {
+        descriptor: ToolDescriptor;
+    }, optional?: Record<string, never>) => Promise<void>;
+    /** Host registration metadata, supplied outside model-controlled arguments. */
+    readonly diagnosticToolIds?: readonly string[];
     /** The resolved daemon HTTP base URL (no trailing slash), fixed for the lifetime of one server run. */
     readonly baseUrl: string;
     /** Defaults to the global `fetch`; threaded through so a host can inject its own (e.g. for tests). */
@@ -42,6 +96,7 @@ export declare function daemonCallOptions({ ctx }: {
     fetchImpl: typeof fetch;
     headers?: Record<string, string>;
     signal?: AbortSignal;
+    diagnosticToolIds?: readonly string[];
 };
 /**
  * One MCP tool a `createMcpToolServer` caller registers. `name` must be unique within a given
@@ -51,10 +106,9 @@ export declare function daemonCallOptions({ ctx }: {
  * `CallToolResult` shape by {@link handleToolCall}, so individual tools never construct MCP
  * protocol objects themselves.
  */
-export interface McpToolDef<Args extends Record<string, unknown> = Record<string, unknown>> {
+export interface McpToolDef<Args extends Record<string, unknown> = Record<string, unknown>> extends McpToolArgumentContract {
     readonly name: string;
     readonly description: string;
-    readonly inputSchema: Tool['inputSchema'];
     readonly annotations?: Tool['annotations'];
     readonly handler: (requiredArgs: {
         args: Args;
@@ -62,7 +116,7 @@ export interface McpToolDef<Args extends Record<string, unknown> = Record<string
     }) => Promise<unknown> | unknown;
 }
 /**
- * Wraps a successful tool result as an MCP `CallToolResult`.
+ * Wraps a tool result as an MCP `CallToolResult`, preserving explicit errors and failed batch outcomes.
  *
  * 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 — `image`, `resource`, or any
@@ -72,7 +126,7 @@ export interface McpToolDef<Args extends Record<string, unknown> = Record<string
  * JSON-stringified (compact, no indentation) into one.
  *
  * @complexity O(n) in the number of content-array entries, only when `payload` already looks like an
- * envelope; O(1) otherwise.
+ * envelope or batch; O(1) otherwise.
  */
 export declare function okResult({ payload }: {
     payload: unknown;
@@ -95,7 +149,8 @@ export declare function buildToolIndex({ tools }: {
     tools: readonly McpToolDef[];
 }): Map<string, McpToolDef>;
 /**
- * `tools/call` dispatch: looks up `name` in `tools`, validates `rawArgs` against the tool's
+ * `tools/call` dispatch: looks up `name` in `tools`, normalizes aliases/wrapper input, then
+ * validates the canonical arguments 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,
@@ -103,8 +158,8 @@ export declare function buildToolIndex({ tools }: {
  * 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.
+ * result: either can end up echoing caller- or daemon-supplied text. The validation prefix uses the
+ * registered tool name outside sanitization so long gateway names are not mistaken for secrets.
  */
 export declare function handleToolCall({ name, tools, ctx }: {
     name: string;

package/dist/server/tool-protocol.js

@@ -44,9 +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 { sanitizeUntrustedText } from '@jini-ai/core/text';
-import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker';
+import { Validator } from '@cfworker/json-schema';
 import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
+import { argumentShapeMessage, isRecord, normalizeToolArguments } from './tool-arguments.js';
 /**
  * Maps a tool context onto the `DaemonRequestOptions` every daemon call needs.
  *
@@ -64,13 +66,11 @@ import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
 export function daemonCallOptions({ ctx }) {
     return {
         fetchImpl: ctx.fetchImpl,
+        ...(ctx.diagnosticToolIds !== undefined ? { diagnosticToolIds: ctx.diagnosticToolIds } : {}),
         ...(ctx.authHeaders !== undefined ? { headers: { ...ctx.authHeaders } } : {}),
         ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
     };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /**
  * True when `block` is a well-formed MCP content block this module will pass through verbatim rather
  * than JSON-stringify. Delegates to the pinned `@modelcontextprotocol/sdk`'s own `ContentBlockSchema`
@@ -101,7 +101,7 @@ function isMcpContentEnvelope(payload) {
     return Array.isArray(content) && content.every(isPassthroughContentBlock);
 }
 /**
- * Wraps a successful tool result as an MCP `CallToolResult`.
+ * Wraps a tool result as an MCP `CallToolResult`, preserving explicit errors and failed batch outcomes.
  *
  * 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 — `image`, `resource`, or any
@@ -111,17 +111,20 @@ function isMcpContentEnvelope(payload) {
  * JSON-stringified (compact, no indentation) into one.
  *
  * @complexity O(n) in the number of content-array entries, only when `payload` already looks like an
- * envelope; O(1) otherwise.
+ * envelope or batch; O(1) otherwise.
  */
 export function okResult({ payload }) {
+    const outcome = batchOutcomeFor({ output: payload });
+    const isError = (typeof payload === 'object' && payload !== null && 'isError' in payload && payload.isError === true)
+        || outcome === 'partial_failure' || outcome === 'error';
     if (isMcpContentEnvelope(payload)) {
-        return { content: payload.content };
+        return { content: payload.content, ...(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
     // `formatToolOutputForDisplay`).
     const text = typeof payload === 'string' ? payload : JSON.stringify(payload);
-    return { content: [{ type: 'text', text }] };
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
 }
 /** Wraps a tool failure as an MCP `isError` result. */
 export function errorResult({ message }) {
@@ -154,31 +157,22 @@ export function buildToolIndex({ tools }) {
     }
     return index;
 }
-/**
- * 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.
- */
+/** Compiled schemas are reused for each stable tool definition, as in the SDK provider. */
 const compiledValidators = new WeakMap();
+/** Returns the cached validator, retaining structured field locations for recovery instructions. */
 function validatorForTool(tool) {
     const cached = compiledValidators.get(tool);
     if (cached)
         return cached;
-    const validator = schemaValidatorProvider.getValidator(tool.inputSchema);
+    // The validator adds internal URI fields while compiling. F0's published schemas are frozen;
+    // compile a detached copy so validation cannot mutate the immutable wire contract.
+    const validator = new Validator(structuredClone(tool.inputSchema), '2020-12', true);
     compiledValidators.set(tool, validator);
     return validator;
 }
 /**
- * `tools/call` dispatch: looks up `name` in `tools`, validates `rawArgs` against the tool's
+ * `tools/call` dispatch: looks up `name` in `tools`, normalizes aliases/wrapper input, then
+ * validates the canonical arguments 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,
@@ -186,34 +180,30 @@ function validatorForTool(tool) {
  * 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.
+ * result: either can end up echoing caller- or daemon-supplied text. The validation prefix uses the
+ * registered tool name outside sanitization so long gateway names are not mistaken for secrets.
  */
 export async function handleToolCall({ name, tools, ctx }, { rawArgs } = {}) {
+    const diagnosticToolIds = [...tools.keys(), ...(ctx.diagnosticToolIds ?? [])];
+    ctx = { ...ctx, diagnosticToolIds };
     const tool = tools.get(name);
     if (tool === undefined) {
         return errorResult({ message: `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.
+    // Normalization and schema validation share an error boundary; handlers run only afterward.
+    // See docs/decisions/DR-005-proxy-argument-shapes.md.
     let validatedArgs;
     try {
-        const validation = validatorForTool(tool)(args);
+        const args = normalizeToolArguments({ tool, rawArgs: rawArgs ?? {} });
+        const validation = validatorForTool(tool).validate(args);
         if (!validation.valid) {
-            return errorResult({ message: sanitizeUntrustedText({ text: `invalid arguments for ${name}: ${validation.errorMessage}` }) });
+            return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: argumentShapeMessage({ errors: validation.errors }) }, { diagnosticToolIds })}` });
         }
-        validatedArgs = validation.data;
+        validatedArgs = args;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return errorResult({ message: sanitizeUntrustedText({ text: `invalid arguments for ${name}: ${message}` }) });
+        return errorResult({ message: `invalid arguments for ${tool.name}: ${sanitizeUntrustedText({ text: message }, { diagnosticToolIds })}` });
     }
     try {
         const result = await tool.handler({ args: validatedArgs, ctx: ctx });
@@ -221,7 +211,7 @@ export async function handleToolCall({ name, tools, ctx }, { rawArgs } = {}) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return errorResult({ message: sanitizeUntrustedText({ text: message }) });
+        return errorResult({ message: sanitizeUntrustedText({ text: message }, { diagnosticToolIds }) });
     }
 }
 //# sourceMappingURL=tool-protocol.js.map

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

@@ -7,6 +7,7 @@
  * with nominal private fields; default adapters translate those contracts to the real SDK.
  */
 import type { Readable, Writable } from 'node:stream';
+import { type ToolDescriptor } from '@jini-ai/core';
 import type { McpTransportLike } from './ports.js';
 export type { McpTransportLike } from './ports.js';
 import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
@@ -14,6 +15,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 import type { CallToolResult, Implementation, ListResourcesResult, ListToolsResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
 import { type McpResourceDef } from './resource-protocol.js';
 import { type McpToolDef } from './tool-protocol.js';
+import { type CreateExecuteDelegatedToolToolOptions } from './tools/delegated-tool.js';
 /** Object-shaped server port. The default adapter translates it to the SDK interface. */
 export interface McpServerLike {
     setRequestHandler(args: {
@@ -52,6 +54,8 @@ export interface McpServerLike {
     connect(args: {
         transport: McpTransportLike;
     }): Promise<void>;
+    /** Optional for static embeddings; required when delegated publication is enabled. */
+    sendToolListChanged?(required: Record<string, never>, optional?: Record<string, never>): Promise<void>;
 }
 /** Required identity, tool surface, and daemon URL resolver. */
 export interface McpToolServerRequiredArgs {
@@ -64,6 +68,10 @@ export interface McpToolServerRequiredArgs {
     readonly resolveBaseUrl: () => Promise<string> | string;
 }
 export interface McpToolServerOptions {
+    /** Opt in to bounded, per-run typed publication after describe_tool. */
+    readonly delegatedTools?: McpDelegatedToolsOptions;
+    /** Trusted daemon registration IDs carried into every error sanitizer. */
+    readonly diagnosticToolIds?: readonly string[];
     /** The bounded, explicit read-only resource list this server hosts. Duplicate uris throw at construction time. Omit (or pass an empty array) for a tools-only server — `capabilities.resources` is only advertised when this is non-empty. */
     readonly resources?: readonly McpResourceDef[];
     /** Free-text guidance surfaced to the MCP client alongside the tool list. Optional — omit for a caller with nothing to add beyond each tool's own `description`. */
@@ -93,6 +101,17 @@ export interface McpToolServerOptions {
         stdout?: Writable;
     }) => McpTransportLike;
 }
+/** The admitted host descriptors supplied here must come from the existing registry/catalog.
+ * Publication never connects to a federated server or admits its upstream list changes.
+ */
+export interface McpDelegatedToolsOptions extends CreateExecuteDelegatedToolToolOptions {
+    readonly runId: string;
+    /** Resolve these through the authenticated daemon before running a client without refresh. */
+    readonly initialTools?: readonly ToolDescriptor[];
+    /** Defaults to F0's 64 tools and 256 KiB of schemas; new entries are skipped at the cap. */
+    readonly maxTools?: number;
+    readonly maxSchemaBytes?: number;
+}
 export interface McpToolServerHandle {
     /**
      * Resolves the daemon base URL, connects the MCP server to its transport, and holds the process

package/dist/server/tool-server.js

@@ -1,3 +1,4 @@
+import { createToolExposure } from '@jini-ai/core';
 import { adaptSdkTransport, resolveSdkTransport } from './sdk-transport.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -5,6 +6,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 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';
 /** Auto-exit an idle server after this long without tool activity. */
 const DEFAULT_IDLE_MS = 30 * 60 * 1000;
 // SDK objects remain behind these adapters; hosts implement the object-shaped ports above.
@@ -13,11 +15,84 @@ function defaultCreateServer({ info, options }) {
     return {
         setRequestHandler: (({ schema, handler }) => server.setRequestHandler(schema, (request, extra) => handler({ request }, { extra }))),
         connect: ({ transport }) => server.connect(resolveSdkTransport({ transport })),
+        sendToolListChanged: () => server.sendToolListChanged(),
     };
 }
 function defaultCreateTransport(_requiredArgs, { stdin, stdout } = {}) {
     return adaptSdkTransport({ transport: new StdioServerTransport(stdin, stdout) });
 }
+/**
+ * The tool context shared by every call in one run: the resolved daemon URL without its trailing
+ * slash (coerced to a string for JS hosts that ignore the contract), the configured or global
+ * `fetch`, and the auth headers and diagnostic IDs only when configured.
+ */
+function buildToolContext({ resolvedBaseUrl }, options) {
+    return {
+        ...(options.diagnosticToolIds !== undefined ? { diagnosticToolIds: options.diagnosticToolIds } : {}),
+        baseUrl: String(resolvedBaseUrl).replace(/\/$/, ''),
+        fetchImpl: options.fetchImpl ?? fetch,
+        ...(options.authHeaders !== undefined ? { authHeaders: options.authHeaders } : {}),
+    };
+}
+/** The stdio pair handed to `createTransport`, carrying only the streams the caller configured. */
+function stdioOptions(options) {
+    return {
+        ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+        ...(options.stdout === undefined ? {} : { stdout: options.stdout }),
+    };
+}
+/**
+ * Own only the MCP projection/dispatch index. F0 owns immutable exposure, and the daemon catalog
+ * supplies each descriptor; the temporary source below is not another definition catalog.
+ * @returns An install-before-notify publisher, or undefined for a static server.
+ * @throws On malformed schemas, invalid exposure limits, or an embedding without notification support.
+ * @complexity O(n + s) per promotion for n bounded exposed tools and s schema bytes; no daemon I/O.
+ */
+function createToolPublisher({ index, server, options }) {
+    if (!options)
+        return undefined;
+    const notify = server.sendToolListChanged?.bind(server);
+    if (!notify)
+        throw new Error('delegated publication requires tools/list_changed support');
+    let descriptors = options.initialTools ?? [];
+    const exposure = createToolExposure({ registry: { list: () => descriptors } }, {
+        reservedNames: [...index.keys()],
+        ...(options.maxTools === undefined ? {} : { maxTools: options.maxTools }),
+        ...(options.maxSchemaBytes === undefined ? {} : { maxSchemaBytes: options.maxSchemaBytes }),
+    });
+    // Validate before promotion: malformed descriptors must not consume a pinned name or budget.
+    const validate = (descriptor) => createTypedDelegatedToolTool({ runId: options.runId, tool: { wireName: descriptor.id, descriptor } }, options);
+    for (const descriptor of descriptors)
+        validate(descriptor);
+    const initial = exposure.promote({ toolIds: descriptors.map(descriptor => descriptor.id) });
+    for (const tool of initial.snapshot.tools)
+        index.set(tool.wireName, createTypedDelegatedToolTool({ runId: options.runId, tool }, options));
+    descriptors = [];
+    let notificationPending = false;
+    return async ({ descriptor }, _optional = {}) => {
+        validate(descriptor);
+        descriptors = [descriptor];
+        const delta = exposure.promote({ toolIds: [descriptor.id] });
+        descriptors = [];
+        for (const tool of delta.snapshot.tools) {
+            if (!index.has(tool.wireName))
+                index.set(tool.wireName, createTypedDelegatedToolTool({ runId: options.runId, tool }, options));
+        }
+        if (delta.added.length > 0)
+            notificationPending = true;
+        if (!notificationPending)
+            return;
+        // Clear before awaiting: a concurrent promotion must retain its own unsent notification.
+        notificationPending = false;
+        try {
+            await notify({});
+        }
+        catch (error) {
+            notificationPending = true;
+            throw error;
+        }
+    };
+}
 /**
  * Builds a stdio MCP server hosting `requiredArgs.tools` (and, optionally, `options.resources`).
  * Construction is synchronous and cheap (validates tool-name uniqueness via
@@ -26,35 +101,35 @@ function defaultCreateTransport(_requiredArgs, { stdin, stdout } = {}) {
  * handle's `run()`.
  */
 export function createMcpToolServer(requiredArgs, options = {}) {
-    const toolIndex = buildToolIndex({ tools: requiredArgs.tools });
+    // Validate eagerly, but keep the mutable dispatch index inside run() so re-runs are isolated.
+    buildToolIndex({ tools: requiredArgs.tools });
     const resources = options.resources ?? [];
     const resourceIndex = buildResourceIndex({ resources });
     const createServer = options.createServer ?? defaultCreateServer;
     const createTransport = options.createTransport ?? defaultCreateTransport;
     return {
         async run(_required) {
-            const resolvedBaseUrl = await requiredArgs.resolveBaseUrl();
-            const ctx = {
-                baseUrl: String(resolvedBaseUrl).replace(/\/$/, ''),
-                fetchImpl: options.fetchImpl ?? fetch,
-                ...(options.authHeaders !== undefined ? { authHeaders: options.authHeaders } : {}),
-            };
-            let closeTransportForIdle = null;
-            const idleExit = createMcpIdleExitController({
-                idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
-                onIdle: () => closeTransportForIdle?.(),
-            });
-            const withActivity = (handler) => (...args) => idleExit.trackRequest({ fn: () => handler(...args) });
+            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: {}, ...(resources.length > 0 ? { resources: {} } : {}) },
+                    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 };
+            let closeTransportForIdle = null;
+            const idleExit = createMcpIdleExitController({
+                idleMs: options.idleMs ?? DEFAULT_IDLE_MS,
+                onIdle: () => closeTransportForIdle?.(),
+            });
+            const withActivity = (handler) => (...args) => idleExit.trackRequest({ fn: () => handler(...args) });
             server.setRequestHandler({
                 schema: ListToolsRequestSchema,
-                handler: withActivity(async () => ({ tools: toolsToList({ tools: requiredArgs.tools }) })),
+                handler: withActivity(async () => ({ tools: toolsToList({ tools: [...toolIndex.values()] }) })),
             });
             server.setRequestHandler({
                 schema: CallToolRequestSchema,
@@ -70,10 +145,7 @@ export function createMcpToolServer(requiredArgs, options = {}) {
                     handler: withActivity(async ({ request }) => handleResourceRead({ uri: request.params.uri, resources: resourceIndex, ctx })),
                 });
             }
-            const transport = createTransport({}, {
-                ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
-                ...(options.stdout === undefined ? {} : { stdout: options.stdout }),
-            });
+            const transport = createTransport({}, stdioOptions(options));
             try {
                 closeTransportForIdle = () => {
                     void transport.close({}).catch(() => { });

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

@@ -1,3 +1,39 @@
+/**
+ * @module @jini-ai/mcp/server/tools/delegated-tool
+ *
+ * `execute_delegated_tool` and its read-only companion `execute_readonly_delegated_tool` — the
+ * MCP-callback half of gap 3's continuation transport (see
+ * `packages/daemon/archived provenance ledger`'s "run/chat orchestration gap 3, part 1" addition and this
+ * package's own dated section in `archived provenance ledger` for the rest of the spike). The swarm-consensus
+ * Final Recommendation asked for exactly this: "inject the already-shipped MCP host into one
+ * MCP-capable CLI's launch config, prove a tool round-trip through the existing
+ * `delegated-tool-bridge.ts`." Where `../tools/run-tools.js`'s tools proxy generic
+ * run-lifecycle HTTP endpoints, this tool proxies the new `POST /api/delegated-tool-calls`
+ * daemon route (`packages/http/src/delegated-tools.ts`), which is the one and only thing that
+ * calls into `createDelegatedToolBridge` (`packages/daemon/src/delegated-tool-bridge.ts`) — the
+ * same `ToolExecutor` deny-by-default gate every other tool-execution path in this codebase
+ * already uses. No parallel authorization mechanism is introduced anywhere on this path.
+ *
+ * Unlike every other tool this package ships (`run-tools.ts`'s five tools, plain static
+ * objects), this one is a **factory**. The MCP server subprocess a `claude` run spawns via
+ * `.mcp.json` (see `../../bin/serve.js`) is scoped to exactly one `runId` for its entire
+ * lifetime — the daemon injected that run id into the subprocess's own environment at spawn
+ * time, before the model ever said a word. `runId` is therefore closed over at construction
+ * time, not accepted as a per-call tool argument: a model has no legitimate way to pick, or
+ * need to know, which run it is currently inside, and letting it supply one would open a
+ * confused-deputy path (one run's MCP subprocess executing a tool call "as" a different run).
+ * `toolUseId` is likewise generated per call (`randomUUID` by default), not model-supplied — a
+ * model has no legitimate reason to choose its own correlation id either.
+ *
+ * TWO defs, ONE code path. `createDelegatedGateway` builds both; the factories differ only in the
+ * name/title/description they present and in whether the request carries `requireReadOnly: true`.
+ * The read-only companion exists because MCP annotations are static per tool declaration — a
+ * surface that promises "this only reads" can only be a second declaration, never a per-call mode —
+ * and it ENFORCES that promise daemon-side rather than asserting it, because a `readOnlyHint: true`
+ * tool that could still reach writes would launder a write past its caller's own safety gate. See
+ * {@link createExecuteReadonlyDelegatedToolTool} for the failure that motivated it.
+ */
+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.
@@ -87,4 +123,15 @@ export declare function createExecuteDelegatedToolTool(requiredArgs: CreateExecu
  * every caller, including the ones the annotation exists to protect.
  */
 export declare function createExecuteReadonlyDelegatedToolTool(requiredArgs: CreateExecuteDelegatedToolToolRequiredArgs, options?: CreateExecuteDelegatedToolToolOptions): McpToolDef;
+/**
+ * Project a pinned registry descriptor as one concrete MCP tool, reusing the existing gateway.
+ * @param requiredArgs - Trusted run scope and F0's collision-checked, exposed descriptor.
+ * @param options - The same correlation source and deadline used by the legacy wrappers.
+ * @returns A schema-preserving definition; model arguments become only the delegated input.
+ * @throws Error when the descriptor has no MCP object input schema.
+ * @complexity O(s) schema parsing time/space for s schema fields; execution is one daemon call.
+ */
+export declare function createTypedDelegatedToolTool({ runId, tool }: CreateExecuteDelegatedToolToolRequiredArgs & {
+    tool: ExposedToolDescriptor;
+}, options?: CreateExecuteDelegatedToolToolOptions): McpToolDef;
 //# sourceMappingURL=delegated-tool.d.ts.map

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

@@ -33,6 +33,8 @@
  * tool that could still reach writes would launder a write past its caller's own safety gate. See
  * {@link createExecuteReadonlyDelegatedToolTool} for the failure that motivated it.
  */
+import { batchOutcomeFor, isReadOnlyTool } from '@jini-ai/core';
+import { ToolSchema } from '@modelcontextprotocol/sdk/types.js';
 import { randomUUID } from 'node:crypto';
 import { postDaemonJson } from '../daemon-client.js';
 import { daemonCallOptions, requireString } from '../tool-protocol.js';
@@ -42,6 +44,7 @@ function isRecord(value) {
 /**
  * Unwraps a completed delegated call's `{executionId, status, output, ...}` envelope down to just
  * `output` when — and only when — `output` is itself an MCP content envelope (`{content: [...]}`).
+ * Batches expose partial_failure/error and isError while retaining every item.
  * Every other shape (a non-completed status, a plain JSON `output` like a string or a list, no
  * `output` at all) is returned byte-identical to `result` — this is an additive unwrap, not a new
  * general response shape, so the existing "surfaces the result envelope unchanged" contract for an
@@ -57,9 +60,14 @@ function isRecord(value) {
  * block the bridge already preserved.
  */
 function unwrapMcpContentEnvelope(result) {
-    if (!isRecord(result) || result['status'] !== 'completed')
+    if (!isRecord(result))
         return result;
     const output = result['output'];
+    const outcome = batchOutcomeFor({ output });
+    if (outcome === 'partial_failure' || outcome === 'error')
+        return { ...result, status: outcome, outcome, isError: true };
+    if (result['status'] !== 'completed')
+        return result;
     if (!isRecord(output) || !Array.isArray(output['content']))
         return result;
     return output;
@@ -109,7 +117,8 @@ function createDelegatedGateway(variant, { runId }, options) {
         : DEFAULT_DELEGATED_TOOL_TIMEOUT_MS;
     return {
         name: variant.name,
-        description: variant.description,
+        description: `${variant.description} Put the tool's own arguments inside input; non-conflicting top-level tool arguments are moved there automatically.`,
+        argumentNormalization: { foldIntoInput: true },
         inputSchema: {
             type: 'object',
             properties: {
@@ -223,4 +232,28 @@ export function createExecuteReadonlyDelegatedToolTool(requiredArgs, options = {
         requireReadOnly: true,
     }, requiredArgs, options);
 }
+/**
+ * Project a pinned registry descriptor as one concrete MCP tool, reusing the existing gateway.
+ * @param requiredArgs - Trusted run scope and F0's collision-checked, exposed descriptor.
+ * @param options - The same correlation source and deadline used by the legacy wrappers.
+ * @returns A schema-preserving definition; model arguments become only the delegated input.
+ * @throws Error when the descriptor has no MCP object input schema.
+ * @complexity O(s) schema parsing time/space for s schema fields; execution is one daemon call.
+ */
+export function createTypedDelegatedToolTool({ runId, tool }, options = {}) {
+    const { descriptor, wireName } = tool;
+    const inputSchema = ToolSchema.shape.inputSchema.parse(descriptor.inputSchema);
+    const readOnly = isReadOnlyTool({ descriptor });
+    const gateway = readOnly
+        ? createExecuteReadonlyDelegatedToolTool({ runId }, options)
+        : createExecuteDelegatedToolTool({ runId }, options);
+    return {
+        name: wireName,
+        description: descriptor.description ?? descriptor.id,
+        // Parse to check the MCP boundary, but publish the original schema, including extensions.
+        inputSchema: descriptor.inputSchema,
+        annotations: { ...gateway.annotations, title: descriptor.id },
+        handler: ({ args, ctx }) => gateway.handler({ args: { toolId: descriptor.id, input: args }, ctx }),
+    };
+}
 //# sourceMappingURL=delegated-tool.js.map