dsh-in-hand 1.6.0 → 1.7.0

package/README.md

@@ -36,8 +36,9 @@ metrics row above the composer.
 渲染成手机上看得懂的样子。目的很朴素——不用坐到电脑前，也能知道它现在在干什么、有没有
 事在等你。
 
-后来发现同一组窄接口能接上 DSH **自己的**会话运行时，于是「写」只用了 5 条路由就够：
-附件导入、对话、逐字收回复、随时停止、建会话与切换模型。**读是监控，写是对话**——两者共用一套令牌和
+后来发现同一组窄接口能接上 DSH **自己的**会话运行时，于是「写」只用了 6 条路由就够：
+附件导入、对话（含插队与硬打断）、逐字收回复、随时停止、建会话与切换模型、调整排队顺序。
+**读是监控，写是对话**——两者共用一套令牌和
 一条反向隧道，始终不碰 GUI。
 
 所以这里没有 App 可装：没有原生代码、没有打包产物、没有应用商店。手机上进一次「添加到主
@@ -72,7 +73,7 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 
 - **读**：把状态渲染成一份手机看得懂的页面，只放行这一条路径就够。
 - **写**：`/taskwatch/chat/*` 把 DSH **自己的**会话运行时接到手机上 —— 直接对话、
-  逐字收回复、随时停止、切换会话与模型。写入口**只有 5 条**，全部列在下面。
+  逐字收回复、随时停止、切换会话与模型、调整排队顺序。写入口**只有 6 条**，全部列在下面。
 
 采集面完全通过 `ctx.get(...)` 软读取服务，任何一个服务不存在都只会让对应的那一块
 留空，不会让插件挂载失败。对话那一组同理：拿不到 `sessionController` 时只让这一个
@@ -107,25 +108,46 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 | `/taskwatch/chat/titles?ids=` | JSON | 批量补会话标题（最多 20 个，宿主缓存 10 分钟） |
 | `/taskwatch/chat/page?...` | JSON | 往更早翻会话历史 |
 | `/taskwatch/chat/stream?sessionId=` | SSE | 跟随一个会话：开场快照 + 增量事件 + 逐字输出 |
+| `/taskwatch/chat/queue?sessionId=` | JSON | 该会话未领取的消息：`items`（下一轮队列，可重排）与 `steering`（已插到本回合下一步） |
 | `/taskwatch/manifest.webmanifest` | JSON | PWA manifest |
 | `/taskwatch/sw.js` | JS | service worker |
 | `/taskwatch/icon-192.png` · `/taskwatch/icon-512.png` | PNG | 图标 |
 
-写（`POST`）—— **只有这 5 条**：
+写（`POST`）—— **只有这 6 条**：
 
 | 路径 | 请求体 | 说明 |
 |---|---|---|
 | `/taskwatch/chat/upload` | 原始二进制（`sessionId/kind/name/mime` 查询参数） | 导入文件或图片；图片由宿主校验，文件按会话签发 receipt |
-| `/taskwatch/chat/send` | `{sessionId,text,attachments?,mode?,timeZone?}` | 给会话发文字和已上传附件 |
+| `/taskwatch/chat/send` | `{sessionId,text,attachments?,mode?,now?,interrupt?,timeZone?}` | 给会话发文字和已上传附件；`now:true` 走宿主原生 steer 插队（见下） |
 | `/taskwatch/chat/cancel` | `{sessionId}` | 停止当前这一轮 |
 | `/taskwatch/chat/create` | `{}` 或 `{workspace}` | 新建会话；`workspace` 必须命中 `/taskwatch/chat/workspaces` 列出的路径 |
 | `/taskwatch/chat/model` | `{sessionId,provider,model}` | 切换该会话使用的模型 |
+| `/taskwatch/chat/queue/reorder` | `{sessionId,ids:[...]}` | 重排下一轮队列；`ids` 必须是当前队列的完整 id 列表 |
 
 全部注册在 `ctx.webServer` 上，不代理 DSH 自身的 `/api`，也不转发任意路径。
-写入口就只有上面 5 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
+写入口就只有上面 6 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
 （早先那条断言写的是"源码里不出现 `method === 'POST'`"。加了 5 个写路由之后它
 照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。
 
