Add DeepSeek Harness (DSH) as CodexHub's fifth fully supported managed client

[NOirBRight]

Summary

Add DeepSeek Harness (DSH) as CodexHub's fifth fully supported managed Gateway client.

This is a product-integration issue, not the Beta4.1 protocol-classifier fix. The DSH/Collaboration name-collision regression is tracked in #429 and should be fixed in Beta4.1. This issue has no Beta4.1 delivery requirement.

Initial qualification target:

• Client: @deepseek-ai/dsh
• Baseline version: 0.1.0-rc.6
• Primary config: ~/.dsh/settings.yaml
• Gateway protocol: OpenAI Responses-compatible
• Supported preset baseline: DSH Standard

Product outcome

DSH appears alongside the four existing supported clients and receives the same first-class CodexHub lifecycle:

• detection and version reporting;
• configuration preview;
• Apply with truthful result;
• readback/reconciliation;
• restore/direct-mode switching;
• model and credential projection;
• real-client qualification and documented support status.

A user must not need to hand-edit settings.yaml, restart CodexHub merely to publish configuration, patch the installed DSH package, or replace DSH-owned tools.

Scope

Client detection and support status

• Detect the dsh executable/package and report the exact installed version.
• Detect ~/.dsh/settings.yaml using platform-correct home/config resolution.
• Initially qualify the pinned baseline version; report newer/unknown config or protocol shapes as unqualified/drifted rather than silently claiming support.
• Add DSH to the UI/client status surface as the fifth client without reordering or regressing existing clients unnecessarily.

Managed configuration

Use the existing managed-client adapter seam and support preview/apply/readback/restore.

CodexHub may own only the fields necessary to route DSH through the local Gateway:

• local Gateway base URL;
• local Gateway client key;
• Responses protocol/provider selection;
• selected canonical model and any required model mapping.

Requirements:

