dsh-plugin-desktop-notify 0.5.7 → 0.6.1

package/README.en.md

@@ -55,6 +55,48 @@ __DSH_DESKTOP_NOTIFY__.state()
 __DSH_DESKTOP_NOTIFY__.report()
 ```
 
+
+## Notification interface for other tools
+
+The Host half exposes two loopback routes for scripts, browser agents and cron
+jobs:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/desktop-notify/request` | Post one notification: `{"title": "...", "body": "...", "sessionId": "optional"}` |
+| `GET` | `/desktop-notify/pending` | The renderer drains what is waiting (scripts do not call it) |
+
+The address is written to `~/.dsh/desktop-notify.endpoint`, so callers never guess
+the port:
+
+```bash
+curl -s "$(cat ~/.dsh/desktop-notify.endpoint)" \
+  -H 'content-type: application/json' \
+  -d '{"title":"BrowserOS needs you","body":"A takeover request is waiting"}'
+```
+
+Python:
+
+```python
+import json, pathlib, urllib.request
+
+url = pathlib.Path.home().joinpath(".dsh/desktop-notify.endpoint").read_text().strip()
+request = urllib.request.Request(
+    url,
+    data=json.dumps({"title": "BrowserOS needs you", "body": "A takeover request is waiting"}).encode(),
+    headers={"content-type": "application/json"},
+)
+urllib.request.urlopen(request, timeout=3).read()
+```
+
+Notes:
+
+- The banner is posted by **DSH itself** (attributed to DeepSeek Harness), not by
+  a script host
+- Clicking it raises the window; with `sessionId` it also switches to that session
+- The interface binds loopback only and needs no login; `enabled: false` switches
+  off the osascript fallback, not the interface
+
 ## Known limits
 
 - **Windows**: clicking a notification switches the session, but the window does

package/README.md

