@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
732 lines (715 loc) • 37.6 kB
text/typescript
import { createHash } from "node:crypto";
import type { AdapterEvent, OcxProviderConfig } from "../types";
import type { ProviderAdapter } from "./base";
import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
import { isCursorBenignCancelError, isCursorIncompleteToolCallMessage, isCursorInvalidArgumentError, isCursorOverflowRemintCandidate, isCursorRootEnvelopeError, safeCursorErrorMessage, type CursorSizeContext } from "./cursor/cursor-errors";
import { cursorCheckpointModelAffinityId, cursorNeedsExternalToolContinuation, inferCursorContextWindow, isCursorExternalWireModel } from "./cursor/discovery";
import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
import { mapCursorServerMessage } from "./cursor/message-mapper";
import {
createCursorRequest,
cursorClientThreadOwner,
cursorCoveredPrefixDigest,
cursorInstructionDigest,
cursorRequestEmitsFastVariant,
} from "./cursor/request-builder";
import {
createLiveCursorTransport,
CursorMissingCredentialError,
rekeyCursorContextUsage,
resolveCursorToken,
capturedCursorCheckpointBytes,
} from "./cursor/live-transport";
import {
commitCursorCheckpoint,
cursorCheckpointRefHash,
cursorCheckpointShape,
invalidateCursorCheckpoint,
} from "./cursor/checkpoint-store";
import { debugProviderDiagnostic } from "../lib/debug";
import { isDebugEnabled } from "../lib/debug-settings";
import { createAdapterTierMetadata } from "../providers/fastwire";
import { estimateTokens } from "../lib/token-estimate";
import { ToolEnvelopeEchoFilter } from "../lib/tool-envelope-echo-filter";
import {
clearCursorIncompleteToolRemint,
cursorIncompleteToolRemintScopeKey,
clearCursorEnvelopeEchoRemint,
cursorEnvelopeEchoRemintScopeKey,
cursorOverflowRemintScopeKey,
markCursorOverflowSurfaced,
recordCursorIncompleteToolRemint,
recordCursorEnvelopeEchoRemint,
recordCursorOverflowRemint,
rememberCursorConversationRewrite,
rememberCursorThreadConversation,
shouldSkipCursorOverflowRemint,
shouldSurfaceCursorOverflowFirst,
} from "./cursor/thread-continuity";
import { runCursorTurnWithRetry } from "./cursor/transport-retry";
import { cursorRequestHasShellAlias, cursorRequestUsesCodeMode } from "./cursor/tool-definitions";
import {
CURSOR_OUTPUT_GUARD_MAX_HOLD_BYTES,
CURSOR_ECHO_RETRY_CONTINUATION_TEXT,
CURSOR_ROUTING_COMMENTARY_RETRY_TEXT,
CursorEnvelopeEchoSniffer,
CursorMidstreamEchoObserver,
CursorRoutingCommentaryError,
CursorRoutingCommentarySniffer,
CursorToolResultEchoError,
} from "./cursor/envelope-echo";
import {
createDisabledCursorTransport,
CursorTransportDisabledError,
type CursorTransportFactory,
} from "./cursor/transport";
import { cursorLiveRosterScope } from "./cursor/catalog";
export const CURSOR_API_URL = "https://api2.cursor.sh";
export {
CURSOR_EXEC_CASES_DENIED,
cursorExecDeniedMessage,
type CursorDeniedExecCase,
} from "./cursor/exec-policy";
const CURSOR_TRANSPORT_DISABLED_MESSAGE = [
"An explicit disabled Cursor transport was injected.",
"Production Cursor requests use live transport when a Cursor access token is configured.",
].join(" ");
export interface CursorAdapterDeps {
createTransport?: CursorTransportFactory;
kv?: CursorKvStore;
/** Test seam: observe/replace context-usage rekeying on conversation-id rotation. */
rekeyContextUsage?: (fromConversationId: string, toConversationId: string) => void;
}
function safeCursorTransportError(err: unknown, sizeContext?: CursorSizeContext): string {
if (err instanceof CursorTransportDisabledError) return CURSOR_TRANSPORT_DISABLED_MESSAGE;
if (err instanceof CursorMissingCredentialError) {
return "Cursor live transport is enabled, but no Cursor access token is configured. Set provider.apiKey or OPENCODEX_CURSOR_TEST_TOKEN.";
}
// A locally raised envelope rejection is already safe, specific, and actionable: it was composed
// here from our own measurements and contains no upstream text. Passing it through
// `safeCursorErrorMessage` would collapse it to the bare label "Cursor invalid request" (it
// matches the "invalid"/"exceeds" keyword branch) and discard the counts that tell the operator
// which limit was hit and by how much.
if (isCursorRootEnvelopeError(err)) {
return err instanceof Error ? `Cursor invalid request: ${err.message}` : "Cursor invalid request";
}
const message = err instanceof Error ? err.message : typeof err === "string" ? err : undefined;
if (message) return safeCursorErrorMessage(message, sizeContext);
return "Cursor upstream error: transport failed before completion.";
}
/**
* Size prior for bare resource_exhausted classification (devlog 260): a rough input
* estimate over the outgoing text vs the model's context window. Only used to keep
* SMALL requests on the 429 class — unknown/large stays on the overflow mapping.
*/
function cursorRequestSizeContext(request: {
modelId: string;
_cursorIdentityScope?: string;
system: string[];
messages: { content: string }[];
}): CursorSizeContext {
const text = [...request.system, ...request.messages.map(message => message.content)].join("\n");
return {
estimatedInputTokens: estimateTokens(text, request.modelId),
// Prefers this identity scope's checkpoint `maxTokens` over the id heuristic
// so a plan-gated ceiling participates in the 0.5-window overflow vs 429 prior.
contextWindow: inferCursorContextWindow(request.modelId, {
identityScope: request._cursorIdentityScope,
}),
};
}
export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAdapterDeps = {}): ProviderAdapter {
return {
name: "cursor",
// Cursor emits Fast as a model variant, so the generic "no field emitted" fallback in
// adapters/registry.ts would report every Fast turn as downgraded. This recomputes the
// variant from the same pure inputs the builder uses: tierLogForRunTurn runs BEFORE
// runTurn, and createCursorRequest mints conversation ids, so rebuilding it here would
// describe a request that was never sent.
tierLogForRunTurn(parsed) {
const fast = cursorRequestEmitsFastVariant(parsed);
return createAdapterTierMetadata(
parsed.options.tierObservation,
parsed.options.tierDecision,
fast ? "cursor-variant" : null,
fast ? "fast" : null,
);
},
buildRequest() {
return {
url: provider.baseUrl || CURSOR_API_URL,
method: "POST",
headers: {},
body: "",
};
},
async *parseStream(): AsyncGenerator<AdapterEvent> {
yield {
type: "error",
message: "Cursor adapter uses runTurn; the fetch/parseStream path is disabled.",
};
},
async runTurn(_parsed, incoming, emit) {
if (incoming.abortSignal?.aborted) {
emit({ type: "error", message: "Cursor turn was aborted before start." });
return;
}
// Captured after createCursorRequest so the catch block can apply the bare-RE
// size prior (devlog 260) even though `request` is scoped inside the try.
let requestSizeContext: CursorSizeContext | undefined;
try {
const makeTransport = deps.createTransport ?? createLiveCursorTransport;
const kv = deps.kv ?? createCursorKvStore({}, incoming.translatorBudget);
const rekeyContextUsage = deps.rekeyContextUsage ?? rekeyCursorContextUsage;
// 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.
let liveRosterScope: string | undefined;
if (!_parsed._cursorIdentityScope) {
try {
const token = resolveCursorToken(provider, incoming.headers);
liveRosterScope = cursorLiveRosterScope(provider.baseUrl, token);
_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. */
}
} else {
try {
liveRosterScope = cursorLiveRosterScope(provider.baseUrl, resolveCursorToken(provider, incoming.headers));
} catch {
/* Missing credential is handled by the live transport path below. */
}
}
const inheritedCheckpointRef = _parsed._providerContinuation?.cursor?.checkpointRef;
const previousConversationId = _parsed._cursorConversationId;
let request = {
...createCursorRequest(_parsed, { liveRosterScope }),
_cursorIdentityScope: _parsed._cursorIdentityScope?.trim() || "local",
};
requestSizeContext = cursorRequestSizeContext(request);
// 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";
let completedNormally = false;
let lastTransport: { captured?: Uint8Array } | undefined;
let emittedClientTool = false;
let sawIncompleteToolCall = false;
let sawMidstreamEnvelopeEcho = false;
// Ordering proof for tool-suspended checkpoints: true only when the newest captured
// checkpoint bytes arrived AFTER the turn emitted a client tool call, i.e. upstream
// serialized its suspended-on-tool-call state. Only that snapshot can safely resume
// with the covered-prefix + trailing-toolResult path (devlog 260826 050).
let capturedAfterClientTool = false;
const commitCapturedCheckpoint = (activeRequest: ReturnType<typeof createCursorRequest>): void => {
const toolSuspendedCommit =
emittedClientTool
&& capturedAfterClientTool
&& isCursorExternalWireModel(activeRequest.modelId);
if (
replayUnsafe
|| (emittedClientTool && !toolSuspendedCommit)
|| activeRequest.contextUsageStoreCheckpoints === false
|| !lastTransport?.captured
|| lastTransport.captured.byteLength === 0
) {
// Refusal diagnostics (devlog 260826 050/080): name the exact guard so a live
// missing_ref chain can be attributed without instrumented rebuilds.
debugProviderDiagnostic("cursor", "checkpoint-commit-refused", {
replayUnsafe,
emittedClientTool,
capturedAfterClientTool,
externalModel: isCursorExternalWireModel(activeRequest.modelId),
storeCheckpoints: activeRequest.contextUsageStoreCheckpoints !== false,
capturedBytes: lastTransport?.captured?.byteLength ?? 0,
// Byte length says nothing about coverage. `pendingToolCalls` does: it is what
// distinguishes a snapshot that knows about the suspended call from one that merely
// arrived after it (#4245). Counts only; the decode is skipped unless debug is on.
capturedShape: isDebugEnabled() ? cursorCheckpointShape(lastTransport?.captured) : undefined,
});
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),
toolSuspended: toolSuspendedCommit,
});
if (!checkpointRef) return;
if (previousRef && previousRef !== checkpointRef) invalidateCursorCheckpoint(previousRef);
_parsed._providerContinuation = {
...(_parsed._providerContinuation ?? {}),
cursor: {
...(_parsed._providerContinuation?.cursor ?? {}),
conversationId: activeRequest.conversationId,
// A tool-suspended checkpoint is only usable by the immediate trailing-toolResult
// continuation; the request-builder guard keys on this checkpointUsable=false and
// the snapshot's persisted toolSuspended flag for that.
checkpointUsable: !toolSuspendedCommit,
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,
...(toolSuspendedCommit ? { toolSuspended: true } : {}),
});
};
const runOnce = async (activeRequest: ReturnType<typeof createCursorRequest>) => {
// Envelope echo quarantine (devlog 260826 gap-10): external full-replay continuations
// whose trailing input is a tool result sometimes ECHO the replayed "[Tool Result]"
// envelope as assistant text (kimi-k3 ~30-40% of multi-round probes). Hold the first
// text deltas until they provably diverge from the markers; a completed marker turns
// the turn into a retryable semantic failure BEFORE any client-visible delta escapes.
// Armed for ANY external turn whose replayed history contains a tool result — echo
// priming was observed live on user-action rounds too (the envelope lives in the
// flattened history regardless of which role ends the input).
const replaysToolResult = (_parsed.context.messages ?? []).some(message => message.role === "toolResult");
const armEchoSniffer = isCursorExternalWireModel(activeRequest.modelId) && replaysToolResult;
const echoSniffer = armEchoSniffer ? new CursorEnvelopeEchoSniffer() : undefined;
// Mid-stream observer (devlog 260828 F1/F2): diagnostic-only; armed with the
// prefix sniffer because both fire on flattened tool-result replay priming.
// The composer-2.5 builds are native-wire but also replay the tool result as root text
// (cursorNeedsExternalToolContinuation), so the client-visible strip and the next-turn
// remint follow that predicate. The prefix retry above stays external-only: its
// corrective continuation text is encoded for external wire models alone.
const armMidstreamEcho = cursorNeedsExternalToolContinuation(activeRequest.modelId) && replaysToolResult;
const midstreamObserver = armMidstreamEcho ? new CursorMidstreamEchoObserver() : undefined;
const midstreamFilter = armMidstreamEcho ? new ToolEnvelopeEchoFilter() : undefined;
const armRoutingCommentarySniffer =
isCursorExternalWireModel(activeRequest.modelId)
&& (
cursorRequestUsesCodeMode(activeRequest.tools, activeRequest.toolChoice)
|| cursorRequestHasShellAlias(activeRequest.tools)
);
const routingCommentarySniffer = armRoutingCommentarySniffer
? new CursorRoutingCommentarySniffer()
: undefined;
let guardHeld: AdapterEvent[] = [];
let guardHeldBytes = 0;
const guardEncoder = new TextEncoder();
// Exactly-once observation: every client-bound text delta passes through here
// exactly once — held deltas only on release, ordinary deltas at emit time.
const emitTextObserved = (event: AdapterEvent): void => {
if (event.type !== "text_delta") { emit(event); return; }
midstreamObserver?.feed(event.text);
const text = midstreamFilter?.feed(event.text) ?? event.text;
if (midstreamFilter?.matched) sawMidstreamEnvelopeEcho = true;
if (text) emit({ ...event, text });
};
const releaseGuardHeld = () => {
for (const held of guardHeld) {
if (held.type !== "heartbeat") emittedOutput = true;
emitTextObserved(held);
}
guardHeld = [];
guardHeldBytes = 0;
};
// A single frame can carry a multi-megabyte payload (the transport accepts up to the
// 16 MiB Cursor message bound), so the serialized size is projected — object overhead
// plus raw payload length — BEFORE any encoded copy exists. Escapes only inflate the
// exact figure, making the raw length a safe lower bound for the overflow decision.
const GUARD_EVENT_OVERHEAD_BYTES = 64;
const projectedGuardEventBytes = (event: AdapterEvent): number =>
GUARD_EVENT_OVERHEAD_BYTES
+ (event.type === "text_delta"
? Buffer.byteLength(event.text, "utf8")
: event.type === "thinking_delta"
? Buffer.byteLength(event.thinking, "utf8")
: 0);
const holdGuardEvent = (event: AdapterEvent) => {
if (guardHeldBytes + projectedGuardEventBytes(event) > CURSOR_OUTPUT_GUARD_MAX_HOLD_BYTES) {
// Too large to retain even unescaped: settle the sniffers, release what was held,
// and pass this event through without ever encoding it.
echoSniffer?.finish();
routingCommentarySniffer?.finish();
releaseGuardHeld();
if (event.type !== "heartbeat") emittedOutput = true;
emitTextObserved(event);
return false;
}
guardHeld.push(event);
// Count the complete retained representation, including per-event overhead, so an
// upstream cannot evade the cap with empty or non-text reasoning frames.
guardHeldBytes += guardEncoder.encode(JSON.stringify(event)).byteLength;
if (guardHeldBytes <= CURSOR_OUTPUT_GUARD_MAX_HOLD_BYTES) return true;
echoSniffer?.finish();
routingCommentarySniffer?.finish();
releaseGuardHeld();
return false;
};
// Bound each feed before a sniffer copies or encodes it. Their normal 40 B / 512 B
// hold thresholds are checked after classification, so one large frame previously
// let a late match inspect an arbitrary tail. Only these leading UTF-16 prefixes
// now participate in corrective retry; later text remains ordinary output.
const ECHO_SNIFF_FEED_MAX_CHARS = 512;
const ROUTING_SNIFF_FEED_MAX_CHARS = 2048;
const boundedSniffText = (text: string, maxChars: number): string =>
text.length > maxChars ? text.slice(0, maxChars) : text;
const guardsSettled = () =>
(!echoSniffer || echoSniffer.settled)
&& (!routingCommentarySniffer || routingCommentarySniffer.settled);
await runCursorTurnWithRetry(
makeTransport,
{
provider,
headers: incoming.headers,
translatorBudget: incoming.translatorBudget,
requestDeclaresFullAccess: cursorRequestDeclaresFullAccess(activeRequest),
sessionId: activeRequest.conversationId,
...(incoming.providerFetch ? { fetch: incoming.providerFetch } : {}),
},
activeRequest,
incoming.abortSignal,
(message, activeTransport) => {
if (incoming.abortSignal?.aborted) {
emit({ type: "error", message: "Cursor turn was aborted." });
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) {
if (captured !== lastTransport?.captured) capturedAfterClientTool = emittedClientTool;
lastTransport = { captured };
}
const events = mapCursorServerMessage(message, {
kv,
writeClient: clientMessage => {
void activeTransport.writeClient(clientMessage);
},
});
for (const event of events) {
if (event.type === "error" && isCursorIncompleteToolCallMessage(event.message)) {
sawIncompleteToolCall = true;
}
if (!guardsSettled()) {
if (event.type === "text_delta") {
// Classify the delta before the aggregate-cap check: an oversized first
// delta must still pass the armed sniffers (echo/hallucination detection is
// prefix-based), so the cap cannot disarm them before they see the text.
if (echoSniffer && !echoSniffer.settled) {
const decision = echoSniffer.feed(boundedSniffText(event.text, ECHO_SNIFF_FEED_MAX_CHARS));
if (decision.kind === "echo") {
guardHeld = [];
throw new CursorToolResultEchoError(decision.marker);
}
}
if (routingCommentarySniffer && !routingCommentarySniffer.settled) {
const decision = routingCommentarySniffer.feed(boundedSniffText(event.text, ROUTING_SNIFF_FEED_MAX_CHARS));
if (decision.kind === "hallucination") {
guardHeld = [];
throw new CursorRoutingCommentaryError();
}
}
if (!holdGuardEvent(event)) continue;
if (guardsSettled()) releaseGuardHeld();
continue;
} else if (event.type === "thinking_delta" || event.type === "heartbeat") {
// Reasoning before first text stays ordered; liveness still passes through.
if (event.type === "thinking_delta") {
holdGuardEvent(event);
continue;
}
} else {
// A tool call, done, or error closes the text quarantine. Re-check the full
// held first line before release so a fragmented routing claim cannot leak.
echoSniffer?.finish();
const routingDecision = routingCommentarySniffer?.finish();
if (routingDecision?.kind === "hallucination") {
guardHeld = [];
throw new CursorRoutingCommentaryError();
}
releaseGuardHeld();
}
}
if (event.type !== "heartbeat") emittedOutput = true;
if (event.type === "done") {
const suffix = midstreamFilter?.finish();
// A fenced marker released by hold overflow is unproven code: remint to be safe.
if (midstreamFilter?.matched || midstreamFilter?.unverifiedMarker) sawMidstreamEnvelopeEcho = true;
if (suffix) emit({ type: "text_delta", text: suffix });
// The observer is diagnostic only: the fence-aware filter's verdict decides the
// remint, so a quoted marker in a closed code block does not rotate the thread.
const midstreamFindings = midstreamObserver?.findings() ?? [];
for (const finding of midstreamFindings) {
debugProviderDiagnostic("cursor", "midstream-envelope-echo", {
wireModel: activeRequest.modelId,
conversationHash: activeRequest.conversationId.slice(0, 16),
marker: finding.marker,
offset: finding.offset,
callIdCorrupt: finding.callIdCorrupt,
});
}
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 {
emitTextObserved(event);
}
}
},
// Cursor's retry ladder re-sends the WHOLE turn, so each attempt is a physical send
// the enclosing request pays for. A meta without a budget -- every adapter unit test,
// and any caller predating this -- keeps the adapter's own three attempts (#4546).
incoming.sendBudget ? { sendBudget: incoming.sendBudget } : {},
);
};
const remintConversationId = (failedConversationId: string) => {
lastTransport = undefined;
_parsed._cursorConversationId = undefined;
const next = {
...createCursorRequest(_parsed, { forceFreshConversation: true, liveRosterScope }),
_cursorIdentityScope: _parsed._cursorIdentityScope?.trim() || "local",
};
rekeyContextUsage(failedConversationId, next.conversationId);
_parsed._cursorConversationId = next.conversationId;
// Persist recovery for store:false clients that send any stable Cursor thread owner, 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 or Desktop owner.
const threadOwner = cursorClientThreadOwner(_parsed);
if (_parsed._cursorIsolateConversation !== true) {
rememberCursorConversationRewrite(failedConversationId, next.conversationId, _parsed._cursorIdentityScope);
}
if (threadOwner && _parsed._cursorIsolateConversation !== true) {
rememberCursorThreadConversation(
threadOwner,
next.conversationId,
_parsed._cursorIdentityScope,
);
}
return next;
};
for (;;) {
try {
await runOnce(request);
break;
} catch (err) {
const outputGuardRetryText =
err instanceof CursorToolResultEchoError
? CURSOR_ECHO_RETRY_CONTINUATION_TEXT
: err instanceof CursorRoutingCommentaryError
? CURSOR_ROUTING_COMMENTARY_RETRY_TEXT
: undefined;
// One-shot corrective retry for guarded external output (devlog 260826 gap-10/11).
// The quarantine guarantees no client-visible delta escaped, so a fresh-conversation
// retry is safe. A second rejection propagates as an error rather than looping.
if (
outputGuardRetryText
&& !emittedOutput
&& !replayUnsafe
&& !incoming.abortSignal?.aborted
) {
debugProviderDiagnostic(
"cursor",
err instanceof CursorToolResultEchoError
? "envelope-echo-retry"
: "routing-commentary-retry",
{
wireModel: request.modelId,
conversationHash: request.conversationId.slice(0, 16),
},
);
const echoedConversationId = request.conversationId;
request = {
...remintConversationId(echoedConversationId),
echoRetryContinuationText: outputGuardRetryText,
};
await runOnce(request);
break;
} else {
const overflowRemintSafe =
!lastRawIsToolResult
&& !emittedOutput
&& !replayUnsafe
&& _parsed._cursorIsolateConversation !== true
&& request.contextUsageStoreCheckpoints !== false
&& !incoming.abortSignal?.aborted;
const overflowScopeKey = cursorOverflowRemintScopeKey(
cursorClientThreadOwner(_parsed),
_parsed._cursorIdentityScope,
);
if (
overflowScopeKey
&& overflowRemintSafe
&& isCursorOverflowRemintCandidate(err, requestSizeContext)
) {
if (shouldSkipCursorOverflowRemint(overflowScopeKey)) throw err;
if (shouldSurfaceCursorOverflowFirst(overflowScopeKey)) {
markCursorOverflowSurfaced(overflowScopeKey);
throw err;
}
if (!recordCursorOverflowRemint(overflowScopeKey)) throw err;
if (inheritedCheckpointRef) invalidateCursorCheckpoint(inheritedCheckpointRef);
request = remintConversationId(request.conversationId);
continue;
}
// 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
|| emittedOutput
|| replayUnsafe
|| incoming.abortSignal?.aborted
) {
throw err;
}
request = remintConversationId(request.conversationId);
await runOnce(request);
break;
}
}
}
const incompleteToolRemintScopeKey =
_parsed._cursorIsolateConversation !== true
&& request.contextUsageStoreCheckpoints !== false
? cursorIncompleteToolRemintScopeKey(
cursorClientThreadOwner(_parsed),
_parsed._cursorIdentityScope,
)
: null;
// Incomplete-tool errors are streamed, not thrown. Do not retry this turn; rotate only
// the next turn's id. request-prepare currently isolates compaction, but adapter callers
// can bypass that upstream invariant, so checkpoint storage is the local isolation boundary.
if (sawIncompleteToolCall && incompleteToolRemintScopeKey) {
if (recordCursorIncompleteToolRemint(incompleteToolRemintScopeKey)) {
if (inheritedCheckpointRef) invalidateCursorCheckpoint(inheritedCheckpointRef);
debugProviderDiagnostic("cursor", "incomplete-tool-remint", {
wireModel: request.modelId,
conversationHash: request.conversationId.slice(0, 16),
});
remintConversationId(request.conversationId);
} else {
debugProviderDiagnostic("cursor", "incomplete-tool-remint-exhausted", {
wireModel: request.modelId,
conversationHash: request.conversationId.slice(0, 16),
});
}
} else if (!sawIncompleteToolCall && completedNormally && incompleteToolRemintScopeKey) {
clearCursorIncompleteToolRemint(incompleteToolRemintScopeKey);
}
// Strip a split mid-stream marker before it reaches the client, then rotate the next
// conversation because the upstream checkpoint may still contain the echoed envelope.
//
// Its own budget, not the incomplete-tool one: echoing is cheap and repeatable while an
// incomplete client-tool stream is rare and structural, so a shared counter would let a
// persistently echoing model spend the allowance the other recovery needs. Skipped when
// the incomplete-tool arm already reminted this turn — one rotation is enough.
const envelopeEchoRemintScopeKey =
_parsed._cursorIsolateConversation !== true
&& request.contextUsageStoreCheckpoints !== false
? cursorEnvelopeEchoRemintScopeKey(
cursorClientThreadOwner(_parsed),
_parsed._cursorIdentityScope,
request.conversationId,
)
: null;
if (sawMidstreamEnvelopeEcho && !sawIncompleteToolCall && envelopeEchoRemintScopeKey) {
if (recordCursorEnvelopeEchoRemint(envelopeEchoRemintScopeKey)) {
if (inheritedCheckpointRef) invalidateCursorCheckpoint(inheritedCheckpointRef);
debugProviderDiagnostic("cursor", "midstream-envelope-echo-remint", {
wireModel: request.modelId,
conversationHash: request.conversationId.slice(0, 16),
});
remintConversationId(request.conversationId);
} else {
debugProviderDiagnostic("cursor", "midstream-envelope-echo-remint-exhausted", {
wireModel: request.modelId,
conversationHash: request.conversationId.slice(0, 16),
});
}
} else if (!sawMidstreamEnvelopeEcho && completedNormally && envelopeEchoRemintScopeKey) {
clearCursorEnvelopeEchoRemint(envelopeEchoRemintScopeKey);
}
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;
emit({
type: "error",
message: isTranslatorBudgetExceededError(err)
? "upstream translation buffer exceeded the safe limit"
: safeCursorTransportError(err, requestSizeContext),
...(isTranslatorBudgetExceededError(err)
? { status: 502, errorType: "upstream_error", code: "translation_buffer_limit" }
: {}),
// A local envelope rejection is a client error with a stable code, and the caller needs
// that code to distinguish "this conversation cannot be sent" from a transient upstream
// fault. Without this the class was flattened to a bare message and the code was lost.
...(isCursorRootEnvelopeError(err)
? { status: 400, errorType: "invalid_request_error", code: "cursor_root_envelope_limit", retryable: false }
: {}),
...(partialUsage ? { usage: partialUsage } : {}),
});
}
},
};
}