dsh-plugin-mobile-gateway 0.5.0 → 0.6.0

package/PROTOCOL.md

@@ -1,11 +1,11 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送消息、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.5.0）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.0）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
 - **公网端点**：必须由 TLS 反向代理提供 `wss://<域名>/ws/mobile`
-- **帧格式**：全部为 JSON 文本帧（UTF-8）
+- **帧格式**：全部为 JSON 文本帧（UTF-8）；图片字节使用标准 Base64
 - **连接即推送**：连上后服务端立刻发送一条 `hello`，之后 agent 输出以 `event` 帧实时推送
 
 ---
@@ -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": 2, "authenticated": true,
+{ "kind": "hello", "protocol": 3, "capabilities": ["images"], "authenticated": true,
   "device": { "id": "...", "name": "iPhone" }, "port": 3080, "clients": 1 }
 ```
 
@@ -265,6 +265,48 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 - `sessionId`：可选。省略时**自动创建新会话**（可用 `workspaceId` 或 `cwd` 指定归属工作区，至多一个，workspaceId 优先）
 - `mode`：`"queue"`（排队，默认）/ `"steer"`（打断当前回合）
 - `text` 以 `/` 开头会被当作**斜杠命令**（如 `/permission ask`），宿主直接执行、**绝不发给模型**
+- `text` 与 `images` 至少提供一项；因此支持纯图片消息
+- `clientTimeZone`：可选 IANA 时区，例如 `Asia/Shanghai`，宿主会校验后记录到这条用户消息
+
+### 发送图片
+
+iOS 将本地图片原始文件数据编码成**标准 Base64**，不要包含 `data:image/...;base64,` 前缀：
+
+```json
+{
+  "type": "message",
+  "sessionId": "session-abc",
+  "text": "请描述这两张图片",
+  "clientTimeZone": "Asia/Shanghai",
+  "images": [
+    {
+      "mediaType": "image/jpeg",
+      "data": "/9j/4AAQSkZJRgABAQ...",
+      "name": "IMG_1024.JPG"
+    },
+    {
+      "mediaType": "image/png",
+      "data": "iVBORw0KGgoAAA...",
+      "name": "diagram.png"
+    }
+  ]
+}
+```
+
+支持的 `mediaType`：`image/png`、`image/jpeg`、`image/webp`、`image/gif`。宿主会验证 Base64、文件签名、格式、尺寸、像素数、单图大小、图片数量和总大小；声明 MIME 与真实字节不一致会拒绝整条消息，且不会产生部分附件。
+
+当前 DSH 默认最多 20 张图片、单图约 3.5 MiB、单条消息图片总计 100 MiB，实际值以最近一次 `history.projections.values.imageLimits` 为准。WebSocket 单帧上限默认 144 MiB，用于容纳 100 MiB 图片经 Base64 后的 JSON 请求；反向代理也必须允许相应大小的 WebSocket 帧。
+
+Swift 编码示例：
+
+```swift
+let data = try Data(contentsOf: imageURL)
+let image = [
+    "mediaType": "image/jpeg",
+    "data": data.base64EncodedString(),
+    "name": imageURL.lastPathComponent
+]
+```
 
 ```json
 → { "kind": "sent", "sessionId": "session-abc", "mode": "queue" }
@@ -279,6 +321,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 |---|---|---|
 | `sessions` | — | 会话列表（`updatedAt/running/blank/cwd/agentPreset`） |
 | `history` | `sessionId`, `beforeSeq?`, `maxMessages?`, `maxBytes?`, `view?` | 历史事件页（见下） |
+| `attachment` | `sessionId`, `attachmentId` | 读取历史中属于该会话的图片字节 |
 | `search` | `query` | 会话全文搜索 |
 | `session-stats` | `sessionId` | 执行统计投影（输入框统计条数据源） |
 | `context-usage` | `sessionId` | token 用量 + 上下文占用投影 |
