stitchkit 0.37.0 → 0.39.0

package/llms-full.txt

@@ -229,8 +229,8 @@ export const users = defineContract({ prefix: 'users' }, {
 
 | Field | Required | Purpose |
 |-------|----------|---------|
-| `method` | yes | `GET` · `POST` · `PUT` · `PATCH` · `DELETE` |
-| `path` | yes | route path under the contract `prefix`; `:name` marks a path param |
+| `method` | yes | `GET` · `HEAD` · `POST` · `PUT` · `PATCH` · `DELETE` |
+| `path` | yes | route path under the contract `prefix`; `:name` marks a path param and a named terminal `/*filePath` captures the remaining path |
 | `desc` | yes | human description — also the MCP / agent tool description |
 | `params` | no | Zod schema for **path params** (`:id`, …) |
 | `input` | no | Zod schema for the **request body** (or query, for GET/DELETE) |
@@ -245,15 +245,27 @@ export const users = defineContract({ prefix: 'users' }, {
 | `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
 | `rawResponse` | no | the handler returns the `Response` itself — a download, a file, an SSE stream. HTTP-only, never a tool, no `output`. See [Raw-response endpoints](./server.md#raw-response-endpoints) |
 | `rawBody` | no | retain original JSON text for a signed HTTP webhook. See [Signed JSON webhooks](./server.md#signed-json-webhooks) |
+| `responseMeta` | no | make a typed-data endpoint HTTP-only, optionally declare its success status and expose `ctx.response.headers` — [Typed JSON response metadata](./server.md#typed-json-response-metadata) |
 | `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
 
+`HEAD` is an explicit HTTP-only operation, never an automatic alias for `GET`.
+It must declare `rawResponse: true`; request body, `input`, multipart, `rawBody`,
+typed `output` and tool exposure are rejected. The handler owns status and
+headers, while Stitchkit guarantees an empty wire body even if the returned
+`Response` accidentally contains one.
+
 ## `params` vs `input` vs `output`
 
 The three schemas are distinct on purpose:
 
 - **`params`** — values in the URL path. `path: '/:id'` ⇒
   `params: z.object({ id: z.string() })`. The client takes them from the call
-  argument and substitutes them into the URL.
+  argument and substitutes them into the URL. A terminal wildcard is explicitly
+  named: `path: '/:slug/*filePath'` with
+  `params: z.object({ slug: z.string(), filePath: z.string() })` matches both
+  `/foo/page` and `/foo/a/b`; the handler reads `ctx.params.filePath` as
+  `'page'` or `'a/b'`. Bare `/*`, invalid/duplicate names and a wildcard before
+  the final segment fail at contract definition.
 - **`input`** — the request payload. For `POST` / `PUT` / `PATCH` it is the JSON
   body; for `GET` / `DELETE` it is the query string. The handler reads it as
   `ctx.input`.
@@ -267,6 +279,9 @@ the body.
 ```ts
 // path: '/:id', params: { id }, input: { text }
 await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
+
+// path: '/:slug/*filePath', params: { slug, filePath }
+await api.app({ slug: 'foo', filePath: 'a/b' })   // GET /apps/foo/a/b
 ```
 
 ### Input vs. output types
@@ -317,10 +332,12 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
-Tool transports (`MCP`, `AGENT`) skip two kinds of endpoint automatically:
+Tool transports (`MCP`, `AGENT`) skip three kinds of endpoint automatically:
 `multipart` (a file upload is not a tool call) and
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
-a tool result cannot carry — it would serialize to `{}`).
+a tool result cannot carry — it would serialize to `{}`), plus
+[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
+headers have no meaning on a tool call).
 
 ## `toolName`
 
@@ -764,6 +781,18 @@ prefix param in the schema, use a non-strict `z.object` (extra keys are dropped
 from `ctx.params`, but `ctx.tenantId` still works), or read the param off the
 context root.
 
+**Trailing wildcard.** A contract path may end in a named wildcard.
+`/app/:slug/*filePath` matches
+both `/app/foo` and nested paths such as `/app/foo/a/b`; the collected params are
+`{ slug: 'foo', filePath: '' }` and `{ slug: 'foo', filePath: 'a/b' }`
+respectively. Put `filePath` in the endpoint's `params` schema to keep it in
+typed `ctx.params`. Each captured segment is URL-decoded before the remainder is
+joined, so encoded spaces and reserved characters reach the handler as their
+semantic values while `/` remains the segment boundary. Static and named-param
+routes are matched before a catch-all, so a
+more specific endpoint wins regardless of declaration order. The same matcher
+drives `405 Allow` resolution.
+
 ### Scope-driven mounting (`scopePrefixes`)
 
 With several scopes, hand-partitioning services into `groups` duplicates the
@@ -796,7 +825,7 @@ createServer({
   hooks: {
     onRequest(req)               { /* logging, global rate limit — may return a Response to short-circuit */ },
     beforeHandle(ctx, endpoint)  { /* auth, scope checks — throw to reject */ },
-    afterHandle(ctx, result, ep) { /* transform the result, set cache headers */ },
+    afterHandle(ctx, result, ep) { /* transform the result data */ },
     onError(ctx, error, ep)      { /* custom error response — return a Response */ },
   },
 })
@@ -849,6 +878,46 @@ not retain the text. `maxJsonBodyBytes` may also be set once on `createServer` /
 `createHandler`; a route value wins. Both limits are opt-in and abort an
 oversized stream before it is fully buffered. → ADR 0051
 
+## Typed JSON response metadata
+
+A JSON endpoint that must attach dynamic HTTP headers while preserving typed
+output declares `responseMeta`. The handler still returns ordinary data:
+
+```ts
+const auth = defineContract({ prefix: 'auth' }, {
+  complete: {
+    method: 'POST', path: '/complete', desc: 'Complete authentication',
+    input: CompleteAuthSchema,
+    output: AuthUserSchema,
+    responseMeta: { status: 200 },
+  },
+})
+
+complete: async ({ input, response }) => {
+  const result = await authenticate(input.token)
+  response.headers.append('Set-Cookie', session.set(result.sessionId))
+  response.headers.append('Set-Cookie', preferences.set(result.preferencesId))
+  return result.user
+}
+```
+
+`ctx.response.headers` is a fresh Web Fetch `Headers` bag per request. `append`
+preserves repeated `Set-Cookie` values on Bun and Node. The endpoint is
+HTTP-only, but its typed client method still resolves to `AuthUser` — not
+`Response` — and the final data still passes group/global `afterHandle` and the
+declared `output` schema exactly once.
+
+`responseMeta.status` is static contract metadata and OpenAPI publishes the same
+2xx code. Without it, data keeps status `200` and no-data keeps `204`. Bodyless
+`204`/`205` cannot be combined with `output`. Redirects, streams, files and
+handler-owned status/body logic remain [`rawResponse: true`](#raw-response-endpoints).
+
+Collected headers are merged only after the complete success pipeline. A
+handler, hook or output-validation failure discards them. `Content-Type`,
+`Content-Length`, `x-request-id` and every `Access-Control-*` header remain
+framework-owned; trying to set one fails loudly with the endpoint identity.
+→ [ADR 0052](../decisions/0052-typed-json-response-metadata.md)
+
 ## Raw-response endpoints
 
 An endpoint that answers with **bytes rather than data** — a PDF download, a
@@ -891,6 +960,10 @@ const name = res.headers.get('Content-Disposition')
 const blob = await res.blob()
 ```
 
+When the browser should navigate or assign the endpoint directly to `src`, use
+[`createUrlBuilder`](./client.md#contract-url-builders). Raw-response GET methods
+are included, while mutation and multipart methods are intentionally absent.
+
 Cross-origin, remember that those headers are readable only because CORS exposes
 them — see [`cors.exposeHeaders`](#serving-files--range-requests).
 
@@ -902,6 +975,11 @@ client — which is what you want for an OAuth redirect or a non-JSON webhook. A
 signed JSON webhook can stay validated through
 [`rawBody: true`](#signed-json-webhooks).
 
+If an endpoint returns typed JSON and only needs an additional status/header,
+use [`responseMeta`](#typed-json-response-metadata), not `rawResponse`: the raw
+variant deliberately transfers response ownership and changes the client result
+to `Response`.
+
 ⚠️ **Delete the old raw route when you move an endpoint into the contract.** Raw
 routes are matched **first**, so a leftover one keeps serving the bytes and the
 contract endpoint — with its auth gate — never runs. stitchkit warns at startup
@@ -957,9 +1035,9 @@ createServer({
 })
 ```
 
-A path may be exact, carry `:param` segments, or end in `/*` for a prefix
-wildcard — and the two combine: `/app/:slug/*` matches `/app/x/a/b` with
-`ctx.params.slug === 'x'` and the remainder in `ctx.params['*']` (a SPA
+A path may be exact, carry `:param` segments, or end in `/*filePath` for a prefix
+wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` with
+`ctx.params.slug === 'x'` and the remainder in `ctx.params.filePath` (a SPA
 deep-link fallback). List more specific routes before the wildcard — the first
 match wins. `staticRoute()` builds a raw route that serves a directory.
 
@@ -998,24 +1076,35 @@ seek and cache, use **`serveFile`** (Bun) — it streams the requested byte rang
 and speaks the conditional-request half of RFC 7233 / 9110:
 
 ```ts
-import { serveFile } from 'stitchkit/server'
+import { defineContract } from 'stitchkit/contract'
+import { implement, serveFile } from 'stitchkit/server'
+import { z } from 'zod'
 
-createServer({
-  services,
-  rawRoutes: [
-    {
-      // `ALL` — so a HEAD probe also reaches serveFile (raw routes match the
-      // method exactly, and `HEAD` is not a contract `HttpMethod`); serveFile
-      // itself handles GET + HEAD and answers 405 for anything else.
-      method: 'ALL',
-      path: '/media/:id',
-      handler: (req, ctx) =>
-        serveFile(req, { path: pathForId(ctx.params.id), filename: 'clip.mp4' }),
-    },
-  ],
+const MediaParams = z.object({ id: z.string() })
+const media = defineContract({ prefix: 'media' }, {
+  download: {
+    method: 'GET', path: '/:id', desc: 'Download media',
+    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
+  },
+  inspect: {
+    method: 'HEAD', path: '/:id', desc: 'Inspect media',
+    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
+  },
+})
+
+const mediaService = implement(media, {
+  download: ({ req, params }) =>
+    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
+  inspect: ({ req, params }) =>
+    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
 })
 ```
 
+GET and HEAD are separate operations deliberately: declaring GET never creates
+a hidden HEAD alias. Both travel through the normal contract router, params,
+lifecycle/RBAC and request logging. A HEAD handler may inspect the raw query via
+`ctx.req.url`, but cannot declare a request input schema or body.
+
 `serveFile` returns `206` (range, with `Content-Range` + `Content-Length`), `200`
 (full), `416` (unsatisfiable, `Content-Range: bytes */size`), `304`
 (`If-None-Match` / `If-Modified-Since`), `404` (missing) or `405` (non GET/HEAD).
@@ -1135,6 +1224,15 @@ createServer({ services: [users, orders], rawRoutes: [openApiRoute('/openapi.jso
 
 Only HTTP-exposed methods appear (an MCP/agent-only tool is skipped).
 
+OpenAPI 3.1 has no standard multi-segment path parameter. For a contract path
+ending in a named wildcard such as `/*filePath`, Stitchkit keeps the literal
+runtime path, omits `filePath` from the
+standard `in: path` parameter list, and emits
+`x-stitchkit-trailing-wildcard` on the operation with its parameter name,
+schema and semantics. A generic OpenAPI client therefore cannot invent
+catch-all expansion; use Stitchkit's typed client or teach the generator that
+extension.
+
 ### Curating the spec — `includeMethod`
 
 To publish a **subset** — a public spec that advertises only some methods
@@ -1189,11 +1287,19 @@ and adds cookie auth, SSR cookie forwarding, error parsing into `ApiError`, a
 `401 → unauthorized` event stream and safe transport retry.
 
 ```ts
-import { createHttpClient } from 'stitchkit'
+import { contractEndpointMatchers, createHttpClient } from 'stitchkit'
+import { publicAuth } from '../shared/contracts'
 
-const http = createHttpClient({ baseUrl: '/api' })
+const http = createHttpClient({
+  baseUrl: '/api',
+  suppressUnauthorizedFor: contractEndpointMatchers(publicAuth, ['complete', 'verify']),
+})
 ```
 
+The returned `ConfiguredHttpClient` keeps that `baseUrl` as a readonly public
+field. Besides executing requests, it can therefore seed contract URL builders
+without repeating transport configuration.
+
 ### `HttpClientConfig`
 
 | Field | Default | Purpose |
@@ -1203,13 +1309,22 @@ const http = createHttpClient({ baseUrl: '/api' })
 | `credentials` | `'include'` | fetch credentials mode |
 | `retry` | 2× GET, network errors only | transport retry policy |
 | `headers` | — | extra headers — an object, or a function re-run per request |
-| `authEndpoints` | `['auth/']` | paths that should **not** emit `unauthorized` on 401 |
+| `suppressUnauthorizedFor` | `[]` | exact contract-derived operation matchers whose expected 401 does not emit `unauthorized` |
 | `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
 | `trace` | `false` | emit a W3C `traceparent` header on every request |
 
 `headers` as a function is the hook for runtime tokens — a bearer token or any
 short-lived credential — re-evaluated on every request.
 
+Expected 401 policy is explicit and contract-driven. Select individual
+operations with `contractEndpointMatchers(contract, ['login'])`, or omit the
+second argument to select every HTTP operation in that contract. Pass the same
+`ContractClientConfig` as the typed client when routes use a static or dynamic
+`pathPrefix`; dynamic matchers require `stripPrefixKeys`, so the helper can
+compile the prefix structure without a concrete tenant id. Matching is exact by
+path segments, including params and trailing wildcards — a shared prefix never
+suppresses a neighbouring protected endpoint.
+
 `trace: true` mints a fresh root trace per request. The stitchkit server
 [continues an inbound `traceparent`](./observability.md#trace-context), so the
 browser call, the HTTP handler and every nested tool call share one trace id
@@ -1235,10 +1350,22 @@ await api.update({ id: '1', name: 'M' })  // PUT /users/1  body: { name }
 await api.delete({ id: '1' })      // DELETE /users/1
 ```
 
+An explicit contract `HEAD` operation is exposed like any other typed method.
+Because HEAD endpoints are `rawResponse`, it resolves to the untouched
+`Response`, giving the caller direct access to status and headers without JSON
+parsing:
+
+```ts
+const response = await assets.head({ name: 'clip.mp4' })
+console.log(response.headers.get('content-length'))
+```
+
 Each call takes one argument object. The client routes each field by the
 contract:
 
 - a **path param** (`:id`) is substituted into the URL,
+- a named terminal wildcard (`/*filePath`) consumes that field and preserves its
+  path segments (`{ filePath: 'a/b' }` → `/a/b`, not `/%2Fa%2Fb` or a query field),
 - for `GET` / `DELETE`, the remaining fields become the **query string**
   (arrays become repeated keys),
 - for `POST` / `PUT` / `PATCH`, they become the **JSON body**,
@@ -1257,8 +1384,87 @@ await api.users.list()
 await api.posts.create({ title: 'Hi' })
 ```
 
+When contracts use different path-prefix rules, route the same registry by the
+scope already declared in each contract. An array composes contracts with
+different scopes into one logical namespace:
+
+```ts
+const api = createScopedClients(
+  { auth: [publicAuth, authenticatedAuth], widgets },
+  http,
+  {
+    public: {},
+    user: {},
+    tenant: {
+      stripPrefixKeys: ['tenantId'],
+      pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+    },
+  },
+)
+
+await api.auth.login()
+await api.auth.me()
+await api.widgets.list({ tenantId: 't1' })
+```
+
+Every scope present in the registry needs a config. Unknown/missing scopes and
+duplicate method names inside a composed namespace fail before a request runs.
+
 `createClients` builds one typed client per contract from a registry — list the
-contracts once, get the whole API typed.
+contracts once, get the whole API typed. It accepts the same optional scoped
+config as `createClient`, so a whole registry can share one resource prefix:
+
+```ts
+const tenantApi = createClients({ users, posts }, http, {
+  stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+})
+```
+
+Every method now requires `tenantId`, and the callback sees it as a `string`.
+The batch form delegates to the same single-contract client runtime, including
+HTTP exposure filtering, multipart, raw responses and output validation.
+
+## Contract URL builders
+
+Browser-native consumers such as `<img src>`, downloads and navigation need a
+URL, not a fetched response. `createUrlBuilder` derives those URLs from the same
+contract path planner used by both typed-client transports:
+
+```ts
+import { createUrlBuilder, createUrlBuilders } from 'stitchkit'
+
+const mediaUrls = createUrlBuilder(media, http, {
+  stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+})
+
+const src = mediaUrls.file({
+  tenantId: 't_123',
+  fileId: 'f_456',
+  thumbnail: true,
+})
+
+// Body and multipart fields are intentionally absent: only the URL-bound
+// params are accepted by URL functions.
+const formAction = mediaUrls.replace({ tenantId: 't_123', fileId: 'f_456' })
+const beaconUrl = mediaUrls.track({ tenantId: 't_123' })
+
+const urls = createUrlBuilders({ media, exports }, http)
+```
+
+Every HTTP-exposed endpoint appears on a URL builder, including body, multipart
+and raw-response operations. Path and scoped-prefix keys are consumed by the
+path. `GET` and `DELETE` input becomes the query string, including repeated keys
+for arrays; body-method input and multipart files are not URL arguments and are
+never serialized into the URL. Passing such a field through an untyped boundary
+fails before a URL is returned.
+
+Building a URL is synchronous and performs no request, auth event, header
+resolution or output validation. A `ConfiguredHttpClient` created by
+`createHttpClient` supplies its base URL; custom transports can pass an explicit
+`{ baseUrl: 'https://api.example.com' }` instead. Relative bases produce relative
+URLs.
 
 ## `ApiError`
 
@@ -1288,7 +1494,7 @@ The HTTP client emits events your app can react to globally:
 
 ```ts
 const unsubscribe = http.subscribe((event) => {
-  if (event.type === 'unauthorized') redirectToLogin()  // a 401 outside authEndpoints
+  if (event.type === 'unauthorized') redirectToLogin()  // a non-suppressed 401
   if (event.type === 'network_error') showOfflineBanner()
 })
 
@@ -1329,7 +1535,7 @@ segment to every URL — the client half of a multi-tenant API
 interface ContractClientConfig {
   /** Prepended to every request URL. A function is called per request with the
    *  call's argument object, so the prefix can depend on the arguments. */
-  pathPrefix?: string | ((args: Record<string, unknown>) => string)
+  pathPrefix?: string | ((args: { [K in ConsumedKey]: string }) => string)
   /** Argument keys consumed by `pathPrefix` — stripped from the query/body so
    *  they are not also sent there (the endpoint's own path `:params` are
    *  stripped automatically; list any *extra* keys here). */
@@ -1341,8 +1547,8 @@ A per-tenant client — `tenantId` goes into the URL, not the body:
 
 ```ts
 const widgets = createClient(widgetsContract, http, {
-  pathPrefix: (args) => `tenants/${args.tenantId}/`,
   stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}/`,
 })
 
 widgets.list({ tenantId: 't_123' })            // GET  /tenants/t_123/widgets
@@ -1415,7 +1621,8 @@ The same contract that drives the HTTP API also drives AI tooling. An endpoint
 exposed on `MCP` becomes a [Model Context Protocol](https://modelcontextprotocol.io)
 tool — callable from Claude, Cursor and other MCP clients. An endpoint exposed on
 `AGENT` becomes a [Vercel AI SDK](https://sdk.vercel.ai) tool — callable from an
-agent loop. No tool is hand-written; both come from the contract.
+agent loop. Contract operations are never re-described by hand; pathless
+runtime operations use one framework definition shared by both tool transports.
 
 ## Which endpoints become tools
 
@@ -1475,6 +1682,38 @@ and after, compare.
 > HTTP-only shows up in the list, which is the one check that catches it however
 > many places the line was forgotten.
 
+## In-process calls — `createToolInvoker`
+
+When one application operation dispatches to a contract tool, do not mount an
+AI SDK `ToolSet` and call its transport adapter manually. Compile an in-process
+invoker once and call the shared framework runner directly:
+
+```ts
+import { createToolInvoker } from 'stitchkit/tools'
+
+const invoker = createToolInvoker(services, {
+  transport: 'AGENT',       // required exposure policy
+  source: 'internal',       // default; audit names the real call source
+  context: { identity },
+  lifecycle,
+  hooks,
+})
+
+const result = await invoker.invoke('update_entity', args)
+if (!result.ok) throw new AppError(result.code, 'Nested tool call failed')
+```
+
+`transport` is required and uses the exact existing `MCP`, `AGENT` or `CLI`
+exposure rules; there is no internal bypass mode. The immutable name lookup is
+compiled once. Every invocation—including parallel and recursive calls—gets a
+fresh tool-call context and runs the same extension resolution, input/output
+validation, lifecycle, hooks and output-strip reporter as mounted tools.
+
+`invoke` returns the canonical discriminated `ToolResult`, not an AI SDK or MCP
+presentation envelope. An unknown name throws `AppError('NOT_FOUND')` before
+the runner because there is no operation identity against which hooks could run.
+Duplicate and provider-invalid names fail when the invoker is created.
+
 ## MCP — `createMcpHandler`
 
 `createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
@@ -1852,6 +2091,7 @@ the merged `params` + `input`. `context` is merged into every tool handler's
 | `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see [Guarding tools](#guarding-tools--lifecycle)) |
 | `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
 | `extend` | add extra args resolved before the handler runs (see below) |
+| `runtimeTools` | framework-managed pathless operations from `defineRuntimeTool` |
 
 `lifecycle` works the same as on the MCP server — without it an agent tool call
 bypasses the HTTP `beforeHandle` auth gate. Pass your `createAuthHook` result.
@@ -1902,51 +2142,78 @@ as the HTTP prefix param — see
 so one handler serves both surfaces. Pair `extend` with `lifecycle` (your
 `createAuthHook`) so the tool call is still scope-gated.
 
-## Native multimodal tools
+## Pathless runtime tools and multimodal results
 
-Contract tools return JSON. A native tool can return MCP text/image/audio/
-resource content directly while still using stitchkit's input/output validation,
-isolated per-call context, lifecycle/RBAC and tool hooks:
+Use `defineRuntimeTool` for an operation that has no HTTP path but still needs
+the same validation, isolated per-call context, lifecycle/RBAC and hooks as a
+contract tool. The handler returns one transport-neutral, schema-validated
+result. Optional presentation callbacks map that result to MCP content and AI
+SDK model output without coupling the handler to either SDK:
 
 ```ts
-import { createMcpHandler } from 'stitchkit/tools'
+import { createMcpHandler, defineRuntimeTool, mountAgent } from 'stitchkit/tools'
 import { z } from 'zod'
 
+const renderPreview = defineRuntimeTool({
+  name: 'render_preview',
+  description: 'Render and inspect a preview',
+  identity: {
+    serviceName: 'mediaTools',
+    action: 'renderPreview',
+    scope: 'admin',
+    method: 'POST',
+  },
+  input: z.object({ prompt: z.string() }),
+  output: z.object({ assetId: z.string(), imageBase64: z.string() }),
+  handler: async ({ input }) => renderAndSave(input.prompt),
+  present: {
+    mcp: (output) => ({
+      content: [
+        { type: 'image', data: output.imageBase64, mimeType: 'image/png' },
+        { type: 'text', text: output.assetId },
+      ],
+    }),
+    agent: (output) => ({
+      type: 'content',
+      value: [{
+        type: 'file',
+        data: { type: 'data', data: output.imageBase64 },
+        mediaType: 'image/png',
+        filename: `${output.assetId}.png`,
+      }],
+    }),
+  },
+})
+
 const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
   lifecycle: { beforeHandle: authHook },
   hooks: audit.toolCall,
-  nativeTools: ({ registerTool }, identity) => {
-    registerTool({
-      name: 'render_preview',
-      description: 'Render and inspect a preview',
-      identity: {
-        serviceName: 'mediaTools',
-        action: 'renderPreview',
-        scope: 'admin',
-        method: 'POST',
-      },
-      input: z.object({ prompt: z.string() }),
-      output: z.object({ assetId: z.string() }),
-      handler: async ({ input, traceId }) => ({
-        content: [
-          { type: 'image', data: await renderBase64(input.prompt), mimeType: 'image/png' },
-          { type: 'text', text: `trace: ${traceId}` },
-        ],
-        structuredContent: { assetId: await saveAsset(identity) },
-      }),
-    })
-  },
+  nativeTools: ({ registerTool }) => registerTool(renderPreview),
+})
+
+const agentTools = mountAgent([service], {
+  runtimeTools: [renderPreview],
+  lifecycle: { beforeHandle: authHook },
+  hooks: audit.toolCall,
 })
 ```
 
-The configured identity becomes the hook/lifecycle `OperationIdentity` and the
-tool `RequestEvent` (`serviceName`, `action`, `httpMethod`). A native operation
-has no HTTP route, so no fake `path` is added to that identity. If `output` is
-declared, stitchkit parses `structuredContent` with it after `afterHandle`; all
-other MCP fields and content blocks are preserved.
+`transports` defaults to `['MCP', 'AGENT']`; set an explicit subset when an
+operation belongs on only one surface. The configured identity becomes the
+hook/lifecycle `OperationIdentity` and the tool `RequestEvent`
+(`serviceName`, `action`, `httpMethod`). A runtime operation has no HTTP route,
+so no fake `path` is added.
+
+When `output` is declared, Stitchkit validates the neutral handler result after
+`afterHandle`. MCP owns `structuredContent` and `isError`: a presenter supplies
+only rich `content`/metadata, while the framework inserts the validated
+structured result and normalises failures. The Agent adapter uses the AI SDK's
+official `toModelOutput` callback, so `execute` and application UI keep the
+neutral output while the model receives text/file content. Presentation
+callbacks require an output schema.
 
 The MCP registration uses an identity carrier: the SDK advertises the compiled
 JSON Schema but forwards the raw object into Stitchkit. Input failures therefore
@@ -2240,7 +2507,7 @@ It returns a handle with three pieces, all wired into `createServer`:
 createServer({
   services,
   websocket: socket.websocket,   // → Bun.serve websocket handlers
-  rawRoutes: [socket.route],     // ready-made /socket.io/* route
+  rawRoutes: [socket.route],     // ready-made /socket.io/*socketPath route
 })
 
 // elsewhere — broadcast:
@@ -2251,7 +2518,7 @@ socket.io.emit('note:created', note)
 |--------------|---------|
 | `io` | the typed Socket.IO server — attach `connection` handlers, broadcast |
 | `websocket` | Bun WebSocket handlers — pass to `createServer({ websocket })` |
-| `route` | the `/socket.io/*` raw route — pass to `createServer({ rawRoutes })` |
+| `route` | the `/socket.io/*socketPath` raw route — pass to `createServer({ rawRoutes })` |
 
 `SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout` and
 `pingInterval`. For anything else socket.io's `ServerOptions` exposes, use the
@@ -2427,9 +2694,16 @@ updater per entity:
 import { createEntityCacheHandlers } from 'stitchkit/react'
 
 const widgetCache = createEntityCacheHandlers<Widget>({
-  getId: (w) => w.id,
-  listKey: ['widgets'],
-  detailKey: (id) => ['widgets', id],
+  getId: (widget) => widget.id,
+  getListItemId: (widget) => widget.id,
+  toListItem: (widget) => widget,
+  list: {
+    key: ['widgets'],
+    shape: 'paginated',
+    createAt: 'start',
+    updateMissing: 'skip',
+  },
+  detailKey: (event) => ['widgets', event.id],
 })
 
 createCacheBridge({ socket, queryClient, handlers: {
@@ -2439,10 +2713,52 @@ createCacheBridge({ socket, queryClient, handlers: {
 }})
 ```
 
-It patches stitchkit's `Paginated<T>` list envelope (plain or an infinite list
-of pages) and honours the same `isFresh` echo guard. It deliberately does **not**
-flatten pages or add a `useAllX` surface — flattening stays in the component;
-this only keeps the cache correct.
+The `list.shape` discriminant supports `array`, `paginated`, `infinite-array`
+and `infinite-paginated`. Every mutation preserves the surrounding envelope,
+page metadata and `pageParams`; an infinite create changes only the selected
+edge page (`createAt: 'start' | 'end'`). Creates are deduplicated across every
+cached page. `updateMissing` makes an absent update explicitly skip or insert.
+
+The event entity may be richer than a list row. Keep the full value in detail
+cache, project it for lists, and provide the same comparator the backend uses:
+
+```ts
+const memberCache = createEntityCacheHandlers<Member, MemberListItem>({
+  getId: (member) => member.id,
+  getListItemId: (item) => item.id,
+  toListItem: (member) => ({
+    id: member.id,
+    name: member.name,
+    joinedAt: member.joinedAt,
+  }),
+  list: {
+    key: (event) => {
+      if (event.type !== 'deleted') {
+        return ['workspaces', event.entity.workspaceId, 'members']
+      }
+      if ('workspaceId' in event.payload) {
+        return ['workspaces', event.payload.workspaceId, 'members']
+      }
+      throw new Error('A scoped delete must carry its entity')
+    },
+    shape: 'array',
+    createAt: 'start',
+    updateMissing: 'skip',
+    compare: (left, right) => left.joinedAt.localeCompare(right.joinedAt),
+  },
+  detailKey: (event) => ['members', event.id],
+})
+```
+
+Static `QueryKey` values remain the short path. A key factory receives a typed
+`created | updated | deleted` event, so scoped keys can use the full entity or
+deleted payload without guessing. The same resolved detail key drives the
+`isFresh` echo guard. Shape checks also leave neighbouring detail caches alone
+when a list key is intentionally used as a partial query-key prefix.
+
+The helper deliberately does **not** flatten pages, update totals, derive a
+sort order or replace arbitrary `setQueryData` logic. Those are application
+policies; this helper only applies declared CRUD semantics.
 
 ## Raw binary lane (Bun)
 
@@ -2516,7 +2832,7 @@ Notes:
 - **Bun-only.** On Node, Socket.IO attaches to the `node:http.Server` `upgrade`
   event (`serveNode({ socket })`); a raw lane there is a separate upgrade
   handler, not this composition. See [ADR 0020](../decisions/0020-raw-websocket-lane.md).
-- The upgrade path must not collide with `/socket.io/*`.
+- The upgrade path must not collide with `/socket.io/*socketPath`.
 - The tuning (`maxPayloadLength`, `idleTimeout`, `backpressureLimit`, …) is
   global — keep `idleTimeout` ≥ Socket.IO needs (> 2 × `pingInterval`).
 - For high throughput, handle backpressure in the raw lane: `ws.send()` returns
@@ -2576,6 +2892,19 @@ gives you the contract and the metadata (`idempotent`, the open `source` tag,
 
 # Auth & errors
 
+Client-side login/session operations may legitimately answer `401`. Declare
+that policy with contract-owned matchers instead of path strings:
+
+```ts
+const http = createHttpClient({
+  baseUrl,
+  suppressUnauthorizedFor: contractEndpointMatchers(publicAuth, ['login', 'verify']),
+})
+```
+
+Only the selected operations suppress the global `unauthorized` event; a 401
+from any neighbouring protected route still signals session expiry.
+
 stitchkit carries no domain model — it does not know what a user is. What it
 provides is the *control flow*: a scope on every endpoint, one hook that
 enforces it, and one error model shared by every transport. The identity and
@@ -2744,6 +3073,20 @@ session.clear()         // → a Set-Cookie value that expires it
 config is not repeated at every call site. `parseCookies(header)` and
 `serializeCookie(name, value, opts)` are the lower-level primitives.
 
+To set a cookie from a schema-validated JSON endpoint without losing its typed
+client result, declare [`responseMeta`](./server.md#typed-json-response-metadata)
+and append the generated value:
+
+```ts
+complete: async ({ response }) => {
+  response.headers.append('Set-Cookie', session.set('abc123'))
+  return authenticatedUser
+}
+```
+
+Append once per cookie; Stitchkit preserves separate `Set-Cookie` fields through
+both Bun and Node. Cookie/session policy remains application logic.
+
 ## The error model
 
 One error type, `AppError`, is shared by the contract, the server and the
@@ -3609,7 +3952,7 @@ keeps `tenantId` out of the body/query
 
 ```ts
 const widgetsApi = createClient(widgets, http, {
-  pathPrefix: (args) => `tenants/${args.tenantId}/`,
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}/`,
   stripPrefixKeys: ['tenantId'],
 })
 
@@ -3714,6 +4057,109 @@ 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.
 
+## Unreleased breaking migrations
+
+Entity cache handlers now require the cached list shape and CRUD policies. Move
+`listKey` under `list`, make detail keys event-aware, and state the list-item
+identity/projection explicitly:
+
+```ts
+// before
+createEntityCacheHandlers<Entity>({
+  getId,
+  listKey: ['entities'],
+  detailKey: (id) => ['entities', id],
+})
+
+// after
+createEntityCacheHandlers<Entity, EntityListItem>({
+  getId,
+  getListItemId: (item) => item.id,
+  toListItem: (entity) => ({ id: entity.id, name: entity.name }),
+  list: {
+    key: ['entities'],
+    shape: 'paginated',
+    createAt: 'start',
+    updateMissing: 'skip',
+  },
+  detailKey: (event) => ['entities', event.id],
+})
+```
+
+Choose `array`, `paginated`, `infinite-array` or `infinite-paginated` to match
+the actual cached data. A dynamic `list.key` / `detailKey` receives a
+discriminated event and can derive scoped keys from the created/updated entity
+or deleted payload. Add `compare` only when the backend has a canonical order;
+the framework does not guess it or mutate pagination metadata.
+
+Protected native MCP operations now use the transport-neutral runtime tool
+definition. Return the schema-owned value from the handler and move MCP content
+or metadata into `present.mcp`; `structuredContent` and `isError` are
+framework-owned:
+
+```ts
+// before
+registerTool({ input, output, handler: async () => ({
+  content: [{ type: 'image', data, mimeType: 'image/png' }],
+  structuredContent: { assetId },
+}) })
+
+// after
+const preview = defineRuntimeTool({
+  name: 'render_preview', description, identity, input, output,
+  handler: async () => ({ assetId, data }),
+  present: {
+    mcp: (result) => ({
+      content: [{ type: 'image', data: result.data, mimeType: 'image/png' }],
+    }),
+  },
+})
+nativeTools: ({ registerTool }) => registerTool(preview)
+```
+
+The removed `NativeMcp*` types have no aliases. Use `RuntimeToolDefinition`,
+`RuntimeToolIdentity`, `RuntimeToolHandlerContext` and
+`RuntimeMcpPresentation`. The same definition can now be passed to
+`mountAgent(services, { runtimeTools: [preview] })`; add `present.agent` only
+when the model needs rich text/file content instead of the neutral JSON result.
+
+Trailing wildcards must be named consistently across the path and params schema:
+
+```ts
+// before
+path: '/app/:slug/*'
+params: z.object({ slug: z.string(), '*': z.string() })
+ctx.params['*']
+api.app({ slug: 'foo', '*': 'a/b' })
+
+// after
+path: '/app/:slug/*filePath'
+params: z.object({ slug: z.string(), filePath: z.string() })
+ctx.params.filePath
+api.app({ slug: 'foo', filePath: 'a/b' })
+```
+
+Bare wildcards have no compatibility alias; raw routes use the same named form.
+
+### Expected-401 matchers
+
+`HttpClientConfig.authEndpoints` is removed. Replace manual path prefixes with
+the operations whose 401 response is expected:
+
+```ts
+// before
+createHttpClient({ baseUrl, authEndpoints: ['/api/auth/'] })
+
+// after
+createHttpClient({
+  baseUrl,
+  suppressUnauthorizedFor: contractEndpointMatchers(authContract, ['login', 'verify']),
+})
+```
+
+There is no implicit `/auth/` suppression. Omit `suppressUnauthorizedFor` when
+every 401 should emit the global `unauthorized` event.
+
 ## The 0.37 migration
 
 Tool presentation is no longer an executable Zod parser. Replace the removed
@@ -3908,13 +4354,26 @@ The browser-and-server entrypoint. Re-exports everything from
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
-| `createClients` | function | build one typed client per contract from a registry |
+| `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
+| `createScopedClients` | function | build one registry routed by contract scope; arrays compose contracts into one namespace |
+| `ScopeClientConfigs` | _type_ | per-scope client routing configuration consumed by `createScopedClients` |
+| `ScopedClientRegistry` | _type_ | exact composed registry returned by `createScopedClients` |
+| `ClientRegistryValue` | _type_ | one contract or a contract array composing one client namespace |
+| `ClientContract` | _type_ | HTTP-client-compatible contract value used by scoped registries |
+| `RegistryScope` | _type_ | contract-scope union inferred from a scoped client registry value |
+| `createUrlBuilder` | function | build synchronous browser-native URLs for all HTTP endpoints; body methods accept URL-bound args only — [guide](../guide/client.md#contract-url-builders) |
+| `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
+| `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
+| `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
+| `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
+| `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient` |
+| `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
 | `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
@@ -3965,7 +4424,12 @@ from the root `stitchkit`.
 | `ContractDef` | _type_ | a defined contract |
 | `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` |
+| `HeadEndpointDef` | _type_ | explicit HTTP-only, bodyless `HEAD` endpoint definition |
+| `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
+| `ResponseMetadata` | _type_ | per-request outbound collector exposed as `ctx.response` only for a `responseMeta` endpoint |
+| `HttpSuccessStatus` | _type_ | supported declared 2xx success statuses |
+| `BodyHttpSuccessStatus` | _type_ | supported 2xx statuses excluding bodyless 204/205 |
+| `HttpMethod` | _type_ | `GET \| HEAD \| POST \| PUT \| PATCH \| DELETE` |
 | `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
 | `TransportSource` | _type_ | `http \| mcp \| agent \| cli` — the value of `ctx.source` |
 | `RuntimeContext` | _type_ | the loose context seen by transport and hooks |
@@ -3975,6 +4439,9 @@ from the root `stitchkit`.
 | `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
 | `ScopedHttpClient` | _type_ | a client whose `stripPrefixKeys` become required args ([guide](../guide/multi-tenant.md)) |
 | `ScopedEndpointFn` | _type_ | one method's signature with the consumed keys folded in |
+| `TypedUrlBuilder` | _type_ | one contract's HTTP endpoints as synchronous, method-aware URL functions |
+| `ScopedUrlBuilder` | _type_ | a URL builder whose scoped-prefix keys are required method arguments |
+| `ScopedUrlFn` | _type_ | one URL method's signature with scoped-prefix keys folded in |
 | `MultipartFile` | _type_ | a `multipart` file field — `Blob \| FileDescriptor` |
 | `FileDescriptor` | _type_ | a React Native / Expo file — `{ uri, name, type }` |
 | `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |
@@ -4217,6 +4684,8 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
 | `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
 | `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
+| `defineRuntimeTool` | function | define one validated pathless operation for MCP, Agent or both — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
+| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
@@ -4232,10 +4701,17 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
 | `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
 | `NativeMcpRegistrar` | _type_ | protected `registerTool` plus explicit unprotected `rawServer` access |
-| `NativeMcpToolDefinition` | _type_ | native name, operation identity, Zod schemas and MCP-result handler |
-| `NativeMcpOperationIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for native lifecycle/audit |
-| `NativeMcpHandlerContext` | _type_ | runtime context with the definition's parsed native input |
-| `NativeMcpResult` | _type_ | MCP content result, with typed `structuredContent` when output is declared |
+| `RuntimeToolDefinition` | _type_ | transport-neutral pathless operation with identity, schemas, handler and optional presenters |
+| `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
+| `RuntimeToolDefinitionWithOutput` | _type_ | runtime definition whose handler and presenters share a validated output type |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition without output validation or presentation callbacks |
+| `RuntimeToolIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for runtime lifecycle/audit |
+| `RuntimeToolHandlerContext` | _type_ | runtime context with the definition's parsed input |
+| `RuntimeToolOutput` | _type_ | output inferred from a runtime tool's optional Zod schema |
+| `RuntimeToolPresenters` | _type_ | optional MCP and AI SDK `toModelOutput` presentation callbacks |
+| `RuntimeMcpPresentation` | _type_ | MCP content/metadata result without framework-owned `structuredContent` or `isError` |
+| `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
+| `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT'` |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
 | `CliConfig` | _type_ | config for `createCli` |
@@ -4251,6 +4727,9 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `ToolErrorOptions` | _type_ | `{ toolName, error, context, endpoint }` for a thrown handler-path value |
 | `ErrorHintFn` | _type_ | `(toolName, errorCode) => string \| null` — a per-tool recovery hint, shared by every mount |
 | `ToolResult` | _type_ | the result of one tool call |
+| `ToolInvoker` | _type_ | immutable compiled dispatcher (`names` + `invoke`) |
+| `ToolInvokerConfig` | _type_ | exposure policy, context, lifecycle, hooks and runner options |
+| `ToolInvokerTransport` | _type_ | invoker exposure policy: `MCP \| AGENT \| CLI` |
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source }` plus whatever the mount's `context` added |
 | `ViewFileOptions` | _type_ | options for `mountViewFile` |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |
@@ -4389,6 +4868,10 @@ and `react-query-kit` peers.
 | `createEntityCacheHandlers` | function | created/updated/deleted cache handlers for one entity — [guide](../guide/realtime.md#entity-cache-handlers) |
 | `EntityCacheConfig` | _type_ | config for `createEntityCacheHandlers` |
 | `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
+| `EntityCacheEvent` | _type_ | discriminated created/updated/deleted input for dynamic cache keys |
+| `EntityCacheKey` | _type_ | static `QueryKey` or event-aware key factory |
+| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and comparator |
+| `EntityCacheListShape` | _type_ | `array \| paginated \| infinite-array \| infinite-paginated` |
 | `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
 | `CacheBridge` | _type_ | the `createCacheBridge` handle |