stitchkit 0.121.0 → 0.122.0

package/dist/entrypoints/server.js

@@ -1449,6 +1449,66 @@ function createTrustFence(config) {
     check
   };
 }
+// src/server/openapi-security.ts
+import { z as z2 } from "zod";
+var SchemeNameSchema = z2.string().regex(/^[a-zA-Z0-9._-]+$/, 'a scheme name may hold only letters, digits, ".", "_" and "-"');
+var described = { description: z2.string().min(1).optional() };
+var OpenApiSecuritySchemeSchema = z2.union([
+  z2.strictObject({
+    type: z2.literal("http"),
+    scheme: z2.literal("bearer"),
+    bearerFormat: z2.string().min(1).optional(),
+    ...described
+  }),
+  z2.strictObject({ type: z2.literal("http"), scheme: z2.literal("basic"), ...described }),
+  z2.strictObject({
+    type: z2.literal("apiKey"),
+    in: z2.enum(["header", "query", "cookie"]),
+    name: z2.string().min(1),
+    ...described
+  })
+]);
+var OpenApiSecuritySchema = z2.strictObject({
+  schemes: z2.record(SchemeNameSchema, OpenApiSecuritySchemeSchema),
+  scopes: z2.record(z2.string().min(1), z2.array(SchemeNameSchema).readonly()),
+  defaultScope: z2.string().min(1).optional()
+});
+var PUBLIC_SCOPE = "public";
+function refuse(message) {
+  throw new Error(`[stitchkit] openapi: ${message}`);
+}
+function planOpenApiSecurity(input) {
+  const parsed = OpenApiSecuritySchema.safeParse(input);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    refuse(`security.${issue?.path.join(".") ?? ""}: ${issue?.message ?? "invalid"}`);
+  }
+  const { schemes, scopes, defaultScope } = parsed.data;
+  if (Object.hasOwn(scopes, PUBLIC_SCOPE)) {
+    refuse(`security.scopes lists "${PUBLIC_SCOPE}", which is open by definition — remove it, or give the protected endpoints their own scope`);
+  }
+  for (const [scope, names] of Object.entries(scopes)) {
+    for (const name of names) {
+      if (!Object.hasOwn(schemes, name)) {
+        refuse(`security.scopes.${scope} names the scheme "${name}", which security.schemes does not declare`);
+      }
+    }
+  }
+  return {
+    schemes,
+    requirement(scope, operation) {
+      const effective = scope ?? defaultScope;
+      if (effective === undefined || effective === PUBLIC_SCOPE)
+        return;
+      const names = Object.hasOwn(scopes, effective) ? scopes[effective] : undefined;
+      if (names === undefined) {
+        refuse(`${operation} has scope "${effective}", but security.scopes names no scheme for it — a protected operation cannot be advertised as open`);
+      }
+      return names.length === 0 ? undefined : names.map((name) => ({ [name]: [] }));
+    }
+  };
+}
+
 // src/server/openapi.ts
 var ERROR_ENVELOPE_SCHEMA = {
   type: "object",
@@ -1484,18 +1544,56 @@ function errorResponse(description) {
     content: { "application/json": { schema: ERROR_ENVELOPE_SCHEMA } }
   };
 }