• Preserve unrelated YAML, comments/structure where the existing YAML strategy permits, presets, local tools, prompts, and all user-owned settings.
• Never overwrite DSH upstream credentials or unrelated Provider configuration.
• Use backup plus atomic write.
• Detect concurrent/external edits before destructive replacement.
• Restore at field granularity according to existing ownership rules; do not replace the whole user file with a stale snapshot.
• Mask local and upstream credentials in preview, logs, telemetry, errors, tests, and readback evidence.
• Participate in Gateway-key rotation/republication so a successful Apply leaves DSH and the running Gateway on the same credential generation (see Changing the local Gateway client key is not applied transactionally to the running Gateway and managed Codex client #428).

Protocol and tool ownership

• Route DSH through the normal Responses compatibility path; do not add a Kimi-, model-, User-Agent-, or DSH-specific Gateway routing branch.
• Treat DSH's subagent, subagent_fork, send_message, interrupt_agent, list_agents, and other tools as DSH-owned.
• CodexHub must not rename or namespace-wrap those tools, translate DSH agent IDs into Codex task paths, execute them, or synthesize their results.
• Reuse the generic fix from Fix ordinary DSH tools being misclassified as Codex Collaboration V2 #429 so ordinary DSH tools are not mistaken for Codex Collaboration V2.
• Preserve ordinary function-call and function-result history across continuation.

UX and documentation

• Expose detected version, config location, managed/direct state, selected model, last Apply/readback outcome, and actionable drift/errors.
• Document supported version/preset/protocol boundaries and what CodexHub owns in the YAML.
• Clearly distinguish the local Gateway client key from Kimi/other upstream Provider API keys.
• Document reversible switching between direct DSH use and CodexHub-managed Gateway use.

Acceptance criteria

• DSH is visible as the fifth supported client with accurate installed/version/config status.
• Preview shows only intended owned-field changes and masks all credentials.
• One Apply configures a clean pinned DSH installation for the local Gateway without manual YAML editing.
• Readback proves endpoint, protocol, model, and local key projection match the intended state before reporting success.
• Unrelated YAML, presets, DSH-owned tools, user credentials, and custom settings survive Apply unchanged.
• Restore/direct-mode switching removes or restores only CodexHub-owned fields and is reversible.
• Concurrent modification and version/config drift fail truthfully without clobbering user data.
• A pinned DSH Standard E2E turn succeeds through one native Responses Provider route with exact route identity and no upstream fallback.
• An ordinary function call/result continuation succeeds.
• A DSH subagent/control lifecycle succeeds while DSH remains the executor and owner of its schemas/IDs.
• Exact Codex Collaboration V1/V2 traffic remains unaffected; DSH's same-named ordinary tools are covered by Fix ordinary DSH tools being misclassified as Codex Collaboration V2 #429 regressions.
• Gateway client-key rotation republishes and verifies DSH without restarting CodexHub or manually editing DSH.
• Existing four supported clients retain their current preview/apply/readback/restore behavior.
• Qualification fixtures/evidence contain no prompts, tool arguments/results, credentials, session IDs, or absolute user paths.

Suggested implementation seams

• Add a dedicated Rust managed-client adapter consistent with Split Rust Gateway client adapters into dedicated modules #8 rather than extending unrelated client-specific conditionals.
• Add a headless materialization/readback path for isolated E2E consistent with Expose headless managed-client config materialization for isolated runners #194.
• Reuse the real-client qualification foundation from Add pinned real-client E2E qualification foundation for Gateway candidates #190.
• Add platform-focused YAML preservation and ownership tests plus a packaged Windows smoke test.

Release planning

• Not required for Beta4.1.
• Schedule after Fix ordinary DSH tools being misclassified as Codex Collaboration V2 #429 is integrated and the managed-client/key lifecycle dependencies are ready.
• Do not block or expand the Beta4.1 release solely for this full-client integration.

Related

• Fix ordinary DSH tools being misclassified as Codex Collaboration V2 #429 — Beta4.1 generic Collaboration false-positive fix.
• Changing the local Gateway client key is not applied transactionally to the running Gateway and managed Codex client #428 — transactional Gateway client-key rotation and managed-client republishing.
• Split Rust Gateway client adapters into dedicated modules #8 — managed-client adapter module seam.
• Add pinned real-client E2E qualification foundation for Gateway candidates #190/Expose headless managed-client config materialization for isolated runners #194 — real-client qualification and headless materialization/readback.
• Spike complete Codex model capability exposure on third-party providers #57/0.1.8 Beta2: Implement runtime-derived tool compatibility for custom Responses endpoints #58/0.1.8 Beta2: Define tool-type compatibility rules for custom Responses endpoints #65 — generic tool compatibility contracts.

[NOirBRight]

This was generated by AI during triage.

Triage update — redesigned as Provider Injection (campaign 0.1.9)

The maintainer has redirected this issue: DSH will be integrated under the new Provider Injection semantics, not the Managed Takeover semantics this body's acceptance criteria assumed. Campaign tracking: #436. ADR-0004 records the decision.

Decided design points (grilling session, all settled)

• Injection, not takeover: CodexHub adds one entry under the existing llm-pi-ai.providers map (route key codexhub, api: openai-responses, baseURL, apiKeyEnv, full models list). All user-owned providers (kimi-coding, llm-openai-codex, llm-ollama, ...) stay untouched.
• No activation (Q1=A): Apply never touches agent-default-model. The user switches DSH's default model themselves; CodexHub surfaces the pointing state as read-only information, never as drift.
• Adoption, not conflict (Q4=B): a pre-existing codexhub provider entry pointing at the local Gateway is adopted as the injected block.
• Full model projection (Q5=B): all currently enabled Gateway models are projected into the injected entry and re-projected on catalog change (DSH hot-reloads settings.yaml; no restart).
• Surgical credential write (Q6=A): the Gateway client key goes into ~/.dsh/.credentials.yaml as a single key (CODEXHUB_GATEWAY_KEY), backup + atomic write, masked in all evidence. Key rotation (Changing the local Gateway client key is not applied transactionally to the running Gateway and managed Codex client #428) for DSH = rewrite that one key.
• Surgical detach (Q3=A): removal deletes exactly the injected provider entry + the credential key (+ nothing else). Snapshots degrade to disaster-recovery-only. Readback moves to block fingerprint — see Block-fingerprint readback for injected clients (replace byte-compare) #433.

Acceptance-criteria deltas vs. the original body

• "Restore/direct-mode switching removes or restores only CodexHub-owned fields" — unchanged in letter, now the primary path (not the fallback).
• "Participate in Gateway-key rotation" — now scoped to the credential-file key only; settings.yaml untouched by rotation.
• New: Apply must NOT modify agent-default-model. UI uses a connection metaphor: a connect/disconnect toggle that IS inject/detach (never touches the model-selection switch); no separate active/pointing indicator.
• New: user-added foreign providers must never fail readback or detach.

Phasing

• Phase 1 (0.1.9-beta1): headless detection/injection/detach on the declarative descriptor (Declarative per-client injection descriptor (managed-client adapter seam) #432) with block-fingerprint readback (Block-fingerprint readback for injected clients (replace byte-compare) #433).
• Phase 2 (0.1.9-beta2): real-client qualification (pinned 0.1.0-rc.6, Windows E2E), key rotation, UI fifth client card. Blocked on Fix ordinary DSH tools being misclassified as Codex Collaboration V2 #429 landing.

State: moving to ready-for-human — the remaining work includes Windows real-client qualification and product judgment on UI state presentation.