@luv1211/dsh-pet 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Luv061211
+Copyright (c) DeepSeek AI (DeepSeek Harness, https://github.com/deepseek-ai/deepseek-harness)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/pet/pet/README.md
+README.md: 932fd5ad5e1d2912635ae9cb33123223e7ae3575
+README.zh.md: bb77c78c7dcda4611872c61a629470a564b5e004

package/README.md

@@ -0,0 +1,35 @@
+# @luv1211/dsh-pet
+
+English | [中文](README.zh.md)
+
+Settings-backed desktop-pet domain. It owns the durable pet preference, the validated built-in and user package catalog, and the activity read model consumed by browser and desktop companion clients. The service adds no model-visible state.
+
+## Service contract
+
+`ctx.pets` is the single writer of the global `pet` settings namespace. The durable preference is `{ version: 3, selectedPetId, awake, sizePx }`; a missing section defaults to the awake built-in `deepseek-whale` at 112 CSS pixels. Any stored preference whose version is not 3 fails during service setup instead of being migrated. Empty ids, invalid sizes, and ids absent from the loaded catalog fail during service setup or mutation.
+
+The catalog always contains the embedded `deepseek-whale` package and may contain validated packages under the configured `<dshHome>/pets` root. A package consists of `pet.json` and the WebP named by its safe manifest-relative `spritesheetPath`; the closed manifest accepts `id`, `displayName`, `description`, `spritesheetPath`, `frame`, and `animations`, plus the Codex-authored `kind` and `spriteVersionNumber` fields, which are parsed but ignored. The WebP must be a complete image of 192×208 cells in an 8-column grid; the standard nine-row 1536×1872 atlas and the eleven-row v2 1536×2288 atlas are both accepted, and a manifest without a `frame` derives its rows and columns from the decoded image. The host rejects oversized files from metadata before reading them, checks bounded image headers through `image-dimensions`, fully decodes user-package pixels with Sharp in an isolated process, and enforces identifier, text, containment, and regular-file rules before `@luv1211/dsh-pet-compat` validates geometry, paths, animation frames, and fallbacks. `maxManifestBytes`, `maxSpriteBytes`, and `decodeTimeoutMs` configure the three host-side resource limits. A package directory may be named `<id>.codex-pet` or any other directory name; the manifest id is authoritative, dot-prefixed directories (including stale `.tmp` residue) are skipped, duplicate ids are excluded. User packages are loaded in deterministic id order, malformed packages are excluded silently, and imports validate before publishing through a temporary directory and atomic rename. Catalog descriptors carry their `builtin` or `user` origin, immutable frame and animation metadata, and origin-relative asset URLs. Clients never supply paths — the native picker resolves packages host-side — and the read model exposes exactly one display-only path: the user package root.
+
+`pets.getSnapshot()` returns detached preference, catalog, user package root, host capability flags, and deterministically ordered activity records. `pets.getCatalog()` returns the detached catalog. `pets.selectPet(id)`, `pets.setSize(sizePx)`, and `pets.setAwake(awake)` serialize complete preference writes and return the committed snapshot. `pets.importPetPackage()` asks an optional native host to select package bytes and reports `published`, `cancelled`, or `host-unavailable`. `pets.refreshCatalog()` rescans the user root without a restart; a dropped package that fails validation stays absent without explanation. `pets.updatePetPackage(id)` asks the same native host to pick replacement bytes for one existing user package and swaps them in place through a fixed three-rename sequence: a synchronous failure leaves the old content intact, the package is briefly absent between two renames, and crash residue is a same-id `.tmp` directory that the next replacement of that id sweeps. A picked manifest whose id differs from the target, or any non-user target, fails before anything is written. `pets.openPetFolder()` asks the same host to open the DSH-owned package directory and reports `opened` or `host-unavailable`.
+
+The optional `petActivity` service key supplies a host-owned activity projection. Without it, the domain adapter observes the existing `session/event` and `session/disposed` streams: turn start becomes `running`, blocked or error completion becomes `blocked`, other completion becomes `ready`, and disposal removes the record. A host projection can additionally report pending interaction and user-facing titles. The records are presentation state and are not written back as session events.
+
+Every preference or activity publication emits `pet/update`. Companion clients consume the snapshot and event through the generated `pets` Remote namespace. The desktop companion page (`/__dsh/pet/overlay`) polls `/__dsh/pet/overlay-state`, and its right-click close item tucks the pet through `POST /__dsh/pet/overlay-awake`, which accepts only an `application/json` body of exactly `{ awake: boolean }` so a cross-site POST cannot reach it. Native import and folder actions are capability-gated; browser-only compositions leave the native service absent and expose neither action as available.
+
+## Extension points
+
+Provide `petActivity` when the host already owns a richer session projection. Provide `petNative` only from a trusted local host; its picker returns bytes rather than a client-controlled path, and its folder opener receives the service-owned package root. The desktop companion registry is optional, so the domain also runs in a browser composition with the same catalog and activity Remote API.
+
+## Model Experience
+
+None, as the pet domain stores local preferences and presentation state only.
+
+#### KV Cache effect
+
+None.
+
+## Known Limitations and Deferred Work
+
+- **Default activity fallback** — the built-in adapter covers session lifecycle events; richer pending-interaction and title data requires a host-provided `petActivity` projection.
+- **External catalog edits** — packages are discovered at startup, after an import or replacement, and on an explicit refresh; there is no remove operation, no external-directory watch, and a package that fails validation stays absent without explanation.
+- **Desktop window** — an always-on-top transparent window still requires the Electron companion shell; browser compositions keep the native actions unavailable.

package/README.zh.md

@@ -0,0 +1,35 @@
+# @luv1211/dsh-pet
+
+[English](README.md) | 中文
+
+由 settings 持久化的桌面宠物领域。它拥有持久化宠物偏好、经过校验的内置与用户包目录，以及浏览器和桌面 companion 客户端消费的活动读模型。该服务不新增模型可见状态。
+
+## 服务契约
+
+`ctx.pets` 是全局 `pet` settings 命名空间的唯一写者。持久化偏好为 `{ version: 3, selectedPetId, awake, sizePx }`；缺少该节时默认为已唤醒的内置 `deepseek-whale`，尺寸为 112 CSS 像素。任何版本不是 3 的已存偏好都会在服务启动时失败，不会被迁移。空 id、非法尺寸，以及不在已加载目录中的 id，会在服务启动或变更时失败。
+
+目录始终包含内置 `deepseek-whale`，也可以从配置的 `<dshHome>/pets` 根目录加载经过校验的用户包。一个包由 `pet.json` 和其中安全的清单相对 `spritesheetPath` 所指向的 WebP 组成；封闭清单接受 `id`、`displayName`、`description`、`spritesheetPath`、`frame` 和 `animations`，以及 Codex 生成的 `kind` 与 `spriteVersionNumber` 字段（解析但忽略）。WebP 必须是完整的 8 列图集，单元尺寸 192×208；标准九行的 1536×1872 图集与十一行 v2 的 1536×2288 图集都被接受，清单未提供 `frame` 时依据解码后的图片尺寸推导行与列。宿主在读取文件前根据元数据拒绝超限文件，使用 `image-dimensions` 检查有界图片头，在隔离进程中使用 Sharp 完整解码用户包像素，并执行标识符、文本、目录包含关系和普通文件规则；随后由 `@luv1211/dsh-pet-compat` 校验几何、路径、动画帧和回退。`maxManifestBytes`、`maxSpriteBytes` 和 `decodeTimeoutMs` 配置三项宿主资源限制。包目录可以命名为 `<id>.codex-pet` 或任意其他目录名：清单 id 是权威标识，点开头的目录（包括陈旧的 `.tmp` 残留）会被跳过，重复 id 会被排除。用户包按确定性的 id 顺序加载，格式错误的包会被静默排除；导入会先校验，再通过临时目录和原子重命名发布。目录描述符带有 `builtin` 或 `user` 来源、不可变的帧与动画元数据，以及相对当前 origin 的资源 URL。客户端永不提供路径 —— 原生选择器在宿主侧解析包；读模型只暴露一个仅用于展示的路径：用户包根目录。
+
+`pets.getSnapshot()` 返回分离的偏好、目录、用户包根目录、宿主能力标志和按确定性规则排序的活动记录。`pets.getCatalog()` 返回分离的目录。`pets.selectPet(id)`、`pets.setSize(sizePx)` 和 `pets.setAwake(awake)` 通过完整偏好写入链串行化，并返回已提交的快照。`pets.importPetPackage()` 请求可选的原生宿主选择包字节，并报告 `published`、`cancelled` 或 `host-unavailable`。`pets.refreshCatalog()` 无需重启即重扫用户根目录；放入后校验失败的包不会出现，也没有任何解释。`pets.updatePetPackage(id)` 请求同一原生宿主为某个已存在的用户包挑选替换字节，并通过固定的三步改名序列原位换入：同步失败时旧内容保持完整，两次改名之间该包短暂缺席，进程中断的残留是同 id 的 `.tmp` 目录，由该 id 的下一次替换清扫。所选 manifest id 与目标不一致，或目标不是 user 包时，会在写入任何内容之前失败。`pets.openPetFolder()` 请求同一宿主打开 DSH 所有的包目录，并报告 `opened` 或 `host-unavailable`。
+
+可选的 `petActivity` service key 提供由宿主拥有的活动投影。没有该服务时，领域适配器观察现有的 `session/event` 和 `session/disposed` 流：turn 开始变为 `running`，blocked 或 error 结束变为 `blocked`，其他结束变为 `ready`，销毁则移除记录。宿主投影还可以提供待处理交互和面向用户的标题。这些记录是展示状态，不会被写回为 session 事件。
+
+每次偏好或活动发布都会发出 `pet/update`。伴侣客户端通过生成的 `pets` Remote 命名空间消费快照和事件。桌面伴侣页面（`/__dsh/pet/overlay`）轮询 `/__dsh/pet/overlay-state`，其右键菜单中的"关闭宠物"项通过 `POST /__dsh/pet/overlay-awake` 收起宠物；该写入只接受恰好为 `{ awake: boolean }` 的 `application/json` 请求体，跨站 POST 无法触达。原生导入与打开目录操作由能力标志控制；纯浏览器组合不提供原生服务，也不会报告这些能力可用。
+
+## 扩展点
+
+当宿主已经拥有更丰富的会话投影时，提供 `petActivity`。只应由可信的本地宿主提供 `petNative`；其选择器返回字节而不是由客户端控制的路径，其目录打开器接收由服务拥有的包根目录。桌面 companion 注册表是可选的，因此领域也可以在浏览器组合中运行，并提供相同的目录和活动 Remote API。
+
+## Model Experience
+
+无。宠物领域只存储本地偏好和展示状态。
+
+#### KV Cache 影响
+
+无。
+
+## Known Limitations and Deferred Work
+
+- **默认活动回退**——内置适配器覆盖会话生命周期事件；更丰富的待交互和标题数据需要宿主提供 `petActivity` 投影。
+- **外部目录编辑**——包会在启动、导入或替换之后，以及显式刷新时被发现；没有删除操作，也没有外部目录监听，校验失败的包不会出现且没有任何解释。
+- **桌面窗口**——置顶透明窗口仍需要 Electron companion shell；浏览器组合会继续禁用原生操作。

package/assets/deepseek-whale/pet.json

@@ -0,0 +1,12 @@
+{
+  "id": "deepseek-whale",
+  "displayName": "DeepSeek Whale",
+  "description": "A pixel-art blue whale companion for DeepSeek Harness tasks.",
+  "spritesheetPath": "spritesheet.webp",
+  "frame": {
+    "width": 192,
+    "height": 208,
+    "columns": 8,
+    "rows": 9
+  }
+}