@oai404iao/pi-codex-runtime 0.1.0-alpha.1

package/src/model-catalog/default-models.json

@@ -0,0 +1,252 @@
+{
+  "version": 1,
+  "models": [
+    {
+      "id": "openai/gpt-5.6-sol",
+      "enabled": true,
+      "responses": {
+        "providerShim": true,
+        "endpoint": "openai",
+        "mode": "lite",
+        "systemPromptPlacement": "developer",
+        "transport": "auto",
+        "websocketPrewarm": true
+      },
+      "tools": {
+        "parallelCalls": false,
+        "applyPatch": "custom",
+        "webSearch": {
+          "implementation": "standalone",
+          "contentTypes": ["text", "image"]
+        },
+        "imageGeneration": "standalone",
+        "viewImage": false
+      },
+      "compaction": "responses",
+      "fast": {
+        "serviceTier": "priority",
+        "costMultiplier": 2
+      }
+    },
+    {
+      "id": "openai/gpt-5.6-terra",
+      "extends": "openai/gpt-5.6-sol"
+    },
+    {
+      "id": "openai/gpt-5.6-luna",
+      "extends": "openai/gpt-5.6-sol"
+    },
+    {
+      "id": "openai/gpt-5.5",
+      "enabled": true,
+      "responses": {
+        "providerShim": true,
+        "endpoint": "openai",
+        "mode": "standard",
+        "systemPromptPlacement": "instructions",
+        "transport": "auto",
+        "websocketPrewarm": true
+      },
+      "tools": {
+        "parallelCalls": true,
+        "applyPatch": "custom",
+        "webSearch": {
+          "implementation": "hosted",
+          "contentTypes": ["text", "image"]
+        },
+        "imageGeneration": "standalone",
+        "viewImage": false
+      },
+      "compaction": "responses",
+      "fast": {
+        "serviceTier": "priority",
+        "costMultiplier": 2.5
+      }
+    },
+    {
+      "id": "openai/gpt-5.4",
+      "extends": "openai/gpt-5.5",
+      "fast": {
+        "serviceTier": "priority",
+        "costMultiplier": 2
+      }
+    },
+    {
+      "id": "openai/gpt-5.4-mini",
+      "extends": "openai/gpt-5.4",
+      "fast": false
+    },
+    {
+      "id": "openai/gpt-5.2",
+      "extends": "openai/gpt-5.4-mini",
+      "tools": {
+        "webSearch": {
+          "implementation": "hosted",
+          "contentTypes": ["text"]
+        }
+      }
+    },
+    {
+      "id": "openai/codex-auto-review",
+      "extends": "openai/gpt-5.4-mini"
+    },
+    {
+      "id": "openai/gpt-5",
+      "extends": "openai/gpt-5.2",
+      "fast": {
+        "serviceTier": "priority",
+        "costMultiplier": 2
+      }
+    },
+    {
+      "id": "openai/gpt-5-mini",
+      "extends": "openai/gpt-5",
+      "fast": false
+    },
+    {
+      "id": "openai/gpt-5.1",
+      "extends": "openai/gpt-5"
+    },
+    {
+      "id": "openai/gpt-5.1-codex",
+      "extends": "openai/gpt-5.1"
+    },
+    {
+      "id": "openai/gpt-5.3-codex",
+      "extends": "openai/gpt-5.4-mini"
+    },
+    {
+      "id": "openai/gpt-4.1",
+      "enabled": true,
+      "responses": {
+        "providerShim": true,
+        "endpoint": "openai",
+        "mode": "standard",
+        "systemPromptPlacement": "instructions",
+        "transport": "sse",
+        "websocketPrewarm": false
+      },
+      "tools": {
+        "parallelCalls": true,
+        "applyPatch": false,
+        "webSearch": false,
+        "imageGeneration": "hosted",
+        "viewImage": false
+      },
+      "compaction": "pi",
+      "fast": false
+    },
+    {
+      "id": "openai/o4-mini",
+      "extends": "openai/gpt-4.1",
+      "tools": {
+        "imageGeneration": false
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.6-sol",
+      "extends": "openai/gpt-5.6-sol",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.6-terra",
+      "extends": "openai/gpt-5.6-terra",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.6-luna",
+      "extends": "openai/gpt-5.6-luna",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.5",
+      "extends": "openai/gpt-5.5",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.4",
+      "extends": "openai/gpt-5.4",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.4-mini",
+      "extends": "openai/gpt-5.4-mini",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.2",
+      "extends": "openai/gpt-5.2",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/codex-auto-review",
+      "extends": "openai/codex-auto-review",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5",
+      "extends": "openai/gpt-5",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5-mini",
+      "extends": "openai/gpt-5-mini",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.1",
+      "extends": "openai/gpt-5.1",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.1-codex",
+      "extends": "openai/gpt-5.1-codex",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-5.3-codex",
+      "extends": "openai/gpt-5.3-codex",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/gpt-4.1",
+      "extends": "openai/gpt-4.1",
+      "responses": {
+        "endpoint": "codex"
+      }
+    },
+    {
+      "id": "openai-codex/o4-mini",
+      "extends": "openai/o4-mini",
+      "responses": {
+        "endpoint": "codex"
+      }
+    }
+  ]
+}

package/src/model-catalog/runtime.ts

@@ -0,0 +1,113 @@
+import type { CodexRequestProfileOverride } from "../codex-request-profile.js";
+import {
+	loadSettings,
+	type CodexMinimalToolsSettings,
+} from "../settings.js";
+import { resolveModelProfile } from "./catalog.js";
+import type {
+	ModelIdentityLike,
+	ResolvedModelProfile,
+	ResponsesEndpoint,
+} from "./types.js";
+
+export interface ResolvedCodexModelSettings extends CodexMinimalToolsSettings {
+	modelProfile?: ResolvedModelProfile;
+	modelProfileHash?: string;
+	providerShimActive?: boolean;
+	webSearchImplementation?: "hosted" | "standalone";
+	imageGenerationImplementation?: "hosted" | "standalone";
+	fastServiceTier?: string;
+	fastCostMultiplier?: number;
+}
+
+function endpointUsesApiKey(endpoint: ResponsesEndpoint, model: ModelIdentityLike | undefined): boolean {
+	if (endpoint === "openai") return true;
+	if (endpoint === "codex") return false;
+	return model?.provider !== "openai-codex";
+}
+
+export function supportsCodexResponsesApi(model: ModelIdentityLike | undefined): boolean {
+	if (model?.api === "openai-responses" || model?.api === "openai-codex-responses") return true;
+	if (model?.api) return false;
+	return model?.provider === "openai" || model?.provider === "openai-codex";
+}
+
+export function loadModelSettings(
+	model: ModelIdentityLike | undefined,
+	cwd?: string,
+	baseSettings = loadSettings(cwd),
+): ResolvedCodexModelSettings {
+	const modelProfile = resolveModelProfile(model, { settings: baseSettings });
+	if (!modelProfile || !modelProfile.effective.enabled) {
+		return {
+			...baseSettings,
+			providerShimActive: false,
+			nativeProviderTools: false,
+			openaiTransport: "sse",
+			openaiWebSocketPrewarm: false,
+			compactionMode: "pi",
+			requestProfile: {
+				responsesMode: "standard",
+				reasoningSummary: "auto",
+				systemPromptPlacement: "instructions",
+				patchTransport: "function",
+				supportsHostedTools: false,
+				supportsParallelTools: true,
+			},
+			apiKeyMode: model?.provider !== "openai-codex",
+			imageGeneration: false,
+			webSearchEnabled: false,
+			viewImage: false,
+			applyPatchEnabled: false,
+		};
+	}
+
+	const effective = modelProfile.effective;
+	const packageEnabled = baseSettings.enabled;
+	const providerShimActive = packageEnabled
+		&& effective.responses.providerShim
+		&& supportsCodexResponsesApi(model);
+	const configuredWebSearchImplementation = effective.tools.webSearch
+		? effective.tools.webSearch.implementation
+		: undefined;
+	const configuredImageGenerationImplementation = effective.tools.imageGeneration || undefined;
+	const webSearchImplementation = !packageEnabled
+		|| (configuredWebSearchImplementation === "hosted" && !providerShimActive)
+		? undefined
+		: configuredWebSearchImplementation;
+	const imageGenerationImplementation = !packageEnabled
+		|| (configuredImageGenerationImplementation === "hosted" && !providerShimActive)
+		? undefined
+		: configuredImageGenerationImplementation;
+	const supportsHostedTools = webSearchImplementation === "hosted"
+		|| imageGenerationImplementation === "hosted";
+	const usesProviderToolRewrite = Boolean(webSearchImplementation || imageGenerationImplementation);
+	const requestProfile: CodexRequestProfileOverride = {
+		responsesMode: effective.responses.mode,
+		reasoningSummary: effective.responses.reasoningSummary,
+		systemPromptPlacement: effective.responses.systemPromptPlacement,
+		patchTransport: effective.tools.applyPatch === "custom" ? "custom" : "function",
+		supportsHostedTools,
+		supportsParallelTools: effective.tools.parallelCalls,
+	};
+	return {
+		...baseSettings,
+		providerShimActive,
+		nativeProviderTools: providerShimActive && usesProviderToolRewrite,
+		openaiTransport: effective.responses.transport,
+		openaiWebSocketPrewarm: effective.responses.websocketPrewarm,
+		compactionMode: providerShimActive ? effective.compaction : "pi",
+		requestProfile,
+		apiKeyMode: endpointUsesApiKey(effective.responses.endpoint, model),
+		imageGeneration: imageGenerationImplementation !== undefined,
+		webSearchEnabled: webSearchImplementation !== undefined,
+		viewImage: packageEnabled && effective.tools.viewImage,
+		applyPatchEnabled: packageEnabled && effective.tools.applyPatch !== false,
+		modelProfile,
+		modelProfileHash: modelProfile.profileHash,
+		webSearchImplementation,
+		imageGenerationImplementation,
+		fastServiceTier: providerShimActive && effective.fast ? effective.fast.serviceTier : undefined,
+		fastCostMultiplier: providerShimActive && effective.fast ? effective.fast.costMultiplier : undefined,
+	};
+}

package/src/model-catalog/types.ts

@@ -0,0 +1,95 @@
+export type ResponsesEndpoint = "auto" | "openai" | "codex";
+export type ResponsesMode = "standard" | "lite";
+export type ReasoningSummary = "auto" | "concise" | "detailed" | "none";
+export type ResponsesTransport = "sse" | "websocket" | "websocket-cached" | "auto";
+export type SystemPromptPlacement = "instructions" | "developer";
+export type PatchTransport = "function" | "custom";
+export type WebSearchContentType = "text" | "image";
+export type NativeCompactionMode = "pi" | "responses" | "responses-compact";
+
+export interface ModelIdentityLike {
+	provider?: string;
+	id?: string;
+	name?: string;
+	api?: string;
+}
+
+export interface ResponsesProfilePatch {
+	providerShim?: boolean;
+	endpoint?: ResponsesEndpoint;
+	mode?: ResponsesMode;
+	reasoningSummary?: ReasoningSummary;
+	systemPromptPlacement?: SystemPromptPlacement;
+	transport?: ResponsesTransport;
+	websocketPrewarm?: boolean;
+}
+
+export interface WebSearchProfile {
+	implementation: "hosted" | "standalone";
+	contentTypes?: WebSearchContentType[];
+}
+
+export interface ModelToolsProfilePatch {
+	parallelCalls?: boolean;
+	applyPatch?: false | PatchTransport;
+	webSearch?: false | WebSearchProfile;
+	imageGeneration?: false | "hosted" | "standalone";
+	viewImage?: boolean;
+}
+
+export interface FastModeProfile {
+	serviceTier: string;
+	costMultiplier?: number;
+}
+
+export interface ModelProfilePatch {
+	id: string;
+	extends?: string;
+	enabled?: boolean;
+	responses?: ResponsesProfilePatch;
+	tools?: ModelToolsProfilePatch;
+	compaction?: NativeCompactionMode;
+	fast?: false | FastModeProfile;
+}
+
+export interface ModelCatalogFile {
+	$schema?: string;
+	version: 1;
+	models: ModelProfilePatch[];
+}
+
+export interface EffectiveResponsesProfile {
+	providerShim: boolean;
+	endpoint: ResponsesEndpoint;
+	mode: ResponsesMode;
+	reasoningSummary: ReasoningSummary;
+	systemPromptPlacement: SystemPromptPlacement;
+	transport: ResponsesTransport;
+	websocketPrewarm: boolean;
+}
+
+export interface EffectiveModelToolsProfile {
+	parallelCalls: boolean;
+	applyPatch: false | PatchTransport;
+	webSearch: false | WebSearchProfile;
+	imageGeneration: false | "hosted" | "standalone";
+	viewImage: boolean;
+}
+
+export interface EffectiveModelProfile {
+	enabled: boolean;
+	responses: EffectiveResponsesProfile;
+	tools: EffectiveModelToolsProfile;
+	compaction: NativeCompactionMode;
+	fast: false | FastModeProfile;
+}
+
+export type ModelProfileSource = "bundled" | "user" | "legacy";
+
+export interface ResolvedModelProfile {
+	id: string;
+	sources: ModelProfileSource[];
+	profileHash: string;
+	effective: EffectiveModelProfile;
+	diagnostics: string[];
+}

package/src/provider-headers.ts

@@ -0,0 +1,54 @@
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
+
+const suppressedHeaders = new WeakMap<Headers, Set<string>>();
+
+function normalizedName(name: string): string {
+	return name.trim().toLowerCase();
+}
+
+export function providerHeaderDirective(
+	headers: ProviderHeaders | undefined,
+	name: string,
+): string | null | undefined {
+	const target = normalizedName(name);
+	let directive: string | null | undefined;
+	for (const [candidate, value] of Object.entries(headers ?? {})) {
+		if (normalizedName(candidate) === target) directive = value;
+	}
+	return directive;
+}
+
+export function mergeProviderHeaders(...layers: Array<ProviderHeaders | undefined>): Headers {
+	const headers = new Headers();
+	const suppressed = new Set<string>();
+	for (const layer of layers) {
+		for (const [name, value] of Object.entries(layer ?? {})) {
+			const normalized = normalizedName(name);
+			if (value === null) {
+				headers.delete(name);
+				suppressed.add(normalized);
+			} else {
+				headers.set(name, value);
+				suppressed.delete(normalized);
+			}
+		}
+	}
+	suppressedHeaders.set(headers, suppressed);
+	return headers;
+}
+
+export function isProviderHeaderSuppressed(headers: Headers, name: string): boolean {
+	return suppressedHeaders.get(headers)?.has(normalizedName(name)) ?? false;
+}
+
+export function setProviderDefaultHeader(headers: Headers, name: string, value: string): boolean {
+	if (isProviderHeaderSuppressed(headers, name) || headers.has(name)) return false;
+	headers.set(name, value);
+	return true;
+}
+
+export function setProviderGeneratedHeader(headers: Headers, name: string, value: string): boolean {
+	if (isProviderHeaderSuppressed(headers, name)) return false;
+	headers.set(name, value);
+	return true;
+}

package/src/providers/openai-codex/stream-effects.ts

@@ -0,0 +1,21 @@
+import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-works/pi-ai/compat";
+import type { StreamEventShape } from "./types.js";
+
+export interface ProviderEventContext {
+	cwd: string;
+	requestPrompt?: string;
+	signal?: AbortSignal;
+	output: AssistantMessage;
+	stream: AssistantMessageEventStream;
+}
+
+/**
+ * A fresh observer is created for each response attempt. Events are normalized
+ * and continuation items captured before observation; observation is awaited
+ * before replay parsing. Observers must not mutate wire items or consume events.
+ * Optional effects own their failure policy; uncaught errors fail the stream.
+ */
+export interface ProviderStreamEffects {
+	createEventObserver?: (context: ProviderEventContext) =>
+		(event: StreamEventShape) => void | Promise<void>;
+}

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

@@ -0,0 +1,155 @@
+import { type SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
+import { type ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
+import { type CodexRequestIdentity } from "../../codex-wire-identity.js";
+
+export interface WebSocketLike {
+	readyState?: number;
+	bufferedAmount?: number;
+	send(data: string, callback?: (error?: Error) => void): void;
+	close(code?: number, reason?: string): void;
+	addEventListener(type: string, listener: (event: unknown) => void): void;
+	removeEventListener(type: string, listener: (event: unknown) => void): void;
+}
+
+export interface SessionWebSocketCacheEntry {
+	socket: WebSocketLike;
+	busy: boolean;
+	waiters: WebSocketAcquireWaiter[];
+	idleTimer?: ReturnType<typeof setTimeout>;
+	continuation?: CachedWebSocketContinuationState;
+}
+
+export interface WebSocketAcquireWaiter {
+	resolve: (acquired: AcquiredWebSocket) => void;
+	reject: (error: Error) => void;
+	signal?: AbortSignal;
+	onAbort?: () => void;
+}
+
+export interface AcquiredWebSocket {
+	socket: WebSocketLike;
+	entry?: SessionWebSocketCacheEntry;
+	reused: boolean;
+	release: (options?: { keep?: boolean }) => void;
+}
+
+export interface CachedWebSocketContinuationState {
+	lastRequestBody: ResponsesBody;
+	lastResponseId: string;
+	lastResponseItems: unknown[];
+}
+
+export interface WebSocketPrewarmRequest {
+	url: string;
+	headers: Headers;
+	cacheKey: string;
+	body: ResponsesBody;
+	requestMetadata: WebSocketRequestMetadata;
+	signal?: AbortSignal;
+	connectTimeoutMs?: number;
+}
+
+export interface WebSocketRequestMetadata {
+	/** Legacy Pi session lookup key used by exported test helpers. */
+	sessionId?: string;
+	threadId?: string;
+	turnId: string;
+	requestKind?: "turn" | "compaction" | "prewarm";
+	identity?: CodexRequestIdentity;
+}
+
+export type NativeToolOwnership = (name: "web_search" | "image_generation") => boolean;
+
+export interface OpenAIResponsesProviderController {
+	ownsNativeTool?: NativeToolOwnership;
+	getCurrentTurnId(sessionId: string | undefined): string | undefined;
+	getRequestIdentity?(
+		sessionId: string | undefined,
+		requestKind?: CodexRequestIdentity["requestKind"],
+	): CodexRequestIdentity | undefined;
+}
+
+export interface ResponsesBody {
+	model: string;
+	store: boolean;
+	stream: boolean;
+	instructions?: string;
+	previous_response_id?: string;
+	input: unknown[];
+	text: { verbosity: string };
+	include: string[];
+	prompt_cache_key?: string;
+	tool_choice: "auto";
+	parallel_tool_calls: boolean;
+	temperature?: number;
+	service_tier?: string;
+	generate?: boolean;
+	tools?: unknown[];
+	reasoning?: {
+		effort?: string;
+		summary?: string;
+		context?: "all_turns";
+	};
+	client_metadata?: Record<string, string>;
+	[key: string]: unknown;
+}
+
+interface ResponseEnvelope {
+	id?: string;
+	status?: string;
+	usage?: {
+		input_tokens?: number;
+		output_tokens?: number;
+		total_tokens?: number;
+		input_tokens_details?: { cached_tokens?: number };
+	};
+	service_tier?: string;
+	error?: { message?: string };
+	[key: string]: unknown;
+}
+
+export type ServiceTier = ResponseCreateParamsStreaming["service_tier"];
+
+export type ProviderTransport = NonNullable<SimpleStreamOptions["transport"]>;
+
+export interface NodeWebSocketModule {
+	WebSocket: new (url: string, options?: Record<string, unknown>) => {
+		readyState: number;
+		bufferedAmount: number;
+		send(data: string, callback?: (error?: Error) => void): void;
+		close(code?: number, reason?: string): void;
+		terminate?(): void;
+		on(type: string, listener: (...args: any[]) => void): void;
+		off(type: string, listener: (...args: any[]) => void): void;
+	};
+}
+
+export interface StreamEventShape {
+	type?: string;
+	status?: number;
+	status_code?: number;
+	sequence_number?: number;
+	error?: {
+		type?: string;
+		message?: string;
+		code?: string;
+		plan_type?: string;
+		resets_at?: number;
+		[key: string]: unknown;
+	};
+	response?: ResponseEnvelope;
+	item_id?: string;
+	output_index?: number;
+	item?: {
+		id?: string;
+		type?: string;
+		result?: string | null;
+		output_format?: string;
+		revised_prompt?: string;
+		status?: string;
+		[key: string]: unknown;
+	};
+	code?: string;
+	message?: string;
+	[key: string]: unknown;
+}