# dsh-notify

English | [中文](#chinese)

A DeepSeek Harness (dsh) Web GUI plugin that sends browser desktop notifications when a **conversation completes** or the agent is **waiting for your confirmation**.

Stop checking back on long-running tasks — work in another window and let the system tray tell you when the agent finished or needs an approval.

## Features

| Trigger | Notification |
|---|---|
| Turn complete (`running → idle`) | "对话完成" + session title |
| Tool permission approval | "等待批准" + session title |
| Plan review | "等待计划审批" + session title |
| Agent question (`ask_user_question`) | "等待回答" + session title |

- **Noise gate** — notifies only when the page is hidden or the affected session is not the selected one
- **Click to focus** — clicking a notification focuses the window; auto-closes after 10 s
- **All sessions covered** — watches the full session list, not just the open one
- **Silent degradation** — denied permission or missing Notification API never errors
- **Zero host cost** — host half is an empty placeholder; pure JavaScript, no build step

## Install

```sh
# from git (no build step, no allowBuilds needed)
dsh plugin --profile web add github:pedesdestiny/dsh-notify

# or a local checkout
dsh plugin --profile web add /path/to/dsh-notify

# restart to load
dsh --profile web
```

Open http://127.0.0.1:3080 and **allow** the notification permission prompt. If you previously denied it, re-enable via the browser's site settings (lock icon → Notifications).

## How it works

```
┌─ dsh host ────────────────────────────────────┐
│  cordis.patch.yml  →  inserts a Loader row    │
│  index.js          →  empty (placeholder)     │
└──────────────┬────────────────────────────────┘
               │ dsh.client declaration →
               │ bundle injects window.__DSH_BOOT__
┌──────────────▼────────────────────────────────┐
│  Browser                                       │
│  client.js → registers into shell.overlay slot │
│    └─ invisible component, useSessions watches │
│       all sessions                             │
│         ├─ running edge  → completion notice   │
│         └─ pending edge  → confirmation notice │
└────────────────────────────────────────────────┘
```

- **`client.js`** — browser half: an invisible React component mounted in the always-rendered `shell.overlay` slot. It watches session-list snapshots through the standard `useSessions` hook, detects `running` / `pendingInteraction` edges, and fires the `Notification` API
- **`index.js`** — empty host placeholder for the Loader row
- **`cordis.patch.yml`** — bundle layer inserting the plugin row
- **`package.json`** — declares `dsh.bundle` and `dsh.client` (depends on `dsh-client-runtime` / `dsh-client-ui-layout`)

## Limitations

- Requires the GUI tab to remain open (background tab is fine); no notifications when the browser is fully closed
- Permission is granted per site origin (`127.0.0.1:3080`)
- The first snapshot is a baseline: sessions that finished before page load do not notify

## License

MIT

---

<a id="chinese"></a>

# dsh-notify（中文）

DeepSeek Harness (dsh) Web GUI 插件：在**对话完成**或**等待用户确认**时，向你的操作系统发送浏览器桌面通知。

挂后台跑长任务、切去别的窗口工作时，不必再频繁回头检查对话状态——任务跑完或 Agent 需要你批准操作时，系统右下角会弹出通知。

## 功能

| 触发时机 | 通知内容 |
|---|---|
| 对话完成（会话 `running → idle`） | 「对话完成」+ 会话标题 |
| 工具权限批准（approval） | 「等待批准」+ 会话标题 |
| 计划审批（plan review） | 「等待计划审批」+ 会话标题 |
| Agent 提问（ask_user_question） | 「等待回答」+ 会话标题 |

特性：

- **免打扰门槛** — 仅当页面处于后台，或受影响的会话不是当前选中的会话时才通知；你正盯着看的对话不会打扰你
- **点击聚焦** — 点击通知回到浏览器窗口
- **自动关闭** — 通知 10 秒后自动消失
- **多会话覆盖** — 监听全部会话（含后台会话），不只当前打开的
- **静默降级** — 浏览器通知权限被拒绝或 API 不可用时，插件保持沉默，绝不报错
- **零宿主开销** — 宿主端为空实现，全部逻辑在浏览器端；纯 JavaScript，无构建步骤

## 安装

### 方式一：git 安装（推荐）

```sh
dsh plugin --profile web add github:pedesdestiny/dsh-notify
```

本插件无构建步骤，git 安装开箱即用，无需 `allowBuilds` 授权。

### 方式二：本地目录

```sh
dsh plugin --profile web add /path/to/dsh-notify
```

### 生效

```sh
dsh --profile web   # 重启 dsh 加载插件
```

打开 http://127.0.0.1:3080，浏览器弹出通知权限请求时点击**允许**。

> 提示：如果之前拒绝过权限，需要在浏览器站点设置中（地址栏锁图标 → 通知）手动改为允许。

## 验证

1. 打开 Web GUI，切到别的窗口（让页面进入后台）
2. 发送一个任务给 Agent
3. 任务完成时，系统应弹出「对话完成」通知
4. 触发一个需要批准的操作（如越权文件写入），系统应弹出「等待批准」通知

## 工作原理

```
┌─ dsh 宿主 ─────────────────────────────┐
│  cordis.patch.yml  →  插入 Loader 行    │
│  index.js          →  空实现（占位）     │
└──────────────┬─────────────────────────┘
               │ dsh.client 声明 →
               │ bundle 注入 window.__DSH_BOOT__
┌──────────────▼─────────────────────────┐
│  浏览器                                  │
│  client.js → 注册进 shell.overlay slot   │
│    └─ 隐形组件 useSessions 监听全部会话   │
│         ├─ running 边沿  → 对话完成通知   │
│         └─ pending 边沿  → 等待确认通知   │
└────────────────────────────────────────┘
```

- **`client.js`** — 浏览器端核心：一个挂载在常驻 `shell.overlay` slot 的隐形 React 组件，通过标准 `useSessions` 钩子监听完整会话列表快照，检测 `running` 与 `pendingInteraction` 的状态边沿并触发 `Notification` API
- **`index.js`** — 宿主端空实现，仅为 Loader 行提供合法模块
- **`cordis.patch.yml`** — bundle 层，向配置树插入插件行
- **`package.json`** — 声明 `dsh.bundle`（组合包）与 `dsh.client`（浏览器面，依赖 `dsh-client-runtime` / `dsh-client-ui-layout`）

## 已知限制

- 通知依赖浏览器 `Notification` API：**GUI 标签页必须处于打开状态**（后台标签可以）；浏览器完全关闭时不会通知
- 通知权限按浏览器站点（`127.0.0.1:3080`）粒度授予
- 首次快照作为基线：页面加载时已经在运行的会话，其完成事件仍会正常通知；加载前已结束的不会

## 许可证

MIT