@@ -288,6 +331,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 { "type": "history", "sessionId": "session-abc", "maxMessages": 60, "maxBytes": 4194304, "view": "conversation" }
 ```
 - 返回**原始 SessionEvent**（`{type, seq, time, data}`，方案A），可选裁剪
+- 图片不会内联进历史页。`user/message.data.content[]` 中的图片块为 `{ "type":"image", "attachment": ImageAttachmentRef }`；iOS 使用其中的 `attachmentId` 请求图片数据
 - `maxBytes`：单帧字节预算，默认 **4 MiB**；超预算保留最新部分并给出 `nextBeforeSeq` 续页（客户端 16 MiB 上限的安全余量）
 - `view: "conversation"`：**对话裁剪模式**——丢弃 `assistant/chunk`（token 回放）与 `request/header`（system prompt），`tool/result` 嵌套文本截断到 2000 字符
 - 分页：`hasMore` 为真时用 `beforeSeq: nextBeforeSeq` 请求更早一页
@@ -298,6 +342,48 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
     "projections": { "asOfSeq": 127, "values": { "tokenUsage": {...}, "contextPressure": {...}, "permissions": {...}, "sessionStats": {...} } } }
 ```
 
+图片引用结构：
+
+```json
+{
+  "type": "image",
+  "attachment": {
+    "attachmentId": "sha256-opaque-id",
+    "mediaType": "image/jpeg",
+    "bytes": 184320,
+    "width": 1200,
+    "height": 900,
+    "name": "IMG_1024.JPG"
+  }
+}
+```
+
+iOS 发现尚未缓存的 `attachmentId` 后发送：
+
+```json
+{ "type":"attachment", "sessionId":"session-abc", "attachmentId":"sha256-opaque-id" }
+```
+
+服务端在确认该会话历史确实引用了这张图片后返回：
+
+```json
+{
+  "kind": "attachment",
+  "sessionId": "session-abc",
+  "attachment": {
+    "attachmentId": "sha256-opaque-id",
+    "mediaType": "image/jpeg",
+    "bytes": 184320,
+    "width": 1200,
+    "height": 900,
+    "name": "IMG_1024.JPG"
+  },
+  "data": "/9j/4AAQSkZJRgABAQ..."
+}
+```
+
+iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建议以 `attachmentId` 为缓存键。不要把 Base64 长期保存在对话模型对象里。并发同步历史时可限制为 2～4 个附件请求，优先加载当前可见消息。
+
 ### `session-stats` 详细（输入框统计条）
 ```json
 { "type": "session-stats", "sessionId": "session-abc" }
@@ -423,7 +509,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 | kind | 触发时机 |
 |---|---|
 | `paired` | 首次配对成功；仅此一次返回长期设备 token |
-| `hello` | 连接成功：`{ "kind":"hello", "protocol":2, "authenticated":true, "port":3080, "clients":1 }` |
+| `hello` | 连接成功：`{ "kind":"hello", "protocol":3, "capabilities":["images"], "authenticated":true, "port":3080, "clients":1 }` |
 | `event` | 任意会话的 agent 输出（见下） |
 | `question-requested` / `question-resolved` | Human-in-the-loop 问题请求与最终状态 |
 | `pong` / `subscribed` / `sent` | 对应请求的回复 |
@@ -434,7 +520,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
   "event": { "type": "assistant/chunk", "turn": 1, "step": 0, "chunkType": "text-delta", "text": "正在" } }
 ```
 `event.type` 覆盖（精炼字段）：
-- `user/message` → `{text, source}`
+- `user/message` → `{text, source, images?: ImageAttachmentRef[]}`
 - `assistant/chunk` → `{turn, step, chunkType: text-delta|reasoning-delta|tool-call-delta|usage|finish, text?/tool?/usage?/finish?}`
 - `assistant/message` → `{turn, step, text, reasoning, toolCalls[]}`
 - `tool/call` → `{turn, step, callId, name, arguments}`
@@ -487,6 +573,7 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 | v0.1.17 | models 支持无 sessionId 全局目录；新增 providers |
 | v0.3.0 | 默认设备鉴权；一次性二维码配对；摘要化凭证存储；WebUI 设备面板；在线状态和即时吊销 |
 | v0.5.0 | Human-in-the-loop：转发 API Gateway question 请求、整批回答/取消、重连重放与多端状态收敛 |
+| v0.6.0 | DSH 0.1.1 图片：WebSocket Base64 上传、实时图片引用、历史附件按会话安全读取 |
 
 ---
 

package/README.md

@@ -4,7 +4,7 @@
 
 # dsh-plugin-mobile-gateway
 
