stitchkit 0.68.9 → 0.68.10

package/dist/tools.js

@@ -1,10 +1,14 @@
 import {
   redact
-} from "./index-hmfpjnh7.js";
+} from "./index-22tjt2rk.js";
+import {
+  buildToolManifest,
+  mountAgent
+} from "./index-bt5179zb.js";
 import {
   signJwt,
   verifyPkce
-} from "./index-3ydx9j01.js";
+} from "./index-xyvxez9r.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_PROCESS_SIGNALS,
@@ -12,39 +16,39 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-z575awm9.js";
+} from "./index-hxh98zbm.js";
 import {
   createToolInvoker
-} from "./index-9t2tdk1x.js";
+} from "./index-grgvpbch.js";
 import {
   WaitTimeoutError,
-  collectToolSurface,
   createCli,
-  createRuntimeToolFactory,
   defineCliCommand,
-  defineRuntimeTool,
   fetchGuarded,
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-1bmpkhj2.js";
+} from "./index-2t6zt5cg.js";
 import {
-  collectTools,
-  createToolRunner,
-  formatToolError
-} from "./index-88yyydag.js";
+  collectToolSurface,
+  createRuntimeToolFactory,
+  defineRuntimeTool
+} from "./index-eqqyd9v8.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,
+  collectTools,
+  createToolRunner,
   executeToolMethod,
+  formatToolError,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-04agqrs8.js";
+} from "./index-y2ctppmg.js";
 import {
   getRequestContext,
   getTraceId,
   runWithRequestContext
-} from "./index-51a19y3v.js";
+} from "./index-f24xg2cw.js";
 import {
   ManagedFileError
 } from "./index-bfcpjw20.js";
