@liangliang205/dsh-task-reminder 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-task-reminder contributors
+
+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.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# dsh-task-reminder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+会话**完成、失败、被阻塞、等你授权、等你回答**时提醒你：带 DeepSeek Harness 名字和图标的系统通知 + 提示音 + 可选 Webhook。你正看着窗口时不打扰。
+
+DSH 插件 bundle，零改动 DSH 核心，可发布到 npm 后用 `dsh plugin add` 一键安装。
+
+> **npm 包名**：`@liangliang205/dsh-task-reminder`（无 scope 的 `dsh-task-reminder` 被 npm 以“与 `dsh-taskreminder` 过于相似”拒绝）。
+
+## 它会提醒的五种时刻
+
+| 时刻 | 判定依据（会话日志事件） | 文案 |
+| --- | --- | --- |
+| 任务完成 | `turn/end` → `reason.kind = completed` | DSH · 任务完成 |
+| 任务失败 | `turn/end` → `error`（带错误摘要） | DSH · 任务失败 |
+| 被阻塞 | `turn/end` → `blocked` | DSH · 等待你处理 |
+| 等你授权 | `approval/asked`（同一 `id` 只提醒一次） | DSH · 需要授权（带工具名与原因） |
+| 等你回答 | `tool/call` 且工具是 `ask_user_question` | DSH · 需要回答（带第一个问题） |
+| 超限 / 中止 | `turn/end` → `max-tokens` / `aborted` | 可分别用配置关掉 |
+
+`forked`、`interrupted` 不是真实的任务结束，永不提醒；子代理会话默认静默。
+
+## 你正看着窗口时不打扰
+
+浏览器侧（`lib/client.js`）把「页面可见 + 窗口有焦点」上报给 Host；Host 在收到报告后的 `activeWindowMs`（默认 45 秒）内认为你在前台，期间的提醒只写日志、不弹通知。页面失焦、切走、关闭都会立即上报。
+
+- **失败开放**：没有任何客户端报告时（比如 headless profile、页面还没加载），一律照常提醒——宁可吵，不可静默失效。
+- **心跳**：前台状态每 20 秒续期，页面崩溃后 45 秒自动过期，不会永久静音。
+- **无浏览器构建**：`lib/client.js` 直接以 `window.__ModuleLoader__` 形式手写，仓库里没有打包步骤。
+
+诊断端点（仅回环/受信 host 可访问）：
+
+```powershell
+# 当前是否判定为"你在前台"，以及每个页面实例的上报
+curl http://127.0.0.1:55543/task-reminder/api/state
+# {"ok":true,"foreground":false,"clients":[{"clientId":"…","active":false,"ageMs":2604}]}
+```
+
+上报接口 `POST /task-reminder/api/visibility` 强制要求 `content-type: application/json`——跨站表单发不出这个头，浏览器的预检又不会被批准，所以第三方网页无法伪造"你在前台"。
+
+## 和已有的 `dsh-task-notify` 什么关系
+
+npm 上已经有 `dsh-task-notify@0.4.1`（Gitee: `chy959799/dsh-task-notify`），功能相近，所以本包换名发布，避免撞名。两者取舍不同：
+
+| 能力 | 本包 `dsh-task-reminder` | 已有 `dsh-task-notify` |
+| --- | --- | --- |
+| Windows 通知归属 | WinRT toast + `com.deepseek.dsh` AUMID，显示 **DeepSeek Harness** + DSH 图标 | `node-notifier`（Windows 走 SnoreToast，需要额外可执行文件） |
+| 提醒时刻 | 完成/失败/阻塞/阻塞授权/等待回答/超限/中止 | 完成 + 授权 + 提问 |
+| 推送渠道 | ✅ 系统通知 + 提示音 + Webhook（固定 payload） | 仅系统通知 |
+| 前台静默 | ✅ 可见 + 有焦点才算前台，超时自动过期 | ✅ 仅页面可见性 |
+| 设置界面 | ❌ 只走 `cordis.patch.yml`（见下） | ✅ 设置页 |
+| 运行时依赖 | 0（纯 Node + 系统能力） | `node-notifier`、`schemastery` |
+
+一句话：**要"推到手机/别的机器"或"原生 DSH 品牌通知"用这个；要图形化设置页用那个。**
+
+### 为什么暂时没有设置页
+
+DSH 的设置页给插件投影的只有 schema 里标了 `.volatile()` 的字段（`dsh-settings` 的 form projection），而且要自带 React 客户端包注册 `settings.section` slot 才有完整界面。本包当前选择零依赖 + 零构建，所以配置走 profile 的 `cordis.patch.yml`；要图形化编辑，下一步是把配置改成 schemastery `Config` 并补一个 `settings.section` 客户端包。
+
+## 安装
+
+```powershell
+# 从 npm 安装（推荐）
+dsh plugin --profile desktop add @liangliang205/dsh-task-reminder
+
+# 本地路径（开发）
+dsh plugin --profile desktop add D:\pr\dsh-task-reminder
+```
+
+也可以让 agent 用 `plugin_manager` 工具：`install_bundle` + 目标名或绝对路径。装完热生效，不用重启应用。
+
+## 配置
+
+默认值在 `cordis.patch.yml`。要改就在 profile 的 `cordis.patch.yml` 里按 id 覆盖；patch 会整体替换该行 `config`，没写的字段回落到插件内置默认值：
+
+```yaml
+- id: task-reminder
+  name: '@liangliang205/dsh-task-reminder'
+  config:
+    onlyWhenBlurred: false            # 不管你在不在看，都弹
+    minDurationMs: 8000               # 8 秒内的短任务不提醒
+    notifyOn: [completed, blocked]
+    webhookUrl: https://example.com/hook
+```
+
+| 字段 | 默认 | 含义 |
+| --- | --- | --- |
+| `locale` | `zh` | 文案语言，`zh` / `en` |
+| `desktop` | `true` | 系统通知：Windows toast / macOS 通知中心 / Linux `notify-send` |
+| `sound` | `true` | 提示音；与通知同开时 toast 自身静音，避免响两声 |
+| `onlyWhenBlurred` | `true` | 页面在前台时静默（失败开放） |
+| `notifyOn` | 全部 5 种 | 哪些 `turn/end` 原因提醒 |
+| `notifyOnApproval` | `true` | 工具等待授权时提醒 |
+| `notifyOnQuestion` | `true` | agent 提问时提醒 |
+| `minDurationMs` | `0` | 短于此时长的任务不提醒（毫秒） |
+| `includeSubagents` | `false` | 子代理会话是否也提醒 |
+| `minGapMs` | `1200` | 提醒之间的最小间隔 |
+| `activeWindowMs` | `45000` | 一次前台报告的有效期（毫秒） |
+| `soundFile` | 空 | 自定义提示音（`.wav`） |
+| `toastAppId` | `com.deepseek.dsh` | toast 归属的 AppUserModelID |
+| `webhookUrl` | 空 | 非空则 POST payload |
+| `webhookTimeoutMs` | `5000` | Webhook 超时 |
+| `notifyOnStart` | `false` | 挂载时先发一条"已开启"，用于验证接线 |
+| `verbose` | `false` | 每次提醒写一行日志 |
+
+### Webhook payload
+
+字段风格对齐 StarRailAssistant 的通知数据包，现成的 webhook 消费端（Bark / Server酱 / n8n / OneBot）可以直接接：
+
+```json
+{
+  "title": "DSH · 任务完成",
+  "event": "session.turn.completed",
+  "result": "success",
+  "timestamp": "2026-11-07 20:25:39",
+  "sessionId": "smoke-session",
+  "sessionTitle": "本地实现任务完成提醒",
+  "cwd": "D:\\pr\\deepseek-harness",
+  "durationMs": 74000,
+  "message": "会话任务已完成：本地实现任务完成提醒",
+  "detail": "1m 14s · deepseek-harness"
+}
+```
+
+`event` 取值：`session.turn.completed` / `session.turn.failed` / `session.turn.blocked` / `session.turn.cancelled` / `session.turn.max-tokens` / `session.approval.asked` / `session.question.asked`；`result` 取值 `success` / `failure` / `blocked` / `cancelled` / `truncated`，其中"等你处理"的三类都是 `blocked`，便于消费端优先处理。
+
+## 验证
+
+```powershell
+node --test                      # 20 个行为测试：文案、配置校验、真实 HTTP webhook、子代理静默、
+                                 # 授权去重、提问解析、前台门控、路由鉴权、浏览器半体的上报与清理
+node tools/notify-smoke.mjs      # 手工触发一次真实通知（走生产代码路径）
+npm pack --dry-run               # 检查发布内容
+```
+
+## 发布
+
+```powershell
+npm login                                  # 必做一次
+npm version patch                          # 0.2.0 → 0.2.1（首次发布 0.2.0 时不要执行）
+npm publish --access public
+```
+
+两个踩过的坑：
+
+1. **首次发布会要求 2FA**：邮件 OTP 型账号必须用带 **Bypass two-factor authentication** 的 granular token，登录验证码不能用于发布。注意 npm 已公告 2027 年 1 月起取消“token 直发”，之后要走 `npm stage publish` + 网页 2FA 批准。
+2. **包名过近似会被拒**：`dsh-task-reminder` 与已存在的 `dsh-taskreminder` 被判相似，因此发布在 `@liangliang205` scope 下。
+
+发布前确认：
+
+1. `dsh.bundle.patch` 指向 `cordis.patch.yml`——DSH 认出"这是组合包"的唯一依据；
+2. `dsh.client.platform = "web"` 且 `exports["./client"]` 存在——浏览器半体靠这两个才能被扫到并注入；
+3. `files` 覆盖 `lib/`、`cordis.patch.yml`、`README.md`、`LICENSE`。
+
+想被 **Discover** 页发现，需要一个市场索引 JSON（格式 1，见 DSH 仓库 `packages/util/plugin-market-index`），托管后可让用户把自己的索引 URL 加进 Discover；进官方目录则要走 DSH 仓库的 PR。
+
+## 已知限制
+
+- **只验证了 Windows**；macOS / Linux 分支按平台命令行写好，未真机跑过。
+- **每个 turn 都提醒**：一个任务被拆成多轮追问会提醒多次，还没按"整段任务"聚合。
+- **应用退出后没有提醒**：提醒由 host 进程内插件发出，没有后台守护。
+- **toast 依赖已注册的 AUMID**：源码跑 Web 版或换机器时，要么用已安装的桌面版，要么把 `toastAppId` 换成该机器上已注册的 AUMID，否则 Windows 会静默丢弃通知。
+- **没有设置页**：配置只走 `cordis.patch.yml`，见上文原因。
+- **前台判定需要页面配合**：页面没加载（例如刚启动还没打开窗口）时按"不在前台"处理，会照常提醒。

