| 1 | # DeepSeek Harness connected through Codewhale |
| 2 | |
| 3 | `codewhale integrations dsh …` connects a user's **existing** official DeepSeek |
| 4 | Harness installation (`dsh`, npm `@deepseek-ai/dsh`) to their Codewhale setup. |
| 5 | DSH stays an integrated harness surface. Codewhale remains the owner of Fleet |
| 6 | configuration, provider/model selection, permissions, credentials, and |
| 7 | lifecycle authority; DSH is not a second Fleet scheduler and never an |
| 8 | authority bypass. |
| 9 | |
| 10 | Verified against `dsh 0.1.0-rc.6` (the latest published release at the time |
| 11 | of writing). DSH is a developer preview that warns of compatibility-breaking |
| 12 | changes; a newer `dsh` is reported as `stale-version` (launchable, unverified), |
| 13 | an older one or one without `--patch` as `incompatible`. |
| 14 | |
| 15 | ## What is (and is not) connected |
| 16 | |
| 17 | Codewhale uses only DSH's documented seams: |
| 18 | |
| 19 | | Seam | How Codewhale uses it | |
| 20 | | --- | --- | |
| 21 | | `dsh --version` / `dsh --help` | read-only detection (never initializes a profile) | |
| 22 | | `$DSH_HOME` (or `~/.dsh`) | read-only inventory: profile names, `settings.yaml` top-level namespaces, whether `.credentials.yaml` exists and is `0600`. Values are never read. | |
| 23 | | `--patch <file>` overlay | Codewhale writes **one** overlay under its own home and passes it at launch | |
| 24 | | `DSH_PERMISSION_MODE` env | mirrors the Codewhale permission posture | |
| 25 | | `--profile web` / `--profile headless` | the two shipped DSH profiles; DSH initializes them itself on first launch (its own documented behavior) | |
| 26 | |
| 27 | Codewhale writes **only** under `$CODEWHALE_HOME/integrations/dsh/` (plus, |
| 28 | with the opt-in plugin path below, whatever `dsh plugin` itself writes into |
| 29 | the dedicated `codewhale` DSH profile): |
| 30 | |
| 31 | - `codewhale.patch.yml` — the overlay. Identity only: provider route, model, |
| 32 | base URL, and (native DeepSeek route) `reasoningEffort`. For every |
| 33 | non-native route it declares a `codewhale-<provider>` route on DSH's |
| 34 | `llm-pi-ai` adapter, naming that route's own wire dialect under `api:` |
| 35 | (`openai-completions`, `openai-responses`, or `anthropic-messages`) and |
| 36 | `apiKeyEnv` naming the provider's canonical environment variable — the |
| 37 | *name*, never the value. Keyless local routes (loopback Ollama / LM Studio |
| 38 | / vLLM / SGLang) carry no credential reference. |
| 39 | - `receipt.json` — the current connection record plus an append-only history |
| 40 | of `connect` / `update` / `disable` / `enable` / `remove` events with the |
| 41 | overlay SHA-256, dsh version, `$DSH_HOME`, mapped identity, permission mode, |
| 42 | and timestamps (see `docs/RECEIPTS.md`). Every event is also appended to |
| 43 | `$CODEWHALE_HOME/audit.log`. |
| 44 | - `bundle/` — only after `install-bundle`; see below. The Codewhale palette |
| 45 | (skin) and the ambient ocean scene live here, in the bundle's client half — |
| 46 | no stylesheet is exported. |
| 47 | |
| 48 | Codewhale **never**: |
| 49 | |
| 50 | - copies, prints, or embeds API keys, OAuth documents, environment secrets, |
| 51 | prompts, or filesystem contents (a `--api-key`/keyring credential Codewhale |
| 52 | itself materialized into the process is stripped from the launched child; |
| 53 | a key the user exported in their own shell is left alone); |
| 54 | - writes to `$DSH_HOME` (settings, credentials, profiles, sessions); |
| 55 | - edits installed `@deepseek-ai/dsh` package files; |
| 56 | - switches to a cloud model or broadens permissions silently. Codewhale |
| 57 | `read-only` → DSH `read-only`; anything else → `workspace-write`; |
| 58 | `danger-full-access` only with `--allow-full-access` **and** a Codewhale |
| 59 | full-access posture (`sandbox_mode = "danger-full-access"` / yolo). |
| 60 | |
| 61 | ## States |
| 62 | |
| 63 | | State | Meaning | Launch | |
| 64 | | --- | --- | --- | |
| 65 | | `not-installed` | `dsh` not on `PATH` | refused | |
| 66 | | `offline` | `dsh` exists but `--version` failed | refused | |
| 67 | | `incompatible` | older than 0.1.0-rc.6 or no `--patch` | refused | |
| 68 | | `detected` | usable dsh, no Codewhale overlay | refused (`connect` first) | |
| 69 | | `connected` | overlay matches the current Codewhale route | allowed | |
| 70 | | `stale-config` | route changed, overlay edited outside Codewhale, or missing | refused (`update`) | |
| 71 | | `stale-version` | connected, but dsh is newer than verified | allowed, unverified | |
| 72 | | `disabled` | overlay kept, launches refused | refused (`enable`) | |
| 73 | |
| 74 | `status`, `plan`, `/setup tools` (Tools and MCP step) and `codewhale doctor` |
| 75 | are side-effect free. |
| 76 | |
| 77 | ## Commands |
| 78 | |
| 79 | ```bash |
| 80 | codewhale integrations dsh status [--json] |
| 81 | codewhale integrations dsh plan [--profile web|headless] [--allow-full-access] [--skin] [--json] |
| 82 | codewhale integrations dsh connect [--profile web|headless] [--allow-full-access] [--skin] [--yes] |
| 83 | codewhale integrations dsh update [--profile …] [--allow-full-access] [--skin true|false] [--ocean true|false] [--yes] |
| 84 | codewhale integrations dsh launch [--profile web|headless] [--dry-run] [-- <dsh app args>] |
| 85 | codewhale integrations dsh disable |
| 86 | codewhale integrations dsh enable |
| 87 | codewhale integrations dsh remove [--yes] |
| 88 | codewhale integrations dsh install-bundle [--app web|headless] [--yes] |
| 89 | codewhale integrations dsh remove-bundle [--yes] |
| 90 | ``` |
| 91 | |
| 92 | `connect`, `update`, and `remove` print the exact plan (files, identity, |
| 93 | permission mode, disclosures, and the overlay text) and require confirmation |
| 94 | (`--yes` when stdin is not a terminal). `launch` runs |
| 95 | `DSH_PERMISSION_MODE=<mode> dsh --profile <p> --patch <overlay> …` in the |
| 96 | Codewhale workspace with the user's own `$DSH_HOME`, so their credentials, |
| 97 | sessions, and profiles remain theirs. |
| 98 | |
| 99 | ### Disclosures the plan makes |
| 100 | |
| 101 | - DSH layers the user's `settings.yaml` sections (`agent-default-model`, |
| 102 | `llm-deepseek`, `llm-pi-ai`) over the overlay per field. If those sections |
| 103 | exist, DSH's saved selection can shadow the pinned identity until it is |
| 104 | cleared in DSH; `status`/`plan` list them. |
| 105 | - Reasoning tiers are mapped only for the native DeepSeek route |
| 106 | (`off|high|max`); hand-declared routes send no effort parameter. |
| 107 | - Wire dialects are carried, never approximated: a Chat Completions route |
| 108 | declares `api: openai-completions`, an OpenAI Responses route (e.g. the |
| 109 | default `deepseek/deepseek-v4-flash`) declares `api: openai-responses`, |
| 110 | and an Anthropic Messages route declares `api: anthropic-messages`. This |
| 111 | follows the installed adapters' own declarations (verified against |
| 112 | `@deepseek-ai/dsh@0.1.0-rc.6`): `@deepseek-ai/dsh-llm-deepseek` — the |
| 113 | `deepseek-official` route — speaks chat completions only (its single wire |
| 114 | call posts to `<baseURL>/chat/completions`, with no protocol switch), |
| 115 | while `@deepseek-ai/dsh-llm-pi-ai`'s hand-declared route schema accepts |
| 116 | exactly `openai-completions | openai-responses | anthropic-messages` for |
| 117 | `api:`. So DeepSeek chat routes ride the native adapter (with reasoning |
| 118 | tiers), and every other dialect — including DeepSeek's own |
| 119 | Responses-dialect models — rides a hand-declared `codewhale-*` pi-ai |
| 120 | route in its own dialect. |
| 121 | - What is refused: base URLs that embed credentials (userinfo or |
| 122 | query/fragment material) are never copied into the overlay; `plan` fails |
| 123 | naming the current `provider/model` and the reason, and `status` shows |
| 124 | carry-ability for the current route before `plan` is ever run. |
| 125 | |
| 126 | ## The DSH plugin path (`install-bundle`) |
| 127 | |
| 128 | `--patch` is Codewhale's default because it needs nothing but the launcher. |
| 129 | The **documented DSH plugin mechanism** is available as an explicit opt-in: |
| 130 | |
| 131 | ```bash |
| 132 | codewhale integrations dsh install-bundle [--app web|headless] [--yes] |
| 133 | codewhale integrations dsh remove-bundle [--yes] |
| 134 | ``` |
| 135 | |
| 136 | `install-bundle` requires an existing connection and `pnpm` on `PATH` (dsh |
| 137 | shells out to it); without pnpm the status reads |
| 138 | `plugin path: not available: pnpm missing …` and the command refuses. It: |
| 139 | |
| 140 | 1. materializes an npm-shaped bundle package under |
| 141 | `$CODEWHALE_HOME/integrations/dsh/bundle/` — `package.json` |
| 142 | (`codewhale-dsh-bundle`, private, MIT, version |
| 143 | `<codewhale version>+dsh.<patch sha12>`, `"dsh": {"bundle": {"patch": |
| 144 | "./cordis.patch.yml"}}`), `cordis.patch.yml` (the identity overlay, |
| 145 | plus one trailing skin insert row when the skin is on — see below), |
| 146 | `README.md`, `NOTICE.md` (DSH MIT notice retained), and, with the skin |
| 147 | on, `lib/index.js` + `lib/client.js` (the palette plugin, with the ocean |
| 148 | scene spliced in unless `--ocean false`); |
| 149 | 2. runs the documented `dsh plugin --profile codewhale add <path>` twice: first |
| 150 | for DSH's own shipped app bundle (`@deepseek-ai/dsh-web-app` or |
| 151 | `dsh-headless`, linked from the installed launcher so the profile can boot; |
| 152 | no network), then for the Codewhale bundle so its rows patch last. DSH |
| 153 | creates the **dedicated** profile `$DSH_HOME/profiles/codewhale` |
| 154 | (`package.json` with `link:` dependencies, `pnpm-lock.yaml`, |
| 155 | `node_modules` links). The user's `web`/`headless` profiles are never |
| 156 | touched; |
| 157 | 3. records an `install_bundle` receipt (profile dir, bundle dir, package |
| 158 | version, patch SHA-256, app bundle source, pnpm version, SHA-256 digest of |
| 159 | the `dsh plugin` output — the output text itself is not stored). |
| 160 | |
| 161 | Afterwards `dsh --profile codewhale` alone carries the identity (verified with |
| 162 | `dsh --profile codewhale --dump-config`), and `launch` prefers that profile |
| 163 | without `--patch`; `launch --profile web|headless` still uses the overlay. |
| 164 | Because the profile dependency is a `link:` to the Codewhale-owned directory, |
| 165 | `update` regenerates `cordis.patch.yml` (and the skin files) in place — no |
| 166 | pnpm run. Stale detection covers the bundle: a modified or missing bundle |
| 167 | patch, a bundle that no longer matches the overlay, a `lib/client.js` that |
| 168 | is missing, modified, present while the receipt says the skin is off, or |
| 169 | carrying/lacking the ocean scene against the receipt's `ocean` decision, or |
| 170 | a profile manifest that stopped listing `codewhale-dsh-bundle` all report |
| 171 | `stale-config`. |
| 172 | |
| 173 | `remove-bundle` runs `dsh plugin --profile codewhale remove |
| 174 | codewhale-dsh-bundle` and deletes only the Codewhale-owned bundle files. The |
| 175 | profile directory itself (and the app bundle link dsh recorded there) is |
| 176 | DSH-owned and is left in place; the receipt says so. `remove` refuses while a |
| 177 | bundle is installed. |
| 178 | |
| 179 | ## Skin (bundle profile, `overrideTokens`) |
| 180 | |
| 181 | DSH 0.1.0-rc.6 has one documented token-level theming seam: |
| 182 | `ThemeService.overrideTokens(source, tokens)` in |
| 183 | `@deepseek-ai/dsh-client-ui-theme`, which stacks a partial `--dsw-alias-*` |
| 184 | layer over the active theme (per-token, later layers win) and returns a |
| 185 | disposer. That is the mechanism the Codewhale skin uses. It is **applied only |
| 186 | through the bundle profile** (`dsh --profile codewhale`); the `--patch` |
| 187 | overlay never carries skin code, so `launch --profile web|headless` stays |
| 188 | overlay-only and stock-themed. |
| 189 | |
| 190 | `install-bundle` turns the skin **on by default**. With the skin on, the |
| 191 | bundle is a dual-face DSH plugin: |
| 192 | |
| 193 | - `package.json` gains `"dsh": {"client": {"platform": "web", "immediately": |
| 194 | true, "inject": ["@deepseek-ai/dsh-client-ui-theme"]}}` and |
| 195 | `"exports": {".": …, "./client": …, "./package.json": …}` (Node exports maps are exhaustive; the loader imports the bare name and dsh-client-modules resolves `<name>/package.json`); |
| 196 | - `lib/index.js` is a no-op Node cordis entry (so the row mounts) and |
| 197 | `lib/client.js` is a plain `window.__ModuleLoader__.load({ id, factory })` |
| 198 | script whose factory calls |
| 199 | `ctx.theme.overrideTokens("codewhale-dsh-bundle", TOKENS)` inside |
| 200 | `ctx.effect` and returns the disposer (`inject: ["theme"]` defers it until |
| 201 | the theme service exists); |
| 202 | - `cordis.patch.yml` ends with |
| 203 | `- insert: [{ id: codewhale-skin, name: codewhale-dsh-bundle }]` after the |
| 204 | identity rows. |
| 205 | |
| 206 | `TOKENS` is a bounded map of `--dsw-alias-*` names (backgrounds, borders, |
| 207 | brand, buttons, labels, error/success/warn states, code blocks, scrollbar, |
| 208 | toast, tooltip) onto light/dark values rendered from the TUI's real palette |
| 209 | (`crates/palette/src`, Blue Stage dark and light) — palette constants |
| 210 | only, no user data or environment. The receipt records `skin: true|false` |
| 211 | and `skin_sha256` (SHA-256 of the rendered `TOKENS` JSON); `package.json` |
| 212 | carries the same hash under `codewhale.skin_sha256`. |
| 213 | |
| 214 | ### Whale Brothers / Codewhale identity |
| 215 | |
| 216 | The skin mounts a small plugin-owned lockup in the top-right corner that says |
| 217 | `WHALE BROTHERS`, `CODEWHALE`, and `× DEEPSEEK HARNESS`. It is additive: it |
| 218 | registers through DSH's frame-wide `shell.overlay` slot and does not replace or |
| 219 | rewrite DeepSeek Harness branding or controls. The lockup uses the active skin |
| 220 | tokens, ignores pointer input, collapses to a compact whale mark below 760 px, |
| 221 | and is removed with the client plugin. |
| 222 | `package.json` records the generated fragment as `codewhale.brand_sha256`. |
| 223 | |
| 224 | ### Ocean scene (whales and glyph fish) |
| 225 | |
| 226 | With the skin on, `lib/client.js` also carries an ambient ocean: a |
| 227 | full-viewport `<canvas>` (`position: fixed; inset: 0; z-index: -1; |
| 228 | pointer-events: none`, painted below `#root` and above the body background) |
| 229 | with a visible depth gradient, one near and one far whale silhouette (blunt |
| 230 | head, low dorsal hump, long pectoral flipper, horizontal fluke flexing ±10°) |
| 231 | gliding slowly across on a gentle sine, biased to the lower half and the top |
| 232 | edge so they never cross the composer card, an occasional short spout of |
| 233 | bubbles from the head, a small school of Codewhale glyph fish (`><>` / |
| 234 | `><o>` in the code font, flocking-lite behind a wandering leader) and faint |
| 235 | rising bubbles. The |
| 236 | palette is the skin's own (`surface_bg`, `accent_primary`, `text_body`, |
| 237 | `text_dim` for light and dark); the scene follows DSH's `theme/change` event |
| 238 | so it flips with the app. |
| 239 | |
| 240 | To let the canvas show through, the client re-issues two background tokens |
| 241 | as translucent rgba over the opaque table while the scene is on: |
| 242 | `--dsw-alias-bg-base` (α 0.42; the frame and the centre column both paint |
| 243 | it) and `--dsw-specific-sidebar-fill` (α 0.78, keeping navigation distinct). |
| 244 | Panels, |
| 245 | composer, code blocks and every other layer stay opaque. Verified live on |
| 246 | dsh 0.1.0-rc.6 in both schemes: no console errors, frames differ, and text |
| 247 | stays legible (see `docs/design/assets/dsh-ocean-{light,dark}.png`). |
| 248 | |
| 249 | Budget: `requestAnimationFrame` capped at ~30 fps, paused while |
| 250 | `document.hidden`, one static frame under `prefers-reduced-motion: reduce`, |
| 251 | device-pixel-ratio aware, no per-frame allocations (typed arrays reused). |
| 252 | The scene ships inside `client.js` because dsh-client-modules serves exactly |
| 253 | one file per client plugin (`/plugins/<id>/client.js`); there is no |
| 254 | `lib/scene.js`. `package.json` records `codewhale.ocean` and |
| 255 | `codewhale.ocean_scene_sha256`; the receipt records `ocean: true|false`. |
| 256 | |
| 257 | Off switches, smallest first: in the browser `localStorage["codewhale.ocean"] |
| 258 | = "off"` (or body class `codewhale-ocean-off`) skips both the canvas and the |
| 259 | translucent tokens on that machine; `window.__codewhaleOcean.stop()` / |
| 260 | `.start()` / `.setIntensity(0..1)` are exposed for the console; and |
| 261 | `codewhale integrations dsh update --ocean false` regenerates `client.js` |
| 262 | without the scene (default on; a bare `update` keeps the previous choice; |
| 263 | `--skin false` implies no scene). |
| 264 | |
| 265 | Escape hatch: `codewhale integrations dsh update --skin false` regenerates |
| 266 | the bundle without the client half and without the insert row (no pnpm run; |
| 267 | the `link:` dependency picks the files up in place); `update --skin true` |
| 268 | turns it back on, and a bare `update` keeps the previous choice. |
| 269 | `install-bundle` itself takes no `--skin` flag. `connect --skin` / `plan |
| 270 | --skin` record the same decision ahead of a later bundle install and write |
| 271 | no extra files. `remove-bundle` deletes the client half with the rest of the |
| 272 | Codewhale-owned bundle files, and the `overrideTokens` layer is disposed |
| 273 | with the plugin, so stock DSH theming returns. |
| 274 | |
| 275 | The 0.9.8 `--skin` CSS/preview export (`codewhale-dsh-skin.css`, |
| 276 | `codewhale-dsh-skin-preview.html`) is gone: `dsh-client-ui-layout` writes |
| 277 | the alias tokens as inline `body.style` properties, so any stylesheet rule |
| 278 | lost to them by construction. `connect`/`update` delete those leftover files |
| 279 | if present. |
| 280 | |
| 281 | ## Removal |
| 282 | |
| 283 | `remove` deletes only the overlay (and any 0.9.8 skin/preview leftovers) |
| 284 | under `$CODEWHALE_HOME/integrations/dsh/`, appends a `remove` receipt, and |
| 285 | never touches `$DSH_HOME` or the installed package. DSH keeps working exactly as |
| 286 | before the connection. |
| 287 | |
| 288 | ## Attribution |
| 289 | |
| 290 | DeepSeek Harness is © 2026 DeepSeek, MIT licensed; the integration invokes the |
| 291 | installed launcher and does not redistribute it. This is not native Codewhale |
| 292 | functionality: every surface labels it "DeepSeek Harness connected through |
| 293 | Codewhale". |
| 294 |