stitchkit 0.40.0 → 0.42.0

package/llms-full.txt

@@ -234,7 +234,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | `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) |
-| `output` | no | Zod schema for the **response body** |
+| `output` | no | Zod schema for the **response body**; its presence declares a JSON result (`null` is data, `undefined` is not) |
 | `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
 | `expose` | no | which transports carry this endpoint — see [below](#transports) |
 | `toolName` | no | explicit MCP / agent tool name (default: a verb-aware derivation, see below — not a literal `prefix_key`) |
@@ -256,6 +256,13 @@ headers, while Stitchkit guarantees an empty wire body even if the returned
 
 ## `params` vs `input` vs `output`
 
+`output` owns response presence across HTTP and tool transports. With a schema,
+the handler must return a value that validates and can be represented as JSON;
+a nullable schema may return `null`, but `undefined` is always a contract
+violation. Without `output`, the handler is empty (`undefined`/`null`) and may
+not return undeclared data. On HTTP this means a default `200` JSON response
+with output and a default bodyless `204` without it.
+
 The three schemas are distinct on purpose:
 
 - **`params`** — values in the URL path. `path: '/:id'` ⇒
@@ -910,9 +917,13 @@ HTTP-only, but its typed client method still resolves to `AuthUser` — not
 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).
+2xx code. Without it, an endpoint with `output` uses `200`; an endpoint without
+`output` uses `204`. A nullable output returns JSON `null` with status `200` —
+the runtime value never turns a declared response body into no content.
+`undefined` violates a declared output, while returning non-null data without an
+output schema is also a server fault. 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`,
@@ -1352,6 +1363,13 @@ await api.update({ id: '1', name: 'M' })  // PUT /users/1  body: { name }
 await api.delete({ id: '1' })      // DELETE /users/1
 ```
 
+The client follows response presence from the contract, not from the HTTP
+status or a truthy runtime value. An endpoint with nullable `output` resolves
+JSON `null` as `null`; an endpoint without `output` resolves `undefined`,
+including an explicitly declared empty `200` or `205`. A missing body for a
+declared output, or a body for an endpoint with no output, fails loudly instead
+of changing the typed result.
+
 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
@@ -1685,16 +1703,16 @@ call —
 ### Pinning tool names — `listToolNames`
 
 Derived tool names are part of your public surface — an MCP client config or an
-agent prompt refers to them by string. `listToolNames(services)` resolves every
-tool name your services expose (the exact resolver the mounts use), with its
-`(service, method)` identity and transports, sorted — a stable shape to
-snapshot:
+agent prompt refers to them by string. `listToolNames({ services, runtimeTools })`
+resolves the complete mixed surface (the exact resolver the mounts use), with
+its origin, `(service, method)` identity and transports, sorted — a stable shape
+to snapshot:
 
 ```ts
 import { listToolNames } from 'stitchkit/tools'
 
 test('tool names have not drifted', () => {
-  expect(listToolNames(services)).toMatchSnapshot()
+  expect(listToolNames({ services, runtimeTools })).toMatchSnapshot()
 })
 ```
 
