dsh-turn-reminder

Readme

# dsh-turn-reminder

[中文说明](README.zh.md)

User-attention notifications for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) web. Whenever a session blocks waiting for **you**, this plugin reminds you: an in-page toast while the page is visible, an OS-level browser notification while the page is hidden (click it to jump back; falls back to the toast when the system channel is unavailable).

## What it watches

| Channel | Trigger | Notes |
| --- | --- | --- |
| `turnEnd` | `agent/status` event, running → idle | A turn finished and the session waits for input. Blocked goals and errored turns end the turn, so they are covered transitively. |
| `approval` | `approval/request` waterfall (pass-through listener) | Tool approvals, sandbox escalations, etc. These block **mid-turn** — the agent never goes idle, so a turn-end watcher alone misses them. |
| `question` | `tools/pre-execute` waterfall, filtered on `ask_user_question` (pass-through listener) | The model asks you a question; also blocks mid-turn. |
| `plan` | `tools/pre-execute` waterfall, filtered on `exit_plan_mode` (pass-through listener) | The model presents a plan for review. The review panel opens **inside** the tool call, so this also blocks mid-turn — earlier versions wrongly assumed `turnEnd` covered it. |

Notification bodies carry detail: approvals show the tool name plus the asker's reason, questions show the first question's text, plan reviews show the plan's first markdown heading (all clipped at 60 chars). Counters are per session, so multiple tabs each remind only about their own session.

## Usage

A 🔔 control sits at the right end of the composer tool row. Click it once to grant the browser Notification permission (browsers require a user gesture; the permission persists per origin). The in-page toast dismisses itself after 8 seconds, or on click.

## Build & install

```sh
npm install
npm run build          # tsc (host half) + tsdown (client closure-factory bundle)
npm pack               # produces dsh-turn-reminder-0.1.0.tgz
dsh plugin --profile web add dsh-turn-reminder-0.1.0.tgz
```

Then **restart `dsh web`** — bundle plugin rows load at boot. After that it serves every session automatically.

## How it works

- **Host half** (bundle layer): listens to `agent/status` / `approval/request` / `tools/pre-execute` (`ask_user_question` and `exit_plan_mode`) across all agents, keeps per-session counters per channel, and exposes them through a Typert Remote service `turnReminder/poll` (agent-scoped; the wire argument `agentId` is the session id).
- **Client half**: registered into the session-scoped `conversation.input.right` slot, whose standard props carry `sessionId` — that is how the page knows which session to poll. Polls every 1.5 s; on a counter increment, fires the toast or a system `Notification` (per-channel tags so different kinds don't replace each other).
- Both waterfall listeners are pass-through (`return next()`); they observe, never decide.

## Notes

- Counters only cover events after the plugin loaded; they reset on process restart, and the first poll only records a baseline (no catch-up reminders for history).
- Tested against dsh `0.1.0-rc.6`. Reinstalling from a local tarball needs a version bump (pnpm dedupes same name+version and keeps the old build).

## License

MIT