dsh-plugin-mobile-gateway 0.6.8 → 0.6.9

package/PROTOCOL.md

@@ -1,6 +1,6 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.8）。
+移动端通过一个经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.6.9）。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -343,10 +343,148 @@ Agent 调用 DSH 的 `ask_user_question` 工具时，插件通过 API Gateway
 ```
 - `sessionId`：可选。省略时**自动创建新会话**（可用 `workspaceId` 或 `cwd` 指定归属工作区，至多一个，workspaceId 优先）
 - `mode`：`"queue"`（排队，默认）/ `"steer"`（打断当前回合）
-- `text` 以 `/` 开头会被当作**斜杠命令**（如 `/permission ask`），宿主直接执行、**绝不发给模型**
+- `message` 始终是用户 Prompt，Gateway 不会猜测或拦截其中的 `/...`。Host 命令必须使用下文的 `command-execute`；技能（如 `/android-cli 连接设备`）仍作为 `message` 发送，Host 会在 pre-step 阶段注入技能内容。
 - `text` 与 `images` 至少提供一项；因此支持纯图片消息
 - `clientTimeZone`：可选 IANA 时区，例如 `Asia/Shanghai`，宿主会校验后记录到这条用户消息
 
+### 输入菜单目录（命令 + 技能）
+
+目录按会话查询：Agent preset 会影响 Host 命令，会话工作目录会影响可用技能。客户端输入 `/` 后请求：
+
+```json
+{ "type": "commands", "sessionId": "session-abc", "locale": "zh-CN" }
+```
+
+```json
+→ {
+  "kind": "commands",
+  "sessionId": "session-abc",
+  "locale": "zh-CN",
+  "groups": [
+    {
+      "id": "commands",
+      "title": "命令",
+      "items": [
+        {
+          "id": "command:compact",
+          "name": "compact",
+          "description": "Compact older conversation history",
+          "source": "host",
+          "ui": {
+            "kind": "immediate",
+            "submitRequest": "command-execute",
+            "submitText": "/compact"
+          }
+        },
+        {
+          "id": "command:permission",
+          "name": "permission",
+          "description": "Switch the permission preset",
+          "source": "host",
+          "ui": {
+            "kind": "select",
+            "insertText": "/permission",
+            "optionsRequest": "command-options",
+            "selectionRequest": "command-select"
+          }
+        }
+      ]
+    },
+    {
+      "id": "skills",
+      "title": "技能",
+      "items": [
+        {
+          "id": "skill:android-cli",
+          "name": "android-cli",
+          "description": "Provides instructions for installing and using the Android CLI",
+          "source": "skill",
+          "action": "insert",
+          "modelInvocable": true,
+          "ui": {
+            "kind": "input",
+            "insertText": "/android-cli ",
+            "images": true,
+            "submitRequest": "message"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `groups` 是客户端的权威渲染结构；分组标题、顺序、条目和交互参数全部由服务端下发。
+- `locale` 可传 `zh-CN` 或英文 locale；服务端返回实际使用的 locale，并为已知命令下发 `ui.displayHint`。客户端优先显示 `displayHint`，缺失时回退到 Host 原始 `hint`。
+- 客户端只解释 `ui`，不按条目名写分支：`immediate` 将 `submitText` 通过 `submitRequest` 发送；`input` 插入 `insertText`、高亮首个 Token 并使用可选的 `displayHint/hint/images`；`select` 插入 `insertText` 并打开通用二级菜单。
+- `source: "host"` / `action: "execute"`：真实 DSH 斜杠命令，必须将 `/<name>` 或 `/<name> <args>` 通过 `command-execute.line` 提交，不得放入 `message.text`。
+- `source: "skill"`：条目来自 DSH `skill.list({sessionId})`。选中时仅按 `ui.insertText` 写入草稿，发送后 Host 会在 pre-step 阶段加载技能内容，不需要专用执行接口。`modelInvocable: false` 的用户专用技能也会被列出，其显示描述由服务端加上“仅用户”标记。
+- `model` 虽然是与官方 Web UI 一致的客户端命令，但选项加载与提交同样走下述通用接口，客户端不需要识别它的名字或模型协议。
+- Host 命令和技能各自保留原始顺序，`model` 客户端命令追加在命令组末尾。若未来 Host 自己注册 `model`，gateway 不会重复追加。
+- `hello.capabilities` 包含 `commands` 时表示服务端支持此目录接口。
+
+#### Host 命令执行
+
+`ui.submitRequest` 为 `command-execute` 时，客户端将完整命令行发送到专用接口：
+
+```json
+{ "type": "command-execute", "sessionId": "session-abc",
+  "line": "/compact", "images": [] }
+→ {
+  "kind": "command-executed",
+  "sessionId": "session-abc",
+  "line": "/compact",
+  "commandId": "command-123",
+  "result": { "kind": "success", "text": "Compacted 24 history items (~7230 tokens)." }
+}
+```
+
+带参数命令仍是 `command-execute`：
+
+```json
+{ "type": "command-execute", "sessionId": "session-abc",
+  "line": "/plan 帮我完成 Android 端适配", "images": [] }
+```
+
+- `line` 必须以 `/` 开头，参数作为同一字符串跟在命令后面。
+- 只有目录中 `ui.images: true` 的命令可携带图片；图片结构与 `message.images` 相同。Gateway 会再次校验。
+- `result.kind: "error"` 表示命令已进入 Host 但处理失败；客户端应保留当前草稿和图片供用户修改。
+- 命令不会生成 `user/message`，也不会进入模型 Prompt。Host 会持久化 `command/run` / `command/done`；`compact` 还会产生 `compaction/start` / `compaction/summary` / `compaction/end`。Gateway 会把这些事件实时转发，客户端据此渲染“正在压缩…”和最终结果。
+
+#### 通用二级菜单
+
+当 `ui.kind` 为 `select` 时，客户端使用 `ui.optionsRequest` 指定的请求类型加载标准化选项：
+
+```json
+{ "type": "command-options", "sessionId": "session-abc", "command": "permission" }
+→ {
+  "kind": "command-options",
+  "sessionId": "session-abc",
+  "command": "permission",
+  "options": [
+    { "id": "ask", "label": "Ask", "description": "Ask before risky operations", "selected": true },
+    { "id": "workspace-write", "label": "Workspace Write", "selected": false }
+  ]
+}
+```
+
+`id` 是服务端拥有的 opaque 值；客户端只负责原样回传。模型选项和权限选项使用完全相同的 `{id,label,detail?,description?,selected}` 结构。
+
+选择后使用 `ui.selectionRequest` 指定的请求类型提交：
+
+```json
+{ "type": "command-select", "sessionId": "session-abc",
+  "command": "permission", "optionId": "workspace-write" }
+→ {
+  "kind": "command-selected",
+  "sessionId": "session-abc",
+  "command": "permission",
+  "selected": { "id": "workspace-write", "label": "Workspace Write", "selected": true }
+}
+```
+
+客户端用 `selected.label/detail` 更新输入框状态栏。`model`、`permission` 的具体查询、校验和写入全部由服务端处理；现有 `models/select-model` 与 `permission-options/permission` 仅作为兼容接口保留。
+
 ### 发送图片
 
 iOS 将本地图片原始文件数据编码成**标准 Base64**，不要包含 `data:image/...;base64,` 前缀：
@@ -720,6 +858,7 @@ iOS 用 `Data(base64Encoded:)` 解码并按 `attachment.mediaType` 渲染，建
 | 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 完整性校验 |
+| v0.6.9 | 服务端驱动的命令与技能目录：支持本地化 Hint、通用二级选项、专用命令执行，以及 command/compaction 生命周期事件；Host 命令不再作为用户 Prompt 发送 |
 
 ---
 

package/README.md

@@ -4,7 +4,7 @@
 
 # dsh-plugin-mobile-gateway
 
-让 iPhone 通过经过设备鉴权的 WebSocket 连接 DeepSeek Harness。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
+DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
 
 - WebSocket：`/ws/mobile`
 - 局域网：`ws://<局域网 IP>:3081/ws/mobile`
@@ -13,7 +13,7 @@
 
 ## 配套 iOS 客户端
 
-[DeepSeek Harness Mobile](https://github.com/Clarklevis1995/dsh-mobile) 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、工作区内创建文件夹、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop、模型与权限设置。
+[DeepSeek Harness Mobile](https://github.com/Clarklevis1995/dsh-mobile) 是本仓库的兄弟项目。它是面向 iOS 17+ 的 SwiftUI 原生客户端，支持工作区与会话、工作区内创建文件夹、历史和实时对话、图片、Agent 执行轨迹、Human-in-the-loop，以及由网关配置驱动的命令、技能、模型与权限菜单。
 
 <table>
   <tr>

package/lib/index.mjs

@@ -47,6 +47,10 @@
 //                     { "type": "fork", "sessionId", "atSeq"? }    -> branch a new session from a completed turn
 //                     { "type": "models", "sessionId"? }           -> per-session catalog (with sessionId) or global (without)
 //                     { "type": "providers" }                       -> configurable provider list (live/dormant)
+//                     { "type": "commands", "sessionId" }          -> slash-command catalog for this session
+//                     { "type": "command-execute", "sessionId", "line", "images"? } -> execute a Host command
+//                     { "type": "command-options", "sessionId", "command" } -> normalized submenu options
+//                     { "type": "command-select", "sessionId", "command", "optionId" } -> apply submenu option
 //                     { "type": "select-model", "sessionId", "provider", "model", "reasoningEffort"? }
 //                     { "type": "permission-options", "sessionId"? } -> permission presets (+ session knobs)
 //                     { "type": "permission", "sessionId", "name" }  -> switch preset via /permission command
@@ -60,12 +64,20 @@
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
 //                     { "type": "approval-response", "rpcId", "sessionId", "approvalId",
 //                       "outcome": "allowed-once"|"rejected" }
-//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "file-downloads"],
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "file-downloads"],
 //                       "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
 //                     { "kind": "sent", "sessionId", "mode", "command"? }
 //                     { "kind": "workspaces" | "sessions" | "history" | "search", ...data }
+//                     { "kind": "commands", "sessionId", "groups": [
+//                       { "id", "title", "items": [{ "id", "name", "description", "ui" }] }
+//                     ] }
+//                     { "kind": "command-options", "sessionId", "command", "options": [
+//                       { "id", "label", "detail"?, "description"?, "selected" }
+//                     ] }
+//                     { "kind": "command-executed", "sessionId", "line", "commandId", "result" }
+//                     { "kind": "command-selected", "sessionId", "command", "selected" }
 //                     { "kind": "attachment", "sessionId", "attachment", "data" }
 //                     { "kind": "file-list", "requestId"?, "sessionId", "path", "entries" }
 //                     { "kind": "file-download-opened", "requestId", "transferId", "sessionId",
@@ -120,6 +132,42 @@ const INTERACTION_PROTOCOL_REVISION = 'question-approval-v2'
 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'])
+const COMMAND_UI_OVERRIDES = Object.freeze({
+  permission: Object.freeze({
+    kind: 'select',
+    optionsRequest: 'command-options',
+    selectionRequest: 'command-select',
+  }),
+  model: Object.freeze({
+    kind: 'select',
+    optionsRequest: 'command-options',
+    selectionRequest: 'command-select',
+  }),
+})
+const COMMAND_CATALOG_COPY = Object.freeze({
+  zh: Object.freeze({
+    locale: 'zh-CN',
+    commandsTitle: '命令',
+    skillsTitle: '技能',
+    userOnly: '仅用户',
+    modelDescription: '选择本会话使用的模型',
+    hints: Object.freeze({
+      plan: '描述你的任务以生成计划',
+      goal: '输入目标，智能体将持续执行',
+    }),
+  }),
+  en: Object.freeze({
+    locale: 'en',
+    commandsTitle: 'Commands',
+    skillsTitle: 'Skills',
+    userOnly: 'user-only',
+    modelDescription: 'Select the model for this conversation',
+    hints: Object.freeze({
+      plan: 'describe your task to generate plan',
+      goal: 'describe the objective for a long-running task',
+    }),
+  }),
+})
 
 // Cordis validates this schema at plugin load and fills these defaults. Keep
 // the defaults conservative: installing the bundle must never create an
@@ -248,6 +296,55 @@ function buildWireEvent(session, event) {
         },
       })
     }
+    case 'command/run':
+      return Object.assign(base, {
+        event: {
+          type: 'command/run',
+          commandId: d.commandId,
+          name: d.name,
+          ...(typeof d.args === 'string' ? { args: d.args } : {}),
+          ...(d.source ? { source: d.source } : {}),
+        },
+      })
+    case 'command/done':
+      return Object.assign(base, {
+        event: {
+          type: 'command/done',
+          commandId: d.commandId,
+          outcome: d.kind,
+          ...(typeof d.text === 'string' ? { text: d.text } : {}),
+          ...(typeof d.sourceEventSeq === 'number' ? { sourceEventSeq: d.sourceEventSeq } : {}),
+        },
+      })
+    case 'compaction/start':
+      return Object.assign(base, {
+        event: {
+          type: 'compaction/start',
+          compactionId: d.compactionId,
+          ...(d.sourceCommandId ? { sourceCommandId: d.sourceCommandId } : {}),
+          turn: d.turn ?? null,
+        },
+      })
+    case 'compaction/summary':
+      return Object.assign(base, {
+        event: {
+          type: 'compaction/summary',
+          compactionId: d.compactionId,
+          ...(d.sourceCommandId ? { sourceCommandId: d.sourceCommandId } : {}),
+          shadowedItemCount: Array.isArray(d.shadowedSeqs) ? d.shadowedSeqs.length : null,
+          shadowedTokenCount: typeof d.shadowedTokenCount === 'number' ? d.shadowedTokenCount : null,
+        },
+      })
+    case 'compaction/end':
+      return Object.assign(base, {
+        event: {
+          type: 'compaction/end',
+          compactionId: d.compactionId,
+          ...(d.sourceCommandId ? { sourceCommandId: d.sourceCommandId } : {}),
+          turn: d.turn ?? null,
+          ...(typeof d.error === 'string' ? { error: d.error } : {}),
+        },
+      })
     case 'turn/start':
     case 'turn/end':
     case 'step/start':
@@ -260,31 +357,28 @@ function buildWireEvent(session, event) {
   }
 }
 
-// Handle one mobile -> agent message through the official host API. Returns
-// 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() : ''
-  const images = msg.images === undefined ? [] : msg.images
+function parseWireImages(rawImages, requestType) {
+  const images = rawImages === undefined ? [] : rawImages
   if (!Array.isArray(images)) {
-    return { kind: 'error', code: 'bad-request', message: 'images must be an array' }
+    return { error: { kind: 'error', code: 'bad-request', message: 'images must be an array', requestType } }
   }
   if (images.length > 20) {
-    return { kind: 'error', code: 'bad-request', message: 'a message can contain at most 20 images' }
+    return { error: { kind: 'error', code: 'bad-request', message: 'a request can contain at most 20 images', requestType } }
   }
   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` }
+      return { error: { kind: 'error', code: 'bad-request', message: `images[${index}] must be an object`, requestType } }
     }
     if (!IMAGE_MEDIA_TYPES.has(image.mediaType)) {
-      return { kind: 'error', code: 'bad-request', message: `images[${index}].mediaType is unsupported` }
+      return { error: { kind: 'error', code: 'bad-request', message: `images[${index}].mediaType is unsupported`, requestType } }
     }
     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` }
+      return { error: { kind: 'error', code: 'bad-request', message: `images[${index}].data must be a non-empty base64 string`, requestType } }
     }
     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` }
+      return { error: { kind: 'error', code: 'bad-request', message: `images[${index}].name must be a string of at most 255 characters`, requestType } }
     }
     imageParts.push({
       type: 'image',
@@ -293,6 +387,88 @@ async function admitMessage(api, msg) {
       ...(image.name ? { name: image.name } : {}),
     })
   }
+  return { value: imageParts }
+}
+
+function commandNameOf(line) {
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('/')) return null
+  const end = trimmed.search(/\s/)
+  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,
+  })
+  if (!Array.isArray(listed)) throw new Error('commands/list returned an invalid catalog')
+  return listed
+}
+
+async function executeHostCommand(typertGateway, sessionId, line, images, requestType) {
+  try {
+    const execution = await typertGateway.invoke({
+      namespace: 'commands',
+      method: 'execute',
+      args: { agentId: sessionId, line, images },
+      signal: new AbortController().signal,
+    })
+    if (execution === undefined || execution === null) {
+      return { kind: 'error', code: 'unknown-command', message: `unknown or malformed command: ${line}`, requestType, sessionId }
+    }
+    log(`command executed: session=${sessionId} line=${JSON.stringify(line)} commandId=${execution.commandId} outcome=${execution.result.kind}`)
+    return {
+      kind: 'command-executed',
+      sessionId,
+      line,
+      commandId: execution.commandId,
+      result: execution.result,
+    }
+  } catch (error) {
+    const code = error && error.code ? error.code : 'internal'
+    const message = error && error.message ? error.message : String(error)
+    log(`command rejected: session=${sessionId} ${code}: ${message}`)
+    return { kind: 'error', code, message, requestType, sessionId }
+  }
+}
+
+async function admitCommand(typertGateway, msg) {
+  const sessionId = requireSessionId(msg)
+  if (sessionId.error) return sessionId.error
+  const line = typeof msg.line === 'string' ? msg.line.trim() : ''
+  const name = commandNameOf(line)
+  if (!name) {
+    return { kind: 'error', code: 'bad-request', message: 'command-execute requires a slash-prefixed line', requestType: 'command-execute', sessionId: sessionId.value }
+  }
+  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 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 }
+    }
+    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')
+  } catch (error) {
+    const code = error && error.code ? error.code : 'internal'
+    const message = error && error.message ? error.message : String(error)
+    return { kind: 'error', code, message, requestType: 'command-execute', sessionId: sessionId.value }
+  }
+}
+
+// Handle one mobile -> agent message through the official host API. Returns
+// 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() : ''
+  const parsedImages = parseWireImages(msg.images, 'message')
+  if (parsedImages.error) return parsedImages.error
+  const imageParts = parsedImages.value
   if (!text && imageParts.length === 0) {
     return { kind: 'error', code: 'bad-request', message: 'message requires non-empty text or at least one image' }
   }
@@ -856,6 +1032,171 @@ function capHistoryEvents(events, maxBytes, trim) {
   return { events: processed.slice(keptStart), bytes: total, dropped: keptStart }
 }
 
+function resolveCommandCatalogCopy(locale) {
+  return typeof locale === 'string' && !locale.toLowerCase().startsWith('zh')
+    ? COMMAND_CATALOG_COPY.en
+    : COMMAND_CATALOG_COPY.zh
+}
+
+function commandUiDescriptor(command, copy) {
+  const override = COMMAND_UI_OVERRIDES[command.name]
+  if (override) return { ...override, insertText: `/${command.name}` }
+  if (command.input && typeof command.input.hint === 'string') {
+    const displayHint = copy.hints[command.name]
+    return {
+      kind: 'input',
+      insertText: `/${command.name} `,
+      hint: command.input.hint,
+      ...(displayHint ? { displayHint } : {}),
+      images: command.input.images === true,
+      submitRequest: 'command-execute',
+    }
+  }
+  return { kind: 'immediate', submitRequest: 'command-execute', submitText: `/${command.name}` }
+}
+
+function skillUiDescriptor(skill) {
+  return {
+    kind: 'input',
+    insertText: `/${skill.name} `,
+    images: true,
+    submitRequest: 'message',
+  }
+}
+
+function modelCommandOptionId(provider, model) {
+  return Buffer.from(JSON.stringify([provider, model]), 'utf8').toString('base64url')
+}
+
+function decodeModelCommandOptionId(optionId) {
+  try {
+    const value = JSON.parse(Buffer.from(optionId, 'base64url').toString('utf8'))
+    if (!Array.isArray(value) || value.length !== 2 || value.some((part) => typeof part !== 'string' || part === '')) return null
+    return { provider: value[0], model: value[1] }
+  } catch {
+    return null
+  }
+}
+
+async function loadCommandOptions(api, command, sessionId) {
+  if (command === 'model') {
+    const frame = await proxyQuery(api, 'models', api.sessions.models.bind(api.sessions), { sessionId })
+    if (frame.kind !== 'models') return frame
+    const options = []
+    for (const group of frame.groups || []) {
+      for (const model of group.models || []) {
+        options.push({
+          id: modelCommandOptionId(String(group.id), String(model.id)),
+          label: String(model.name || model.id),
+          detail: String(group.name || group.id),
+          ...(model.description ? { description: String(model.description) } : {}),
+          selected: frame.current && frame.current.provider === group.id && frame.current.model === model.id,
+        })
+      }
+    }
+    return { kind: 'command-options', sessionId, command, options }
+  }
+
+  if (command === 'permission') {
+    const history = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), { sessionId })
+    if (history.kind !== 'history') return history
+    const permissions = history.projections && history.projections.values && history.projections.values.permissions
+    if (!permissions || !Array.isArray(permissions.options) || typeof permissions.currentValue !== 'string') {
+      return {
+        kind: 'error',
+        code: 'command-options-unavailable',
+        message: 'permission options are unavailable for this session',
+        requestType: 'command-options',
+        sessionId,
+      }
+    }
+    return {
+      kind: 'command-options',
+      sessionId,
+      command,
+      options: permissions.options.map((option) => ({
+        id: String(option.value),
+        label: String(option.name || option.value),
+        ...(option.description ? { description: String(option.description) } : {}),
+        selected: option.value === permissions.currentValue,
+      })),
+    }
+  }
+
+  return {
+    kind: 'error',
+    code: 'bad-request',
+    message: `command does not provide selectable options: ${command}`,
+    requestType: 'command-options',
+    sessionId,
+  }
+}
+
+async function selectCommandOption(api, typertGateway, 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)
+  if (!option) {
+    return {
+      kind: 'error',
+      code: 'bad-request',
+      message: `unknown option for ${command}: ${optionId}`,
+      requestType: 'command-select',
+      sessionId,
+    }
+  }
+
+  if (command === 'permission') {
+    try {
+      const execution = await typertGateway.invoke({
+        namespace: 'commands',
+        method: 'execute',
+        args: { agentId: sessionId, line: '/permission ' + optionId, images: [] },
+        signal: 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 }
+      }
+      return { kind: 'command-selected', sessionId, command, selected: { ...option, selected: true } }
+    } catch (error) {
+      const code = error && error.code ? error.code : 'internal'
+      const message = error && error.message ? error.message : String(error)
+      return { kind: 'error', code, message, requestType: 'command-select', sessionId }
+    }
+  }
+
+  if (command === 'model') {
+    const selection = decodeModelCommandOptionId(optionId)
+    if (!selection) {
+      return { kind: 'error', code: 'bad-request', message: 'invalid model option id', requestType: 'command-select', sessionId }
+    }
+    const models = await proxyQuery(api, 'models', api.sessions.models.bind(api.sessions), { sessionId })
+    if (models.kind !== 'models') return models
+    const group = (models.groups || []).find((candidate) => candidate.id === selection.provider)
+    const model = group && (group.models || []).find((candidate) => candidate.id === selection.model)
+    if (!model) {
+      return { kind: 'error', code: 'bad-request', message: 'model option is no longer available', requestType: 'command-select', sessionId }
+    }
+    const payload = { sessionId, ...selection }
+    const reasoningEffort = models.current && models.current.provider === selection.provider && models.current.model === selection.model
+      ? models.current.reasoningEffort
+      : model.reasoning && model.reasoning.defaultEffort
+    if (reasoningEffort) payload.reasoningEffort = reasoningEffort
+    const selected = await proxyQuery(api, 'select-model', api.sessions.selectModel.bind(api.sessions), payload)
+    if (selected.kind !== 'select-model') return selected
+    return {
+      kind: 'command-selected',
+      sessionId,
+      command,
+      selected: { ...option, selected: true },
+      value: selected.selected,
+    }
+  }
+
+  return { kind: 'error', code: 'bad-request', message: `command is not selectable: ${command}`, requestType: 'command-select', sessionId }
+}
+
 // Dispatch one mobile query frame; returns the wire frame to send back.
 async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
   if (msg.type === 'workspaces') {
@@ -986,6 +1327,99 @@ async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
   if (msg.type === 'providers') {
     return proxyQuery(api, 'providers', api.llm.providers.bind(api.llm), {})
   }
+  if (msg.type === 'command-execute') {
+    return admitCommand(typertGateway, msg)
+  }
+  if (msg.type === 'commands') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const copy = resolveCommandCatalogCopy(msg.locale)
+    try {
+      // This is the same session-scoped catalog used by the official Web UI.
+      // Copy only the stable descriptor fields so no live Typert object crosses
+      // 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),
+        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' }),
+      ])
+      if (!Array.isArray(listed)) throw new Error('commands/list returned an invalid catalog')
+      const commands = listed
+        .filter((command) => command && typeof command.name === 'string' && typeof command.description === 'string')
+        .map((command) => ({
+          id: `command:${command.name}`,
+          name: command.name,
+          description: command.description,
+          source: 'host',
+          action: 'execute',
+          ui: commandUiDescriptor(command, copy),
+          ...(command.input && typeof command.input.hint === 'string'
+            ? { input: { hint: command.input.hint, ...(command.input.images === true ? { images: true } : {}) } }
+            : {}),
+        }))
+      if (!commands.some((command) => command.name === 'model')) {
+        commands.push({
+          id: 'command:model',
+          name: 'model',
+          description: copy.modelDescription,
+          source: 'client',
+          action: 'select-model',
+          ui: commandUiDescriptor({ name: 'model' }, copy),
+        })
+      }
+      const skills = skillFrame.kind === 'skills' && Array.isArray(skillFrame.skills)
+        ? skillFrame.skills
+          .filter((skill) => skill && typeof skill.name === 'string' && typeof skill.description === 'string')
+          .map((skill) => ({
+            id: `skill:${skill.name}`,
+            name: skill.name,
+            description: skill.modelInvocable === true ? skill.description : `${copy.userOnly} · ${skill.description}`,
+            source: 'skill',
+            action: 'insert',
+            modelInvocable: skill.modelInvocable === true,
+            ...(typeof skill.whenToUse === 'string' && skill.whenToUse !== '' ? { whenToUse: skill.whenToUse } : {}),
+            ui: skillUiDescriptor(skill),
+          }))
+        : []
+      const groups = [
+        { id: 'commands', title: copy.commandsTitle, items: commands },
+        ...(skills.length > 0 ? [{ id: 'skills', title: copy.skillsTitle, items: skills }] : []),
+      ]
+      const warnings = skillFrame.kind === 'error'
+        ? [{ source: 'skills', code: skillFrame.code, message: skillFrame.message }]
+        : []
+      log(`command catalog queried: session=${sessionId.value} commands=${commands.length} skills=${skills.length}`)
+      return {
+        kind: 'commands',
+        sessionId: sessionId.value,
+        locale: copy.locale,
+        groups,
+        ...(warnings.length > 0 ? { warnings } : {}),
+      }
+    } catch (error) {
+      const code = error && error.code ? error.code : 'internal'
+      const message = error && error.message ? error.message : String(error)
+      log(`command catalog failed: session=${sessionId.value} ${code}: ${message}`)
+      return { kind: 'error', code, message, requestType: 'commands', sessionId: sessionId.value }
+    }
+  }
+  if (msg.type === 'command-options') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const command = typeof msg.command === 'string' && msg.command.trim() !== '' ? msg.command.trim() : null
+    if (!command) return { kind: 'error', code: 'bad-request', message: 'command-options requires a command', requestType: 'command-options', sessionId: sessionId.value }
+    return loadCommandOptions(api, command, sessionId.value)
+  }
+  if (msg.type === 'command-select') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    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)
+  }
   if (msg.type === 'select-model') {
     const sessionId = requireSessionId(msg)
     if (sessionId.error) return sessionId.error
@@ -1824,7 +2258,8 @@ const plugin = {
               })
             } 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 === 'directory-create' ||
-                       msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'select-model' ||
+                       msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'commands' || msg.type === 'command-execute' ||
+                       msg.type === 'command-options' || msg.type === 'command-select' || msg.type === 'select-model' ||
                        msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
                        msg.type === 'agent-presets' || msg.type === 'defaults' || msg.type === 'set-default' ||
                        msg.type === 'session-stats' || msg.type === 'default-model' ||
@@ -1857,7 +2292,7 @@ const plugin = {
           ws.send(JSON.stringify({
             kind: 'hello',
             protocol: 3,
-            capabilities: ['images', ...(options.fileDownloadsEnabled ? ['file-downloads'] : [])],
+            capabilities: ['images', 'commands', ...(options.fileDownloadsEnabled ? ['file-downloads'] : [])],
             port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.6.8",
-  "description": "1.support permission requirement;\n2. support file transfer",
+  "version": "0.6.9",
+  "description": "Authenticated mobile gateway for DeepSeek Harness with server-driven commands, skills, approvals, and file transfers",
   "main": "lib/index.mjs",
   "files": [
     "bin",