-function errorResponses(scope) {
+function errorResponses(guarded) {
   const responses = {
     "400": errorResponse("Validation error"),
     "500": errorResponse("Server error")
   };
-  if (scope && scope !== "public") {
+  if (guarded) {
     responses["401"] = errorResponse("Unauthorized");
     responses["403"] = errorResponse("Forbidden");
   }
   return responses;
 }
+function multipartRequestBody(inputSchema, multipart) {
+  const inputJson = safeJson(inputSchema, "input");
+  const baseProps = isRecord(inputJson.properties) ? inputJson.properties : {};
+  const baseRequired = Array.isArray(inputJson.required) ? inputJson.required : [];
+  const fileProperties = {};
+  const requiredFiles = [];
+  for (const [field, policy] of Object.entries(multipart.files)) {
+    const binary = {
+      type: "string",
+      format: "binary",
+      ...policy.maxBytes !== undefined && { maxLength: policy.maxBytes },
+      ...policy.contentTypes !== undefined && {
+        "x-accepted-content-types": policy.contentTypes
+      }
+    };
+    fileProperties[field] = policy.multiple === true ? {
+      type: "array",
+      items: binary,
+      minItems: policy.required === false ? 0 : 1,
+      ...policy.maxFiles !== undefined && { maxItems: policy.maxFiles }
+    } : binary;
+    if (policy.required !== false)
+      requiredFiles.push(field);
+  }
+  return {
+    required: baseRequired.length > 0 || requiredFiles.length > 0,
+    content: {
+      "multipart/form-data": {
+        schema: {
+          type: "object",
+          properties: { ...baseProps, ...fileProperties },
+          required: [...baseRequired, ...requiredFiles]
+        }
+      }
+    }
+  };
+}
 function generateOpenApiDocument(config) {
+  const security = config.security ? planOpenApiSecurity(config.security) : undefined;
   const groups = [
     ...(config.services ?? []).map((service) => ({ pathPrefix: undefined, service })),
     ...(config.groups ?? []).flatMap((group) => group.services.map((service) => ({ pathPrefix: group.pathPrefix, service })))
@@ -1537,7 +1635,9 @@ function generateOpenApiDocument(config) {
           });
         }
       }
-      const responses = { ...errorResponses(method.scope) };
+      const requirement = security?.requirement(method.scope, `${method.method} ${fullPath}`);
+      const guarded = security ? requirement !== undefined : method.scope !== undefined && method.scope !== PUBLIC_SCOPE;
+      const responses = { ...errorResponses(guarded) };
       if (method.rawResponse) {
         responses["200"] = method.method === "HEAD" ? { description: "Headers only" } : {
           description: "Success",
@@ -1579,6 +1679,7 @@ function generateOpenApiDocument(config) {
         "x-stitchkit-has-output": Boolean(method.outputSchema || method.stream),
         ...method.stream && { "x-stitchkit-stream": true },
         ...parameters.length > 0 && { parameters },
+        ...requirement && { security: requirement },
         responses
       };
       if (trailingWildcard) {
@@ -1591,44 +1692,7 @@ function generateOpenApiDocument(config) {
       }
       if (!inputInQuery && (method.inputSchema || method.multipart)) {
         if (method.multipart) {
-          const inputJson = safeJson(method.inputSchema, "input");
-          const baseProps = isRecord(inputJson.properties) ? inputJson.properties : {};
-          const baseRequired = Array.isArray(inputJson.required) ? inputJson.required : [];
-          const fileProperties = {};
-          const requiredFiles = [];
-          for (const [field, policy] of Object.entries(method.multipart.files)) {
-            const binary = {
-              type: "string",
-              format: "binary",
-              ...policy.maxBytes !== undefined && { maxLength: policy.maxBytes },
-              ...policy.contentTypes !== undefined && {
-                "x-accepted-content-types": policy.contentTypes
-              }
-            };
-            fileProperties[field] = policy.multiple === true ? {
-              type: "array",
-              items: binary,
-              minItems: policy.required === false ? 0 : 1,
-              ...policy.maxFiles !== undefined && { maxItems: policy.maxFiles }
-            } : binary;
-            if (policy.required !== false)
-              requiredFiles.push(field);
-          }
-          operation.requestBody = {
-            required: baseRequired.length > 0 || requiredFiles.length > 0,
-            content: {
-              "multipart/form-data": {
-                schema: {
-                  type: "object",
-                  properties: {
-                    ...baseProps,
-                    ...fileProperties
-                  },
-                  required: [...baseRequired, ...requiredFiles]
-                }
-              }
-            }
-          };
+          operation.requestBody = multipartRequestBody(method.inputSchema, method.multipart);
         } else if (method.inputSchema) {
           const required = jsonSchemaFields(safeJson(method.inputSchema, "input")).some((f) => f.required);
           const schema = safeJson(method.inputSchema, "input");
@@ -1647,7 +1711,8 @@ function generateOpenApiDocument(config) {
     openapi: "3.1.0",
     info: config.info,
     ...config.servers && { servers: config.servers },
-    paths
+    paths,
+    ...security && { components: { securitySchemes: { ...security.schemes } } }
   };
 }
 function openApiRoute(path, document) {

package/dist/entrypoints/tools/agent.js

@@ -8,7 +8,7 @@ import"../../index-69t14s4a.js";
 import"../../index-ycqhyars.js";
 import {
   mountAgent2
-} from "../../index-7zwtbak8.js";
+} from "../../index-1fyea34p.js";
 import"../../index-ff39f9dr.js";
 import"../../index-aqwg2dm5.js";
 export {

package/dist/entrypoints/tools/toolkit.js

@@ -8,10 +8,10 @@ import"../../index-69t14s4a.js";
 import"../../index-ycqhyars.js";
 import {
   mountAgent2
-} from "../../index-7zwtbak8.js";
+} from "../../index-1fyea34p.js";
 import {
   createCli2
-} from "../../index-0fra8xvy.js";
+} from "../../index-v8yqk4w7.js";
 import"../../index-m5m9rmvt.js";
 import {
   mountMcp2,

package/dist/{index-7zwtbak8.js → index-1fyea34p.js}

@@ -8,8 +8,8 @@ import {
   formatToolError
 } from "./index-ycqhyars.js";
 import {
-  resolveToolDurability
-} from "./index-sb9dr3tq.js";
+  resolveRuntimeToolCall
+} from "./index-eh71zr32.js";
 import {
   AgentToolError2
 } from "./index-1psbyyhj.js";
@@ -54,8 +54,13 @@ function mountAgent2(services, config = {}) {
     });
     const execute = async (rawArgs, options) => {
       const args = isRecord(rawArgs) ? rawArgs : {};
-      const durability = resolveToolDurability(options.context, options.toolCallId, options.abortSignal) ?? config.durability?.(options.toolCallId, options.abortSignal);
-      const callContext = { signal: options.abortSignal, toolCallId: options.toolCallId };
+      const runtimeCall = resolveRuntimeToolCall(options.context, options.toolCallId, options.abortSignal);
+      const durability = runtimeCall?.durability ?? config.durability?.(options.toolCallId, options.abortSignal);
+      const callContext = {
+        signal: options.abortSignal,
+        toolCallId: options.toolCallId,
+        ...runtimeCall && { reportProgress: runtimeCall.reportProgress }
+      };
       const executeTool = durability ? createToolRunner({
         source: "agent",
         toolSurface: true,

package/dist/{index-4qnzda76.js → index-7qyv50r4.js}

@@ -3,7 +3,7 @@ import {
 } from "./index-qaet40b2.js";
 import {
   AgentRuntimeEventSchema2
-} from "./index-mnkk1ffz.js";
+} from "./index-hs76yzt7.js";
 
 // src/agent-runtime/events.ts
 function createAgentRuntimeEventSink2(config) {

package/dist/{index-qctbzmg9.js → index-am1h8c9v.js}

@@ -16,8 +16,9 @@ import {
   isToolExecutionControlError2
 } from "./index-s3yxw6kt.js";
 import {
+  AGENT_TOOL_PROGRESS_MESSAGE_MAX2,
   agentDurableEventId2
-} from "./index-mnkk1ffz.js";
+} from "./index-hs76yzt7.js";
 import {
   createLocalStepDurability2
 } from "./index-zyc64nbh.js";
@@ -38,8 +39,8 @@ import {
   messageOf
 } from "./index-g149e9pk.js";
 import {
-  createToolDurabilityContext
-} from "./index-sb9dr3tq.js";
+  createRuntimeToolContext
+} from "./index-eh71zr32.js";
 import {
   createMutationQueue
 } from "./index-sykb5ag7.js";
@@ -2597,6 +2598,7 @@ async function acquireRun(dependencies, input) {
     absorbed: new Map,
     eventsSinceCheckpoint: 0,
     sequence: 0,
+    settledToolCalls: new Set,
     terminalReason: "success",
     nonModelUsage: input.acceptedRun.usage,
     modelUsage: undefined,
@@ -2976,6 +2978,7 @@ async function applyToolPart(execution, part) {
       emittedAt: now().toISOString()
     });
   } else if (part.type === "tool-result") {
+    state.settledToolCalls.add(part.toolCallId);
     state.parts.push(AgentMessagePartSchema2.parse({
       type: "tool-result",
       callId: part.toolCallId,
@@ -2993,6 +2996,7 @@ async function applyToolPart(execution, part) {
       emittedAt: now().toISOString()
     });
   } else if (part.type === "tool-error") {
+    state.settledToolCalls.add(part.toolCallId);
     state.internalCause = part.error;
     if (isToolExecutionControlError2(part.error)) {
       await publish({
@@ -3024,6 +3028,7 @@ async function applyToolPart(execution, part) {
       emittedAt: now().toISOString()
     });
   } else if (part.type === "tool-output-denied") {
+    state.settledToolCalls.add(part.toolCallId);
     state.parts.push(AgentMessagePartSchema2.parse({
       type: "tool-result",
       callId: part.toolCallId,
@@ -3194,6 +3199,37 @@ async function applyStreamPart(execution, scope, part) {
   }
 }
 
+// src/agent-runtime/tool-progress.ts
+var TOOL_PROGRESS_MIN_INTERVAL_MS = 250;
+function finite(value) {
+  return value !== undefined && Number.isFinite(value) ? value : undefined;
+}
+function createToolProgressReporter(execution, toolName, callId, signal) {
+  let lastPublishedAt;
+  return async (update) => {
+    if (signal?.aborted || execution.state.settledToolCalls.has(callId))
+      return;
+    const now = execution.dependencies.now();
+    if (lastPublishedAt !== undefined && now.getTime() - lastPublishedAt < TOOL_PROGRESS_MIN_INTERVAL_MS) {
+      return;
+    }
+    lastPublishedAt = now.getTime();
+    const message = update.message?.slice(0, AGENT_TOOL_PROGRESS_MESSAGE_MAX2);
+    const progress = finite(update.progress);
+    const total = finite(update.total);
+    await execution.dependencies.publish({
+      type: "tool-progress",
+      ...transientHead(execution),
+      callId,
+      toolName,
+      ...message !== undefined && { message },
+      ...progress !== undefined && { progress },
+      ...total !== undefined && { total },
+      emittedAt: now.toISOString()
+    });
+  };
+}
+
 // src/agent-runtime/run-model-attempts.ts
 function createStopConditions(execution, turn) {
   const { config, maxSteps } = execution.dependencies;
@@ -3268,10 +3304,30 @@ async function prepareAttemptStep(context, attempt, options) {
   });
   return { ...preparedStep, model };
 }
+function runToolDurability(context, toolName, toolCallId, signal) {
+  const { config } = context.execution.dependencies;
+  const { state } = context.execution;
+  const port = config.durability;
+  if (typeof port === "function")
+    return port({
+      store: config.store,
+      conversationId: state.run.conversationId,
+      runId: state.run.id,
+      toolName,
+      toolCallId,
+      signal
+    });
+  return createLocalStepDurability2({
+    store: config.store,
+    conversationId: state.run.conversationId,
+    runId: JSON.stringify([state.run.id, toolName, toolCallId]),
+    signal
+  });
+}
 function startAttemptStream(context, attempt, stopConditions) {
   const { execution, turn } = context;
   const { config } = execution.dependencies;
-  const { state, idleDeadline, operationLifecycle } = execution;
+  const { idleDeadline, operationLifecycle } = execution;
   const { tools } = turn;
   const attemptSignal = AbortSignal.any([
     execution.executionSignal,
@@ -3280,29 +3336,15 @@ function startAttemptStream(context, attempt, stopConditions) {
   return streamAgentTextBoundary({
     model: turn.selectedModel.model,
     tools,
-    ...config.durability && {
-      toolsContext: Object.fromEntries(Object.keys(tools).map((toolName) => [
-        toolName,
-        createToolDurabilityContext((toolCallId, signal) => {
-          const port = config.durability;
-          if (typeof port === "function")
-            return port({
-              store: config.store,
-              conversationId: state.run.conversationId,
-              runId: state.run.id,
-              toolName,
-              toolCallId,
-              signal
-            });
-          return createLocalStepDurability2({
-            store: config.store,
-            conversationId: state.run.conversationId,
-            runId: JSON.stringify([state.run.id, toolName, toolCallId]),
-            signal
-          });
-        })
-      ]))
-    },
+    toolsContext: Object.fromEntries(Object.entries(tools).filter(([, tool]) => tool.contextSchema === undefined).map(([toolName]) => [
+      toolName,
+      createRuntimeToolContext((toolCallId, signal) => ({
+        ...config.durability && {
+          durability: runToolDurability(context, toolName, toolCallId, signal)
+        },
+        reportProgress: createToolProgressReporter(execution, toolName, toolCallId, signal)
+      }))
+    ])),
     instructions: turn.projection.withCarriedSystem(turn.prompt.instructions),
     messages: turn.history,
     abortSignal: attemptSignal,

package/dist/{index-yt7gyg5x.js → index-b51tzcgh.js}

@@ -9,7 +9,7 @@ import {
   AgentControlRequestSchema2,
   AgentControlResponseSchema2,
   AgentControlDeliverySchema2
-} from "./index-b0w7rbpt.js";
+} from "./index-t05a2ry4.js";
 
 // src/agent-runtime/browser-control-contract.ts
 import { z } from "zod";

package/dist/{index-aw6zahv1.js → index-dqpesdck.js}

@@ -1,10 +1,10 @@
 import {
   AgentControlRequestSchema2,
   AgentControlResponseSchema2
-} from "./index-b0w7rbpt.js";
+} from "./index-t05a2ry4.js";
 import {
   createAgentRuntimeEventSink2
-} from "./index-4qnzda76.js";
+} from "./index-7qyv50r4.js";
 import {
   assertPositiveSafeInteger
 } from "./index-0s4xebbg.js";

package/dist/{index-sb9dr3tq.js → index-eh71zr32.js}

@@ -1,14 +1,14 @@
-// src/tools/durability-context.ts
+// src/tools/runtime-call-context.ts
 var contexts = new WeakMap;
-function createToolDurabilityContext(factory) {
+function createRuntimeToolContext(factory) {
   const context = {};
   contexts.set(context, factory);
   return context;
 }
-function resolveToolDurability(context, callId, signal) {
+function resolveRuntimeToolCall(context, callId, signal) {
   if (typeof context !== "object" || context === null)
     return;
   return contexts.get(context)?.(callId, signal);
 }
 
-export { createToolDurabilityContext, resolveToolDurability };
+export { createRuntimeToolContext, resolveRuntimeToolCall };

package/dist/{index-mnkk1ffz.js → index-hs76yzt7.js}

@@ -86,6 +86,17 @@ var AgentToolStatusEventSchema2 = EventIdentitySchema.extend({
   input: z.json().optional(),
   output: z.json().optional()
 });
+var AGENT_TOOL_PROGRESS_MESSAGE_MAX2 = 280;
+var AgentToolProgressEventSchema2 = EventIdentitySchema.extend({
+  type: z.literal("tool-progress"),
+  runtimeEpoch: z.string().min(1),
+  sequence: z.int().nonnegative(),
+  callId: AgentRecordIdSchema2,
+  toolName: z.string().min(1),
+  message: z.string().max(AGENT_TOOL_PROGRESS_MESSAGE_MAX2).optional(),
+  progress: z.number().finite().optional(),
+  total: z.number().finite().optional()
+});
 var AgentTerminalEventSchema2 = EventIdentitySchema.extend({
   type: z.literal("terminal"),
   eventId: AgentRecordIdSchema2,
@@ -106,6 +117,7 @@ var AgentRuntimeEventSchema2 = z.discriminatedUnion("type", [
   AgentRunStateEventSchema2,
   AgentRunOperationEventSchema2,
   AgentToolStatusEventSchema2,
+  AgentToolProgressEventSchema2,
   AgentTerminalEventSchema2
 ]);
 var AgentRuntimeEventCursorSchema2 = z.object({
@@ -147,4 +159,4 @@ function agentDurableEventId2(type, runId, snapshotVersion) {
   return `${runId}:${type}:${snapshotVersion}`;
 }
 
-export { AgentAdmissionEventSchema2, AgentTransientDeltaEventSchema2, AgentReasoningStartEventSchema2, AgentReasoningDeltaEventSchema2, AgentReasoningEndEventSchema2, AgentAttemptResetEventSchema2, AgentCheckpointEventSchema2, AgentRunStateEventSchema2, AgentRunOperationEventSchema2, AgentToolStatusEventSchema2, AgentTerminalEventSchema2, AgentRuntimeEventSchema2, AgentRuntimeEventCursorSchema2, advanceAgentRuntimeEventCursor2, agentDurableEventId2 };
+export { AgentAdmissionEventSchema2, AgentTransientDeltaEventSchema2, AgentReasoningStartEventSchema2, AgentReasoningDeltaEventSchema2, AgentReasoningEndEventSchema2, AgentAttemptResetEventSchema2, AgentCheckpointEventSchema2, AgentRunStateEventSchema2, AgentRunOperationEventSchema2, AgentToolStatusEventSchema2, AGENT_TOOL_PROGRESS_MESSAGE_MAX2, AgentToolProgressEventSchema2, AgentTerminalEventSchema2, AgentRuntimeEventSchema2, AgentRuntimeEventCursorSchema2, advanceAgentRuntimeEventCursor2, agentDurableEventId2 };

package/dist/{index-b0w7rbpt.js → index-t05a2ry4.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-8kzct1d6.js";
 import {
   AgentRuntimeEventSchema2
-} from "./index-mnkk1ffz.js";
+} from "./index-hs76yzt7.js";
 
 // src/agent-runtime/control-schema.ts
 import { z } from "zod";
@@ -154,6 +154,43 @@ function advanceAgentMultiSessionCursor2(raw, event) {
     }
   };
 }
+var EMPTY_TRANSIENT = { text: "", reasoning: "", tools: {} };
+function nextRunTransient(transient, event) {
+  switch (event.type) {
+    case "assistant-delta":
+      return { ...transient, text: transient.text + event.textDelta };
+    case "reasoning-delta":
+      return { ...transient, reasoning: transient.reasoning + event.textDelta };
+    case "attempt-reset":
+      return EMPTY_TRANSIENT;
+    case "tool-progress": {
+      const { toolName, message, progress, total } = event;
+      return {
+        ...transient,
+        tools: {
+          ...transient.tools,
+          [event.callId]: {
+            toolName,
+            ...message !== undefined && { message },
+            ...progress !== undefined && { progress },
+            ...total !== undefined && { total }
+          }
+        }
+      };
+    }
+    case "tool-status": {
+      if (event.status === "started" || !Object.hasOwn(transient.tools, event.callId)) {
+        return transient;
+      }
+      return {
+        ...transient,
+        tools: Object.fromEntries(Object.entries(transient.tools).filter(([callId]) => callId !== event.callId))
+      };
+    }
+    default:
+      return transient;
+  }
+}
 function createAgentControlView2() {
   return { cursor: { conversations: {} }, conversations: {} };
 }
@@ -199,8 +236,7 @@ function reduceAgentControlEvent2(view, rawEvent) {
       }
     };
   }
-  const transient = current.transientByRun[event.runId] ?? { text: "", reasoning: "" };
-  const nextTransient = event.type === "assistant-delta" ? { ...transient, text: transient.text + event.textDelta } : event.type === "reasoning-delta" ? { ...transient, reasoning: transient.reasoning + event.textDelta } : event.type === "attempt-reset" ? { text: "", reasoning: "" } : transient;
+  const nextTransient = nextRunTransient(current.transientByRun[event.runId] ?? EMPTY_TRANSIENT, event);
   const snapshotStale = durable(event) && current.snapshot?.version !== event.snapshotVersion;
   const transientByRun = event.type === "terminal" ? Object.fromEntries(Object.entries(current.transientByRun).filter(([runId]) => runId !== event.runId)) : { ...current.transientByRun, [event.runId]: nextTransient };
   return {

package/dist/{index-0fra8xvy.js → index-v8yqk4w7.js}

@@ -185,8 +185,16 @@ function emitResult2(result, writers, opts) {
 `);
   return cliExitCode2(result, opts.exitCodes);
 }
+function presentationFailureHint(repeatable, printed) {
+  if (repeatable) {
+    return "The result was not printed: this command only reads. Repeat it with a corrected view.";
+  }
+  return printed ? "The complete, unformatted result is on stdout. Do not repeat the command to recover its result." : "The command returned no result. Do not repeat it.";
+}
 function emitPresentationFailure(result, failure, writers, opts) {
-  emitResult2(result, writers, opts);
+  const printed = !opts.repeatable && result.data !== undefined;
+  if (printed)
+    emitResult2(result, writers, opts);
   return emitResult2({
     ok: false,
     code: "CLI_PRESENTATION_FAILED",
@@ -195,9 +203,10 @@ function emitPresentationFailure(result, failure, writers, opts) {
       message: "The command completed successfully, but its result presentation failed.",
       command: opts.toolName,
       operationSucceeded: true,
+      resultOnStdout: printed,
       cause: formatToolError(failure)
     },
-    hint: "The complete, unformatted result is on stdout. Do not repeat the command to recover its result."
+    hint: presentationFailureHint(opts.repeatable, printed)
   }, writers, { json: opts.json, toolName: opts.toolName, exitCodes: opts.exitCodes });
 }
 
@@ -1773,6 +1782,11 @@ 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 {
@@ -2225,7 +2239,7 @@ async function runManagedCommand(session, route, command, managed) {
     toolArgs,
     options
   });
-  return emitManagedResult(session, command, result, options);
+  return emitManagedResult(session, command, result, options, isRepeatableRead(tool.method));
 }
 async function executeManagedTool(session, route, command, managed, tool, { toolArgs, options }) {
   const { config } = session;
@@ -2271,7 +2285,7 @@ async function executeManagedTool(session, route, command, managed, tool, { tool
   }
   return result;
 }
-async function emitManagedResult(session, command, initial, options) {
+async function emitManagedResult(session, command, initial, options, repeatable) {
   const { config } = session;
   const { stdout, stderr, exit } = session.io;
   let result = initial;
@@ -2289,7 +2303,7 @@ async function emitManagedResult(session, command, initial, options) {
         code: "BAD_REQUEST",
         details: { message: error.message }
       } : toolResultFromError(error);
-      return exit(emitPresentationFailure(result, failure, { stdout, stderr }, emitOptionsFor(config, options.json, command)));
+      return exit(emitPresentationFailure(result, failure, { stdout, stderr }, { ...emitOptionsFor(config, options.json, command), repeatable }));
     }
     if (viewed.kind === "text") {
       stdout(viewed.text);
@@ -2352,7 +2366,7 @@ async function runNativeCommand2(session, route, command, native) {
   const result = await executeCliCommand(native, toolArgs, options, { stdout, stderr }, config.coerceJsonArgs ?? true, globals);
   const emission = prepareCliCommandEmission(native, result, options);
   if (emission.result.ok && emission.presentationFailure !== undefined) {
-    return exit(emitPresentationFailure(emission.result, emission.presentationFailure, { stdout, stderr }, emitOptionsFor(config, options.json, command)));
+    return exit(emitPresentationFailure(emission.result, emission.presentationFailure, { stdout, stderr }, { ...emitOptionsFor(config, options.json, command), repeatable: false }));
   }
   let emittedExitCode;
   if (emission.result.ok && emission.presentation !== undefined) {