stitchkit 0.38.0 → 0.40.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 and a terminal `/*` captures the remaining path |
+| `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) |
@@ -248,16 +248,24 @@ export const users = defineContract({ prefix: 'users' }, {
 | `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. A terminal wildcard is the
-  quoted `'*'` field: `path: '/:slug/*'` with
-  `params: z.object({ slug: z.string(), '*': z.string() })` matches both
-  `/foo/page` and `/foo/a/b`; the handler receives `'page'` or `'a/b'`.
+  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`.
@@ -272,8 +280,8 @@ the body.
 // path: '/:id', params: { id }, input: { text }
 await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
 
-// path: '/:slug/*', params: { slug, '*': remainder }
-await api.app({ slug: 'foo', '*': 'a/b' })   // GET /apps/foo/a/b
+// path: '/:slug/*filePath', params: { slug, filePath }
+await api.app({ slug: 'foo', filePath: 'a/b' })   // GET /apps/foo/a/b
 ```
 
 ### Input vs. output types
@@ -523,11 +531,13 @@ the endpoint is public (fail-open). If every contract in your app must be scoped
 // app: one line, once
 export const { defineContract } = createContractFactory<'public' | 'user' | 'admin'>()
 
-// scope is now mandatory and checked against the union
+// scope is mandatory, checked against the union and retained as the 'user' literal
 export const users = defineContract({ prefix: 'users', scope: 'user' }, { … })
 ```
 
-The vocabulary is yours; the returned contracts are ordinary `ContractDef`s.
+The vocabulary is yours; each returned `ContractDef` retains its concrete scope
+literal, so scope-aware registries select the exact config without another
+wrapper.
 
 ## One source of truth
 
@@ -773,11 +783,12 @@ 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 `/*`. `/app/:slug/*` matches
+**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', '*': '' }` and `{ slug: 'foo', '*': 'a/b' }` respectively. Put
-the quoted `'*'` field in the endpoint's `params` schema to keep it in typed
-`ctx.params`. Each captured segment is URL-decoded before the remainder is
+`{ 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
@@ -1026,9 +1037,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.
 
@@ -1067,24 +1078,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).
@@ -1205,7 +1227,8 @@ 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 `/*`, Stitchkit keeps the literal runtime path, omits `*` from the
+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
@@ -1266,9 +1289,13 @@ 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
@@ -1284,13 +1311,22 @@ without repeating transport configuration.
 | `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
@@ -1316,12 +1352,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 terminal wildcard (`/*`) consumes the `'*'` field and preserves its path
-  segments (`{ '*': 'a/b' }` → `/a/b`, not `/%2Fa%2Fb` or a query field),
+- 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**,
@@ -1340,6 +1386,32 @@ 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. It accepts the same optional scoped
 config as `createClient`, so a whole registry can share one resource prefix:
@@ -1362,7 +1434,7 @@ 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'
+import { createScopedUrlBuilders, createUrlBuilder, createUrlBuilders } from 'stitchkit'
 
 const mediaUrls = createUrlBuilder(media, http, {
   stripPrefixKeys: ['tenantId'],
@@ -1375,13 +1447,47 @@ const src = mediaUrls.file({
   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)
 ```
 
-Only HTTP-exposed, non-multipart `GET` endpoints appear on a URL builder. Raw
-response GET endpoints are included, so downloads and streams stay
-contract-driven. Path and scoped-prefix keys are consumed by the path; remaining
-GET input becomes the query string, including repeated keys for arrays.
+When contracts use different dynamic prefixes, route the registry by the same
+literal `contract.meta.scope` model as `createScopedClients`:
+
+```ts
+const urls = createScopedUrlBuilders(
+  {
+    assets: publicAssets,
+    media: [tenantFiles, tenantMetadata], // one composed namespace
+  },
+  http,
+  {
+    public: {},
+    tenant: {
+      stripPrefixKeys: ['tenantId'],
+      pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+    },
+  },
+)
+
+urls.assets.logo()
+urls.media.file({ tenantId: 't1', fileId: 'f' })
+```
+
+Every reachable scope needs a config. A missing config or duplicate method in a
+composed namespace fails while the registry is built; URL generation itself
+continues to use the same request planner as `createClient`.
+
+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
@@ -1417,7 +1523,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()
 })
 
@@ -1544,7 +1650,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
 
@@ -1604,6 +1711,51 @@ 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
+})
+
+const result = await invoker.invoke('update_entity', args, {
+  source: 'internal',       // default; audit names the real call source
+  context: { identity },
+  lifecycle,
+  hooks,
+})
+
+// Composition path: validated data or the exact normalized AppError.
+const data = await invoker.invokeOrThrow('update_entity', args, {
+  context: { identity },
+  lifecycle,
+  hooks,
+})
+```
+
+`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. Call-specific identity, context, lifecycle and hooks are passed
+to `invoke` / `invokeOrThrow`, so one registry can safely serve parallel and
+recursive calls without retaining request state. Every invocation 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. `invokeOrThrow` returns validated data and throws the
+runner's normalized `AppError` on failure, preserving an application error's
+code, status, message, details and hint without reconstructing it from the
+model-safe envelope. Unexpected throws remain scrubbed. 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
@@ -1981,6 +2133,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.
@@ -2031,51 +2184,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
@@ -2369,7 +2549,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:
@@ -2380,7 +2560,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
@@ -2556,9 +2736,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: {
@@ -2568,10 +2755,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)
 
@@ -2645,7 +2874,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
@@ -2705,6 +2934,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
@@ -3857,6 +4099,135 @@ 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
+
+`createToolInvoker` now separates immutable registry preparation from per-call
+runtime state. Move source/context/lifecycle/hooks/output-strip reporting from
+the factory config to the third invocation argument. Use `invokeOrThrow` when a
+nested operation should preserve the normalized `AppError` instead of returning
+a model-facing failure envelope:
+
+```ts
+// before
+const invoker = createToolInvoker(services, {
+  transport: 'AGENT', context: { identity }, lifecycle, hooks,
+})
+const result = await invoker.invoke(name, args)
+
+// after
+const invoker = createToolInvoker(services, { transport: 'AGENT' })
+const result = await invoker.invoke(name, args, {
+  context: { identity }, lifecycle, hooks,
+})
+const data = await invoker.invokeOrThrow(name, args, {
+  context: { identity }, lifecycle, hooks,
+})
+```
+
+There is no static runtime-config overload: request identity must not be retained
+by a reusable compiled registry.
+
+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
@@ -4052,17 +4423,27 @@ The browser-and-server entrypoint. Re-exports everything from
 |--------|------|---------|
 | `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
 | `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
-| `createUrlBuilder` | function | build synchronous browser-native URLs for one contract's HTTP GET endpoints — [guide](../guide/client.md#contract-url-builders) |
+| `createScopedClients` | function | build one registry routed by contract scope; arrays compose contracts into one namespace |
+| `createScopedUrlBuilders` | function | build one URL registry routed by contract scope; arrays compose contracts into one namespace |
+| `ScopeClientConfigs` | _type_ | per-scope routing configuration consumed by scoped clients and URL builders |
+| `ScopedClientRegistry` | _type_ | exact composed registry returned by `createScopedClients` |
+| `ScopedUrlBuilderRegistry` | _type_ | exact composed registry returned by `createScopedUrlBuilders` |
+| `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` |
@@ -4107,17 +4488,18 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
-| `createContractFactory` | function | a `defineContract` with a required, typed `scope` — [guide](../guide/contracts.md#scope) |
+| `createContractFactory` | function | a `defineContract` with a required allowed scope that retains each concrete literal — [guide](../guide/contracts.md#scope) |
 | `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` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition |
+| `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 \| POST \| PUT \| PATCH \| DELETE` |
+| `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 |
@@ -4127,7 +4509,7 @@ 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, non-multipart GET endpoints as synchronous URL functions |
+| `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` |
@@ -4372,6 +4754,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 |
@@ -4387,10 +4771,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` |
@@ -4406,6 +4797,10 @@ 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`, envelope `invoke`, throwing `invokeOrThrow`) |
+| `ToolInvokerConfig` | _type_ | compile-time exposure, extension and presentation options |
+| `ToolInvocationOptions` | _type_ | per-call source, context, lifecycle, hooks and output-strip reporter |
+| `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 |
@@ -4544,6 +4939,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 |