stitchkit 0.24.0 → 0.26.0

package/dist/tools.js

@@ -2,11 +2,13 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-a9n8m4ec.js";
+} from "./index-p6fge9a5.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-tje0q6gp.js";
 import {
+  assertToolName,
+  assertUniqueToolName,
   coerceJsonArgs,
   collectTools,
   createCli,
@@ -17,15 +19,17 @@ import {
   formatToolError,
   pollUntil,
   readCapped,
-  toolResultFromError
-} from "./index-x8m8e7dc.js";
+  toolResultFromError,
+  writeDownload
+} from "./index-q5w3cvvp.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
   AppError,
-  isWithinDir
-} from "./index-4gawbm74.js";
+  isWithinDir,
+  mergeMeta
+} from "./index-0d0rb85d.js";
 import"./index-khwedj16.js";
 import {
   isRecord,
@@ -44,16 +48,15 @@ function mountAgent(services, config = {}) {
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     errorHint: config.errorHint,
-    coerceJsonArgs: config.coerceJsonArgs
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip
   });
   for (const service of serviceList) {
     for (const mountable of collectTools(service, "AGENT", {
       extend: config.extend,
       flattenUnionInput: config.flattenUnionInput
     })) {
-      if (mountable.name in tools) {
-        throw new Error(`Duplicate agent tool name "${mountable.name}" across mounted services`);
-      }
+      assertUniqueToolName(mountable.name, Object.hasOwn(tools, mountable.name), "agent tool name");
       tools[mountable.name] = tool({
         description: mountable.method.desc,
         inputSchema: zodSchema(mountable.schema),
@@ -79,7 +82,7 @@ function listToolNames(services) {
   const entries = new Map;
   for (const service of services) {
     for (const transport of TOOL_TRANSPORTS) {
-      for (const tool2 of collectTools(service, transport)) {
+      for (const tool2 of collectTools(service, transport, { assertNames: false })) {
         const id = `${service.name}\x00${tool2.method.key}`;
         const existing = entries.get(id);
         if (existing) {
@@ -188,9 +191,7 @@ function throwIfFailures(failures) {
   }
 }
 function prepareMcpTool(mountable, policy, logger, failures, seen) {
-  if (seen.has(mountable.name)) {
-    throw new Error(`Duplicate MCP tool name "${mountable.name}" across mounted services`);
-  }
+  assertUniqueToolName(mountable.name, seen.has(mountable.name), "MCP tool name");
   seen.add(mountable.name);
   if (!(mountable.schema instanceof z.ZodObject)) {
     reportIncompatible(`MCP tool "${mountable.name}" — input must be an object schema; a union, discriminated union or scalar cannot be an MCP tool input (flatten it in the contract, or drop MCP from \`expose\`)`, policy, logger, failures);
@@ -231,7 +232,8 @@ function mountMcp(mcpServer, services, config = {}) {
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     errorHint: config.errorHint,
-    coerceJsonArgs: config.coerceJsonArgs
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip
   });
   const seen = new Set;
   const failures = [];
@@ -283,7 +285,7 @@ function buildMcpServer(config, auth) {
     flattenUnionInput: config.flattenUnionInput,
     errorHint: config.errorHint
   });
-  config.nativeTools?.(server);
+  config.nativeTools?.(server, auth);
   for (const resource of config.resources ?? []) {
     mountMcpResource(server, resource);
   }
@@ -490,7 +492,6 @@ async function createStdioMcpServer(config) {
   return server;
 }
 // src/tools/mount-download.ts
-import { mkdir, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 
 // src/tools/native-result.ts
@@ -531,7 +532,9 @@ function baseNameFor(url) {
   }
 }
 function mountDownload(server, config) {
-  server.registerTool(config.name ?? "download", { description: config.description, inputSchema: config.inputSchema }, async (rawArgs) => {
+  const name = config.name ?? "download";
+  assertToolName(name, "<native>", "download");
+  server.registerTool(name, { description: config.description, inputSchema: config.inputSchema }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     try {
       const url = await config.resolveUrl(args);
@@ -551,9 +554,8 @@ function mountDownload(server, config) {
       if (!buffer)
         return textResult(`Download failed: file exceeds the ${max}-byte cap`, true);
       const dir = config.dirFromArgs?.(args) ?? config.defaultDir;
-      await mkdir(dir, { recursive: true });
       const filePath = join(dir, `${baseNameFor(url)}${extensionFor(url, mimeType)}`);
-      await writeFile(filePath, buffer);
+      await writeDownload(dir, filePath, buffer);
       return textResult(JSON.stringify({ path: filePath, size: buffer.length, mimeType }, null, 2));
     } catch (err) {
       return textResult(`Download failed: ${err instanceof Error ? err.message : String(err)}`, true);
@@ -563,7 +565,9 @@ function mountDownload(server, config) {
 // src/tools/mount-upload.ts
 import { z as z2 } from "zod";
 function mountUpload(server, config) {
-  server.registerTool(config.name ?? "upload", {
+  const name = config.name ?? "upload";
+  assertToolName(name, "<native>", "upload");
+  server.registerTool(name, {
     description: config.description,
     inputSchema: { path: z2.string().describe("Path to a local file on this machine") }
   }, async (rawArgs) => {
@@ -581,7 +585,9 @@ function mountUpload(server, config) {
 }
 // src/tools/mount-wait.ts
 function mountWait(server, config) {
-  server.registerTool(config.name ?? "wait", { description: config.description, inputSchema: config.inputSchema }, async (rawArgs) => {
+  const name = config.name ?? "wait";
+  assertToolName(name, "<native>", "wait");
+  server.registerTool(name, { description: config.description, inputSchema: config.inputSchema }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     try {
       const { state, timedOut } = await pollUntil({
@@ -870,6 +876,25 @@ function mountOAuthProvider(config) {
   };
   return [metadataRoute, registerRoute, authorizeRoute, tokenRoute];
 }
+// src/browser/client-multipart.ts
+function isFileDescriptor(value) {
+  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
+}
+function isMultipartFile(value) {
+  return value instanceof Blob || isFileDescriptor(value);
+}
+function appendMultipartFile(form, field, file) {
+  const sink = form;
+  sink.append(field, file);
+}
+function appendFormFields(formData, values, skipKeys) {
+  for (const [key, value] of Object.entries(values)) {
+    if (skipKeys.has(key) || value === undefined || value === null)
+      continue;
+    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+  }
+}
+
 // src/browser/http.ts
 import ky, { isHTTPError } from "ky";
 class ApiError extends Error {
@@ -1079,23 +1104,6 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
     return endpoint.output ? endpoint.output.parse(json2) : json2;
   };
 }
-function isFileDescriptor(value) {
-  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
-}
-function isMultipartFile(value) {
-  return value instanceof Blob || isFileDescriptor(value);
-}
-function appendMultipartFile(form, field, file) {
-  const sink = form;
-  sink.append(field, file);
-}
-function appendFormFields(formData, values, skipKeys) {
-  for (const [key, value] of Object.entries(values)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
-  }
-}
 async function throwForErrorResponse(res, config, fallbackBody) {
   const body = await res.json().catch(() => fallbackBody);
   config.onError?.(res.status, body);
@@ -1159,7 +1167,7 @@ function implementRemote(contract, http, options) {
       expose: endpoint.expose,
       ui: "ui" in endpoint ? endpoint.ui : undefined,
       annotations: "annotations" in endpoint ? endpoint.annotations : undefined,
-      meta: endpoint.meta,
+      meta: mergeMeta(contract.meta.meta, endpoint.meta),
       scope: endpoint.scope ?? groupScope,
       paramsSchema: endpoint.params,
       inputSchema: endpoint.input,
@@ -1236,7 +1244,7 @@ function summarizeTransports(services) {
         counts.HTTP += 1;
     }
     for (const transport of TOOL_TRANSPORTS2) {
-      counts[transport] = collectTools(service, transport).length;
+      counts[transport] = collectTools(service, transport, { assertNames: false }).length;
     }
     for (const transport of Object.keys(counts)) {
       totals[transport] += counts[transport];

package/llms-full.txt

@@ -237,7 +237,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | `output` | no | Zod schema for the **response body** |
 | `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
 | `expose` | no | which transports carry this endpoint — see [below](#transports) |
-| `toolName` | no | explicit MCP / agent tool name (defaults to `prefix_key`) |
+| `toolName` | no | explicit MCP / agent tool name (default: a verb-aware derivation, see below — not a literal `prefix_key`) |
 | `multipart` | no | field name of a file upload — see [below](#file-uploads) |
 | `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
 | `idempotent` | no | safe to call twice with the same input (like `PUT`/`DELETE`); a retrying transport reads it — see [Realtime](./realtime.md#bring-your-own-transport) |
@@ -326,8 +326,41 @@ derivation from the method key + prefix (`users` + `create` ⇒ `create_user`,
 { method: 'POST', path: '/', desc: 'Create a user', toolName: 'create_user', /* … */ }
 ```
 
+**Every tool name — derived or explicit — must match `[a-zA-Z0-9_-]` and be at
+most 64 characters**, the character class every major provider accepts.
+
+Note the two classes differ. What is *accepted* includes the hyphen; what
+derivation *keeps* does not — a derived name normalises everything outside
+`[a-zA-Z0-9_]` to `_`, the hyphen included, so `bot-status` + `get` ⇒
+`get_bot_status` and `admin/analytics` + `get` ⇒ `get_admin_analytics`. A hyphen
+survives only in an explicit `toolName`, which is taken verbatim.
+
+A prefix with *no* usable character at all (`'///'`, `'_'`, a fully non-ASCII
+prefix) and any explicit `toolName` outside the accepted class **throw at
+mount**. An unusable prefix is rescued by setting an explicit `toolName` — the
+prefix then never enters the name. An over-long name is fixed by a shorter
+explicit `toolName` (or a shorter prefix / method key). Nothing downstream checks this: the provider rejects the whole
+request, so one bad name takes every tool of that mount down with it.
+→ [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md).
+
 ## Endpoint metadata (`meta`)
 
+A contract can declare a **default** `meta` that every endpoint inherits, and an
+endpoint's own keys are **shallow-merged over** it:
+
+```ts
+defineContract({ prefix: 'admin', meta: { public: true } }, {
+  list: { method: 'GET', path: '/', desc: 'List', /* meta → { public: true } */ },
+  purge: { method: 'POST', path: '/purge', desc: 'Purge', meta: { rateTier: 2 } },
+  //                                          meta → { public: true, rateTier: 2 }
+})
+```
+
+One level deep — no deep merge, no way to unset an inherited key; declare it on
+the endpoint instead. `expose` deliberately has **no** contract-level equivalent
+(→ [ADR 0036](../decisions/0036-contract-level-meta.md)).
+
+
 `meta` is an **opaque, app-defined** bag the core attaches no meaning to — the
 same escape-hatch spirit as `scope` being a free string ([ADR 0002](../decisions/0002-generic-core.md) /
 [ADR 0021](../decisions/0021-endpoint-meta-passthrough.md)). Declare app concerns
@@ -1172,7 +1205,14 @@ By default every endpoint is a tool on every transport. `expose` narrows it:
 `desc` is the tool description the model reads — write it for the model, not
 just for a human. A `multipart` endpoint is never a tool. The tool name defaults
 to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
-`get_widget`); set `toolName` for an explicit one. See
+`get_widget`); set `toolName` for an explicit one. Derivation normalises every
+character outside `[a-zA-Z0-9_]` to `_` — the hyphen included, so `bot-status`
+derives `get_bot_status` — while a name is *accepted* if it matches
+`[a-zA-Z0-9_-]`, so a hyphen survives in an explicit `toolName`. A name that
+still cannot be delivered (illegal explicit `toolName`, over 64 characters, or a
+prefix with no usable character) throws at mount rather than at the first model
+call —
+→ [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md). See
 [Contracts → transports](./contracts.md#transports).
 
 ### Pinning tool names — `listToolNames`
@@ -1196,6 +1236,14 @@ now fails this test instead of silently breaking the clients that call the
 tool. It is also the mechanical diff when migrating a service: run it before
 and after, compare.
 
+> **This is also the guard against a forgotten `expose`.** An endpoint that
+> declares none is a tool on MCP **and** AGENT — the default is fail-open, and
+> there is no contract-level `expose` to set once (→
+> [ADR 0036](../decisions/0036-contract-level-meta.md)). A snapshot of
+> `listToolNames` fails the build the moment an endpoint you meant to keep
+> HTTP-only shows up in the list, which is the one check that catches it however
+> many places the line was forgotten.
+
 ## MCP — `createMcpHandler`
 
 `createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
@@ -1234,11 +1282,11 @@ createServer({
 | `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
 | `onIncompatibleSchema` | `'throw'` (default) · `'skip'` · `'warn'` — see below |
 | `logger` | a `StitchLogger` for the `'warn'` policy |
-| `nativeTools` | register non-contract tools directly on the `McpServer` |
+| `nativeTools` | `(server, auth) => …` — register non-contract tools directly on the `McpServer`; receives the resolved identity, but is **not** a scope gate (`lifecycle` does not run for native tools) |
 | `instructions` | a short host-facing usage hint, surfaced to MCP tool-search |
 
-`services` and `context` receive the resolved identity, so a tenant can be
-shown only its own tools and every handler can read `ctx.tenantId`.
+`services`, `context` and `nativeTools` all receive the resolved identity, so a
+tenant can be shown only its own tools and every handler can read `ctx.tenantId`.
 
 ### Guarding tools — `lifecycle`
 
@@ -1303,11 +1351,23 @@ each variant's fields become optional with a `Required if <disc> = …` hint.
 It is **deep**: unions are flattened at every depth — top level, object fields,
 array items, and through `optional` / `nullable` / `default` / intersection
 wrappers — so no `oneOf` survives anywhere (e.g. a `content.parts[]` that is an
-array of a discriminated union). It is **advertised-only and lossy**: the original
-schemas stay the validation schemas in `executeToolMethod`, so requests are still
-validated against the real union. Schemas a transform cannot safely rebuild
+array of a discriminated union). Schemas a transform cannot safely rebuild
 (refined / piped / lazy / plain non-discriminated unions) are left as-is.
 
+The flattened form is **lossy but never destructive**. Lossy: per-variant
+strictness and object-level refinements are not advertised — the original schemas
+enforce them in `executeToolMethod`. Not destructive: every object keeps its own
+**key policy** (`.strict()` stays strict, `.loose()` / `.catchall()` still keep
+extra keys), because the advertised schema is not advertised-only — the MCP and
+AI SDKs parse the caller's arguments *with it* and hand the handler the parsed
+result. An object advertised without its policy would silently delete keys the
+contract would have rejected. → [ADR 0034](../decisions/0034-advertised-schema-key-policy.md).
+
+A consequence worth knowing when you read logs: a `.strict()` violation is caught
+by the SDK **before** the tool callback runs, so it comes back as an MCP
+`InvalidParams` protocol error rather than a stitchkit `VALIDATION_ERROR`
+envelope, and `beforeToolCall` / `afterToolCall` do not fire for it.
+
 ## `mountMcp`
 
 If you already run an `McpServer` from the SDK, `mountMcp` adds contract tools
@@ -2467,7 +2527,13 @@ const onError = createErrorHook({
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
   } satisfies Record<StitchErrorCode, string>,
-  render: (info) => ({ ok: false, error: { code: info.code, message: info.message } }),
+  // `ctx` is the request's RuntimeContext — read `ctx.traceId` for a
+  // correlation id in the envelope. Declaring it is optional.
+  render: (info, ctx) => ({
+    ok: false,
+    error: { code: info.code, message: info.message },
+    traceId: ctx.traceId,
+  }),
 })
 
 createServer({ services, hooks: { onError } })
@@ -3111,6 +3177,42 @@ current one *up to* your target, and apply each snippet.
    (`STITCH_ERROR_STATUS`, `serveFile`, `scopePrefixes`, `afterToolCall`'s
    `MethodDef`, `maxUploadBytes`) are available to adopt, not required.
 
+## Your handlers may be returning more than the contract declares
+
+stitchkit validates every handler's return value against the endpoint's `output`
+schema and **passes on the parsed result** — so any field the schema does not
+declare is silently removed. That is deliberate (the contract is the published
+shape of the response), but when you are moving a *live* API onto stitchkit it is
+invisible: TypeScript does not reject excess properties, nothing logs it, and the
+client just receives fewer fields.
+
+While migrating, turn the diagnostic on:
+
+```ts
+createServer({ services, warnOnOutputStrip: true })   // off by default
+```
+
+Every removed key is logged as a dot-path with the endpoint that produced it
+(`notes.get: secret, nested.alsoSecret`). Tool transports strip identically —
+`mountMcp` / `mountAgent` take `onOutputStrip: (toolName, paths) => …`. Read the
+list, then either widen the contract or stop returning the field, and turn the
+flag back off: it is for the migration window, not for production.
+
+## Tool names may shift between versions
+
+Derived tool names are part of your public surface — an MCP client config or an
+agent prompt refers to them by string. Before and after any upgrade that touches
+name derivation, diff them mechanically:
+
+```ts
+import { listToolNames } from 'stitchkit/tools'
+console.log(JSON.stringify(listToolNames(services), null, 2))
+```
+
+`listToolNames` never throws on an illegal name — that is deliberate, so it can
+show you the offending row when a mount would refuse it. Pin it in a snapshot
+test and a shift fails your build instead of your clients.
+
 ## When you author a breaking change in stitchkit
 
 You are on the other side of this flow — see
@@ -3200,7 +3302,7 @@ from the root `stitchkit`.
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
-| `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` |
+| `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition |
 | `HttpMethod` | _type_ | `GET \| POST \| PUT \| PATCH \| DELETE` |
 | `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
@@ -3529,7 +3631,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `flattenDiscriminatedUnion` | function | flatten one discriminated union into a single object schema |
-| `flattenUnionsDeep` | function | flatten discriminated unions at every depth (advertised schema only) |
+| `flattenUnionsDeep` | function | flatten discriminated unions at every depth — union shape only; each object keeps its own key policy (`.strict()` / `.loose()` / `.catchall()`) |
 | `MountableTool` | _type_ | one contract method resolved for mounting |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "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",