stitchkit 0.93.0 → 0.94.1

package/llms/tools.2.txt

@@ -0,0 +1,647 @@
+# stitchkit/tools — stitchkit docs slice, part 2 of 3
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+> Continues in `llms/tools.3.txt`.
+
+Parts of this slice:
+- `llms/tools.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+- `llms/tools.2.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+- `llms/tools.3.txt`: API reference: `stitchkit/tools`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
+==============================================================================
+
+## A different answer for tools — `withToolView`
+
+An admin page wants the full record; a model wants a card. Every byte of a
+tool result enters the model's context and stays in its history, and personal
+fields a task does not need are better never shown to it. Two endpoints on one
+path (one `expose: ['HTTP']`, one for the tools) duplicate the description, the
+schemas and the handler; branching on `ctx.source` teaches every handler about
+transports and still advertises the full output schema.
+
+A **tool view** declares the difference on the endpoint instead. Most often the
+difference is only the call — a model needs a lighter one, and the answer keeps
+its one shape:
+
+```ts
+import { defineContract, withToolView } from 'stitchkit';
+
+export const items = defineContract({ prefix: 'items' }, {
+  list: withToolView(
+    {
+      method: 'GET', path: '/:slug/items', desc: 'List items', tool: { name: 'db_items' },
+      input: ItemsQuery,        // include: z.array(...).default(['relations'])
+      output: ItemsResponse,    // one answer on HTTP and on the tools
+    },
+    { defaults: { include: [] } },   // what a tool call gets when it passes nothing
+  ),
+});
+```
+
+When the answer itself differs, the view carries its own schema too:
+
+```ts
+import { defineContract, withToolView } from 'stitchkit';
+
+export const users = defineContract({ prefix: 'users' }, {
+  list: withToolView(
+    {
+      method: 'GET', path: '/', desc: 'List users', tool: { name: 'user_list' },
+      input: UserListQuery,        // include: z.array(...).default(['profile', 'stats'])
+      output: UserListResponse,    // HTTP, OpenAPI and the typed client — unchanged
+    },
+    {
+      defaults: { include: [] },                          // what a tool call gets when it passes nothing
+      output: UserCardList,                               // the tool answer and its schema
+      project: (full, { input }) => ({ items: full.items.map(toCard) }),  // optional: without it, `output` slices
+    },
+  ),
+});
+```
+
+- **One handler, one parser.** `defaults` joins the tool call's arguments
+  *before* the endpoint's own `input` parses them, so the handler receives an
+  ordinary `input` — `include: []` from a tool, the HTTP default from HTTP — and
+  loads only what was asked for. An explicit argument wins over the default.
+- **The answer is derived, then checked.** The handler's result is validated
+  against the full `output` first, as always; then `project` (a pure,
+  synchronous function of the full result and the parsed input) or a slice by
+  the view's `output`, then validation against the view's schema. A projection
+  that throws, returns a Promise or breaks its schema is `INTERNAL_SERVER_ERROR`
+  — a server fault, like any output mismatch.
+- **Where it applies.** The MCP, agent and CLI mounts answer with the view;
+  `outputSchema`, `structuredContent`, the advertised input `default`, the
+  catalog stamp and the surface snapshot follow it. HTTP, OpenAPI, the typed
+  client and the in-process [`createToolInvoker`](#in-process-calls--createtoolinvoker)
+  keep the full answer — code, not a model, is calling there.
+- **Four forms, one helper.** With `defaults` alone the call changes and the
+  answer is the full `output`, validated by it and advertised as it. With
+  `output` and `project` the answer has its own schema. With `project` alone it
+  reshapes values inside the full schema. With `output` alone it is a slice, and
+  the full result must fit that schema — `withToolView` refuses the endpoint at
+  compile time when it does not.
+- **Exposure.** A view needs a tool transport. With `createContractFactory({
+  toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
+  endpoint with a view names its tool transports in `expose`.
+- **What it refuses.** `defineContract` rejects a view on an endpoint with no
+  tool transport or no full `output`, on a raw, `rawBody`, multipart,
+  `responseMeta` or streaming endpoint, a view that declares no `defaults`,
+  `output` or `project` — it would change nothing — and a default for a key the input does not have, for a path
+  param, or with a value the input would reject.
+
+A projection adds nothing the full result does not carry: a field the tool
+answer needs belongs in the full answer, loaded by the handler. Keys a
+projection returns beyond its schema are reported by `onOutputStrip`; a slice
+removes keys on purpose and is not reported. → [ADR 0196](../decisions/0196-a-tool-answer-is-a-declared-view.md)
+
+## AI agents — `mountAgent`
+
+`mountAgent` remains the low-level path when the application owns its own model
+loop and conversation state. For the optional Stitchkit-owned run/history loop,
+see [Agent application runtime](./agent-runtime.md).
+
+`mountAgent` turns a service into a Vercel AI SDK `ToolSet`, ready for
+`generateText` / `streamText`:
+
+```ts
+import { mountAgent } from 'stitchkit/tools'
+import { generateText } from 'ai'
+
+const tools = mountAgent(usersService, { context: { userId: 'agent-1' } })
+
+const result = await generateText({
+  model,
+  tools,
+  prompt: 'Create a user named Max',
+})
+```
+
+Each contract endpoint exposed on `AGENT` becomes a tool whose input schema is
+the merged `params` + `input`. `context` is merged into every tool handler's
+`ctx`, alongside `source: 'agent'`.
+
+### `AgentMountConfig`
+
+| Field | Purpose |
+|-------|---------|
+| `context` | values merged into every tool handler's `ctx` |
+| `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 `authorize` gate. Pass your `createAuthHook` result.
+
+### Adding tool-only args — `extend`
+
+`extend` adds **tool-only** arguments — fields the model fills that are resolved
+into context, then stripped before the contract handler sees them. Use it when a
+tool needs an argument the HTTP endpoint does not — the classic case being a
+**multi-tenant** server reached by one API key, where the model passes `tenantId`
+on every call. It is the same `ToolExtend` shape on `mountMcp`, `createMcpHandler`
+and `mountAgent`:
+
+```ts
+interface ToolExtend {
+  /** Extra Zod fields added to every matching tool's input schema. */
+  schema: Record<string, z.ZodType>
+  /** Turn the extra args into context merged into the handler's ctx. */
+  resolve: (args: Record<string, unknown>) => Partial<Ctx> | Promise<Partial<Ctx>>
+  /** Limit the extension to specific methods — default: every method. */
+  filter?: (service: ServiceDef, method: MethodDef) => boolean
+}
+```
+
+On the MCP server — add `tenantId` to each tool, validate access in `resolve`,
+inject the resolved tenant into `ctx`, and `filter` to the tenant-scoped tools:
+
+```ts
+createMcpHandler({
+  serverInfo, auth,
+  services: [widgetsService],
+  extend: {
+    schema: { tenantId: z.string().describe('Tenant to act on') },
+    resolve: async ({ tenantId }) => {
+      const id = String(tenantId)
+      if (!(await tenantExists(id))) throw new Error(`unknown tenant ${id}`)
+      return { tenantId: id }          // merged into ctx → ctx.tenantId
+    },
+    filter: (_service, method) => method.scope === 'tenant',
+  },
+})
+```
+
+The model calls `widgets_list({ tenantId: 't_123' })`; `resolve` checks access and
+puts `tenantId` on `ctx`; the contract handler reads `ctx.tenantId` (same place
+as the HTTP prefix param — see
+[Route groups → param prefixes](./server.md#param-prefixes-resource-scoped-paths)),
+so one handler serves both surfaces. Pair `extend` with `lifecycle` (your
+`createAuthHook`) so the tool call is still scope-gated.
+
+## Pathless runtime tools and multimodal results
+
+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, 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],
+  runtimeTools: [renderPreview],
+  lifecycle: { beforeHandle: authHook },
+  hooks: audit.toolCall,
+})
+
+const agentTools = mountAgent([service], {
+  runtimeTools: [renderPreview],
+  lifecycle: { beforeHandle: authHook },
+  hooks: audit.toolCall,
+})
+```
+
+When several runtime tools share application context and identity, bind both
+once with `createRuntimeToolFactory`. Its Zod context schema is parsed once per
+call inside the same runner; the authored handler receives validated context and
+parsed `input`, while lifecycle, hooks, output validation and presenters remain
+unchanged:
+
+```ts
+const knowledgeTools = createRuntimeToolFactory({
+  serviceName: 'agentKnowledge',
+  scope: 'user',
+  context: z.object({ userId: z.string(), tz: z.string() }),
+})
+
+const countRecords = knowledgeTools.define({
+  name: 'count_records',
+  action: 'countRecords',
+  method: 'GET',
+  description: 'Count records',
+  input: z.object({ kind: z.string() }),
+  output: z.object({ count: z.number() }),
+  handler: async ({ userId, tz, input }) => countFor(userId, tz, input.kind),
+})
+```
+
+`serviceName` and `scope` cannot be overridden by one definition. Use standalone
+`defineRuntimeTool` when tools do not share a context schema or identity.
+
+`transports` defaults to `['MCP', 'AGENT']`; set an explicit subset when an
+operation belongs on only one surface. Include `'CLI'` explicitly to reuse the
+definition through `createCli({ runtimeTools })`; adding CLI support never
+widens existing definitions silently. 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
+use the same validation, lifecycle and hook path as contract tools.
+
+### Managed wait, download, upload and view-file
+
+The common imperative shapes have typed definition factories. They produce
+ordinary runtime-tool definitions, so one value can enter `runtimeTools` on MCP
+and Agent and receives the same lifecycle, hooks, context, cancellation,
+collision checks and introspection as any `defineRuntimeTool` operation:
+
+```ts
+import {
+  defineDownloadTool,
+  defineUploadTool,
+  defineViewFileTool,
+  defineWaitTool,
+} from 'stitchkit/tools'
+import { createManagedFileBoundary } from 'stitchkit/files'
+import { z } from 'zod'
+
+const files = await createManagedFileBoundary({
+  root: '/srv/job-media',
+  createRoot: true, // creates only this final directory; /srv must already be trusted
+  inspectionTimeoutMs: 15_000,
+  inspect: ({ prefix, name, declaredMediaType, signal }) =>
+    inspectFile(prefix, { name, declaredMediaType, signal }),
+})
+
+const waitForJob = defineWaitTool({
+  name: 'wait_for_job',
+  description: 'Wait for a job to finish',
+  identity: { serviceName: 'jobs', action: 'waitForJob', scope: 'user' },
+  input: z.object({ id: z.string() }),
+  state: z.object({ id: z.string(), status: z.enum(['RUNNING', 'DONE']) }),
+  poll: ({ id }, context) => getJob(id, context.signal),
+  done: (state) => state.status === 'DONE',
+  backoff: [2, 3, 5],
+  defaultTimeout: 120,
+})
+
+const downloadResult = defineDownloadTool({
+  name: 'download_result',
+  description: 'Download a completed result',
+  identity: { serviceName: 'jobs', action: 'downloadResult', scope: 'user' },
+  input: z.object({ id: z.string() }),
+  resolveUrl: ({ id }) => resolveResultUrl(id),
+  files,
+  pathFromInput: ({ id }) => `results/${id}.bin`,
+})
+
+const uploadInput = defineUploadTool({
+  name: 'upload_input',
+  description: 'Upload a local input file',
+  identity: { serviceName: 'jobs', action: 'uploadInput', scope: 'user' },
+  output: z.object({ url: z.url() }),
+  files,
+  upload: (source, context) => uploadBytes(source.bytes, context.signal),
+})
+
+const viewResult = defineViewFileTool({
+  name: 'view_result',
+  description: 'Inspect generated media',
+  identity: { serviceName: 'jobs', action: 'viewResult', scope: 'user' },
+  // Local files are disabled when files is omitted. URL fetches retain SSRF
+  // protection; use allowPrivateHosts only for an explicitly trusted network.
+  files,
+})
+
+const runtimeTools = [waitForJob, downloadResult, uploadInput, viewResult]
+```
+
+Managed factories return neutral validated data. Expected failures go through
+the standard failed `ToolResult` path rather than masquerading as a successful
+payload with `isError`. Wait sleep is abort-aware, guarded downloads receive the
+active signal, and upload implementations receive it on their typed context.
+Managed view-file accepts one or several paths/URLs, retains successful
+multimodal content beside structured per-item `errors`, and charges every item
+to one total 20 MB batch budget. Its MCP and Agent presenters are built in;
+remote fetch cancellation follows the active call signal.
+
+The older `mountWait`, `mountDownload`, `mountUpload` and `mountViewFile`
+functions remain
+intentional raw MCP adapters with their text-envelope behavior. Use them under
+`rawTools` only when opting out of managed policy is deliberate; they share the
+same neutral mechanics but do not gain lifecycle or hooks. The raw view-file
+adapter preserves its content-only MCP envelope while using the same bounded
+batch operation.
+
+### Async-operation protocol
+
+For a complete long-running operation, define the linked runtime-only surface
+once. Stitchkit owns transport names, validation and wait mechanics; the
+application still owns storage, execution, retries and domain states:
+
+```ts
+import {
+  createAsyncOperationSnapshotSchema,
+  defineAsyncOperation,
+} from 'stitchkit/tools'
+
+const id = z.object({ id: z.string() })
+const state = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded']),
+  value: z.string().optional(),
+})
+const snapshot = createAsyncOperationSnapshotSchema({
+  failure: z.object({ code: z.string() }),
+  progress: z.object({ current: z.number(), total: z.number() }),
+})
+
+const exportOperation = defineAsyncOperation({
+  mode: 'runtime-only',
+  name: 'export',
+  description: 'Export project data',
+  identity: { serviceName: 'exports', action: 'export', scope: 'user' },
+  startInput: z.object({ projectId: z.string() }),
+  id,
+  state,
+  snapshot,
+  start: ({ projectId }) => enqueueExport(projectId),
+  authorize: ({ id }, capability, ctx) => authorizeExport(id, capability, ctx),
+  inspect: ({ id }, ctx) => readExport(id, ctx.signal),
+  classify: (job) => ({ phase: job.phase }),
+  result: {
+    output: z.object({ value: z.string() }),
+    handler: (job) => ({ value: job.value ?? '' }),
+  },
+})
+
+const runtimeTools = exportOperation.runtimeTools
+```
+
+#### Durable application-owned execution
+
+The executable reference
+[`durable-async-operation-harness.ts`](../../packages/core/examples/tools/durable-async-operation-harness.ts)
+shows the complete boundary behind that surface. It composes
+`defineAsyncOperationContract`, `defineAsyncOperation`, `createApplication`,
+`createBoundedAdmission`, managed shutdown and `createAgentToolFenceLifecycle`
+around an injected store and provider.
+
+The store transactionally owns the idempotency key **and normalized request
+hash**. Reusing both returns the existing operation; reusing the key with a
+different hash conflicts. Every mutation is an expected-revision CAS. Before an
+external call, the application persists a unique attempt/effect key and marks
+the dispatch `possibly-dispatched`; a lost response is therefore reconciled by
+that key after restart and is never treated as permission to submit the effect
+again. Provider acknowledgement, progress, cancellation intent, result and
+artifact references remain durable application state.
+
+Agent tool fencing and operation idempotency are separate guarantees. The fence
+prevents a stale run owner from crossing an effect boundary; the transactional
+idempotency record makes a repeated current call converge on one operation.
+Neither replaces the other.
+
+Stitchkit deliberately does **not** own the durable queue, operation database,
+lease renewal, provider retry/reconciliation protocol, asset catalog or domain
+states. The process-local application resource stops admission and drains
+accepted work; unresolved durable records survive shutdown for the next
+recovery pass. The packed consumer lane executes this composition from the
+published package on Bun and Node.
+
+Every follow-up repeats `authorize`; an opaque id is never authority. Aborting
+`wait` only stops waiting and never calls optional domain `cancel`.
+
+For a new HTTP surface, derive the canonical capability contract once. The
+factory defines schemas and routes only; the application still supplies normal
+handlers to `implement` and owns the job:
+
+```ts
+import { defineAsyncOperationContract } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const operationId = z.object({ id: z.string() })
+const operationSnapshot = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded', 'failed', 'cancelled']),
+})
+
+const operations = defineAsyncOperationContract({
+  prefix: 'exports',
+  scope: 'user',
+  description: 'Export project data',
+  startInput: z.object({ projectId: z.string() }),
+  id: operationId,
+  snapshot: operationSnapshot,
+  cancel: true,
+  result: z.object({ downloadUrl: z.url() }),
+})
+
+// Pass operations.contract and ordinary handlers to implement(...).
+// operations.capabilities/schemas/adapters are the canonical protocol metadata.
+```
+
+If an existing dedicated contract has a different wire shape — for example
+`start` returns a snapshot while follow-ups accept separate envelopes — bind it
+without casts or duplicate endpoints. Inline callbacks are contextually typed;
+every returned id/input is parsed by the destination schema:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { bindContractAsyncOperation } from 'stitchkit/tools'
+
+const startOutput = z.object({ operation: operationId, acceptedAt: z.string() })
+const statusInput = z.object({ operationId: z.string() })
+const waitInput = z.object({ lookup: operationId })
+
+const existing = defineContract({ prefix: 'exports' }, {
+  start: {
+    method: 'POST', path: '/', desc: 'Start export',
+    input: z.object({ projectId: z.string() }), output: startOutput,
+  },
+  status: {
+    method: 'POST', path: '/status', desc: 'Read export status',
+    input: statusInput, output: operationSnapshot,
+  },
+  wait: {
+    method: 'POST', path: '/wait', desc: 'Wait for export',
+    input: waitInput, output: operationSnapshot,
+  },
+})
+
+const operationHandlers = {
+  start: () => ({ operation: { id: 'example' }, acceptedAt: new Date().toISOString() }),
+  status: (): z.output<typeof operationSnapshot> => ({ phase: 'pending' }),
+  wait: (): z.output<typeof operationSnapshot> => ({ phase: 'succeeded' }),
+}
+
+const bound = bindContractAsyncOperation({
+  mode: 'contract-backed',
+  binding: 'adapted',
+  contract: existing,
+  id: operationId,
+  capabilities: { start: 'start', status: 'status', wait: 'wait' },
+  adapters: {
+    idFromStart: (output) => output.operation,
+    inputFor: {
+      status: (id) => ({ operationId: id.id }),
+      wait: (id) => ({ lookup: id }),
+    },
+  },
+  handlers: operationHandlers,
+})
+```
+
+Direct binding remains the short form when start already returns the id and
+every follow-up reuses that exact schema instance. Its ID schema must be
+wire-stable: input and output types match and parsing has no transform,
+coercion, default or overwrite. This also excludes same-type transforms because
+the direct adapters would parse an already parsed ID again. Use adapted binding
+and explicitly project the parsed ID back into each follow-up input. In both
+modes the binder creates no router;
+it returns the existing contract, handlers and protocol metadata for
+application composition.
+
+### Explicit raw SDK registration
+
+`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`, `mountWait`, `mountDownload` and
+`mountUpload` helpers remain raw for callers that choose that boundary; the
+media helper fetches with SSRF and path-traversal defenses:
+
+```ts
+import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth,
+  services: [service],
+  rawTools: (server) => mountViewFile(server, { files }),
+})
+```
+
+Use raw registration only when opting out is intentional. For a protected
+`view_file`, use `defineViewFileTool` in `runtimeTools`; it supplies the
+canonical schemas, shared batch budget, structured partial failures and both
+multimodal presenters. `resolveMedia` remains the single-item core for custom
+operations whose contract intentionally differs.
+
+## 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.
+
+Applications using Stitchkit's durable runtime can compose this manifest with
+bounded per-run activation through `createDeferredAgentToolSurface` from
+`stitchkit/agent-runtime`. It keeps selected calls as direct `mountAgent` tools
+rather than routing them through a generic executor. Search receipts live in
+ordinary durable tool-result history, so recovery restores activation and a
+queued successor cannot inherit it. See
+[Bounded deferred tool catalogs](./agent-runtime.md#bounded-deferred-tool-catalogs)
+and ADR 0129. Raw `mountAgent`, `mountMcp` and `buildToolManifest` behavior is
+unchanged.
+
+`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`
+
+Every tool mount fires an `afterToolCall` hook. `createToolLogger` is a ready
+preset for it — one line logs each call (ok / failed, duration, which endpoint,
+keyed by the endpoint's stable `serviceName` / `key` identity):
+
+```ts
+import { createToolLogger } from 'stitchkit/tools'
+
+mountMcp(server, services, { hooks: createToolLogger() })
+// [tool] ok list_widgets (widgets.list) 12ms
+// [tool] warn get_widget (widgets.get) NOT_FOUND 4ms
+```
+
+By default the line goes to `console.error` — **stderr, never stdout**. That is
+deliberate: in a stdio-MCP server stdout is the JSON-RPC protocol channel, and a
+log line written there corrupts the stream. If you pass your own `log`, keep it
+off stdout for any stdio deployment.
+
+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, runtimeTools })` returns the mixed
+per-transport counts for you to log.
+
+## One handler, three callers
+
+A contract handler runs the same for an HTTP request, an MCP tool call and an
+agent tool call. `ctx.source` (`'http'` · `'mcp'` · `'agent'`) tells it which —
+the rest of the context (`params`, `input`, anything `context` injects) is
+identical. Write the handler once; it serves every surface.