dsh-openai-codex

OpenAI Codex (ChatGPT subscription) authentication and LLM provider for deepseek-harness.

This plugin adds:

1. A Settings card (web) with a “Sign in with OpenAI Codex” button — OAuth against auth.openai.com, backed by your ChatGPT/Codex subscription.
2. The codex LLM provider, exposing subscription models (e.g. gpt-5.5) to any model-routing configuration in DSH.

There is no API key to paste: the plugin performs the same OAuth sign-in flow as the Codex CLI (browser or device code), then keeps the credential refreshed in DSH's own credential store.

---

Install

From inside a DSH profile directory (or with --profile), add the plugin bundle:

dsh plugin --profile <name> add ./dsh-openai-codex

This consumes the bundle's patch (cordis.patch.yml), installing the openai-codex plugin and wiring its client (Settings card). After install, refresh the web GUI.

Authenticate

1. Open Settings → Plugins (or the provider settings card).
2. In the OpenAI Codex card, click Sign in with OpenAI Codex.
   • A browser tab opens to auth.openai.com (interactive login). Or use Device code to get a one-time code to enter at https://auth.openai.com/codex/device.
3. Grant access; the plugin stores the OAuth credential envelope in DSH's credential store ($DSH_HOME/.credentials.yaml). The account id is derived from the access-token JWT and used for the chatgpt-account-id header.

On sign-out, the stored credential is cleared.

Use the provider

Select provider codex and a model in your model-routing config, e.g. in cordis.yml:

llm:
  routes:
    - provider: codex
      model: gpt-5.5

Available catalog models (configurable under the openai-codex settings namespace): gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, gpt-5.2, gpt-5-4-mini.

Configuration

All keys live under the plugin's settings namespace. With openai-codex scoped globally, you can set defaults directly:

openai-codex:
  # Reasoning effort applied when a request omits one.
  reasoningEffort: high   # off | low | medium | high | max
  # Default output budget.
  maxTokens: 128000
  # Advisory context window for models without an exact catalog value.
  defaultContextWindow: 400000
  # Text verbosity.
  verbosity: low          # low | medium | high
  # Refresh the access token this far before expiry.
  refreshBeforeMs: 300000
  # Drop an in-flight request after this much provider idle time.
  streamIdleTimeoutMs: 30000
  # Override the codex Responses endpoint (advanced/debugging).
  baseURL: https://chatgpt.com/backend-api/codex/responses

Unset optional keys (reasoningEffort, verbosity, retryPolicy) fall back to provider defaults.

How it works

• Host half (src/index.ts): registers the codex LLM adapter + a configurable provider, the credential store (OPENAI_CODEX_CREDENTIAL), a settings namespace, and an RPC channel (/rpc-codex) the Settings card calls to start/poll OAuth.
• Client half (src/client): a React card injected into settings.plugin.item; talks to the Host through the generic Connection RPC bridge (authority: loopback).
• OAuth (src/oauth): PKCE S256; interactive browser redirect to http://127.0.0.1:1455/auth/callback or the device-code flow; token refresh via the refresh_token grant.
• Codex wire (src/codex): POST /backend-api/codex/responses, SSE, parsed with eventsource-parser; Responses events are translated into harness StreamChunks (text / reasoning / tool-call blocks, usage-before-finish).

Development

This checkout is a standalone package whose @deepseek-ai/* peer deps resolve from a deepseek-harness checkout when installed into a profile (via dsh plugin add), and from that same checkout's node_modules (symlinked under node_modules/) when building/testing locally. The .npmrc sets verify-deps-before-run=false so pnpm doesn't try to re-install the peer deps here — do not run pnpm install in this directory expecting it to fetch them from npm.

pnpm build       # emits lib/index.js (Host ESM) + lib/client.js (browser bundle)
pnpm typecheck   # tsc --noEmit over src + tests
pnpm test        # vitest run (unit tests)

Before the first local build/typecheck/test, node_modules must expose the toolchain and the @deepseek-ai/* sources. Recreate the symlink farm once, pointing at your deepseek-harness checkout:

scripts/setup-local-dev.sh /absolute/path/to/deepseek-harness

The build ships the prebuilt lib/, so end users installing via dsh plugin add never need to build.

The browser client bundle artifact is the loader-wrapped CJS (window.__ModuleLoader__.load({ id, factory: (require) => … })) the client-module system serves at /plugins/dsh-openai-codex/client.js.

Layout

src/index.ts            Host plugin entry (apply)
src/oauth/              PKCE, JWT account-id, callback server, OAuth flows
src/codex/              Responses wire: types, serialization, SSE, translate
src/codex/adapter.ts    LlmAdapter implementing stream/listModels/resolveModel
src/client/             Settings card, RPC bridge, locales
test/                   unit tests (vitest)

Notes / caveats

• The interactive login binds a localhost port (1455) to catch the OAuth redirect. A firewall or container can prevent this; the device-code flow is the portable fallback.
• Codex streams are long-lived; the adapter ties liveness to a per-request idle timeout and honors DSH's request abort signal.
• OAuth token expiry cannot be observed by this plugin in this environment; expiry is derived from the issued expires_in, and refresh is re-attempted pre-emptively before each request near expiry.