dsh-plugin-desktop-notify 0.6.2 → 0.6.3

package/README.en.md

@@ -44,6 +44,7 @@ Stored in localStorage under `dsh-plugin-desktop-notify.preferences`:
 | `notifyError` | `true` | Notify when a turn fails |
 | `notifyViewed` | `false` | Also notify for the session you are looking at |
 | `badge` | `true` | Show the badge |
+| `pinAttention` | `true` | pin what needs you to the top of its group (uses the app's own pin) |
 | `excludeSubagents` | `true` | Ignore subagent sessions |
 | `titleComplete` / `titlePending` / `titleError` | empty | Custom titles; empty keeps the built-in copy |
 | `maxBodyChars` | `140` | Body length limit |

package/README.md

@@ -16,6 +16,7 @@
 - **等待你操作**——工具审批、提问、执行计划确认
 - **任务失败**——这一轮出错时提示
 - **说清楚怎么结束的**——正常完成、被拦截、输出到上限、被中止，各自一句话，不把中断说成「已完成」
+- **需要你的排在前面**——运行中、待你审批/回答、出错、未读完成的会话自动置顶到所属分组第一条，处理完自动放开
 - **小红点**——应用图标上显示「需要你的会话数」，你看过之后才清零
 - **点击通知**——切到对应会话，而不是只把应用叫到前面
 
@@ -45,6 +46,7 @@ dsh-plugin-desktop-notify
 | `notifyViewed` | `false` | 正在看的会话也通知（默认跳过） |
 | `badge` | `true` | 显示小红点 |
 | `excludeSubagents` | `true` | 忽略子智能体会话 |
+| `pinAttention` | `true` | 把需要你处理的会话自动置顶到所属分组第一条（用 DSH 自带置顶，处理完自动取消） |
 | `titleComplete` / `titlePending` / `titleError` | 空 | 自定义标题，空 = 用内置文案 |
 | `maxBodyChars` | `140` | 正文长度上限 |
 
@@ -60,6 +62,7 @@ dsh-plugin-desktop-notify
 __DSH_DESKTOP_NOTIFY__.capabilities()   // 平台、通知权限、小红点、服务可达性
 __DSH_DESKTOP_NOTIFY__.state()          // 小红点、待处理会话、最近一次通知/点击
 __DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于排查
+__DSH_DESKTOP_NOTIFY__.pinState()       // 插件置顶了哪些、你自己又置顶了哪些
 ```
 
 
@@ -72,6 +75,7 @@ __DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于
 | `POST` | `/desktop-notify/request` | 发一条通知，body：`{"title": "...", "body": "...", "sessionId": "可选"}` |
 | `GET` | `/desktop-notify/pending` | 渲染层取走待显示的通知（脚本不用调） |
 | `GET` | `/desktop-notify/turn?sessionId=...` | 渲染层确认这一轮是怎么结束的（脚本不用调） |
+| `GET`/`POST` | `/desktop-notify/pins` | 渲染层读写「插件自己置顶了哪些会话」（脚本不用调） |
 
 地址写在 `~/.dsh/desktop-notify.endpoint`，所以调用方不用猜端口：
 
@@ -107,6 +111,9 @@ urllib.request.urlopen(request, timeout=3).read()
 ## 已知限制
 
 - 重启或刷新窗口时，已经存在的「未读 / 待审批」只恢复小红点，不再补弹横幅
+- 自动置顶用的是 DSH 自己的置顶，所以会话行上会出现置顶标记，右键里也有「取消置顶」。
+  插件只取消**自己**置顶的会话，你手动置顶的一律不动；想一次清干净可在控制台跑
+  `__DSH_DESKTOP_NOTIFY__.clearPins()`
 
 - **Windows**：点通知会切到对应会话，但窗口不一定到前台——`AppUserModelID` 和主进程 focus 通道属于桌面端，渲染层插件做不到
 - **通知归属**：系统通知中心里显示为 DeepSeek Harness（用的是渲染层原生通知）

package/index.js

@@ -16,6 +16,7 @@
 
 import { execFile, spawn } from "node:child_process"
 import { randomBytes } from "node:crypto"
+import { readFileSync } from "node:fs"
 import { appendFile, mkdir, rm, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
 import { basename, dirname, join } from "node:path"
@@ -47,6 +48,8 @@ const DEFAULTS = {
   api: true,
   /** Where the endpoint URL is written for those tools. */
   endpointPath: "~/.dsh/desktop-notify.endpoint",
+  /** Where the sessions this plugin pinned are remembered across window lives. */
+  pinsPath: "~/.dsh/desktop-notify-pins.json",
   /** Longest accepted request body. */
   apiBodyLimit: 8192,
   /** How many unread requests the interface keeps. */
@@ -65,6 +68,7 @@ const TURN_END_BODIES = {
 const API_REQUEST_PATH = "/desktop-notify/request"
 const API_PENDING_PATH = "/desktop-notify/pending"
 const API_TURN_PATH = "/desktop-notify/turn"
+const API_PINS_PATH = "/desktop-notify/pins"
 
 /** Read one JSON request body, bounded by `limit` bytes. */
 function readBody(request, limit) {
@@ -237,6 +241,37 @@ function mountInterface(ctx, config, state) {
       answer(response, 200, entry === undefined ? {} : { kind: entry.kind, at: entry.at })
     }
 
+    /**
+     * Remember which sessions this plugin pinned. The renderer's origin (and so
+     * its localStorage) changes with every launch, while the sidebar pins live
+     * on the Host; this file is what lets a restart release the pins it owns
+     * instead of mistaking them for the user's own.
+     */
+    const pins = (request, response) => {
+      if (rejected(request, response, false)) return
+      if (request.method === "GET") {
+        answer(response, 200, { ids: [...state.pinnedByPlugin] })
+        return
+      }
+      if (request.method !== "POST") {
+        answer(response, 405, { ok: false, error: "use GET or POST" })
+        return
+      }
+      void readBody(request, Math.max(1024, config.apiBodyLimit))
+        .then((payload) => {
+          const ids = Array.isArray(payload?.ids) ? payload.ids.filter((id) => typeof id === "string" && id !== "") : []
+          state.pinnedByPlugin = new Set(ids.slice(0, Math.max(1, config.maxTrackedSessions)))
+          const path = expandHome(config.pinsPath)
+          if (path !== "") {
+            void mkdir(dirname(path), { recursive: true })
+              .then(() => writeFile(path, `${JSON.stringify({ ids: [...state.pinnedByPlugin] })}\n`, "utf8"))
+              .catch(() => {})
+          }
+          answer(response, 200, { ok: true, tracked: state.pinnedByPlugin.size })
+        })
+        .catch((error) => answer(response, 400, { ok: false, error: String(error?.message ?? error) }))
+    }
+
     let disposers
     try {
       disposers = [
@@ -257,6 +292,13 @@ function mountInterface(ctx, config, state) {
             answer(response, 500, {})
           }
         } }),
+        server.register({ kind: "exact", path: API_PINS_PATH, handler: (request, response) => {
+          try {
+            pins(request, response)
+          } catch {
+            answer(response, 500, { ok: false })
+          }
+        } }),
       ]
     } catch (error) {
       void noteToLog(config.logPath, `interface: cannot register routes: ${String(error)}`)
@@ -407,7 +449,19 @@ function runDetached(command, args) {
 export function apply(ctx, rawConfig) {
   const config = resolveConfig(rawConfig)
   /** The newest turn-end kind per session, read by the renderer over the local interface. */
-  const state = { lastTurnEnds: new Map() }
+  const state = { lastTurnEnds: new Map(), pinnedByPlugin: new Set() }
+  // Seeded synchronously: the renderer asks for it as soon as it applies.
+  try {
+    const pinsPath = expandHome(config.pinsPath)
+    if (pinsPath !== "") {
+      const remembered = JSON.parse(readFileSync(pinsPath, "utf8"))
+      if (Array.isArray(remembered?.ids)) {
+        for (const id of remembered.ids) if (typeof id === "string" && id !== "") state.pinnedByPlugin.add(id)
+      }
+    }
+  } catch {
+    /* no remembered pins yet */
+  }
   mountInterface(ctx, config, state)
 
   const logPath = expandHome(config.logPath)

package/lib/client.js

@@ -30,8 +30,10 @@ window.__ModuleLoader__.load({
   factory: (require) => {
     const NS = "dsh-plugin-desktop-notify"
     /** Reported by capabilities(); keep in step with package.json (cross-machine support). */
-    const VERSION = "0.6.2"
+    const VERSION = "0.6.3"
     const PREFERENCES_KEY = `${NS}:preferences`
+    /** Sessions this plugin pinned itself; a reload reads it back so it never drops a user's own pin. */
+    const PINNED_KEY = `${NS}:pinned`
 
     /** Defaults; override per field with the localStorage JSON described in README. */
     const DEFAULTS = {
@@ -42,6 +44,8 @@ window.__ModuleLoader__.load({
       notifyViewed: false,
       badge: true,
       excludeSubagents: true,
+      // Keep the sessions that need you at the top of their sidebar group.
+      pinAttention: true,
       // Empty means "use the built-in copy for the active UI language".
       titleComplete: "",
       titlePending: "",
@@ -141,6 +145,8 @@ window.__ModuleLoader__.load({
      */
     const TURN_KIND_PATH = "/desktop-notify/turn"
     const TURN_LOOKUP_TIMEOUT_MS = 800
+    /** Where the Host remembers the sessions this plugin pinned. */
+    const PINS_PATH = "/desktop-notify/pins"
 
     /** Ask the Host how one turn ended; undefined when it cannot answer in time. */
     function lookupTurnKind(sessionId) {
@@ -192,6 +198,18 @@ window.__ModuleLoader__.load({
       return preferences
     }
 
+    /** The session ids this plugin pinned in an earlier window life. */
+    function readPinnedIds() {
+      try {
+        const raw = storage()?.getItem(PINNED_KEY)
+        if (typeof raw !== "string" || raw === "") return []
+        const parsed = JSON.parse(raw)
+        return Array.isArray(parsed) ? parsed.filter((id) => typeof id === "string") : []
+      } catch {
+        return []
+      }
+    }
+
     /** Collapse whitespace and cut to the body budget. */
     function bodyText(text, maxChars) {
       const collapsed = String(text).replace(/\s+/gu, " ").trim()
@@ -310,6 +328,128 @@ window.__ModuleLoader__.load({
       /** sessionId -> ms timestamp when the current turn was first seen running. */
       const turnStartedAt = new Map()
       let lastBadge
+      /** Sessions this plugin pinned itself, so unpinning never touches the user's own pins. */
+      const selfPinned = new Set(readPinnedIds())
+      /** Whether the Host has answered with its remembered pins; nothing is pinned before that. */
+      let pinsReady = false
+      /** The most recent wanted set, so hydration can reconcile the moment it lands. */
+      let lastWanted = new Set()
+
+      /**
+       * Write the pinned-by-this-plugin set back. localStorage covers a reload of
+       * the same origin; the Host file covers a new launch, whose URL (and so
+       * this origin) has changed and taken localStorage with it.
+       */
+      function persistPins() {
+        try {
+          storage()?.setItem(PINNED_KEY, JSON.stringify([...selfPinned]))
+        } catch {
+          /* a storage-less renderer keeps the set for this life only */
+        }
+        if (typeof fetch !== "function") return
+        try {
+          void fetch(PINS_PATH, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ids: [...selfPinned] }),
+          }).catch(() => {})
+        } catch {
+          /* the local interface may not be mounted */
+        }
+      }
+
+      /**
+       * Read back the pins an earlier launch left behind. Until this answers the
+       * plugin pins nothing: acting first would make its own pins look like the
+       * user's and leave them in the sidebar forever.
+       */
+      async function hydratePins() {
+        if (typeof fetch !== "function") {
+          pinsReady = true
+          return
+        }
+        try {
+          const response = await fetch(PINS_PATH, { headers: { accept: "application/json" }, cache: "no-store" })
+          if (response.ok) {
+            const payload = await response.json()
+            if (Array.isArray(payload?.ids)) {
+              for (const sessionId of payload.ids) if (typeof sessionId === "string" && sessionId !== "") selfPinned.add(sessionId)
+            }
+          }
+        } catch {
+          /* no Host half: this life reconciles from localStorage alone */
+        }
+        pinsReady = true
+        reconcilePins(lastWanted)
+      }
+
+      /** The sidebar's pinned snapshot, or undefined on a build without the workspace service. */
+      function pinnedSnapshot() {
+        try {
+          return ctx.uiWorkspace?.workspaces?.list?.getSnapshot?.()
+        } catch {
+          return undefined
+        }
+      }
+
+      /** Pin or unpin one session, best effort: a refused call must not disturb notifications. */
+      function callPin(sessionId, pin) {
+        const service = ctx.uiWorkspace
+        const method = pin ? "pinSession" : "unpinSession"
+        if (typeof service?.[method] !== "function") return
+        try {
+          const pending = service[method](sessionId)
+          if (pending !== null && typeof pending === "object" && typeof pending.catch === "function") pending.catch(() => {})
+        } catch {
+          /* the view keeps its order */
+        }
+      }
+
+      /**
+       * Keep what needs you at the top of its group. The sidebar's own pin seats
+       * a session ahead of the rest of the group, so this pins exactly the ones
+       * the plugin would notify about and unpins each once that reason is gone —
+       * never a session the user pinned by hand, and never one this plugin did
+       * not pin in the first place.
+       */
+      function reconcilePins(wanted) {
+        lastWanted = wanted
+        if (!pinsReady) return
+        let changed = false
+        if (!preferences.pinAttention) {
+          for (const sessionId of [...selfPinned]) {
+            selfPinned.delete(sessionId)
+            callPin(sessionId, false)
+            changed = true
+          }
+          if (changed) persistPins()
+          return
+        }
+        const snapshot = pinnedSnapshot()
+        if (snapshot === undefined) return
+        const pinned = new Set(Array.isArray(snapshot.pinnedSessionIds) ? snapshot.pinnedSessionIds : [])
+        // An archived session is out of the tree anyway, and pinning it is not
+        // this plugin's business.
+        const archived = new Set(Array.isArray(snapshot.archivedSessionIds) ? snapshot.archivedSessionIds : [])
+        for (const sessionId of wanted) {
+          if (archived.has(sessionId)) continue
+          if (selfPinned.has(sessionId) || pinned.has(sessionId)) continue
+          selfPinned.add(sessionId)
+          changed = true
+          callPin(sessionId, true)
+        }
+        for (const sessionId of [...selfPinned]) {
+          if (wanted.has(sessionId) && !archived.has(sessionId)) continue
+          selfPinned.delete(sessionId)
+          changed = true
+          callPin(sessionId, false)
+        }
+        if (changed) persistPins()
+      }
+
+      // Ask the Host which pins an earlier launch left; nothing is pinned until it answers.
+      void hydratePins()
+
       /** The last banner attempt and its outcome — Windows has several ways to swallow it. */
       let lastNotify
       /** The last banner click and what it managed to do — Windows/macOS differ here. */
@@ -551,6 +691,8 @@ window.__ModuleLoader__.load({
         const statuses = ctx.uiSession.sessionStatus.getSnapshot()
         const summaries = ctx.sessions.list.getSnapshot().byId ?? {}
         const seen = new Set()
+        /** Sessions that should sit at the top of their group. */
+        const wanted = new Set()
 
         for (const [sessionId, status] of statuses) {
           const summary = summaries[sessionId]
@@ -592,8 +734,8 @@ window.__ModuleLoader__.load({
             turnStartedAt.delete(sessionId)
             const duration = started === undefined ? "" : durationText(Date.now() - started, languageOf())
             // Watching it finish is only worth a banner when the user opted in.
-            const wanted = preferences.notifyComplete && (looking ? preferences.notifyViewed : true)
-            if (wanted) deliverCompletion(sessionId, table, name, duration)
+            const shouldNotify = preferences.notifyComplete && (looking ? preferences.notifyViewed : true)
+            if (shouldNotify) deliverCompletion(sessionId, table, name, duration)
           }
 
           if (looking) {
@@ -620,6 +762,13 @@ window.__ModuleLoader__.load({
             })
           }
 
+          // The pin follows the same facts the banner and badge use, plus a
+          // running turn: anything that would make you look belongs on top.
+          const current = attention.get(sessionId) ?? {}
+          if (!looking && (running || current.completed === true || current.pendingKind !== undefined || current.error !== undefined)) {
+            wanted.add(sessionId)
+          }
+
           previous.set(sessionId, { running, completed, pendingKind })
         }
 
@@ -628,6 +777,7 @@ window.__ModuleLoader__.load({
           previous.delete(sessionId)
           turnStartedAt.delete(sessionId)
         }
+        reconcilePins(wanted)
         applyBadge()
       }
 
@@ -762,10 +912,29 @@ window.__ModuleLoader__.load({
             badge: lastBadge ?? 0,
             attention: [...attention.entries()].map(([sessionId, entry]) => ({ sessionId, ...entry })),
             tracked: [...previous.keys()],
+            pins: [...selfPinned],
             lastNotify: lastNotify ?? null,
             lastClick: lastClick ?? null,
           }
         },
+        /** What this plugin pinned, next to what the sidebar currently shows. */
+        pinState() {
+          const snapshot = pinnedSnapshot()
+          return {
+            enabled: preferences.pinAttention,
+            pinnedByPlugin: [...selfPinned],
+            pinnedByUser: Array.isArray(snapshot?.pinnedSessionIds) ? snapshot.pinnedSessionIds.filter((id) => !selfPinned.has(id)) : null,
+          }
+        },
+        /** Release every pin this plugin owns — leaves manual pins alone. */
+        clearPins() {
+          for (const sessionId of [...selfPinned]) {
+            selfPinned.delete(sessionId)
+            callPin(sessionId, false)
+          }
+          persistPins()
+          return this.pinState()
+        },
         simulateComplete(sessionId = "desktop-notify-simulation") {
           const table = copy(languageOf())
           setAttention(sessionId, { completed: true })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-desktop-notify",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "description": "Desktop notifications and a Dock/taskbar badge for DeepSeek Harness: a finished turn, a pending approval or question, and a failure, with click-through back to the session",
   "license": "MIT",
@@ -58,5 +58,8 @@
   },
   "scripts": {
     "test": "node test/client.test.mjs && node test/host.test.mjs /tmp/dsh-notify-host-test.log"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }