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

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

@@ -0,0 +1,301 @@
+import { Type } from "typebox";
+
+export type WebRunSearchQuery = {
+  q: string;
+  recency?: number | null;
+  domains?: string[] | null;
+};
+
+export type WebRunCommands = {
+  search_query?: WebRunSearchQuery[] | null;
+  image_query?: WebRunSearchQuery[] | null;
+  open?: Array<{
+    ref_id: string;
+    lineno?: number | null;
+  }> | null;
+  click?: Array<{
+    ref_id: string;
+    id: number;
+  }> | null;
+  find?: Array<{
+    ref_id: string;
+    pattern: string;
+  }> | null;
+  screenshot?: Array<{
+    ref_id: string;
+    pageno: number;
+  }> | null;
+  finance?: Array<{
+    ticker: string;
+    type: "equity" | "fund" | "crypto" | "index";
+    market?: string | null;
+  }> | null;
+  weather?: Array<{
+    location: string;
+    start?: string | null;
+    duration?: number | null;
+  }> | null;
+  sports?: Array<{
+    tool?: "sports" | null;
+    fn: "schedule" | "standings";
+    league: "nba" | "wnba" | "nfl" | "nhl" | "mlb" | "epl" | "ncaamb" | "ncaawb" | "ipl";
+    team?: string | null;
+    opponent?: string | null;
+    date_from?: string | null;
+    date_to?: string | null;
+    num_games?: number | null;
+    locale?: string | null;
+  }> | null;
+  time?: Array<{
+    utc_offset: string;
+  }> | null;
+  response_length?: "short" | "medium" | "long" | null;
+};
+
+/**
+ * Exact post-normalization `SearchCommands` schema emitted by Codex at
+ * upstream commit bb5054fe47abe73ecbbd454751066a28c89f4bb9. Codex parses the
+ * generated schema through its Responses JSON-schema subset before transport,
+ * which drops unsupported annotations such as `format` and `minimum`.
+ */
+export const WEB_RUN_PARAMETERS = Type.Unsafe<WebRunCommands>({
+  type: "object",
+  properties: {
+    click: {
+      type: "array",
+      description: "Open links from previously opened pages.",
+      items: {
+        type: "object",
+        properties: {
+          id: {
+            type: "integer",
+            description: "Numbered link id to open.",
+          },
+          ref_id: {
+            type: "string",
+            description: "Reference id containing the numbered link.",
+          },
+        },
+        required: ["id", "ref_id"],
+      },
+    },
+    finance: {
+      type: "array",
+      description: "Look up prices for the given stock symbols.",
+      items: {
+        type: "object",
+        properties: {
+          market: {
+            type: "string",
+            description: 'ISO 3166-1 alpha-3 country code, "OTC", or "" for cryptocurrency.',
+          },
+          ticker: {
+            type: "string",
+            description: "Ticker symbol to look up.",
+          },
+          type: {
+            type: "string",
+            description: "Asset type to look up.",
+            enum: ["equity", "fund", "crypto", "index"],
+          },
+        },
+        required: ["ticker", "type"],
+      },
+    },
+    find: {
+      type: "array",
+      description: "Find text patterns in pages.",
+      items: {
+        type: "object",
+        properties: {
+          pattern: {
+            type: "string",
+            description: "Text pattern to find.",
+          },
+          ref_id: {
+            type: "string",
+            description: "Reference id or URL to search within.",
+          },
+        },
+        required: ["pattern", "ref_id"],
+      },
+    },
+    image_query: {
+      type: "array",
+      description: "Query the image search engine for a given list of queries.",
+      items: {
+        type: "object",
+        properties: {
+          domains: {
+            type: "array",
+            description: "Whether to filter by a specific list of domains.",
+            items: {
+              type: "string",
+            },
+          },
+          q: {
+            type: "string",
+            description: "Search query.",
+          },
+          recency: {
+            type: "integer",
+            description: "Whether to filter by recency, as a number of recent days.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    open: {
+      type: "array",
+      description: "Open pages by reference id or URL.",
+      items: {
+        type: "object",
+        properties: {
+          lineno: {
+            type: "integer",
+            description: "Line number to position the page at.",
+          },
+          ref_id: {
+            type: "string",
+            description: "Reference id or URL to open.",
+          },
+        },
+        required: ["ref_id"],
+      },
+    },
+    response_length: {
+      type: "string",
+      description: "Set the length of the response to be returned.",
+      enum: ["short", "medium", "long"],
+    },
+    screenshot: {
+      type: "array",
+      description: "Take screenshots of PDF pages.",
+      items: {
+        type: "object",
+        properties: {
+          pageno: {
+            type: "integer",
+            description: "Zero-indexed PDF page number.",
+          },
+          ref_id: {
+            type: "string",
+            description: "Reference id or URL to screenshot.",
+          },
+        },
+        required: ["pageno", "ref_id"],
+      },
+    },
+    search_query: {
+      type: "array",
+      description: "Query the internet search engine for a given list of queries.",
+      items: {
+        type: "object",
+        properties: {
+          domains: {
+            type: "array",
+            description: "Whether to filter by a specific list of domains.",
+            items: {
+              type: "string",
+            },
+          },
+          q: {
+            type: "string",
+            description: "Search query.",
+          },
+          recency: {
+            type: "integer",
+            description: "Whether to filter by recency, as a number of recent days.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    sports: {
+      type: "array",
+      description: "Look up sports schedules and standings.",
+      items: {
+        type: "object",
+        properties: {
+          date_from: {
+            type: "string",
+            description: "Start date in YYYY-MM-DD format.",
+          },
+          date_to: {
+            type: "string",
+            description: "End date in YYYY-MM-DD format.",
+          },
+          fn: {
+            type: "string",
+            description: "Sports function to call.",
+            enum: ["schedule", "standings"],
+          },
+          league: {
+            type: "string",
+            description: "League to look up.",
+            enum: ["nba", "wnba", "nfl", "nhl", "mlb", "epl", "ncaamb", "ncaawb", "ipl"],
+          },
+          locale: {
+            type: "string",
+            description: "Locale for the lookup.",
+          },
+          num_games: {
+            type: "integer",
+            description: "Number of games to return.",
+          },
+          opponent: {
+            type: "string",
+            description: "Opponent to use with `team` when narrowing the lookup.",
+          },
+          team: {
+            type: "string",
+            description:
+              "Team to look up, using the common 3 or 4 letter alias used in broadcasts.",
+          },
+          tool: {
+            type: "string",
+            description: "Tool name for sports requests.",
+            enum: ["sports"],
+          },
+        },
+        required: ["fn", "league"],
+      },
+    },
+    time: {
+      type: "array",
+      description: "Get time for the given UTC offsets.",
+      items: {
+        type: "object",
+        properties: {
+          utc_offset: {
+            type: "string",
+            description: 'UTC offset formatted like "+03:00".',
+          },
+        },
+        required: ["utc_offset"],
+      },
+    },
+    weather: {
+      type: "array",
+      description: "Look up weather forecasts.",
+      items: {
+        type: "object",
+        properties: {
+          duration: {
+            type: "integer",
+            description: "Number of days to return. Defaults to 7.",
+          },
+          location: {
+            type: "string",
+            description: 'Location in "Country, Area, City" format.',
+          },
+          start: {
+            type: "string",
+            description: "Start date in YYYY-MM-DD format. Defaults to today.",
+          },
+        },
+        required: ["location"],
+      },
+    },
+  },
+});

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

@@ -0,0 +1,164 @@
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  approximateTokens,
+  isObject,
+  truncateMiddleWithTokenBudget,
+  type JsonRecord,
+  type ResponsesItem,
+} from "./codex-protocol.ts";
+import { requestCodexJson, type CodexJsonRequestOptions } from "./codex-transport.ts";
+import type { CodexCompatConfig, WebSearchMode } from "./config.ts";
+import type { CodexToolBackgroundResolver } from "./codex-tool-surface.ts";
+import { DEFAULT_CONFIG } from "./config.ts";
+import { WEB_RUN_TOOL_NAME } from "./namespaced-tools.ts";
+import { isCodexModel } from "./request-options.ts";
+import { codexToolAuthentication, codexToolHistory } from "./tool-runtime.ts";
+import { renderWebRunCall, renderWebRunResult, type WebRunDetails } from "./web-run-render.ts";
+import { WEB_RUN_PARAMETERS } from "./web-run-schema.ts";
+
+const SEARCH_ENDPOINT = "alpha/search";
+const SEARCH_OUTPUT_TOKEN_BUDGET = 2_500;
+const ASSISTANT_CONTEXT_TOKEN_BUDGET = 1_000;
+
+const WEB_RUN_DESCRIPTION = readFileSync(
+  new URL("./web-run-description.txt", import.meta.url),
+  "utf8",
+);
+
+export type { WebRunDetails } from "./web-run-render.ts";
+
+type ConfigResolver = (ctx: ExtensionContext) => CodexCompatConfig;
+type JsonRequester = (
+  model: Model<any>,
+  path: string,
+  body: JsonRecord,
+  options: CodexJsonRequestOptions,
+) => Promise<unknown>;
+
+function visibleMessage(item: ResponsesItem): JsonRecord | undefined {
+  if (item.type !== undefined && item.type !== "message") return undefined;
+  if (item.role !== "user" && item.role !== "assistant") return undefined;
+  if (!Array.isArray(item.content)) return undefined;
+
+  const content = item.content
+    .filter(isObject)
+    .filter((part) =>
+      item.role === "user" ? part.type === "input_text" : part.type === "output_text",
+    )
+    .filter((part) => typeof part.text === "string")
+    .map((part) => ({ type: part.type, text: part.text }));
+  if (content.length === 0) return undefined;
+  return { type: "message", role: item.role, content };
+}
+
+function truncateAssistantMessages(messages: JsonRecord[]): JsonRecord[] {
+  let remaining = ASSISTANT_CONTEXT_TOKEN_BUDGET;
+  const result: JsonRecord[] = [];
+
+  for (const message of messages) {
+    if (message.role !== "assistant" || !Array.isArray(message.content)) {
+      result.push(message);
+      continue;
+    }
+
+    const content: JsonRecord[] = [];
+    for (const part of message.content.filter(isObject)) {
+      if (part.type !== "output_text" || typeof part.text !== "string" || remaining === 0) {
+        continue;
+      }
+      const tokens = approximateTokens(part.text);
+      if (tokens <= remaining) {
+        content.push(part);
+        remaining -= tokens;
+      } else {
+        content.push({
+          ...part,
+          text: truncateMiddleWithTokenBudget(part.text, remaining),
+        });
+        remaining = 0;
+      }
+    }
+    if (content.length > 0) result.push({ ...message, content });
+  }
+  return result;
+}
+
+/** Build the same two-user-turn text tail used by standalone Codex search. */
+export function recentSearchInput(history: readonly ResponsesItem[]): JsonRecord[] | undefined {
+  const visible = history.map(visibleMessage).filter((item): item is JsonRecord => Boolean(item));
+  const latestUser = visible.findLastIndex((item) => item.role === "user");
+  if (latestUser < 0) return undefined;
+
+  const throughLatestUser = visible.slice(0, latestUser + 1);
+  const userIndexes = throughLatestUser
+    .map((item, index) => (item.role === "user" ? index : -1))
+    .filter((index) => index >= 0);
+  const start = userIndexes.at(-2) ?? userIndexes.at(-1);
+  if (start === undefined) return undefined;
+  return truncateAssistantMessages(throughLatestUser.slice(start));
+}
+
+function externalWebAccess(mode: WebSearchMode): boolean | "indexed" {
+  if (mode === "live") return true;
+  if (mode === "indexed") return "indexed";
+  return false;
+}
+
+export default function registerWebRun(
+  pi: ExtensionAPI,
+  resolveConfig: ConfigResolver,
+  resolveToolBackground: CodexToolBackgroundResolver = () => DEFAULT_CONFIG.toolBackground,
+  requestJson: JsonRequester = requestCodexJson,
+): void {
+  pi.registerTool({
+    name: WEB_RUN_TOOL_NAME,
+    label: WEB_RUN_TOOL_NAME,
+    description: WEB_RUN_DESCRIPTION,
+    parameters: WEB_RUN_PARAMETERS,
+    executionMode: "parallel",
+    renderShell: "self",
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const model = ctx.model;
+      if (!isCodexModel(model)) {
+        throw new Error("web.run is available only with an OpenAI Codex model.");
+      }
+      const authentication = await codexToolAuthentication(ctx, model);
+      const config = resolveConfig(ctx);
+      const history = codexToolHistory(pi, ctx, model, config.imageDetail);
+      const input = recentSearchInput(history);
+      const body: JsonRecord = {
+        id: ctx.sessionManager.getSessionId(),
+        model: model.id,
+        ...(input ? { input } : {}),
+        commands: params,
+        settings: {
+          allowed_callers: ["direct"],
+          external_web_access: externalWebAccess(config.webSearch),
+        },
+        max_output_tokens: SEARCH_OUTPUT_TOKEN_BUDGET,
+      };
+      const response = await requestJson(model, SEARCH_ENDPOINT, body, {
+        ...authentication,
+        ...(signal ? { signal } : {}),
+      });
+      if (!isObject(response) || typeof response["output"] !== "string") {
+        throw new Error("OpenAI Codex returned an invalid standalone web-search response.");
+      }
+      const results = Array.isArray(response["results"])
+        ? response["results"].map((result) => structuredClone(result))
+        : undefined;
+      return {
+        content: [{ type: "text", text: response["output"] }],
+        details: (results ? { results } : {}) satisfies WebRunDetails,
+      };
+    },
+    renderCall(args, theme, context) {
+      return renderWebRunCall(args, theme, context, resolveToolBackground);
+    },
+    renderResult(result, options, theme, context) {
+      return renderWebRunResult(result, options, theme, context, resolveToolBackground);
+    },
+  });
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-openai-codex-compat",
+  "version": "0.0.1-alpha.0",
+  "description": "OpenAI Codex compatibility for Pi with native compaction, fast mode, and Codex-optimized capabilities",
+  "keywords": [
+    "pi-package"
+  ],
+  "homepage": "https://github.com/2h2d-co/pi-openai-codex-compat#readme",
+  "bugs": {
+    "url": "https://github.com/2h2d-co/pi-openai-codex-compat/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Kaan Ozdokmeci",
+    "email": "kaan@ozdokmeci.com",
+    "url": ""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/2h2d-co/pi-openai-codex-compat.git"
+  },
+  "files": [
+    "extensions/openai-codex-compat",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSES",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "check": "hk check --all --check",
+    "test": "node --test --test-concurrency=1 test/*.test.ts",
+    "fmt": "oxfmt",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
+    "@types/node": "22.20.1",
+    "oxfmt": "0.60.0",
+    "oxlint": "1.75.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "typebox": "1.3.7",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.83.0 <0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <0.84.0",
+    "@earendil-works/pi-tui": ">=0.83.0 <0.84.0",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/openai-codex-compat/index.ts"
+    ]
+  }
+}