+### 排队、重排与「立即发送」的真实语义
+
+宿主本来就有两条投递通道：`mode:'queue'`（进 `nextTurn`，等下一轮）与
+`mode:'steer'`（进 `nextStep`，在本回合下一个步骤边界被领取）。手机端：
+
+- **排队** = 默认的 `queue`；`GET /taskwatch/chat/queue` 读 `nextTurn` 的顺序，
+  `POST /taskwatch/chat/queue/reorder` 用同一批 Message 整体重新 `splice`，
+  不伪造消息、不改内容。
+- **立即发送** = `send` 带 `now:true`，即宿主原生 `steer`。它进入 steering lane，
+  排在本轮所有 `nextTurn` 排队消息之前，**但不会中止**正在执行的工具调用或模型
+  请求 —— 消息在下一个 step 边界才被模型看到；会话空闲时会立刻唤醒并起一轮。
+  同一 lane 里更早的 steering 消息仍按先来后到排在它前面。
+- **硬打断** = 再带 `interrupt:true`：先 `cancel({keepInbox:true})`（队列保留），
+  等 agent 真正 idle（最多 2 秒）再 steer；成了就先于保留的 `nextTurn` 队列执行
+  （cancel 前已有的 steering 仍按原顺序先跑）。2 秒内停不下来返回
+  `409 interrupt-timeout`，消息不发出、队列不动。
+- **不会**做的事：不把队列顺序存在插件内存里（那会和宿主真实队列漂移），
+  也不支持把 `steering` 消息重新排进 `nextTurn`。
+
 ### 手机能选工作区，但选不了任意目录
 
 「在手机上新开一个对话」得能指定在哪个目录开工，否则只能落在部署默认值上。但

package/lib/index.js

@@ -830,6 +830,93 @@ export function apply(ctx) {
         return true
       }
 
