@iislee/opencodex 2.11.0 → 2.35.0

package/src/adapters/cursor/protobuf-request.ts

@@ -4,16 +4,21 @@ import { ValueSchema } from "@bufbuild/protobuf/wkt";
 import type { OcxAssistantContentPart, OcxMessage, OcxToolResultMessage } from "../../types";
 import { namespacedToolName } from "../../types";
 import type { CursorRunRequest } from "./types";
-import { isCursorExternalWireModel } from "./discovery";
+import { decodeCursorCallId } from "./call-id";
+import { cursorNeedsExternalToolContinuation, isCursorExternalWireModel } from "./discovery";
+import { normalizeCursorToolResultText } from "./tool-result-normalize";
 import { debugProviderDiagnostic } from "../../lib/debug";
 import {
   createCursorBlobRequestScope,
+  cursorBlobMaxEntryBytes,
   releaseCursorBlobRequestScope,
   sealCursorBlobRequestScope,
   storeCursorBlob,
   type CursorBlobRequestScopeToken,
 } from "./native-exec";
+import { buildSelectedContext, CURSOR_VISION_IMAGE_HISTORY_MARKER } from "./images";
 import { estimateTokens } from "../../lib/token-estimate";
+import { parseDataUrl } from "../image";
 import {
   AgentClientMessageSchema,
   AgentConversationTurnStructureSchema,
@@ -22,10 +27,12 @@ import {
   ConversationActionSchema,
   ConversationStepSchema,
   ConversationStateStructureSchema,
+  type ConversationStateStructure,
   ConversationTurnStructureSchema,
   McpArgsSchema,
   McpSuccessSchema,
   McpTextContentSchema,
+  McpImageContentSchema,
   McpToolCallSchema,
   McpToolResultContentItemSchema,
   McpToolResultSchema,
@@ -65,6 +72,14 @@ export const CURSOR_EXTERNAL_ROOT_BLOB_LIMIT = 192;
 /** Approximate prompt-size guard; tool schemas and protocol framing consume context separately. */
 export const CURSOR_EXTERNAL_ROOT_BYTE_LIMIT = 512 * 1024;
 
+/**
+ * Action text for external-model tool-result continuations. Native models keep
+ * resumeAction; external wire models continue as userMessageAction so the
+ * results already stored in history blobs are visible without a ResumeAction.
+ */
+export const CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT =
+  "Continue: the requested tool results are provided in the conversation history above.";
+
 /** Runtime timezone for protobuf RequestContextEnv (dynamic, never hardcoded). */
 function runtimeTimeZone(): string {
   try {
@@ -119,6 +134,10 @@ function rootBlobCandidate(
   };
 }
 
+function toolResultRootPayload(text: string): { role: "assistant"; content: [{ type: "text"; text: string }] } {
+  return { role: "assistant", content: [{ type: "text", text }] };
+}
+
 function truncateToolResultBlob(entry: RootBlobCandidate, maxBytes: number): RootBlobCandidate | null {
   if (entry.byteLength <= maxBytes) return entry;
   if (entry.role !== "toolResult" || entry.text === undefined) return null;
@@ -131,7 +150,7 @@ function truncateToolResultBlob(entry: RootBlobCandidate, maxBytes: number): Roo
     while (end > 0 && end < encoded.byteLength && (encoded[end]! & 0xc0) === 0x80) end -= 1;
     const truncated = `${decoder.decode(encoded.subarray(0, end))}${marker}`;
     const result = rootBlobCandidate(
-      { role: "user", content: [{ type: "text", text: truncated }] },
+      toolResultRootPayload(truncated),
       "toolResult",
       { messageIndex: entry.messageIndex, text: truncated },
     );
@@ -140,7 +159,7 @@ function truncateToolResultBlob(entry: RootBlobCandidate, maxBytes: number): Roo
     keepBytes = Math.max(0, end - (result.byteLength - maxBytes) - 16);
   }
   const markerOnly = rootBlobCandidate(
-    { role: "user", content: [{ type: "text", text: marker.trimStart() }] },
+    toolResultRootPayload(marker.trimStart()),
     "toolResult",
     { messageIndex: entry.messageIndex, text: marker.trimStart() },
   );
@@ -170,11 +189,12 @@ function assistantRootText(
 }
 
 // Cursor builds the actual model prompt from rootPromptMessagesJson (turns[] is UI/display metadata),
-// so prior history — including assistant tool calls and tool results — must be replayed here or a
-// ResumeAction has nothing model-visible to continue from. The active user message is excluded
-// because it travels in the action. Tool results are rendered as user-role text with a marker, and
-// each entry is a SHA-256 blob ID (Cursor fetches the bytes back via getBlobArgs). Mirrors the
-// danger-pi reference buildRootPromptMessagesJson.
+// so prior history must be replayed here or a ResumeAction has nothing model-visible to continue from.
+// The active user message is excluded because it travels in the action. When the continuation cannot
+// rely on native MCP turn state, tool results stay assistant-role text with a [Tool Result] /
+// [Tool Error] marker so Cursor does not wrap them as `<user_query>` (#1992). Native resume models
+// already carry the paired MCP result on turns[], so that marker is omitted from root replay — Auto
+// few-shot-mimics it as chat text otherwise. Each entry is a SHA-256 blob ID.
 function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobRequestScopeToken): {
   ids: Uint8Array[];
   byteLength: number;
@@ -195,19 +215,59 @@ function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobR
   }
 
   const externalModel = isCursorExternalWireModel(request.modelId);
+  const echoToolResultInRoot = cursorNeedsExternalToolContinuation(request.modelId);
   const lastRawIsToolResult = messages.at(-1)?.role === "toolResult";
   const activeUserIndex = lastRawIsToolResult ? -1 : lastActionIndex(messages);
+  // Repetition breaker (devlog 260826 gap-9): external full-replay flattens history to text,
+  // so N identical assistant/tool-result rounds replay as N identical lines and PRIME the model
+  // to emit the same line again (self-reinforcing loop: S2a 180x, identical-probe repetition).
+  // Collapse consecutive duplicates into one entry + a count marker, and count collapses so a
+  // strategy-change note can be appended when the pattern is severe.
+  let lastReplayText: string | undefined;
+  let lastReplayEntry: RootBlobCandidate | undefined;
+  let collapsedRepeats = 0;
+  let maxRunLength = 1;
+  let currentRun = 1;
+  const pushDeduped = (
+    payload: { role: string; content: [{ type: "text"; text: string }] },
+    role: RootBlobCandidate["role"],
+    opts: { messageIndex: number; text?: string },
+    normalized: string,
+  ): void => {
+    if (externalModel && lastReplayText !== undefined && normalized === lastReplayText && lastReplayEntry) {
+      collapsedRepeats++;
+      currentRun++;
+      if (currentRun > maxRunLength) maxRunLength = currentRun;
+      const marked = `${normalized}\n[note: this exact output was produced ${currentRun} times in a row]`;
+      const replacement = rootBlobCandidate(
+        { role: payload.role, content: [{ type: "text", text: marked }] },
+        role,
+        opts,
+      );
+      entries[entries.indexOf(lastReplayEntry)] = replacement;
+      lastReplayEntry = replacement;
+      return;
+    }
+    currentRun = 1;
+    const entry = rootBlobCandidate(payload, role, opts);
+    entries.push(entry);
+    lastReplayText = normalized;
+    lastReplayEntry = entry;
+  };
 
   for (let i = 0; i < messages.length; i++) {
     if (i === activeUserIndex) break;
     const message = messages[i];
     if (!message) continue;
     if (message.role === "user" || message.role === "developer") {
-      const text = contentText(message).trim();
+      const text = historyContentText(message).trim();
       // Cursor root replay expects OpenAI-style content parts for historical user messages.
       // A bare string survives blob hydration but external workers reject the completed replay
       // before tokenization (`usedTokens: 0`, then invalid_argument).
       if (text.length > 0) {
+        lastReplayText = undefined;
+        lastReplayEntry = undefined;
+        currentRun = 1;
         entries.push(rootBlobCandidate({
           role: "user",
           content: [{ type: "text", text }],
@@ -218,23 +278,33 @@ function rootPromptMessages(request: CursorRunRequest, requestScope: CursorBlobR
       // Native Composer state can preserve it through ThinkingMessage/history structures.
       const text = assistantRootText(message, !externalModel).trim();
       if (text.length > 0) {
-        entries.push(rootBlobCandidate(
+        pushDeduped(
           { role: "assistant", content: [{ type: "text", text }] },
           "assistant",
           { messageIndex: i },
-        ));
+          text,
+        );
       }
       // Assistant tool CALLS are intentionally NOT replayed as visible "[Tool Call]" text here.
     } else if (message.role === "toolResult") {
-      const prefix = message.isError ? "[Tool Error]" : "[Tool Result]";
+      // Native resume models already receive the paired MCP result through turns[]. Replaying
+      // the same payload as assistant-role "[Tool Result]" / "[tool_result]" text teaches Auto
+      // to echo that envelope as chat instead of continuing from the structured result.
+      if (!echoToolResultInRoot) continue;
+      // #1920: the prefix must reflect the NORMALIZED error state (an empty
+      // node_repl result is an error even when the runtime said isError=false).
+      const prefix = normalizedToolResult(message, contentToText(message.content)).isError ? "[Tool Error]" : "[Tool Result]";
       const text = `${prefix}\n${toolResultToText(message)}`;
-      entries.push(rootBlobCandidate(
-        { role: "user", content: [{ type: "text", text }] },
-        "toolResult",
-        { messageIndex: i, text },
-      ));
+      pushDeduped(toolResultRootPayload(text), "toolResult", { messageIndex: i, text }, text);
     }
   }
+  // Severe repetition: tell the model ONCE, imperatively, to change strategy.
+  if (externalModel && maxRunLength >= 3) {
+    entries.push(rootBlobCandidate({
+      role: "user",
+      content: [{ type: "text", text: `[context note] The transcript above contains the same output repeated ${maxRunLength} times in a row. Repeating it again is a failure. Take a DIFFERENT action now, or state plainly what is blocking progress.` }],
+    }, "user", {}));
+  }
 
   let selected = entries;
   let historyMessageStart = 0;
@@ -318,7 +388,7 @@ function contentText(message: OcxMessage): string {
     .map(part => {
       if (part.type === "text") return part.text;
       if (part.type === "thinking") return part.thinking;
-      if (part.type === "image") return `[image input unsupported by Cursor adapter phase 3: ${part.detail ?? "auto"}]`;
+      if (part.type === "image") return undefined;
       return undefined;
     })
     .filter((value): value is string => typeof value === "string" && value.length > 0)
@@ -328,21 +398,217 @@ function contentText(message: OcxMessage): string {
 function contentToText(content: OcxToolResultMessage["content"]): string {
   if (typeof content === "string") return content;
   return content
-    .map(part => part.type === "text" ? part.text : `[image input unsupported by Cursor adapter phase 3: ${part.detail ?? "auto"}]`)
+    .map(part => {
+      if (part.type === "text") return part.text;
+      if (part.type === "image") return CURSOR_VISION_IMAGE_HISTORY_MARKER;
+      return undefined;
+    })
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
     .join("\n");
 }
 
+/** History serializer. Replayed turns are text-only; never embed image bytes. */
+function historyContentText(message: OcxMessage): string {
+  if (message.role === "toolResult" || typeof message.content === "string") return contentText(message);
+  return message.content
+    .map(part => {
+      if (part.type === "text") return part.text;
+      if (part.type === "thinking") return part.thinking;
+      if (part.type === "image") return CURSOR_VISION_IMAGE_HISTORY_MARKER;
+      return undefined;
+    })
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
+    .join("\n");
+}
+
+const BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/**
+ * Decode a Codex inline image into Cursor wire bytes.
+ *
+ * `OcxImageContent.imageUrl` is either a `data:` URL or a remote https URL, so this cannot reuse
+ * the MCP helper (which takes bare base64 plus a separate mime). It layers strict validation over
+ * the shared `parseDataUrl` rather than tightening it, because Anthropic, Google, and Command Code
+ * share that parser. `Buffer.from(x, "base64")` accepts many invalid strings silently, so the
+ * charset is checked explicitly. Remote URLs are out of scope: `McpImageContent` needs bytes, and
+ * fetching here would put network IO inside request construction.
+ */
+function decodeInlineImage(imageUrl: string): { bytes: Uint8Array; mimeType: string } | undefined {
+  const parsed = parseDataUrl(imageUrl);
+  if (!parsed) return undefined;
+  const base64 = parsed.base64.trim();
+  if (base64.length === 0 || base64.length % 4 !== 0 || !BASE64_PATTERN.test(base64)) return undefined;
+  try {
+    const bytes = Uint8Array.from(Buffer.from(base64, "base64"));
+    if (bytes.length === 0) return undefined;
+    return { bytes, mimeType: parsed.mediaType || "application/octet-stream" };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A degraded image must never make a step LARGER than the legacy encoding did, or this change
+ * could fail admission for a request that previously fit. The old placeholder was
+ * `[image input unsupported by Cursor adapter phase 3: <detail>]`; anything we emit in its place
+ * is truncated to that budget so the zero-image case is byte-bounded by the pre-change behavior.
+ */
+const LEGACY_IMAGE_PLACEHOLDER_BUDGET =
+  "[image input unsupported by Cursor adapter phase 3: auto]".length;
+
+function imagePlaceholder(reason: string): string {
+  const text = `[image omitted: ${reason}]`;
+  return text.length <= LEGACY_IMAGE_PLACEHOLDER_BUDGET
+    ? text
+    : `${text.slice(0, LEGACY_IMAGE_PLACEHOLDER_BUDGET - 1)}]`;
+}
+
+type DecodedResultPart =
+  | { kind: "text"; text: string }
+  | { kind: "image"; bytes: Uint8Array; mimeType: string }
+  | { kind: "undecodable" };
+
+type NormalizedToolResult = { text: string; isError: boolean };
+
+/**
+ * Decode a tool result's parts ONCE. `toolCallStep` may re-serialize a step several times while
+ * shrinking it to fit blob admission, and decoding base64 on every attempt made that loop
+ * quadratic (an audit measured ~3s for 100 images).
+ */
+function decodeResultParts(message: OcxToolResultMessage): DecodedResultPart[] | undefined {
+  const content = message.content;
+  if (typeof content === "string") return undefined;
+  return content.map((part): DecodedResultPart => {
+    if (part.type === "text") return { kind: "text", text: part.text };
+    if (part.type === "video") return { kind: "text", text: "[video]" };
+    const decoded = decodeInlineImage(part.imageUrl);
+    return decoded ? { kind: "image", ...decoded } : { kind: "undecodable" };
+  });
+}
+
+function countImages(parts: DecodedResultPart[] | undefined): number {
+  return parts ? parts.filter(p => p.kind === "image").length : 0;
+}
+
+/**
+ * Build the wire content items for a tool result, preserving part order.
+ *
+ * Images become real `McpImageContent` — the Cursor schema has an image case on
+ * `McpToolResultContentItem`, and `native-exec-mcp.ts` already uses it for MCP-invoked tools.
+ * Flattening them to placeholder text blinded every screenshot-returning tool (Computer Use,
+ * browser QA) that Codex routes through this path.
+ */
+function toolResultContentItems(
+  message: OcxToolResultMessage,
+  decoded?: DecodedResultPart[],
+  maxImages = Number.POSITIVE_INFINITY,
+  normalizedText?: NormalizedToolResult,
+) {
+  const parts = decoded ?? decodeResultParts(message);
+  const textItem = (text: string) => [create(McpToolResultContentItemSchema, {
+    content: { case: "text" as const, value: create(McpTextContentSchema, { text }) },
+  })];
+  if (!parts) {
+    const normalized = normalizedText
+      ?? normalizedToolResult(message, typeof message.content === "string" ? message.content : "");
+    return textItem(normalized.text);
+  }
+  const normalized = normalizedText ?? normalizedDecodedTextResult(message, parts);
+  if (normalized) {
+    // #1920/#1866: empty or failure-state Computer Use / node_repl results are
+    // normalized before they reach the native wire. Pure-text part arrays use
+    // the same newline-joined representation this serializer already emitted;
+    // image-bearing and undecodable results stay on the lossless part path.
+    return textItem(normalized.text);
+  }
+  // Images are dropped OLDEST first when the step must shrink: the most recent screenshot is the
+  // one the model is reasoning about, so it is the last to go.
+  const totalImages = countImages(parts);
+  const allowed = Math.max(0, Math.min(totalImages, maxImages));
+  let seen = 0;
+  // Consecutive text runs are newline-joined into ONE item, exactly as the legacy encoding did.
+  // Emitting one protobuf item per part adds per-item framing, which was enough to push a
+  // previously admissible step past the blob ceiling (round-3 audit: 1020 -> 1025 bytes at a
+  // 1024 limit). A result with no images must serialize identically to before this feature.
+  const items: ReturnType<typeof create<typeof McpToolResultContentItemSchema>>[] = [];
+  let pendingText: string[] = [];
+  const flushText = () => {
+    if (pendingText.length === 0) return;
+    const text = pendingText.join("\n");
+    pendingText = [];
+    items.push(create(McpToolResultContentItemSchema, {
+      content: { case: "text" as const, value: create(McpTextContentSchema, { text }) },
+    }));
+  };
+  for (const part of parts) {
+    if (part.kind === "text") {
+      pendingText.push(part.text);
+      continue;
+    }
+    if (part.kind === "undecodable") {
+      pendingText.push(imagePlaceholder("no inline data"));
+      continue;
+    }
+    seen++;
+    if (seen <= totalImages - allowed) {
+      pendingText.push(imagePlaceholder(`${part.bytes.byteLength}B over step limit`));
+      continue;
+    }
+    flushText();
+    items.push(create(McpToolResultContentItemSchema, {
+      content: { case: "image" as const, value: create(McpImageContentSchema, {
+        data: part.bytes,
+        mimeType: part.mimeType,
+      }) },
+    }));
+  }
+  flushText();
+  if (items.length === 0) {
+    items.push(create(McpToolResultContentItemSchema, {
+      content: { case: "text" as const, value: create(McpTextContentSchema, { text: "" }) },
+    }));
+  }
+  return items;
+}
+
 function toolResultToText(message: OcxToolResultMessage): string {
+  const normalized = normalizedToolResult(message, contentToText(message.content));
   return [
     "[tool_result]",
-    `call_id: ${message.toolCallId}`,
+    `call_id: ${decodeCursorCallId(message.toolCallId)}`,
     `name: ${namespacedToolName(message.toolNamespace, message.toolName)}`,
-    `is_error: ${message.isError}`,
+    `is_error: ${normalized.isError}`,
     "output:",
-    contentToText(message.content),
+    normalized.text,
   ].join("\n");
 }
 
+/**
+ * Shared #1920 normalization entry: pure-text results only. Image-bearing or
+ * encrypted results pass through untouched (their content is not plain text).
+ */
+function normalizedToolResult(message: OcxToolResultMessage, text: string): NormalizedToolResult {
+  if (message.containsEncryptedContent) return { text, isError: message.isError };
+  return normalizeCursorToolResultText(text, {
+    toolName: message.toolName,
+    toolNamespace: message.toolNamespace,
+    isError: message.isError,
+  });
+}
+
+/**
+ * A content-part result is plain text only when every decoded part is text (the empty array is the
+ * empty text result). Join it exactly as toolResultContentItems already did, then share the string
+ * normalization contract. Any image or undecodable part keeps the existing part-preserving path.
+ */
+function normalizedDecodedTextResult(
+  message: OcxToolResultMessage,
+  parts: DecodedResultPart[],
+): NormalizedToolResult | undefined {
+  if (parts.some(part => part.kind !== "text")) return undefined;
+  return normalizedToolResult(message, parts.map(part => part.kind === "text" ? part.text : "").join("\n"));
+}
+
 function argBytes(value: unknown): Uint8Array {
   try {
     return toBinary(ValueSchema, fromJson(ValueSchema, value as JsonValue));
@@ -359,7 +625,8 @@ function toolCallStep(
   const args: Record<string, Uint8Array> = {};
   for (const [key, value] of Object.entries(part.arguments ?? {})) args[key] = argBytes(value);
   const toolName = namespacedToolName(part.namespace, part.name);
-  return storeCursorBlob(toBinary(ConversationStepSchema, create(ConversationStepSchema, {
+  const decodedResult = result ? decodeResultParts(result) : undefined;
+  const serialize = (maxImages: number): Uint8Array => toBinary(ConversationStepSchema, create(ConversationStepSchema, {
     message: {
       case: "toolCall",
       value: create(ToolCallSchema, {
@@ -369,27 +636,42 @@ function toolCallStep(
             args: create(McpArgsSchema, {
               name: toolName,
               toolName,
-              toolCallId: part.id,
+              toolCallId: decodeCursorCallId(part.id),
               providerIdentifier: OCX_RESPONSES_TOOL_PROVIDER,
               args,
             }),
-            ...(result ? { result: toolResultPart(result) } : {}),
+            ...(result ? { result: toolResultPart(result, decodedResult, maxImages) } : {}),
           }),
         },
       }),
     },
-  })), requestScope);
+  }));
+
+  // A step is stored as ONE blob, so its images share an entry with the call's arguments, text,
+  // mime strings, and protobuf framing. A byte budget over decoded images alone cannot bound that
+  // (an audit reproduced a 448-byte-argument call whose 460-byte image pushed a previously
+  // admitted step past the ceiling). Measure the real serialized size instead, then drop images —
+  // oldest first, so the most recent screenshot survives — until the step fits.
+  const limit = cursorBlobMaxEntryBytes();
+  const imageCount = countImages(decodedResult);
+  let encoded = serialize(imageCount);
+  for (let allowed = imageCount - 1; allowed >= 0 && encoded.byteLength > limit; allowed--) {
+    encoded = serialize(allowed);
+  }
+  return storeCursorBlob(encoded, requestScope);
 }
 
-function toolResultPart(message: OcxToolResultMessage) {
+function toolResultPart(message: OcxToolResultMessage, decoded?: DecodedResultPart[], maxImages?: number) {
+  const parts = decoded ?? decodeResultParts(message);
+  const normalized = parts
+    ? normalizedDecodedTextResult(message, parts)
+    : normalizedToolResult(message, typeof message.content === "string" ? message.content : "");
   return create(McpToolResultSchema, {
     result: {
       case: "success",
       value: create(McpSuccessSchema, {
-        isError: message.isError,
-        content: [create(McpToolResultContentItemSchema, {
-          content: { case: "text", value: create(McpTextContentSchema, { text: contentToText(message.content) }) },
-        })],
+        isError: normalized?.isError ?? message.isError,
+        content: toolResultContentItems(message, parts, maxImages, normalized),
       }),
     },
   });
@@ -481,11 +763,15 @@ function conversationTurns(
     if (message.role === "toolResult") {
       if (!current) continue;
       if (externalModel) {
-        const prefix = message.isError ? "[Tool Error]" : "[Tool Result]";
+        // #1920/#1866: this external-replay site bypasses toolResultToText, so it
+        // must consume the normalizer directly — cursor/grok-4.6 is the exact
+        // reported repro path for empty Computer Use results.
+        const normalized = normalizedToolResult(message, contentToText(message.content));
+        const prefix = normalized.isError ? "[Tool Error]" : "[Tool Result]";
         current.steps.push(storeCursorBlob(toBinary(ConversationStepSchema, create(ConversationStepSchema, {
           message: {
             case: "assistantMessage",
-            value: create(AssistantMessageSchema, { text: `${prefix}\n${contentToText(message.content)}` }),
+            value: create(AssistantMessageSchema, { text: `${prefix}\n${normalized.text}` }),
           },
         })), requestScope));
         continue;
@@ -507,8 +793,10 @@ function conversationTurns(
     flush();
     current = {
       userMessage: storeCursorBlob(toBinary(UserMessageSchema, create(UserMessageSchema, {
-        text: contentText(message),
+        text: historyContentText(message),
         messageId: crypto.randomUUID(),
+        selectedContext: buildSelectedContext([], requestScope),
+        mode: 1,
       })), requestScope),
       steps: [],
     };
@@ -577,19 +865,38 @@ function buildPreparedCursorRunRequest(
   const text = lastRole === "user" || lastRole === "developer"
     ? appendCursorGenericToolUseHint(request.tools, rawText)
     : rawText;
-  // Tool-result-only turns resume the remembered Cursor conversation with results in history.
   const lastRawIsToolResult = request.rawMessages?.at(-1)?.role === "toolResult";
-  const actionCase = !lastRawIsToolResult && text.trim().length > 0
+  const selectedImages = request.selectedImages ?? [];
+  // Native models resume the remembered Cursor conversation. External wire
+  // models continue as userMessageAction so history-blob tool results stay
+  // visible without a ResumeAction. Some native composer ids are also routed
+  // through the external continuation path (cursorNeedsExternalToolContinuation)
+  // because a bare resumeAction makes them continue exploring with native tools
+  // instead of answering (observed on composer-2.5; see discovery.ts).
+  const externalToolContinuation = lastRawIsToolResult && cursorNeedsExternalToolContinuation(request.modelId);
+  // Image-only active turns (including soft-omitted images) stay userMessageAction.
+  const actionCase = (
+    externalToolContinuation
+    || (!lastRawIsToolResult && (text.trim().length > 0 || selectedImages.length > 0))
+  )
     ? "userMessageAction"
     : "resumeAction";
+  const actionText = externalToolContinuation
+    ? (request.echoRetryContinuationText ?? CURSOR_EXTERNAL_TOOL_CONTINUATION_TEXT)
+    : request.echoRetryContinuationText
+      ? `${text}\n\n[correction] ${request.echoRetryContinuationText}`
+      : text;
   const action = create(ConversationActionSchema, {
     action: actionCase === "userMessageAction"
       ? {
           case: "userMessageAction",
           value: create(UserMessageActionSchema, {
             userMessage: create(UserMessageSchema, {
-              text,
+              text: actionText,
               messageId: crypto.randomUUID(),
+              selectedContext: buildSelectedContext(selectedImages, requestScope),
+              // OmniRoute / cursor-agent always send mode=1 on UserMessage.
+              mode: 1,
             }),
             requestContext: buildRequestContext(),
           }),
@@ -601,9 +908,70 @@ function buildPreparedCursorRunRequest(
           }),
         },
   });
-  const rootPromptMessagesState = rootPromptMessages(request, requestScope);
-  const rootPromptMessageIds = rootPromptMessagesState.ids;
-  const turnIds = conversationTurns(request, requestScope, rootPromptMessagesState.historyMessageStart);
+  let continuationMode: "full-replay" | "checkpoint" = "full-replay";
+  let checkpointInvalidationReason = request.checkpointInvalidationReason;
+  let conversationState: ConversationStateStructure | undefined;
+  let rootPromptMessagesState: ReturnType<typeof rootPromptMessages> | undefined;
+  if (request.checkpointBytes && request.checkpointBytes.byteLength > 0) {
+    try {
+      conversationState = fromBinary(ConversationStateStructureSchema, request.checkpointBytes);
+      continuationMode = "checkpoint";
+      const suffixStart = request.checkpointSuffixStart;
+      if (
+        typeof suffixStart === "number"
+        && Number.isSafeInteger(suffixStart)
+        && suffixStart >= 0
+        && request.rawMessages
+        && suffixStart < request.rawMessages.length
+      ) {
+        const suffixRequest: CursorRunRequest = {
+          ...request,
+          system: [],
+          rawMessages: request.rawMessages.slice(suffixStart),
+        };
+        const suffixRoots = rootPromptMessages(suffixRequest, requestScope);
+        const suffixTurns = conversationTurns(suffixRequest, requestScope, suffixRoots.historyMessageStart);
+        const suffixSystemCount = systemPromptBlobs(suffixRequest).length;
+        const suffixHistoryIds = suffixRoots.ids.slice(suffixSystemCount);
+        const suffixHistorySerialized = suffixRoots.serialized.slice(suffixSystemCount);
+        conversationState = create(ConversationStateStructureSchema, {
+          ...conversationState,
+          rootPromptMessagesJson: [
+            ...conversationState.rootPromptMessagesJson,
+            ...suffixHistoryIds,
+          ],
+          turns: [
+            ...conversationState.turns,
+            ...suffixTurns,
+          ],
+        });
+        rootPromptMessagesState = {
+          ids: suffixHistoryIds,
+          byteLength: suffixRoots.byteLength,
+          historyMessageStart: suffixRoots.historyMessageStart,
+          serialized: suffixHistorySerialized,
+        };
+      }
+    } catch {
+      checkpointInvalidationReason = "decode_failed";
+    }
+  }
+  if (!conversationState) {
+    rootPromptMessagesState = rootPromptMessages(request, requestScope);
+    conversationState = create(ConversationStateStructureSchema, {
+      rootPromptMessagesJson: rootPromptMessagesState.ids,
+      turns: conversationTurns(request, requestScope, rootPromptMessagesState.historyMessageStart),
+      todos: [],
+      pendingToolCalls: [],
+      previousWorkspaceUris: [],
+      fileStates: {},
+      fileStatesV2: {},
+      summaryArchives: [],
+      turnTimings: [],
+      subagentStates: {},
+      readPaths: [],
+    });
+  }
   // Hoisted out of the mcp_tools spread below so the estimate can read the same
   // filtered definitions the wire carries. Both helpers are pure.
   const visibleTools = cursorToolsForActivePrompt(request.tools, rawText, request.toolChoice);
@@ -615,46 +983,46 @@ function buildPreparedCursorRunRequest(
     turnType: lastRawIsToolResult ? "tool-continuation" : "initial",
     externalModel: isCursorExternalWireModel(request.modelId),
     rawMessages: request.rawMessages?.length ?? 0,
-    rootBlobs: rootPromptMessageIds.length,
-    rootBytes: rootPromptMessagesState.byteLength,
-    turnBlobs: turnIds.length,
+    continuationMode,
+    checkpointPresent: continuationMode === "checkpoint",
+    checkpointBytes: continuationMode === "checkpoint" ? request.checkpointBytes?.byteLength : undefined,
+    checkpointInvalidationReason,
+    rootBlobs: conversationState.rootPromptMessagesJson.length,
+    rootBytes: rootPromptMessagesState?.byteLength ?? 0,
+    turnBlobs: conversationState.turns.length,
     tools: request.tools?.length ?? 0,
   });
 
+  const requestedModelParameters = [
+    ...(request.requestedModelParameters ?? []),
+    ...(request.routingLevel ? [{ id: CURSOR_ROUTING_LEVEL_PARAMETER_ID, value: request.routingLevel }] : []),
+  ];
+  const hasExplicitModelParameters = (request.requestedModelParameters?.length ?? 0) > 0;
   const runRequest = create(AgentRunRequestSchema, {
     conversationId: request.conversationId,
-    conversationState: create(ConversationStateStructureSchema, {
-      rootPromptMessagesJson: rootPromptMessageIds,
-      turns: turnIds,
-      todos: [],
-      pendingToolCalls: [],
-      previousWorkspaceUris: [],
-      fileStates: {},
-      fileStatesV2: {},
-      summaryArchives: [],
-      turnTimings: [],
-      subagentStates: {},
-      readPaths: [],
-    }),
+    conversationState,
     action,
-    modelDetails: create(ModelDetailsSchema, {
-      modelId: request.modelId,
-      displayModelId: request.modelId,
-      displayName: request.modelId,
-      displayNameShort: request.modelId,
-      aliases: [],
-    }),
-    // requested_model is currently a Cursor Router-only surface. External model clients still
-    // send model_details alone; sending both makes external workers reach stepCompleted and then
-    // reject the turn with invalid_argument.
-    ...(request.routingLevel ? {
+    // Explicit model-picker parameters follow current Cursor clients and use requested_model alone.
+    // Keep legacy model_details for flat model ids and the already-live Router path; sending both for
+    // a parameterized external model can resolve conflicting selections and end in invalid_argument.
+    ...(!hasExplicitModelParameters ? {
+      modelDetails: create(ModelDetailsSchema, {
+        modelId: request.modelId,
+        displayModelId: request.modelId,
+        displayName: request.modelId,
+        displayNameShort: request.modelId,
+        aliases: [],
+        ...(request.maxMode === true ? { maxMode: true } : {}),
+      }),
+    } : {}),
+    ...(requestedModelParameters.length > 0 || request.maxMode === true ? {
       requestedModel: create(RequestedModelSchema, {
         modelId: request.modelId,
-        maxMode: false,
-        parameters: [create(RequestedModel_ModelParameterbytesSchema, {
-          id: CURSOR_ROUTING_LEVEL_PARAMETER_ID,
-          value: request.routingLevel,
-        })],
+        // Max Mode must be raised on BOTH RequestedModel and ModelDetails; missing either
+        // can invalid_argument upstream (devlog 260826 070).
+        maxMode: request.maxMode === true,
+        parameters: requestedModelParameters.map(parameter =>
+          create(RequestedModel_ModelParameterbytesSchema, parameter)),
       }),
     } : {}),
     // Mirror the client (Responses) tool definitions into the top-level AgentRunRequest.mcp_tools
@@ -670,7 +1038,11 @@ function buildPreparedCursorRunRequest(
     // the event-state `clientToolNames` use (live-transport.ts). Advertising the raw `request.tools`
     // here would let mcp_tools expose a tool that the event state does not recognize for a generic
     // tool-count prompt, so a call to it would be rejected as an unknown Responses tool.
-    ...(mcpToolDefs.length > 0 ? { mcpTools: create(McpToolsSchema, { mcpTools: mcpToolDefs }) } : {}),
+    // An explicitly empty McpTools wrapper (bare API callers) suppresses Cursor's default
+    // native catalog; an absent field lets identified Codex sessions keep it (devlog 260826 040).
+    ...(mcpToolDefs.length > 0 || request.suppressDefaultCursorToolCatalog === true
+      ? { mcpTools: create(McpToolsSchema, { mcpTools: mcpToolDefs }) }
+      : {}),
   });
 
   const message = create(AgentClientMessageSchema, {
@@ -682,8 +1054,8 @@ function buildPreparedCursorRunRequest(
   // Same instances that produced `bytes`, so the estimate cannot count history or
   // tools the payload dropped — the defect that blocked PR #376.
   const modelVisibleParts = [
-    ...rootPromptMessagesState.serialized,
-    ...(actionCase === "userMessageAction" ? [text] : []),
+    ...(rootPromptMessagesState?.serialized ?? []),
+    ...(actionCase === "userMessageAction" ? [actionText] : []),
     ...mcpToolDefs.map(modelVisibleToolText),
   ];
   return {