dsh-plugin-mobile-gateway 0.7.0 → 0.7.1

package/PROTOCOL.md

@@ -1,6 +1,6 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.7.0）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.7.1）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -162,11 +162,11 @@ Human-in-the-loop 分为两条独立通道：
 - **提问**：Agent 的 `ask_user_question` 工具向用户收集答案。
 - **审批**：高风险工具操作（例如沙箱升权）请求一次性允许或拒绝。
 
-二者都是 API Gateway 的临时请求，不属于持久化的 `session/event`，且都必须以其原始 `rpcId` 通过专用响应帧回答，不能作为普通 `message` 发送。
+二者都是 Host waterfall 的临时请求，不属于持久化的 `session/event`，且都必须以插件为该次请求生成的 `rpcId` 通过专用响应帧回答，不能作为普通 `message` 发送。该内部实现不改变移动端帧格式。
 
 ### 3.1 提问与回答
 
-Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway 的 `events.mux()` 收到临时的待回答请求，并推送给移动端。
+Agent 调用 DSH 的 `ask_user_question` 工具时，插件直接接入 Host 的 `user-questions/request` waterfall，并把临时请求投影给移动端。若没有可处理该 Session 的移动连接，插件调用 `next()`，由 WebUI 或后续 Host answerer 处理。
 
 #### `question-requested` — 服务端推送问题
 
@@ -191,7 +191,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 }
 ```
 
-- `rpcId`：API Gateway 为这一整批问题生成的稳定 ID。回答或取消时必须原样返回，客户端不得自行生成。
+- `rpcId`：移动网关为这一整批问题生成的不透明稳定 ID。回答或取消时必须原样返回，客户端不得自行生成或解析。
 - `questions`：一次工具调用中的完整问题批次；可能包含多题。
 - `id`：问题 ID，必须在对应答案中原样返回。
 - `header` / `detail`：可选展示信息。
@@ -226,7 +226,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 }
 ```
 
-提交规则由 API Gateway 严格校验：
+提交规则由移动网关在进入 Host waterfall 前严格校验：
 
 - 必须一次提交这一批中的全部问题，`answers` 数量、顺序和 `id` 必须与 `questions` 一致。
 - `selected` 中的值必须与原始 `options[].label` 完全一致，且不能重复。
@@ -264,13 +264,13 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "outcome":"answered" }
 ```
 
-`outcome` 为 `answered` 或 `cancelled`。WebUI、iOS 或其他客户端中的第一个合法响应获胜；所有移动连接都会收到最终状态并应关闭对应选择界面。移动端断线重连后，API Gateway 会重放仍待回答的问题；DSH 进程重启则会取消这些仅存在于运行时的问题。
+`outcome` 为 `answered` 或 `cancelled`。存在匹配 Session 的移动连接时，移动网关优先认领请求，多台移动设备中的第一个合法响应获胜；若没有匹配连接或连接全部断开，则通过 `next()` 回退给 WebUI/后续 Host answerer。所有移动连接都会收到由移动端完成的最终状态并应关闭对应选择界面。重连时网关会重放仍由它持有的问题；DSH 进程重启则会取消这些仅存在于运行时的问题。
 
 ---
 
 ### 3.2 操作审批
 
-当 DSH 的工具管线要求人工授权时，插件会从 API Gateway 收到一次 `approval/requested`。这正是 Web UI 中“等待审批”卡片对应的事件：`reason` 是面向用户的审批说明，`toolName` 标识请求操作的工具，`callId` 可用于与实时工具调用轨迹关联。
+当 DSH 的工具管线要求人工授权时，插件会接入一次 Host `approval/request` waterfall，并向移动端投影为 `approval-requested`。这正是 Web UI 中“等待审批”卡片对应的能力：`reason` 是面向用户的审批说明，`toolName` 标识请求操作的工具，`callId` 可用于与实时工具调用轨迹关联。
 
 #### `approval-requested` — 服务端推送待审批操作
 
@@ -288,7 +288,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 ```
 
 - `rpcId`：本次可回答请求的稳定 RPC ID；提交决定时必须原样返回。
-- `approvalId`：审批审计 ID；同样必须原样返回，并用于将最终状态关联到本地审批卡片。
+- `approvalId`：移动网关生成的本次审批关联 ID；同样必须原样返回，并用于将最终状态关联到本地审批卡片。
 - `toolName`：请求审批的工具名。
 - `callId` / `reason`：可选。前者可关联工具调用，后者应直接显示为待审批原因。
 - `replay: true`：表示当前仍未决定的审批在移动端连接或切换 Session 后重放。客户端应按 `rpcId` 去重。
@@ -321,7 +321,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "approvalId":"approval-1", "outcome":"allowed-once", "accepted":true }
 ```
 
-如果 Web UI 或另一台移动设备已经先作出决定，则回执为 `accepted:false`，并附带 `reason:"not-pending"`。收到错误帧或未被接受的回执时，客户端应保留当前状态，等待最终状态或重新打开事件流。
+如果另一台移动设备已经先作出决定，或请求已经回退给 WebUI/后续 answerer，则回执为 `accepted:false`，并附带 `reason:"not-pending"`。收到错误帧或未被接受的回执时，客户端应保留当前状态，等待最终状态或重新打开事件流。
 
 #### `approval-resolved` — 服务端广播最终状态
 
@@ -330,7 +330,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "approvalId":"approval-1", "outcome":"allowed-once" }
 ```
 
-`outcome` 为 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`。所有移动连接都会收到最终状态并关闭对应审批卡片。移动端断线重连后，API Gateway 会重放仍待决定的审批；已决审批不会重放。
+`outcome` 为 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`。所有移动连接都会收到由移动网关完成的最终状态并关闭对应审批卡片。移动端断线重连后，网关会重放仍由它持有的审批；已决或已回退的审批不会重放。
 
 ---
 
@@ -949,6 +949,7 @@ WebUI 中的“任务”与“进行中的目标”分别对应 DSH 的 `todos`
 | v0.6.8 | 会话工作目录受限的文件列表与分块下载：支持图片、文档、IPA、APK 等普通文件，含连接归属、路径越界防护、取消、超时和 SHA-256 完整性校验 |
 | v0.6.9 | 服务端驱动的命令与技能目录：支持本地化 Hint、通用二级选项、专用命令执行，以及 command/compaction 生命周期事件；Host 命令不再作为用户 Prompt 发送 |
 | v0.7.0 | 任务与 Goal 对齐：任务/Goal 基线查询、`todos`/`goal` 实时投影、Goal 改名、暂停、继续与删除 |
+| v0.7.1 | DSH v0.1.2-rc.1 兼容：内部迁移至 Remote Gateway 与 Host waterfall，移除 APIProxy 依赖；`dsh-mobile-v1` 保持不变 |
 
 ---
 

package/README.md

@@ -6,7 +6,15 @@
 
 DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、任务列表和当前 Goal 同步及管理、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
 
