stitchkit 0.40.0 → 0.42.0

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-92gs1m5b.js";
+} from "./index-310bfer5.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-6jypn22c.js";
@@ -25,7 +25,7 @@ import {
   toolErrorFromResult,
   toolResultFromError,
   writeDownload
-} from "./index-p1x65gk7.js";
+} from "./index-p9vkwns1.js";
 import {
   toJsonSchema
 } from "./index-frfyw9fa.js";
@@ -39,7 +39,7 @@ import {
   mergeMeta,
   parseTrailingWildcard,
   typedEntries
-} from "./index-fyfk537k.js";
+} from "./index-gex6gxhe.js";
 
 // src/tools/agent.ts
 import { jsonSchema, tool } from "ai";
@@ -70,8 +70,10 @@ function runtimeToolIdentity(definition) {
     ui: definition.ui
   };
 }
-function runtimeToolMountable(definition) {
-  assertToolName(definition.name, definition.identity.serviceName, definition.identity.action);
+function runtimeToolMountable(definition, assertName = true) {
+  if (assertName) {
+    assertToolName(definition.name, definition.identity.serviceName, definition.identity.action);
+  }
   const method = {
     ...runtimeToolIdentity(definition),
     inputSchema: definition.input,
@@ -90,6 +92,55 @@ function runtimeToolMountable(definition) {
   };
 }
 
+// src/tools/surface.ts
+function duplicateLabel(transport) {
+  if (transport === "MCP")
+    return "MCP tool name";
+  if (transport === "AGENT")
+    return "agent tool name";
+  return "CLI command";
+}
+function collectToolSurface({
+  surface,
+  transport,
+  assertUniqueNames = true,
+  ...collectConfig
+}) {
+  const entries = [];
+  const names = new Set;
+  const append = (entry) => {
+    if (assertUniqueNames) {
+      assertUniqueToolName(entry.mountable.name, names.has(entry.mountable.name), duplicateLabel(transport));
+    }
+    names.add(entry.mountable.name);
+    entries.push(entry);
+  };
+  for (const service of surface.services ?? []) {
+    for (const mountable of collectTools(service, transport, collectConfig)) {
+      append({
+        kind: "contract",
+        service: service.name,
+        action: mountable.method.key,
+        mountable
+      });
+    }
+  }
+  if (transport === "CLI")
+    return entries;
+  for (const definition of surface.runtimeTools ?? []) {
+    if (!runtimeToolSupports(definition, transport))
+      continue;
+    append({
+      kind: "runtime",
+      service: definition.identity.serviceName,
+      action: definition.identity.action,
+      mountable: runtimeToolMountable(definition, collectConfig.assertNames),
+      definition
+    });
+  }
+  return entries;
+}
+
 // src/tools/agent.ts
 function mountAgent(services, config = {}) {
   const serviceList = Array.isArray(services) ? services : [services];
@@ -104,36 +155,13 @@ function mountAgent(services, config = {}) {
     coerceJsonArgs: config.coerceJsonArgs,
     onOutputStrip: config.onOutputStrip
   });
-  for (const service of serviceList) {
-    for (const mountable of collectTools(service, "AGENT", {
-      extend: config.extend,
-      flattenUnionInput: config.flattenUnionInput
-    })) {
-      assertUniqueToolName(mountable.name, Object.hasOwn(tools, mountable.name), "agent tool name");
-      tools[mountable.name] = tool({
-        description: mountable.method.desc,
-        inputSchema: jsonSchema(mountable.presentationSchema, {
-          validate: async (value) => isRecord(value) ? { success: true, value } : { success: false, error: new Error("Tool arguments must be an object") }
-        }),
-        execute: async (rawArgs) => {
-          const args = isRecord(rawArgs) ? rawArgs : {};
-          try {
-            const result = await runTool(mountable, args);
-            if (result.ok)
-              return result.data;
-            return formatToolError(result, mountable.name, config.errorHint);
-          } catch (err) {
-            return formatToolError(toolResultFromError(err), mountable.name, config.errorHint);
-          }
-        }
-      });
-    }
-  }
-  for (const definition of config.runtimeTools ?? []) {
-    if (!runtimeToolSupports(definition, "AGENT"))
-      continue;
-    const mountable = runtimeToolMountable(definition);
-    assertUniqueToolName(definition.name, Object.hasOwn(tools, definition.name), "agent tool name");
+  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") }
     });
@@ -148,9 +176,13 @@ function mountAgent(services, config = {}) {
         return formatToolError(toolResultFromError(err), mountable.name, config.errorHint);
       }
     };
