stitchkit 0.122.0 → 0.122.1

package/CHANGELOG.md

@@ -15,6 +15,27 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.122.1] - 2026-11-10
+
+### Fixed
+
+- `stitchkit/tools/mcp` — the MCP server publishes `readOnlyHint: true` for a `GET` tool that
+  declared no `readOnlyHint`; it published only declared annotations, so a read was
+  indistinguishable from a write to every MCP client. A declared `readOnlyHint` is published as
+  written, and a `GET` declaring `destructiveHint: true` gets none. The catalog digest hashes the
+  published annotations and moves once on upgrade. A `GET` endpoint with an effect must declare
+  `readOnlyHint: false`: a host may run a read-only tool without asking. → ADR 0287
+  **Affects:** `stitchkit/tools/mcp` behaviour
+- `stitchkit/tools/connections` — `defineMcpClientConnection` carries the annotations a server
+  published onto the tools it mounts; it dropped them, so a CLI built over an MCP surface printed
+  a read's complete result on a refused view (`--table` with an unknown column) while the same
+  command over the contract printed nothing. 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. → ADR 0287
+  **Affects:** `stitchkit/tools/connections` behaviour
+- `stitchkit/cli` — a `GET` command declaring `destructiveHint: true` without `readOnlyHint`
+  keeps its result on stdout after a refused view; it was treated as a read. → ADR 0287
+  **Affects:** `stitchkit/cli` behaviour
+
 ## [0.122.0] - 2026-11-10
 
 ### ⚠️ Breaking changes

package/dist/entrypoints/cli.js

@@ -16,13 +16,14 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-v8yqk4w7.js";
+} from "../index-aswegq1r.js";
 import"../index-k42ckyzx.js";
 import"../index-ct75c3at.js";
 import"../index-x4p3kw1p.js";
 import"../index-s3yxw6kt.js";
 import"../index-69t14s4a.js";
 import"../index-ycqhyars.js";