-> v0.7.0：移动端现可与 WebUI 对齐展示任务列表和当前 Goal；支持 Goal 改名、暂停、继续和删除，并通过实时 projection 与 revision 校验处理多设备并发更新。
+> v0.7.1：适配 DSH v0.1.2-rc.1 Remote Gateway，移除 APIProxy 依赖；移动端协议和现有功能保持兼容。
+
+## 协议与 DSH 兼容层
+
+移动端连接的是本项目维护的 `dsh-mobile-v1`，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH v0.1.2-rc.1 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals 等 namespace 和严格参数只存在于该适配层。
+
+因此本次从旧 APIProxy 迁移到 Remote Gateway 不要求现有移动端修改：WebSocket 子协议、`hello.protocol = 3`、配对鉴权和已有请求/响应字段保持不变。以后 DSH 调整 Remote API 时，优先只更新插件适配层及契约测试；只有移动协议本身发生不可兼容变化时，才会新增并并行支持新的移动端协议版本。
+
+详细实施边界见 [Remote Gateway 重构实施计划](docs/remote-gateway-refactor-plan.md)。
 
 - WebSocket：`/ws/mobile`
 - 局域网：`ws://<局域网 IP>:3081/ws/mobile`

package/cordis.patch.yml

@@ -1,7 +1,7 @@
 # dsh-plugin-mobile-gateway bundle patch.
 # Applied after dsh-base and dsh-web-app: inserts the persistent /ws/mobile
-# gateway row into the host plane (it consumes the host `webServer` service
-# and the host `session/event` feed, and publishes no service of its own).
+# gateway row into the host plane (it consumes `webServer`, the Host Remote
+# Gateway and the `session/event` feed, and publishes no service of its own).
 - insert:
     - id: mobile-gateway
       name: 'dsh-plugin-mobile-gateway'

package/docs/blog-mobile-gateway.md

@@ -379,7 +379,7 @@ DSH 用 Cordis 的依赖注入容器编排"服务行"。插件通过 `package.js
 const plugin = {
   name: 'mobile-gateway',
   Config,
-  inject: ['webServer', 'apiProxy', 'typertGateway', 'agentDefaultModel'],
+  inject: ['webServer', 'typertGateway', 'agentDefaultModel'],
   apply(ctx, config) { /* ... */ },
 }
 ```

package/docs/remote-gateway-refactor-plan.md

@@ -0,0 +1,52 @@
+# Remote Gateway 重构实施计划
+
+## 目标
+
+在保持移动端 `dsh-mobile-v1`、配对流程和现有消息字段不变的前提下，移除对 DSH `APIProxy` 的依赖，改为只通过 Host 侧 `typertGateway` 访问 DSH v0.1.2-rc.1 Remote API。所有上游协议差异集中在插件内部适配层，后续 DSH 发生破坏性更新时不要求移动端同步升级。
+
+## 稳定边界
+
+- 对移动端：继续协商 `dsh-mobile-v1`，`hello.protocol` 保持 `3`，已有请求和响应帧保持兼容。
+- 对 DSH：仅 `lib/dsh-host-adapter.mjs` 知道 Remote namespace、method、严格参数名、stream opening frame 和错误形态。
+- 对业务编排：`lib/index.mjs` 只调用语义化 Host Adapter，不拼装 Remote 描述符。
+- 对错误：上游带 `code/message` 的错误映射为既有移动端错误帧；未知异常稳定映射为 `internal`。
+- 对历史：适配层把 RC 版压缩的 `chunkrow/*` 记录还原为 v1 已支持的 `assistant/chunk` 事件。
+
+## 实施阶段
+
+### 1. Host Adapter 与普通 RPC
+
+- 封装 `invoke()` / `stream()`，校验关键返回值。
+- 迁移 Session、Workspace、Settings、Commands、Skills、Agent Presets、LLM、Goals。
+- Session 历史通过 `session.follow` 获取快照游标和 projections；旧页通过 `session.page` 读取。
+- Workspace 列表通过 `workspace.follow` 的 baseline 获取。
+- Host 信息由插件本地能力和 Remote catalog 合成，不再依赖已删除的 `host.describe`。
+
+### 2. 实时与 Human-in-the-loop
+
+- 普通实时会话事件继续使用 Host 内部 `session/event`，保持移动端事件帧不变。
+- projection 更新从 `session.control` stream 转发，替代旧 `api.events.mux()` 中的投影帧。
+- approval/question 改为 Cordis waterfall listener；生成插件自有不透明 `rpcId`，等待移动端回答。
+- 只有存在匹配会话的已认证移动连接时才认领 waterfall；否则立即 `next()`，保留 WebUI 回退路径。
+- 连接断开、请求 signal 取消或插件卸载时释放等待者并回退/取消，禁止悬挂 Promise。
+
+### 3. 兼容性测试与门禁
+
+- 使用假的 `typertGateway`，按 RC 的精确 namespace/method/args 测试，不再模拟 APIProxy。
+- 添加 Host Adapter 单元测试，覆盖 direct value、throw、stream baseline、历史 chunk 展开和严格参数形状。
+- 保留现有 WebSocket v1 端到端用例，验证移动端请求/响应字段没有改变。
+- 增加静态门禁：生产代码不得出现 `apiProxy`、旧 `{ rpcId, payload }` Remote 调用或 `api.events.mux()`。
+
+### 4. 配置与文档
+
+- 删除 `apiProxy` 注入声明。
+- 更新 README、PROTOCOL 和 bundle patch 注释，明确移动协议与 DSH Remote 的分层。
+- 保留 `session-query-sqlite` 的按需搜索配置，但将其标记为可选能力，避免它成为插件启动前提。
+
+## 验收标准
+
+1. 插件可在 DSH v0.1.2-rc.1 组合中加载，且不请求 `apiProxy`。
+2. 当前移动端无需修改即可完成配对、会话列表、历史、发送消息、命令、模型、设置、任务、Goal、文件和交互审批。
+3. 全量测试通过；Remote 调用参数均由适配层测试锁定。
+4. 上游 namespace 或数据结构未来变化时，改动范围原则上限定于 Host Adapter 及对应契约测试。
+

package/lib/dsh-host-adapter.mjs

@@ -0,0 +1,304 @@
+import crypto from 'node:crypto'
+import os from 'node:os'
+
+function requireRecord(value, endpoint) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${endpoint} returned an invalid object`)
+  }
+  return value
+}
+
+function requireArray(value, endpoint) {
+  if (!Array.isArray(value)) throw new Error(`${endpoint} returned an invalid array`)
+  return value
+}
+
+function chunkRowLength(event) {
+  if (event.type === 'chunkrow/tool-call-chunks') return requireArray(event.data?.args, event.type).length
+  return requireArray(event.data?.texts, event.type).length
+}
+
+// DSH 0.1.2 compresses consecutive assistant deltas inside history pages.
+// dsh-mobile-v1 predates that storage shape, so restore the exact logical
+// SessionEvent sequence at this boundary instead of teaching every client a
+// Host-specific encoding detail.
+function expandChunkRow(event) {
+  const data = requireRecord(event.data, event.type)
+  const values = event.type === 'chunkrow/tool-call-chunks'
+    ? requireArray(data.args, event.type)
+    : requireArray(data.texts, event.type)
+  const gaps = requireArray(data.dt, event.type)
+  if (gaps.length !== Math.max(0, values.length - 1)) {
+    throw new Error(`${event.type} returned invalid timing data`)
+  }
+  const events = []
+  let time = event.time
+  for (let index = 0; index < values.length; index += 1) {
+    if (index > 0) time += gaps[index - 1]
+    let chunk
+    if (event.type === 'chunkrow/text-chunks') {
+      chunk = { type: 'text-delta', index: data.index, text: values[index] }
+    } else if (event.type === 'chunkrow/reasoning-chunks') {
+      chunk = { type: 'reasoning-delta', index: data.index, text: values[index] }
+    } else {
+      chunk = {
+        type: 'tool-call-delta',
+        index: data.index,
+        id: data.id,
+        ...(Object.hasOwn(data, 'name') ? { name: data.name } : {}),
+        argumentsDelta: values[index],
+      }
+    }
+    events.push({
+      type: 'assistant/chunk',
+      seq: event.seq + index,
+      time,
+      data: { turn: data.turn, step: data.step, chunk },
+    })
+  }
+  return events
+}
+
+export function expandHistoryRecords(records) {
+  const events = []
+  for (const record of requireArray(records, 'session history')) {
+    const value = requireRecord(record, 'session history record')
+    const event = requireRecord(value.event, 'session history event')
+    if (value.type === 'event') {
+      events.push(event)
+      continue
+    }
+    if (value.type !== 'chunks' || ![
+      'chunkrow/text-chunks',
+      'chunkrow/reasoning-chunks',
+      'chunkrow/tool-call-chunks',
+    ].includes(event.type)) {
+      throw new Error('session history returned an unsupported record')
+    }
+    if (chunkRowLength(event) === 0) throw new Error(`${event.type} returned an empty run`)
+    events.push(...expandChunkRow(event))
+  }
+  return events
+}
+
+async function firstStreamFrame(gateway, namespace, method, args, signal) {
+  const ownedAbort = signal === undefined ? new AbortController() : null
+  const streamSignal = signal ?? ownedAbort.signal
+  const iterable = await gateway.stream({ namespace, method, args, signal: streamSignal })
+  const iteratorFactory = iterable?.[Symbol.asyncIterator] ?? iterable?.[Symbol.iterator]
+  if (typeof iteratorFactory !== 'function') throw new Error(`${namespace}/${method} returned an invalid stream`)
+  const iterator = iteratorFactory.call(iterable)
+  try {
+    const first = await iterator.next()
+    if (first.done) throw new Error(`${namespace}/${method} ended before its opening frame`)
+    return first.value
+  } finally {
+    ownedAbort?.abort()
+    if (typeof iterator.return === 'function') await iterator.return()
+  }
+}
+
+function requestArgs(request) {
+  return { request }
+}
+
+// The RC.1 SessionController intentionally names its reserved list argument
+// `_request`. Typert descriptors preserve that source parameter name exactly,
+// so this endpoint cannot share the normal `{ request }` wrapper.
+function sessionListArgs(request) {
+  return { _request: request }
+}
+
+/**
+ * The only module allowed to know DSH Remote endpoint names and argument
+ * descriptors. Its public methods intentionally match mobile-gateway domain
+ * operations, not the upstream transport envelope.
+ */
+export function createDshHostAdapter(typertGateway) {
+  if (!typertGateway || typeof typertGateway.invoke !== 'function' || typeof typertGateway.stream !== 'function') {
+    throw new Error('mobile-gateway requires the DSH Remote Gateway host service')
+  }
+
+  const invoke = (namespace, method, args, signal) => typertGateway.invoke({
+    namespace,
+    method,
+    args,
+    ...(signal === undefined ? {} : { signal }),
+  })
+
+  const sessionSnapshot = async (request, signal) => {
+    const frame = requireRecord(await firstStreamFrame(
+      typertGateway,
+      'session',
+      'follow',
+      requestArgs(request),
+      signal,
+    ), 'session/follow')
+    if (frame.type !== 'snapshot' || !Number.isSafeInteger(frame.cursor)) {
+      throw new Error('session/follow returned an invalid opening snapshot')
+    }
+    return frame
+  }
+
+  const history = async (payload, signal) => {
+    const request = {
+      address: { kind: 'session', sessionId: payload.sessionId },
+      ...(payload.maxMessages === undefined ? {} : { maxMessages: payload.maxMessages }),
+    }
+    const snapshot = await sessionSnapshot(request, signal)
+    let records = snapshot.records
+    let hasMore = snapshot.hasMore === true
+    if (payload.beforeSeq !== undefined) {
+      const page = requireRecord(await invoke('session', 'page', requestArgs({
+        address: request.address,
+        throughSeq: snapshot.cursor,
+        beforeSeq: payload.beforeSeq,
+        ...(payload.maxMessages === undefined ? {} : { maxMessages: payload.maxMessages }),
+      }), signal), 'session/page')
+      records = page.records
+      hasMore = page.hasMore === true
+    }
+    return {
+      events: expandHistoryRecords(records).map(event => ({ event })),
+      hasMore,
+      projections: requireRecord(snapshot.projections, 'session/follow projections'),
+    }
+  }
+
+  const modelCatalog = async (signal) => requireRecord(
+    await invoke('session', 'modelCatalog', {}, signal),
+    'session/modelCatalog',
+  )
+
+  const commands = {
+    list: (sessionId, signal) => invoke('commands', 'list', { agentId: sessionId }, signal),
+    execute: (sessionId, line, images, signal) => invoke(
+      'commands',
+      'execute',
+      { agentId: sessionId, line, images },
+      signal,
+    ),
+  }
+
+  const goalRefValue = (value, endpoint) => {
+    const goal = requireRecord(value, endpoint)
+    if (typeof goal.id !== 'string' || !Number.isSafeInteger(goal.revision)) {
+      throw new Error(`${endpoint} returned an invalid goal`)
+    }
+    return { ref: { id: goal.id, revision: goal.revision } }
+  }
+
+  const describeHost = async (signal) => {
+    const [sessions, catalog, canOpenPath] = await Promise.all([
+      invoke('session', 'list', sessionListArgs({}), signal),
+      modelCatalog(signal),
+      invoke('session', 'canOpenWorkspacePath', {}, signal).catch(() => false),
+    ])
+    return {
+      version: 'remote-gateway',
+      cwd: os.homedir(),
+      attachedSessions: Array.isArray(sessions?.items) ? sessions.items.length : 0,
+      canOpenPath: canOpenPath === true,
+      defaultProvider: catalog.default?.provider,
+      defaultModel: catalog.default?.model,
+    }
+  }
+
+  return {
+    sessions: {
+      list: (payload = {}, signal) => invoke('session', 'list', sessionListArgs(payload), signal),
+      search: (payload, signal) => invoke('session', 'search', requestArgs(payload), signal),
+      create: (payload, signal) => invoke('session', 'create', requestArgs(payload), signal),
+      prompt: (payload, signal) => invoke('session', 'prompt', requestArgs({
+        requestId: crypto.randomUUID(),
+        ...payload,
+      }), signal),
+      attachment: (payload, signal) => invoke('session', 'attachment', requestArgs(payload), signal),
+      fork: (payload, signal) => invoke('session', 'fork', requestArgs(payload), signal),
+      selectModel: (payload, signal) => invoke('session', 'selectModel', requestArgs(payload), signal),
+      history,
+      async models(payload, signal) {
+        const [catalog, snapshot] = await Promise.all([
+          modelCatalog(signal),
+          sessionSnapshot({ address: { kind: 'session', sessionId: payload.sessionId }, maxMessages: 1 }, signal),
+        ])
+        const current = snapshot.projections?.values?.modelSelection?.next ?? catalog.default
+        return {
+          current,
+          routable: typeof current?.provider === 'string'
+            && requireArray(catalog.routableProviders, 'session/modelCatalog routableProviders').includes(current.provider),
+          groups: requireArray(catalog.groups, 'session/modelCatalog groups'),
+          failures: requireArray(catalog.failures, 'session/modelCatalog failures'),
+        }
+      },
+    },
+    workspace: {
+      async list(_payload = {}, signal) {
+        const frame = requireRecord(await firstStreamFrame(typertGateway, 'workspace', 'follow', {}, signal), 'workspace/follow')
+        if (frame.type !== 'baseline') throw new Error('workspace/follow returned an invalid opening baseline')
+        return requireRecord(frame.value, 'workspace/follow baseline')
+      },
+      create: (payload, signal) => invoke('workspace', 'create', requestArgs(payload), signal),
+    },
+    settings: {
+      describe: (_payload = {}, signal) => invoke('settings', 'describe', {}, signal),
+      update: (payload, signal) => invoke('settings', 'update', {
+        ns: payload.ns,
+        patch: payload.patch,
+        ...(payload.expectedRevision === undefined ? {} : { expectedRevision: payload.expectedRevision }),
+      }, signal),
+    },
+    skills: {
+      list: (payload, signal) => invoke('skills', 'list', requestArgs(payload), signal),
+    },
+    agentPresets: {
+      list: (_payload = {}, signal) => invoke('agentPresets', 'list', {}, signal),
+    },
+    llm: {
+      async models(_payload = {}, signal) {
+        const catalog = await modelCatalog(signal)
+        return { groups: catalog.groups, failures: catalog.failures }
+      },
+      async providers(_payload = {}, signal) {
+        const providers = await invoke('llm', 'listConfigurableProviders', {}, signal)
+        return { providers: requireArray(providers, 'llm/listConfigurableProviders') }
+      },
+    },
+    goals: {
+      async edit(payload) {
+        return goalRefValue(await invoke('goals', 'edit', {
+          agentId: payload.sessionId,
+          ref: payload.ref,
+          request: {
+            ...(payload.objective === undefined ? {} : { objective: payload.objective }),
+            ...(payload.maxGoalRounds === undefined ? {} : { maxGoalRounds: payload.maxGoalRounds }),
+          },
+        }), 'goals/edit')
+      },
+      async pause(payload) {
+        return goalRefValue(
+          await invoke('goals', 'pause', { agentId: payload.sessionId, ref: payload.ref }),
+          'goals/pause',
+        )
+      },
+      async resume(payload) {
+        return goalRefValue(
+          await invoke('goals', 'resume', { agentId: payload.sessionId, ref: payload.ref }),
+          'goals/resume',
+        )
+      },
+      clear: async payload => {
+        await invoke('goals', 'clear', { agentId: payload.sessionId, ref: payload.ref })
+        return { cleared: true }
+      },
+    },
+    commands,
+    host: {
+      describe: (_payload = {}, signal) => describeHost(signal),
+    },
+    describeHost,
+    openControlStream(signal) {
+      return typertGateway.stream({ namespace: 'session', method: 'control', args: {}, signal })
+    },
+  }
+}

package/lib/index.mjs

@@ -6,7 +6,7 @@
 //     feed the browser UI consumes) to connected mobile clients as curated
 //     JSON text frames.
 //  2. Mobile -> agent: clients send a message through the same socket; the
-//     plugin admits it through the official host API (apiProxy.sessions.prompt)
+//     plugin admits it through the DSH Remote Gateway Host API.
 //     so it enters the target session exactly like a browser-submitted prompt.
 //
 // Wire protocol (JSON text frames):
@@ -114,6 +114,7 @@ import crypto from 'node:crypto'
 import Schema from '@deepseek-ai/schemastery'
 import { WebSocketServer } from 'ws'
 import devicesModule from './devices.js'
+import { createDshHostAdapter } from './dsh-host-adapter.mjs'
 import QRCode from 'qrcode'
 
 const { createRegistry } = devicesModule
@@ -407,25 +408,15 @@ function commandNameOf(line) {
   return (end === -1 ? trimmed.slice(1) : trimmed.slice(1, end)) || null
 }
 
-async function listHostCommands(typertGateway, sessionId) {
-  const listed = await typertGateway.invoke({
-    namespace: 'commands',
-    method: 'list',
-    args: { agentId: sessionId },
-    signal: new AbortController().signal,
-  })
+async function listHostCommands(host, sessionId) {
+  const listed = await host.commands.list(sessionId, new AbortController().signal)
   if (!Array.isArray(listed)) throw new Error('commands/list returned an invalid catalog')
   return listed
 }
 
-async function executeHostCommand(typertGateway, sessionId, line, images, requestType) {
+async function executeHostCommand(host, sessionId, line, images, requestType) {
   try {
-    const execution = await typertGateway.invoke({
-      namespace: 'commands',
-      method: 'execute',
-      args: { agentId: sessionId, line, images },
-      signal: new AbortController().signal,
-    })
+    const execution = await host.commands.execute(sessionId, line, images, new AbortController().signal)
     if (execution === undefined || execution === null) {
       return { kind: 'error', code: 'unknown-command', message: `unknown or malformed command: ${line}`, requestType, sessionId }
     }
@@ -445,7 +436,7 @@ async function executeHostCommand(typertGateway, sessionId, line, images, reques
   }
 }
 
-async function admitCommand(typertGateway, msg) {
+async function admitCommand(host, msg) {
   const sessionId = requireSessionId(msg)
   if (sessionId.error) return sessionId.error
   const line = typeof msg.line === 'string' ? msg.line.trim() : ''
@@ -456,7 +447,7 @@ async function admitCommand(typertGateway, msg) {
   const parsedImages = parseWireImages(msg.images, 'command-execute')
   if (parsedImages.error) return { ...parsedImages.error, sessionId: sessionId.value }
   try {
-    const listed = await listHostCommands(typertGateway, sessionId.value)
+    const listed = await listHostCommands(host, sessionId.value)
     const descriptor = listed.find((command) => command && command.name === name)
     if (!descriptor) {
       return { kind: 'error', code: 'unknown-command', message: `command not found: /${name}`, requestType: 'command-execute', sessionId: sessionId.value }
@@ -464,7 +455,7 @@ async function admitCommand(typertGateway, msg) {
     if (parsedImages.value.length > 0 && descriptor.input?.images !== true) {
       return { kind: 'error', code: 'bad-request', message: `/${name} does not accept image attachments`, requestType: 'command-execute', sessionId: sessionId.value }
     }
-    return executeHostCommand(typertGateway, sessionId.value, line, parsedImages.value, 'command-execute')
+    return executeHostCommand(host, sessionId.value, line, parsedImages.value, 'command-execute')
   } catch (error) {
     const code = error && error.code ? error.code : 'internal'
     const message = error && error.message ? error.message : String(error)
@@ -497,44 +488,30 @@ async function admitMessage(api, msg) {
         if (createPayload.workspaceId) log('mobile message: both workspaceId and cwd given, using workspaceId')
         else createPayload.cwd = msg.cwd.trim()
       }
-      const created = await api.sessions.create({ rpcId: crypto.randomUUID(), payload: createPayload })
-      if (!created.result.ok) {
-        return { kind: 'error', code: created.result.error.code, message: created.result.error.message }
-      }
-      sessionId = created.result.value.sessionId
+      const created = await api.sessions.create(createPayload)
+      sessionId = created.sessionId
       log(`mobile message created new session ${sessionId} (${JSON.stringify(createPayload)})`)
     }
 
     const resp = await api.sessions.prompt({
-      rpcId: crypto.randomUUID(),
-      payload: {
-        sessionId,
-        mode,
-        // Match the official WebUI ordering: images first, optional text last.
-        content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
-        ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
-      },
+      sessionId,
+      mode,
+      // Match the official WebUI ordering: images first, optional text last.
+      content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
+      ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
     })
-    if (resp.result.ok) {
-      log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
-      return {
-        kind: 'sent',
-        sessionId,
-        mode,
-        ...(resp.result.value.command ? { command: resp.result.value.command } : {}),
-      }
-    }
-    log(`mobile message rejected: ${resp.result.error.code}: ${resp.result.error.message}`)
+    log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
     return {
-      kind: 'error',
-      code: resp.result.error.code,
-      message: resp.result.error.message,
-      ...(sessionId ? { sessionId } : {}),
+      kind: 'sent',
+      sessionId,
+      mode,
+      ...(resp.command ? { command: resp.command } : {}),
     }
   } catch (error) {
+    const code = error && error.code ? error.code : 'internal'
     const message = error && error.message ? error.message : String(error)
     log(`mobile message failed: ${message}`)
-    return { kind: 'error', code: 'internal', message, ...(sessionId ? { sessionId } : {}) }
+    return { kind: 'error', code, message, ...(sessionId ? { sessionId } : {}) }
   }
 }
 
@@ -543,23 +520,17 @@ async function admitMessage(api, msg) {
 // the uniform `{ kind: 'error', code, message, requestType }` frame.
 async function proxyQuery(api, type, method, payload, signal) {
   try {
-    const req = { rpcId: crypto.randomUUID(), payload }
-    const resp = signal ? await method(req, signal) : await method(req)
-    if (resp.result.ok) {
-      log(`query ok: ${type}`)
-      return { kind: type, ...resp.result.value }
-    }
-    log(`query rejected: ${type} -> ${resp.result.error.code}: ${resp.result.error.message}`)
-    return {
-      kind: 'error',
-      code: resp.result.error.code,
-      message: resp.result.error.message,
-      requestType: type,
+    const value = signal ? await method(payload, signal) : await method(payload)
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error(`${type} returned an invalid response`)
     }
+    log(`query ok: ${type}`)
+    return { kind: type, ...value }
   } catch (error) {
+    const code = error && error.code ? error.code : 'internal'
     const message = error && error.message ? error.message : String(error)
-    log(`query failed: ${type} -> ${message}`)
-    return { kind: 'error', code: 'internal', message, requestType: type }
+    log(`query failed: ${type} -> ${code}: ${message}`)
+    return { kind: 'error', code, message, requestType: type }
   }
 }
 
@@ -1190,7 +1161,7 @@ async function loadCommandOptions(api, command, sessionId) {
   }
 }
 
-async function selectCommandOption(api, typertGateway, command, sessionId, optionId) {
+async function selectCommandOption(api, host, command, sessionId, optionId) {
   const catalog = await loadCommandOptions(api, command, sessionId)
   if (catalog.kind !== 'command-options') return catalog
   const option = catalog.options.find((candidate) => candidate.id === optionId)
@@ -1206,12 +1177,12 @@ async function selectCommandOption(api, typertGateway, command, sessionId, optio
 
   if (command === 'permission') {
     try {
-      const execution = await typertGateway.invoke({
-        namespace: 'commands',
-        method: 'execute',
-        args: { agentId: sessionId, line: '/permission ' + optionId, images: [] },
-        signal: new AbortController().signal,
-      })
+      const execution = await host.commands.execute(
+        sessionId,
+        '/permission ' + optionId,
+        [],
+        new AbortController().signal,
+      )
       if (!execution || !execution.result) throw new Error('permission command returned an invalid result')
       if (execution.result.kind === 'error') {
         return { kind: 'error', code: 'command-error', message: execution.result.text, requestType: 'command-select', sessionId }
@@ -1256,7 +1227,7 @@ async function selectCommandOption(api, typertGateway, command, sessionId, optio
 }
 
 // Dispatch one mobile query frame; returns the wire frame to send back.
-async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
+async function handleQuery(api, host, agentDefaultModel, msg) {
   if (msg.type === 'workspaces') {
     return proxyQuery(api, 'workspaces', api.workspace.list.bind(api.workspace), {})
   }
@@ -1386,7 +1357,7 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     return proxyQuery(api, 'providers', api.llm.providers.bind(api.llm), {})
   }
   if (msg.type === 'command-execute') {
-    return admitCommand(typertGateway, msg)
+    return admitCommand(host, msg)
   }
   if (msg.type === 'commands') {
     const sessionId = requireSessionId(msg)
@@ -1398,7 +1369,7 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
       // the mobile wire. The Web UI also contributes /model client-side; expose
       // the equivalent action here so mobile clients can render the same menu.
       const [listed, skillFrame] = await Promise.all([
-        listHostCommands(typertGateway, sessionId.value),
+        listHostCommands(host, sessionId.value),
         api.skills && typeof api.skills.list === 'function'
           ? proxyQuery(api, 'skills', api.skills.list.bind(api.skills), { sessionId: sessionId.value })
           : Promise.resolve({ kind: 'error', code: 'unsupported', message: 'skill catalog is unavailable', requestType: 'skills' }),
@@ -1476,7 +1447,7 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     const command = typeof msg.command === 'string' && msg.command.trim() !== '' ? msg.command.trim() : null
     const optionId = typeof msg.optionId === 'string' && msg.optionId !== '' ? msg.optionId : null
     if (!command || !optionId) return { kind: 'error', code: 'bad-request', message: 'command-select requires command and optionId', requestType: 'command-select', sessionId: sessionId.value }
-    return selectCommandOption(api, typertGateway, command, sessionId.value, optionId)
+    return selectCommandOption(api, host, command, sessionId.value, optionId)
   }
   if (msg.type === 'select-model') {
     const sessionId = requireSessionId(msg)
@@ -1518,14 +1489,14 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     // command registry handler WITHOUT sending anything to the model, and the
     // api-remotes agent lookup resumes cold sessions just like prompt does.
     try {
-      const execution = await typertGateway.invoke({
-        namespace: 'commands',
-        method: 'execute',
-        // commands/execute 的当前 Typert descriptor 要求 images 字段始终存在；
-        // 权限斜杠命令没有附件，因此显式传空数组。
-        args: { agentId: sessionId.value, line: '/permission ' + name, images: [] },
-        signal: new AbortController().signal,
-      })
+      // commands/execute 的当前 Typert descriptor 要求 images 字段始终存在；
+      // 权限斜杠命令没有附件，因此显式传空数组。
+      const execution = await host.commands.execute(
+        sessionId.value,
+        '/permission ' + name,
+        [],
+        new AbortController().signal,
+      )
       if (execution === undefined || execution === null) {
         return { kind: 'error', code: 'unknown-command', message: 'command not found: /permission', requestType: 'permission', sessionId: sessionId.value }
       }
@@ -1863,16 +1834,16 @@ const plugin = {
   name: 'mobile-gateway',
   Config,
   // Hard dependencies: the gateway registers on the host web server and
-  // admits mobile messages through the host API gateway. Cordis must not
+  // admits mobile messages through the Host Remote Gateway. Cordis must not
   // activate this row before either service exists.
-  inject: ['webServer', 'apiProxy', 'typertGateway', 'agentDefaultModel'],
+  inject: ['webServer', 'typertGateway', 'agentDefaultModel'],
   // exported for local tests; Cordis ignores unknown plugin fields
   admitMessage,
   handleQuery,
   apply(ctx, config) {
     const webServer = ctx.webServer
-    const api = ctx.apiProxy
-    const typertGateway = ctx.typertGateway
+    const api = createDshHostAdapter(ctx.typertGateway)
+    const host = api
     const agentDefaultModel = ctx.agentDefaultModel
     const options = {
       path: DEFAULT_WS_PATH,
@@ -1929,7 +1900,7 @@ const plugin = {
         log(`file download expiry failed: ${error && error.message ? error.message : String(error)}`)
       })
     }, Math.min(options.fileDownloadIdleMs, 30_000))
-    const interactionMuxAbort = new AbortController()
+    const controlStreamAbort = new AbortController()
     let counter = 0
     let gatewayEnabled = options.gatewayEnabled === true
     let waitExpiresAt = null
@@ -2035,6 +2006,96 @@ const plugin = {
       return { questionCount, approvalCount }
     }
 
+    const hasInteractionClient = (sessionId) => [...clients].some((client) => (
+      client.readyState === 1
+      && (!client.filterSessionId || client.filterSessionId === sessionId)
+    ))
+
+    const completeQuestion = (pending, action, answer, cancellationCode = 'ASK_CANCELLED') => {
+      if (pendingQuestions.get(pending.rpcId) !== pending) return false
+      pendingQuestions.delete(pending.rpcId)
+      pending.cleanup()
+      if (action === 'answer') pending.resolve(answer)
+      else {
+        const error = new Error('question cancelled by mobile user')
+        error.name = 'UserQuestionError'
+        error.code = cancellationCode
+        pending.reject(error)
+      }
+      broadcastInteractionFrame({
+        kind: 'question-resolved',
+        rpcId: pending.rpcId,
+        sessionId: pending.sessionId,
+        outcome: action === 'answer' ? 'answered' : 'cancelled',
+      })
+      return true
+    }
+
+    const normalizeQuestionAnswers = (pending, answers) => {
+      if (answers.length !== pending.questions.length) return { error: 'answers must cover every question exactly once' }
+      const normalized = []
+      for (let index = 0; index < pending.questions.length; index += 1) {
+        const question = pending.questions[index]
+        const answer = answers[index]
+        if (!answer || typeof answer !== 'object' || answer.id !== question.id || !Array.isArray(answer.selected)) {
+          return { error: 'answers must preserve question order, ids, and selected arrays' }
+        }
+        if (answer.selected.some((label) => typeof label !== 'string')) return { error: 'selected values must be strings' }
+        if (new Set(answer.selected).size !== answer.selected.length) return { error: 'selected values must not repeat' }
+        const offered = new Set((question.options || []).map((option) => option.label))
+        if (answer.selected.some((label) => !offered.has(label))) return { error: 'selected values must match offered option labels' }
+        if (question.multiSelect !== true && answer.selected.length > 1) return { error: 'single-select questions accept at most one selection' }
+        let custom
+        if (answer.custom !== undefined) {
+          if (typeof answer.custom !== 'string' || !answer.custom.trim()) return { error: 'custom answers must be non-empty strings' }
+          custom = answer.custom.trim()
+        }
+        if (question.multiSelect !== true && custom !== undefined && answer.selected.length > 0) {
+          return { error: 'single-select custom answers cannot accompany a selection' }
+        }
+        normalized.push({ id: answer.id, selected: [...answer.selected], ...(custom === undefined ? {} : { custom }) })
+      }
+      return { value: { answers: normalized } }
+    }
+
+    const completeApproval = (pending, outcome) => {
+      if (pendingApprovals.get(pending.rpcId) !== pending) return false
+      pendingApprovals.delete(pending.rpcId)
+      pending.cleanup()
+      pending.resolve(outcome)
+      broadcastInteractionFrame({
+        kind: 'approval-resolved',
+        rpcId: pending.rpcId,
+        sessionId: pending.sessionId,
+        approvalId: pending.approvalId,
+        outcome,
+      })
+      return true
+    }
+
+    const fallbackQuestion = (pending) => {
+      if (pendingQuestions.get(pending.rpcId) !== pending) return
+      pendingQuestions.delete(pending.rpcId)
+      pending.cleanup()
+      Promise.resolve().then(pending.next).then(pending.resolve, pending.reject)
+    }
+
+    const fallbackApproval = (pending) => {
+      if (pendingApprovals.get(pending.rpcId) !== pending) return
+      pendingApprovals.delete(pending.rpcId)
+      pending.cleanup()
+      Promise.resolve().then(pending.next).then(pending.resolve, pending.reject)
+    }
+
+    const releaseUnclaimedInteractions = () => {
+      for (const pending of [...pendingQuestions.values()]) {
+        if (!hasInteractionClient(pending.sessionId)) fallbackQuestion(pending)
+      }
+      for (const pending of [...pendingApprovals.values()]) {
+        if (!hasInteractionClient(pending.sessionId)) fallbackApproval(pending)
+      }
+    }
+
     const respondToQuestion = async (msg, cancel = false) => {
       const rpcId = typeof msg.rpcId === 'string' && msg.rpcId.trim() ? msg.rpcId.trim() : null
       const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() ? msg.sessionId.trim() : null
@@ -2042,46 +2103,30 @@ const plugin = {
         return { kind: 'error', code: 'bad-request', message: `${msg.type} requires rpcId and sessionId`, requestType: msg.type }
       }
 
-      if (cancel) {
-        const pending = pendingQuestions.get(rpcId)
-        if (pending && pending.sessionId !== sessionId) {
-          return { kind: 'error', code: 'bad-request', message: 'sessionId does not match the pending question', requestType: msg.type, sessionId }
-        }
-      } else if (!Array.isArray(msg.answers)) {
+      const pending = pendingQuestions.get(rpcId)
+      if (!pending) {
+        return { kind: 'question-response', rpcId, sessionId, action: cancel ? 'cancel' : 'answer', accepted: false, reason: 'not-pending' }
+      }
+      if (pending.sessionId !== sessionId) {
+        return { kind: 'error', code: 'bad-request', message: 'sessionId does not match the pending question', requestType: msg.type, sessionId }
+      }
+      if (!cancel && !Array.isArray(msg.answers)) {
         return { kind: 'error', code: 'bad-request', message: 'question-answer requires an answers array', requestType: msg.type, sessionId }
       }
-
-      const result = cancel
-        ? { ok: false, error: { code: 'cancelled', message: 'question cancelled by mobile user', details: {} } }
-        : {
-            ok: true,
-            value: {
-              sessionId,
-              answer: {
-                answers: msg.answers.map((answer) => ({
-                  id: answer && answer.id,
-                  selected: answer && answer.selected,
-                  ...(answer && answer.custom !== undefined ? { custom: answer.custom } : {}),
-                })),
-              },
-            },
-          }
-
-      try {
-        const receipt = await api.respond({ type: 'client-response', rpcId, result })
-        log(`question response: rpcId=${rpcId} session=${sessionId} action=${cancel ? 'cancel' : 'answer'} accepted=${receipt.accepted}${receipt.accepted ? '' : ` reason=${receipt.reason}`}`)
-        return {
-          kind: 'question-response',
-          rpcId,
-          sessionId,
-          action: cancel ? 'cancel' : 'answer',
-          accepted: receipt.accepted,
-          ...(!receipt.accepted ? { reason: receipt.reason } : {}),
-        }
-      } catch (error) {
-        const message = error && error.message ? error.message : String(error)
-        log(`question response failed: rpcId=${rpcId} ${message}`)
-        return { kind: 'error', code: 'internal', message, requestType: msg.type, sessionId }
+      const normalized = cancel ? null : normalizeQuestionAnswers(pending, msg.answers)
+      if (normalized?.error) {
+        return { kind: 'error', code: 'bad-response', message: normalized.error, requestType: msg.type, sessionId }
+      }
+      const answer = normalized?.value
+      const accepted = completeQuestion(pending, cancel ? 'cancel' : 'answer', answer)
+      log(`question response: rpcId=${rpcId} session=${sessionId} action=${cancel ? 'cancel' : 'answer'} accepted=${accepted}`)
+      return {
+        kind: 'question-response',
+        rpcId,
+        sessionId,
+        action: cancel ? 'cancel' : 'answer',
+        accepted,
+        ...(!accepted ? { reason: 'not-pending' } : {}),
       }
     }
 
@@ -2098,30 +2143,22 @@ const plugin = {
       }
 
       const pending = pendingApprovals.get(rpcId)
-      if (pending && (pending.sessionId !== sessionId || pending.approvalId !== approvalId)) {
+      if (!pending) {
+        return { kind: 'approval-response', rpcId, sessionId, approvalId, outcome, accepted: false, reason: 'not-pending' }
+      }
+      if (pending.sessionId !== sessionId || pending.approvalId !== approvalId) {
         return { kind: 'error', code: 'bad-request', message: 'approval-response does not match the pending approval', requestType: msg.type, sessionId }
       }
-
-      try {
-        const receipt = await api.respond({
-          type: 'client-response',
-          rpcId,
-          result: { ok: true, value: { sessionId, approvalId, outcome } },
-        })
-        log(`approval response: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} outcome=${outcome} accepted=${receipt.accepted}${receipt.accepted ? '' : ` reason=${receipt.reason}`}`)
-        return {
-          kind: 'approval-response',
-          rpcId,
-          sessionId,
-          approvalId,
-          outcome,
-          accepted: receipt.accepted,
-          ...(!receipt.accepted ? { reason: receipt.reason } : {}),
-        }
-      } catch (error) {
-        const message = error && error.message ? error.message : String(error)
-        log(`approval response failed: rpcId=${rpcId} ${message}`)
-        return { kind: 'error', code: 'internal', message, requestType: msg.type, sessionId }
+      const accepted = completeApproval(pending, outcome)
+      log(`approval response: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} outcome=${outcome} accepted=${accepted}`)
+      return {
+        kind: 'approval-response',
+        rpcId,
+        sessionId,
+        approvalId,
+        outcome,
+        accepted,
+        ...(!accepted ? { reason: 'not-pending' } : {}),
       }
     }
 
@@ -2357,7 +2394,7 @@ const plugin = {
                        msg.type === 'save-default-model' || msg.type === 'fork' || msg.type === 'providers' ||
                        msg.type === 'tasks' || msg.type === 'goal' || msg.type === 'goal-edit' ||
                        msg.type === 'goal-pause' || msg.type === 'goal-resume' || msg.type === 'goal-clear') {
-              handleQuery(api, typertGateway, agentDefaultModel, msg).then((frame) => {
+              handleQuery(api, host, agentDefaultModel, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
               })
             } else {
@@ -2368,6 +2405,7 @@ const plugin = {
           ws.on('close', () => {
             clients.delete(ws)
             if (ws.deviceId) registry.disconnected(ws.deviceId)
+            releaseUnclaimedInteractions()
             fileTransfers.closeClient(ws).catch((error) => {
               log(`file download cleanup failed: ${error && error.message ? error.message : String(error)}`)
             })
@@ -2456,104 +2494,114 @@ const plugin = {
     })
     log('session/event listener attached')
 
-    const interactionMuxTask = api.events && typeof api.events.mux === 'function' && typeof api.respond === 'function'
-      ? (async () => {
-          try {
-            for await (const envelope of api.events.mux(
-              { rpcId: crypto.randomUUID(), payload: {} },
-              interactionMuxAbort.signal,
-            )) {
-              const payload = envelope && envelope.payload
-              if (!payload || typeof payload.type !== 'string') continue
-              log(`interaction observed: type=${payload.type} hasRpc=${envelope.rpcId !== undefined} hasSession=${payload.sessionId !== undefined} hasApprovalId=${payload.approvalId !== undefined} hasToolName=${payload.toolName !== undefined}`)
-              if (payload.type === 'question/requested') {
-                const rpcId = String(envelope.rpcId)
-                const pending = {
-                  rpcId,
-                  sessionId: String(payload.sessionId),
-                  questions: payload.questions,
-                }
-                pendingQuestions.set(rpcId, pending)
-                broadcastInteractionFrame(questionFrameFor(rpcId, pending))
-                log(`question requested: rpcId=${rpcId} session=${pending.sessionId} questions=${Array.isArray(pending.questions) ? pending.questions.length : 0}`)
-              } else if (payload.type === 'approval/requested') {
-                const rpcId = String(envelope.rpcId)
-                const pending = {
-                  rpcId,
-                  sessionId: String(payload.sessionId),
-                  approvalId: String(payload.approvalId),
-                  toolName: payload.toolName,
-                  ...(payload.callId !== undefined ? { callId: payload.callId } : {}),
-                  ...(payload.reason !== undefined ? { reason: payload.reason } : {}),
-                }
-                pendingApprovals.set(rpcId, pending)
-                broadcastInteractionFrame(approvalFrameFor(rpcId, pending))
-                log(`approval requested: rpcId=${rpcId} approvalId=${pending.approvalId} session=${pending.sessionId} tool=${pending.toolName}`)
-              } else if (payload.type === 'question/resolved') {
-                const questionRpcId = String(payload.questionRpcId)
-                pendingQuestions.delete(questionRpcId)
-                broadcastInteractionFrame({
-                  kind: 'question-resolved',
-                  rpcId: questionRpcId,
-                  sessionId: String(payload.sessionId),
-                  outcome: payload.outcome,
-                })
-                log(`question resolved: rpcId=${questionRpcId} session=${payload.sessionId} outcome=${payload.outcome}`)
-              } else if (payload.type === 'approval/resolved') {
-                const approvalId = String(payload.approvalId)
-                const sessionId = String(payload.sessionId)
-                const entry = [...pendingApprovals.entries()].find(([, pending]) => pending.approvalId === approvalId && pending.sessionId === sessionId)
-                if (!entry) {
-                  log(`approval resolved without pending request: approvalId=${approvalId} session=${sessionId} outcome=${payload.outcome}`)
-                  continue
-                }
-                const [rpcId, pending] = entry
-                pendingApprovals.delete(rpcId)
-                broadcastInteractionFrame({
-                  kind: 'approval-resolved',
-                  rpcId,
-                  sessionId,
-                  approvalId,
-                  outcome: payload.outcome,
-                })
-                log(`approval resolved: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} outcome=${payload.outcome}`)
-              } else if (payload.type === 'session/projection' && (payload.key === 'todos' || payload.key === 'goal')) {
-                const sessionId = String(payload.sessionId)
-                const kind = payload.key === 'todos' ? 'tasks-updated' : 'goal-updated'
-                const valueKey = payload.key === 'todos' ? 'todos' : 'goal'
-                broadcastInteractionFrame({
-                  kind,
-                  sessionId,
-                  asOfSeq: payload.seq,
-                  [valueKey]: payload.value,
-                })
-                log(`projection forwarded: key=${payload.key} session=${sessionId} seq=${payload.seq}`)
-              } else {
-                log(`interaction ignored: type=${payload.type}`)
-              }
-            }
-          } catch (error) {
-            if (!interactionMuxAbort.signal.aborted) {
-              log(`interaction mux failed: ${error && error.message ? error.message : String(error)}`)
-            }
+    const disposeQuestions = ctx.on('user-questions/request', (request, next) => {
+      const sessionId = request?.agent?.id === undefined ? null : String(request.agent.id)
+      if (!sessionId || !Array.isArray(request.questions) || !hasInteractionClient(sessionId)) return next()
+      const rpcId = crypto.randomUUID()
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          const pending = pendingQuestions.get(rpcId)
+          if (pending) completeQuestion(pending, 'cancel', undefined, 'ASK_ABORTED')
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const pending = {
+          rpcId,
+          sessionId,
+          questions: request.questions,
+          next,
+          resolve,
+          reject,
+          cleanup: () => request.signal?.removeEventListener('abort', onAbort),
+        }
+        pendingQuestions.set(rpcId, pending)
+        broadcastInteractionFrame(questionFrameFor(rpcId, pending))
+        log(`question requested: rpcId=${rpcId} session=${sessionId} questions=${request.questions.length}`)
+      })
+    }, { prepend: true })
+
+    const disposeApprovals = ctx.on('approval/request', (request, next) => {
+      const sessionId = request?.agent?.id === undefined ? null : String(request.agent.id)
+      if (!sessionId || typeof request.toolName !== 'string' || !hasInteractionClient(sessionId)) return next()
+      const rpcId = crypto.randomUUID()
+      const approvalId = crypto.randomUUID()
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          const pending = pendingApprovals.get(rpcId)
+          if (pending) completeApproval(pending, 'cancelled')
+        }
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const pending = {
+          rpcId,
+          sessionId,
+          approvalId,
+          toolName: request.toolName,
+          ...(request.callId !== undefined ? { callId: request.callId } : {}),
+          ...(request.reason !== undefined ? { reason: request.reason } : {}),
+          next,
+          resolve,
+          reject,
+          cleanup: () => request.signal?.removeEventListener('abort', onAbort),
+        }
+        pendingApprovals.set(rpcId, pending)
+        broadcastInteractionFrame(approvalFrameFor(rpcId, pending))
+        log(`approval requested: rpcId=${rpcId} approvalId=${approvalId} session=${sessionId} tool=${request.toolName}`)
+      })
+    }, { prepend: true })
+
+    const projectionTask = (async () => {
+      while (!controlStreamAbort.signal.aborted) {
+        try {
+          const stream = await api.openControlStream(controlStreamAbort.signal)
+          for await (const frame of stream) {
+            if (frame?.type !== 'projection' || (frame.key !== 'todos' && frame.key !== 'goal')) continue
+            const sessionId = String(frame.sessionId)
+            const kind = frame.key === 'todos' ? 'tasks-updated' : 'goal-updated'
+            const valueKey = frame.key === 'todos' ? 'todos' : 'goal'
+            broadcastInteractionFrame({
+              kind,
+              sessionId,
+              asOfSeq: frame.seq,
+              [valueKey]: frame.value,
+            })
+            log(`projection forwarded: key=${frame.key} session=${sessionId} seq=${frame.seq}`)
           }
-        })()
-      : null
-    if (interactionMuxTask) log('api gateway interaction mux attached')
-    else log('api gateway interaction mux unavailable; human-in-the-loop disabled')
+          if (!controlStreamAbort.signal.aborted) log('session control stream ended; retrying')
+        } catch (error) {
+          if (!controlStreamAbort.signal.aborted) {
+            log(`session control stream failed; retrying: ${error && error.message ? error.message : String(error)}`)
+          }
+        }
+        if (controlStreamAbort.signal.aborted) break
+        await new Promise((resolve) => {
+          const onAbort = () => {
+            clearTimeout(timer)
+            resolve()
+          }
+          const timer = setTimeout(() => {
+            controlStreamAbort.signal.removeEventListener('abort', onAbort)
+            resolve()
+          }, 1_000)
+          controlStreamAbort.signal.addEventListener('abort', onAbort, { once: true })
+        })
+      }
+    })()
+    void projectionTask
+    log('Host waterfall interaction listeners and session control stream attached')
 
     ctx.effect(() => () => {
       if (waitTimer) clearTimeout(waitTimer)
       clearInterval(fileTransferExpiryTimer)
-      interactionMuxAbort.abort()
-      pendingQuestions.clear()
-      pendingApprovals.clear()
+      controlStreamAbort.abort()
+      for (const pending of [...pendingQuestions.values()]) fallbackQuestion(pending)
+      for (const pending of [...pendingApprovals.values()]) fallbackApproval(pending)
       fileTransfers.dispose().catch((error) => {
         log(`file download disposal failed: ${error && error.message ? error.message : String(error)}`)
       })
       disposeUpgrade()
       disposeMgmt()
       disposeEvents()
+      disposeQuestions()
+      disposeApprovals()
       if (lanServer) lanServer.close()
       for (const client of clients) client.terminate()
       clients.clear()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Secure mobile gateway for DeepSeek Harness with realtime sessions, tasks, goals, commands, approvals, and file transfers",
   "main": "lib/index.mjs",
   "files": [
@@ -26,7 +26,7 @@
   },
   "bin": "bin/setup-ip.mjs",
   "scripts": {
-    "test": "node test/setup-ip.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs"
+    "test": "node test/setup-ip.test.mjs && node test/host-adapter.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs"
   },
   "exports": {
     ".": "./lib/index.mjs",