@christiandoxa/prodex 0.189.0 → 0.191.0

package/README.md

@@ -41,6 +41,9 @@ If you only use one Codex account and do not need quota rotation, you probably d
 
 You need at least one logged-in Prodex profile.
 
+<details>
+<summary>Tool requirements</summary>
+
 | Tool | Used by |
 |---|---|
 | Codex CLI | `prodex`, `prodex run`, `prodex caveman`, `prodex super` |
@@ -48,6 +51,8 @@ You need at least one logged-in Prodex profile.
 | Claude-Mem | `mem` variants |
 | RTK | `rtk` variants and `prodex s` / `prodex super` |
 
+</details>
+
 ## Supported providers
 
 Prodex supports two provider paths:
@@ -55,6 +60,9 @@ Prodex supports two provider paths:
 - **Profile-backed routing**: persisted profiles that Prodex can select, rotate, and inspect where provider APIs allow it.
 - **Runtime provider launch**: `prodex s gemini`, `prodex s deepseek`, or `prodex s --provider ...` starts Codex with a temporary provider bridge for that session.
 
+<details>
+<summary>Supported provider matrix</summary>
+
 | Provider | Launch to Codex | Auth path | Quota view | Notes |
 |---|---:|---|---:|---|
 | OpenAI / Codex | `prodex`, `prodex run`, `prodex s` | ChatGPT OAuth, device code, or OpenAI/API-compatible key via `prodex login` | Yes | Full quota preflight and profile auto-rotation. |
@@ -65,8 +73,13 @@ Prodex supports two provider paths:
 | Local OpenAI-compatible | `prodex super --url http://127.0.0.1:8131` | Local server auth/config | Health snapshot | `prodex quota --all --provider local --base-url ...` checks the local `/models` endpoint. |
 | Bedrock / custom Codex `model_provider` | `prodex run` / `prodex caveman` direct pass-through | Codex-owned config | Config snapshot | Prodex reports configured provider metadata; provider-side quota stays owned by Codex/upstream. |
 
+</details>
+
 `prodex gateway` exposes the provider bridge as a standalone OpenAI-compatible service for non-Codex clients:
 
+<details>
+<summary>Gateway quickstart</summary>
+
 ```bash
 PRODEX_GATEWAY_TOKEN=change-me GEMINI_API_KEY=... prodex gateway --provider gemini
 auth_header="Authorization: Bearer $PRODEX_GATEWAY_TOKEN"
@@ -76,7 +89,16 @@ curl http://127.0.0.1:4000/v1/responses \
   -d '{"model":"prodex-fast","input":"hello"}'
 ```
 
