stitchkit 0.53.1 → 0.54.0

package/llms-full.txt

@@ -2364,8 +2364,9 @@ must not be used as authorization input.
 ### Modern discovery, routing and cache hints
 
 Stitchkit forwards the negotiated protocol era and validated MCP request data
-to `RequestEvent.mcp`; untrusted routing headers never become application
-identity. The SDK validates `MCP-Protocol-Version`, JSON-RPC shape and routing
+to both `RequestEvent.mcp` and the current managed call's typed `context.mcp`;
+untrusted routing headers never become application identity. The SDK validates
+`MCP-Protocol-Version`, JSON-RPC shape and routing
 metadata before lifecycle or tool handlers run. Framework-owned tool and
 resource registration preserves declaration order across HTTP and stdio. Tool
 manifests preserve mount order; `listToolNames` is a sorted diagnostics view.
@@ -2380,6 +2381,30 @@ finite `surfaces` registry when identities share a provably immutable surface.
 Stitchkit never advertises list-change or subscription capabilities
 without an implementation.
 
+### Typed MCP call metadata
+
+Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
+see the same optional `McpCallContext` for the current invocation:
+
+```ts
+const sourceLabel = context.mcp?.clientInfo?.name ?? context.source
+
+context.mcp?.era             // 'modern' | 'legacy'
+context.mcp?.method          // validated MCP method
+context.mcp?.toolName        // resolved framework tool name
+context.mcp?.protocolVersion // when supplied by a modern host
+context.mcp?.clientInfo      // { name, version } when validated
+context.mcp?.outcome         // multi-round attempt outcome
+context.mcp?.round           // multi-round attempt number
+```
+
+The field is absent on HTTP, Agent, CLI and bring-your-own transports. A legacy
+MCP call exposes `era: 'legacy'` but does not invent modern client information.
+`clientInfo` is the host's self-description: use it for labels or analytics,
+never for authentication, RBAC, tenant selection or rate limiting. Verified
+identity still comes from `auth`; the `context(auth)` callback remains the
+application-context factory and receives no protocol metadata.
+
 ### Multi-round tool input (`input_required`)
 
 An MCP-only operation can require typed user input before its final side effect:
