DSH Codex Agent Bridge

简体中文

@jadynchou/dsh-codex-agent-bridge is a community plugin that connects DeepSeek Harness agents to the official Codex App Server protocol. It registers an openai-codex provider, discovers the models available to the local Codex CLI login, and exposes each model's supported reasoning efforts in the DSH model picker.

The plugin uses the Codex CLI authentication of the operating-system user running DSH. Codex supports both ChatGPT subscription access and API-key access; credentials remain managed by Codex CLI and do not need to be copied into the DSH profile. See the official Codex authentication and App Server documentation.

Features

• Live model discovery through model/list, including the default model and supported reasoning efforts.
• Streaming text, reasoning summaries, usage data, and current-message image inputs.
• DSH dynamic Tool execution inside Codex agent turns.
• Reuse of one Codex thread when the DSH history is continuous and receipt-confirmed, so normal follow-up turns send only the new message.
• DSH remains the sole durable-history authority; compaction, restore, fork, or configuration divergence automatically rebuilds the Codex thread.
• A permanently read-only native Codex sandbox, with workspace reads, searches, writes, edits, deletes, moves, and commands routed to DSH dynamic Tools.
• DSH compaction-request support and runtime learning of each model's actual App Server context window.
• Explicit failures for unsupported DSH request fields instead of silently ignoring them.

Requirements

• DeepSeek Harness 0.1.0-rc.5 or a compatible later release.
• Node.js ^22.19.0 || >=24.0.0.
• Codex CLI available in the DSH process PATH. Version 0.147.0 is the currently tested protocol baseline.
• A valid Codex CLI login for the same operating-system user that runs DSH.

Install Codex CLI using the official instructions, then authenticate:

npm install --global @openai/codex
codex login
codex --version

If DSH runs as a system service, authenticate as that service user or configure its HOME / CODEX_HOME to use the intended Codex login.

Install

Run DSH through npx

If you use DSH without installing it globally, install the package manager required by dsh plugin once, then prefix every DSH command with npx --yes @deepseek-ai/dsh:

npm install --global pnpm
npx --yes @deepseek-ai/dsh plugin --profile web add @jadynchou/dsh-codex-agent-bridge@latest
npx --yes @deepseek-ai/dsh web

This keeps DSH itself npx-only. Plugin files and the web profile remain under the shared DSH home directory (~/.dsh by default, or %USERPROFILE%\.dsh on Windows), so later npx runs keep the installed plugin. latest is npm's moving stable-release tag, not a numeric version pinned in this README.

Installed DSH CLI

With an installed DSH CLI:

dsh plugin --profile web add @jadynchou/dsh-codex-agent-bridge@latest
dsh web

DeepSeek Harness source checkout

When running DeepSeek Harness from a source checkout:

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add @jadynchou/dsh-codex-agent-bridge@latest
pnpm dsh web

Run pnpm dsh ... only from the DeepSeek Harness repository root, where its package.json is located. If dsh is installed as a command, use dsh ... from any directory instead. The npm release contains prebuilt lib/ output and does not require pnpm approve-builds for this plugin.

For a source review before an npm release, pin a GitHub commit rather than a moving branch:

dsh plugin --profile web add github:je00/dsh-codex-agent-bridge#<commit-sha>

Verify and use

Check authentication and confirm that the bundle layer is present before starting the server:

codex login status
dsh --profile web --dump-config
dsh web

For npx-only DSH, replace the last two commands with npx --yes @deepseek-ai/dsh --profile web --dump-config and npx --yes @deepseek-ai/dsh web. For a DeepSeek Harness source checkout, use pnpm dsh --profile web --dump-config and pnpm dsh web. The dumped configuration should contain an @jadynchou/dsh-codex-agent-bridge layer and a codex-agent-bridge row.

In the Web UI:

1. Open the model settings page.
2. Select the OpenAI Codex (ChatGPT) provider.
3. Select one of the models returned by the authenticated Codex account.
4. Select a reasoning effort supported by that model.
5. Start an Agent session whose workspace is an absolute local directory.

After successful configuration, the model picker shows an OpenAI Codex (ChatGPT) group with the models returned by the current Codex account. Seeing the provider and model list below confirms that the plugin layer, Codex CLI login, and model catalog are active.

The model names and reasoning-effort choices come from Codex rather than a hard-coded catalog. Changing accounts or workspace entitlements may change the list after the five-minute cache expires or the DSH process restarts.

Upgrade or remove

Upgrade to the latest published release:

dsh plugin --profile web update @jadynchou/dsh-codex-agent-bridge --latest

This follows npm's moving latest tag without pinning a numeric version. pnpm 11 normally waits 24 hours before accepting a newly published dependency version as a supply-chain safeguard. To install a release immediately after publication, override that delay for this one command:

dsh plugin --profile web update @jadynchou/dsh-codex-agent-bridge --latest --config.minimum-release-age=0

Remove the plugin:

dsh plugin --profile web remove @jadynchou/dsh-codex-agent-bridge

