deskbuddy 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/deskbuddy-dsh.mjs

@@ -0,0 +1,706 @@
+// DeskBuddy 的 DeepSeek Harness（dsh）原生插件（spec 2026-10-03-deskbuddy-deepseek-harness-design）。
+// `deskbuddy enable deepseek_harness` 往 $DSH_HOME/cordis.patch.yml 追加一条 insert，name 是本文件的绝对路径；
+// 本文件随 hook.cjs / gate.cjs 一起同步到 ~/.deskbuddy/，CLI 升级即生效。
+//
+// 做的事和 opencode.mjs 一样只有翻译：dsh 的 Cordis 事件 → cc-hook 同构输入，喂同目录的 hook.cjs（状态）和 gate.cjs（设备确认）。
+//
+// 实测依据（dsh 0.2.0-rc.2，10-03 spike）：
+// - CC hooks 兼容插件在 `dsh web` 下静默不加载，只能走原生插件
+// - approval/request、user-questions/request 是串行瀑布：不调 next() 就挡住了原生界面。
+//   抢答做法：把 req.signal 换成 AbortSignal.any([原 signal, 自己的])，再 next() 让原生界面照常弹，同时推设备，谁先回用谁；
+//   设备先答就 abort 自己那个 —— web 的卡片立即消失（next() 随之 reject，要接住）。原生先答就结束 gate 子进程，daemon 撤设备卡片
+// - 审批请求不带工具参数，靠 callId 从先到的 tool/call 事件里补
+//
+// 🔴 窗口兜底方向：任何失败都交给原生界面（只调 next()），绝不替用户表态。
+
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const HOOK = join(HERE, 'hook.cjs')
+const GATE = join(HERE, 'gate.cjs')
+export const TOOL = 'deepseek_harness'
+
+/** hook.cjs 自己有 2 秒上报超时，这里再兜一层：一次卡死不能堵住后面所有状态 */
+const HOOK_KILL_MS = 10 * 1000
+/** 工具调用参数缓存时长：tool/call 记下，随后的审批请求靠它显示真实命令 */
+const CALL_TTL_MS = 10 * 60 * 1000
+
+/** 下发信箱：心跳间隔、轮询间隔（与 src/core/dshMailbox.ts 的约定一致：心跳 5 秒内算新鲜、≤1 秒取信） */
+const HEARTBEAT_MS = 1000
+const INBOX_POLL_MS = 500
+const ID_RE = /^[A-Za-z0-9_-]{1,128}$/
+/** 信龄超过这个就不投（daemon 回执超时 8 秒 + 收回宽限 3 秒 + 余量，与 src/core/dshMailbox.ts 的 DSH_STALE_MS 一致） */
+export const STALE_LETTER_MS = 12 * 1000
+/** followup 结束的等待上限（daemon 等回执 8 秒，这里要更早写回执） */
+const FOLLOWUP_WAIT_MS = 5 * 1000
+/** 信件文件名 `<sessionId>.<instructionId>.json`（与 src/core/dshMailbox.ts 一致） */
+export const LETTER_RE = /^([A-Za-z0-9_-]{1,128})\.([A-Za-z0-9_-]{1,128})\.json$/
+
+/** 验证过的 dsh 版本线。其余版本只上报状态、不抢答（接口在开发者预览期，可能有破坏性变更） */
+export const SUPPORTED_VERSION_RE = /^0\.2\./
+
+/** 不当窗口的 profile：一次性任务 / 给程序用的。ACP 的应答方是编辑器那头，没实测，也先不抢 */
+const NON_WINDOW_PROFILES = new Set(['headless', 'sdk', 'sdk-minimal', 'acp'])
+
+// ---------------- 纯函数（有单测） ----------------
+
+/** dsh 工具 → cc-hook 同构的 tool_name / tool_input。dsh 的参数名本来就和 Claude Code 一样（file_path / command / pattern） */
+export function toCcTool(tool, args) {
+  const a = args && typeof args === 'object' && !Array.isArray(args) ? args : {}
+  const s = (v) => (typeof v === 'string' ? v : '')
+  switch (tool) {
+    case 'bash':
+    case 'pwsh':
+      return { tool_name: 'Bash', tool_input: { command: s(a.command) } }
+    case 'read':
+    case 'read_image':
+      return { tool_name: 'Read', tool_input: { file_path: s(a.file_path) } }
+    case 'write':
+      return { tool_name: 'Write', tool_input: { file_path: s(a.file_path) } }
+    case 'edit':
+    case 'str_replace_editor':
+      return { tool_name: 'Edit', tool_input: { file_path: s(a.file_path) || s(a.path) } }
+    case 'glob':
+      return { tool_name: 'Glob', tool_input: { pattern: s(a.pattern), path: s(a.path) } }
+    case 'grep':
+      return { tool_name: 'Grep', tool_input: { pattern: s(a.pattern), path: s(a.path) } }
+    case 'web_fetch':
+      return { tool_name: 'WebFetch', tool_input: { url: s(a.url) } }
+    case 'web_search':
+      return { tool_name: 'WebSearch', tool_input: { query: s(a.query) } }
+    case 'todo_write':
+      return { tool_name: 'TodoWrite', tool_input: {} }
+    case 'subagent':
+    case 'subagent_fork':
+      return { tool_name: 'Task', tool_input: {} }
+    case 'ask_user_question':
+      return { tool_name: 'AskUserQuestion', tool_input: {} }
+    default:
+      // 不认识的工具（MCP 等）原名原参数交出去：classify 对不认识的一律推设备
+      return { tool_name: String(tool || ''), tool_input: a }
+  }
+}
+
+/** tool/call 事件的 arguments 是 JSON 字符串；解不开就当空对象 */
+export function parseArgs(raw) {
+  if (raw && typeof raw === 'object') return raw
+  try {
+    const v = JSON.parse(String(raw || ''))
+    return v && typeof v === 'object' ? v : {}
+  } catch (_) {
+    return {}
+  }
+}
+
+/** user-questions/request 的题目 → AskUserQuestion 形状（统一走 daemon 的选择题链路）。没有题返回 null */
+export function questionsToCc(questions) {
+  if (!Array.isArray(questions) || questions.length === 0) return null
+  return {
+    tool_name: 'AskUserQuestion',
+    tool_input: {
+      questions: questions.map((q) => ({
+        question: q && q.question,
+        header: (q && q.header) || '',
+        multiSelect: !!(q && q.multiSelect),
+        options: q && Array.isArray(q.options) ? q.options.map((o) => ({ label: o && o.label, description: (o && o.description) || '' })) : [],
+      })),
+    },
+  }
+}
+
+/**
+ * 设备答案（gate 输出的 deskbuddyAnswers：每题选中的原文 label，自己填的放最后）→ dsh 的 AskUserQuestionAnswer。
+ * 按本地题目 id 对齐；不在选项里的算自填（custom）。单选题有自填时 selected 留空（dsh 的约定：custom 覆盖选项）。
+ * 题数对不上返回 null（不表态，交给原生界面）
+ */
+export function answersFromLists(questions, lists) {
+  if (!Array.isArray(questions) || !Array.isArray(lists) || lists.length !== questions.length) return null
+  const answers = []
+  for (let i = 0; i < questions.length; i++) {
+    const q = questions[i] || {}
+    if (typeof q.id !== 'string') return null
+    const items = Array.isArray(lists[i]) ? lists[i].filter((x) => typeof x === 'string' && x !== '') : []
+    const labels = new Set(Array.isArray(q.options) ? q.options.map((o) => o && o.label) : [])
+    const selected = items.filter((x) => labels.has(x))
+    const custom = items.filter((x) => !labels.has(x)).join('\n')
+    answers.push({ id: q.id, selected: custom && !q.multiSelect ? [] : selected, ...(custom ? { custom } : {}) })
+  }
+  return { answers }
+}
+
+/** 设备上「跳过」= 整组不答：每题 selected 为空（与 web 题卡点「跳过」给模型的结果一致，10-03 实测） */
+export function skippedAnswers(questions) {
+  // 与 answersFromLists 同样校验：题目 id 不是字符串就不表态
+  if (!Array.isArray(questions) || questions.length === 0 || questions.some((q) => !q || typeof q.id !== 'string')) return null
+  return { answers: questions.map((q) => ({ id: q.id, selected: [] })) }
+}
+
+/** 子代理会话 → 根会话（沿 parentSession 往上找，最多 8 层；找不到返回原 id） */
+export function rootSession(parents, sid) {
+  let cur = sid
+  for (let i = 0; i < 8 && parents.has(cur); i++) cur = parents.get(cur)
+  return cur
+}
+
+/** 当前 profile 名：优先 Cordis 的 profileContext，取不到看命令行（`dsh <name>` / `dsh --profile <name>`） */
+export function profileName(ctxProfile, argv = process.argv) {
+  if (ctxProfile && typeof ctxProfile.name === 'string' && ctxProfile.name) return ctxProfile.name
+  const args = Array.isArray(argv) ? argv.slice(2) : []
+  const i = args.indexOf('--profile')
+  if (i >= 0 && typeof args[i + 1] === 'string') return args[i + 1]
+  const first = args.find((a) => typeof a === 'string' && !a.startsWith('-'))
+  return first || ''
+}
+
+/** 这个 profile 有人在电脑前（web / Desktop / 用户自建的）：抢答。headless 等不抢 */
+export function isWindowProfile(name) {
+  return !NON_WINDOW_PROFILES.has(String(name || ''))
+}
+
+/** 版本门槛：读不到版本（Desktop 的打包形态可能找不到 package.json）放行；读到了但不是验证过的版本线就只报状态 */
+export function gatingAllowed(version) {
+  return !version || SUPPORTED_VERSION_RE.test(version)
+}
+
+/** 从 dsh 的启动脚本往上找 @deepseek-ai/dsh 的 package.json，取版本。找不到返回 '' */
+export function dshVersion(argv = process.argv) {
+  try {
+    let dir = dirname(realpathSync(String(argv[1] || '')))
+    for (let i = 0; i < 6; i++) {
+      const p = join(dir, 'package.json')
+      if (existsSync(p)) {
+        const pkg = JSON.parse(readFileSync(p, 'utf8'))
+        if (pkg && pkg.name === '@deepseek-ai/dsh' && typeof pkg.version === 'string') return pkg.version
+      }
+      const up = dirname(dir)
+      if (up === dir) break
+      dir = up
+    }
+  } catch (_) {
+    /* 读不到 */
+  }
+  return ''
+}
+
+/** daemon 起的 headless 任务带 DESKBUDDY_GATE_RUN（远程关卡的 runId，与 opencode 插件同一约定） */
+export function runIdFromEnv(env = process.env) {
+  const v = (env && env.DESKBUDDY_GATE_RUN) || ''
+  return /^[0-9a-zA-Z_-]{1,64}$/.test(v) ? v : ''
+}
+
+/** 信箱所在的 DeskBuddy 家目录：显式的 DESKBUDDY_HOME，否则就是本文件所在目录（syncHookFile 把它装在家目录下） */
+export function mailboxHome(env = process.env) {
+  return (env && env.DESKBUDDY_HOME) || HERE
+}
+
+/** 远程关卡（gate.cjs --run）的结果：只有 exit 0 且明确 allow 才放行，其余一律拒（远程模式的兜底方向） */
+export function runGateAllowed(r) {
+  if (!r || r.code !== 0 || !r.out) return false
+  try {
+    return JSON.parse(r.out).hookSpecificOutput.permissionDecision === 'allow'
+  } catch (_) {
+    return false
+  }
+}
+
+/** gate.cjs 的输出 → { decision: 'allow'|'deny', answers? }；不表态 / 读不懂返回 null */
+export function parseGateOut(r) {
+  if (!r || r.code !== 0 || !r.out) return null
+  let out
+  try {
+    out = JSON.parse(r.out)
+  } catch (_) {
+    return null
+  }
+  const d = out && out.hookSpecificOutput && out.hookSpecificOutput.decision
+  if (!d || (d.behavior !== 'allow' && d.behavior !== 'deny')) return null
+  return { decision: d.behavior, answers: Array.isArray(out.deskbuddyAnswers) ? out.deskbuddyAnswers : null }
+}
+
+/**
+ * 抢答：原生（next）与设备（device：resolve 成有效结果或 null = 不表态）谁先回用谁。
+ * - 原生先回：cancelDevice()（结束 gate 子进程 → daemon 撤设备卡片），用原生的结果
+ * - 设备先回有效结果：abortNative()（web 卡片消失），用设备的；原生那边随后的 reject / 迟到结果吞掉
+ * - 设备不表态（null）：只等原生
+ * 原生 reject 且设备还没回：cancelDevice() 后把错误抛回去（与没装插件时一样）
+ */
+export function race(next, device, cancelDevice, abortNative) {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const win = (fn) => {
+      if (settled) return false
+      settled = true
+      fn()
+      return true
+    }
+    let native
+    try {
+      native = Promise.resolve(next())
+    } catch (e) {
+      native = Promise.reject(e)
+    }
+    native.then(
+      (v) => win(() => (cancelDevice(), resolve(v))),
+      (e) => win(() => (cancelDevice(), reject(e)))
+    )
+    Promise.resolve(device).then(
+      (v) => {
+        if (v == null) return
+        win(() => (abortNative(), resolve(v)))
+      },
+      () => {}
+    )
+  })
+}
+
+/** 把自己的 AbortController 拼进请求的 signal：next() 往下传的就是同一个 req 对象（10-03 实测 req 没冻结） */
+export function spliceSignal(req, ac) {
+  try {
+    const orig = req.signal
+    if (orig && typeof AbortSignal.any !== 'function') return false
+    const merged = orig ? AbortSignal.any([orig, ac.signal]) : ac.signal
+    req.signal = merged
+    return req.signal === merged
+  } catch (_) {
+    return false
+  }
+}
+
+// ---------------- 插件本体 ----------------
+
+/** 活着的子进程；dsh 退出时一并结束，不留孤儿 gate 挂着设备卡片 */
+const LIVE = new Set()
+process.on('exit', () => {
+  for (const c of LIVE) {
+    try {
+      c.kill('SIGTERM')
+    } catch (_) {
+      /* 已经退了 */
+    }
+  }
+})
+
+function startChild(node, script, args, input, env, killMs = 0) {
+  let child = null
+  const done = new Promise((resolve) => {
+    let out = ''
+    let err = ''
+    try {
+      child = spawn(node, [script, ...args], { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, ...env } })
+    } catch (e) {
+      resolve({ code: -1, out, err: String(e) })
+      return
+    }
+    LIVE.add(child)
+    const timer = killMs > 0 ? setTimeout(() => child.kill('SIGKILL'), killMs) : null
+    const finish = (r) => {
+      LIVE.delete(child)
+      if (timer) clearTimeout(timer)
+      resolve(r)
+    }
+    child.stdout.on('data', (c) => (out += c))
+    child.stderr.on('data', (c) => (err += c))
+    child.on('error', (e) => finish({ code: -1, out, err: String(e) }))
+    child.on('close', (code) => finish({ code, out, err }))
+    child.stdin.on('error', () => {})
+    child.stdin.end(JSON.stringify(input))
+  })
+  return { child, done }
+}
+
+function debugLog(line) {
+  try {
+    appendFileSync(join(HERE, 'hook-debug.log'), `${new Date().toISOString()} [dsh] ${line}\n`, 'utf8')
+  } catch (_) {
+    /* 记不下不影响 */
+  }
+}
+
+export const name = 'deskbuddy'
+
+/**
+ * Cordis 插件入口。config 来自 cordis.patch.yml 里我们那条 insert：{ node }（稳定的 node 路径 ——
+ * Desktop 里宿主是 Electron，process.execPath 起不了 hook.cjs）
+ */
+export function apply(ctx, config) {
+  const node = process.env.DESKBUDDY_NODE || (config && typeof config.node === 'string' && config.node) || 'node'
+  const profile = profileName(safeGet(ctx, 'profileContext'))
+  const version = dshVersion()
+  const window = isWindowProfile(profile)
+  const gating = window && gatingAllowed(version)
+  if (!gatingAllowed(version)) debugLog(`dsh ${version} 不在验证过的版本线内，只上报状态、不推设备确认`)
+  const runId = runIdFromEnv()
+  // 有人在电脑前、版本验证过：开下发信箱，会话上报时标 remoteWindow（服务端据此放行回复）
+  const mailbox = gating
+  const env = { DESKBUDDY_AGENT_PID: String(process.pid), DESKBUDDY_AGENT_SELF: '1', ...(mailbox ? { DESKBUDDY_DSH_MAILBOX: '1' } : {}) }
+
+  // 进行中的 gate 子进程：插件卸载（热重载 / 关闭）时一并结束，daemon 随之撤掉设备卡片
+  const inflight = new Set()
+  if (ctx && typeof ctx.effect === 'function') {
+    ctx.effect(() => () => {
+      for (const c of inflight) {
+        try {
+          c.kill('SIGTERM')
+        } catch (_) {
+          /* 已经退了 */
+        }
+      }
+      inflight.clear()
+    })
+  }
+  const spawnGate = (args, input) => {
+    const h = startChild(node, GATE, args, input, env)
+    if (h.child) {
+      inflight.add(h.child)
+      h.done.then(() => inflight.delete(h.child))
+    }
+    return h
+  }
+
+  // ---- 状态上报：串行喂 hook.cjs ----
+  const sessions = new Map() // sessionId → { cwd, title }
+  const parents = new Map() // 子代理会话 → 父会话（子代理的审批归到根会话上推设备）
+  let queue = Promise.resolve()
+  const report = (event, sid, extra) => {
+    const s = sessions.get(sid)
+    if (!s) return
+    const input = { hook_event_name: event, session_id: sid, cwd: s.cwd, ...extra }
+    if (s.title) input.oc_session_title = s.title
+    queue = queue.then(() => startChild(node, HOOK, [TOOL], input, env, HOOK_KILL_MS).done).catch(() => {})
+  }
+
+  const calls = new Map() // callId → { cc, at }
+  const prune = () => {
+    const now = Date.now()
+    for (const [k, v] of calls) if (now - v.at > CALL_TTL_MS) calls.delete(k)
+  }
+
+  ctx.on('session/created', (session) => {
+    const h = session && session.header
+    if (!h || typeof session.id !== 'string') return
+    // 子代理会话不单独上屏（与 opencode 的 parentID 同理），只记下它属于哪个父会话
+    if (h.parentSession || h.origin === 'subagent') {
+      if (typeof h.parentSession === 'string') parents.set(session.id, h.parentSession)
+      return
+    }
+    sessions.set(session.id, { cwd: typeof h.cwd === 'string' ? h.cwd : process.cwd(), title: '' })
+  })
+
+  ctx.on('session/disposed', (session) => {
+    // 不报 SessionEnd：web 卸载空闲会话也会走这里，会话本身还在。进程退出由 daemon 按 pid 判活收尾
+    if (session && typeof session.id === 'string') {
+      sessions.delete(session.id)
+      parents.delete(session.id)
+    }
+  })
+
+  ctx.on('session/event', (session, event) => {
+    try {
+      onEvent(session && session.id, event)
+    } catch (e) {
+      debugLog(`处理事件出错：${(e && e.message) || e}`)
+    }
+  })
+
+  function onEvent(sid, e) {
+    if (!sid || !sessions.has(sid) || !e) return
+    const d = e.data || {}
+    switch (e.type) {
+      case 'session/title': {
+        const t = typeof d.title === 'string' ? d.title.trim() : ''
+        if (t) sessions.get(sid).title = t.slice(0, 100)
+        break
+      }
+      case 'user/message': {
+        // 只认用户自己说的（运行时上下文快照、技能清单等系统补的 user/message 来源不是 user）
+        if (!d.source || d.source.kind !== 'user') break
+        const text = Array.isArray(d.content)
+          ? d.content.filter((c) => c && c.type === 'text' && typeof c.text === 'string').map((c) => c.text).join('\n')
+          : ''
+        report('UserPromptSubmit', sid, { prompt: text })
+        break
+      }
+      case 'tool/call': {
+        prune()
+        const cc = toCcTool(d.name, parseArgs(d.arguments))
+        if (typeof d.callId === 'string') calls.set(d.callId, { cc, at: Date.now() })
+        report('PreToolUse', sid, cc)
+        break
+      }
+      case 'tool/result': {
+        const callId = d.message && d.message.toolCallId
+        const call = typeof callId === 'string' ? calls.get(callId) : null
+        if (call) calls.delete(callId)
+        report('PostToolUse', sid, call ? call.cc : { tool_name: '', tool_input: {} })
+        break
+      }
+      case 'turn/end':
+        report('Stop', sid)
+        break
+      default:
+    }
+  }
+
+  // ---- 下发信箱（spec §3 下发通道；与 src/core/dshMailbox.ts 同一约定） ----
+  const status = new Map() // sessionId → running / idle
+  ctx.on('agent/status', (p) => {
+    const sid = p && p.agent && (p.agent.id || (p.agent.session && p.agent.session.id))
+    if (typeof sid === 'string') status.set(sid, p.status)
+  })
+  if (mailbox) startMailbox(ctx, sessions, status)
+
+  // ---- 审批：与原生界面抢答；daemon 起的 headless 任务走远程关卡 ----
+  ctx.on('approval/request', function (req, next) {
+    // 子代理（headless 的 subagent 等）的审批归到根会话：设备卡片显示在根会话上，远程关卡按根会话认 run
+    const sid = rootSession(parents, agentSid(req))
+    if (runId && !window && gatingAllowed(version) && sid && sessions.has(sid)) return remoteApproval(req, sid)
+    if (!gating || !sid || !sessions.has(sid)) return next()
+    const call = req.callId ? calls.get(req.callId) : null
+    const cc = call ? call.cc : toCcTool(req.toolName, {})
+    report('PermissionRequest', sid, cc)
+    return ask(req, next, sid, cc, (g) => (g.decision === 'allow' ? 'allowed-once' : 'rejected'))
+  })
+
+  // ---- 选择题：与原生界面抢答 ----
+  ctx.on('user-questions/request', function (req, next) {
+    const sid = rootSession(parents, agentSid(req))
+    const cc = req && questionsToCc(req.questions)
+    if (!gating || !sid || !sessions.has(sid) || !cc) return next()
+    report('PermissionRequest', sid, cc)
+    return ask(req, next, sid, cc, (g) => {
+      if (g.decision === 'deny') return skippedAnswers(req.questions) // 题目 id 不对时是 null = 不表态
+      return answersFromLists(req.questions, g.answers)
+    })
+  })
+
+  /**
+   * headless 里没有原生应答者（next() 恒为 unavailable）：远程任务的授权全靠设备，经 gate.cjs --run 走 daemon 的远程关卡。
+   * 🔴 任何失败都拒（远程模式的兜底方向，与 opencode 插件一致）
+   */
+  function remoteApproval(req, sid) {
+    const call = req.callId ? calls.get(req.callId) : null
+    const cc = call ? call.cc : toCcTool(req.toolName, {})
+    report('PermissionRequest', sid, cc)
+    const input = { hook_event_name: 'PreToolUse', session_id: sid, cwd: sessions.get(sid).cwd, ...cc }
+    const { child, done } = spawnGate(['--run', runId], input)
+    const sig = req.signal
+    const onAbort = () => {
+      try {
+        if (child && child.exitCode === null) child.kill('SIGTERM')
+      } catch (_) {
+        /* 已经退了 */
+      }
+    }
+    const listening = !!(sig && typeof sig.addEventListener === 'function')
+    if (listening) sig.addEventListener('abort', onAbort, { once: true })
+    const off = () => {
+      if (listening) sig.removeEventListener('abort', onAbort)
+    }
+    return done.then(
+      (r) => (off(), runGateAllowed(r) ? 'allowed-once' : 'rejected'),
+      () => (off(), 'rejected')
+    )
+  }
+
+  /** 推设备 + 原生照常弹，谁先回用谁。map 把 gate 的结果翻成 dsh 的返回值；翻不出（null）= 不表态 */
+  function ask(req, next, sid, cc, map) {
+    const own = new AbortController()
+    const orig = req.signal
+    if (!spliceSignal(req, own)) {
+      // 拼不进 signal：设备先答后原生卡片撤不掉、还会占着卡片位（10-03 实测），这种情况不推设备
+      debugLog('请求的 signal 改不了，本次不推设备')
+      return next()
+    }
+    const input = { hook_event_name: 'PermissionRequest', session_id: sid, cwd: sessions.get(sid).cwd, ...cc }
+    const { child, done } = spawnGate(['--window', '--tool', TOOL], input)
+    const cancelDevice = () => {
+      try {
+        if (child && child.exitCode === null) child.kill('SIGTERM')
+      } catch (_) {
+        /* 已经退了 */
+      }
+    }
+    const listening = !!(orig && typeof orig.addEventListener === 'function')
+    if (listening) orig.addEventListener('abort', cancelDevice, { once: true })
+    const device = done.then((r) => {
+      const g = parseGateOut(r)
+      return g ? map(g) : null
+    })
+    // 设备先答：abort 自己的（原生卡片消失），随即把 req.signal 还原成原 signal 再交回结果 ——
+    // 免得之后谁再读 req.signal 看到的是一个已 abort 的 signal（评审 d；10-03 实测设备的允许 / 答案确实生效）
+    const abortNative = () => {
+      own.abort()
+      try {
+        req.signal = orig
+      } catch (_) {
+        /* 还原不了也不影响这次的结果 */
+      }
+    }
+    const settled = race(next, device, cancelDevice, abortNative)
+    const off = () => {
+      if (listening) orig.removeEventListener('abort', cancelDevice)
+    }
+    settled.then(off, off)
+    return settled
+  }
+}
+
+/**
+ * 心跳：每秒写 alive/<pid>.json，列出这个进程里活着的会话；取信：≤1 秒扫一次 inbox，
+ * 是自己的会话就 rename 认领（与 daemon 收回互斥）→ 读 → 删 → followup → 写 ack
+ */
+function startMailbox(ctx, sessions, status) {
+  const home = mailboxHome()
+  const dir = (name) => join(home, 'dsh', name)
+  const alivePath = join(dir('alive'), `${process.pid}.json`)
+  const ensure = (p) => {
+    mkdirSync(p, { recursive: true, mode: 0o700 })
+    try {
+      chmodSync(p, 0o700)
+    } catch (_) {
+      /* 改不了权限也不挡 */
+    }
+  }
+  const writeJson = (path, value) => {
+    const tmp = `${path}.${process.pid}.tmp`
+    writeFileSync(tmp, JSON.stringify(value), { encoding: 'utf8', mode: 0o600 })
+    renameSync(tmp, path)
+  }
+  const agents = () => safeGet(ctx, 'agents')
+  const live = () => {
+    const a = agents()
+    return [...sessions.keys()].filter((id) => {
+      try {
+        return !!(a && a.get(id))
+      } catch (_) {
+        return false
+      }
+    })
+  }
+  const beat = () => {
+    try {
+      ensure(dir('alive'))
+      writeJson(alivePath, { pid: process.pid, at: Date.now(), sessions: live() })
+    } catch (e) {
+      debugLog(`写心跳失败：${(e && e.message) || e}`)
+    }
+  }
+  const poll = () => {
+    let names
+    try {
+      names = readdirSync(dir('inbox'))
+    } catch (_) {
+      return
+    }
+    for (const n of names.sort()) {
+      const m = LETTER_RE.exec(n)
+      if (!m || !sessions.has(m[1])) continue
+      const sid = m[1]
+      const claim = join(dir('inbox'), `${n}.${process.pid}.claim`)
+      try {
+        renameSync(join(dir('inbox'), n), claim)
+      } catch (_) {
+        continue // daemon 收回了 / 别的进程认领了
+      }
+      let letter = null
+      try {
+        letter = JSON.parse(readFileSync(claim, 'utf8'))
+      } catch (_) {
+        letter = null
+      }
+      try {
+        unlinkSync(claim)
+      } catch (_) {
+        /* 删不掉也不影响 */
+      }
+      if (!letter || letter.instructionId !== m[2] || !ID_RE.test(letter.instructionId)) continue
+      const iid = letter.instructionId
+      // 孤儿信：daemon 早已按超时回报过了，再投就是设备以为没发、电脑上却执行了（评审）
+      const age = Date.now() - (typeof letter.at === 'number' ? letter.at : 0)
+      if (age > STALE_LETTER_MS) {
+        writeAck(iid, { ok: false, reason: 'stale' })
+        continue
+      }
+      deliver(sid, typeof letter.text === 'string' ? letter.text : '').then(
+        (ack) => writeAck(iid, ack),
+        () => writeAck(iid, { ok: false, reason: 'followup_failed' })
+      )
+    }
+  }
+  const writeAck = (iid, ack) => {
+    try {
+      ensure(dir('ack'))
+      writeJson(join(dir('ack'), `${iid}.json`), ack)
+    } catch (e) {
+      debugLog(`写回执失败：${(e && e.message) || e}`)
+    }
+  }
+  /** followup 后等它结束（它现在是同步的；万一以后返回 Promise，限时等、失败写 ok:false，绝不变成 unhandledRejection） */
+  const deliver = async (sid, text) => {
+    if (!text.trim()) return { ok: false, reason: 'empty' }
+    let agent = null
+    try {
+      const a = agents()
+      agent = a ? a.get(sid) : null
+    } catch (_) {
+      agent = null
+    }
+    if (!agent || typeof agent.followup !== 'function') return { ok: false, reason: 'not_live' }
+    const busy = status.get(sid) === 'running'
+    let timer = null
+    try {
+      const msg = Object.freeze({ content: [{ type: 'text', text }], source: { kind: 'user' }, role: 'user', id: randomUUID() })
+      const r = await Promise.race([
+        Promise.resolve().then(() => agent.followup(msg)).then(() => 'ok'),
+        new Promise((x) => (timer = setTimeout(() => x('timeout'), FOLLOWUP_WAIT_MS))),
+      ])
+      if (r === 'timeout') return { ok: false, reason: 'followup_timeout' }
+      return { ok: true, busy }
+    } catch (e) {
+      debugLog(`followup 失败：${(e && e.message) || e}`)
+      return { ok: false, reason: 'followup_failed' }
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+  const start = () => {
+    beat()
+    const t1 = setInterval(beat, HEARTBEAT_MS)
+    const t2 = setInterval(poll, INBOX_POLL_MS)
+    if (t1.unref) t1.unref()
+    if (t2.unref) t2.unref()
+    const cleanup = () => {
+      clearInterval(t1)
+      clearInterval(t2)
+      try {
+        unlinkSync(alivePath)
+      } catch (_) {
+        /* 已经没了 */
+      }
+    }
+    process.once('exit', cleanup)
+    return cleanup
+  }
+  // Cordis 卸载插件（热重载 / 关闭）时一并停掉；假 ctx（测试）没有 effect 就直接起
+  if (ctx && typeof ctx.effect === 'function') ctx.effect(start)
+  else start()
+}
+
+/** 请求属于哪个会话：Agent 的 id 就是 SessionId，保险起见再看 agent.session.id */
+function agentSid(req) {
+  const a = req && req.agent
+  const v = (a && a.session && a.session.id) || (a && a.id)
+  return typeof v === 'string' ? v : ''
+}
+
+function safeGet(ctx, key) {
+  try {
+    return ctx && typeof ctx.get === 'function' ? ctx.get(key) : undefined
+  } catch (_) {
+    return undefined
+  }
+}