@@ -2598,7 +2623,7 @@ client (Claude Desktop, Claude Code, Cursor, Codex), on the user's machine, so
 it can reach the local filesystem.
 
 ```ts
-import { createStdioMcpServer } from 'stitchkit/tools'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools'
 
 const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
@@ -2606,8 +2631,16 @@ const stdio = await createStdioMcpServer({
   services: [usersService],
 })
 
-// During graceful shutdown:
-await stdio.close()
+const signals = bindStdioProcessSignals(stdio, {
+  onClose: () => stopWorkers(),
+  onComplete: () => { process.exitCode = 0 },
+  onError: (_phase, error) => {
+    console.error(error) // stderr only — stdout is JSON-RPC
+    process.exitCode = 1
+  },
+})
+
+await signals.promise
 ```
 
 A stdio server is a single process serving one client, so `auth` is a value (or
@@ -2620,6 +2653,14 @@ through the official stdio adapter. Use `legacy: 'reject'` for a modern-only
 binary. Each invocation builds a fresh server; the returned handle owns
 transport shutdown.
 
+Signal binding is explicit: `createStdioMcpServer` installs no global process
+listeners by itself. The first `SIGINT`/`SIGTERM` starts exactly one official
+`close()` chain. Stdio has no force primitive, so a later signal restores the
+OS default disposition instead of reporting a fictional forced result.
+`signals.close()` removes an idle binding; the framework never calls
+`process.exit()` or chooses the exit code. See
+[deployment lifecycle](./testing-and-deployment.md#stdio-process-signals).
+
 Both transports build the server through the shared `buildMcpServer` — same
 contract/runtime pipeline, same surface selection, context, hooks, raw escape
 hatch and instructions.
@@ -2943,7 +2984,9 @@ const countRecords = knowledgeTools.define({
 `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. The configured identity becomes the
+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.
@@ -2960,12 +3003,88 @@ 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 { z } from 'zod'
+
+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(), dir: z.string().optional() }),
+  resolveUrl: ({ id }) => resolveResultUrl(id),
+  defaultDir: './downloads',
+  dirFromInput: ({ dir }) => dir,
+})
+
+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() }),
+  upload: (path, context) => uploadFile(path, context.signal),
+})
+
+const viewResult = defineViewFileTool({
+  name: 'view_result',
+  description: 'Inspect generated media',
+  identity: { serviceName: 'jobs', action: 'viewResult', scope: 'user' },
+  // Local files are disabled when baseDir is omitted. URL fetches retain SSRF
+  // protection; use allowPrivateHosts only for an explicitly trusted network.
+  baseDir: '/srv/job-media',
+})
+
+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.
+
 ### 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` helper remains raw for callers that choose
-that boundary; it fetches media with SSRF and path-traversal defenses:
+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'
@@ -2979,8 +3098,10 @@ const handleMcp = createMcpHandler({
 ```
 
 Use raw registration only when opting out is intentional. For a protected
-`view_file`, define it with `defineRuntimeTool`, include it in `runtimeTools`,
-and call the exported `resolveMedia` core from its handler.
+`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
 
@@ -3061,11 +3182,13 @@ identical. Write the handler once; it serves every surface.
 
 # CLI
 
-The same contract that drives the HTTP API, MCP tools and agent tools also
-drives a command-line program. `createCli` turns contract methods into commands
-— `myapp generate "a fox" --wait`, `myapp models list --json | jq …` — run
-through the very same validation, auth gate and error model as every other
-surface (HTTP ≡ MCP ≡ agent ≡ CLI, [ADR 0014](../decisions/0014-tool-http-parity.md)).
+The same contract and managed runtime tools that drive HTTP, MCP and agent
+surfaces can also drive a command-line program. `createCli` composes their
+commands with explicitly local binary commands in one router and help tree.
+Managed commands — `myapp generate "a fox" --wait`,
+`myapp models list --json | jq …` — run through the same validation, auth gate
+and error model as every other managed surface (HTTP ≡ MCP ≡ agent ≡ CLI,
+[ADR 0014](../decisions/0014-tool-http-parity.md)).
 
 It exists for what the other three surfaces cannot do: a generation kicked off
 with `Bash(run_in_background)` that notifies on exit, a `SKILL.md` that shells
@@ -3086,8 +3209,10 @@ the CLI never silently turns your existing API tools into shell commands.
 ```
 
 A fresh contract shows **zero** CLI commands until methods opt in — that is the
-design, not a bug. The command name is the tool name — `toolName` if set, else a
-verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
+design, not a bug. A pathless runtime definition follows the same rule: it must
+explicitly include `'CLI'` in `transports`; the undefined default remains
+`['MCP', 'AGENT']`. The command name is the tool name — `toolName` if set, else
+a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
 `get_widget`), not a literal `prefix_key`.
 
 ## A minimal CLI
@@ -3105,7 +3230,7 @@ await createCli({
   name: 'myapp',
   version: '1.0.0',
   services: [catalogService, generateService],
-  auth: process.env.MYAPP_TOKEN,            // resolved ONCE, like a stdio MCP server
+  resolveAuth: () => resolveToken(process.env.MYAPP_TOKEN), // lazy, at most once
 })
 ```
 
@@ -3117,6 +3242,81 @@ await createCli({
 `stitchkit/cli` pulls in neither the MCP SDK nor `ai`, so a CLI binary needs no
 MCP/agent peer dependencies.
 
+## Pathless managed commands
+
+Use `runtimeTools` when an application operation has no HTTP path but must keep
+the canonical operation identity, context, lifecycle/RBAC, hooks and
+introspection. It can share one definition with MCP and Agent while opting into
+CLI explicitly:
+
+```ts
+import { createCli } from 'stitchkit/cli'
+import { defineUploadTool } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const uploadInput = defineUploadTool({
+  name: 'upload_input',
+  description: 'Upload one local input file',
+  identity: { serviceName: 'jobs', action: 'uploadInput', scope: 'user' },
+  output: z.object({ url: z.url() }),
+  transports: ['MCP', 'AGENT', 'CLI'],
+  upload: (path, context) => uploadFile(path, context.signal),
+})
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  runtimeTools: [uploadInput],
+})
+```
+
+`services` and `runtimeTools` may each be static arrays or factories receiving
+the resolved identity. A runtime-only CLI is valid; `stitchkit/cli` still pulls
+in neither MCP nor AI peers. Contract/runtime name collisions and reserved
+option fields fail through the same checks before managed dispatch.
+
+## Native binary commands
+
+Login, self-update, diagnostics, integration setup and shell completion belong
+to the executable, not to HTTP/MCP/Agent. Define them with `defineCliCommand`:
+
+```ts
+import { createCli, defineCliCommand } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const login = defineCliCommand({
+  name: 'login',
+  description: 'Store credentials for later managed commands',
+  input: z.object({ token: z.string() }),
+  output: z.object({ configured: z.boolean() }),
+  handler: async ({ input }) => {
+    await saveToken(input.token)
+    return { configured: true }
+  },
+})
+
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  commands: [login],
+  resolveAuth: loadStoredIdentity,
+  services: (identity) => createRemoteServices(identity),
+})
+```
+
+Native commands receive only typed `input`, parsed global `options` and the
+configured stdout/stderr writers. They reuse help, argv/stdin parsing,
+validation, dry-run, error envelopes and exit mapping, but deliberately have no
+fake service/action/scope/method identity, lifecycle or tool hooks and never
+appear in MCP/Agent manifests.
+
+`--version`, a selected native command and its command help run before
+`resolveAuth`, services, context or runtime-tool factories. Top-level help is
+also credential-free when managed surfaces are static. A dynamic factory must
+resolve identity to discover its command names; its collisions are checked at
+that resolution boundary. If eager global collision proof matters, keep the
+surface static.
+
 ## Calling commands
 
 ```
@@ -3201,7 +3401,7 @@ const authHook = createAuthHook({ /* resolve, resolveFromContext, rules */ })
 await createCli({
   name: 'myapp',
   version: '1.0.0',
-  auth: await resolveIdentityFromToken(process.env.MYAPP_TOKEN),
+  resolveAuth: () => resolveIdentityFromToken(process.env.MYAPP_TOKEN),
   context: (identity) => ({ user: identity }),   // resolveFromContext reads this
   lifecycle: { beforeHandle: authHook },          // same policy; HTTP wires it as authorize
   services,
@@ -3233,11 +3433,12 @@ await tools.createCli({
 })
 ```
 
-## Not in v1
+## Remaining boundary
 
-File-upload (`multipart`) endpoints are CLI-invisible, the same as on MCP /
-agent — a dedicated upload command (auto-uploading local paths) is future work.
-Streaming (SSE) output is not yet piped to stdout.
+File-upload (`multipart`) contract endpoints remain CLI-invisible, the same as
+on MCP/Agent: their wire body is not a JSON tool form. Model file-oriented
+application behavior as a managed pathless command, or binary-only behavior as
+a native command. Streaming (SSE) output is not yet piped to stdout.
 
 
 ==============================================================================
@@ -5079,6 +5280,38 @@ domain run-state remain application resources and close explicitly after server
 drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
 `shutdown()`.
 
+### Stdio process signals
+
+An MCP stdio handle has `close()`, not managed HTTP `shutdown()` with a force
+signal and deadline. Bind its process lifecycle with the truthful close-only
+sibling from `stitchkit/tools`:
+
+```ts
+import {
+  bindStdioProcessSignals,
+  createStdioMcpServer,
+} from 'stitchkit/tools'
+
+const stdio = await createStdioMcpServer(config)
+const binding = bindStdioProcessSignals(stdio, {
+  onClose: () => stopWorkers(),
+  onComplete: () => { process.exitCode = 0 },
+  onError: (phase, error) => {
+    console.error(phase, error) // stderr; stdout stays JSON-RPC-only
+    process.exitCode = 1
+  },
+})
+
+await binding.promise
+```
+
+The first signal starts exactly one close chain. A same-turn duplicate is
+ignored; a later signal restores the default OS disposition because the
+official stdio close is not abortable and Stitchkit will not pretend otherwise.
+`binding.close()` removes idle listeners and resolves the promise with
+`undefined`. No listener is installed until the binder is called, and the
+framework never calls `process.exit()`.
+
 ### Deploy on Node
 
 The contract, `implement`, hooks, auth and the client are runtime-agnostic. Only
@@ -6443,8 +6676,11 @@ from the root `stitchkit`.
 | `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 |
-| `HandlerContext` | _type_ | the typed context seen by a handler |
+| `RuntimeContext` | _type_ | the loose context seen by transport and hooks, including optional typed `mcp` metadata |
+| `HandlerContext` | _type_ | the typed context seen by a handler, including optional typed `mcp` metadata |
+| `McpCallContext` | _type_ | validated metadata for the active managed MCP call (`era`, method, tool, client and multi-round fields) |
+| `McpClientInfo` | _type_ | self-reported MCP host name/version; attribution only, never application identity |
+| `McpRoundOutcome` | _type_ | managed multi-round attempt outcome |
 | `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
 | `EndpointFn` | _type_ | the call signature of one client method |
 | `TypedClient` | _type_ | the full typed client for a contract |
@@ -6775,14 +7011,16 @@ payload.
 | `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
 | `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
 | `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
+| `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
 | `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
 | `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) |
+| `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [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`) |
+| `defineCliCommand` | function | define one typed CLI-only command with no fake managed-tool identity — [guide](../guide/cli.md#native-binary-commands) (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 |
 | `resolveMedia` | function | resolve a media reference for a tool result |
@@ -6796,6 +7034,10 @@ payload.
 | `McpLegacyPolicy` | _type_ | `'serve' \| 'reject'` protocol-era compatibility policy |
 | `McpStdioHandle` | _type_ | closeable official stdio transport handle |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
+| `StdioCloseTarget` | _type_ | minimal close-only target accepted by `bindStdioProcessSignals` |
+| `StdioProcessSignalsOptions` | _type_ | signal source, close callbacks and phased error reporting |
+| `StdioProcessSignalsBinding` | _type_ | close-only signal binding with observed `promise` and listener `close()` |
+| `StdioProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'close' \| 'complete'` reporting phase |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
 | `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
 | `McpServer` | _type_ | official split-SDK server instance accepted by raw extension points |
@@ -6833,10 +7075,16 @@ payload.
 | `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
 | `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
-| `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT'` |
+| `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT' \| 'CLI'`; omission still means MCP+Agent only |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
 | `CliConfig` | _type_ | config for `createCli` |
+| `CliSurfaceSource` | _type_ | static managed surface or identity-dependent surface factory for `createCli` |
+| `CliCommandDefinition` | _type_ | Zod-first CLI-only command union |
+| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema and validated handler result |
+| `CliCommandDefinitionWithoutOutput` | _type_ | void native command with no output schema |
+| `CliCommandContext` | _type_ | parsed native command input, global options and injected writers |
 | `CliWaitConfig` | _type_ | `--wait` polling config |
 | `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
@@ -6853,9 +7101,15 @@ payload.
 | `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` |
+| `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
+| `ViewFileOptions` | _type_ | shared URL/local-sandbox policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
+| `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
+| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
+| `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
+| `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |
+| `McpAnnotationsSchema` | constant | Zod schema for MCP media annotations |
+| `McpMediaContentSchema` | constant | Zod schema for text/image/audio media content |
 | `CollectToolsConfig` | _type_ | options for `collectTools` |
 | `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
 | `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
@@ -6868,13 +7122,28 @@ payload.
 
 ### Native tools
 
-Generic host-supplied tools mounted onto a server — not derived from a contract.
+Generic host-supplied operations — managed definitions for the canonical
+runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `mountDownload` | function | a "download a URL to disk" tool (SSRF-guarded, size-capped) |
-| `mountUpload` | function | an "upload a local file" tool |
-| `mountWait` | function | a generic `--wait`-style polling tool |
+| `defineDownloadTool` | function | define a guarded, size-capped managed download for MCP/Agent `runtimeTools` |
+| `defineUploadTool` | function | define a typed managed local-file upload for MCP/Agent `runtimeTools` |
+| `defineWaitTool` | function | define a typed, cancellable managed polling operation for MCP/Agent `runtimeTools` |
+| `defineViewFileTool` | function | define a guarded, batch-capped managed multimodal operation for MCP/Agent `runtimeTools` |
+| `DefineDownloadToolConfig` | _type_ | Zod input, stable identity, URL resolver, storage policy and presenters for `defineDownloadTool` |
+| `DefineUploadToolConfig` | _type_ | stable identity, typed output, upload callback and presenters for `defineUploadTool` |
+| `DefineWaitToolConfig` | _type_ | Zod input/state, identity, poll/done/timeout policy and presenters for `defineWaitTool` |
+| `DefineViewFileToolConfig` | _type_ | identity, media security policy and optional presenters for `defineViewFileTool` |
+| `ManagedNativeToolConfig` | _type_ | shared name, description, identity, exposure and annotations for managed native factories |
+| `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
+| `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
+| `DownloadResultSchema` | constant | Zod schema for a saved download's path, byte size and MIME type |
+| `DownloadResult` | _type_ | validated output of `defineDownloadTool` |
+| `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
+| `mountDownload` | function | raw MCP "download a URL to disk" adapter (SSRF-guarded, size-capped) |
+| `mountUpload` | function | raw MCP "upload a local file" adapter |
+| `mountWait` | function | raw MCP generic `--wait`-style polling adapter |
 | `DownloadToolConfig` | _type_ | config for `mountDownload` |
 | `UploadToolConfig` | _type_ | config for `mountUpload` |
 | `WaitToolConfig` | _type_ | config for `mountWait` |
@@ -6979,17 +7248,25 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 
 ## `stitchkit/cli`
 
-Server-only. Turns contracts into a command-line program — the fourth transport.
-Light by design: needs neither the MCP SDK nor the `ai` peer.
+Server-only. Composes contract/runtime managed operations and CLI-only native
+commands into one command-line program. Light by design: needs neither the MCP
+SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `defineCliCommand` | function | define one Zod-typed CLI-only executable command |
 | `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
 | `pollUntilDone` | function | the generic `--wait` poller (advanced) |
 | `emitResult` | function | write a `ToolResult` to stdout/stderr + exit code (advanced) |
 | `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
 | `CliConfig` | _type_ | config for `createCli` |
+| `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
+| `CliCommandDefinition` | _type_ | native command definition union |
+| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output |
+| `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
+| `CliCommandContext` | _type_ | parsed input, global options and stdout/stderr writers |
 | `CliRunOptions` | _type_ | parsed global flags (`--json`, `--wait`, …) |
 | `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
 | `CliWaitConfig` | _type_ | per-command `--wait` polling config |

package/package.json

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