dsh-openai-live

GPT-Live-1 full-duplex voice for DeepSeek Harness.

Status: pre-release. Verified against the live API, not against documentation. 168 tests, a per-file 100% coverage gate that is enforced rather than reported, and a built-artifact smoke that runs the published output under plain node. Not yet published to npm.

Why this exists

DeepSeek Harness ships no full-duplex speech subsystem at all, and no plugin in the ecosystem implements gpt-live-1 — the only live, non-sunsetting full-duplex voice model. The nearest existing plugin targets the retiring gpt-realtime family at a different endpoint with a different event vocabulary. This is that port.

The interesting part is not the audio. It is that the model can delegate: mid-conversation it raises a task for the host agent and waits to be answered, without stopping the conversation. Getting that envelope right — and failing closed when it cannot be answered — is the domain of this project.

The seam, not a monolith

Three packages, mirroring how DSH itself models ctx.llm:

Package	Role
dsh-realtime	The seam. Registers the realtime service; owns providers, routes, and session lifecycle. Deliberately refuses to own turn-taking, endpointing, or any auto-answer path for a delegation.
dsh-realtime-openai	The GPT-Live-1 adapter. Wire types, transport, translation, and the session — four separable layers, with the translation layer pure and tested against recorded frames.
dsh-realtime-replay	The keyless backend. Plays a recorded session through the real adapter and session, so conformance runs in CI with no credential, no network, and no spend.

A fourth package, dsh-openai-live (this repo's root), is a bundle: it carries the cordis.patch.yml that mounts the two rows above and depends on all three.

Install

dsh plugin --profile <name> add dsh-openai-live      # once published
dsh --profile <name> --dump-config                   # composes?
dsh --profile <name> web

Then supply the credential from the environment — it is a validated config field, never a file this code reads:

export OPENAI_LIVE_API_KEY=…

A profile composes fine without one. The route registers, and opening a session fails with MISSING_CREDENTIAL — an error that names the setting and never the value. That is deliberate: an unconfigured machine should boot and then say precisely what is missing, rather than break the harness at startup.

Properties held to, and tested

1. Fail-closed delegation. An unresolvable or erroring delegation never auto-approves.
2. The provider owns the turn boundary. There is no hand-rolled VAD, and the seam refuses end-of-utterance calls outright — session.input_audio.commit does not exist in the API, which the server itself confirmed by enumerating its vocabulary.
3. Credentials are a tested invariant, not a convention. The credential error names the setting. No value reaches a log, a fixture, a commit, or a published tarball.
4. Keyless replay. The full conversation path is exercised with no API key present.
5. Drift canary. A scheduled check fails loudly when the provider changes shape, so the first signal is a red build rather than a user bug report.
6. Appends resolve on the provider's acknowledgement, correlated on the echoed client_event_id with a FIFO fallback — an undocumented echo must degrade to ordering, never to a hung promise.
7. Usage is cumulative, so a consumer replaces its figure rather than adding to it. The same value legitimately arrives twice, on session.usage.updated and again on session.closed.
8. Every registry proves disposal — a contribution is made from a child fiber, that fiber is disposed, and the contribution is observed gone.

Verified against the live API

The docs/ directory is the primary record. Everything in it was measured, and the traps each cost a run:

Document	What it holds
docs/protocol.md	GPT-Live-1 over WebSocket: the full client and server vocabulary, the delegation envelope, audio formats, and the traps
docs/design.md	architecture, scope, session lifecycle
docs/decisions.md	ADRs — why client delegation, why a seam, why this repo is non-governed
docs/w1-entitlement-probe.md	entitlement, and why a zero balance is not an entitlement failure
docs/w1-delegation-envelope.md	the two delegation modes, measured

Working on it

pnpm install
pnpm gate      # build → typecheck (src AND tests) → coverage gate → built-artifact smoke
pnpm canary    # live drift check; self-skips without OPENAI_LIVE_API_KEY

The gate enforces per-file 100% statements, branches, functions and lines. That is enforced with perFile: true, and the enforcement was proven to bite: one injected uncovered branch exits 1 naming the file and each axis. Beyond unit tests there are two tiers a change cannot skip — a real composition test that boots a cordis.yml through the actual Loader, and a built-artifact smoke that runs the published lib/ under plain node.

See CONTRIBUTING.md.

Security

No credential is stored in this repository. .gitignore was committed before the first tracked file, and the full history is secret-scanned in CI — a secret removed in a later commit is still published. Report a vulnerability per SECURITY.md.

Licence

MIT — see LICENSE.