@vib-rato/ai 0.16.0

package/src/providers/openai-codex/constants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Constants for OpenAI code provider (ChatGPT OAuth) backend
+ */
+export declare const CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+export declare const OPENAI_HEADERS: {
+    readonly BETA: "OpenAI-Beta";
+    readonly ACCOUNT_ID: "chatgpt-account-id";
+    readonly ORIGINATOR: "originator";
+    readonly SESSION_ID: "session_id";
+    readonly CONVERSATION_ID: "conversation_id";
+};
+export declare const OPENAI_HEADER_VALUES: {
+    readonly BETA_RESPONSES: "responses=experimental";
+    readonly BETA_RESPONSES_WEBSOCKETS_V2: "responses_websockets=2026-02-06";
+    readonly ORIGINATOR_CODEX: "pi";
+};
+export declare const URL_PATHS: {
+    readonly RESPONSES: "/responses";
+    readonly CODEX_RESPONSES: "/codex/responses";
+};
+export declare const JWT_CLAIM_PATH: "https://api.openai.com/auth";
+/**
+ * Extract account ID from a OpenAI code backend JWT access token.
+ * Returns undefined if the token is not a valid OpenAI code backend JWT.
+ */
+export declare function getCodexAccountId(accessToken: string): string | undefined;

package/src/providers/openai-codex/constants.ts

