@jini-ai/mcp 0.1.2 → 0.3.1

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

@@ -1,7 +1,8 @@
 /**
  * @module @jini-ai/mcp/server/tools/delegated-tool
  *
- * `execute_delegated_tool` — the MCP-callback half of gap 3's continuation transport (see
+ * `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/source-map.md`'s "run/chat orchestration gap 3, part 1" addition and this
  * package's own dated section in `source-map.md` for the rest of the spike). The swarm-consensus
  * Final Recommendation asked for exactly this: "inject the already-shipped MCP host into one
@@ -23,22 +24,93 @@
  * 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 { randomUUID } from 'node:crypto';
 import { postDaemonJson } from '../daemon-client.js';
-import { requireString } from '../tool-protocol.js';
+import { daemonCallOptions, requireString } from '../tool-protocol.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
- * 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.
+ * 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: [...]}`).
+ * 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
+ * ordinary tool call is untouched.
+ *
+ * Why unwrap at all: `../tool-protocol.js`'s `okResult()` only recognizes an already-well-formed
+ * content envelope AT THE TOP LEVEL of what a handler returns. Left wrapped inside
+ * `{executionId, status, output}`, a genuine `image` block in `output.content` (kept there by
+ * `@jini-ai/daemon`'s `delegated-tool-bridge.ts`, which treats `image` as model-safe — see that
+ * package's `tool-result-surfaces.ts`) would still get JSON.stringified into inert text by
+ * `okResult()`'s fallback path, because the wrapper object itself has no top-level `content` field
+ * for it to recognize. Unwrapping here is what lets `okResult()`'s whitelist actually reach the
+ * block the bridge already preserved.
  */
