pi-openai-codex-compat 0.0.1-alpha.0

package/extensions/openai-codex-compat/native-history.ts

@@ -0,0 +1,78 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { isObject, isResponsesItem, type ResponsesItem } from "./codex-protocol.ts";
+
+export const NATIVE_RESPONSE_ENTRY_TYPE = "openai-codex-compat-native-response";
+export const NATIVE_RESPONSE_FORMAT_VERSION = 1;
+
+export type NativeResponseData = {
+  kind: typeof NATIVE_RESPONSE_ENTRY_TYPE;
+  version: typeof NATIVE_RESPONSE_FORMAT_VERSION;
+  modelId: string;
+  responseId: string;
+  items: ResponsesItem[];
+};
+
+export function nativeResponseData(
+  modelId: string,
+  responseId: string,
+  items: readonly ResponsesItem[],
+): NativeResponseData {
+  return {
+    kind: NATIVE_RESPONSE_ENTRY_TYPE,
+    version: NATIVE_RESPONSE_FORMAT_VERSION,
+    modelId,
+    responseId,
+    items: items.map((item) => structuredClone(item)),
+  };
+}
+
+export function parseNativeResponse(value: unknown): NativeResponseData | undefined {
+  if (!isObject(value)) return undefined;
+  if (
+    value.kind !== NATIVE_RESPONSE_ENTRY_TYPE ||
+    value.version !== NATIVE_RESPONSE_FORMAT_VERSION ||
+    typeof value.modelId !== "string" ||
+    typeof value["responseId"] !== "string" ||
+    !Array.isArray(value["items"])
+  ) {
+    return undefined;
+  }
+
+  const items: ResponsesItem[] = [];
+  for (const item of value["items"]) {
+    if (!isResponsesItem(item)) return undefined;
+    items.push(structuredClone(item));
+  }
+  if (items.length === 0) return undefined;
+
+  return {
+    kind: NATIVE_RESPONSE_ENTRY_TYPE,
+    version: NATIVE_RESPONSE_FORMAT_VERSION,
+    modelId: value.modelId,
+    responseId: value["responseId"],
+    items,
+  };
+}
+
+/** Load native assistant output overrides from the active Pi branch. */
+export function nativeResponseOverrides(
+  branch: readonly SessionEntry[],
+  modelId: string,
+): ReadonlyMap<string, ResponsesItem[]> {
+  const overrides = new Map<string, ResponsesItem[]>();
+
+  for (const entry of branch) {
+    if (entry.type !== "custom" || entry.customType !== NATIVE_RESPONSE_ENTRY_TYPE) continue;
+    const parsed = parseNativeResponse(entry.data);
+    if (!parsed) {
+      throw new Error(`Codex native response entry ${entry.id} is corrupt.`);
+    }
+    if (parsed.modelId !== modelId) continue;
+    overrides.set(
+      parsed.responseId,
+      parsed.items.map((item) => structuredClone(item)),
+    );
+  }
+
+  return overrides;
+}