+import"../index-332d0m9g.js";
 import"../index-m5m9rmvt.js";
 import {
   CliBuildSignatureSchema2,

package/dist/entrypoints/tools/connections.js

@@ -1,3 +1,6 @@
+import {
+  readDiscoveredToolAnnotations
+} from "../../index-332d0m9g.js";
 import"../../index-69t14s4a.js";
 import"../../index-ct75c3at.js";
 import {
@@ -919,6 +922,7 @@ async function mountMcpConnection(connection, instanceId, onSkipped) {
       name,
       description,
       identity: { serviceName: connection.name, action: name, method: "POST" },
+      ...tool.annotations && { annotations: tool.annotations },
       ...connection.transports && { transports: connection.transports },
       input,
       output: z2.unknown(),
@@ -945,10 +949,12 @@ function readDiscoveredTools(listed, connectionName) {
   for (const raw of listed.tools) {
     if (!isRecord(raw) || typeof raw.name !== "string")
       continue;
+    const annotations = readDiscoveredToolAnnotations(raw.annotations);
     tools.push({
       name: raw.name,
       ...typeof raw.description === "string" && { description: raw.description },
-      ...isRecord(raw.inputSchema) && { inputSchema: raw.inputSchema }
+      ...isRecord(raw.inputSchema) && { inputSchema: raw.inputSchema },
+      ...annotations && { annotations }
     });
   }
   return tools;

package/dist/entrypoints/tools/mcp.js

@@ -1,4 +1,5 @@
 import"../../index-ct75c3at.js";
+import"../../index-332d0m9g.js";
 import"../../index-k42ckyzx.js";
 import"../../index-dsa676h8.js";
 import"../../index-rbzq0q16.js";
@@ -20,7 +21,7 @@ import {
   createMcpHandler2,
   createMcpHttpRoute2,
   createStdioMcpServer2
-} from "../../index-knmnj11j.js";
+} from "../../index-y6ye582c.js";
 import {
   DEFAULT_PROCESS_SIGNALS,
   defaultSignalSource,

package/dist/entrypoints/tools/toolkit.js

@@ -11,14 +11,15 @@ import {
 } from "../../index-1fyea34p.js";
 import {
   createCli2
-} from "../../index-v8yqk4w7.js";
+} from "../../index-aswegq1r.js";
+import"../../index-332d0m9g.js";
 import"../../index-m5m9rmvt.js";
 import {
   mountMcp2,
   buildMcpServer2,
   createMcpHandler2,
   createStdioMcpServer2
-} from "../../index-knmnj11j.js";
+} from "../../index-y6ye582c.js";
 import"../../index-aqmadanx.js";
 import"../../index-eeahxwvg.js";
 import"../../index-ff39f9dr.js";

package/dist/index-332d0m9g.js

@@ -0,0 +1,37 @@
+// src/tools/read-operation.ts
+import { z } from "zod";
+function isRepeatableRead(operation) {
+  const declared = operation.annotations;
+  if (declared?.readOnlyHint !== undefined)
+    return declared.readOnlyHint;
+  return operation.method === "GET" && declared?.destructiveHint !== true;
+}
+function publishedToolAnnotations(operation) {
+  const declared = operation.annotations;
+  if (declared?.readOnlyHint !== undefined || !isRepeatableRead(operation))
+    return declared;
+  return { ...declared, readOnlyHint: true };
+}
+var DiscoveredToolAnnotationsSchema = z.object({
+  title: z.string().optional().catch(undefined),
+  readOnlyHint: z.boolean().optional().catch(undefined),
+  destructiveHint: z.boolean().optional().catch(undefined),
+  idempotentHint: z.boolean().optional().catch(undefined),
+  openWorldHint: z.boolean().optional().catch(undefined)
+});
+function readDiscoveredToolAnnotations(raw) {
+  const parsed = DiscoveredToolAnnotationsSchema.safeParse(raw);
+  if (!parsed.success)
+    return;
+  const { title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint } = parsed.data;
+  const annotations = {
+    ...title !== undefined && { title },
+    ...readOnlyHint !== undefined && { readOnlyHint },
+    ...destructiveHint !== undefined && { destructiveHint },
+    ...idempotentHint !== undefined && { idempotentHint },
+    ...openWorldHint !== undefined && { openWorldHint }
+  };
+  return Object.keys(annotations).length > 0 ? annotations : undefined;
+}
+
+export { isRepeatableRead, publishedToolAnnotations, readDiscoveredToolAnnotations };

package/dist/{index-v8yqk4w7.js → index-aswegq1r.js}

@@ -23,6 +23,9 @@ import {
   createToolRunner,
   formatToolError
 } from "./index-ycqhyars.js";
+import {
+  isRepeatableRead
+} from "./index-332d0m9g.js";
 import {
   writeContainedFile
 } from "./index-aqmadanx.js";
@@ -1782,11 +1785,6 @@ async function prepareInvocation(command, commandArgv, descriptor, config, readS
   return { ok: true, toolArgs, options };
 }
 
-// src/tools/cli/repeatable-read.ts
-function isRepeatableRead(operation) {
-  return operation.annotations?.readOnlyHint ?? operation.method === "GET";
-}
-
 // src/tools/cli/session.ts
 function nativeDescriptor(definition) {
   return {

package/dist/{index-knmnj11j.js → index-y6ye582c.js}

@@ -1,6 +1,9 @@
 import {
   toJsonSchema
 } from "./index-ct75c3at.js";
+import {
+  publishedToolAnnotations
+} from "./index-332d0m9g.js";
 import {
   toolSurfaceOutputSchema,
   staticInputRounds,
@@ -86,7 +89,7 @@ function toolFingerprint(descriptor) {
     description: mountable.method.desc,
     input: descriptor.inputSchema,
     output: descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema, "output", "any") : null,
-    annotations: mountable.method.annotations ?? null
+    annotations: publishedToolAnnotations(mountable.method) ?? null
   };
 }
 function mcpCatalogStamp(surface) {
@@ -556,8 +559,9 @@ function registerMcpTool(server, presentation, descriptor, config) {
   };
   if (descriptor.outputSchema)
     toolConfig.outputSchema = descriptor.outputSchema;
-  if (presentation.annotations)
-    toolConfig.annotations = presentation.annotations;
+  const annotations = publishedToolAnnotations(mountable.method);
+  if (annotations)
+    toolConfig.annotations = annotations;
   if (presentation.ui) {
     toolConfig._meta = {
       ui: presentation.ui,
@@ -665,7 +669,6 @@ function mountPreparedRuntimeMcp(server, tools, config) {
     registerMcpTool(server, {
       name: definition.name,
       description: definition.description,
-      annotations: definition.annotations,
       ui: definition.ui,
       ...present && { present }
     }, descriptor, {
@@ -716,7 +719,6 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
     registerMcpTool(mcpServer, {
       name,
       description: method.desc,
-      annotations: method.annotations,
       ui: method.ui
     }, descriptor, {
       runTool,

package/dist/tools/connections/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAIhF,OAAO,EACL,KAAK,0BAA0B,EAIhC,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAQlE,gEAAgE;AAChE,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAsElC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAIhF,OAAO,EACL,KAAK,0BAA0B,EAIhC,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAUlE,gEAAgE;AAChE,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAyElC"}

package/dist/tools/mcp/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAmB,MAAM,WAAW,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,eAAe,CAclF;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAQzE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACvF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACjF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/catalog.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAmB,MAAM,WAAW,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,eAAe,CAclF;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAQzE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACvF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACjF,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAGT"}

package/dist/tools/mcp/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/mount.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/mount.ts"],"names":[],"mappings":"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"}

package/dist/tools/mcp/register.d.ts

@@ -1,5 +1,5 @@
 import { type CallToolResult, type McpServer } from '@modelcontextprotocol/server';
-import type { EndpointToolAnnotations, EndpointUiMeta } from '../../contract/tool-options.js';
+import type { EndpointUiMeta } from '../../contract/tool-options.js';
 import type { ToolExecutionOptions } from '../execute.js';
 import type { ToolCallHooks } from '../execute-hooks.js';
 import { type ToolResult } from '../execute-result.js';
@@ -11,7 +11,6 @@ import { type McpRoundRuntime } from './round.js';
 export interface McpToolPresentation {
     name: string;
     description: string;
-    annotations?: EndpointToolAnnotations;
     ui?: EndpointUiMeta;
     /** A runtime tool's own MCP answer, built from its validated output. */
     present?(data: unknown): unknown | Promise<unknown>;

package/dist/tools/mcp/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/register.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,mBAAmB,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,EAAE,KAAK,eAAe,EAA0C,MAAM,WAAW,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,SAAS,CAAC;AAIhE,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,wEAAwE;IACxE,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,KACnD,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,eAAe,CAAC,YAAY,CAAC,EACnC,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,mBAAmB,EACjC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,yBAAyB,GAChC,IAAI,CA8HN"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/register.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAA2B,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,mBAAmB,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EAAE,KAAK,eAAe,EAA0C,MAAM,WAAW,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,KAAK,eAAe,EAAmB,MAAM,SAAS,CAAC;AAIhE,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,wEAAwE;IACxE,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,KACnD,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,eAAe,CAAC,YAAY,CAAC,EACnC,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,YAAY,EAAE,mBAAmB,EACjC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,yBAAyB,GAChC,IAAI,CAiIN"}

package/dist/tools/mcp/runtime-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/runtime-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,UAAU,sBAAsB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,EACxD,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;CACrB;AAaD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAkCN"}
+{"version":3,"file":"runtime-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp/runtime-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,UAAU,sBAAsB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC,YAAY,CAAC,EACxD,QAAQ,EAAE,MAAM,KACb,cAAc,CAAC;CACrB;AAaD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAiCN"}

package/dist/tools/read-operation.d.ts

@@ -0,0 +1,21 @@
+import type { EndpointToolAnnotations } from '../contract/tool-options.js';
+import type { OperationIdentity } from '../server/types.js';
+type Operation = Pick<OperationIdentity, 'method' | 'annotations'>;
+/**
+ * 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 — unless it declares
+ * `destructiveHint: true`, which says the opposite in the same breath.
+ */
+export declare function isRepeatableRead(operation: Operation): boolean;
+/**
+ * The annotations a tool surface publishes for the operation: the declared
+ * ones, with `readOnlyHint: true` stated for a read that declared none. A
+ * declared `readOnlyHint`, either way, is published as written.
+ */
+export declare function publishedToolAnnotations(operation: Operation): EndpointToolAnnotations | undefined;
+/** The hints another MCP server published for one of its tools, or `undefined` when it gave none. */
+export declare function readDiscoveredToolAnnotations(raw: unknown): EndpointToolAnnotations | undefined;
+export {};
+//# sourceMappingURL=read-operation.d.ts.map

package/dist/tools/read-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-operation.d.ts","sourceRoot":"","sources":["../../src/tools/read-operation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,KAAK,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,aAAa,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAI9D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,GACnB,uBAAuB,GAAG,SAAS,CAIrC;AAeD,qGAAqG;AACrG,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,GACX,uBAAuB,GAAG,SAAS,CAYrC"}

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:
@@ -10847,9 +10877,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,14 +14,14 @@ 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

package/package.json

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