@@ -1788,13 +1806,16 @@ createServer({
 | `serverInfo` | MCP server identity — `{ name, version }` |
 | `auth` | `(req) => identity \| null` — `null` rejects with 401 |
 | `services` | the services to expose — an array, or `(auth) => ServiceDef[]` |
+| `runtimeTools` | managed pathless operations — an array, or `(auth) => RuntimeToolDefinition[]` |
+| `surfaces` | finite `{ key: { services, runtimeTools } }` registry prepared eagerly |
+| `selectSurface` | `(auth) => declaredKey` — required with `surfaces` |
 | `context` | `(auth) => {…}` — values merged into every tool handler's `ctx` |
 | `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see below) |
 | `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
 | `extend` | extra advertised arguments resolved into handler context |
 | `schemaValidation` | compatibility policy, typed-property guard and portable-format guard |
 | `logger` | a `StitchLogger` for the `'warn'` policy |
-| `nativeTools` | `({ registerTool, rawServer }, auth) => …` — protected native registration plus an explicit raw SDK escape hatch |
+| `rawTools` | `(server, auth) => …` — explicit SDK registration without framework guarantees |
 | `resources` | MCP Apps `ui://` resources mounted on every server |
 | `instructions` | a short host-facing usage hint, surfaced to MCP tool-search |
 | `coerceJsonArgs` | coerce JSON-stringified object/array arguments (default `true`) |
@@ -1804,14 +1825,37 @@ createServer({
 | `protectedResource` | RFC 9728 metadata used by HTTP `401` responses |
 | `sessionMode` | `'stateless'` (default) or explicit `'stateful'` session/SSE continuity |
 
-`services`, `context` and `nativeTools` all receive the resolved identity, so a
-tenant can be shown only its own tools and every handler can read `ctx.tenantId`.
+Direct `services` / `runtimeTools` factories, `context`, `selectSurface` and
+`rawTools` receive the resolved identity, so a tenant can be shown only its own
+tools and every handler can read `ctx.tenantId`.
+
+Use direct factories only when the definitions are genuinely arbitrary per
+identity. For a bounded role/plan set, declare a finite registry instead:
+
+```ts
+const handleMcp = createMcpHandler({
+  serverInfo,
+  auth,
+  surfaces: {
+    admin: { services: allServices, runtimeTools: [renderPreview] },
+    member: { services: memberServices, runtimeTools: [renderPreview] },
+  },
+  selectSurface: (identity) => identity.isAdmin ? 'admin' : 'member',
+  context: (identity) => ({ identity }),
+})
+```
+
+Every declared entry is schema-validated and prepared once when the handler is
+constructed. The selected immutable descriptors are shared; the SDK server,
+transport, auth-derived context, lifecycle runner and tool-call context are
+fresh for every stateless request (or every stateful session). Unknown keys
+fail before the server connects. The registry never retains auth values.
 
 ### Stateless by default; stateful only when required
 
 The default `sessionMode: 'stateless'` creates a fresh SDK server, transport,
-resolved auth/context and runner for each HTTP request. Static contract schemas
-are still prepared once when the handler is constructed. There is no session
+resolved auth/context and runner for each HTTP request. Static direct and finite
+registry schemas are still prepared once when the handler is constructed. There is no session
 map, event store, sweep timer or `Mcp-Session-Id`, so process replacement and
 load balancing cannot strand a client on an in-memory session.
 
@@ -1988,8 +2032,8 @@ than a per-request `(req) => …`. Keep all logging on **stderr**: stdout is the
 JSON-RPC channel.
 
 Both transports build the server through the shared `buildMcpServer` — same
-contract pipeline, same `services` / `context` / `hooks` / `nativeTools` /
-`instructions`.
+contract/runtime pipeline, same surface selection, context, hooks, raw escape
+hatch and instructions.
 
 ## OAuth 2.1 — a native remote connector
 
@@ -2231,9 +2275,9 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
+  runtimeTools: [renderPreview],
   lifecycle: { beforeHandle: authHook },
   hooks: audit.toolCall,
-  nativeTools: ({ registerTool }) => registerTool(renderPreview),
 })
 
 const agentTools = mountAgent([service], {
@@ -2263,7 +2307,7 @@ use the same validation, lifecycle and hook path as contract tools.
 
 ### Explicit raw SDK registration
 
-`rawServer` is deliberately named as an escape hatch. A tool registered there
+`rawTools` is deliberately named as an escape hatch. A tool registered there
 does **not** receive stitchkit schema policy, lifecycle, per-call context or
 hooks. The built-in `mountViewFile` helper remains raw for callers that choose
 that boundary; it fetches media with SSRF and path-traversal defenses:
@@ -2275,14 +2319,51 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
-  nativeTools: ({ rawServer }) =>
-    mountViewFile(rawServer, { baseDir: '/srv/uploads' }),
+  rawTools: (server) => mountViewFile(server, { baseDir: '/srv/uploads' }),
 })
 ```
 
 Use raw registration only when opting out is intentional. For a protected
-`view_file`, define it through `registerTool` and call the exported
-`resolveMedia` core from its handler.
+`view_file`, define it with `defineRuntimeTool`, include it in `runtimeTools`,
+and call the exported `resolveMedia` core from its handler.
+
+## Introspecting the complete tool surface
+
+Deferred tool search, name snapshots and boot diagnostics accept the same
+object-shaped surface as the mounts. Contract operations are followed by
+runtime definitions, matching mount order; exposure filters and collisions are
+resolved by Stitchkit rather than by consumer code:
+
+```ts
+import {
+  buildToolManifest,
+  listToolNames,
+  summarizeTransports,
+} from 'stitchkit/tools'
+
+const surface = { services, runtimeTools: [renderPreview] }
+
+const manifest = buildToolManifest({
+  ...surface,
+  transport: 'AGENT',
+  flattenUnionInput: true,
+})
+
+const names = listToolNames(surface)
+const summary = summarizeTransports(surface)
+```
+
+`buildToolManifest` returns the exact immutable presentation schema shown to
+the selected MCP or Agent transport. It does not execute validation effects and
+fails first on duplicate contract/runtime names. There is no runtime-only
+manifest helper or public mount adapter: the framework owns merging and schema
+projection.
+
+`listToolNames` remains diagnostic and reports `kind: 'contract' | 'runtime'`
+for every identity. `summarizeTransports` returns `contractServices`,
+`runtimeTools`, aggregate `totals`, and a `sources` breakdown. Runtime tools
+contribute only to MCP/Agent according to their `transports`; they never inflate
+HTTP or CLI counts.
 
 ## Logging tool calls — `createToolLogger`
 
@@ -2302,9 +2383,9 @@ Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
 structured `ToolCallRecord`. That record carries `traceId` whenever an
 observability context is active, so a tool call made inside an HTTP request
 joins that request's log line on one key — see
-[Observability](./observability.md). For a boot-time picture of what is exposed where,
-`summarizeTransports(services)` returns per-transport operation counts (HTTP /
-MCP / AGENT / CLI) for you to log.
+[Observability](./observability.md). For a boot-time picture of what is exposed
+where, `summarizeTransports({ services, runtimeTools })` returns the mixed
+per-transport counts for you to log.
 
 ## One handler, three callers
 
@@ -3235,27 +3316,46 @@ onError: (ctx, err) => {
 
 ## Domain errors — `defineErrors`
 
-Declaring your app's error codes once gives you typed throwers on the server and
-a code table the client matches with autocomplete — instead of reading the raw
-`message` string (which breaks the moment a code expects a string but gets an
-object):
+Declare each domain code, HTTP status and optional structured-details schema in
+one immutable registry. The generated functions construct typed branded
+`AppError` instances; ordinary `throw` remains explicit at the call site:
 
 ```ts
-export const { errors, codes, isCode } = defineErrors({
-  SESSION_NOT_FOUND: 404,
-  QUOTA_EXCEEDED: 429,
+import { z } from 'zod'
+
+export const { errors, codes, definitions, isCode } = defineErrors({
+  SESSION_NOT_FOUND: { status: 404 },
+  QUOTA_EXCEEDED: {
+    status: 429,
+    details: z.object({ retryAfterSeconds: z.number().int().positive() }),
+  },
 })
 
-// server — a typed thrower, the right HTTP status baked in
-throw errors.SESSION_NOT_FOUND('no such session')
+throw errors.SESSION_NOT_FOUND({ message: 'No such session' })
+throw errors.QUOTA_EXCEEDED({
+  message: 'Try later',
+  details: { retryAfterSeconds: 30 },
+  hint: 'Wait for the current window to expire',
+})
+
+// Construction without throwing is useful for composition or inspection.
+const error = errors.QUOTA_EXCEEDED({ details: { retryAfterSeconds: 30 } })
+definitions.QUOTA_EXCEEDED.status // 429 — same source, no copied status map
 
 // client — match the code, never a magic string
 if (err instanceof ApiError && err.code === codes.SESSION_NOT_FOUND) { … }
 ```
 
-The `code` rides through unchanged in both the HTTP envelope and the MCP tool
-result, so one vocabulary covers every transport. The codes are yours; the core
-stays domain-free.
+With no `details` schema, the options object forbids `details`. A required
+`z.object` makes `details` required; `z.object(...).optional()` makes it
+optional. Supplied details are parsed when the error is constructed, before any
+transport sees them. `code` remains literal and the parsed details type is
+retained on the returned `AppError`.
+
+HTTP renders the complete code/status/message/details/hint. Tool transports keep
+their established model-facing projection (code/details/hint, without HTTP
+status), while `invokeOrThrow` recovers the exact normalized `AppError`. The
+codes and schemas remain application-owned; Stitchkit stays domain-free.
 
 ## `createErrorHook`
 
@@ -3287,6 +3387,27 @@ createServer({ services, hooks: { onError } })
 Codes you threw yourself (not stitchkit's) pass through `codeMap` unchanged; the
 `satisfies Record<StitchErrorCode, …>` keeps the map exhaustive across upgrades.
 
+Both `onError` and `render` may be asynchronous and receive the matched endpoint
+as their final argument. The observer is awaited before rendering, so it can
+resolve identity or enrich the request context even for failures raised before
+`beforeHandle`:
+
+```ts
+const onError = createErrorHook({
+  onError: async (_error, _info, ctx, endpoint) => {
+    await attributeFailedRequest(ctx, endpoint)
+  },
+  render: (info, ctx) => ({
+    error: { code: info.code },
+    actorId: ctx.actorId,
+  }),
+})
+```
+
+`endpoint` is `undefined` when the failure happened before route resolution.
+Synchronous callbacks and renderers that declare fewer parameters continue to
+work normally.
+
 Invalid input (a `ZodError`) is classified as `VALIDATION_ERROR` 400 before it
 reaches `render` — a client fault is an honest 400, not a 500 — and the
 offending fields arrive as structured `info.details.issues`, so your `render`
@@ -3459,6 +3580,12 @@ context carries nothing yet, so your value always wins.
 `event.serviceName` / `event.action` are present on every event, including a
 pre-handler 400. Nothing to wire.
 
+When failure attribution itself is asynchronous, use `createErrorHook`'s
+`onError(error, info, ctx, endpoint)` observer. The framework awaits it before
+calling `render`, so identity or audit enrichment is visible to both the final
+error envelope and the request event. `endpoint` is the matched `MethodDef`, or
+`undefined` when routing failed before a method was selected.
+
 **Domain dimensions** — attach your own tenant / project / entity id with
 `setRequestDimensions`. It is an opaque `Record<string, string>` the core gives no
 meaning to (→ ADR 0021). Resolve it cheaply from `ctx.params` / headers in
@@ -4101,6 +4228,119 @@ current one *up to* your target, and apply each snippet.
 
 ## Unreleased breaking migrations
 
+Tool introspection now accepts one object-shaped contract/runtime surface. Stop
+calling the internal contract collector or merging a locally converted runtime
+manifest:
+
+```ts
+// before
+buildToolManifest(services.flatMap((service) => collectTools(service, 'AGENT')))
+listToolNames(services)
+summarizeTransports(services)
+
+// after
+const surface = { services, runtimeTools }
+buildToolManifest({ ...surface, transport: 'AGENT' })
+listToolNames(surface)
+summarizeTransports(surface)
+```
+
+`ToolNameEntry` adds `kind: 'contract' | 'runtime'`. `TransportSummary` is now
+`{ contractServices, runtimeTools, totals, sources }`; replace `services` and
+`perService` reads with the explicit counts and mixed-source breakdown. There
+is no positional overload and no `buildRuntimeToolManifest`: Stitchkit owns the
+combined order, transport filtering, canonical presentation schema and
+cross-origin collision checks.
+
+`defineErrors` now uses one Zod-first definition object and returns constructors
+instead of positional throwers. Add explicit `throw`, move message/details/hint
+into one options object, and declare a details schema when that code carries
+structured context:
+
+```ts
+// before
+const { errors } = defineErrors({ QUOTA_EXCEEDED: 429 })
+errors.QUOTA_EXCEEDED('Try later', { retryAfterSeconds: 30 }, 'Wait')
+
+// after
+const { errors, definitions } = defineErrors({
+  QUOTA_EXCEEDED: {
+    status: 429,
+    details: z.object({ retryAfterSeconds: z.number().positive() }),
+  },
+})
+throw errors.QUOTA_EXCEEDED({
+  message: 'Try later',
+  details: { retryAfterSeconds: 30 },
+  hint: 'Wait',
+})
+```
+
+There is no positional overload. A code without `details` forbids them; use an
+optional object schema when the details object itself is optional. Read status
+and schemas from the frozen `definitions` registry instead of maintaining a
+parallel map.
+
+Managed MCP runtime tools are now declared as immutable data. Move protected
+registrar calls to `runtimeTools`; rename deliberate raw SDK registration to
+`rawTools`. There is no registrar alias:
+
+```ts
+// before — protected
+createMcpHandler({
+  services,
+  nativeTools: ({ registerTool }) => registerTool(preview),
+})
+
+// after — protected and prepared with the rest of the surface
+createMcpHandler({ services, runtimeTools: [preview] })
+
+// before — deliberate raw SDK opt-out
+nativeTools: ({ rawServer }, auth) => mountRaw(rawServer, auth)
+
+// after — still a deliberate raw SDK opt-out
+rawTools: (server, auth) => mountRaw(server, auth)
+```
+
+When identity selects from a bounded set, replace a repeatedly prepared
+`services(auth)` factory with a finite registry:
+
+```ts
+createMcpHandler({
+  surfaces: {
+    admin: { services: allServices, runtimeTools: [preview] },
+    member: { services: memberServices, runtimeTools: [preview] },
+  },
+  selectSurface: (auth) => auth.isAdmin ? 'admin' : 'member',
+})
+```
+
+Keep direct `services(auth)` / `runtimeTools(auth)` only for genuinely
+unbounded definitions; Stitchkit intentionally does not cache arbitrary auth
+values.
+
+Contract success bodies are now determined by the presence of `output`, not by
+the handler's runtime value. A nullable output returns JSON `null` with status
+`200`; `undefined` with a declared output and non-null data without an output
+schema are contract violations:
+
+```ts
+// nullable JSON data: 200 with body `null`
+session: {
+  method: 'GET', path: '/session', desc: 'Current session',
+  output: SessionSchema.nullable(),
+}
+
+// bodyless operation: 204 with no body
+logout: {
+  method: 'POST', path: '/logout', desc: 'End the session',
+}
+```
+
+Add an output schema to every handler that returns data. Omit `output` and
+return nothing for bodyless operations; runtime tools follow the same rule and
+type no-output handlers as `void`.
+
 `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
@@ -4182,7 +4422,7 @@ const preview = defineRuntimeTool({
     }),
   },
 })
-nativeTools: ({ registerTool }) => registerTool(preview)
+runtimeTools: [preview]
 ```
 
 The removed `NativeMcp*` types have no aliases. Use `RuntimeToolDefinition`,
@@ -4381,7 +4621,7 @@ name derivation, diff them mechanically:
 
 ```ts
 import { listToolNames } from 'stitchkit/tools'
-console.log(JSON.stringify(listToolNames(services), null, 2))
+console.log(JSON.stringify(listToolNames({ services, runtimeTools }), null, 2))
 ```
 
 `listToolNames` never throws on an illegal name — that is deliberate, so it can
@@ -4493,7 +4733,7 @@ from the root `stitchkit`.
 | `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 |
+| `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid) |
 | `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 |
@@ -4530,9 +4770,17 @@ from the root `stitchkit`.
 | `conflict` | function | throw `409 CONFLICT` |
 | `rateLimited` | function | throw `429 RATE_LIMITED` |
 | `appError` | function | throw an `AppError` for any code |
-| `defineErrors` | function | declare domain error codes → typed throwers + a code table — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
-| `DefinedErrors` | _type_ | the `{ errors, codes, isCode }` handle `defineErrors` returns |
-| `ErrorThrower` | _type_ | one `defineErrors` thrower — `(message?, details?, hint?) => never` |
+| `defineErrors` | function | declare immutable domain error definitions → typed `AppError` constructors, codes and schemas — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
+| `DefinedErrors` | _type_ | the `{ errors, codes, definitions, isCode }` handle `defineErrors` returns |
+| `DefinedAppError` | _type_ | literal-code error instance with schema-refined details |
+| `ErrorDefinition` | _type_ | `{ status, details? }` definition for one domain code |
+| `ErrorDefinitions` | _type_ | string-keyed domain error definition registry |
+| `ErrorDetailsSchema` | _type_ | required or optional Zod object accepted for structured details |
+| `ErrorDetailsOutput` | _type_ | parsed details inferred from one definition |
+| `ErrorFactoryArguments` | _type_ | options tuple with forbidden/required/optional details inferred per code |
+| `ErrorFactory` | _type_ | one typed `AppError` constructor |
+| `ErrorFactories` | _type_ | mapped constructor registry derived from all definitions |
+| `FrozenErrorDefinitions` | _type_ | read-only definition registry returned to consumers |
 | `STITCH_ERROR_STATUS` | const | `code → HTTP status` map for stitchkit's own error codes — [guide](../guide/auth-and-errors.md#stitch-codes-vs-your-codes) |
 | `StitchErrorCode` | _type_ | a code stitchkit itself emits (`keyof STITCH_ERROR_STATUS`) |
 | `isStitchErrorCode` | function | type guard — is a code one of stitchkit's own? |
@@ -4600,8 +4848,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAuthHook` | function | a scope-enforcing `beforeHandle` hook — [guide](../guide/auth-and-errors.md#createauthhook) |
-| `createErrorHook` | function | an `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
-| `ErrorHookConfig` | _type_ | config for `createErrorHook` |
+| `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
+| `ErrorHookConfig` | _type_ | async observer/renderer config for `createErrorHook` |
 | `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
 | `createBearerResolver` | function | a bearer-token identity resolver |
 | `signJwt` | function | sign an HS256 JWT |
@@ -4750,7 +4998,7 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 |--------|------|---------|
 | `createMcpHandler` | function | a complete Streamable-HTTP MCP server — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
 | `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
-| `buildMcpServer` | function | build an `McpServer` from contracts — the transport-neutral core |
+| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces — the transport-neutral core |
 | `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) |
