@bitkyc08/opencodex 2.7.36 → 2.7.37

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

@@ -46,9 +46,17 @@ import {
 } from "./tool-definitions";
 
 const encoder = new TextEncoder();
+const decoder = new TextDecoder();
 
 /** Parameter id advertised by Cursor's `default` model for its Cost/Balance/Intelligence control. */
 export const CURSOR_ROUTING_LEVEL_PARAMETER_ID = "optimization";
+// Cursor external workers reject oversized root replay sets with a late invalid_argument after
+// hydrating every blob (observed at 208 roots with usedTokens=0). Keep headroom below that boundary,
+// retaining all system prompts and the newest model-visible history. Cursor IDE similarly bounds /
+// compacts long conversations rather than replaying an unbounded message list.
+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;
 
 /** Runtime timezone for protobuf RequestContextEnv (dynamic, never hardcoded). */
 function runtimeTimeZone(): string {
@@ -72,7 +80,59 @@ function jsonBlob(value: unknown): Uint8Array {
   return encoder.encode(JSON.stringify(value));
 }
 
-function systemPromptBlobs(request: CursorRunRequest): Uint8Array[] {
+type StoredRootBlob = {
+  id: Uint8Array;
+  byteLength: number;
+  role: "system" | "user" | "assistant" | "toolResult";
+  messageIndex?: number;
+  /** Original JSON text payload used when an active tool result must be truncated to fit. */
+  text?: string;
+};
+
+function storedRootBlob(
+  value: unknown,
+  role: StoredRootBlob["role"],
+  opts?: { messageIndex?: number; text?: string },
+): StoredRootBlob {
+  const data = jsonBlob(value);
+  return {
+    id: storeCursorBlob(data),
+    byteLength: data.byteLength,
+    role,
+    ...(opts?.messageIndex !== undefined ? { messageIndex: opts.messageIndex } : {}),
+    ...(opts?.text !== undefined ? { text: opts.text } : {}),
+  };
+}
+
+function truncateToolResultBlob(entry: StoredRootBlob, maxBytes: number): StoredRootBlob | null {
+  if (entry.byteLength <= maxBytes) return entry;
+  if (entry.role !== "toolResult" || entry.text === undefined) return null;
+  const marker = "\n…[truncated for Cursor external replay budget]";
+  const encoded = encoder.encode(entry.text);
+  // Leave headroom for JSON envelope (`role`/`content` wrapper) around the truncated text.
+  let keepBytes = Math.min(encoded.byteLength, Math.max(0, maxBytes - encoder.encode(marker).byteLength - 96));
+  for (let attempt = 0; attempt < 8; attempt++) {
+    let end = keepBytes;
+    while (end > 0 && end < encoded.byteLength && (encoded[end]! & 0xc0) === 0x80) end -= 1;
+    const truncated = `${decoder.decode(encoded.subarray(0, end))}${marker}`;
+    const result = storedRootBlob(
+      { role: "user", content: [{ type: "text", text: truncated }] },
+      "toolResult",
+      { messageIndex: entry.messageIndex, text: truncated },
+    );
+    if (result.byteLength <= maxBytes) return result;
+    if (end === 0) break;
+    keepBytes = Math.max(0, end - (result.byteLength - maxBytes) - 16);
+  }
+  const markerOnly = storedRootBlob(
+    { role: "user", content: [{ type: "text", text: marker.trimStart() }] },
+    "toolResult",
+    { messageIndex: entry.messageIndex, text: marker.trimStart() },
+  );
+  return markerOnly.byteLength <= maxBytes ? markerOnly : null;
+}
+
+function systemPromptBlobs(request: CursorRunRequest): StoredRootBlob[] {
   const prompts = request.system.length > 0 ? [...request.system] : ["You are a helpful assistant."];
   if (cursorRequestHasShellAlias(request.tools)) prompts.push(CURSOR_SHELL_ALIAS_SYSTEM_NOTE);
   const cursorToolGuidance = buildCursorToolGuidanceSystemNote(
@@ -80,13 +140,16 @@ function systemPromptBlobs(request: CursorRunRequest): Uint8Array[] {
     request.toolChoice,
   );
   if (cursorToolGuidance) prompts.push(cursorToolGuidance);
-  return prompts.map(content => storeCursorBlob(jsonBlob({ role: "system", content })));
+  return prompts.map(content => storedRootBlob({ role: "system", content }, "system"));
 }
 
-function assistantRootText(message: Extract<OcxMessage, { role: "assistant" }>): string {
+function assistantRootText(
+  message: Extract<OcxMessage, { role: "assistant" }>,
+  includeThinking: boolean,
+): string {
   if (typeof message.content === "string") return message.content;
   return message.content
-    .map(part => (part.type === "text" ? part.text : part.type === "thinking" ? part.thinking : undefined))
+    .map(part => (part.type === "text" ? part.text : includeThinking && part.type === "thinking" ? part.thinking : undefined))
     .filter((value): value is string => typeof value === "string" && value.length > 0)
     .join("\n");
 }
@@ -97,11 +160,23 @@ function assistantRootText(message: Extract<OcxMessage, { role: "assistant" }>):
 // 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.
-function rootPromptMessages(request: CursorRunRequest): Uint8Array[] {
+function rootPromptMessages(request: CursorRunRequest): {
+  ids: Uint8Array[];
+  byteLength: number;
+  historyMessageStart: number;
+} {
   const entries = systemPromptBlobs(request);
+  const systemEntryCount = entries.length;
   const messages = request.rawMessages;
-  if (!messages?.length) return entries;
+  if (!messages?.length) {
+    return {
+      ids: entries.map(entry => entry.id),
+      byteLength: entries.reduce((sum, entry) => sum + entry.byteLength, 0),
+      historyMessageStart: 0,
+    };
+  }
 
+  const externalModel = isCursorExternalWireModel(request.modelId);
   const lastRawIsToolResult = messages.at(-1)?.role === "toolResult";
   const activeUserIndex = lastRawIsToolResult ? -1 : lastActionIndex(messages);
 
@@ -111,24 +186,110 @@ function rootPromptMessages(request: CursorRunRequest): Uint8Array[] {
     if (!message) continue;
     if (message.role === "user" || message.role === "developer") {
       const text = contentText(message).trim();
-      if (text.length > 0) entries.push(storeCursorBlob(jsonBlob({ role: "user", content: text })));
+      // 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) {
+        entries.push(storedRootBlob({
+          role: "user",
+          content: [{ type: "text", text }],
+        }, "user", { messageIndex: i }));
+      }
     } else if (message.role === "assistant") {
-      const text = assistantRootText(message).trim();
-      if (text.length > 0) entries.push(storeCursorBlob(jsonBlob({ role: "assistant", content: [{ type: "text", text }] })));
+      // External Cursor clients do not replay hidden reasoning as assistant-visible prompt text.
+      // Native Composer state can preserve it through ThinkingMessage/history structures.
+      const text = assistantRootText(message, !externalModel).trim();
+      if (text.length > 0) {
+        entries.push(storedRootBlob(
+          { role: "assistant", content: [{ type: "text", text }] },
+          "assistant",
+          { messageIndex: i },
+        ));
+      }
       // Assistant tool CALLS are intentionally NOT replayed as visible "[Tool Call]" text here.
-      // rootPromptMessagesJson is the model-visible prompt, so a synthetic "[Tool Call]" marker in an
-      // assistant turn gets few-shot-mimicked: the model then emits later (esp. parallel/mixed) tool
-      // calls as inert text instead of real tool frames, halting multi-tool continuations. The paired
-      // tool result below ([Tool Result]/[Tool Error]) carries the call id/name/output Cursor needs to
-      // continue, and conversationTurns replays the native mcpToolCall step. Mirrors request-builder.ts
-      // contentPartToText() which returns undefined for toolCall for the same reason.
     } else if (message.role === "toolResult") {
       const prefix = message.isError ? "[Tool Error]" : "[Tool Result]";
       const text = `${prefix}\n${toolResultToText(message)}`;
-      entries.push(storeCursorBlob(jsonBlob({ role: "user", content: [{ type: "text", text }] })));
+      entries.push(storedRootBlob(
+        { role: "user", content: [{ type: "text", text }] },
+        "toolResult",
+        { messageIndex: i, text },
+      ));
+    }
+  }
+
+  let selected = entries;
+  let historyMessageStart = 0;
+  if (externalModel) {
+    const systemEntries = entries.slice(0, systemEntryCount);
+    const history = entries.slice(systemEntryCount);
+    const systemBytes = systemEntries.reduce((sum, entry) => sum + entry.byteLength, 0);
+    const historyLimit = Math.max(0, CURSOR_EXTERNAL_ROOT_BLOB_LIMIT - systemEntryCount);
+    const historyBudget = Math.max(0, CURSOR_EXTERNAL_ROOT_BYTE_LIMIT - systemBytes);
+
+    // Retain the active trailing tool-result block when it fits (may truncate text).
+    // If even a truncation marker cannot fit the remaining budget, omit it rather than
+    // emitting an oversized root blob.
+    let activeStart = history.length;
+    while (activeStart > 0 && history[activeStart - 1]?.role === "toolResult") activeStart -= 1;
+    const active = history
+      .slice(activeStart)
+      .map(entry => truncateToolResultBlob(entry, historyBudget))
+      .filter((entry): entry is StoredRootBlob => entry !== null);
+    let activeBytes = active.reduce((sum, entry) => sum + entry.byteLength, 0);
+    while (active.length > 1 && activeBytes > historyBudget) {
+      const dropped = active.shift();
+      activeBytes -= dropped?.byteLength ?? 0;
+    }
+    if (active.length === 1 && active[0] && activeBytes > historyBudget) {
+      const truncated = truncateToolResultBlob(active[0], historyBudget);
+      if (truncated) {
+        active[0] = truncated;
+        activeBytes = truncated.byteLength;
+      } else {
+        active.length = 0;
+        activeBytes = 0;
+      }
+    }
+
+    const prior = history.slice(0, activeStart);
+    const keptPrior: StoredRootBlob[] = [];
+    let priorBytes = 0;
+    // Take complete turns from the end: a turn starts at a user/developer root entry.
+    let i = prior.length - 1;
+    while (i >= 0 && keptPrior.length + active.length < historyLimit) {
+      let turnStart = i;
+      while (turnStart > 0 && prior[turnStart]?.role !== "user") turnStart -= 1;
+      const turn = prior.slice(turnStart, i + 1);
+      const turnBytes = turn.reduce((sum, entry) => sum + entry.byteLength, 0);
+      if (
+        keptPrior.length + active.length + turn.length > historyLimit
+        || priorBytes + activeBytes + turnBytes > historyBudget
+      ) {
+        break;
+      }
+      keptPrior.unshift(...turn);
+      priorBytes += turnBytes;
+      i = turnStart - 1;
     }
+
+    const historyEntries = [...keptPrior, ...active];
+    // Guard against orphan assistant / toolResult at the start of the retained suffix.
+    while (historyEntries[0]?.role === "assistant" || historyEntries[0]?.role === "toolResult") {
+      // Never drop the sole active tool-result block.
+      if (historyEntries.length <= active.length) break;
+      historyEntries.shift();
+    }
+    selected = [...systemEntries, ...historyEntries];
+    const firstKept = historyEntries.find(entry => entry.messageIndex !== undefined);
+    historyMessageStart = firstKept?.messageIndex ?? (messages.length);
   }
-  return entries;
+
+  return {
+    ids: selected.map(entry => entry.id),
+    byteLength: selected.reduce((sum, entry) => sum + entry.byteLength, 0),
+    historyMessageStart,
+  };
 }
 
 function contentText(message: OcxMessage): string {
@@ -240,11 +401,13 @@ function lastActionIndex(messages: readonly OcxMessage[] | undefined): number {
   return -1;
 }
 
-function conversationTurns(request: CursorRunRequest): Uint8Array[] {
+function conversationTurns(request: CursorRunRequest, historyMessageStart = 0): Uint8Array[] {
   const messages = request.rawMessages;
   if (!messages?.length) return [];
   const end = lastActionIndex(messages);
+  const externalModel = isCursorExternalWireModel(request.modelId);
   const historyEnd = messages.at(-1)?.role === "toolResult" ? messages.length : Math.max(0, end);
+  const start = externalModel ? Math.max(0, historyMessageStart) : 0;
   const turns: Uint8Array[] = [];
   let current: { userMessage: Uint8Array; steps: Uint8Array[] } | undefined;
   const pendingToolCalls = new Map<string, Extract<OcxAssistantContentPart, { type: "toolCall" }>>();
@@ -261,10 +424,24 @@ function conversationTurns(request: CursorRunRequest): Uint8Array[] {
     pendingToolCalls.clear();
   };
 
-  for (const message of messages.slice(0, historyEnd)) {
+  for (const message of messages.slice(start, historyEnd)) {
     if (message.role === "assistant") {
       if (!current) continue;
       for (const part of message.content) {
+        if (externalModel) {
+          // Working external-model clients replay only assistant text. Native mcpToolCall and
+          // ThinkingMessage structures are Composer state and cause external workers to hydrate
+          // the blobs, reach stepCompleted, then reject the turn with invalid_argument.
+          if (part.type === "text" && part.text.length > 0) {
+            current.steps.push(storeCursorBlob(toBinary(ConversationStepSchema, create(ConversationStepSchema, {
+              message: {
+                case: "assistantMessage",
+                value: create(AssistantMessageSchema, { text: part.text }),
+              },
+            }))));
+          }
+          continue;
+        }
         if (part.type === "toolCall") {
           pendingToolCalls.set(part.id, part);
           continue;
@@ -276,6 +453,16 @@ function conversationTurns(request: CursorRunRequest): Uint8Array[] {
     }
     if (message.role === "toolResult") {
       if (!current) continue;
+      if (externalModel) {
+        const prefix = message.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)}` }),
+          },
+        }))));
+        continue;
+      }
       const priorCall = pendingToolCalls.get(message.toolCallId);
       if (priorCall) {
         current.steps.push(toolCallStep(priorCall, message));
@@ -322,13 +509,11 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
   const text = lastRole === "user" || lastRole === "developer"
     ? appendCursorShellAliasHint(request.tools, appendCursorGenericToolUseHint(request.tools, rawText))
     : rawText;
-  // A tool-result-only turn (the last raw message is a toolResult) continues the SAME Cursor
-  // conversation with the tool result carried as structured conversation history (mcpToolCall.result
-  // in conversationTurns). It must NOT inject the tool result text as a new UserMessageAction — that
-  // would pollute the model input and double-deliver the result. Use ResumeAction so Cursor picks up
-  // from the history we provided.
+  // 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 ? "userMessageAction" : "resumeAction";
+  const actionCase = !lastRawIsToolResult && text.trim().length > 0
+    ? "userMessageAction"
+    : "resumeAction";
   const action = create(ConversationActionSchema, {
     action: actionCase === "userMessageAction"
       ? {
@@ -348,19 +533,27 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
           }),
         },
   });
+  const rootPromptMessagesState = rootPromptMessages(request);
+  const rootPromptMessageIds = rootPromptMessagesState.ids;
+  const turnIds = conversationTurns(request, rootPromptMessagesState.historyMessageStart);
   debugProviderDiagnostic("cursor", "run-request", {
     wireModel: request.modelId,
     action: actionCase,
     conversationId: request.conversationId,
     turnType: lastRawIsToolResult ? "tool-continuation" : "initial",
     externalModel: isCursorExternalWireModel(request.modelId),
+    rawMessages: request.rawMessages?.length ?? 0,
+    rootBlobs: rootPromptMessageIds.length,
+    rootBytes: rootPromptMessagesState.byteLength,
+    turnBlobs: turnIds.length,
+    tools: request.tools?.length ?? 0,
   });
 
   const runRequest = create(AgentRunRequestSchema, {
     conversationId: request.conversationId,
     conversationState: create(ConversationStateStructureSchema, {
-      rootPromptMessagesJson: rootPromptMessages(request),
-      turns: conversationTurns(request),
+      rootPromptMessagesJson: rootPromptMessageIds,
+      turns: turnIds,
       todos: [],
       pendingToolCalls: [],
       previousWorkspaceUris: [],
@@ -379,6 +572,9 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
       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 ? {
       requestedModel: create(RequestedModelSchema, {
         modelId: request.modelId,

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

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type {
   OcxAssistantContentPart,
   OcxContentPart,
@@ -8,7 +9,7 @@ import type {
 } from "../../types";
 import { isAllowedToolChoice, namespacedToolName, toolChoiceAliases, type OcxTool, type OcxToolChoice } from "../../types";
 import type { CursorRequestMessage, CursorRunRequest } from "./types";
-import { cursorWireModelSelection, isCursorExternalWireModel, type CursorRoutingLevel } from "./discovery";
+import { cursorWireModelSelection, type CursorRoutingLevel } from "./discovery";
 import { cursorEffortSuffix } from "./effort-map";
 import {
   cursorMcpToolEncodedSize,
@@ -17,6 +18,7 @@ import {
   cursorToolWireName,
   cursorToolsForActivePrompt,
 } from "./tool-definitions";
+import { lookupCursorThreadConversation } from "./thread-continuity";
 
 /** Probe-verified Cursor Connect boundaries, with byte headroom for the enclosing field. */
 export const CURSOR_TOOL_COUNT_LIMIT = 330;
@@ -159,6 +161,43 @@ export function generatedCursorConversationId(): string {
   return `cursor_${crypto.randomUUID().replace(/-/g, "")}`;
 }
 
+/** Derive an opaque provider-scoped Cursor id from the upstream client's conversation identity. */
+export function cursorConversationIdFromClientThread(threadId: string, identityScope?: string): string {
+  const digest = createHash("sha256")
+    .update("ocx:cursor:thread:")
+    .update(identityScope?.trim() || "local")
+    .update("\0")
+    .update(threadId)
+    .digest("hex")
+    .slice(0, 32);
+  return `cursor_${digest}`;
+}
+
+/**
+ * Resolve the Cursor conversation id for this turn.
+ * Priority: force-fresh → isolate helper → remembered → thread override → client thread → random.
+ * Never use OpenAI Responses `previous_response_id` (resp_*) or shared `prompt_cache_key`
+ * (cache-cohort fingerprint, not conversation ownership).
+ */
+export function resolveCursorConversationId(
+  parsed: OcxParsedRequest,
+  _wireModelId: string,
+  options: CreateCursorRequestOptions = {},
+): string {
+  if (options.forceFreshConversation === true) return generatedCursorConversationId();
+  // Helper/shadow/compaction turns must not append into the parent's Cursor conversation,
+  // even when previous_response_id restored the parent's remembered id.
+  if (parsed._cursorIsolateConversation === true) return generatedCursorConversationId();
+  if (parsed._cursorConversationId) return parsed._cursorConversationId;
+  const threadId = parsed._clientThreadId?.trim();
+  if (threadId) {
+    const recovered = lookupCursorThreadConversation(threadId, parsed._cursorIdentityScope);
+    if (recovered) return recovered;
+    return cursorConversationIdFromClientThread(threadId, parsed._cursorIdentityScope);
+  }
+  return generatedCursorConversationId();
+}
+
 export interface CreateCursorRequestOptions {
   /** Force a brand-new Cursor conversation id even when remembered state exists. */
   forceFreshConversation?: boolean;
@@ -176,23 +215,10 @@ export function createCursorRequest(
   const budget = applyCursorToolBudget(visibleTools, parsed.options.toolChoice);
   const limitNote = catalogLimitNote(budget.tools, budget.omitted);
   const model = normalizeCursorModelId(parsed.modelId, parsed.options.reasoning);
-  const lastRaw = parsed.context.messages.at(-1);
-  // External Cursor models (e.g. gpt-5.6-sol) can corrupt server-side conversation state across
-  // tool-result continuations when ResumeAction reuses the same conversationId. Force a fresh id
-  // so the full history is replayed without depending on that state.
-  const forceFreshConversation =
-    options.forceFreshConversation === true
-    || (lastRaw?.role === "toolResult" && isCursorExternalWireModel(model.modelId));
   return {
     modelId: model.modelId,
     ...(model.routingLevel ? { routingLevel: model.routingLevel } : {}),
-    // The Cursor conversation id comes ONLY from remembered state (_cursorConversationId). Do NOT fall
-    // back to the OpenAI Responses previous_response_id (resp_*): that is a Responses-chain id in a
-    // different namespace and would start an unrelated Cursor conversation, breaking tool-result
-    // continuation. If we have no remembered Cursor conversation, start a fresh one.
-    conversationId: forceFreshConversation
-      ? generatedCursorConversationId()
-      : (parsed._cursorConversationId ?? generatedCursorConversationId()),
+    conversationId: resolveCursorConversationId(parsed, model.modelId, options),
     system: [...(parsed.context.systemPrompt ?? []), ...(limitNote ? [limitNote] : [])],
     messages,
     rawMessages: parsed.context.messages,

package/src/adapters/cursor/thread-continuity.ts

@@ -0,0 +1,67 @@
+/**
+ * Bounded in-memory overrides for Cursor conversation continuity.
+ *
+ * When an invalid_argument recovery mints a fresh conversation id for a store:false
+ * thread-identified client, later turns without previous_response_id must reuse that
+ * recovered id instead of recomputing the stale deterministic thread hash.
+ */
+
+const OVERRIDE_TTL_MS = 60 * 60 * 1000;
+const OVERRIDE_MAX_ENTRIES = 2048;
+
+const overrides = new Map<string, { conversationId: string; updatedAt: number }>();
+
+function now(): number {
+  return Date.now();
+}
+
+function prune(at: number): void {
+  for (const [key, entry] of overrides) {
+    if (at - entry.updatedAt > OVERRIDE_TTL_MS) overrides.delete(key);
+    else break; // Map iterates insertion order; refreshed entries are moved to the end
+  }
+  while (overrides.size > OVERRIDE_MAX_ENTRIES) {
+    const oldest = overrides.keys().next().value;
+    if (oldest === undefined) break;
+    overrides.delete(oldest);
+  }
+}
+
+/** Scope key for a client thread, optionally namespaced by authenticated tenant/operator identity. */
+export function cursorThreadScopeKey(threadId: string, identityScope?: string): string {
+  const scope = identityScope?.trim() || "local";
+  return `${scope}\0${threadId}`;
+}
+
+export function rememberCursorThreadConversation(
+  threadId: string,
+  conversationId: string,
+  identityScope?: string,
+): void {
+  const key = cursorThreadScopeKey(threadId, identityScope);
+  const at = now();
+  overrides.delete(key);
+  overrides.set(key, { conversationId, updatedAt: at });
+  prune(at);
+}
+
+export function lookupCursorThreadConversation(
+  threadId: string,
+  identityScope?: string,
+): string | undefined {
+  const key = cursorThreadScopeKey(threadId, identityScope);
+  const entry = overrides.get(key);
+  if (!entry) return undefined;
+  const at = now();
+  if (at - entry.updatedAt > OVERRIDE_TTL_MS) {
+    overrides.delete(key);
+    return undefined;
+  }
+  overrides.delete(key);
+  overrides.set(key, { conversationId: entry.conversationId, updatedAt: at });
+  return entry.conversationId;
+}
+
+export function clearCursorThreadContinuityForTests(): void {
+  overrides.clear();
+}

package/src/adapters/cursor/types.ts

@@ -42,7 +42,9 @@ export type CursorServerMessage =
   | { type: "heartbeat" }
   | { type: "kv_get"; key: string }
   | { type: "kv_set"; key: string; value: Uint8Array }
-  | { type: "exec"; execCase: string; requestId: string };
+  | { type: "exec"; execCase: string; requestId: string }
+  /** A native exec/MCP action ran locally; retrying this turn could duplicate its side effects. */
+  | { type: "local_side_effect" };
 
 export type CursorClientMessage =
   | { type: "kv_value"; key: string; value?: Uint8Array }

package/src/adapters/cursor.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { AdapterEvent, OcxProviderConfig } from "../types";
 import type { ProviderAdapter } from "./base";
 import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
@@ -5,12 +6,14 @@ import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErro
 import { isCursorExternalWireModel } from "./cursor/discovery";
 import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
-import { createCursorRequest, generatedCursorConversationId } from "./cursor/request-builder";
+import { createCursorRequest } from "./cursor/request-builder";
 import {
   createLiveCursorTransport,
   CursorMissingCredentialError,
   rekeyCursorContextUsage,
+  resolveCursorToken,
 } from "./cursor/live-transport";
+import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
 import { runCursorTurnWithRetry } from "./cursor/transport-retry";
 import {
   createDisabledCursorTransport,
@@ -77,16 +80,36 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         const makeTransport = deps.createTransport ?? createLiveCursorTransport;
         const kv = deps.kv ?? createCursorKvStore();
         const rekeyContextUsage = deps.rekeyContextUsage ?? rekeyCursorContextUsage;
-        _parsed._cursorConversationId ??= generatedCursorConversationId();
+        // Namespace thread→conversation derivation by the authenticated Cursor credential so
+        // shared-proxy tenants with different Cursor accounts cannot collide on a parent thread id.
+        // Prefer an already-set auth scope (e.g. Codex pool account) when present.
+        if (!_parsed._cursorIdentityScope) {
+          try {
+            const token = resolveCursorToken(provider, incoming.headers);
+            _parsed._cursorIdentityScope = createHash("sha256")
+              .update("ocx:cursor:acct:")
+              .update(token)
+              .digest("hex")
+              .slice(0, 16);
+          } catch {
+            /* Missing credential is handled by the live transport path below. */
+          }
+        }
         const previousConversationId = _parsed._cursorConversationId;
         let request = createCursorRequest(_parsed);
-        // Keep remembered conversation id in sync when the request builder mints a fresh id
-        // for external-model tool-result continuations (stateless replay).
-        if (request.conversationId !== previousConversationId) {
+        // The builder may derive a stable provider id from the client thread when Responses state
+        // is unavailable. Rekey only existing state; there is nothing to migrate on a fresh turn,
+        // and isolated helper/compaction turns must never inherit or donate the parent's usage state.
+        if (
+          previousConversationId
+          && request.conversationId !== previousConversationId
+          && _parsed._cursorIsolateConversation !== true
+        ) {
           rekeyContextUsage(previousConversationId, request.conversationId);
         }
         _parsed._cursorConversationId = request.conversationId;
         let emittedOutput = false;
+        let replayUnsafe = false;
         const lastRawIsToolResult = _parsed.context.messages.at(-1)?.role === "toolResult";
 
         const runOnce = async (activeRequest: ReturnType<typeof createCursorRequest>) => {
@@ -104,6 +127,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
                 emit({ type: "error", message: "Cursor turn was aborted." });
                 return;
               }
+              if (message.type === "local_side_effect") replayUnsafe = true;
               const events = mapCursorServerMessage(message, {
                 kv,
                 writeClient: clientMessage => {
@@ -121,14 +145,15 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         try {
           await runOnce(request);
         } catch (err) {
-          // One-shot fallback: only for external-model tool-result continuations that fail
-          // with Connect invalid_argument before any non-heartbeat output was forwarded.
-          // Replaying after text/tool events would duplicate output.
+          // One-shot fallback for external-model Connect invalid_argument before any
+          // non-heartbeat output. Retries apply only to safe plain-user turns; tool-result
+          // resumes, local exec/MCP side effects, and already-emitted output fail closed.
           if (
             !isCursorInvalidArgumentError(err)
             || !isCursorExternalWireModel(request.modelId)
-            || !lastRawIsToolResult
+            || lastRawIsToolResult
             || emittedOutput
+            || replayUnsafe
             || incoming.abortSignal?.aborted
           ) {
             throw err;
@@ -138,6 +163,16 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           request = createCursorRequest(_parsed, { forceFreshConversation: true });
           rekeyContextUsage(failedConversationId, request.conversationId);
           _parsed._cursorConversationId = request.conversationId;
+          // Persist recovery for store:false clients that only send a parent thread id, so the
+          // next turn does not recompute the stale deterministic thread hash. Isolated helper /
+          // compaction turns must not park their throwaway id under the parent thread key.
+          if (_parsed._clientThreadId && _parsed._cursorIsolateConversation !== true) {
+            rememberCursorThreadConversation(
+              _parsed._clientThreadId,
+              request.conversationId,
+              _parsed._cursorIdentityScope,
+            );
+          }
           await runOnce(request);
         }
       } catch (err) {