stitchkit 0.122.0 → 0.122.2

package/llms/cli.txt

@@ -718,9 +718,18 @@ and `details.resultOnStdout` states which case occurred:
 | 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` 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.
+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.

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:
@@ -865,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-full.txt

@@ -4182,6 +4182,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:
@@ -5770,7 +5800,11 @@ Selection is a versioned receipt in the ordinary durable tool-result history.
 The latest valid same-run search replaces the earlier selection; parallel
 searches in one step merge in call order. Recovery reconstructs it, while a
 different run or finite surface cannot inherit it. Known inactive calls take a
-recoverable `SEARCH_REQUIRED` search round; unknown names still fail.
+recoverable `SEARCH_REQUIRED` search round; unknown names still fail. The
+runtime marks that round with `reason: 'inactive_call'` beside the exact tool
+name. The field is the runtime's to write; a model that sets it anyway gets
+the same `SEARCH_REQUIRED` answer with an exact name, and with a query in words
+the field is ignored and the query is ranked as usual.
 
 Every ceiling is required. `maxSchemaBytes` measures UTF-8 bytes over canonical
 name, description and presentation schema. It is useful for before/after
@@ -10847,9 +10881,18 @@ and `details.resultOnStdout` states which case occurred:
 | 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` 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.
+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.

package/llms.txt

@@ -14,21 +14,21 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.7 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 22.7 KB
 - **stitchkit/react/keyboard/testing**: [llms/react-keyboard-testing.txt](llms/react-keyboard-testing.txt) 1.9 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 47.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 30.5 KB → [llms/tools.3.txt](llms/tools.3.txt) 21.0 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 43.2 KB → [llms/tools.2.txt](llms/tools.2.txt) 35.7 KB → [llms/tools.3.txt](llms/tools.3.txt) 21.0 KB
 - **stitchkit/tools/mcp**: [llms/tools-mcp.txt](llms/tools-mcp.txt) 6.6 KB
 - **stitchkit/tools/agent**: [llms/tools-agent.txt](llms/tools-agent.txt) 1.1 KB
 - **stitchkit/tools/toolkit**: [llms/tools-toolkit.txt](llms/tools-toolkit.txt) 0.9 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.9 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 37.2 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 37.8 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 33.8 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 13.2 KB
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 23.1 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 23.5 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 47.6 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 43.3 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 45.1 KB → [llms/agent-runtime.4.txt](llms/agent-runtime.4.txt) 11.7 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 5.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 44.1 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 42.5 KB → [llms/agent-runtime.4.txt](llms/agent-runtime.4.txt) 45.2 KB → [llms/agent-runtime.5.txt](llms/agent-runtime.5.txt) 11.8 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 11.0 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 5.0 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.122.0",
+  "version": "0.122.2",
   "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",

package/dist/tools/cli/repeatable-read.d.ts

@@ -1,9 +0,0 @@
-import type { OperationIdentity } from '../../server/types.js';
-/**
- * Whether calling the operation again returns its answer without a new effect.
- *
- * The declared `readOnlyHint` decides in either direction; without one, `GET` is
- * the contract's own statement that the endpoint reads.
- */
-export declare function isRepeatableRead(operation: Pick<OperationIdentity, 'method' | 'annotations'>): boolean;
-//# sourceMappingURL=repeatable-read.d.ts.map

package/dist/tools/cli/repeatable-read.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"repeatable-read.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/repeatable-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,aAAa,CAAC,GAC3D,OAAO,CAET"}