package/cordis.patch.yml

@@ -0,0 +1,34 @@
+# dsh-task-reminder bundle patch: one Host row over the profile root.
+#
+# Install into a profile with:
+#   dsh plugin --profile <name> add @liangliang205/dsh-task-reminder
+# or send the plugin_manager install_bundle target (a registry name, an
+# absolute path, or a `file:`/`link:` spec). The row below is the shipped
+# default; override `config` by id from the profile's own cordis.patch.yml.
+
+- insert:
+    - id: task-reminder
+      name: '@liangliang205/dsh-task-reminder'
+      config:
+        locale: zh
+        desktop: true
+        sound: true
+        onlyWhenBlurred: true
+        notifyOn:
+          - completed
+          - error
+          - blocked
+          - aborted
+          - max-tokens
+        notifyOnApproval: true
+        notifyOnQuestion: true
+        minDurationMs: 0
+        includeSubagents: false
+        minGapMs: 1200
+        activeWindowMs: 45000
+        soundFile: ''
+        toastAppId: com.deepseek.dsh
+        webhookUrl: ''
+        webhookTimeoutMs: 5000
+        notifyOnStart: false
+        verbose: false

package/lib/channels.js

@@ -0,0 +1,189 @@
+/**
+ * Delivery channels for one reminder payload: an OS notification, a sound, and
+ * an optional webhook. Delivery is best-effort by design — a reminder must never
+ * fail a turn — so every channel contains its own errors and reports them to the
+ * plugin log.
+ */
+import { execFile } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = fileURLToPath(new URL('.', import.meta.url))
+
+/** Longest a notification helper may run before it is killed. */
+const HELPER_TIMEOUT_MS = 10_000
+
+/** XML-escape one toast text node. */
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+}
+
+/** Escape one AppleScript string literal. */
+function escapeAppleScript(value) {
+  return String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')
+}
+
+/** Run one helper process and reject with its stderr on failure. */
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { timeout: HELPER_TIMEOUT_MS, windowsHide: true }, (error, stdout, stderr) => {
+      if (error !== null) {
+        const detail = typeof stderr === 'string' && stderr.trim() !== '' ? stderr.trim() : error.message
+        reject(new Error(`${command} failed: ${detail}`))
+        return
+      }
+      resolve(stdout)
+    })
+  })
+}
+
+/** `ToastGeneric` document; `silent` suppresses the toast's own cue when the sound channel is on. */
+function toastXml(payload, silent) {
+  const detail = payload.detail === undefined ? '' : `<text>${escapeXml(payload.detail)}</text>`
+  return '<?xml version="1.0" encoding="utf-8"?>'
+    + '<toast duration="short">'
+    + '<visual><binding template="ToastGeneric">'
+    + `<text>${escapeXml(payload.title)}</text>`
+    + `<text>${escapeXml(payload.message)}</text>`
+    + detail
+    + '</binding></visual>'
+    + (silent ? '<audio silent="true"/>' : '')
+    + '</toast>'
+}
+
+/** Show a Windows toast under the DSH AppUserModelID so it carries the app name and icon. */
+async function windowsToast(payload, settings) {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-task-notify-'))
+  const xmlPath = join(dir, 'toast.xml')
+  try {
+    await writeFile(xmlPath, toastXml(payload, settings.sound), 'utf8')
+    await run('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+      '-File', join(scriptDir, 'toast.ps1'),
+      '-XmlPath', xmlPath,
+      '-AppId', settings.toastAppId,
+    ])
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+/** Show a notification on the current platform; unsupported platforms report why. */
+async function showDesktop(payload, settings, log) {
+  switch (process.platform) {
+    case 'win32':
+      await windowsToast(payload, settings)
+      return
+    case 'darwin':
+      await run('osascript', [
+        '-e',
+        `display notification "${escapeAppleScript(payload.message)}" with title "${escapeAppleScript(payload.title)}"`,
+      ])
+      return
+    case 'linux':
+      await run('notify-send', ['--app-name=DeepSeek Harness', payload.title, payload.message])
+      return
+    default:
+      log(`desktop notifications are not supported on ${process.platform}; skipping`)
+  }
+}
+
+/** Play the configured cue; `soundFile` overrides the platform default. */
+async function playSound(settings, log) {
+  const file = settings.soundFile
+  if (process.platform === 'win32') {
+    await run('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+      '-File', join(scriptDir, 'sound.ps1'),
+      '-SoundFile', file,
+    ])
+    return
+  }
+  if (process.platform === 'darwin') {
+    await run('afplay', [file === '' ? '/System/Library/Sounds/Glass.aiff' : file])
+    return
+  }
+  if (process.platform === 'linux') {
+    await run('paplay', [file === '' ? '/usr/share/sounds/freedesktop/stereo/complete.oga' : file])
+    return
+  }
+  log(`sound playback is not supported on ${process.platform}; skipping`)
+}
+
+/** POST the payload to one webhook; failures stay local to the log. */
+async function postWebhook(payload, settings, log) {
+  try {
+    const response = await fetch(settings.webhookUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(settings.webhookTimeoutMs),
+    })
+    if (!response.ok) log(`webhook answered ${response.status} ${response.statusText}`)
+  } catch (error) {
+    log(`webhook delivery failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/**
+ * Create the channel set.
+ * @param {object} settings - resolved plugin settings.
+ * @param {{ log: (message: string, error?: unknown) => void }} hooks - plugin logger.
+ * @returns {{ notify: (payload: object) => void, dispose: () => void }} dispatcher.
+ */
+export function createChannels(settings, hooks) {
+  const { log } = hooks
+  const queue = []
+  let pumping = false
+  let disposed = false
+
+  const report = (label) => (error) => {
+    log(`${label} failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  /** Delay between notification groups so a burst of finished turns does not stack toasts. */
+  const idle = () => new Promise((resolve) => {
+    setTimeout(resolve, settings.minGapMs).unref()
+  })
+
+  async function pump() {
+    if (pumping) return
+    pumping = true
+    try {
+      while (queue.length > 0 && !disposed) {
+        const group = queue.shift()
+        await Promise.allSettled(group.map((task) => task()))
+        if (queue.length > 0 && !disposed) await idle()
+      }
+    } finally {
+      pumping = false
+    }
+  }
+
+  const enqueue = (tasks) => {
+    if (disposed) return
+    queue.push(tasks)
+    void pump()
+  }
+
+  return {
+    notify(payload) {
+      const tasks = []
+      if (settings.desktop) tasks.push(() => showDesktop(payload, settings, log).catch(report('desktop notification')))
+      if (settings.sound) tasks.push(() => playSound(settings, log).catch(report('sound')))
+      if (tasks.length > 0) enqueue(tasks)
+      if (settings.webhookUrl !== '') void postWebhook(payload, settings, log)
+    },
+    dispose() {
+      disposed = true
+      queue.length = 0
+    },
+  }
+}

package/lib/client.js

@@ -0,0 +1,114 @@
+/**
+ * Browser half: report whether this page is in front, so the host can stay
+ * quiet while you are looking at it.
+ *
+ * Written directly in the client module-loader form (`window.__ModuleLoader__`)
+ * because this package ships without a browser build step. It registers no
+ * slot and renders nothing: one JSON POST per state change, plus a heartbeat
+ * that expires when the page is closed.
+ */
+window.__ModuleLoader__.load({
+  // Must equal the npm package name: the client module table is keyed by the
+  // graph row id, which is the package name. A mismatch fails the whole web
+  // boot with "no registered factory".
+  id: '@liangliang205/dsh-task-reminder',
+  factory: function (_require) {
+    'use strict'
+    var module = { exports: {} }
+
+    /** Host endpoint installed by the plugin's own web route. */
+    var ENDPOINT = '/task-reminder/api/visibility'
+    /** Re-report interval, shorter than the host's expiry for one report. */
+    var HEARTBEAT_MS = 20000
+
+    var clientId = (function () {
+      try {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+          return crypto.randomUUID()
+        }
+      } catch (error) {
+        // A browser without crypto.randomUUID falls through to the random id.
+      }
+      return 'c' + Math.random().toString(36).slice(2) + Date.now().toString(36)
+    })()
+
+    /** POST one report; failures are irrelevant because the next heartbeat retries. */
+    function post(active, keepalive) {
+      var body = JSON.stringify({ client: clientId, active: active === true })
+      try {
+        if (typeof fetch === 'function') {
+          fetch(ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: body,
+            keepalive: keepalive === true,
+          }).catch(function () {})
+          return
+        }
+      } catch (error) {
+        // Fall through to the beacon path.
+      }
+      try {
+        if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+          navigator.sendBeacon(ENDPOINT, new Blob([body], { type: 'application/json' }))
+        }
+      } catch (error) {
+        // Offline or blocked; nothing to retry beyond the next heartbeat.
+      }
+    }
+
+    /** Visible and focused; a desktop window can lose focus while still visible. */
+    function isActive() {
+      try {
+        if (typeof document === 'undefined' || document.visibilityState !== 'visible') return false
+        return typeof document.hasFocus !== 'function' || document.hasFocus()
+      } catch (error) {
+        return true
+      }
+    }
+
+    /**
+     * Attach the focus reporters for this page instance.
+     * @param {{ effect?: (factory: () => () => void) => unknown }} ctx - client plugin context.
+     */
+    function apply(ctx) {
+      var last = null
+
+      var report = function (keepalive) {
+        var active = isActive()
+        last = active
+        post(active, keepalive)
+      }
+      var onWake = function () {
+        var active = isActive()
+        if (active !== last) report(false)
+      }
+      var onLeave = function () {
+        last = false
+        post(false, true)
+      }
+
+      document.addEventListener('visibilitychange', onWake)
+      window.addEventListener('focus', onWake)
+      window.addEventListener('blur', onWake)
+      window.addEventListener('pagehide', onLeave)
+      report(false)
+      var timer = setInterval(function () {
+        // A heartbeat keeps the last known state current without extra state changes.
+        post(last === true, false)
+      }, HEARTBEAT_MS)
+
+      var cleanup = function () {
+        clearInterval(timer)
+        document.removeEventListener('visibilitychange', onWake)
+        window.removeEventListener('focus', onWake)
+        window.removeEventListener('blur', onWake)
+        window.removeEventListener('pagehide', onLeave)
+      }
+      if (typeof ctx.effect === 'function') ctx.effect(function () { return cleanup })
+    }
+
+    module.exports = { name: 'task-reminder-client', apply: apply }
+    return module.exports
+  },
+})

