Codex-DSH Bridge
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex-DSH Bridge delegate fixing the failing auth test in ~/projects/api and show the evidence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: opencode-delegate
The workflow
Inspect configuration with
dsh_get_capabilities.Submit a workspace, goal, constraints, and acceptance criteria with
dsh_submit_task.Observe progress with
dsh_get_task/dsh_wait_task; page detailed events withdsh_get_events(bounded cursor, never a whole-file read).Read
dsh_get_result, checkingmodelReportandbridgeObservedseparately.Supply an actual review to
dsh_continue_task, record a structured external receipt withdsh_submit_review, or end the runtime withdsh_cancel_task.After a bridge restart, inspect recorded tasks with
dsh_list_history/dsh_get_history;dsh_get_eventscan also page their recorded logs read-only.If the work must continue, call
dsh_prepare_recoveryand thendsh_recover_taskto 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 testThe 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:
Variable | Purpose |
| Absolute directory containing the DSH runtime's |
| Existing workspace roots; separate with |
| Private writable location for task state and evidence |
|
|
| Credential for the |
| Credential for the |
|
|
| Optional local desktop profile path; use an absent path when no desktop profile is available |
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.jsThe 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.mjsintentionally 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.
Available Tools
14 toolsdsh_cancel_taskStop this task's own SDK process and preserve its evidence (destructive)ADestructive
Stops the SDK process this bridge started for THIS task only, then verifies the pid is gone. It never touches the user's running DSH Desktop. Because the SDK has no per-turn cancel, the turn is interrupted rather than gracefully cancelled, and files may already have been partly modified; the returned diff is what the bridge actually observed.
Inputs: taskId (required), reason.
dsh_continue_taskSend Codex review comments as the next stage of the same sessionA
Continues the SAME live session so the model still has its earlier work in context. Refuses unknown taskIds, a stage already in flight, cancelled tasks, tasks whose runtime died, and any stage after shutdown. Each stage gets its own number and its own result; earlier stage evidence is never overwritten.
Inputs: review (required), taskId (required), goal, acceptance.
dsh_export_deliveryExport the recorded final delivery bundleA
Copies a recorded delivery index, selected source snapshot and evidence to a new directory inside allowed workspace roots. It exports a settled live task or a validated persisted-history task when no live task exists. Historical export requires task/deliveryStage/index taskId and stageCount alignment and still validates every recorded artifact hash and path; it copies recorded source bytes only, never reruns acceptance, never recaptures the current workspace and starts no model request or runtime.
Inputs: taskId (required), destination (required).
dsh_get_capabilitiesInspect the DSH bridge environment (read-only)ARead-onlyIdempotent
Read-only. Reports the community-edition DSH paths and versions, the pinned model route and any drift from the live desktop profile, credential presence (never its value), the SDK methods actually present in the pinned runtime, workspace bounds and the honest limit list. Starts no model request.
Inputs: no named parameters.
dsh_get_eventsRead bounded incremental task events (read-only)ARead-onlyIdempotent
Reads at most limit (default 25, hard cap 100) events from the task event log, starting at an opaque cursor. Logs are scanned in bounded chunks, never loaded whole; a trailing partial JSONL line is not consumed. Cursors are bound to task id and file identity, and invalid/cross-task/stale cursors are refused. Live and persisted-history reads are read-only: no PID is probed or controlled, no runtime is started and no model request is made. Secrets are scrubbed and model reasoning is stripped at output as well as storage.
Inputs: taskId (required), limit, cursor.
dsh_get_historyRead one persisted task record and stage result (read-only, bounded)ARead-onlyIdempotent
Reads one task recorded by an earlier bridge process, optionally one stage. Returns a fixed read-only envelope (source=persisted-history, runtimeAttached=false, runtimeAlive=null, canContinue=false, canCancel=false) plus projected, scrubbed task/stage/checkpoint/delivery evidence. Prompts, context, environment, reasoning, raw argv and record-controlled absolute paths are not returned. A missing or corrupt stage result is reported explicitly and never replaced with an earlier stage. The recorded PID is never probed or used for process control.
Inputs: taskId (required), stage.
dsh_get_resultRead one stage result: model report and bridge-observed evidence (read-only)ARead-onlyIdempotent
Returns the latest or a named stage. Model report and bridge evidence are separate. modelReport.previewTruncated means only the display preview was shortened; upstreamTruncated means the model hit its output limit and the stage is incomplete. Full recorded text stays on disk. bridgeObserved.toolCallsTotal is the TRUE tool-call total (not the retained 60); usageAccounting separates latest, stage sum and task sum (missing counters are null, never 0); verification.status states whether the bridge command ran, its attempts/exit code and any not-run reason; deliverySummary gives a compact deterministic acceptance basis and evidence paths. Model-internal reasoning is excluded.
Inputs: taskId (required), stage, verbose.
dsh_get_taskRead the current state of a task (read-only, never blocks)BRead-onlyIdempotent
Returns the eight-state task state, the current stage summary, runtime liveness, cancel/timeout facts and whether the task can accept another stage. Never blocks.
Inputs: taskId (required).
dsh_list_historyList persisted task history after a bridge restart (read-only, bounded)ARead-onlyIdempotent
Read-only view of tasks recorded under the configured DATA_ROOT/tasks by earlier bridge processes. Returns at most limit (default 20, hard maximum 100) projected summaries. Every response fixes source=persisted-history, runtimeAttached=false, runtimeAlive=null, canContinue=false and canCancel=false. The recorded state, timestamps and PID are evidence only; this tool never probes, resumes, continues, cancels or restarts a recorded runtime, and never recaptures a workspace. One corrupt entry is reported without hiding valid entries.
Inputs: limit.
dsh_prepare_recoveryPlan a checkpoint recovery into a new session (read-only)ARead-onlyIdempotent
Read-only. Loads a persisted task record and checkpoint under DATA_ROOT/tasks with anchored, symlink-refusing reads, checks that the caller workspace matches the recorded workspace, and returns a bounded scrubbed plan with a planToken bound to the exact source record/checkpoint and current workspace state. Starts no runtime and makes no model request; never probes or reuses the recorded PID and never exposes prompts, context, environment, reasoning or the recorded argv. A source still in this bridge process's live map is refused; use dsh_continue_task. A missing or corrupt checkpoint is an explicit refusal. A source recorded accepted/starting/running produces a warning and requires allowUnsettledSource=true at recovery.
Inputs: taskId (required), workspace (required).
dsh_recover_taskRecover a persisted checkpoint into a NEW task/session (starts a model request)A
Starts a NEW task, private SDK runtime and session from a plan produced by dsh_prepare_recovery, using the checked original goal/constraints, a bounded checkpoint summary and the current instructions. The old task tree is never written and its stages are never appended. The recorded PID and recorded verification argv are never reused or executed: fresh caller-supplied verification settings are required when the source configured verification, and original protected pins must still match. A durable atomic claim returns the same new taskId with alreadyRecovered=true on retries, including after a bridge restart. A source recorded accepted/starting/running requires explicit allowUnsettledSource=true; that is a caller acknowledgment, not bridge proof of old-process liveness.
Inputs: taskId (required), planToken (required), workspace (required), instructions (required), +13 more.
dsh_submit_reviewRecord a structured external acceptance receipt (may start one repair stage)A
Records a caller-reported external acceptance receipt bound to the exact latest settled stage. source=caller-reported: supplied commands and check outputs are DATA ONLY and are never executed. reviewedSource paths must be workspace-relative regular no-link files whose current SHA-256 matches. The receipt is persisted before any prompt. outcome=pass/blocked never starts the model; outcome=fail with actionable findings starts ONE repair stage in the same live session, even if host verification previously passed. Same reviewId with the same body is idempotent and never sends a second prompt; conflicting reuse is refused. Stale/in-flight/cancelled/historical/dead-runtime controls are refused without modifying files.
Inputs: stage (required), taskId (required), outcome (required), summary (required), +4 more.
dsh_submit_taskDelegate one stage of work to DSH (starts a model request)A
Validates the workspace against the allowed roots, creates an isolated task directory and DSH_HOME, starts a private SDK runtime process, sends the stage prompt and returns immediately with taskId/sessionId/state. It does NOT wait for the work to finish: use dsh_wait_task and dsh_get_result. May create or modify files inside the workspace.
Inputs: goal (required), workspace (required), context, budgetMs, +12 more.
dsh_wait_taskWait a bounded time for the current stage to settle (read-only)ARead-onlyIdempotent
Blocks up to timeoutMs (default 30000, hard cap 120000 = limits.waitTimeoutMaxMs in dsh_get_capabilities) waiting for the current stage to end. On timeout it returns the latest status and says you may simply call it again. It never waits indefinitely and never treats a timeout as failure. IMPORTANT for clients: set your own per-request timeout above limits.clientRequestTimeoutFloorMs (125000ms); an MCP client's SDK default is 60s, so a long wait will otherwise be aborted client-side and look like a transport failure.
Inputs: taskId (required), timeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have a clearly distinct purpose (submit/wait/get_result/get_events/continue/cancel map to discrete lifecycle actions), and descriptions explicitly state what each does NOT do. The riskiest overlaps are within the read family — dsh_get_task vs dsh_get_result vs dsh_get_history vs dsh_list_history — where an agent must parse long descriptions to pick correctly.
All names use a uniform dsh_ prefix with snake_case verb_noun structure (dsh_submit_task, dsh_get_events, dsh_cancel_task), which is highly predictable. Minor deviation: the prepare_recovery/recover_task pair splits one conceptual operation across two verbs, and some names are verb_noun_noun (dsh_submit_review, dsh_get_capabilities), slightly reducing uniformity.
14 tools sit comfortably in the expected 3-15 band, and each maps to a real lifecycle stage (discovery, execution, observation, review, export, recovery). The set is on the heavier side but no tool looks redundant or trivially trivial.
The surface covers a full task lifecycle: capabilities, submit, poll/wait, result, events, continue, cancel, review, delivery export, history, and recovery. Minor gaps: there is no way to enumerate live tasks in the current bridge process (only persisted history is listable), and no explicit cleanup/delete of task directories.
Maintenance
Related MCP Connectors
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceExposes DeepSeek Harness agent capabilities over MCP so any MCP client can delegate real coding work to a running agent with its full toolset (bash, filesystem, todo, web). Turns are dispatched asynchronously into sessions and then tracked through status, tail, wait, cancel, compact, and rename tools, with the session log as the source of truth so results survive restarts.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to delegate bounded tasks to a local OpenCode worker while monitoring progress, reviewing evidence, and managing session rework or recovery. It also supports persistent TUI tabs for delegated task workspaces.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables Codex to delegate scoped tasks to a local DeepSeek Harness over MCP — dispatching read-only reviews or authorized workspace writes, steering and monitoring runs to a terminal state, and returning structured evidence such as changed paths, test results, and assistant text. It also supports exact archival of the terminal session by full session ID.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables Codex and DeepSeek Harness to hand off work to each other, then track progress, wait for results, cancel running work, and continue the original execution session. Tasks run in a local service independent of the caller, so closing a chat or losing the MCP connection does not stop them.MIT