dsh-codex-bridge

English | 中文

A dual-face (host + browser) plugin for DeepSeek Harness (dsh) that bridges the Codex CLI into the harness.

Why

A dsh agent often wants a second opinion or a parallel coding pass from an external coding agent (OpenAI Codex). Doing that by hand — spawning codex, capturing JSONL, polling, wiring the output back — is exactly the kind of scaffolding a harness plugin exists to remove. This plugin makes Codex a first-class dsh citizen:

1. Calls Codex as a tool — call_codex starts a Codex session (codex -a never exec --json) in the session's working directory, with async (returns immediately; multiple calls run in parallel) and block (waits for the final answer) modes, plus codex_status to poll and codex_abort to cancel.
2. Continues the same thread — codex_steer resumes a settled Codex session on the SAME thread (codex exec resume <thread_id>), so you can redirect, ask follow-ups, or correct direction with the full history retained. The thread is linear: the parent must be the latest record, and one thread can have only one active continuation.
3. Shows the whole agent loop — the Codex tab in the conversation pane (on par with Chat and Trajectory) observes each session live: status, prompt, an Agent Loop waterfall (messages, tool calls with command/args, collapsible tool output with exit code, turn separators), the transcript, and the final answer — pushed through the session projection channel.

Design stance: this is a UX channel, not a security boundary. Codex runs with the calling user's privileges under its own sandbox policy (read-only/workspace-write are offered to the model; danger-full-access is deploy-config only). The model-facing surface is deliberately tight: Codex always runs in the session working directory (never the host cwd — fail closed), only top-level agents may call by default, and maxParallel/maxSessionsPerSession/maxLoopSteps/maxLoopBytes bound resource and write amplification.

Installation

Requirements: Node.js 22 or newer, @deepseek-ai/dsh@0.1.0-rc.6, and an authenticated Codex CLI available as codex (or set codexPath). The plugin does not read or store API keys; authentication remains owned by the Codex CLI.

Build, validate, and pack the standalone bundle from the plugin directory:

npm install
npm run check
npm pack

Install the generated tarball into a DSH profile, then restart dsh web. Installing the source directory as a link is not supported because host peers are supplied by the DSH profile:

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add ./dsh-codex-bridge-0.1.0.tgz
npx @deepseek-ai/dsh@0.1.0-rc.6 web

The browser half is served at /plugins/dsh-codex-bridge/client.js and appears in the conversation pane. Verify it against a running default Web profile:

curl -s http://127.0.0.1:3080/plugins/dsh-codex-bridge/client.js | head

To update, build a tarball with a newer package version, remove the installed bundle, add the new tarball, and restart. To uninstall:

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web remove dsh-codex-bridge

Config

Key	Default	Meaning
codexPath	codex	codex executable (absolute path or PATH lookup)
defaultSandbox	read-only	codex sandbox policy for its shell commands (deployment may raise it)
defaultTimeoutMs	0	lifetime limit per codex session (0 = unlimited)
maxParallel	3	global cap on concurrent codex processes
maxSessionsPerSession	8	cap on live codex sessions per dsh session
maxRetained	16	retained (settled) records per dsh session (oldest evicted)
maxPromptChars	16384	prompt length cap (longer prompts are rejected)
maxTranscriptChars	16384	transcript cap recorded in events/projections
maxLoopSteps	32	bounded agent-loop window (steps kept in the record/projection)
maxLoopBytes	16384	serialized-byte cap for the loop window (UTF-8; oldest completed steps evicted)
allowedAgents	roots	who may call call_codex: roots | all
killGraceMs	2000	SIGTERM → SIGKILL grace on abort

Tools

• call_codex — { prompt, mode?: async|block, sandbox?: read-only|workspace-write, model?, timeout_ms?, codex_session_id? }. async starts and returns immediately (parallel); block waits for the answer (or, with codex_session_id, waits on a previously started session). A cancelled blocking wait aborts the codex session.
• codex_status — list the current session's codex sessions (status, prompt preview, progress).
• codex_abort — { codex_session_id }; SIGTERM the process group, then SIGKILL after killGraceMs.
• codex_steer — { codex_session_id, prompt, mode?: async|block, model?, timeout_ms? }. Continue a settled parent session on the SAME thread (codex exec resume <thread_id>); the new record links back via parent (lineage shows in the Codex tab). A post-restart parent works as long as its record carries the codex thread id.

Model Experience

The Codex tab (conversation pane, after Chat/Trajectory):

• Left column — every codex session of the current dsh session, with status dot, prompt preview, and relative time. Click to select.
• Right column — status badge, meta (id/codexId/cwd/sandbox/model/ duration/exit/error), the prompt, and an Activity | Text toggle:
  • Activity — the Agent Loop waterfall: messages, tool rows (tool name, running/done/failed, duration, exit code, truncated marker; output auto-expands on failure), turn separators, and a "N steps dropped" marker when the bounded window evicted older steps.
  • Text — the streamed transcript and the final answer.

State changes ride the session projection channel (codex/session events, codex/sessions projection), so the tab updates live and survives page refresh (history replay).

Known Limitations and Deferred Work

• One shot per call, then continuation. call_codex starts a fresh codex exec run; live mid-run steering (injecting a message while Codex is still working) is not available in the standard CLI — that would require the experimental codex app-server/remote-control daemon path.
• The loop window is recent-activity, not an audit trail. Older steps are physically evicted under maxLoopSteps/maxLoopBytes; the canonical dsh session log still holds the whole-value snapshots, but the tab only shows the retained window.
• Sandbox is Codex's own. defaultSandbox maps to codex -s; it bounds what Codex's shell commands may touch, not the harness's sandbox. Never call it a harness security boundary.
• POSIX-only process groups. Abort uses detached + negative-pid kill; a Windows port needs Job Object / taskkill /T tree termination.
• Telemetry redaction covers dsh exports only. Codex's own telemetry is out of scope.

Development

npm run check    # typecheck + tests + compliance
npm run build    # host (tsc) + client bundle (esbuild, __ModuleLoader__ ABI)

The client bundle speaks the harness __ModuleLoader__.load({id, factory}) protocol with the platform module table as externals; the host half follows the bundle format from create-dsh-plugin.

License

MIT