@bitkyc08/opencodex 2.28.0 → 2.29.0

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

@@ -9,7 +9,7 @@ import type {
 } from "../../types";
 import { isAllowedToolChoice, namespacedToolName, toolChoiceAliases, type OcxTool, type OcxToolChoice } from "../../types";
 import type { CursorRequestMessage, CursorRequestedModelParameter, CursorRunRequest } from "./types";
-import { cursorWireModelSelection, type CursorRoutingLevel } from "./discovery";
+import { cursorCheckpointModelAffinityId, cursorWireModelSelection, type CursorRoutingLevel } from "./discovery";
 import { cursorEffortSuffix, cursorRequestWireModelIdWithEffort } from "./effort-map";
 import {
   cursorMcpToolEncodedSize,
@@ -25,6 +25,12 @@ import {
   isCursorWaitTool,
 } from "./tool-definitions";
 import { lookupCursorThreadConversation } from "./thread-continuity";
+import {
+  getCursorCheckpoint,
+  getCursorCheckpointForPrefix,
+  type CursorCheckpointInvalidationReason,
+  type CursorCheckpointSnapshot,
+} from "./checkpoint-store";
 
 /** Probe-verified Cursor Connect boundaries, with byte headroom for the enclosing field. */
 export const CURSOR_TOOL_COUNT_LIMIT = 330;
@@ -285,24 +291,120 @@ export function resolveCursorConversationId(
   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 cursorConversationIdFromClientThread(`thread:${threadId}`, parsed._cursorIdentityScope);
   }
   return generatedCursorConversationId();
 }
 
+function updateFramed(hash: ReturnType<typeof createHash>, value: string): void {
+  const bytes = Buffer.from(value, "utf8");
+  const length = Buffer.allocUnsafe(4);
+  length.writeUInt32BE(bytes.byteLength);
+  hash.update(length);
+  hash.update(bytes);
+}
+
+export function cursorInstructionDigest(parsed: OcxParsedRequest): string {
+  const hash = createHash("sha256").update("ocx:cursor:sys:");
+  for (const line of parsed.context.systemPrompt ?? []) updateFramed(hash, line);
+  for (const message of parsed.context.messages) {
+    if (message.role !== "developer") continue;
+    updateFramed(hash, contentToText(message.content));
+  }
+  return hash.digest("hex");
+}
+
+export function cursorCoveredPrefixDigest(parsed: OcxParsedRequest, coveredMessageCount: number): string {
+  const hash = createHash("sha256").update("ocx:cursor:prefix:");
+  updateFramed(hash, cursorInstructionDigest(parsed));
+  for (const message of parsed.context.messages.slice(0, coveredMessageCount)) {
+    updateFramed(hash, message.role);
+    updateFramed(hash, contentToText(message.content));
+  }
+  return hash.digest("hex");
+}
+
 export interface CreateCursorRequestOptions {
   /** Force a brand-new Cursor conversation id even when remembered state exists. */
   forceFreshConversation?: boolean;
 }
 
