@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
835 lines (776 loc) • 36.7 kB
text/typescript
import type { CursorForegroundShellOwner } from "./native-foreground-shell";
import { createHash } from "node:crypto";
import { enforceAppOwnedMemoryBudget } from "../../lib/app-owned-memory";
import { create } from "@bufbuild/protobuf";
import {
DiagnosticsErrorSchema,
DiagnosticsResultSchema,
ErrorSchema,
GetBlobResultSchema,
KvClientMessageSchema,
McpErrorSchema,
McpResultSchema,
RequestContextResultSchema,
RequestContextSchema,
RequestContextSuccessSchema,
SetBlobResultSchema,
type ExecServerMessage,
type KvServerMessage,
} from "./gen/agent_pb";
import {
deleteExec,
grepExec,
lsExec,
readExec,
rejectDeleteExecForApplyPatch,
rejectDeleteExecForPolicy,
rejectGrepExecForPolicy,
rejectLsExecForPolicy,
rejectReadExecForPolicy,
rejectWriteExecForApplyPatch,
rejectWriteExecForPolicy,
writeExec,
} from "./native-exec-fs";
import { debugProviderDiagnostic } from "../../lib/debug";
import { fetchExec, rejectFetchExecForPolicy, type CursorNativeNetworkDeps } from "./native-exec-network";
import {
backgroundShellSpawnExec,
rejectBackgroundShellSpawnExecForPolicy,
rejectShellExecForPolicy,
rejectShellStreamExecForPolicy,
rejectWriteShellStdinExecForPolicy,
shellExec,
shellStreamExec,
writeShellStdinExec,
} from "./native-exec-shell";
import {
computerUseExec,
listMcpResourcesExec,
mcpExec,
readMcpResourceExec,
recordScreenExec,
type CursorNativeToolDeps,
} from "./native-exec-tools";
import { clientBytes, execBytes, execStreamCloseBytes, execThrowBytes } from "./native-exec-common";
import type { McpToolDefinition } from "./gen/agent_pb";
import { OCX_RESPONSES_TOOL_PROVIDER } from "./tool-definitions";
import { CODEX_UNIFIED_EXEC_TOOL, cursorRequestHasExecutionPath, cursorRequestHasShellAlias, cursorRequestUsesCodeMode, cursorToolWireName } from "./tool-naming";
import { CODE_MODE_RESULT_ECHO_SENTENCE } from "../exec-tool-result-normalize";
import type { OcxTool } from "../../types";
import { CURSOR_DEFERRED_TOOL_FALLBACK, cursorPlainNativeExecFallback, cursorPlainNativeExecRedirectHint, cursorUsesPlainToolWording } from "./tool-wording";
export type CursorNativeExecDeps = CursorNativeNetworkDeps & CursorNativeToolDeps;
/**
* Execution context for a Cursor stream: the per-call executors plus the MCP tool definitions
* advertised to the server via `requestContextResult`. Without `mcpToolDefs`, the server is
* never told any MCP tools exist, so it never sends `mcpArgs`.
*/
export interface CursorNativeExecContext extends CursorNativeExecDeps {
/** Stable owner for background shells created by this transport session. */
sessionId?: string;
foregroundShellOwner?: CursorForegroundShellOwner;
signal?: AbortSignal;
mcpToolDefs?: McpToolDefinition[];
clientToolDefs?: McpToolDefinition[];
/** Unsafe opt-in escape hatch for Cursor server-driven local fs/shell/fetch execution. */
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;
/** Catalog-aware redirect text for denied native fs/shell attempts (undefined = default bridge wording). */
nativeExecRedirectHint?: string;
/** Claude-family Cursor targets receive factual redirects, without narration restrictions. */
plainToolWording?: boolean;
}
const REDIRECT_HINT_MAX_TOOLS = 16;
/**
* Catalog-aware redirect for denied Cursor-native fs/shell/fetch attempts. Code mode must point
* inside freeform `exec`, since the default refusal names top-level shell tools it does not expose.
* When no execution path exists, name the actual client and configured MCP tools instead and stay
* neutral about their capabilities, so a listed file/search/fetch tool is never contradicted.
*/
export function cursorNativeExecRedirectHint(
tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
mcpToolDefs: readonly Pick<McpToolDefinition, "name" | "providerIdentifier">[] = [],
modelId?: string,
): string | undefined {
if (cursorUsesPlainToolWording(modelId)) return cursorPlainNativeExecRedirectHint(tools, mcpToolDefs);
const clientTools = tools ?? [];
if (cursorRequestHasShellAlias(clientTools)) return undefined;
// Code mode (freeform unified `exec`, no bare shell bridge): the default bridge wording names
// top-level shell tools this catalog does not expose, so the model probes for tools that cannot
// exist. Redirect INSIDE `exec` instead — shell, file, search, and fetch are nested helpers of
// the code cell. The caller supplies the active-turn catalog, so no tool_choice re-filter here.
if (cursorRequestUsesCodeMode(clientTools)) return cursorCodeModeExecRedirectHint();
if (cursorRequestHasExecutionPath(clientTools)) return undefined;
// Client tools are advertised under OCX_RESPONSES_TOOL_PROVIDER, so the harness shows them as
// `mcp_<provider>_<wire name>`; configured MCP servers are advertised under their own provider id.
// A request with no client tools but configured MCP tools still gets those named; a request that
// advertises nothing at all keeps the default bridge wording.
const names = [...new Set([
...clientTools.map(tool => cursorToolWireName(tool, clientTools)),
...mcpToolDefs.map(def => `mcp_${def.providerIdentifier}_${def.name}`),
])];
if (names.length === 0) return undefined;
const shown = names.slice(0, REDIRECT_HINT_MAX_TOOLS).map(name => `\`${name}\``).join(", ");
const more = names.length > REDIRECT_HINT_MAX_TOOLS ? ` (+${names.length - REDIRECT_HINT_MAX_TOOLS} more)` : "";
return (
`Re-issue this operation NOW through one of the tools listed in this request's catalog: ${shown}${more} `
+ `(the harness displays a \`${OCX_RESPONSES_TOOL_PROVIDER}\` entry as \`mcp_${OCX_RESPONSES_TOOL_PROVIDER}_<name>\`; that is the same tool). `
+ "Cursor-native Read/Glob/Grep/LS/Shell/Write/Fetch are not part of this request's catalog; do not retry them. "
+ "Pick the listed tool that fits the operation — a listed file, search, or fetch tool if there is one, otherwise the listed tool that delegates work to a worker agent. "
+ "Do NOT narrate this redirect, do NOT comment on tool availability, and do NOT re-announce the task — just make the catalog tool call."
);
}
/**
* Code-mode half of the redirect above: the only execution surface is the freeform `exec` cell,
* so the denial names the nested helpers instead of the missing flat bridge. The result-echo
* sentence is the shared canonical wording tool-guidance emits for the same isolate.
*/
function cursorCodeModeExecRedirectHint(): string {
return (
`Re-issue this operation NOW through the \`${CODEX_UNIFIED_EXEC_TOOL}\` tool: this turn uses Codex code mode, so \`${CODEX_UNIFIED_EXEC_TOOL}\` takes a JavaScript body and shell, file, search, and fetch are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`text(await tools.exec_command({cmd: "ls"}))\`. `
+ "Cursor-native Read/Glob/Grep/LS/Shell/Write/Fetch are not part of this request's catalog; do not retry them, and do not call `shell_command` or `exec_command` at the top level here — code mode exposes no bare shell bridge, only the nested helpers. Every other tool this turn lists is called directly, outside `exec`, as usual. "
+ CURSOR_DEFERRED_TOOL_FALLBACK + " "
+ CODE_MODE_RESULT_ECHO_SENTENCE + " "
+ `Do NOT narrate this redirect, do NOT comment on tool availability, and do NOT re-announce the task — just make the \`${CODEX_UNIFIED_EXEC_TOOL}\` call.`
);
}
export function cursorUnsafeNativeLocalExecEnabled(input: Pick<CursorNativeExecContext, "unsafeAllowNativeLocalExec"> = {}): boolean {
return input.unsafeAllowNativeLocalExec === true;
}
/**
* Content-addressed blob store shared across streams. Bounded: without eviction a long-running
* proxy accumulates every conversation's prompt blobs forever (unbounded memory) and any stale
* blob stays servable indefinitely — a cross-conversation contamination enabler if Cursor's
* server-side state ever references old ids (devlog 260702 P0). Continuation requests re-store
* their blobs on every turn (`rootPromptMessages` → `storeCursorBlob`), so TTL + cap eviction is
* safe for live sessions: only genuinely abandoned entries age out.
*/
const BLOB_TTL_MS = 15 * 60_000;
const BLOB_MAX_ENTRIES = 4_096;
const BLOB_MAX_ENTRY_BYTES = 16 * 1024 * 1024;
export const CURSOR_BLOB_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
type CursorBlobProvenance = "local-regenerated" | "remote-setBlobArgs";
export type CursorBlobRequestScopeToken = symbol;
interface CursorBlobEntry {
data: Uint8Array;
storedAt: number;
sizeBytes: number;
provenance: CursorBlobProvenance;
requestPins: Set<CursorBlobRequestScopeToken>;
}
type CursorBlobRejectionReason = "entry_too_large" | "pinned_saturation" | "request_pinned_conflict";
type CursorBlobAdmission =
| { admitted: true; replaced: boolean }
| { admitted: false; reason: CursorBlobRejectionReason };
interface CursorBlobLimits {
ttlMs: number;
maxEntries: number;
maxEntryBytes: number;
maxTotalBytes: number;
}
interface CursorBlobRequestScopeState {
keys: Set<string>;
sealed: boolean;
kind: "request" | "checkpoint";
}
const DEFAULT_BLOB_LIMITS: CursorBlobLimits = {
ttlMs: BLOB_TTL_MS,
maxEntries: BLOB_MAX_ENTRIES,
maxEntryBytes: BLOB_MAX_ENTRY_BYTES,
maxTotalBytes: CURSOR_BLOB_MAX_TOTAL_BYTES,
};
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;
let blobOldestEvictableAt: number | null = null;
let rejectedEntryTooLarge = 0;
let rejectedPinnedSaturation = 0;
let blobExpiryAccountingTimer: ReturnType<typeof setTimeout> | undefined;
/** Earliest unpinned storedAt+ttl; skip the write-time TTL walk while this is in the future. */
let blobNextUnpinnedExpiryAt: number | null = null;
/** Earliest unpinned remote expiry strictly in the future; drives the single reclassify timer. */
let blobNextRemoteExpiryAt: number | null = null;
function isExpired(entry: CursorBlobEntry, now: number): boolean {
return now - entry.storedAt >= blobLimits.ttlMs;
}
function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
if (a.byteLength !== b.byteLength) return false;
for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
return true;
}
function recomputeBlobClassAccounting(): void {
const now = Date.now();
let localBytes = 0;
let pinnedBytes = 0;
let evictableBytes = 0;
let oldestAt: number | null = null;
let nextUnpinnedExpiry = Number.POSITIVE_INFINITY;
let nextRemoteExpiry = Number.POSITIVE_INFINITY;
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;
// 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 + k.length;
oldestAt = oldestAt === null ? entry.storedAt : Math.min(oldestAt, entry.storedAt);
}
if (!requestPinned) {
const expiresAt = entry.storedAt + blobLimits.ttlMs;
nextUnpinnedExpiry = Math.min(nextUnpinnedExpiry, expiresAt);
if (entry.provenance === "remote-setBlobArgs" && expiresAt > now) {
nextRemoteExpiry = Math.min(nextRemoteExpiry, expiresAt);
}
}
}
blobLocalBytes = localBytes;
blobPinnedBytes = pinnedBytes;
blobEvictableBytes = evictableBytes;
blobOldestEvictableAt = oldestAt;
blobNextUnpinnedExpiryAt = Number.isFinite(nextUnpinnedExpiry) ? nextUnpinnedExpiry : null;
blobNextRemoteExpiryAt = Number.isFinite(nextRemoteExpiry) ? nextRemoteExpiry : null;
scheduleBlobExpiryAccounting(now);
}
function reconcileBlobClassAccountingAndEnforce(): void {
recomputeBlobClassAccounting();
enforceAppOwnedMemoryBudget();
}
function scheduleBlobExpiryAccounting(now: number): void {
if (blobExpiryAccountingTimer) clearTimeout(blobExpiryAccountingTimer);
blobExpiryAccountingTimer = undefined;
const nextExpiry = blobNextRemoteExpiryAt;
if (nextExpiry === null || nextExpiry <= now || !Number.isFinite(nextExpiry)) return;
blobExpiryAccountingTimer = setTimeout(() => {
blobExpiryAccountingTimer = undefined;
reconcileBlobClassAccountingAndEnforce();
}, Math.max(0, nextExpiry - now));
blobExpiryAccountingTimer.unref?.();
}
/**
* O(1) class/timer update for a newly admitted key when no other row changed.
* Full-map recompute stays on replacement, eviction, pin changes, and TTL fire —
* the 4096-entry ceiling fill must not walk the store on every remote admit.
*/
function accountAdmittedBlob(k: string, entry: CursorBlobEntry, now: number): void {
const requestPinned = entry.requestPins.size > 0;
const expired = isExpired(entry, now);
const provenancePinned = entry.provenance === "remote-setBlobArgs" && !expired;
const logicalBytes = entry.sizeBytes + k.length;
if (entry.provenance === "local-regenerated") blobLocalBytes += entry.sizeBytes;
if (requestPinned || provenancePinned) blobPinnedBytes += logicalBytes;
if (!requestPinned && (entry.provenance === "local-regenerated" || expired)) {
blobEvictableBytes += logicalBytes;
blobOldestEvictableAt = blobOldestEvictableAt === null ? entry.storedAt : Math.min(blobOldestEvictableAt, entry.storedAt);
}
if (requestPinned) return;
const expiresAt = entry.storedAt + blobLimits.ttlMs;
blobNextUnpinnedExpiryAt = blobNextUnpinnedExpiryAt === null
? expiresAt
: Math.min(blobNextUnpinnedExpiryAt, expiresAt);
if (entry.provenance !== "remote-setBlobArgs" || expiresAt <= now) return;
const previousRemoteExpiry = blobNextRemoteExpiryAt;
blobNextRemoteExpiryAt = previousRemoteExpiry === null
? expiresAt
: Math.min(previousRemoteExpiry, expiresAt);
if (
!blobExpiryAccountingTimer
|| previousRemoteExpiry === null
|| expiresAt < previousRemoteExpiry
) {
scheduleBlobExpiryAccounting(now);
}
}
function deleteBlob(k: string, recompute = true): number {
const entry = blobs.get(k);
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();
// 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 {
const entry = blobs.get(k);
if (!entry) return;
const scopes = requestScope ? [requestScope] : [...entry.requestPins];
let changed = false;
for (const scope of scopes) {
if (!entry.requestPins.delete(scope)) continue;
changed = true;
const state = blobRequestScopes.get(scope);
state?.keys.delete(k);
if (state?.sealed && state.keys.size === 0) blobRequestScopes.delete(scope);
}
if (changed) reconcileBlobClassAccountingAndEnforce();
}
function setBlob(
k: string,
data: Uint8Array,
provenance: CursorBlobProvenance,
requestScope?: CursorBlobRequestScopeToken,
): CursorBlobAdmission {
if (data.byteLength > blobLimits.maxEntryBytes) {
rejectedEntryTooLarge++;
return { admitted: false, reason: "entry_too_large" };
}
const now = Date.now();
const existing = blobs.get(k);
const sameData = existing ? bytesEqual(existing.data, data) : false;
if (existing && !sameData && existing.requestPins.size > 0) {
return { admitted: false, reason: "request_pinned_conflict" };
}
const removals = new Set<string>();
if (blobNextUnpinnedExpiryAt !== null && now >= blobNextUnpinnedExpiryAt) {
for (const [candidateKey, entry] of blobs) {
if (candidateKey === k && sameData) continue;
if (entry.requestPins.size === 0 && isExpired(entry, now)) removals.add(candidateKey);
}
}
const existingRemovedByTtl = existing !== undefined && removals.has(k);
const reuseExisting = existing !== undefined && sameData && !existingRemovedByTtl;
const mergedProvenance: CursorBlobProvenance = reuseExisting && existing.provenance === "remote-setBlobArgs"
? "remote-setBlobArgs"
: provenance;
const storedAt = reuseExisting && existing.provenance === "remote-setBlobArgs" && provenance === "local-regenerated"
? existing.storedAt
: now;
let projectedBytes = blobBytes;
let projectedCount = blobs.size;
for (const candidateKey of removals) {
const entry = blobs.get(candidateKey);
if (!entry) continue;
projectedBytes -= entry.sizeBytes;
projectedCount--;
}
if (existing && !existingRemovedByTtl) {
projectedBytes -= existing.sizeBytes;
projectedCount--;
}
projectedBytes += data.byteLength;
projectedCount++;
if (projectedBytes > blobLimits.maxTotalBytes || projectedCount > blobLimits.maxEntries) {
const localVictims = [...blobs.entries()].sort((a, b) => a[1].storedAt - b[1].storedAt);
for (const [candidateKey, entry] of localVictims) {
if (
candidateKey === k
|| removals.has(candidateKey)
|| entry.requestPins.size > 0
|| entry.provenance !== "local-regenerated"
) continue;
removals.add(candidateKey);
projectedBytes -= entry.sizeBytes;
projectedCount--;
if (projectedBytes <= blobLimits.maxTotalBytes && projectedCount <= blobLimits.maxEntries) break;
}
}
if (projectedBytes > blobLimits.maxTotalBytes || projectedCount > blobLimits.maxEntries) {
rejectedPinnedSaturation++;
return { admitted: false, reason: "pinned_saturation" };
}
// Carry forward only pins whose scope still has live state; a dead scope's
// token can never be released again (review C1-1).
const requestPins = new Set<CursorBlobRequestScopeToken>();
if (reuseExisting) {
for (const scope of existing.requestPins) {
if (blobRequestScopes.has(scope)) requestPins.add(scope);
}
}
// A pin is only attached when the scope still has live UNSEALED state:
// sealing fixes the advertised key set (locked contract), so a remote
// setBlobArgs arriving after seal must not extend the pin set — and a
// sealed scope whose advertised keys have all hydrated is already deleted,
// so attaching its stale token would create a permanent untracked pin the
// terminal release could never clear (reviews C1-1/C2-1).
const scopeState = requestScope ? blobRequestScopes.get(requestScope) : undefined;
if (requestScope && scopeState && !scopeState.sealed) requestPins.add(requestScope);
const entry: CursorBlobEntry = {
data: reuseExisting ? existing.data : data.slice(),
storedAt,
sizeBytes: data.byteLength,
provenance: mergedProvenance,
requestPins,
};
for (const candidateKey of removals) deleteBlob(candidateKey, false);
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);
if (removals.size > 0 || existing !== undefined) {
reconcileBlobClassAccountingAndEnforce();
} else {
accountAdmittedBlob(k, entry, now);
enforceAppOwnedMemoryBudget();
}
return { admitted: true, replaced: existing !== undefined };
}
function getBlob(k: string): Uint8Array | undefined {
const entry = blobs.get(k);
if (!entry) return undefined;
if (entry.requestPins.size === 0 && isExpired(entry, Date.now())) {
deleteBlob(k);
return 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 {
if (bytes.byteLength <= MAX_BLOB_ID_PASSTHROUGH_BYTES) return `h:${Buffer.from(bytes).toString("hex")}`;
return `d:${createHash("sha256").update(bytes).digest("hex")}`;
}
/**
* Store a blob (SHA-256 keyed) in the shared map that `handleCursorNativeKv` serves, and return its
* blob id. Cursor's `rootPromptMessagesJson`/turn entries are blob IDS, not inline content — the
* server fetches the bytes back via `getBlobArgs`. Mirrors jawcode `createBlobId`/`storeCursorBlob`.
*/
export class CursorBlobAdmissionError extends Error {
readonly code = "cursor_blob_capacity";
constructor(readonly reason: CursorBlobRejectionReason) {
super("Cursor blob capacity is exhausted; retry with a smaller request.");
this.name = "CursorBlobAdmissionError";
}
}
let blobScopeSequence = 0;
export function createCursorBlobRequestScope(): CursorBlobRequestScopeToken {
// Unique description per token so debug snapshots expose exact pin
// 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, kind: "request" });
return scope;
}
export function sealCursorBlobRequestScope(scope: CursorBlobRequestScopeToken): void {
const state = blobRequestScopes.get(scope);
if (!state) return;
state.sealed = true;
if (state.keys.size === 0) blobRequestScopes.delete(scope);
}
export function releaseCursorBlobRequestScope(scope: CursorBlobRequestScopeToken): void {
const state = blobRequestScopes.get(scope);
if (!state) return;
for (const k of state.keys) blobs.get(k)?.requestPins.delete(scope);
blobRequestScopes.delete(scope);
reconcileBlobClassAccountingAndEnforce();
}
export function storeCursorBlob(data: Uint8Array, requestScope?: CursorBlobRequestScopeToken): Uint8Array {
const blobId = new Uint8Array(createHash("sha256").update(data).digest());
const admission = setBlob(key(blobId), data, "local-regenerated", requestScope);
if (!admission.admitted) throw new CursorBlobAdmissionError(admission.reason);
return blobId;
}
/**
* Stored byte length of one blob, or null when it is not in the store.
*
* Size only, never content: the envelope guard needs to measure the FINAL root set, which mixes
* roots minted this turn with roots carried inside a checkpoint. Reading them back through a
* hydration path would both defeat the request-scope sealing and log served bytes for a request
* that may never be sent.
*/
export function cursorBlobByteLength(blobId: Uint8Array): number | null {
const entry = blobs.get(key(blobId));
return entry ? entry.data.byteLength : null;
}
/** Read one stored root for usage estimation without hydration, pin release, or served-byte accounting. */
export function cursorBlobTextForEstimate(blobId: Uint8Array): string | null {
if (!(blobId instanceof Uint8Array) || blobId.byteLength === 0) return null;
try {
const entry = blobs.get(key(blobId));
if (!entry) return null;
return new TextDecoder("utf-8", { fatal: true }).decode(entry.data);
} catch {
debugProviderDiagnostic("cursor", "blob-estimate-unreadable", {
bytes: blobId.byteLength,
});
return null;
}
}
/**
* Serve-time integrity for content-addressed blobs (devlog 260826_cursor_responses_gap 080):
* a raw 32-byte blob id IS the SHA-256 of its bytes, so served data whose digest mismatches
* the id means in-store corruption — the splice signature behind garbled replayed tool
* results. Ids longer than 32 bytes (digested-key namespace) and server-minted ids are not
* content-addressed and always pass.
*/
export function cursorBlobServeIntegrityOk(blobId: Uint8Array, served: Uint8Array): boolean {
if (blobId.byteLength !== 32) return true;
const digest = createHash("sha256").update(served).digest();
return digest.equals(Buffer.from(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;
rejectedPinnedSaturation: number;
oldestAt: number | null;
}
export function cursorBlobMetrics(): CursorBlobMetrics {
return {
count: blobs.size,
totalBytes: blobBytes,
keyBytes: blobKeyBytes,
localBytes: blobLocalBytes,
pinnedBytes: blobPinnedBytes,
rejectedEntryTooLarge,
rejectedPinnedSaturation,
oldestAt: blobOldestEvictableAt,
};
}
export function cursorBlobRetainedStoreSnapshot(): {
count: number;
bytes: number;
evictableBytes: number;
pinnedBytes: number;
oldestAt: number | null;
} {
return {
count: blobs.size,
// 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,
};
}
export function evictOldestCursorBlobForBudget(): number {
const now = Date.now();
let oldest: [string, CursorBlobEntry] | undefined;
for (const candidate of blobs) {
const entry = candidate[1];
if (entry.requestPins.size > 0) continue;
if (entry.provenance !== "local-regenerated" && !isExpired(entry, now)) continue;
if (!oldest || entry.storedAt < oldest[1].storedAt) oldest = candidate;
}
return oldest ? deleteBlob(oldest[0]) : 0;
}
export function setCursorBlobLimitsForTests(limits?: Partial<CursorBlobLimits>): void {
resetCursorBlobStateForTests();
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();
}
export function cursorBlobStoreDebugSnapshotForTests(): Array<{
key: string;
sizeBytes: number;
storedAt: number;
provenance: CursorBlobProvenance;
requestPins: number;
dataDigest: string;
pinTokens: string[];
}> {
return [...blobs].map(([blobKey, entry]) => ({
key: blobKey,
sizeBytes: entry.sizeBytes,
storedAt: entry.storedAt,
provenance: entry.provenance,
requestPins: entry.requestPins.size,
// Byte-for-byte content identity + exact pin-set membership so rollback
// tests can deep-compare complete state (review C1-2).
dataDigest: createHash("sha256").update(entry.data).digest("hex"),
pinTokens: [...entry.requestPins].map(scope => String(scope.description ?? "scope")).sort(),
}));
}
export async function handleCursorNativeExec(execMsg: ExecServerMessage, deps: CursorNativeExecContext = {}): Promise<Uint8Array[]> {
const execCase = execMsg.message.case;
if (deps.plainToolWording && !deps.nativeExecRedirectHint) {
deps = { ...deps, nativeExecRedirectHint: cursorPlainNativeExecFallback([...(deps.clientToolDefs ?? []), ...(deps.mcpToolDefs ?? [])]) };
}
if (execCase === "requestContextArgs") {
const tools = [...(deps.mcpToolDefs ?? []), ...(deps.clientToolDefs ?? [])];
return [execBytes(execMsg, "requestContextResult", create(RequestContextResultSchema, {
result: { case: "success", value: create(RequestContextSuccessSchema, { requestContext: create(RequestContextSchema, { tools }) }) },
}))];
}
if (!cursorUnsafeNativeLocalExecEnabled(deps)) {
if (execCase === "readArgs") return [rejectReadExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "writeArgs") return [rejectWriteExecForPolicy(execMsg, deps.nativeExecRedirectHint, deps.plainToolWording)];
if (execCase === "deleteArgs") return [rejectDeleteExecForPolicy(execMsg, deps.nativeExecRedirectHint, deps.plainToolWording)];
if (execCase === "lsArgs") return [rejectLsExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "grepArgs") return [rejectGrepExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "shellArgs") return [rejectShellExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "shellStreamArgs") return rejectShellStreamExecForPolicy(execMsg, deps.nativeExecRedirectHint);
if (execCase === "backgroundShellSpawnArgs") return [rejectBackgroundShellSpawnExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "writeShellStdinArgs") return [rejectWriteShellStdinExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "fetchArgs") return [rejectFetchExecForPolicy(execMsg, deps.nativeExecRedirectHint)];
}
if (execCase === "readArgs") return [readExec(execMsg)];
if (execCase === "writeArgs") return [deps.rejectNativeFileMutations ? rejectWriteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true, deps.plainToolWording) : writeExec(execMsg)];
if (execCase === "deleteArgs") return [deps.rejectNativeFileMutations ? rejectDeleteExecForApplyPatch(execMsg, deps.structuredEditAvailable === true, deps.plainToolWording) : deleteExec(execMsg)];
if (execCase === "lsArgs") return [lsExec(execMsg)];
if (execCase === "grepArgs") return [grepExec(execMsg)];
if (execCase === "shellArgs") return [shellExec(execMsg, deps.nativeExecRedirectHint)];
if (execCase === "shellStreamArgs") return shellStreamExec(execMsg, deps.foregroundShellOwner, deps.signal, deps.nativeExecRedirectHint);
if (execCase === "backgroundShellSpawnArgs") return [backgroundShellSpawnExec(execMsg, deps.sessionId ?? "")];
if (execCase === "writeShellStdinArgs") return [writeShellStdinExec(execMsg, deps.sessionId ?? "")];
if (execCase === "fetchArgs") return [await fetchExec(execMsg, deps)];
if (execCase === "mcpArgs" && execMsg.message.value.providerIdentifier === OCX_RESPONSES_TOOL_PROVIDER) {
return [execBytes(execMsg, "mcpResult", create(McpResultSchema, {
result: {
case: "error",
value: create(McpErrorSchema, { error: "Cursor requested a client Responses tool through the native exec channel; bridge suspension is not implemented." }),
},
}))];
}
if (execCase === "mcpArgs") return [await mcpExec(execMsg, deps)];
if (execCase === "listMcpResourcesExecArgs") return [await listMcpResourcesExec(execMsg, deps)];
if (execCase === "readMcpResourceExecArgs") return [await readMcpResourceExec(execMsg, deps)];
if (execCase === "computerUseArgs") return [await computerUseExec(execMsg, deps)];
if (execCase === "recordScreenArgs") return [await recordScreenExec(execMsg, deps)];
if (execCase === "diagnosticsArgs") {
const path = execMsg.message.value.path;
return [execBytes(execMsg, "diagnosticsResult", create(DiagnosticsResultSchema, {
result: {
case: "error",
value: create(DiagnosticsErrorSchema, {
path,
error: "Diagnostics are not supported by the opencodex Cursor transport.",
}),
},
}))];
}
// Unknown exec case — Cursor added a new native exec type that our protobuf definition does not
// 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 [
execThrowBytes(execMsg, "Unknown exec message variant; this client does not implement it."),
execStreamCloseBytes(execMsg),
];
}
export function handleCursorNativeKv(
kvMsg: KvServerMessage,
requestScope?: CursorBlobRequestScopeToken,
): Uint8Array {
if (kvMsg.message.case === "getBlobArgs") {
const blobKey = key(kvMsg.message.value.blobId);
const blobData = getBlob(blobKey);
// Splice-class corruption guard (devlog 260826 080): diagnostic only, never blocks serving.
if (blobData && !cursorBlobServeIntegrityOk(kvMsg.message.value.blobId, blobData)) {
debugProviderDiagnostic("cursor", "blob-integrity-mismatch", {
blobKey: blobKey.slice(0, 18),
servedBytes: blobData.byteLength,
});
}
if (blobData && requestScope && blobRequestScopes.get(requestScope)?.kind === "request") {
releaseHydratedBlob(blobKey, requestScope);
}
return clientBytes({
message: {
case: "kvClientMessage",
value: create(KvClientMessageSchema, {
id: kvMsg.id,
message: { case: "getBlobResult", value: create(GetBlobResultSchema, blobData ? { blobData } : {}) },
}),
},
});
}
if (kvMsg.message.case === "setBlobArgs") {
const admission = setBlob(
key(kvMsg.message.value.blobId),
kvMsg.message.value.blobData,
"remote-setBlobArgs",
requestScope,
);
return clientBytes({
message: {
case: "kvClientMessage",
value: create(KvClientMessageSchema, {
id: kvMsg.id,
message: {
case: "setBlobResult",
value: create(SetBlobResultSchema, admission.admitted ? {} : {
error: create(ErrorSchema, {
message: "Cursor blob capacity is exhausted; the blob was not stored.",
}),
}),
},
}),
},
});
}
return clientBytes({ message: { case: "kvClientMessage", value: create(KvClientMessageSchema, { id: kvMsg.id }) } });
}