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.8. 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.

Version 1.0.8 adds bounded same-live-session continuation after real provider output exhaustion (autoContinue), structured caller-reported external acceptance receipts (dsh_submit_review), and separate automation metrics with honest per-stage cause/elapsed evidence. It preserves 1.0.7 persistence health, source-scope/import, event paging and live progress, 1.0.6 checkpoint recovery, 1.0.5 read-only history and every old tool schema. See the 1.0.8 release notes, 1.0.7 release notes and the SDK resume assessment.

中文说明 · 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: dsh-mcp-server

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 / dsh_wait_task; page detailed events with dsh_get_events (bounded cursor, never a whole-file read).

4. Read dsh_get_result, checking modelReport and bridgeObserved separately.

5. Supply an actual review to dsh_continue_task, record a structured external receipt with dsh_submit_review, or end the runtime with dsh_cancel_task.

6. After a bridge restart, inspect recorded tasks with dsh_list_history / dsh_get_history; dsh_get_events can also page their recorded logs read-only.

7. If the work must continue, call dsh_prepare_recovery and then dsh_recover_task to start a NEW task/session from the persisted checkpoint. The old task stays read-only; the new task gets its own stage list and evidence.

A returned report is evidence for review, not automatic acceptance. Continuation requires the original runtime to remain alive. Checkpoint recovery is not native SDK conversation resume: it starts a new session, does not restore the old prompt/reasoning, and never probes or reuses the old PID.

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. Ubuntu-DSH is the intended execution target; native Windows execution is deferred. Some Windows tests retain the original D:\AGENTS scratch-directory convention, and Windows-native host acceptance is not claimed.

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.

For a complete implementation and repair loop, set deliveryPreset: "complete" and provide both verificationCommand and non-empty protectedVerificationFiles. This selects high reasoning, 32768 tokens, a 30-minute stage budget, and up to three extra repair stages. Explicit overrides remain authoritative. Auto-repair is otherwise off by default. autoRepair.totalBudgetMs bounds the current automatic-repair cycle, not all manual continuation stages; a manual continuation resets the automatic-repair counters in the same live session. Review USAGE.md before enabling it; verifier dependencies must be declared by the caller.

Use dsh_list_history and dsh_get_history after a restart to read bounded, scrubbed, read-only records. Those records fix runtimeAttached=false, runtimeAlive=null, canContinue=false and canCancel=false; the recorded PID is never probed. Continue/cancel/wait refuse a historical id with historical_not_live.

Use dsh_prepare_recovery to validate a persisted checkpoint and current workspace and obtain a planToken, then dsh_recover_task with fresh instructions and fresh verification settings. When the source configured verification or pinned protected files, the recorded argv is not executed and the original pins cannot be dropped. Retries with the same plan token return the same new task with alreadyRecovered=true; a source recorded running is refused unless the caller explicitly acknowledges allowUnsettledSource=true.

Use dsh_export_delivery to copy a settled task's recorded source snapshots, evidence, and indexes to a new allowed directory. With deliverySource, the index additionally binds source.mode, source.scope, source.final and (patch) source.baseline; import it with node scripts/import-delivery.mjs --bundle <export> --destination <dir> (dry run) and add --apply to write. Patch import verifies the destination's exact baseline and retains a backup transaction; complete import requires a new/empty directory. It also accepts a validated historical task id when no live task exists. Export validates the latest task/stage/index binding and every artifact hash, copies recorded source bytes, and does not repeat acceptance or recapture the workspace. Runtime-dependent baseline checks remain separate from portable scripted checks; skipped checks are not a full runtime pass.

Boundaries and known gaps

• The allowed-root check validates task admission, and the SDK overlay is configured with workspace-write. That is not proof of OS/filesystem isolation 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.