@jaralabs/codex-bridge 0.3.0 → 0.4.1

package/README.md

@@ -1,22 +1,36 @@
 # @jaralabs/codex-bridge
 
-> Use your ChatGPT Business / Team / Plus subscription from OpenCode instead of paying for the OpenAI API.
+> Use your ChatGPT Business / Team / Plus subscription from OpenCode instead
+> of paying for the OpenAI API.
 
 `codex-bridge` runs an OpenAI-compatible HTTP server on `127.0.0.1:11434` that
-forwards chat-completion requests to the [OpenAI Codex CLI][codex]. Because
-the Codex CLI reuses the local ChatGPT OAuth session in `~/.codex/auth.json`,
-your OpenCode prompts consume your subscription credits — not the OpenAI API
-balance.
-
-[codex]: https://github.com/openai/codex
+forwards chat-completion requests to the ChatGPT Responses API
+(`https://chatgpt.com/backend-api/codex/responses`) using the OAuth session in
+`~/.codex/auth.json`. Your OpenCode prompts consume your subscription credits
+— not the OpenAI API balance.
+
+The bridge is a thin, durable proxy:
+
+* No dependency on the Codex CLI at runtime. (The CLI rejects ChatGPT Plus
+  models when invoked directly; the bridge speaks the same wire format
+  itself.)
+* Auto-refreshes the access token via `https://auth.openai.com/oauth/token`
+  when the API returns 401, and persists the new tokens to `auth.json`.
+* Wraps every upstream call in retry-with-jitter and a circuit breaker, so
+  transient 429/5xx errors do not bubble to OpenCode.
+* Probes the upstream API at boot and persists the wire shape to
+  `~/.codex/bridge_capabilities.json`. A drift on the next boot (model
+  rename, missing event, status flip) is logged as a warning.
+* Exposes `/v1/health` for in-process resilience metrics (requests, retries,
+  circuit state).
 
 ## Why
 
 If you have a ChatGPT Business / Team / Plus plan, the OpenAI API and the
-ChatGPT web subscription are billed separately. You can use Codex CLI / web
-App today with the subscription. `codex-bridge` exposes the same models over
-an OpenAI-compatible HTTP surface so OpenCode (and any other OpenAI client
-like Claude Code, Cline, aider) can use them without an API key.
+ChatGPT web subscription are billed separately. You can use the Codex CLI /
+web App today with the subscription. `codex-bridge` exposes the same models
+over an OpenAI-compatible HTTP surface so OpenCode (and any other OpenAI
+client like Claude Code, Cline, aider) can use them without an API key.
 
 ## Install
 
@@ -24,76 +38,143 @@ like Claude Code, Cline, aider) can use them without an API key.
 npm install -g @jaralabs/codex-bridge
 ```
 
-Requires Node 18 or newer and the OpenAI Codex CLI installed and logged in
-once with `codex login` on a machine with the ChatGPT Business / Team / Plus
-session.
+Requires:
 
-## Wire it into OpenCode
+* Node.js 20 or newer.
+* The OpenAI Codex CLI installed and logged in **once** with `codex login`
+  on a machine with the ChatGPT Business / Team / Plus session. The bridge
+  reads `~/.codex/auth.json` for the OAuth tokens. After the first login,
+  the CLI is no longer required at runtime.
 
-Add a `chatgpt` provider to `~/.config/opencode/opencode.jsonc`:
-
-```json
-{
-  "provider": {
-    "chatgpt": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "ChatGPT Business (codex-bridge)",
-      "options": {
-        "baseURL": "http://127.0.0.1:11434/v1"
-      },
-      "models": {
-        "gpt-6.1-sol": {
-          "name": "GPT-6.1 Sol (Business)",
-          "limit": { "context": 272000, "output": 128000 },
-          "modalities": { "input": ["text", "image"], "output": ["text"] }
-        }
-      }
-    }
-  }
-}
-```
+## Wire it into OpenCode
 
-The exact model list depends on what your plan exposes. `codex-bridge start`
-syncs the model list from `~/.codex/models_cache.json` (refreshed by Codex
-whenever it talks to ChatGPT) and rewrites the `provider.chatgpt.models`
-block to match. Re-run `codex-bridge start` after any plan change.
+There are two pieces: the bridge running on `127.0.0.1:11434`, and the
+OpenCode plugin that registers the `chatgpt` provider plus the default MCP
+servers.
 
-## Usage
+### 1. Run the bridge
 
 ```bash
 codex-bridge start    # sync models + start HTTP server in background
 codex-bridge status   # is it up?
-codex-bridge sync     # only sync model list (no server)
 codex-bridge logs     # tail the server log
 codex-bridge stop     # kill the server
 ```
 
-In another terminal:
+Other useful commands:
+
+```bash
+codex-bridge sync     # only sync the model list (no server)
+```
+
+### 2. Install the OpenCode plugin
+
+Copy or symlink `lib/plugin.ts` to `~/.config/opencode/plugins/codex-bridge.ts`:
 
 ```bash
