dsh-plugin-mobile-link 0.6.5 → 0.7.0

package/lib/jobs-roster.js

@@ -0,0 +1,377 @@
+/**
+ * 活动名单：本地方法 `_link/jobRoster` 与推帧 `link/jobs`（spec 018）。
+ *
+ * 为什么由连接器聚合：宿主没有 host-wide 的任务读法——`JobRegistry.list(caller)`
+ * 只回该会话自己的 + 所有无主任务，`session/control` 的基线在本版本也只带
+ * projections。连接器与宿主同进程，逐会话读是内存过滤，既没有网络往返，也不需要
+ * 手机为每个会话各开一条 `job/list` 流。
+ *
+ * 契约：`specs/018-mobile-activity-visibility/contracts/link-job-roster.md`。
+ * 与 `_link/sessionWindow` / `_link/sessionFind` 同族：连接器自己回答，不转发宿主。
+ * 特性检测而不是版本比较——拿不到 `ctx.jobs` 时回 `link/unsupported`，手机整块不显示。
+ */
+
+/** 连接器自答的方法名（`_link/` 前缀表示"不转发宿主"，与 history 一族一致）。 */
+export const ROSTER_METHOD = '_link/jobRoster'
+
+/** 推帧的 `type`。包在 per-device `$events` 的 item 里，旧 App 当未知类型忽略。 */
+export const JOBS_FRAME = 'link/jobs'
+
+/**
+ * 还算"活着"的状态。其余（`completed` / `killed` / `failed`，以及宿主将来可能
+ * 新增的终态）一律只计入 `settled`，不下发——否则每个会话的历史任务都会跟着名单
+ * 一起上手机。
+ */
+export const LIVE_STATUSES = Object.freeze(['running', 'stopping'])
+
+/**
+ * 合并窗口（毫秒）。一次任务生命周期里宿主会在毫秒级连发 registered / progress /
+ * stopping / settled 几个事件；按会话合并成最后一帧，手机只看到稳定后的那一格。
+ */
+export const DEFAULT_DEBOUNCE_MS = 120
+
+const LIVE = new Set(LIVE_STATUSES)
+
+/** 会改变名单的宿主事件。`output` 只影响输出流，不影响这一格。 */
+const LIFECYCLE_TYPES = new Set(['registered', 'progress', 'stopping', 'settled', 'removed'])
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function failure(code, message, details = {}) {
+  return { ok: false, error: { code, message, details } }
+}
+
+/** 默认调度器：`unref` 掉，去抖窗口里没有别的事情时不该把进程按住不让退出。 */
+function defaultSchedule(fn, ms) {
+  const handle = setTimeout(fn, ms)
+  handle.unref?.()
+  return handle
+}
+
+function defaultCancel(handle) {
+  clearTimeout(handle)
+}
+
+/**
+ * 请求参数只允许空对象（契约 §2）。未知字段一律拒绝：放宽了，将来某个字段改名
+ * 就会静默变成"没有过滤条件"，而不是一条能看到的 bad-request。
+ * @returns {object|undefined} 失败时的回包，成功时 undefined
+ */
+function checkArgs(args) {
+  if (args === undefined || args === null) return undefined
+  if (typeof args !== 'object' || Array.isArray(args)) {
+    return failure('gateway/bad-request', 'arguments must be an empty object')
+  }
+  const keys = Object.keys(args)
+  if (keys.length > 0) return failure('gateway/bad-request', `unknown field "${keys[0]}"`)
+  return undefined
+}
+
+/**
+ * 宿主 `JobView` → 契约的 `JobLite`。
+ *
+ * 只减不增：手机不读 `outputLimitBytes` / `spillPaths`，就不下发。`progress` /
+ * `detail` / `finishedAt` 按宿主现值原样带上，缺省即不带（不补 null，手机按"没有"
+ * 处理）。`outputLost` 是唯一重命名：`output.earliest > 0` 表示输出环丢过头部。
+ */
+export function jobLite(job) {
+  const output = job?.output ?? {}
+  const lite = {
+    id: job?.id,
+    kind: job?.kind,
+    label: job?.label,
+    status: job?.status,
+    startedAt: job?.startedAt,
+    outputTotal: Number.isFinite(output.total) ? output.total : 0,
+  }
+  if (typeof job?.owner === 'string' && job.owner) lite.owner = job.owner
+  if (typeof job?.progress === 'string') lite.progress = job.progress
+  if (typeof job?.detail === 'string') lite.detail = job.detail
+  if (Number.isFinite(job?.finishedAt)) lite.finishedAt = job.finishedAt
+  if (Number.isFinite(output.earliest) && output.earliest > 0) lite.outputLost = true
+  return lite
+}
+
+/** 会话对象 → id。宿主的 `Session` 把 id 放在 `id` 上；裸 id 只在测试与将来的读法里出现。 */
+function sessionIdOf(entry) {
+  const id = typeof entry === 'string' ? entry : entry?.id
+  return typeof id === 'string' && id.length > 0 ? id : undefined
+}
+
+/**
+ * @param {{
+ *   getJobs?: () => object | undefined,
+ *   getSessions?: () => object | undefined,
+ *   deliver?: (value: object) => void,
+ *   logger?: { debug?: Function, info?: Function, warn?: Function },
+ *   now?: () => number,
+ *   debounceMs?: number,
+ *   schedule?: (fn: Function, ms: number) => unknown,
+ *   cancel?: (handle: unknown) => void,
+ * }} deps
+ */
+export function createJobsRoster({
+  getJobs = () => undefined,
+  getSessions = () => undefined,
+  deliver = () => {},
+  logger = console,
+  now = Date.now,
+  debounceMs = DEFAULT_DEBOUNCE_MS,
+  schedule = defaultSchedule,
+  cancel = defaultCancel,
+} = {}) {
+  /**
+   * 服务来自两处：构造参数是读取函数（`link.js` 用它把 roster 接在 agent 上），
+   * `bindServices` 是插件注入时直接把服务实例交进来。**后者优先**：注入晚于第一台
+   * 设备连接时，正是它让订阅能补上。
+   */
+  const bound = { jobs: undefined, sessions: undefined }
+
+  /**
+   * 已在线、且需要收 `link/jobs` 的设备。**不**包含"断了但 `$events` 还替它值班"的
+   * 设备：离线期间的旧任务状态没有补发意义（契约 §3），重连后手机重新问一次名单。
+   */
+  const devices = new Set()
+  /** 宿主 `ctx.jobs.events.subscribe(...)` 的 disposer；undefined = 现在没订阅。 */
+  let unsubscribe
+  /** 去抖定时器的句柄；undefined = 没有排队的帧。 */
+  let timer
+  /** 窗口内变过的会话；flush 时逐个重算那一格。 */
+  const pending = new Set()
+  /** 已发出的最大 `at`：同一连接内单调不减，手机据此丢弃乱序帧（契约 §4.5）。 */
+  let lastAt = 0
+
+  function jobs() {
+    return bound.jobs ?? getJobs()
+  }
+
+  function sessions() {
+    return bound.sessions ?? getSessions()
+  }
+
+  function available() {
+    return jobs() !== undefined && sessions() !== undefined
+  }
+
+  /**
+   * 挂上（或摘下）宿主服务。注入可能晚于第一台设备连上，所以绑定后要补一次订阅：
+   * 只在 attach 时订阅的话，这台连接会一直到下一次设备 attach 才开始推帧。
+   */
+  function bindServices(next = {}) {
+    bound.jobs = next.jobs
+    bound.sessions = next.sessions
+    if (devices.size > 0) {
+      if (available()) subscribe()
+      else releaseSubscription()
+    }
+    return available()
+  }
+
+  function nextAt() {
+    const value = Number(now())
+    if (Number.isFinite(value) && value > lastAt) lastAt = value
+    return lastAt
+  }
+
+  /** 一个会话那一格：只留活的任务，其余计数。 */
+  function cellOf(sessionId) {
+    const running = []
+    let settled = 0
+    for (const job of jobs().list(sessionId) ?? []) {
+      if (LIVE.has(job?.status)) running.push(jobLite(job))
+      else settled += 1
+    }
+    return { running, settled }
+  }
+
+  /**
+   * 宿主活会话列表（`ctx.sessions.list()`）。
+   *
+   * 形状不可信：`undefined` / 非数组 / `list` 不是函数（宿主换实现、依赖没装全时都可能）
+   * 一律当空名单。名单只是一份旁路读数，为它把整个 `_link/jobRoster` 变成
+   * `link/failed`，等于跟手机说"这台连接器不支持活动名单"（契约 §2 的失败口径只留给
+   * **真的读不出来**的情形）。读的时候**抛错**仍然向上抛，由 `handle` 转成 `link/failed`。
+   * 元素缺 `id` 不是异常形状，在 `sample` 里逐条跳过。
+   */
+  function sessionEntries() {
+    const store = sessions()
+    if (typeof store?.list !== 'function') return []
+    const listed = store.list()
+    return Array.isArray(listed) ? listed : []
+  }
+
+  /** 整份名单（`_link/jobRoster` 的 `value`）。 */
+  function sample() {
+    const at = nextAt()
+    const out = {}
+    for (const entry of sessionEntries()) {
+      const sessionId = sessionIdOf(entry)
+      if (sessionId === undefined || out[sessionId] !== undefined) continue
+      let cell
+      try {
+        cell = cellOf(sessionId)
+      } catch (error) {
+        // 会话在枚举与读取之间消失，或宿主拒绝这次读：少一格好过整份名单失败。
+        logger.debug?.(`mobile-link: job roster skipped ${sessionId}: ${messageOf(error)}`)
+        continue
+      }
+      // 一件任务都没有的会话不占位：手机把"缺席"读成"没有活"（契约 §2）。
+      // 有已结算任务的会话仍然占位——`settled` 是面板「已结束 N 个」的口径。
+      if (cell.running.length === 0 && cell.settled === 0) continue
+      out[sessionId] = cell
+    }
+    return { at, sessions: out }
+  }
+
+  function subscribe() {
+    if (unsubscribe !== undefined) return
+    const events = jobs()?.events
+    if (typeof events?.subscribe !== 'function') {
+      logger.debug?.('mobile-link: this Host has no jobs event stream; link/jobs frames stay off')
+      return
+    }
+    try {
+      // `{owners:'scope'}`：连接器挂在宿主全局层，作用域就是整个进程，等价于"全部会话"。
+      //
+      // 不用 `{owners:'all'}`：本机实测（0.2.0-rc.2 桌面版宿主）该过滤器的订阅装上了
+      // 但**一条事件都收不到**（subscribe 成功、onChange 从不触发），于是 `link/jobs`
+      // 永远不推、手机只能显示建连那一刻的名单（2026-10-17 owner 报"任务结束了手机还显示在跑"）。
+      // `scope` 在同一宿主上按预期收到 registered/settled/removed，因此改用它。
+      unsubscribe = events.subscribe({ owners: 'scope' }, onChange)
+    } catch (error) {
+      logger.warn?.(`mobile-link: subscribing to jobs events failed: ${messageOf(error)}`)
+    }
+  }
+
+  function releaseSubscription() {
+    const dispose = unsubscribe
+    unsubscribe = undefined
+    if (typeof dispose !== 'function') return
+    try {
+      dispose()
+    } catch (error) {
+      logger.debug?.(`mobile-link: releasing jobs events failed: ${messageOf(error)}`)
+    }
+  }
+
+  function onChange(event) {
+    if (!LIFECYCLE_TYPES.has(event?.type)) return
+    // 帧只描述"一个会话的那一格"；无主任务没有归属会话，放不进任何一格。
+    // 它仍然会在 `_link/jobRoster` 的首答里出现（宿主对每个会话都可见）。
+    const sessionId = event?.job?.owner
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return
+    pending.add(sessionId)
+    arm()
+  }
+
+  function arm() {
+    if (timer !== undefined) return
+    timer = schedule(flush, debounceMs)
+  }
+
+  function flush() {
+    timer = undefined
+    const dirty = [...pending]
+    pending.clear()
+    // 没有在线设备：不产帧、也不把变化攒着（契约 §3「设备未连接时不产生帧，不缓存」）。
+    if (devices.size === 0 || dirty.length === 0) return
+    const at = nextAt()
+    for (const sessionId of dirty) {
+      let cell
+      try {
+        cell = cellOf(sessionId)
+      } catch (error) {
+        // 读不到就不推：推一份空的 `running` 会把手机上正在跑的任务擦掉（比漏一帧更糟）。
+        // 记 warn——这是一次手机可见的漏帧，不是无关噪音；这一格在下一轮事件到来时重算。
+        logger.warn?.(`mobile-link: link/jobs skipped ${sessionId}: ${messageOf(error)}`)
+        continue
+      }
+      try {
+        deliver({
+          type: JOBS_FRAME,
+          value: { at, sessionId, running: cell.running, settled: cell.settled },
+        })
+      } catch (error) {
+        // 投递失败只算这一帧丢了：若让异常掀掉整个 flush，同一窗口里其它会话的帧会一起
+        // 发不出去，而且它会冲进定时器回调，把进程级异常变成无人接的错误。
+        logger.warn?.(`mobile-link: link/jobs delivery failed: ${messageOf(error)}`)
+      }
+    }
+  }
+
+  /**
+   * 帧处理（`_link/jobRoster`）。回包形状与 history 一族一致：`{ok:true,value}` 或
+   * `{ok:false,error:{code,message,details}}`。
+   */
+  async function handle(args) {
+    const rejected = checkArgs(args)
+    if (rejected !== undefined) return rejected
+    // 没有 ctx.jobs 时**不能**回空名单：空名单会被手机读成"没有活"，
+    // 把"这台连接器不支持"说成了事实（契约 §4.3）。
+    if (!available()) return failure('link/unsupported', 'this Host does not expose the jobs service')
+    try {
+      return { ok: true, value: sample() }
+    } catch (error) {
+      logger.warn?.(`mobile-link: jobRoster failed: ${messageOf(error)}`)
+      return failure('link/failed', messageOf(error))
+    }
+  }
+
+  function addDevice(deviceId) {
+    if (typeof deviceId !== 'string' || deviceId.length === 0) return false
+    if (devices.has(deviceId)) return false
+    devices.add(deviceId)
+    // 第一台设备连上才订阅：没人收的帧不值得算（契约 §3）。
+    if (devices.size === 1) subscribe()
+    return true
+  }
+
+  function removeDevice(deviceId) {
+    if (!devices.delete(deviceId)) return false
+    if (devices.size === 0) {
+      // 最后一台设备走了：订阅与服务一起放掉，窗口里的变化也不留。
+      releaseSubscription()
+      pending.clear()
+      if (timer !== undefined) {
+        cancel(timer)
+        timer = undefined
+      }
+    }
+    return true
+  }
+
+  /** 进程收尾（`router.teardownAll`）：全部设备、订阅、定时器都不留。 */
+  function releaseAll() {
+    devices.clear()
+    releaseSubscription()
+    pending.clear()
+    if (timer !== undefined) {
+      cancel(timer)
+      timer = undefined
+    }
+  }
+
+  return {
+    bindServices,
+    handle,
+    addDevice,
+    removeDevice,
+    releaseAll,
+    dispose: releaseAll,
+    get available() {
+      return available()
+    },
+    get subscribed() {
+      return unsubscribe !== undefined
+    },
+    get deviceCount() {
+      return devices.size
+    },
+  }
+}
+
+export function isJobsMethod(method) {
+  return method === ROSTER_METHOD
+}