@@ -59,17 +63,16 @@ import {
   prepareProjectedMcpTools,
   presentationMetadata,
   validateMcpRoundPolicy
-} from "./index-vkk06pv1.js";
-import"./index-6djpbnda.js";
+} from "./index-22by16v6.js";
 import"./index-cby4ar3v.js";
 import {
   defineContract,
   normalizeError,
   resolvePropagationContext
-} from "./index-bmmtz6r9.js";
+} from "./index-pgsyp3xh.js";
 import {
   isRecord
-} from "./index-smpbdg6k.js";
+} from "./index-qyrqwr4c.js";
 import {
   AppError,
   STITCH_ERROR_STATUS
@@ -78,77 +81,6 @@ import {
   ManagedFilePathSchema,
   ManagedFileRefSchema
 } from "./index-6k1937bx.js";
-
-// src/tools/agent.ts
-import { jsonSchema, tool } from "ai";
-function mountAgent(services, config = {}) {
-  const serviceList = Array.isArray(services) ? services : [services];
-  const tools = {};
-  const runTool = createToolRunner({
-    source: "agent",
-    extend: config.extend,
-    context: config.context,
-    hooks: config.hooks,
-    lifecycle: config.lifecycle,
-    errorHint: config.errorHint,
-    coerceJsonArgs: config.coerceJsonArgs,
-    onOutputStrip: config.onOutputStrip
-  });
-  for (const entry of collectToolSurface({
-    surface: { services: serviceList, runtimeTools: config.runtimeTools },
-    transport: "AGENT",
-    extend: config.extend,
-    flattenUnionInput: config.flattenUnionInput
-  })) {
-    const { mountable } = entry;
-    const inputSchema = jsonSchema(mountable.presentationSchema, {
-      validate: async (value) => isRecord(value) ? { success: true, value } : { success: false, error: new Error("Tool arguments must be an object") }
-    });
-    const execute = async (rawArgs, options) => {
-      const args = isRecord(rawArgs) ? rawArgs : {};
-      try {
-        const result = await runTool(mountable, args, { signal: options.abortSignal });
-        if (result.ok)
-          return result.data;
-        return formatToolError(result, mountable.name, config.errorHint);
-      } catch (err) {
-        if (isToolExecutionControlError(err))
-          throw err;
-        return formatToolError(toolResultFromError(err), mountable.name, config.errorHint);
-      }
-    };
-    const presenter = entry.kind === "runtime" ? entry.definition.present?.agent : undefined;
-    if (entry.kind === "runtime" && presenter) {
-      const { definition } = entry;
-      const output = definition.output;
-      if (!output) {
-        throw new Error(`Runtime tool "${definition.name}" presenter requires an output schema`);
-      }
-      tools[definition.name] = tool({
-        description: definition.description,
-        inputSchema,
-        outputSchema: output,
-        execute,
-        toModelOutput: async ({ output: rawOutput }) => {
-          const parsed = output.safeParse(rawOutput);
-          if (!parsed.success) {
-            return { type: "text", value: JSON.stringify(rawOutput) };
-          }
-          return presenter(parsed.data);
-        }
-      });
-    } else {
-      const output = entry.kind === "runtime" ? entry.definition.output : undefined;
-      tools[mountable.name] = tool({
-        description: mountable.method.desc,
-        inputSchema,
-        ...output && { outputSchema: output },
-        execute
-      });
-    }
-  }
-  return tools;
-}
 // src/tools/async-operation.ts
 import { z } from "zod";
 
@@ -1003,19 +935,6 @@ function listToolNames(surface) {
 function listContractToolNames(contracts) {
   return listToolNames({ services: contracts.map(contractOnlyService) });
 }
-// src/tools/manifest.ts
-function buildToolManifest(config) {
-  return collectToolSurface({
-    surface: config,
-    transport: config.transport,
-    extend: config.extend,
-    flattenUnionInput: config.flattenUnionInput
-  }).map(({ mountable }) => ({
-    name: mountable.name,
-    description: mountable.method.desc,
-    inputSchema: mountable.presentationSchema
-  }));
-}
 // src/tools/mcp.ts
 import {
   createRequestStateCodec,
@@ -1178,23 +1097,23 @@ async function argumentsDigest(args) {
     binary += String.fromCodePoint(byte);
   return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
 }
-function operationIdentity(tool2) {
+function operationIdentity(tool) {
   return {
-    toolName: tool2.name,
-    serviceName: tool2.method.serviceName,
-    action: tool2.method.key,
-    method: tool2.method.method,
-    ...tool2.method.scope !== undefined && { scope: tool2.method.scope }
+    toolName: tool.name,
+    serviceName: tool.method.serviceName,
+    action: tool.method.key,
+    method: tool.method.method,
+    ...tool.method.scope !== undefined && { scope: tool.method.scope }
   };
 }
 function sameIdentity(left, right) {
   return left.toolName === right.toolName && left.serviceName === right.serviceName && left.action === right.action && left.method === right.method && left.scope === right.scope;
 }
-async function runRoundSuccess(tool2, rawArgs, runTool, context) {
+async function runRoundSuccess(tool, rawArgs, runTool, context) {
   return runTool({
-    ...tool2,
+    ...tool,
     method: {
-      ...tool2.method,
+      ...tool.method,
       outputSchema: undefined,
       handler: () => {
         return;
@@ -1202,11 +1121,11 @@ async function runRoundSuccess(tool2, rawArgs, runTool, context) {
     }
   }, rawArgs, context);
 }
-async function runRoundFailure(tool2, rawArgs, runTool, context, code, message) {
+async function runRoundFailure(tool, rawArgs, runTool, context, code, message) {
   return runTool({
-    ...tool2,
+    ...tool,
     method: {
-      ...tool2.method,
+      ...tool.method,
       outputSchema: undefined,
       handler: () => {
         throw new AppError(code, message, 400);
@@ -1402,7 +1321,7 @@ function mountPreparedRuntimeMcp(server, tools, config) {
     }
     server.registerTool(definition.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, definition.name, async () => {
       const args = isRecord(rawArgs) ? rawArgs : {};
-      const runTool = (tool2, toolArgs, roundContext) => executeToolMethod(tool2.method, definition.name, toolArgs, { ...config.context, ...roundContext, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
+      const runTool = (tool, toolArgs, roundContext) => executeToolMethod(tool.method, definition.name, toolArgs, { ...config.context, ...roundContext, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
       const round = await resolveMcpRound({
         tool: mountable,
         rawArgs: args,

package/llms-full.txt

@@ -3712,6 +3712,16 @@ fails first on duplicate contract/runtime names. There is no runtime-only
 manifest helper or public mount adapter: the framework owns merging and schema
 projection.
 
+Applications using Stitchkit's durable runtime can compose this manifest with
+bounded per-run activation through `createDeferredAgentToolSurface` from
+`stitchkit/agent-runtime`. It keeps selected calls as direct `mountAgent` tools
+rather than routing them through a generic executor. Search receipts live in
+ordinary durable tool-result history, so recovery restores activation and a
+queued successor cannot inherit it. See
+[Bounded deferred tool catalogs](./agent-runtime.md#bounded-deferred-tool-catalogs)
+and ADR 0129. Raw `mountAgent`, `mountMcp` and `buildToolManifest` behavior is
+unchanged.
+
 `listToolNames` remains diagnostic and reports `kind: 'contract' | 'runtime'`
 for every identity. `summarizeTransports` returns `contractServices`,
 `runtimeTools`, aggregate `totals`, and a `sources` breakdown. Runtime tools
@@ -3763,7 +3773,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-08-28
+updated: 2026-08-29
 ---
 
 # Agent application runtime
@@ -3918,6 +3928,69 @@ await ticket.accepted
 const terminal = await ticket.result
 ```
 
+## Bounded deferred tool catalogs
+
+Use `createDeferredAgentToolSurface` when a measured large catalog makes
+sending every schema on every provider step expensive. The controller mounts
+the complete executable surface in process, but initially advertises only its
+search tool, explicit `alwaysOn` tools and bounded policy pins:
+
+```ts
+import { createDeferredAgentToolSurface } from 'stitchkit/agent-runtime'
+import { composeToolLifecycle } from 'stitchkit/tools'
+
+const deferred = createDeferredAgentToolSurface({
+  surfaces: {
+    member: { services: memberServices, runtimeTools, alwaysOn: ['ask_user'] },
+    broadcast: { services: broadcastServices, runtimeTools },
+  },
+  selectSurface: ({ context }) => context.mode,
+  pins: ({ context }) => context.skillTools,
+  search: {
+    name: 'tool_search',
+    maxQueryBytes: 1_024,
+    maxResults: 8,
+    maxResultBytes: 8_192,
+    select: ({ query, manifest }) => rankCatalog(query, manifest),
+  },
+  activation: {
+    maxSelectedTools: 8,
+    maxActiveTools: 16,
+    maxSchemaBytes: 32_768,
+  },
+  observe: event => recordDeferredToolEvidence(event),
+})
+
+const runtime = createAgentRuntime({
+  // protocol, store, models and prompt...
+  tools: runContext => deferred.mount(runContext, {
+    context: runContext.context,
+    lifecycle: composeToolLifecycle(authLifecycle, runContext.toolFenceLifecycle),
+  }),
+  loop: { prepareStep: deferred.prepareStep(applicationPrepareStep) },
+})
+```
+
+The built-in selector deterministically ranks exact name, prefix/token and
+description matches. A custom async selector returns names only; unknown and
+duplicate output is removed against the local canonical manifest. Search never
+executes the selected operation and never returns its schema. A later provider
+step receives the real selected tools by name, so their direct lifecycle,
+fencing, hooks, errors and `present.agent` output remain unchanged.
+
+Selection is a versioned receipt in the ordinary durable tool-result history.
+The latest valid same-run search replaces the earlier selection; parallel
+searches in one step merge in call order. Recovery reconstructs it, while a
+different run or finite surface cannot inherit it. Known inactive calls take a
+recoverable `SEARCH_REQUIRED` search round; unknown names still fail.
+
+Every ceiling is required. `maxSchemaBytes` measures UTF-8 bytes over canonical
+name, description and presentation schema. It is useful for before/after
+comparison, but provider serialization and tokenization differ: use existing
+provider-reported input usage and cost to decide whether the extra search round
+is beneficial. Controller evidence intentionally omits query text, prompts,
+arguments and application context. → ADR 0129.
+
 ### Executable headless harness and capability map
 
 [`packages/core/examples/headless-agent-harness.ts`](../../packages/core/examples/headless-agent-harness.ts)
@@ -11683,6 +11756,12 @@ Server-only optional application runtime. See the
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAgentRuntime` | function | compose durable acceptance, stream loop, checkpoints, coordination, managed tools and winner-only terminal publication; reconciles same-owner terminal/interrupt/head CAS races before releasing the lane |
+| `createDeferredAgentToolSurface` | function | bounded canonical catalog search plus durable same-run activation of direct `mountAgent` tools; supports one immutable surface or a finite identity-specific registry |
+| `DeferredAgentToolSearchInputSchema` / `DeferredAgentToolMatchSchema` / `DeferredAgentToolReceiptSchema` | schema | bounded search input, public match and versioned durable selection receipt |
+| `DeferredAgentToolSurfaceConfig` / `DeferredAgentToolCommonConfig` / `DeferredAgentToolSurfaceDefinition` / `DeferredAgentToolController` | _type_ | finite catalogs, selector, pin, budget and `mount`/`prepareStep` composition contracts |
+| `DeferredAgentRuntimeToolDefinition` / `DeferredAgentToolMountConfig` | _type_ | peer-free Agent-only runtime definition and canonical mount configuration accepted by the controller |
+| `DeferredAgentToolManifestEntry` / `DeferredAgentToolSearchContext` / `DeferredAgentToolReceipt` | _type_ | canonical selector input and inferred durable receipt records |
+| `DeferredAgentToolEvent` | _type_ | PII-free search/step evidence with surface, provenance, counts, canonical schema bytes and ceilings |
 | `defineAgentProtocol` | function | declare context, input metadata, canonical parts and optional pre-CAS terminal acceptance (`allow-empty`, `require-output` or callback) |
 | `hasAgentTerminalOutput` | function | generic `require-output` predicate for non-blank text, generated files, structured provider parts and explicit tool-only policy stops |
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.9",
+  "version": "0.68.10",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/index-6djpbnda.js

@@ -1,56 +0,0 @@
-import {
-  toJsonSchema
-} from "./index-cby4ar3v.js";
-
-// src/tools/schema.ts
-import { z } from "zod";
-function objectShapeKeys(schema) {
-  return schema instanceof z.ZodObject ? Object.keys(schema.shape) : [];
-}
-function keyPolicyOf(schema) {
-  return schema.def.catchall;
-}
-function rebuildObject(source, shape) {
-  return withKeyPolicy(z.object(shape), keyPolicyOf(source));
-}
-function withKeyPolicy(object, policy) {
-  if (policy === undefined)
-    return object;
-  return object.catchall(representable(policy));
-}
-function representable(policy) {
-  if (policy instanceof z.ZodNever || policy instanceof z.ZodUnknown)
-    return policy;
-  if (!(policy instanceof z.ZodType))
-    return z.unknown();
-  try {
-    toJsonSchema(policy, "input");
-    return policy;
-  } catch {
-    return z.unknown();
-  }
-}
-function mergeSchemas(paramsSchema, inputSchema) {
-  if (paramsSchema && !(paramsSchema instanceof z.ZodObject)) {
-    throw new Error("Tool params schema must be a z.object()");
-  }
-  const paramsObject = paramsSchema instanceof z.ZodObject ? paramsSchema : undefined;
-  if (!inputSchema) {
-    return paramsObject ?? z.object({});
-  }
-  if (inputSchema instanceof z.ZodObject) {
-    if (paramsObject) {
-      const conflicts = Object.keys(paramsObject.shape).filter((key) => (key in inputSchema.shape));
-      if (conflicts.length > 0) {
-        throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
-      }
-    }
-    return rebuildObject(inputSchema, {
-      ...paramsObject?.shape ?? {},
-      ...inputSchema.shape
-    });
-  }
-  return paramsObject ? z.intersection(paramsObject, inputSchema) : inputSchema;
-}
-
-export { objectShapeKeys, rebuildObject, mergeSchemas };

package/dist/index-88yyydag.js

@@ -1,75 +0,0 @@
-import {
-  executeToolMethod
-} from "./index-04agqrs8.js";
-import {
-  assertToolExtensionCompatible,
-  projectToolSurface
-} from "./index-vkk06pv1.js";
-import {
-  mergeSchemas,
-  rebuildObject
-} from "./index-6djpbnda.js";
-
-// src/tools/mount.ts
-import { z } from "zod";
-function applyExtend(base, extra) {
-  if (base instanceof z.ZodObject) {
-    assertToolExtensionCompatible(base, extra);
-    return rebuildObject(base, { ...extra, ...base.shape });
-  }
-  return z.intersection(z.object(extra), base);
-}
-function contractToolMountable(projected, extend) {
-  const method = projected.source;
-  const baseArgumentSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
-  const argumentSchema = projected.shouldExtend && extend ? applyExtend(baseArgumentSchema, extend.schema) : baseArgumentSchema;
-  return {
-    method,
-    name: projected.name,
-    argumentSchema,
-    presentationSchema: projected.presentationSchema,
-    shouldExtend: projected.shouldExtend
-  };
-}
-function collectTools(service, transport, config = {}) {
-  const { extend, flattenUnionInput = false, assertNames = true } = config;
-  const tools = [];
-  for (const projected of projectToolSurface({ services: [service] }, transport === "HTTP" ? "AGENT" : transport, {
-    extend,
-    flattenUnionInput,
-    assertNames,
-    assertUniqueNames: false
-  })) {
-    if (projected.kind !== "contract")
-      continue;
-    tools.push(contractToolMountable(projected, extend));
-  }
-  return tools;
-}
-function createToolRunner(config) {
-  const extension = config.extend ? {
-    schema: z.object(config.extend.schema),
-    resolve: config.extend.resolve
-  } : undefined;
-  return async function runOneToolCall(tool, rawArgs, context) {
-    return executeToolMethod(tool.method, tool.name, rawArgs, { ...config.context, ...context, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(tool.name, paths) : undefined, tool.shouldExtend ? extension : undefined);
-  };
-}
-function formatToolError(result, toolName, errorHint) {
-  const err = { error: result.code };
-  if (result.details)
-    err.details = result.details;
-  const hints = [];
-  if (result.hint)
-    hints.push(result.hint);
-  if (errorHint && toolName) {
-    const global = errorHint(toolName, result.code);
-    if (global)
-      hints.push(global);
-  }
-  if (hints.length > 0)
-    err._hint = hints.join(" ");
-  return err;
-}
-
-export { contractToolMountable, collectTools, createToolRunner, formatToolError };

package/dist/index-smpbdg6k.js

@@ -1,27 +0,0 @@
-// src/internal/typed.ts
-function typedEntries(value) {
-  return Object.entries(value);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function callRuntimeHandler(handler, context) {
-  if (typeof handler !== "function") {
-    throw new TypeError("Runtime handler must be a function");
-  }
-  return Reflect.apply(handler, undefined, [context]);
-}
-function transportResult(value) {
-  return value;
-}
-function mapObject(source, mapper) {
-  const result = {};
-  for (const [key, value] of typedEntries(source)) {
-    const mapped = mapper(key, value);
-    if (mapped !== undefined)
-      result[key] = mapped;
-  }
-  return result;
-}
-
-export { typedEntries, isRecord, callRuntimeHandler, transportResult, mapObject };