-opencode run --model=chatgpt/gpt-6.1-sol "say hi"
+mkdir -p ~/.config/opencode/plugins
+ln -s "$(npm root -g)/@jaralabs/codex-bridge/lib/plugin.ts" \
+       ~/.config/opencode/plugins/codex-bridge.ts
 ```
 
+The plugin:
+
+* Registers the `chatgpt` provider pointing at `http://127.0.0.1:11434/v1`.
+* Adds the live model list from `~/.codex/models_cache.json`.
+* Registers the default MCP servers (Doop, codegraph, codegraph-fe, angecom).
+  Disable per-instance with `CODEX_BRIDGE_DISABLE_<NAME>=1`.
+* Seeds a V2 permission policy: read-only tools are `allow`, anything that
+  mutates state is `ask`, mirroring the ChatGPT Plus UX.
+
+Restart OpenCode after installing the plugin so it picks it up.
+
+### 3. Pick a model
+
+In OpenCode, choose one of the `chatgpt/*` models from the picker and chat
+normally. Tool calls (Doop, codegraph, etc.) round-trip through the bridge
+and trigger the OpenCode approval prompt when the policy says `ask`.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/v1/models` | List the ChatGPT Plus models available in your plan |
+| `POST` | `/v1/chat/completions` | OpenAI-style chat completions (streaming or JSON) |
+| `GET` | `/v1/tools` | List registered MCP tools the bridge will advertise to the model |
+| `POST` | `/v1/tools` | Register a list of MCP tools (used by the OpenCode plugin on session start) |
+| `DELETE` | `/v1/tools` | Clear the registry |
+| `GET` | `/v1/health` | Resilience metrics: requests, successes, failures, retries, circuit state |
+| `GET` | `/healthz` | Liveness probe (always returns `{ ok: true }`) |
+
+## Tool-call flow
+
+1. OpenCode sends `POST /v1/chat/completions` with `messages` and optionally
+   `tools=[]`.
+2. The bridge translates Chat Completions into the OpenAI Responses API wire
+   format. If `tools` is missing, the registered MCP tools are rendered into
+   a Plus-style system block describing what the model can call.
+3. The bridge POSTs to `chatgpt.com/backend-api/codex/responses` with the
+   current access token. The response is an SSE stream of
+   `response.output_text.delta` / `response.function_call_arguments.delta` /
+   `response.completed` events.
+4. The bridge streams OpenAI-style chunks back: `delta.content` for text and
+   `delta.tool_calls[]` for tool calls. Tool calls carry an OpenAI-shaped
+   `tool_call_id` so the AI SDK can match them on the next round-trip.
+5. OpenCode runs the tool against the real MCP server and sends a follow-up
+   request with `role: "tool"` messages. The bridge translates those into
+   `function_call_output` items and re-issues.
+6. Loop until the model returns no more tool calls.
+
+## Tests
+
+```bash
+npm test              # smoke (server up, /healthz, /v1/models, chat)
+npm run test:tools    # tool transport, registry, multi-turn loop
+npm run test:resilience  # retry, circuit breaker, metrics (pure unit)
+npm run test:smoke    # live integration test against the real ChatGPT API
+                       # (requires ~/.codex/auth.json on the machine)
+```
+
+The `test:smoke` script is what the GitHub Actions daily cron runs to catch
+wire-shape drift the day OpenAI changes something. Set
+`CODEX_BRIDGE_SKIP_LIVE=1` to skip the network call in air-gapped CI.
+
+## CI
+
+The GitHub Actions workflow at `.github/workflows/publish.yml` has three
+jobs:
+
+* **test**: resilience unit tests, type-check the OpenCode plugin, and
+  `node --check` every ESM source file.
+* **smoke**: writes `CODEX_AUTH_JSON` to `~/.codex/auth.json` and runs
+  `test:smoke.mjs` against the real ChatGPT API. Runs on push to main and
+  on a daily cron. Skipped silently when the secret is missing, so a
+  private repo without the secret can still build.
+* **publish**: on push to main, bumps the package to npm via **OpenID
+  Connect Trusted Publishing** (no NPM_TOKEN secret). The trusted publisher
+  is configured on the package itself
+  (`https://www.npmjs.com/package/@jaralabs/codex-bridge` → Settings →
+  Trusted Publishers → `jaralabs/codex-bridge` / `publish.yml`).
+
+The publish step only uploads a new version when `package.json`'s version
+differs from the latest on npm, so doc and test commits on main are no-ops.
+
 ## How it works
 
 ```
 ┌──────────┐        HTTP (OpenAI-compatible)        ┌────────────────┐
 │ OpenCode │ ──────────────────────────────────────▶ │ codex-bridge   │
-│          │ ◀────────────────────────────────────── │ 127.0.0.1:11434│
+│  + MCP   │ ◀────────────────────────────────────── │ 127.0.0.1:11434│
 └──────────┘                                         └────────────────┘
                                                           │
-                                       spawns             ▼
+                                       HTTPS + OAuth       ▼
                                                   ┌─────────────────┐
-                                                  │ codex exec      │
-                                                  │ (uses ChatGPT   │
-                                                  │  OAuth session) │
+                                                  │ chatgpt.com/    │
+                                                  │ backend-api/    │
+                                                  │ codex/responses │
                                                   └─────────────────┘
 ```
 