-    if (definition.present?.agent) {
-      const presenter = definition.present.agent;
+    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,
@@ -165,10 +197,11 @@ function mountAgent(services, config = {}) {
         }
       });
     } else {
-      tools[definition.name] = tool({
-        description: definition.description,
+      const output = entry.kind === "runtime" ? entry.definition.output : undefined;
+      tools[mountable.name] = tool({
+        description: mountable.method.desc,
         inputSchema,
-        ...definition.output && { outputSchema: definition.output },
+        ...output && { outputSchema: output },
         execute
       });
     }
@@ -224,34 +257,43 @@ function createToolInvoker(services, config) {
 }
 // src/tools/list-names.ts
 var TOOL_TRANSPORTS = ["MCP", "AGENT", "CLI"];
-function listToolNames(services) {
+function listToolNames(surface) {
   const entries = new Map;
-  for (const service of services) {
-    for (const transport of TOOL_TRANSPORTS) {
-      for (const tool2 of collectTools(service, transport, { assertNames: false })) {
-        const id = `${service.name}\x00${tool2.method.key}`;
-        const existing = entries.get(id);
-        if (existing) {
-          existing.transports.push(transport);
-        } else {
-          entries.set(id, {
-            name: tool2.name,
-            service: service.name,
-            method: tool2.method.key,
-            transports: [transport]
-          });
-        }
+  for (const transport of TOOL_TRANSPORTS) {
+    for (const entry of collectToolSurface({
+      surface,
+      transport,
+      assertNames: false,
+      assertUniqueNames: false
+    })) {
+      const id = `${entry.kind}\x00${entry.service}\x00${entry.action}`;
+      const existing = entries.get(id);
+      if (existing) {
+        existing.transports.push(transport);
+      } else {
+        entries.set(id, {
+          kind: entry.kind,
+          name: entry.mountable.name,
+          service: entry.service,
+          method: entry.action,
+          transports: [transport]
+        });
       }
     }
   }
   return [...entries.values()].sort((a, b) => a.name.localeCompare(b.name) || a.service.localeCompare(b.service));
 }
 // src/tools/manifest.ts
-function buildToolManifest(tools) {
-  return tools.map((tool2) => ({
-    name: tool2.name,
-    description: tool2.method.desc,
-    inputSchema: tool2.presentationSchema
+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
@@ -285,63 +327,53 @@ import { z } from "zod";
 function isCallToolResult(value) {
   return CallToolResultSchema.safeParse(value).success;
 }
-function createNativeMcpRegistrar(server, config) {
-  return {
-    rawServer: server,
-    registerTool: (definition) => {
-      if (!runtimeToolSupports(definition, "MCP"))
-        return;
-      assertUniqueToolName(definition.name, config.takenNames.has(definition.name), "MCP tool name");
-      config.takenNames.add(definition.name);
-      const mountable = runtimeToolMountable(definition);
-      const [prepared] = config.prepare(mountable);
-      if (!prepared)
-        return;
-      const toolConfig = {
-        description: definition.description,
-        inputSchema: z.looseObject({}).meta(presentationMetadata(prepared.inputSchema))
+function mountPreparedRuntimeMcp(server, tools, config) {
+  for (const { definition, descriptor } of tools) {
+    const { mountable } = descriptor;
+    const toolConfig = {
+      description: definition.description,
+      inputSchema: z.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
+    };
+    if (descriptor.outputSchema)
+      toolConfig.outputSchema = descriptor.outputSchema;
+    if (definition.annotations)
+      toolConfig.annotations = definition.annotations;
+    if (definition.ui) {
+      toolConfig._meta = {
+        ui: definition.ui,
+        "ui/resourceUri": definition.ui.resourceUri
       };
-      if (prepared.outputSchema)
-        toolConfig.outputSchema = prepared.outputSchema;
-      if (definition.annotations)
-        toolConfig.annotations = definition.annotations;
-      if (definition.ui) {
-        toolConfig._meta = {
-          ui: definition.ui,
-          "ui/resourceUri": definition.ui.resourceUri
-        };
+    }
+    server.registerTool(definition.name, toolConfig, async (rawArgs) => {
+      const args = isRecord(rawArgs) ? rawArgs : {};
+      const result = await executeToolMethod(mountable.method, definition.name, args, { ...config.context, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
+      if (!result.ok || !definition.present?.mcp) {
+        return config.formatResult(result, descriptor.outputMode, definition.name);
       }
-      server.registerTool(definition.name, toolConfig, async (rawArgs) => {
-        const args = isRecord(rawArgs) ? rawArgs : {};
-        const result = await executeToolMethod(mountable.method, definition.name, args, { ...config.context, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
-        if (!result.ok || !definition.present?.mcp) {
-          return config.formatResult(result, prepared.outputMode, definition.name);
-        }
-        const presented = await definition.present.mcp(result.data);
-        if ("structuredContent" in presented || "isError" in presented) {
-          return config.formatResult({
-            ok: false,
-            code: "INTERNAL_SERVER_ERROR",
-            details: {
-              message: "Runtime MCP presenter cannot set framework-owned structuredContent or isError"
-            }
-          }, "none", definition.name);
-        }
-        const structured = config.formatResult(result, prepared.outputMode, definition.name).structuredContent;
-        const response = {
-          ...presented,
-          ...structured && { structuredContent: structured }
-        };
-        if (isCallToolResult(response))
-          return response;
+      const presented = await definition.present.mcp(result.data);
+      if ("structuredContent" in presented || "isError" in presented) {
         return config.formatResult({
           ok: false,
           code: "INTERNAL_SERVER_ERROR",
-          details: { message: "Runtime MCP presenter returned an invalid CallToolResult" }
+          details: {
+            message: "Runtime MCP presenter cannot set framework-owned structuredContent or isError"
+          }
         }, "none", definition.name);
-      });
-    }
-  };
+      }
+      const structured = config.formatResult(result, descriptor.outputMode, definition.name).structuredContent;
+      const response = {
+        ...presented,
+        ...structured && { structuredContent: structured }
+      };
+      if (isCallToolResult(response))
+        return response;
+      return config.formatResult({
+        ok: false,
+        code: "INTERNAL_SERVER_ERROR",
+        details: { message: "Runtime MCP presenter returned an invalid CallToolResult" }
+      }, "none", definition.name);
+    });
+  }
 }
 
 // src/tools/portable-formats.ts
@@ -629,6 +661,37 @@ function prepareMcpTools(tools, config = {}) {
   throwIfFailures(failures);
   return Object.freeze(prepared);
 }
+function prepareMcpServerSurface(surface, config = {}) {
+  const contractMountables = [];
+  const definitions = [];
+  const runtimeMountables = [];
+  for (const entry of collectToolSurface({
+    surface,
+    transport: "MCP",
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput
+  })) {
+    if (entry.kind === "contract") {
+      contractMountables.push(entry.mountable);
+    } else {
+      definitions.push(entry.definition);
+      runtimeMountables.push(entry.mountable);
+    }
+  }
+  const contractTools = prepareMcpTools(contractMountables, config);
+  const runtimeDescriptors = prepareMcpTools(runtimeMountables, {
+    schemaValidation: config.schemaValidation,
+    logger: config.logger
+  });
+  const descriptorsByName = new Map(runtimeDescriptors.map((descriptor) => [descriptor.mountable.name, descriptor]));
+  const runtimeTools = [];
+  for (const definition of definitions) {
+    const descriptor = descriptorsByName.get(definition.name);
+    if (descriptor)
+      runtimeTools.push(Object.freeze({ definition, descriptor }));
+  }
+  return Object.freeze({ contractTools, runtimeTools: Object.freeze(runtimeTools) });
+}
 function validateMcpSchemas(config) {
   prepareMcpSurface(config.services, {
     extend: config.extend,
@@ -686,8 +749,22 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
   }
 }
 function buildMcpServer(config, auth) {
-  const services = typeof config.services === "function" ? config.services(auth) : config.services;
-  const prepared = prepareMcpSurface(services, {
+  let surface;
+  if (config.surfaces) {
+    const key = config.selectSurface(auth);
+    if (!Object.hasOwn(config.surfaces, key)) {
+      throw new Error(`[stitchkit] Unknown MCP surface "${key}"`);
+    }
+    const selected = config.surfaces[key];
+    if (!selected)
+      throw new Error(`[stitchkit] Unknown MCP surface "${key}"`);
+    surface = selected;
+  } else {
+    const services = typeof config.services === "function" ? config.services(auth) : config.services;
+    const runtimeTools = typeof config.runtimeTools === "function" ? config.runtimeTools(auth) : config.runtimeTools;
+    surface = { services, runtimeTools };
+  }
+  const prepared = prepareMcpServerSurface(surface, {
     extend: config.extend,
     flattenUnionInput: config.flattenUnionInput,
     schemaValidation: config.schemaValidation,
@@ -698,7 +775,7 @@ function buildMcpServer(config, auth) {
 function buildMcpServerFromPrepared(config, auth, prepared) {
   const server = new McpServer(config.serverInfo, config.instructions ? { instructions: config.instructions } : undefined);
   const context = config.context?.(auth);
-  mountPreparedMcp(server, prepared, {
+  mountPreparedMcp(server, prepared.contractTools, {
     context,
     hooks: config.hooks,
     lifecycle: config.lifecycle,
@@ -710,23 +787,15 @@ function buildMcpServerFromPrepared(config, auth, prepared) {
     errorHint: config.errorHint,
     onOutputStrip: config.onOutputStrip
   });
-  if (config.nativeTools) {
-    const takenNames = new Set(prepared.map((tool2) => tool2.mountable.name));
-    const registrar = createNativeMcpRegistrar(server, {
-      context,
-      hooks: config.hooks,
-      lifecycle: config.lifecycle,
-      coerceJsonArgs: config.coerceJsonArgs,
-      onOutputStrip: config.onOutputStrip,
-      takenNames,
-      prepare: (tool2) => prepareMcpTools([tool2], {
-        schemaValidation: config.schemaValidation,
-        logger: config.logger
-      }),
-      formatResult: (result, mode, toolName) => formatMcpResult(result, mode, toolName, config.errorHint)
-    });
-    config.nativeTools(registrar, auth);
-  }
+  mountPreparedRuntimeMcp(server, prepared.runtimeTools, {
+    context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip,
+    formatResult: (result, mode, toolName) => formatMcpResult(result, mode, toolName, config.errorHint)
+  });
+  config.rawTools?.(server, auth);
   for (const resource of config.resources ?? []) {
     mountMcpResource(server, resource);
   }
@@ -838,13 +907,37 @@ function jsonRpcError(code, message, status, headers) {
 }
 function createMcpHandler(config) {
   let buildServer;
-  if (Array.isArray(config.services)) {
-    const prepared = prepareMcpSurface(config.services, {
-      logger: config.logger,
-      extend: config.extend,
-      flattenUnionInput: config.flattenUnionInput,
-      schemaValidation: config.schemaValidation
-    });
+  const preparation = {
+    logger: config.logger,
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config.schemaValidation
+  };
+  if (config.surfaces && config.selectSurface) {
+    const selectSurface = config.selectSurface;
+    const preparedByKey = new Map;
+    const preparedBySurface = new WeakMap;
+    for (const key in config.surfaces) {
+      if (!Object.hasOwn(config.surfaces, key))
+        continue;
+      const surface = config.surfaces[key];
+      if (!surface)
+        continue;
+      const existing = preparedBySurface.get(surface);
+      const prepared = existing ?? prepareMcpServerSurface(surface, preparation);
+      if (!existing)
+        preparedBySurface.set(surface, prepared);
+      preparedByKey.set(key, prepared);
+    }
+    buildServer = (auth) => {
+      const key = selectSurface(auth);
+      const prepared = preparedByKey.get(key);
+      if (!prepared)
+        throw new Error(`[stitchkit] Unknown MCP surface "${key}"`);
+      return buildMcpServerFromPrepared(config, auth, prepared);
+    };
+  } else if (config.services && typeof config.services !== "function" && typeof config.runtimeTools !== "function") {
+    const prepared = prepareMcpServerSurface({ services: config.services, runtimeTools: config.runtimeTools }, preparation);
     buildServer = (auth) => buildMcpServerFromPrepared(config, auth, prepared);
   } else {
     buildServer = (auth) => buildMcpServer(config, auth);
@@ -1490,7 +1583,7 @@ function parseApiErrorBody(body) {
 
 // src/browser/client.ts
 function withTimeout(options, endpoint) {
-  const responseType = endpoint.rawResponse ? "response" : undefined;
+  const responseType = endpoint.rawResponse ? "response" : endpoint.output ? undefined : "void";
   if (endpoint.timeout === undefined && responseType === undefined)
     return options;
   return {
@@ -1500,10 +1593,20 @@ function withTimeout(options, endpoint) {
   };
 }
 function withOutput(endpoint, result) {
-  const schema = endpoint.output;
-  if (!schema)
+  if (endpoint.rawResponse)
     return result;
-  return result.then((value) => value === undefined ? undefined : schema.parse(value));
+  const schema = endpoint.output;
+  return result.then((value) => {
+    if (!schema) {
+      if (value === undefined || value === null)
+        return;
+      throw new Error("Server returned data for an endpoint with no output contract");
+    }
+    if (value === undefined) {
+      throw new Error("Server returned no body for an endpoint with an output contract");
+    }
+    return schema.parse(value);
+  });
 }
 function createClient(contract, configOrClient, contractConfig) {
   const client = {};
@@ -1580,10 +1683,14 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       }
       if (endpoint.rawResponse)
         return res2;
-      if (res2.status === 204)
+      if (!endpoint.output) {
+        const text = await res2.text();
+        if (text.length > 0) {
+          throw new Error("Server returned data for an endpoint with no output contract");
+        }
         return;
-      const json3 = await res2.json();
-      return endpoint.output ? endpoint.output.parse(json3) : json3;
+      }
+      return endpoint.output.parse(await res2.json());
     }
     const res = await fetch(url, {
       method: endpoint.method,
@@ -1599,10 +1706,14 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
     }
     if (endpoint.rawResponse)
       return res;
-    if (res.status === 204)
+    if (!endpoint.output) {
+      const text = await res.text();
+      if (text.length > 0) {
+        throw new Error("Server returned data for an endpoint with no output contract");
+      }
       return;
-    const json2 = await res.json();
-    return endpoint.output ? endpoint.output.parse(json2) : json2;
+    }
+    return endpoint.output.parse(await res.json());
   };
 }
 async function throwForErrorResponse(res, config, fallbackBody) {
@@ -1709,27 +1820,71 @@ function createToolkit() {
   };
 }
 // src/tools/transports.ts
+var ALL_TRANSPORTS = ["HTTP", "MCP", "AGENT", "CLI"];
 var TOOL_TRANSPORTS2 = ["MCP", "AGENT", "CLI"];
 function emptyCounts() {
   return { HTTP: 0, MCP: 0, AGENT: 0, CLI: 0 };
 }
-function summarizeTransports(services) {
+function contractCounts(service) {
+  const counts = emptyCounts();
+  for (const method of Object.values(service.methods)) {
+    if (!method.expose || method.expose.includes("HTTP"))
+      counts.HTTP += 1;
+  }
+  for (const transport of TOOL_TRANSPORTS2) {
+    counts[transport] = collectToolSurface({
+      surface: { services: [service] },
+      transport,
+      assertNames: false,
+      assertUniqueNames: false
+    }).length;
+  }
+  return counts;
+}
+function runtimeCounts(runtimeTools) {
+  const counts = emptyCounts();
+  for (const transport of TOOL_TRANSPORTS2) {
+    counts[transport] = collectToolSurface({
+      surface: { runtimeTools },
+      transport,
+      assertNames: false,
+      assertUniqueNames: false
+    }).length;
+  }
+  return counts;
+}
+function addCounts(target, source) {
+  for (const transport of ALL_TRANSPORTS)
+    target[transport] += source[transport];
+}
+function summarizeTransports(surface) {
   const totals = emptyCounts();
-  const perService = services.map((service) => {
-    const counts = emptyCounts();
-    for (const method of Object.values(service.methods)) {
-      if (!method.expose || method.expose.includes("HTTP"))
-        counts.HTTP += 1;
-    }
-    for (const transport of TOOL_TRANSPORTS2) {
-      counts[transport] = collectTools(service, transport, { assertNames: false }).length;
-    }
-    for (const transport of Object.keys(counts)) {
-      totals[transport] += counts[transport];
-    }
-    return { service: service.name, counts };
-  });
-  return { services: services.length, totals, perService };
+  const sources = [];
+  for (const service of surface.services ?? []) {
+    const counts = contractCounts(service);
+    addCounts(totals, counts);
+    sources.push({ kind: "contract", service: service.name, counts });
+  }
+  const runtimeGroups = new Map;
+  for (const definition of surface.runtimeTools ?? []) {
+    const service = definition.identity.serviceName;
+    const group = runtimeGroups.get(service);
+    if (group)
+      group.push(definition);
+    else
+      runtimeGroups.set(service, [definition]);
+  }
+  for (const [service, runtimeTools] of runtimeGroups) {
+    const counts = runtimeCounts(runtimeTools);
+    addCounts(totals, counts);
+    sources.push({ kind: "runtime", service, counts });
+  }
+  return {
+    contractServices: surface.services?.length ?? 0,
+    runtimeTools: surface.runtimeTools?.length ?? 0,
+    totals,
+    sources
+  };
 }
 // src/tools/view-file.ts
 import { readFile, realpath, stat } from "node:fs/promises";