dsh-dock 0.5.0 → 0.7.0

package/features/mobile-relay/gateway.js

@@ -0,0 +1,279 @@
+// dsh-dock · 手机接力局域网安全网关
+//
+// DSH 0.1.1-rc.2 有意拒绝直接绑定 0.0.0.0：浏览器表层尚无登录认证，直接开放
+// 会把代码执行能力交给同一网络里的任何人。本文件提供一个最小认证反向代理：主 DSH
+// 继续只监听 127.0.0.1，手机凭 256-bit 一次性链接换取 HttpOnly 会话后才能访问。
+import { createServer, request as httpRequest } from 'node:http'
+import { networkInterfaces } from 'node:os'
+import { randomBytes } from 'node:crypto'
+
+const COOKIE_NAME = 'dsh_mobile_session'
+const CONNECT_PATH = '/__dsh_mobile/connect'
+const HEALTH_PATH = '/__dsh_mobile/health'
+const COMPAT_PATH = '/__dsh_mobile/compat.js'
+const SESSION_TTL_MS = 12 * 60 * 60 * 1000
+const MAX_CONNECT_BODY = 4096
+const MAX_HTML_BYTES = 2 * 1024 * 1024
+
+// LAN HTTP is not a browser secure context. Some mobile browsers therefore expose
+// crypto.getRandomValues() but omit crypto.randomUUID(), while the official DSH
+// connection/workspace clients call randomUUID() directly. This tiny standards-compatible
+// UUID v4 fallback is injected before every DSH bootstrap script through the proxy only.
+const MOBILE_COMPAT_JS = `(()=>{const c=globalThis.crypto;if(!c||typeof c.randomUUID==='function'||typeof c.getRandomValues!=='function')return;const make=()=>{const b=new Uint8Array(16);c.getRandomValues(b);b[6]=(b[6]&15)|64;b[8]=(b[8]&63)|128;const h=Array.from(b,x=>x.toString(16).padStart(2,'0')).join('');return h.slice(0,8)+'-'+h.slice(8,12)+'-'+h.slice(12,16)+'-'+h.slice(16,20)+'-'+h.slice(20)};try{Object.defineProperty(c,'randomUUID',{value:make,configurable:true})}catch{try{c.randomUUID=make}catch{}}})()`
+
+function secret() { return randomBytes(32).toString('base64url') }
+function now() { return Date.now() }
+function isPrivateIpv4(ip) {
+  const p = String(ip).split('.').map(Number)
+  return p.length === 4 && (p[0] === 10 || (p[0] === 172 && p[1] >= 16 && p[1] <= 31) || (p[0] === 192 && p[1] === 168))
+}
+function interfacePriority(name) {
+  if (/^en0$/.test(name)) return 100
+  if (/^en\d+$/.test(name)) return 90
+  if (/^(eth|enp|wlan|wl)/.test(name)) return 80
+  if (/^bridge/.test(name)) return 20
+  if (/^(utun|tun|tap)/.test(name)) return 10
+  return 50
+}
+
+/** 当前可用于手机连接的非回环 IPv4，私网地址优先。 */
+export function lanAddresses() {
+  const rows = []
+  const table = networkInterfaces()
+  for (const [name, list] of Object.entries(table)) {
+    for (const item of list || []) {
+      if (!item || item.internal || item.family !== 'IPv4') continue
+      rows.push({ address: item.address, interface: name, private: isPrivateIpv4(item.address) })
+    }
+  }
+  return rows.sort((a, b) => Number(b.private) - Number(a.private)
+    || interfacePriority(b.interface) - interfacePriority(a.interface)
+    || a.interface.localeCompare(b.interface))
+}
+
+function parseCookies(header) {
+  const result = {}
+  for (const part of String(header || '').split(';')) {
+    const at = part.indexOf('=')
+    if (at <= 0) continue
+    result[part.slice(0, at).trim()] = part.slice(at + 1).trim()
+  }
+  return result
+}
+function sendJson(res, status, value, headers = {}) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', ...headers })
+  res.end(JSON.stringify(value))
+}
+function readSmallJson(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_CONNECT_BODY) { reject(new Error('请求过大')); req.destroy(); return }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')) }
+      catch { reject(new Error('请求格式错误')) }
+    })
+    req.on('error', reject)
+  })
+}
+function connectHtml() {
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta name="color-scheme" content="dark light"><title>连接 DSH</title><style>html{font-family:system-ui,-apple-system,sans-serif;color-scheme:dark light}body{margin:0;min-height:100dvh;display:grid;place-items:center;padding:env(safe-area-inset-top) 0 env(safe-area-inset-bottom);background:#111318;color:#f4f6fa}.card{box-sizing:border-box;width:min(420px,calc(100vw - 32px));padding:28px;border:1px solid #30343d;border-radius:18px;background:#1c1f26;box-shadow:0 18px 60px #0007;text-align:center}.icon{width:48px;height:48px;margin:0 auto 16px;display:grid;place-items:center;border-radius:15px;background:#38bdf822;color:#38bdf8}.icon svg{width:24px;height:24px;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}h1{margin:0 0 8px;font-size:20px}p{margin:0;color:#abb1bd;line-height:1.6;font-size:14px}.error{margin-top:16px;padding:10px 12px;border-radius:10px;background:#ef44441a;color:#ff8b8b;text-align:left}[hidden]{display:none}@media(prefers-color-scheme:light){body{background:#f1f4f8;color:#16181d}.card{background:#fff;border-color:#d8dde6}.card p{color:#586173}}</style></head><body><main class="card"><div class="icon" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="M10 13a5 5 0 0 0 7.54.54l2-2a5 5 0 0 0-7.07-7.07l-1.15 1.15"/><path d="M14 11a5 5 0 0 0-7.54-.54l-2 2a5 5 0 0 0 7.07 7.07l1.14-1.14"/></svg></div><h1>正在安全连接</h1><p id="status">验证一次性链接并进入 DSH…</p><div id="error" class="error" role="alert" hidden></div></main><script>(()=>{const status=document.getElementById('status'),error=document.getElementById('error'),token=decodeURIComponent(location.hash.slice(1));history.replaceState(null,'',location.pathname);if(!token){status.textContent='连接链接不完整';error.hidden=false;error.textContent='请回到电脑端重新复制手机接力链接。';return}fetch(${JSON.stringify(CONNECT_PATH)},{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({token})}).then(async r=>{const d=await r.json().catch(()=>({}));if(!r.ok||!d.ok)throw new Error(d.error||'连接验证失败');status.textContent='验证成功，正在打开任务…';location.replace('/#dsh-mobile-relay='+encodeURIComponent(d.launch))}).catch(e=>{status.textContent='无法连接';error.hidden=false;error.textContent=e&&e.message?e.message:String(e)})})()</script></body></html>`
+}
+function rewriteProxyHeaders(headers, upstreamAuthority) {
+  const next = { ...headers, host: upstreamAuthority }
+  delete next.cookie
+  // HTML must stay uncompressed so the proxy can inject the early compatibility script.
+  delete next['accept-encoding']
+  if (next.origin) next.origin = 'http://' + upstreamAuthority
+  return next
+}
+function injectMobileCompat(html) {
+  if (html.includes('data-dsh-mobile-compat')) return html
+  const match = /<head(?:\s[^>]*)?>/i.exec(html)
+  const script = `<script data-dsh-mobile-compat src="${COMPAT_PATH}"></script>`
+  if (!match) return script + html
+  const at = match.index + match[0].length
+  return html.slice(0, at) + script + html.slice(at)
+}
+function writeUpgradeHead(socket, response) {
+  const lines = [`HTTP/1.1 ${response.statusCode || 101} ${response.statusMessage || 'Switching Protocols'}`]
+  for (let i = 0; i < response.rawHeaders.length; i += 2) lines.push(response.rawHeaders[i] + ': ' + response.rawHeaders[i + 1])
+  socket.write(lines.join('\r\n') + '\r\n\r\n')
+}
+
+/**
+ * 开启一个需要一次性链接认证的局域网代理。返回的 issue() 生成只在 fragment 中传输的令牌。
+ */
+export function startProtectedLanGateway({ port, upstreamHost = '127.0.0.1', upstreamPort }) {
+  return new Promise((resolve, reject) => {
+    const pending = new Map() // gateway token -> { pairId, launch, expiresAt }
+    const sessions = new Map() // cookie secret -> { pairId, expiresAt, seenAt }
+    const upgradedSockets = new Map() // client socket -> { sessionId, pairId, upstreamSocket }
+    const authority = upstreamHost + ':' + upstreamPort
+
+    function purge() {
+      const stamp = now()
+      for (const [key, value] of pending) if (value.expiresAt <= stamp) pending.delete(key)
+      const expiredSessions = new Set()
+      for (const [key, value] of sessions) {
+        if (value.expiresAt <= stamp) { sessions.delete(key); expiredSessions.add(key) }
+      }
+      if (expiredSessions.size) {
+        for (const [socket, value] of upgradedSockets) {
+          if (expiredSessions.has(value.sessionId)) {
+            if (value.upstreamSocket) value.upstreamSocket.destroy()
+            socket.destroy()
+          }
+        }
+      }
+    }
+    function authorize(req) {
+      purge()
+      const value = parseCookies(req.headers.cookie)[COOKIE_NAME]
+      const session = value ? sessions.get(value) : null
+      if (!session) return null
+      session.seenAt = now()
+      return { ...session, sessionId: value }
+    }
+    function proxyHttp(req, res) {
+      const upstream = httpRequest({
+        hostname: upstreamHost, port: upstreamPort, method: req.method, path: req.url,
+        headers: rewriteProxyHeaders(req.headers, authority),
+      }, (upstreamRes) => {
+        const contentType = String(upstreamRes.headers['content-type'] || '').toLowerCase()
+        if (!contentType.includes('text/html')) {
+          res.writeHead(upstreamRes.statusCode || 502, upstreamRes.headers)
+          upstreamRes.pipe(res)
+          return
+        }
+        const chunks = []
+        let size = 0
+        upstreamRes.on('data', (chunk) => {
+          size += chunk.length
+          if (size <= MAX_HTML_BYTES) chunks.push(chunk)
+        })
+        upstreamRes.on('end', () => {
+          if (size > MAX_HTML_BYTES) {
+            if (!res.headersSent) sendJson(res, 502, { ok: false, error: 'DSH 页面过大，无法注入手机兼容层。' })
+            return
+          }
+          const headers = { ...upstreamRes.headers }
+          delete headers['content-length']
+          delete headers['content-encoding']
+          headers['cache-control'] = 'no-store'
+          res.writeHead(upstreamRes.statusCode || 502, headers)
+          res.end(injectMobileCompat(Buffer.concat(chunks).toString('utf8')))
+        })
+      })
+      upstream.on('error', (error) => {
+        if (!res.headersSent) sendJson(res, 502, { ok: false, error: 'DSH 主服务连接失败：' + error.message })
+        else res.destroy(error)
+      })
+      req.pipe(upstream)
+    }
+
+    const server = createServer(async (req, res) => {
+      const url = new URL(req.url || '/', 'http://dsh-mobile.internal')
+      if (url.pathname === HEALTH_PATH) return sendJson(res, 200, { ok: true })
+      if (url.pathname === CONNECT_PATH && req.method === 'GET') {
+        res.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store',
+          'content-security-policy': "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+          'x-content-type-options': 'nosniff', 'referrer-policy': 'no-referrer',
+        })
+        return res.end(connectHtml())
+      }
+      if (url.pathname === CONNECT_PATH && req.method === 'POST') {
+        try {
+          const body = await readSmallJson(req)
+          const token = String(body && body.token || '')
+          const grant = pending.get(token)
+          if (!grant || grant.expiresAt <= now()) return sendJson(res, 403, { ok: false, error: '一次性链接无效或已过期，请在电脑端重新开启。' })
+          pending.delete(token)
+          const sessionId = secret()
+          sessions.set(sessionId, { pairId: grant.pairId, expiresAt: now() + SESSION_TTL_MS, seenAt: now() })
+          return sendJson(res, 200, { ok: true, launch: grant.launch }, {
+            'set-cookie': `${COOKIE_NAME}=${sessionId}; HttpOnly; SameSite=Strict; Path=/`,
+          })
+        } catch (error) {
+          return sendJson(res, 400, { ok: false, error: error.message || String(error) })
+        }
+      }
+      if (!authorize(req)) return sendJson(res, 401, { ok: false, error: '手机连接未认证或已过期，请使用电脑端生成的接力链接重新进入。' })
+      if (url.pathname === COMPAT_PATH && req.method === 'GET') {
+        res.writeHead(200, {
+          'content-type': 'text/javascript; charset=utf-8',
+          'cache-control': 'no-store',
+          'x-content-type-options': 'nosniff',
+        })
+        return res.end(MOBILE_COMPAT_JS)
+      }
+      return proxyHttp(req, res)
+    })
+
+    server.on('upgrade', (req, socket, head) => {
+      const authorized = authorize(req)
+      if (!authorized) { socket.end('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n'); return }
+      const connection = { sessionId: authorized.sessionId, pairId: authorized.pairId, upstreamSocket: null }
+      upgradedSockets.set(socket, connection)
+      const forgetSocket = () => upgradedSockets.delete(socket)
+      socket.once('close', forgetSocket)
+      const upstream = httpRequest({
+        hostname: upstreamHost, port: upstreamPort, method: req.method, path: req.url,
+        headers: rewriteProxyHeaders(req.headers, authority),
+      })
+      upstream.on('upgrade', (response, upstreamSocket, upstreamHead) => {
+        connection.upstreamSocket = upstreamSocket
+        writeUpgradeHead(socket, response)
+        if (head && head.length) upstreamSocket.write(head)
+        if (upstreamHead && upstreamHead.length) socket.write(upstreamHead)
+        socket.once('close', () => upstreamSocket.destroy())
+        upstreamSocket.once('close', () => socket.destroy())
+        socket.pipe(upstreamSocket).pipe(socket)
+      })
+      upstream.on('response', (response) => {
+        socket.end(`HTTP/1.1 ${response.statusCode || 502} ${response.statusMessage || 'Bad Gateway'}\r\nConnection: close\r\n\r\n`)
+      })
+      upstream.on('error', () => socket.destroy())
+      upstream.end()
+    })
+    server.once('error', reject)
+    server.listen(port, '0.0.0.0', () => {
+      server.removeListener('error', reject)
+      const listened = server.address()
+      const listenedPort = listened && typeof listened === 'object' ? listened.port : port
+      resolve({
+        port: listenedPort,
+        addresses: lanAddresses(),
+        issue(pairId, launch, expiresAt) {
+          const token = secret()
+          pending.set(token, { pairId, launch, expiresAt })
+          return token
+        },
+        revokePair(pairId) {
+          for (const [key, value] of pending) if (value.pairId === pairId) pending.delete(key)
+          for (const [key, value] of sessions) if (value.pairId === pairId) sessions.delete(key)
+          for (const [socket, value] of upgradedSockets) {
+            if (value.pairId !== pairId) continue
+            if (value.upstreamSocket) value.upstreamSocket.destroy()
+            socket.destroy()
+          }
+        },
+        purge,
+        close() {
+          pending.clear(); sessions.clear()
+          for (const [socket, value] of upgradedSockets) {
+            if (value.upstreamSocket) value.upstreamSocket.destroy()
+            socket.destroy()
+          }
+          upgradedSockets.clear()
+          return new Promise((done) => server.close(() => done()))
+        },
+      })
+    })
+  })
+}

