Skip to main content
Glama
README.md
# 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](docs/RELEASE-1.0.8.md), [1.0.7 release notes](docs/RELEASE-1.0.7.md) and the [SDK resume assessment](docs/SDK-RESUME-ASSESSMENT.md).

[中文说明](README.zh-CN.md) · [Calling conventions](USAGE.md) · [Validation and limitations](docs/VALIDATION.md)

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

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

```sh
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:

| Variable | Purpose |
| --- | --- |
| `DSH_BRIDGE_RUNTIME_ROOT` | Absolute directory containing the DSH runtime's `node_modules` |
| `DSH_BRIDGE_ALLOWED_ROOTS` | Existing workspace roots; separate with `;` on Windows or `:` on POSIX |
| `DSH_BRIDGE_DATA_ROOT` | Private writable location for task state and evidence |
| `DSH_BRIDGE_PROVIDER` | `opencode-go` (default) or `commandcode-goat` |
| `OPENCODE_GO_API_KEY` | Credential for the `opencode-go` route |
| `COMMANDCODE_API_KEY` | Credential for the `commandcode-goat` route |
| `DSH_BRIDGE_PROXY_MODE` | `inherit` (default) or explicit `direct` for the child process |
| `DSH_BRIDGE_DESKTOP_PROFILE_PATCH` | 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:

```sh
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:

```sh
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](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](docs/VALIDATION.md) 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](LICENSE). External dependencies and the separately installed DSH runtime retain their own licenses and terms. See [third-party notices](THIRD_PARTY_NOTICES.md).

TDQS

A3.9/5.0

Scored across 14 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo recent community issues