Skip to content

Commit 1ffee21

Browse files
committed
fix(cursor): pin store:false chat hops and helper-owned cache
Chat Completions / Codex Sol hops often omit previous_response_id and thread headers, so every hop minted a new conversation and missed the checkpoint store. Pin those hops to the first user text and reuse the live snapshot. Isolated helpers keep their own cache and stay off the parent thread. Refs #1527
1 parent 766b81a commit 1ffee21

6 files changed

Lines changed: 237 additions & 43 deletions

File tree

‎src/adapters/cursor.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,6 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
127127
if (
128128
replayUnsafe
129129
|| emittedClientTool
130-
|| _parsed._cursorIsolateConversation === true
131130
|| activeRequest.contextUsageStoreCheckpoints === false
132131
|| !lastTransport?.captured
133132
|| lastTransport.captured.byteLength === 0
@@ -253,7 +252,6 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
253252
if (
254253
request.checkpointInvalidationReason
255254
&& request.checkpointInvalidationReason !== "missing_ref"
256-
&& request.checkpointInvalidationReason !== "isolated_turn"
257255
&& request.checkpointInvalidationReason !== "compaction"
258256
) {
259257
invalidateCursorCheckpoint(_parsed._providerContinuation?.cursor?.checkpointRef);

‎src/adapters/cursor/checkpoint-store.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@ export type CursorCheckpointInvalidationReason =
2020
| "identity_changed"
2121
| "model_changed"
2222
| "compaction"
23-
| "isolated_turn"
2423
| "trailing_tool_result"
2524
| "force_fresh"
2625
| "upstream_invalid_argument";
@@ -149,6 +148,17 @@ export function commitCursorCheckpoint(input: {
149148
return store.snapshots.has(ref) ? ref : undefined;
150149
}
151150

151+
export function getLatestCursorCheckpoint(
152+
match: (snapshot: CursorCheckpointSnapshot) => boolean,
153+
): CursorCheckpointSnapshot | undefined {
154+
prune();
155+
let found: CursorCheckpointSnapshot | undefined;
156+
for (const snapshot of store.snapshots.values()) {
157+
if (match(snapshot)) found = snapshot;
158+
}
159+
return found ? getCursorCheckpoint(found.ref) : undefined;
160+
}
161+
152162
export function getCursorCheckpoint(ref: string | undefined): CursorCheckpointSnapshot | undefined {
153163
if (!ref) return undefined;
154164
prune();

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

Lines changed: 52 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,9 @@ import {
2727
import { lookupCursorThreadConversation } from "./thread-continuity";
2828
import {
2929
getCursorCheckpoint,
30+
getLatestCursorCheckpoint,
3031
type CursorCheckpointInvalidationReason,
32+
type CursorCheckpointSnapshot,
3133
} from "./checkpoint-store";
3234

3335
/** Probe-verified Cursor Connect boundaries, with byte headroom for the enclosing field. */
@@ -289,53 +291,76 @@ export function resolveCursorConversationId(
289291
options: CreateCursorRequestOptions = {},
290292
): string {
291293
if (options.forceFreshConversation === true) return generatedCursorConversationId();
292-
// Helper/shadow/compaction turns must not append into the parent's Cursor conversation,
293-
// even when previous_response_id restored the parent's remembered id.
294-
if (parsed._cursorIsolateConversation === true) return generatedCursorConversationId();
294+
// Helper/shadow turns must not append into the parent's Cursor conversation, even when
295+
// previous_response_id restored the parent's remembered id. They still keep their own
296+
// cache, keyed off this turn's first user/developer text.
297+
if (parsed._cursorIsolateConversation === true) {
298+
const isolatedSeed = cursorHistorySeed(parsed);
299+
if (isolatedSeed) {
300+
return cursorConversationIdFromClientThread(`isolate:${isolatedSeed}`, parsed._cursorIdentityScope);
301+
}
302+
return generatedCursorConversationId();
303+
}
295304
if (parsed._cursorConversationId) return parsed._cursorConversationId;
296305
const threadId = parsed._clientThreadId?.trim();
297306
if (threadId) {
298307
const recovered = lookupCursorThreadConversation(threadId, parsed._cursorIdentityScope);
299308
if (recovered) return recovered;
300-
return cursorConversationIdFromClientThread(threadId, parsed._cursorIdentityScope);
309+
return cursorConversationIdFromClientThread(`thread:${threadId}`, parsed._cursorIdentityScope);
301310
}
311+
const historySeed = cursorHistorySeed(parsed);
312+
if (historySeed) return cursorConversationIdFromClientThread(`history:${historySeed}`, parsed._cursorIdentityScope);
302313
return generatedCursorConversationId();
303314
}
304315

316+
function cursorHistorySeed(parsed: OcxParsedRequest): string | undefined {
317+
for (const message of parsed.context.messages) {
318+
if (message.role !== "user" && message.role !== "developer") continue;
319+
const text = contentToText(message.content).trim();
320+
if (text) return text;
321+
}
322+
return undefined;
323+
}
324+
305325
export interface CreateCursorRequestOptions {
306326
/** Force a brand-new Cursor conversation id even when remembered state exists. */
307327
forceFreshConversation?: boolean;
308328
}
309329

310-
function checkpointInvalidationReason(
330+
function resolveCursorCheckpoint(
311331
parsed: OcxParsedRequest,
312332
request: CursorRunRequest,
313333
options: CreateCursorRequestOptions,
314-
): CursorCheckpointInvalidationReason | undefined {
315-
if (options.forceFreshConversation === true) return "force_fresh";
316-
if (parsed._cursorIsolateConversation === true) return "isolated_turn";
317-
if (parsed._compactionRequest === true || parsed._contextCompactionBoundary === true) return "compaction";
334+
): { snapshot: CursorCheckpointSnapshot } | { reason: CursorCheckpointInvalidationReason } {
335+
if (options.forceFreshConversation === true) return { reason: "force_fresh" };
336+
if (parsed._compactionRequest === true || parsed._contextCompactionBoundary === true) return { reason: "compaction" };
337+
const isolated = parsed._cursorIsolateConversation === true;
318338
const cursorState = parsed._providerContinuation?.cursor;
319-
const ref = cursorState?.checkpointRef;
320-
if (!ref) return "missing_ref";
321-
const snapshot = getCursorCheckpoint(ref);
322-
if (!snapshot) return "expired";
323-
if (snapshot.conversationId !== request.conversationId) return "conversation_changed";
339+
const ref = isolated ? undefined : cursorState?.checkpointRef;
324340
const identityScope = parsed._cursorIdentityScope?.trim() || "local";
325-
if (snapshot.identityScope !== identityScope) return "identity_changed";
326-
if (cursorCheckpointModelAffinityId(snapshot.modelId) !== cursorCheckpointModelAffinityId(request.modelId)) {
327-
return "model_changed";
341+
const modelAffinity = cursorCheckpointModelAffinityId(request.modelId);
342+
let snapshot = getCursorCheckpoint(ref);
343+
if (!snapshot) {
344+
snapshot = getLatestCursorCheckpoint(candidate =>
345+
candidate.conversationId === request.conversationId
346+
&& candidate.identityScope === identityScope
347+
&& cursorCheckpointModelAffinityId(candidate.modelId) === modelAffinity
348+
);
328349
}
350+
if (!snapshot) return { reason: ref ? "expired" : "missing_ref" };
351+
if (snapshot.conversationId !== request.conversationId) return { reason: "conversation_changed" };
352+
if (snapshot.identityScope !== identityScope) return { reason: "identity_changed" };
353+
if (cursorCheckpointModelAffinityId(snapshot.modelId) !== modelAffinity) return { reason: "model_changed" };
329354
const lastRole = parsed.context.messages.at(-1)?.role;
330355
if (lastRole === "toolResult") {
331-
if (snapshot.coveredMessageCount === undefined) return "trailing_tool_result";
356+
if (snapshot.coveredMessageCount === undefined) return { reason: "trailing_tool_result" };
332357
if (snapshot.coveredMessageCount < 0 || snapshot.coveredMessageCount >= parsed.context.messages.length) {
333-
return "trailing_tool_result";
358+
return { reason: "trailing_tool_result" };
334359
}
335360
} else if (cursorState?.checkpointUsable === false) {
336-
return "trailing_tool_result";
361+
return { reason: "trailing_tool_result" };
337362
}
338-
return undefined;
363+
return { snapshot };
339364
}
340365

341366
export function createCursorRequest(
@@ -364,22 +389,16 @@ export function createCursorRequest(
364389
...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
365390
...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),
366391
};
367-
const invalidation = checkpointInvalidationReason(parsed, request, options);
368-
if (invalidation) {
369-
request.continuationMode = "full-replay";
370-
request.checkpointInvalidationReason = invalidation;
371-
return request;
372-
}
373-
const snapshot = getCursorCheckpoint(parsed._providerContinuation?.cursor?.checkpointRef);
374-
if (!snapshot) {
392+
const resolved = resolveCursorCheckpoint(parsed, request, options);
393+
if ("reason" in resolved) {
375394
request.continuationMode = "full-replay";
376-
request.checkpointInvalidationReason = "missing_ref";
395+
request.checkpointInvalidationReason = resolved.reason;
377396
return request;
378397
}
379-
request.checkpointBytes = snapshot.checkpointBytes;
398+
request.checkpointBytes = resolved.snapshot.checkpointBytes;
380399
request.continuationMode = "checkpoint";
381-
if (parsed.context.messages.at(-1)?.role === "toolResult" && snapshot.coveredMessageCount !== undefined) {
382-
request.checkpointSuffixStart = snapshot.coveredMessageCount;
400+
if (parsed.context.messages.at(-1)?.role === "toolResult" && resolved.snapshot.coveredMessageCount !== undefined) {
401+
request.checkpointSuffixStart = resolved.snapshot.coveredMessageCount;
383402
}
384403
return request;
385404
}

‎src/adapters/cursor/types.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import type { OcxUsage } from "../../types";
22
import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
33
import type { CursorRoutingLevel } from "./discovery";
4+
import type { CursorCheckpointInvalidationReason } from "./checkpoint-store";
45

56
export interface CursorRequestedModelParameter {
67
id: string;
@@ -37,7 +38,7 @@ export interface CursorRunRequest {
3738
*/
3839
checkpointBytes?: Uint8Array;
3940
continuationMode?: "full-replay" | "checkpoint";
40-
checkpointInvalidationReason?: string;
41+
checkpointInvalidationReason?: CursorCheckpointInvalidationReason;
4142
/**
4243
* When set with checkpointBytes, only this suffix of rawMessages is replayed onto the
4344
* decoded ConversationStateStructure. Used for tool-result continuations.

‎structure/04_transports-and-sidecars.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -519,10 +519,13 @@ pre-compaction checkpoint is not persisted for later carry-forward.
519519
After a successful no-tool turn, the Cursor adapter keeps the returned ConversationStateStructure in
520520
a process-local store and reuses that snapshot on the next validated linear continuation instead of
521521
rebuilding rootPromptMessagesJson and conversationTurns. Tool-result turns reuse the last completed
522-
checkpoint plus only the uncovered suffix. Compaction, helper/shadow isolation, account or model
523-
mismatch, missing refs, decode failures, and invalid_argument recovery keep the existing full-replay
524-
path. previous_response_id may select a branch's opaque checkpointRef; it is never a Cursor
525-
conversation ownership key. Cursor Connect still does not expose authoritative cache_read_tokens.
522+
checkpoint plus only the uncovered suffix. Chat Completions hops that omit previous_response_id and
523+
thread headers pin to the first user/developer text and reuse the live snapshot for that
524+
conversation. Isolated helper/shadow turns keep their own checkpoint and never join the parent
525+
conversation. Compaction, account or model mismatch, missing refs, decode failures, and
526+
invalid_argument recovery keep the existing full-replay path. previous_response_id may select a
527+
branch's opaque checkpointRef; it is never a Cursor conversation ownership key. Cursor Connect still
528+
does not expose authoritative cache_read_tokens.
526529

527530
```text
528531
[Decision Log]

0 commit comments

Comments
 (0)