package/features/mobile-relay/host.js

@@ -0,0 +1,328 @@
+// dsh-dock · 功能模块【手机接力】· 宿主半部
+//
+// 不复制或迁移 DSH 会话：手机与电脑都连接同一个 DSH 宿主时，会话本来就是同一份。
+// 本模块只负责短时配对、在线状态、实时任务摘要和接力备注，避免把任务状态再做成一套
+// 容易分叉的副本。所有配对凭据均只存内存，宿主重启后自动失效。
+import { randomBytes } from 'node:crypto'
+import { readBody, sendJson } from '../../src/host-core.js'
+import { lanAddresses, startProtectedLanGateway } from './gateway.js'
+
+const PAIR_TTL_MS = 10 * 60 * 1000
+const PRESENCE_TTL_MS = 45 * 1000
+const NOTE_MAX_LENGTH = 1200
+const MAX_JOIN_ATTEMPTS = 8
+const DEFAULT_GATEWAY_PORT = 3081
+
+function now() { return Date.now() }
+function cleanText(value, max) { return String(value || '').replace(/\u0000/g, '').trim().slice(0, max) }
+function publicId() { return randomBytes(9).toString('base64url') }
+function joinCode() { return randomBytes(5).toString('hex').toUpperCase() }
+function phaseOf(event) {
+  if (event && event.type === 'assistant/chunk') {
+    const type = event.data && event.data.chunk && event.data.chunk.type
+    if (type === 'reasoning-delta') return 'think'
+    if (type === 'text-delta') return 'write'
+  }
+  if (event && event.type === 'tool/call') {
+    const name = String(event.data && event.data.name || '').toLowerCase()
+    return /web|search|fetch|grep|glob|find|read|ls$|^ls|tree|locate/.test(name) ? 'search' : 'code'
+  }
+  return ''
+}
+function extractText(content) {
+  if (!Array.isArray(content)) return ''
+  return content.filter((x) => x && x.type === 'text' && typeof x.text === 'string')
+    .map((x) => x.text).join(' ').replace(/\s+/g, ' ').trim()
+}
+function routeMethod(req) {
+  const url = new URL(req.url || '/', 'http://dsh.internal')
+  return url.pathname.replace(/^\/dsh-dock\/mobile-relay\/?/, '').split('/')[0] || ''
+}
+
+export const feature = {
+  id: 'mobile-relay',
+  name: '手机接力',
+  description: '安全反向代理与扫码接力，同步当前任务状态和备注',
+  defaultEnabled: true,
+  setup(ctx) {
+    const disposers = []
+    const pairs = new Map()
+    const tasks = new Map()
+    const joinAttempts = new Map()
+    let gateway = null
+    let gatewayStarting = null
+
+    async function stopGateway() {
+      const current = gateway
+      gateway = null
+      gatewayStarting = null
+      if (current) await current.close()
+    }
+
+    async function ensureGateway(webServer, requestedPort) {
+      const port = Number(requestedPort === undefined ? DEFAULT_GATEWAY_PORT : requestedPort)
+      if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+        const error = new Error('局域网端口需为 1024 到 65535 之间的整数')
+        error.statusCode = 400
+        throw error
+      }
+      if (port === webServer.port) {
+        const error = new Error(`局域网端口不能与 DSH 主服务端口 ${webServer.port} 相同`)
+        error.statusCode = 400
+        throw error
+      }
+      if (gateway && gateway.port === port) return gateway
+      if (gateway) {
+        const error = new Error(`局域网网关已在 ${gateway.port} 端口运行，请先关闭当前手机连接`)
+        error.statusCode = 409
+        throw error
+      }
+      if (!gatewayStarting) {
+        gatewayStarting = startProtectedLanGateway({ port, upstreamHost: '127.0.0.1', upstreamPort: webServer.port })
+          .then((started) => { gateway = started; gatewayStarting = null; return started })
+          .catch((error) => { gatewayStarting = null; throw error })
+      }
+      try { return await gatewayStarting }
+      catch (cause) {
+        const error = new Error(cause && cause.code === 'EADDRINUSE'
+          ? `端口 ${port} 已被占用，请换一个端口`
+          : '无法开启局域网网关：' + ((cause && cause.message) || String(cause)))
+        error.statusCode = 400
+        throw error
+      }
+    }
+
+    function purge() {
+      const stamp = now()
+      for (const [id, pair] of pairs) {
+        for (const [deviceId, device] of pair.devices) {
+          if (stamp - device.seenAt > PRESENCE_TTL_MS) pair.devices.delete(deviceId)
+        }
+        if (pair.joinExpiresAt <= stamp && pair.devices.size === 0) {
+          pairs.delete(id)
+          if (gateway) gateway.revokePair(id)
+        }
+      }
+      for (const [key, stampAt] of joinAttempts) if (stamp - stampAt.firstAt > PAIR_TTL_MS) joinAttempts.delete(key)
+      if (gateway) gateway.purge()
+      if (gateway && pairs.size === 0) void stopGateway()
+    }
+    const purgeTimer = setInterval(purge, 15 * 1000)
+    disposers.push(() => clearInterval(purgeTimer))
+
+    function taskSnapshot() {
+      const stamp = now()
+      return [...tasks.values()].filter((task) => task.running).map((task) => ({
+        sessionId: task.sessionId,
+        title: task.title || task.firstPrompt || '(等待任务标题)',
+        phase: task.phase || 'think',
+        startedAt: task.startedAt,
+        elapsed: stamp - task.startedAt,
+        lastActivityAt: task.lastActivityAt,
+      })).sort((a, b) => b.lastActivityAt - a.lastActivityAt)
+    }
+    function visiblePair(pair) {
+      const devices = [...pair.devices.values()].map((device) => ({
+        id: device.id,
+        role: device.role,
+        label: device.label,
+        seenAt: device.seenAt,
+      })).sort((a, b) => b.seenAt - a.seenAt)
+      return {
+        id: pair.id,
+        expiresAt: pair.joinExpiresAt,
+        note: pair.note,
+        noteAt: pair.noteAt,
+        noteFrom: pair.noteFrom,
+        devices,
+        tasks: taskSnapshot(),
+        now: now(),
+      }
+    }
+    function requirePair(payload) {
+      const pairId = cleanText(payload && payload.pairId, 48)
+      const deviceId = cleanText(payload && payload.deviceId, 80)
+      const secret = cleanText(payload && payload.secret, 160)
+      const pair = pairs.get(pairId)
+      if (!pair) {
+        const error = new Error('配对不存在，请在电脑端重新开启连接')
+        error.statusCode = 410
+        throw error
+      }
+      const device = pair.devices.get(deviceId)
+      if (!device || device.secret !== secret) {
+        const error = new Error('此设备未完成配对，请重新打开手机接力链接')
+        error.statusCode = 403
+        throw error
+      }
+      device.seenAt = now()
+      return { pair, device }
+    }
+    function joinRateKey(req) {
+      return (req.socket && req.socket.remoteAddress) || 'unknown'
+    }
+    function recordFailedJoin(req) {
+      const key = joinRateKey(req)
+      const item = joinAttempts.get(key) || { count: 0, firstAt: now() }
+      if (now() - item.firstAt > PAIR_TTL_MS) { item.count = 0; item.firstAt = now() }
+      item.count++
+      joinAttempts.set(key, item)
+      return item.count
+    }
+    function canJoin(req) {
+      const item = joinAttempts.get(joinRateKey(req))
+      return !item || now() - item.firstAt > PAIR_TTL_MS || item.count < MAX_JOIN_ATTEMPTS
+    }
+
+    // 任务状态只取最小必要字段。真正的会话内容仍由 DSH 的既有会话服务管理，
+    // 这样手机继续输入后不会和电脑产生两个任务副本。
+    disposers.push(ctx.inject(['sessionQuery'], (sqCtx) => {
+      const sessionQuery = sqCtx.sessionQuery
+      const titleFor = async (task) => {
+        try {
+          const snapshot = sessionQuery && typeof sessionQuery.readTitle === 'function'
+            ? await sessionQuery.readTitle(task.sessionId) : null
+          if (snapshot && snapshot.title && tasks.get(task.sessionId) === task) task.title = snapshot.title
+        } catch { /* 标题缺失时以首条输入兜底 */ }
+      }
+      disposers.push(sqCtx.on('agent/status', (payload) => {
+        const agent = payload && payload.agent
+        const sid = agent && agent.id ? String(agent.id) : ''
+        if (!sid) return
+        if (payload.status === 'running') {
+          let task = tasks.get(sid)
+          if (!task) {
+            task = { sessionId: sid, title: '', firstPrompt: '', phase: 'think', startedAt: now(), lastActivityAt: now(), running: true }
+            tasks.set(sid, task)
+            titleFor(task)
+          }
+          task.running = true
+          task.lastActivityAt = now()
+        } else if (payload.status === 'idle') {
+          const task = tasks.get(sid)
+          if (task) { task.running = false; task.lastActivityAt = now() }
+        }
+      }))
+      disposers.push(sqCtx.on('agent/disposed', (payload) => {
+        const sid = payload && payload.agent && payload.agent.id ? String(payload.agent.id) : ''
+        const task = tasks.get(sid)
+        if (task) { task.running = false; task.lastActivityAt = now() }
+      }))
+      disposers.push(sqCtx.on('session/event', (session, event) => {
+        const sid = typeof session === 'object' && session ? String(session.id || '') : String(session || '')
+        const task = tasks.get(sid)
+        if (!task) return
+        const phase = phaseOf(event)
+        if (phase) task.phase = phase
+        if (!task.firstPrompt && event && event.type === 'user/message') {
+          const text = extractText(event.data && event.data.content)
+          if (text) task.firstPrompt = text.slice(0, 120)
+        }
+        task.lastActivityAt = (event && event.time) || now()
+      }))
+    }))
+
+    disposers.push(ctx.inject(['webServer'], (wsCtx) => {
+      wsCtx.effect(() => wsCtx.webServer.register({
+        kind: 'prefix',
+        path: '/dsh-dock/mobile-relay',
+        async handler(req, res) {
+          try {
+            const method = routeMethod(req)
+            const payload = await readBody(req)
+            purge()
+            if (method === 'network') {
+              return sendJson(res, 200, { ok: true, data: {
+                addresses: lanAddresses(),
+                defaultPort: DEFAULT_GATEWAY_PORT,
+                main: { host: wsCtx.webServer.host, port: wsCtx.webServer.port },
+                gateway: gateway ? { active: true, port: gateway.port, addresses: gateway.addresses } : { active: false },
+              } })
+            }
+            if (method === 'start') {
+              const activeGateway = await ensureGateway(wsCtx.webServer, payload && payload.port)
+              const id = publicId()
+              const code = joinCode()
+              const desktopId = cleanText(payload && payload.deviceId, 80) || publicId()
+              const desktopSecret = publicId() + publicId()
+              const pair = {
+                id, code, joinExpiresAt: now() + PAIR_TTL_MS, note: '', noteAt: 0, noteFrom: '', devices: new Map(),
+              }
+              pair.devices.set(desktopId, { id: desktopId, secret: desktopSecret, role: 'desktop', label: '电脑端', seenAt: now() })
+              pairs.set(id, pair)
+              const gatewayToken = activeGateway.issue(id, `${id}.${code}`, pair.joinExpiresAt)
+              return sendJson(res, 200, { ok: true, data: {
+                pairId: id, code, secret: desktopSecret, expiresAt: pair.joinExpiresAt, gatewayToken,
+                gateway: { active: true, port: activeGateway.port, addresses: activeGateway.addresses },
+                pair: visiblePair(pair),
+              } })
+            }
+            if (method === 'join') {
+              if (!canJoin(req)) {
+                const error = new Error('尝试次数过多，请稍后重试或在电脑端重新生成链接')
+                error.statusCode = 429
+                throw error
+              }
+              const pairId = cleanText(payload && payload.pairId, 48)
+              const code = cleanText(payload && payload.code, 32).toUpperCase()
+              const pair = pairs.get(pairId)
+              if (!pair || pair.joinExpiresAt <= now() || code !== pair.code) {
+                recordFailedJoin(req)
+                const error = new Error('连接码无效或已过期，请回到电脑端重新开启')
+                error.statusCode = 403
+                throw error
+              }
+              const deviceId = cleanText(payload && payload.deviceId, 80) || publicId()
+              const secret = publicId() + publicId()
+              pair.devices.set(deviceId, { id: deviceId, secret, role: 'mobile', label: cleanText(payload && payload.label, 32) || '手机端', seenAt: now() })
+              return sendJson(res, 200, { ok: true, data: { pairId, secret, expiresAt: pair.joinExpiresAt, pair: visiblePair(pair) } })
+            }
+            if (method === 'status') {
+              const { pair } = requirePair(payload)
+              return sendJson(res, 200, { ok: true, data: { pair: visiblePair(pair) } })
+            }
+            if (method === 'note') {
+              const { pair, device } = requirePair(payload)
+              const note = cleanText(payload && payload.note, NOTE_MAX_LENGTH)
+              if (!note) {
+                const error = new Error('请先写下接力内容')
+                error.statusCode = 400
+                throw error
+              }
+              pair.note = note
+              pair.noteAt = now()
+              pair.noteFrom = device.role === 'mobile' ? '手机端' : '电脑端'
+              return sendJson(res, 200, { ok: true, data: { pair: visiblePair(pair) } })
+            }
+            if (method === 'end') {
+              const { pair } = requirePair(payload)
+              pairs.delete(pair.id)
+              if (gateway) gateway.revokePair(pair.id)
+              const shouldStopGateway = pairs.size === 0
+              sendJson(res, 200, { ok: true, data: { ended: true } })
+              // 手机端的关闭请求本身也经过网关。先完成响应，再异步停止监听，
+              // 避免 server.close() 等待当前请求、当前请求又等待 close() 的死锁。
+              if (shouldStopGateway) setTimeout(() => { void stopGateway() }, 50)
+              return
+            }
+            return sendJson(res, 404, { ok: false, error: { code: 'method-not-found', message: 'unknown method: ' + method } })
+          } catch (error) {
+            const status = error && error.statusCode ? error.statusCode : 500
+            if (status >= 500) console.error('[dsh-dock] mobile relay HTTP error:', error && error.message)
+            return sendJson(res, status, { ok: false, error: { code: status >= 500 ? 'internal' : 'bad-request', message: (error && error.message) || String(error) } })
+          }
+        },
+      }), 'dsh-dock mobile relay: /dsh-dock/mobile-relay HTTP route')
+    }))
+
+    return () => {
+      while (disposers.length) {
+        const dispose = disposers.pop()
+        try { if (typeof dispose === 'function') dispose() } catch { /* ignore */ }
+      }
+      pairs.clear()
+      tasks.clear()
+      void stopGateway()
+    }
+  },
+}