@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
110 lines (104 loc) • 5.1 kB
text/typescript
import type { OcxUsage } from "../../types";
import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
import type { CursorRoutingLevel } from "./discovery";
import type { CursorCheckpointInvalidationReason } from "./checkpoint-store";
import type { ResolvedCursorImage } from "./images";
export interface CursorRequestedModelParameter {
id: string;
value: string;
}
export interface CursorRunRequest {
modelId: string;
/**
* Normalized Cursor identity scope carried from request parsing so checkpoint
* observations stay scope-local. Transport metadata only; never serialized on the wire.
*/
_cursorIdentityScope?: string;
/** Cursor model-picker parameters encoded through AgentRunRequest.requested_model. */
requestedModelParameters?: readonly CursorRequestedModelParameter[];
/** Cursor Router optimization parameter; valid only while modelId is the `default` wire model. */
routingLevel?: CursorRoutingLevel;
/**
* Cursor Max Mode (ultra/big-context). Set from a synthetic `-1m` picker variant; the wire
* keeps the original model id and raises RequestedModel.maxMode + ModelDetails.maxMode
* (both fields — missing either can invalid_argument upstream). Devlog 260826 070.
*/
maxMode?: boolean;
/**
* Bare API callers (no caller tools, no Codex thread identity) pay a ~10-15K input-token
* preamble because an absent AgentRunRequest.mcp_tools field makes Cursor inject its default
* native tool catalog. When true, an explicitly empty McpTools wrapper is serialized instead,
* suppressing that default. Codex-identified sessions keep the absent-field behavior.
*/
suppressDefaultCursorToolCatalog?: boolean;
/**
* Corrective active-turn text for the single envelope-echo retry (devlog 260826 gap-10).
* When set on an external tool-result continuation, buildPreparedCursorRunRequest uses it as
* the userMessageAction prefix instead of the standard continuation text; rawMessages stay
* untouched so history replay is unchanged.
*/
echoRetryContinuationText?: string;
conversationId: string;
/** Prompt fallback for Responses structured output; Cursor has no native schema field. */
textFormat?: OcxRequestOptions["textFormat"];
system: string[];
messages: CursorRequestMessage[];
rawMessages?: readonly OcxMessage[];
/**
* Images for the active user/developer turn or an external model's trailing tool-result run.
* Encoded as SelectedImage blobIdWithData refs under
* UserMessage.selected_context (bytes live in the request-scoped KV store for getBlobArgs
* hydration). Bounded sourceLabel metadata from tool images is appended to the active action,
* outside prunable history; it is not a new image wire field. Native Composer selection stays
* unchanged. History stays text-only. data: URLs only in this slice.
*/
selectedImages?: readonly ResolvedCursorImage[];
tools?: OcxTool[];
toolChoice?: OcxRequestOptions["toolChoice"];
parallelToolCalls?: boolean;
/**
* Clear provider-private context-usage carry-forward before this run. Used when Codex starts a
* newly observed compacted context epoch, so pre-compaction totals are not over-reported while
* historical previous_response_id replay remains idempotent.
*/
contextUsageReset?: boolean;
/**
* Defaults to true. Set false for compaction summarizer turns: their checkpoints describe the
* 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 {
role: "user" | "assistant" | "developer" | "tool";
content: string;
}
export type CursorServerMessage =
| { type: "text"; text: string }
| { type: "thinking"; thinking: string }
| { type: "tool_call_start"; id: string; name: string }
| { type: "tool_call_delta"; arguments: string }
| { type: "tool_call_end"; id?: string }
| { type: "done"; usage?: OcxUsage }
| { type: "error"; message: string; usage?: OcxUsage }
| { type: "heartbeat" }
| { type: "kv_get"; key: string }
| { type: "kv_set"; key: string; value: Uint8Array }
| { type: "exec"; execCase: string; requestId: string }
/** A native exec/MCP action ran locally; retrying this turn could duplicate its side effects. */
| { type: "local_side_effect" };
export type CursorClientMessage =
| { type: "kv_value"; key: string; value?: Uint8Array }
| { type: "kv_stored"; key: string }
| { type: "exec_result"; requestId: string; ok: boolean; message: string };