@iislee/opencodex 2.11.0 → 2.31.0

package/src/adapters/cursor/native-exec-common.ts

@@ -1,6 +1,7 @@
 import { create, toBinary } from "@bufbuild/protobuf";
 import {
   AgentClientMessageSchema,
+  ExecClientThrowSchema,
   ExecClientControlMessageSchema,
   ExecClientMessageSchema,
   ExecClientStreamCloseSchema,
@@ -15,14 +16,18 @@ export function clientBytes(message: Parameters<typeof create<typeof AgentClient
   return toBinary(AgentClientMessageSchema, create(AgentClientMessageSchema, message));
 }
 
-export function execBytes(execMsg: ExecServerMessage, messageCase: ExecClientMessage["message"]["case"], value: unknown): Uint8Array {
+export function execBytes<K extends ExecClientMessage["message"]["case"]>(
+  execMsg: ExecServerMessage,
+  messageCase: K,
+  value: Extract<ExecClientMessage["message"], { case: K }>["value"],
+): Uint8Array {
   return clientBytes({
     message: {
       case: "execClientMessage",
       value: create(ExecClientMessageSchema, {
         id: execMsg.id,
         execId: execMsg.execId,
-        message: { case: messageCase, value: value as never },
+        message: { case: messageCase, value } as ExecClientMessage["message"],
       }),
     },
   });
@@ -45,6 +50,22 @@ export function execStreamCloseBytes(execMsg: ExecServerMessage): Uint8Array {
   });
 }
 
+/**
+ * Exec-channel typed throw (`execClientControlMessage.throw`). senpi's contract (T05):
+ * a frame that cannot be answered at all must get an explicit error reply + stream-close
+ * so the server unblocks with a known failure, instead of waiting forever on silence.
+ */
+export function execThrowBytes(execMsg: ExecServerMessage, error: string): Uint8Array {
+  return clientBytes({
+    message: {
+      case: "execClientControlMessage",
+      value: create(ExecClientControlMessageSchema, {
+        message: { case: "throw", value: create(ExecClientThrowSchema, { id: execMsg.id, error }) },
+      }),
+    },
+  });
+}
+
 export function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }

package/src/adapters/cursor/native-exec-fs.ts

@@ -39,12 +39,15 @@ const MAX_GREP_FILES = 500;
 const MAX_GREP_RESULTS = 200;
 const MAX_FILE_BYTES = 1_000_000;
 
-function codexNativeMutationRefusal(operation: "write" | "delete"): string {
-  return `Cursor-native ${operation} is disabled for this Codex request because apply_patch is available. Use the apply_patch tool for file edits so Codex can approve the change, enforce sandbox policy, show diffs, and record rollout. No file was changed.`;
+function codexNativeMutationRefusal(operation: "write" | "delete", structuredEditAvailable: boolean): string {
+  const structuredHint = structuredEditAvailable
+    ? " Use the structured edit tools (`edit_file` / `multi_edit`) or the `apply_patch` tool for file edits so Codex can approve the change, enforce sandbox policy, show diffs, and record rollout."
+    : " Use the `apply_patch` tool for file edits so Codex can approve the change, enforce sandbox policy, show diffs, and record rollout.";
+  return `Cursor-native ${operation} is disabled for this Codex request because apply_patch is available.${structuredHint} No file was changed.`;
 }
 
 const NATIVE_LOCAL_EXEC_DISABLED =
-  "Route filesystem work through the Codex Responses bridge shell tool (`shell_command` / `exec_command`, or the listed `mcp_opencodex-responses_*` display alias) with equivalent shell commands (cat, head, ls, rg, grep), or `apply_patch` for file edits. Do not tell the user shell or read access is blocked, disabled, or denied — silently call that bridge tool.";
+  "Cursor-native filesystem tools are not executed locally. Use a catalog tool for this work: `shell_command` / `exec_command` (or the listed `mcp_opencodex-responses_*` display alias) with host-shell-safe equivalents: POSIX (`cat`, `head`, `ls`, `rg`, `grep`) or Windows PowerShell (`Get-Content`, `Get-ChildItem`, `Select-String`); use `apply_patch` for file edits.";
 
 export function rejectReadExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
   if (execMsg.message.case !== "readArgs") throw new Error("invalid read exec");
@@ -84,13 +87,13 @@ export function readExec(execMsg: ExecServerMessage): Uint8Array {
   }
 }
 
