Skip to content

Latest commit

 

History

History
242 lines (191 loc) · 14.3 KB

README.md

File metadata and controls

242 lines (191 loc) · 14.3 KB

NVIDIA NeMo Fabric Codex Adapter

The nvidia.fabric.codex adapter uses the official Codex Python SDK behind NeMo Fabric's normalized invocation contract. It does not resolve or execute a separately installed codex command. The SDK package owns its pinned app-server runtime and typed JSON-RPC protocol.

Install

The following table shows which components each installation provides:

Installation Runtime Adapter Harness NeMo Relay CLI
pip install "nemo-fabric[codex]" Yes Yes Yes Yes
pip install "nemo-fabric-adapters-codex[harness]" No Yes Yes Yes
pip install nemo-fabric-adapters-codex No Yes No No

For an environment-managed SDK, use openai-codex==0.154.0. For split runtime and adapter environments, configure ADAPTER_PYTHON and use matching NeMo Fabric release versions. Refer to the installation guide.

The full extra is equivalent to harness. Both install the supported NeMo Relay CLI so Relay telemetry and Runtime.invoke_stream() work without a separate CLI installation.

Authentication

For a cached ChatGPT or Codex API-key login, NeMo Fabric reuses the authentication state under CODEX_HOME (default: ~/.codex). Sign in with Codex before running NeMo Fabric. Set CODEX_HOME to the same location for login and execution if you use a nondefault credential store.

For noninteractive OpenAI API-key authentication, set models.<role>.api_key_env to the name of an environment variable containing the key. The adapter calls the Codex SDK's login_api_key during startup. It creates a private, temporary CODEX_HOME outside Fabric artifacts for this login, even if the host has another CODEX_HOME, and removes it after the runtime stops or startup fails. This mode uses OpenAI Platform billing rather than ChatGPT plan credits.

Treat any Codex CODEX_HOME/auth.json as a secret when Codex uses file-based credential storage. Do not copy it into NeMo Fabric configuration or artifacts. Refer to the Codex authentication documentation for login and credential-storage options.

The native openai provider retains Codex authentication and endpoint discovery. For another provider name, configure both models.<role>.api_key_env and models.<role>.base_url. The endpoint must implement the OpenAI Responses protocol. The adapter defines a runtime-scoped Codex model provider with that name and isolates its Codex state under the NeMo Fabric artifact root, so execution does not depend on or modify a user's Codex login. Provider names identify configuration; the adapter does not maintain a provider allowlist.

The adapter uses the Codex SDK, which installs and selects its matching app-server runtime. NeMo Fabric does not declare the runtime package directly or treat it as a user-installed command or adapter descriptor requirement.

A codex command on PATH is not selected implicitly.

Execution Model

Each NeMo Fabric runtime currently starts one local adapter host and retains one AsyncCodex client and one Codex thread. The Codex starts and controls its pinned local codex app-server subprocess over JSON-RPC. Ordered Runtime.invoke(...) calls reuse that client and thread directly; the adapter closes the SDK client and app-server transport during Runtime.stop(). Codex owns the transcript; NeMo Fabric owns runtime-to-thread correlation, timeout, cancellation, and cleanup.

The result includes the SDK's typed terminal response, turn status, token usage, timing, and completed thread items. It does not expose CLI commands, return codes, stdout, or stderr.

Normalized usage contains invocation-local token counts from the SDK's cumulative thread totals, including cached input tokens. Input tokens already include cached tokens (input_tokens_include_cache=True). Reused threads report the difference from the previous invocation rather than counting the thread total again. Missing, invalid, or reset counters remain unknown; a missing snapshot requires a new baseline before differences can be reported. The adapter preserves native usage in output.usage, does not infer cost, and retains available usage on unsuccessful results. If the SDK raises before returning usage, normalized usage remains unavailable.

Runtime Health

