pi-openai-codex-compat 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.0.2 - 2026-08-03
+
+### Added
+
+- Add transient `PI_OPENAI_CODEX_COMPAT_*` environment overrides for every compatibility setting, including common boolean aliases, explicit `off`/`default` percentage-compaction values, and an unambiguous `WEB_SEARCH_MODE` name.
+
+### Changed
+
+- Make `Enter` save and close `/codex-settings`, make `Escape` discard unsaved changes and close, and retain `Ctrl+S` as save without closing.
+
 ## 0.0.1 - 2026-08-03
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ OpenAI Codex compatibility for [Pi](https://github.com/earendil-works/pi-mono),
 - **Dedicated Codex tool UI**: renders `apply_patch`, `image_gen.imagegen`, and `web.run` on a shared configurable surface with compact summaries and `Ctrl+O` expansion.
 - **Hosted web-search fallback**: injects native `web_search` only when `web.run` is inactive, with cached, indexed, or live modes.
 - **Native request controls**: configures Responses API text verbosity, reasoning summaries, and GPT-5.6 standard/pro reasoning mode.
-- **Session-local settings pane**: `/codex-settings` changes every compatibility setting for the current session; `Ctrl+S` explicitly persists the current values.
+- **Session-local settings pane**: `/codex-settings` changes every compatibility setting for the current session; `Enter` persists and closes, `Escape` discards unsaved changes and closes, and `Ctrl+S` persists without closing.
 - **Compact footer indicators**: non-default Codex request modes are appended to the model side of Pi's normal second footer line.
 
 Pi provides the Codex OAuth flow and model catalog. At session start, this package overrides the built-in `openai-codex` runtime under the same provider id so ordinary responses and remote compaction share one transport, parser, native-history store, and sticky WebSocket session.
@@ -143,7 +143,7 @@ A trusted project can override it at:
 <project>/.pi/openai-codex-compat.json
 ```
 
-Each session inherits the effective file-backed settings. Open `/codex-settings` to make immediate session-local changes. Press `Ctrl+S` in the pane to persist the current values; the global file is the normal save target, while an existing trusted project override remains the target for that project.
+Each session inherits the effective file-backed settings. Open `/codex-settings` to make immediate session-local changes. Press `Enter` to persist and close, `Escape` to discard unsaved changes and close, or `Ctrl+S` to persist without closing. The global file is the normal save target, while an existing trusted project override remains the target for that project. After `Ctrl+S`, later unsaved changes can still be discarded back to the values from that save.
 
 The effective settings are printed once when a TUI session starts. The footer shows `fast` and `pro` only when enabled, and shows text verbosity or reasoning summary only when they differ from their defaults.
 
@@ -181,7 +181,36 @@ Defaults:
 | `reasoningSummary`     | `auto`, `concise`, `detailed`, `off`                 | `auto`     | Sets `reasoning.summary` when reasoning is enabled; `off` omits the summary parameter.                                                                                                                                                    |
 | `reasoningMode`        | `standard`, `pro`                                    | `standard` | Sets `reasoning.mode` on GPT-5.6 models independently of Pi's reasoning-effort control.                                                                                                                                                   |
 
-Invalid values are ignored and invalid JSON does not prevent Pi from starting. The settings pane never writes on ordinary changes, refuses to overwrite invalid JSON when `Ctrl+S` is pressed, and retains unknown keys when saving. Project configuration is read only when the project is trusted.
+Invalid JSON setting values are ignored and invalid JSON does not prevent Pi from starting. The settings pane never writes on ordinary changes, refuses to overwrite invalid JSON when `Enter` or `Ctrl+S` attempts to save, and retains unknown keys when saving. Project configuration is read only when the project is trusted.
+
+Every setting can also be overridden for one Pi process with an environment variable:
+
+| Setting                | Environment variable                             |
+| ---------------------- | ------------------------------------------------ |
+| `fastMode`             | `PI_OPENAI_CODEX_COMPAT_FAST_MODE`               |
+| `toolBackground`       | `PI_OPENAI_CODEX_COMPAT_TOOL_BACKGROUND`         |
+| `applyPatch`           | `PI_OPENAI_CODEX_COMPAT_APPLY_PATCH`             |
+| `imageGeneration`      | `PI_OPENAI_CODEX_COMPAT_IMAGE_GENERATION`        |
+| `imageDetail`          | `PI_OPENAI_CODEX_COMPAT_IMAGE_DETAIL`            |
+| `webRun`               | `PI_OPENAI_CODEX_COMPAT_WEB_RUN`                 |
+| `autoCompactAtPercent` | `PI_OPENAI_CODEX_COMPAT_AUTO_COMPACT_AT_PERCENT` |
+| `webSearch`            | `PI_OPENAI_CODEX_COMPAT_WEB_SEARCH_MODE`         |
+| `textVerbosity`        | `PI_OPENAI_CODEX_COMPAT_TEXT_VERBOSITY`          |
+| `reasoningSummary`     | `PI_OPENAI_CODEX_COMPAT_REASONING_SUMMARY`       |
+| `reasoningMode`        | `PI_OPENAI_CODEX_COMPAT_REASONING_MODE`          |
+
+Environment variables have the highest precedence: defaults < global JSON < trusted-project JSON < environment. Boolean values accept `true`/`false`, `1`/`0`, `on`/`off`, or `enabled`/`disabled`. Other settings use the values in the defaults table; `PI_OPENAI_CODEX_COMPAT_AUTO_COMPACT_AT_PERCENT=off` and `PI_OPENAI_CODEX_COMPAT_AUTO_COMPACT_AT_PERCENT=default` explicitly select Pi's default compaction lifecycle.
+
+Environment-controlled rows are marked `(env)` and locked in `/codex-settings`. Saving the pane does not copy their effective values into JSON, so CLI overrides remain transient. Invalid environment values fail fast with the variable name and accepted values.
+
+For example:
+
+```bash
+PI_OPENAI_CODEX_COMPAT_WEB_RUN=off \
+PI_OPENAI_CODEX_COMPAT_IMAGE_DETAIL=high \
+PI_OPENAI_CODEX_COMPAT_AUTO_COMPACT_AT_PERCENT=90 \
+pi
+```
 
 ## Native compaction
 
@@ -262,7 +291,7 @@ The tool generates new images with `gpt-image-2` or edits up to five local/recen
 ~/.pi/agent/generated_images/<session-id>/<call-id>.png
 ```
 
-The active Pi agent directory replaces `~/.pi/agent` when configured differently. Turning `imageGeneration` off removes the tool immediately for the current session; `Ctrl+S` in `/codex-settings` persists the value.
+The active Pi agent directory replaces `~/.pi/agent` when configured differently. Turning `imageGeneration` off removes the tool immediately for the current session; `Enter` or `Ctrl+S` in `/codex-settings` persists the value.
 
 Pi also persists the returned image content in tool-result history so later image edits and provider replay remain self-contained. Generated-image turns therefore increase the session file by approximately the base64 image size in addition to the saved PNG artifact.
 

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;
@@ -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/index.ts

@@ -30,7 +30,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/settings-pane.ts

@@ -10,11 +10,15 @@ import {
   type SettingItem,
   SettingsList,
   Text,
+  truncateToWidth,
 } from "@earendil-works/pi-tui";
 import {
+  CONFIG_ENVIRONMENT_VARIABLES,
   configLayer,
   loadConfig,
+  parseEnvironmentConfig,
   saveConfig,
+  withoutEnvironmentOverrides,
   writableConfigPath,
   type CodexCompatConfig,
   type ConfigLayer,
@@ -48,8 +52,11 @@ function thresholdValue(value: number | undefined): string {
   return value === undefined ? "Pi default" : `${value}%`;
 }
 
-export function settingItems(config: CodexCompatConfig): SettingItem[] {
-  return [
+export function settingItems(
+  config: CodexCompatConfig,
+  environmentConfig: ConfigLayer = {},
+): SettingItem[] {
+  const items: SettingItem[] = [
     {
       id: "fastMode",
       label: "Fast mode",
@@ -130,6 +137,18 @@ export function settingItems(config: CodexCompatConfig): SettingItem[] {
       values: ["Pi default", "75%", "80%", "85%", "90%", "95%"],
     },
   ];
+
+  return items.map((item) => {
+    const id = item.id as SettingId;
+    if (!Object.hasOwn(environmentConfig, id)) return item;
+
+    const variable = CONFIG_ENVIRONMENT_VARIABLES[id];
+    const lockedItem = { ...item };
+    lockedItem.currentValue = `${item.currentValue} (env)`;
+    lockedItem.description = `${item.description} Locked by ${variable}.`;
+    delete lockedItem.values;
+    return lockedItem;
+  });
 }
 
 export function settingPatch(id: string, value: string): ConfigLayer | undefined {
@@ -212,18 +231,21 @@ async function showSettings(
   }
 
   let config = callbacks.getConfig?.(ctx) ?? loadConfig(ctx.cwd, ctx.isProjectTrusted());
+  let persistedConfig = { ...config };
   let revision = 0;
   let savedRevision = 0;
   let saveQueue = Promise.resolve();
   const filePath = writableConfigPath(ctx.cwd, ctx.isProjectTrusted());
+  const environmentConfig = parseEnvironmentConfig();
 
-  await ctx.ui.custom((tui, theme, _keybindings, done) => {
+  await ctx.ui.custom((tui, theme, keybindings, done) => {
+    let closing = false;
     const container = new Container();
     container.addChild(
       new Text(theme.fg("accent", theme.bold("OpenAI Codex Compatibility Settings")), 1, 1),
     );
     container.addChild(
-      new Text(theme.fg("dim", `Session-only. Ctrl+S saves to ${filePath}`), 1, 0),
+      new Text(theme.fg("dim", `Ctrl+S saves without closing to ${filePath}`), 1, 0),
     );
     const saveStatus = new Text(
       theme.fg("dim", "Changes apply to this session immediately."),
@@ -232,10 +254,61 @@ async function showSettings(
     );
     container.addChild(saveStatus);
 
+    const queueSave = (closeAfterSave: boolean): void => {
+      if (closing) return;
+      if (closeAfterSave) closing = true;
+
+      const snapshotConfig = { ...config };
+      const snapshot = withoutEnvironmentOverrides(configLayer(snapshotConfig), environmentConfig);
+      const snapshotRevision = revision;
+      saveStatus.setText(theme.fg("dim", closeAfterSave ? "Saving and closing…" : "Saving…"));
+      saveQueue = saveQueue.then(async () => {
+        try {
+          const savedPath = await saveConfig(ctx.cwd, ctx.isProjectTrusted(), snapshot);
+          if (snapshotRevision >= savedRevision) {
+            persistedConfig = snapshotConfig;
+            savedRevision = snapshotRevision;
+          }
+          if (closeAfterSave) {
+            done(undefined);
+            return;
+          }
+          saveStatus.setText(
+            savedRevision === revision
+              ? theme.fg("success", `Saved to ${savedPath}`)
+              : theme.fg("warning", "Unsaved session changes."),
+          );
+        } catch (error) {
+          if (closeAfterSave) closing = false;
+          const message = error instanceof Error ? error.message : String(error);
+          saveStatus.setText(theme.fg("error", message));
+          ctx.ui.notify(message, "error");
+        }
+        tui.requestRender();
+      });
+      tui.requestRender();
+    };
+
+    const discardAndClose = (): void => {
+      if (closing) return;
+      closing = true;
+      saveStatus.setText(theme.fg("dim", "Discarding unsaved changes…"));
+      saveQueue = saveQueue.then(() => {
+        if (revision !== savedRevision) {
+          config = { ...persistedConfig };
+          revision = savedRevision;
+          callbacks.onChange?.(config, ctx);
+        }
+        done(undefined);
+      });
+      tui.requestRender();
+    };
+
+    const listTheme = getSettingsListTheme();
     const list = new SettingsList(
-      settingItems(config),
+      settingItems(config, environmentConfig),
       12,
-      getSettingsListTheme(),
+      listTheme,
       (id, value) => {
         const patch = settingPatch(id, value);
         if (!patch) return;
@@ -246,36 +319,42 @@ async function showSettings(
         saveStatus.setText(theme.fg("warning", "Unsaved session changes."));
         tui.requestRender();
       },
-      () => done(undefined),
+      discardAndClose,
       { enableSearch: true },
     );
-    container.addChild(list);
+    container.addChild({
+      render: (width: number) => {
+        const lines = list.render(width);
+        if (lines.length > 0) {
+          lines[lines.length - 1] = truncateToWidth(
+            listTheme.hint(
+              "  Type to search · Space changes · Enter save & close · Esc discard & close",
+            ),
+            width,
+            "",
+          );
+        }
+        return lines;
+      },
+      invalidate: () => list.invalidate(),
+      handleInput: (data: string) => list.handleInput(data),
+    });
 
     return {
       render: (width: number) => container.render(width),
       invalidate: () => container.invalidate(),
       handleInput: (data: string) => {
+        if (closing) return;
         if (matchesKey(data, Key.ctrl("s"))) {
-          const snapshot = configLayer(config);
-          const snapshotRevision = revision;
-          saveStatus.setText(theme.fg("dim", "Saving…"));
-          saveQueue = saveQueue.then(async () => {
-            try {
-              const savedPath = await saveConfig(ctx.cwd, ctx.isProjectTrusted(), snapshot);
-              savedRevision = Math.max(savedRevision, snapshotRevision);
-              saveStatus.setText(
-                savedRevision === revision
-                  ? theme.fg("success", `Saved to ${savedPath}`)
-                  : theme.fg("warning", "Unsaved session changes."),
-              );
-            } catch (error) {
-              const message = error instanceof Error ? error.message : String(error);
-              saveStatus.setText(theme.fg("error", message));
-              ctx.ui.notify(message, "error");
-            }
-            tui.requestRender();
-          });
-          tui.requestRender();
+          queueSave(false);
+          return;
+        }
+        if (matchesKey(data, Key.enter)) {
+          queueSave(true);
+          return;
+        }
+        if (matchesKey(data, Key.escape) || keybindings.matches(data, "tui.select.cancel")) {
+          discardAndClose();
           return;
         }
         list.handleInput(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-codex-compat",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "OpenAI Codex compatibility for Pi with native compaction, fast mode, and Codex-optimized capabilities",
   "keywords": [
     "pi-package"