pi-openai-codex-compat 0.0.2 → 0.0.3

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

@@ -73,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",

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 {

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 ?? []);
-}

package/extensions/openai-codex-compat/web-run.ts

@@ -116,6 +116,13 @@ export default function registerWebRun(
     name: WEB_RUN_TOOL_NAME,
     label: WEB_RUN_TOOL_NAME,
     description: WEB_RUN_DESCRIPTION,
+    promptSnippet: "Search and browse the internet",
+    promptGuidelines: [
+      "Use `web.run` when the user explicitly asks to browse or when answering requires current, niche, high-stakes, or precisely sourced information, including recommendations that may change over time.",
+      'Batch independent `web.run` operations in one call, pass only required parameters, and keep `search_query` to at most four queries; use `response_length: "medium"` or `"long"` when sending four.',
+      "For technical research, prefer primary sources; for OpenAI product questions, inspect local code first and restrict fallback browsing to official OpenAI sites.",
+      "Cite supported claims with direct Markdown links near the relevant text, never expose internal reference IDs, and respect the description's quotation and source word limits.",
+    ],
     parameters: WEB_RUN_PARAMETERS,
     executionMode: "parallel",
     renderShell: "self",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-codex-compat",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "OpenAI Codex compatibility for Pi with native compaction, fast mode, and Codex-optimized capabilities",
   "keywords": [
     "pi-package"
@@ -31,6 +31,7 @@
   "scripts": {
     "check": "hk check --all --check",
     "test": "node --test --test-concurrency=1 test/*.test.ts",
+    "test:live:codex": "PI_CODEX_LIVE_TEST=1 node --test --test-concurrency=1 test/codex-transport.live.test.ts",
     "fmt": "oxfmt",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix"