dsh-codex-suite

DSH Codex Suite

English | 简体中文

A suite of DeepSeek Harness (DSH) plugins that brings ChatGPT/OpenAI Codex models and a Codex-style conversation experience to the DSH Web UI. Built against DSH 0.2.1-rc.2 (peer range >=0.2.0-rc.2 <0.3.0-0).

The repository is a pnpm monorepo containing two independent runtime plugins and one pure bundle package:

The two plugins are fully decoupled: the Conversation UI works with any model, and the Codex Provider works with the stock chat UI.

---

Why this suite

Codex Provider — reliable ChatGPT access without an API key

• ChatGPT OAuth, both flows. Browser-based login with device-code fallback. Login failures are classified into secret-free, localized reasons (region restrictions, callback port conflicts, token exchange errors, network issues…) instead of raw stack traces.
• IPv6 loopback callback bridge. pi-ai's OAuth listener only binds IPv4; on IPv6-preferred hosts the suite transparently relays the loopback callback, so login still works.
• Proactive token refresh. Access tokens rotate ~5 minutes before expiry with retry backoff; a dead refresh token is detected precisely and surfaces as reconnect required instead of failing mid-stream.
• Usage dashboard. Plan (shown under its user-facing name such as Plus, Pro 5x, or Pro 20x), credits, and primary/secondary rate-limit windows with used-percent bars and reset times, fetched from the account-scoped ChatGPT endpoint.
• Banked rate-limit resets. View how many resets the account has banked and their earliest expiry, then redeem one from a confirmation dialog to restore the 5-hour and weekly limit windows.
• Proxy-aware networking. Auto-detects environment and system proxies (macOS / Windows / Linux), routes only OpenAI traffic through them, keeps loopback direct, and exposes an explicit proxy mode (auto / environment / off).
• Reliability-first defaults. SSE transport by default (no partial-output duplication on WebSocket failure), 5-minute stream idle timeout, configurable retry policy.
• Native Settings page at Plugins → DSH Codex Suite → codex-provider with zh/en localization, live status, and a loopback-only RPC boundary — credentials never leave the Host.

Conversation UI — enhancements within native DSH chat

• Native presentation. DSH owns tool groups, work-details modes, process folding, running status, and viewport restoration.
• Two reveal modes. typewriter (default) progressively reveals graphemes with three presets and a configurable rate; teleprompter displays current snapshots. After a turn settles, the remaining queue drains at a faster settle rate before switching to the full snapshot, including stopped, failed, and reduced-motion paths.
• Thinking preference. The persisted auto-expand setting opens native streaming reasoning; readers can still collapse it manually.
• Native assistant features. Markdown, images, file mentions, stopped markers, and final-answer actions retain DSH behavior.
• Deliverables card. Completed turns list file edits and websites with real added/removed line counts. When DSH’s native changed-files card is active, files belong to that card (including diff preview and review) and the plugin adds websites only, so one turn never shows two file cards. Relative and absolute spellings of one file are merged.

---

Plugin display metadata is exported as locale/en.json and locale/zh.json, using meta.title and meta.description. DSH localizes the plugin list, details, and component names; the ordinary package description remains English for npm.

The manifest declares a packaged SVG with icon: "./icon.svg". The suite and both components use the teal code mark.

Installation

Prerequisites: DeepSeek Harness (dsh) >=0.2.0-rc.2 <0.3.0-0 with the web profile, Node.js ^22.19 || >=24, pnpm 11.

Install the whole suite (recommended):

dsh plugin --profile web add @jcy2387/dsh-suite@0.2.1-rc.2
dsh web

Or install plugins individually:

dsh plugin --profile web add @jcy2387/dsh-codex-provider@0.2.1-rc.2
dsh plugin --profile web add @jcy2387/dsh-conversation-ui@0.2.1-rc.2
dsh web

Local development — link a workspace package instead of the published one:

dsh plugin --profile web add link:$PWD/packages/codex-provider
dsh plugin --profile web add link:$PWD/packages/conversation-ui
dsh web

