dsh-plugin-mobile-gateway 0.6.5 → 0.6.9

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()
@@ -43,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
@@ -54,18 +62,38 @@
 //                     { "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", "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",
+//                       "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,12 +121,53 @@ 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.
 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
@@ -109,6 +178,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(''),
@@ -222,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':
@@ -234,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',
@@ -267,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' }
   }
@@ -351,6 +553,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
@@ -516,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') {
@@ -646,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
@@ -1015,6 +1789,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: '',
@@ -1052,7 +1831,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
@@ -1122,7 +1908,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
@@ -1130,6 +1927,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
@@ -1180,6 +1994,46 @@ const plugin = {
       }
     }
 
+    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 }
+      }
+
+      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,
@@ -1187,7 +2041,7 @@ const plugin = {
     // 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: path=${wsPath}, webServer.port=${webServer.port}, gatewayEnabled=${gatewayEnabled}, requireAuth=${requireAuth}, devices=${registry.count()}`)
+    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({
@@ -1381,6 +2235,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 }))
@@ -1388,13 +2243,23 @@ 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))
               })
             } 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' ||
@@ -1410,6 +2275,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})`)
           })
 
@@ -1424,16 +2292,13 @@ const plugin = {
           ws.send(JSON.stringify({
             kind: 'hello',
             protocol: 3,
-            capabilities: ['images'],
+            capabilities: ['images', 'commands', ...(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')
         })
     }
 
@@ -1498,15 +2363,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 = {
@@ -1515,34 +2381,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()