@jini-ai/mcp 0.4.2 → 0.4.4

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

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

@@ -4,24 +4,40 @@
  * `search_tools` / `describe_tool` — the discovery half of `ai-control-plane.md` §29 /
  * `PROP-tool-catalog-discovery-2026-07-26.md` §6.1, proxying `@jini-ai/http-kit`'s
  * `GET /api/tools/search` / `GET /api/tools/:id` exactly as `run-tools.ts`'s tools proxy
- * `runs.ts` — no separate authorization mechanism, no caching, no state.
+ * `runs.ts` — no separate authorization mechanism or catalog cache.
  *
  * v0 scope: no principal scoping, no versioning, no schema narrowing. Execution is unchanged —
- * a caller still runs a discovered id through `execute_delegated_tool`
- * (`../tools/delegated-tool.js`), which is the only thing that ever reaches `ToolExecutor`.
+ * a caller runs a discovered id through the delegated gateway (`../tools/delegated-tool.js`),
+ * either with its legacy wrapper or a concrete definition published after a successful describe.
+ * Both reach the same `ToolExecutor`.
  * Finding a tool id here grants nothing (`PROP` §6.3).
  */
 import { getDaemonJson } from '../daemon-client.js';
+import { isRecord } from '../tool-arguments.js';
 import { daemonCallOptions, requireString } from '../tool-protocol.js';
 const READ_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
     openWorldHint: false,
 };
+/** Validate the daemon's identity before publishing; discovery cannot substitute another tool.
+ * Unknown risk remains unclassified and therefore cannot claim a read-only annotation.
+ * @complexity O(1); no effects. The schema is checked by the publication boundary.
+ */
+function describedDescriptor({ id, data }) {
+    if (!isRecord(data) || data.id !== id)
+        throw new Error('daemon returned a mismatched tool descriptor');
+    return {
+        id,
+        ...(typeof data.description === 'string' ? { description: data.description } : {}),
+        ...(typeof data.readOnly === 'boolean' ? { readOnly: data.readOnly } : {}),
+        ...(data.inputSchema === undefined ? {} : { inputSchema: data.inputSchema }),
+    };
+}
 /** `search_tools` -> `GET /api/tools/search` (`packages/http/src/tool-catalog.ts`'s `toolCatalogSearchRoute`). */
 export const searchToolsTool = {
     name: 'search_tools',
-    description: 'Search the durable tool catalog. Returns ranked {id, description, source, score} candidates only — no input schemas, so this stays cheap to call broadly. Call describe_tool on the 1-3 candidates that look right before calling execute_delegated_tool. If nothing in the results fits, re-search with a higher limit or different phrasing rather than assuming the tool does not exist.',
+    description: 'Search the durable tool catalog. Returns ranked {id, description, source, score, readOnly, sideEffects} candidates only — no input schemas, so this stays cheap to call broadly. Call describe_tool on the 1-3 candidates that look right before calling execute_delegated_tool. If nothing in the results fits, re-search with a higher limit or different phrasing rather than assuming the tool does not exist.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -80,19 +96,25 @@ export const searchToolsTool = {
 /** `describe_tool` -> `GET /api/tools/:id` (`packages/http/src/tool-catalog.ts`'s `toolCatalogDescribeRoute`). */
 export const describeToolTool = {
     name: 'describe_tool',
-    description: 'Get the full descriptor for one tool id found via search_tools — description and input schema. Paid for only on the candidates that survive search, per the tool catalog\'s staged-discovery design.',
+    description: 'Get the full descriptor for one tool id found via search_tools — description, input schema, readOnly and sideEffects. When dynamic publication is enabled, this also exposes that operation as a concrete tool in tools/list; call it with its own arguments. Legacy fallback: use execute_readonly_delegated_tool only when readOnly is true. Supply id (aliases: toolId or name). Paid for only on the candidates that survive search, per the tool catalog\'s staged-discovery design.',
     inputSchema: {
         type: 'object',
         properties: {
-            id: { type: 'string', description: 'Tool id returned by search_tools. Required.' },
+            id: { type: 'string', description: 'Tool id returned by search_tools. Supply id, toolId, or name.' },
+            toolId: { type: 'string', description: 'Alias of id, matching the delegated-execute wrappers.' },
+            name: { type: 'string', description: 'Alias of id.' },
         },
-        required: ['id'],
+        anyOf: [{ required: ['id'] }, { required: ['toolId'] }, { required: ['name'] }],
         additionalProperties: false,
     },
+    argumentNormalization: { aliases: { toolId: 'id', name: 'id' } },
     annotations: { ...READ_ANNOTATIONS, title: 'Describe a tool' },
     handler: async ({ args, ctx }) => {
         const id = requireString({ value: args.id, name: 'id' });
-        return getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/${encodeURIComponent(id)}` }, daemonCallOptions({ ctx }));
+        const data = await getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/${encodeURIComponent(id)}` }, daemonCallOptions({ ctx }));
+        if (ctx.publishTool)
+            await ctx.publishTool({ descriptor: describedDescriptor({ id, data }) });
+        return data;
     },
 };
 /** Both tool-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */

package/dist/tools/ask-choice/index.d.ts

@@ -1,9 +1,23 @@
-import type { AskChoiceCall, AskChoiceExchangeStore, AskChoiceMessages, AskChoicePendingStore, AskChoicePolicy, AskChoicePresentation } from './types.js';
+import type { AskChoiceCall, AskChoiceExchange, AskChoiceExchangeStore, AskChoiceMessages, AskChoicePendingStore, AskChoicePolicy, AskChoicePresentation, AskChoiceQuestion } from './types.js';
 export type * from './types.js';
 export { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
 export { createAskChoiceAnswerTicketStore } from './pending.js';
 /** Existing callback wire keys; the tool's identity is supplied by the host. */
 export declare const ASK_CHOICE_ANSWER_TICKET_PARAM = "__askChoiceAnswerTicket";
+/** Run a trusted host question through the same abort, delivery, validation and cleanup lifecycle
+ * as the model-facing tool. The host owns presentation and action policy, never exchange mechanics.
+ * @returns Classified human answer, including an offered action when configured.
+ * @complexity O(n) offered options and selections.
+ */
+export declare function askChoice({ exchange, question, toolId, principalId, presentation, signal, messages }: {
+    exchange: AskChoiceExchange;
+    question: AskChoiceQuestion;
+    toolId: string;
+    principalId: string;
+    presentation: Pick<AskChoicePresentation, 'render'>;
+    signal: AbortSignal;
+    messages: AskChoiceMessages;
+}, _options?: {}): Promise<Record<string, unknown>>;
 /** Creates a choice tool without a CMS, renderer, permission system, clock, or global store.
  * The host composes this descriptor/handler into its registry and mounts callbacks against the
  * same exchange and pending stores. Policy and presentation are required, with no product defaults.
@@ -29,15 +43,50 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
         inputSchema: {
             readonly type: "object";
             readonly additionalProperties: false;
-            readonly required: readonly ["title"];
             readonly anyOf: readonly [{
-                readonly required: readonly ["singleSelect"];
+                readonly required: readonly ["question", "options"];
             }, {
-                readonly required: readonly ["multiSelect"];
+                readonly required: readonly ["title", "singleSelect"];
+            }, {
+                readonly required: readonly ["title", "multiSelect"];
             }];
             readonly properties: {
+                readonly question: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "The question to ask the human.";
+                };
+                readonly options: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["label"];
+                        readonly properties: {
+                            readonly label: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly value: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly description: "Defaults to label when omitted.";
+                            };
+                            readonly description: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+                readonly multiple: {
+                    readonly type: "boolean";
+                    readonly description: "Allow several selections. Defaults to false.";
+                };
                 readonly title: {
                     readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Legacy alias: title with singleSelect or multiSelect.";
                 };
                 readonly description: {
                     readonly type: "string";
@@ -46,25 +95,33 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
                     readonly type: "string";
                 };
                 readonly singleSelect: {
+                    readonly description: "Legacy nested single-choice alias.";
                     readonly type: "object";
                     readonly additionalProperties: false;
                     readonly required: readonly ["label", "options"];
                     readonly properties: {
                         readonly label: {
                             readonly type: "string";
+                            readonly minLength: 1;
                         };
                         readonly options: {
                             readonly type: "array";
                             readonly minItems: 1;
                             readonly items: {
+                                readonly required: readonly ["value", "label"];
                                 readonly type: "object";
                                 readonly additionalProperties: false;
-                                readonly required: readonly ["value", "label"];
                                 readonly properties: {
+                                    readonly label: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
                                     readonly value: {
                                         readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly description: "Defaults to label when omitted.";
                                     };
-                                    readonly label: {
+                                    readonly description: {
                                         readonly type: "string";
                                     };
                                 };
@@ -73,25 +130,33 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
                     };
                 };
                 readonly multiSelect: {
+                    readonly description: "Legacy nested multiple-choice alias.";
                     readonly properties: {
                         readonly hint: {
                             readonly type: "string";
                         };
                         readonly label: {
                             readonly type: "string";
+                            readonly minLength: 1;
                         };
                         readonly options: {
                             readonly type: "array";
                             readonly minItems: 1;
                             readonly items: {
+                                readonly required: readonly ["value", "label"];
                                 readonly type: "object";
                                 readonly additionalProperties: false;
-                                readonly required: readonly ["value", "label"];
                                 readonly properties: {
+                                    readonly label: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
                                     readonly value: {
                                         readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly description: "Defaults to label when omitted.";
                                     };
-                                    readonly label: {
+                                    readonly description: {
                                         readonly type: "string";
                                     };
                                 };
@@ -102,19 +167,153 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
                     readonly additionalProperties: false;
                     readonly required: readonly ["label", "options"];
                 };
-                readonly choice: {
+            };
+        };
+    };
+    invocationSchema: {
+        readonly anyOf: readonly [{
+            readonly required: readonly ["question", "options"];
+        }, {
+            readonly required: readonly ["title", "singleSelect"];
+        }, {
+            readonly required: readonly ["title", "multiSelect"];
+        }, {
+            readonly required: readonly ["choice", "__askChoiceAnswerTicket"];
+        }, {
+            readonly required: readonly ["selections", "__askChoiceAnswerTicket"];
+        }];
+        readonly properties: {
+            readonly choice: {
+                readonly type: "string";
+            };
+            readonly selections: {
+                readonly type: "array";
+                readonly items: {
                     readonly type: "string";
-                    readonly description: "Set by the rendered form; never by the model.";
                 };
-                readonly selections: {
-                    readonly type: "array";
-                    readonly items: {
+            };
+            readonly __askChoiceAnswerTicket: {
+                readonly type: "string";
+            };
+            readonly question: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "The question to ask the human.";
+            };
+            readonly options: {
+                readonly type: "array";
+                readonly minItems: 1;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["label"];
+                    readonly properties: {
+                        readonly label: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly value: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "Defaults to label when omitted.";
+                        };
+                        readonly description: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly multiple: {
+                readonly type: "boolean";
+                readonly description: "Allow several selections. Defaults to false.";
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Legacy alias: title with singleSelect or multiSelect.";
+            };
+            readonly description: {
+                readonly type: "string";
+            };
+            readonly submitLabel: {
+                readonly type: "string";
+            };
+            readonly singleSelect: {
+                readonly description: "Legacy nested single-choice alias.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["label", "options"];
+                readonly properties: {
+                    readonly label: {
                         readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly required: readonly ["value", "label"];
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly value: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "Defaults to label when omitted.";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            readonly multiSelect: {
+                readonly description: "Legacy nested multiple-choice alias.";
+                readonly properties: {
+                    readonly hint: {
+                        readonly type: "string";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly required: readonly ["value", "label"];
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly value: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "Defaults to label when omitted.";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
                     };
-                    readonly description: "Set by the rendered form; never by the model.";
                 };
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["label", "options"];
             };
         };
+        readonly type: "object";
+        readonly additionalProperties: false;
     };
     handler({ ctx }: {
         ctx: AskChoiceCall;