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

package/extensions/openai-codex-compat/image-generation-render.ts

@@ -0,0 +1,166 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, type Component, Text, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+  CodexToolSurfaceComponent,
+  type CodexToolBackgroundResolver,
+} from "./codex-tool-surface.ts";
+import { DEFAULT_CONFIG } from "./config.ts";
+import { IMAGE_GENERATION_TOOL_NAME } from "./namespaced-tools.ts";
+
+export type ImageGenerationDetails = {
+  operation: "generate" | "edit";
+  revisedPrompt: string;
+  savedPath?: string;
+  saveError?: string;
+};
+
+type ImageGenerationArgs = {
+  prompt: string;
+  referenced_image_paths?: string[] | null;
+  num_last_images_to_include?: number | null;
+};
+
+type ImageGenerationRenderContext = {
+  args: ImageGenerationArgs;
+  isPartial: boolean;
+  expanded: boolean;
+  isError: boolean;
+};
+
+type ImageGenerationResult = {
+  content: Array<{ type: string; text?: string }>;
+  details?: unknown;
+};
+
+function promptPreview(prompt: string, maximum = 250): string {
+  const singleLine = prompt.replace(/\s+/gu, " ").trim();
+  const preview =
+    singleLine.length > maximum ? `${singleLine.slice(0, Math.max(0, maximum - 1))}…` : singleLine;
+  return `"${preview}"`;
+}
+
+function imageCount(args: ImageGenerationArgs): number | undefined {
+  const paths = args.referenced_image_paths ?? [];
+  if (paths.length > 0) return paths.length;
+  return args.num_last_images_to_include ?? undefined;
+}
+
+function describeImageCall(args: ImageGenerationArgs): string {
+  const count = imageCount(args);
+  const operation =
+    count === undefined ? "generate" : `edit ${count} ${count === 1 ? "image" : "images"}`;
+  return `${operation} ${promptPreview(args.prompt)}`;
+}
+
+function isImageGenerationDetails(value: unknown): value is ImageGenerationDetails {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const details = value as Partial<ImageGenerationDetails>;
+  return (
+    (details.operation === "generate" || details.operation === "edit") &&
+    typeof details.revisedPrompt === "string" &&
+    (details.savedPath === undefined || typeof details.savedPath === "string") &&
+    (details.saveError === undefined || typeof details.saveError === "string")
+  );
+}
+
+function textOutput(result: ImageGenerationResult): string {
+  return result.content
+    .filter((item) => item.type === "text" && typeof item.text === "string")
+    .map((item) => item.text)
+    .join("\n");
+}
+
+function wrapLines(lines: readonly string[], width: number): string[] {
+  return lines.flatMap((line) => (line === "" ? [""] : wrapTextWithAnsi(line, width)));
+}
+
+class ImageGenerationResultComponent implements Component {
+  private readonly result: ImageGenerationResult;
+  private readonly expanded: boolean;
+  private readonly theme: Theme;
+  private readonly isError: boolean;
+
+  constructor(result: ImageGenerationResult, expanded: boolean, theme: Theme, isError: boolean) {
+    this.result = result;
+    this.expanded = expanded;
+    this.theme = theme;
+    this.isError = isError;
+  }
+
+  render(width: number): string[] {
+    const output = textOutput(this.result);
+    if (this.isError) {
+      const lines = [this.theme.bold(this.theme.fg("error", "✘ Image generation failed"))];
+      if (this.expanded && output) {
+        lines.push("", ...output.split("\n").map((line) => this.theme.fg("error", line)));
+      }
+      return wrapLines(lines, width);
+    }
+
+    if (!isImageGenerationDetails(this.result.details)) {
+      return wrapLines([this.theme.fg("warning", "Image result metadata unavailable")], width);
+    }
+    const details = this.result.details;
+    const verb = details.operation === "edit" ? "Edited" : "Generated";
+    const lines = [
+      `${this.theme.fg("dim", "• ")}${this.theme.bold(`${verb} image`)}${
+        details.savedPath ? `  ${this.theme.fg("accent", details.savedPath)}` : ""
+      }`,
+    ];
+    if (details.saveError) {
+      lines.push(this.theme.fg("warning", `  Could not save image: ${details.saveError}`));
+    }
+    if (this.expanded) {
+      lines.push(
+        "",
+        `${this.theme.fg("muted", "Prompt")}  ${this.theme.fg("toolOutput", details.revisedPrompt)}`,
+      );
+      if (details.savedPath) {
+        lines.push(
+          `${this.theme.fg("muted", "Saved")}   ${this.theme.fg("accent", details.savedPath)}`,
+        );
+      }
+    }
+    return wrapLines(lines, width);
+  }
+
+  invalidate(): void {}
+}
+
+export function renderImageGenerationCall(
+  args: ImageGenerationArgs,
+  theme: Theme,
+  context: ImageGenerationRenderContext,
+  resolveBackground: CodexToolBackgroundResolver = () => DEFAULT_CONFIG.toolBackground,
+): Component {
+  const title = theme.fg("toolTitle", theme.bold(IMAGE_GENERATION_TOOL_NAME));
+  const summary = theme.fg("muted", describeImageCall(args));
+  return new CodexToolSurfaceComponent(new Text(`${title}  ${summary}`, 0, 0), theme, {
+    background: resolveBackground,
+    status: context.isPartial ? "pending" : context.isError ? "error" : "success",
+    top: true,
+    bottom: context.isPartial,
+  });
+}
+
+export function renderImageGenerationResult(
+  result: ImageGenerationResult,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  context: ImageGenerationRenderContext,
+  resolveBackground: CodexToolBackgroundResolver = () => DEFAULT_CONFIG.toolBackground,
+): Component {
+  if (options.isPartial) {
+    return new Container();
+  }
+  return new CodexToolSurfaceComponent(
+    new ImageGenerationResultComponent(result, options.expanded, theme, context.isError),
+    theme,
+    {
+      background: resolveBackground,
+      status: context.isError ? "error" : "success",
+      top: false,
+      bottom: true,
+    },
+  );
+}

