pi-openai-codex-compat 0.0.17 → 0.0.19

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

@@ -1,5 +1,5 @@
 import { isBoolean, isString } from "./value-contracts.ts";
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import {
   buildSessionContext,
   buildSessionProjection,
@@ -7,9 +7,9 @@ import {
   sessionEntryToContextMessages,
   type ContextEditEntry,
   type SessionEntry,
-  type ToolInfo,
 } from "@earendil-works/pi-coding-agent";
 import {
+  getDeclaredTools,
   getInitialSystemMessage,
   getSystemMessageText,
   normalizeContext,
@@ -19,24 +19,17 @@ import {
   type Message,
   type Model,
   type SystemMessage,
+  type Tool,
   type TranscriptContext,
 } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
-import { APPLY_PATCH_LARK_GRAMMAR, APPLY_PATCH_TOOL_NAME } from "./apply-patch.ts";
 import { CODEX_TOOL_CALL_PROVIDERS } from "./codex-identifiers.ts";
 import type { ImageDetail } from "./config.ts";
-import {
-  installCompactionItem,
-  isObject,
-  requireResponsesInputItems,
-  type JsonRecord,
-} from "./codex-protocol.ts";
+import { installCompactionItem, isObject, requireResponsesInputItems } from "./codex-protocol.ts";
 import { nativeCommittedPrefixBeforeOverflow, nativeResponseOverrides } from "./native-history.ts";
-import { stableResponsesJson } from "./responses-replay.ts";
 import {
   CODEX_NAMESPACED_TOOL_NAMES,
   CODEX_TEXT_CONTENT_ITEM_TOOL_RESULT_NAMES,
-  splitNamespacedToolName,
 } from "./namespaced-tools.ts";
 import {
   RESPONSES_COMPACTION_ITEM_SCHEMA,
@@ -45,8 +38,12 @@ import {
   type ResponsesInputItem,
   type ResponsesOutputItem,
 } from "./responses-item-schema.ts";
-import type { ResponsesToolDefinition } from "./responses-tool-schema.ts";
-import { convertResponsesMessages } from "./vendor/pi-ai/openai-responses-serialization.ts";
+import {
+  convertResponsesMessages,
+  convertResponsesTools,
+  createGrammarToolInputProperties,
+  type ResponsesItem,
+} from "./vendor/pi-ai/openai-responses-serialization.ts";
 
 type AgentMessages = ReturnType<typeof sessionEntryToContextMessages>;
 
@@ -113,148 +110,41 @@ export function requestInstructions(context: TranscriptContext): string {
   return initial ? getSystemMessageText(initial) : "";
 }
 
+/** A session branch as the Pi AI messages Pi sends, including the system messages that declare tools. */
+export function branchTranscript(branch: readonly SessionEntry[]): Message[] {
+  return convertToLlm(buildSessionContext([...branch]).messages);
+}
+
 /** `instructions` for a request built from a session branch rather than Pi's live transcript. */
 export function branchInstructions(model: Model<Api>, branch: readonly SessionEntry[]): string {
   return requestInstructions(
-    resolveRequestTranscript(model, {
-      messages: convertToLlm(buildSessionContext([...branch]).messages),
-    }),
+    resolveRequestTranscript(model, { messages: branchTranscript(branch) }),
   );
 }
 
-function responsesToolParameters(tool: ToolInfo): JsonRecord {
-  if (!isObject(tool.parameters)) {
-    throw new Error(`Tool ${tool.name} must have JSON object parameters.`);
-  }
-  return tool.parameters;
-}
-
-function asResponsesTool(
-  tool: ToolInfo,
-  grammarToolInputProperties: GrammarToolInputProperties,
-): ResponsesToolDefinition {
-  if (tool.name === APPLY_PATCH_TOOL_NAME && grammarToolInputProperties.has(tool.name)) {
-    return {
-      type: "custom",
-      name: tool.name,
-      description: tool.description,
-      format: {
-        type: "grammar",
-        syntax: "lark",
-        definition: APPLY_PATCH_LARK_GRAMMAR,
-      },
-    };
-  }
-  const namespaced = splitNamespacedToolName(tool.name);
-  if (namespaced) {
-    return {
-      type: "namespace",
-      name: namespaced.namespace,
-      description: `Tools in the ${namespaced.namespace} namespace.`,
-      tools: [
-        {
-          type: "function",
-          name: namespaced.name,
-          description: tool.description,
-          parameters: responsesToolParameters(tool),
-          strict: false,
-        },
-      ],
-    };
-  }
-  return {
-    type: "function",
-    name: tool.name,
-    description: tool.description,
-    parameters: responsesToolParameters(tool),
-    strict: false,
-  };
-}
-
-export function activeResponsesTools(
-  allTools: readonly ToolInfo[],
-  activeNames: readonly string[],
-  grammarToolInputProperties: GrammarToolInputProperties = new Map(),
-): ResponsesToolDefinition[] | undefined {
-  const enabled = new Set(activeNames);
-  const tools = allTools.filter((tool) => enabled.has(tool.name));
-  return tools.length > 0
-    ? tools.map((tool) => asResponsesTool(tool, grammarToolInputProperties))
-    : undefined;
-}
-
-/** The raw tool definition fields that both Pi AI's `Tool` and Pi's `ToolInfo` carry. */
-export type ToolDeclarationSource = Pick<ToolInfo, "name" | "description" | "parameters">;
-
 /**
- * Fingerprint raw tool definitions by name, description, and parameter schema,
- * independent of declaration order. Both the transcript tools a turn request
- * declared and the registry's active `ToolInfo` list produce the same value for
- * the same definitions, so a cached turn template can be compared with the
- * current tools without reversing the strict schema conversion applied on the
- * wire.
+ * The top-level `tools` of a Codex request declaring the given transcript tools.
+ * Turn requests and native compaction share this conversion, so the same tools
+ * produce the same declarations and the same prompt-cache prefix.
  */
-export function toolDefinitionFingerprint(tools: readonly ToolDeclarationSource[]): string {
-  const declarations = tools
-    .map((tool) => {
-      // The JSON round-trip drops typebox symbol keys and undefined fields, as
-      // Pi AI's own declaration comparison does.
-      const parameters: unknown = JSON.parse(JSON.stringify(tool.parameters));
-      return { name: tool.name, description: tool.description, parameters };
-    })
-    .sort((left, right) => left.name.localeCompare(right.name));
-  return createHash("sha256").update(stableResponsesJson(declarations)).digest("hex");
-}
-
-/** Fingerprint of the registry tools that are currently active. */
-export function activeToolFingerprint(
-  allTools: readonly ToolInfo[],
-  activeNames: readonly string[],
-): string {
-  const enabled = new Set(activeNames);
-  return toolDefinitionFingerprint(allTools.filter((tool) => enabled.has(tool.name)));
+export function requestTools(model: Model<Api>, tools: readonly Tool[]): ResponsesItem[] {
+  const compat = responsesCompatibility(model.compat);
+  return convertResponsesTools(tools, {
+    strict: false,
+    supportsStrictMode: compat.supportsStrictMode ?? true,
+    supportsOpenAIGrammarTools: compat.supportsOpenAIGrammarTools ?? false,
+    namespacedToolNames: CODEX_NAMESPACED_TOOL_NAMES,
+  });
 }
 
-/**
- * Whether a cached turn template still declares exactly the active tools.
- *
- * The serialized `tools` list must name the active set (namespace members
- * count as `namespace.member`), and the raw definitions that produced it must
- * fingerprint identically to the active registry tools. Comparing names and
- * descriptions alone missed parameter-schema changes under an unchanged name.
- *
- * A cached turn template carries the exact declarations the turn requests sent,
- * including strict schema conversion that `ToolInfo` cannot reproduce. Reusing
- * it keeps the compaction request on the turn requests' prompt-cache prefix.
- */
-export function declaresActiveTools(
-  serialized: readonly JsonRecord[],
-  cachedToolFingerprint: string,
-  allTools: readonly ToolInfo[],
-  activeNames: readonly string[],
-): boolean {
-  if (cachedToolFingerprint !== activeToolFingerprint(allTools, activeNames)) return false;
-  const declared = new Map<string, string | undefined>();
-  for (const item of serialized) {
-    if (item.type === "namespace" && isString(item.name) && Array.isArray(item.tools)) {
-      for (const member of item.tools) {
-        if (!isObject(member) || !isString(member.name)) return false;
-        declared.set(
-          `${item.name}.${member.name}`,
-          isString(member["description"]) ? member["description"] : undefined,
-        );
-      }
-    } else if ((item.type === "function" || item.type === "custom") && isString(item.name)) {
-      declared.set(item.name, isString(item["description"]) ? item["description"] : undefined);
-    } else {
-      return false;
-    }
-  }
-  const enabled = new Set(activeNames);
-  const active = allTools.filter((tool) => enabled.has(tool.name));
-  return (
-    declared.size === active.length &&
-    active.every((tool) => declared.has(tool.name) && declared.get(tool.name) === tool.description)
+/** Input properties of the grammar tools a transcript ever declared, for replaying their calls. */
+export function requestGrammarToolInputProperties(
+  model: Model<Api>,
+  messages: readonly Message[],
+): GrammarToolInputProperties {
+  return createGrammarToolInputProperties(
+    getDeclaredTools([...messages]),
+    responsesCompatibility(model.compat).supportsOpenAIGrammarTools ?? false,
   );
 }
 

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

@@ -24,12 +24,6 @@ export const REASONING_SUMMARY_SCHEMA = {
 
 export type ReasoningSummary = Static<typeof REASONING_SUMMARY_SCHEMA>;
 
-export const REASONING_MODE_SCHEMA = {
-  enum: ["standard", "pro"],
-} as const;
-
-export type ReasoningMode = Static<typeof REASONING_MODE_SCHEMA>;
-
 export const IMAGE_DETAIL_SCHEMA = {
   enum: ["auto", "low", "high", "original"],
 } as const;
@@ -80,7 +74,6 @@ export interface CodexCompatConfig {
   webSearch: WebSearchMode;
   textVerbosity: TextVerbosity;
   reasoningSummary: ReasoningSummary;
-  reasoningMode: ReasoningMode;
 }
 
 export const CONFIG_ENVIRONMENT_VARIABLES = {
@@ -98,7 +91,6 @@ export const CONFIG_ENVIRONMENT_VARIABLES = {
   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 = {
@@ -116,7 +108,6 @@ export type ConfigLayer = {
   webSearch?: WebSearchMode;
   textVerbosity?: TextVerbosity;
   reasoningSummary?: ReasoningSummary;
-  reasoningMode?: ReasoningMode;
 };
 
 export const CONFIG_FILE = "openai-codex-compat.json";
@@ -134,7 +125,6 @@ export const DEFAULT_CONFIG: CodexCompatConfig = {
   webSearch: "disabled",
   textVerbosity: "low",
   reasoningSummary: "auto",
-  reasoningMode: "standard",
 };
 
 type Environment = Readonly<Record<string, string | undefined>>;
@@ -277,13 +267,6 @@ export function parseEnvironmentConfig(environment: Environment = process.env):
   );
   if (reasoningSummary !== undefined) layer.reasoningSummary = reasoningSummary;
 
-  const reasoningMode = environmentEnum(
-    environment,
-    CONFIG_ENVIRONMENT_VARIABLES.reasoningMode,
-    REASONING_MODE_SCHEMA,
-  );
-  if (reasoningMode !== undefined) layer.reasoningMode = reasoningMode;
-
   return layer;
 }
 
@@ -357,11 +340,6 @@ export function parseConfig(value: unknown): ConfigLayer {
     layer.reasoningSummary = reasoningSummary;
   }
 
-  const reasoningMode = value["reasoningMode"];
-  if (Value.Check(REASONING_MODE_SCHEMA, reasoningMode)) {
-    layer.reasoningMode = reasoningMode;
-  }
-
   return layer;
 }
 
@@ -404,7 +382,6 @@ export function resolveConfig(
   if (merged.webSearch) config.webSearch = merged.webSearch;
   if (merged.textVerbosity) config.textVerbosity = merged.textVerbosity;
   if (merged.reasoningSummary) config.reasoningSummary = merged.reasoningSummary;
-  if (merged.reasoningMode) config.reasoningMode = merged.reasoningMode;
   return config;
 }
 
@@ -448,7 +425,6 @@ export function configLayer(config: CodexCompatConfig): ConfigLayer {
     webSearch: config.webSearch,
     textVerbosity: config.textVerbosity,
     reasoningSummary: config.reasoningSummary,
-    reasoningMode: config.reasoningMode,
   };
 }
 

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

@@ -4,6 +4,7 @@ import {
   type ExtensionContext,
   type ReadonlyFooterDataProvider,
   type SessionEntry,
+  type SessionManager,
 } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
 import type { CodexCompatConfig } from "./config.ts";
@@ -42,7 +43,6 @@ export type FooterContext = ConfigContext &
 export function footerSettingLabels(config: CodexCompatConfig): string[] {
   return [
     config.fastMode ? "fast" : undefined,
-    config.reasoningMode === "pro" ? "pro" : undefined,
     config.textVerbosity !== "low" ? `verbosity ${config.textVerbosity}` : undefined,
     config.reasoningSummary !== "auto" ? `summary ${config.reasoningSummary}` : undefined,
   ].filter((label): label is string => label !== undefined);
@@ -69,14 +69,23 @@ export function footerModel(
   return { ...model, id, reasoning: false };
 }
 
+/**
+ * The part of Pi's `AgentSession` that `FooterComponent` reads. Pi constructs the
+ * footer with its own session, so the compiler cannot check this adapter against
+ * the footer's actual reads; the packaged TUI test renders it through Pi.
+ */
 interface FooterSessionAdapter {
   readonly state: {
     model: Model<Api> | undefined;
     thinkingLevel: string;
   };
+  /** Pi keys its cached session statistics on this identity. */
+  readonly model: Model<Api> | undefined;
+  /** Extensions cannot observe virtual-model routing, so the footer omits it. */
+  readonly routedModel: undefined;
   sessionManager: Pick<
-    ExtensionContext["sessionManager"],
-    "getEntries" | "getCwd" | "getSessionName"
+    SessionManager,
+    "getEntries" | "getEntryCount" | "getCwd" | "getLeafId" | "getSessionId" | "getSessionName"
   >;
   getContextUsage: () => ReturnType<ExtensionContext["getContextUsage"]>;
   modelRuntime: {
@@ -190,13 +199,20 @@ class CachedFooterSession implements FooterSessionAdapter {
 
   readonly sessionManager: FooterSessionAdapter["sessionManager"];
   readonly modelRuntime: FooterSessionAdapter["modelRuntime"];
+  readonly routedModel = undefined;
 
   constructor(ctx: FooterContext, resolveConfig: ConfigResolver) {
     this.ctx = ctx;
     this.resolveConfig = resolveConfig;
+    // Pi's footer caches its statistics by session id, leaf id, entry count, and
+    // model. The aggregated snapshot is keyed by the same session and leaf, so
+    // both caches refresh together.
     this.sessionManager = {
       getEntries: () => this.getSnapshot().entries,
+      getEntryCount: () => this.getSnapshot().entries.length,
       getCwd: () => ctx.sessionManager.getCwd(),
+      getLeafId: () => ctx.sessionManager.getLeafId(),
+      getSessionId: () => ctx.sessionManager.getSessionId(),
       getSessionName: () => this.getSnapshot().displayName,
     };
     this.modelRuntime = {
@@ -220,6 +236,10 @@ class CachedFooterSession implements FooterSessionAdapter {
     };
   }
 
+  get model(): Model<Api> | undefined {
+    return selectedRegistryModel(this.ctx);
+  }
+
   get state(): FooterSessionAdapter["state"] {
     const model = selectedRegistryModel(this.ctx);
     return {

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

@@ -288,6 +288,14 @@ export default function registerImageGeneration(
     parameters: IMAGE_GENERATION_PARAMETERS,
     executionMode: "sequential",
     renderShell: "self",
+    // Each call adds a new image file and refuses to replace a different one. The request goes
+    // to the OpenAI image service.
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const model = ctx.model;
       if (!isCodexModel(model)) {

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

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import * as piAi from "@earendil-works/pi-ai";
 import * as piCodingAgent from "@earendil-works/pi-coding-agent";
-import { requirePiTranscriptRuntime } from "./pi-runtime.ts";
+import { requirePiRuntime } from "./pi-runtime.ts";
 import { DEFAULT_CONFIG, loadConfig, type CodexCompatConfig } from "./config.ts";
 import type { ConfigContext } from "./config-context.ts";
 import { registerCodexProvider } from "./codex-provider.ts";
@@ -24,7 +24,7 @@ export {
 } from "./codex-transport.ts";
 
 export default function registerOpenAICodexCompat(pi: ExtensionAPI): void {
-  requirePiTranscriptRuntime(piAi, piCodingAgent);
+  requirePiRuntime(piAi, piCodingAgent, pi);
   let activeConfig: CodexCompatConfig | undefined;
   let sessionContext: Parameters<typeof loadSessionConfig>[0] | undefined;
   const resolveConfig = (ctx: ConfigContext): CodexCompatConfig => {

package/extensions/openai-codex-compat/pi-runtime.ts

@@ -1,5 +1,5 @@
 /**
- * Every Pi 0.86 transcript API this extension imports as a value from
+ * Every transcript API this extension imports as a value from
  * `@earendil-works/pi-ai`. Pi's extension loader turns a missing named import
  * into `undefined` rather than a load error, so an older host fails at first use
  * unless the surface is checked up front. Keep this list equal to the value
@@ -18,27 +18,80 @@ export const TRANSCRIPT_APIS = [
 ] as const;
 
 /**
- * Every Pi 0.87 session API this extension imports as a value from
+ * Every session API this extension imports as a value from
  * `@earendil-works/pi-coding-agent`. Keep this list equal to the value imports
  * in `compaction-checkpoint.ts`.
  */
 export const SESSION_APIS = ["buildSessionProjection"] as const;
 
-export const REQUIRED_PI = "Pi 0.87.x";
+/**
+ * Host APIs that first shipped in Pi 0.99: the footer's `SessionManager.getEntryCount()`
+ * and the extension API's `getSettings()`. They prove the loaded runtime is 0.99 even when
+ * `PI_PACKAGE_DIR` points package metadata at another installation.
+ */
+export const PI_099_APIS = ["SessionManager.getEntryCount", "ExtensionAPI.getSettings"] as const;
+
+export const MINIMUM_PI_VERSION = "0.99.1";
+export const REQUIRED_PI = `Pi ${MINIMUM_PI_VERSION} or later`;
+
+function isFunction(value: unknown): boolean {
+  return typeof value === "function";
+}
+
+function prototypeMethod(value: unknown, name: string): unknown {
+  if (typeof value !== "function") return undefined;
+  const prototype: unknown = value.prototype;
+  return typeof prototype === "object" && prototype !== null
+    ? Reflect.get(prototype, name)
+    : undefined;
+}
 
-/** Check the loaded host, not package metadata that PI_PACKAGE_DIR can override. */
-export function requirePiTranscriptRuntime(
+/** Compare dotted numeric release versions; prerelease suffixes rank below their release. */
+export function atLeastVersion(version: unknown, minimum: string): boolean {
+  if (typeof version !== "string") return false;
+  const match = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/.exec(version);
+  if (!match) return false;
+  const actual = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const required = minimum.split(".").map(Number);
+  for (let index = 0; index < 3; index++) {
+    const left = actual[index] ?? 0;
+    const right = required[index] ?? 0;
+    if (left !== right) return left > right;
+  }
+  return match[4] === undefined;
+}
+
+/**
+ * Require the Pi 0.99 host surface and a reported version of at least 0.99.1. The version comes
+ * from package metadata, so the API checks also run to catch an older executable whose
+ * `PI_PACKAGE_DIR` names a newer package.
+ */
+export function requirePiRuntime(
   transcriptApi: Record<string, unknown>,
   sessionApi: Record<string, unknown>,
+  extensionApi: { readonly getSettings?: unknown },
 ): void {
   const missing = [
-    ...TRANSCRIPT_APIS.filter((name) => typeof transcriptApi[name] !== "function"),
-    ...SESSION_APIS.filter((name) => typeof sessionApi[name] !== "function"),
+    ...TRANSCRIPT_APIS.filter((name) => !isFunction(transcriptApi[name])),
+    ...SESSION_APIS.filter((name) => !isFunction(sessionApi[name])),
+    ...(isFunction(prototypeMethod(sessionApi["SessionManager"], "getEntryCount"))
+      ? []
+      : ["SessionManager.getEntryCount"]),
+    ...(isFunction(extensionApi.getSettings) ? [] : ["ExtensionAPI.getSettings"]),
+  ];
+  const version = sessionApi["VERSION"];
+  const problems = [
+    ...(missing.length > 0 ? [`Missing host APIs: ${missing.join(", ")}.`] : []),
+    ...(atLeastVersion(version, MINIMUM_PI_VERSION)
+      ? []
+      : [
+          `The host reports Pi ${typeof version === "string" ? version : "with no version"}, below ${MINIMUM_PI_VERSION}.`,
+        ]),
   ];
-  if (missing.length > 0) {
+  if (problems.length > 0) {
     throw new Error(
       `pi-openai-codex-compat requires a running ${REQUIRED_PI} runtime. ` +
-        `Missing host APIs: ${missing.join(", ")}. ` +
+        `${problems.join(" ")} ` +
         `Exit Pi and start ${REQUIRED_PI} after updating. /reload cannot upgrade the running ` +
         "runtime, and PI_PACKAGE_DIR can make an older executable report a newer version.",
     );