+      // 新路由的错误统一带机器可读的 code，并给出可分辨的状态码：
+      //   400 参数不合法 / 404 会话不存在 / 409 队列不可用或已变化 /
+      //   501 这个宿主缺服务 / 502 宿主拒绝或抛错。
+      const failJson = (res, status, code, message, extra) =>
+        json(res, status, { error: message, code, ...(extra || {}) })
+
+      // ---- 消息队列 ---------------------------------------------------------
+      //
+      // 队列就是宿主 Agent.inbox 里还没被领取的输入，DSH 自己分成两份：
+      //   nextTurn：等下一轮执行的排队消息（手机上显示为「队列」，顺序可调）；
+      //   nextStep：等本回合下一个 step 边界插入的 steering 消息（已经是插队，
+      //             不再参与排序）。
+      // 读与重排都直接走 dsh-agent 文档化的 Agent.inbox 接口；投递仍走
+      // sessionController.prompt({mode})，和 /taskwatch/chat/send 完全同一条路。
+      //
+      // 为什么重排不用 sessionController.updateQueue：它的 action 只有
+      // edit / remove / steer 三种，**没有换位置**。Inbox 的 splice 是宿主公开的
+      // 结构化接口（dsh-agent README「持久 inbox」一节），重排就是把同一批 Message
+      // 按新顺序原地重新 splice 一次 —— 不伪造消息、不改内容、不额外唤醒。
+      const agentsOf = () => {
+        const svc = ctx.get('agents')
+        return svc !== undefined && typeof svc.get === 'function' ? svc : undefined
+      }
+      const liveAgentOf = (sessionId) => {
+        const svc = agentsOf()
+        if (svc === undefined) return undefined
+        try { return svc.get(sessionId) } catch { return undefined }
+      }
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+      // interrupt 用例必须等 agent 真正离开 running 再 steer：cancel 的 abort 还没
+      // 收敛时，ReactLoopAgent.send() 的 wakingAfterAbort 会把 steer 改投到
+      // next-turn **末尾**，插队就悄悄失效了。宁可 409 也不假装成功。
+      const waitIdle = async (agent, timeoutMs) => {
+        const deadline = Date.now() + timeoutMs
+        while (Date.now() < deadline) {
+          if (agent.status !== 'running') return true
+          await sleep(50)
+        }
+        return agent.status !== 'running'
+      }
+      // 区分「会话不存在」（404）和「会话存在但当前没有 live agent，队列不可读」
+      // （409）。返回 false 表示确证不存在，null 表示没法确认（按不可用处理）。
+      const sessionExists = async (sessionId) => {
+        const store = ctx.get('sessions')
+        if (store !== undefined && typeof store.get === 'function') {
+          try { if (store.get(sessionId) !== undefined) return true } catch { /* 继续找 */ }
+        }
+        const persistence = ctx.get('sessionPersistence')
+        if (persistence !== undefined && typeof persistence.stat === 'function') {
+          try { if (await persistence.stat(sessionId)) return true } catch { /* 继续找 */ }
+        }
+        try {
+          const value = await chatOf().list({}, ctl().signal)
+          return !!(value && Array.isArray(value.items)
+            && value.items.some((s) => String(s.sessionId) === sessionId))
+        } catch {
+          return null
+        }
+      }
+      const queueText = (message) => {
+        const text = blocksText(message && message.content)
+        return text.length > 2000 ? text.slice(0, 2000) + '…（已截断）' : text
+      }
+      const queueItemOf = (message, index) => {
+        const content = message && Array.isArray(message.content) ? message.content : []
+        return {
+          id: String(message && message.id ? message.id : ''),
+          index,
+          text: queueText(message),
+          images: content.filter((b) => b && b.type === 'image').length,
+          files: content.filter((b) => b && b.type === 'file').length,
+          source: asText(message && message.source ? message.source.kind : ''),
+        }
+      }
+      const MAX_QUEUE_ITEMS = 200
+      const queueViewOf = (agent) => {
+        const turn = Array.isArray(agent.inbox.nextTurn) ? agent.inbox.nextTurn : []
+        const step = Array.isArray(agent.inbox.nextStep) ? agent.inbox.nextStep : []
+        return {
+          running: agent.status === 'running',
+          items: turn.slice(0, MAX_QUEUE_ITEMS).map(queueItemOf),
+          steering: step.slice(0, MAX_QUEUE_ITEMS).map(queueItemOf),
+          counts: { queued: turn.length, steering: step.length },
+          truncated: turn.length > MAX_QUEUE_ITEMS || step.length > MAX_QUEUE_ITEMS,
+        }
+      }
+
       // 原始二进制上传：文件由 fileUploads 按 Session 暂存，图片由 attachments
       // 先做图像准入再用一次性 token 交给后续 prompt。请求体硬上限沿用交付文件
       // 的 32 MiB 边界，名称只作为显示名传给宿主，绝不解释为路径。
@@ -1024,6 +1111,18 @@ export function apply(ctx) {
       }), 'in-hand: chat create route')
 
       // 发消息。requestId 由宿主生成：客户端不该能决定请求身份。
+      //
+      // now:true 的语义（宿主原生能力，不模拟）：
+      //   - 不打断：走 mode:'steer'。消息不进 nextTurn 队列，而是进 nextStep
+      //     （steering lane），在本回合**下一个 step 边界**被领取 —— 排在本轮所有
+      //     nextTurn 排队消息之前；若已有更早的 steering 消息，它们仍按先来后到
+      //     排在前面（同一 lane 不改序）。会话空闲时 steer 会直接唤醒 agent，
+      //     立刻起一轮。正在执行的工具调用或模型请求不会被中止。
+      //   - 要硬打断：再带 interrupt:true。先 cancel({keepInbox:true})（队列保留），
+      //     等 agent 真正 idle（最多 2 秒）再 steer；新消息进入新回合的 steering
+      //     lane，先于保留的 nextTurn 队列。cancel 前就存在的 steering 消息仍会
+      //     按原顺序先跑。没停下来就 409，消息不发出、队列不动。
+      //   兼容旧的 mode:'steer' 写法：它等价于 now:true 但不会 cancel。
       ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/taskwatch/chat/send',