package/extensions/openai-codex-compat/image-generation.ts

@@ -0,0 +1,355 @@
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { CodexCompatConfig } from "./config.ts";
+import type { CodexToolBackgroundResolver } from "./codex-tool-surface.ts";
+import { DEFAULT_CONFIG } from "./config.ts";
+import { isObject, type JsonRecord, type ResponsesItem } from "./codex-protocol.ts";
+import { requestCodexJson, type CodexJsonRequestOptions } from "./codex-transport.ts";
+import { IMAGE_GENERATION_TOOL_NAME } from "./namespaced-tools.ts";
+import {
+  renderImageGenerationCall,
+  renderImageGenerationResult,
+  type ImageGenerationDetails,
+} from "./image-generation-render.ts";
+import { isCodexModel } from "./request-options.ts";
+import { codexToolAuthentication, codexToolHistory } from "./tool-runtime.ts";
+
+const IMAGE_MODEL = "gpt-image-2";
+const MAX_EDIT_IMAGES = 5;
+const GENERATION_ENDPOINT = "images/generations";
+const EDIT_ENDPOINT = "images/edits";
+const GENERATED_IMAGES_DIRECTORY = "generated_images";
+
+const IMAGE_GENERATION_DESCRIPTION = `The \`image_gen.imagegen\` tool enables image generation from descriptions and editing of existing images based on specific instructions. Use it when:
+
+- The user requests an image based on a scene description, such as a diagram, portrait, comic, meme, or any other visual.
+- The user wants to modify an attached or previously generated image with specific changes, including adding or removing elements, altering colors, improving quality/resolution, or transforming the style (e.g., cartoon, oil painting).
+
+Guidelines:
+- imagegen needs a few minutes to finish. In code-mode, use the first-line @exec directive to give the initial call 120 seconds and the same yield for any waits that follow. Once it finishes, return the image with generatedImage(result).
+- Omit both \`referenced_image_paths\` and \`num_last_images_to_include\` when generating a brand new image.
+- For edits, use \`referenced_image_paths\` when every target image has a local file path.
+- If you have not seen a local image yet, use \`view_image\` to inspect it before editing.
+- Use \`num_last_images_to_include\` only when at least one target image has no local file path.
+- Set \`num_last_images_to_include\` to the smallest number of recent conversation images that includes every target image, up to 5.
+- Never provide both \`referenced_image_paths\` and \`num_last_images_to_include\`.
+- If neither mechanism can include every target image, ask the user to attach the missing images again.
+- Directly generate the image without reconfirmation or clarification unless required images must be attached again.
+- Always use this tool for image editing unless the user explicitly requests otherwise. Do not use the \`python\` tool for image editing unless specifically instructed.
+`;
+
+const imageGenerationParameters = Type.Unsafe<{
+  prompt: string;
+  referenced_image_paths?: string[] | null;
+  num_last_images_to_include?: number | null;
+}>({
+  type: "object",
+  properties: {
+    num_last_images_to_include: {
+      type: ["integer", "null"],
+    },
+    prompt: {
+      type: "string",
+    },
+    referenced_image_paths: {
+      type: ["array", "null"],
+      items: {
+        type: "string",
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      },
+    },
+  },
+  required: ["prompt"],
+  additionalProperties: false,
+});
+
+export type { ImageGenerationDetails } from "./image-generation-render.ts";
+
+type JsonRequester = (
+  model: Model<any>,
+  path: string,
+  body: JsonRecord,
+  options: CodexJsonRequestOptions,
+) => Promise<unknown>;
+type ConfigResolver = (ctx: ExtensionContext) => CodexCompatConfig;
+
+type ImageRequest = {
+  operation: "generate" | "edit";
+  endpoint: typeof GENERATION_ENDPOINT | typeof EDIT_ENDPOINT;
+  body: JsonRecord;
+};
+
+function imageUrlsFromContent(content: unknown): string[] {
+  if (!Array.isArray(content)) return [];
+  return content
+    .filter(isObject)
+    .toReversed()
+    .filter((item) => item.type === "input_image" && typeof item["image_url"] === "string")
+    .map((item) => item["image_url"] as string);
+}
+
+/** Return recent provider-history images in chronological order. */
+export function recentImageUrls(history: readonly ResponsesItem[], count: number): string[] {
+  const functionCallIds = new Set<string>();
+  const customToolCallIds = new Set<string>();
+  for (const item of history) {
+    if (item.type === "function_call" && typeof item["call_id"] === "string") {
+      functionCallIds.add(item["call_id"]);
+    } else if (item.type === "custom_tool_call" && typeof item["call_id"] === "string") {
+      customToolCallIds.add(item["call_id"]);
+    }
+  }
+
+  const newestFirst: string[] = [];
+  for (const item of history.toReversed()) {
+    let imageUrls: string[] = [];
+    if (item.type === undefined || item.type === "message") {
+      imageUrls = imageUrlsFromContent(item.content);
+    } else if (
+      item.type === "function_call_output" &&
+      typeof item["call_id"] === "string" &&
+      functionCallIds.has(item["call_id"])
+    ) {
+      imageUrls = imageUrlsFromContent(item["output"]);
+    } else if (
+      item.type === "custom_tool_call_output" &&
+      typeof item["call_id"] === "string" &&
+      customToolCallIds.has(item["call_id"])
+    ) {
+      imageUrls = imageUrlsFromContent(item["output"]);
+    } else if (item.type === "image_generation_call" && typeof item["result"] === "string") {
+      imageUrls = [`data:image/png;base64,${item["result"]}`];
+    }
+
+    for (const imageUrl of imageUrls) {
+      newestFirst.push(imageUrl);
+      if (newestFirst.length === count) return newestFirst.reverse();
+    }
+  }
+  return newestFirst.reverse();
+}
+
+function normalizeImagePath(path: string): string {
+  const normalized = path.startsWith("@") ? path.slice(1) : path;
+  if (!isAbsolute(normalized)) {
+    throw new Error(`referenced image path must be absolute: ${path}`);
+  }
+  return normalized;
+}
+
+function imageMimeType(bytes: Uint8Array, path: string): string {
+  if (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47 &&
+    bytes[4] === 0x0d &&
+    bytes[5] === 0x0a &&
+    bytes[6] === 0x1a &&
+    bytes[7] === 0x0a
+  ) {
+    return "image/png";
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return "image/jpeg";
+  }
+  const signature = Buffer.from(bytes.subarray(0, 12)).toString("ascii");
+  if (signature.startsWith("GIF87a") || signature.startsWith("GIF89a")) return "image/gif";
+  if (signature.startsWith("RIFF") && signature.slice(8, 12) === "WEBP") return "image/webp";
+  throw new Error(`unsupported referenced image format: ${path}`);
+}
+
+async function localImageUrl(path: string): Promise<string> {
+  const absolutePath = normalizeImagePath(path);
+  const bytes = await readFile(absolutePath);
+  const mimeType = imageMimeType(bytes, absolutePath);
+  return `data:${mimeType};base64,${bytes.toString("base64")}`;
+}
+
+async function imageRequest(
+  params: {
+    prompt: string;
+    referenced_image_paths?: string[] | null;
+    num_last_images_to_include?: number | null;
+  },
+  history: readonly ResponsesItem[],
+): Promise<ImageRequest> {
+  const paths = params.referenced_image_paths ?? [];
+  const recentCount = params.num_last_images_to_include ?? undefined;
+  if (paths.length > MAX_EDIT_IMAGES) {
+    throw new Error(`referenced_image_paths must contain at most ${MAX_EDIT_IMAGES} paths`);
+  }
+  if (
+    recentCount !== undefined &&
+    (!Number.isInteger(recentCount) || recentCount < 1 || recentCount > MAX_EDIT_IMAGES)
+  ) {
+    throw new Error(`num_last_images_to_include must be between 1 and ${MAX_EDIT_IMAGES}`);
+  }
+  if (paths.length > 0 && recentCount !== undefined) {
+    throw new Error("provide only one of referenced_image_paths or num_last_images_to_include");
+  }
+  if (paths.length === 0 && recentCount === undefined) {
+    return {
+      operation: "generate",
+      endpoint: GENERATION_ENDPOINT,
+      body: {
+        prompt: params.prompt,
+        background: "auto",
+        model: IMAGE_MODEL,
+        quality: "auto",
+        size: "auto",
+      },
+    };
+  }
+
+  const imageUrls =
+    paths.length > 0
+      ? await Promise.all(paths.map(localImageUrl))
+      : recentImageUrls(history, recentCount ?? 0);
+  const expectedCount = paths.length > 0 ? paths.length : recentCount;
+  if (expectedCount === undefined || imageUrls.length !== expectedCount) {
+    throw new Error(
+      `requested ${expectedCount ?? 0} conversation images, but only ${imageUrls.length} were available`,
+    );
+  }
+  return {
+    operation: "edit",
+    endpoint: EDIT_ENDPOINT,
+    body: {
+      images: imageUrls.map((imageUrl) => ({ image_url: imageUrl })),
+      prompt: params.prompt,
+      background: "auto",
+      model: IMAGE_MODEL,
+      quality: "auto",
+      size: "auto",
+    },
+  };
+}
+
+function normalizedBase64(value: string): string {
+  const normalized = value.replace(/\s+/g, "");
+  if (
+    normalized.length === 0 ||
+    normalized.length % 4 !== 0 ||
+    !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)
+  ) {
+    throw new Error("OpenAI Codex returned invalid generated-image data.");
+  }
+  return normalized;
+}
+
+function safePathSegment(value: string): string {
+  const sanitized = value.replace(/[^A-Za-z0-9_-]/gu, "_");
+  return sanitized || "generated_image";
+}
+
+async function saveGeneratedImage(
+  sessionId: string,
+  callId: string,
+  imageBase64: string,
+): Promise<string> {
+  const directory = join(getAgentDir(), GENERATED_IMAGES_DIRECTORY, safePathSegment(sessionId));
+  const outputPath = join(directory, `${safePathSegment(callId)}.png`);
+  const imageBytes = Buffer.from(imageBase64, "base64");
+  await mkdir(directory, { recursive: true });
+  try {
+    await writeFile(outputPath, imageBytes, {
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const existing = await readFile(outputPath);
+    if (!existing.equals(imageBytes)) throw error;
+  }
+  return outputPath;
+}
+
+function outputHint(outputPath: string): string {
+  return `Generated images are saved to ${dirname(outputPath)} as ${outputPath} by default.
+If you need to use the generated image at another path, copy it and leave the original in place unless the user explicitly asks you to delete it.
+The generated image is already displayed to the user. There is no need to render it in the final response as a Markdown image or file link.`;
+}
+
+export default function registerImageGeneration(
+  pi: ExtensionAPI,
+  resolveConfig: ConfigResolver,
+  resolveToolBackground: CodexToolBackgroundResolver = () => DEFAULT_CONFIG.toolBackground,
+  requestJson: JsonRequester = requestCodexJson,
+): void {
+  pi.registerTool({
+    name: IMAGE_GENERATION_TOOL_NAME,
+    label: IMAGE_GENERATION_TOOL_NAME,
+    description: IMAGE_GENERATION_DESCRIPTION,
+    parameters: imageGenerationParameters,
+    executionMode: "sequential",
+    renderShell: "self",
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const model = ctx.model;
+      if (!isCodexModel(model)) {
+        throw new Error("image_gen.imagegen is available only with an OpenAI Codex model.");
+      }
+      onUpdate?.({
+        content: [{ type: "text", text: "Generating image…" }],
+        details: undefined,
+      });
+      const config = resolveConfig(ctx);
+      const history = codexToolHistory(pi, ctx, model, config.imageDetail);
+      const request = await imageRequest(params, history);
+      const authentication = await codexToolAuthentication(ctx, model);
+      const callId = toolCallId.split("|")[0] || toolCallId;
+      const response = await requestJson(model, request.endpoint, request.body, {
+        ...authentication,
+        extraHeaders: { "x-codex-image-turn-id": callId },
+        ...(signal ? { signal } : {}),
+      });
+      if (!isObject(response) || !Array.isArray(response["data"])) {
+        throw new Error("OpenAI Codex returned an invalid image-generation response.");
+      }
+      const first = response["data"].find(isObject);
+      if (!first || typeof first["b64_json"] !== "string") {
+        throw new Error("OpenAI Codex image generation returned no image data.");
+      }
+      const imageBase64 = normalizedBase64(first["b64_json"]);
+      let savedPath: string | undefined;
+      let saveError: string | undefined;
+      try {
+        savedPath = await saveGeneratedImage(
+          ctx.sessionManager.getSessionId(),
+          callId,
+          imageBase64,
+        );
+      } catch (error) {
+        saveError = error instanceof Error ? error.message : String(error);
+      }
+
+      return {
+        content: [
+          { type: "image", data: imageBase64, mimeType: "image/png" },
+          ...(savedPath ? [{ type: "text" as const, text: outputHint(savedPath) }] : []),
+        ],
+        details: {
+          operation: request.operation,
+          revisedPrompt: params.prompt,
+          ...(savedPath ? { savedPath } : {}),
+          ...(saveError ? { saveError } : {}),
+        } satisfies ImageGenerationDetails,
+      };
+    },
+    renderCall(args, theme, context) {
+      return renderImageGenerationCall(args, theme, context, resolveToolBackground);
+    },
+    renderResult(result, options, theme, context) {
+      return renderImageGenerationResult(result, options, theme, context, resolveToolBackground);
+    },
+  });
+}

package/extensions/openai-codex-compat/index.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_CONFIG,
+  loadConfig,
+  writableConfigPath,
+  type CodexCompatConfig,
+} from "./config.ts";
+import { registerCodexProvider } from "./codex-provider.ts";
+import { installCodexFooter } from "./footer.ts";
+import registerCodexModelPolicy from "./model-policy.ts";
+import registerRemoteCompaction from "./remote-compaction.ts";
+import registerCodexRequestOptions from "./request-options.ts";
+import registerCodexSettings from "./settings-pane.ts";
+import registerCodexTools, { syncCodexTools } from "./tools.ts";
+
+const DISPLAY_NAME = "OpenAI Codex Compat";
+
+function settingsSummary(ctx: ExtensionContext, config: CodexCompatConfig): string {
+  return [
+    DISPLAY_NAME,
+    `fast mode: ${config.fastMode ? "on" : "off"}`,
+    `reasoning mode: ${config.reasoningMode}`,
+    `Codex tool background: ${config.toolBackground}`,
+    `apply_patch: ${config.applyPatch ? "on" : "off"}`,
+    `image_gen.imagegen: ${config.imageGeneration ? "on" : "off"}`,
+    `image result detail: ${config.imageDetail}`,
+    `web.run: ${config.webRun ? "on" : "off"}`,
+    `web search: ${config.webSearch}`,
+    `text verbosity: ${config.textVerbosity}`,
+    `reasoning summary: ${config.reasoningSummary}`,
+    `auto-compact threshold: ${config.autoCompactAtPercent ?? "Pi default"}`,
+    `save target: ${writableConfigPath(ctx.cwd, ctx.isProjectTrusted())}`,
+    "settings: /codex-settings (session-only until Ctrl+S)",
+  ].join("\n");
+}
+
+export default function registerOpenAICodexCompat(pi: ExtensionAPI): void {
+  let activeConfig: CodexCompatConfig | undefined;
+  const resolveConfig = (ctx: ExtensionContext): CodexCompatConfig => {
+    activeConfig ??= loadConfig(ctx.cwd, ctx.isProjectTrusted());
+    return activeConfig;
+  };
+  const resolveToolBackground = () => activeConfig?.toolBackground ?? DEFAULT_CONFIG.toolBackground;
+
+  pi.on("session_start", (event, ctx) => {
+    activeConfig = loadConfig(ctx.cwd, ctx.isProjectTrusted());
+    installCodexFooter(ctx, resolveConfig);
+    if (event.reason !== "reload" && ctx.mode === "tui") {
+      ctx.ui.notify(settingsSummary(ctx, activeConfig), "info");
+    }
+  });
+
+  registerCodexTools(pi, resolveConfig, resolveToolBackground);
+  const codexProvider = registerCodexProvider(pi, resolveConfig);
+  registerCodexRequestOptions(pi, resolveConfig);
+  registerRemoteCompaction(pi, codexProvider, resolveConfig);
+  registerCodexModelPolicy(pi, resolveConfig);
+  registerCodexSettings(pi, {
+    getConfig: resolveConfig,
+    onChange(config, ctx) {
+      activeConfig = config;
+      syncCodexTools(pi, ctx.model, config);
+    },
+  });
+}

