stitchkit 0.121.0 → 0.122.1

package/llms/agent-runtime.3.txt

@@ -14,6 +14,114 @@ Parts of this slice:
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
 ==============================================================================
 
+## Observability
+
+`createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
+reuses the same bounded sink lifecycle as request/tool observability without
+sending new event kinds to existing request sinks. Product events omit provider
+causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
+set `includeInternalCause` and own its retention policy.
+
+### What a run says it spent
+
+Usage values carry `provider-reported`, `computed`, `estimated` or `unavailable`
+provenance, **per field**. Cost additionally carries an ISO currency code;
+OpenRouter-reported cost is normalized as USD.
+
+Read the provenance before the number (→ ADR 0109):
+
+- **`provider-reported`** — the provider handed us exactly this. On
+  `step-finished`, that is what a step's figures are.
+- **`computed`** — a total, added up over steps. **Every figure on a terminal
+  event is this**, tokens included: the AI SDK's `totalUsage` is a sum it
+  performed, not a number a provider reported for the run. It is not a figure to
+  bill against unchanged.
+- **`unavailable`** — nobody reported it. Not zero.
+
+Two rules follow from that last one, and they differ by field on purpose:
+
+- **A token total with an unreported step is a floor**, labelled `computed`. A
+  token count is a diagnostic, and a floor is a useful one.
+- **A cost with an unreported step is `unavailable`, not a floor.** Money is what
+  people bill against, and "at least $1.00" reported as `$1.00` is the same class
+  of lie this whole section exists to remove. One step that did not report its
+  cost makes the run's cost unknown — not smaller. It also stays unknown: later
+  steps reporting normally cannot revive it.
+
+**A terminal event always carries `usage`.** A run that ended before the provider
+reported anything — superseded, interrupted, timed out, shut down, failed —
+carries every field `unavailable`. That is deliberately different from a run that
+spent nothing, and an omitted object could not tell you which one you had.
+
+Two costs in different currencies do not add: the sum reports `unavailable`
+rather than picking a label. The core records a currency and never converts one.
+
+`step-finished.response` identifies the provider response for that one step. The terminal event
+does not copy the last response: response identity remains per-step, while every terminal usage
+figure remains a `computed` aggregate.
+
+**A run's figure is durable, and that is where to read it when a channel loses
+it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
+record, so a crashed process leaves behind what it had already spent and a
+dropped event is not a lost number:
+
+```ts
+const snapshot = await store.loadSnapshot(conversationId)
+const spent = snapshot.runs.find((run) => run.id === runId)?.usage
+```
+
+Two gaps are open and are stated rather than left to be discovered:
+
+- **Both event sinks are bounded and drop under load**, by arrival order — the
+  event carrying the money is exactly as droppable as the one carrying nothing.
+  The run record is the recovery, and this paragraph is the only place that says
+  so.
+- **`AgentRuntimeResult.metrics` is `undefined` when this executor did not win
+  the terminal race.** Read `result.run.usage` — the durable figure — rather than
+  `result.metrics`, which is the channel that can go missing.
+- **Compaction spend is invisible unless you report it.** `config.history.compact`
+  calls a model inside the turn and produces no step and no event of its own.
+  Return `usage` from `AgentCompactionResult` and it joins the run's figure;
+  omit it and the run under-reports by whatever summarising cost.
+
+What stitchkit does **not** keep is a ledger: one figure, on the run that
+produced it, never aggregated and never reconciled against a provider invoice
+(→ ADR 0110).
+
+### Reconciling with the provider's own accounting
+
+Whether a provider bills for a call that was aborted mid-flight cannot be known
+inside the process: the authoritative number arrives later, from the provider's
+accounting. **stitchkit does not accept it back** (→ ADR 0110) — a terminal run
+is an absorbing state, and a write that reached it through the conversation
+aggregate could conflict a concurrent compaction into discarding a summary it had
+just paid a model to produce.
+
+The join is yours, and `runId` is the key:
+
+```ts
+// when the run terminates — write what the runtime observed
+await ledger.record({
+  runId: terminal.run.id,
+  conversationId: terminal.run.conversationId,
+  // The durable figure, not `terminal.metrics` — that one is absent whenever
+  // this executor did not win the terminal race.
+  costUsd: terminal.run.usage?.cost?.value ?? null,        // null when `unavailable`
+  provenance: terminal.run.usage?.cost?.provenance ?? 'unavailable',
+})
+
+// later — the provider's accounting names the same generation
+await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
+```
+
+Record the row even when the figure is `unavailable`: that row is the evidence
+that a run happened and cost something nobody has counted yet, and it is what the
+provider's later figure attaches to. A run with no row is a run you cannot
+reconcile.
+
+The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
+outbox.
+
 ## Deterministic race and adapter proof
 
 `stitchkit/agent-runtime/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver`,
@@ -391,7 +499,9 @@ Delivery exports are `AgentAdmissionEventSchema`, `AgentAttemptResetEventSchema`
 `AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
 `AgentTransientDeltaEventSchema`,
 `AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
-`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentRuntimeEvent`,
+`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentToolProgressEventSchema` (what a
+running tool reported through `ctx.reportProgress`, transient and never part of the model's input),
+`AgentRuntimeEvent`,
 `AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,
 `advanceAgentRuntimeEventCursor`, `agentDurableEventId`, `AgentRuntimeEventSink`,
 `AgentRuntimeEventSinkConfig` and `createAgentRuntimeEventSink`. Cursor gaps require a canonical

