Codex–DSH Bridge

A local MCP bridge that lets Codex delegate bounded development tasks to a separate DSH agent harness, inspect the evidence, and explicitly decide whether to continue.

Development status: work in progress. The current source baseline is 1.0.2. This is an independent community project, with no claim of affiliation with OpenAI or DeepSeek. Public adoption and cross-model coverage have not been established.

中文说明 · Calling conventions · Validation and limitations

Why this exists

Connecting an MCP client to another agent is only the first step. A useful delegation loop also needs bounded execution, inspectable results, explicit review, continuation, and cancellation.

This bridge keeps Codex in charge of that loop. DSH executes one stage in a private SDK process and task home; the bridge records SDK events, workspace changes, and optional host verification separately from the model's own report. Reaching an output limit is reported as incomplete, rather than being presented as successful completion.

The project is also a place to develop reproducible harness and model compatibility checks. Its current provider routes are deliberately narrow; it does not claim universal provider support or measured cost savings.

Related MCP server: engineering-mcp

The workflow

1. Inspect configuration with dsh_get_capabilities.

2. Submit a workspace, goal, constraints, and acceptance criteria with dsh_submit_task.

3. Observe progress with dsh_get_task or dsh_wait_task.

4. Read dsh_get_result, checking modelReport and bridgeObserved separately.

5. Supply an actual review to dsh_continue_task, or end the runtime with dsh_cancel_task.

A returned report is evidence for review, not automatic acceptance. Continuation requires the original runtime to remain alive. There is no recovery of live sessions across bridge restarts.

Build and run

Use Node.js 24 for the currently tested development environment. The package declares Node.js 20 or later, but the full suite has not been validated on every declared Node version.

npm ci
npm run build
npm test

The ordinary suite uses scripted execution and synthetic package metadata, requires no installed DSH runtime, and makes no model requests. The initial automated CI targets Ubuntu. Some Windows tests retain the original D:\AGENTS scratch-directory convention; Windows CI portability remains unfinished.

Actual delegation additionally needs a separately installed community DSH runtime. The development baseline used @deepseek-ai/dsh 0.2.1-rc.2. DSH and its SDK packages are not bundled or installed by this repository. Compatibility with later versions must be checked rather than assumed.

After configuring that installation, npm run test:installed-runtime runs two additional read-only checks against the actual bundle. Those checks fail when the installation is missing; they never fall back to synthetic metadata. They do not test model reachability.

Configure the MCP server to execute node /absolute/path/to/codex-dsh-bridge/dist/src/main.js over stdio. Set these environment variables in the launcher or MCP server configuration:

Supply only the credential for the route you intend to use. Read it from your private environment; do not commit it to a repository or a shared launcher. A ChatGPT subscription is not itself a credential for these DSH provider routes.

Example POSIX launcher, after defining the selected provider credential privately:

export DSH_BRIDGE_RUNTIME_ROOT="$HOME/dsh-runtime"
export DSH_BRIDGE_ALLOWED_ROOTS="$HOME/projects"
export DSH_BRIDGE_DATA_ROOT="$HOME/.codex-dsh-bridge"
export DSH_BRIDGE_PROVIDER="opencode-go"
mkdir -p "$HOME/projects" "$DSH_BRIDGE_DATA_ROOT"
node /absolute/path/to/codex-dsh-bridge/dist/src/main.js

The Windows defaults in src/config.ts still reflect the original development machine. Override the paths explicitly on other machines. A WSL runtime expects Linux paths and workspaces visible inside that environment; a Windows path cannot be passed to it unchanged.

Optional execution profiles

Omit executionProfile for the legacy overlay. Explicit native and ptc profiles mount scoped agent presets and require a local critical-runtime baseline. That baseline is installation specific and is intentionally excluded from Git.

After reviewing the installed runtime and building the bridge, capture it locally:

node maintenance/guard.mjs baseline \
  --runtime-root "$DSH_BRIDGE_RUNTIME_ROOT" \
  --assets-root "$PWD" \
  --baseline "$PWD/baseline/execution-profiles-baseline.json"

The guard refuses to overwrite an existing baseline and blocks explicit profiles on drift. A baseline records selected files; it is not a full audit of the runtime or its dependency tree. Desktop plugins are not inherited by these profiles.

Task parameters

Omitted work parameters select reasoningEffort=medium, maxTokens=16384, and a 300000 ms per-stage budget. Explicit shorter diagnostic budgets and high effort are preserved. On the GOAT route, off/none is mapped to low with a warning; there is no silent provider switch.

verificationCommand is an optional argv array executed by the bridge in the workspace. Its exit code is recorded independently of the model report. Long MCP waits also require a client request timeout above the floor reported by capabilities.

Boundaries and known gaps

• The allowed-root check validates task admission. It is not an operating-system sandbox and does not isolate arbitrary child commands. Use a separate OS account, container, VM, or other appropriate host boundary for untrusted work.

• The default concurrency limit is one task. Model calls require your own authorized provider access and can incur charges.

• A read-only capability probe does not establish model reachability or end-to-end acceptance.

• Cancellation records process cleanup evidence, with platform-dependent coverage. It does not guarantee capture of arbitrary escaped descendants.

• The model harness is version sensitive. Browser, desktop, account, and arbitrary model/provider compatibility remain outside the current acceptance claims.

• Live model scripts are separate from npm test; review them and configure the runtime before running them. scripts/e2e-real.mjs intentionally waits for a review file between stages.

See validation notes before relying on the bridge for a new environment.

Contributing

Small, reproducible bug reports are useful: include the bridge commit, Node/OS version, DSH runtime version, selected route and execution profile, expected behavior, and a redacted minimal reproduction. Never attach credentials, private prompts, task homes, or unredacted model logs.

Build and run npm test before proposing a change. State whether evidence comes from scripted tests or a real runtime. Cross-model claims need the exact route/model/runtime and a reproducible task; configuration alone is insufficient.

License and dependencies

Bridge source is released under the MIT License. External dependencies and the separately installed DSH runtime retain their own licenses and terms. See third-party notices.