package/extensions/openai-codex-compat/model-policy.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { CodexCompatConfig } from "./config.ts";
+import { hasNativeCheckpointEntry } from "./compaction-checkpoint.ts";
+import { syncCodexTools } from "./tools.ts";
+
+type ConfigResolver = (ctx: ExtensionContext) => CodexCompatConfig;
+
+function activeBranchHasCheckpoint(ctx: ExtensionContext): boolean {
+  return hasNativeCheckpointEntry(ctx.sessionManager.getBranch() as SessionEntry[]);
+}
+
+export default function registerCodexModelPolicy(
+  pi: ExtensionAPI,
+  resolveConfig: ConfigResolver,
+): void {
+  let restoringRejectedSwitch = false;
+
+  pi.on("session_start", (_event, ctx) => {
+    syncCodexTools(pi, ctx.model, resolveConfig(ctx));
+  });
+
+  pi.on("model_select", async (event, ctx) => {
+    if (restoringRejectedSwitch) {
+      syncCodexTools(pi, event.model, resolveConfig(ctx));
+      return;
+    }
+
+    const previousModel = event.previousModel;
+    if (
+      event.source === "restore" ||
+      previousModel === undefined ||
+      !activeBranchHasCheckpoint(ctx)
+    ) {
+      syncCodexTools(pi, event.model, resolveConfig(ctx));
+      return;
+    }
+
+    restoringRejectedSwitch = true;
+    let restored = false;
+    try {
+      restored = await pi.setModel(previousModel);
+    } catch (error) {
+      ctx.ui.notify(
+        `OpenAI Codex could not restore the previous model after rejecting the switch: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        "error",
+      );
+    } finally {
+      restoringRejectedSwitch = false;
+    }
+
+    if (!restored) {
+      syncCodexTools(pi, event.model, resolveConfig(ctx));
+      ctx.ui.notify(
+        "The active branch contains a native OpenAI Codex compaction checkpoint, but the previous model could not be restored.",
+        "error",
+      );
+      return;
+    }
+
+    ctx.ui.notify(
+      "Model switch rejected because the active branch contains a native OpenAI Codex compaction checkpoint. Navigate to a branch before the checkpoint or start a new session first.",
+      "warning",
+    );
+  });
+}

package/extensions/openai-codex-compat/namespaced-tools.ts

@@ -0,0 +1,43 @@
+export const IMAGE_GENERATION_TOOL_NAME = "image_gen.imagegen";
+export const WEB_RUN_TOOL_NAME = "web.run";
+
+export const CODEX_NAMESPACED_TOOL_NAMES: ReadonlySet<string> = new Set([
+  IMAGE_GENERATION_TOOL_NAME,
+  WEB_RUN_TOOL_NAME,
+]);
+
+/** Tools whose successful text output Codex transports as `input_text` content items. */
+export const CODEX_TEXT_CONTENT_ITEM_TOOL_RESULT_NAMES: ReadonlySet<string> = new Set([
+  WEB_RUN_TOOL_NAME,
+]);
+
+export type NamespacedToolName = {
+  namespace: string;
+  name: string;
+};
+
+export function splitNamespacedToolName(
+  toolName: string,
+  allowedNames: ReadonlySet<string> = CODEX_NAMESPACED_TOOL_NAMES,
+): NamespacedToolName | undefined {
+  if (!allowedNames.has(toolName)) return undefined;
+  const separator = toolName.indexOf(".");
+  if (separator <= 0 || separator === toolName.length - 1) {
+    throw new Error(`Invalid namespaced Codex tool name: ${toolName}`);
+  }
+  return {
+    namespace: toolName.slice(0, separator),
+    name: toolName.slice(separator + 1),
+  };
+}
+
+export function namespacedToolCallName(namespace: unknown, name: unknown): string {
+  if (typeof namespace !== "string" || typeof name !== "string") {
+    throw new Error("Codex returned a namespaced tool call without a valid namespace and name.");
+  }
+  const toolName = `${namespace}.${name}`;
+  if (!CODEX_NAMESPACED_TOOL_NAMES.has(toolName)) {
+    throw new Error(`Codex returned an unsupported namespaced tool call: ${toolName}`);
+  }
+  return toolName;
+}