Use Fabric.check(environment=..., request=...) with a runtime ID and live, active, or ready. Checks run during an invocation and report busy or idle for NeMo Fabric activity.

  • live checks whether the owned Codex app-server process has exited.
  • active reads the selected native thread through the app-server request interface and confirms the thread is loaded.
  • ready uses the same fresh native response as a readiness equivalent: the initialized thread must report idle or active. Native systemError fails readiness; notLoaded reports a closed session.

Each check uses the caller's deadline. A pending native health request remains the only request in flight after a caller timeout. Later checks wait within their own deadlines, then obtain a fresh response after the pending request completes.

Run the credential-free native qualification with uv run --no-sync pytest tests/e2e/test_codex_checks.py -q. The tests use the SDK-pinned app-server and a local mock provider before, during, and after an invocation.

Refer to the SDK health-check overview for shared behavior and a comparison of native evidence across adapters.

Configuration

Use normalized FabricConfig fields for portable configuration:

  • models selects the Codex model. The native openai provider retains Codex authentication and endpoint discovery. Any other provider name must configure a Responses-compatible base_url and api_key_env.
  • instructions.system supports replace and maps to Codex base instructions. Codex rejects append during planning and direct adapter startup.
  • runtime.timeout_seconds sets the NeMo Fabric invocation deadline.
  • environment.workspace sets the working directory, and environment.env supplies explicit harness-visible variables.
  • mcp maps stdio, HTTP, and streamable HTTP servers into the Codex thread's mcp_servers configuration. For stdio, set url to the executable and pass each command-line argument as a separate args element.
  • Codex starts the configured MCP servers itself when the runtime starts and leaves out the tools of a server that fails; the runtime starts with the tools of the remaining servers. Every result from that runtime reports the servers whose latest Codex startup status is failed under output.mcp.unavailable_servers (name, transport, and reason of failed, or authentication_required when Codex reports that stored OAuth credentials need reauthentication), and the adapter writes a warning to standard error. Codex error messages are omitted because they can carry credentials. A server that is still starting is not reported, and a new runtime starts every server again. Invalid server configuration, such as an unsupported transport or authentication mode, still fails startup.
  • skills.paths names skill directories that contain SKILL.md. The adapter registers each directory as a process-scoped Codex skill root so Codex can select matching skills through its normal discovery behavior.
  • telemetry enables native OpenTelemetry or NeMo Relay observability.

Invocation deadlines return the normalized error code timeout, including when the deadline expires during MCP authentication; a Codex SDK request that times out earlier returns codex_timed_out. The adapter interrupts the active turn and closes the SDK before returning either outcome. With a timeout under 10 seconds, NeMo Fabric's own timeout can stop the adapter host before the interrupt finishes, which fails the invocation with a core host_timeout error instead.

The Codex adapter does not declare tools.blocked support. The current Codex runtime has per-MCP-server tool filters, but it does not provide one complete deny boundary for built-in, local, MCP, and hosted tools. NeMo Fabric therefore routes normalized blocked-tool policy as unsupported instead of applying a partial policy.

Only Codex-specific controls belong in harness.settings:

Setting Type Required Static Default
sandbox One of read-only, workspace-write, or danger-full-access No read-only
approval_mode One of auto_review or deny_all No auto_review
developer_instructions Nonempty string No No default
personality One of none, friendly, or pragmatic No No default
reasoning_effort One of none, minimal, low, medium, high, xhigh, max, or ultra No No default
service_tier Nonempty string No No default
output_schema JSON Schema object for the final assistant message No No default
config_overrides Object that maps nonempty dotted Codex configuration keys to JSON-compatible values No {}

ultra uses Codex's model-specific effort selection. Codex resolves it to a supported provider effort; models without effort metadata fall back to medium.

Planning validates these settings against the schema in the resolved Codex descriptor. Unknown keys, empty dotted-key segments, invalid types, and invalid enum values fail before the adapter starts. Schema defaults are documentation only; planning preserves the supplied settings without adding defaults. config_overrides is the intentional adapter-specific escape hatch for Codex configuration that has no normalized NeMo Fabric field.

Set model selection and endpoints through models, system instructions through instructions.system, the invocation deadline through runtime.timeout_seconds, and the working directory and explicit environment through environment. In particular, the SDK's base_instructions value comes from instructions.system, not harness.settings.