+function lookupPrefixSnapshot(
+  parsed: OcxParsedRequest,
+  request: CursorRunRequest,
+  identityScope: string,
+): CursorCheckpointSnapshot | undefined {
+  const systemDigest = cursorInstructionDigest(parsed);
+  const modelId = cursorCheckpointModelAffinityId(request.modelId);
+  for (let covered = parsed.context.messages.length; covered >= 1; covered--) {
+    const snapshot = getCursorCheckpointForPrefix({
+      prefixDigest: cursorCoveredPrefixDigest(parsed, covered),
+      systemDigest,
+      coveredMessageCount: covered,
+      identityScope,
+      modelId,
+    });
+    if (snapshot) return snapshot;
+  }
+  return undefined;
+}
+
+function lineageMismatch(
+  parsed: OcxParsedRequest,
+  snapshot: CursorCheckpointSnapshot,
+): CursorCheckpointInvalidationReason | undefined {
+  const covered = snapshot.coveredMessageCount;
+  if (covered === undefined || covered < 0 || covered > parsed.context.messages.length) {
+    return "lineage_mismatch";
+  }
+  if (!snapshot.prefixDigest || !snapshot.systemDigest) return "lineage_mismatch";
+  if (snapshot.systemDigest !== cursorInstructionDigest(parsed)) return "lineage_mismatch";
+  if (snapshot.prefixDigest !== cursorCoveredPrefixDigest(parsed, covered)) return "lineage_mismatch";
+  const lastRole = parsed.context.messages.at(-1)?.role;
+  if (lastRole === "toolResult" && covered >= parsed.context.messages.length) return "trailing_tool_result";
+  return undefined;
+}
+
+function resolveCursorCheckpoint(
+  parsed: OcxParsedRequest,
+  request: CursorRunRequest,
+  options: CreateCursorRequestOptions,
+): { snapshot: CursorCheckpointSnapshot } | { reason: CursorCheckpointInvalidationReason } {
+  if (options.forceFreshConversation === true) return { reason: "force_fresh" };
+  if (parsed._compactionRequest === true || parsed._contextCompactionBoundary === true) return { reason: "compaction" };
+  const isolated = parsed._cursorIsolateConversation === true;
+  const cursorState = parsed._providerContinuation?.cursor;
+  const ref = isolated ? undefined : cursorState?.checkpointRef;
+  const identityScope = parsed._cursorIdentityScope?.trim() || "local";
+  let snapshot: CursorCheckpointSnapshot | undefined;
+  if (ref) {
+    snapshot = getCursorCheckpoint(ref);
+    if (!snapshot) return { reason: "expired" };
+  } else {
+    snapshot = lookupPrefixSnapshot(parsed, request, identityScope);
+    if (!snapshot) return { reason: "missing_ref" };
+  }
+  if (!isolated && snapshot.conversationId !== request.conversationId && ref) {
+    return { reason: "conversation_changed" };
+  }
+  if (snapshot.identityScope !== identityScope) return { reason: "identity_changed" };
+  if (cursorCheckpointModelAffinityId(snapshot.modelId) !== cursorCheckpointModelAffinityId(request.modelId)) {
+    return { reason: "model_changed" };
+  }
+  if (parsed.context.messages.at(-1)?.role !== "toolResult" && cursorState?.checkpointUsable === false) {
+    return { reason: "trailing_tool_result" };
+  }
+  const lineage = lineageMismatch(parsed, snapshot);
+  if (lineage) return { reason: lineage };
+  return { snapshot };
+}
+
 export function createCursorRequest(
   parsed: OcxParsedRequest,
   options: CreateCursorRequestOptions = {},
@@ -315,7 +417,7 @@ 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);
-  return {
+  const request: CursorRunRequest = {
     modelId: model.modelId,
     ...(model.requestedModelParameters ? { requestedModelParameters: model.requestedModelParameters } : {}),
     ...(model.routingLevel ? { routingLevel: model.routingLevel } : {}),
@@ -329,4 +431,16 @@ export function createCursorRequest(
     ...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
     ...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),
   };
+  const resolved = resolveCursorCheckpoint(parsed, request, options);
+  if ("reason" in resolved) {
+    request.continuationMode = "full-replay";
+    request.checkpointInvalidationReason = resolved.reason;
+    return request;
+  }
+  request.checkpointBytes = resolved.snapshot.checkpointBytes;
+  request.continuationMode = "checkpoint";
+  if (parsed.context.messages.at(-1)?.role === "toolResult" && resolved.snapshot.coveredMessageCount !== undefined) {
+    request.checkpointSuffixStart = resolved.snapshot.coveredMessageCount;
+  }
+  return request;
 }

package/src/adapters/cursor/transport.ts

