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
License
Apache-2.0. See LICENSE and NOTICE.
