dsh-plugin-mobile-link 0.3.0 → 0.3.1

package/lib/dlp.js

@@ -190,6 +190,15 @@ export class StreamTable {
     return this.byDlp.get(StreamTable.key(deviceId, dlpId))
   }
 
+  /** Every open entry for one device, in insertion order. */
+  byDevice(deviceId) {
+    const entries = []
+    for (const entry of this.byMux.values()) {
+      if (entry.deviceId === deviceId) entries.push(entry)
+    }
+    return entries
+  }
+
   entryOfMux(muxId) {
     return this.byMux.get(muxId)
   }

package/lib/link.js

@@ -10,7 +10,10 @@ import { DshClient } from './dsh-client.js'
 import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
 import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
 import { mintPairCode } from './pairing.js'
-import { EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf } from './router.js'
+import {
+  DEFAULT_EVENTS_BACKLOG, DEFAULT_EVENTS_GRACE_MS,
+  EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
+} from './router.js'
 import { SERVER_VERSION, SERVER_CAPABILITIES } from './hello.js'
 import { MissingIdentity, resolveIdentity } from './state.js'
 import { connect as wsConnect } from './ws.js'
@@ -28,12 +31,24 @@ function sleep(ms, signal) {
   })
 }
 
+/** Read a positive number from the environment; anything else falls back. */
+function numberFromEnv(raw, fallback) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return fallback
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
 export class MobileLinkAgent extends EventEmitter {
   constructor({
     relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, endpointFile,
     logger = console, heartbeatMs = 20000, pongTimeoutMs = 60000, maxBackoffMs = 30000,
     random = Math.random, now = Date.now, dshClient, connectImpl = wsConnect, enabled = true,
     inviteCode, fetchImpl = fetch, env = process.env,
+    // 「手机不在时替它留着 $events 流」的宽限期与缓冲上限（见 router.js 的说明）；
+    // 环境变量给部署用，构造参数给测试用。
+    eventsGraceMs = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_GRACE_MS, DEFAULT_EVENTS_GRACE_MS),
+    eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
+    setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout,
   } = {}) {
     super()
     this.config = { relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, endpointFile, inviteCode }
@@ -56,6 +71,10 @@ export class MobileLinkAgent extends EventEmitter {
       logger,
       now,
       protocolVersion: PROTOCOL_VERSION,
+      eventsGraceMs,
+      eventsBacklog,
+      setTimeoutFn,
+      clearTimeoutFn,
       send: (deviceId, frame) => this.sendToDevice(deviceId, frame),
       onChange: () => this.emit('status'),
     })

package/lib/router.js

@@ -19,6 +19,33 @@ import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
 export const EVENTS_ENDPOINT = '$events'
 export const EVENTS_RESULT = '$events/result'
 
+/**
+ * 手机断了之后，这条 `$events` 流还替它留多久（毫秒）。
+ *
+ * 为什么需要：手机是唯一客户端时，它一断，DSH 那边就没人持有这条流了——
+ * 提问（waterfall）会随 Agent Context 释放被撤掉，用户回到手机再也看不到
+ * （根因见 maintainers/PENDING-WATERFALL-LOSS.md）。留着流就等于"代手机值班"：
+ * 这期间来的提问先攒着，手机回来补发。
+ *
+ * 代价是这段时间里 DSH 认为"设备还在"，会话的 Agent Context 不会因此释放；
+ * 所以必须有上限，不能无限留。
+ */
+export const DEFAULT_EVENTS_GRACE_MS = 15 * 60 * 1000
+
+/** 离线期间最多替一台设备攒多少条 `$events` 项（只攒 waterfall/cancel）。 */
+export const DEFAULT_EVENTS_BACKLOG = 50
+
+/**
+ * 手机不在时要攒下来的 `$events` 项：只有"待回答的提问"和"提问作废"两种。
+ *
+ * 别的一律不攒——emit 类的都是"某事刚发生"的通知，几分钟后补发只会让 App
+ * 对着旧事件发通知（例如一条早就结束的 turn）。
+ */
+export function isBufferedEvent(value) {
+  if (!value || typeof value !== 'object') return false
+  return value.type === 'waterfall' || value.type === 'cancel'
+}
+
 export function messageOf(error) {
   return error instanceof Error ? error.message : String(error)
 }
