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

Field	Default	Notes
provider	codex	The only accepted provider route.
command	codex	Direct executable name or path. Empty values fail.
cwd	process.cwd()	Working directory for Codex threads.
sandbox	workspace-write	Also accepts read-only and danger-full-access.
approvalPolicy	untrusted	Also accepts never and on-request.
inheritSessionPermissions	false	When enabled, applies explicit per-session DSH sandbox overrides and maps DSH never to Codex never for newly started or resumed threads. Missing or interactive session state retains the static fallback.
allowApiKeyAuth	false	When true, permits an API-key login already owned by Codex. The plugin never receives the key.
experimentalDynamicTools	false	Opts into the experimental DSH tool bridge and app-server experimental API.
dynamicToolTimeoutMs	600000	Bounds a deferred DSH tool call from 1,000 to 3,600,000 ms.
requestTimeoutMs	30000	Range 1,000 to 300,000 ms.
turnTimeoutMs	600000	Range 1,000 to 3,600,000 ms.

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

Document	Purpose
Architecture	Runtime layers and trust boundaries
Configuration	Provider schema and defaults
Setup	Source build and local tarball installation
Implementation plan	Verified phases and remaining release work
CHANGELOG.md	Unreleased changes
SECURITY.md	Reporting and security scope

License

Apache-2.0. See LICENSE and NOTICE.