For Fabric.start_runtime(...), the model provider, MCP configuration, skill roots, and config_overrides are fixed when the runtime starts and cannot vary between Runtime.invoke(...) calls. Start a new runtime to change them. Fabric.run(...) starts the same runtime, invokes it once, and stops it.

The adapter filters the inherited environment. It retains portable OS and Codex state variables, the selected model's api_key_env, explicit environment.env values, and variables named by environment.env_names while clearing unrelated parent-process secrets.

Relay Integration

Relay requires a NeMo Relay CLI in the >=0.9,<0.12 range on PATH. The Codex adapter does not provide a separate relay extra; its harness and full extras install the compatible CLI through nemo-relay-cli-bin. The root nemo-fabric[relay] extra installs only the Relay Python package.

NeMo Fabric wraps Codex PreToolUse checks so Relay launch errors, timeouts, and nonzero exits return exit code 2 with a blocking reason. This includes the exit code 1 used by Relay 0.9.x and 0.10.0. The wrapper allows 35 seconds for Relay, within the harness timeout of 45 seconds. Codex 0.154.0 can still continue if the wrapper itself fails to start or reaches the harness timeout.

Enable Relay with FabricConfig.enable_relay(...). The adapter starts the installed nemo-relay CLI as a supervised sidecar; do not start the gateway separately. The 30-second readiness wait starts after gateway launch and covers required worker initialization. The Relay CLI check and plugin configuration writing happen before launch and are outside this wait. Startup fails on early process exit or an expired budget, and the gateway log is retained for diagnosis. NeMo Fabric routes the selected Responses-compatible provider through the gateway and passes its explicit base_url to Relay as the upstream endpoint.

Credential-free HTTP model gateways

For Relay-enabled runs, NeMo Relay CLI 0.11.x supports explicit trust for HTTP model hosts. Set harness.settings.insecure_http_model_hosts to the exact hostnames or IP addresses of your private inference gateways:

config.harness.settings["insecure_http_model_hosts"] = ["inference.internal", "10.0.0.10"]

Entries contain no scheme, port, path, or wildcard. Matching ignores DNS case and a trailing dot, permits any port or path on that host, and does not infer trust from DNS resolution. The adapter passes this list to Relay's runtime [upstream] configuration. An explicit empty list clears inherited HTTP trust; omitting the setting preserves Relay's existing configuration behavior. System Relay configuration takes precedence and can enforce an empty list.

This path is for unauthenticated model endpoints: Relay strips authorization, API-key, cookie, and other credential headers before remote HTTP forwarding, including model credentials supplied to the harness. Relay rejects conflicting upstream authorization configuration. Prompts and responses still travel over plaintext HTTP. HTTPS remains the default. This setting affects Relay-enabled Codex, Claude, and Pi model forwarding; MCP policy is unchanged. Older Relay CLIs reject the setting with an upgrade message.

Testing

Run the unit and opt-in real SDK tests separately:

uv run pytest tests/adapters/test_codex_adapter.py -q
RUN_FABRIC_CODEX_INTEGRATION=1 uv run pytest tests/e2e/test_codex.py -q
RUN_FABRIC_CODEX_RELAY_INTEGRATION=1 \
  FABRIC_TEST_NEMO_RELAY_COMMAND=/path/to/nemo-relay \
  uv run pytest tests/e2e/test_codex.py -q

Set FABRIC_TEST_CODEX_BIN=/path/to/codex on either opt-in command to validate an explicit app-server override instead of the SDK-pinned runtime.

The SDK test uses the current Codex authentication state and exercises both the single-invocation convenience API and multiple turns against one started runtime. The Relay test additionally requires an external gateway binary and verifies model responses, stable thread identity across turns, Agent Trajectory Observability Format (ATOF), and Agent Trajectory Interchange Format (ATIF); gateway startup alone is not a passing result. The semantic regression requires the LLM request content to be decoded. It also requires ATIF to contain the model, token usage, and expected agent response.