package/lib/link.js

@@ -7,7 +7,7 @@
 import { EventEmitter } from 'node:events'
 
 import { DshClient } from './dsh-client.js'
-import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
+import { agentEndpoint, decodeFrame, encodeFrameChecked, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
 
 /**
  * 进程级登记表：**同一个进程里只允许有一条到中转的 agent 连接**。
@@ -21,13 +21,15 @@ const LIVE_AGENT = Symbol.for('dsh.mobile-link.live-agent')
 import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
 import { handoffFromEndpoint, writeHandoff } from './handoff.js'
 import { LinkJournal, defaultJournalPath } from './journal.js'
+import { LogSpool, defaultLogsRoot } from './logs.js'
 import { statusSnapshot } from './status.js'
-import { mintPairCode } from './pairing.js'
+import { mintPairCode, regeneratePairCode } from './pairing.js'
 import {
   DEFAULT_EVENTS_BACKLOG, DEFAULT_SLOW_REQUEST_MS,
   EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
 } from './router.js'
-import { SERVER_VERSION, SERVER_CAPABILITIES } from './hello.js'
+import { SERVER_VERSION, SERVER_CAPABILITIES, hostVersion } from './hello.js'
+import { createJobsRoster } from './jobs-roster.js'
 import { MissingIdentity, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
@@ -66,6 +68,9 @@ export class MobileLinkAgent extends EventEmitter {
     // 生命周期流水（见 journal.js）：`journal` 传实例（测试注入），`journalPath`
     // 传路径（`defaultJournalPath()` 之外的位置），false 表示只留内存不落盘。
     journal, journalPath,
+    // 设备日志落盘（见 logs.js）：`logs` 传实例（测试注入），`logsRoot` 换目录，
+    // `logs: false` 关掉接收（手机会把它当旧连接器，静默忽略）。
+    logs = true, logsRoot,
     // 手机不在时替它攒下来的提问条数上限（见 router.js）；环境变量给部署用，
     // 构造参数给测试用。**没有"留多久"这个旋钮**：`$events` 一直留到设备被撤销。
     eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
@@ -97,6 +102,12 @@ export class MobileLinkAgent extends EventEmitter {
       now,
       logger,
     })
+    /** 设备日志落盘：默认开着，目录在身份文件旁边，保留 7 天（清理在写入路径上）。 */
+    this.logsSpool = logs === false
+      ? null
+      : (logs && typeof logs === 'object'
+        ? logs
+        : new LogSpool({ root: logsRoot, logger, now }))
     this.router = new DeviceRouter({
       dsh: this.dsh,
       logger,
@@ -105,6 +116,7 @@ export class MobileLinkAgent extends EventEmitter {
       eventsBacklog,
       slowRequestMs: this.slowRequestMs,
       diagnostics: this.diagnostics,
+      logs: this.logsSpool,
       send: (deviceId, frame) => this.sendToDevice(deviceId, frame),
       // 设备侧的 attach/detach 与链路侧同源记进流水：事后想把"手机断了"和
       // "连接器拆链"对上时间，两边必须写在同一份文件里。
@@ -126,6 +138,15 @@ export class MobileLinkAgent extends EventEmitter {
     /// 历史读取（spec 007）：宿主 `sessionQuery` 就绪后由插件挂上；没挂上时
     /// 路由回 `link/unsupported`，手机继续走 `session/page`。
     this.setHistoryService = (service) => { this.router.history = service }
+    /// 活动名单与 `link/jobs` 推帧（spec 018）：帧由 router 广播给在线设备，
+    /// 订阅与去抖都在 roster 里。宿主服务由 `setJobsServices` 挂上。
+    this.jobsRoster = createJobsRoster({
+      deliver: (value) => this.router.publishEvent(value),
+      logger,
+      now,
+    })
+    this.router.bindJobsRoster(this.jobsRoster)
+    this.setJobsServices = (services) => this.jobsRoster.bindServices(services)
     this.relay = undefined
     this.socket = undefined
     this.state = 'idle'
@@ -420,6 +441,10 @@ export class MobileLinkAgent extends EventEmitter {
       agentId: identity.agentId,
       attempt: this.reconnectAttempts,
       sinceCloseMs: this._lastClosedAt === undefined ? undefined : this.now() - this._lastClosedAt,
+      // 这次连接属于哪套版本：连接器 + 宿主 DSH。一连接一行，事后从本机流水就能
+      // 认出"出问题的那天跑的是哪两个版本"，不必再去翻安装记录。
+      serverVersion: SERVER_VERSION,
+      hostVersion: hostVersion(),
     })
     this.emit('status')
 
@@ -570,8 +595,30 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── relay I/O ───────────────────────────────────────────────────────────
 
+  /**
+   * 序列化一条出站帧，并把"修掉了落单代理项"记下来。
+   *
+   * 上游（宿主预览）切坏了 emoji 时，出口把它修成 U+FFFD 再发：帧合法，解码方
+   * 不会整条失败；同时留一条本机流水，出问题的源头仍然查得到。日志限流一分钟一次，
+   * 累计值不丢。
+   */
+  #encodeForWire(frame) {
+    const { text, repaired } = encodeFrameChecked(frame)
+    if (repaired <= 0) return text
+    this.surrogateRepairs = (this.surrogateRepairs ?? 0) + repaired
+    this.journal.record('frame.surrogate_repaired', { repaired, total: this.surrogateRepairs })
+    const now = this.now()
+    if (now - (this._lastSurrogateWarnAt ?? -Infinity) >= 60_000) {
+      this._lastSurrogateWarnAt = now
+      this.logger.warn?.(
+        `mobile-link: repaired ${repaired} unpaired surrogate(s) in an outbound frame ` +
+        `(a host preview was cut inside an emoji); ${this.surrogateRepairs} so far`)
+    }
+    return text
+  }
+
   #rawSend(frame) {
-    return this.#sendText(encodeFrame(frame))
+    return this.#sendText(this.#encodeForWire(frame))
   }
 
   /** 唯一的发送出口：socket 不在就丢掉，发送异常只记 debug、绝不抛。 */
@@ -591,7 +638,7 @@ export class MobileLinkAgent extends EventEmitter {
     // `deviceId` 为空＝这是一条**不带寻址**的帧（`fsPutAck`/`fsPutDone`/`fsErr` 那一族）：
     // relay 靠 `bid` 把回复对回发起的那个 HTTP 请求，多一个 deviceId 反而会让它对不上。
     if (deviceId === undefined || deviceId === null) return this.#rawSend(frame)
-    const text = encodeFrame({ ...frame, deviceId })
+    const text = this.#encodeForWire({ ...frame, deviceId })
     // 记字节给路由层的"慢请求/汇总"用（它按 deviceId 归）：只有这里知道真正上线了多少字节。
     this.router.noteSent?.(deviceId, Buffer.byteLength(text))
     return this.#sendText(text)
@@ -606,6 +653,10 @@ export class MobileLinkAgent extends EventEmitter {
         name: this.identity?.agentName || undefined,
         dshPort: this.dsh?.endpoint?.port,
         protocol: PROTOCOL_VERSION,
+        // 这台电脑的两段版本。中转据此按 agent 记一行（变化才写），手机据此
+        // 在「关于」里显示 DSH 版本——只在控制帧上走一次，不进任何业务流。
+        version: SERVER_VERSION,
+        hostVersion: hostVersion(),
       },
     })
   }
@@ -653,12 +704,22 @@ export class MobileLinkAgent extends EventEmitter {
 
   // ── relay-side helpers ──────────────────────────────────────────────────
 
-  /** Ask the relay to mint a pairing code for this agent (relay NOTES.md §2). */
-  async mintPairCode({ ttlMs = 10 * 60 * 1000, fetchImpl = fetch } = {}) {
+  /**
+   * Ask the relay to mint a pairing code for this agent (relay NOTES.md §2).
+   *
+   * 032：默认持久（`ttlMs: null`）；传秒数得到限时码。
+   */
+  async mintPairCode({ ttlMs = null, fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
     return mintPairCode({ identity, ttlMs, fetchImpl })
   }
 
+  /** 用户点「重新生成」：作废旧码、铸新的，**不碰已配对设备**（032）。 */
+  async regeneratePairCode({ fetchImpl = fetch } = {}) {
+    const identity = this.identity ?? await resolveIdentity(this.config)
+    return regeneratePairCode({ identity, fetchImpl })
+  }
+
   /** Snapshot for `GET /mobile-link/status`（载荷本身在 status.js，便于守住"只增不改"）。 */
   status() {
     return statusSnapshot(this)