For npx-only DSH, prefix the same commands with npx --yes @deepseek-ai/dsh, just as in the installation section.

Configuration

The native Codex sandbox is permanently read-only. DSH dynamic Tools still execute through ctx.tools.execute(); tool visibility, pre-execution policy, approval, guards, result policy, and the selected backend apply as appropriate for the current Agent/session and tool. Override other settings in the profile's cordis.patch.yml when needed:

- id: codex-agent-bridge
  config:
    codexCommand: codex
    modelCacheMs: 300000

DSH patch rows replace the complete config value instead of deeply merging keys, so keep every non-default key you still need when overriding this row.

Option	Default	Description
codexCommand	codex	Executable name or absolute Codex CLI path; Windows .cmd and .bat launchers are supported.
env	{}	Variables layered onto DSH's scrubbed subprocess environment. Do not store secrets in YAML.
disposeGraceMs	3000	Grace period before the managed App Server process tree is forcefully terminated.
modelCacheMs	300000	Successful model-catalog cache duration; use 0 to refresh every time.
includeHiddenModels	false	Include models hidden from the default Codex picker.
sandbox	fixed read-only	Retained only for old configuration compatibility; every other value is rejected. Write access comes from the DSH Tool sandbox and approval chain.
catalogCwd	DSH process cwd	Absolute working directory used only for the model-catalog App Server.
modelContextWindows	{}	Optional positive model id → context window map. Enter only verified App Server values; a smaller runtime observation wins.

Session and security behavior

DSH is the sole authority for durable conversation history; a Codex thread is only a disposable runtime mirror. On the first turn or after a rebuild, the plugin gives a new ephemeral Codex thread the current DSH-derived history. A follow-up reuses that thread and sends only the new current message when the prior assistant's private receipt, message IDs, content, provenance, and all model-facing configuration match exactly. Local hash verification does not send history to the model or consume model tokens.

DSH history compaction, restore, deletion, reordering, or fork; a missing or altered receipt; and changes to the model, reasoning effort, system prompt, tools, or workspace all cause an automatic rebuild from DSH history. App Server auto-compaction, model rerouting, extra steer/hook input, and any native item that cannot be reconstructed completely from DSH messages or validated Tool replay data also retire the mirror after the current answer is delivered. Process restart and failure recovery rebuild as well. Because App Server cannot immediately unload one ephemeral thread, a divergent mirror retires its session process instead of accumulating inaccessible threads. Normal continuous conversations therefore avoid full-history resend without allowing native Codex state to overwrite DSH truth.

The plugin learns the exact App Server context window from thread/tokenUsage/updated and exposes it to DSH proactive compaction on later requests. App Server publishes no reliable pre-turn capacity field; if capacity must be known before the first turn, configure a verified exact value in modelContextWindows rather than copying a capacity from an OpenAI API model page. DSH compaction uses a disposable App Server process and cannot contaminate the conversational thread. It declares no dynamic Tools to the summary thread, so compaction cannot trigger workspace side effects. Summary chunks are buffered until reported usage proves the result stayed within maxTokens; an over-limit summary is rejected without retiring the still-valid conversational mirror.

The current user message can include images, which are sent to Codex as data URLs. Historical images currently retain only media type and size metadata. Dynamic Tools requested by Codex are restricted to those declared for the current DSH request and run through DSH ToolRuntime under the current Agent identity. Successful call arguments and final results are stored as validated adapter-private replay data on the assistant message; a rebuilt thread can therefore recover the same Tool context from DSH instead of depending on hidden native state.

For ordinary Agent turns, the plugin contributes a provider-filtered execution-route section during DSH system-prompt assembly. The rendered text is persisted in the data.header.system field of the request/header event and passed unchanged to Codex as developerInstructions, so an exported session.jsonl can be audited by searching that field for DeepSeek Harness execution route:. The route tells Codex to use declared DSH Tools for workspace operations, call only run_code directly in Code Mode, use ask_user_question for user decisions, and treat Tool-returned sandbox or approval guidance as authoritative. A route owner that later changes the provider through agent/request must declare the same provider during prompt assembly. The cooperative path rejects a mismatch before header persistence; a final AgentLoop dispatch guard also catches an outer waterfall reorder before adapter I/O, although that failed attempt may already have logged its header snapshot. A small idempotent compatibility fallback preserves direct and legacy-header calls that bypass normal assembly, plus complete prompts whose exact section is restored after the assembly waterfall. Because that fallback runs inside the adapter, it cannot retroactively add text to an earlier request/header.

