dsh-codex

@softspark/dsh-codex connects DeepSeek Harness to a locally authenticated Codex app server under provider ID codex.

Version 1.0.0 is the first public release. The plugin does not implement OAuth, read Codex authentication files, copy tokens, call the OpenAI Responses API directly, or emit telemetry.

This is an independently maintained SoftSpark community integration. It is unofficial and is not affiliated with or endorsed by OpenAI or DeepSeek.

What's new

The 1.5.0 candidate adds DSH 0.1.2-rc.1 compatibility and prevents older session permissions from overriding a newer interactive or invalid policy. DSH 0.1.1-rc.2 remains supported. Published 1.4.0 requires the older DSH host; use a local candidate tarball for the new host until 1.5.0 is published.

Current artifact checks and runtime limitations are recorded in verification on 2026-09-06.

Historical verification

The 2026-08-26 verification run produced this evidence:

• 131 of 131 unit, protocol, bridge, and composition tests passed.
• Coverage reached 88.98 percent statements, 82 percent branches, and 91.32 percent lines.
• A live app-server reported authentication kind chatgpt and seven models.
• A direct adapter turn returned the exact marker, finish reason stop, and token usage.
• An isolated DSH web profile booted with HTTP 200.
• DSH loaded provider codex with seven models.
• A DSH session survived a host restart with the same Codex thread ID, and a live cancellation ended as aborted.
• The user screenshot showed GPT-5.6-Sol with xhigh reasoning.

These results describe the original 1.0.0 verification only. Later releases require their own source and published-artifact checks.

Requirements

• Node.js 22.19.0 or newer.
• npm for this repository.
• pnpm available to the DSH profile plugin manager.
• A local Codex CLI that can start codex app-server.
• An existing Codex login managed by the Codex CLI.
• DeepSeek Harness 0.1.1-rc.2 or 0.1.2-rc.1, with matching attachment, LLM and session seams and @deepseek-ai/cordis@4.0.2.

For subscription-backed use, codex login status must report ChatGPT.

Build and install a local tarball

git clone https://github.com/softspark/dsh-codex.git
cd dsh-codex

npm ci --ignore-scripts
npm run verify
npm run typecheck
npm run lint
npm run test:coverage
npm run build
npm run audit
npm run package:check

command -v pnpm
pnpm --version

PLUGIN_TGZ="$(npm pack --ignore-scripts --silent)"
dsh plugin --profile web add "file:$(pwd)/$PLUGIN_TGZ"

Use an isolated DSH_HOME for evaluation before modifying a regular profile.

With DSH profiles configured as autoInstallPeers=false, a pnpm peer check can report missing @deepseek-ai/cordis and @deepseek-ai/dsh-llm. The verified DSH host loader supplies those extension seams. Do not install duplicate peer copies unless a future DSH version fails at runtime and its compatibility instructions require them.

Install a published release

Install the exact reviewed version into a DSH profile:

dsh plugin --profile web add @softspark/dsh-codex@1.4.0 --save-exact

This command installs the current published artifact for DSH 0.1.1-rc.2. The 1.5.0 candidate must be tested from its local tarball before publication. Restart DSH after installation.

Architecture

DeepSeek Harness
    |
    | provider: codex
    v
@softspark/dsh-codex
    |
    | validated JSON-RPC over JSONL stdio
    v
local codex app-server
    |
    | Codex-owned auth, agent loop, built-in tools, thread state
    v
ChatGPT subscription

The plugin maps DSH text messages, model choice, reasoning effort, streaming, usage, cancellation, and finish state to the stable app-server protocol. Codex owns authentication and credential storage.

Configuration

See configuration reference.

Tool boundary

Codex app-server built-in tools run inside Codex under the selected Codex sandbox and approval policy. With inheritSessionPermissions: true, a newly started or resumed thread reads only the matching DSH Session log: the explicit Full pair (danger-full-access plus never) becomes the same Codex pair, while absent, malformed, or interactive approval state keeps the configured fallback.

By default, DSH tools remain unavailable and tool-result continuation fails closed. With experimentalDynamicTools: true, the adapter registers the current DSH tool catalog with Codex, emits canonical DSH tool-call chunks, lets the normal DSH agent loop execute the tool, then returns the correlated text result to the same Codex turn. The bridge never executes DSH tools directly.

The opt-in bridge carries text and images, is bounded, unavailable for ephemeral sessions, and does not support thread replay after a process restart. A block it cannot carry is described in the text rather than failing the turn — a result is already in the transcript when it is validated, so refusing one ends the session rather than the call. Use the sibling @softspark/dsh-orchestrator bundle to register subscription-backed Claude Code and Gemini ACP delegation tools.

Security boundaries

• App-server starts as a direct child process with shell: false.
• JSON-RPC input is untrusted and runtime validated.
• Credential-like values are redacted from errors and diagnostics.
• The plugin adds no telemetry, remote logging, or direct network client.
• DSH and Cordis remain peer dependencies supplied by the host.
• npm lifecycle scripts are forbidden.

Report vulnerabilities privately through SECURITY.md.

Development

npm ci --ignore-scripts
npm run verify
npm run typecheck
npm run lint
npm run test:coverage
npm run build
npm run audit
npm run audit:permissions
npm run audit:dependencies
npm run audit:signatures
npm run package:check

Documentation

License

Apache-2.0. See LICENSE and NOTICE.