stitchkit 0.25.0 → 0.26.0

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`
 
@@ -2479,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 } })
@@ -3123,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
@@ -3212,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` |

package/package.json

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