# @signalight/dsh-codex-pet A **DSH web-GUI pet runtime plugin** — one plugin that renders *any* Codex spritesheet-atlas pet (v1 / v2) as a draggable desktop pet in the DeepSeek Harness web GUI. It is the runtime half of the [`codex-to-dsh-pet`](https://github.com/Signalight/codex-to-dsh-pet) framework: instead of building each pet into its own plugin bundle, you install this plugin **once**, then add pets as plain data files — no per-pet code. > The plugin ships one built-in example pet **`nastya` (娜斯佳)** — an original > character (CC BY-NC 4.0, non-commercial) — so the registry is never empty. > See `assets/nastya/`. ## Features - Renders Codex spritesheet atlases (8 columns × 192×208 cells): - **v1** (1536×1872, 9 rows) — auto-detected; - **v2** (1536×2288, 11 rows) — adds 16 mouse-tracking "look" cells. - Draggable (position persists across restarts), wave-on-hover, jump-on-double-click. - **Opt-in mouse tracking (v2 only, default on)**: the «桌宠» settings section has an **Eye tracking** toggle; the UI notes it applies to v2 atlases only (v1 has no look cells, so the toggle is inert for v1 pets). - Live activity poses: idle / waiting / running / review, driven by the conversation state. - Progress bubble showing the running tool name or the live model text tail. - Optional fixed-interval first-person LLM summaries, with a per-session journal shown when hovering the pet. Automatic summaries observe only requests completed after selecting a session; they do not backfill historical conversations. Right- click the pet to explicitly analyze prior unsummarized requests. This is disabled by default. Enabling it sends bounded excerpts of user, assistant, tool, and error content to the selected LLM and incurs that provider's usage/cost. Select a provider and model before enabling summaries. Cadence and bubble duration are configurable. - Configurable completion, error and interruption voices, including per-track volume, bundled rotating takes and user-uploaded audio overrides. - Zero per-pet code: the browser half is registry-driven from `/api/codex-pet/*`. ## DSH compatibility DSH gates every profile plugin row on its `@deepseek-ai/dsh*` **peerDependencies**: a peer range the running DSH version does not satisfy disables the **whole row** (no pet, no settings section) with `Plugin … is incompatible with dsh …: peerDependencies …`. This plugin therefore declares only peers that exist across the DSH 0.2 line and later, with open-ended ranges: ```json "@deepseek-ai/dsh-client-ui-slots": ">=0.1.0-rc.6", "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.6" ``` It works on **0.1.x** and on **0.2.0-rc.1+**. The obsolete `@deepseek-ai/dsh-client-runtime` peer is *not* declared: DSH 0.2.0-rc.1 removed that package, so declaring it (`^0.1.0-rc.6`, as 0.3.1 did) makes DSH disable the row — which is exactly why the pet vanished on 0.2.0-rc.1. The same upgrade also **retired the client runtime at runtime**, not just in the manifest. On 0.1.x the pet overlay read the conversation from `sessions.currentProvideInfo`; that bridge is gone in the 0.2 line, which would leave the snapshot `null` and the bubble permanently blank (0.3.2 had this bug — the pet appeared but never spoke). The overlay now reads the internal `uiSession` service's main binding instead: - `hooks.chat` → the live tail (`partial`, `runningCalls`) plus `turnEnds`; this is the target `dsh-client-ui-chat` registers, i.e. the streaming reply text and the "running: \" bubble text; - `hooks.trajectory` → the same fields plus `requests`, kept as a fallback when the chat hook is absent (its own `partial` only fills in once its target has accumulated chunks); - `hooks.session` → `running`, `pendingSubmissions`, `openState`; - `nodes` / `turnEnds` are rebuilt from the trajectory event nodes, keeping the done chime and the periodic summaries working. `ui-trajectory` pushes the **finalized node itself** into `eventNodes` (`{ kind: "user" | "assistant" | "tool-result", seq, turn, step, blocks, … }`), so that is the shape read here; the older `{ data: { kind, node } }` contribution wrapper is still accepted as a fallback. Reading only the wrapper is what made every summary claim the pet had done nothing (0.4.1 and earlier): the node array came out empty, so the summarizer received no instruction, no reply text and no tool calls. `uiSession` is deliberately **not** listed in `inject`: it is an internal service that older hosts never provide, and Cordis parks the entire plugin when a hard dependency is missing. It is resolved lazily with `ctx.get("uiSession")` (plus a short polling subscribe, because the service can arrive after the plugin loads), and when it never shows up the overlay falls back to the legacy `currentProvideInfo` path — so one build serves both hosts. ## Install **Recommended — one command (needs pnpm):** ```powershell # from npm dsh plugin --profile web add @signalight/dsh-codex-pet # or straight from GitHub dsh plugin --profile web add github:Signalight/codex-to-dsh-pet#path:/packages/dsh-codex-pet ``` **Manual route (no pnpm):** from the repository root run ```powershell .\install-runtime.ps1 ``` This copies the package into `~/.dsh/profiles/node_modules/@signalight/dsh-codex-pet` and registers the plugin row in `~/.dsh/profiles/web/cordis.patch.yml`. Then: 1. Hard-refresh `http://127.0.0.1:3080` (Ctrl+Shift+R) — the DSH profile hot-reloads `cordis.patch.yml`. If the pet still doesn't show, fully quit and relaunch the DSH desktop app (command-line users can restart `dsh web`). Rollback: delete `~/.dsh/profiles/node_modules/@signalight/dsh-codex-pet` and restore the `.bak` next to the patch file. ## Add a pet A pet is a folder holding a `pet.json` manifest plus one atlas image. Drop it into any source (later sources override earlier ones on id collision): - built-in: `packages/dsh-codex-pet/assets//` - Codex pets: `~/.codex/pets//` — read **in place**, nothing is copied; point `CODEX_HOME` elsewhere to use a different Codex home - user: `~/.dsh/pets//` (survives plugin updates) Resolution order is **built-in → Codex → user**, so a pet you import overrides the same id coming from Codex, which overrides the bundled example. The settings surface groups the gallery by these three sources and puts a `v1` / `v2` badge on every card. `pet.json`: ```json { "id": "nastya", "displayName": "娜斯佳", "description": "娜斯佳 Nastya — original character (CC BY-NC 4.0).", "spritesheetPath": "spritesheet.webp", "spriteVersionNumber": 2, "size": 120, "pin": "bottom-right" } ``` Only `id` and `spritesheetPath` are required. `spriteVersionNumber` is auto-detected from the image dimensions when omitted (1536×1872 = v1, nine rows; 1536×2288 = v2, eleven rows); `size` (px width) and `pin` (`top-left` / `bottom-right` / …) default to `120` and `bottom-right`. ### Reading local Codex pets `GET /api/codex-pet/state` reports `codexPets: { enabled }` and `codexPetsDir`, and `POST /api/codex-pet/set-config` accepts `{ "codexPets": { "enabled": false } }` to stop reading them (the default is `true`). Toggling the source rebuilds the registry immediately and re-seats a selection that no longer exists, so the pet never points at a vanished atlas. `resetAll()` puts the switch back to its default. The browser half renders the picker as a gallery: each card shows the atlas's first cell as a thumbnail, mounted only while the card is near the viewport (`IntersectionObserver`, `rootMargin: 300px`) and unmounted once it scrolls away — a decoded atlas is roughly 14 MB, so keeping a dozen of them alive would stall the settings page. **No manual editing needed**: in the DSH settings surface open the «桌宠» section and click **导入桌宠 (webp / png / gif)** — the plugin writes the file into `~/.dsh/pets//`, auto-detects the atlas version, and selects the new pet. The pet id comes from the filename (`my-pet.webp` → `my-pet`); if that id is already taken the plugin appends a `-2` / `-3` suffix instead of overwriting the earlier pet (all Codex atlases are named `spritesheet.webp`, so without this every import would clobber the previous one). Re-importing the same id with the same typed display name updates that pet in place. ## Architecture ``` src/ ├── index.js host half: name/inject/apply, mounts service + routes ├── registry.js scans assets/* + ~/.dsh/pets/*, normalizes Codex atlases ├── service.js persisted selection + display config (~/.dsh/codex-pet.json) ├── routes.js /api/codex-pet/* JSON API + /codex-pet//* assets └── client.js browser half: registry-driven overlay renderer ``` - **Host half** registers same-origin routes via the DSH web server (`ctx.webServer.register`), serving the pet list, state and atlas assets. - **Browser half** fetches `/api/codex-pet/state`, renders the selected pet, mirrors drags back via `POST /api/codex-pet/set-config`, and seats a `settings.section` entry («桌宠») that edits the pet through the same API. It also carries the two recovery buttons (position / everything) under «还原 Reset», and re-seats the pet in place whenever the host bumps `display.layoutRev` — a dragged `left`/`top` outranks the pin, so clearing it changes none of the fields the pet is recreated for. Bubbles, the journal and the context menu are absolutely positioned with no default coordinates, so the rule is **place first, show second**: a reveal reads the pet's live rect, falls back to the placement the controller recorded (`controller.box`, also used to seat the pet itself when a pin is empty or unknown), and otherwise keeps the element hidden while retrying every 100 ms for up to 1.2 s. An unplaced overlay would render at the host origin, i.e. the top-left corner of the screen. ### API | Endpoint | Method | Purpose | | --- | --- | --- | | `/api/codex-pet/pets` | GET | pet registry (list of definitions) | | `/api/codex-pet/state` | GET | selected pet, display config, `codexPets` switch + `codexPetsDir`, pet list with `source` / `spriteVersionNumber` | | `/api/codex-pet/set-pet` | POST | `{ petId }` — switch pet | | `/api/codex-pet/set-config` | POST | update display, `summary`, `sound`, or `{ codexPets: { enabled } }` | | `/api/codex-pet/set-visible` | POST | `{ visible }` | | `/api/codex-pet/reset-position` | POST | drop a dragged `left`/`top` so the pet is re-seated by its pin | | `/api/codex-pet/reset-all` | POST | restore every setting to its default; pet choice and imported files stay | | `/api/codex-pet/import?id=&name=` | POST | raw image body — import a Codex atlas | | `/api/codex-pet/models` | GET | available LLM providers and models for summaries | | `/api/codex-pet/summarize` | POST | summarize one completed assistant-request batch | | `/api/codex-pet/journal?session=&limit=` | GET | recent persisted summaries (`&all=1` returns all records for manual coverage checks) | | `/api/codex-pet/sound?track=` | POST | upload a raw audio override (8 MiB maximum) | | `/api/codex-pet/reset-sound?track=` | POST | remove an audio override | | `/codex-pet-sound?track=` | GET | stream the effective `done`, `error`, or `interrupt` track | | `/codex-pet//` | GET | pet.json + spritesheet assets | Summary journals are stored under `~/.dsh/codex-pet-journal/`. Uploaded voice overrides are stored under `~/.dsh/pets/sounds/` and survive plugin updates. ## Roadmap - [x] Settings section («桌宠» in the DSH settings surface: pet selector, show/hide, size, corner pin, bubble color/opacity, **eye tracking** — the last is v2-only and noted as such), backed by the plugin's own API. - [x] In-GUI import button (upload a Codex atlas → auto-detect → install → select). - [x] Read the local Codex pet folder (`~/.codex/pets`) automatically, with a thumbnail gallery, `v1` / `v2` badges and a default-on switch. - [ ] In-GUI preview before import (live canvas frame preview). - [x] Published to npm (`@signalight/dsh-codex-pet`) + `dsh-plugin` GitHub topic. ## License MIT — see the repository root `LICENSE`. ### Built-in scenario voice / sound assets The plugin ships 8 built-in scenario sounds under `assets/sounds/` (`done-1~4.wav`, `error.wav`, `interrupt-1~3.wav`): - **Attribution**: these sounds were generated by contributor **@yabo083** (PR #4) using **Qwen3-TTS VoiceDesign** and submitted with the plugin; they were reviewed and accepted into this package, and are distributed under MIT together with the plugin. - **Generator license**: the Qwen3-TTS model repo is [Apache-2.0](https://github.com/QwenLM/Qwen3-TTS/blob/main/LICENSE); that license applies to the model repo only and does **not** change this project's license. Using Qwen3-TTS does not imply endorsement by Qwen. - **Relationship to the character**: these lines are usually performed as the built-in example pet `nastya` (娜斯佳). That character is an **original character**, and its atlas is licensed **CC BY-NC 4.0** (non-commercial), so even though the sound files are MIT-licensed, using them as that character's voice keeps the character's **non-commercial** restriction in force; ask the character's author before any commercial use. - **User audio**: you may upload your own audio to replace any scenario sound (Settings → 完成提示音); custom audio's copyright and license are your own responsibility.