-为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供经过设备鉴权的持久化 WebSocket 网关，让 iOS 等移动客户端能够查看工作区和历史会话、接收 Agent 实时输出、处理 Human-in-the-loop 选择、发送任务，以及调整会话模型与权限。
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供经过设备鉴权的持久化 WebSocket 网关，让 iOS 等移动客户端能够查看工作区和历史会话、收发文字与图片、接收 Agent 实时输出、处理 Human-in-the-loop 选择，以及调整会话模型与权限。
 
 ![DeepSeek Harness 移动设备管理面板](docs/assets/mobile-device-management.png)
 
@@ -15,20 +15,22 @@
 
 ## 直接安装（推荐，无需下载源码）
 
+如果使用 nvm 安装 Node.js，并希望不打开 WebUI、直接从服务器终端生成 iOS 配对字符串，请参照[公网 IP 命令行配对指南](docs/public-ip-deployment-guide.md)。
+
 ### 1. 安装插件
 
 确保本机已经安装并能正常运行 DeepSeek Harness，然后执行：
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway
+dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
 ```
 
-这条命令会直接从 npm 获取插件、安装依赖，并将插件加入 `web` profile 的 bundle 列表。用户不需要 clone 仓库，也不需要运行 `pnpm install`。
+这条命令会在执行时从 npm 获取 `latest` 标签指向的最新插件、安装依赖，并将插件加入 `web` profile 的 bundle 列表。用户不需要 clone 仓库，也不需要运行 `pnpm install`。已经安装的插件不会后台自动升级；重新安装最新版本后需要重启 WebUI。
 
 如果希望固定版本，可以在包名后指定版本号：
 
 ```bash
