dsh-codex-app-server

简体中文

Experimental DeepSeek Harness bundle that runs the official Codex CLI as the DSH AgentFactory through codex app-server --stdio.

This package does not read Codex credentials, exchange ChatGPT subscriptions for API keys, or call private ChatGPT endpoints. Authentication, model access, quotas, Codex-native tools, MCP, and the Codex sandbox remain owned by the user-installed official CLI. DSH tools continue to execute inside the DSH host through its own policy pipeline.

> Status: 0.1.0-beta.3. Use a dedicated DSH profile and review the limitations below before relying on it for important work. This project is not endorsed by DeepSeek or OpenAI.

Compatibility

App Server is still evolving. Unknown server requests fail closed. A Codex upgrade can therefore stop a turn instead of silently accepting changed semantics.

Prerequisites and install

Install and sign in to the official Codex CLI first. Confirm that codex (codex.cmd on Windows) works in the same host execution world as DSH. The plugin never opens or copies ~/.codex/auth.json.

The DSH CLI package is @deepseek-ai/dsh; the unscoped npm package named dsh is unrelated. To install the plugin and launch the web profile directly from the registry without cloning or building this repository, use either of the following options.

One-off npx:

npx --yes --package=@deepseek-ai/dsh@0.1.0-rc.6 -- dsh plugin --profile web add dsh-codex-app-server
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web

Global npm installation:

npm install --global @deepseek-ai/dsh@0.1.0-rc.6
dsh plugin --profile web add dsh-codex-app-server
dsh web

The profile is persisted under the normal DSH home directory, so later launches do not reinstall the plugin. To inspect the composed configuration, replace web in the launch command with --profile web --dump-config.

Local development installation:

pnpm install
pnpm build
npx --yes --package=@deepseek-ai/dsh@0.1.0-rc.6 -- dsh plugin --profile web add link:/absolute/path/to/dsh-codex-app-server
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 --profile web --dump-config

The resulting configuration must show agent-loop disabled and one enabled dsh-codex-app-server row. The patch preserves the profile's session persistence, UI, ACP/JSON-RPC, filesystem, subprocess, permission, and sandbox providers.

Configuration

Configure the inserted dsh-codex-app-server row through the normal Cordis profile overlay.

Installing this bundle makes the target DSH profile a dedicated Codex profile. Its composition disables the base Agent loop, ordinary DeepSeek/pi-ai LLM adapters, and the LLM-backed title generator without deleting their user settings; those providers remain available in other profiles. The remaining catalog-only codex-app-server provider populates the Web selector from the official App Server's paginated model/list response for the signed-in account, including each model's supported reasoning efforts. On first discovery, a stale non-Codex DSH default is replaced with Codex's advertised default. A foreign selection left on an existing session is rejected explicitly rather than silently executed as Codex. A Codex model and effort selected in DSH are snapshotted at each step and sent to thread/start, thread/resume, and turn/start; the catalog adapter never carries conversation traffic.

Assistant text and reasoning deltas are appended to the DSH Session as they arrive. Codex execution items are retained as standard namespaced tool-call/result trajectories, including their complete started/completed payloads and reviewed intermediate updates. Plan snapshots drive DSH todo state, while plan explanations and turn diffs remain replayable Codex-provenance reasoning.

Before connection and before each native turn, the provider assembles the exact agent-scoped DSH prompt, runtime context, and tool schemas. Prompt sections are supplied as App Server developerInstructions; they do not replace Codex base instructions. Tools are registered under the dsh dynamic-tool namespace. An item/tool/call request is executed by ctx.tools.execute with the unchanged Codex callId, agent scope, arguments, and turn cancellation signal, so DSH validation, guards, approval policy, skill/subagent implementations, Cordis tools, and result rendering remain authoritative. Changed prompt or tool snapshots force a bounded process reconnect and exact thread/resume before the next turn.

Ownership is deliberately split. Codex owns its built-in tools, MCP/apps, native collaboration/delegation, Codex skills, rollout, and native history compaction. DSH owns dsh.* execution, DSH skills, subagents/workflows, Cordis dynamic packages, and their approval audit. The bundle replaces DSH /compact with thread/compact/start, because compacting only the projected DSH Session would not change the model-visible Codex rollout.