Install either the suite or the individual plugins in a given profile. The suite registers codex-provider and conversation-ui directly; installing their standalone bundles alongside it declares duplicate loader entry ids and prevents startup. Restart dsh after any bundle-list change.

When upgrading from the grouped suite, remove overlays targeting suite-plugins; configure codex-provider and conversation-ui directly. Plugin ids, saved preferences, credentials, and session data remain unchanged.

Quick start

1. Install the suite (see above) and open the Web UI (dsh web).
2. Go to Plugins → DSH Codex Suite → codex-provider, click Connect, and choose Browser login (or Device login on a headless/remote machine). Complete the ChatGPT authorization.
3. Back in the chat, pick an openai-codex model in the model selector and start talking.
4. Optional: review the usage panel in the same settings page, and tune the conversation stream in Plugins → DSH Codex Suite (or Conversation UI).

Configuration

Both plugins read deployment defaults from the profile's cordis.patch.yml overlay. Conversation UI's mode, preset, revealCharsPerSec, and auto-expand thinking are also live, durable preferences in the plugin settings card.

Codex Provider (profile patch ID: codex-provider)

Conversation UI (profile patch ID: conversation-ui)

To temporarily disable the Conversation UI without uninstalling it, apply the bundled conversation-ui-off.yml overlay:

- id: conversation-ui
  disabled: true

Settings surfaces

Architecture

Each runtime plugin ships two halves:

• Host half (Node) — Cordis plugin: provider registration, OAuth lifecycle, networking, settings persistence. Loaded from the package root.
• Web half (browser) — React views discovered through the dsh.client manifest. The Codex Provider contributes the Settings section; the Conversation UI replaces the assistant node view and wraps tool rows.

The halves communicate through two narrow channels: an inline boot-config global (window.__DSH_CONVERSATION_UI_CONFIG__) injected into the served HTML carries validated plugin config to the browser, and the authenticated Connection RPC carries settings reads/writes back to the Host. Secrets (tokens, proxy URLs) never cross the RPC boundary.

Package-level docs: codex-provider · conversation-ui · suite

DSH 0.2.1-rc.2 compatibility

The provider uses pi-ai 1.3.0, matching the DSH adapter. The Conversation UI leaves live status and scrolling to DSH 0.2 and uses its localized duration units for completed Turns, including stopped and failed outcomes. The provider, Conversation UI, and Suite were booted together with the Models and Logistics plugins in an isolated DSH 0.2.1-rc.2 Web profile; all three plugin settings pages rendered without browser console errors. Restart DSH after replacing an older plugin version.

DSH 0.1.7-rc.2 startup

Upgrade the Suite to 0.1.7-rc.2 when running DSH 0.1.7-rc.2. Suite 0.1.7-rc.1 installed DSH dsh-settings 0.1.7-rc.1 beside the host, and the newer host disables that incompatible copy, leaving Codex Provider waiting for Settings. The updated Suite uses the host's Settings service. Restart DSH after updating the plugin.

Upgrading to DSH 0.1.7-rc.1

On the first start of each profile, the plugins import openai-codex.proxyMode and conversation-ui.thinkAutoExpand from $DSH_HOME/settings.yaml, falling back to settings.yaml.imported when the live file is absent. Values are written to that profile’s cordis.patch.yml; the compatibility import only fills missing profile values. A successful import records a .plugin-settings-migrations/ marker so later resets are not undone. Failed imports retain the source and retry on restart. DSH’s own importer renames the old file to .imported; back up DSH_HOME before upgrading.

The provider keeps using OPENAI_CODEX_OAUTH in the original credential store; no credential is moved or deleted. Sessions and attachments remain owned by DSH and are not rewritten by this plugin. Keep the same DSH_HOME to retain them. Account and proxy controls live on the plugin’s codex-provider component page; conversation preferences live on the Suite or standalone Conversation UI configuration page.

Development

Requirements: Node.js ^22.19.0 || >=24.0.0 and pnpm 11.7.

pnpm install
pnpm run check        # typecheck + test + build + pack dry-run, same as CI

Per-package commands:

