dsh-plugin-mobile-gateway 0.8.1 → 0.10.0

package/lib/cloudflare-tunnel.mjs

@@ -4,6 +4,7 @@ import path from 'node:path'
 import crypto from 'node:crypto'
 import { spawn } from 'node:child_process'
 import { ensureCloudflared } from './cloudflared-binary.mjs'
+import { checkPublicEndpoint } from './public-endpoint-check.mjs'
 
 function hostnameOf(value) {
   if (typeof value !== 'string') throw new TypeError('Cloudflare hostname is required')
@@ -61,7 +62,7 @@ function writeState(file, value) {
 // Cloudflare can never reach the DSH WebUI or the /mgw management API through it.
 export function createCloudflareTunnel({ file, port = 3082, wsPath, executable = 'cloudflared',
   supported = true, isGatewayEnabled, onUpgrade, log = () => {}, spawnProcess = spawn,
-  prepareExecutable = ensureCloudflared }) {
+  prepareExecutable = ensureCloudflared, probeEndpoint = checkPublicEndpoint }) {
   let settings = supported ? readState(file) : { version: 1, enabled: false, mode: 'quick', hostname: '', token: '' }
   let server = null
   let child = null
@@ -73,6 +74,22 @@ export function createCloudflareTunnel({ file, port = 3082, wsPath, executable =
   let quickUrl = null
   let queue = Promise.resolve()
   const sockets = new Set()
+  let endpointHealth = { state: 'unchecked', message: '尚未检测公网 DNS、TLS 和 WebSocket 路由。' }
+  let healthGeneration = 0
+  let healthPending = null
+  const checkEndpoint = () => {
+    const endpoint = publicUrl()
+    if (!shouldRun() || !endpoint || phase !== 'online') return Promise.resolve(snapshot())
+    if (healthPending) return healthPending
+    const generation = healthGeneration
+    endpointHealth = { state: 'checking', message: '正在检测公网 DNS、TLS 和 WebSocket 路由…' }
+    const pending = Promise.resolve().then(() => probeEndpoint(endpoint)).catch(() => ({ state: 'network-error', message: '公网检测失败，请稍后重试。', checkedAt: new Date().toISOString() })).then((health) => {
+      if (generation === healthGeneration) endpointHealth = health
+      return snapshot()
+    }).finally(() => { if (healthPending === pending) healthPending = null })
+    healthPending = pending
+    return pending
+  }
 
   const shouldRun = () => supported && !disposed && settings.enabled && isGatewayEnabled()
   const publicUrl = () => settings.mode === 'quick'
@@ -88,9 +105,14 @@ export function createCloudflareTunnel({ file, port = 3082, wsPath, executable =
     port,
     state: !settings.enabled ? 'disabled' : !isGatewayEnabled() ? 'waiting-for-gateway' : phase,
     error,
+    endpointHealth,
+    publicReady: phase === 'online' && shouldRun() && endpointHealth.state === 'reachable',
   })
 
   const stop = async () => {
+    healthGeneration += 1
+    healthPending = null
+    endpointHealth = { state: 'unchecked', message: '尚未检测公网 DNS、TLS 和 WebSocket 路由。' }
     if (retryTimer) clearTimeout(retryTimer)
     retryTimer = null
     const previous = child
@@ -147,8 +169,10 @@ export function createCloudflareTunnel({ file, port = 3082, wsPath, executable =
               .replace(/eyJ[A-Za-z0-9._=-]+/g, '[redacted]').trim().slice(-500)
           }
           if (registered && (!quick || quickUrl)) {
+            const firstOnline = phase !== 'online'
             phase = 'online'
             error = null
+            if (firstOnline) void checkEndpoint()
           }
         }
         running.stderr?.on('data', onOutput)
@@ -156,6 +180,9 @@ export function createCloudflareTunnel({ file, port = 3082, wsPath, executable =
         const exited = (reason) => {
           if (child !== running) return
           child = null
+          healthGeneration += 1
+          healthPending = null
+          endpointHealth = { state: 'unchecked', message: '隧道已断开，需重新检测公网入口。' }
           quickUrl = null
           phase = 'error'
           error = reason || diagnostics || 'cloudflared exited unexpectedly'
@@ -263,6 +290,20 @@ export function createCloudflareTunnel({ file, port = 3082, wsPath, executable =
     return snapshot()
   }
 
+  const restart = () => {
+    queue = queue.catch(() => {}).then(async () => {
+      if (!shouldRun()) {
+        const cause = new Error('请先开启移动网关和 Cloudflare Tunnel')
+        cause.status = 409
+        throw cause
+      }
+      await stop()
+      await start()
+      return snapshot()
+    })
+    return queue
+  }
+
   const dispose = () => { disposed = true; void stop() }
-  return { snapshot, configure, reconcile, dispose }
+  return { snapshot, configure, reconcile, restart, checkEndpoint, dispose }
 }

package/lib/devices.js

@@ -99,9 +99,18 @@ function createRegistry(file, options = {}) {
 
   return {
     list() {
-      return devices
-        .filter((device) => !device.revokedAt)
-        .map((device) => publicDevice(device, online.get(device.id) || 0))
+      const active = devices.filter((device) => !device.revokedAt)
+      const counts = new Map()
+      const indices = new Map()
+      for (const device of active) counts.set(device.name, (counts.get(device.name) || 0) + 1)
+      return active.map((device) => {
+        const index = (indices.get(device.name) || 0) + 1
+        indices.set(device.name, index)
+        return {
+          ...publicDevice(device, online.get(device.id) || 0),
+          displayName: counts.get(device.name) > 1 ? `${device.name} (${index})` : device.name,
+        }
+      })
     },
 
     count() {
@@ -125,7 +134,7 @@ function createRegistry(file, options = {}) {
       return typeof code === 'string' && pairings.has(digest(code))
     },
 
-    claimPairing(code, clientDeviceId) {
+    claimPairing(code, clientDeviceId, clientDeviceName) {
       prunePairings()
       if (typeof code !== 'string' || code === '') return undefined
       const codeHash = digest(code)
@@ -143,13 +152,13 @@ function createRegistry(file, options = {}) {
         // A valid one-time pairing code authorizes credential rotation. Keep
         // the stable server-side device record while replacing its token, so
         // re-pairing one iOS installation never creates duplicate rows.
-        device.name = pairing.name
+        device.name = typeof clientDeviceName === 'string' && clientDeviceName.trim() ? clientDeviceName.trim().slice(0, 80) : '未命名设备'
         device.tokenHash = digest(token)
         device.clientDeviceId = normalizedClientDeviceId
       } else {
         device = {
           id: pairing.id,
-          name: pairing.name,
+          name: typeof clientDeviceName === 'string' && clientDeviceName.trim() ? clientDeviceName.trim().slice(0, 80) : '未命名设备',
           clientDeviceId: normalizedClientDeviceId,
           tokenHash: digest(token),
           createdAt: Date.now(),
@@ -162,7 +171,7 @@ function createRegistry(file, options = {}) {
       return { device: publicDevice(device, 0), token }
     },
 
-    authenticate(token, clientDeviceId) {
+    authenticate(token, clientDeviceId, clientDeviceName) {
       if (typeof token !== 'string' || token === '') return undefined
       const tokenHash = digest(token)
       const device = devices.find((candidate) => !candidate.revokedAt && safeEqualHex(candidate.tokenHash, tokenHash))
@@ -177,6 +186,13 @@ function createRegistry(file, options = {}) {
           save()
         }
       }
+      if (device && typeof clientDeviceName === 'string' && clientDeviceName.trim()) {
+        const name = clientDeviceName.trim().slice(0, 80)
+        if (device.name !== name) {
+          device.name = name
+          save()
+        }
+      }
       return device ? publicDevice(device, online.get(device.id) || 0) : undefined
     },
 

package/lib/dsh-host-adapter.mjs

@@ -13,7 +13,7 @@ function requireArray(value, endpoint) {
   return value
 }
 
-export const DSH_VERSION = '0.1.7-rc.2'
+export const DSH_VERSION = '0.2.0-rc.2'
 export const SESSION_FORMAT_VERSION = 4
 
 export function readHistoryRecords(records) {
@@ -247,12 +247,39 @@ export function createDshHostAdapter(typertGateway) {
     },
     settings: {
       describe: (_payload = {}, signal) => invoke('settings', 'describe', {}, signal),
+      mutate: (payload, signal) => invoke('settings', 'mutate', {
+        ns: payload.ns,
+        ops: payload.ops,
+        expectedRevision: payload.expectedRevision,
+      }, signal),
       update: (payload, signal) => invoke('settings', 'update', {
         ns: payload.ns,
         patch: payload.patch,
         ...(payload.expectedRevision === undefined ? {} : { expectedRevision: payload.expectedRevision }),
       }, signal),
     },
+    plugins: {
+      inventory: (_payload = {}, signal) => invoke('pluginInventory', 'list', {}, signal),
+      listBundles: (signal) => invoke('pluginManager', 'listBundles', {}, signal),
+      listPlugins: (signal) => invoke('pluginManager', 'listPlugins', {}, signal),
+      registries: (signal) => invoke('pluginManager', 'registries', {}, signal),
+      inspect: (spec, options, signal) => invoke('pluginManager', 'inspect', {
+        spec, ...(options === undefined ? {} : { options }),
+      }, signal),
+      installBundle: (spec, options) => invoke('pluginManager', 'installBundle', { spec, options }),
+      waitForInstall: (requestId) => invoke('pluginManager', 'waitForInstall', { requestId }),
+      cancelInstall: (requestId) => invoke('pluginManager', 'cancelInstall', { requestId }),
+      setBundleEnabled: (name, enabled) => invoke('pluginManager', 'setBundleEnabled', { name, enabled }),
+      setPluginEnabled: (id, enabled) => invoke('pluginManager', 'setPluginEnabled', { id, enabled }),
+      removeBundle: (name) => invoke('pluginManager', 'removeBundle', { name }),
+      listVersionExemptions: () => invoke('pluginManager', 'listVersionExemptions', {}),
+      setVersionExemption: (packageVersion, runtimeVersion, enabled, acceptRisk) => invoke(
+        'pluginManager', 'setVersionExemption', {
+          packageVersion, runtimeVersion, enabled,
+          ...(acceptRisk === undefined ? {} : { acceptRisk }),
+        },
+      ),
+    },
     permissionPresets: {
       catalog: (_payload = {}, signal) => invoke('permissionPresets', 'catalog', {}, signal),
     },

package/lib/gateway-probe.mjs

@@ -0,0 +1,6 @@
+// Echo only a strictly bounded, non-secret challenge on an unauthenticated
+// rejection. This does not authorize a device or expose management data.
+export function gatewayProbeHeader(value) {
+  return typeof value === 'string' && /^[a-f0-9]{32}$/.test(value)
+    ? `X-DSH-Gateway-Probe: ${value}\r\n` : ''
+}

package/lib/index.mjs

@@ -68,6 +68,8 @@ import { stringifyWireFrame } from './wire-json.mjs'
 //                     { "type": "goal", "sessionId" }                -> current goal projection
 //                     { "type": "goal-edit", "sessionId", "ref", "objective"?, "maxGoalRounds"? }
 //                     { "type": "goal-pause"|"goal-resume"|"goal-clear", "sessionId", "ref" }
+//                     { "type": "plugin-catalog"|"plugin-inspect"|"plugin-install"|"plugin-settings"|..., "requestId", ... }
+//                        -> paired control connection; see PROTOCOL.md section 18
 //                     { "type": "agent-presets" }                     -> preset roster (+ isDefault)
 //                     { "type": "defaults" }                          -> default agent preset + default permission
 //                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
@@ -75,7 +77,7 @@ import { stringifyWireFrame } from './wire-json.mjs'
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
 //                     { "type": "approval-response", "rpcId", "sessionId", "approvalId",
 //                       "outcome": "allowed-once"|"rejected" }
-//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "tasks", "goals", "session-cancel", "queue-control", "session-archive", "session-rename", "file-downloads"],
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "tasks", "goals", "plugin-management-v1", "session-cancel", "queue-control", "session-archive", "session-rename", "file-downloads"],
 //                       "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
@@ -130,9 +132,11 @@ import Schema from '@deepseek-ai/schemastery'
 import { WebSocketServer } from 'ws'
 import devicesModule from './devices.js'
 import { createDshHostAdapter, DSH_VERSION, SESSION_FORMAT_VERSION } from './dsh-host-adapter.mjs'
+import { handlePluginQuery, PLUGIN_REQUEST_TYPES } from './plugin-management.mjs'
 import { createSessionFollower } from './session-follower.mjs'
 import { createGatewayState, GATEWAY_MODES } from './gateway-state.mjs'
 import { createCloudflareTunnel } from './cloudflare-tunnel.mjs'
+import { gatewayProbeHeader } from './gateway-probe.mjs'
 import { webRestartAvailable, prepareWebRestart } from './gateway-tools.mjs'
 import QRCode from 'qrcode'
 
@@ -1335,7 +1339,8 @@ function parseAgentPreset(msg, requestType, required = false) {
 }
 
 // Dispatch one mobile query frame; returns the wire frame to send back.
-async function handleQuery(api, host, agentDefaultModel, msg) {
+async function handleQuery(api, host, agentDefaultModel, msg, pluginContext) {
+  if (PLUGIN_REQUEST_TYPES.has(msg.type)) return handlePluginQuery(api, msg, pluginContext)
   if (msg.type === 'session-agent-preset' || msg.type === 'select-agent-preset') {
     const session = requireSessionId(msg)
     const preset = parseAgentPreset(msg, msg.type, msg.type === 'select-agent-preset')
@@ -1934,9 +1939,16 @@ function extractClientDeviceId(req) {
   return /^[A-Za-z0-9._:-]{8,128}$/.test(normalized) ? normalized : undefined
 }
 
-function rejectUpgrade(socket, status, message) {
+function extractClientDeviceName(req) {
+  const value = req.headers['x-dsh-device-name']
+  if (typeof value !== 'string' || value.length > 512 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return undefined
+  const name = Buffer.from(value, 'base64').toString('utf8').trim()
+  return name && !/[\u0000-\u001f\u007f\ufffd]/.test(name) ? name.slice(0, 80) : undefined
+}
+
+function rejectUpgrade(socket, status, message, probe) {
   const reason = status === 401 ? 'Unauthorized' : status === 403 ? 'Forbidden' : status === 404 ? 'Not Found' : status === 503 ? 'Service Unavailable' : 'Bad Request'
-  socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}`)
+  socket.write(`HTTP/1.1 ${status} ${reason}\r\n${gatewayProbeHeader(probe)}Connection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}`)
   socket.destroy()
 }
 
@@ -2196,6 +2208,7 @@ const plugin = {
       },
     })
     const clients = new Set()
+    const pluginInstallOwners = new Map()
     const pendingQuestions = new Map()
     const pendingApprovals = new Map()
     const fileTransfers = createFileTransferManager(api, options)
@@ -2210,6 +2223,7 @@ const plugin = {
     let sessionProjectionBaselines = {}
     let counter = 0
     let gatewayMode = gatewayState.mode ?? options.gatewayMode ?? (options.gatewayEnabled === true ? 'persistent' : 'disabled')
+    const gatewayInstanceId = crypto.randomUUID()
     let gatewayEnabled = gatewayMode !== 'disabled'
     let waitExpiresAt = null
     let waitTimer = null
@@ -2638,6 +2652,7 @@ const plugin = {
               connectedClients: clients.size,
               webPort: webServer.port,
               webPid: process.pid,
+              gatewayInstanceId,
               wsPath,
               publicUrl: tunnel?.snapshot().enabled && tunnel.snapshot().mode === 'quick'
                 ? tunnel.snapshot().publicUrl
@@ -2722,6 +2737,12 @@ const plugin = {
             if (body.enabled && gatewayMode !== 'persistent') setGatewayMode('persistent', 'Cloudflare Tunnel enabled from management UI')
             await tunnel.reconcile()
             sendJson(res, 200, { ...tunnel.snapshot(), gatewayEnabled, gatewayMode })
+          } else if (req.method === 'POST' && p === '/mgw/cloudflare/check') {
+            await tunnel.checkEndpoint()
+            sendJson(res, 200, { ...tunnel.snapshot(), gatewayEnabled, gatewayMode })
+          } else if (req.method === 'POST' && p === '/mgw/cloudflare/restart') {
+            await tunnel.restart()
+            sendJson(res, 200, { ...tunnel.snapshot(), gatewayEnabled, gatewayMode })
           } else if (req.method === 'POST' && p === '/mgw/auth') {
             const body = await readBody(req)
             if (typeof body.enabled !== 'boolean') throw badRequest('enabled must be a boolean')
@@ -2746,10 +2767,9 @@ const plugin = {
               throw error
             }
             const body = await readBody(req)
-            const name = typeof body.name === 'string' ? body.name : undefined
             const publicUrl = normalizePublicUrl(body.publicUrl || configuredPublicUrl(), req, wsPath)
             const endpoints = advertisedEndpoints(publicUrl, normalizeEndpoints(body.endpoints ?? []))
-            const pairing = registry.createPairing(name)
+            const pairing = registry.createPairing()
             const payload = {
               version: 2,
               publicUrl,
@@ -2812,7 +2832,7 @@ const plugin = {
             rejectUpgrade(socket, 400, 'pairing requires X-DSH-Device-ID; update the iOS client')
             return
           }
-          paired = registry.claimPairing(credential.value, clientDeviceId)
+          paired = registry.claimPairing(credential.value, clientDeviceId, extractClientDeviceName(req))
           device = paired && paired.device
           if (!device) {
             log('pairing rejected: invalid, expired, or already-used code')
@@ -2820,7 +2840,7 @@ const plugin = {
             return
           }
         } else if (credential && credential.kind === 'token') {
-          device = registry.authenticate(credential.value, extractClientDeviceId(req))
+          device = registry.authenticate(credential.value, extractClientDeviceId(req), extractClientDeviceName(req))
         }
 
         // The separately exposed LAN listener is always authenticated. The
@@ -2829,7 +2849,7 @@ const plugin = {
         // plane.
         if ((requireAuth || transport.lan === true) && !device) {
           logAuthRejected(req)
-          rejectUpgrade(socket, 401, 'missing or invalid device credential')
+          rejectUpgrade(socket, 401, 'missing or invalid device credential', req.headers['x-dsh-gateway-probe'])
           return
         }
 
@@ -2944,8 +2964,23 @@ const plugin = {
                        msg.type === 'tasks' || msg.type === 'goal' || msg.type === 'goal-edit' ||
                        msg.type === 'goal-pause' || msg.type === 'goal-resume' || msg.type === 'goal-clear' ||
                        msg.type === 'schedule-catalog' || msg.type === 'schedule-list' || msg.type === 'schedule-history' ||
-                       msg.type === 'schedule-update' || msg.type === 'schedule-delete') {
-              handleQuery(api, host, agentDefaultModel, msg).then((frame) => {
+                       msg.type === 'schedule-update' || msg.type === 'schedule-delete' ||
+                       PLUGIN_REQUEST_TYPES.has(msg.type)) {
+              if (PLUGIN_REQUEST_TYPES.has(msg.type) && !ws.deviceId) {
+                sendFrame({ kind: 'error', code: 'authentication-required', requestType: msg.type,
+                  ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}),
+                  message: 'Plugin management requires a paired device' })
+                return
+              }
+              if (msg.type === 'plugin-install' && pluginInstallOwners.has(msg.requestId)) {
+                sendFrame({ kind: 'error', code: 'plugin-install/in-progress', requestType: msg.type,
+                  requestId: msg.requestId, message: 'An installation already uses this requestId' })
+                return
+              }
+              handleQuery(api, host, agentDefaultModel, msg, {
+                onInstallStart: (requestId) => pluginInstallOwners.set(requestId, ws),
+                onInstallEnd: (requestId) => pluginInstallOwners.delete(requestId),
+              }).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(stringifyWireFrame(frame))
               })
             } else {
@@ -2991,6 +3026,7 @@ const plugin = {
               'tasks',
               'goals',
               'schedule-management',
+              'plugin-management-v1',
               'session-cancel',
               'queue-control',
               'session-archive',
@@ -3111,6 +3147,26 @@ const plugin = {
       if (clients.size > 0) broadcastSessionMetadataFrame({ kind: 'schedule-changed' })
     })
 
+    const disposePluginsChanged = ctx.on('plugin-manager/changed', (change) => {
+      if (clients.size > 0) broadcastSessionMetadataFrame({ kind: 'plugins-changed', reason: change?.reason })
+    })
+    const disposePluginSettingsChanged = ctx.on('settings/document-updated', (ns, revision) => {
+      if (clients.size > 0) broadcastSessionMetadataFrame({ kind: 'plugin-settings-changed', ns, revision })
+    })
+    const sendPluginInstallEvent = (kind, event) => {
+      const owner = pluginInstallOwners.get(event?.requestId)
+      if (owner?.readyState === 1) owner.send(stringifyWireFrame({ kind, ...event }))
+    }
+    const disposePluginInstallState = ctx.on('plugin-manager/install-state', (progress) => {
+      sendPluginInstallEvent('plugin-install-state', progress)
+    })
+    const disposePluginInstallLog = ctx.on('plugin-manager/install-log', (chunk) => {
+      if (!chunk?.requestId) return
+      const { requestId, jobId, stream, text, exitCode } = chunk
+      sendPluginInstallEvent('plugin-install-log', { requestId, jobId, stream, text,
+        ...(exitCode === undefined ? {} : { exitCode }) })
+    })
+
     const disposeQuestions = ctx.on('user-questions/request', (request, next) => {
       const sessionId = request?.agent?.id === undefined ? null : String(request.agent.id)
       if (!sessionId || !Array.isArray(request.questions) || !hasInteractionClient(sessionId)) return next()
@@ -3349,6 +3405,10 @@ const plugin = {
       disposeMgmt()
       disposeEvents()
       disposeScheduleChanged()
+      disposePluginsChanged()
+      disposePluginSettingsChanged()
+      disposePluginInstallState()
+      disposePluginInstallLog()
       disposeQuestions()
       disposeApprovals()
       if (lanServer) lanServer.close()
@@ -3358,6 +3418,7 @@ const plugin = {
         client.terminate()
       }
       clients.clear()
+      pluginInstallOwners.clear()
       wss.close()
       log('plugin stopped, all sockets closed')
     })

package/lib/plugin-management.mjs

@@ -0,0 +1,194 @@
+const OFFICIAL_CONFIGURATION_ITEMS = Object.freeze([
+  { id: 'shell', namespaces: ['bash-sandbox', 'pwsh-sandbox'] },
+  { id: 'agent-loop', namespaces: ['agent-loop'] },
+  { id: 'subagent', namespaces: ['subagent', 'subagent-model-selection-settings'] },
+  { id: 'web-search', namespaces: ['web-search-deepseek'] },
+])
+
+export const PLUGIN_REQUEST_TYPES = new Set([
+  'plugin-catalog',
+  'plugin-registries',
+  'plugin-inspect',
+  'plugin-install',
+  'plugin-install-status',
+  'plugin-install-cancel',
+  'plugin-bundle-set-enabled',
+  'plugin-entry-set-enabled',
+  'plugin-remove',
+  'plugin-settings',
+  'plugin-settings-mutate',
+  'plugin-version-exemptions',
+  'plugin-version-exemption-set',
+])
+
+const FLAT_RESPONSE_TYPES = new Set([
+  'plugin-catalog', 'plugin-registries', 'plugin-settings',
+  'plugin-settings-mutate', 'plugin-version-exemptions',
+])
+
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonempty(value, maxLength = 2048) {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= maxLength
+}
+
+function badRequest(type, requestId, message) {
+  return { kind: 'error', code: 'bad-request', message, requestType: type,
+    ...(requestId === undefined ? {} : { requestId }) }
+}
+
+function registryOption(msg, type, requestId) {
+  if (msg.registry === undefined) return { value: undefined }
+  if (msg.registry === null || (nonempty(msg.registry) && /^https?:\/\//i.test(msg.registry))) {
+    return { value: msg.registry }
+  }
+  return { error: badRequest(type, requestId, 'registry must be null or an HTTP(S) URL') }
+}
+
+function requireName(msg, field, type, requestId) {
+  if (!nonempty(msg[field], 512)) return { error: badRequest(type, requestId, `${field} must be a non-empty string`) }
+  return { value: msg[field].trim() }
+}
+
+async function pluginCatalog(api) {
+  const inventory = await api.plugins.inventory()
+  if (!record(inventory) || !Array.isArray(inventory.entries)) throw new Error('pluginInventory/list returned an invalid inventory')
+  if (inventory.managementAvailable !== true) {
+    return { managementAvailable: false, bundles: [], plugins: [], officialItems: [], settingsWritable: false }
+  }
+  const [bundles, plugins, settings] = await Promise.all([
+    api.plugins.listBundles(),
+    api.plugins.listPlugins(),
+    api.settings.describe(),
+  ])
+  if (!Array.isArray(bundles) || !Array.isArray(plugins) || !Array.isArray(settings?.namespaces)) {
+    throw new Error('plugin manager returned an invalid catalog')
+  }
+  const available = new Set(settings.namespaces.map(item => item.ns))
+  const officialItems = OFFICIAL_CONFIGURATION_ITEMS
+    .filter(item => item.namespaces.some(ns => available.has(ns)))
+    .map(item => ({ id: item.id, namespaces: item.namespaces.filter(ns => available.has(ns)) }))
+  return {
+    managementAvailable: true,
+    bundles: bundles.map(bundle => ({
+      ...bundle,
+      experimental: bundle.name.startsWith('@deepseek-ai/dsh-experimental-'),
+    })),
+    plugins,
+    officialItems,
+    settingsWritable: settings.writable === true,
+  }
+}
+
+/**
+ * The mobile wire owns its request names and correlation ids. The Host adapter
+ * owns Typert endpoint names and argument descriptors.
+ */
+export async function handlePluginQuery(api, msg, { onInstallStart, onInstallEnd } = {}) {
+  const type = msg?.type
+  if (!PLUGIN_REQUEST_TYPES.has(type)) return null
+  const requestId = nonempty(msg.requestId, 128) ? msg.requestId.trim() : undefined
+  if (!requestId) return badRequest(type, undefined, `${type} requires a requestId`)
+
+  try {
+    let value
+    let kind = type
+    if (type === 'plugin-catalog') {
+      value = await pluginCatalog(api)
+    } else if (type === 'plugin-registries') {
+      value = await api.plugins.registries()
+    } else if (type === 'plugin-inspect' || type === 'plugin-install') {
+      const spec = requireName(msg, 'spec', type, requestId)
+      if (spec.error) return spec.error
+      const registry = registryOption(msg, type, requestId)
+      if (registry.error) return registry.error
+      if (type === 'plugin-inspect') {
+        value = await api.plugins.inspect(spec.value, registry.value === undefined ? undefined : { registry: registry.value })
+        kind = 'plugin-inspection'
+      } else {
+        if (msg.enabled !== undefined && typeof msg.enabled !== 'boolean') {
+          return badRequest(type, requestId, 'enabled must be a boolean')
+        }
+        if (msg.approvedBuilds !== undefined && (!Array.isArray(msg.approvedBuilds)
+          || msg.approvedBuilds.length > 100 || msg.approvedBuilds.some(name => !nonempty(name, 512)))) {
+          return badRequest(type, requestId, 'approvedBuilds must be an array of package names')
+        }
+        const options = {
+          requestId,
+          ...(msg.enabled === undefined ? {} : { enabled: msg.enabled }),
+          ...(registry.value === undefined ? {} : { registry: registry.value }),
+          ...(msg.approvedBuilds === undefined ? {} : { approvedBuilds: msg.approvedBuilds }),
+        }
+        onInstallStart?.(requestId)
+        try {
+          value = await api.plugins.installBundle(spec.value, options)
+        } finally {
+          onInstallEnd?.(requestId)
+        }
+        kind = 'plugin-install-result'
+      }
+    } else if (type === 'plugin-install-status' || type === 'plugin-install-cancel') {
+      const installId = requireName(msg, 'installId', type, requestId)
+      if (installId.error) return installId.error
+      value = type === 'plugin-install-status'
+        ? await api.plugins.waitForInstall(installId.value)
+        : await api.plugins.cancelInstall(installId.value)
+    } else if (type === 'plugin-bundle-set-enabled' || type === 'plugin-entry-set-enabled') {
+      const field = type === 'plugin-bundle-set-enabled' ? 'name' : 'entryId'
+      const target = requireName(msg, field, type, requestId)
+      if (target.error) return target.error
+      if (typeof msg.enabled !== 'boolean') return badRequest(type, requestId, 'enabled must be a boolean')
+      value = type === 'plugin-bundle-set-enabled'
+        ? await api.plugins.setBundleEnabled(target.value, msg.enabled)
+        : await api.plugins.setPluginEnabled(target.value, msg.enabled)
+    } else if (type === 'plugin-remove') {
+      const name = requireName(msg, 'name', type, requestId)
+      if (name.error) return name.error
+      value = await api.plugins.removeBundle(name.value)
+    } else if (type === 'plugin-settings') {
+      const described = await api.settings.describe()
+      if (!record(described) || !Array.isArray(described.namespaces)) throw new Error('settings/describe returned an invalid response')
+      if (msg.ns !== undefined) {
+        const ns = requireName(msg, 'ns', type, requestId)
+        if (ns.error) return ns.error
+        const namespace = described.namespaces.find(item => item.ns === ns.value)
+        if (!namespace) return { kind: 'error', code: 'plugin-settings/not-found',
+          message: `settings namespace is unavailable: ${ns.value}`, requestType: type, requestId }
+        value = { writable: described.writable === true, namespace }
+      } else {
+        value = described
+      }
+    } else if (type === 'plugin-settings-mutate') {
+      const ns = requireName(msg, 'ns', type, requestId)
+      if (ns.error) return ns.error
+      if (!Number.isSafeInteger(msg.expectedRevision) || msg.expectedRevision < 0) {
+        return badRequest(type, requestId, 'expectedRevision must be a non-negative integer')
+      }
+      if (!Array.isArray(msg.ops) || msg.ops.length < 1 || msg.ops.length > 100
+        || msg.ops.some(op => !record(op) || !['set', 'unset'].includes(op.op)
+          || !Array.isArray(op.path) || op.path.some(part => !nonempty(part, 256))
+          || (op.op === 'set' && !Object.hasOwn(op, 'value')))) {
+        return badRequest(type, requestId, 'ops must contain valid set or unset path edits')
+      }
+      value = await api.settings.mutate({ ns: ns.value, ops: msg.ops, expectedRevision: msg.expectedRevision })
+    } else if (type === 'plugin-version-exemptions') {
+      value = await api.plugins.listVersionExemptions()
+    } else if (type === 'plugin-version-exemption-set') {
+      const packageVersion = requireName(msg, 'packageVersion', type, requestId)
+      const runtimeVersion = requireName(msg, 'runtimeVersion', type, requestId)
+      if (packageVersion.error || runtimeVersion.error) return packageVersion.error || runtimeVersion.error
+      if (typeof msg.enabled !== 'boolean' || (msg.acceptRisk !== undefined && typeof msg.acceptRisk !== 'boolean')) {
+        return badRequest(type, requestId, 'enabled and acceptRisk must be booleans')
+      }
+      value = await api.plugins.setVersionExemption(packageVersion.value, runtimeVersion.value,
+        msg.enabled, msg.acceptRisk)
+    }
+    return { kind, requestId, ...(FLAT_RESPONSE_TYPES.has(type) && record(value)
+      ? value : { result: value }) }
+  } catch (error) {
+    return { kind: 'error', code: error?.code || 'internal',
+      message: error?.message || String(error), requestType: type, requestId }
+  }
+}