dsh-notify-windows 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeverusZh
+
+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.en.md

@@ -0,0 +1,75 @@
+# dsh-notify
+
+A DeepSeek Harness (DSH) plugin that sends Windows toast notifications whenever
+the agent needs your attention:
+
+1. Task finished (turn/end) — a turn completed, errored, or hit the token cap;
+2. Approval pending (approval/asked) — a permission decision is waiting for you
+   (skipped when the session's approval policy is never, since nothing waits);
+3. Question pending — the agent asked you a question via ask_user_question,
+   including calls nested inside run_code programs (in this deployment every
+   tool call goes through run_code, so the plugin scans run_code source for
+   tools.ask_user_question( calls).
+
+Zero runtime dependencies: toasts are sent through Windows PowerShell 5.1's
+WinRT toast API (lib/notify.ps1), with the AppUserModelId registered under HKCU
+on first use (no admin required).
+
+## Install
+
+```powershell
+pwsh scripts\install-profile.ps1 -Profile web   # or: dsh plugin --profile web add dsh-notify-windows
+```
+
+The script deploys the package into the profile's hoisted node_modules as
+dsh-notify-<version> (the versioned directory lets a running host hot-load a
+redeploy without a restart) and adds this entry to the profile's
+cordis.patch.yml, which the running host hot-applies:
+
+```yaml
+- insert:
+    - id: dsh-notify
+      name: 'dsh-notify-0.4.0'
+      config:
+        enabled: true
+        reasons: [completed, error, max-tokens]
+        includeSubagents: false
+        notifyOnStart: true
+        notifyOnApproval: true
+        notifyOnAskUser: true
+        appName: 'DeepSeek Harness'
+        aumid: 'DeepSeekHarness.Notify'
+        log: true
+        debug: false
+```
+
+## Configuration
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| enabled | true | master switch |
+| reasons | [completed, error, max-tokens] | turn-end reasons to notify |
+| includeSubagents | false | also notify subagent sessions |
+| notifyOnStart | false | toast when the plugin loads |
+| notifyOnApproval | true | toast on approval/asked (policy-aware) |
+| notifyOnAskUser | true | toast when the agent asks a question |
+| appName | DeepSeek Harness | toast source display name |
+| aumid | DeepSeekHarness.Notify | toast AppUserModelId |
+| log | true | write %TEMP%\dsh-notify\notify.log |
+| debug | false | log every session event (diagnostics, heavy) |
+
+## Verify
+
+```powershell
+node scripts\smoke-test.mjs
+```
+
+Runs the plugin on a bare cordis Context with synthetic events and asserts the
+log output (task, approval, and question toasts fire; subagent / never-policy /
+unrelated events are filtered).
+
+## Limitations
+
+- Windows only (requires Windows PowerShell 5.1, shipped with Windows 10/11);
+- toast delivery depends on the system notification / Focus Assist settings;
+- the run_code question detection is heuristic and may miss or misreport.

package/README.md

@@ -0,0 +1,93 @@
+# dsh-notify
+
+DeepSeek Harness（DSH）插件：Agent 需要你关注时，向 Windows 发送系统桌面通知。
+
+触发时机（三类，均可在配置中开关）：
+
+1. 任务完成（turn/end）：Agent 每完成一轮回复，或任务出错/输出超限时弹窗提醒；
+2. 权限审批（approval/asked）：有操作在等待你的审批时立即提醒（会话审批策略为
+   never 时自动跳过，因为那时没有东西在等你）；
+3. 提问确认（ask_user_question）：Agent 向你提问、等待回答时提醒——包括通过
+   run_code 内部调用 ask_user_question 的情形（本部署下所有工具都经 run_code
+   调用，插件会扫描 run_code 程序源码里的 tools.ask_user_question 调用）。
+
+让你无需盯着网页界面也能知道任务结束、需要审批或等待你回答。
+
+## 功能
+
+- 监听会话事件流：turn/end、approval/asked、tool/call（含 run_code 源码启发式检测）；
+- turn/end 支持按结束原因过滤：completed、error、max-tokens、aborted、interrupted、blocked；
+- 审批提醒按会话生效策略折叠：策略为 never 时不提醒；
+- 默认忽略子代理（subagent）会话，只提醒主会话，避免通知轰炸；
+- 通知标题自动使用会话标题（session/title），正文显示原因与轮次；
+- 零运行时依赖：通知通过 Windows PowerShell 5.1 的 WinRT Toast API 发送，并自动注册通知用的 AppUserModelId；
+- 可选的日志文件（%TEMP%\dsh-notify\notify.log）与 debug 事件日志便于排查。
+
+## 工作原理
+
+turn/end、approval/asked、tool/call (session/event) -> lib/index.js -> spawn powershell.exe -> lib/notify.ps1 -> WinRT Toast
+
+1. 插件在根上下文监听 session/event；
+2. 匹配到关注的结束原因/审批请求/提问调用后生成标题与正文；
+3. 启动 powershell.exe 执行 lib/notify.ps1：先按需在 HKCU\SOFTWARE\Classes\AppUserModelId 下注册 AUMID（无需管理员权限），再发送 Toast。
+
+## 安装
+
+把本包放进 DSH profile 可解析的位置，然后在 profile 的 cordis.patch.yml 里追加条目。
+
+### 方式一：自动安装脚本（Windows）
+
+pwsh scripts\install-profile.ps1 -Profile web
+
+脚本会把插件复制到 profile 的 hoisted node_modules（目录名为 dsh-notify-版本号，
+重新部署时目录名变化可使运行中的宿主热加载新代码而无需重启），并幂等地写入/更新
+$HOME\.dsh\profiles\web\cordis.patch.yml（该文件被运行中的 DSH 热监视）：
+
+- insert:
+    - id: dsh-notify
+      name: 'dsh-notify-0.4.0'
+      config:
+        enabled: true
+        reasons: [completed, error, max-tokens]
+        includeSubagents: false
+        notifyOnStart: true
+        notifyOnApproval: true
+        notifyOnAskUser: true
+        appName: 'DeepSeek Harness'
+        aumid: 'DeepSeekHarness.Notify'
+        log: true
+        debug: false
+
+### 方式二：dsh plugin 命令
+
+dsh plugin --profile web add 本仓库路径
+
+再手动把上面的 insert 条目加入 cordis.patch.yml（注意：修改插件代码后若想被运行中的宿主立即加载，请用安装脚本，它会更换部署目录名以绕过模块缓存）。
+
+## 配置项
+
+enabled            true    总开关
+reasons            [completed, error, max-tokens]    需要提醒的回合结束原因
+includeSubagents   false   是否也提醒子代理会话
+notifyOnStart      false   插件加载时发一条「已激活」通知
+notifyOnApproval   true    审批请求提醒（策略 never 时自动跳过）
+notifyOnAskUser    true    Agent 提问等待回答时提醒
+appName            DeepSeek Harness    通知来源显示名与兜底标题
+aumid              DeepSeekHarness.Notify    通知 AppUserModelId
+log                true    写日志到 %TEMP%\dsh-notify\notify.log
+debug              false   把所有收到的会话事件写入日志（排查用，量大会产生大量磁盘写入）
+
+## 验证
+
+node scripts\smoke-test.mjs
+
+独立进程内用 cordis Context 模拟会话事件，通过后会弹出多条测试通知（任务完成、
+审批、提问），并断言日志记录与过滤行为。
+
+## 限制与说明
+
+- 仅支持 Windows（依赖 Windows PowerShell 5.1，Windows 10/11 自带）；
+- 通知是否弹出受系统「专注助手 / 通知中心」设置影响；
+- Toast 显示为 appName 名称；首次发送会自动注册 AUMID（HKCU，无需管理员）；
+- 审批提醒只在会话审批策略为 ask（默认）时有意义；策略为 never 的会话不提醒；
+- 提问检测依赖 run_code 程序源码中出现 tools.ask_user_question( 调用，属启发式，可能漏检或误报。

package/lib/index.js

@@ -0,0 +1,211 @@
+// dsh-notify — DeepSeek Harness plugin: send a Windows toast notification
+// whenever the agent needs the user's attention:
+//   - turn/end          — a task completed, failed, or was cut off;
+//   - approval/asked    — a permission approval is waiting (only when the
+//                         session's effective approval policy is "ask");
+//   - tool/call         — the agent called the ask_user_question tool and is
+//                         waiting for an answer.
+//
+// Zero runtime dependencies: notifications go through the toast sender
+// script (./notify.ps1) executed by Windows PowerShell 5.1, whose .NET
+// Framework runtime supports the WinRT toast API.
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NOTIFY_SCRIPT = fileURLToPath(new URL("./notify.ps1", import.meta.url));
+const VERSION = "0.4.0";
+
+const REASON_TEXT = {
+  completed: "任务已完成",
+  error: "任务出错",
+  "max-tokens": "输出达到 token 上限",
+  aborted: "任务已取消",
+  interrupted: "任务中断",
+  blocked: "任务未开始",
+};
+
+export const name = "dsh-notify";
+
+function truncate(text, max) {
+  if (typeof text !== "string") return "";
+  return text.length > max ? text.slice(0, max) + "…" : text;
+}
+
+/** First question text of an ask_user_question tool call, if parseable. */
+function extractAskQuestion(argumentsJson) {
+  try {
+    const parsed = JSON.parse(argumentsJson);
+    const first = Array.isArray(parsed?.questions) ? parsed.questions[0] : undefined;
+    return typeof first?.question === "string" ? first.question : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * This deployment invokes every tool through run_code programs, so a real
+ * question never appears as a model-level ask_user_question tool call.
+ * Detect the nested call inside a run_code program's code and pull out the
+ * first question text.
+ */
+function extractQuestionFromCode(argumentsJson) {
+  try {
+    const parsed = JSON.parse(argumentsJson);
+    const code = typeof parsed?.code === "string" ? parsed.code : "";
+    const callIndex = code.search(/tools\.ask_user_question\s*\(/);
+    if (callIndex < 0) return undefined;
+    const region = code.slice(callIndex, callIndex + 8000);
+    const matches = [...region.matchAll(/question\s*:\s*["']([^"']{2,200})["']/g)];
+    return matches.length > 0 ? matches[0][1] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export default function dshNotify(ctx, config = {}) {
+  const cfg = {
+    enabled: true,
+    reasons: ["completed", "error", "max-tokens"],
+    includeSubagents: false,
+    notifyOnStart: false,
+    notifyOnApproval: true,
+    notifyOnAskUser: true,
+    appName: "DeepSeek Harness",
+    aumid: "DeepSeekHarness.Notify",
+    log: true,
+    debug: false,
+    ...config,
+  };
+  const reasons = new Set(cfg.reasons);
+  const logPath = join(tmpdir(), "dsh-notify", "notify.log");
+
+  const log = (entry) => {
+    if (!cfg.log) return;
+    try {
+      mkdirSync(join(tmpdir(), "dsh-notify"), { recursive: true });
+      appendFileSync(logPath, JSON.stringify({ time: Date.now(), ...entry }) + "\n");
+    } catch {
+      // diagnostics must never break the agent loop
+    }
+  };
+
+  const sendToast = (title, body) => {
+    const child = spawn(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        NOTIFY_SCRIPT,
+        "-Title",
+        title,
+        "-Body",
+        body,
+        "-Aumid",
+        cfg.aumid,
+        "-AppName",
+        cfg.appName,
+      ],
+      { stdio: "ignore", windowsHide: true },
+    );
+    child.on("error", (error) => {
+      log({ event: "error", message: String(error?.message ?? error) });
+      ctx.logger?.warn?.("dsh-notify: 启动通知进程失败", error);
+    });
+    child.on("exit", (code) => {
+      if (code !== 0) {
+        log({ event: "error", code });
+        ctx.logger?.warn?.("dsh-notify: 通知进程退出码 " + code);
+      }
+    });
+  };
+
+  const titleFor = (session) => {
+    try {
+      return ctx.sessionTitle?.get?.(session)?.title;
+    } catch {
+      return undefined;
+    }
+  };
+
+  /** True for subagent sessions when subagents are excluded. */
+  const isFilteredSession = (session) => {
+    if (cfg.includeSubagents) return false;
+    return session?.header?.origin === "subagent" || session?.header?.depth !== undefined;
+  };
+
+  /** Last approval/policy event of the session, or undefined (defaults to ask). */
+  const effectivePolicy = (session) => {
+    const events = session?.events ?? [];
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index];
+      if (event?.type === "approval/policy") return event.data?.policy;
+    }
+    return undefined;
+  };
+
+  ctx.on("session/event", (session, event) => {
+    if (!cfg.enabled) return;
+    if (cfg.debug) {
+      log({ event: "debug", type: event.type, name: event.data?.name ?? null, sessionId: session?.id });
+    }
+    if (isFilteredSession(session)) return;
+
+    if (event.type === "turn/end") {
+      const reason = event.data?.reason;
+      if (typeof reason?.kind !== "string" || !reasons.has(reason.kind)) return;
+      const title = titleFor(session) || cfg.appName;
+      const body = REASON_TEXT[reason.kind] ?? "任务已结束";
+      sendToast(title, body + (Number.isInteger(event.data.turn) ? "（第 " + event.data.turn + " 轮）" : ""));
+      log({
+        event: "notify",
+        sessionId: session?.id,
+        reason: reason.kind,
+        turn: event.data?.turn,
+        title,
+        body,
+      });
+      return;
+    }
+
+    if (event.type === "approval/asked" && cfg.notifyOnApproval) {
+      // Never notify when the session policy auto-rejects: nothing waits for
+      // the user, so a toast would be noise.
+      if (effectivePolicy(session) === "never") return;
+      const data = event.data ?? {};
+      const body = typeof data.toolName === "string"
+        ? (typeof data.reason === "string" && data.reason.length > 0
+          ? "工具 " + data.toolName + "：" + truncate(data.reason, 100)
+          : "工具 " + data.toolName)
+        : "有一项操作等待你的批准";
+      sendToast(cfg.appName + " · 需要审批", body);
+      log({ event: "approval", sessionId: session?.id, id: data.id, toolName: data.toolName, reason: data.reason });
+      return;
+    }
+
+    if (event.type === "tool/call" && cfg.notifyOnAskUser) {
+      const data = event.data ?? {};
+      let question;
+      if (data.name === "ask_user_question") {
+        question = extractAskQuestion(data.arguments);
+      } else if (data.name === "run_code" && typeof data.arguments === "string" && data.arguments.includes("ask_user_question")) {
+        question = extractQuestionFromCode(data.arguments);
+      }
+      if (question !== undefined || data.name === "ask_user_question") {
+        sendToast(cfg.appName + " · 需要回答", question ? truncate(question, 100) : "Agent 正在等待你的确认");
+        log({ event: "ask-user", sessionId: session?.id, question: question ?? null });
+      }
+      return;
+    }
+  });
+
+  log({ event: "start", version: VERSION, enabled: cfg.enabled, reasons: [...reasons], sessionId: null });
+  if (cfg.enabled && cfg.notifyOnStart) {
+    sendToast(cfg.appName, "任务完成提醒已激活（v" + VERSION + "）");
+  }
+}

package/lib/notify.ps1

@@ -0,0 +1,35 @@
+# dsh-notify toast sender (Windows PowerShell 5.1 required: WinRT projection).
+# Parameters are bound by PowerShell from the process argument vector, so this
+# file stays ASCII-only and needs no BOM.
+param(
+  [Parameter(Mandatory = $true)][string]$Title,
+  [Parameter(Mandatory = $true)][string]$Body,
+  [string]$Aumid = "DeepSeekHarness.Notify",
+  [string]$AppName = "DeepSeek Harness"
+)
+$ErrorActionPreference = "Stop"
+
+# Register the AppUserModelId once under HKCU so Win32 toasts are allowed.
+# Best effort: if the write is denied we still try to show the toast below.
+$key = "HKCU:\SOFTWARE\Classes\AppUserModelId\$Aumid"
+try {
+  if (-not (Test-Path $key)) {
+    New-Item -Path $key -Force | Out-Null
+    New-ItemProperty -Path $key -Name DisplayName -Value $AppName -PropertyType String -Force | Out-Null
+  }
+} catch {
+  Write-Warning ("AUMID registration failed: " + $_.Exception.Message)
+}
+
+# Project the WinRT toast API (supported natively by .NET Framework).
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+
+$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$texts = $xml.GetElementsByTagName("text")
+$texts.Item(0).AppendChild($xml.CreateTextNode($Title)) | Out-Null
+$texts.Item(1).AppendChild($xml.CreateTextNode($Body)) | Out-Null
+
+$toast = New-Object Windows.UI.Notifications.ToastNotification($xml)
+$notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($Aumid)
+$notifier.Show($toast)
+Write-Output "toast shown"

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "dsh-notify-windows",
+  "version": "0.4.0",
+  "description": "DeepSeek Harness 插件：任务完成时发送 Windows 系统通知",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SeverusZh/dsh-notify-windows.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "notify",
+    "toast",
+    "windows"
+  ]
+}