@@ -1031,10 +1130,13 @@ export function apply(ctx) {
           if (!requirePost(req, res, 'application/json')) return
           const lifetime = requestLifetime(req, res)
           const locked = []
+          let nowRequested = false
           try {
             const body = await readJson(req)
             const sessionId = asText(body.sessionId)
             const text = asText(body.text)
+            const wantNow = body.now === true
+            const wantInterrupt = wantNow && body.interrupt === true
             if (!sessionId) throw new Error('缺少 sessionId')
             if (body.attachments !== undefined && !Array.isArray(body.attachments)) throw new Error('附件格式无效')
             const uploads = body.attachments || []
@@ -1086,10 +1188,33 @@ export function apply(ctx) {
                 continue
               }
             }
+            // interrupt 只对正在跑的回合适用；空闲会话没有可打断的工作，
+            // 直接 steer 就会立刻起一轮，不必也无从 cancel。
+            if (wantInterrupt) {
+              const active = liveAgentOf(sessionId)
+              if (active !== undefined && active.status === 'running') {
+                const service = chatOf()
+                if (typeof service.cancel !== 'function') {
+                  failJson(res, 501, 'host-unsupported', '宿主不支持取消当前回合，无法立即发送')
+                  return
+                }
+                try {
+                  await service.cancel({ sessionId })
+                } catch (e) {
+                  failJson(res, 502, 'host-rejected', '打断当前回合失败：' + why(e))
+                  return
+                }
+                if (!(await waitIdle(active, 2000))) {
+                  failJson(res, 409, 'interrupt-timeout', '当前回合没能在 2 秒内停下，消息未发送')
+                  return
+                }
+              }
+            }
+            nowRequested = wantNow
             const request = {
               requestId: randomUUID(),
               sessionId,
-              mode: body.mode === 'steer' ? 'steer' : 'queue',
+              mode: (wantNow || body.mode === 'steer') ? 'steer' : 'queue',
               content,
             }
             if (asText(body.timeZone)) request.clientTimeZone = asText(body.timeZone)
@@ -1098,7 +1223,12 @@ export function apply(ctx) {
             for (const { key, record } of locked) if (pendingUploads.get(key) === record) pendingUploads.delete(key)
             if (!res.destroyed && !res.writableEnded) json(res, 200, { ok: true, accepted: true })
           } catch (e) {
-            if (!res.destroyed && !res.writableEnded) json(res, 200, { error: why(e) })
+            if (!res.destroyed && !res.writableEnded) {
+              // 老客户端只认 200 + {error}，保持原契约；带 now 的新语义失败用 502，
+              // 让调用方能和「参数不对」（仍是 200 + 文本）分开。
+              if (nowRequested) failJson(res, 502, 'host-rejected', '立即发送失败：' + why(e))
+              else json(res, 200, { error: why(e) })
+            }
           } finally {
             for (const { record } of locked) record.sending = false
             lifetime.dispose()
@@ -1123,6 +1253,120 @@ export function apply(ctx) {
         },
       }), 'in-hand: chat cancel route')
 