-export function createExecuteDelegatedToolTool(options) {
+function unwrapMcpContentEnvelope(result) {
+    if (!isRecord(result) || result['status'] !== 'completed')
+        return result;
+    const output = result['output'];
+    if (!isRecord(output) || !Array.isArray(output['content']))
+        return result;
+    return output;
+}
+/**
+ * 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 const DEFAULT_DELEGATED_TOOL_TIMEOUT_MS = 6 * 60 * 1000;
+/**
+ * Builds one gateway def. Both exported factories call this; there is no second copy of the
+ * request body, the timeout rule, or the unwrap.
+ *
+ * @param variant - The presentation/constraint half (see {@link DelegatedGatewayVariant}).
+ * @param options - The per-process run scope and its optional overrides.
+ * @returns The `McpToolDef` to host.
+ * @complexity O(1) at construction; each call is one HTTP round trip.
+ */
+function createDelegatedGateway(variant, options) {
     const { runId } = options;
     const generateToolUseId = options.generateToolUseId ?? randomUUID;
+    const requested = options.delegatedToolTimeoutMs;
+    const timeoutMs = typeof requested === 'number' && Number.isFinite(requested) && requested > 0
+        ? requested
+        : DEFAULT_DELEGATED_TOOL_TIMEOUT_MS;
     return {
-        name: 'execute_delegated_tool',
-        description: 'Execute a Jini-registered tool (never an agent-vendor-specific tool name) against the current run, routed through the daemon\'s ToolExecutor deny-by-default gate — the same authorization/confirmation/audit path every other tool-execution mechanism in this host uses. Returns {result}, a ToolExecutionResult: {status, output?, truncated?, error?} where status is one of completed|denied|confirmation-denied|timed-out|cancelled|failed.',
+        name: variant.name,
+        description: variant.description,
         inputSchema: {
             type: 'object',
             properties: {
@@ -66,11 +138,11 @@ export function createExecuteDelegatedToolTool(options) {
             additionalProperties: false,
         },
         annotations: {
-            readOnlyHint: false,
-            idempotentHint: false,
+            readOnlyHint: variant.readOnlyHint,
+            idempotentHint: variant.idempotentHint,
             destructiveHint: false,
             openWorldHint: false,
-            title: 'Execute a Jini-registered tool',
+            title: variant.title,
         },
         handler: async (args, ctx) => {
             requireString(args.toolId, 'toolId');
@@ -79,12 +151,74 @@ export function createExecuteDelegatedToolTool(options) {
                 toolUseId: generateToolUseId(),
                 toolId: args.toolId,
                 input: args.input,
+                ...(variant.requireReadOnly === undefined ? {} : { requireReadOnly: variant.requireReadOnly }),
             };
             const data = await postDaemonJson(ctx.baseUrl, '/api/delegated-tool-calls', body, {
-                fetchImpl: ctx.fetchImpl,
+                ...daemonCallOptions(ctx),
+                timeoutMs,
             });
-            return data.result;
+            return unwrapMcpContentEnvelope(data.result);
         },
     };
 }
+/**
+ * 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 function createExecuteDelegatedToolTool(options) {
+    return createDelegatedGateway({
+        name: 'execute_delegated_tool',
+        title: 'Execute a Jini-registered tool',
+        description: 'Execute a Jini-registered tool (never an agent-vendor-specific tool name) against the current run, routed through the daemon\'s ToolExecutor deny-by-default gate — the same authorization/confirmation/audit path every other tool-execution mechanism in this host uses. On a completed outcome, returns {result} normally. Any other outcome surfaces as an HTTP error the caller must catch, not a status field in a 200 body: denied/confirmation-denied raise a 403 TOOL_OPERATION_DENIED; timed-out/cancelled/failed raise a 500 INTERNAL_ERROR.',
+        readOnlyHint: false,
+        idempotentHint: false,
+    }, options);
+}
+/**
+ * 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 function createExecuteReadonlyDelegatedToolTool(options) {
+    return createDelegatedGateway({
+        name: 'execute_readonly_delegated_tool',
+        title: 'Execute a read-only Jini-registered tool',
+        description: 'Execute a READ-ONLY Jini-registered tool (never an agent-vendor-specific tool name) against the current run. Identical to execute_delegated_tool — same ToolExecutor deny-by-default authorization/confirmation/audit path, same {result} envelope, same errors — except that the daemon first checks the requested toolId against the live registry and refuses anything not registered as read-only, with a 403 TOOL_OPERATION_DENIED naming the tool. Use this for any tool that only reads. For a tool that creates, updates, deletes, publishes, or mints anything, call execute_delegated_tool instead; this one will refuse it.',
+        readOnlyHint: true,
+        // A read-only call has no state to advance, so repeating it is the same call. Matches
+        // `tool-catalog-tools.ts`'s and `run-tools.ts`'s own read annotations rather than inventing a
+        // third convention for the same claim.
+        idempotentHint: true,
+        requireReadOnly: true,
+    }, options);
+}
 //# sourceMappingURL=delegated-tool.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"delegated-tool.js","sourceRoot":"","sources":["../../../src/server/tools/delegated-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAcrE;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAAC,OAA8C;IAC3F,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1B,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,UAAU,CAAC;IAElE,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,mbAAmb;QACrb,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4CAA4C;iBAC1D;gBACD,KAAK,EAAE;oBACL,qFAAqF;oBACrF,kFAAkF;oBAClF,oFAAoF;oBACpF,kFAAkF;oBAClF,uFAAuF;oBACvF,8EAA8E;oBAC9E,EAAE;oBACF,mFAAmF;oBACnF,sFAAsF;oBACtF,gFAAgF;oBAChF,IAAI,EAAE,QAAQ;oBACd,oBAAoB,EAAE,IAAI;oBAC1B,WAAW,EAAE,wIAAwI;iBACtJ;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,oBAAoB,EAAE,KAAK;SAC5B;QACD,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,cAAc,EAAE,KAAK;YACrB,eAAe,EAAE,KAAK;YACtB,aAAa,EAAE,KAAK;YACpB,KAAK,EAAE,gCAAgC;SACxC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC3B,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACrC,MAAM,IAAI,GAA4B;gBACpC,KAAK;gBACL,SAAS,EAAE,iBAAiB,EAAE;gBAC9B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;aAClB,CAAC;YACF,MAAM,IAAI,GAAG,MAAM,cAAc,CAA+B,GAAG,CAAC,OAAO,EAAE,2BAA2B,EAAE,IAAI,EAAE;gBAC9G,SAAS,EAAE,GAAG,CAAC,SAAS;aACzB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"delegated-tool.js","sourceRoot":"","sources":["../../../src/server/tools/delegated-tool.ts"],"names":[],"mappings":"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"}

package/dist/server/tools/run-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/run-tools.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAmBrE,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,UAiC1B,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,UAAU,EAAE,UAgBxB,CAAC;AAEF,uGAAuG;AACvG,eAAO,MAAM,aAAa,EAAE,UAoB3B,CAAC;AAOF,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,EAAE,UAgBlC,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,cAAc,EAAE,UAM5B,CAAC;AAEF,wHAAwH;AACxH,eAAO,MAAM,SAAS,EAAE,SAAS,UAAU,EAM1C,CAAC"}
+{"version":3,"file":"run-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/run-tools.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAmBxF,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAE,UAiC1B,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,UAAU,EAAE,UAgBxB,CAAC;AAEF,uGAAuG;AACvG,eAAO,MAAM,aAAa,EAAE,UAoB3B,CAAC;AAOF,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,EAAE,UAgBlC,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,cAAc,EAAE,UAM5B,CAAC;AAEF,wHAAwH;AACxH,eAAO,MAAM,SAAS,EAAE,SAAS,UAAU,EAM1C,CAAC"}

package/dist/server/tools/run-tools.js

@@ -2,19 +2,19 @@
  * @module @jini-ai/mcp/server/tools/run-tools
  *
  * The first real, concrete `McpToolDef`s hosted by `createMcpToolServer`
- * (`../tool-server.js`) — a proxy over `@jini-ai/http`'s already-gated `Run`
+ * (`../tool-server.js`) — a proxy over `@jini-ai/http-kit`'s already-gated `Run`
  * transport (`packages/http/src/runs.ts`) plus the generic active-resource
  * channel (`packages/http/src/active-context.ts`) and the agent-def listing
  * (`packages/http/src/agents.ts`). Each tool's `handler` does nothing but
  * validate its own arguments and proxy a single HTTP call via
  * `../daemon-client.js` — no separate authorization mechanism, no caching,
- * no state: whatever `@jini-ai/http`'s same-origin guard / bearer-auth
+ * no state: whatever `@jini-ai/http-kit`'s same-origin guard / bearer-auth
  * middleware already enforces on the target route is the only gate a call
  * here passes through (see `source-map.md`'s 2026-07-21 addition for the
  * full origin-mapping and what was deliberately not ported).
  */
 import { getDaemonJson, postDaemonJson } from '../daemon-client.js';
-import { requireString } from '../tool-protocol.js';
+import { daemonCallOptions, requireString } from '../tool-protocol.js';
 const READ_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
@@ -62,7 +62,7 @@ export const startRunTool = {
         const idempotencyKey = optionalNonEmptyString(args.idempotencyKey);
         if (idempotencyKey !== undefined)
             body.idempotencyKey = idempotencyKey;
-        return postDaemonJson(ctx.baseUrl, '/api/runs', body, { fetchImpl: ctx.fetchImpl });
+        return postDaemonJson(ctx.baseUrl, '/api/runs', body, daemonCallOptions(ctx));
     },
 };
 /** `get_run` -> `GET /api/runs/:runId` (`packages/http/src/runs.ts`'s `runStatusRoute`). */
@@ -80,7 +80,7 @@ export const getRunTool = {
     annotations: { ...READ_ANNOTATIONS, title: 'Check a run' },
     handler: async (args, ctx) => {
         requireString(args.runId, 'runId');
-        return getDaemonJson(ctx.baseUrl, `/api/runs/${encodeURIComponent(args.runId)}`, { fetchImpl: ctx.fetchImpl });
+        return getDaemonJson(ctx.baseUrl, `/api/runs/${encodeURIComponent(args.runId)}`, daemonCallOptions(ctx));
     },
 };
 /** `cancel_run` -> `POST /api/runs/:runId/cancel` (`packages/http/src/runs.ts`'s `runCancelRoute`). */
@@ -103,7 +103,7 @@ export const cancelRunTool = {
         const reason = optionalNonEmptyString(args.reason);
         if (reason !== undefined)
             body.reason = reason;
-        return postDaemonJson(ctx.baseUrl, `/api/runs/${encodeURIComponent(args.runId)}/cancel`, body, { fetchImpl: ctx.fetchImpl });
+        return postDaemonJson(ctx.baseUrl, `/api/runs/${encodeURIComponent(args.runId)}/cancel`, body, daemonCallOptions(ctx));
     },
 };
 /** `get_active_context` -> `GET /api/active` (`packages/http/src/active-context.ts`'s `getActiveRoute`). */
@@ -113,7 +113,7 @@ export const getActiveContextTool = {
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: { ...READ_ANNOTATIONS, title: 'What is the caller focused on?' },
     handler: async (_args, ctx) => {
-        const data = await getDaemonJson(ctx.baseUrl, '/api/active', { fetchImpl: ctx.fetchImpl });
+        const data = await getDaemonJson(ctx.baseUrl, '/api/active', daemonCallOptions(ctx));
         if (data.active !== true) {
             return {
                 active: false,
@@ -129,7 +129,7 @@ export const listAgentsTool = {
     description: 'List every agent def registered with this host\'s @jini-ai/agent-runtime — {id, name} pairs suitable for start_run\'s optional agentId argument. Static registration data only: this does not probe which agent binaries are actually installed on the host machine.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: { ...READ_ANNOTATIONS, title: 'List registered agents' },
-    handler: async (_args, ctx) => getDaemonJson(ctx.baseUrl, '/api/agents', { fetchImpl: ctx.fetchImpl }),
+    handler: async (_args, ctx) => getDaemonJson(ctx.baseUrl, '/api/agents', daemonCallOptions(ctx)),
 };
 /** The full set of kernel-run tool defs this package ships, ready to pass as `createMcpToolServer`'s `tools` option. */
 export const RUN_TOOLS = [

package/dist/server/tools/run-tools.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"tool-catalog-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/tool-catalog-tools.ts"],"names":[],"mappings":"AAcA,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAiBrE,kHAAkH;AAClH,eAAO,MAAM,eAAe,EAAE,UAuB7B,CAAC;AAEF,kHAAkH;AAClH,eAAO,MAAM,gBAAgB,EAAE,UAiB9B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,EAAE,SAAS,UAAU,EAAwC,CAAC"}
+{"version":3,"file":"tool-catalog-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/tool-catalog-tools.ts"],"names":[],"mappings":"AAcA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAiBxF,kHAAkH;AAClH,eAAO,MAAM,eAAe,EAAE,UA2D7B,CAAC;AAEF,kHAAkH;AAClH,eAAO,MAAM,gBAAgB,EAAE,UAiB9B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,EAAE,SAAS,UAAU,EAAwC,CAAC"}

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

@@ -2,7 +2,7 @@
  * @module @jini-ai/mcp/server/tools/tool-catalog-tools
  *
  * `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`'s
+ * `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.
  *
@@ -12,7 +12,7 @@
  * Finding a tool id here grants nothing (`PROP` §6.3).
  */
 import { getDaemonJson } from '../daemon-client.js';
-import { requireString } from '../tool-protocol.js';
+import { daemonCallOptions, requireString } from '../tool-protocol.js';
 const READ_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
@@ -21,12 +21,48 @@ const READ_ANNOTATIONS = {
 /** `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 by keyword. 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.',
+    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.',
     inputSchema: {
         type: 'object',
         properties: {
-            query: { type: 'string', description: 'Keywords to search for, e.g. "navigate page" or "fill form". Required.' },
-            limit: { type: 'number', description: 'Max hits to return (1-25). Optional, defaults to 10.' },
+            // Descriptive phrasing, NOT keywords — and the example matters as much as the instruction.
+            // The catalog is matched on tool *descriptions* (BM25 over description text), so a query
+            // written in the register of a description retrieves far better than a keyword bag. Measured
+            // on an independent n=130 blind set: terse keywords 25% top-1, descriptive phrasing 72%.
+            // This field previously read 'Keywords to search for, e.g. "navigate page" or "fill form"',
+            // which is the 25% form. It also directly contradicted the descriptive guidance a host server
+            // may inject upstream (a host's agent-daemon systemOverlay said the opposite), so a caller was
+            // given two conflicting instructions — with this one sitting on the parameter itself, read at
+            // the moment the query is composed.
+            //
+            // NOT measured: which instruction won. The hypothesis was that a two-word example outranks
+            // prose guidance, but the conflict was removed before anyone measured it, so treat that as
+            // untested rather than established. What IS measured, on the coherent state after this fix:
+            // 35/35 real search_tools calls across 24 live CLI sessions used descriptive phrasing.
+            // Keep the example long-form; shortening it re-creates the 25% form.
+            query: {
+                type: 'string',
+                description: 'Describe what the tool you need DOES, the way its own documentation would describe it — a full phrase, not a keyword bag. Name the thing being acted on and the action, and include likely synonyms for both. Example: for a request like "how many people visited last week", write "retrieve site traffic and visitor analytics counts for a date range" rather than "visitors last week". Descriptive phrasing retrieves substantially better than terse keywords, because the catalog is matched on tool descriptions. Required.',
+            },
+            // Bounds mirror `packages/http-kit/src/tool-catalog.ts`'s `parseSearchInput`
+            // exactly (`MAX_SEARCH_LIMIT = 25`, `DEFAULT_SEARCH_LIMIT = 10`, integers only,
+            // `>= 1`). Declared rather than left as a bare `number` so MCP validation and the
+            // route agree: otherwise `0`/`1.5` pass here and are refused downstream, and `26`
+            // passes here and is silently clamped — the caller is told one contract and given
+            // another.
+            // The escalation clause is the cheap half of a measured ceiling. On the same n=130 blind set,
+            // with the host's operator-vocabulary + doc2query index folded in, the right tool is in the
+            // default top 10 for 98% of cases and in the top 20 for 100% — so the residual misses are
+            // ranked just below the cutoff, never absent. Raising the DEFAULT to 20 would buy those 2
+            // cases at ~900 extra tokens on every single call; telling the caller to escalate on demand
+            // buys the same ceiling only when it is needed. Same lever as the descriptive-phrasing fix
+            // above: a prompt change, not an LLM call.
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 25,
+                description: 'Max hits to return (1-25). Optional, defaults to 10. If none of the returned candidates fit what you need, search again with a HIGHER limit (try 25) before concluding no tool exists — the right tool is in the top 10 about 98% of the time and in the top 20 100% of the time, so a near-miss is ranked just below the default cutoff rather than missing.',
+            },
         },
         required: ['query'],
         additionalProperties: false,
@@ -37,9 +73,7 @@ export const searchToolsTool = {
         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/tools/search?${params.toString()}`, {
-            fetchImpl: ctx.fetchImpl,
-        });
+        const data = await getDaemonJson(ctx.baseUrl, `/api/tools/search?${params.toString()}`, daemonCallOptions(ctx));
         return data.hits;
     },
 };
@@ -58,7 +92,7 @@ export const describeToolTool = {
     annotations: { ...READ_ANNOTATIONS, title: 'Describe a tool' },
     handler: async (args, ctx) => {
         requireString(args.id, 'id');
-        return getDaemonJson(ctx.baseUrl, `/api/tools/${encodeURIComponent(args.id)}`, { fetchImpl: ctx.fetchImpl });
+        return getDaemonJson(ctx.baseUrl, `/api/tools/${encodeURIComponent(args.id)}`, daemonCallOptions(ctx));
     },
 };
 /** Both tool-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */

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

@@ -1 +1 @@
-{"version":3,"file":"tool-catalog-tools.js","sourceRoot":"","sources":["../../../src/server/tools/tool-catalog-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAErE,MAAM,gBAAgB,GAAG;IACvB,YAAY,EAAE,IAAI;IAClB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACZ,CAAC;AAWX,kHAAkH;AAClH,MAAM,CAAC,MAAM,eAAe,GAAe;IACzC,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,sQAAsQ;IACxQ,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wEAAwE,EAAE;YAChH,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sDAAsD,EAAE;SAC/F;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE,EAAE,GAAG,gBAAgB,EAAE,KAAK,EAAE,yBAAyB,EAAE;IACtE,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,CAA4B,GAAG,CAAC,OAAO,EAAE,qBAAqB,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE;YACjH,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF,CAAC;AAEF,kHAAkH;AAClH,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,sMAAsM;IACxM,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6CAA6C,EAAE;SACnF;QACD,QAAQ,EAAE,CAAC,IAAI,CAAC;QAChB,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE,EAAE,GAAG,gBAAgB,EAAE,KAAK,EAAE,iBAAiB,EAAE;IAC9D,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,cAAc,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/G,CAAC;CACF,CAAC;AAEF,kGAAkG;AAClG,MAAM,CAAC,MAAM,kBAAkB,GAA0B,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"tool-catalog-tools.js","sourceRoot":"","sources":["../../../src/server/tools/tool-catalog-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.1.2",
+  "version": "0.3.1",
+  "description": "Model Context Protocol adapters: server config schema and IO, an MCP client, and agent-side MCP server installation.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -10,10 +11,10 @@
   "jini": {
     "domain": "integration",
     "kind": "protocol-adapter",
-    "runtime": "node",
-    "admission": "incubating"
+    "runtime": "node"
   },
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -21,6 +22,9 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./bin": {
+      "default": "./dist/bin/serve.js"
     }
   },
   "bin": {
@@ -39,10 +43,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "undici": "^7.25.0",
-    "@jini-ai/cli": "0.1.2",
-    "@jini-ai/platform": "0.1.2"
+    "@jini-ai/cli": "0.3.0",
+    "@jini-ai/platform": "0.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",