246 lines
14 KiB
Markdown
246 lines
14 KiB
Markdown
# Route drivers
|
||
|
||
Codex MMO is model-maker neutral, but protocols and access products are not interchangeable. In MMO generation 8, an executable `route` selects one driver and records its API operator, access product, wire protocol, billing mode, transport capabilities, credential names, and resource group.
|
||
|
||
The filename remains `PROVIDER_DRIVERS.md` for documentation organization only; the public catalog object is `routes`, not the old provider-shaped schema.
|
||
|
||
## Driver matrix
|
||
|
||
| Driver | Execution path | Typical use | Managed gateway |
|
||
|---|---|---|:---:|
|
||
| `codex_builtin` | Codex reserved provider | ChatGPT-backed Codex models | no |
|
||
| `codex_custom` | Direct Codex Responses endpoint | Conforming private/third-party Responses API | no |
|
||
| `codex_oss` | Codex native local integration | Ollama or LM Studio | no |
|
||
| `switchyard` | Immutable snapshot-specific route | Chat, Responses, Anthropic Messages, compatible local APIs | yes |
|
||
| `catalog_only` | Metadata only | Media/service endpoint or unsupported transport | no execution |
|
||
|
||
## Common route identity
|
||
|
||
```toml
|
||
[routes.example_openai_chat]
|
||
name = "Example API"
|
||
api_operator = "example"
|
||
access_product = "example_api"
|
||
wire_protocol = "openai_chat"
|
||
billing_mode = "api"
|
||
driver = "switchyard"
|
||
base_url = "https://models.example.test/v1"
|
||
credential_envs = ["EXAMPLE_API_KEY"]
|
||
resource_group = "example_pool"
|
||
transport_modalities = ["text"]
|
||
transport_output_modalities = ["text"]
|
||
tool_calling = true
|
||
parallel_tool_calls = false
|
||
max_retries = 1
|
||
```
|
||
|
||
Required identity fields are never inferred from a route key. A recognized field that does not apply to the selected driver is rejected instead of retained inertly.
|
||
|
||
## `codex_builtin`
|
||
|
||
```toml
|
||
[routes.codex_chatgpt_builtin]
|
||
name = "Built-in Codex with ChatGPT authentication"
|
||
api_operator = "openai"
|
||
access_product = "chatgpt_codex"
|
||
wire_protocol = "codex_builtin"
|
||
billing_mode = "chatgpt_subscription"
|
||
driver = "codex_builtin"
|
||
provider_id = "openai"
|
||
auth = "chatgpt"
|
||
resource_group = "chatgpt_subscription"
|
||
transport_modalities = ["text", "image"]
|
||
tool_calling = true
|
||
parallel_tool_calls = true
|
||
```
|
||
|
||
This preserves Codex’s native authentication, entitlement, tools, images, and active model catalog. A generated home uses the configured base home’s file-backed `auth.json` according to `auth_link_mode`; Codex 0.149 keyring-only state cannot be transferred to another `CODEX_HOME`.
|
||
|
||
Account-visible models and capabilities remain authoritative. The bundled catalog is a release baseline, not an entitlement claim.
|
||
|
||
## `codex_custom`
|
||
|
||
```toml
|
||
[routes.private_responses]
|
||
name = "Private Responses"
|
||
api_operator = "example"
|
||
access_product = "private_responses"
|
||
wire_protocol = "openai_responses"
|
||
billing_mode = "api"
|
||
driver = "codex_custom"
|
||
base_url = "https://llm.example.internal/v1"
|
||
wire_api = "responses"
|
||
credential_envs = ["PRIVATE_LLM_API_KEY"]
|
||
transport_modalities = ["text", "image"]
|
||
preserves_tool_media = true
|
||
tool_result_modalities = ["text", "image"]
|
||
|
||
[routes.private_responses.http_headers]
|
||
"X-Static-Tenant" = "engineering"
|
||
|
||
[routes.private_responses.env_http_headers]
|
||
"X-Private-Token" = "PRIVATE_HEADER_VALUE"
|
||
```
|
||
|
||
Use direct mode only when the endpoint faithfully implements Responses and direct transport is preferable to translation. The Codex process necessarily receives declared credential/header variables, so place sensitive work in a suitable OS boundary.
|
||
|
||
`wire_api` is currently `responses`. Direct retry fields are `request_max_retries`, `stream_max_retries`, and `stream_idle_timeout_ms`. Codex interprets zero as immediate expiry, not “disabled,” so route validation rejects it. Generated homes raise the effective idle floor to at least one hour and twice the role's warning-only stall interval. That value detects a genuinely broken stream; it is not a task deadline, goal budget, or instruction for the model to keep time.
|
||
|
||
## `codex_oss`
|
||
|
||
```toml
|
||
[routes.ollama_codex_oss]
|
||
name = "Codex native Ollama OSS mode"
|
||
api_operator = "local"
|
||
access_product = "ollama"
|
||
wire_protocol = "codex_oss"
|
||
billing_mode = "local"
|
||
driver = "codex_oss"
|
||
provider_id = "ollama"
|
||
resource_group = "local_gpu_0"
|
||
transport_modalities = ["text"]
|
||
```
|
||
|
||
Supported `provider_id` values are `ollama` and `lmstudio`. Switchyard variants also exist for compatible local Chat endpoints when common routing and telemetry matter more than native transport.
|
||
|
||
## `switchyard`
|
||
|
||
Switchyard 0.2.0 supports these route protocols:
|
||
|
||
- `openai_chat`;
|
||
- `openai_responses`;
|
||
- `anthropic_messages`.
|
||
|
||
The compiler emits only routes used by one immutable snapshot. A profile with no Switchyard binding starts no gateway. Managed ingress is restricted to a loopback IP literal because the generated gateway has no client-auth layer.
|
||
|
||
Bundled Switchyard routes include:
|
||
|
||
- OpenCode Go Chat, Responses, and Anthropic Messages through `OPENCODE_API_KEY`;
|
||
- OpenCode Zen Chat, Responses, and Anthropic Messages through the same `OPENCODE_API_KEY`;
|
||
- OpenRouter Chat through `OPENROUTER_API_KEY`;
|
||
- Z.AI Coding Plan Chat and Responses through `ZAI_CODING_API_KEY`;
|
||
- Z.AI General API through the separately explicit `ZAI_API_KEY`;
|
||
- a bundled llama.cpp model binding;
|
||
- direct OpenAI/Anthropic and LM Studio/Ollama route definitions for explicit
|
||
user catalog extensions. A route without a model record is not an executable
|
||
bundled model binding.
|
||
|
||
Switchyard receives `extra_headers`, not environment-backed per-header mappings. API authentication uses `credential_envs`. MMO emits `max_retries = 1` by default, meaning one additional attempt; the accepted range is 0–10.
|
||
|
||
### Temporary Codex MCP namespace bridge
|
||
|
||
Codex 0.149 represents MCP servers as Responses `namespace` tools. Switchyard 0.2.0's Responses decoder retains top-level function and ID tools but does not retain that namespace shape. For a gateway whose recorded executable version is exactly `0.2.0`, MMO therefore asks the same Codex app-server for its granted MCP tool schemas, registers equivalent flat `mmo_mcp__SERVER__TOOL` dynamic functions when a thread is first created, and routes each dynamic call back through Codex's `mcpServer/tool/call`. The MMO-owned prefix is deliberate because Codex rejects dynamic declarations using its reserved native `mcp__` prefix. Codex remains the MCP connection owner and enforces its configured server/tool allowlists; the bridge does not read supervisor files or connect to MCP servers independently. MCP text, image, audio, error state, and non-redundant structured content are preserved; a structured value is omitted only when an existing text block parses to that exact value (including the common single-key result wrapper), avoiding duplicate context without discarding distinct information. Durable Codex threads retain the dynamic tool declarations, while every replacement host reconstructs only the in-memory routing map.
|
||
|
||
This is a release-scoped compatibility shim, not a second permanent MCP architecture. It is disabled for every Switchyard version other than `0.2.0`. The baseline/bridge guard test deliberately fails when the reviewed Switchyard baseline changes. Before accepting a newer baseline:
|
||
|
||
1. prove with the exact candidate binary that Codex 0.149 namespace tools reach both the Go and Zen model routes and that a real MCP call completes;
|
||
2. prove new-thread, resumed-thread, worker, allowlist, error, and cancellation behavior without `dynamicTools`;
|
||
3. remove the bridge constants, dynamic schema discovery/call routing, root/worker injection, and their compatibility tests;
|
||
4. update this section, the architecture/veracity records, changelog, package manifest, and installed runtime.
|
||
|
||
An operator-supplied newer Switchyard is never assigned the 0.2.0 shim merely because the profile uses the `switchyard` driver. Its native namespace path must pass live qualification before production use.
|
||
|
||
#### Open removal tracker
|
||
|
||
Upstream [Switchyard PR #384](https://github.com/NVIDIA-NeMo/Switchyard/pull/384), merged as commit [`c7beccd4891fa5cfe3a3b94fdd376f5765864507`](https://github.com/NVIDIA-NeMo/Switchyard/commit/c7beccd4891fa5cfe3a3b94fdd376f5765864507) on 2026-08-20, implements native Codex namespace preservation. The current `v0.2.0` tag predates that commit, and no published tag contains it as of 2026-08-23. This tracker remains open until the first official `switchyard-server` release whose tag contains that commit is available.
|
||
|
||
The release containing that commit is an upgrade/removal trigger, not permission to retain both paths. The baseline bump must be one atomic change: run the qualification matrix above against the exact released binary, delete the dynamic bridge and its version constant, then update the pin. The existing `test_temporary_switchyard_bridge_must_be_removed_when_baseline_advances` test blocks a baseline-only update. If native qualification fails, keep `0.2.0` pinned and record the failure; do not extend the bridge to the newer release.
|
||
|
||
Z.AI Coding Plan uses distinct documented bases by wire protocol: Responses/Codex uses `https://api.z.ai/api/v1`, while OpenAI-compatible Chat uses `https://api.z.ai/api/coding/paas/v4`. Switchyard appends the protocol endpoint suffix. MMO does not retry one route through the other and does not fall back to the separately credentialed General API.
|
||
|
||
The Coding Plan Anthropic-compatible endpoint remains catalog-only: its documented Bearer authentication cannot be represented by Switchyard 0.2.0’s fixed Anthropic `x-api-key` behavior. No hidden transport fallback is attempted.
|
||
|
||
## `catalog_only`
|
||
|
||
Catalog-only records preserve complete inventory information without pretending the endpoint can run a Codex agent. Examples include OCR, image/video generation, audio transcription, hosted application agents, Google-native Zen models without an installed driver, and the incompatible Coding Plan Anthropic route.
|
||
|
||
```toml
|
||
[routes.zai_general_catalog]
|
||
name = "Z.AI media and specialist API catalog"
|
||
api_operator = "zai"
|
||
access_product = "zai_general_api"
|
||
wire_protocol = "catalog_only"
|
||
billing_mode = "catalog_only"
|
||
driver = "catalog_only"
|
||
transport_modalities = ["text", "image", "video", "audio", "file"]
|
||
|
||
[models.zai_general_catalog__glm_image]
|
||
maker = "zai"
|
||
route = "zai_general_catalog"
|
||
upstream_id = "glm-image"
|
||
kind = "image_generation"
|
||
agent_compatible = false
|
||
```
|
||
|
||
## Driver-specific fields
|
||
|
||
| Field | Drivers | Meaning |
|
||
|---|---|---|
|
||
| `api_operator` | all | API operator identity |
|
||
| `access_product` | all | Plan/service identity |
|
||
| `wire_protocol` | all | Exact protocol enum |
|
||
| `billing_mode` | all | `api`, `subscription`, `chatgpt_subscription`, `local`, or `catalog_only` |
|
||
| `provider_id` | built-in/OSS | Codex-owned provider identifier |
|
||
| `base_url` | custom/Switchyard/catalog-only | Absolute HTTP(S) API root |
|
||
| `credential_envs` | custom/Switchyard/catalog-only | Ordered valid environment names |
|
||
| `wire_api` | custom | Direct Codex API; `responses` |
|
||
| `http_headers` | custom | Static Codex headers |
|
||
| `env_http_headers` | custom | Header name to environment name |
|
||
| `extra_headers` | Switchyard | Static Switchyard headers |
|
||
| `max_retries` | Switchyard | Additional attempts, 0–10 |
|
||
| `request_max_retries` | custom | Direct request retries |
|
||
| `stream_max_retries` | custom | Stream reconnections |
|
||
| `stream_idle_timeout_ms` | custom | Provider stream-idle floor (at least 1,000 ms); generated app-server configs raise it through the role's execution window plus finalization grace when that is longer |
|
||
| `transport_modalities` | all | Inputs the complete path preserves |
|
||
| `transport_output_modalities` | all | Outputs the complete path preserves |
|
||
| `preserves_tool_media` | all | Whether tool media survives transport |
|
||
| `tool_result_modalities` | all | Preserved tool-result media types |
|
||
| `supports_documents` | all | Complete file/document path |
|
||
| `openrouter_policy` | OpenRouter only | Route-wide typed serving policy |
|
||
|
||
There are no singular credential aliases or legacy header-name aliases in the v2 contract. Use exactly `credential_envs`, `http_headers`, `env_http_headers`, and `extra_headers` for their documented drivers.
|
||
|
||
`base_url` must be an absolute HTTP(S) root with a nonempty host. Userinfo, control/space characters, backslashes, queries, and fragments are rejected. Header names and values are validated before downstream configuration is generated.
|
||
|
||
## Model transport fields
|
||
|
||
```toml
|
||
[models.example_openai_chat__example_coder]
|
||
maker = "example"
|
||
route = "example_openai_chat"
|
||
upstream_id = "example-coder"
|
||
kind = "chat"
|
||
agent_compatible = true
|
||
modalities = ["text"]
|
||
output_modalities = ["text"]
|
||
tool_calling = true
|
||
parallel_tool_calls = false
|
||
structured_output = true
|
||
context_window = 200000
|
||
max_output_tokens = 32000
|
||
reasoning_levels = ["none", "high"]
|
||
default_reasoning = "high"
|
||
resource_group = "example_pool"
|
||
```
|
||
|
||
The compiler checks model capabilities against route capabilities. A maker/model name alone is never evidence that a particular transport preserves tools, images, documents, reasoning selectors, or structured output. `extra_body` is supported only for Switchyard-backed model targets and must contain finite JSON-compatible values.
|
||
|
||
## Credentials
|
||
|
||
Credential assignments belong in `~/.config/codex-mmo/credentials.env` or the launch environment. Profiles, catalogs, snapshots, and generated static configuration store names, never values. Worker/gateway environments filter conventional unrelated credential names and explicitly re-admit only the selected route and Tool MCP variables.
|
||
|
||
That filtering is name-based, not an OS sandbox or secret oracle. Use conventional secret names and sanitize unusual variables before launching untrusted work.
|
||
|
||
## Adding a route
|
||
|
||
Add a generation-8 fragment under `~/.config/codex-mmo/catalog.d/`, then run:
|
||
|
||
```bash
|
||
codex-mmo catalog verify
|
||
codex-mmo catalog routes
|
||
codex-mmo catalog models --route ROUTE_KEY
|
||
codex-mmo profile validate PROFILE
|
||
```
|
||
|
||
No runtime plugin is needed when an existing driver fits. Executable driver plugins are intentionally outside profile packs.
|