Human questions use the DSH-owned interaction route. Codex is instructed to call the declared ask_user_question Tool; in Code Mode it calls that Tool through the generated SDK inside run_code. If Codex still emits native request_user_input, the bridge accepts the defensive fallback only when the current turn declares ask_user_question or exposes the run_code SDK route and the current Agent can see the question Tool. The fallback also enters the complete ToolRuntime pipeline: Native/Both mode executes ask_user_question directly, while Code Mode executes run_code and lets its SDK dispatch the nested question Tool. Tool visibility, pre-execution policy, approval, guards, and result policy therefore remain effective, and a denial at any layer never falls back to a direct dialog. The bridge waits for an explicit answer before Codex can continue. Question headings, prompts, declared choices, and answers pass through without translation, so English and Chinese sessions keep their own language. The answer is retained in private replay data and the native thread is retired after the turn. Cancellation, Skip or another empty answer, a missing interaction provider, a hidden Tool, a policy denial, malformed or incomplete answers, and secret-input requests fail the turn instead of silently returning an empty answer. Answers submitted through the dialog never enter the ordinary message Queue; normal messages sent while the Agent is busy still follow DSH's Queue/Steer preference.

Subagent settlement notices may contain reasoning blocks copied from the child's closing response. For current user input, the bridge ignores those provider-only reasoning blocks while preserving every text and image block, matching DSH's other user-input adapters and preventing a settlement notice from aborting the parent turn.

Routing reads through DSH Tools is a model-behavior constraint, not an additional kernel security boundary; Codex's native read-only capabilities may still physically read the workspace. The route also lets DSH read establish the file-observation state used by later edit/write concurrency protection. If no suitable DSH Tool is declared, the model should report the missing capability.

The App Server approval policy is fixed to never and its native sandbox is fixed to read-only; native permission requests fail closed instead of opening a second interactive approval path. Write capability therefore comes only through the existing DSH Tool execution chain. If the model still invokes a native command, web search, MCP call, or another unprojected capability, the plugin does not trust that hidden result as reusable history and retires the mirror after the turn. DSH's file sandbox promises a file-impact boundary; it does not mean every Tool requires approval or that all network and process visibility is confined.

Current limitations

• Normal conversation temperature, maxTokens, stop, and auxiliary purposes other than compaction remain UNSUPPORTED. For purpose: compaction, maxTokens is a prompt plus result-level check; App Server has no hard generation cap, so it cannot reduce upstream tokens already generated.
• Without a configured modelContextWindows entry, capacity becomes known after the first successful turn. A first-turn overflow relies on DSH's overflow-compaction recovery path.
• App Server dynamic Tools depend on the protocol's experimental capability used by Codex CLI 0.147.0; retest before declaring compatibility with a newer CLI release.
• Dynamic Tool calls do not yet create native persistent DSH Tool cards; their validated private replay trace preserves rebuild semantics but is not presented as a Tool card.
• Secret native request_user_input fields are rejected because the current DSH question dialog has no masked-answer control. Ask for non-secret information through ask_user_question instead.
• The DSH dialog currently shows its normal custom-answer field for choice questions even when native request_user_input sets isOther: false; submitting that extra field fails the turn because the native question did not permit it. The preferred DSH ask_user_question route keeps DSH's own custom-answer semantics.
• A complete: true DSH prompt still runs the assembly waterfall, then intentionally restores its exact section as the only final prompt section. The adapter compatibility fallback still supplies the execution route to Codex, but that late fallback is not visible in request/header. Explicit cross-provider compaction also reuses the latest header system verbatim, so provider-specific prompt sections cannot currently be re-filtered for the summarizer route.
• A failed model turn retires that session's App Server process. The next request starts a clean process, and automatic model retries are disabled. If context overflow occurs after a DSH Tool has started, the plugin converts it into a non-recoverable failure so DSH overflow-compaction recovery cannot repeat the same side effect.

Troubleshooting

• Codex executable was not found: run codex --version as the DSH service user or set an absolute codexCommand.
• A Codex-provider authentication error or HTTP 401 / 403: run codex login status and codex login as the same user that starts DSH, then verify the service's HOME / CODEX_HOME.
• No models in the picker: confirm the Codex login can list models, then restart DSH or set modelCacheMs: 0 while diagnosing.
• Protocol errors after a Codex CLI upgrade: install the tested CLI baseline or validate the new release with pnpm test:live before production use.
• A Codex question does not open a dialog: verify that the Web profile includes the DSH userQuestions provider, that ask_user_question remains visible in the current Agent preset, and that the turn exposes either that Tool or run_code. The bridge fails the turn when the route is unavailable instead of treating the question as answered.

A browser transport error such as /api/settings.describe: HTTP 403 comes from the DSH Web trust boundary, not Codex authentication. Fix the DSH Web host/trusted-host deployment first; changing this plugin or repeating codex login will not resolve that endpoint error.

Development

pnpm install
pnpm run typecheck
pnpm run lint
pnpm run test:coverage
pnpm run build
pnpm run test:live

test:live uses the current Codex login for one real read-only dynamic Tool turn and may consume a small amount of account usage. The normal unit and package-runtime tests do not contact OpenAI.

License and trademarks

MIT. This is an independent community project and is not an official DeepSeek or OpenAI package. DeepSeek, DeepSeek Harness, OpenAI, ChatGPT, and Codex are trademarks of their respective owners.