dsh-plugin-mobile-gateway 0.1.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clarklevis1995
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,282 @@
+# dsh Mobile Gateway — WebSocket 协议参考
+
+移动端通过一个 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送消息、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现（v0.1.17）。
+
+- **端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
+- **帧格式**：全部为 JSON 文本帧（UTF-8）
+- **连接即推送**：连上后服务端立刻发送一条 `hello`，之后 agent 输出以 `event` 帧实时推送
+
+---
+
+## 1. 通用约定
+
+### 客户端 → 服务端（请求帧）
+```json
+{ "type": "<消息类型>", ...参数 }
+```
+
+### 服务端 → 客户端（响应/推送帧）
+```json
+{ "kind": "<类型>", ...数据 }
+```
+
+### 统一错误帧
+```json
+{ "kind": "error", "code": "session-not-found", "message": "no such session",
+  "requestType": "history", "sessionId": "..." }
+```
+- `code`：`bad-request` / `session-not-found` / `agent-busy` / `model-unavailable` / `fork-unavailable` / `unknown-command` / `workspace-invalid-path` / `directory-unreadable` / `internal` 等（多为宿主错误码透传）
+- `requestType`：出错请求的类型（`message` 直发类错误无此字段）
+- `sessionId`：涉及会话时附带
+
+### 会话 ID 获取
+`{"type":"sessions"}` 列表取 `sessionId`，或 `{"type":"message"}` 省略 sessionId 自动创建后从 `sent` 响应拿。
+
+---
+
+## 2. 连接管理
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `ping` | — | 心跳；回复 `pong` |
+| `subscribe` | `sessionId` | 事件流过滤：之后只收到该会话的 `event`（不订阅 = 接收所有会话） |
+| `unsubscribe` | — | 取消过滤 |
+
+```json
+{"type":"ping"}
+→ {"kind":"pong","at":1786937352316}
+
+{"type":"subscribe","sessionId":"session-abc"}
+→ {"kind":"subscribed","sessionId":"session-abc"}
+```
+
+---
+
+## 3. 消息（手机 → agent）
+
+### `message` — 发送消息（会话不存在则创建）
+```json
+{ "type": "message", "sessionId": "session-abc", "text": "你好",
+  "mode": "queue", "workspaceId": "w1", "cwd": "/path" }
+```
+- `sessionId`：可选。省略时**自动创建新会话**（可用 `workspaceId` 或 `cwd` 指定归属工作区，至多一个，workspaceId 优先）
+- `mode`：`"queue"`（排队，默认）/ `"steer"`（打断当前回合）
+- `text` 以 `/` 开头会被当作**斜杠命令**（如 `/permission ask`），宿主直接执行、**绝不发给模型**
+
+```json
+→ { "kind": "sent", "sessionId": "session-abc", "mode": "queue" }
+→ { "kind": "sent", "sessionId": "session-abc", "mode": "queue", "command": { "kind": "success", "text": "..." } }   // 斜杠命令时
+```
+
+---
+
+## 4. 会话与历史查询
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `sessions` | — | 会话列表（`updatedAt/running/blank/cwd/agentPreset`） |
+| `history` | `sessionId`, `beforeSeq?`, `maxMessages?`, `maxBytes?`, `view?` | 历史事件页（见下） |
+| `search` | `query` | 会话全文搜索 |
+| `session-stats` | `sessionId` | 执行统计投影（输入框统计条数据源） |
+| `context-usage` | `sessionId` | token 用量 + 上下文占用投影 |
+
+### `history` 详细
+```json
+{ "type": "history", "sessionId": "session-abc", "maxMessages": 60, "maxBytes": 4194304, "view": "conversation" }
+```
+- 返回**原始 SessionEvent**（`{type, seq, time, data}`，方案A），可选裁剪
+- `maxBytes`：单帧字节预算，默认 **4 MiB**；超预算保留最新部分并给出 `nextBeforeSeq` 续页（客户端 16 MiB 上限的安全余量）
+- `view: "conversation"`：**对话裁剪模式**——丢弃 `assistant/chunk`（token 回放）与 `request/header`（system prompt），`tool/result` 嵌套文本截断到 2000 字符
+- 分页：`hasMore` 为真时用 `beforeSeq: nextBeforeSeq` 请求更早一页
+
+```json
+→ { "kind": "history", "sessionId": "session-abc", "events": [ ...原始事件... ],
+    "bytes": 3521, "view": "conversation", "hasMore": true, "nextBeforeSeq": 128,
+    "projections": { "asOfSeq": 127, "values": { "tokenUsage": {...}, "contextPressure": {...}, "permissions": {...}, "sessionStats": {...} } } }
+```
+
+### `session-stats` 详细（输入框统计条）
+```json
+{ "type": "session-stats", "sessionId": "session-abc" }
+→ { "kind": "session-stats", "sessionId": "session-abc", "asOfSeq": 42,
+    "sessionStats": { "turns": 6, "steps": 69, "llmMs": 2280000, "toolMs": 41400,
+                      "ttftMs": 2600, "ttftSteps": 1, "decodeMs": 5000, "decodeTokens": 385,
+                      "lastTurn": 6, "openStep": null, "pendingCalls": {} },
+    "tokenUsage": { "totals": { "inputTokens": 10, "outputTokens": 5, "cacheReadTokens": 1, "cacheWriteTokens": 0, "reasoningTokens": 0 } },
+    "contextPressure": { "contextWindow": 128000, "pressureTokens": 1500, "surfaceTokens": 2000 } }
+```
+展示公式（与浏览器同源）：LLM 时长=`llmMs`、工具=`toolMs`、首 token 平均=`ttftMs/ttftSteps`、速率=`decodeTokens/(decodeMs/1000)`、缓存命中=`cacheHitPercent(tokenUsage.totals)`、输入=`billedInputTokens(totals)`、输出=`outputTokens`。
+
+---
+
+## 5. 工作区与目录
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `workspaces` | — | 全部工作区（含每个的 `sessionIds`） |
+| `workspace-create` | `path` | 对**已存在目录**创建工作区（已归属→`created:false` 幂等） |
+| `directories` | `path?` | 浏览 server 目录（缺省 = home）；`crumbs` 面包屑 + `entries`（含 `hidden` 标记） |
+
+```json
+{ "type": "workspace-create", "path": "/Users/lichaofan/DeepseekHarnessProject" }
+→ { "kind": "workspace-create", "workspace": { "workspaceId": "w9", "path": "...", "title": "...", "sessionIds": [] },
+    "created": true }
+```
+
+---
+
+## 6. 模型与思考等级
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `models` | `sessionId?` | **带 sessionId**：该会话的模型目录（`current` + `routable` + `groups`）；**不带**：全局模型目录（`groups` + `failures`，无需会话） |
+| `providers` | — | 可配置 provider 列表（含 live/dormant 状态） |
+| `select-model` | `sessionId`, `provider`, `model`, `reasoningEffort?` | 切换**该会话**的模型/思考等级（写入会话日志） |
+| `default-model` | — | **默认**模型选择（新会话用，含 `reasoningEffort`） |
+| `save-default-model` | `provider`, `model`, `reasoningEffort?` | 修改**默认**模型 + 思考等级（全局） |
+
+```json
+{ "type": "models" }
+→ { "kind": "models",
+    "groups": [ { "id": "deepseek", "name": "DeepSeek",
+                  "models": [ { "id": "deepseek-chat", "name": "DeepSeek Chat",
+                                "reasoning": { "efforts": [ { "id": "low", "name": "Low" }, ... ] } } ] } ],
+    "failures": [] }
+
+{ "type": "models", "sessionId": "session-abc" }
+→ { "kind": "models", "current": { "provider": "deepseek", "model": "deepseek-chat" },
+    "routable": true, "groups": [ ... ], "failures": [] }
+
+{ "type": "providers" }
+→ { "kind": "providers", "providers": [ { "provider": "deepseek", "displayName": "DeepSeek", "declared": true } ] }
+
+{ "type": "select-model", "sessionId": "session-abc", "provider": "deepseek",
+  "model": "deepseek-chat", "reasoningEffort": "high" }
+→ { "kind": "select-model", "selected": { "provider": "deepseek", "model": "deepseek-chat", "reasoningEffort": "high" } }
+```
+
+---
+
+## 7. 权限控制
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `permission-options` | `sessionId?` | 可用权限 preset 列表（`namespace`）+ 该会话当前生效值（`sessionPermissions`） |
+| `permission` | `sessionId`, `name` | 切换**该会话**的权限 preset（走官方 `/permission` 命令，不触发模型） |
+
+```json
+{ "type": "permission", "sessionId": "session-abc", "name": "workspace-write" }
+→ { "kind": "permission", "sessionId": "session-abc", "set": "workspace-write",
+    "commandId": "cmd-1", "result": { "kind": "success", "text": "..." } }
+```
+
+---
+
+## 8. 新会话默认配置
+
+| type | 参数 | 说明 |
+|---|---|---|
+| `agent-presets` | — | preset 名册（含 `isDefault` 标记） |
+| `defaults` | — | 读取默认 agent 预设 + 默认权限 |
+| `set-default` | `target`(agent-preset\|permission), `value` | 修改默认预设/默认权限（全局） |
+
+```json
+{ "type": "defaults" }
+→ { "kind": "defaults", "agentPresetDefault": "standard", "permissionDefault": "ask" }
+
+{ "type": "set-default", "target": "agent-preset", "value": "minimal" }
+→ { "kind": "set-default", "target": "agent-preset", "value": "minimal", "applied": true }
+```
+
+---
+
+## 9. 分支（fork）
+
+```json
+{ "type": "fork", "sessionId": "session-abc", "atSeq": 42 }
+→ { "kind": "fork", "sessionId": "session-分支新会话" }
+```
+- `atSeq`：从该消息所在的**完整一轮**分叉（省略 = 最近完成的 turn）；进行中的 turn 分叉会报 `fork-unavailable`
+- 子会话继承源 cwd / 模型 / 血缘 / 标题 / 工作区
+
+---
+
+## 10. 宿主信息
+
+| type | 返回 |
+|---|---|
+| `host` | `version`, `cwd`, `provider`/`model`（默认模型精简版）, `attachedSessions`, `canOpenPath` |
+
+```json
+{ "type": "host" }
+→ { "kind": "host", "version": "0.1.0-rc.6", "cwd": "/Users/lichaofan",
+    "provider": "deepseek", "model": "deepseek-chat", "attachedSessions": 3, "canOpenPath": true }
+```
+
+---
+
+## 11. 服务端主动推送
+
+| kind | 触发时机 |
+|---|---|
+| `hello` | 连接成功：`{ "kind":"hello", "protocol":1, "port":3080, "clients":1 }` |
+| `event` | 任意会话的 agent 输出（见下） |
+| `pong` / `subscribed` / `sent` | 对应请求的回复 |
+
+### `event` 帧（agent 实时输出）
+```json
+{ "kind": "event", "sessionId": "session-abc", "seq": 42, "time": 1786937352,
+  "event": { "type": "assistant/chunk", "turn": 1, "step": 0, "chunkType": "text-delta", "text": "正在" } }
+```
+`event.type` 覆盖（精炼字段）：
+- `user/message` → `{text, source}`
+- `assistant/chunk` → `{turn, step, chunkType: text-delta|reasoning-delta|tool-call-delta|usage|finish, text?/tool?/usage?/finish?}`
+- `assistant/message` → `{turn, step, text, reasoning, toolCalls[]}`
+- `tool/call` → `{turn, step, callId, name, arguments}`
+- `tool/result` → `{turn, step, callId, isError, preview(≤400字符)}`
+- `turn/start|end` / `step/start|end` → `{turn, step, reason?}`
+
+---
+
+## 12. 端到端示例（Postman）
+
+1. Connect → 收到 `hello`
+2. `{"type":"sessions"}` → 挑 `sessionId`（或直接下一步自动建）
+3. `{"type":"subscribe","sessionId":"session-abc"}`
+4. `{"type":"message","sessionId":"session-abc","text":"帮我查一下deepseek"}` → `sent`
+5. 盯着 Messages 面板：`event` 流实时滚动（chunk → tool/call → tool/result → assistant/message）
+6. `{"type":"history","sessionId":"session-abc","view":"conversation","maxMessages":60}` → 最近历史（自动分页用 `beforeSeq: nextBeforeSeq`）
+7. `{"type":"session-stats","sessionId":"session-abc"}` → 统计条数据
+8. 完事 `{"type":"unsubscribe"}` 或 Disconnect
+
+---
+
+## 13. 安全注意
+
+- 当前 `/ws/mobile` **无认证**：任何能连到端口的人都能读会话、发消息、改配置（含全局默认值）
+- 仅限本机/受信局域网使用；**暴露公网前必须加 token 认证**
+- `set-default` / `save-default-model` 是全局写操作，客户端 UI 应加确认
+
+---
+
+## 14. 版本历史（插件）
+
+| 版本 | 新增 |
+|---|---|
+| v0.1.5 | workspace-create / directories / host |
+| v0.1.6 | 修复消息分发器遗漏（host/directories/workspace-create 未路由） |
+| v0.1.7 | models / select-model / permission-options / permission / context-usage |
+| v0.1.8 | permission 改走 typert 网关（不再经 prompt） |
+| v0.1.9 | 修复 `agentId` wire 键 |
+| v0.1.10 | message 支持 workspaceId/cwd 建会话 |
+| v0.1.11 | agent-presets / defaults / set-default |
+| v0.1.12 | history 字节上限 + 自动续页 + conversation 裁剪 |
+| v0.1.13 | session-stats |
+| v0.1.14 | default-model |
+| v0.1.15 | save-default-model |
+| v0.1.16 | fork（新对话分支） |
+| v0.1.17 | models 支持无 sessionId 全局目录；新增 providers |
+
+---
+
+*协议与插件源码同源维护：`dsh-plugin-mobile-gateway/lib/index.js` 顶部注释即协议摘要。*

