pi-openai-codex-compat 0.0.1 → 0.0.3

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

@@ -11,6 +11,8 @@ export type ReasoningMode = "standard" | "pro";
 export type ImageDetail = "auto" | "low" | "high" | "original";
 export type CodexToolBackground = "subtle" | "status" | "none";
 
+export const ENV_PREFIX = "PI_OPENAI_CODEX_COMPAT_";
+
 export interface CodexCompatConfig {
   /** Send OpenAI Codex requests through the priority service tier. */
   fastMode: boolean;
@@ -36,6 +38,20 @@ export interface CodexCompatConfig {
   reasoningMode: ReasoningMode;
 }
 
+export const CONFIG_ENVIRONMENT_VARIABLES = {
+  fastMode: `${ENV_PREFIX}FAST_MODE`,
+  applyPatch: `${ENV_PREFIX}APPLY_PATCH`,
+  toolBackground: `${ENV_PREFIX}TOOL_BACKGROUND`,
+  imageGeneration: `${ENV_PREFIX}IMAGE_GENERATION`,
+  imageDetail: `${ENV_PREFIX}IMAGE_DETAIL`,
+  webRun: `${ENV_PREFIX}WEB_RUN`,
+  autoCompactAtPercent: `${ENV_PREFIX}AUTO_COMPACT_AT_PERCENT`,
+  webSearch: `${ENV_PREFIX}WEB_SEARCH_MODE`,
+  textVerbosity: `${ENV_PREFIX}TEXT_VERBOSITY`,
+  reasoningSummary: `${ENV_PREFIX}REASONING_SUMMARY`,
+  reasoningMode: `${ENV_PREFIX}REASONING_MODE`,
+} as const satisfies Record<keyof CodexCompatConfig, string>;
+
 export type ConfigLayer = {
   fastMode?: boolean;
   applyPatch?: boolean;
@@ -57,8 +73,8 @@ export const DEFAULT_CONFIG: CodexCompatConfig = {
   toolBackground: "subtle",
   imageGeneration: true,
   imageDetail: "auto",
-  webRun: true,
-  webSearch: "cached",
+  webRun: false,
+  webSearch: "disabled",
   textVerbosity: "low",
   reasoningSummary: "auto",
   reasoningMode: "standard",
@@ -71,10 +87,136 @@ const REASONING_MODES = new Set<ReasoningMode>(["standard", "pro"]);
 const IMAGE_DETAILS = new Set<ImageDetail>(["auto", "low", "high", "original"]);
 const CODEX_TOOL_BACKGROUNDS = new Set<CodexToolBackground>(["subtle", "status", "none"]);
 
+type Environment = Readonly<Record<string, string | undefined>>;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function invalidEnvironmentValue(name: string, value: string, expected: string): never {
+  throw new Error(`Invalid ${name}=${JSON.stringify(value)}; expected ${expected}`);
+}
+
+function environmentBoolean(environment: Environment, name: string): boolean | undefined {
+  const raw = environment[name];
+  if (raw === undefined) return undefined;
+
+  switch (raw.trim().toLowerCase()) {
+    case "1":
+    case "enabled":
+    case "on":
+    case "true":
+      return true;
+    case "0":
+    case "disabled":
+    case "off":
+    case "false":
+      return false;
+    default:
+      return invalidEnvironmentValue(name, raw, "true, false, 1, 0, on, off, enabled, or disabled");
+  }
+}
+
+function environmentEnum<T extends string>(
+  environment: Environment,
+  name: string,
+  values: ReadonlySet<T>,
+): T | undefined {
+  const raw = environment[name];
+  if (raw === undefined) return undefined;
+
+  const value = raw.trim();
+  if (values.has(value as T)) return value as T;
+  return invalidEnvironmentValue(name, raw, [...values].join(", "));
+}
+
+/**
+ * Parse explicit process-level overrides. Unlike invalid JSON settings, invalid
+ * environment values fail fast so a CLI test cannot silently exercise a
+ * different configuration than requested.
+ */
+export function parseEnvironmentConfig(environment: Environment = process.env): ConfigLayer {
+  const layer: ConfigLayer = {};
+
+  const fastMode = environmentBoolean(environment, CONFIG_ENVIRONMENT_VARIABLES.fastMode);
+  if (fastMode !== undefined) layer.fastMode = fastMode;
+
+  const applyPatch = environmentBoolean(environment, CONFIG_ENVIRONMENT_VARIABLES.applyPatch);
+  if (applyPatch !== undefined) layer.applyPatch = applyPatch;
+
+  const toolBackground = environmentEnum(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.toolBackground,
+    CODEX_TOOL_BACKGROUNDS,
+  );
+  if (toolBackground !== undefined) layer.toolBackground = toolBackground;
+
+  const imageGeneration = environmentBoolean(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.imageGeneration,
+  );
+  if (imageGeneration !== undefined) layer.imageGeneration = imageGeneration;
+
+  const imageDetail = environmentEnum(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.imageDetail,
+    IMAGE_DETAILS,
+  );
+  if (imageDetail !== undefined) layer.imageDetail = imageDetail;
+
+  const webRun = environmentBoolean(environment, CONFIG_ENVIRONMENT_VARIABLES.webRun);
+  if (webRun !== undefined) layer.webRun = webRun;
+
+  const thresholdName = CONFIG_ENVIRONMENT_VARIABLES.autoCompactAtPercent;
+  const rawThreshold = environment[thresholdName];
+  if (rawThreshold !== undefined) {
+    const value = rawThreshold.trim();
+    if (value.toLowerCase() === "off" || value.toLowerCase() === "default") {
+      layer.autoCompactAtPercent = null;
+    } else {
+      const threshold = Number(value);
+      if (value.length === 0 || !Number.isFinite(threshold) || threshold <= 0 || threshold > 100) {
+        invalidEnvironmentValue(
+          thresholdName,
+          rawThreshold,
+          "a number greater than 0 and at most 100, off, or default",
+        );
+      }
+      layer.autoCompactAtPercent = threshold;
+    }
+  }
+
+  const webSearch = environmentEnum(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.webSearch,
+    WEB_SEARCH_MODES,
+  );
+  if (webSearch !== undefined) layer.webSearch = webSearch;
+
+  const textVerbosity = environmentEnum(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.textVerbosity,
+    TEXT_VERBOSITIES,
+  );
+  if (textVerbosity !== undefined) layer.textVerbosity = textVerbosity;
+
+  const reasoningSummary = environmentEnum(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.reasoningSummary,
+    REASONING_SUMMARIES,
+  );
+  if (reasoningSummary !== undefined) layer.reasoningSummary = reasoningSummary;
+
+  const reasoningMode = environmentEnum(
+    environment,
+    CONFIG_ENVIRONMENT_VARIABLES.reasoningMode,
+    REASONING_MODES,
+  );
+  if (reasoningMode !== undefined) layer.reasoningMode = reasoningMode;
+
+  return layer;
+}
+
 export function parseConfig(value: unknown): ConfigLayer {
   if (!isRecord(value)) return {};
 
@@ -157,8 +299,9 @@ function readConfig(filePath: string): ConfigLayer {
 export function resolveConfig(
   globalConfig: ConfigLayer,
   projectConfig: ConfigLayer,
+  environmentConfig: ConfigLayer = {},
 ): CodexCompatConfig {
-  const merged = { ...globalConfig, ...projectConfig };
+  const merged = { ...globalConfig, ...projectConfig, ...environmentConfig };
   return {
     ...DEFAULT_CONFIG,
     ...(typeof merged.fastMode === "boolean" ? { fastMode: merged.fastMode } : {}),
@@ -193,10 +336,14 @@ export function writableConfigPath(cwd: string, projectTrusted: boolean): string
   return projectTrusted && existsSync(projectPath) ? projectPath : globalConfigPath();
 }
 
-export function loadConfig(cwd: string, projectTrusted: boolean): CodexCompatConfig {
+export function loadConfig(
+  cwd: string,
+  projectTrusted: boolean,
+  environment: Environment = process.env,
+): CodexCompatConfig {
   const globalConfig = readConfig(globalConfigPath());
   const projectConfig = projectTrusted ? readConfig(projectConfigPath(cwd)) : {};
-  return resolveConfig(globalConfig, projectConfig);
+  return resolveConfig(globalConfig, projectConfig, parseEnvironmentConfig(environment));
 }
 
 export function configLayer(config: CodexCompatConfig): ConfigLayer {
@@ -215,6 +362,18 @@ export function configLayer(config: CodexCompatConfig): ConfigLayer {
   };
 }
 
+/** Keep process-level overrides transient when an effective config is saved. */
+export function withoutEnvironmentOverrides(
+  layer: ConfigLayer,
+  environmentConfig: ConfigLayer,
+): ConfigLayer {
+  const result = { ...layer };
+  for (const key of Object.keys(environmentConfig) as (keyof ConfigLayer)[]) {
+    delete result[key];
+  }
+  return result;
+}
+
 async function readWritableConfig(filePath: string): Promise<Record<string, unknown>> {
   try {
     const value = JSON.parse(await readFile(filePath, "utf8")) as unknown;

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

@@ -0,0 +1,37 @@
+import { Type } from "typebox";
+
+export const MAX_EDIT_IMAGES = 5;
+
+export type ImageGenerationParameters = {
+  prompt: string;
+  referenced_image_paths?: string[] | null;
+  num_last_images_to_include?: number | null;
+};
+
+const REFERENCED_IMAGE_PATH_DESCRIPTION =
+  "Absolute path to a local PNG, JPEG, GIF, or WebP image to include in an edit. Convert relative paths to absolute paths before calling the tool; the file must exist and be readable.";
+
+/**
+ * Server-reserved image-generation schema. Range and selector constraints are
+ * enforced by the executor because OpenAI rejects additional schema keywords.
+ */
+export const IMAGE_GENERATION_PARAMETERS = Type.Unsafe<ImageGenerationParameters>({
+  type: "object",
+  properties: {
+    num_last_images_to_include: {
+      type: ["integer", "null"],
+    },
+    prompt: {
+      type: "string",
+    },
+    referenced_image_paths: {
+      type: ["array", "null"],
+      items: {
+        type: "string",
+        description: REFERENCED_IMAGE_PATH_DESCRIPTION,
+      },
+    },
+  },
+  required: ["prompt"],
+  additionalProperties: false,
+});

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

@@ -1,17 +1,21 @@
 import { readFile, mkdir, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, normalize } 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_PARAMETERS,
+  MAX_EDIT_IMAGES,
+  type ImageGenerationParameters,
+} from "./image-generation-schema.ts";
 import { IMAGE_GENERATION_TOOL_NAME } from "./namespaced-tools.ts";
 import {
   renderImageGenerationCall,
@@ -22,55 +26,25 @@ 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:
+const IMAGE_GENERATION_DESCRIPTION = `The \`image_gen.imagegen\` tool generates new images from descriptions and edits existing images according to 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).
+- The user wants to modify a local, attached, or previously generated image by adding or removing elements, changing colors, improving quality or resolution, or transforming its style.
 
 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).
+- Call \`image_gen.imagegen\` directly without reconfirmation unless required source images are unavailable.
 - 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.
+- For edits, use \`referenced_image_paths\` when every target image has an absolute local path, with at most 5 paths. Use \`read\` first when you need to inspect a local image.
+- Use \`num_last_images_to_include\` only when at least one target image has no local path, and set it to the smallest number of recent conversation images that includes every target, 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.
+- Generated images are returned, displayed, and saved automatically. Do not embed the image in the final response unless the user asks.
 `;
 
-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 = (
@@ -137,12 +111,12 @@ export function recentImageUrls(history: readonly ResponsesItem[], count: number
   return newestFirst.reverse();
 }
 
-function normalizeImagePath(path: string): string {
-  const normalized = path.startsWith("@") ? path.slice(1) : path;
-  if (!isAbsolute(normalized)) {
+export function normalizeImagePath(path: string): string {
+  const unprefixed = path.startsWith("@") ? path.slice(1) : path;
+  if (!isAbsolute(unprefixed)) {
     throw new Error(`referenced image path must be absolute: ${path}`);
   }
-  return normalized;
+  return normalize(unprefixed);
 }
 
 function imageMimeType(bytes: Uint8Array, path: string): string {
@@ -176,11 +150,7 @@ async function localImageUrl(path: string): Promise<string> {
 }
 
 async function imageRequest(
-  params: {
-    prompt: string;
-    referenced_image_paths?: string[] | null;
-    num_last_images_to_include?: number | null;
-  },
+  params: ImageGenerationParameters,
   history: readonly ResponsesItem[],
 ): Promise<ImageRequest> {
   const paths = params.referenced_image_paths ?? [];
@@ -290,7 +260,14 @@ export default function registerImageGeneration(
     name: IMAGE_GENERATION_TOOL_NAME,
     label: IMAGE_GENERATION_TOOL_NAME,
     description: IMAGE_GENERATION_DESCRIPTION,
-    parameters: imageGenerationParameters,
+    promptSnippet: "Generate new images or edit existing images",
+    promptGuidelines: [
+      "Use image_gen.imagegen directly to generate new images or edit existing images without reconfirmation unless required source images are unavailable.",
+      "For new images, call image_gen.imagegen without referenced_image_paths or num_last_images_to_include.",
+      "For image_gen.imagegen edits, use up to five absolute referenced_image_paths when every target is local; otherwise use num_last_images_to_include from 1 to 5, and use read when you need to inspect a local image.",
+      "Never pass both image selectors to image_gen.imagegen; ask the user to reattach images when every target cannot be referenced.",
+    ],
+    parameters: IMAGE_GENERATION_PARAMETERS,
     executionMode: "sequential",
     renderShell: "self",
     async execute(toolCallId, params, signal, onUpdate, ctx) {

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

@@ -13,6 +13,13 @@ import registerCodexRequestOptions from "./request-options.ts";
 import registerCodexSettings from "./settings-pane.ts";
 import registerCodexTools, { syncCodexTools } from "./tools.ts";
 
+export {
+  closeOpenAICodexWebSocketSessions,
+  getOpenAICodexWebSocketDebugStats,
+  resetOpenAICodexWebSocketDebugStats,
+  type OpenAICodexWebSocketDebugStats,
+} from "./codex-transport.ts";
+
 const DISPLAY_NAME = "OpenAI Codex Compat";
 
 function settingsSummary(ctx: ExtensionContext, config: CodexCompatConfig): string {
@@ -30,7 +37,7 @@ function settingsSummary(ctx: ExtensionContext, config: CodexCompatConfig): stri
     `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)",
+    "settings: /codex-settings (Enter saves & closes; Esc discards; Ctrl+S saves)",
   ].join("\n");
 }
 

package/extensions/openai-codex-compat/provider-error.ts

@@ -0,0 +1,79 @@
+const MAX_PROVIDER_ERROR_BODY_CHARS = 4_000;
+
+type ProviderErrorShape = Error & {
+  statusCode?: unknown;
+  status?: unknown;
+  body?: unknown;
+  error?: unknown;
+  $metadata?: { httpStatusCode?: unknown };
+  $response?: { statusCode?: unknown; body?: unknown };
+};
+
+function safeJsonStringify(value: unknown): string {
+  try {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? String(value) : serialized;
+  } catch {
+    return String(value);
+  }
+}
+
+function truncateErrorText(text: string): string {
+  return text.length <= MAX_PROVIDER_ERROR_BODY_CHARS
+    ? text
+    : `${text.slice(0, MAX_PROVIDER_ERROR_BODY_CHARS)}... [truncated ${
+        text.length - MAX_PROVIDER_ERROR_BODY_CHARS
+      } chars]`;
+}
+
+function isPlainNonEmptyObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return (prototype === Object.prototype || prototype === null) && Object.keys(value).length > 0;
+}
+
+function isReadableStreamLike(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "pipe" in value &&
+    typeof value.pipe === "function"
+  );
+}
+
+function errorStatus(error: ProviderErrorShape): number | undefined {
+  if (typeof error.statusCode === "number") return error.statusCode;
+  if (typeof error.status === "number") return error.status;
+  if (typeof error.$metadata?.httpStatusCode === "number") {
+    return error.$metadata.httpStatusCode;
+  }
+  if (typeof error.$response?.statusCode === "number") return error.$response.statusCode;
+  return undefined;
+}
+
+function errorBody(error: ProviderErrorShape): string | undefined {
+  let body: string | undefined;
+  if (typeof error.body === "string") body = error.body;
+  else if (isPlainNonEmptyObject(error.error)) body = safeJsonStringify(error.error);
+  else if (typeof error.$response?.body === "string") body = error.$response.body;
+  else if (
+    !isReadableStreamLike(error.$response?.body) &&
+    isPlainNonEmptyObject(error.$response?.body)
+  ) {
+    body = safeJsonStringify(error.$response.body);
+  }
+  const trimmed = body?.trim();
+  return trimmed ? truncateErrorText(trimmed) : undefined;
+}
+
+/** Match Pi AI's provider error normalization without importing a private package subpath. */
+export function formatProviderError(error: unknown): string {
+  if (!(error instanceof Error)) return safeJsonStringify(error);
+  const providerError = error as ProviderErrorShape;
+  const status = errorStatus(providerError);
+  const body = errorBody(providerError);
+  if (status !== undefined && body !== undefined && !error.message.includes(body)) {
+    return `${status}: ${body}`;
+  }
+  return error.message;
+}

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

@@ -24,10 +24,3 @@ export function normalizeReplayItem(item: JsonRecord): JsonRecord {
   }
   return normalized;
 }
-
-export function replayItemsEqual(
-  left: readonly JsonRecord[] | undefined,
-  right: readonly JsonRecord[] | undefined,
-): boolean {
-  return stableResponsesJson(left ?? []) === stableResponsesJson(right ?? []);
-}