+      // 查询一个会话的消息队列。只回纯标量（id / 文本 / 附件计数 / 来源），
+      // 绝不把 live 的 Message 对象或图片字节带出去。
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/taskwatch/chat/queue',
+        handler: async (req, res) => {
+          if (req.method !== 'GET') {
+            res.setHeader('allow', 'GET')
+            failJson(res, 405, 'method-not-allowed', '只接受 GET')
+            return
+          }
+          try {
+            const url = new URL(req.url || '/', 'http://127.0.0.1')
+            const sessionId = asText(url.searchParams.get('sessionId')).trim()
+            if (!sessionId) { failJson(res, 400, 'bad-request', '缺少 sessionId'); return }
+            if (agentsOf() === undefined) {
+              failJson(res, 501, 'host-unsupported', '宿主没有 agents 服务，消息队列不可用')
+              return
+            }
+            const agent = liveAgentOf(sessionId)
+            if (agent === undefined) {
+              const exists = await sessionExists(sessionId)
+              if (exists === false) { failJson(res, 404, 'session-not-found', '会话不存在'); return }
+              failJson(res, 409, 'queue-unavailable', '会话当前没有活动的 agent，消息队列不可用')
+              return
+            }
+            json(res, 200, { ok: true, sessionId, ...queueViewOf(agent) })
+          } catch (e) {
+            failJson(res, 502, 'host-rejected', '读取消息队列失败：' + why(e))
+          }
+        },
+      }), 'in-hand: chat queue route')
+
+      // 重排 nextTurn（下一轮队列）。ids 必须是当前队列的**完整** id 列表：
+      // 少了、多了、重复或包含 steering 消息都会 409 并要求客户端刷新。
+      // 这是有意的 —— 只按客户端看到的快照整体替换，避免「把已经被领走的消息
+      // 又插回去」这类不可见的数据错乱。
+      ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/taskwatch/chat/queue/reorder',
+        handler: async (req, res) => {
+          if (!requirePost(req, res, 'application/json')) return
+          try {
+            const body = await readJson(req)
+            const sessionId = asText(body.sessionId).trim()
+            if (!sessionId) { failJson(res, 400, 'bad-request', '缺少 sessionId'); return }
+            if (!Array.isArray(body.ids)) {
+              failJson(res, 400, 'bad-request', 'ids 必须是消息 id 数组')
+              return
+            }
+            const ids = body.ids.map((id) => asText(id))
+            if (!ids.length || ids.some((id) => !id)) {
+              failJson(res, 400, 'bad-request', 'ids 必须是非空的消息 id 数组')
+              return
+            }
+            if (new Set(ids).size !== ids.length) {
+              failJson(res, 400, 'bad-request', 'ids 里有重复的消息')
+              return
+            }
+            if (agentsOf() === undefined) {
+              failJson(res, 501, 'host-unsupported', '宿主没有 agents 服务，消息队列不可用')
+              return
+            }
+            const agent = liveAgentOf(sessionId)
+            if (agent === undefined) {
+              const exists = await sessionExists(sessionId)
+              if (exists === false) { failJson(res, 404, 'session-not-found', '会话不存在'); return }
+              failJson(res, 409, 'queue-unavailable', '会话当前没有活动的 agent，消息队列不可用')
+              return
+            }
+            // 从这里到 splice 全部同步：中间不能 await，否则读到的队列和写回的队列
+            // 可能不是同一份（消息被领取后，旧对象会被重新插回去）。
+            let current
+            try {
+              current = Array.from(agent.inbox.nextTurn)
+            } catch (e) {
+              failJson(res, 409, 'queue-unavailable', '这个会话的队列状态读不到：' + why(e))
+              return
+            }
+            const currentIds = current.map((m) => String(m && m.id))
+            // 只重排普通用户提示词。目标轮次 / 子代理续跑 / 提问回复这类消息在
+            // 宿主里有各自的 discarded 副作用（重排会产生一次 discard + insert），
+            // 不去碰它们；手机上这些行的 source 会显示出来，由客户端禁用排序。
+            const foreign = current.find((m) => !(m && m.source && m.source.kind === 'user'))
+            if (foreign) {
+              failJson(res, 409, 'queue-unavailable', '队列里有非用户消息（目标轮次/子代理/提问回复），暂不支持重排')
+              return
+            }
+            const sameSet = currentIds.length === ids.length
+              && ids.every((id) => currentIds.indexOf(id) >= 0)
+            if (!sameSet) {
+              failJson(res, 409, 'queue-changed', '队列已经变化（有消息被领取或新增），请刷新后重试', { current: currentIds })
+              return
+            }
+            const changed = ids.some((id, i) => id !== currentIds[i])
+            if (changed) {
+              const byId = new Map(current.map((m) => [String(m.id), m]))
+              const ordered = ids.map((id) => byId.get(id))
+              try {
+                agent.inbox.splice('next-turn', 0, current.length, ordered)
+              } catch (e) {
+                failJson(res, 502, 'host-rejected', '宿主拒绝重排：' + why(e))
+                return
+              }
+            }
+            json(res, 200, {
+              ok: true, sessionId, changed, ids: ids.slice(), ...queueViewOf(agent),
+            })
+          } catch (e) {
+            failJson(res, 502, 'host-rejected', '重排失败：' + why(e))
+          }
+        },
+      }), 'in-hand: chat queue reorder route')
+
       // 会话日志的流式跟随（SSE）。
       //
       // follow() 返回的本来就是**为传输设计的 wire 帧**（SessionWireEvent.data 是