User prompts never enter process argv. The default sandbox has no network access. Missing DSH approval or question providers produce a conservative decline/empty answer. Secret and explicitly nonblocking Codex questions also return no answer because DSH rc.6 has no matching safe interaction seam.

Lifecycle and persistence

Each live DSH Agent owns one Codex process and one non-ephemeral Codex thread. Creation is unpublished until setup, connection, and durable binding complete. Rollback reverses registry/session/process ownership. Resume requires DSH session persistence plus an exact plugin-owned {session, thread, cwd fingerprint} binding; a missing or mismatched binding fails instead of opening a context-free thread. Codex does not materialize a rollout until a thread reaches its first model step, so an explicitly reported missing rollout may be replaced only when the persisted DSH session has no lineage or seed and has never recorded step/start. This includes turns that failed before Codex received a request. Any session that reached a model step still fails closed.

An active turn must continue producing correlated App Server activity. When it remains idle past turnIdleTimeoutMs, the driver requests an interrupt; if completion still does not arrive within interruptGraceMs, it closes the transport, terminates the process tree, and reconnects by resuming the exact durable thread on the next turn. Explicit interrupts use the same bounded recovery path. App Server warnings, deprecations, configuration warnings, model reroutes, and terminal turn errors are surfaced through the plugin logger with bounded secret redaction.

A DSH fork always starts a new Codex thread. Its first turn receives at most 64 KiB of text/reasoning projected from the fork seed. Later turns rely on the new native thread and do not repeat the seed.

Development and smoke tests

corepack enable
pnpm install --frozen-lockfile
pnpm check

Reforge 0.2.0 and coverage are required gates. pnpm check also verifies formatting, lint, types, tests, source maps, build output, and package contents. Run pnpm protocol:check whenever the installed Codex baseline changes; it compares the complete generated App Server TypeScript contract and request/notification method sets against the reviewed 0.147.0 snapshot.

The real smoke is opt-in and does not inspect credential files:

RUN_REAL_CODEX=1 pnpm test:e2e

It uses approvalPolicy: never, a read-only/no-network sandbox, a temporary workspace, two context-preserving turns, and an interrupt. It self-skips when Codex is unavailable or the account is not usable.

Update, uninstall, and rollback

Update the installed plugin with the DSH plugin command for your profile, then inspect dsh --profile web --dump-config and run a harmless session. Before changing Codex CLI versions, retain the old binary until the smoke test passes.

Uninstall this bundle with the DSH plugin removal command for the same profile. Removing its patch layer restores the base bundle's original agent-loop row; verify the dump before deleting plugin-owned bindings. Binding files contain thread IDs and cwd hashes, not credentials, and can be retained for rollback.

Known limitations

• User image blocks are supported when a DSH attachment store is installed: verified bytes are read by reference and sent as bounded data URLs. Text, reasoning, and images are accepted as input; tool-call and tool-result blocks are rejected instead of being mistranslated.
• App Server dynamic tools are experimental in Codex 0.147.0. A protocol upgrade must pass pnpm protocol:check, focused bridge tests, and the real smoke before release.
• A Cordis package that adds prompt sections or tools during a running Codex turn becomes visible on the next native turn. App Server does not currently provide an in-turn dynamic-tool replacement operation.
• DSH additionalContexts returned by a tool are included in that dynamic-tool response. A DSH concludesTurn marker is reported to Codex but cannot force the native turn to stop.
• The public question service does not currently append a durable question audit pair.
• MCP elicitation is declined because there is no complete DSH mapping yet.
• One Agent permits only one active Codex turn. Native steering is serialized onto that turn.
• Host versus remote-sandbox process placement must match where the user's Codex installation and login exist; this package currently owns a local host process.
• Real Codex smoke coverage has been performed on Ubuntu. Windows has CI coverage for argv, protocol, lifecycle, and package behavior, but still needs a credential-isolated real smoke before a stable release.

See [design](docs/design.md), [security model](docs/security.md), [contributing](CONTRIBUTING.md), and [security reporting](SECURITY.md).

License

Apache-2.0. Users remain responsible for complying with the terms that apply to their Codex/OpenAI and DeepSeek Harness use.