package/llms/cli.txt

@@ -702,15 +702,36 @@ Rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
-If the command succeeds but its requested view cannot be built, the CLI writes
-the complete original result to stdout, using the normal JSON format (`--json`
-still selects compact output). It writes a separate structured
-`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
-through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
-distinguish a presentation refusal from a failed operation; `details.cause`
-preserves the safe reason. Recover the answer from stdout instead of repeating
-the mutation. Domain retry hints are not appended to this diagnostic. CLI
-argument errors detected before execution still exit with `2`
+If the command succeeds but its requested view cannot be built, the CLI writes a
+structured `CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`,
+configurable through `exitCodes`. Its `details.operationSucceeded: true` and
+`retryable: false` distinguish a presentation refusal from a failed operation;
+`details.cause` preserves the safe reason, such as the misspelled field and the
+fields that are there. Domain retry hints are not appended to this diagnostic.
+
+What reaches stdout depends on whether the command can be called again for its answer,
+and `details.resultOnStdout` states which case occurred:
+
+| Command | stdout | Recover the answer by |
+|---|---|---|
+| has an effect | the complete original result in the normal JSON format (`--json` still selects compact output) | reading stdout — never by repeating the mutation |
+| only reads | nothing | repeating the command with a corrected view |
+
+A managed command only reads when its tool declares `annotations.readOnlyHint: true`,
+or declares no `readOnlyHint` and its method is `GET`. `readOnlyHint: false`, or
+`destructiveHint: true` without a `readOnlyHint`, on a `GET` endpoint keeps the result on stdout. A native
+`defineCliCommand` declares neither fact, so a failed `present` always keeps the validated
+result on stdout.
+
+A CLI that mounts a server's tools through `defineMcpClientConnection` never sees the
+method — every MCP call is a `POST` — so it reads the `readOnlyHint` the server
+publishes. A Stitchkit server publishes it for every `GET` by the rule above
+([MCP → `readOnlyHint`](./mcp-and-agents.md#saying-which-tools-only-read--readonlyhint)),
+so the same command behaves the same over the contract and over MCP. The hint is the
+server's word: a server that labels a write as read-only makes the CLI withhold that
+write's result on a refused view, and repeating the command repeats the effect.
+
+CLI argument errors detected before execution still exit with `2`
 and have no successful result to preserve.
 
 ## Named profiles

package/llms/server.2.txt

@@ -507,3 +507,51 @@ is simply never emitted, so nothing about a hidden endpoint leaks.
 const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind auth
 const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
 ```
