dsh-plugin-desktop-notify 0.6.3 → 0.6.5

package/README.en.md

@@ -44,7 +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) |
+| `orderAttention` | `true` | seat what needs you below your pins (writes the view's order, never the pin state) |
 | `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,7 +16,7 @@
 - **等待你操作**——工具审批、提问、执行计划确认
 - **任务失败**——这一轮出错时提示
 - **说清楚怎么结束的**——正常完成、被拦截、输出到上限、被中止，各自一句话，不把中断说成「已完成」
-- **需要你的排在前面**——运行中、待你审批/回答、出错、未读完成的会话自动置顶到所属分组第一条，处理完自动放开
+- **还在进行的排在前面**——正在跑、等你审批/回答、刚出错 的会话排到**手动置顶的下面、其余会话的上面**，处理完自动放回原位；完成未读只进小红点，不搬动列表
 - **小红点**——应用图标上显示「需要你的会话数」，你看过之后才清零
 - **点击通知**——切到对应会话，而不是只把应用叫到前面
 
@@ -46,7 +46,7 @@ dsh-plugin-desktop-notify
 | `notifyViewed` | `false` | 正在看的会话也通知（默认跳过） |
 | `badge` | `true` | 显示小红点 |
 | `excludeSubagents` | `true` | 忽略子智能体会话 |
-| `pinAttention` | `true` | 把需要你处理的会话自动置顶到所属分组第一条（用 DSH 自带置顶，处理完自动取消） |
+| `orderAttention` | `true` | 把仍在进行中的会话排到手动置顶下面（不改置顶状态；关掉后完全不碰排序） |
 | `titleComplete` / `titlePending` / `titleError` | 空 | 自定义标题，空 = 用内置文案 |
 | `maxBodyChars` | `140` | 正文长度上限 |
 
@@ -62,7 +62,7 @@ dsh-plugin-desktop-notify
 __DSH_DESKTOP_NOTIFY__.capabilities()   // 平台、通知权限、小红点、服务可达性
 __DSH_DESKTOP_NOTIFY__.state()          // 小红点、待处理会话、最近一次通知/点击
 __DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于排查
-__DSH_DESKTOP_NOTIFY__.pinState()       // 插件置顶了哪些、你自己又置顶了哪些
+__DSH_DESKTOP_NOTIFY__.orderState()     // 当前被排到前面的是哪几条、按什么顺序
 ```
 
 
@@ -111,9 +111,10 @@ urllib.request.urlopen(request, timeout=3).read()
 ## 已知限制
 
 - 重启或刷新窗口时，已经存在的「未读 / 待审批」只恢复小红点，不再补弹横幅
-- 自动置顶用的是 DSH 自己的置顶，所以会话行上会出现置顶标记，右键里也有「取消置顶」。
-  插件只取消**自己**置顶的会话，你手动置顶的一律不动；想一次清干净可在控制台跑
-  `__DSH_DESKTOP_NOTIFY__.clearPins()`
+- 这个排序是插件接管「手动排序」实现的：插件只写「需要你」那几条的顺序，其余会话仍然按最近更新往后排，
+  所以视觉上和「最近更新」一样，只是多了一条仍在进行中的带状区域。切换窗口焦点不会触发重排。
+  代价是侧栏的排序方式会显示成「手动」，
+  而且你把会话拖动排序后，下一次有会话需要你时会被重排覆盖。不想要就 `orderAttention: false`
 
 - **Windows**：点通知会切到对应会话，但窗口不一定到前台——`AppUserModelID` 和主进程 focus 通道属于桌面端，渲染层插件做不到
 - **通知归属**：系统通知中心里显示为 DeepSeek Harness（用的是渲染层原生通知）

package/index.js

@@ -16,7 +16,6 @@
 
 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"
@@ -48,8 +47,6 @@ 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. */
@@ -68,7 +65,6 @@ 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) {
@@ -241,37 +237,6 @@ 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 = [
@@ -292,13 +257,6 @@ 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)}`)
@@ -449,19 +407,7 @@ 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(), 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 */
-  }
+  const state = { lastTurnEnds: new Map() }
   mountInterface(ctx, config, state)
 
   const logPath = expandHome(config.logPath)

package/lib/client.js

@@ -30,10 +30,8 @@ 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.3"
+    const VERSION = "0.6.5"
     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 = {
@@ -44,8 +42,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,
+      // Seat what needs you directly below the manual pins in its group.
+      orderAttention: true,
       // Empty means "use the built-in copy for the active UI language".
       titleComplete: "",
       titlePending: "",
@@ -145,8 +143,9 @@ 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"
+    /** The sidebar's flat-list order key, and how long a tier change waits before it is written. */
+    const FLAT_ORDER_KEY = "__flat_session_order__"
+    const ORDER_SETTLE_MS = 600
 
     /** Ask the Host how one turn ended; undefined when it cannot answer in time. */
     function lookupTurnKind(sessionId) {
@@ -198,18 +197,6 @@ 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()
@@ -328,128 +315,101 @@ 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.
+       * The sessions that need you, in the order they started needing you.
+       * FIFO on purpose: a new arrival joins the bottom of the tier instead of
+       * displacing whoever was already in it, so a few running turns can never
+       * shuffle the sidebar under the cursor.
        */
-      function persistPins() {
+      let tier = []
+      /** One coalesced write per settled tier, never one per status tick. */
+      let tierTimer
+      /** Whether an order was ever written, so an empty tier can clear it once and then stay quiet. */
+      let hasWrittenOrder = false
+      /** The last order written per account key; an unchanged tier touches nothing. */
+      const lastOrderByKey = new Map()
+
+      /** The sidebar's workspace snapshot, or undefined on a build without the service. */
+      function workspaceSnapshot() {
         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(() => {})
+          return ctx.uiWorkspace?.workspaces?.list?.getSnapshot?.()
         } catch {
-          /* the local interface may not be mounted */
+          return undefined
         }
       }
 
-      /**
-       * 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)
+      /** True when two id arrays are identical, so a no-op sync never reorders anything. */
+      function sameOrder(left, right) {
+        if (left.length !== right.length) return false
+        for (let index = 0; index < left.length; index += 1) if (left[index] !== right[index]) return false
+        return true
       }
 
-      /** 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
-        }
+      /** Recompute the tier; only a membership change schedules a write. */
+      function updateTier(wanted) {
+        const next = tier.filter((sessionId) => wanted.has(sessionId))
+        for (const sessionId of wanted) if (!next.includes(sessionId)) next.push(sessionId)
+        if (sameOrder(next, tier)) return
+        tier = next
+        scheduleOrderWrite()
       }
 
-      /** 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 */
-        }
+      /** Coalesce a burst of status ticks into one write. */
+      function scheduleOrderWrite() {
+        if (tierTimer !== undefined) return
+        tierTimer = setTimeout(() => {
+          tierTimer = undefined
+          writeOrder()
+        }, ORDER_SETTLE_MS)
       }
 
       /**
-       * 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.
+       * Seat the tier directly below the manual pins in every group. Only the
+       * tier ids are written, so everything else keeps falling back to recency:
+       * the result reads like the "most recent" sort with a needs-you band.
        */
-      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
+      function writeOrder() {
+        const view = ctx.uiWorkspace?.view
+        if (typeof view?.setSessionOrder !== "function") return
+        const snapshot = workspaceSnapshot()
+        const list = ctx.sessions.list.getSnapshot()
+        if (snapshot === undefined || list?.phase !== "ready") return
+        // The workspace registry hydrates separately; writing before it is ready
+        // would file every session under "" and then rewrite them a moment later.
+        if (snapshot.phase !== "ready" || snapshot.state === "loading") return
+        const archived = new Set(Array.isArray(snapshot.archivedSessionIds) ? snapshot.archivedSessionIds : [])
+        const live = tier.filter((sessionId) => !archived.has(sessionId))
+        const active = preferences.orderAttention && live.length > 0
+        if (!active && !hasWrittenOrder) return
+        const accounted = new Set()
+        const groups = []
+        for (const item of Array.isArray(snapshot.items) ? snapshot.items : []) {
+          const memberIds = Array.isArray(item?.sessionIds) ? item.sessionIds : []
+          for (const sessionId of memberIds) accounted.add(sessionId)
+          groups.push([item?.workspaceId ?? "", memberIds])
+        }
+        const ids = Array.isArray(list.ids) ? list.ids : []
+        const known = (sessionId) => list.byId?.[sessionId] !== undefined
+        groups.push(["", ids.filter((sessionId) => known(sessionId) && !accounted.has(sessionId))])
+        groups.push([FLAT_ORDER_KEY, ids.filter(known)])
+        for (const [key, memberIds] of groups) {
+          const members = new Set(memberIds)
+          const order = active ? live.filter((sessionId) => members.has(sessionId)) : []
+          const signature = order.join("\n")
+          // Never touch a group this plugin has not seated before: writing an
+          // empty order there would wipe the user's own drag arrangement.
+          if (lastOrderByKey.get(key) === signature) continue
+          if (signature === "" && !lastOrderByKey.has(key)) continue
+          try {
+            view.setSessionOrder(key, order, {})
+            lastOrderByKey.set(key, signature)
+          } catch {
+            /* a view store that refuses the write keeps its own order */
           }
-          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()
+        hasWrittenOrder = active
       }
 
-      // 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. */
@@ -762,10 +722,14 @@ 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.
+          // Only what is still in flight is seated: a running turn, a question
+          // waiting on you, or a failure. An unread completion stays in the
+          // badge instead — promoting it would move the list every time you
+          // read a session, and it is exactly what made the band churn.
+          // Focus is deliberately not part of this: a running turn keeps its
+          // seat while you tab away, so the band never reshuffles on blur.
           const current = attention.get(sessionId) ?? {}
-          if (!looking && (running || current.completed === true || current.pendingKind !== undefined || current.error !== undefined)) {
+          if (running || pendingKind !== undefined || current.error !== undefined) {
             wanted.add(sessionId)
           }
 
@@ -777,7 +741,7 @@ window.__ModuleLoader__.load({
           previous.delete(sessionId)
           turnStartedAt.delete(sessionId)
         }
-        reconcilePins(wanted)
+        updateTier(wanted)
         applyBadge()
       }
 
@@ -869,6 +833,21 @@ window.__ModuleLoader__.load({
         }
       }, "dsh-plugin-desktop-notify: badge release")
 
+      /* Give the sidebar back the order this plugin took when it unloads. */
+      ctx.effect(() => () => {
+        const view = ctx.uiWorkspace?.view
+        if (typeof view?.setSessionOrder !== "function") return
+        for (const [key, signature] of lastOrderByKey) {
+          if (signature === "") continue
+          try {
+            view.setSessionOrder(key, [], {})
+          } catch {
+            /* a torn-down view keeps whatever it had */
+          }
+        }
+        lastOrderByKey.clear()
+      }, "dsh-plugin-desktop-notify: order release")
+
       /*
        * Diagnostic surface for DevTools (⌘⌥I):
        *   __DSH_DESKTOP_NOTIFY__.capabilities()      — what this renderer supports
@@ -912,28 +891,24 @@ window.__ModuleLoader__.load({
             badge: lastBadge ?? 0,
             attention: [...attention.entries()].map(([sessionId, entry]) => ({ sessionId, ...entry })),
             tracked: [...previous.keys()],
-            pins: [...selfPinned],
+            order: [...tier],
             lastNotify: lastNotify ?? null,
             lastClick: lastClick ?? null,
           }
         },
-        /** What this plugin pinned, next to what the sidebar currently shows. */
-        pinState() {
-          const snapshot = pinnedSnapshot()
+        /** Which sessions the plugin seats under the pins, and in what order. */
+        orderState() {
           return {
-            enabled: preferences.pinAttention,
-            pinnedByPlugin: [...selfPinned],
-            pinnedByUser: Array.isArray(snapshot?.pinnedSessionIds) ? snapshot.pinnedSessionIds.filter((id) => !selfPinned.has(id)) : null,
+            enabled: preferences.orderAttention,
+            tier: [...tier],
+            written: Object.fromEntries([...lastOrderByKey].map(([key, value]) => [key, value === "" ? 0 : value.split("\n").length])),
           }
         },
-        /** 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()
+        /** Drop the whole tier; the next settle clears it from the sidebar. */
+        clearOrder() {
+          tier = []
+          scheduleOrderWrite()
+          return this.orderState()
         },
         simulateComplete(sessionId = "desktop-notify-simulation") {
           const table = copy(languageOf())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-desktop-notify",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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",