package/README.md

@@ -0,0 +1,56 @@
+# dsh-plugin-mobile-gateway
+
+dsh 的持久化 WebSocket 网关：在 web 服务器上注册 `/ws/mobile`，转发 agent 实时输出给移动端，并提供会话/工作区/模型/权限/默认配置/分支等 24 个信令。
+
+- **协议文档**：[`PROTOCOL.md`](PROTOCOL.md)（与源码 `lib/index.js` 顶部注释同源）
+- **日志**：`/tmp/mobile-gateway.log`（连接/查询/错误），宿主 stdout 同步输出
+
+## 它是如何生效的
+
+```
+① package.json 声明 dsh.bundle.patch（门槛：有它才算 dsh 插件）
+② dsh plugin --profile web add <路径>  → pnpm 安装 + 自动加入 dsh.profile.bundles
+③ 启动 dsh web  → 按 bundles 顺序叠加各 bundle 的 cordis.patch.yml → 插件生效
+```
+
+`dsh.bundle.patch` 缺失时 `dsh plugin add` 只装依赖、**不生效**。
+
+## 管理命令速查
+
+```bash
+# 安装（file: 复制安装，自包含，依赖解析最稳）
+dsh plugin --profile web add file:/Users/lichaofan/DeepseekHarnessProject/dsh-plugin-mobile-gateway
+
+# 更新（file: 是复制安装——改源码后必须 remove + add 才会刷新副本）
+dsh plugin --profile web remove dsh-plugin-mobile-gateway
+dsh plugin --profile web add file:/Users/lichaofan/DeepseekHarnessProject/dsh-plugin-mobile-gateway
+
+# 卸载
+dsh plugin --profile web remove dsh-plugin-mobile-gateway
+#   并从 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 里删除该包名
+
+# 验证组合树（不启动）
+dsh --profile web --dump-config | grep -A3 mobile-gateway
+```
+
+## 重要注意事项
+
+| 事项 | 说明 |
+|---|---|
+| **改代码必须重装** | `file:` 是复制，改 `lib/index.js` 后需 remove + add（或 bump package.json 版本） |
+| **重装后必须重启** | composition 启动时解析，web profile 的 HMR 被禁用：`dsh web` 重启才生效 |
+| **不要用 link:** | `link:` 符号链接会从源码真实路径解析依赖（`ws` 会找不到）；`file:` 复制进 profile node_modules 才稳 |
+| **补丁覆盖是整段替换** | 覆盖现有行要重述全部 config key；行 id 不能与现有行冲突 |
+| **认证缺失** | `/ws/mobile` 无鉴权，暴露公网前必须加 token |
+
+## 本地测试
+
+```bash
+# 完整分发链路测试（mock harness + 真实 ws 客户端，当前 34 个断言）
+NODE_PATH=/Users/lichaofan/.npm/_npx/1e7f6d9597241db0/node_modules \
+  node test/gateway.test.js
+```
+
+## 版本历史
+
+见 `PROTOCOL.md` §14。

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# dsh-plugin-mobile-gateway bundle patch.
+# Applied after dsh-base and dsh-web-app: inserts the persistent /ws/mobile
+# gateway row into the host plane (it consumes the host `webServer` service
+# and the host `session/event` feed, and publishes no service of its own).
+- insert:
+    - id: mobile-gateway
+      name: 'dsh-plugin-mobile-gateway'
+
+# The gateway's `search` query channel needs the full-text session index,
+# which dsh-web-app deliberately ships as `openAt: never` (search disabled).
+# This later layer opts the deployment into on-demand opening: the node:sqlite
+# import and the in-memory index stay deferred until the first search call,
+# so startup is unaffected. A patch replaces the row's whole config, so both
+# keys are restated here.
+- id: session-query-sqlite
+  config:
+    path: ':memory:'
+    openAt: first-search

package/lib/index.js

@@ -0,0 +1,692 @@
+// dsh-plugin-mobile-gateway — persistent Host plugin.
+//
+// Two directions:
+//  1. Agent -> mobile: registers a WebSocket endpoint at /ws/mobile on the dsh
+//     web server and forwards agent session output (the same `session/event`
+//     feed the browser UI consumes) to connected mobile clients as curated
+//     JSON text frames.
+//  2. Mobile -> agent: clients send a message through the same socket; the
+//     plugin admits it through the official host API (apiProxy.sessions.prompt)
+//     so it enters the target session exactly like a browser-submitted prompt.
+//
+// Wire protocol (JSON text frames):
+//   client -> server: { "type": "ping" }
+//                     { "type": "subscribe", "sessionId": "..." }  (optional filter)
+//                     { "type": "unsubscribe" }
+//                     { "type": "message", "sessionId"?, "text", "mode"?: "queue"|"steer",
+//                       "workspaceId"?, "cwd"? }
+//                        sessionId omitted -> a new session is created first; the
+//                        new session can be placed in a workspace via workspaceId
+//                        (or cwd; at most one, workspaceId wins)
+//                     { "type": "workspaces" }                     -> workspace list
+//                     { "type": "sessions" }                       -> session list
+//                     { "type": "history", "sessionId", "beforeSeq"?, "maxMessages"?,
+//                       "maxBytes"?, "view"?: "conversation" }
+//                        -> raw SessionEvent page (scheme A), capped at maxBytes
+//                           (default 4 MiB); hasMore + nextBeforeSeq page backward;
+//                           view:"conversation" trims chunk/header events and tool output
+//                     { "type": "search", "query" }                -> session search
+//                     { "type": "host" }                           -> host.describe snapshot (incl. default provider/model)
+//                     { "type": "default-model" }                   -> agentDefaultModel.currentSelection()
+//                     { "type": "save-default-model", "provider", "model", "reasoningEffort"? }
+//                     { "type": "directories", "path"? }           -> server dir listing (fs-based)
+//                     { "type": "workspace-create", "path" }       -> create workspace over a dir
+//                     { "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": "select-model", "sessionId", "provider", "model", "reasoningEffort"? }
+//                     { "type": "permission-options", "sessionId"? } -> permission presets (+ session knobs)
+//                     { "type": "permission", "sessionId", "name" }  -> switch preset via /permission command
+//                     { "type": "context-usage", "sessionId" }       -> tokenUsage + contextPressure projections
+//                     { "type": "session-stats", "sessionId" }       -> sessionStats + tokenUsage projections
+//                        (the input-box stats strip source)
+//                     { "type": "agent-presets" }                     -> preset roster (+ isDefault)
+//                     { "type": "defaults" }                          -> default agent preset + default permission
+//                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
+//   server -> client: { "kind": "hello", "protocol": 1, "port", "clients" }
+//                     { "kind": "pong", "at" }
+//                     { "kind": "subscribed", "sessionId" }
+//                     { "kind": "sent", "sessionId", "mode", "command"? }
+//                     { "kind": "workspaces" | "sessions" | "history" | "search", ...data }
+//                     { "kind": "error", "code", "message", "requestType"?, "sessionId"? }
+//                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
+'use strict'
+
+const fs = require('node:fs')
+const fsp = require('node:fs/promises')
+const os = require('node:os')
+const path = require('node:path')
+const crypto = require('node:crypto')
+const { WebSocketServer } = require('ws')
+
+const MAX_PREVIEW = 400
+const LOG_FILE = '/tmp/mobile-gateway.log'
+
+function log(line) {
+  const msg = `[${new Date().toISOString()}] ${line}`
+  console.log('mobile-gateway:', msg)
+  try {
+    fs.appendFileSync(LOG_FILE, msg + '\n')
+  } catch (error) {
+    // never let logging break the gateway
+  }
+}
+
+// Extract plain text from a ContentBlock[] (text blocks only).
+function textOf(blocks) {
+  let text = ''
+  for (const block of blocks) {
+    if (block && block.type === 'text' && typeof block.text === 'string') text += block.text
+  }
+  return text
+}
+
+// Build the small, owned JSON wire record for one session event. Reads only
+// leaf fields of the live SessionEvent — never serializes live objects.
+function buildWireEvent(session, event) {
+  const base = { sessionId: String(session.id), seq: event.seq, time: event.time }
+  const d = event.data || {}
+  switch (event.type) {
+    case 'user/message':
+      return Object.assign(base, {
+        event: {
+          type: 'user/message',
+          text: textOf(d.content || []),
+          source: d.source && d.source.kind,
+        },
+      })
+    case 'assistant/chunk': {
+      const chunk = d.chunk || {}
+      const ev = { type: 'assistant/chunk', turn: d.turn, step: d.step, chunkType: chunk.type }
+      if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') ev.text = chunk.text
+      if (chunk.type === 'tool-call-delta') ev.tool = { id: chunk.id, name: chunk.name, argumentsDelta: chunk.argumentsDelta }
+      if (chunk.type === 'usage') ev.usage = chunk.usage
+      if (chunk.type === 'finish') ev.finish = { kind: chunk.reason && chunk.reason.kind }
+      return Object.assign(base, { event: ev })
+    }
+    case 'assistant/message': {
+      const blocks = (d.message && d.message.content) || []
+      let text = ''
+      let reasoning = ''
+      const toolCalls = []
+      for (const block of blocks) {
+        if (!block) continue
+        if (block.type === 'text' && typeof block.text === 'string') text += block.text
+        else if (block.type === 'reasoning' && typeof block.text === 'string') reasoning += block.text
+        else if (block.type === 'tool-call') toolCalls.push({ id: block.id, name: block.name, arguments: block.arguments })
+      }
+      return Object.assign(base, {
+        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls },
+      })
+    }
+    case 'tool/call':
+      return Object.assign(base, {
+        event: { type: 'tool/call', turn: d.turn, step: d.step, callId: d.callId, name: d.name, arguments: d.arguments },
+      })
+    case 'tool/result': {
+      let preview = ''
+      for (const block of (d.message && d.message.content) || []) {
+        for (const inner of (block && block.content) || []) {
+          if (inner.type === 'text' && typeof inner.text === 'string') preview += inner.text
+        }
+      }
+      if (preview.length > MAX_PREVIEW) preview = preview.slice(0, MAX_PREVIEW) + '…'
+      return Object.assign(base, {
+        event: {
+          type: 'tool/result',
+          turn: d.turn,
+          step: d.step,
+          callId: d.message && d.message.source && d.message.source.callId,
+          isError: !!d.error,
+          preview,
+        },
+      })
+    }
+    case 'turn/start':
+    case 'turn/end':
+    case 'step/start':
+    case 'step/end':
+      return Object.assign(base, {
+        event: { type: event.type, turn: d.turn, step: d.step, reason: d.reason && d.reason.kind },
+      })
+    default:
+      return Object.assign(base, { event: { type: event.type } })
+  }
+}
+
+// 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() : ''
+  if (!text) {
+    return { kind: 'error', code: 'bad-request', message: 'text must be a non-empty string' }
+  }
+  const mode = msg.mode === 'steer' ? 'steer' : 'queue'
+
+  let sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : undefined
+  try {
+    if (sessionId === undefined) {
+      // New session: optionally place it in a workspace (at most one of
+      // workspaceId / cwd, per the host create contract; workspaceId wins).
+      const createPayload = {}
+      if (typeof msg.workspaceId === 'string' && msg.workspaceId.trim() !== '') {
+        createPayload.workspaceId = msg.workspaceId.trim()
+      }
+      if (typeof msg.cwd === 'string' && msg.cwd.trim() !== '') {
+        if (createPayload.workspaceId) log('mobile message: both workspaceId and cwd given, using workspaceId')
+        else createPayload.cwd = msg.cwd.trim()
+      }
+      const created = await api.sessions.create({ rpcId: crypto.randomUUID(), payload: createPayload })
+      if (!created.result.ok) {
+        return { kind: 'error', code: created.result.error.code, message: created.result.error.message }
+      }
+      sessionId = created.result.value.sessionId
+      log(`mobile message created new session ${sessionId} (${JSON.stringify(createPayload)})`)
+    }
+
+    const resp = await api.sessions.prompt({
+      rpcId: crypto.randomUUID(),
+      payload: { sessionId, mode, content: [{ type: 'text', text }] },
+    })
+    if (resp.result.ok) {
+      log(`mobile message accepted: session=${sessionId} mode=${mode} text="${text.slice(0, 60)}"`)
+      return {
+        kind: 'sent',
+        sessionId,
+        mode,
+        ...(resp.result.value.command ? { command: resp.result.value.command } : {}),
+      }
+    }
+    log(`mobile message rejected: ${resp.result.error.code}: ${resp.result.error.message}`)
+    return {
+      kind: 'error',
+      code: resp.result.error.code,
+      message: resp.result.error.message,
+      ...(sessionId ? { sessionId } : {}),
+    }
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error)
+    log(`mobile message failed: ${message}`)
+    return { kind: 'error', code: 'internal', message, ...(sessionId ? { sessionId } : {}) }
+  }
+}
+
+// Proxy one read-only query to the official host API (the same surface the
+// browser uses). Success returns `{ kind: <type>, ...value }`; failure returns
+// the uniform `{ kind: 'error', code, message, requestType }` frame.
+async function proxyQuery(api, type, method, payload, signal) {
+  try {
+    const req = { rpcId: crypto.randomUUID(), payload }
+    const resp = signal ? await method(req, signal) : await method(req)
+    if (resp.result.ok) {
+      log(`query ok: ${type}`)
+      return { kind: type, ...resp.result.value }
+    }
+    log(`query rejected: ${type} -> ${resp.result.error.code}: ${resp.result.error.message}`)
+    return {
+      kind: 'error',
+      code: resp.result.error.code,
+      message: resp.result.error.message,
+      requestType: type,
+    }
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error)
+    log(`query failed: ${type} -> ${message}`)
+    return { kind: 'error', code: 'internal', message, requestType: type }
+  }
+}
+
+// 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
+// `host.listDirectory` would otherwise gate behind the `browse` capability.
+async function listServerDirectory(target) {
+  try {
+    const home = os.homedir()
+    const requested = target ? path.resolve(target) : home
+    const crumbs = []
+    let cur = requested
+    for (;;) {
+      crumbs.unshift({ name: cur === path.parse(cur).root ? cur : path.basename(cur), path: cur, hidden: false })
+      const parent = path.dirname(cur)
+      if (parent === cur) break
+      cur = parent
+    }
+    const entries = []
+    const dirents = await fsp.readdir(requested, { withFileTypes: true })
+    for (const dirent of dirents) {
+      if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue
+      entries.push({ name: dirent.name, path: path.join(requested, dirent.name), hidden: dirent.name.startsWith('.') })
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    log(`query ok: directories (${requested}, ${entries.length} entries)`)
+    return { kind: 'directories', path: requested, home, crumbs, entries, truncated: false }
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error)
+    log(`query failed: directories -> ${message}`)
+    return { kind: 'error', code: 'directory-unreadable', message, requestType: 'directories' }
+  }
+}
+
+// Validate one sessionId field; returns { value } or { error }.
+function requireSessionId(msg) {
+  const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+  if (!sessionId) {
+    return { error: { kind: 'error', code: 'bad-request', message: 'this request requires a sessionId', requestType: typeof msg.type === 'string' ? msg.type : 'query' } }
+  }
+  return { value: sessionId }
+}
+
+// ---------------------------------------------------------------------------
+// History frame sizing: raw session logs can be huge (trajectory, tool output,
+// context), so a single history response must never blow the client's
+// WebSocket frame limit. We cap the serialized size per frame, keep the NEWEST
+// suffix within the budget, and hand the client `hasMore` + `nextBeforeSeq` so
+// it can page backward. An optional `view: "conversation"` trims events that
+// are not needed for a chat page (token-level chunks, system-prompt headers)
+// and truncates oversized tool-result text.
+// ---------------------------------------------------------------------------
+const HISTORY_DEFAULT_MAX_BYTES = 4 * 1024 * 1024 // 4 MiB per frame
+const HISTORY_TOOL_RESULT_MAX_CHARS = 2000 // per text block in conversation view
+
+function eventBytes(event) {
+  return Buffer.byteLength(JSON.stringify(event), 'utf8')
+}
+
+// Trim one event for the conversation page: null drops it, otherwise a shallow
+// copy with oversized payloads truncated. The events come from the host RPC as
+// plain JSON, so copying is safe.
+function trimConversationEvent(event) {
+  switch (event.type) {
+    case 'assistant/chunk':
+    case 'request/header':
+      // token-level replay / system-prompt header: not rendered on the chat page
+      return null
+    case 'tool/result': {
+      const d = event.data || {}
+      const message = d.message
+      if (!message || !Array.isArray(message.content)) return event
+      let changed = false
+      const truncateBlock = (block) => {
+        if (!block || typeof block !== 'object') return block
+        if (block.type === 'text' && typeof block.text === 'string' && block.text.length > HISTORY_TOOL_RESULT_MAX_CHARS) {
+          changed = true
+          return { ...block, text: block.text.slice(0, HISTORY_TOOL_RESULT_MAX_CHARS) + '…' }
+        }
+        if (Array.isArray(block.content)) {
+          return { ...block, content: block.content.map(truncateBlock) }
+        }
+        return block
+      }
+      const content = message.content.map(truncateBlock)
+      if (!changed) return event
+      return { ...event, data: { ...d, message: { ...message, content } } }
+    }
+    default:
+      return event
+  }
+}
+
+// Keep the newest suffix of `events` (ascending seq) within `maxBytes`.
+// Always keeps the newest event even if it alone exceeds the budget (an event
+// cannot be split); drops older events beyond the budget. Returns the kept
+// events, their total serialized bytes, and whether anything was dropped.
+function capHistoryEvents(events, maxBytes, trim) {
+  const processed = trim ? events.map(trimConversationEvent).filter(Boolean) : events
+  if (processed.length === 0) return { events: [], bytes: 0, dropped: 0 }
+  let total = 0
+  let keptStart = processed.length
+  for (let i = processed.length - 1; i >= 0; i--) {
+    const size = eventBytes(processed[i])
+    if (keptStart === processed.length) {
+      // always keep the newest event
+      total = size
+      keptStart = i
+      continue
+    }
+    if (total + size > maxBytes) break
+    total += size
+    keptStart = i
+  }
+  return { events: processed.slice(keptStart), bytes: total, dropped: keptStart }
+}
+
+// Dispatch one mobile query frame; returns the wire frame to send back.
+async function handleQuery(api, typertGateway, agentDefaultModel, msg) {
+  if (msg.type === 'workspaces') {
+    return proxyQuery(api, 'workspaces', api.workspace.list.bind(api.workspace), {})
+  }
+  if (msg.type === 'sessions') {
+    return proxyQuery(api, 'sessions', api.sessions.list.bind(api.sessions), {})
+  }
+  if (msg.type === 'history') {
+    const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+    if (!sessionId) {
+      return { kind: 'error', code: 'bad-request', message: 'history requires a sessionId', requestType: 'history' }
+    }
+    const payload = { sessionId }
+    if (typeof msg.beforeSeq === 'number' && Number.isFinite(msg.beforeSeq)) payload.beforeSeq = msg.beforeSeq
+    if (typeof msg.maxMessages === 'number' && Number.isFinite(msg.maxMessages)) payload.maxMessages = msg.maxMessages
+    const frame = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), payload)
+    if (frame.kind === 'history') {
+      // Scheme A base: pass the raw SessionEvent list through (drop the host
+      // render intent); keep the projections block and echo the sessionId.
+      const rawEvents = Array.isArray(frame.events) ? frame.events.map((entry) => entry.event) : []
+      // Byte budget + optional conversation trim — keeps the frame under the
+      // client's WebSocket limit and pages the rest via nextBeforeSeq.
+      const maxBytes = typeof msg.maxBytes === 'number' && Number.isFinite(msg.maxBytes) && msg.maxBytes > 0
+        ? Math.floor(msg.maxBytes)
+        : HISTORY_DEFAULT_MAX_BYTES
+      const trim = msg.view === 'conversation'
+      const capped = capHistoryEvents(rawEvents, maxBytes, trim)
+      frame.events = capped.events
+      frame.sessionId = sessionId
+      frame.bytes = capped.bytes
+      if (trim) frame.view = 'conversation'
+      // hasMore combines the host's message-count pagination with byte-drop.
+      const apiHasMore = frame.hasMore === true
+      const byteDropped = capped.dropped > 0
+      frame.hasMore = apiHasMore || byteDropped > 0
+      if (frame.hasMore && capped.events.length > 0) {
+        frame.nextBeforeSeq = capped.events[0].seq // oldest kept event: page back from here
+      }
+    }
+    return frame
+  }
+  if (msg.type === 'search') {
+    const query = typeof msg.query === 'string' ? msg.query.trim() : ''
+    if (!query) {
+      return { kind: 'error', code: 'bad-request', message: 'search requires a query', requestType: 'search' }
+    }
+    return proxyQuery(api, 'search', api.sessions.search.bind(api.sessions), { query }, new AbortController().signal)
+  }
+  if (msg.type === 'host') {
+    return proxyQuery(api, 'host', api.host.describe.bind(api.host), {})
+  }
+  if (msg.type === 'default-model') {
+    try {
+      const selection = agentDefaultModel.currentSelection()
+      log(`default-model queried: ${selection.provider}/${selection.model}`)
+      return { kind: 'default-model', selection }
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error)
+      return { kind: 'error', code: 'internal', message, requestType: 'default-model' }
+    }
+  }
+  if (msg.type === 'save-default-model') {
+    const provider = typeof msg.provider === 'string' && msg.provider.trim() !== '' ? msg.provider.trim() : null
+    const model = typeof msg.model === 'string' && msg.model.trim() !== '' ? msg.model.trim() : null
+    if (!provider || !model) {
+      return { kind: 'error', code: 'bad-request', message: 'save-default-model requires provider and model', requestType: 'save-default-model' }
+    }
+    const selection = { provider, model }
+    if (typeof msg.reasoningEffort === 'string' && msg.reasoningEffort.trim() !== '') selection.reasoningEffort = msg.reasoningEffort.trim()
+    try {
+      await agentDefaultModel.saveSelection(selection)
+      log(`default model saved: ${provider}/${model}${selection.reasoningEffort ? ' (effort=' + selection.reasoningEffort + ')' : ''}`)
+      return { kind: 'save-default-model', saved: selection }
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error)
+      log(`save-default-model failed: ${message}`)
+      return { kind: 'error', code: 'internal', message, requestType: 'save-default-model' }
+    }
+  }
+  if (msg.type === 'fork') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const payload = { sessionId: sessionId.value }
+    if (typeof msg.atSeq === 'number' && Number.isFinite(msg.atSeq)) payload.atSeq = Math.floor(msg.atSeq)
+    const frame = await proxyQuery(api, 'fork', api.sessions.fork.bind(api.sessions), payload)
+    if (frame.kind === 'fork') {
+      log(`forked session ${sessionId.value} -> ${frame.sessionId}${payload.atSeq !== undefined ? ' at seq ' + payload.atSeq : ''}`)
+    }
+    return frame
+  }
+  if (msg.type === 'workspace-create') {
+    const wsPath = typeof msg.path === 'string' && msg.path.trim() !== '' ? msg.path.trim() : null
+    if (!wsPath) {
+      return { kind: 'error', code: 'bad-request', message: 'workspace-create requires a path', requestType: 'workspace-create' }
+    }
+    return proxyQuery(api, 'workspace-create', api.workspace.create.bind(api.workspace), { path: wsPath })
+  }
+  if (msg.type === 'directories') {
+    return listServerDirectory(typeof msg.path === 'string' && msg.path.trim() !== '' ? msg.path.trim() : undefined)
+  }
+  if (msg.type === 'models') {
+    const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+    if (sessionId) {
+      // per-session catalog: current selection + routable + full groups
+      return proxyQuery(api, 'models', api.sessions.models.bind(api.sessions), { sessionId })
+    }
+    // global catalog: every provider route, no session needed
+    return proxyQuery(api, 'models', api.llm.models.bind(api.llm), {})
+  }
+  if (msg.type === 'providers') {
+    return proxyQuery(api, 'providers', api.llm.providers.bind(api.llm), {})
+  }
+  if (msg.type === 'select-model') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const provider = typeof msg.provider === 'string' && msg.provider.trim() !== '' ? msg.provider.trim() : null
+    const model = typeof msg.model === 'string' && msg.model.trim() !== '' ? msg.model.trim() : null
+    if (!provider || !model) {
+      return { kind: 'error', code: 'bad-request', message: 'select-model requires provider and model', requestType: 'select-model' }
+    }
+    const payload = { sessionId: sessionId.value, provider, model }
+    if (typeof msg.reasoningEffort === 'string' && msg.reasoningEffort.trim() !== '') payload.reasoningEffort = msg.reasoningEffort.trim()
+    return proxyQuery(api, 'select-model', api.sessions.selectModel.bind(api.sessions), payload)
+  }
+  if (msg.type === 'permission-options') {
+    const frame = await proxyQuery(api, 'permission-options', api.settings.describe.bind(api.settings), {})
+    if (frame.kind !== 'permission-options') return frame
+    const out = {
+      kind: 'permission-options',
+      namespace: (frame.namespaces || []).find((n) => n.ns === 'permission') || null,
+    }
+    const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+    if (sessionId) {
+      const hist = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), { sessionId })
+      if (hist.kind === 'history' && hist.projections && hist.projections.values) {
+        out.sessionPermissions = hist.projections.values.permissions || null
+      }
+    }
+    return out
+  }
+  if (msg.type === 'permission') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const name = typeof msg.name === 'string' && msg.name.trim() !== '' ? msg.name.trim() : null
+    if (!name) {
+      return { kind: 'error', code: 'bad-request', message: 'permission requires a name', requestType: 'permission' }
+    }
+    // Execute the /permission command through the Typert Remote gateway — the
+    // same endpoint the browser calls (remote.commands.execute). This runs the
+    // command registry handler WITHOUT sending anything to the model, and the
+    // api-remotes agent lookup resumes cold sessions just like prompt does.
+    try {
+      const execution = await typertGateway.invoke({
+        namespace: 'commands',
+        method: 'execute',
+        args: { agentId: sessionId.value, line: '/permission ' + name },
+        signal: new AbortController().signal,
+      })
+      if (execution === undefined || execution === null) {
+        return { kind: 'error', code: 'unknown-command', message: 'command not found: /permission', requestType: 'permission', sessionId: sessionId.value }
+      }
+      log(`permission switched: session=${sessionId.value} preset=${name} (commandId=${execution.commandId})`)
+      return {
+        kind: 'permission',
+        sessionId: sessionId.value,
+        set: name,
+        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(`permission rejected: ${code}: ${message}`)
+      return { kind: 'error', code, message, requestType: 'permission', sessionId: sessionId.value }
+    }
+  }
+  if (msg.type === 'context-usage') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const hist = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), { sessionId: sessionId.value })
+    if (hist.kind !== 'history') return hist
+    const values = (hist.projections && hist.projections.values) || {}
+    return {
+      kind: 'context-usage',
+      sessionId: sessionId.value,
+      asOfSeq: hist.projections ? hist.projections.asOfSeq : undefined,
+      tokenUsage: values.tokenUsage || null,
+      contextPressure: values.contextPressure || null,
+    }
+  }
+  if (msg.type === 'session-stats') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const hist = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), { sessionId: sessionId.value })
+    if (hist.kind !== 'history') return hist
+    const values = (hist.projections && hist.projections.values) || {}
+    return {
+      kind: 'session-stats',
+      sessionId: sessionId.value,
+      asOfSeq: hist.projections ? hist.projections.asOfSeq : undefined,
+      sessionStats: values.sessionStats || null,
+      tokenUsage: values.tokenUsage || null,
+      contextPressure: values.contextPressure || null,
+    }
+  }
+  if (msg.type === 'agent-presets') {
+    return proxyQuery(api, 'agent-presets', api.agentPresets.list.bind(api.agentPresets), {})
+  }
+  if (msg.type === 'defaults') {
+    const frame = await proxyQuery(api, 'defaults', api.settings.describe.bind(api.settings), {})
+    if (frame.kind !== 'defaults') return frame
+    const agentPresetNs = (frame.namespaces || []).find((n) => n.ns === 'agent-presets')
+    const permissionNs = (frame.namespaces || []).find((n) => n.ns === 'permission')
+    return {
+      kind: 'defaults',
+      agentPresetDefault: agentPresetNs && agentPresetNs.value && agentPresetNs.value.default !== undefined ? agentPresetNs.value.default : null,
+      permissionDefault: permissionNs && permissionNs.value && permissionNs.value.defaultPreset !== undefined ? permissionNs.value.defaultPreset : null,
+    }
+  }
+  if (msg.type === 'set-default') {
+    const target = typeof msg.target === 'string' && msg.target.trim() !== '' ? msg.target.trim() : null
+    const value = typeof msg.value === 'string' && msg.value.trim() !== '' ? msg.value.trim() : null
+    if (target !== 'agent-preset' && target !== 'permission') {
+      return { kind: 'error', code: 'bad-request', message: 'set-default target must be "agent-preset" or "permission"', requestType: 'set-default' }
+    }
+    if (!value) {
+      return { kind: 'error', code: 'bad-request', message: 'set-default requires a value', requestType: 'set-default' }
+    }
+    const ns = target === 'agent-preset' ? 'agent-presets' : 'permission'
+    const patch = target === 'agent-preset' ? { default: value } : { defaultPreset: value }
+    const updated = await proxyQuery(api, 'set-default', api.settings.update.bind(api.settings), { ns, patch })
+    if (updated.kind !== 'set-default') return updated
+    log(`default updated: ${ns}.${Object.keys(patch)[0]} = ${value}`)
+    return { kind: 'set-default', target, value, applied: true, namespace: updated }
+  }
+  return null
+}
+
+module.exports = {
+  name: 'mobile-gateway',
+  // Hard dependencies: the gateway registers on the host web server and
+  // admits mobile messages through the host API gateway. Cordis must not
+  // activate this row before either service exists.
+  inject: ['webServer', 'apiProxy', 'typertGateway', 'agentDefaultModel'],
+  // exported for local tests; Cordis ignores unknown plugin fields
+  admitMessage,
+  handleQuery,
+  apply(ctx, config) {
+    const webServer = ctx.webServer
+    const api = ctx.apiProxy
+    const typertGateway = ctx.typertGateway
+    const agentDefaultModel = ctx.agentDefaultModel
+    const path = (config && config.path) || '/ws/mobile'
+    const wss = new WebSocketServer({ noServer: true })
+    const clients = new Set()
+    let counter = 0
+
+    log(`applying: path=${path}, webServer.port=${webServer.port}, apiProxy=${api ? 'present' : 'absent'}`)
+
+    const disposeUpgrade = webServer.registerUpgrade({
+      path,
+      handler(req, socket, head) {
+        wss.handleUpgrade(req, socket, head, (ws) => {
+          const id = ++counter
+          ws.filterSessionId = undefined
+          clients.add(ws)
+
+          ws.on('message', (data) => {
+            let msg
+            try {
+              msg = JSON.parse(data.toString())
+            } catch (error) {
+              ws.send(JSON.stringify({ kind: 'error', message: 'invalid json' }))
+              return
+            }
+            if (!msg || typeof msg.type !== 'string') return
+
+            if (msg.type === 'ping') {
+              ws.send(JSON.stringify({ kind: 'pong', at: Date.now() }))
+            } else if (msg.type === 'subscribe') {
+              ws.filterSessionId = typeof msg.sessionId === 'string' ? msg.sessionId : undefined
+              ws.send(JSON.stringify({ kind: 'subscribed', sessionId: ws.filterSessionId || null }))
+            } else if (msg.type === 'unsubscribe') {
+              ws.filterSessionId = undefined
+              ws.send(JSON.stringify({ kind: 'subscribed', sessionId: null }))
+            } else if (msg.type === 'message') {
+              admitMessage(api, msg).then((frame) => {
+                if (frame) ws.send(JSON.stringify(frame))
+              })
+            } else if (msg.type === 'workspaces' || msg.type === 'sessions' || msg.type === 'history' ||
+                       msg.type === 'search' || msg.type === 'host' || msg.type === 'directories' ||
+                       msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'select-model' ||
+                       msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
+                       msg.type === 'agent-presets' || msg.type === 'defaults' || msg.type === 'set-default' ||
+                       msg.type === 'session-stats' || msg.type === 'default-model' ||
+                       msg.type === 'save-default-model' || msg.type === 'fork' || msg.type === 'providers') {
+              handleQuery(api, typertGateway, agentDefaultModel, msg).then((frame) => {
+                if (frame) ws.send(JSON.stringify(frame))
+              })
+            } else {
+              ws.send(JSON.stringify({ kind: 'error', message: 'unknown message type: ' + msg.type }))
+            }
+          })
+
+          ws.on('close', () => {
+            clients.delete(ws)
+            log(`client disconnected (id=${id}, remaining=${clients.size})`)
+          })
+
+          log(`client connected (id=${id}, total=${clients.size})`)
+          ws.send(JSON.stringify({ kind: 'hello', protocol: 1, port: webServer.port, clients: clients.size }))
+        })
+      },
+    })
+    log(`upgrade route registered: ${path}`)
+
+    const disposeEvents = ctx.on('session/event', (session, event) => {
+      if (clients.size === 0) return
+      const wire = buildWireEvent(session, event)
+      if (!wire) return
+      const payload = JSON.stringify(wire)
+      for (const client of clients) {
+        if (client.filterSessionId && client.filterSessionId !== String(session.id)) continue
+        if (client.readyState === 1) client.send(payload)
+      }
+    })
+    log('session/event listener attached')
+
+    ctx.effect(() => () => {
+      disposeUpgrade()
+      disposeEvents()
+      for (const client of clients) client.terminate()
+      clients.clear()
+      wss.close()
+      log('plugin stopped, all sockets closed')
+    })
+  },
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "dsh-plugin-mobile-gateway",
+  "version": "0.1.17",
+  "description": "Persistent WebSocket gateway for dsh: exposes /ws/mobile on the web server and forwards agent session output to connected mobile clients",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "PROTOCOL.md"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT"
+}