-The bridge has zero state of its own. It just maps an OpenAI-style HTTP
-request into a Codex CLI invocation and pipes the result back. Codex handles
-auth, plan routing, and rate limits.
-
 ## License
 
 MIT.

package/lib/auth.mjs

@@ -0,0 +1,79 @@
+// auth.mjs: load, cache, and refresh the ChatGPT account tokens that
+// live in ~/.codex/auth.json. The bridge never writes the password
+// back to the file; only the refreshed tokens. The cache TTL is short
+// (30s) so an external `codex login` is picked up without a bridge
+// restart, and refresh is triggered by 401 from the upstream API.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CODEX_HOME = process.env.CODEX_HOME || join(homedir(), ".codex");
+const AUTH_PATH = join(CODEX_HOME, "auth.json");
+const AUTH_TTL_MS = 30_000;
+
+const OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+const OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+
+let _authCache = null;
+let _authLoadedAt = 0;
+
+export function loadAuth() {
+  if (!existsSync(AUTH_PATH)) {
+    throw new Error(`auth.json not found at ${AUTH_PATH}; run \`codex login\` first`);
+  }
+  if (_authCache && Date.now() - _authLoadedAt < AUTH_TTL_MS) return _authCache;
+  const raw = readFileSync(AUTH_PATH, "utf8");
+  const parsed = JSON.parse(raw);
+  if (parsed.auth_mode !== "chatgpt") {
+    throw new Error(`auth.json auth_mode=${parsed.auth_mode}; only chatgpt supported`);
+  }
+  _authCache = parsed.tokens;
+  _authLoadedAt = Date.now();
+  return _authCache;
+}
+
+export async function refreshAccessToken(refreshToken) {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: OAUTH_CLIENT_ID,
+    scope: "openid profile email offline-access",
+  });
+  const res = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`oauth refresh failed ${res.status}: ${text.slice(0, 300)}`);
+  }
+  const json = await res.json();
+  const current = _authCache || loadAuth();
+  const updated = {
+    ...current,
+    access_token: json.access_token,
+    refresh_token: json.refresh_token || current.refresh_token,
+    id_token: json.id_token || current.id_token,
+  };
+  try {
+    const raw = readFileSync(AUTH_PATH, "utf8");
+    const file = JSON.parse(raw);
+    file.tokens = updated;
+    writeFileSync(AUTH_PATH, JSON.stringify(file, null, 2));
+  } catch {
+    // best-effort; next refresh will try again
+  }
+  _authCache = updated;
+  _authLoadedAt = Date.now();
+  return updated;
+}
+
+export async function getAuth() {
+  const a = loadAuth();
+  if (!a.access_token && a.refresh_token) {
+    return refreshAccessToken(a.refresh_token);
+  }
+  return a;
+}

package/lib/capabilities.mjs