+
+### Security schemes — `security`
+
+A generic client reads the spec to learn how to authenticate, and a scope name
+alone does not tell it which header to send. Pass `security` to describe that in
+standard OpenAPI terms: named schemes become `components.securitySchemes`, and
+every protected operation gets a `security` requirement. It is keyed by the
+scopes your contracts already declare, so there is no second list of which
+endpoint is protected:
+
+```ts
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+  security: {
+    schemes: {
+      apiKey: { type: 'http', scheme: 'bearer', description: 'An account API key' },
+    },
+    // Each protected scope → the schemes that satisfy it, any one of them.
+    scopes: { account: ['apiKey'] },
+  },
+})
+```
+
+A scheme is `{ type: 'http', scheme: 'bearer' | 'basic' }` or
+`{ type: 'apiKey', in: 'header' | 'query' | 'cookie', name }` (a session cookie
+is the `cookie` form). An operation is described by the scope the auth hook
+checks it under:
+
+| The operation's scope | In the document |
+|---|---|
+| `'public'` | no `security`, no 401/403 |
+| listed in `scopes` with schemes | `security: [{ apiKey: [] }, …]` and 401/403 |
+| listed with an empty list — a custom scope whose rule is `'public'` | no `security`, no 401/403 |
+| not listed | generation throws, naming the operation |
+| none of its own | read as `defaultScope` — pass the same value as `createAuthHook({ defaultScope })` |
+
+Generation refuses a protected scope it cannot describe instead of emitting the
+operation as open — a client would otherwise call it without a credential. Only
+the operations the document advertises need a mapping: a method `includeMethod`
+filters out is never checked. A scheme `scopes` names but `schemes` does not
+declare, and an entry for `'public'`, are refused the same way.
+
+The metadata describes your policy; it does not enforce it. The auth hook is
+still the only gate, and removing `security` changes the document, never a
+401 or 403. Credential values never belong here: describe where the key goes,
+not what it is.

package/llms/server.5.txt

@@ -236,6 +236,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
 | `OpenApiDocument` | _type_ | the generated document |
 | `OpenApiInfo` | _type_ | the spec `info` block |
+| `OpenApiSecurity` | _type_ | `OpenApiConfig.security` — named schemes and the schemes each protected scope accepts — [guide](../guide/server.md#security-schemes--security) |
+| `OpenApiSecurityScheme` | _type_ | one way a caller presents its credential: HTTP bearer or basic, or an API key in a header, query or cookie |
 | `OpenApiServer` | _type_ | a spec `servers` entry |
 
 ---

package/llms/stitchkit.txt

@@ -92,13 +92,13 @@ own, recorded as an ADR.
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 66 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 67 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 66 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 67 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -110,7 +110,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 66 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 67 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/tools.2.txt

@@ -13,6 +13,115 @@ Parts of this slice:
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
 ==============================================================================
 
+## OAuth 2.1 — a native remote connector
+
+A remote MCP server is connectable from Claude (Desktop / web "custom
+connector") only through the MCP authorization spec: OAuth 2.1 with PKCE, plus
+the discovery documents (RFC 9728 / 8414), Client ID Metadata Documents (CIMD)
+and resource indicators (RFC 8707). A Bearer-only server returns a
+bare `401` and the connector never establishes.
+
+stitchkit ships the OAuth **protocol mechanics**; the app supplies only
+**identity and storage**. Three pieces wire it together:
+
+```ts
+import { mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
+import { createServer } from 'stitchkit/server'
+
+const resource = 'https://api.example.com/mcp'
+const issuer = 'https://api.example.com'
+
+// 1. Resource server — the 401 now points at the metadata.
+const mcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: resolveOAuthToken,        // validate the Bearer JWT (verifyJwt + audience)
+  services,
+  protectedResource: { resource, authorizationServers: [issuer] },
+})
+
+// 2. Authorization server — CIMD, /authorize (PKCE), /token.
+const oauthRoutes = mountOAuthProvider({
+  issuer,
+  resource,
+  signingSecret: env.OAUTH_SECRET,
+  clientRegistration: {
+    preRegistered: { get: getFirstPartyClient },
+    // CIMD is enabled with secure defaults; DCR remains disabled.
+  },
+  codes, refreshTokens,           // your stores (DB or in-memory)
+  authorizeUser,                  // → { userId, approvedScopes } | Response
+})
+
+createServer({
+  services,
+  rawRoutes: [
+    createMcpHttpRoute({ path: '/mcp', handler: mcp }),
+    oauthProtectedResourceRoute({ resource, authorizationServers: [issuer] }),
+    ...oauthRoutes,
+  ],
+})
+```
+
+Access tokens are signed HS256 JWTs (`signJwt`) whose `aud` is the resource and
+whose `iss` is the issuer — validate both in `auth` with
+`verifyJwt(token, secret, { audience: resource, issuer })`. `authorizeUser` is
+where the app authenticates the user (reuse an existing session) and records
+consent; return `{ userId, approvedScopes }`, where approved scopes are a subset
+of the requested/supported values, or a `Response` to redirect the browser to a
+login page first. The AS and resource server can co-locate or live
+on separate origins. See
+[ADR 0015](../decisions/0015-oauth-resource-server.md).
+
+Client resolution is deterministic: exact pre-registered client, then an HTTPS
+URL client id resolved as CIMD, then explicitly enabled DCR. CIMD is on by
+default; DCR is off unless `clientRegistration.dcr` supplies both `register` and
+`get`. A CIMD-only deployment therefore exposes neither `/register` nor a
+`registration_endpoint`. The metadata document must declare a `client_id` that
+exactly equals its URL, explicit redirect URIs and
+`token_endpoint_auth_method: 'none'`.
+
+The token endpoint and `/register` read at most 64 KiB of a request body, or
+`maxRequestBodyBytes` when you set it; a larger one is answered `413` with
+`invalid_request` and the rest is not read.
+
+The production fetcher rejects credentials, fragments, non-HTTPS URLs and
+private/reserved targets. Every redirect is DNS-resolved and IP-pinned again;
+timeouts, redirect count and body size are bounded. Its bounded cache respects
+`Cache-Control` (including `no-store`/`no-cache`), `Age`, `Expires`, `ETag` and
+`Last-Modified`, coalesces concurrent misses and reports sanitized cache events;
+invalid or unavailable identity receives only a short fail-closed cache entry.
+
+Resolution itself is rate-limited on two levels (`CimdCachePolicy`):
+`maxResolutionsPerClient` (default 10) bounds ONE `client_id` per
+`resolutionWindowMs` window (default 60 s) — a client whose document disables
+caching burns its own budget, not the server's — while `maxResolutions`
+(default 120) caps the server-wide outbound rate as the flood backstop.
+Positive and negative cache entries keep separate pools of `maxEntries` each,
+so a flood of unresolvable ids cannot evict warmed clients and a burst of
+successes cannot reset a failing client's backoff.
+
+### Authorization hardening (MCP 2026-07-28)
+
+- **`iss` on every authorization response (RFC 9207, SEP-2468).** Success *and*
+  error redirects carry `iss`, and the AS metadata advertises
+  `authorization_response_iss_parameter_supported: true`. A client that talks to
+  several authorization servers validates `iss` before redeeming the code, which
+  closes the **mix-up attack** — an attacker's server cannot pass its response
+  off as this issuer's. Additive on the wire: a client that ignores `iss` is
+  unaffected.
+- **`application_type` on registration (SEP-837).** A client may declare
+  `"native"` (desktop / CLI) or `"web"` in its DCR body. A **native** client may
+  register an `http` loopback redirect (`http://127.0.0.1:…`, RFC 8252 §7.3); a
+  **web** client is held to `https` only — that mismatch is the usual cause of
+  the `redirect_uri` rejection CLI clients hit. Omit the field and registration
+  behaves exactly as before (loopback allowed); an unknown value is rejected
+  rather than silently defaulted.
+
+> Dynamic Client Registration is an explicit interoperability mode, not the
+> default. Enabling it changes public discovery and adds `/register`; keep it off
+> unless a client that cannot publish CIMD requires it.
+
 ## Proxying a remote API — `implementRemote`
 
 `implement` binds a contract to local handlers. `implementRemote` binds it to a

package/llms/tools.txt

@@ -317,6 +317,36 @@ schema and annotations, and nothing else — it moves when the contract moves an
 not when a handler does. Raw SDK registrations stay consumer-owned and are
 outside it.
 
+### Saying which tools only read — `readOnlyHint`
+
+A host reads a tool's `annotations` to group tools and to choose permission
+defaults, and a CLI mounted over this surface reads them to decide what a
+refused view may withhold ([CLI → views](./cli.md#aggregate-views)). The server publishes the
+annotations the tool declared, and states `readOnlyHint: true` for a read that
+declared none:
+
+| The tool | Published `readOnlyHint` |
+|---|---|
+| declares `readOnlyHint`, either way | as declared |
+| `GET` with no `readOnlyHint` | `true` |
+| `GET` declaring `destructiveHint: true` and no `readOnlyHint` | none |
+| any other method with no `readOnlyHint` | none |
+
+A runtime tool follows the same rule by its `identity.method`. A raw SDK
+registration (`mountWait`, `mountViewFile` and the like) publishes only what it
+passes. The catalog digest hashes the published annotations, so it moves once
+when a server starts publishing the derived hint.
+
+> **A `GET` with an effect must say so.** Hosts may run a tool that publishes
+> `readOnlyHint: true` without asking. An endpoint that changes something on
+> `GET` — marks as seen, rotates a token — declares
+> `tool: { annotations: { readOnlyHint: false } }`.
+
+A client connection (`defineMcpClientConnection`) carries the hints a server
+published onto the tools it mounts, field by field: a hint of the wrong type is
+dropped and the tool stays. The mounted tool is as read-only as its server says
+it is, and a surface that re-publishes mounted tools passes those hints on.
+
 ### Shaping arguments before validation — `beforeToolCall`
 
 `beforeToolCall` sees the arguments as they arrived and may **replace** them:
@@ -498,7 +528,10 @@ render: async (ctx) => {
 
 `reportProgress` is present on every **tool** call — MCP, agent and CLI — so a
 handler never branches on transport, and it does nothing wherever nobody is
-listening. It is absent on the HTTP transport, which has no channel for it, so a
+listening. Under the agent runtime somebody is: each report becomes a transient
+`tool-progress` event of the run, so the person watching the agent sees the
+stage while the model still reads only the tool's result (see
+[Agent runtime → events](./agent-runtime.md)). It is absent on the HTTP transport, which has no channel for it, so a
 handler that also serves HTTP writes `ctx.reportProgress?.(…)`. It never throws and never
 rejects: a message about work must not be able to kill the work it describes, so
 a refused notification leaves the host exactly where a host that never asked for
@@ -862,112 +895,3 @@ OS default disposition instead of reporting a fictional forced result.
 Both transports build the server through the shared `buildMcpServer` — same
 contract/runtime pipeline, same surface selection, context, hooks, raw escape
 hatch and instructions.
-
-## OAuth 2.1 — a native remote connector
-
-A remote MCP server is connectable from Claude (Desktop / web "custom
-connector") only through the MCP authorization spec: OAuth 2.1 with PKCE, plus
-the discovery documents (RFC 9728 / 8414), Client ID Metadata Documents (CIMD)
-and resource indicators (RFC 8707). A Bearer-only server returns a
-bare `401` and the connector never establishes.
-
-stitchkit ships the OAuth **protocol mechanics**; the app supplies only
-**identity and storage**. Three pieces wire it together:
-
-```ts
-import { mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
-import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
-import { createServer } from 'stitchkit/server'
-
-const resource = 'https://api.example.com/mcp'
-const issuer = 'https://api.example.com'
-
-// 1. Resource server — the 401 now points at the metadata.
-const mcp = createMcpHandler({
-  serverInfo: { name: 'my-app', version: '1.0.0' },
-  auth: resolveOAuthToken,        // validate the Bearer JWT (verifyJwt + audience)
-  services,
-  protectedResource: { resource, authorizationServers: [issuer] },
-})
-
-// 2. Authorization server — CIMD, /authorize (PKCE), /token.
-const oauthRoutes = mountOAuthProvider({
-  issuer,
-  resource,
-  signingSecret: env.OAUTH_SECRET,
-  clientRegistration: {
-    preRegistered: { get: getFirstPartyClient },
-    // CIMD is enabled with secure defaults; DCR remains disabled.
-  },
-  codes, refreshTokens,           // your stores (DB or in-memory)
-  authorizeUser,                  // → { userId, approvedScopes } | Response
-})
-
-createServer({
-  services,
-  rawRoutes: [
-    createMcpHttpRoute({ path: '/mcp', handler: mcp }),
-    oauthProtectedResourceRoute({ resource, authorizationServers: [issuer] }),
-    ...oauthRoutes,
-  ],
-})
-```
-
-Access tokens are signed HS256 JWTs (`signJwt`) whose `aud` is the resource and
-whose `iss` is the issuer — validate both in `auth` with
-`verifyJwt(token, secret, { audience: resource, issuer })`. `authorizeUser` is
-where the app authenticates the user (reuse an existing session) and records
-consent; return `{ userId, approvedScopes }`, where approved scopes are a subset
-of the requested/supported values, or a `Response` to redirect the browser to a
-login page first. The AS and resource server can co-locate or live
-on separate origins. See
-[ADR 0015](../decisions/0015-oauth-resource-server.md).
-
-Client resolution is deterministic: exact pre-registered client, then an HTTPS
-URL client id resolved as CIMD, then explicitly enabled DCR. CIMD is on by
-default; DCR is off unless `clientRegistration.dcr` supplies both `register` and
-`get`. A CIMD-only deployment therefore exposes neither `/register` nor a
-`registration_endpoint`. The metadata document must declare a `client_id` that
-exactly equals its URL, explicit redirect URIs and
-`token_endpoint_auth_method: 'none'`.
-
-The token endpoint and `/register` read at most 64 KiB of a request body, or
-`maxRequestBodyBytes` when you set it; a larger one is answered `413` with
-`invalid_request` and the rest is not read.
-
-The production fetcher rejects credentials, fragments, non-HTTPS URLs and
-private/reserved targets. Every redirect is DNS-resolved and IP-pinned again;
-timeouts, redirect count and body size are bounded. Its bounded cache respects
-`Cache-Control` (including `no-store`/`no-cache`), `Age`, `Expires`, `ETag` and
-`Last-Modified`, coalesces concurrent misses and reports sanitized cache events;
-invalid or unavailable identity receives only a short fail-closed cache entry.
-
-Resolution itself is rate-limited on two levels (`CimdCachePolicy`):
-`maxResolutionsPerClient` (default 10) bounds ONE `client_id` per
-`resolutionWindowMs` window (default 60 s) — a client whose document disables
-caching burns its own budget, not the server's — while `maxResolutions`
-(default 120) caps the server-wide outbound rate as the flood backstop.
-Positive and negative cache entries keep separate pools of `maxEntries` each,
-so a flood of unresolvable ids cannot evict warmed clients and a burst of
-successes cannot reset a failing client's backoff.
-
-### Authorization hardening (MCP 2026-07-28)
-
-- **`iss` on every authorization response (RFC 9207, SEP-2468).** Success *and*
-  error redirects carry `iss`, and the AS metadata advertises
-  `authorization_response_iss_parameter_supported: true`. A client that talks to
-  several authorization servers validates `iss` before redeeming the code, which
-  closes the **mix-up attack** — an attacker's server cannot pass its response
-  off as this issuer's. Additive on the wire: a client that ignores `iss` is
-  unaffected.
-- **`application_type` on registration (SEP-837).** A client may declare
-  `"native"` (desktop / CLI) or `"web"` in its DCR body. A **native** client may
-  register an `http` loopback redirect (`http://127.0.0.1:…`, RFC 8252 §7.3); a
-  **web** client is held to `https` only — that mismatch is the usual cause of
-  the `redirect_uri` rejection CLI clients hit. Omit the field and registration
-  behaves exactly as before (loopback allowed); an unknown value is rejected
-  rather than silently defaulted.
-
-> Dynamic Client Registration is an explicit interoperability mode, not the
-> default. Enabling it changes public discovery and adds `/register`; keep it off
-> unless a client that cannot publish CIMD requires it.

package/llms/{upgrading-0.106.0-0.121.0.txt → upgrading-0.106.0-0.122.0.txt}

@@ -1,14 +1,42 @@
-# Upgrading 0.106.0 → 0.121.0 — stitchkit docs slice
+# Upgrading 0.106.0 → 0.122.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.106.0 → 0.121.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.106.0 → 0.122.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.106.0 → 0.121.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.106.0 → 0.122.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.122.0
+
+### read-view-refusal
+
+**Who must act:** scripts and agents that read stdout after a managed CLI command exits with
+`CLI_PRESENTATION_FAILED` (`8` by default) when that command is a `GET` endpoint or a tool
+declaring `annotations.readOnlyHint: true`. Commands with an effect and native
+`defineCliCommand` presenters change nothing.
+
+A read no longer prints its complete result when the requested view is refused; stdout is
+empty and the diagnostic carries `details.resultOnStdout: false`.
+
+```sh
+# before: the full list arrived on stdout beside the diagnostic
+app user_list --table id,nosuchcolumn > users.json   # exit 8, users.json holds every record
+
+# after: repeat the read with a field the diagnostic names
+app user_list --table id,nosuchcolumn                # exit 8, stdout empty
+app user_list --table id,name
+```
+
+A `GET` endpoint whose call has an effect that must not be repeated declares it, and keeps
+its result on stdout:
+
+```ts
+tool: { name: 'token_rotate', annotations: { readOnlyHint: false } }
+```
+
 ## Released migration: 0.121.0
 
 ### bounded-coding-search

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.106.0 → 0.121.0: `llms/upgrading-0.106.0-0.121.0.txt`
+- 0.106.0 → 0.122.0: `llms/upgrading-0.106.0-0.122.0.txt`
 - 0.96.0 → 0.105.0: `llms/upgrading-0.96.0-0.105.0.txt`
 - 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
 - 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`