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.
2025-09-28 19:34:06 -07:00
parent a9d54b9e92
commit 618a42adf5
13 changed files with 387 additions and 64 deletions
--- a/codex-cli/README.md
+++ b/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>

--- a/codex-cli/bin/codex.js
+++ b/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" ? ";" : ":";
--- a/codex-cli/package-lock.json
+++ b/codex-cli/package-lock.json
@@ -11,7 +11,7 @@
        "codex": "bin/codex.js"
      },
      "engines": {
-        "node": ">=20"
+        "node": ">=16"
      }
    }
  }
--- a/codex-cli/package.json
+++ b/codex-cli/package.json
@@ -7,7 +7,7 @@
  },
  "type": "module",
  "engines": {
-    "node": ">=20"
+    "node": ">=16"
  },
  "files": [
    "bin",
--- a/codex-cli/scripts/build_npm_package.py
+++ b/codex-cli/scripts/build_npm_package.py
@@ -13,6 +13,7 @@ from pathlib import Path
 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 @@ WORKFLOW_NAME = ".github/workflows/rust-release.yml"

 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")

-    with open(CODEX_CLI_ROOT / "package.json", "r", encoding="utf-8") as fh:
+        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")
+
+        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)


--- a/codex-cli/scripts/install_native_deps.py
+++ b/codex-cli/scripts/install_native_deps.py
@@ -9,6 +9,7 @@ import subprocess
 import tarfile
 import tempfile
 import zipfile
+from dataclasses import dataclass
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from typing import Iterable, Sequence
@@ -20,7 +21,7 @@ CODEX_CLI_ROOT = SCRIPT_DIR.parent
 DEFAULT_WORKFLOW_URL = "https://github.com/openai/codex/actions/runs/17952349351"  # rust-v0.40.0
 VENDOR_DIR_NAME = "vendor"
 RG_MANIFEST = CODEX_CLI_ROOT / "bin" / "rg"