@@ -53,6 +53,44 @@ __DSH_DESKTOP_NOTIFY__.state()          // 小红点、待处理会话、最近
 __DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于排查
 ```
 
+
+## 给其它工具用的通知接口
+
+宿主半边在**回环地址**上开了两个路由，供脚本、浏览器代理、定时任务调用：
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| `POST` | `/desktop-notify/request` | 发一条通知，body：`{"title": "...", "body": "...", "sessionId": "可选"}` |
+| `GET` | `/desktop-notify/pending` | 渲染层取走待显示的通知（脚本不用调） |
+
+地址写在 `~/.dsh/desktop-notify.endpoint`，所以调用方不用猜端口：
+
+```bash
+curl -s "$(cat ~/.dsh/desktop-notify.endpoint)" \
+  -H 'content-type: application/json' \
+  -d '{"title":"BrowserOS 需要你","body":"有一个接管请求"}'
+```
+
+Python（比如监听 neo 的守护脚本）：
+
+```python
+import json, pathlib, urllib.request
+
+url = pathlib.Path.home().joinpath(".dsh/desktop-notify.endpoint").read_text().strip()
+request = urllib.request.Request(
+    url,
+    data=json.dumps({"title": "BrowserOS 需要你", "body": "有一个接管请求"}).encode(),
+    headers={"content-type": "application/json"},
+)
+urllib.request.urlopen(request, timeout=3).read()
+```
+
+要点：
+
+- 通知由 **DSH 自己弹出**（归属 DeepSeek Harness），不是 Script Editor
+- 点通知会把窗口叫到前面；带 `sessionId` 时会切到那个会话
+- 接口只监听回环地址，不需要登录；`enabled: false` 只关 osascript 兜底，不影响接口
+
 ## 已知限制
 
 - **Windows**：点通知会切到对应会话，但窗口不一定到前台——`AppUserModelID` 和主进程 focus 通道属于桌面端，渲染层插件做不到

package/index.js

@@ -15,9 +15,9 @@
  */
 
 import { execFile, spawn } from "node:child_process"
-import { appendFile, mkdir } from "node:fs/promises"
+import { appendFile, mkdir, rm, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
-import { basename, dirname } from "node:path"
+import { basename, dirname, join } from "node:path"
 
 /** Read the notification in argv order, so no AppleScript string escaping is needed. */
 const APPLESCRIPT = [
@@ -42,6 +42,14 @@ const DEFAULTS = {
   maxTrackedSessions: 64,
   /** Log the decision without spawning osascript/afplay; the tests use it. */
   dryRun: false,
+  /** Local interface other tools post notifications to (see README). */
+  api: true,
+  /** Where the endpoint URL is written for those tools. */
+  endpointPath: "~/.dsh/desktop-notify.endpoint",
+  /** Longest accepted request body. */
+  apiBodyLimit: 8192,
+  /** How many unread requests the interface keeps. */
+  apiQueueLimit: 50,
 }
 
 /** Turn-end bodies for the kinds that carry no model text. */
@@ -52,6 +60,178 @@ const TURN_END_BODIES = {
   "max-tokens": () => "输出达到上限，本轮结束",
 }
 
+/** The URL path tools post to, and the path the renderer drains. */
+const API_REQUEST_PATH = "/desktop-notify/request"
+const API_PENDING_PATH = "/desktop-notify/pending"
+
+/** Read one JSON request body, bounded by `limit` bytes. */
+function readBody(request, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    request.on("data", (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        reject(new Error("body too large"))
+        request.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    request.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")))
+      } catch (error) {
+        reject(error)
+      }
+    })
+    request.on("error", reject)
+  })
+}
+
+/** Write one JSON answer with the headers a local tool needs. */
+function answer(response, status, payload) {
+  const body = JSON.stringify(payload)
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+    "cache-control": "no-store",
+    "access-control-allow-origin": "*",
+    "access-control-allow-headers": "content-type",
+  })
+  response.end(body)
+}
+
+/**
+ * Mount the local notification interface other tools (a watch script, a
+ * browser agent, a cron job) post to.
+ *
+ * The interface is two loopback HTTP routes on the Host's own web server: POST
+ * a request, and the renderer drains the queue over the app protocol. The
+ * renderer shows the banner, so it is attributed to DeepSeek Harness rather
+ * than to a script host. Nothing here needs authentication: the server binds
+ * loopback, and the endpoint URL is written to a file the caller can read.
+ */
+function mountInterface(ctx, config) {
+  if (!config.api) return
+  const server = (() => {
+    try {
+      return ctx.get?.("webServer")
+    } catch {
+      return undefined
+    }
+  })()
+  if (server === undefined || typeof server.register !== "function") {
+    void noteToLog(config.logPath, "interface: the Host has no webServer service; the interface is unavailable")
+    return
+  }
+
+  const queue = []
+  const disposers = []
+
+  const post = async (request, response) => {
+    if (request.method === "OPTIONS") {
+      answer(response, 204, {})
+      return
+    }
+    if (request.method !== "POST") {
+      answer(response, 405, { ok: false, error: "use POST" })
+      return
+    }
+    let payload
+    try {
+      payload = await readBody(request, Math.max(1024, config.apiBodyLimit))
+    } catch (error) {
+      answer(response, 400, { ok: false, error: String(error?.message ?? error) })
+      return
+    }
+    const title = typeof payload?.title === "string" ? payload.title.trim() : ""
+    const body = typeof payload?.body === "string" ? payload.body.trim() : ""
+    if (title === "" && body === "") {
+      answer(response, 400, { ok: false, error: "title or body is required" })
+      return
+    }
+    queue.push({
+      at: new Date().toISOString(),
+      title: title === "" ? "DeepSeek Harness" : title,
+      body: body.slice(0, 400),
+      ...typeof payload?.sessionId === "string" && payload.sessionId !== "" ? { sessionId: payload.sessionId } : {},
+    })
+    while (queue.length > Math.max(1, config.apiQueueLimit)) queue.shift()
+    answer(response, 202, { ok: true, queued: queue.length })
+  }
+
+  const pending = (request, response) => {
+    if (request.method === "OPTIONS") {
+      answer(response, 204, {})
+      return
+    }
+    if (request.method !== "GET") {
+      answer(response, 405, { ok: false, error: "use GET" })
+      return
+    }
+    const items = queue.splice(0, queue.length)
+    answer(response, 200, items)
+  }
+
+  try {
+    disposers.push(server.register({ kind: "exact", path: API_REQUEST_PATH, handler: (request, response) => {
+      void post(request, response).catch(() => answer(response, 500, { ok: false }))
+    } }))
+    disposers.push(server.register({ kind: "exact", path: API_PENDING_PATH, handler: (request, response) => {
+      try {
+        pending(request, response)
+      } catch {
+        answer(response, 500, [])
+      }
+    } }))
+  } catch (error) {
+    void noteToLog(config.logPath, `interface: cannot register routes: ${String(error)}`)
+    return
+  }
+
+  // Hand the caller an address to post to; the port is whatever the Host took.
+  const endpointPath = expandHome(config.endpointPath)
+  const origin = (() => {
+    try {
+      return typeof server.getOrigin === "function" ? server.getOrigin() : undefined
+    } catch {
+      return undefined
+    }
+  })() ?? (typeof server.port === "number" ? `http://127.0.0.1:${server.port}` : undefined)
+  if (endpointPath !== "" && origin !== undefined) {
+    void mkdir(dirname(endpointPath), { recursive: true })
+      .then(() => writeFile(endpointPath, `${origin}${API_REQUEST_PATH}\n`, "utf8"))
+      .then(() => noteToLog(config.logPath, `interface: ${origin}${API_REQUEST_PATH}`))
+      .catch((error) => noteToLog(config.logPath, `interface: cannot write the endpoint file: ${String(error)}`))
+  } else {
+    void noteToLog(config.logPath, `interface: routes registered but the address is unknown (origin=${String(origin)})`)
+  }
+
+  ctx.effect(() => () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        /* the route table is being torn down anyway */
+      }
+    }
+    if (endpointPath !== "") void rm(endpointPath, { force: true }).catch(() => {})
+  }, "desktop-notify: local interface")
+}
+
+/** Append one best-effort line to the log from outside the session machinery. */
+async function noteToLog(logPathConfig, line) {
+  try {
+    const path = expandHome(logPathConfig)
+    if (path === "") return
+    await mkdir(dirname(path), { recursive: true })
+    await appendFile(path, `${new Date().toISOString()} ${line}\n`, "utf8")
+  } catch {
+    /* logging is best effort */
+  }
+}
+
 /** Merge the row's config over the defaults, keeping field types honest. */
 function resolveConfig(raw) {
   const config = { ...DEFAULTS }
@@ -142,6 +322,7 @@ function runDetached(command, args) {
  */
 export function apply(ctx, rawConfig) {
   const config = resolveConfig(rawConfig)
+  mountInterface(ctx, config)
   if (!config.enabled) return
 
   const logPath = expandHome(config.logPath)

package/lib/client.js

@@ -30,7 +30,7 @@ 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.5.6"
+    const VERSION = "0.6.1"
     const PREFERENCES_KEY = `${NS}:preferences`
 
     /** Defaults; override per field with the localStorage JSON described in README. */
@@ -344,6 +344,74 @@ window.__ModuleLoader__.load({
         return { ok: false, attempts }
       }
 
+      /**
+       * Banners requested by other tools: the Host half accepts POSTs on a
+       * loopback route and this half drains them over the app protocol, so the
+       * banner is a real DeepSeek Harness notification rather than a script
+       * host's.
+       */
+      const EXTERNAL_PENDING_PATH = "/desktop-notify/pending"
+      let externalTimer
+      let externalStopped = false
+      const showExternal = (item) => {
+        const title = typeof item?.title === "string" && item.title !== "" ? item.title : "DeepSeek Harness"
+        const body = typeof item?.body === "string" ? item.body.slice(0, 200) : ""
+        if (!preferences.notifications) {
+          recordNotify({ kind: "external", title, body, result: "skipped: preferences.notifications=false" })
+          return
+        }
+        if (!canNotify()) {
+          recordNotify({ kind: "external", title, body, result: "skipped: Notification unavailable" })
+          return
+        }
+        let notification
+        try {
+          notification = new Notification(title, { body })
+        } catch (error) {
+          recordNotify({ kind: "external", title, body, result: `threw: ${String(error)}` })
+          return
+        }
+        recordNotify({ kind: "external", title, body, result: "posted" })
+        notification.onclick = () => {
+          let focused = false
+          try {
+            window.focus()
+            focused = true
+          } catch {
+            /* focus is best effort */
+          }
+          const sessionId = typeof item?.sessionId === "string" && item.sessionId !== "" ? item.sessionId : null
+          const opened = sessionId === null ? undefined : openSessionTarget(sessionId)
+          lastClick = {
+            at: new Date().toISOString(),
+            kind: "external",
+            sessionId,
+            ...opened === undefined ? {} : { opened },
+            focused,
+          }
+        }
+      }
+      const pollExternal = async () => {
+        if (externalStopped || typeof fetch !== "function") return
+        try {
+          const response = await fetch(EXTERNAL_PENDING_PATH, {
+            headers: { accept: "application/json" },
+            cache: "no-store",
+          })
+          if (!response.ok) return
+          const items = await response.json()
+          for (const item of Array.isArray(items) ? items : []) showExternal(item)
+        } catch {
+          /* no Host half, or this build does not proxy the path */
+        }
+      }
+      if (preferences.notifications) {
+        externalTimer = setInterval(() => { void pollExternal() }, 2500)
+        // Node-style timers can hold a process open; the renderer's cannot.
+        externalTimer?.unref?.()
+        void pollExternal()
+      }
+
       /** Post one banner; clicking it opens the session and raises the window. */
       function notify(kind, sessionId, title, body) {
         if (!preferences.notifications) {
@@ -582,6 +650,11 @@ window.__ModuleLoader__.load({
         }
       }, "dsh-plugin-desktop-notify: failure watch")
 
+      ctx.effect(() => () => {
+        externalStopped = true
+        clearInterval(externalTimer)
+      }, "dsh-plugin-desktop-notify: external interface release")
+
       ctx.effect(() => () => {
         try {
           if (canBadge()) void navigator.clearAppBadge()

package/package.json

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