@@ -12,6 +12,11 @@ export interface CursorTransport {
    * accepted is never replayed. Absent (undefined) is treated as "committed" — safe by default.
    */
   requestCommitted?(): boolean;
+  /**
+   * Last ConversationStateStructure captured from conversationCheckpointUpdate on this transport.
+   * Test and adapter seams use this instead of reaching into LiveCursorTransport.
+   */
+  capturedConversationCheckpoint?(): Uint8Array | undefined;
 }
 
 export interface CursorTransportFactoryInput {

package/src/adapters/cursor/types.ts

@@ -1,6 +1,7 @@
 import type { OcxUsage } from "../../types";
 import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
 import type { CursorRoutingLevel } from "./discovery";
+import type { CursorCheckpointInvalidationReason } from "./checkpoint-store";
 
 export interface CursorRequestedModelParameter {
   id: string;
@@ -31,6 +32,18 @@ export interface CursorRunRequest {
    * pre-compaction history being summarized and must not become the next turn's carry-forward total.
    */
   contextUsageStoreCheckpoints?: boolean;
+  /**
+   * Reuse a previously captured ConversationStateStructure instead of rebuilding historical
+   * root/turn blobs. Absent means the existing full-replay path.
+   */
+  checkpointBytes?: Uint8Array;
+  continuationMode?: "full-replay" | "checkpoint";
+  checkpointInvalidationReason?: CursorCheckpointInvalidationReason;
+  /**
+   * When set with checkpointBytes, only this suffix of rawMessages is replayed onto the
+   * decoded ConversationStateStructure. Used for tool-result continuations.
+   */
+  checkpointSuffixStart?: number;
 }
 
 export interface CursorRequestMessage {

package/src/adapters/cursor.ts

@@ -4,16 +4,27 @@ import type { ProviderAdapter } from "./base";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
 import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
 import { isCursorBenignCancelError, isCursorInvalidArgumentError, safeCursorErrorMessage } from "./cursor/cursor-errors";
-import { isCursorExternalWireModel } from "./cursor/discovery";
+import { cursorCheckpointModelAffinityId, isCursorExternalWireModel } from "./cursor/discovery";
 import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
-import { createCursorRequest } from "./cursor/request-builder";
+import {
+  createCursorRequest,
+  cursorCoveredPrefixDigest,
+  cursorInstructionDigest,
+} from "./cursor/request-builder";
 import {
   createLiveCursorTransport,
   CursorMissingCredentialError,
   rekeyCursorContextUsage,
   resolveCursorToken,
+  capturedCursorCheckpointBytes,
 } from "./cursor/live-transport";
+import {
+  commitCursorCheckpoint,
+  cursorCheckpointRefHash,
+  invalidateCursorCheckpoint,
+} from "./cursor/checkpoint-store";
+import { debugProviderDiagnostic } from "../lib/debug";
 import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
 import { runCursorTurnWithRetry } from "./cursor/transport-retry";
 import {
@@ -96,6 +107,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             /* Missing credential is handled by the live transport path below. */
           }
         }
+        const inheritedCheckpointRef = _parsed._providerContinuation?.cursor?.checkpointRef;
         const previousConversationId = _parsed._cursorConversationId;
         let request = createCursorRequest(_parsed);
         // The builder may derive a stable provider id from the client thread when Responses state
@@ -112,6 +124,48 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         let emittedOutput = false;
         let replayUnsafe = false;
         const lastRawIsToolResult = _parsed.context.messages.at(-1)?.role === "toolResult";
+        let completedNormally = false;
+        let lastTransport: { captured?: Uint8Array } | undefined;
+        let emittedClientTool = false;
+
+        const commitCapturedCheckpoint = (activeRequest: ReturnType<typeof createCursorRequest>): void => {
+          if (
+            replayUnsafe
+            || emittedClientTool
+            || activeRequest.contextUsageStoreCheckpoints === false
+            || !lastTransport?.captured
+            || lastTransport.captured.byteLength === 0
+          ) return;
+          const previousRef = _parsed._providerContinuation?.cursor?.checkpointRef;
+          const coveredMessageCount = _parsed.context.messages.length;
+          const checkpointRef = commitCursorCheckpoint({
+            conversationId: activeRequest.conversationId,
+            identityScope: _parsed._cursorIdentityScope,
+            modelId: cursorCheckpointModelAffinityId(activeRequest.modelId),
+            checkpointBytes: lastTransport.captured,
+            coveredMessageCount,
+            prefixDigest: cursorCoveredPrefixDigest(_parsed, coveredMessageCount),
+            systemDigest: cursorInstructionDigest(_parsed),
+          });
+          if (!checkpointRef) return;
+          if (previousRef && previousRef !== checkpointRef) invalidateCursorCheckpoint(previousRef);
+          _parsed._providerContinuation = {
+            ...(_parsed._providerContinuation ?? {}),
+            cursor: {
+              ...(_parsed._providerContinuation?.cursor ?? {}),
+              conversationId: activeRequest.conversationId,
+              checkpointUsable: true,
+              checkpointRef,
+            },
+          };
+          debugProviderDiagnostic("cursor", "checkpoint-continuation", {
+            mode: activeRequest.continuationMode ?? "full-replay",
+            conversationHash: activeRequest.conversationId.slice(0, 16),
+            checkpointRefHash: cursorCheckpointRefHash(checkpointRef),
+            checkpointBytes: lastTransport.captured.byteLength,
+            wireModel: activeRequest.modelId,
+          });
+        };
 
         const runOnce = async (activeRequest: ReturnType<typeof createCursorRequest>) => {
           await runCursorTurnWithRetry(
@@ -132,6 +186,10 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
                 return;
               }
               if (message.type === "local_side_effect") replayUnsafe = true;
+              if (message.type === "done") completedNormally = true;
+              if (message.type === "tool_call_end") emittedClientTool = true;
+              const captured = capturedCursorCheckpointBytes(activeTransport);
+              if (captured) lastTransport = { captured };
               const events = mapCursorServerMessage(message, {
                 kv,
                 writeClient: clientMessage => {
@@ -140,7 +198,28 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               });
               for (const event of events) {
                 if (event.type !== "heartbeat") emittedOutput = true;
-                emit(event);
+                if (event.type === "done") {
+                  commitCapturedCheckpoint(activeRequest);
+                  const inheritedCursor = _parsed._providerContinuation?.cursor;
+                  const isolatedOrCompaction =
+                    _parsed._cursorIsolateConversation === true
+                    || activeRequest.contextUsageStoreCheckpoints === false;
+                  const providerState = inheritedCursor
+                    ? {
+                        cursor: isolatedOrCompaction
+                          ? {
+                              conversationId: activeRequest.conversationId,
+                              ...(inheritedCursor.checkpointUsable !== undefined
+                                ? { checkpointUsable: inheritedCursor.checkpointUsable }
+                                : {}),
+                            }
+                          : { ...inheritedCursor, conversationId: activeRequest.conversationId },
+                      }
+                    : undefined;
+                  emit(providerState ? { ...event, providerState } : event);
+                } else {
+                  emit(event);
+                }
               }
             },
           );
@@ -163,6 +242,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             throw err;
           }
           const failedConversationId = request.conversationId;
+          lastTransport = undefined;
           _parsed._cursorConversationId = undefined;
           request = createCursorRequest(_parsed, { forceFreshConversation: true });
           rekeyContextUsage(failedConversationId, request.conversationId);
@@ -179,6 +259,32 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           }
           await runOnce(request);
         }
+        if (
+          request.checkpointInvalidationReason
+          && request.checkpointInvalidationReason !== "missing_ref"
+        ) {
+          invalidateCursorCheckpoint(inheritedCheckpointRef);
+          debugProviderDiagnostic("cursor", "checkpoint-invalidated", {
+            reason: request.checkpointInvalidationReason,
+          });
+        } else if (!completedNormally && request.checkpointInvalidationReason) {
+          debugProviderDiagnostic("cursor", "checkpoint-invalidated", {
+            reason: request.checkpointInvalidationReason,
+          });
+        }
+        if (
+          _parsed._cursorIsolateConversation === true
+          || request.contextUsageStoreCheckpoints === false
+        ) {
+          const inherited = _parsed._providerContinuation?.cursor;
+          if (inherited) {
+            const { checkpointRef: _ignoredCheckpointRef, ...cursorWithoutCheckpointRef } = inherited;
+            _parsed._providerContinuation = {
+              ...(_parsed._providerContinuation ?? {}),
+              cursor: cursorWithoutCheckpointRef,
+            };
+          }
+        }
       } catch (err) {
         if (isCursorBenignCancelError(err)) return;
         const partialUsage = (err as { partialUsage?: import("../types").OcxUsage }).partialUsage;

package/src/adapters/google-antigravity-replay.ts

@@ -702,11 +702,38 @@ export function applyAntigravityReplay(model: string, sessionId: string, content
       if (!fc) continue;
       if (part.thoughtSignature !== undefined || part.thought_signature !== undefined) continue;
       const ck = functionCallKey(fc.name, fc.args);
-      const call = ck ? entry.byCall.get(ck) : undefined;
-      if (call && ck) {
+      let call = ck ? entry.byCall.get(ck) : undefined;
+      let matchedKey = ck;
+      if (!call && typeof fc.name === "string" && typeof fc.args === "object" && fc.args !== null) {
+        // Freeform / custom tool replay unwrap:
+        // The client replays custom_tool_call with arguments: { input: "..." }.
+        // Upstream was invoked with args: { input: "..." } or raw string or parsed JSON.
+        const argsObj = fc.args as Record<string, unknown>;
+        if (typeof argsObj.input === "string") {
+          const trimmedInput = argsObj.input.trim();
+          if (
+            trimmedInput.length <= REPLAY_MAX_CANONICAL_ARGS_BYTES
+            && utf8.encode(trimmedInput).byteLength <= REPLAY_MAX_CANONICAL_ARGS_BYTES
+          ) {
+            try {
+              const parsedInput = JSON.parse(trimmedInput);
+            if (parsedInput && typeof parsedInput === "object") {
+              const altKey = functionCallKey(fc.name, parsedInput);
+              if (altKey && entry.byCall.has(altKey)) {
+                call = entry.byCall.get(altKey);
+                matchedKey = altKey;
+              }
+            }
+            } catch {
+              // not JSON, keep default
+            }
+          }
+        }
+      }
+      if (call && matchedKey) {
         part.thoughtSignature = call.signature;
-        entry.byCall.delete(ck);
-        entry.byCall.set(ck, { ...call, touchedAtMs: now });
+        entry.byCall.delete(matchedKey);
+        entry.byCall.set(matchedKey, { ...call, touchedAtMs: now });
         touched = true;
       }
     }