-CODEX_TARGETS = (
+BINARY_TARGETS = (
    "x86_64-unknown-linux-musl",
    "aarch64-unknown-linux-musl",
    "x86_64-apple-darwin",
@@ -29,6 +30,27 @@ CODEX_TARGETS = (
    "aarch64-pc-windows-msvc",
 )

+
+@dataclass(frozen=True)
+class BinaryComponent:
+    artifact_prefix: str  # matches the artifact filename prefix (e.g. codex-<target>.zst)
+    dest_dir: str  # directory under vendor/<target>/ where the binary is installed
+    binary_basename: str  # executable name inside dest_dir (before optional .exe)
+
+
+BINARY_COMPONENTS = {
+    "codex": BinaryComponent(
+        artifact_prefix="codex",
+        dest_dir="codex",
+        binary_basename="codex",
+    ),
+    "codex-responses-api-proxy": BinaryComponent(
+        artifact_prefix="codex-responses-api-proxy",
+        dest_dir="codex-responses-api-proxy",
+        binary_basename="codex-responses-api-proxy",
+    ),
+}
+
 RG_TARGET_PLATFORM_PAIRS: list[tuple[str, str]] = [
    ("x86_64-unknown-linux-musl", "linux-x86_64"),
    ("aarch64-unknown-linux-musl", "linux-aarch64"),
@@ -50,6 +72,16 @@ def parse_args() -> argparse.Namespace:
            "known good run when omitted."
        ),
    )
+    parser.add_argument(
+        "--component",
+        dest="components",
+        action="append",
+        choices=tuple(list(BINARY_COMPONENTS) + ["rg"]),
+        help=(
+            "Limit installation to the specified components."
+            " May be repeated. Defaults to 'codex' and 'rg'."
+        ),
+    )
    parser.add_argument(
        "root",
        nargs="?",
@@ -69,18 +101,28 @@ def main() -> int:
    vendor_dir = codex_cli_root / VENDOR_DIR_NAME
    vendor_dir.mkdir(parents=True, exist_ok=True)

+    components = args.components or ["codex", "rg"]
+
    workflow_url = (args.workflow_url or DEFAULT_WORKFLOW_URL).strip()
    if not workflow_url:
        workflow_url = DEFAULT_WORKFLOW_URL

    workflow_id = workflow_url.rstrip("/").split("/")[-1]
+    print(f"Downloading native artifacts from workflow {workflow_id}...")

    with tempfile.TemporaryDirectory(prefix="codex-native-artifacts-") as artifacts_dir_str:
        artifacts_dir = Path(artifacts_dir_str)
        _download_artifacts(workflow_id, artifacts_dir)
-        install_codex_binaries(artifacts_dir, vendor_dir, CODEX_TARGETS)
+        install_binary_components(
+            artifacts_dir,
+            vendor_dir,
+            BINARY_TARGETS,
+            [name for name in components if name in BINARY_COMPONENTS],
+        )

-    fetch_rg(vendor_dir, DEFAULT_RG_TARGETS, manifest_path=RG_MANIFEST)
+    if "rg" in components:
+        print("Fetching ripgrep binaries...")
+        fetch_rg(vendor_dir, DEFAULT_RG_TARGETS, manifest_path=RG_MANIFEST)

    print(f"Installed native dependencies into {vendor_dir}")
    return 0
@@ -124,6 +166,8 @@ def fetch_rg(
    results: dict[str, Path] = {}
    max_workers = min(len(task_configs), max(1, (os.cpu_count() or 1)))

+    print("Installing ripgrep binaries for targets: " + ", ".join(targets))
+
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        future_map = {
            executor.submit(
@@ -140,6 +184,7 @@ def fetch_rg(
        for future in as_completed(future_map):
            target = future_map[future]
            results[target] = future.result()
+            print(f"  installed ripgrep for {target}")

    return [results[target] for target in targets]

@@ -158,40 +203,60 @@ def _download_artifacts(workflow_id: str, dest_dir: Path) -> None:
    subprocess.check_call(cmd)


-def install_codex_binaries(
-    artifacts_dir: Path, vendor_dir: Path, targets: Iterable[str]
-) -> list[Path]:
+def install_binary_components(
+    artifacts_dir: Path,
+    vendor_dir: Path,
+    targets: Iterable[str],
+    component_names: Sequence[str],
+) -> None:
+    selected_components = [BINARY_COMPONENTS[name] for name in component_names if name in BINARY_COMPONENTS]
+    if not selected_components:
+        return
+
    targets = list(targets)
    if not targets:
-        return []
+        return

-    results: dict[str, Path] = {}
-    max_workers = min(len(targets), max(1, (os.cpu_count() or 1)))
-
-    with ThreadPoolExecutor(max_workers=max_workers) as executor:
-        future_map = {
-            executor.submit(_install_single_codex_binary, artifacts_dir, vendor_dir, target): target
-            for target in targets
-        }
-
-        for future in as_completed(future_map):
-            target = future_map[future]
-            results[target] = future.result()
-
-    return [results[target] for target in targets]
+    for component in selected_components:
+        print(
+            f"Installing {component.binary_basename} binaries for targets: "
+            + ", ".join(targets)
+        )
+        max_workers = min(len(targets), max(1, (os.cpu_count() or 1)))
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {
+                executor.submit(
+                    _install_single_binary,
+                    artifacts_dir,
+                    vendor_dir,
+                    target,
+                    component,
+                ): target
+                for target in targets
+            }
+            for future in as_completed(futures):
+                installed_path = future.result()
+                print(f"  installed {installed_path}")


-def _install_single_codex_binary(artifacts_dir: Path, vendor_dir: Path, target: str) -> Path:
+def _install_single_binary(
+    artifacts_dir: Path,
+    vendor_dir: Path,
+    target: str,
+    component: BinaryComponent,
+) -> Path:
    artifact_subdir = artifacts_dir / target
-    archive_name = _archive_name_for_target(target)
+    archive_name = _archive_name_for_target(component.artifact_prefix, target)
    archive_path = artifact_subdir / archive_name
    if not archive_path.exists():
        raise FileNotFoundError(f"Expected artifact not found: {archive_path}")

-    dest_dir = vendor_dir / target / "codex"
+    dest_dir = vendor_dir / target / component.dest_dir
    dest_dir.mkdir(parents=True, exist_ok=True)

-    binary_name = "codex.exe" if "windows" in target else "codex"
+    binary_name = (
+        f"{component.binary_basename}.exe" if "windows" in target else component.binary_basename
+    )
    dest = dest_dir / binary_name
    dest.unlink(missing_ok=True)
    extract_archive(archive_path, "zst", None, dest)
@@ -200,10 +265,10 @@ def _install_single_codex_binary(artifacts_dir: Path, vendor_dir: Path, target:
    return dest


-def _archive_name_for_target(target: str) -> str:
+def _archive_name_for_target(artifact_prefix: str, target: str) -> str:
    if "windows" in target:
-        return f"codex-{target}.exe.zst"
-    return f"codex-{target}.zst"
+        return f"{artifact_prefix}-{target}.exe.zst"
+    return f"{artifact_prefix}-{target}.zst"


 def _fetch_single_rg(