# Codex Worker Runtime

Role-based external LLM delegation for Codex.

Codex stays the orchestrator and delegates bounded work through four MCP tools:

- `delegate_work`
- `list_workers`
- `worker_health`
- `get_worker_run`

## Current routes

| Role | Worker | Adapter |
| --- | --- | --- |
| `code_review` | `qwen` | OpenAI-compatible API |
| `x_research` | `grok` | guarded Grok CLI |
| `planning` | `kimi` | opencodex Responses API |
| `research` | `kimi` | opencodex Responses API |

Kimi is reached only through the worker runtime. The main Codex provider,
history, CLI shim, account pool, and native subagent catalog do not need to be
changed.

## Guarantees

- External workers cannot edit local files or execute Codex commands.
- `secret` and `credential` requests are rejected before dispatch.
- Worker results are normalized into a stable transport and semantic contract.
- `completed + rejected` is preserved and is never overwritten by another
  provider.
- Unavailable or timed-out workers return control to Codex according to policy.
- Requests, attempts, and results are stored in a local SQLite audit ledger.
- Prepared requests and raw provider responses stay out of the normal result.

## Configuration

The runtime loads the first available policy:

1. `CODEX_WORKER_CONFIG`
2. `~/.codex/codex-worker-runtime/workers.toml`
3. bundled `config/workers.toml`

Relative worker commands are resolved from the policy file. `~/` paths expand
to the current user home directory.

The bundled policy expects:

- an OpenAI-compatible Qwen endpoint at `http://127.0.0.1:8081`
- Grok Build installed at `~/.grok/bin/grok`
- Grok privacy settings that pass `runtime/grok/grok_privacy_guard.py`
- opencodex listening on `127.0.0.1:10100` with the `kimi` provider authenticated

Start only the local proxy server used by the Kimi worker, without Codex model
injection, history synchronization, a CLI shim, or a background service:

```bash
npm run start:kimi-proxy
```

To keep a custom policy outside the plugin, copy the file, update any relative
worker commands for its new location, and set `CODEX_WORKER_CONFIG` to its
absolute path.

## Development

```bash
npm install
npm run check
npm run test:all
```

## Local personal-plugin install

The installer creates named backups, stages the plugin, verifies
source/target/cache hashes, and checks plugin activation.

```bash
node scripts/install-personal.mjs --dry-run
node scripts/install-personal.mjs
```

Optional environment variables:

- `CODEX_WORKER_CODEX_ROOT`
- `CODEX_WORKER_CODEX_CLI`
- `CODEX_WORKER_INSTALL_TARGET`
- `CODEX_WORKER_MARKETPLACE`
- `CODEX_WORKER_AUDIT`

## Coexistence with opencodex

[opencodex](https://github.com/lidge-jun/opencodex) and Codex Worker Runtime can
coexist because they operate at different layers:

- opencodex proxies the main Codex Responses API transport.
- Codex Worker Runtime delegates selected roles through MCP.

Recommended policy:

- keep the main Codex provider explicit
- avoid routing the same job to both a native routed subagent and an MCP worker
- review `~/.codex/config.toml` after running `ocx init` or installing its shim
- let only one installer manage the Codex provider configuration and CLI shim
- keep credentials in each provider's own configuration; do not copy them into
  `workers.toml`

The runtime uses stdio MCP and does not bind opencodex's default port `10100`.
Its bundled Qwen example uses port `8081`.

## Adding a worker

1. Add the worker and role to `config/workers.toml`.
2. Reuse an existing adapter or add a dedicated adapter.
3. Normalize the response into the common result contract.
4. Add health, timeout, failure, audit, and redaction tests.

## License

MIT