-The gateway serves `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/images/*`, `/v1/audio/*`, `/v1/batches`, `/v1/rerank`, `/v1/a2a`, `/v1/messages`, and `/v1/models` where the selected upstream supports them. It adds `x-prodex-call-id` to responses, writes local request detail plus `gateway_spend` events to runtime logs, can export those events to JSONL or HTTP using generic, OTel, Datadog, or Langfuse-shaped payloads, supports policy-defined routing strategies (`fallback`, `round-robin`, `least-busy`, `lowest-cost`, `lowest-latency`, `rpm`, `tpm`, `first`) for model aliases/fallback chains, and can apply keyword/model, Presidio, and external webhook guardrails before calls and on outputs. Configure defaults under `[gateway]` in `policy.toml`.
+</details>
+
+<details>
+<summary>Gateway capabilities</summary>
+
+The gateway serves `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/images/*`, `/v1/audio/*`, `/v1/batches`, `/v1/rerank`, `/v1/a2a`, `/v1/messages`, and `/v1/models` where the selected upstream supports them. It adds `x-prodex-call-id` to responses, writes local request detail plus `gateway_spend` events for both `request` and `response` phases to runtime logs, can export those events to JSONL or HTTP using generic, OTel, Datadog, or Langfuse-shaped payloads, supports catalog-backed policy routing strategies (`fallback`, `round-robin`, `least-busy`, `lowest-cost`, `lowest-latency`, `rpm`, `tpm`, `first`) for model aliases/fallback chains, can enforce static virtual keys with persisted request/spend usage plus model/budget/RPM/TPM limits, supports file, SQLite, Postgres, or Redis-backed gateway admin/usage/ledger/SCIM state, and can apply keyword/model, local PII redaction, Presidio, and external webhook guardrails before calls and on outputs. Admin-token, trusted-proxy SSO, or OIDC/JWT bearer requests can list usage, create generated-token keys, rotate/disable/update/delete admin-managed keys, provision SSO users through SCIM-compatible `/v1/prodex/gateway/scim/v2/Users`, inspect usage at `/v1/prodex/gateway/keys` and `/v1/prodex/gateway/usage`, read recent billing ledger records with response-status/output-token reconciliation at `/v1/prodex/gateway/ledger`, read aggregated billing totals at `/v1/prodex/gateway/ledger/summary`, export billing CSV from `/v1/prodex/gateway/ledger.csv` and `/v1/prodex/gateway/ledger/summary.csv`, scrape Prometheus text metrics at `/v1/prodex/gateway/metrics`, inspect provider adapter contracts at `/v1/prodex/gateway/providers`, inspect active observability and guardrail configuration at `/v1/prodex/gateway/observability` and `/v1/prodex/gateway/guardrails`, fetch the machine-readable gateway contract at `/v1/prodex/gateway/openapi.json`, and open the built-in gateway admin dashboard at `/v1/prodex/gateway/admin`; policy/env-backed keys remain read-only, SCIM users can carry tenant/team/project/user/budget scopes for SSO/OIDC fallback, admin-managed key and SCIM user mutations are recorded in `prodex audit`, and additional admin-plane tokens can be `admin` or read-only `viewer` with optional virtual-key prefix plus tenant/team/project/user/budget scopes. Configure defaults under `[gateway]` in `policy.toml`; validate provider catalog edits with `npm run catalog:providers`.
+
+JavaScript clients can use `@christiandoxa/prodex-gateway-sdk` for `/v1/responses` plus gateway key, usage, billing ledger, metrics, and OpenAPI admin calls.
+
+</details>
 
 <details>
 <summary>Provider behavior details</summary>