@@ -34,8 +61,16 @@ export class DeviceRouter {
    * @param {(deviceId: string, frame: object) => boolean} options.send  deliver one frame to one device
    * @param {() => void} [options.onChange]    called whenever the status snapshot changes
    */
-  constructor({ dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1 } = {}) {
+  constructor({
+    dsh, send, logger = console, onChange = () => {}, now = Date.now, protocolVersion = 1,
+    eventsGraceMs = DEFAULT_EVENTS_GRACE_MS, eventsBacklog = DEFAULT_EVENTS_BACKLOG,
+    setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout,
+  } = {}) {
     this.dsh = dsh
+    this.eventsGraceMs = eventsGraceMs
+    this.eventsBacklog = eventsBacklog
+    this.setTimeoutFn = setTimeoutFn
+    this.clearTimeoutFn = clearTimeoutFn
     // Reported to the app so it can tell which wire revision it is talking to.
     this.protocolVersion = protocolVersion
     this.send = send
@@ -100,7 +135,20 @@ export class DeviceRouter {
   // ── device lifecycle ────────────────────────────────────────────────────
 
   async attachDevice(deviceId, info = {}) {
-    if (!nonEmptyString(deviceId) || this.devices.has(deviceId)) return
+    if (!nonEmptyString(deviceId)) return
+    const existing = this.devices.get(deviceId)
+    if (existing) {
+      // 回头客：宽限期内又连上了。流和攒下的提问都还在，交给 handleOpen 补发。
+      if (existing.offlineSince !== undefined) {
+        this.clearTimeoutFn(existing.offlineTimer)
+        existing.offlineTimer = undefined
+        existing.offlineSince = undefined
+        this.logger.info?.(
+          `mobile-link: device ${deviceId} reattached with ${existing.eventsPending.size} unanswered question(s)`)
+        this.#changed()
+      }
+      return
+    }
     this.devices.set(deviceId, {
       deviceId,
       name: info?.name,
@@ -110,6 +158,13 @@ export class DeviceRouter {
       readyValue: undefined,
       eventsMuxId: undefined,
       dlpIds: new Set(),
+      // 手机不在时的"值班"状态：offlineSince 有值 = 这条流在替它留着；
+      // eventsPending 是**还没被回答**的提问（按 eventId 存）。
+      // 注意它不是一个"送一次就清空"的队列：送过也要留着，否则 App 再重启一次
+      // （或崩一次）这条提问就永远丢了——2026-09-22 验收时正是这么发现的。
+      offlineSince: undefined,
+      offlineTimer: undefined,
+      eventsPending: new Map(),
     })
     this.logger.info?.(`mobile-link: device ${deviceId} attached (${info?.name ?? 'unknown'})`)
     this.#changed()
@@ -119,9 +174,42 @@ export class DeviceRouter {
   async detachDevice(deviceId, reason) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 除了 `$events`，其它流（文件、会话流）立刻撤掉：它们没有"值班"的意义，
+    // 留着只会占资源。`$events` 留着，见 DEFAULT_EVENTS_GRACE_MS 的说明。
+    const keep = []
+    for (const entry of this.streams.byDevice(deviceId)) {
+      if (entry.endpoint === EVENTS_ENDPOINT) {
+        keep.push(entry)
+        continue
+      }
+      this.streams.removeByMux(entry.muxId)
+      this.dsh.cancelStream(entry.muxId)
+    }
+    record.dlpIds.clear()
+    for (const entry of keep) record.dlpIds.add(entry.dlpId)
+
+    if (record.offlineSince === undefined) {
+      record.offlineSince = this.now()
+      record.offlineTimer = this.setTimeoutFn(() => {
+        void this.#expireOfflineDevice(deviceId)
+      }, this.eventsGraceMs)
+      // 定时器不该把进程钉住（CLI 与测试里尤其明显）。
+      record.offlineTimer?.unref?.()
+    }
+    this.logger.info?.(
+      `mobile-link: device ${deviceId} detached (${reason ?? 'closed'})；`
+      + `$events 流替它留 ${Math.round(this.eventsGraceMs / 1000)} 秒，期间来的提问会攒着`)
+    this.#changed()
+  }
+
+  /** 宽限期到点：真的把这台设备放下（撤流、清缓冲）。 */
+  async #expireOfflineDevice(deviceId) {
+    const record = this.devices.get(deviceId)
+    if (!record || record.offlineSince === undefined) return
     for (const muxId of this.streams.removeDevice(deviceId)) this.dsh.cancelStream(muxId)
     this.devices.delete(deviceId)
-    this.logger.info?.(`mobile-link: device ${deviceId} detached (${reason ?? 'closed'})`)
+    this.logger.info?.(
+      `mobile-link: device ${deviceId} 宽限期结束，已放下（丢掉 ${record.eventsPending.size} 条没人回答的提问）`)
     this.#changed()
   }
 
@@ -148,6 +236,8 @@ export class DeviceRouter {
   teardownAll() {
     const muxIds = []
     for (const deviceId of [...this.devices.keys()]) {
+      const record = this.devices.get(deviceId)
+      this.clearTimeoutFn(record?.offlineTimer)
       muxIds.push(...this.streams.removeDevice(deviceId))
       this.devices.delete(deviceId)
     }
@@ -253,6 +343,17 @@ export class DeviceRouter {
       if (record.readyValue !== undefined) {
         this.send(deviceId, { t: 'item', id: frame.id, value: record.readyValue })
       }
+      // 还没被回答的提问在这里补发：ready 已经发过，所以 App 拿得到 clientId，
+      // 补发的提问是可以被回答的。**送出去不清空**——App 可能又崩/又重启，
+      // 只要还没人回答，下次连上还得再给一遍（App 侧按 eventId 去重）。
+      if (record.eventsPending.size > 0) {
+        const pending = [...record.eventsPending.values()]
+        this.logger.info?.(
+          `mobile-link: replaying ${pending.length} unanswered question(s) to ${deviceId}`)
+        for (const value of pending) {
+          this.send(deviceId, { t: 'item', id: frame.id, value })
+        }
+      }
       return
     }
     const muxId = `s:${deviceId}:${frame.id}`
@@ -302,6 +403,8 @@ export class DeviceRouter {
       })
       return
     }
+    // 答过了就不再是"待答"：删掉它，免得下次重连又把已经回答过的问题推给 App。
+    record.eventsPending.delete(eventId)
     // The clientId is always the one from *this device's* $events ready frame
     // (spec §4.1.5); any clientId the device echoed is ignored on purpose.
     if (!this.dedupe.claim(eventId)) return
@@ -339,6 +442,27 @@ export class DeviceRouter {
   forwardEvent(deviceId, value) {
     const record = this.devices.get(deviceId)
     if (!record) return
+    // 只有"待回答的提问"值得留：别的都是"某事刚发生"的通知，补发只会让 App
+    // 对着几分钟前的事件发通知（例如一条早就结束的 turn）。
+    // 待答表：不管手机在不在都记下来，直到**有人回答**或 host 作废它。
+    // 只记在线时的转发是不够的——App 收下提问后崩一次/重启一次，那条提问就再也没人
+    // 记得了（host 认为已经投给这条流了，不会重发）。连接器记着，重连时再给一遍。
+    if (nonEmptyString(value?.eventId)) {
+      if (value.type === 'cancel') record.eventsPending.delete(value.eventId)
+      else if (value.type === 'waterfall') {
+        record.eventsPending.set(value.eventId, value)
+        if (record.eventsPending.size > this.eventsBacklog) {
+          // 超上限时丢最老的（Map 保持插入顺序）。
+          const oldest = record.eventsPending.keys().next().value
+          record.eventsPending.delete(oldest)
+        }
+      }
+    }
+    if (record.offlineSince !== undefined && isBufferedEvent(value)) {
+      this.logger.debug?.(
+        `mobile-link: kept ${value.type} ${value.event ?? value.eventId ?? ''} for offline ${deviceId}`)
+      return
+    }
     if (value && value.type === 'ready' && nonEmptyString(value.clientId)) {
       record.clientId = value.clientId
       record.readyValue = value
@@ -411,6 +535,8 @@ export class DeviceRouter {
       // Which build that phone reported on its last handshake.
       client: record.client ?? null,
       connectedAt: record.connectedAt,
+      offlineSince: record.offlineSince ?? null,
+      unansweredEvents: record.eventsPending.size,
       eventsReady: Boolean(record.clientId),
       openStreams: record.dlpIds.size,
     }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-link",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Put your PC's DeepSeek Harness in your pocket: dials a relay over WSS so the native iOS client reaches this machine even without a public IP.",
   "keywords": [
     "dsh",