dsh-plugin-mobile-gateway 0.6.4 → 0.6.8

package/PROTOCOL.md

@@ -1,6 +1,6 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.3）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.8）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -77,7 +77,7 @@ const pairingText = Buffer.from(JSON.stringify(payload), 'utf8').toString('base6
 ```json
 { "kind": "paired", "token": "<长期设备 token>",
   "device": { "id": "...", "name": "iPhone", "createdAt": 1787111700000 } }
-{ "kind": "hello", "protocol": 3, "capabilities": ["images"], "authenticated": true,
+{ "kind": "hello", "protocol": 3, "capabilities": ["images", "file-downloads"], "authenticated": true,
   "device": { "id": "...", "name": "iPhone" }, "port": 3080, "clients": 1 }
 ```
 
@@ -138,7 +138,7 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 | type | 参数 | 说明 |
 |---|---|---|
 | `ping` | — | 心跳；回复 `pong` |
-| `subscribe` | `sessionId` | 事件流过滤：之后只收到该会话的 `event`（不订阅 = 接收所有会话） |
+| `subscribe` | `sessionId` | 事件流过滤：之后只收到该会话的 `event`，并重放该会话仍待处理的提问与审批（不订阅 = 接收所有会话） |
 | `unsubscribe` | — | 取消过滤 |
 
 ```json
@@ -149,13 +149,26 @@ func connectAuthenticated(publicURL: URL, token: String) -> URLSessionWebSocketT
 → {"kind":"subscribed","sessionId":"session-abc"}
 ```
 
+`subscribed` 之后，服务端会紧接着发送该 Session 尚未处理的
+`question-requested` / `approval-requested`，并标记 `replay: true`。客户端必须按
+`rpcId` 去重。这保证移动端在审批产生后才打开已有 Session 时仍能显示待处理卡片。
+
 ---
 
-## 3. Human-in-the-loop 提问与回答
+## 3. Human-in-the-loop
+
+Human-in-the-loop 分为两条独立通道：
+
+- **提问**：Agent 的 `ask_user_question` 工具向用户收集答案。
+- **审批**：高风险工具操作（例如沙箱升权）请求一次性允许或拒绝。
+
+二者都是 API Gateway 的临时请求，不属于持久化的 `session/event`，且都必须以其原始 `rpcId` 通过专用响应帧回答，不能作为普通 `message` 发送。
 
-Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway 的 `events.mux()` 收到临时的待回答请求，并推送给移动端。该请求不属于持久化的 `session/event`；回答必须使用本节协议，不能作为普通 `message` 发送。
+### 3.1 提问与回答
 
-### `question-requested` — 服务端推送问题
+Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway 的 `events.mux()` 收到临时的待回答请求，并推送给移动端。
+
+#### `question-requested` — 服务端推送问题
 
 ```json
 {
@@ -187,7 +200,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 - `intent`：可选展示意图。目前可能为 `{ "kind":"plan-review", "approve":"批准选项标签" }`；未知 intent 应退化为普通选项列表。
 - `replay: true`：可选。表示这是移动端连接后重放的仍待回答问题。iOS 必须按 `rpcId` 去重。
 
-### `question-answer` — 移动端提交整批答案
+#### `question-answer` — 移动端提交整批答案
 
 ```json
 {
@@ -236,7 +249,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 
 答案结构不合法时 `reason` 为 `bad-response`。这两种情况均不能重发为普通聊天消息。
 
-### `question-cancel` — 跳过/取消整批问题
+#### `question-cancel` — 跳过/取消整批问题
 
 ```json
 { "type":"question-cancel", "rpcId":"5ce4f5d1-...", "sessionId":"session-abc" }
@@ -244,7 +257,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 
 回执仍为 `question-response`，其中 `action` 为 `cancel`。取消会让等待中的 `ask_user_question` 以 `ASK_CANCELLED` 结束，iOS 应在用户确认后再执行。
 
-### `question-resolved` — 服务端广播最终状态
+#### `question-resolved` — 服务端广播最终状态
 
 ```json
 { "kind":"question-resolved", "rpcId":"5ce4f5d1-...", "sessionId":"session-abc",
@@ -255,6 +268,72 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 
 ---
 
+### 3.2 操作审批
+
+当 DSH 的工具管线要求人工授权时，插件会从 API Gateway 收到一次 `approval/requested`。这正是 Web UI 中“等待审批”卡片对应的事件：`reason` 是面向用户的审批说明，`toolName` 标识请求操作的工具，`callId` 可用于与实时工具调用轨迹关联。
+
+#### `approval-requested` — 服务端推送待审批操作
+
+```json
+{
+  "kind": "approval-requested",
+  "rpcId": "approval-rpc-1",
+  "sessionId": "session-abc",
+  "approvalId": "approval-1",
+  "toolName": "bash",
+  "callId": "call-42",
+  "reason": "escalate sandbox to danger-full-access",
+  "replay": true
+}
+```
+
+- `rpcId`：本次可回答请求的稳定 RPC ID；提交决定时必须原样返回。
+- `approvalId`：审批审计 ID；同样必须原样返回，并用于将最终状态关联到本地审批卡片。
+- `toolName`：请求审批的工具名。
+- `callId` / `reason`：可选。前者可关联工具调用，后者应直接显示为待审批原因。
+- `replay: true`：表示当前仍未决定的审批在移动端连接或切换 Session 后重放。客户端应按 `rpcId` 去重。
+
+审批请求不含工具完整参数；移动端应将 `reason` 与可见的工具调用轨迹作为展示依据，不应自行推断或构造命令。
+
+#### `approval-response` — 移动端提交决定
+
+```json
+{
+  "type": "approval-response",
+  "rpcId": "approval-rpc-1",
+  "sessionId": "session-abc",
+  "approvalId": "approval-1",
+  "outcome": "allowed-once"
+}
+```
+
+`outcome` 只能是：
+
+- `allowed-once`：仅允许这一次请求的操作。
+- `rejected`：拒绝该操作。
+
+这是一次性决定；协议不支持“始终允许”。`cancelled` 与 `unavailable` 是宿主侧状态，移动端不得提交。请求的 `sessionId`、`approvalId` 与 `rpcId` 必须匹配同一待审批项。
+
+网关立即返回交付回执：
+
+```json
+{ "kind":"approval-response", "rpcId":"approval-rpc-1", "sessionId":"session-abc",
+  "approvalId":"approval-1", "outcome":"allowed-once", "accepted":true }
+```
+
+如果 Web UI 或另一台移动设备已经先作出决定，则回执为 `accepted:false`，并附带 `reason:"not-pending"`。收到错误帧或未被接受的回执时，客户端应保留当前状态，等待最终状态或重新打开事件流。
+
+#### `approval-resolved` — 服务端广播最终状态
+
+```json
+{ "kind":"approval-resolved", "rpcId":"approval-rpc-1", "sessionId":"session-abc",
+  "approvalId":"approval-1", "outcome":"allowed-once" }
+```
+
+`outcome` 为 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`。所有移动连接都会收到最终状态并关闭对应审批卡片。移动端断线重连后，API Gateway 会重放仍待决定的审批；已决审批不会重放。
+
+---
+
 ## 4. 消息（手机 → agent）
 
 ### `message` — 发送消息（会话不存在则创建）
@@ -322,6 +401,10 @@ let image = [
 | `sessions` | — | 会话列表（`updatedAt/running/blank/cwd/agentPreset`） |
 | `history` | `sessionId`, `beforeSeq?`, `maxMessages?`, `maxBytes?`, `view?` | 历史事件页（见下） |
 | `attachment` | `sessionId`, `attachmentId` | 读取历史中属于该会话的图片字节 |
+| `file-list` | `sessionId`, `path?`, `requestId?` | 列出会话工作目录内的一层文件与文件夹 |
+| `file-download-open` | `sessionId`, `path`, `requestId` | 打开一个工作目录内的普通文件下载 |
+| `file-download-read` | `transferId`, `offset` | 拉取下载的下一块字节 |
+| `file-download-cancel` | `transferId` | 取消并关闭下载 |
 | `search` | `query` | 会话全文搜索 |
 | `session-stats` | `sessionId` | 执行统计投影（输入框统计条数据源） |
 | `context-usage` | `sessionId` | token 用量 + 上下文占用投影 |
@@ -384,6 +467,46 @@ iOS 发现尚未缓存的 `attachmentId` 后发送：
 
 iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建议以 `attachmentId` 为缓存键。不要把 Base64 长期保存在对话模型对象里。并发同步历史时可限制为 2～4 个附件请求，优先加载当前可见消息。
 
+### 文件下载（图片、文档、IPA、APK 及其他普通文件）
+
+文件下载是独立于历史图片 `attachment` 的二进制传输通道。它不按扩展名做授权白名单：图片、PDF/Office 文档、`.ipa`、`.apk` 和其他**普通文件**均可下载；服务端仅根据扩展名给出 `mediaType`，以便移动端决定打开方式。
+
+所有 `path` 都是相对于该 `sessionId` 的 `cwd` 的相对路径，使用 `/` 分隔。例如先列出根目录：
+
+```json
+{ "type": "file-list", "requestId": "files-1", "sessionId": "session-abc" }
+→ {
+  "kind": "file-list", "requestId": "files-1", "sessionId": "session-abc", "path": ".",
+  "entries": [
+    { "name": "builds", "path": "builds", "kind": "directory" },
+    { "name": "app.ipa", "path": "app.ipa", "kind": "file", "bytes": 123456,
+      "modifiedAt": 1787111700000, "mediaType": "application/octet-stream" }
+  ]
+}
+```
+
+打开并按需拉取每一块：
+
+```json
+{ "type": "file-download-open", "requestId": "download-1", "sessionId": "session-abc", "path": "builds/app-release.apk" }
+→ { "kind": "file-download-opened", "requestId": "download-1", "transferId": "...",
+    "sessionId": "session-abc", "path": "builds/app-release.apk", "name": "app-release.apk",
+    "mediaType": "application/vnd.android.package-archive", "size": 2345678, "chunkBytes": 524288 }
+
+{ "type": "file-download-read", "transferId": "...", "offset": 0 }
+→ { "kind": "file-download-chunk", "transferId": "...", "offset": 0,
+    "data": "<标准 Base64>", "eof": false }
+
+{ "type": "file-download-read", "transferId": "...", "offset": 524288 }
+→ { "kind": "file-download-chunk", "transferId": "...", "offset": 524288,
+    "data": "<标准 Base64>", "eof": true, "sha256": "<64 位十六进制摘要>" }
+```
+
+- 客户端必须严格使用服务端返回块的 `offset + 已解码 data 字节数` 作为下一次 `offset`；当前版本不支持断线续传。请先写入临时文件，收到 `eof: true` 后校验整文件 SHA-256，再原子重命名为最终文件。
+- 每个 `transferId` 仅归属创建它的 WebSocket 连接。连接关闭、`file-download-cancel`、空闲 2 分钟、传完最后一块或插件卸载都会关闭文件句柄；取消成功返回 `{ "kind":"file-download-cancelled", "transferId":"..." }`。
+- 默认每块为 512 KiB、同时最多 4 个下载、单个文件最多 512 MiB。部署方可用 `fileDownloadChunkBytes`、`fileDownloadMaxTransfers`、`fileDownloadMaxBytes`、`fileDownloadIdleMs` 调整；`fileDownloadsEnabled: false` 会关闭该能力，且 `hello.capabilities` 不再包含 `file-downloads`。
+- 绝对路径、空路径（`file-download-open`）、`..` 路径段、NUL 字符、工作目录外的符号链接、目录和其他非普通文件都会被拒绝。`file-list` 不返回符号链接，避免客户端误认为其可下载。
+
 ### `session-stats` 详细（输入框统计条）
 ```json
 { "type": "session-stats", "sessionId": "session-abc" }
@@ -523,9 +646,10 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 | kind | 触发时机 |
 |---|---|
 | `paired` | 首次配对成功；仅此一次返回长期设备 token |
-| `hello` | 连接成功：`{ "kind":"hello", "protocol":3, "capabilities":["images"], "authenticated":true, "port":3080, "clients":1 }` |
+| `hello` | 连接成功：`{ "kind":"hello", "protocol":3, "capabilities":["images","file-downloads"], "authenticated":true, "port":3080, "clients":1 }` |
 | `event` | 任意会话的 agent 输出（见下） |
 | `question-requested` / `question-resolved` | Human-in-the-loop 问题请求与最终状态 |
+| `approval-requested` / `approval-resolved` | Human-in-the-loop 操作审批请求与最终状态 |
 | `pong` / `subscribed` / `sent` | 对应请求的回复 |
 
 ### `event` 帧（agent 实时输出）
@@ -566,6 +690,8 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 - 长期 token 只保存在 iOS Keychain；服务端磁盘仅保存摘要
 - `set-default` / `save-default-model` 是全局写操作，客户端 UI 应加确认
 - `question-answer` / `question-cancel` 会直接恢复或终止等待中的 Agent 工具调用；只允许经过鉴权的可信设备提交，并按 `rpcId` 防止重复操作
+- `approval-response` 会直接允许或拒绝等待中的高风险工具操作；只允许经过鉴权的可信设备提交，并按 `rpcId` 和 `approvalId` 防止串用或重复操作
+- 文件下载只允许读取该会话 `cwd` 内的普通文件；移动端必须在写入完成后校验最终块给出的 SHA-256，且不得把 `transferId` 视为可跨连接复用的凭证
 
 ---
 
@@ -589,8 +715,11 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 | v0.3.0 | 默认设备鉴权；一次性二维码配对；摘要化凭证存储；WebUI 设备面板；在线状态和即时吊销 |
 | v0.5.0 | Human-in-the-loop：转发 API Gateway question 请求、整批回答/取消、重连重放与多端状态收敛 |
 | v0.6.0 | DSH 0.1.1 图片：WebSocket Base64 上传、实时图片引用、历史附件按会话安全读取 |
-| v0.6.3 | macOS native picker 兼容：目录创建改用与目录浏览一致的宿主文件系统实现，并补齐路径、名称和错误码校验 |
 | v0.6.2 | 目录创建：通过 API Gateway `host.createDirectory` 在工作区目录下创建子文件夹 |
+| v0.6.3 | macOS native picker 兼容：目录创建改用与目录浏览一致的宿主文件系统实现，并补齐路径、名称和错误码校验 |
+| v0.6.6 | Human-in-the-loop 操作审批：转发 API Gateway approval 请求、一次性允许/拒绝、重连重放与多端最终状态收敛 |
+| v0.6.7 | 订阅已有 Session 时重放待处理 Human-in-the-loop 请求，并增加 Approval 端到端诊断日志与安装版本标记 |
+| v0.6.8 | 会话工作目录受限的文件列表与分块下载：支持图片、文档、IPA、APK 等普通文件，含连接归属、路径越界防护、取消、超时和 SHA-256 完整性校验 |
 
 ---
 

package/README.md

@@ -8,7 +8,7 @@
 
 - WebSocket：`/ws/mobile`
 - 局域网：`ws://<局域网 IP>:3081/ws/mobile`
-- 公网：`wss://<公网 IP>/ws/mobile`
+- Linux 服务器公网：`wss://<公网 IP>/ws/mobile`
 - 协议文档：[PROTOCOL.md](PROTOCOL.md)
 
 ## 配套 iOS 客户端
@@ -30,7 +30,7 @@
 
 ## 安装插件
 
-前提：已经安装 `dsh` CLI，并能正常启动 `dsh web`。
+前提：已经安装 `dsh` CLI 和 `pnpm`，并能正常启动 `dsh web`。可先执行 `pnpm --version` 确认当前用户的环境能够找到 `pnpm`。
 
 局域网使用只需安装插件：
 
@@ -38,7 +38,7 @@
 dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 ```
 
-需要公网接入时，推荐执行统一初始化命令。它会安装/更新插件，并请求一次 sudo 权限安装系统 Helper：
+需要在 Linux 服务器通过公网 IP 接入时，推荐执行统一初始化命令。它会安装/更新插件，并请求一次 sudo 权限安装系统 Helper：
 
 ```bash
 npx --yes dsh-plugin-mobile-gateway@latest init
@@ -68,35 +68,41 @@ dsh web
 
 如果系统防火墙拦截连接，只允许私有网络访问 TCP `3081`。不要把 3081 开放到公网。
 
-## 公网 IP 配对
+## Linux 服务器公网 IP 配对
 
-适用于带固定公网 IPv4 的 Ubuntu/Debian 服务器（其他发行版本可自行尝试）。Node.js 通过 nvm 安装时，也使用下面的命令。
+> [!NOTE]
+> 本文所说的“公网 IP 配对”特指 Linux 服务器。一键公网安装从 `v0.6.4` 开始提供，适用于带固定公网 IPv4 的 Ubuntu/Debian 服务器。服务器需要已经安装 Node.js、`pnpm` 和 `dsh` CLI；当前尚不支持 CentOS。
 
-### 1. 配置端口
+### 1. 准备公网端口
 
-从云厂商控制台复制服务器的公网 IPv4，并在安全组中放行入站 TCP `80` 和 `443`。
+在云厂商控制台复制服务器的公网 IPv4，并在安全组中放行入站 TCP `80` 和 `443`。不要将 DSH WebUI 端口或 TCP `3081` 开放到公网。
 
-不要开放 TCP `3080` 和 `3081`！！！
-不要开放 TCP `3080` 和 `3081`！！！
-不要开放 TCP `3080` 和 `3081`！！！
+### 2. 一键初始化
 
-### 2. 配置公网入口
+先确认普通 DSH 用户可以直接调用 `pnpm`：
 
-执行一次初始化（已经执行过可跳过）：
+```bash
+pnpm --version
+```
+
+然后使用同一个普通用户执行（不要使用 `root` 或 `sudo npx`）：
 
 ```bash
+npm_config_registry=https://registry.npmjs.org \
 npx --yes dsh-plugin-mobile-gateway@latest init
 ```
 
-然后启动或重新启动：
+该命令会安装或更新插件，并请求一次 sudo 权限安装 Nginx、Certbot、系统 Helper 和证书续期定时器。`init` 会确保 DSH profile 与 Helper 使用同一个精确版本。
+
+完成后启动或重新启动 WebUI：
 
 ```bash
 dsh web
 ```
 
-### 3. 打开远程 WebUI（使用端口转发，VSCode等IDE自带）
+### 3. 打开远程 WebUI
 
-如果 WebUI 运行在远程服务器，在自己的电脑执行：
+优先使用 VS Code、Cursor 等 IDE 自带的端口转发。也可以在自己的电脑执行：
 
 ```bash
 ssh -N -L <本地端口>:127.0.0.1:<DSH 实际端口> <服务器用户名>@<服务器公网 IP>
@@ -108,18 +114,67 @@ ssh -N -L <本地端口>:127.0.0.1:<DSH 实际端口> <服务器用户名>@<服
 http://127.0.0.1:<本地端口>
 ```
 
-### 4. 使用 WebUI 配对
+### 4. 在 UI 配置公网入口
+
+打开左侧的“移动设备”，在“公网接入”填写云厂商控制台提供的公网 IPv4，然后点击“配置公网接入”或“更新公网配置”。Helper 会自动读取当前 `dsh web` 端口并配置 Nginx、TLS 证书和 `wss://<公网 IP>/ws/mobile`。
+
+<p align="center">
+  <img src="docs/assets/public-access-ui.png" alt="在移动设备面板配置公网接入" width="420">
+</p>
+
+### 5. 配对移动设备
 
-1. 打开“移动设备”，在“公网接入”中填写云厂商控制台提供的公网 IPv4。
-2. 点击“配置公网接入”。Helper 会自动使用当前 `dsh web` 端口配置 Nginx 和证书。
-3. 开启“允许移动设备连接”，保持“设备鉴权”开启。
-4. 填写设备名称并点击“生成配对二维码”。
-5. iPhone 打开“设备认证”并扫描二维码。
-6. WebUI 的可信设备显示“在线”后即完成。
+1. 开启“允许移动设备连接”，保持“设备鉴权”开启。
+2. 填写设备名称并点击“生成配对二维码”。
+3. iPhone 打开“设备认证”并扫描二维码。
+4. WebUI 的可信设备显示“在线”后即完成。
 
 二维码只能使用一次，并会在 5 分钟后过期；超时后在 WebUI 重新生成即可。
 
-## 公网入口管理
+## Windows / macOS 家用电脑远程连接
+
+家用电脑通常没有固定公网 IP，不建议配置路由器端口转发。可以使用 Tailscale 长期连接，或使用 Cloudflare Quick Tunnel 临时调试。两种方式都转发到插件专用的 `3081` 端口，不会公开 DSH WebUI。
+
+使用前先启动 `dsh web`，并在“移动设备”面板开启“允许移动设备连接”和“设备鉴权”。
+
+### Tailscale（推荐长期使用）
+
+1. 在电脑和 iPhone 安装 [Tailscale](https://tailscale.com/download)，并登录同一个 Tailnet。
+2. 在 Windows PowerShell 或 macOS 终端执行：
+
+```bash
+tailscale serve --bg 3081
+```
+
+3. 执行 `tailscale serve status` 查看生成的 `https://<设备名>.<tailnet>.ts.net` 地址。
+4. 将地址改为 `wss://<设备名>.<tailnet>.ts.net/ws/mobile`，填入 WebUI 的“WebSocket 地址”，再生成二维码配对。
+
+Tailscale Serve 只允许同一 Tailnet 中符合访问规则的设备连接，并自动提供 HTTPS。可用 `tailscale serve reset` 停止转发。参见 [Tailscale Serve 文档](https://tailscale.com/docs/reference/tailscale-cli/serve)。
+
+### Cloudflare Quick Tunnel（仅临时调试）
+
+1. 安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/)。
+2. 在 Windows PowerShell 或 macOS 终端执行：
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:3081
+```
+
+3. 命令行会显示随机的 `https://<随机名称>.trycloudflare.com` 地址。
+4. 将地址改为 `wss://<随机名称>.trycloudflare.com/ws/mobile`，填入 WebUI 的“WebSocket 地址”，再生成二维码配对。
+
+保持该命令运行；停止命令后隧道立即失效。Quick Tunnel 的地址每次可能变化，且没有可用性保证，不适合正式或长期使用。公网调试时必须保持“设备鉴权”开启。参见 [Cloudflare Quick Tunnel 文档](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/)。
+
+## 网关配置方式总览
+
+| 使用场景 | 推荐入口 | iOS WebSocket 地址 | 需要的额外配置 | 端口与鉴权 |
+|---|---|---|---|---|
+| 同一局域网 | 插件局域网入口 | `ws://<电脑局域网 IP>:3081/ws/mobile` | 无需 Helper 或 Nginx；电脑与 iPhone 位于可互访的局域网 | 仅对私有网络放行 TCP `3081`；保持鉴权开启 |
+| 本机 iOS 模拟器 | DSH WebUI 本地入口 | `ws://127.0.0.1:<DSH WebUI 端口>/ws/mobile` | 无需 Helper、Nginx 或独立的 `3081` 端口 | 不开放任何外部端口；仅 Debug 时可关闭鉴权 |
+| Linux 公网服务器 | 插件 Helper + Nginx + TLS | `wss://<服务器公网 IPv4>/ws/mobile` | 执行 `init`，再从 WebUI 填写公网 IPv4 | 云安全组放行 TCP `80/443`；不要公开 DSH 端口和 `3081`；必须鉴权 |
+| 家用 Windows / macOS | Tailscale Serve；临时调试可用 Quick Tunnel | `wss://<Tailscale 域名>/ws/mobile` 或 `wss://<随机名称>.trycloudflare.com/ws/mobile` | 隧道转发到 `127.0.0.1:3081`，将生成的地址填入 WebUI | 无需路由器端口转发；保持鉴权开启 |
+
+## Linux 服务器公网入口管理
 
 查看状态：
 
@@ -162,8 +217,8 @@ sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest remove-helper
 | WebUI 没有“移动设备” | 确认安装在 `web` profile，并完整重启 `dsh web` |
 | iOS 收到 `503` | 回到 WebUI 开启“允许移动设备连接” |
 | iOS 收到 `401` | 在 WebUI 重新生成二维码并配对 |
-| 公网连接超时 | 检查云安全组、服务器防火墙和 TCP `80/443` |
-| 公网地址没有自动显示 | 确认已执行 `setup --ip <公网 IP>`，然后重启 `dsh web` |
+| Linux 服务器公网连接超时 | 检查云安全组、服务器防火墙和 TCP `80/443` |
+| Linux 服务器公网地址没有显示 | 在“移动设备 → 公网接入”填写公网 IPv4 并点击更新 |
 | 需要查看服务端日志 | 执行 `tail -f /tmp/mobile-gateway.log` |
 
 ## 源码开发

package/lib/index.mjs

@@ -33,6 +33,10 @@
 //                           view:"conversation" trims chunk/header events and tool output
 //                     { "type": "attachment", "sessionId", "attachmentId" }
 //                        -> verified image metadata + canonical base64 bytes
+//                     { "type": "file-list", "requestId"?, "sessionId", "path"? }
+//                     { "type": "file-download-open", "requestId", "sessionId", "path" }
+//                     { "type": "file-download-read", "transferId", "offset" }
+//                     { "type": "file-download-cancel", "transferId" }
 //                     { "type": "search", "query" }                -> session search
 //                     { "type": "host" }                           -> host.describe snapshot (incl. default provider/model)
 //                     { "type": "default-model" }                   -> agentDefaultModel.currentSelection()
@@ -54,18 +58,30 @@
 //                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
 //                     { "type": "question-answer", "rpcId", "sessionId", "answers": [...] }
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
-//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images"],
+//                     { "type": "approval-response", "rpcId", "sessionId", "approvalId",
+//                       "outcome": "allowed-once"|"rejected" }
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "file-downloads"],
 //                       "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
 //                     { "kind": "sent", "sessionId", "mode", "command"? }
 //                     { "kind": "workspaces" | "sessions" | "history" | "search", ...data }
 //                     { "kind": "attachment", "sessionId", "attachment", "data" }
+//                     { "kind": "file-list", "requestId"?, "sessionId", "path", "entries" }
+//                     { "kind": "file-download-opened", "requestId", "transferId", "sessionId",
+//                       "path", "name", "mediaType", "size", "chunkBytes" }
+//                     { "kind": "file-download-chunk", "transferId", "offset", "data", "eof", "sha256"? }
+//                     { "kind": "file-download-cancelled", "transferId" }
 //                     { "kind": "error", "code", "message", "requestType"?, "sessionId"? }
 //                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
 //                     { "kind": "question-requested", "rpcId", "sessionId", "questions", "replay"? }
 //                     { "kind": "question-response", "rpcId", "sessionId", "action", "accepted", "reason"? }
 //                     { "kind": "question-resolved", "rpcId", "sessionId", "outcome" }
+//                     { "kind": "approval-requested", "rpcId", "sessionId", "approvalId",
+//                       "toolName", "callId"?, "reason"?, "replay"? }
+//                     { "kind": "approval-response", "rpcId", "sessionId", "approvalId",
+//                       "outcome", "accepted", "reason"? }
+//                     { "kind": "approval-resolved", "rpcId", "sessionId", "approvalId", "outcome" }
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import http from 'node:http'
@@ -93,6 +109,11 @@ const HELPER_SOCKET = '/run/dsh-mobile-gateway/helper.sock'
 const DEFAULT_WS_PATH = '/ws/mobile'
 const DEFAULT_PAIRING_TTL_MS = 5 * 60 * 1000
 const DEFAULT_GATEWAY_WAIT_TIMEOUT_MS = 5 * 60 * 1000
+const DEFAULT_FILE_DOWNLOAD_MAX_BYTES = 512 * 1024 * 1024
+const DEFAULT_FILE_DOWNLOAD_CHUNK_BYTES = 512 * 1024
+const DEFAULT_FILE_DOWNLOAD_IDLE_MS = 2 * 60 * 1000
+const DEFAULT_FILE_DOWNLOAD_MAX_TRANSFERS = 4
+const INTERACTION_PROTOCOL_REVISION = 'question-approval-v2'
 // DSH 0.1.1 allows up to 100 MiB of decoded images in one prompt. Base64 plus
 // the JSON envelope needs roughly 4/3 of that on the wire. Keep this separately
 // configurable so deployments may choose a lower transport ceiling.
@@ -109,6 +130,11 @@ const Config = Schema.object({
   gatewayEnabled: Schema.boolean().default(false),
   gatewayWaitTimeoutMs: Schema.natural().min(30_000).max(30 * 60 * 1000).default(DEFAULT_GATEWAY_WAIT_TIMEOUT_MS),
   maxPayloadBytes: Schema.natural().min(1024 * 1024).max(160 * 1024 * 1024).default(DEFAULT_MAX_WS_PAYLOAD_BYTES),
+  fileDownloadsEnabled: Schema.boolean().default(true),
+  fileDownloadMaxBytes: Schema.natural().min(1024 * 1024).max(2 * 1024 * 1024 * 1024).default(DEFAULT_FILE_DOWNLOAD_MAX_BYTES),
+  fileDownloadChunkBytes: Schema.natural().min(64 * 1024).max(1024 * 1024).default(DEFAULT_FILE_DOWNLOAD_CHUNK_BYTES),
+  fileDownloadIdleMs: Schema.natural().min(10_000).max(30 * 60 * 1000).default(DEFAULT_FILE_DOWNLOAD_IDLE_MS),
+  fileDownloadMaxTransfers: Schema.natural().min(1).max(16).default(DEFAULT_FILE_DOWNLOAD_MAX_TRANSFERS),
   adminLoopbackOnly: Schema.boolean().default(true),
   publicUrl: Schema.string().default(''),
   deviceFile: Schema.string().default(''),
@@ -351,6 +377,320 @@ async function proxyQuery(api, type, method, payload, signal) {
   }
 }
 
+function fileTransferError(code, message, requestType, sessionId) {
+  return {
+    kind: 'error',
+    code,
+    message,
+    requestType,
+    ...(sessionId ? { sessionId } : {}),
+  }
+}
+
+function fileMediaType(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case '.apk': return 'application/vnd.android.package-archive'
+    case '.doc': return 'application/msword'
+    case '.docx': return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+    case '.ipa': return 'application/octet-stream'
+    case '.json': return 'application/json'
+    case '.pdf': return 'application/pdf'
+    case '.ppt': return 'application/vnd.ms-powerpoint'
+    case '.pptx': return 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+    case '.txt': return 'text/plain'
+    case '.xls': return 'application/vnd.ms-excel'
+    case '.xlsx': return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    case '.zip': return 'application/zip'
+    default: return 'application/octet-stream'
+  }
+}
+
+function workspaceRelativePath(root, target) {
+  const relative = path.relative(root, target)
+  return relative ? relative.split(path.sep).join('/') : '.'
+}
+
+function isInsideWorkspace(root, target) {
+  const relative = path.relative(root, target)
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+}
+
+function normalizedWorkspaceInput(value, { allowEmpty = false } = {}) {
+  if (value === undefined && allowEmpty) return '.'
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (!trimmed && allowEmpty) return '.'
+  if (!trimmed || trimmed.includes('\0') || path.isAbsolute(trimmed)) return null
+  if (trimmed.split(/[\\/]+/).includes('..')) return null
+  return trimmed
+}
+
+// Owns only workspace-scoped, regular-file downloads. The host API has an
+// image-only attachment read path, so arbitrary document/archive bytes must be
+// guarded here instead of accepting a host path from the mobile client.
+function createFileTransferManager(api, options) {
+  const transfers = new Map()
+
+  const closeTransfer = async (transferId) => {
+    const transfer = transfers.get(transferId)
+    if (!transfer) return false
+    transfers.delete(transferId)
+    try {
+      await transfer.handle.close()
+    } catch {
+      // A failed close cannot make a completed or cancelled transfer usable.
+    }
+    return true
+  }
+
+  const resolveSessionRoot = async (sessionId, requestType) => {
+    const sessions = await proxyQuery(api, requestType, api.sessions.list.bind(api.sessions), {})
+    if (sessions.kind === 'error') return sessions
+    const item = Array.isArray(sessions.items)
+      ? sessions.items.find((entry) => entry && String(entry.sessionId) === sessionId)
+      : null
+    if (!item) return fileTransferError('session-not-found', 'no such session', requestType, sessionId)
+    if (typeof item.cwd !== 'string' || !item.cwd.trim()) {
+      return fileTransferError('file-workspace-unavailable', 'the session has no working directory', requestType, sessionId)
+    }
+    try {
+      const root = await fsp.realpath(item.cwd)
+      const stat = await fsp.stat(root)
+      if (!stat.isDirectory()) {
+        return fileTransferError('file-workspace-unavailable', 'the session working directory is unavailable', requestType, sessionId)
+      }
+      return { root }
+    } catch {
+      return fileTransferError('file-workspace-unavailable', 'the session working directory is unavailable', requestType, sessionId)
+    }
+  }
+
+  const resolveWorkspaceTarget = async (sessionId, rawPath, requestType, inputOptions) => {
+    const requested = normalizedWorkspaceInput(rawPath, inputOptions)
+    if (!requested) {
+      return fileTransferError('bad-request', `${requestType} requires a relative workspace path`, requestType, sessionId)
+    }
+    const rootResult = await resolveSessionRoot(sessionId, requestType)
+    if (rootResult.kind === 'error') return rootResult
+    const candidate = path.resolve(rootResult.root, requested)
+    if (!isInsideWorkspace(rootResult.root, candidate)) {
+      return fileTransferError('file-not-allowed', 'path must stay inside the session working directory', requestType, sessionId)
+    }
+    try {
+      const target = await fsp.realpath(candidate)
+      if (!isInsideWorkspace(rootResult.root, target)) {
+        return fileTransferError('file-not-allowed', 'path must stay inside the session working directory', requestType, sessionId)
+      }
+      const stat = await fsp.stat(target)
+      return { root: rootResult.root, target, stat }
+    } catch (error) {
+      if (error && error.code === 'ENOENT') {
+        return fileTransferError('file-not-found', 'file does not exist', requestType, sessionId)
+      }
+      return fileTransferError('file-unreadable', 'file cannot be read', requestType, sessionId)
+    }
+  }
+
+  const fileList = async (msg) => {
+    const session = requireSessionId(msg)
+    if (session.error) return session.error
+    const resolved = await resolveWorkspaceTarget(session.value, msg.path, 'file-list', { allowEmpty: true })
+    if (resolved.kind === 'error') return resolved
+    if (!resolved.stat.isDirectory()) {
+      return fileTransferError('file-not-directory', 'path is not a directory', 'file-list', session.value)
+    }
+    try {
+      const dirents = await fsp.readdir(resolved.target, { withFileTypes: true })
+      const entries = []
+      for (const dirent of dirents) {
+        if (dirent.isSymbolicLink()) continue
+        const child = path.join(resolved.target, dirent.name)
+        if (dirent.isDirectory()) {
+          entries.push({ name: dirent.name, path: workspaceRelativePath(resolved.root, child), kind: 'directory' })
+        } else if (dirent.isFile()) {
+          const stat = await fsp.stat(child)
+          entries.push({
+            name: dirent.name,
+            path: workspaceRelativePath(resolved.root, child),
+            kind: 'file',
+            bytes: stat.size,
+            modifiedAt: stat.mtimeMs,
+            mediaType: fileMediaType(child),
+          })
+        }
+      }
+      entries.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === 'directory' ? -1 : 1))
+      const requestId = typeof msg.requestId === 'string' && msg.requestId.trim() ? msg.requestId.trim() : null
+      return {
+        kind: 'file-list',
+        ...(requestId ? { requestId } : {}),
+        sessionId: session.value,
+        path: workspaceRelativePath(resolved.root, resolved.target),
+        entries,
+      }
+    } catch {
+      return fileTransferError('file-unreadable', 'directory cannot be read', 'file-list', session.value)
+    }
+  }
+
+  const open = async (client, msg) => {
+    const requestId = typeof msg.requestId === 'string' && msg.requestId.trim() ? msg.requestId.trim() : null
+    const session = requireSessionId(msg)
+    if (!requestId) return fileTransferError('bad-request', 'file-download-open requires a requestId', 'file-download-open')
+    if (session.error) return session.error
+    if (transfers.size >= options.fileDownloadMaxTransfers) {
+      return fileTransferError('file-transfer-limit', 'too many active file downloads', 'file-download-open', session.value)
+    }
+    const resolved = await resolveWorkspaceTarget(session.value, msg.path, 'file-download-open')
+    if (resolved.kind === 'error') return resolved
+    if (!resolved.stat.isFile()) {
+      return fileTransferError('file-not-regular', 'only regular files can be downloaded', 'file-download-open', session.value)
+    }
+    if (resolved.stat.size > options.fileDownloadMaxBytes) {
+      return fileTransferError('file-too-large', 'file exceeds the configured download limit', 'file-download-open', session.value)
+    }
+
+    let handle
+    try {
+      // Reject a last-moment leaf symlink replacement after the realpath
+      // containment check above. macOS and Linux both support O_NOFOLLOW.
+      handle = await fsp.open(resolved.target, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
+      const opened = await handle.stat()
+      if (!opened.isFile() || opened.size !== resolved.stat.size) {
+        await handle.close()
+        return fileTransferError('file-changed', 'file changed before download could start', 'file-download-open', session.value)
+      }
+    } catch {
+      return fileTransferError('file-unreadable', 'file cannot be opened', 'file-download-open', session.value)
+    }
+
+    const transferId = crypto.randomUUID()
+    const transfer = {
+      client,
+      handle,
+      sessionId: session.value,
+      path: workspaceRelativePath(resolved.root, resolved.target),
+      name: path.basename(resolved.target),
+      mediaType: fileMediaType(resolved.target),
+      size: resolved.stat.size,
+      offset: 0,
+      hash: crypto.createHash('sha256'),
+      reading: false,
+      lastActiveAt: Date.now(),
+    }
+    transfers.set(transferId, transfer)
+    log(`file download opened: transfer=${transferId} session=${transfer.sessionId} bytes=${transfer.size}`)
+    return {
+      kind: 'file-download-opened',
+      requestId,
+      transferId,
+      sessionId: transfer.sessionId,
+      path: transfer.path,
+      name: transfer.name,
+      mediaType: transfer.mediaType,
+      size: transfer.size,
+      chunkBytes: options.fileDownloadChunkBytes,
+    }
+  }
+
+  const read = async (client, msg) => {
+    const transferId = typeof msg.transferId === 'string' && msg.transferId.trim() ? msg.transferId.trim() : null
+    if (!transferId) return fileTransferError('bad-request', 'file-download-read requires a transferId', 'file-download-read')
+    const transfer = transfers.get(transferId)
+    if (!transfer || transfer.client !== client) {
+      return fileTransferError('file-transfer-not-found', 'file download is no longer active', 'file-download-read')
+    }
+    if (!Number.isSafeInteger(msg.offset) || msg.offset !== transfer.offset) {
+      return fileTransferError('file-transfer-offset', 'offset must match the next unread byte', 'file-download-read', transfer.sessionId)
+    }
+    if (transfer.reading) {
+      return fileTransferError('file-transfer-busy', 'a chunk read is already in progress', 'file-download-read', transfer.sessionId)
+    }
+
+    transfer.reading = true
+    try {
+      const remaining = transfer.size - transfer.offset
+      const bytesToRead = Math.min(options.fileDownloadChunkBytes, remaining)
+      const chunk = Buffer.allocUnsafe(bytesToRead)
+      const { bytesRead } = bytesToRead === 0
+        ? { bytesRead: 0 }
+        : await transfer.handle.read(chunk, 0, bytesToRead, transfer.offset)
+      if (bytesRead !== bytesToRead) {
+        await closeTransfer(transferId)
+        return fileTransferError('file-changed', 'file changed during download', 'file-download-read', transfer.sessionId)
+      }
+      const payload = bytesRead === chunk.length ? chunk : chunk.subarray(0, bytesRead)
+      transfer.hash.update(payload)
+      const offset = transfer.offset
+      transfer.offset += bytesRead
+      transfer.lastActiveAt = Date.now()
+      const eof = transfer.offset === transfer.size
+      const frame = {
+        kind: 'file-download-chunk',
+        transferId,
+        offset,
+        data: payload.toString('base64'),
+        eof,
+      }
+      if (eof) {
+        frame.sha256 = transfer.hash.digest('hex')
+        await closeTransfer(transferId)
+        log(`file download completed: transfer=${transferId} bytes=${transfer.size}`)
+      }
+      return frame
+    } catch {
+      await closeTransfer(transferId)
+      return fileTransferError('file-unreadable', 'file cannot be read', 'file-download-read', transfer.sessionId)
+    } finally {
+      transfer.reading = false
+    }
+  }
+
+  const cancel = async (client, msg) => {
+    const transferId = typeof msg.transferId === 'string' && msg.transferId.trim() ? msg.transferId.trim() : null
+    if (!transferId) return fileTransferError('bad-request', 'file-download-cancel requires a transferId', 'file-download-cancel')
+    const transfer = transfers.get(transferId)
+    if (!transfer || transfer.client !== client) {
+      return fileTransferError('file-transfer-not-found', 'file download is no longer active', 'file-download-cancel')
+    }
+    await closeTransfer(transferId)
+    log(`file download cancelled: transfer=${transferId}`)
+    return { kind: 'file-download-cancelled', transferId }
+  }
+
+  const expire = async () => {
+    const cutoff = Date.now() - options.fileDownloadIdleMs
+    for (const [transferId, transfer] of transfers) {
+      if (transfer.lastActiveAt < cutoff && !transfer.reading) {
+        await closeTransfer(transferId)
+        log(`file download expired: transfer=${transferId}`)
+      }
+    }
+  }
+
+  return {
+    async handle(client, msg) {
+      if (!options.fileDownloadsEnabled) {
+        return fileTransferError('file-download-disabled', 'file downloads are disabled by gateway configuration', msg.type)
+      }
+      if (msg.type === 'file-list') return fileList(msg)
+      if (msg.type === 'file-download-open') return open(client, msg)
+      if (msg.type === 'file-download-read') return read(client, msg)
+      if (msg.type === 'file-download-cancel') return cancel(client, msg)
+      return null
+    },
+    async closeClient(client) {
+      for (const [transferId, transfer] of transfers) {
+        if (transfer.client === client) await closeTransfer(transferId)
+      }
+    },
+    async dispose() {
+      for (const transferId of [...transfers.keys()]) await closeTransfer(transferId)
+    },
+    expire,
+  }
+}
+
 // List one directory level directly with node:fs, mirroring the official
 // browse backend's semantics (crumbs + name-sorted child directories). Works
 // on every deployment regardless of the composed picker capability, which
@@ -689,7 +1029,9 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
       const execution = await typertGateway.invoke({
         namespace: 'commands',
         method: 'execute',
-        args: { agentId: sessionId.value, line: '/permission ' + name },
+        // commands/execute 的当前 Typert descriptor 要求 images 字段始终存在；
+        // 权限斜杠命令没有附件，因此显式传空数组。
+        args: { agentId: sessionId.value, line: '/permission ' + name, images: [] },
         signal: new AbortController().signal,
       })
       if (execution === undefined || execution === null) {
@@ -1013,6 +1355,11 @@ const plugin = {
       gatewayEnabled: false,
       gatewayWaitTimeoutMs: DEFAULT_GATEWAY_WAIT_TIMEOUT_MS,
       maxPayloadBytes: DEFAULT_MAX_WS_PAYLOAD_BYTES,
+      fileDownloadsEnabled: true,
+      fileDownloadMaxBytes: DEFAULT_FILE_DOWNLOAD_MAX_BYTES,
+      fileDownloadChunkBytes: DEFAULT_FILE_DOWNLOAD_CHUNK_BYTES,
+      fileDownloadIdleMs: DEFAULT_FILE_DOWNLOAD_IDLE_MS,
+      fileDownloadMaxTransfers: DEFAULT_FILE_DOWNLOAD_MAX_TRANSFERS,
       adminLoopbackOnly: true,
       publicUrl: '',
       deviceFile: '',
@@ -1050,7 +1397,14 @@ const plugin = {
     })
     const clients = new Set()
     const pendingQuestions = new Map()
-    const questionMuxAbort = new AbortController()
+    const pendingApprovals = new Map()
+    const fileTransfers = createFileTransferManager(api, options)
+    const fileTransferExpiryTimer = setInterval(() => {
+      fileTransfers.expire().catch((error) => {
+        log(`file download expiry failed: ${error && error.message ? error.message : String(error)}`)
+      })
+    }, Math.min(options.fileDownloadIdleMs, 30_000))
+    const interactionMuxAbort = new AbortController()
     let counter = 0
     let gatewayEnabled = options.gatewayEnabled === true
     let waitExpiresAt = null
@@ -1120,7 +1474,18 @@ const plugin = {
       ...(replay ? { replay: true } : {}),
     })
 
-    const broadcastQuestionFrame = (frame) => {
+    const approvalFrameFor = (rpcId, payload, replay = false) => ({
+      kind: 'approval-requested',
+      rpcId: String(rpcId),
+      sessionId: String(payload.sessionId),
+      approvalId: String(payload.approvalId),
+      toolName: payload.toolName,
+      ...(payload.callId !== undefined ? { callId: payload.callId } : {}),
+      ...(payload.reason !== undefined ? { reason: payload.reason } : {}),
+      ...(replay ? { replay: true } : {}),
+    })
+
+    const broadcastInteractionFrame = (frame) => {
       const wire = JSON.stringify(frame)
       for (const client of clients) {
         if (client.filterSessionId && client.filterSessionId !== frame.sessionId) continue
@@ -1128,6 +1493,23 @@ const plugin = {
       }
     }
 
+    const replayPendingInteractions = (ws, trigger) => {
+      let questionCount = 0
+      let approvalCount = 0
+      for (const pending of pendingQuestions.values()) {
+        if (ws.filterSessionId && ws.filterSessionId !== pending.sessionId) continue
+        ws.send(JSON.stringify(questionFrameFor(pending.rpcId, pending, true)))
+        questionCount += 1
+      }
+      for (const pending of pendingApprovals.values()) {
+        if (ws.filterSessionId && ws.filterSessionId !== pending.sessionId) continue
+        ws.send(JSON.stringify(approvalFrameFor(pending.rpcId, pending, true)))
+        approvalCount += 1
+      }
+      log(`interaction replay: trigger=${trigger} filtered=${Boolean(ws.filterSessionId)} questions=${questionCount} approvals=${approvalCount}`)
+      return { questionCount, approvalCount }
+    }
+
     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
@@ -1178,9 +1560,54 @@ const plugin = {
       }
     }
 
-    if (gatewayEnabled) setGatewayEnabled(true, 'enabled by startup config')
+    const respondToApproval = async (msg) => {
+      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
+      const approvalId = typeof msg.approvalId === 'string' && msg.approvalId.trim() ? msg.approvalId.trim() : null
+      const outcome = msg.outcome
+      if (!rpcId || !sessionId || !approvalId) {
+        return { kind: 'error', code: 'bad-request', message: 'approval-response requires rpcId, sessionId, and approvalId', requestType: msg.type }
+      }
+      if (outcome !== 'allowed-once' && outcome !== 'rejected') {
+        return { kind: 'error', code: 'bad-request', message: 'approval-response outcome must be "allowed-once" or "rejected"', requestType: msg.type, sessionId }
+      }
 
-    log(`applying: path=${wsPath}, webServer.port=${webServer.port}, gatewayEnabled=${gatewayEnabled}, requireAuth=${requireAuth}, devices=${registry.count()}`)
+      const pending = pendingApprovals.get(rpcId)
+      if (pending && (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 }
+      }
+    }
+
+    // Startup-config enablement (gatewayEnabled: true in cordis.patch.yml) is a
+    // standing-service decision made by the operator: do NOT arm the no-device
+    // auto-close. That safety net stays attached to the ephemeral panel toggle,
+    // where it belongs. gatewayEnabled is already true from options at this point,
+    // so nothing else is needed here beyond the log line.
+    if (gatewayEnabled) log('mobile gateway enabled by startup config: standing mode, no auto-close timer')
+
+    log(`applying: version=${PLUGIN_VERSION} interactionProtocol=${INTERACTION_PROTOCOL_REVISION} path=${wsPath}, webServer.port=${webServer.port}, gatewayEnabled=${gatewayEnabled}, requireAuth=${requireAuth}, devices=${registry.count()}`)
 
     // ---- device management routes (loopback-gated admin surface) ----
     const disposeMgmt = webServer.register({
@@ -1374,6 +1801,7 @@ const plugin = {
             } else if (msg.type === 'subscribe') {
               ws.filterSessionId = typeof msg.sessionId === 'string' ? msg.sessionId : undefined
               ws.send(JSON.stringify({ kind: 'subscribed', sessionId: ws.filterSessionId || null }))
+              replayPendingInteractions(ws, 'subscribe')
             } else if (msg.type === 'unsubscribe') {
               ws.filterSessionId = undefined
               ws.send(JSON.stringify({ kind: 'subscribed', sessionId: null }))
@@ -1381,6 +1809,15 @@ const plugin = {
               respondToQuestion(msg, msg.type === 'question-cancel').then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
               })
+            } else if (msg.type === 'approval-response') {
+              respondToApproval(msg).then((frame) => {
+                if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
+              })
+            } else if (msg.type === 'file-list' || msg.type === 'file-download-open' ||
+                       msg.type === 'file-download-read' || msg.type === 'file-download-cancel') {
+              fileTransfers.handle(ws, msg).then((frame) => {
+                if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
+              })
             } else if (msg.type === 'message') {
               admitMessage(api, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
@@ -1403,6 +1840,9 @@ const plugin = {
           ws.on('close', () => {
             clients.delete(ws)
             if (ws.deviceId) registry.disconnected(ws.deviceId)
+            fileTransfers.closeClient(ws).catch((error) => {
+              log(`file download cleanup failed: ${error && error.message ? error.message : String(error)}`)
+            })
             log(`client disconnected (id=${id}, remaining=${clients.size})`)
           })
 
@@ -1417,16 +1857,13 @@ const plugin = {
           ws.send(JSON.stringify({
             kind: 'hello',
             protocol: 3,
-            capabilities: ['images'],
+            capabilities: ['images', ...(options.fileDownloadsEnabled ? ['file-downloads'] : [])],
             port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,
             ...(device ? { device: { id: device.id, name: device.name } } : {}),
           }))
-          for (const pending of pendingQuestions.values()) {
-            if (ws.filterSessionId && ws.filterSessionId !== pending.sessionId) continue
-            ws.send(JSON.stringify(questionFrameFor(pending.rpcId, pending, true)))
-          }
+          replayPendingInteractions(ws, 'connect')
         })
     }
 
@@ -1491,15 +1928,16 @@ const plugin = {
     })
     log('session/event listener attached')
 
-    const questionMuxTask = api.events && typeof api.events.mux === 'function' && typeof api.respond === 'function'
+    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: {} },
-              questionMuxAbort.signal,
+              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 = {
@@ -1508,34 +1946,72 @@ const plugin = {
                   questions: payload.questions,
                 }
                 pendingQuestions.set(rpcId, pending)
-                broadcastQuestionFrame(questionFrameFor(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)
-                broadcastQuestionFrame({
+                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 {
+                log(`interaction ignored: type=${payload.type}`)
               }
             }
           } catch (error) {
-            if (!questionMuxAbort.signal.aborted) {
-              log(`question mux failed: ${error && error.message ? error.message : String(error)}`)
+            if (!interactionMuxAbort.signal.aborted) {
+              log(`interaction mux failed: ${error && error.message ? error.message : String(error)}`)
             }
           }
         })()
       : null
-    if (questionMuxTask) log('api gateway question mux attached')
-    else log('api gateway question mux unavailable; human-in-the-loop disabled')
+    if (interactionMuxTask) log('api gateway interaction mux attached')
+    else log('api gateway interaction mux unavailable; human-in-the-loop disabled')
 
     ctx.effect(() => () => {
       if (waitTimer) clearTimeout(waitTimer)
-      questionMuxAbort.abort()
+      clearInterval(fileTransferExpiryTimer)
+      interactionMuxAbort.abort()
       pendingQuestions.clear()
+      pendingApprovals.clear()
+      fileTransfers.dispose().catch((error) => {
+        log(`file download disposal failed: ${error && error.message ? error.message : String(error)}`)
+      })
       disposeUpgrade()
       disposeMgmt()
       disposeEvents()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.6.4",
-  "description": "update readme",
+  "version": "0.6.8",
+  "description": "1.support permission requirement;\n2. support file transfer",
   "main": "lib/index.mjs",
   "files": [
     "bin",