-dsh plugin --profile web add dsh-plugin-mobile-gateway@0.5.0
+dsh plugin --profile web add dsh-plugin-mobile-gateway@0.6.0
 ```
 
 也可以不经过 npm，直接安装 GitHub 版本：
@@ -141,6 +143,7 @@ wss://gateway.example.com/ws/mobile
 - 浏览工作区、未分组会话和服务端目录
 - 创建工作区与新会话
 - 加载历史消息与轨迹
+- 从历史消息安全加载图片，并把 iOS 本地图片发送给 Agent
 - 实时接收思考、工具调用和最终回答
 - 向远端 Agent 发送任务
 - 查询或切换会话模型、推理等级和访问权限

package/docs/public-ip-deployment-guide.md

@@ -0,0 +1,135 @@
+# 公网 IP 命令行配对指南
+
+适用于通过 nvm 安装 Node.js、已经可以直接使用 `dsh` 命令的 Ubuntu/Debian 服务器。服务器端不需要打开 WebUI：终端会直接输出 iOS 所需的 Base64URL 配对字符串。
+
+## 1. 放行公网端口
+
+先在云安全组中放行 TCP `80` 和 `443`。不要开放 `3080`、`3081` 或 `/mgw/*`。
+
+如果服务器启用了 UFW：
+
+```bash
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+```
+
+## 2. 安装插件和辅助命令
+
+```bash
+dsh plugin --profile web add dsh-plugin-mobile-gateway@latest
+sudo apt-get update
+sudo apt-get install -y jq tmux
+```
+
+## 3. 配置公网 WSS
+
+获取服务器公网 IPv4：
+
+```bash
+PUBLIC_IP="$(curl -4 -fsS https://ifconfig.me)"
+printf 'Public IP: %s\n' "$PUBLIC_IP"
+```
+
+如果显示的不是服务器实际公网 IPv4，请手动执行 `PUBLIC_IP="实际公网IP"`。
+
+因为 Node.js 来自 nvm，运行安装器时需要把当前 `PATH` 传给 `sudo`：
+
+```bash
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest setup \
+  --ip "$PUBLIC_IP" \
+  --port 3080
+```
+
+安装成功后检查：
+
+```bash
+sudo env "PATH=$PATH" npx --yes dsh-plugin-mobile-gateway@latest status
+```
+
+应显示：
+
+```text
+wss://<公网IP>/ws/mobile
+```
+
+## 4. 启动 DSH
+
+```bash
+tmux new -s dsh
+dsh web
+```
+
+看到 `dsh web: http://127.0.0.1:3080` 后，按 `Ctrl+B`，再按 `D`，让 DSH 在后台继续运行。
+
+## 5. 在终端生成配对字符串
+
+重新读取公网地址，并明确开启设备鉴权和移动网关：
+
+```bash
+PUBLIC_IP="$(curl -4 -fsS https://ifconfig.me)"
+PUBLIC_URL="wss://$PUBLIC_IP/ws/mobile"
+
+curl -fsS -X POST http://127.0.0.1:3080/mgw/auth \
+  -H 'Content-Type: application/json' \
+  -d '{"enabled":true}'
+
+curl -fsS -X POST http://127.0.0.1:3080/mgw/gateway \
+  -H 'Content-Type: application/json' \
+  -d '{"enabled":true}'
+```
+
+生成一次性 Base64URL 配对字符串：
+
+```bash
+PAIRING_TEXT="$(
+  jq -nc --arg name 'iPhone' --arg url "$PUBLIC_URL" \
+    '{name:$name,publicUrl:$url}' \
+  | curl -fsS -X POST http://127.0.0.1:3080/mgw/pair \
+      -H 'Content-Type: application/json' \
+      --data-binary @- \
+  | jq -r '.qrPayload'
+)"
+
+if [ -z "$PAIRING_TEXT" ] || [ "$PAIRING_TEXT" = 'null' ]; then
+  echo '生成配对字符串失败，请检查 DSH 和插件日志'
+else
+  printf '\n复制下面这一整行到 iPhone：\n\n%s\n\n' "$PAIRING_TEXT"
+fi
+```
+
+配对字符串只能使用一次，并在 5 分钟后过期。如果超时，重新执行本节最后两段命令。
+
+## 6. 在 iPhone 完成绑定
+
+1. 打开 iOS 客户端的“设备认证”。
+2. 把终端输出的整行内容粘贴到“手动输入配对信息”。
+3. 点击“配对并连接”或“重新配对并连接”。
+4. 状态显示“已连接”后点击“完成”。
+
+iOS 会把长期设备凭证保存到 Keychain，之后启动时会自动重新连接，不需要再次执行配对。
+
+## 7. 检查结果
+
+服务器查看可信设备：
+
+```bash
+curl -fsS http://127.0.0.1:3080/mgw/devices | jq
+```
+
+查看插件日志：
+
+```bash
+tail -f /tmp/mobile-gateway.log
+```
+
+常见结果：
+
+- `503`：移动网关未开启，重新执行第 5 节的网关开启命令。
+- `401`：配对字符串过期、已使用或客户端凭证无效，重新生成配对字符串。
+- 公网连接超时：检查云安全组、UFW、Nginx，以及 TCP `80/443`。
+
+查看后台 DSH：
+
+```bash
+tmux attach -t dsh
+```

package/lib/index.mjs

@@ -18,8 +18,9 @@
 //   client -> server: { "type": "ping" }
 //                     { "type": "subscribe", "sessionId": "..." }  (optional filter)
 //                     { "type": "unsubscribe" }
-//                     { "type": "message", "sessionId"?, "text", "mode"?: "queue"|"steer",
-//                       "workspaceId"?, "cwd"? }
+//                     { "type": "message", "sessionId"?, "text"?, "images"?:
+//                       [{ "mediaType", "data", "name"? }], "mode"?: "queue"|"steer",
+//                       "workspaceId"?, "cwd"?, "clientTimeZone"? }
 //                        sessionId omitted -> a new session is created first; the
 //                        new session can be placed in a workspace via workspaceId
 //                        (or cwd; at most one, workspaceId wins)
@@ -30,6 +31,8 @@
 //                        -> raw SessionEvent page (scheme A), capped at maxBytes
 //                           (default 4 MiB); hasMore + nextBeforeSeq page backward;
 //                           view:"conversation" trims chunk/header events and tool output
+//                     { "type": "attachment", "sessionId", "attachmentId" }
+//                        -> verified image metadata + canonical base64 bytes
 //                     { "type": "search", "query" }                -> session search
 //                     { "type": "host" }                           -> host.describe snapshot (incl. default provider/model)
 //                     { "type": "default-model" }                   -> agentDefaultModel.currentSelection()
@@ -50,11 +53,13 @@
 //                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
 //                     { "type": "question-answer", "rpcId", "sessionId", "answers": [...] }
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
-//   server -> client: { "kind": "hello", "protocol": 2, "authenticated", "device"?, "port", "clients" }
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images"],
+//                       "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": "error", "code", "message", "requestType"?, "sessionId"? }
 //                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
 //                     { "kind": "question-requested", "rpcId", "sessionId", "questions", "replay"? }
@@ -85,7 +90,12 @@ const LOG_FILE = '/tmp/mobile-gateway.log'
 const DEFAULT_WS_PATH = '/ws/mobile'
 const DEFAULT_PAIRING_TTL_MS = 5 * 60 * 1000
 const DEFAULT_GATEWAY_WAIT_TIMEOUT_MS = 5 * 60 * 1000
+// 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.
+const DEFAULT_MAX_WS_PAYLOAD_BYTES = 144 * 1024 * 1024
 const MAX_MANAGEMENT_BODY_BYTES = 16 * 1024
+const IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif'])
 
 // Cordis validates this schema at plugin load and fills these defaults. Keep
 // the defaults conservative: installing the bundle must never create an
@@ -95,6 +105,7 @@ const Config = Schema.object({
   requireAuth: Schema.boolean().default(true),
   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),
   adminLoopbackOnly: Schema.boolean().default(true),
   publicUrl: Schema.string().default(''),
   deviceFile: Schema.string().default(''),
@@ -126,20 +137,40 @@ function textOf(blocks) {
   return text
 }
 
+function imagesOf(blocks) {
+  const images = []
+  for (const block of blocks) {
+    if (!block || block.type !== 'image' || !block.attachment) continue
+    const attachment = block.attachment
+    images.push({
+      attachmentId: attachment.attachmentId,
+      mediaType: attachment.mediaType,
+      bytes: attachment.bytes,
+      width: attachment.width,
+      height: attachment.height,
+      ...(attachment.name ? { name: attachment.name } : {}),
+    })
+  }
+  return images
+}
+
 // Build the small, owned JSON wire record for one session event. Reads only
 // leaf fields of the live SessionEvent — never serializes live objects.
 function buildWireEvent(session, event) {
-  const base = { sessionId: String(session.id), seq: event.seq, time: event.time }
+  const base = { kind: 'event', sessionId: String(session.id), seq: event.seq, time: event.time }
   const d = event.data || {}
   switch (event.type) {
-    case 'user/message':
+    case 'user/message': {
+      const images = imagesOf(d.content || [])
       return Object.assign(base, {
         event: {
           type: 'user/message',
           text: textOf(d.content || []),
           source: d.source && d.source.kind,
+          ...(images.length ? { images } : {}),
         },
       })
+    }
     case 'assistant/chunk': {
       const chunk = d.chunk || {}
       const ev = { type: 'assistant/chunk', turn: d.turn, step: d.step, chunkType: chunk.type }
@@ -154,6 +185,7 @@ function buildWireEvent(session, event) {
       let text = ''
       let reasoning = ''
       const toolCalls = []
+      const images = imagesOf(blocks)
       for (const block of blocks) {
         if (!block) continue
         if (block.type === 'text' && typeof block.text === 'string') text += block.text
@@ -161,7 +193,7 @@ function buildWireEvent(session, event) {
         else if (block.type === 'tool-call') toolCalls.push({ id: block.id, name: block.name, arguments: block.arguments })
       }
       return Object.assign(base, {
-        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls },
+        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls, ...(images.length ? { images } : {}) },
       })
     }
     case 'tool/call':
@@ -203,8 +235,37 @@ function buildWireEvent(session, event) {
 // the wire frame to send back, or null when nothing should be sent.
 async function admitMessage(api, msg) {
   const text = typeof msg.text === 'string' ? msg.text.trim() : ''
-  if (!text) {
-    return { kind: 'error', code: 'bad-request', message: 'text must be a non-empty string' }
+  const images = msg.images === undefined ? [] : msg.images
+  if (!Array.isArray(images)) {
+    return { kind: 'error', code: 'bad-request', message: 'images must be an array' }
+  }
+  if (images.length > 20) {
+    return { kind: 'error', code: 'bad-request', message: 'a message can contain at most 20 images' }
+  }
+  const imageParts = []
+  for (let index = 0; index < images.length; index++) {
+    const image = images[index]
+    if (!image || typeof image !== 'object') {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}] must be an object` }
+    }
+    if (!IMAGE_MEDIA_TYPES.has(image.mediaType)) {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}].mediaType is unsupported` }
+    }
+    if (typeof image.data !== 'string' || image.data.length === 0) {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}].data must be a non-empty base64 string` }
+    }
+    if (image.name !== undefined && (typeof image.name !== 'string' || image.name.length > 255)) {
+      return { kind: 'error', code: 'bad-request', message: `images[${index}].name must be a string of at most 255 characters` }
+    }
+    imageParts.push({
+      type: 'image',
+      mediaType: image.mediaType,
+      data: image.data,
+      ...(image.name ? { name: image.name } : {}),
+    })
+  }
+  if (!text && imageParts.length === 0) {
+    return { kind: 'error', code: 'bad-request', message: 'message requires non-empty text or at least one image' }
   }
   const mode = msg.mode === 'steer' ? 'steer' : 'queue'
 
@@ -231,10 +292,16 @@ async function admitMessage(api, msg) {
 
     const resp = await api.sessions.prompt({
       rpcId: crypto.randomUUID(),
-      payload: { sessionId, mode, content: [{ type: 'text', text }] },
+      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() } : {}),
+      },
     })
     if (resp.result.ok) {
-      log(`mobile message accepted: session=${sessionId} mode=${mode} text="${text.slice(0, 60)}"`)
+      log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
       return {
         kind: 'sent',
         sessionId,
@@ -438,6 +505,20 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
     }
     return frame
   }
+  if (msg.type === 'attachment') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const attachmentId = typeof msg.attachmentId === 'string' && msg.attachmentId.trim() !== '' ? msg.attachmentId.trim() : null
+    if (!attachmentId) {
+      return { kind: 'error', code: 'bad-request', message: 'attachment requires an attachmentId', requestType: 'attachment', sessionId: sessionId.value }
+    }
+    const frame = await proxyQuery(api, 'attachment', api.sessions.attachment.bind(api.sessions), {
+      sessionId: sessionId.value,
+      attachmentId,
+    })
+    if (frame.kind === 'attachment') frame.sessionId = sessionId.value
+    return frame
+  }
   if (msg.type === 'search') {
     const query = typeof msg.query === 'string' ? msg.query.trim() : ''
     if (!query) {
@@ -827,6 +908,7 @@ const plugin = {
       requireAuth: true,
       gatewayEnabled: false,
       gatewayWaitTimeoutMs: DEFAULT_GATEWAY_WAIT_TIMEOUT_MS,
+      maxPayloadBytes: DEFAULT_MAX_WS_PAYLOAD_BYTES,
       adminLoopbackOnly: true,
       publicUrl: '',
       deviceFile: '',
@@ -855,7 +937,7 @@ const plugin = {
     const registry = createRegistry(deviceFile, { pairingTtlMs: options.pairingTtlMs })
     const wss = new WebSocketServer({
       noServer: true,
-      maxPayload: 1024 * 1024,
+      maxPayload: options.maxPayloadBytes,
       // Authentication data may ride in requested subprotocols, but a secret
       // must never be echoed as the negotiated protocol.
       handleProtocols(protocols) {
@@ -1186,7 +1268,7 @@ const plugin = {
               admitMessage(api, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
               })
-            } else if (msg.type === 'workspaces' || msg.type === 'sessions' || msg.type === 'history' ||
+            } else if (msg.type === 'workspaces' || msg.type === 'sessions' || msg.type === 'history' || msg.type === 'attachment' ||
                        msg.type === 'search' || msg.type === 'host' || msg.type === 'directories' ||
                        msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'select-model' ||
                        msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
@@ -1217,7 +1299,8 @@ const plugin = {
           }
           ws.send(JSON.stringify({
             kind: 'hello',
-            protocol: 2,
+            protocol: 3,
+            capabilities: ['images'],
             port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Persistent WebSocket gateway for dsh: exposes /ws/mobile on the web server and forwards agent session output to connected mobile clients",
   "main": "lib/index.mjs",
   "files": [