package/lib/index.js

@@ -0,0 +1,275 @@
+/**
+ * `task-reminder` — remind the user when a session turn finishes or stalls on
+ * the user.
+ *
+ * The plugin reads the durable session log: `turn/start` and `session/title`
+ * describe the work, `turn/end` closes it, `approval/asked` and a question
+ * tool call mark a wait. One payload per event fans out to an OS notification,
+ * an audible cue, and an optional webhook. It registers no tool, service, or
+ * model-visible text: it moves facts the log already records to a place the
+ * user notices — and, when a page reports itself in front, it stays quiet.
+ */
+import { buildAttentionPayload, buildPayload, buildStartupPayload, NOTIFIABLE_REASONS } from './payload.js'
+import { createChannels } from './channels.js'
+import { createPresenceTracker } from './presence.js'
+import { installRoute } from './server.js'
+
+/** Plugin name used by the loader entry. */
+export const name = 'task-reminder'
+
+/**
+ * Defaults for every setting; a deployment overrides them from `cordis.yml`,
+ * and nothing here is a hardcoded tunable the profile cannot reach.
+ */
+const DEFAULTS = {
+  /** Copy language for titles and messages. */
+  locale: 'zh',
+  /** Show an OS notification (Windows toast, macOS notification, `notify-send`). */
+  desktop: true,
+  /** Play a cue when a turn finishes. */
+  sound: true,
+  /** Stay quiet while a page reports itself in front; fails open without reports. */
+  onlyWhenBlurred: true,
+  /** Reasons that produce a reminder; `forked` and `interrupted` are never live turn ends. */
+  notifyOn: [...NOTIFIABLE_REASONS],
+  /** Remind when a tool waits for the user's approval. */
+  notifyOnApproval: true,
+  /** Remind when the agent waits for an answer. */
+  notifyOnQuestion: true,
+  /** Skip reminders for turns shorter than this, in milliseconds. */
+  minDurationMs: 0,
+  /** Remind for subagent sessions too; off keeps one reminder per user-visible task. */
+  includeSubagents: false,
+  /** Minimum spacing between notification groups, in milliseconds. */
+  minGapMs: 1200,
+  /** How long one foreground report stays current, in milliseconds. */
+  activeWindowMs: 45_000,
+  /** Absolute custom cue path; empty selects the platform default. */
+  soundFile: '',
+  /** Windows AppUserModelID that owns the toast; `com.deepseek.dsh` is the desktop build's. */
+  toastAppId: 'com.deepseek.dsh',
+  /** POST the payload here when non-empty. */
+  webhookUrl: '',
+  /** Deadline for one webhook request, in milliseconds. */
+  webhookTimeoutMs: 5000,
+  /** Announce that reminders are on when the plugin mounts; a wiring check. */
+  notifyOnStart: false,
+  /** Log every dispatched reminder. */
+  verbose: false,
+}
+
+const KNOWN_KEYS = new Set(Object.keys(DEFAULTS))
+
+/** Tool whose call means the agent is waiting on the user's answer. */
+const QUESTION_TOOL = 'ask_user_question'
+
+/** Raise a configuration error naming the offending field. */
+function invalid(field, expected) {
+  throw new TypeError(`task-reminder: config.${field} must be ${expected}`)
+}
+
+/**
+ * Validate and default the loader configuration. Malformed values fail at load
+ * instead of silently disabling reminders.
+ * @param {Record<string, unknown> | undefined} raw - the entry's `config`.
+ * @returns {typeof DEFAULTS} resolved settings.
+ */
+export function resolveConfig(raw) {
+  const input = raw ?? {}
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    throw new TypeError('task-reminder: config must be a mapping')
+  }
+  for (const key of Object.keys(input)) {
+    if (!KNOWN_KEYS.has(key)) throw new TypeError(`task-reminder: config.${key} is not a known setting`)
+  }
+  const settings = { ...DEFAULTS, ...input }
+  if (settings.locale !== 'zh' && settings.locale !== 'en') invalid('locale', '"zh" or "en"')
+  for (const field of [
+    'desktop', 'sound', 'onlyWhenBlurred', 'includeSubagents',
+    'notifyOnApproval', 'notifyOnQuestion', 'notifyOnStart', 'verbose',
+  ]) {
+    if (typeof settings[field] !== 'boolean') invalid(field, 'a boolean')
+  }
+  if (!Array.isArray(settings.notifyOn)) invalid('notifyOn', `an array of ${NOTIFIABLE_REASONS.join(', ')}`)
+  for (const reason of settings.notifyOn) {
+    if (!NOTIFIABLE_REASONS.includes(reason)) {
+      throw new TypeError(`task-reminder: config.notifyOn has unknown reason "${reason}"`)
+    }
+  }
+  for (const field of ['minDurationMs', 'minGapMs', 'activeWindowMs', 'webhookTimeoutMs']) {
+    if (!Number.isFinite(settings[field]) || settings[field] < 0) invalid(field, 'a non-negative number')
+  }
+  for (const field of ['soundFile', 'toastAppId', 'webhookUrl']) {
+    if (typeof settings[field] !== 'string') invalid(field, 'a string')
+  }
+  if (settings.soundFile !== '' && settings.sound === false) {
+    throw new TypeError('task-reminder: config.soundFile is set while config.sound is false')
+  }
+  return settings
+}
+
+/**
+ * Describe the wait a `tool/call` puts on the user.
+ * @param {{ data: { name: string, arguments: string } }} event - the recorded tool call.
+ * @returns {string | undefined} the first question text, or undefined for other tools.
+ */
+export function questionOf(event) {
+  if (event.data.name !== QUESTION_TOOL) return undefined
+  try {
+    const parsed = JSON.parse(event.data.arguments === '' ? '{}' : event.data.arguments)
+    const first = Array.isArray(parsed?.questions) ? parsed.questions[0] : undefined
+    const text = first?.question ?? first?.header
+    return typeof text === 'string' && text.trim() !== '' ? text.trim() : ''
+  } catch {
+    // A non-JSON argument string still means the tool was called; the reminder
+    // says "answer needed" without the question text.
+    return ''
+  }
+}
+
+/**
+ * Mount the reminder listener.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - plugin context.
+ * @param {Record<string, unknown>} [config] - loader configuration.
+ */
+export function apply(ctx, config) {
+  const settings = resolveConfig(config)
+  const logger = ctx.logger
+  const log = (message) => {
+    if (settings.verbose) logger.info(message)
+  }
+  const warn = (message, error) => {
+    logger.warn(error === undefined ? message : `${message}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  const channels = createChannels(settings, { log: warn })
+  ctx.effect(() => () => channels.dispose(), 'task-reminder channels')
+
+  const presence = createPresenceTracker({ activeWindowMs: settings.activeWindowMs })
+  // The route waits for the Web host instead of gating plugin activation: a
+  // profile without one (headless, SDK) still gets completion reminders.
+  ctx.inject(['webServer'], (scope) => {
+    const startup = scope.get('webStartup')
+    scope.effect(() => installRoute({
+      webServer: scope.webServer,
+      trustedHosts: Array.isArray(startup?.trustedHosts) ? startup.trustedHosts : undefined,
+      presence,
+      warn,
+    }), 'task-reminder foreground route')
+  })
+
+  /** In front means a page reported itself visible and focused recently. */
+  const quiet = () => settings.onlyWhenBlurred && presence.foreground()
+
+  /** Turn start time per session id, learned from `turn/start`. */
+  const turnStarts = new Map()
+  /** Latest `session/title` value per session id. */
+  const titles = new Map()
+  /** Approval ids already announced, so one question yields one reminder. */
+  const announcedApprovals = new Set()
+
+  const isSubagent = (session) => session.header.origin === 'subagent' || session.header.parentSession !== undefined
+
+  const dispatch = (payload) => {
+    if (quiet()) {
+      log(`skipped (page in front): ${payload.event}`)
+      return
+    }
+    log(`reminder: ${payload.event} session=${payload.sessionId} result=${payload.result}`)
+    channels.notify(payload)
+  }
+
+  const sessionFacts = (session) => ({
+    sessionId: session.id,
+    ...(titles.get(session.id) === undefined ? {} : { sessionTitle: titles.get(session.id) }),
+    ...(session.header.cwd === undefined ? {} : { cwd: session.header.cwd }),
+  })
+
+  const observeTurnEnd = (session, event) => {
+    const reason = event.data.reason
+    const startedAt = turnStarts.get(session.id)
+    turnStarts.delete(session.id)
+    if (reason.kind === 'forked') return
+    if (!settings.includeSubagents && isSubagent(session)) return
+    if (!settings.notifyOn.includes(reason.kind)) return
+    const endedAt = typeof event.time === 'number' ? event.time : Date.now()
+    if (settings.minDurationMs > 0 && startedAt !== undefined && endedAt - startedAt < settings.minDurationMs) return
+    dispatch(buildPayload({
+      reason: reason.kind,
+      turn: event.data.turn,
+      ...sessionFacts(session),
+      ...(startedAt === undefined ? {} : { startedAt }),
+      endedAt,
+      ...(reason.kind === 'error' ? { errorMessage: reason.error.message } : {}),
+    }, settings.locale))
+  }
+
+  const observeApproval = (session, event) => {
+    if (!settings.notifyOnApproval) return
+    if (!settings.includeSubagents && isSubagent(session)) return
+    const id = event.data.id
+    if (typeof id !== 'string' || announcedApprovals.has(id)) return
+    announcedApprovals.add(id)
+    dispatch(buildAttentionPayload({
+      kind: 'approval',
+      ...sessionFacts(session),
+      ...(typeof event.data.toolName === 'string' ? { toolName: event.data.toolName } : {}),
+      ...(typeof event.data.reason === 'string' ? { reason: event.data.reason } : {}),
+      at: typeof event.time === 'number' ? event.time : Date.now(),
+    }, settings.locale))
+  }
+
+  const observeQuestion = (session, event) => {
+    if (!settings.notifyOnQuestion) return
+    if (!settings.includeSubagents && isSubagent(session)) return
+    const question = questionOf(event)
+    if (question === undefined) return
+    dispatch(buildAttentionPayload({
+      kind: 'question',
+      ...sessionFacts(session),
+      ...(question === '' ? {} : { question }),
+      at: typeof event.time === 'number' ? event.time : Date.now(),
+    }, settings.locale))
+  }
+
+  ctx.on('session/event', (session, event) => {
+    // A reminder must never disturb the log, the loop, or a sibling listener.
+    try {
+      switch (event.type) {
+        case 'turn/start':
+          turnStarts.set(session.id, typeof event.time === 'number' ? event.time : Date.now())
+          return
+        case 'session/title':
+          titles.set(session.id, event.data.title)
+          return
+        case 'turn/end':
+          observeTurnEnd(session, event)
+          return
+        case 'approval/asked':
+          observeApproval(session, event)
+          return
+        case 'approval/decided':
+          if (typeof event.data.id === 'string') announcedApprovals.delete(event.data.id)
+          return
+        case 'tool/call':
+          observeQuestion(session, event)
+          return
+        default:
+          return
+      }
+    } catch (error) {
+      warn('observer failed', error)
+    }
+  })
+
+  ctx.on('session/disposed', (session) => {
+    turnStarts.delete(session.id)
+    titles.delete(session.id)
+  })
+
+  if (settings.notifyOnStart) {
+    const payload = buildStartupPayload(settings.locale, Date.now())
+    log(`reminder: ${payload.event}`)
+    channels.notify(payload)
+  }
+}

package/lib/payload.js

@@ -0,0 +1,188 @@
+/**
+ * Pure notification-payload construction and user-facing text for one finished
+ * session turn. Kept free of I/O so the wording and the wire format are testable
+ * without a host.
+ */
+
+/** Wire `result` value for each logged `turn/end` reason. */
+export const RESULT_BY_REASON = {
+  completed: 'success',
+  error: 'failure',
+  blocked: 'blocked',
+  aborted: 'cancelled',
+  'max-tokens': 'truncated',
+  interrupted: 'interrupted',
+  forked: 'forked',
+}
+
+/** Wire `event` value for each reason; matches the `<entity>.<action>` form. */
+const EVENT_BY_REASON = {
+  completed: 'session.turn.completed',
+  error: 'session.turn.failed',
+  blocked: 'session.turn.blocked',
+  aborted: 'session.turn.cancelled',
+  'max-tokens': 'session.turn.max-tokens',
+  interrupted: 'session.turn.interrupted',
+  forked: 'session.turn.forked',
+}
+
+/** Attention kinds that are not turn ends: a tool needs approval, or the agent asked a question. */
+export const ATTENTION_KINDS = ['approval', 'question']
+
+/** Reasons a reminder can be configured for; `forked` is never a live turn end. */
+export const NOTIFIABLE_REASONS = ['completed', 'error', 'blocked', 'aborted', 'max-tokens']
+
+const MESSAGES = {
+  zh: {
+    completed: { title: 'DSH · 任务完成', message: '会话任务已完成' },
+    error: { title: 'DSH · 任务失败', message: '会话任务失败' },
+    blocked: { title: 'DSH · 等待你处理', message: '会话任务被阻塞，正在等待你的输入或确认' },
+    aborted: { title: 'DSH · 任务已中止', message: '会话任务被中止' },
+    'max-tokens': { title: 'DSH · 达到输出上限', message: '会话任务在达到输出上限后结束' },
+    approval: { title: 'DSH · 需要授权', message: '有工具在等你的授权' },
+    question: { title: 'DSH · 需要回答', message: '会话正在等你的回答' },
+    started: { title: 'DSH · 提醒已开启', message: '会话任务完成时会提醒你' },
+    withTitle: '：',
+    tool: '工具',
+  },
+  en: {
+    completed: { title: 'DSH - task finished', message: 'The session task finished' },
+    error: { title: 'DSH - task failed', message: 'The session task failed' },
+    blocked: { title: 'DSH - waiting for you', message: 'The session task is blocked on your input or approval' },
+    aborted: { title: 'DSH - task cancelled', message: 'The session task was cancelled' },
+    'max-tokens': { title: 'DSH - output limit reached', message: 'The session task ended at its output-token limit' },
+    approval: { title: 'DSH - approval needed', message: 'A tool is waiting for your approval' },
+    question: { title: 'DSH - answer needed', message: 'The session is waiting for your answer' },
+    started: { title: 'DSH - reminders on', message: 'You are notified when a session task finishes' },
+    withTitle: ': ',
+    tool: 'tool',
+  },
+}
+
+/**
+ * Human-readable duration.
+ * @param {number | undefined} ms - elapsed milliseconds, or undefined when the turn start was not observed.
+ * @returns {string | undefined} `"1m 12s"`, `"820ms"`, or undefined.
+ */
+export function formatDuration(ms) {
+  if (ms === undefined || !Number.isFinite(ms) || ms < 0) return undefined
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  const seconds = Math.round(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  const rest = seconds % 60
+  return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`
+}
+
+/**
+ * Local wall-clock timestamp with the field order the payload contract documents.
+ * @param {number} epochMs - epoch milliseconds.
+ * @returns {string} `"YYYY-MM-DD HH:mm:ss"`.
+ */
+export function formatTimestamp(epochMs) {
+  const d = new Date(epochMs)
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+    + ` ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+}
+
+/** Last path segment of a workspace directory, for a one-line toast body. */
+function basename(path) {
+  if (typeof path !== 'string' || path === '') return undefined
+  const parts = path.split(/[\\/]+/).filter(Boolean)
+  return parts.at(-1)
+}
+
+/**
+ * Build the payload handed to every channel.
+ * @param {object} input - observed turn facts.
+ * @param {string} input.reason - `turn/end` reason kind.
+ * @param {number} input.turn - turn number from the log.
+ * @param {string} input.sessionId - session identity.
+ * @param {string} [input.sessionTitle] - latest `session/title` value.
+ * @param {string} [input.cwd] - session working directory from its header.
+ * @param {number} [input.startedAt] - `turn/start` time in epoch milliseconds.
+ * @param {number} input.endedAt - `turn/end` time in epoch milliseconds.
+ * @param {string} [input.errorMessage] - flattened failure message for the error reason.
+ * @param {'zh' | 'en'} locale - copy language.
+ * @returns {{ title: string, event: string, result: string, timestamp: string, sessionId: string,
+ *   sessionTitle?: string, cwd?: string, durationMs?: number, message: string, detail?: string }} payload.
+ */
+export function buildPayload(input, locale) {
+  const copy = MESSAGES[locale] ?? MESSAGES.zh
+  const base = copy[input.reason] ?? { title: `DSH · ${input.reason}`, message: `会话任务结束（${input.reason}）` }
+  const durationMs = input.startedAt === undefined ? undefined : Math.max(0, input.endedAt - input.startedAt)
+  const named = input.sessionTitle === undefined || input.sessionTitle.trim() === ''
+    ? base.message
+    : `${base.message}${copy.withTitle}${input.sessionTitle.trim()}`
+  const failed = input.reason === 'error' && input.errorMessage !== undefined
+    ? `${named}（${input.errorMessage}）`
+    : named
+  const facts = [formatDuration(durationMs), basename(input.cwd)].filter((v) => v !== undefined)
+  return {
+    title: base.title,
+    event: EVENT_BY_REASON[input.reason] ?? `session.turn.${input.reason}`,
+    result: RESULT_BY_REASON[input.reason] ?? 'unknown',
+    timestamp: formatTimestamp(input.endedAt),
+    sessionId: input.sessionId,
+    ...(input.sessionTitle === undefined ? {} : { sessionTitle: input.sessionTitle }),
+    ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+    ...(durationMs === undefined ? {} : { durationMs }),
+    message: failed,
+    ...(facts.length === 0 ? {} : { detail: facts.join(' · ') }),
+  }
+}
+
+/**
+ * Payload for an agent that is waiting on the user rather than finishing: an
+ * approval question, or a question tool. Same wire fields as a turn reminder,
+ * with `result: "blocked"` so consumers can rank it above completions.
+ * @param {object} input - observed attention facts.
+ * @param {'approval' | 'question'} input.kind - which wait it is.
+ * @param {string} input.sessionId - session identity.
+ * @param {string} [input.sessionTitle] - latest `session/title` value.
+ * @param {string} [input.cwd] - session working directory from its header.
+ * @param {string} [input.toolName] - tool the approval is about.
+ * @param {string} [input.reason] - the asker's explanation, when it gave one.
+ * @param {string} [input.question] - first question text for a question tool.
+ * @param {number} input.at - epoch milliseconds when the wait was recorded.
+ * @param {'zh' | 'en'} locale - copy language.
+ * @returns {object} payload handed to every channel.
+ */
+export function buildAttentionPayload(input, locale) {
+  const copy = MESSAGES[locale] ?? MESSAGES.zh
+  const base = copy[input.kind]
+  const detail = input.kind === 'approval'
+    ? [input.toolName === undefined ? undefined : `${copy.tool} ${input.toolName}`, input.reason]
+    : [input.question]
+  const extra = detail.filter((value) => typeof value === 'string' && value.trim() !== '').join(' · ')
+  const facts = [basename(input.cwd)].filter((v) => v !== undefined)
+  return {
+    title: base.title,
+    event: input.kind === 'approval' ? 'session.approval.asked' : 'session.question.asked',
+    result: 'blocked',
+    timestamp: formatTimestamp(input.at),
+    sessionId: input.sessionId,
+    ...(input.sessionTitle === undefined ? {} : { sessionTitle: input.sessionTitle }),
+    ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+    message: extra === '' ? base.message : `${base.message}${copy.withTitle}${extra.slice(0, 160)}`,
+    ...(facts.length === 0 ? {} : { detail: facts.join(' · ') }),
+  }
+}
+
+/**
+ * Payload announcing that the plugin itself mounted, used as a wiring check.
+ * @param {'zh' | 'en'} locale - copy language.
+ * @param {number} now - epoch milliseconds.
+ * @returns {object} a payload with `event: "plugin.started"`.
+ */
+export function buildStartupPayload(locale, now) {
+  const copy = MESSAGES[locale] ?? MESSAGES.zh
+  return {
+    title: copy.started.title,
+    event: 'plugin.started',
+    result: 'success',
+    timestamp: formatTimestamp(now),
+    message: copy.started.message,
+  }
+}

package/lib/presence.js

@@ -0,0 +1,60 @@
+/**
+ * Foreground tracking for the "only when the window is not in front" rule.
+ *
+ * The browser half reports one record per page instance; the host keeps the
+ * latest state and treats a report as current for `activeWindowMs`. A closed
+ * window, a crashed page, or a lost network leaves a stale active record, which
+ * expiry turns back into "not in front" so reminders cannot be lost forever.
+ */
+
+/**
+ * Create the tracker.
+ * @param {object} options - tracker settings.
+ * @param {number} options.activeWindowMs - how long one report stays current.
+ * @param {() => number} [options.now] - clock, injectable for tests.
+ * @returns {{ report: (clientId: string, active: boolean) => void,
+ *   foreground: () => boolean, snapshot: () => { foreground: boolean,
+ *   clients: Array<{ clientId: string, active: boolean, ageMs: number }> } }} tracker.
+ */
+export function createPresenceTracker(options) {
+  const now = options.now ?? Date.now
+  const activeWindowMs = options.activeWindowMs
+  const clients = new Map()
+
+  const live = () => {
+    const at = now()
+    for (const [clientId, record] of clients) {
+      if (at - record.seenAt > activeWindowMs) clients.delete(clientId)
+    }
+    return at
+  }
+
+  return {
+    report(clientId, active) {
+      if (typeof clientId !== 'string' || clientId === '') return
+      clients.set(clientId, { active: active === true, seenAt: now() })
+    },
+    /**
+     * Whether the page is in front. Without any current report the answer is
+     * false — failing open, because a reminder that never arrives is worse than
+     * one that arrives while the window is focused.
+     * @returns {boolean} whether a page reported itself in front recently.
+     */
+    foreground() {
+      live()
+      for (const record of clients.values()) if (record.active) return true
+      return false
+    },
+    snapshot() {
+      const at = live()
+      return {
+        foreground: [...clients.values()].some((record) => record.active),
+        clients: [...clients.entries()].map(([clientId, record]) => ({
+          clientId,
+          active: record.active,
+          ageMs: at - record.seenAt,
+        })),
+      }
+    },
+  }
+}

package/lib/server.js

@@ -0,0 +1,116 @@
+/**
+ * The plugin's loopback JSON endpoint: pages report their foreground state, and
+ * the state is readable for diagnostics.
+ *
+ * The route answers only requests that look like they came from the harness
+ * page: the `Host` header must name the loopback interface or a trusted host
+ * the profile declared, and a report must carry `content-type: application/json`,
+ * which a cross-origin browser request cannot send without a preflight this
+ * route never grants.
+ */
+
+/** Largest accepted report body; a report is one small JSON object. */
+const MAX_BODY_BYTES = 4_096
+
+/** Whether one request addresses a host this deployment serves. */
+function allowedHost(req, trustedHosts) {
+  const host = String(req.headers?.host ?? '').split(':')[0]
+  if (host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]') return true
+  return Array.isArray(trustedHosts) && trustedHosts.includes(host)
+}
+
+/** Read a bounded JSON body; malformed or oversized input resolves to undefined. */
+function readJson(req) {
+  return new Promise((resolve) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        resolve(undefined)
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+        resolve(parsed !== null && typeof parsed === 'object' ? parsed : undefined)
+      } catch {
+        // A non-JSON body cannot carry a report; the caller answers 400.
+        resolve(undefined)
+      }
+    })
+    req.on('error', () => resolve(undefined))
+  })
+}
+
+/** Write one JSON response. */
+function json(res, status, value) {
+  const body = JSON.stringify(value)
+  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) })
+  res.end(body)
+}
+
+/**
+ * Install the endpoint on an already-mounted web server.
+ * @param {object} options - installation inputs.
+ * @param {{ register: (options: object) => () => void }} options.webServer - the host web server service.
+ * @param {string[] | undefined} options.trustedHosts - hosts the profile trusts besides loopback.
+ * @param {{ report: (clientId: string, active: boolean) => void, snapshot: () => object }} options.presence - foreground tracker.
+ * @param {(message: string, error?: unknown) => void} options.warn - plugin log sink.
+ * @returns {() => void} disposer that removes the route.
+ */
+export function installRoute(options) {
+  const { webServer, trustedHosts, presence, warn } = options
+  const base = '/task-reminder/api'
+  return webServer.register({
+    kind: 'prefix',
+    path: base,
+    handler: async (req, res) => {
+      try {
+        if (!allowedHost(req, trustedHosts)) {
+          json(res, 403, { ok: false, error: 'forbidden' })
+          return
+        }
+        const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+        const method = pathname.startsWith(`${base}/`) ? pathname.slice(base.length + 1) : undefined
+        if (method === 'state') {
+          if (req.method !== 'GET') {
+            json(res, 405, { ok: false, error: 'method' })
+            return
+          }
+          json(res, 200, { ok: true, ...presence.snapshot() })
+          return
+        }
+        if (method === 'visibility') {
+          if (req.method !== 'POST') {
+            json(res, 405, { ok: false, error: 'method' })
+            return
+          }
+          if (!String(req.headers?.['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+            json(res, 415, { ok: false, error: 'content-type' })
+            return
+          }
+          const body = await readJson(req)
+          if (body === undefined) {
+            json(res, 400, { ok: false, error: 'body' })
+            return
+          }
+          presence.report(body.client, body.active === true)
+          json(res, 200, { ok: true })
+          return
+        }
+        json(res, 404, { ok: false, error: 'not-found' })
+      } catch (error) {
+        warn('foreground route failed', error)
+        try {
+          json(res, 500, { ok: false, error: 'internal' })
+        } catch {
+          // The response was already written; nothing left to report to the page.
+        }
+      }
+    },
+  })
+}

package/lib/sound.ps1

@@ -0,0 +1,15 @@
+# ASCII-only on purpose: Windows PowerShell 5.1 decodes a BOM-less script with the
+# ANSI code page. The player runs on a background thread, so the script holds the
+# process alive for the cue's first second instead of exiting and cutting it off.
+param(
+  [string]$SoundFile = ''
+)
+
+$ErrorActionPreference = 'Stop'
+if ($SoundFile -ne '') {
+  $player = New-Object Media.SoundPlayer $SoundFile
+  $player.Play()
+} else {
+  [System.Media.SystemSounds]::Asterisk.Play()
+}
+Start-Sleep -Milliseconds 900

package/lib/toast.ps1

@@ -0,0 +1,14 @@
+# ASCII-only on purpose: Windows PowerShell 5.1 decodes a BOM-less script with the
+# ANSI code page, so localized text travels in the UTF-8 XML payload instead.
+param(
+  [Parameter(Mandatory = $true)][string]$XmlPath,
+  [string]$AppId = 'com.deepseek.dsh'
+)
+
+$ErrorActionPreference = 'Stop'
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+$document = New-Object Windows.Data.Xml.Dom.XmlDocument
+$document.LoadXml((Get-Content -Raw -Encoding UTF8 -LiteralPath $XmlPath))
+$toast = New-Object Windows.UI.Notifications.ToastNotification $document
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($AppId).Show($toast)

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@liangliang205/dsh-task-reminder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.2",
+  "description": "Remind you when a DSH session task finishes or waits on you: branded Windows toast, audible cue, and an SRA-compatible webhook.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "dsh-bundle",
+    "notification",
+    "toast",
+    "webhook"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  }
+}