pi-codex-token 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-codex-token contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# pi-codex-token
+
+A [pi](https://github.com/earendil-works/pi) provider extension that registers a
+`codex-token` provider so pi can use **`gpt-5.5` on the OpenAI Codex backend**
+(`chatgpt.com/backend-api/codex`), authenticated **non-interactively with a Codex
+personal/enterprise access token (PAT)**.
+
+It lets you run Codex with a long-lived access token instead of an interactive
+ChatGPT OAuth login — which is what makes it usable for headless/CI automation.
+
+Why a separate provider: pi's built-in `openai-codex` reads the `chatgpt-account-id`
+by JWT-decoding the credential, which an opaque PAT can't satisfy. This provider
+fetches that id out-of-band (the codex `whoami` endpoint) instead, so a plain PAT
+works.
+
+> **Codex access tokens are an OpenAI Codex _enterprise_ feature.** A workspace admin
+> mints a long-lived personal/enterprise access token (`at-…`) for non-interactive use;
+> see OpenAI's docs:
+> [Codex enterprise — access tokens](https://developers.openai.com/codex/enterprise/access-tokens).
+> Without an enterprise plan you won't have a PAT — use pi's built-in `openai-codex`
+> provider (interactive OAuth) instead.
+>
+> **This needs a PAT (`at-…`), not an OpenAI API key (`sk-…`).** The Codex backend is a
+> different auth domain — `sk-…` keys are rejected (401). For `sk-…` keys, use pi's plain
+> `openai` provider.
+
+## Install / local dev
+
+This is a no-build, single-file-style pi extension. Run it straight from a clone:
+
+```bash
+npm install                 # installs dev deps + the pi host packages (peer deps)
+pi -e . --provider codex-token --model gpt-5.5 -p "Reply with exactly: SPIKE_OK"
+```
+
+`pi` resolves the extension's `@earendil-works/pi-*` imports from its own install at
+runtime; `npm install` provides the same packages for local typecheck/test.
+
+## Production use
+
+`pi -e .` is the dev loop. In production you **install** the extension into the
+environment where pi runs (a worker image, CI runner, server) and configure it via env:
+
+1. **Distribute** — publish to npm, or pin a git tag/SHA for an internal build:
+   ```bash
+   pi install pi-codex-token                    # from npm
+   # or, pinned to an immutable ref:
+   pi install <git-url>#<tag-or-sha>
+   ```
+   `pi install` records the source in pi's settings, so the extension loads automatically
+   on every subsequent pi run (no `-e` needed). In a Docker/image build, run the install
+   step at build time so it's baked in.
+
+2. **Configure** (env in the runtime):
+   ```bash
+   export CODEX_ACCESS_TOKEN=at-...     # the enterprise PAT (see above)
+   export CODEX_ACCOUNT_ID=<uuid>       # optional but recommended headless — skips the whoami call
+   ```
+
+3. **Select the provider/model** — either per invocation
+   (`pi --provider codex-token --model gpt-5.5 …`) or via pi's default provider/model config.
+
+At startup pi loads the extension, the async factory discovers the account's models with
+the PAT, and the `codex-token` provider is ready. Pin a tag/SHA (not a moving branch) for a
+reproducible deploy, and gate upgrades on the `npm run smoke` contract test.
+
+## Credentials
+
+PAT precedence (first non-empty wins):
+
+1. the provider `apiKey` (pi resolves `$ENV` / `!command` / `--api-key`)
+2. `CODEX_ACCESS_TOKEN` env, then `CODEX_PAT` (first non-empty wins)
+3. `~/.codex/auth.json` `.personal_access_token` (from `codex login --with-access-token`)
+
+`sk-…` API keys are rejected — the codex backend is a different auth domain (use
+pi's plain `openai` provider for those).
+
+### Account-id (headless)
+
+The `chatgpt-account-id` is a stable workspace UUID resolved in this order:
+
+1. `CODEX_ACCOUNT_ID` env override (**recommended for headless/CI** — no network)
+2. in-memory cache (keyed by `SHA-256(PAT)`)
+3. on-disk cache `~/.pi/agent/codex-token-accountid.json` (mode 0600, keyed by `SHA-256(PAT)`)
+4. codex `whoami` (`Authorization: Bearer <PAT>`)
+5. `~/.codex/auth.json` `.tokens.account_id` (local dev only)
+
+For headless use, set **both** `CODEX_ACCESS_TOKEN` and `CODEX_ACCOUNT_ID` so resolution
+is fully synchronous with no network round-trip.
+
+PATs are **not** auto-refreshable. On a 401 (whoami or backend), the error tells you
+to mint a new PAT.
+
+## Models
+
+The provider **discovers the account's available models** at registration by calling the
+codex `/models` endpoint with the PAT, and registers the ones the account exposes
+(`visibility: list`, API-supported). No PAT at registration, a `/models` error, or an
+empty result falls back to a static `gpt-5.5` entry.
+
+- Set **`CODEX_MODELS`** (comma-separated ids, e.g. `gpt-5.5,gpt-5.4`) to skip discovery
+  and pin an explicit list.
+- `contextWindow` comes from `/models`; **`maxTokens` is a default** (not returned by the
+  endpoint) and is unverified. The static fallback declares `input: ["text"]` (the proven
+  path); discovered entries use the modalities the backend reports.
+
+## Config knobs (env)
+
+| Env var | Purpose |
+|---|---|
+| `CODEX_ACCESS_TOKEN` / `CODEX_PAT` | PAT source (first non-empty wins) |
+| `CODEX_ACCOUNT_ID` | workspace UUID override (skips whoami) |
+| `CODEX_MODELS` | comma-separated model-id list; skips live model discovery |
+| `CODEX_HOME` | dir for `auth.json` (default `~/.codex`) |
+| `CODEX_BASE_URL` | codex inference base URL override |
+| `CODEX_WHOAMI_URL` / `CODEX_AUTHAPI_BASE_URL` | whoami URL override (testing) |
+| `PI_AGENT_HOME` | dir for the on-disk account-id cache |
+
+## Testing
+
+```bash
+npm test            # vitest unit suite + coverage (≥99% on src/**)
+npm run smoke       # live request to the real codex endpoint (needs CODEX_ACCESS_TOKEN)
+npm run check-exports
+```
+
+## How it works
+
+The codex backend is an **undocumented** contract. The provider reuses pi-ai's
+exported `streamSimpleOpenAIResponses` for the HTTP/SSE transport + parsing, injects
+the codex auth headers, and reshapes the request body (top-level `instructions`,
+`store:false`) to satisfy the backend's gates. When the contract drifts, the change
+is confined to `src/codex-envelope.ts` + `src/config.ts`, and the smoke test is the
+early-warning. See [`AGENTS.md`](./AGENTS.md) for the full architecture.
+
+## Contributing
+
+See [`AGENTS.md`](./AGENTS.md) (architecture + conventions) and
+[`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE).

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pi-codex-token",
+  "version": "1.0.1",
+  "description": "pi provider plugin: use gpt-5.5 on the OpenAI Codex backend via a personal access token (PAT), non-interactively.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "codex",
+    "openai",
+    "gpt-5.5",
+    "provider",
+    "personal-access-token"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "smoke": "vitest run test/smoke.test.ts",
+    "check-exports": "node scripts/check-exports.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=20.3"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": ">=0.79.0 <0.80.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.0 <0.80.0",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.79.0 <0.80.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.0 <0.80.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,266 @@
+/**
+ * Credential + account-id lifecycle.
+ *
+ * Pure and provider-agnostic. The PAT is opaque (`at-…`, not a JWT) so the
+ * `chatgpt-account-id` cannot be decoded from it — it is resolved out-of-band via
+ * the codex whoami endpoint and cached, keyed by SHA-256(PAT) so PAT rotation
+ * auto-invalidates the cache and the raw PAT is never written to disk.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  ENV_ACCOUNT_ID,
+  ENV_CODEX_HOME,
+  ENV_PAT_PRIMARY,
+  ENV_PI_AGENT_HOME,
+  PAT_ENV_VARS,
+  PAT_PREFIX,
+  httpTimeoutMs,
+  whoamiUrl,
+} from "./config.js";
+
+/** A fetch-compatible function. The DI seam for whoami (overridable in tests). */
+export type FetchImpl = typeof fetch;
+
+export type CredentialSource = "pi-config" | "env" | "codex-auth-json";
+
+export interface ResolvedCredentials {
+  pat: string;
+  source: CredentialSource;
+}
+
+/**
+ * Raised when a PAT is rejected (401/403) by whoami or the codex backend.
+ * PATs are NOT auto-refreshable (unlike OAuth) — the only recovery is minting a
+ * new one, so the message is actionable.
+ */
+export class PatAuthError extends Error {
+  constructor(public readonly httpStatus?: number) {
+    super(
+      `Codex PAT rejected${httpStatus ? ` (HTTP ${httpStatus})` : ""}. The personal access ` +
+        `token is expired, revoked, or invalid. PATs are NOT auto-refreshable — mint a new one ` +
+        `in the ChatGPT admin console (Settings → Personal access tokens) and update ` +
+        `${ENV_PAT_PRIMARY} (or the provider apiKey / ~/.codex/auth.json). If you switched workspaces, ` +
+        `also clear the cached account-id at ~/.pi/agent/codex-token-accountid.json.`,
+    );
+    this.name = "PatAuthError";
+  }
+}
+
+/** True for HTTP 401/403, whether the value is a PatAuthError, an SDK error, or a 401 message. */
+export function is401(e: unknown): boolean {
+  if (e instanceof PatAuthError) return e.httpStatus === undefined || e.httpStatus === 401 || e.httpStatus === 403;
+  const status = (e as { status?: unknown })?.status;
+  if (status === 401 || status === 403) return true;
+  // Message fallback: only the parenthesized status the inner provider emits
+  // ("OpenAI API error (401): …"). Matching a bare 401/403 anywhere would misread
+  // an id fragment or count in a 400/500 message as an auth failure.
+  const msg = e instanceof Error ? e.message : typeof e === "string" ? e : "";
+  return /\((?:401|403)\)/.test(msg);
+}
+
+// --- PAT sourcing ------------------------------------------------------------
+
+function authJsonPath(env: NodeJS.ProcessEnv): string {
+  const home = env[ENV_CODEX_HOME];
+  return home ? join(home, "auth.json") : join(homedir(), ".codex", "auth.json");
+}
+
+function validate(pat: string, source: CredentialSource): ResolvedCredentials {
+  if (pat.startsWith("sk-")) {
+    // sk- keys are 401 against the codex backend (wrong auth domain).
+    throw new Error(
+      "Got an OpenAI API key (sk-…), but the Codex backend requires a personal access token " +
+        "(at-…). Use the plain `openai` provider for sk- keys.",
+    );
+  }
+  if (!pat.startsWith(PAT_PREFIX)) {
+    // Don't hard-fail (prefix could drift) but warn — the token is opaque, not a JWT.
+    console.warn(`[codex-token] PAT does not start with "${PAT_PREFIX}"; proceeding (opaque token).`);
+  }
+  return { pat, source };
+}
+
+/** First non-empty value among the accepted PAT env vars (precedence order). */
+export function patFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  for (const name of PAT_ENV_VARS) {
+    const value = env[name]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the PAT. Precedence:
+ *   1. pi-resolved ProviderConfig.apiKey (runtime --api-key / $ENV / !command)
+ *   2. PAT env vars: CODEX_ACCESS_TOKEN, then CODEX_PAT
+ *   3. ~/.codex/auth.json .personal_access_token (local `codex login`)
+ */
+export async function resolveCredentials(
+  optionsApiKey?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<ResolvedCredentials> {
+  const fromConfig = optionsApiKey?.trim();
+  if (fromConfig) return validate(fromConfig, "pi-config");
+
+  const fromEnv = patFromEnv(env);
+  if (fromEnv) return validate(fromEnv, "env");
+
+  try {
+    const raw = await readFile(authJsonPath(env), "utf8");
+    const pat = (JSON.parse(raw) as { personal_access_token?: string }).personal_access_token?.trim();
+    if (pat) return validate(pat, "codex-auth-json");
+  } catch {
+    /* no file / unreadable -> fall through */
+  }
+
+  throw new Error(
+    `No Codex PAT found. Set ${ENV_PAT_PRIMARY}, configure the provider's apiKey ` +
+      `(e.g. "$${ENV_PAT_PRIMARY}"), or run \`codex login --with-access-token\`.`,
+  );
+}
+
+// --- account-id resolution (headless) ----------------------------------------
+
+interface WhoamiMetadata {
+  chatgpt_account_id?: string;
+  account_id?: string;
+}
+
+const memCache = new Map<string, string>();
+
+/** Test-only: reset the in-memory account-id cache. */
+export function clearMemCache(): void {
+  memCache.clear();
+}
+
+function patKey(pat: string): string {
+  return createHash("sha256").update(pat).digest("hex").slice(0, 16);
+}
+
+function diskCachePath(env: NodeJS.ProcessEnv): string {
+  const base = env[ENV_PI_AGENT_HOME] ?? join(homedir(), ".pi", "agent");
+  return join(base, "codex-token-accountid.json");
+}
+
+async function readDiskCache(key: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  try {
+    const raw = await readFile(diskCachePath(env), "utf8");
+    return (JSON.parse(raw) as Record<string, string>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeDiskCache(key: string, id: string, env: NodeJS.ProcessEnv): Promise<void> {
+  const path = diskCachePath(env);
+  let current: Record<string, string> = {};
+  try {
+    current = JSON.parse(await readFile(path, "utf8")) as Record<string, string>;
+  } catch {
+    /* fresh file */
+  }
+  current[key] = id;
+  await mkdir(dirname(path), { recursive: true });
+  // Write to a unique temp file then atomically rename, so a concurrent reader (or
+  // another process sharing this cache) never observes a torn/invalid JSON file.
+  // (A last-writer-wins merge can still drop a key under cross-process races, but
+  // that is self-healing: the next readDiskCache miss simply re-resolves via whoami.)
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(current, null, 2), { mode: 0o600 });
+    await rename(tmp, path);
+  } catch (e) {
+    await unlink(tmp).catch(() => {}); // best-effort: don't leave an orphan .tmp behind
+    throw e;
+  }
+}
+
+async function accountIdFromWhoami(
+  pat: string,
+  fetchImpl: FetchImpl,
+  env: NodeJS.ProcessEnv,
+  signal?: AbortSignal,
+): Promise<string> {
+  // Always bound by a timeout; also honor the caller's abort signal if given, so a
+  // cancelled request doesn't leave whoami running to completion.
+  const timeout = AbortSignal.timeout(httpTimeoutMs(env));
+  const res = await fetchImpl(whoamiUrl(env), {
+    headers: { Authorization: `Bearer ${pat}` },
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+  });
+  if (res.status === 401 || res.status === 403) throw new PatAuthError(res.status);
+  if (!res.ok) {
+    throw new Error(
+      `Codex whoami failed with HTTP ${res.status}. The endpoint may have changed; mirror the ` +
+        `official codex CLI (login/src/auth/personal_access_token.rs).`,
+    );
+  }
+  const meta = (await res.json()) as WhoamiMetadata;
+  const id = meta.chatgpt_account_id ?? meta.account_id;
+  if (!id) throw new Error("Codex whoami returned no chatgpt_account_id (response shape drift).");
+  return id;
+}
+
+/** Dev-only convenience: account-id from a local `codex login` (OAuth-mode) auth.json. */
+async function accountIdFromAuthJson(env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  try {
+    const raw = await readFile(authJsonPath(env), "utf8");
+    return (JSON.parse(raw) as { tokens?: { account_id?: string } })?.tokens?.account_id;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the chatgpt-account-id for a PAT. Order:
+ *   1. CODEX_ACCOUNT_ID env override (recommended for headless use — synchronous, no network)
+ *   2. in-memory cache (keyed by SHA-256(PAT))
+ *   3. on-disk cache (~/.pi/agent/codex-token-accountid.json, mode 0600, keyed by SHA-256(PAT))
+ *   4. whoami(PAT)
+ *   5. ~/.codex/auth.json .tokens.account_id (dev convenience only)
+ *
+ * A 401/403 from whoami throws PatAuthError. Other whoami failures fall back to the
+ * dev auth.json before giving up.
+ */
+export async function resolveAccountId(
+  pat: string,
+  fetchImpl: FetchImpl = globalThis.fetch,
+  env: NodeJS.ProcessEnv = process.env,
+  signal?: AbortSignal,
+): Promise<string> {
+  const override = env[ENV_ACCOUNT_ID]?.trim();
+  if (override) return override;
+
+  const key = patKey(pat);
+
+  const mem = memCache.get(key);
+  if (mem) return mem;
+
+  const fromDisk = await readDiskCache(key, env);
+  if (fromDisk) {
+    memCache.set(key, fromDisk);
+    return fromDisk;
+  }
+
+  let id: string;
+  try {
+    id = await accountIdFromWhoami(pat, fetchImpl, env, signal);
+  } catch (e) {
+    if (e instanceof PatAuthError) throw e;
+    // Best-effort dev fallback for a transient whoami failure (timeout/5xx). Do NOT
+    // cache it: the local OAuth auth.json account-id may belong to a different
+    // workspace than the PAT, and caching it would send a mismatched
+    // chatgpt-account-id on every later request even after whoami recovers.
+    const dev = await accountIdFromAuthJson(env);
+    if (dev) return dev;
+    throw e;
+  }
+
+  memCache.set(key, id);
+  await writeDiskCache(key, id, env);
+  return id;
+}

package/src/codex-envelope.ts

@@ -0,0 +1,69 @@
+/**
+ * THE volatile bit, isolated. When the OpenAI codex backend drifts, you edit
+ * ONLY this file (plus config.ts) and the smoke-test fixture.
+ *
+ * Proven-200 request envelope (captured from the working spike, secrets masked):
+ *
+ *   POST https://chatgpt.com/backend-api/codex/responses
+ *   Authorization: Bearer at-***
+ *   chatgpt-account-id: ***UUID***
+ *   OpenAI-Beta: responses=experimental
+ *   originator: pi
+ *   Content-Type: application/json
+ *   Accept: text/event-stream
+ *
+ *   { "model":"gpt-5.5", "input":[{user…}], "stream":true, "store":false,
+ *     "reasoning":{"effort":…}, "instructions":"…" }
+ *
+ * The body-delta vs what pi's generic openai-responses provider emits: codex
+ * requires a TOP-LEVEL `instructions` string. `convertResponsesMessages` instead
+ * inlines the system prompt as a `developer` turn inside `input`, so the backend
+ * returns 400 {"detail":"Instructions are required"}. `makeOnPayload` reproduces
+ * the proven shape post-hoc.
+ */
+
+import { DEFAULT_INSTRUCTIONS, OPENAI_BETA, ORIGINATOR } from "./config.js";
+
+/**
+ * Body transform for the `onPayload` hook. `onPayload` only receives
+ * `(payload, model)` — not `context` — so the system prompt is captured here in a
+ * closure. Carried verbatim from the proven spike.
+ */
+export function makeOnPayload(systemPrompt: string | undefined) {
+  return (payload: unknown): unknown => {
+    const body = payload as Record<string, unknown> & { input?: unknown[] };
+    // 1. Hoist the system prompt to a top-level `instructions` (codex gate).
+    body.instructions =
+      systemPrompt && systemPrompt.length > 0 ? systemPrompt : DEFAULT_INSTRUCTIONS;
+    // 2. Drop the leading developer/system turn convertResponsesMessages injected
+    //    (it would otherwise duplicate the instructions inside `input`).
+    if (Array.isArray(body.input)) {
+      body.input = body.input.filter((m) => {
+        const role = (m as { role?: string })?.role;
+        return role !== "system" && role !== "developer";
+      });
+    }
+    // 3. Enforce codex gates (buildParams already sets these; belt-and-suspenders).
+    body.store = false;
+    body.stream = true;
+    return body;
+  };
+}
+
+/**
+ * The codex wire headers. `streamSimpleOpenAIResponses` merges these as the SDK's
+ * `defaultHeaders` without clobbering, so our values win.
+ */
+export function buildHeaders(
+  pat: string,
+  accountId: string,
+  extra: Record<string, string> = {},
+): Record<string, string> {
+  return {
+    ...extra,
+    Authorization: `Bearer ${pat}`,
+    "chatgpt-account-id": accountId,
+    "OpenAI-Beta": OPENAI_BETA,
+    originator: ORIGINATOR,
+  };
+}

package/src/config.ts

@@ -0,0 +1,105 @@
+/**
+ * All constants and env-var names for the codex-token provider live here.
+ *
+ * The codex backend is an UNDOCUMENTED contract: the betas, headers, and base
+ * URLs below can drift without notice. Keeping them in one file means a contract
+ * change is a one-line edit here (or in codex-envelope.ts), not a hunt across the
+ * package. The values were verified against a live codex request (see AGENTS.md).
+ */
+
+/** Provider id registered with pi. */
+export const PROVIDER_NAME = "codex-token";
+
+/**
+ * Custom api id. Required when `streamSimple` is given, and chosen so it never
+ * collides with pi's built-in `openai` / `openai-codex` / `openai-responses`.
+ * Single source of truth for the api id across the package.
+ */
+export const API_ID = "codex-token-responses";
+
+/** Default codex inference backend. The OpenAI SDK appends `/responses`. */
+export const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex";
+
+/** Default codex auth/whoami host (distinct from the inference host). */
+export const DEFAULT_WHOAMI_URL =
+  "https://auth.openai.com/api/accounts/v1/user-auth-credential/whoami";
+
+/** Dated SSE beta the codex backend accepts today. */
+export const OPENAI_BETA = "responses=experimental";
+
+/** Sent as the `originator` header; matches the proven-200 request. */
+export const ORIGINATOR = "pi";
+
+/** Fallback when there is no system prompt (codex requires top-level instructions). */
+export const DEFAULT_INSTRUCTIONS = "You are a helpful assistant.";
+
+/** Opaque PATs start with this; sk- keys are rejected (wrong auth domain). */
+export const PAT_PREFIX = "at-";
+
+/** maxTokens is not returned by the /models endpoint; sensible default (unverified). */
+export const DEFAULT_MAX_TOKENS = 128000;
+/** contextWindow default when /models omits it. */
+export const DEFAULT_CONTEXT_WINDOW = 272000;
+/** `client_version` query param the /models endpoint requires. */
+export const DEFAULT_CODEX_CLIENT_VERSION = "0.139.0";
+/** Response timeout (ms) for the whoami / models fetches, so they can't hang forever. */
+export const DEFAULT_HTTP_TIMEOUT_MS = 10000;
+
+// --- env var names (no magic strings elsewhere) ------------------------------
+/** Primary PAT env var — matches the OpenAI codex CLI convention (CODEX_ACCESS_TOKEN). */
+export const ENV_PAT_PRIMARY = "CODEX_ACCESS_TOKEN";
+/** PAT env var precedence (first non-empty wins). Primary first. */
+export const PAT_ENV_VARS = [ENV_PAT_PRIMARY, "CODEX_PAT"] as const;
+/** Static workspace UUID override — skips whoami entirely. */
+export const ENV_ACCOUNT_ID = "CODEX_ACCOUNT_ID";
+/** Comma-separated model-id override; skips live model discovery. */
+export const ENV_MODELS = "CODEX_MODELS";
+/** Override for the /models `client_version` query param. */
+export const ENV_CLIENT_VERSION = "CODEX_CLIENT_VERSION";
+/** Override (ms) for the whoami / models fetch timeout. */
+export const ENV_HTTP_TIMEOUT_MS = "CODEX_HTTP_TIMEOUT_MS";
+/** Mirrors codex: dir holding auth.json (local dev). */
+export const ENV_CODEX_HOME = "CODEX_HOME";
+/** Full whoami URL override (testing / mock). */
+export const ENV_WHOAMI_URL = "CODEX_WHOAMI_URL";
+/** Base-URL override for the auth host (mirrors codex personal_access_token.rs). */
+export const ENV_AUTHAPI_BASE_URL = "CODEX_AUTHAPI_BASE_URL";
+/** codex inference base-URL override (testing). */
+export const ENV_CODEX_BASE_URL = "CODEX_BASE_URL";
+/** Dir for the on-disk account-id cache. */
+export const ENV_PI_AGENT_HOME = "PI_AGENT_HOME";
+
+// --- env-derived values (functions so tests can override process.env) --------
+
+/** The codex inference base URL, honoring CODEX_BASE_URL. */
+export function codexBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  return env[ENV_CODEX_BASE_URL]?.trim() || DEFAULT_CODEX_BASE_URL;
+}
+
+/** The codex model-listing endpoint (`{codexBaseUrl}/models`), for discovery. */
+export function modelsUrl(env: NodeJS.ProcessEnv = process.env): string {
+  return `${codexBaseUrl(env)}/models`;
+}
+
+/** The `client_version` query value the /models endpoint requires, honoring the override. */
+export function codexClientVersion(env: NodeJS.ProcessEnv = process.env): string {
+  return env[ENV_CLIENT_VERSION]?.trim() || DEFAULT_CODEX_CLIENT_VERSION;
+}
+
+/** Fetch timeout (ms), honoring CODEX_HTTP_TIMEOUT_MS; falls back to the default for blank/invalid values. */
+export function httpTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env[ENV_HTTP_TIMEOUT_MS]?.trim();
+  const parsed = raw ? Number(raw) : Number.NaN;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_HTTP_TIMEOUT_MS;
+}
+
+/**
+ * The whoami URL. Precedence: CODEX_WHOAMI_URL (full) → CODEX_AUTHAPI_BASE_URL
+ * (base, with the whoami path appended) → default. Mirrors codex's override.
+ */
+export function whoamiUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const full = env[ENV_WHOAMI_URL]?.trim();
+  if (full) return full;
+  const base = env[ENV_AUTHAPI_BASE_URL]?.trim().replace(/\/+$/, "");
+  return base ? `${base}/v1/user-auth-credential/whoami` : DEFAULT_WHOAMI_URL;
+}

package/src/discover-models.ts

@@ -0,0 +1,113 @@
+/**
+ * Live model discovery against the codex `/models` endpoint.
+ *
+ * The account's available models are discovered at registration so the provider isn't
+ * pinned to a hardcoded list. The endpoint needs only `Authorization: Bearer <PAT>` and
+ * a `client_version` query param (no account-id / beta). Its per-model shape carries
+ * `slug`, `display_name`, `context_window`, `input_modalities`,
+ * `supported_reasoning_levels`, `visibility`, and `supported_in_api` — everything we
+ * need except `maxTokens` (defaulted). Verified against the live endpoint; see AGENTS.md.
+ *
+ * Precedence:
+ *   1. CODEX_MODELS env override (comma-separated ids) — no network
+ *   2. live GET {codexBaseUrl}/models?client_version=… → visible, api-supported models
+ *   3. FALLBACK_MODELS ([gpt-5.5]) on any failure / empty result
+ *
+ * Discovery never throws — it always degrades to FALLBACK_MODELS so registration can't break.
+ */
+
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { FetchImpl } from "./auth.js";
+import {
+  API_ID,
+  DEFAULT_CONTEXT_WINDOW,
+  DEFAULT_MAX_TOKENS,
+  ENV_MODELS,
+  codexBaseUrl,
+  codexClientVersion,
+  httpTimeoutMs,
+  modelsUrl,
+} from "./config.js";
+import { FALLBACK_MODELS } from "./models.js";
+
+/** The subset of the codex `/models` per-entry shape we consume. */
+interface RawCodexModel {
+  slug?: string;
+  display_name?: string;
+  context_window?: number;
+  input_modalities?: string[];
+  supported_reasoning_levels?: unknown[];
+  visibility?: string;
+  supported_in_api?: boolean;
+}
+
+function baseConfig(id: string, env: NodeJS.ProcessEnv): ProviderModelConfig {
+  return {
+    id,
+    name: id,
+    api: API_ID,
+    baseUrl: codexBaseUrl(env),
+    reasoning: true,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: DEFAULT_CONTEXT_WINDOW,
+    maxTokens: DEFAULT_MAX_TOKENS,
+  };
+}
+
+function toConfig(raw: RawCodexModel, env: NodeJS.ProcessEnv): ProviderModelConfig | undefined {
+  // Type-guard every field: the /models payload is untrusted wire data, so a single
+  // malformed entry (e.g. a non-string slug) must be skipped, not throw inside .map()
+  // and degrade the whole batch to FALLBACK_MODELS.
+  const id = typeof raw.slug === "string" ? raw.slug.trim() : "";
+  if (!id) return undefined;
+  const modalities = Array.isArray(raw.input_modalities)
+    ? raw.input_modalities.filter((m): m is "text" | "image" => m === "text" || m === "image")
+    : [];
+  const name = typeof raw.display_name === "string" && raw.display_name.trim() ? raw.display_name.trim() : id;
+  return {
+    ...baseConfig(id, env),
+    name,
+    reasoning: Array.isArray(raw.supported_reasoning_levels) && raw.supported_reasoning_levels.length > 0,
+    input: modalities.length ? modalities : ["text"],
+    contextWindow: typeof raw.context_window === "number" ? raw.context_window : DEFAULT_CONTEXT_WINDOW,
+  };
+}
+
+/** Build configs for an explicit CODEX_MODELS override (generic defaults per id). */
+function fromOverride(value: string, env: NodeJS.ProcessEnv): ProviderModelConfig[] {
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((id) => baseConfig(id, env));
+}
+
+export async function discoverModels(
+  pat: string,
+  fetchImpl: FetchImpl = globalThis.fetch,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<ProviderModelConfig[]> {
+  const override = env[ENV_MODELS]?.trim();
+  if (override) {
+    const models = fromOverride(override, env);
+    return models.length ? models : FALLBACK_MODELS;
+  }
+
+  try {
+    const url = `${modelsUrl(env)}?client_version=${encodeURIComponent(codexClientVersion(env))}`;
+    const res = await fetchImpl(url, {
+      headers: { Authorization: `Bearer ${pat}` },
+      signal: AbortSignal.timeout(httpTimeoutMs(env)),
+    });
+    if (!res.ok) return FALLBACK_MODELS;
+    const data = (await res.json()) as { models?: RawCodexModel[] };
+    const models = (data.models ?? [])
+      .filter((m) => m.visibility === "list" && m.supported_in_api !== false)
+      .map((m) => toConfig(m, env))
+      .filter((m): m is ProviderModelConfig => m !== undefined);
+    return models.length ? models : FALLBACK_MODELS;
+  } catch {
+    return FALLBACK_MODELS;
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * pi extension: register the `codex-token` provider so pi can use OpenAI Codex models
+ * (e.g. gpt-5.5) authenticated with an opaque personal access token (PAT),
+ * non-interactively.
+ *
+ * Thin wiring only — all logic lives in the src/ modules (see AGENTS.md):
+ *   config.ts          constants + env-var names
+ *   models.ts          the static FALLBACK_MODELS
+ *   discover-models.ts live model discovery (/models endpoint) + CODEX_MODELS override
+ *   auth.ts            resolveCredentials / resolveAccountId / caching / PatAuthError
+ *   codex-envelope.ts  makeOnPayload + buildHeaders (the volatile contract)
+ *   provider.ts        streamCodexPat (own-stream + async IIFE)
+ */
+
+import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { resolveCredentials } from "./auth.js";
+import { API_ID, DEFAULT_CODEX_BASE_URL, ENV_PAT_PRIMARY, PROVIDER_NAME } from "./config.js";
+import { discoverModels } from "./discover-models.js";
+import { FALLBACK_MODELS } from "./models.js";
+import { streamCodexPat } from "./provider.js";
+
+/**
+ * Best-effort model list at registration: if a PAT is available in the environment
+ * (env or ~/.codex/auth.json), discover the account's models; otherwise use the static
+ * fallback. Never throws — registration must not break on a discovery failure.
+ */
+export async function registrationModels(): Promise<ProviderModelConfig[]> {
+  let pat: string;
+  try {
+    pat = (await resolveCredentials()).pat;
+  } catch {
+    return FALLBACK_MODELS; // no PAT at registration time
+  }
+  return discoverModels(pat);
+}
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+  pi.registerProvider(PROVIDER_NAME, {
+    baseUrl: DEFAULT_CODEX_BASE_URL,
+    apiKey: `$${ENV_PAT_PRIMARY}`,
+    api: API_ID,
+    streamSimple: (model, context, options) => streamCodexPat(model, context, options),
+    models: await registrationModels(),
+  });
+}

package/src/models.ts

@@ -0,0 +1,26 @@
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { API_ID, DEFAULT_CODEX_BASE_URL, DEFAULT_MAX_TOKENS } from "./config.js";
+
+/**
+ * Static fallback model list. Used when live discovery (see `discover-models.ts`) is
+ * unavailable — no PAT at registration, the `/models` endpoint errors, or it returns
+ * nothing. The account's real model set is normally discovered dynamically.
+ *
+ * `gpt-5.5` is the proven model: it returned HTTP 200 on a ChatGPT account, and the
+ * request shape is verified by the smoke test. `input: ["text"]` only — the proven run
+ * was text-only; image is unverified against our SSE transport even though the backend
+ * advertises it. (Discovered entries use the modalities the backend reports.)
+ */
+export const FALLBACK_MODELS: ProviderModelConfig[] = [
+  {
+    id: "gpt-5.5",
+    name: "GPT-5.5 (Codex PAT)",
+    api: API_ID,
+    baseUrl: DEFAULT_CODEX_BASE_URL,
+    reasoning: true,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 272000,
+    maxTokens: DEFAULT_MAX_TOKENS,
+  },
+];

package/src/provider.ts

@@ -0,0 +1,127 @@
+/**
+ * The provider stream function. Thin composition of auth + codex-envelope +
+ * the reused `streamSimpleOpenAIResponses`.
+ *
+ * `streamSimple` must RETURN the stream object synchronously, but the async body
+ * feeding it may await. So we create our own AssistantMessageEventStream, run the
+ * work (credential + account-id resolution, which may hit whoami) in an async
+ * IIFE, pipe the inner provider's events into our stream, and return ours
+ * synchronously.
+ */
+
+import {
+  type Api,
+  type AssistantMessage,
+  type AssistantMessageEvent,
+  type AssistantMessageEventStream,
+  type Context,
+  type Model,
+  type SimpleStreamOptions,
+  createAssistantMessageEventStream,
+  streamSimpleOpenAIResponses,
+} from "@earendil-works/pi-ai";
+import { type FetchImpl, PatAuthError, is401, resolveAccountId, resolveCredentials } from "./auth.js";
+import { buildHeaders, makeOnPayload } from "./codex-envelope.js";
+import { codexBaseUrl } from "./config.js";
+
+/** Injectable seams for unit testing. Defaults are the real implementations. */
+export interface StreamDeps {
+  streamImpl?: typeof streamSimpleOpenAIResponses;
+  createStream?: typeof createAssistantMessageEventStream;
+  resolveCredentialsImpl?: typeof resolveCredentials;
+  resolveAccountIdImpl?: typeof resolveAccountId;
+  fetchImpl?: FetchImpl;
+}
+
+function makeErrorMessage(
+  model: Model<Api>,
+  message: string,
+  stopReason: "error" | "aborted",
+): AssistantMessage {
+  return {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason,
+    errorMessage: message,
+    timestamp: Date.now(),
+  };
+}
+
+export function streamCodexPat(
+  model: Model<Api>,
+  context: Context,
+  options?: SimpleStreamOptions,
+  deps: StreamDeps = {},
+): AssistantMessageEventStream {
+  const streamImpl = deps.streamImpl ?? streamSimpleOpenAIResponses;
+  const createStream = deps.createStream ?? createAssistantMessageEventStream;
+  const resolveCredentialsImpl = deps.resolveCredentialsImpl ?? resolveCredentials;
+  const resolveAccountIdImpl = deps.resolveAccountIdImpl ?? resolveAccountId;
+
+  const stream = createStream();
+
+  (async () => {
+    try {
+      // Honor an already-cancelled request before doing any credential/whoami work;
+      // the signal is also threaded into resolveAccountId so an in-flight whoami aborts.
+      options?.signal?.throwIfAborted();
+      const { pat } = await resolveCredentialsImpl(options?.apiKey);
+      const accountId = await resolveAccountIdImpl(
+        pat,
+        deps.fetchImpl ?? globalThis.fetch,
+        process.env,
+        options?.signal,
+      );
+
+      const headers = buildHeaders(pat, accountId, options?.headers ?? {});
+      // The inner code only reads model.id/baseUrl/reasoning/compat, not the api
+      // string, for body-building — so re-tagging to "openai-responses" is safe.
+      const codexModel = { ...model, baseUrl: codexBaseUrl() } as Model<"openai-responses">;
+
+      const inner = streamImpl(codexModel, context, {
+        ...options,
+        headers,
+        onPayload: makeOnPayload(context.systemPrompt),
+      });
+
+      for await (const ev of inner as AsyncIterable<AssistantMessageEvent>) {
+        // The backend 401 arrives as an `error` event (the inner provider catches
+        // SDK errors internally rather than throwing) — remap its message so the
+        // user gets the same actionable "mint a new PAT" text as a whoami 401.
+        if (ev.type === "error" && is401(ev.error.errorMessage)) {
+          ev.error.errorMessage = new PatAuthError(401).message;
+        }
+        stream.push(ev);
+      }
+      stream.end();
+    } catch (e) {
+      // Thrown before/around the inner stream: missing/invalid PAT, sk- key, a
+      // whoami 401/403 (PatAuthError), or a cancellation. Funnel 401s through the
+      // actionable message, and report a caller cancellation as `aborted` (pi-ai's
+      // convention) rather than a generic error so callers can branch on it.
+      // (A timeout surfaces as TimeoutError → stays `error`, since the backend hung.)
+      const reason: "error" | "aborted" =
+        (e as { name?: string })?.name === "AbortError" ? "aborted" : "error";
+      const message = is401(e)
+        ? new PatAuthError(e instanceof PatAuthError ? e.httpStatus : 401).message
+        : e instanceof Error
+          ? e.message
+          : String(e);
+      stream.push({ type: "error", reason, error: makeErrorMessage(model, message, reason) });
+      stream.end();
+    }
+  })();
+
+  return stream;
+}