-export function rejectWriteExecForApplyPatch(execMsg: ExecServerMessage): Uint8Array {
+export function rejectWriteExecForApplyPatch(execMsg: ExecServerMessage, structuredEditAvailable = false): Uint8Array {
   if (execMsg.message.case !== "writeArgs") throw new Error("invalid write exec");
   const path = resolve(execMsg.message.value.path);
   return execBytes(execMsg, "writeResult", create(WriteResultSchema, {
     result: {
       case: "rejected",
-      value: create(WriteRejectedSchema, { path, reason: codexNativeMutationRefusal("write") }),
+      value: create(WriteRejectedSchema, { path, reason: codexNativeMutationRefusal("write", structuredEditAvailable) }),
     },
   }));
 }
@@ -133,13 +136,13 @@ export function writeExec(execMsg: ExecServerMessage): Uint8Array {
   }
 }
 
-export function rejectDeleteExecForApplyPatch(execMsg: ExecServerMessage): Uint8Array {
+export function rejectDeleteExecForApplyPatch(execMsg: ExecServerMessage, structuredEditAvailable = false): Uint8Array {
   if (execMsg.message.case !== "deleteArgs") throw new Error("invalid delete exec");
   const path = resolve(execMsg.message.value.path);
   return execBytes(execMsg, "deleteResult", create(DeleteResultSchema, {
     result: {
       case: "rejected",
-      value: create(DeleteRejectedSchema, { path, reason: codexNativeMutationRefusal("delete") }),
+      value: create(DeleteRejectedSchema, { path, reason: codexNativeMutationRefusal("delete", structuredEditAvailable) }),
     },
   }));
 }

package/src/adapters/cursor/native-exec-network.ts

@@ -7,7 +7,7 @@ export interface CursorNativeNetworkDeps {
 }
 
 const NATIVE_FETCH_DISABLED =
-  "Route this through the Codex shell bridge tool `shell_command` (aliases: `exec_command`, `mcp_opencodex-responses_shell_command`, `mcp_opencodex-responses_exec_command`) with curl or wget. Do not tell the user network or shell access is blocked, disabled, or denied — silently call that bridge tool.";
+  "Cursor-native fetch is not executed locally. Use the Codex shell bridge tool `shell_command` (aliases: `exec_command`, `mcp_opencodex-responses_shell_command`, `mcp_opencodex-responses_exec_command`) with curl or wget.";
 
 export function rejectFetchExecForPolicy(execMsg: ExecServerMessage): Uint8Array {
   if (execMsg.message.case !== "fetchArgs") throw new Error("invalid fetch exec");

package/src/adapters/cursor/native-exec-shell.ts

@@ -89,7 +89,6 @@ export function nativeShellDisabledMessage(): string {
   // client that executes the bridge (LAN/SSH remote-proxy).
   return (
     "Route this through the Codex bridge shell tool from the current catalog (`shell_command` or `exec_command`, including the long `mcp_opencodex-responses_*` display name if listed). "
-    + "Do not tell the user shell access is blocked, disabled, or denied — silently call that bridge tool. "
     + "Adapt the command for the Codex client host shell before calling the bridge "
     + "(Windows PowerShell 5.1: no CMD `cd /d`, no bash heredocs; `&&`/`||` are unsupported parser errors — prefer the bridge working-directory argument for directory changes, and use `if ($?) { ... }` for success-gated follow-up steps; do not treat `;` as a substitute for `&&`). "
     + "Make at most one corrected bridge attempt after a failure, then report the error and stop — do not repeat equivalent failing commands."

package/src/adapters/cursor/native-exec.ts

@@ -50,7 +50,7 @@ import {
   recordScreenExec,
   type CursorNativeToolDeps,
 } from "./native-exec-tools";
-import { clientBytes, execBytes } from "./native-exec-common";
+import { clientBytes, execBytes, execStreamCloseBytes, execThrowBytes } from "./native-exec-common";
 import type { McpToolDefinition } from "./gen/agent_pb";
 import { OCX_RESPONSES_TOOL_PROVIDER } from "./tool-definitions";
 
@@ -70,6 +70,8 @@ export interface CursorNativeExecContext extends CursorNativeExecDeps {
   unsafeAllowNativeLocalExec?: boolean;
   /** apply_patch is visible for this request; Cursor-native write/delete must not bypass Codex. */
   rejectNativeFileMutations?: boolean;
+  /** The synthetic exact-match edit tools (edit_file / multi_edit) are advertised this request. */
+  structuredEditAvailable?: boolean;
 }
 
 export function cursorUnsafeNativeLocalExecEnabled(input: Pick<CursorNativeExecContext, "unsafeAllowNativeLocalExec"> = {}): boolean {
@@ -115,6 +117,7 @@ interface CursorBlobLimits {
 interface CursorBlobRequestScopeState {
   keys: Set<string>;
   sealed: boolean;
+  kind: "request" | "checkpoint";
 }
 
 const DEFAULT_BLOB_LIMITS: CursorBlobLimits = {
@@ -128,6 +131,8 @@ const blobs = new Map<string, CursorBlobEntry>();
 const blobRequestScopes = new Map<CursorBlobRequestScopeToken, CursorBlobRequestScopeState>();
 let blobLimits = { ...DEFAULT_BLOB_LIMITS };
 let blobBytes = 0;
+/** Retained key-string bytes (separate from the payload cap — see key()). */
+let blobKeyBytes = 0;
 let blobLocalBytes = 0;
 let blobPinnedBytes = 0;
 let blobEvictableBytes = 0;
@@ -152,13 +157,16 @@ function recomputeBlobClassAccounting(): void {
   let pinnedBytes = 0;
   let evictableBytes = 0;
   let oldestAt: number | null = null;
-  for (const entry of blobs.values()) {
+  for (const [k, entry] of blobs) {
     const requestPinned = entry.requestPins.size > 0;
     const provenancePinned = entry.provenance === "remote-setBlobArgs" && !isExpired(entry, now);
     if (entry.provenance === "local-regenerated") localBytes += entry.sizeBytes;
-    if (requestPinned || provenancePinned) pinnedBytes += entry.sizeBytes;
+    // Key strings classify WITH their entry: a zero-payload blob must stay
+    // evictable/pinned exactly as its payload would be, or the budget cannot
+    // select it even though the total snapshot counts its key.
+    if (requestPinned || provenancePinned) pinnedBytes += entry.sizeBytes + k.length;
     if (!requestPinned && (entry.provenance === "local-regenerated" || isExpired(entry, now))) {
-      evictableBytes += entry.sizeBytes;
+      evictableBytes += entry.sizeBytes + k.length;
       oldestAt = oldestAt === null ? entry.storedAt : Math.min(oldestAt, entry.storedAt);
     }
   }
@@ -196,9 +204,12 @@ function deleteBlob(k: string, recompute = true): number {
   if (!entry) return 0;
   blobs.delete(k);
   blobBytes -= entry.sizeBytes;
+  blobKeyBytes -= k.length;
   for (const scope of entry.requestPins) blobRequestScopes.get(scope)?.keys.delete(k);
   if (recompute) recomputeBlobClassAccounting();
-  return entry.sizeBytes;
+  // Full logical release (payload + key): the retained-store snapshot counts
+  // both, so budget enforcement must see both leave.
+  return entry.sizeBytes + k.length;
 }
 
 function releaseHydratedBlob(k: string, requestScope?: CursorBlobRequestScopeToken): void {
@@ -313,6 +324,7 @@ function setBlob(
   if (blobs.has(k)) deleteBlob(k, false);
   blobs.set(k, entry);
   blobBytes += entry.sizeBytes;
+  blobKeyBytes += k.length;
   for (const scope of entry.requestPins) blobRequestScopes.get(scope)?.keys.add(k);
   reconcileBlobClassAccountingAndEnforce();
   return { admitted: true, replaced: existing !== undefined };
@@ -328,8 +340,20 @@ function getBlob(k: string): Uint8Array | undefined {
   return entry.data;
 }
 
+/**
+ * Raw blob IDs up to this size keep their hex passthrough (every ID the live
+ * protocol carries is a 32-byte digest). Anything larger maps to a fixed-size
+ * SHA-256 hex of the raw bytes — the derivation is symmetric across
+ * setBlobArgs/getBlobArgs, so the round-trip still works, but a hostile or
+ * malformed multi-MiB ID can never become an unbounded hex Map key.
+ * The `h:`/`d:` prefix domain-separates the two namespaces: a digested ID's
+ * key can never collide with a raw 32-byte ID that happens to BE that digest.
+ */
+const MAX_BLOB_ID_PASSTHROUGH_BYTES = 64;
+
 function key(bytes: Uint8Array): string {
-  return Buffer.from(bytes).toString("hex");
+  if (bytes.byteLength <= MAX_BLOB_ID_PASSTHROUGH_BYTES) return `h:${Buffer.from(bytes).toString("hex")}`;
+  return `d:${createHash("sha256").update(bytes).digest("hex")}`;
 }
 
 /**
@@ -353,7 +377,7 @@ export function createCursorBlobRequestScope(): CursorBlobRequestScopeToken {
   // IDENTITY, not just pin counts (review C2-2: identical descriptions made
   // scope-swap bugs invisible to deep comparison).
   const scope = Symbol(`cursor-blob-request-${++blobScopeSequence}`);
-  blobRequestScopes.set(scope, { keys: new Set(), sealed: false });
+  blobRequestScopes.set(scope, { keys: new Set(), sealed: false, kind: "request" });
   return scope;
 }
 
@@ -379,9 +403,52 @@ export function storeCursorBlob(data: Uint8Array, requestScope?: CursorBlobReque
   return blobId;
 }
 
+/**
+ * Long-lived pin for blobs referenced by an active Cursor conversation checkpoint.
+ * Unlike a request scope, this lease is not sealed and is not released by getBlob hydration.
+ */
+export function createCursorBlobCheckpointLease(label: string): CursorBlobRequestScopeToken {
+  const scope = Symbol("cursor-blob-checkpoint-" + (++blobScopeSequence) + "-" + label.slice(0, 16));
+  blobRequestScopes.set(scope, { keys: new Set(), sealed: false, kind: "checkpoint" });
+  return scope;
+}
+
+export function pinCursorBlobIdsForCheckpoint(
+  blobIds: readonly Uint8Array[],
+  lease: CursorBlobRequestScopeToken,
+): boolean {
+  const state = blobRequestScopes.get(lease);
+  if (!state || state.sealed) return false;
+  const added: Array<{ entry: { requestPins: Set<CursorBlobRequestScopeToken> }; key: string }> = [];
+  for (const blobId of blobIds) {
+    if (blobId.byteLength === 0) continue;
+    const k = key(blobId);
+    const entry = blobs.get(k);
+    if (!entry || (isExpired(entry, Date.now()) && entry.requestPins.size === 0 && entry.provenance !== "remote-setBlobArgs")) {
+      for (const pinned of added) {
+        pinned.entry.requestPins.delete(lease);
+        state.keys.delete(pinned.key);
+      }
+      return false;
+    }
+    if (!entry.requestPins.has(lease)) {
+      entry.requestPins.add(lease);
+      state.keys.add(k);
+      added.push({ entry, key: k });
+    }
+  }
+  reconcileBlobClassAccountingAndEnforce();
+  return true;
+}
+
+export function hasCursorBlob(blobId: Uint8Array): boolean {
+  return getBlob(key(blobId)) !== undefined;
+}
+
 export interface CursorBlobMetrics {
   count: number;
   totalBytes: number;
+  keyBytes: number;
   localBytes: number;
   pinnedBytes: number;
   rejectedEntryTooLarge: number;
@@ -393,6 +460,7 @@ export function cursorBlobMetrics(): CursorBlobMetrics {
   return {
     count: blobs.size,
     totalBytes: blobBytes,
+    keyBytes: blobKeyBytes,
     localBytes: blobLocalBytes,
     pinnedBytes: blobPinnedBytes,
     rejectedEntryTooLarge,
@@ -410,7 +478,9 @@ export function cursorBlobRetainedStoreSnapshot(): {
 } {
   return {
     count: blobs.size,
-    bytes: blobBytes,
+    // Payload + retained key strings: the framework must see everything the
+    // store retains. The 64 MiB admission cap stays payload-only by design.
+    bytes: blobBytes + blobKeyBytes,
     evictableBytes: blobEvictableBytes,
     pinnedBytes: blobPinnedBytes,
     oldestAt: blobOldestEvictableAt,
@@ -434,12 +504,22 @@ export function setCursorBlobLimitsForTests(limits?: Partial<CursorBlobLimits>):
   blobLimits = limits ? { ...DEFAULT_BLOB_LIMITS, ...limits } : { ...DEFAULT_BLOB_LIMITS };
 }
 
+/**
+ * The live per-blob admission ceiling. Callers that build a blob must budget against THIS value
+ * rather than a copy of the constant: the limit is test-overridable, and a hardcoded 16 MiB would
+ * silently drift from admission the moment either side changes.
+ */
+export function cursorBlobMaxEntryBytes(): number {
+  return blobLimits.maxEntryBytes;
+}
+
 export function resetCursorBlobStateForTests(): void {
   if (blobExpiryAccountingTimer) clearTimeout(blobExpiryAccountingTimer);
   blobExpiryAccountingTimer = undefined;
   blobs.clear();
   blobRequestScopes.clear();
   blobBytes = 0;
+  blobKeyBytes = 0;
   rejectedEntryTooLarge = 0;
   rejectedPinnedSaturation = 0;
   recomputeBlobClassAccounting();
@@ -488,8 +568,8 @@ export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: C
     if (execCase === "fetchArgs") return [rejectFetchExecForPolicy(execMsg)];
   }
   if (execCase === "readArgs") return [readExec(execMsg)];
-  if (execCase === "writeArgs") return [deps.rejectNativeFileMutations ? rejectWriteExecForApplyPatch(execMsg) : writeExec(execMsg)];
-  if (execCase === "deleteArgs") return [deps.rejectNativeFileMutations ? rejectDeleteExecForApplyPatch(execMsg) : deleteExec(execMsg)];
+  if (execCase === "writeArgs") return [deps.rejectNativeFileMutations ? rejectWriteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true) : writeExec(execMsg)];
+  if (execCase === "deleteArgs") return [deps.rejectNativeFileMutations ? rejectDeleteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true) : deleteExec(execMsg)];
   if (execCase === "lsArgs") return [lsExec(execMsg)];
   if (execCase === "grepArgs") return [grepExec(execMsg)];
   if (execCase === "shellArgs") return [shellExec(execMsg)];
@@ -523,10 +603,15 @@ export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: C
     }))];
   }
   // Unknown exec case — Cursor added a new native exec type that our protobuf definition does not
-  // include yet. Return an empty reply so the stream stays alive instead of throwing (which kills
-  // the entire gRPC connection via failAndClear). Same class of bug as #116.
+  // include yet. T05 (senpi contract): reply with ExecClientThrow + stream-close so the server
+  // unblocks with a known failure. Previously this returned an empty reply (silence), which is
+  // the stall class senpi explicitly refused (#116 was about throwing into failAndClear and
+  // killing the whole connection; a typed in-band throw does not do that).
   debugProviderDiagnostic("cursor", "unknown-exec-case", { execCase: execCase ?? "unknown", execId: execMsg.execId });
-  return [];
+  return [
+    execThrowBytes(execMsg, "Unknown exec message variant; this client does not implement it."),
+    execStreamCloseBytes(execMsg),
+  ];
 }
 
 
@@ -537,7 +622,9 @@ export function handleCursorNativeKv(
   if (kvMsg.message.case === "getBlobArgs") {
     const blobKey = key(kvMsg.message.value.blobId);
     const blobData = getBlob(blobKey);
-    if (blobData) releaseHydratedBlob(blobKey, requestScope);
+    if (blobData && requestScope && blobRequestScopes.get(requestScope)?.kind === "request") {
+      releaseHydratedBlob(blobKey, requestScope);
+    }
     return clientBytes({
       message: {
         case: "kvClientMessage",