feat: introduce npm module for codex-responses-api-proxy (#4417)

This PR expands `.github/workflows/rust-release.yml` so that it also
builds and publishes the `npm` module for
`@openai/codex-responses-api-proxy` in addition to `@openai/codex`. Note
both `npm` modules are similar, in that they each contain a single `.js`
file that is a thin launcher around the appropriate native executable.
(Since we have a minimal dependency on Node.js, I also lowered the
minimum version from 20 to 16 and verified that works on my machine.)

As part of this change, we tighten up some of the docs around
`codex-responses-api-proxy` and ensure the details regarding protecting
the `OPENAI_API_KEY` in memory match the implementation.

To test the `npm` build process, I ran:

```
./codex-cli/scripts/build_npm_package.py --package codex-responses-api-proxy --version 0.43.0-alpha.3
```

which stages the `npm` module for `@openai/codex-responses-api-proxy` in
a temp directory, using the binary artifacts from
https://github.com/openai/codex/releases/tag/rust-v0.43.0-alpha.3.

Author: bolinfest

.github/workflows/rust-release.yml

@@ -218,17 +218,30 @@ jobs:
 
       # build_npm_package.py requires DotSlash when staging releases.
       - uses: facebook/install-dotslash@v2
-      - name: Stage npm package
+      - name: Stage codex CLI npm package
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
           TMP_DIR="${RUNNER_TEMP}/npm-stage"
           ./codex-cli/scripts/build_npm_package.py \
+            --package codex \
             --release-version "${{ steps.release_name.outputs.name }}" \
             --staging-dir "${TMP_DIR}" \
             --pack-output "${GITHUB_WORKSPACE}/dist/npm/codex-npm-${{ steps.release_name.outputs.name }}.tgz"
 
+      - name: Stage responses API proxy npm package
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          TMP_DIR="${RUNNER_TEMP}/npm-stage-responses"
+          ./codex-cli/scripts/build_npm_package.py \
+            --package codex-responses-api-proxy \
+            --release-version "${{ steps.release_name.outputs.name }}" \
+            --staging-dir "${TMP_DIR}" \
+            --pack-output "${GITHUB_WORKSPACE}/dist/npm/codex-responses-api-proxy-npm-${{ steps.release_name.outputs.name }}.tgz"
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -271,7 +284,7 @@ jobs:
       - name: Update npm
         run: npm install -g npm@latest
 
-      - name: Download npm tarball from release
+      - name: Download npm tarballs from release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -283,6 +296,10 @@ jobs:
             --repo "${GITHUB_REPOSITORY}" \
             --pattern "codex-npm-${version}.tgz" \
             --dir dist/npm
+          gh release download "$tag" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --pattern "codex-responses-api-proxy-npm-${version}.tgz" \
+            --dir dist/npm
 
       # No NODE_AUTH_TOKEN needed because we use OIDC.
       - name: Publish to npm
@@ -296,7 +313,14 @@ jobs:
             tag_args+=(--tag "${NPM_TAG}")
           fi
 
-          npm publish "${GITHUB_WORKSPACE}/dist/npm/codex-npm-${VERSION}.tgz" "${tag_args[@]}"
+          tarballs=(
+            "codex-npm-${VERSION}.tgz"
+            "codex-responses-api-proxy-npm-${VERSION}.tgz"
+          )
+
+          for tarball in "${tarballs[@]}"; do
+            npm publish "${GITHUB_WORKSPACE}/dist/npm/${tarball}" "${tag_args[@]}"
+          done
 
   update-branch:
     name: Update latest-alpha-cli branch

codex-cli/README.md

@@ -208,7 +208,7 @@ The hardening mechanism Codex uses depends on your OS:
 | Requirement                 | Details                                                         |
 | --------------------------- | --------------------------------------------------------------- |
 | Operating systems           | macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 **via WSL2** |
-| Node.js                     | **22 or newer** (LTS recommended)                               |
+| Node.js                     | **16 or newer** (Node 20 LTS recommended)                       |
 | Git (optional, recommended) | 2.23+ for built-in PR helpers                                   |
 | RAM                         | 4-GB minimum (8-GB recommended)                                 |
 
@@ -513,7 +513,7 @@ Codex runs model-generated commands in a sandbox. If a proposed command or file
 <details>
 <summary>Does it work on Windows?</summary>
 
-Not directly. It requires [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) - Codex has been tested on macOS and Linux with Node 22.
+Not directly. It requires [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) - Codex is regularly tested on macOS and Linux with Node 20+, and also supports Node 16.
 
 </details>
 

codex-cli/bin/codex.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Unified entry point for the Codex CLI.
 
+import { spawn } from "node:child_process";
 import { existsSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -68,7 +69,6 @@ const binaryPath = path.join(archRoot, "codex", codexBinaryName);
 // executing. This allows us to forward those signals to the child process
 // and guarantees that when either the child terminates or the parent
 // receives a fatal signal, both processes exit in a predictable manner.
-const { spawn } = await import("child_process");
 
 function getUpdatedPath(newDirs) {
   const pathSep = process.platform === "win32" ? ";" : ":";

codex-cli/package-lock.json

@@ -7,7 +7,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=16"
   },
   "files": [
     "bin",

codex-cli/package.json

@@ -13,6 +13,7 @@
 SCRIPT_DIR = Path(__file__).resolve().parent
 CODEX_CLI_ROOT = SCRIPT_DIR.parent
 REPO_ROOT = CODEX_CLI_ROOT.parent
+RESPONSES_API_PROXY_NPM_ROOT = REPO_ROOT / "codex-rs" / "responses-api-proxy" / "npm"
 GITHUB_REPO = "openai/codex"
 
 # The docs are not clear on what the expected value/format of
@@ -23,6 +24,12 @@
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Build or stage the Codex CLI npm package.")
+    parser.add_argument(
+        "--package",
+        choices=("codex", "codex-responses-api-proxy"),
+        default="codex",
+        help="Which npm package to stage (default: codex).",
+    )
     parser.add_argument(
         "--version",
         help="Version number to write to package.json inside the staged package.",
@@ -63,6 +70,7 @@ def parse_args() -> argparse.Namespace:
 def main() -> int:
     args = parse_args()
 
+    package = args.package
     version = args.version
     release_version = args.release_version
     if release_version:
@@ -76,7 +84,7 @@ def main() -> int:
     staging_dir, created_temp = prepare_staging_dir(args.staging_dir)
 
     try:
-        stage_sources(staging_dir, version)
+        stage_sources(staging_dir, version, package)
 
         workflow_url = args.workflow_url
         resolved_head_sha: str | None = None
@@ -100,16 +108,23 @@ def main() -> int:
         if not workflow_url:
             raise RuntimeError("Unable to determine workflow URL for native binaries.")
 
-        install_native_binaries(staging_dir, workflow_url)
+        install_native_binaries(staging_dir, workflow_url, package)
 
         if release_version:
             staging_dir_str = str(staging_dir)
-            print(
-                f"Staged version {version} for release in {staging_dir_str}\n\n"
-                "Verify the CLI:\n"
-                f"    node {staging_dir_str}/bin/codex.js --version\n"
-                f"    node {staging_dir_str}/bin/codex.js --help\n\n"
-            )
+            if package == "codex":
+                print(
+                    f"Staged version {version} for release in {staging_dir_str}\n\n"
+                    "Verify the CLI:\n"
+                    f"    node {staging_dir_str}/bin/codex.js --version\n"
+                    f"    node {staging_dir_str}/bin/codex.js --help\n\n"
+                )
+            else:
+                print(
+                    f"Staged version {version} for release in {staging_dir_str}\n\n"
+                    "Verify the responses API proxy:\n"
+                    f"    node {staging_dir_str}/bin/codex-responses-api-proxy.js --help\n\n"
+                )
         else:
             print(f"Staged package in {staging_dir}")
 
@@ -136,20 +151,34 @@ def prepare_staging_dir(staging_dir: Path | None) -> tuple[Path, bool]:
     return temp_dir, True
 
 
-def stage_sources(staging_dir: Path, version: str) -> None:
+def stage_sources(staging_dir: Path, version: str, package: str) -> None:
     bin_dir = staging_dir / "bin"
     bin_dir.mkdir(parents=True, exist_ok=True)
 
-    shutil.copy2(CODEX_CLI_ROOT / "bin" / "codex.js", bin_dir / "codex.js")
-    rg_manifest = CODEX_CLI_ROOT / "bin" / "rg"
-    if rg_manifest.exists():
-        shutil.copy2(rg_manifest, bin_dir / "rg")
+    if package == "codex":
+        shutil.copy2(CODEX_CLI_ROOT / "bin" / "codex.js", bin_dir / "codex.js")
+        rg_manifest = CODEX_CLI_ROOT / "bin" / "rg"
+        if rg_manifest.exists():
+            shutil.copy2(rg_manifest, bin_dir / "rg")
+
+        readme_src = REPO_ROOT / "README.md"
+        if readme_src.exists():
+            shutil.copy2(readme_src, staging_dir / "README.md")
 
-    readme_src = REPO_ROOT / "README.md"
-    if readme_src.exists():
-        shutil.copy2(readme_src, staging_dir / "README.md")
+        package_json_path = CODEX_CLI_ROOT / "package.json"
+    elif package == "codex-responses-api-proxy":
+        launcher_src = RESPONSES_API_PROXY_NPM_ROOT / "bin" / "codex-responses-api-proxy.js"
+        shutil.copy2(launcher_src, bin_dir / "codex-responses-api-proxy.js")
 
-    with open(CODEX_CLI_ROOT / "package.json", "r", encoding="utf-8") as fh:
+        readme_src = RESPONSES_API_PROXY_NPM_ROOT / "README.md"
+        if readme_src.exists():
+            shutil.copy2(readme_src, staging_dir / "README.md")
+
+        package_json_path = RESPONSES_API_PROXY_NPM_ROOT / "package.json"
+    else:
+        raise RuntimeError(f"Unknown package '{package}'.")
+
+    with open(package_json_path, "r", encoding="utf-8") as fh:
         package_json = json.load(fh)
     package_json["version"] = version
 
@@ -158,8 +187,20 @@ def stage_sources(staging_dir: Path, version: str) -> None:
         out.write("\n")
 
 
-def install_native_binaries(staging_dir: Path, workflow_url: str) -> None:
-    cmd = ["./scripts/install_native_deps.py", "--workflow-url", workflow_url, str(staging_dir)]
+def install_native_binaries(staging_dir: Path, workflow_url: str, package: str) -> None:
+    package_components = {
+        "codex": ["codex", "rg"],
+        "codex-responses-api-proxy": ["codex-responses-api-proxy"],
+    }
+
+    components = package_components.get(package)
+    if components is None:
+        raise RuntimeError(f"Unknown package '{package}'.")
+
+    cmd = ["./scripts/install_native_deps.py", "--workflow-url", workflow_url]
+    for component in components:
+        cmd.extend(["--component", component])
+    cmd.append(str(staging_dir))
     subprocess.check_call(cmd, cwd=CODEX_CLI_ROOT)