@@ -0,0 +1,183 @@
+// capabilities.mjs: probe the upstream ChatGPT Responses API at boot
+// and persist a small capability record to ~/.codex/bridge_capabilities.json.
+//
+// The probe sends a minimal request (one user message, no tools) and
+// records:
+//
+//   * which request fields the API accepted (or rejected) so we can
+//     detect a wire-shape drift the next time the bridge starts;
+//   * the round-trip latency;
+//   * the resolved model id (so we know if the model slug was renamed
+//     or routed to a different one);
+//   * the response shape: did we get an event stream? Did the
+//     response.completed event arrive?
+//
+// The next boot compares the new probe against the previous record.
+// If the shape changes in a way we did not anticipate, we log a
+// warn and (optionally) refuse to start.
+//
+// The probe is best-effort. If it fails, the bridge still starts:
+// the real chat handler will surface a clearer error on the first
+// request and the operator can see what changed.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAuth } from "./auth.mjs";
+
+const CODEX_HOME = process.env.CODEX_HOME || join(homedir(), ".codex");
+const CAPS_PATH = join(CODEX_HOME, "bridge_capabilities.json");
+const CHATGPT_BASE = "https://chatgpt.com/backend-api/codex";
+
+const PROBE_MODEL = process.env.CODEX_BRIDGE_PROBE_MODEL || "gpt-6-luna";
+
+// The list of body fields we send on every request. The probe
+// checks which of these the API still accepts. If a previously
+// accepted field is now rejected, we log a strong warn.
+const PROBE_FIELDS = [
+  "model",
+  "store",
+  "stream",
+  "instructions",
+  "input",
+  "tool_choice",
+  "parallel_tool_calls",
+  "prompt_cache_key",
+];
+
+export async function probeCapabilities({ log = console.log.bind(console) } = {}) {
+  const start = Date.now();
+  let result;
+  try {
+    const auth = await getAuth();
+    const body = {
+      model: PROBE_MODEL,
+      store: false,
+      stream: true,
+      input: [
+        {
+          type: "message",
+          role: "user",
+          content: [{ type: "input_text", text: "ping" }],
+        },
+      ],
+      prompt_cache_key: `bridge-probe-${Date.now()}`,
+    };
+    const res = await fetch(`${CHATGPT_BASE}/responses`, {
+      method: "POST",
+      signal: AbortSignal.timeout(15_000),
+      headers: {
+        authorization: `Bearer ${auth.access_token}`,
+        "content-type": "application/json",
+        accept: "text/event-stream",
+        "OpenAI-Beta": "responses=experimental",
+        "chatgpt-account-id": auth.account_id || "",
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      result = { ok: false, status: res.status, error: text.slice(0, 400), latencyMs: Date.now() - start };
+    } else {
+      // Read the SSE stream until the first response.completed or
+      // error event, then bail. We do not need the full response.
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder("utf8");
+      let buf = "";
+      let completed = false;
+      let resolvedModel = null;
+      let firstEvent = null;
+      const events = new Set();
+      while (!completed) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf("\n\n")) !== -1) {
+          const block = buf.slice(0, idx);
+          buf = buf.slice(idx + 2);
+          let data = "";
+          for (const line of block.split("\n")) {
+            if (line.startsWith("data:")) data += line.slice(5).trim();
+          }
+          if (!data || data === "[DONE]") continue;
+          let json;
+          try { json = JSON.parse(data); } catch { continue; }
+          events.add(json.type);
+          if (!firstEvent) firstEvent = json.type;
+          if (json.type === "response.completed") {
+            completed = true;
+            resolvedModel = json.response?.model || null;
+            break;
+          }
+          if (json.type === "error" || json.type === "response.failed") {
+            completed = true;
+            result = { ok: false, status: res.status, error: json.message || json.error || "unknown", events: Array.from(events) };
+            try { await reader.cancel(); } catch {}
+            break;
+          }
+        }
+      }
+      if (!result) {
+        result = {
+          ok: true,
+          status: res.status,
+          latencyMs: Date.now() - start,
+          resolvedModel,
+          firstEvent,
+          events: Array.from(events),
+        };
+      }
+    }
+  } catch (e) {
+    result = { ok: false, error: e?.message || String(e), latencyMs: Date.now() - start };
+  }
+
+  // Compare against the previous record.
+  const previous = readPrevious();
+  const record = {
+    probedAt: new Date().toISOString(),
+    probeModel: PROBE_MODEL,
+    probeFields: PROBE_FIELDS,
+    ...result,
+  };
+  if (previous) {
+    const drift = detectDrift(previous, record);
+    if (drift.length > 0) {
+      log("warn", "capabilities.drift", { drift });
+    }
+  }
+  try {
+    mkdirSync(CODEX_HOME, { recursive: true });
+    writeFileSync(CAPS_PATH, JSON.stringify(record, null, 2));
+  } catch (e) {
+    // best-effort: do not block startup on disk write failure
+  }
+  return record;
+}
+
+function readPrevious() {
+  if (!existsSync(CAPS_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(CAPS_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectDrift(prev, next) {
+  const out = [];
+  if (prev.ok !== next.ok) {
+    out.push({ kind: "ok", before: prev.ok, after: next.ok });
+  }
+  if (prev.resolvedModel && next.resolvedModel && prev.resolvedModel !== next.resolvedModel) {
+    out.push({ kind: "resolvedModel", before: prev.resolvedModel, after: next.resolvedModel });
+  }
+  if (Array.isArray(prev.events) && Array.isArray(next.events)) {
+    const lost = prev.events.filter((e) => !next.events.includes(e));
+    const gained = next.events.filter((e) => !prev.events.includes(e));
+    if (lost.length > 0) out.push({ kind: "eventsLost", events: lost });
+    if (gained.length > 0) out.push({ kind: "eventsGained", events: gained });
+  }
+  return out;
+}

package/lib/resilience.mjs

@@ -0,0 +1,182 @@
+// resilience.mjs: backoff retry, circuit breaker, and in-memory metrics
+// for the upstream ChatGPT Responses API.
+//
+// Goals:
+//   * Survive transient 429/5xx without surfacing the error to the
+//     client when a quick retry would have worked.
+//   * Stop hammering the API when it is clearly down (circuit
+//     breaker) so the bridge does not amplify an outage.
+//   * Surface a small set of counters at /v1/health so an operator
+//     can see whether the bridge is healthy without log scraping.
+//
+// This module is in-memory and process-local. State resets on
+// restart, which is fine for a single-process bridge.
+
+import { appendFileSync } from "node:fs";
+
+const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+const DEFAULT_MAX_RETRIES = 4;
+const DEFAULT_BASE_MS = 400;
+const DEFAULT_MAX_MS = 8_000;
+const CIRCUIT_FAIL_THRESHOLD = 5;        // consecutive failures to open
+const CIRCUIT_WINDOW_MS = 30_000;        // failures older than this drop off
+const CIRCUIT_COOLDOWN_MS = 15_000;      // how long we stay open before half-open
+
+const state = {
+  // metrics
+  requests: 0,
+  successes: 0,
+  failures: 0,
+  retries: 0,
+  lastError: null,
+  lastSuccessAt: 0,
+  lastFailureAt: 0,
+  // circuit breaker
+  failureTimes: [],   // timestamps of recent failures
+  circuitOpenedAt: 0, // 0 = closed; >0 = open since this timestamp
+  halfOpenProbe: null, // one in-flight probe during half-open
+};
+
+export function recordSuccess() {
+  state.requests += 1;
+  state.successes += 1;
+  state.lastSuccessAt = Date.now();
+  state.lastError = null;
+  // A success closes the circuit if we are in half-open.
+  if (state.circuitOpenedAt) {
+    state.circuitOpenedAt = 0;
+    state.halfOpenProbe = null;
+    log("info", "circuit.closed");
+  }
+}
+
+export function recordFailure(err) {
+  state.requests += 1;
+  state.failures += 1;
+  state.lastFailureAt = Date.now();
+  state.lastError = err?.message || String(err);
+  const now = Date.now();
+  state.failureTimes = state.failureTimes.filter((t) => now - t < CIRCUIT_WINDOW_MS);
+  state.failureTimes.push(now);
+  if (
+    state.circuitOpenedAt === 0 &&
+    state.failureTimes.length >= CIRCUIT_FAIL_THRESHOLD
+  ) {
+    state.circuitOpenedAt = now;
+    log("warn", "circuit.opened", { failures: state.failureTimes.length, windowMs: CIRCUIT_WINDOW_MS });
+  }
+}
+
+// Returns true if the breaker permits a request right now. If the
+// breaker is open but the cooldown has elapsed, returns true once
+// (half-open probe); the caller must call recordSuccess or
+// recordFailure to close or re-open the circuit.
+export function circuitPermits() {
+  if (state.circuitOpenedAt === 0) return true;
+  const now = Date.now();
+  const openFor = now - state.circuitOpenedAt;
+  if (openFor < CIRCUIT_COOLDOWN_MS) return false;
+  if (state.halfOpenProbe) return false;
+  state.halfOpenProbe = "in-flight";
+  log("info", "circuit.half_open", { openForMs: openFor });
+  return true;
+}
+
+export function circuitStatus() {
+  if (state.circuitOpenedAt === 0) return "closed";
+  const openFor = Date.now() - state.circuitOpenedAt;
+  if (openFor < CIRCUIT_COOLDOWN_MS) return "open";
+  return "half_open";
+}
+
+// Compute the backoff delay before the next attempt. attempt is
+// 0-indexed: 0 means the first retry, etc.
+export function backoffMs(attempt) {
+  const exp = Math.min(DEFAULT_MAX_MS, DEFAULT_BASE_MS * 2 ** attempt);
+  // Full jitter: random in [0, exp].
+  return Math.floor(Math.random() * exp);
+}
+
+export function isRetryableStatus(status) {
+  return RETRYABLE_STATUS.has(status);
+}
+
+export const retryConfig = {
+  maxRetries: DEFAULT_MAX_RETRIES,
+  baseMs: DEFAULT_BASE_MS,
+  maxMs: DEFAULT_MAX_MS,
+};
+
+export function metrics() {
+  return {
+    requests: state.requests,
+    successes: state.successes,
+    failures: state.failures,
+    retries: state.retries,
+    lastError: state.lastError,
+    lastSuccessAt: state.lastSuccessAt,
+    lastFailureAt: state.lastFailureAt,
+    circuit: circuitStatus(),
+    circuitFailuresInWindow: state.failureTimes.length,
+  };
+}
+
+// Wrap an async function with retry + circuit breaker semantics.
+// fn() must throw an Error with .status attached when the response
+// is a retryable HTTP error. onRetry(attempt, delayMs, err) is
+// called before sleeping between attempts.
+export async function withResilience(label, fn, { onRetry, signal } = {}) {
+  if (!circuitPermits()) {
+    const err = new Error(`circuit open: ${label}`);
+    err.status = 503;
+    err.code = "circuit_open";
+    throw err;
+  }
+  let lastErr;
+  for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+    if (signal?.aborted) {
+      const e = new Error("aborted");
+      e.code = "aborted";
+      throw e;
+    }
+    try {
+      const result = await fn(attempt);
+      recordSuccess();
+      return result;
+    } catch (err) {
+      lastErr = err;
+      const status = err?.status;
+      const retryable = isRetryableStatus(status) || err?.code === "fetch_failed";
+      if (!retryable || attempt === retryConfig.maxRetries) {
+        recordFailure(err);
+        throw err;
+      }
+      state.retries += 1;
+      const delay = backoffMs(attempt);
+      if (onRetry) onRetry(attempt, delay, err);
+      log("warn", "retry", { label, attempt: attempt + 1, status, delayMs: delay, err: err?.message });
+      if (signal) {
+        await new Promise((resolve, reject) => {
+          const t = setTimeout(resolve, delay);
+          signal.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(Object.assign(new Error("aborted"), { code: "aborted" }));
+          }, { once: true });
+        });
+      } else {
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  recordFailure(lastErr);
+  throw lastErr;
+}
+
+function log(level, msg, extra) {
+  try {
+    const line = JSON.stringify({ t: new Date().toISOString(), level, msg, ...(extra || {}) });
+    appendFileSync(process.env.CODEX_BRIDGE_LOG || "/tmp/codex-bridge.log", line + "\n");
+  } catch {
+    // best-effort logging; never throw from the resilience layer
+  }
+}

package/lib/server.mjs

@@ -1,29 +1,25 @@
 #!/usr/bin/env node
 // codex-bridge: OpenAI-compatible HTTP server that talks to ChatGPT
-// Business/Team/Plus via the OpenAI Responses API directly. We do NOT
-// shell out to `codex exec` because the CLI rejects Plus/Business
-// models when invoked with `-m <slug>` and the auth path is simpler to
-// reproduce here.
+// Business/Team/Plus via the OpenAI Responses API directly.
 //
 // Endpoints:
-//   GET  /v1/models            -> { object:"list", data:[...] }
-//   POST /v1/chat/completions  -> OpenAI-style streaming or JSON response
-//   GET  /v1/tools             -> list registered MCP tools
-//   POST /v1/tools             -> register a list of tools
-//   DELETE /v1/tools           -> clear registry
+//   GET  /v1/health           -> { ok, ...metrics }
+//   GET  /v1/models           -> { object:"list", data:[...] }
+//   POST /v1/chat/completions -> OpenAI-style streaming or JSON response
+//   GET  /v1/tools            -> list registered MCP tools
+//   POST /v1/tools            -> register a list of tools
+//   DELETE /v1/tools          -> clear registry
 //
-// Auth: reads ~/.codex/auth.json, refreshes access_token via the OAuth
-// refresh_token grant at https://auth.openai.com/oauth/token when
-// expired.
-//
-// Transport: POST https://chatgpt.com/backend-api/codex/responses with
-// Bearer <access_token> and the OpenAI Responses API body shape. We
-// translate Chat Completions <-> Responses for the OpenCode client.
+// Auth lives in lib/auth.mjs. Upstream resilience (retry, circuit
+// breaker, metrics) lives in lib/resilience.mjs. Boot-time capability
+// probing lives in lib/capabilities.mjs.
 
 import http from "node:http";
-import { readFileSync, existsSync, writeFileSync, appendFileSync } from "node:fs";
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+
+import { getAuth, refreshAccessToken } from "./auth.mjs";
 import {
   registerTool,
   registerTools,
@@ -31,15 +27,17 @@ import {
   clearTools,
   renderToolsSystemBlock,
 } from "./tools-registry.mjs";
+import {
+  withResilience,
+  metrics as resilienceMetrics,
+} from "./resilience.mjs";
+import { probeCapabilities } from "./capabilities.mjs";
 
 const PORT = Number(process.env.PORT || 11434);
 const HOST = process.env.HOST || "127.0.0.1";
 const CODEX_HOME = process.env.CODEX_HOME || join(homedir(), ".codex");
-const AUTH_PATH = join(CODEX_HOME, "auth.json");
 const MODELS_CACHE = join(CODEX_HOME, "models_cache.json");
 const CHATGPT_BASE = "https://chatgpt.com/backend-api/codex";
-const OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
-const OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"; // public client id used by codex CLI
 const LOG_PATH = process.env.CODEX_BRIDGE_LOG || "/tmp/codex-bridge.log";
 
 function log(level, msg, extra) {
@@ -50,72 +48,6 @@ function log(level, msg, extra) {
   }
 }
 
-// ---- auth ----
-let _authCache = null;
-let _authLoadedAt = 0;
-const AUTH_TTL_MS = 30_000; // re-read the file every 30s
-
-function loadAuth() {
-  if (!existsSync(AUTH_PATH)) {
-    throw new Error(`auth.json not found at ${AUTH_PATH}; run \`codex login\` first`);
-  }
-  if (_authCache && Date.now() - _authLoadedAt < AUTH_TTL_MS) return _authCache;
-  const raw = readFileSync(AUTH_PATH, "utf8");
-  const parsed = JSON.parse(raw);
-  if (parsed.auth_mode !== "chatgpt") {
-    throw new Error(`auth.json auth_mode=${parsed.auth_mode}; only chatgpt supported`);
-  }
-  _authCache = parsed.tokens;
-  _authLoadedAt = Date.now();
-  return _authCache;
-}
-
-async function refreshAccessToken(refreshToken) {
-  const body = new URLSearchParams({
-    grant_type: "refresh_token",
-    refresh_token: refreshToken,
-    client_id: OAUTH_CLIENT_ID,
-    scope: "openid profile email offline-access",
-  });
-  const res = await fetch(OAUTH_TOKEN_URL, {
-    method: "POST",
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    body: body.toString(),
-  });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`oauth refresh failed ${res.status}: ${text.slice(0, 300)}`);
-  }
-  const json = await res.json();
-  const updated = {
-    ..._authCache,
-    access_token: json.access_token,
-    refresh_token: json.refresh_token || _authCache.refresh_token,
-    id_token: json.id_token || _authCache.id_token,
-  };
-  // Persist back to auth.json so subsequent runs pick it up.
-  try {
-    const raw = readFileSync(AUTH_PATH, "utf8");
-    const file = JSON.parse(raw);
-    file.tokens = updated;
-    writeFileSync(AUTH_PATH, JSON.stringify(file, null, 2));
-  } catch (e) {
-    log("warn", "could not persist refreshed tokens", { err: String(e) });
-  }
-  _authCache = updated;
-  return updated;
-}
-
-async function getAuth() {
-  const a = loadAuth();
-  // We don't track expiry precisely; the access_token works until the API
-  // returns 401. Refresh preemptively if the token is missing.
-  if (!a.access_token && a.refresh_token) {
-    return refreshAccessToken(a.refresh_token);
-  }
-  return a;
-}
-
 // ---- models ----
 function listModels() {
   if (!existsSync(MODELS_CACHE)) {
@@ -136,17 +68,6 @@ function listModels() {
 }
 
 // ---- OpenAI Chat Completions <-> Responses API translation ----
-//
-// Responses API uses a different shape:
-//   input: [{ type: "message", role, content: [{ type: "input_text", text }] }, ...]
-//   tools: [{ type: "function", name, description, parameters, strict: false }]
-//   output is a list of items:
-//     { type: "message", role: "assistant", content: [{ type: "output_text", text }] }
-//     { type: "function_call", call_id, name, arguments }
-//   To feed tool results back, send input items of type
-//     { type: "function_call_output", call_id, output }
-//
-// We translate from Chat Completions on the way in and back on the way out.
 
 function chatToolsToResponsesTools(tools) {
   if (!Array.isArray(tools) || tools.length === 0) return undefined;
@@ -166,8 +87,6 @@ function chatToolsToResponsesTools(tools) {
 }
 
 function chatMessagesToResponsesInput(messages) {
-  // Chat Completions role types we care about: system, user, assistant, tool, developer.
-  // Responses: instructions (system), input (list of message + function_call + function_call_output).
   let instructions = "";
   const input = [];
   for (const m of messages) {
@@ -184,8 +103,6 @@ function chatMessagesToResponsesInput(messages) {
       continue;
     }
     if (role === "assistant") {
-      // If the assistant produced tool_calls, emit them as function_call items so
-      // the next function_call_output can match.
       if (Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
         for (const tc of m.tool_calls) {
           const name = tc.function?.name || tc.name;
@@ -262,47 +179,57 @@ async function callResponses({ model, instructions, input, tools, signal }) {
   if (tools && tools.length > 0) body.tools = tools;
 
   const headers = {
-    "authorization": `Bearer ${auth.access_token}`,
+    authorization: `Bearer ${auth.access_token}`,
     "content-type": "application/json",
-    "accept": "text/event-stream",
+    accept: "text/event-stream",
     "OpenAI-Beta": "responses=experimental",
     "chatgpt-account-id": auth.account_id || "",
   };
 
-  log("info", "responses.request", { model, instructionsLen: (instructions || "").length, inputItems: input.length, tools: (tools || []).length });
-
-  const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal });
-  if (res.status === 401 && auth.refresh_token) {
-    log("info", "responses.401 refreshing token");
-    const refreshed = await refreshAccessToken(auth.refresh_token);
-    headers.authorization = `Bearer ${refreshed.access_token}`;
-    const retry = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal });
-    if (!retry.ok) {
-      const text = await retry.text();
-      throw new Error(`chatgpt ${retry.status}: ${text.slice(0, 400)}`);
+  log("info", "responses.request", {
+    model,
+    instructionsLen: (instructions || "").length,
+    inputItems: input.length,
+    tools: (tools || []).length,
+  });
+
+  const doFetch = async () => {
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal });
+    } catch (e) {
+      const err = new Error(`fetch failed: ${e?.message || e}`);
+      err.code = "fetch_failed";
+      err.status = 0;
+      throw err;
     }
-    return retry;
-  }
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`chatgpt ${res.status}: ${text.slice(0, 400)}`);
-  }
-  return res;
+    if (res.status === 401 && auth.refresh_token) {
+      log("info", "responses.401 refreshing token");
+      const refreshed = await refreshAccessToken(auth.refresh_token);
+      headers.authorization = `Bearer ${refreshed.access_token}`;
+      res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal });
+    }
+    if (!res.ok) {
+      const text = await res.text();
+      const err = new Error(`chatgpt ${res.status}: ${text.slice(0, 400)}`);
+      err.status = res.status;
+      throw err;
+    }
+    return res;
+  };
+
+  return withResilience("responses", doFetch, { signal });
 }
 
-// Parse SSE stream from Responses API. We accumulate:
-//   - text deltas -> final text
-//   - function_call items -> tool calls
-//   - usage at response.completed
-// Returns { text, toolCalls, usage, raw } where toolCalls is OpenAI shape.
+// Parse SSE stream from Responses API.
 async function readSse(res) {
   const reader = res.body.getReader();
   const decoder = new TextDecoder("utf8");
   let buf = "";
   let text = "";
-  const toolCalls = new Map(); // call_id -> { id, name, arguments }
+  const toolCalls = new Map();
   let usage = null;
-  let currentItem = null; // { type, id?, call_id?, name?, content_index?, delta? }
+  let currentItem = null;
 
   function ensureCall(id, name) {
     if (!toolCalls.has(id)) toolCalls.set(id, { id, name: name || "", arguments: "" });
@@ -317,7 +244,6 @@ async function readSse(res) {
     while ((idx = buf.indexOf("\n\n")) !== -1) {
       const block = buf.slice(0, idx);
       buf = buf.slice(idx + 2);
-      // Parse "event:" and "data:" lines.
       let event = "";
       let data = "";
       for (const line of block.split("\n")) {
@@ -361,7 +287,6 @@ async function readSse(res) {
         case "response.completed": {
           const r = json.response || {};
           if (r.usage) usage = r.usage;
-          // Synthesize text from output if we missed deltas.
           if (!text && Array.isArray(r.output)) {
             for (const item of r.output) {
               if (item.type === "message") {
@@ -388,6 +313,14 @@ const server = http.createServer(async (req, res) => {
     if (req.method === "GET" && url.pathname === "/healthz") {
       return json(res, 200, { ok: true, port: PORT });
     }
+    if (req.method === "GET" && url.pathname === "/v1/health") {
+      return json(res, 200, {
+        ok: true,
+        port: PORT,
+        uptime: process.uptime(),
+        ...resilienceMetrics(),
+      });
+    }
     if (req.method === "GET" && url.pathname === "/v1/models") {
       return json(res, 200, listModels());
     }
@@ -469,9 +402,6 @@ async function handleChatCompletions(payload, req, res) {
   const ac = new AbortController();
   req.on("close", () => ac.abort());
 
-  // Build the Responses API input. If no `tools` came in, we still inject
-  // a Plus-style system block describing the registered tools so the model
-  // can call them.
   const responsesTools = chatToolsToResponsesTools(tools);
   let { instructions, input } = chatMessagesToResponsesInput(messages);
   if (!(responsesTools && responsesTools.length > 0)) {
@@ -483,10 +413,6 @@ async function handleChatCompletions(payload, req, res) {
 
   log("info", "chat.completions", { model, stream, msgs: messages.length, toolCount: (tools || []).length });
 
-  // Single call. We do NOT loop in this implementation: when the model
-  // emits tool_calls, we return finish_reason=tool_calls to OpenCode.
-  // OpenCode will run the tools, send role:"tool" messages back, and the
-  // bridge makes a fresh request that includes those items.
   let result;
   try {
     const upstream = await callResponses({
@@ -498,7 +424,17 @@ async function handleChatCompletions(payload, req, res) {
     });
     result = await readSse(upstream);
   } catch (e) {
-    return json(res, 502, { error: { message: String(e.message || e), type: "upstream_error" } });
+    const status = e?.status || 502;
+    const body = {
+      error: {
+        message: String(e.message || e),
+        type: e?.code || "upstream_error",
+      },
+    };
+    if (status === 503 && e?.code === "circuit_open") {
+      return json(res, 503, { ...body, error: { ...body.error, message: "bridge: circuit open, upstream unavailable" } });
+    }
+    return json(res, status === 401 ? 502 : status, body);
   }
 
   const id = genId("chatcmpl");
@@ -551,7 +487,6 @@ async function handleChatCompletions(payload, req, res) {
       choices: [{ index: 0, delta: {}, finish_reason: finishReason }],
     });
     sse(res, null, { id, object: "chat.completion.chunk", created, model, choices: [], usage });
-    // The "[DONE]" sentinel is the literal string, not a JSON-encoded one.
     res.write("data: [DONE]\n\n");
     return res.end();
   }
@@ -563,10 +498,21 @@ async function handleChatCompletions(payload, req, res) {
   });
 }
 
-server.listen(PORT, HOST, () => {
-  log("info", "listening", { url: `http://${HOST}:${PORT}`, codex_home: CODEX_HOME });
-  process.stderr.write(`codex-bridge listening on http://${HOST}:${PORT}\n`);
-});
+// ---- boot ----
+async function boot() {
+  try {
+    const caps = await probeCapabilities({ log: (level, msg, extra) => log(level, msg, extra) });
+    log("info", "capabilities", { ok: caps.ok, resolvedModel: caps.resolvedModel, events: caps.events, latencyMs: caps.latencyMs });
+  } catch (e) {
+    log("warn", "probe failed; starting anyway", { err: String(e) });
+  }
+  server.listen(PORT, HOST, () => {
+    log("info", "listening", { url: `http://${HOST}:${PORT}`, codex_home: CODEX_HOME });
+    process.stderr.write(`codex-bridge listening on http://${HOST}:${PORT}\n`);
+  });
+}
 
 process.on("SIGTERM", () => server.close(() => process.exit(0)));
 process.on("SIGINT", () => server.close(() => process.exit(0)));
+
+boot();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaralabs/codex-bridge",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": false,
   "description": "OpenAI-compatible HTTP bridge that reuses a local ChatGPT Business / Team / Plus session via codex, so OpenCode can list and call those models without paying for the OpenAI API.",
   "type": "module",
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "start": "bin/codex-bridge start",
@@ -33,7 +33,9 @@
     "sync": "bin/codex-bridge sync",
     "logs": "bin/codex-bridge logs",
     "test": "node test/test.mjs",
-    "test:tools": "node test/test-tools.mjs"
+    "test:tools": "node test/test-tools.mjs",
+    "test:resilience": "node test/test-resilience.mjs",
+    "test:smoke": "node test/smoke.mjs"
   },
   "repository": {
     "type": "git",