@@ -0,0 +1,43 @@
+/**
+ * Constants for OpenAI code provider (ChatGPT OAuth) backend
+ */
+
+export const CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+
+export const OPENAI_HEADERS = {
+	BETA: "OpenAI-Beta",
+	ACCOUNT_ID: "chatgpt-account-id",
+	ORIGINATOR: "originator",
+	SESSION_ID: "session_id",
+	CONVERSATION_ID: "conversation_id",
+} as const;
+
+export const OPENAI_HEADER_VALUES = {
+	BETA_RESPONSES: "responses=experimental",
+	BETA_RESPONSES_WEBSOCKETS_V2: "responses_websockets=2026-02-06",
+	ORIGINATOR_CODEX: "pi",
+} as const;
+
+export const URL_PATHS = {
+	RESPONSES: "/responses",
+	CODEX_RESPONSES: "/codex/responses",
+} as const;
+
+export const JWT_CLAIM_PATH = "https://api.openai.com/auth" as const;
+
+/**
+ * Extract account ID from a OpenAI code backend JWT access token.
+ * Returns undefined if the token is not a valid OpenAI code backend JWT.
+ */
+export function getCodexAccountId(accessToken: string): string | undefined {
+	try {
+		const parts = accessToken.split(".");
+		if (parts.length !== 3) return undefined;
+		const decoded = Buffer.from(parts[1] ?? "", "base64").toString("utf-8");
+		const payload = JSON.parse(decoded) as Record<string, unknown>;
+		const auth = payload[JWT_CLAIM_PATH] as { chatgpt_account_id?: string } | undefined;
+		return auth?.chatgpt_account_id ?? undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/providers/openai-codex/request-transformer.d.ts

@@ -0,0 +1,50 @@
+import type { Api, Model } from "../../types";
+export interface ReasoningConfig {
+    effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    summary?: "auto" | "concise" | "detailed";
+}
+export interface CodexRequestOptions {
+    reasoningEffort?: ReasoningConfig["effort"];
+    reasoningSummary?: ReasoningConfig["summary"] | null;
+    textVerbosity?: "low" | "medium" | "high";
+    include?: string[];
+}
+export interface InputItem {
+    id?: string | null;
+    type?: string | null;
+    role?: string;
+    content?: unknown;
+    call_id?: string | null;
+    name?: string;
+    output?: unknown;
+    arguments?: unknown;
+    encrypted_content?: unknown;
+}
+export interface RequestBody {
+    model: string;
+    store?: boolean;
+    stream?: boolean;
+    instructions?: string;
+    input?: InputItem[];
+    tools?: unknown;
+    tool_choice?: unknown;
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    min_p?: number;
+    presence_penalty?: number;
+    repetition_penalty?: number;
+    reasoning?: Partial<ReasoningConfig>;
+    text?: {
+        verbosity?: "low" | "medium" | "high";
+    };
+    include?: string[];
+    prompt_cache_key?: string;
+    prompt_cache_retention?: "in_memory" | "24h";
+    max_output_tokens?: number;
+    max_completion_tokens?: number;
+    [key: string]: unknown;
+}
+export declare function transformRequestBody(body: RequestBody, model: Model<Api>, options?: CodexRequestOptions, prompt?: {
+    developerMessages: string[];
+}): Promise<RequestBody>;

package/src/providers/openai-codex/request-transformer.ts

@@ -0,0 +1,219 @@
+import type { Effort } from "../../model-thinking";
+import { requireSupportedEffort } from "../../model-thinking";
+import type { Api, Model } from "../../types";
+import { sanitizeJsonStrings } from "../../utils";
+
+export interface ReasoningConfig {
+	effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+	summary?: "auto" | "concise" | "detailed";
+}
+
+export interface CodexRequestOptions {
+	reasoningEffort?: ReasoningConfig["effort"];
+	reasoningSummary?: ReasoningConfig["summary"] | null;
+	textVerbosity?: "low" | "medium" | "high";
+	include?: string[];
+}
+
+export interface InputItem {
+	id?: string | null;
+	type?: string | null;
+	role?: string;
+	content?: unknown;
+	call_id?: string | null;
+	name?: string;
+	output?: unknown;
+	arguments?: unknown;
+	encrypted_content?: unknown;
+}
+
+export interface RequestBody {
+	model: string;
+	store?: boolean;
+	stream?: boolean;
+	instructions?: string;
+	input?: InputItem[];
+	tools?: unknown;
+	tool_choice?: unknown;
+	temperature?: number;
+	top_p?: number;
+	top_k?: number;
+	min_p?: number;
+	presence_penalty?: number;
+	repetition_penalty?: number;
+	reasoning?: Partial<ReasoningConfig>;
+	text?: {
+		verbosity?: "low" | "medium" | "high";
+	};
+	include?: string[];
+	prompt_cache_key?: string;
+	prompt_cache_retention?: "in_memory" | "24h";
+	max_output_tokens?: number;
+	max_completion_tokens?: number;
+	[key: string]: unknown;
+}
+
+function getReasoningConfig(model: Model<Api>, options: CodexRequestOptions): ReasoningConfig {
+	const config: ReasoningConfig = {
+		effort:
+			options.reasoningEffort === "none" ? "none" : requireSupportedEffort(model, options.reasoningEffort as Effort),
+	};
+	if (options.reasoningSummary !== null) {
+		config.summary = options.reasoningSummary ?? "detailed";
+	}
+	return config;
+}
+
+function describeTextPartValue(value: unknown): string {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+
+function normalizeTextPartValue(value: unknown, path: string): string {
+	if (typeof value === "string") return value.toWellFormed();
+	try {
+		const encoded = JSON.stringify(value);
+		if (typeof encoded === "string") return encoded.toWellFormed();
+	} catch {
+		// Fall through to the actionable local error below.
+	}
+	throw new Error(
+		`Invalid Codex request text part at ${path}: expected a string or JSON-serializable value, received ${describeTextPartValue(value)}. Normalize compacted continuation content before sending to Codex.`,
+	);
+}
+
+function normalizeTextPartFields(content: unknown, path: string): unknown {
+	if (typeof content === "string") return content.toWellFormed();
+	if (!Array.isArray(content)) return content;
+	return content.map((part, index) => {
+		if (!part || typeof part !== "object") return part;
+		const normalizedPart = { ...(part as Record<string, unknown>) };
+		if ("text" in normalizedPart) {
+			normalizedPart.text = normalizeTextPartValue(normalizedPart.text, `${path}[${index}].text`);
+		}
+		return normalizedPart;
+	});
+}
+
+function normalizeInputTextPartFields(input: InputItem[] | undefined): InputItem[] | undefined {
+	if (!Array.isArray(input)) return input;
+	return input.map((item, itemIndex) => {
+		const normalizedItem = { ...item };
+		const itemRecord = normalizedItem as Record<string, unknown>;
+		if ("encrypted_content" in itemRecord) {
+			if (typeof itemRecord.encrypted_content === "string") {
+				itemRecord.encrypted_content = itemRecord.encrypted_content.toWellFormed();
+			} else {
+				delete itemRecord.encrypted_content;
+			}
+		}
+		if (normalizedItem.type === "message") {
+			normalizedItem.content = normalizeTextPartFields(normalizedItem.content, `input[${itemIndex}].content`);
+		} else if (normalizedItem.type === "function_call" && "arguments" in itemRecord) {
+			itemRecord.arguments = sanitizeJsonStrings(itemRecord.arguments);
+		} else if (normalizedItem.type === "custom_tool_call" && typeof itemRecord.input === "string") {
+			itemRecord.input = itemRecord.input.toWellFormed();
+		}
+		return normalizedItem;
+	});
+}
+
+function filterInput(input: InputItem[] | undefined): InputItem[] | undefined {
+	if (!Array.isArray(input)) return input;
+
+	return input
+		.filter(item => item.type !== "item_reference")
+		.map(item => {
+			if (item.id != null) {
+				const { id: _id, ...rest } = item;
+				return rest as InputItem;
+			}
+			return item;
+		});
+}
+
+export async function transformRequestBody(
+	body: RequestBody,
+	model: Model<Api>,
+	options: CodexRequestOptions = {},
+	prompt?: { developerMessages: string[] },
+): Promise<RequestBody> {
+	body.store = false;
+	body.stream = true;
+
+	if (body.input && Array.isArray(body.input)) {
+		body.input = filterInput(body.input);
+
+		if (body.input) {
+			const functionCallIds = new Set(
+				body.input
+					.filter(item => item.type === "function_call" && typeof item.call_id === "string")
+					.map(item => item.call_id as string),
+			);
+
+			body.input = body.input.map(item => {
+				if (item.type === "function_call_output" && typeof item.call_id === "string") {
+					const callId = item.call_id as string;
+					if (!functionCallIds.has(callId)) {
+						const itemRecord = item as unknown as Record<string, unknown>;
+						const toolName = typeof itemRecord.name === "string" ? itemRecord.name : "tool";
+						let text = "";
+						try {
+							const output = itemRecord.output;
+							text = typeof output === "string" ? output : JSON.stringify(output);
+						} catch {
+							text = String(itemRecord.output ?? "");
+						}
+						if (text.length > 16000) {
+							text = `${text.slice(0, 16000)}\n...[truncated]`;
+						}
+						return {
+							type: "message",
+							role: "assistant",
+							content: `[Previous ${toolName} result; call_id=${callId}]: ${text}`,
+						} as InputItem;
+					}
+				}
+				return item;
+			});
+		}
+		body.input = normalizeInputTextPartFields(body.input);
+	}
+
+	if (prompt?.developerMessages && prompt.developerMessages.length > 0 && Array.isArray(body.input)) {
+		const developerMessages = prompt.developerMessages.map(
+			text =>
+				({
+					type: "message",
+					role: "developer",
+					content: [{ type: "input_text", text }],
+				}) as InputItem,
+		);
+		body.input = [...developerMessages, ...body.input];
+	}
+
+	if (options.reasoningEffort !== undefined) {
+		const reasoningConfig = getReasoningConfig(model, options);
+		body.reasoning = {
+			...body.reasoning,
+			...reasoningConfig,
+		};
+	} else {
+		delete body.reasoning;
+	}
+
+	body.text = {
+		...body.text,
+		verbosity: options.textVerbosity || "low",
+	};
+
+	const include = Array.isArray(options.include) ? [...options.include] : [];
+	include.push("reasoning.encrypted_content");
+	body.include = Array.from(new Set(include));
+
+	delete body.max_output_tokens;
+	delete body.max_completion_tokens;
+
+	return body;
+}

package/src/providers/openai-codex/response-handler.d.ts

@@ -0,0 +1,18 @@
+export type CodexRateLimit = {
+    used_percent?: number;
+    window_minutes?: number;
+    resets_at?: number;
+};
+export type CodexRateLimits = {
+    primary?: CodexRateLimit;
+    secondary?: CodexRateLimit;
+};
+export type CodexErrorInfo = {
+    message: string;
+    status: number;
+    code?: string;
+    friendlyMessage?: string;
+    rateLimits?: CodexRateLimits;
+    raw?: string;
+};
+export declare function parseCodexError(response: Response): Promise<CodexErrorInfo>;

package/src/providers/openai-codex/response-handler.ts

@@ -0,0 +1,111 @@
+import { toNumber } from "../../utils";
+
+export type CodexRateLimit = {
+	used_percent?: number;
+	window_minutes?: number;
+	resets_at?: number;
+};
+
+export type CodexRateLimits = {
+	primary?: CodexRateLimit;
+	secondary?: CodexRateLimit;
+};
+
+export type CodexErrorInfo = {
+	message: string;
+	status: number;
+	code?: string;
+	friendlyMessage?: string;
+	rateLimits?: CodexRateLimits;
+	raw?: string;
+};
+// Matches the gate's bare rejection body ("Request blocked." / "Request
+// blocked (…)") but never messages that merely mention blocking mid-text.
+const REQUEST_BLOCKED_MESSAGE_RE = /^\s*request blocked\b/i;
+
+export async function parseCodexError(response: Response): Promise<CodexErrorInfo> {
+	const raw = await response.text();
+	let message = raw || response.statusText || "Request failed";
+	let friendlyMessage: string | undefined;
+	let rateLimits: CodexRateLimits | undefined;
+	let code: string | undefined;
+
+	try {
+		const parsed = JSON.parse(raw) as { error?: Record<string, unknown>; detail?: unknown };
+		const err = parsed?.error ?? {};
+
+		const headers = response.headers;
+		const primary = {
+			used_percent: toNumber(headers.get("x-codex-primary-used-percent")),
+			window_minutes: toInt(headers.get("x-codex-primary-window-minutes")),
+			resets_at: toInt(headers.get("x-codex-primary-reset-at")),
+		};
+		const secondary = {
+			used_percent: toNumber(headers.get("x-codex-secondary-used-percent")),
+			window_minutes: toInt(headers.get("x-codex-secondary-window-minutes")),
+			resets_at: toInt(headers.get("x-codex-secondary-reset-at")),
+		};
+		rateLimits =
+			primary.used_percent !== undefined || secondary.used_percent !== undefined
+				? { primary, secondary }
+				: undefined;
+
+		code =
+			typeof (err as { code?: unknown }).code === "string"
+				? (err as { code: string }).code
+				: typeof (err as { type?: unknown }).type === "string"
+					? (err as { type: string }).type
+					: undefined;
+		const resetsAt = (err as { resets_at?: number }).resets_at ?? primary.resets_at ?? secondary.resets_at;
+		const mins = resetsAt ? Math.max(0, Math.round((resetsAt * 1000 - Date.now()) / 60000)) : undefined;
+
+		if (/usage_limit_reached|usage_not_included/i.test(code ?? "")) {
+			const planType = (err as { plan_type?: string }).plan_type;
+			const plan = planType ? ` (${String(planType).toLowerCase()} plan)` : "";
+			const when = mins !== undefined ? ` Try again in ~${mins} min.` : "";
+			friendlyMessage = `You have hit your ChatGPT usage limit${plan}.${when}`.trim();
+		} else if (/rate_limit_exceeded/i.test(code ?? "") || response.status === 429) {
+			const when = mins !== undefined ? ` Try again in ~${mins} min.` : "";
+			friendlyMessage = `ChatGPT rate limit exceeded.${when}`.trim();
+		}
+
+		const errMessage = (err as { message?: string }).message;
+		// The chatgpt.com/backend-api gate rejects with a bare-`detail` body
+		// (`{"detail": "Request blocked."}`) that carries no `error.*` envelope.
+		const detail =
+			typeof parsed?.detail === "string"
+				? parsed.detail
+				: typeof (parsed?.detail as { message?: unknown } | undefined)?.message === "string"
+					? (parsed.detail as { message: string }).message
+					: undefined;
+		message = errMessage || detail || friendlyMessage || message;
+	} catch {
+		// raw body not JSON
+	}
+
+	// A bare "Request blocked" body (detail-shaped JSON or plain text) is the
+	// pre-model gate's form of the deterministic `invalid_prompt` content
+	// rejection. It never carries a structured code, so classify it explicitly
+	// here; otherwise `isInvalidPromptError`, the codex non-retryable event set,
+	// and the session-level circuit breaker all miss it and the failure surfaces
+	// as an unexplained, unrepairable "Request Blocked".
+	if (!code && REQUEST_BLOCKED_MESSAGE_RE.test(message)) {
+		code = "invalid_prompt";
+		friendlyMessage = `${message.trim().replace(/\.+$/, "")} (code=invalid_prompt)`;
+	}
+
+	return {
+		message,
+		status: response.status,
+		friendlyMessage,
+		code,
+		rateLimits,
+		raw: raw,
+	};
+}
+
+function toInt(v: string | null): number | undefined {
+	if (v == null) return undefined;
+	const n = parseInt(v, 10);
+	return Number.isFinite(n) ? n : undefined;
+}

package/src/providers/openai-codex-responses.d.ts

@@ -0,0 +1,71 @@
+import type { ResponseInput } from "openai/resources/responses/responses";
+import { type Context, type Model, type ProviderSessionState, type ServiceTier, type StreamFunction, type StreamOptions, type Tool, type ToolChoice } from "../types";
+export { codexToolCanonicalName, codexToolWireName } from "../codex-tools";
+export interface OpenAICodexResponsesOptions extends StreamOptions {
+    reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    reasoningSummary?: "auto" | "concise" | "detailed" | null;
+    textVerbosity?: "low" | "medium" | "high";
+    include?: string[];
+    codexMode?: boolean;
+    toolChoice?: ToolChoice;
+    preferWebsockets?: boolean;
+    serviceTier?: ServiceTier;
+}
+type CodexTransport = "sse" | "websocket";
+export interface OpenAICodexWebSocketDebugStats {
+    fullContextRequests: number;
+    deltaRequests: number;
+    lastInputItems: number;
+    lastDeltaInputItems?: number;
+    lastPreviousResponseId?: string;
+}
+/** @internal Exported for tests. */
+export declare function normalizeCodexToolChoice(choice: ToolChoice | undefined, tools?: Tool[], model?: Model<"openai-codex-responses">): string | Record<string, unknown> | undefined;
+/** @internal Exported for tests. */
+export declare function formatCodexUserAgent(platform: string, release: string, arch: string): string;
+export declare const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses">;
+export declare function prewarmOpenAICodexResponses(model: Model<"openai-codex-responses">, options?: Pick<OpenAICodexResponsesOptions, "apiKey" | "headers" | "sessionId" | "signal" | "preferWebsockets" | "providerSessionState">): Promise<void>;
+export interface OpenAICodexTransportDetails {
+    websocketPreferred: boolean;
+    lastTransport?: CodexTransport;
+    websocketDisabled: boolean;
+    websocketConnected: boolean;
+    fallbackCount: number;
+    canAppend: boolean;
+    prewarmed: boolean;
+    hasSessionState: boolean;
+    lastFallbackAt?: number;
+}
+export declare function getOpenAICodexWebSocketDebugStats(model: Model<"openai-codex-responses">, options?: {
+    sessionId?: string;
+    baseUrl?: string;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}): OpenAICodexWebSocketDebugStats | undefined;
+export declare function getOpenAICodexTransportDetails(model: Model<"openai-codex-responses">, options?: {
+    sessionId?: string;
+    baseUrl?: string;
+    preferWebsockets?: boolean;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}): OpenAICodexTransportDetails;
+declare function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput;
+/** @internal Exported for tests. `classifyCodexFailureEventRetryable` is the retry classification of a Codex failure event. */
+export { convertMessages as convertCodexResponsesMessages, isRetryableCodexFailureEvent as classifyCodexFailureEventRetryable, };
+type CodexToolPayload = {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    strict?: boolean;
+} | {
+    type: "custom";
+    name: string;
+    description: string;
+    format: {
+        type: "grammar";
+        syntax: "lark" | "regex";
+        definition: string;
+    };
+};
+/** @internal Exported for tests. */
+export declare function convertOpenAICodexResponsesTools(tools: Tool[], model: Model<"openai-codex-responses">): CodexToolPayload[];
+declare function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean;