openpets/packages/dsh

一句话定位

把 OpenPets 桌面宠物接入 DSH 编码代理：根据代理当前是在思考、报错还是等待审批，自动让宠物显示对应的反应气泡和短句提醒，把编码过程可视化但不会泄露任何业务数据。

核心能力

• 监听 DSH 的 agent/status 事件，把代理进入"思考中"映射为 thinking 反应，"已完成"映射为 success 反应
• 监听 DSH 的 agent/error 事件，让宠物立刻切换到 error 反应并弹出报错提示短句
• 监听 DSH 的 approval/request 事件，把等待用户审批的状态映射为 waiting 反应，提示"需要批准"
• 自动派发使用本地 IPC、500 毫秒超时的客户端，不走远程通道，忽略远程环境变量
• 内部采用预置短句池加校验，避免把代码、URL、路径或密钥混入气泡文案
• 在错误事件后的 5 秒内抑制 success/idle 反应，避免"刚报错立刻显示完成"的视觉混乱

技术实现

• 语言: TypeScript（ESM，包内编译产物为 dist/）
• 关键依赖: @deepseek-ai/cordis（peerDep）、@open-pets/agent-events（预置短句池与校验）、@open-pets/client（本地 IPC 客户端）
• 架构模式: 通过 dsh.bundle.patch 把 openpets-dsh 这个 Cordis 插入 apply(ctx, options) 注册到宿主上下文的 agent/status、agent/error、approval/request 三个事件钩子上；分类器只读事件分类值，由调度器异步派发，绝不阻塞宿主流程
• 入口文件: packages/dsh/src/index.ts（导出 apply、name 等，由 cordis.patch.yml 加载）

适用场景

• DSH 用户希望让桌面宠物反映出编码代理此刻的工作状态（思考、报错、等待审批），获得更直观的"陪伴感"，而不希望任何代码或提示词被外泄。
• 不需要远程宠物控制、不希望通过 MCP 调用模型工具的轻度 DSH 用户，需要一个开箱即用、严格本地的轻量集成。
• 想给不同 DSH profile 单独启用宠物联动，并保持与其他 OpenPets 插件/远程 MCP 配置完全解耦的场景。

前置依赖与兼容性

源码中未声明 Node 最低版本，亦未声明平台限制。

安装方式

dsh plugin --profile web add github:alvinunreal/openpets/packages/dsh

配置项

常见问题

Q: 这个插件会被安装到 DSH 的哪里？

A: 通过 dsh plugin --profile web add 按指定的 profile 安装；要让多个 profile 都启用，就对每个 profile 分别执行同一命令。

Q: 启用后我的代码或提示词会被发给宠物吗？

A: 不会。分类器只读取事件信封里的 status 分类值，并且气泡文案只从 agent-events 里预先写好的短句池里抽一句；消息会被强制校验，不能包含 URL、文件路径、密钥等敏感内容，也不会转发任何 prompt 或 tool result。

Q: 它和 OpenPets 自带的远程 MCP 有什么关系？

A: 本插件完全本地化，使用 500 毫秒超时的本地 IPC 客户端与桌面应用通信，并在测试用例里明确忽略 OPENPETS_REMOTE_ENDPOINT/TOKEN 环境变量；远程 MCP 仍可独立配置，互不干扰。

Q: 宠物反应会卡住 DSH 吗？

A: 不会。所有分类与派发都是异步、被调度器（默认走 Promise.resolve().then）放到事件循环里执行，并由宿主测试可注入的 schedule 替换；派发异常会被静默吃掉，绝不回传到 DSH 主流程。

Q: 报错后宠物要过几秒才显示"完成"，是 bug 吗？

A: 属于有意为之。源码常量 errorSuccessSuppressionMs = 5_000 会在 5 秒内抑制 success/idle 反应，让错误状态先被看见；如果不想等，可以临时关闭后端、等待、或联系作者调整阈值。

Q: 如何卸载？

A: 使用对应 profile 的 DSH bundle 移除命令即可；插件不会写入持久化文件，删除后立即失效。

上手难度

入门 — 安装命令一行即可启用，且不依赖任何外部服务、远程凭证或额外配置项，DSH 启动后宠物会自动随代理状态切换反应。

已知问题与限制

• 暂未发现源码中标注的 TODO/FIXME/已知缺陷；runtime.test.ts 已覆盖分类映射、抑制窗口与远程变量忽略三条核心路径。
• 行为上的固有限制（属设计而非 bug）：
  • error 反应后 5 秒内的 success/idle 会被静默抑制，体感上会有"延迟"。
  • 仅支持预置的 4 类（thinking/success/error/permission）短句，无法自定义气泡文案。
  • 仅识别 agent/status、agent/error、approval/request 三类事件，其它 DSH 事件会被分类器直接忽略。
  • 强制使用本地 IPC；若用户配置了远程 OpenPets 端点，此插件也会忽略，仅靠其他插件/CLI 处理远程通道。

A desktop companion platform with pets, plugins, and optional local agent integrations.

OpenPets puts an animated companion on your desktop, then lets plugins turn it into a focus buddy, reminder system, tiny game, launcher, or coding-agent sidekick.

Read this in: English | 日本語 | 한국어 | 简体中文 | 繁體中文 | Português (Brasil) | Español (LatAm)

---

Download OpenPets

Download the latest OpenPets desktop release and launch it. A pet appears immediately; no agent setup required.

• Desktop pets: animated companions that idle, wander, react, and keep your workspace from feeling empty.
• Official plugins: focus timers, reminders, mood check-ins, mini games, launch shortcuts, hydration nudges, and virtual-pet stats.
• Plugin SDK v3: a sandboxed JavaScript/TypeScript runtime for building new pet abilities with permissions, quotas, storage, schedules, commands, panels, events, audio, notifications, and more.
• Optional agent layer: Claude Code, OpenCode, Cursor, Pi, and MCP clients can drive local pet reactions without exposing prompts, code, paths, logs, or secrets in speech bubbles.

---

Star OpenPets

If OpenPets makes your coding setup or desktop workspace a little more fun, please give the repo a star.

---

For Users: Getting Started

You do not need to be a developer or connect any AI agents to enjoy OpenPets. The desktop app is fully functional out of the box with the official plugin lineup.

1. Install OpenPets Desktop

Download the package for your operating system from OpenPets Releases:

• macOS Apple Silicon: OpenPets-*-mac-arm64.dmg
• macOS Intel: OpenPets-*-mac-x64.dmg
• Windows: OpenPets-*-win-x64-setup.exe
• Linux: OpenPets-*-linux-x86_64.AppImage

Note: Windows release installers are signed. macOS builds may still be unsigned and can trigger a security warning; if macOS blocks execution, remove the quarantine flag via terminal:

xattr -dr com.apple.quarantine /Applications/OpenPets.app

2. Manage and Customize Pets

Browse installed pets, preview their animation frames, and configure which pet monitors each workspace or agent window from the built-in Pet Gallery.

3. Enable Official Plugins

OpenPets v3 ships with a modular Official Plugin Catalog. Enable or configure plugins via the desktop Control Center to add focus timers, reminders, and mini interactive games.

Shipped official lineup

• Day Routine: Tracks habits and reminds you to stretch or step away.
• Focus Buddy: Pomodoro-style focus timers to manage work cycles.
• Fortune Cookie: Cracks open randomized daily advice and wisdom.
• Launch Buddy: Allows registering shortcut commands to quickly open local folders, projects, or applications.
• Magic 8 Ball: Ask questions and receive playful, randomized answers from your pet.
• Mood Check-in: Periodically checks in on your mood to support emotional well-being.
• Reminders: Renders snoozeable, bell-alert notifications with custom audio tones.
• Virtual Pet: Turns your desktop companion into a Tamagotchi-style pet with hunger, affection, and energy levels tracked via a live status pin.
• Water Reminder: Keeps you hydrated with regular, customizable drinking prompts.

---

Plugin Platform & SDK v3

The OpenPets plugin system offers a secure, developer-friendly SDK (@open-pets/plugin-sdk) for creating custom companion behavior.

Security & Architecture

• Sandboxed Runtime: Each JS plugin runs inside a sandboxed BrowserWindow host environment.
• Host-Rendered UI: Plugins describe actions, HUDs, and notifications; the desktop host renders them. HTML/JS code cannot render raw HTML or execute arbitrary scripting inside a pet window.
• Permissions Model: Permissions must be declared in the manifest and approved by the user at install. Flagged sensitive APIs (like voice:listen, clipboard, and pet:speak:dynamic) require explicit consent toggles.
• SSRF & Private Host Guards: Network fetch requests are limited to developer-declared hostnames and guarded against local SSRF.

The SDK surface (ctx)

Plugins hook into the desktop environment via the ctx object, exposing:

• ctx.pets / ctx.pet: Manage default and spawned pet instances: spawn, move, animate, and react.
• ctx.ui: Alerts, transient/pinned bubbles, custom menus, panels, and status HUDs. Pinned mini HUD bubbles support compact 2x2 grid layouts with progress bars, such as Virtual Pet stats.
• ctx.audio: Trigger host-managed alert tones or user-imported custom audio.
• ctx.schedule: Set precise timer hooks (once, every, daily, cron, at).
• ctx.ai / ctx.secrets: Hook into the user's host-configured AI provider (Anthropic, OpenAI, Ollama) without exposing API keys to the plugin source.
• ctx.storage: Simple JSON key-value store with change subscriptions.
• Other APIs: events, assets, bus, net (with streaming support), notify, voice (TTS & push-to-talk STT), auth (PKCE browser flow), files (secure picked OS dialogs), system, commands, status, and log.

Developer Tools & Commands

Create, validate, and test plugins using the official CLI.

1. Scaffold a new plugin

Create a template from any of the official layouts (blank, reminder, ambient, ai-chat, tamagotchi, calendar):

npx @open-pets/cli plugin new "My Plugin" --template tamagotchi

2. Validate

Verify manifest layout, permissions, and configuration schemas before packing:

npx @open-pets/cli plugin validate ./my-plugin

3. Test harness

Write deterministic tests without launching the desktop app. Using @open-pets/plugin-sdk/testing's createTestHarness, you can mock the host, advance clocks, trigger actions, and verify reactions:

import { createTestHarness } from "@open-pets/plugin-sdk/testing";
import { register } from "./index.js";

const h = createTestHarness(register, { permissions: ["pet:speak", "schedule"] });
await h.start();
h.expectScheduled("decay");
await h.clock.advance("30m");
h.expectSpoke(/need attention/i);

Run plugin tests from your plugin project:

npm test

---

Advanced: Agent Integrations

If you want your development agent to drive your desktop companion, OpenPets provides an optional local MCP (Model Context Protocol) integration layer.

How it works

When you configure an agent, OpenPets exposes standard MCP tools. The agent can trigger animations, change status, and display text bubbles locally:

1. Claude Code: Installs OpenPets MCP, memory instructions in ~/.claude/CLAUDE.md, and hooks in ~/.claude/settings.json.
2. OpenCode: Installs OpenPets MCP, custom project instruction files, and the @open-pets/opencode automatic hook plugin.
3. Cursor / Other MCP Clients: Register OpenPets as a standard stdio or TCP MCP server.

Diagnose your setup

Check whether the Claude hook and project Cursor MCP integrations are installed, need an update, or are broken, and whether the desktop app is reachable:

npx @open-pets/cli doctor

Pass --cwd <path> to inspect a different project's .cursor/mcp.json, or --json for machine-readable output. The command exits non-zero only when an integration is broken, so it is safe to run before reporting a bug.

MCP Server Configuration

To run OpenPets as an MCP tool, add the server to your agent's configuration:

{
  "mcpServers": {
    "openpets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@open-pets/mcp@latest"]
    }
  }
}

Tip: To target a specific pet, pass the --pet <petId> argument.

Available MCP Tools

• openpets_status: Retrieve target pet ID and check runtime connectivity.
• openpets_react: Set pet reaction animations (e.g., thinking, editing, testing, success, error).
• openpets_say: Display a short speech bubble.

Local Privacy & Safety

• All automated reactions run on static local triggers (e.g., when a command runs or a file is written).
• Speech content is validated to prevent leaking sensitive variables, paths, secrets, or multiline code snippets.
• Real-time interaction requires a local discovery token write/read, protecting the IPC bridge from external network triggers.

---

Development Workspace

For contributing to the OpenPets codebase, testing changes, or building the desktop packages locally.

Prerequisites

• Node.js: version 20 or higher
• pnpm: version 11 or higher
• TypeScript: compiler support