package/extensions/openai-codex-compat/remote-compaction.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from "node:crypto";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  SessionBeforeCompactEvent,
+  SessionEntry,
+  ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import type { Model, OpenAICodexResponsesOptions } from "@earendil-works/pi-ai";
+import { addRemoteCompactionFeature, type JsonRecord } from "./codex-protocol.ts";
+import {
+  activeResponsesTools,
+  providerHistory,
+  searchCheckpoint,
+  type GrammarToolInputProperties,
+} from "./compaction-checkpoint.ts";
+import { loadConfig, type CodexCompatConfig } from "./config.ts";
+import type { CodexProviderRuntime } from "./codex-provider.ts";
+import { APPLY_PATCH_INPUT_PROPERTY, APPLY_PATCH_TOOL_NAME } from "./apply-patch.ts";
+
+const CODEX_PROVIDER = "openai-codex";
+const CODEX_API = "openai-codex-responses";
+
+type ConfigResolver = (ctx: ExtensionContext) => CodexCompatConfig;
+
+function selectedCodexModel(model: Model<any> | undefined): model is Model<any> {
+  return Boolean(model && model.provider === CODEX_PROVIDER && model.api === CODEX_API);
+}
+
+function resolveFileConfig(ctx: ExtensionContext): CodexCompatConfig {
+  return loadConfig(ctx.cwd, ctx.isProjectTrusted());
+}
+
+function appendFeatureHeader(headers: Record<string, string | null>): void {
+  const key = Object.keys(headers).find(
+    (header) => header.toLowerCase() === "x-codex-beta-features",
+  );
+  if (key) headers[key] = addRemoteCompactionFeature(headers[key]);
+  else headers["x-codex-beta-features"] = addRemoteCompactionFeature(undefined);
+}
+
+function featureHeaders(headers: Record<string, string> | undefined): Record<string, string> {
+  const result: Record<string, string | null> = { ...headers };
+  appendFeatureHeader(result);
+  return Object.fromEntries(
+    Object.entries(result).filter((entry): entry is [string, string] => entry[1] !== null),
+  );
+}
+
+function markerSummary(): string {
+  return `OpenAI Codex remote compaction checkpoint (${randomUUID()}).`;
+}
+
+function instructionsForCompaction(systemPrompt: string, customInstructions?: string): string {
+  const custom = customInstructions?.trim();
+  return custom
+    ? `${systemPrompt}\n\nAdditional guidance for this compaction:\n${custom}`
+    : systemPrompt;
+}
+
+function toolInputProperty(tool: ToolInfo | undefined): string | undefined {
+  if (tool?.name === APPLY_PATCH_TOOL_NAME) return APPLY_PATCH_INPUT_PROPERTY;
+  if (!tool || typeof tool.parameters !== "object" || tool.parameters === null) return undefined;
+  const schema = tool.parameters as {
+    required?: unknown;
+    properties?: Record<string, { type?: unknown } | undefined>;
+  };
+  const required = Array.isArray(schema.required)
+    ? schema.required.filter((name): name is string => typeof name === "string")
+    : [];
+  if (required.length !== 1 || !schema.properties) return undefined;
+  return schema.properties[required[0]!]?.type === "string" ? required[0] : undefined;
+}
+
+function requestGrammarToolInputProperties(
+  payload: JsonRecord,
+  tools: readonly ToolInfo[],
+): GrammarToolInputProperties {
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+  const properties = new Map<string, string>();
+  if (!Array.isArray(payload.tools)) return properties;
+
+  for (const declaration of payload.tools) {
+    if (typeof declaration !== "object" || declaration === null || Array.isArray(declaration)) {
+      continue;
+    }
+    const tool = declaration as JsonRecord;
+    if (tool.type !== "custom" || typeof tool.name !== "string") continue;
+    const property = toolInputProperty(byName.get(tool.name));
+    if (property) properties.set(tool.name, property);
+  }
+  return properties;
+}
+
+function fallbackGrammarToolInputProperties(
+  activeNames: readonly string[],
+  model: Model<any>,
+): GrammarToolInputProperties {
+  const compat = model.compat as { supportsOpenAIGrammarTools?: boolean } | undefined;
+  return activeNames.includes(APPLY_PATCH_TOOL_NAME) && compat?.supportsOpenAIGrammarTools
+    ? new Map([[APPLY_PATCH_TOOL_NAME, APPLY_PATCH_INPUT_PROPERTY]])
+    : new Map();
+}
+
+function explain(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export default function registerRemoteCompaction(
+  pi: ExtensionAPI,
+  runtime: CodexProviderRuntime,
+  resolveConfig: ConfigResolver = resolveFileConfig,
+): void {
+  pi.on("session_start", (_event, ctx) => runtime.captureScope(ctx));
+  pi.on("session_shutdown", (_event, ctx) => {
+    runtime.clearSession(ctx.sessionManager.getSessionId());
+  });
+
+  pi.on("context", (event, ctx) => {
+    runtime.captureScope(ctx);
+    const checkpoint = searchCheckpoint(ctx.sessionManager.getBranch() as SessionEntry[]);
+    if (checkpoint.kind === "absent") return undefined;
+    return {
+      messages: event.messages.filter((message) => message.role !== "compactionSummary"),
+    };
+  });
+
+  pi.on("before_provider_headers", (event, ctx) => {
+    if (selectedCodexModel(ctx.model)) appendFeatureHeader(event.headers);
+  });
+
+  pi.on("session_before_compact", async (event: SessionBeforeCompactEvent, ctx) => {
+    if (!selectedCodexModel(ctx.model)) return undefined;
+    if (event.signal.aborted) return { cancel: true };
+    runtime.captureScope(ctx);
+
+    try {
+      const authentication = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+      if (!authentication.ok) throw new Error(authentication.error);
+      if (!authentication.apiKey) throw new Error("OpenAI Codex authentication is unavailable.");
+
+      const sessionId = ctx.sessionManager.getSessionId();
+      const allTools = pi.getAllTools();
+      const cached = runtime.latestTemplate(sessionId);
+      const matching = cached?.modelId === ctx.model.id ? cached : undefined;
+      const config = resolveConfig(ctx);
+      const grammarToolInputProperties =
+        matching?.grammarToolInputProperties ??
+        fallbackGrammarToolInputProperties(pi.getActiveTools(), ctx.model);
+      const history = providerHistory({
+        branch: event.branchEntries as SessionEntry[],
+        wireModel: ctx.model,
+        allTools,
+        grammarToolInputProperties,
+        imageDetail: config.imageDetail,
+        dropLatestFailedAssistant: event.reason === "overflow" && event.willRetry,
+      });
+      const template =
+        matching?.payload ??
+        ({
+          tools: activeResponsesTools(allTools, pi.getActiveTools(), grammarToolInputProperties),
+        } satisfies JsonRecord);
+      const requestOptions: OpenAICodexResponsesOptions = {
+        ...matching?.requestOptions,
+        apiKey: authentication.apiKey,
+        headers: featureHeaders(authentication.headers),
+        sessionId,
+        signal: event.signal,
+      };
+      const compacted = await runtime.compact({
+        model: ctx.model,
+        requestOptions,
+        history,
+        instructions: instructionsForCompaction(ctx.getSystemPrompt(), event.customInstructions),
+        grammarToolInputProperties:
+          matching?.grammarToolInputProperties ??
+          requestGrammarToolInputProperties(template, allTools),
+        template,
+        priority: config.fastMode,
+      });
+
+      return {
+        compaction: {
+          summary: markerSummary(),
+          firstKeptEntryId: event.preparation.firstKeptEntryId,
+          tokensBefore: event.preparation.tokensBefore,
+          ...(compacted.usage ? { usage: compacted.usage } : {}),
+          details: compacted.checkpoint,
+        },
+      };
+    } catch (error) {
+      if (!event.signal.aborted && ctx.hasUI) {
+        ctx.ui.notify(`OpenAI Codex native compaction failed: ${explain(error)}`, "error");
+      }
+      return { cancel: true };
+    }
+  });
+}

package/extensions/openai-codex-compat/request-options.ts

@@ -0,0 +1,121 @@
+import { calculateCost, type AssistantMessage, type Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig, type CodexCompatConfig, type WebSearchMode } from "./config.ts";
+import { isObject, type JsonRecord } from "./codex-protocol.ts";
+import { splitNamespacedToolName, WEB_RUN_TOOL_NAME } from "./namespaced-tools.ts";
+
+const CODEX_PROVIDER = "openai-codex";
+const CODEX_API = "openai-codex-responses";
+
+export function isCodexModel(model: Model<any> | undefined): model is Model<any> {
+  return Boolean(model && model.provider === CODEX_PROVIDER && model.api === CODEX_API);
+}
+
+export function supportsReasoningMode(modelId: string): boolean {
+  return /^gpt-5\.6(?:-|$)/.test(modelId);
+}
+
+function isWebSearchTool(value: unknown): boolean {
+  return isObject(value) && value.type === "web_search";
+}
+
+function isWebRunNamespace(value: unknown): boolean {
+  if (!isObject(value) || value.type !== "namespace") return false;
+  const webRun = splitNamespacedToolName(WEB_RUN_TOOL_NAME)!;
+  return (
+    value.name === webRun.namespace &&
+    Array.isArray(value.tools) &&
+    value.tools.some(
+      (tool) => isObject(tool) && tool.type === "function" && tool.name === webRun.name,
+    )
+  );
+}
+
+function webSearchTool(mode: Exclude<WebSearchMode, "disabled">, images: boolean): JsonRecord {
+  return {
+    type: "web_search",
+    external_web_access: mode !== "cached",
+    ...(mode === "indexed" ? { indexed_web_access: true } : {}),
+    ...(images ? { search_content_types: ["text", "image"] } : {}),
+  };
+}
+
+export function applyCodexRequestOptions(
+  payload: JsonRecord,
+  config: CodexCompatConfig,
+  options: { modelId: string; supportsImageSearch: boolean },
+): JsonRecord {
+  const result = structuredClone(payload);
+
+  if (config.fastMode) result.service_tier = "priority";
+
+  const text = isObject(result.text) ? result.text : {};
+  result.text = { ...text, verbosity: config.textVerbosity };
+
+  const reasoning = result["reasoning"];
+  if (isObject(reasoning)) {
+    const updatedReasoning = { ...reasoning };
+    if (config.reasoningSummary === "off") {
+      Reflect.deleteProperty(updatedReasoning, "summary");
+    } else {
+      updatedReasoning["summary"] = config.reasoningSummary;
+    }
+    if (supportsReasoningMode(options.modelId)) {
+      updatedReasoning["mode"] = config.reasoningMode;
+    } else {
+      Reflect.deleteProperty(updatedReasoning, "mode");
+    }
+    result["reasoning"] = updatedReasoning;
+  }
+
+  const tools = Array.isArray(result.tools) ? result.tools : [];
+  const toolsWithoutSearch = tools.filter((tool) => !isWebSearchTool(tool));
+  if (tools.some(isWebRunNamespace) || config.webSearch === "disabled") {
+    if (Array.isArray(result.tools)) result.tools = toolsWithoutSearch;
+  } else {
+    result.tools = [
+      ...toolsWithoutSearch,
+      webSearchTool(config.webSearch, options.supportsImageSearch),
+    ];
+  }
+
+  return result;
+}
+
+/** Recompute cost from canonical rates so payload-only priority mode cannot be undercounted. */
+export function applyPriorityPricing(
+  message: AssistantMessage,
+  model: Model<any>,
+): AssistantMessage {
+  const usage = structuredClone(message.usage);
+  calculateCost(model, usage);
+  const multiplier = model.id === "gpt-5.5" ? 2.5 : 2;
+  usage.cost.input *= multiplier;
+  usage.cost.output *= multiplier;
+  usage.cost.cacheRead *= multiplier;
+  usage.cost.cacheWrite *= multiplier;
+  usage.cost.total =
+    usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+  return { ...message, usage };
+}
+
+type ConfigResolver = (ctx: ExtensionContext) => CodexCompatConfig;
+
+function resolveFileConfig(ctx: ExtensionContext): CodexCompatConfig {
+  return loadConfig(ctx.cwd, ctx.isProjectTrusted());
+}
+
+export default function registerCodexRequestOptions(
+  pi: ExtensionAPI,
+  resolveConfig: ConfigResolver = resolveFileConfig,
+): void {
+  pi.on("before_provider_request", (event, ctx) => {
+    if (!isCodexModel(ctx.model) || !isObject(event.payload)) return undefined;
+
+    const config = resolveConfig(ctx);
+    return applyCodexRequestOptions(event.payload, config, {
+      modelId: ctx.model!.id,
+      supportsImageSearch: ctx.model!.input.includes("image"),
+    });
+  });
+}

package/extensions/openai-codex-compat/responses-replay.ts

@@ -0,0 +1,33 @@
+import { isObject, type JsonRecord } from "./codex-protocol.ts";
+
+export function stableResponsesJson(value: unknown): string {
+  const normalize = (current: unknown): unknown => {
+    if (Array.isArray(current)) return current.map(normalize);
+    if (!isObject(current)) return current;
+    return Object.fromEntries(
+      Object.entries(current)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, normalize(entry)]),
+    );
+  };
+  return JSON.stringify(normalize(value));
+}
+
+/** Normalize completed provider output into the item shape replayed on the next request. */
+export function normalizeReplayItem(item: JsonRecord): JsonRecord {
+  const normalized = structuredClone(item);
+  if (normalized.type === "message") {
+    normalized["status"] = "completed";
+  } else if (normalized.type === "function_call" || normalized.type === "custom_tool_call") {
+    delete normalized["status"];
+  }
+  return normalized;
+}
+
+export function replayItemsEqual(
+  left: readonly JsonRecord[] | undefined,
+  right: readonly JsonRecord[] | undefined,
+): boolean {
+  return stableResponsesJson(left ?? []) === stableResponsesJson(right ?? []);
+}