@@ -105,6 +127,8 @@ Runtime proxy design contract:
 npm install -g @christiandoxa/prodex
 ```
 
+The npm package uses its bundled `@openai/codex@latest` dependency by default. To deliberately use a separate Codex CLI from your machine, set `PRODEX_CODEX_BIN=/path/to/codex` or `PRODEX_CODEX_RESOLUTION=external`.
+
 </details>
 
 <details>
@@ -1056,6 +1080,7 @@ Contributor testing guidance lives in [docs/testing.md](./docs/testing.md), incl
 - [LOCAL.md](./LOCAL.md) — self-hosted local model setup and testing
 - [docs/state-model.md](./docs/state-model.md) — state ownership and persistence model
 - [docs/runtime-policy.md](./docs/runtime-policy.md) — runtime policy keys, environment overrides, and runtime log path resolution
+- [docs/deployment.md](./docs/deployment.md) — Docker Compose scaffold for the standalone gateway
 - [docs/testing.md](./docs/testing.md) — contributor testing guidance
 
 ## Support

package/lib/codex-shim.cjs

@@ -47,41 +47,81 @@ const PLATFORM_TARGETS = {
   },
 };
 
-function resolveCodexBin() {
+function currentPlatformTarget() {
+  return PLATFORM_TARGETS[process.platform]?.[process.arch] ?? null;
+}
+
+function resolveOpenAiCodexPackageRoot() {
   let packageJsonPath;
   try {
     packageJsonPath = requireFromHere.resolve("@openai/codex/package.json");
+  } catch {
+    return null;
+  }
+  return path.dirname(packageJsonPath);
+}
+
+function codexManagedEnv() {
+  const packageRoot = resolveOpenAiCodexPackageRoot();
+  if (!packageRoot) {
+    return process.env;
+  }
+  return {
+    ...process.env,
+    CODEX_MANAGED_BY_NPM: "1",
+    CODEX_MANAGED_PACKAGE_ROOT: fs.realpathSync(packageRoot),
+  };
+}
+
+function ensureNativeCodexExecutable(nativeBinaryPath) {
+  try {
+    fs.accessSync(nativeBinaryPath, fs.constants.X_OK);
+    return;
+  } catch {
+    repairNativeCodexExecutablePermissionBestEffort(nativeBinaryPath);
+  }
+
+  try {
+    fs.accessSync(nativeBinaryPath, fs.constants.X_OK);
+    return;
   } catch {
     process.stderr.write(
-      "Unable to locate @openai/codex. Reinstall @christiandoxa/prodex so its runtime dependency is present.\n",
+      [
+        `Bundled Codex native binary is not executable: ${nativeBinaryPath}`,
+        "Reinstall @christiandoxa/prodex with optional dependencies enabled, or set PRODEX_CODEX_BIN to an existing Codex CLI.",
+        "",
+      ].join("\n"),
     );
-    process.exit(1);
+    process.exit(126);
   }
+}
 
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-  if (typeof packageJson.bin === "string") {
-    return path.resolve(path.dirname(packageJsonPath), packageJson.bin);
+function repairNativeCodexExecutablePermissionBestEffort(nativeBinaryPath) {
+  if (process.platform === "win32") {
+    return;
   }
-  if (packageJson.bin && typeof packageJson.bin === "object") {
-    const candidate = packageJson.bin.codex ?? Object.values(packageJson.bin)[0];
-    if (typeof candidate === "string") {
-      return path.resolve(path.dirname(packageJsonPath), candidate);
+  try {
+    const stats = fs.statSync(nativeBinaryPath);
+    if (!stats.isFile()) {
+      return;
     }
+    fs.chmodSync(nativeBinaryPath, (stats.mode & 0o777) | 0o755);
+  } catch {
+    // The explicit executable check below reports the actionable failure.
   }
-  return path.resolve(path.dirname(packageJsonPath), "bin", "codex.js");
 }
 
-function explainBundledNativeCodexPermissionIssue() {
-  const platformTarget = PLATFORM_TARGETS[process.platform]?.[process.arch];
-  if (!platformTarget || process.platform === "win32") {
-    return;
+function resolveNativeCodexCommand() {
+  const platformTarget = currentPlatformTarget();
+  if (!platformTarget) {
+    return null;
   }
 
   let platformPackageJsonPath;
   try {
     platformPackageJsonPath = requireFromHere.resolve(`${platformTarget.packageName}/package.json`);
   } catch {
-    return;
+    return null;
   }
 
   const nativeBinaryPath = path.join(
@@ -92,26 +132,66 @@ function explainBundledNativeCodexPermissionIssue() {
     platformTarget.binaryFileName,
   );
   if (!fs.existsSync(nativeBinaryPath)) {
-    return;
-  }
-  try {
-    fs.accessSync(nativeBinaryPath, fs.constants.X_OK);
-  } catch {
     process.stderr.write(
       [
-        `Bundled Codex native binary is not executable: ${nativeBinaryPath}`,
+        `Missing bundled Codex native binary at ${nativeBinaryPath}`,
         "Reinstall @christiandoxa/prodex with optional dependencies enabled, or set PRODEX_CODEX_BIN to an existing Codex CLI.",
         "",
       ].join("\n"),
     );
-    process.exit(126);
+    process.exit(1);
+  }
+  ensureNativeCodexExecutable(nativeBinaryPath);
+
+  return {
+    command: nativeBinaryPath,
+    args: process.argv.slice(2),
+    env: codexManagedEnv(),
+  };
+}
+
+function resolveCodexJsCommand() {
+  const packageRoot = resolveOpenAiCodexPackageRoot();
+  if (!packageRoot) {
+    process.stderr.write(
+      "Unable to locate @openai/codex. Reinstall @christiandoxa/prodex so its runtime dependency is present.\n",
+    );
+    process.exit(1);
+  }
+  const packageJsonPath = path.join(packageRoot, "package.json");
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  if (typeof packageJson.bin === "string") {
+    return {
+      command: process.execPath,
+      args: [path.resolve(packageRoot, packageJson.bin), ...process.argv.slice(2)],
+      env: process.env,
+    };
+  }
+  if (packageJson.bin && typeof packageJson.bin === "object") {
+    const candidate = packageJson.bin.codex ?? Object.values(packageJson.bin)[0];
+    if (typeof candidate === "string") {
+      return {
+        command: process.execPath,
+        args: [path.resolve(packageRoot, candidate), ...process.argv.slice(2)],
+        env: process.env,
+      };
+    }
   }
+  return {
+    command: process.execPath,
+    args: [path.resolve(packageRoot, "bin", "codex.js"), ...process.argv.slice(2)],
+    env: process.env,
+  };
+}
+
+function resolveCodexCommand() {
+  return resolveNativeCodexCommand() ?? resolveCodexJsCommand();
 }
 
-const codexBin = resolveCodexBin();
-explainBundledNativeCodexPermissionIssue();
-const child = spawn(process.execPath, [codexBin, ...process.argv.slice(2)], {
-  env: process.env,
+const codexCommand = resolveCodexCommand();
+const child = spawn(codexCommand.command, codexCommand.args, {
+  env: codexCommand.env,
   stdio: "inherit",
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christiandoxa/prodex",
-  "version": "0.189.0",
+  "version": "0.191.0",
   "description": "Safe multi-account auto-rotate for Codex CLI with isolated CODEX_HOME profiles",
   "license": "Apache-2.0",
   "bin": {
@@ -16,12 +16,18 @@
     "@openai/codex": "latest"
   },
   "optionalDependencies": {
-    "@christiandoxa/prodex-linux-x64": "0.189.0",
-    "@christiandoxa/prodex-linux-arm64": "0.189.0",
-    "@christiandoxa/prodex-darwin-x64": "0.189.0",
-    "@christiandoxa/prodex-darwin-arm64": "0.189.0",
-    "@christiandoxa/prodex-win32-x64": "0.189.0",
-    "@christiandoxa/prodex-win32-arm64": "0.189.0"
+    "@christiandoxa/prodex-linux-x64": "0.191.0",
+    "@christiandoxa/prodex-linux-arm64": "0.191.0",
+    "@christiandoxa/prodex-darwin-x64": "0.191.0",
+    "@christiandoxa/prodex-darwin-arm64": "0.191.0",
+    "@christiandoxa/prodex-win32-x64": "0.191.0",
+    "@christiandoxa/prodex-win32-arm64": "0.191.0",
+    "@openai/codex-linux-x64": "npm:@openai/codex@linux-x64",
+    "@openai/codex-linux-arm64": "npm:@openai/codex@linux-arm64",
+    "@openai/codex-darwin-x64": "npm:@openai/codex@darwin-x64",
+    "@openai/codex-darwin-arm64": "npm:@openai/codex@darwin-arm64",
+    "@openai/codex-win32-x64": "npm:@openai/codex@win32-x64",
+    "@openai/codex-win32-arm64": "npm:@openai/codex@win32-arm64"
   },
   "engines": {
     "node": ">=18"

package/prodex

@@ -97,7 +97,25 @@ function resolveExternalCodexBin() {
   if (process.env.PRODEX_CODEX_BIN) {
     return process.env.PRODEX_CODEX_BIN;
   }
-  return resolveCommandFromPath("codex", process.env.PATH || "");
+  const resolution = (process.env.PRODEX_CODEX_RESOLUTION || "bundled").toLowerCase();
+  if (resolution === "bundled") {
+    return null;
+  }
+  if (resolution !== "external") {
+    process.stderr.write(
+      `Unsupported PRODEX_CODEX_RESOLUTION=${JSON.stringify(process.env.PRODEX_CODEX_RESOLUTION)}; expected "bundled" or "external".\n`,
+    );
+    process.exit(1);
+  }
+
+  const externalCodex = resolveCommandFromPath("codex", process.env.PATH || "");
+  if (!externalCodex) {
+    process.stderr.write(
+      "PRODEX_CODEX_RESOLUTION=external was set, but no executable codex was found on PATH.\n",
+    );
+    process.exit(1);
+  }
+  return externalCodex;
 }
 
 if (!platformPackage) {