Commands

Install project workspace dependencies:

pnpm install

Launch the Electron application in local developer mode:

pnpm dev:desktop

Launch with live official plugins loaded and monitored:

pnpm dev:desktop:plugins

Run workspace typechecking, code-conformance validations, and tests:

pnpm check
pnpm typecheck
pnpm test

Package the desktop application:

# Build & package into target OS directory
pnpm package:desktop:dir

# Build & package into final installer / setup archives
pnpm package:desktop

Workspace Structure

apps/desktop              Electron desktop application
packages/client           @open-pets/client (IPC helper library)
packages/mcp              @open-pets/mcp (Model Context Protocol stdio server)
packages/claude           @open-pets/claude (Claude integrations, memory, & hooks)
packages/opencode         @open-pets/opencode (OpenCode plugins & instruction configs)
packages/pi               @open-pets/pi (Pi CLI extension integration)
packages/agent-events     Shared sanitizers and events helper package
packages/cli              @open-pets/cli (User entry point CLI for configuration & scaffolding)
packages/sdk              @open-pets/plugin-sdk (Plugin SDK v3 declarations & testing harness)
packages/pet-format       @open-pets/pet-format (Pet manifest and schema types)
plugins/official          Official first-party plugin workspace (bundled with host catalog)
docs/                     Technical specifications and architecture documentation

---

Documentation

Explore detailed architectural and platform documentation inside the docs/ folder:

• docs/architecture.md - The one-page mental model: runtime topology, package spine, end-to-end flows.
• docs/desktop.md - The Electron app: process model, tray-first UX, Control Center, security model.
• docs/agent-integrations.md - How Claude Code, MCP, OpenCode, Cursor, and Pi are configured.
• docs/plugins.md - Plugin platform SDK v3 manifest, permissions, and sandboxed runtime.
• docs/sdk.md - Public SDK v3 contract for plugin authors: capability namespaces, permission surface, test harness.
• docs/catalog.md - Pet and plugin catalog contracts: v3/v2, pagination, install artifacts.
• docs/development.md - Developer experience: monorepo layout, command surface, dev modes.
• docs/testing-and-validation.md - Quality gates: behavior tests, runtime checks, release validators.
• docs/release.md - Application packaging and release processes.

---

Ownership & Promise

OpenPets is developed and maintained by Boring Dystopia Development. No foundation, no investors, no hidden agenda — an open project with a named owner. The deal, stated plainly:

• The code is MIT, and stays MIT. Fork it, ship it, remix it, hatch your own pets.
• Local-first, forever. No accounts, no sign-ups, no central AI server. AI features run through connections you configure, with your keys, on your machine.
• The catalog is a convenience, not a leash. Pets and plugins are fetched from openpets.dev, but the app is fully functional without it.
• Users are not the business. OpenPets will never paywall core features, the plugin SDK, or agent integrations — and it will never sell you content you could make yourself for free.

If you want to support the project: star the repo, hatch a pet, share it with a friend.

---

Safety and Privacy

• Local-Only: OpenPets IPC works using a local socket/named pipe, secured with a per-run random security token.
• SSRF Safety: Plugin network connections are restricted to approved domains and blocked from local network/private IP access.
• Dynamic Content Sanitization: Any dynamic AI-speech text runs through strict local filters to redact paths, URLs, secrets, or multiline code snippets.
• Sensitive Permission Consent: Features accessing clipboard, microphone, or dynamic AI responses are off by default and require explicit user opt-in.

---

Code signing policy

OpenPets Windows release artifacts are built only by the project's GitHub Actions trusted-build workflow and signed through the configured SignPath release policy. The canonical public policy is openpets.dev/code-signing-policy.

• Maintainer, committer, reviewer, and signing approver: Alvin Unreal.
• Review: Changes to release workflows, signing configuration, or Windows packaging require maintainer review before release approval.
• Scope: SignPath signing is limited to official OpenPets open-source release artifacts.
• Signing ops: The SignPath GitHub workflow may pause on release-signing requests that need approver review; approvals must be completed in the SignPath dashboard before publishing proceeds.
• Privacy: See the Privacy & network behaviour policy.

Free code signing provided by SignPath.io, certificate by SignPath Foundation.