@@ -4761,20 +5009,26 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
 | `resolveMedia` | function | resolve a media reference for a tool result |
 | `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
-| `listToolNames` | function | every mounted tool name with its `(service, method)` identity — for name-baseline snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
+| `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
 | `McpHandlerConfig` | _type_ | config for `createMcpHandler` |
+| `McpHttpConfig` | _type_ | HTTP auth, protected-resource and session options composed into `McpHandlerConfig` |
 | `McpSessionMode` | _type_ | `'stateless' \| 'stateful'`; HTTP defaults to request-isolated stateless mode |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
+| `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
+| `DirectMcpSurfaceConfig` | _type_ | static or identity-dynamic `services` / `runtimeTools` source |
+| `FiniteMcpSurfaceConfig` | _type_ | bounded `surfaces` registry plus typed selector |
+| `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
+| `McpSurfaceRegistry` | _type_ | finite keyed surface registry for eager preparation |
+| `StdioAuthConfig` | _type_ | startup identity composed into `StdioMcpServerConfig` |
 | `ImplementRemoteOptions` | _type_ | options for `implementRemote` |
 | `McpMountConfig` | _type_ | config for `mountMcp` |
 | `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 |
 | `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 |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no 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 |
@@ -4810,7 +5064,7 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `findNonPortableFormats` | function | deep finder for formats outside the portable MCP/AJV baseline |
 | `NonPortableFormat` | _type_ | one `{ path, format }` portability finding |
 | `PORTABLE_JSON_SCHEMA_FORMATS` | constant | portable-format baseline used by MCP validation |
-| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ name, service, method, transports }` |
+| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ kind, name, service, method, transports }` |
 | `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |
 
@@ -4869,12 +5123,15 @@ Advanced building blocks — the shared machinery the mounts are built on.
 |--------|------|---------|
 | `collectTools` | function | resolve a service's methods to mountable tools (the shared resolver) |
 | `createToolLogger` | function | a ready `afterToolCall` that logs every tool call — [guide](../guide/mcp-and-agents.md#logging-tool-calls--createtoollogger) |
-| `summarizeTransports` | function | per-transport operation counts for a boot-time summary |
-| `buildToolManifest` | function | a searchable `{ name, description, inputSchema }` manifest for a `tool_search` tool |
+| `summarizeTransports` | function | mixed contract/runtime operation counts and per-source breakdown for a boot-time summary |
+| `buildToolManifest` | function | transport-aware searchable `{ name, description, inputSchema }` rows from a mixed surface |
 | `ToolLoggerConfig` | _type_ | config for `createToolLogger` |
 | `ToolCallRecord` | _type_ | the structured record `createToolLogger` passes to `onRecord` |
-| `TransportSummary` | _type_ | the result of `summarizeTransports` |
+| `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
+| `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
+| `ToolSurfaceTransport` | _type_ | tool collector transport: `'MCP' \| 'AGENT' \| 'CLI'` |
+| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions in a JSON Schema document into conservative object joins; never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",