pnpm --filter @jcy2387/dsh-codex-provider check      # typecheck + test + build + publint
pnpm --filter @jcy2387/dsh-conversation-ui typecheck
pnpm --filter @jcy2387/dsh-conversation-ui test
pnpm --filter @jcy2387/dsh-conversation-ui build
pnpm --dir packages/all pack --dry-run

Tests run on vitest — 17 suites covering the OAuth state machine, token refresh, network/proxy detection, usage and banked-reset parsing, the settings controllers, and the streaming client views. Client tests resolve the installed published DSH packages (a small module-table stand-in instantiates the shipped browser factory bundles). CI verifies release tags match all three package versions and audits the published tarball contents, then runs a consumer smoke test that installs the packed tarballs into a scratch project (resolving the published peer ranges against the real registry) and imports every Node-side entry point.

Release

Publishing is automated by the Release workflow (.github/workflows/release.yml), which runs whenever a GitHub Release is published. It requires the release tag to equal the shared version of all three packages (an optional v prefix is stripped), re-runs the full quality gates, packs the three tarballs, verifies the suite bundle no longer carries workspace: ranges, and publishes to npm in dependency order (provider → conversation UI → suite) with provenance via OIDC trusted publishing — no long-lived NPM_TOKEN secret is involved.

One-time setup: configure trusted publishing on npmjs.com for @jcy2387/dsh-codex-provider, @jcy2387/dsh-conversation-ui, and @jcy2387/dsh-suite, each authorizing repository DamonBao/dsh-codex-suite with workflow release.yml (no environment).

The dist-tag follows the GitHub Release's pre-release flag: a full release (checkbox unchecked) publishes under latest — including rc versions — while a pre-release publishes under the channel tag derived from the version (0.1.2-alpha.4 → alpha, 0.1.2-rc.1 → rc). The workflow is idempotent — a package whose version already exists on npm is skipped, so a re-run after a partial failure republishes only what is missing.

A typical release:

# bump the version in all three packages/*/package.json files, then:
pnpm run check
VERSION="$(node -p "require('./packages/codex-provider/package.json').version")"
git commit -am "release: $VERSION"
git tag "$VERSION"
git push origin main --tags

Then create and publish a GitHub Release for that tag. Dependabot checks GitHub Actions dependencies weekly. npm version updates are intentionally not enabled for Dependabot: it regenerates pnpm-lock.yaml without the workspace overrides, so its PRs cannot pass pnpm install --frozen-lockfile — bump dependencies manually with pnpm update.

Repository layout

.
├─ packages/
│  ├─ codex-provider/     # @jcy2387/dsh-codex-provider
│  │  ├─ src/             # Host half: OAuth, refresh, network, usage, banked resets, LLM adapter
│  │  ├─ src/client/      # Web half: Settings section UI
│  │  ├─ tests/           # 12 vitest suites
│  │  └─ cordis.patch.yml
│  ├─ conversation-ui/    # @jcy2387/dsh-conversation-ui
│  │  ├─ src/             # Host half: config bridge, settings RPC
│  │  ├─ src/client/      # Web half: stream views, cards, native-scroll bridge
│  │  ├─ tests/           # 3 vitest suites
│  │  └─ cordis.patch.yml
│  └─ all/                # @jcy2387/dsh-suite (pure bundle, no runtime code)
├─ .github/workflows/ci.yml       # validate + tarball audit + consumer smoke
├─ .github/workflows/release.yml  # npm publish on GitHub Release
├─ pnpm-workspace.yaml
└─ README.md / README.zh.md

Troubleshooting

• Browser login never completes — the callback bridge listens on 127.0.0.1:1455; make sure the port is free and the browser can reach loopback. The settings page classifies the exact failure (port conflict, timeout, state mismatch…).
• Region not supported — OpenAI rejects the login for unsupported regions; the settings page surfaces this as a distinct reason. A proxy (proxyMode) can change the egress route (restart required).
• reauth required after some time — the refresh token expired or was revoked (e.g. password change). Reconnect once from the settings page.

License

MIT © jcy2387