dsh-plugin-mobile-gateway 0.10.4 → 0.11.1

package/docs/dsh-rc2-mobile-integration.md

@@ -1,6 +1,6 @@
-# DSH 0.1.5-rc.2 移动端接入
+# DSH 0.2.1-rc.2 移动端接入
 
-本次源码以 DSH 0.1.5-rc.2 为唯一 Host 基线，不提供旧 Host 分支。配对、设备 token、双连接和 `dsh-mobile-v1` 保持原样；以下是新的实时订阅和历史坐标约定。App 需要同步实现本说明，不能把独立流帧交给旧的 `SessionEvent.seq` reducer。
+本次源码以 DSH 0.2.1-rc.2 为唯一 Host 基线，不提供旧 Host 分支。配对、设备 token、双连接和 `dsh-mobile-v1` 保持原样；以下是新的实时订阅和历史坐标约定。App 需要同步实现本说明，不能把独立流帧交给旧的 `SessionEvent.seq` reducer。
 
 ## 1. 能力与历史缓存
 
@@ -10,13 +10,13 @@
 {
   "kind": "hello",
   "protocol": 3,
-  "dshVersion": "0.1.5-rc.2",
-  "historyFormatVersion": 3,
+  "dshVersion": "0.2.1-rc.2",
+  "historyFormatVersion": 4,
   "capabilities": ["assistant-stream-v1", "history-format-version", "projection-baseline"]
 }
 ```
 
-示例只列出新增字段和能力；原有能力仍在。`dshVersion` 是本适配器的目标版本声明，非运行时 CLI 版本探测。握手协议值 3 与 Session 格式值 3 是独立概念。
+示例只列出新增字段和能力；原有能力仍在。`dshVersion` 是本适配器的目标版本声明，非运行时 CLI 版本探测。握手协议值 3 与 Session 格式值 4 是独立概念。
 
 缓存键至少包含 `(gatewayId, sessionId, historyFormatVersion)`。缓存没有格式版本或与服务端不同，必须丢弃该 Session 的旧历史、分页游标、fork 锚点及临时输出，重新安装基线。DSH 自己迁移磁盘日志，客户端不得迁移旧 seq。
 
@@ -42,7 +42,7 @@
   "sessionId": "s1",
   "subscriptionId": "<UUID>",
   "streamId": "<本次上游 follow 的 UUID>",
-  "historyFormatVersion": 3,
+  "historyFormatVersion": 4,
   "cursor": 41,
   "replace": true,
   "view": "conversation",
@@ -124,16 +124,16 @@
 { "type": "history", "sessionId": "s1", "view": "conversation" }
 ```
 
-返回值新增 `historyFormatVersion: 3`、`cursor`。conversation 视图隐藏 `system/message`、`request/header`、`request/context`，移除 Assistant 事件中的 `data.stream`，保留真实 seq、最终 message、usage 和 interrupted。默认原始视图保留完整内嵌 stream，用于按需读取轨迹。全部为隐藏事件的页仍返回可前进的 nextBeforeSeq。
+返回值新增 `historyFormatVersion: 4`、`cursor`。conversation 视图隐藏 `system/message`、`request/header`、`request/context`，移除 Assistant 事件中的 `data.stream`，保留真实 seq、最终 message、usage 和 interrupted。默认原始视图保留完整内嵌 stream，用于按需读取轨迹。全部为隐藏事件的页仍返回可前进的 nextBeforeSeq。
 
 携带游标必须同时携带读取该游标时的格式版本：
 
 ```json
-{ "type": "history", "sessionId": "s1", "beforeSeq": 20, "historyFormatVersion": 3 }
-{ "type": "fork", "sessionId": "s1", "atSeq": 42, "historyFormatVersion": 3 }
+{ "type": "history", "sessionId": "s1", "beforeSeq": 20, "historyFormatVersion": 4 }
+{ "type": "fork", "sessionId": "s1", "atSeq": 42, "historyFormatVersion": 4 }
 ```
 
-缺失版本、旧版本或版本不匹配，返回 `code: "history-format-mismatch"`、`resetRequired: true` 和当前 historyFormatVersion，且不会调用上游分页/fork。客户端必须重建缓存后再取新坐标，不能给旧坐标补一个 3 后重试。游标必须是非负安全整数。省略 atSeq 的 fork 仍表示从最近完成轮次分叉。
+缺失版本、旧版本或版本不匹配，返回 `code: "history-format-mismatch"`、`resetRequired: true` 和当前 historyFormatVersion，且不会调用上游分页/fork。客户端必须重建缓存后再取新坐标，不能给旧坐标补一个 4 后重试。游标必须是非负安全整数。省略 atSeq 的 fork 仍表示从最近完成轮次分叉。
 
 收到 session-snapshot 后，不要用晚到的普通 history 响应覆盖正在进行的订阅基线；更早历史页只合并到历史部分。这样可以避免独立查询与实时流交错造成回滚。
 

package/docs/file-upload-app-integration.md

@@ -0,0 +1,250 @@
+# 移动端普通文件上传对接指南
+
+## 功能与接入前提
+
+网关通过 `file-upload-v1` 支持 PDF、Office 文档、压缩包、音频及其他普通文件上传。文件先由网关分块接收和校验，再通过 DSH 官方流式接口进入附件存储，得到会话专属的上传凭证；App 随后把凭证与文字一起发送。文件不会被写到用户指定的工作区路径，也不会仅以文字路径代替附件。
+
+基线为 DSH 0.2.1-rc.2、`dsh-mobile-v1`、`hello.protocol: 3`、Session format 4。App 必须已完成设备配对。新增能力只在 `fileUploadsEnabled: true` 的已配对连接中公布；Host 还需组合官方文件上传服务和支持文件流式存储的附件后端。能力声明表示网关协议可用，实际 Host 不提供上传服务时返回 `file-upload-unavailable`。
+
+本功能提供上传、原生附件消息和历史引用。文件内容能否被 Agent 解析，仍取决于 DSH 的工具、技能和文件类型；上传 PDF 不等于模型直接获得 PDF 模态输入。图片继续使用原有 `images` 协议，语音转文字继续使用 `speech-transcribe`。
+
+## 官方 WebUI 的实现方式
+
+源码基于本机安装的 DSH 0.2.1-rc.2：
+
+| 官方模块与入口 | 行为 | App 对应实现 |
+|---|---|---|
+| `dsh-client-ui-conversation` 的 `beginFileUpload` | 创建可取消任务，维护 `uploading/ready/error`，上传成功保存 `receiptId/file` | 共享层保存每个草稿附件的状态、进度和凭证 |
+| 同模块的 `pumpFileUploads` | 按并发限制调度，不一次启动全部上传 | 客户端使用有界上传队列 |
+| 同模块的 `sendSession` | 非图片附件必须为 ready，发送 `{type:"file", receiptId}` | 等所有文件获得完成响应后再发送消息 |
+| `dsh-client-file-upload` 的 `ctx.fileUpload.upload` | Blob 经 Worker/XHR 上传并报告进度；stream 经 Worker/Fetch 传输；精确字节可走 Remote | 移动端改走现有已鉴权 WebSocket 的分块协议 |
+| 官方 Host 路由 `/api/session/uploadFileBinary` | 接收原始二进制流，返回 Session 专属凭证与持久附件引用 | 网关在进程内通过 Connection 路由注册表和固定 owner Peer 调用，不要求手机访问此 HTTP 路由 |
+| 官方 `SessionCommandController.prompt` | 校验同 Session 的凭证，转成原生 file 内容块，再进入 inbox | App 发送网关 `message.files`，不提交任意 `attachmentId` 或主机路径 |
+
+WebUI 切换 Session 时会为携带的文件重新上传和绑定。发送失败时保留草稿，成功后再清理。上传和消息发送是两个独立步骤，上传成功不会自动唤醒 Agent。凭证绑定精确的 Session 实例；Host 处理成功消息后会退休凭证，不能把它当作永久附件 ID。
+
+## 推荐流程与状态
+
+1. 检查 `hello.capabilities` 包含 `file-upload-v1`，并保留当前 `gatewayId` 和连接代际。
+2. 新草稿尚无会话时，先用已有 `session-create` 创建空白普通 Session。上传请求必须指定现有 `sessionId`，不能自动创建会话，也不支持子智能体会话。
+3. 系统选择器取得文件后，复制到 App 私有草稿目录。后台流式计算字节长度和 SHA-256；不要把文件全部读入内存。上传期间固定这份副本，不能改用可能变化的外部文件。
+4. 控制连接发送 open，按返回的 `chunkBytes` 逐块编码、发送并等待确认。
+5. 所有字节确认后发送 finish。UI 显示“处理中”，直到收到 `file-upload-completed`，才能标记为 ready。
+6. 对话连接发送 `message`，包含原始文字、可选图片和所有 ready 文件的 `receiptId`。没有文字的纯文件消息也可发送。
+7. 收到 `sent` 后清理对应草稿；实时和历史渲染使用持久 `file` 引用。发送失败保留草稿，根据错误决定重试还是重新上传。
+
+建议状态为：`preparing → opening → uploading → committing → ready → sending → sent`。各阶段允许进入 `error`；未完成上传可进入 `cancelling → cancelled`。每个草稿附件应有本地稳定 ID，并记录其所属网关、会话、连接代际、uploadId、字节数、摘要、已确认偏移、receiptId 和 file 引用。
+
+## 通道与请求关联
+
+上传的四类请求使用 **control 连接**，兼容 legacy 单连接。`message` 使用 **conversation 连接**，同样兼容 legacy 单连接。文件上传与消息发送可以位于两条不同连接，上传凭证由同一 Host 的目标 Session 校验。
+
+所有上传请求必须带 1 至 128 字符的非空 `requestId`，响应和错误回显。建议每次 RPC 使用新的 UUID；消息发送的 requestId 则固定为该次提交的 UUID，重试同一次提交时保持不变。`uploadId` 仅标识传输，不代替 requestId。
+
+上传中的 uploadId 只属于创建它的 WebSocket；即使另一个 socket 属于同一设备，也不能继续写入或取消。切换网关、Session 或连接代际后，不得把旧回调应用到新草稿。
+
+## 协议帧
+
+### 开始上传
+
+```json
+{
+  "type": "file-upload-open",
+  "requestId": "open-1",
+  "sessionId": "s1",
+  "name": "分析报告.pdf",
+  "size": 7,
+  "sha256": "7d1a54127b222502f5b79b5fb0803061152a44f92b37e23c6527baf665d4da9a"
+}
+```
+
+上例摘要对应 ASCII 内容 `abcdefg`，size 为解码后的精确字节数。摘要为 64 位十六进制，大小写均可；响应规范化为小写。允许零字节文件，使用空文件摘要，open 后直接 finish。
+
+```json
+{
+  "kind": "file-upload-opened",
+  "requestId": "open-1",
+  "uploadId": "upload-uuid",
+  "sessionId": "s1",
+  "name": "分析报告.pdf",
+  "size": 7,
+  "chunkBytes": 262144,
+  "maxBytes": 536870912,
+  "idleTimeoutMs": 120000
+}
+```
+
+`name` 仅为显示文件名，最多 255 个 UTF-16 code unit，不得包含目录分隔符、控制字符、NUL，也不能是 `.` 或 `..`。不要发送移动端完整路径。Host 仍会对最终文件名做清理，后续展示以完成响应中的 `file.name` 为准。
+
+不传 `path`、`cwd`、`parentSessionId` 或 `subagentMode`。通用文件不做扩展名白名单，字节原样存储，不执行、不解压。传输大小使用 64 位整数，并保证落在 JSON 安全整数范围；不要用字符串替代数值。
+
+### 发送分块
+
+```json
+{
+  "type": "file-upload-chunk",
+  "requestId": "chunk-1",
+  "uploadId": "upload-uuid",
+  "offset": 0,
+  "data": "YWJjZGVmZw=="
+}
+```
+
+```json
+{
+  "kind": "file-upload-chunk-accepted",
+  "requestId": "chunk-1",
+  "uploadId": "upload-uuid",
+  "sessionId": "s1",
+  "nextOffset": 7
+}
+```
+
+- `offset` 按解码后的字节计数，必须等于网关当前已接收字节数。下一块必须使用确认帧的 `nextOffset`。
+- 每块为非空、标准带 padding 的 Base64，不带 data URL 前缀、空白或换行。每块独立编码，不能按字符直接切割整文件 Base64。
+- 每个 uploadId 同时只进行一项操作，采用“发一块、等确认、再发下一块”。不同文件可以在服务端并发限制内并行。
+- `chunkBytes` 为解码后的块上限，会同时受 WebSocket payload 配置约束；不能硬编码为 256 KiB。最后一块可以更短。
+- 界面进度根据已确认字节数计算，不使用客户端已发出的 Base64 长度。100% 字节已传输仍须等待 finish 完成。
+
+### 校验并提交
+
+```json
+{ "type": "file-upload-finish", "requestId": "finish-1", "uploadId": "upload-uuid" }
+```
+
+```json
+{
+  "kind": "file-upload-completed",
+  "requestId": "finish-1",
+  "uploadId": "upload-uuid",
+  "sessionId": "s1",
+  "receiptId": "host-receipt-uuid",
+  "file": {
+    "attachmentId": "sha256:7d1a54127b222502f5b79b5fb0803061152a44f92b37e23c6527baf665d4da9a",
+    "name": "分析报告.pdf",
+    "bytes": 7
+  },
+  "sha256": "7d1a54127b222502f5b79b5fb0803061152a44f92b37e23c6527baf665d4da9a"
+}
+```
+
+网关先校验接收长度与摘要，再流式交给官方附件存储。只有 Host 返回合法凭证后才发送完成响应，并删除网关私有暂存文件。`attachmentId` 是不透明持久引用，即使当前带 `sha256:` 前缀，也不要依赖其字符串结构；`receiptId` 是发送新消息所需的会话权限凭证，两者不可互换。
+
+完成结果在原连接上短暂缓存，默认最多 2 分钟，且全网关最多保留 128 条，较早结果可能被逐出。同一连接再次发送相同 uploadId 的 finish，可以取得相同凭证，不重复创建 Host 上传。它不是跨连接断点续传，也不是永久查询接口。
+
+### 取消
+
+```json
+{ "type": "file-upload-cancel", "requestId": "cancel-1", "uploadId": "upload-uuid" }
+```
+
+```json
+{ "kind": "file-upload-cancelled", "requestId": "cancel-1", "uploadId": "upload-uuid", "sessionId": "s1" }
+```
+
+取消会中止接收或正在执行的 Host 提交，等待操作退出，再释放临时文件和并发名额；被取消的活动请求可能同时返回 `file-upload-cancelled` 错误，App 需按各自 requestId 结算。取消已完成的上传不会删除 Host 持久附件。提交与取消竞争时，Host 可能已经完成存储，因此不能承诺取消能回滚已落盘的附件。
+
+## 发送文件消息
+
+```json
+{
+  "type": "message",
+  "requestId": "submission-uuid",
+  "sessionId": "s1",
+  "text": "帮我分析这个报告",
+  "files": [{ "receiptId": "host-receipt-uuid" }],
+  "mode": "queue"
+}
+```
+
+```json
+{ "kind": "sent", "requestId": "submission-uuid", "sessionId": "s1", "mode": "queue" }
+```
+
+`files` 最多 20 项，不允许重复凭证；每项只需 `receiptId`。网关不会采信客户端提供的主机路径或持久 attachmentId。含文件消息必须有已存在的普通 sessionId 和 1 至 128 字符的 requestId。`text` 可省略，可同时携带已有 `images`，`mode` 可为 `queue` 或 `steer`。当前移动协议组装顺序为图片、文件、文字，不表达图片与文件任意交错排序。
+
+网关将文件项转成官方 `{type:"file", receiptId}`。Host 校验该凭证属于当前 Session，准入后转换为 `{type:"file", attachment}` 并处理凭证生命周期；跨 Session、伪造或已退休凭证返回 `session/attachment-invalid`。
+
+含文件消息的 requestId 会原样传给 Host。消息回执丢失但连接可恢复时，用同一个 requestId 重试完全相同的提交，Host 可根据 inbox 或已记录用户消息去重。不要给同一 ID 换正文，也不要在不明确是否送达时用新 ID 自动重复发送。Host 重启或 Session 实例替换后应先核对队列和原始历史中的 `source.rpcId`，凭证可能已失效。
+
+上传成功、消息发送失败时保留草稿；普通可恢复错误可重试原提交，凭证失效则重新上传。切换 Session 必须重新上传并取得新凭证，不能把旧会话凭证携带过去。关闭后重新打开 App 时，也不要仅凭数据库存过 receiptId 就判定文件 ready，应重新校验草稿所属连接与 Host 状态，必要时重新上传。
+
+## 实时消息与历史渲染
+
+持久用户消息的实时帧新增可选 `event.files`：
+
+```json
+{
+  "kind": "event", "sessionId": "s1", "seq": 42, "time": 1000,
+  "event": {
+    "type": "user/message", "text": "帮我分析这个报告", "source": "user",
+    "files": [{ "attachmentId": "opaque-file-id", "name": "分析报告.pdf", "bytes": 7 }]
+  }
+}
+```
+
+`history` 与 `session-snapshot` 保留原生 `{type,seq,time,data}` 结构，文件位于 `user/message.data.content[]` 的 `{type:"file",attachment:{attachmentId,name,bytes}}`。App reducer 必须识别 file 块，不能因未知类型丢掉整条纯文件消息；实时和历史按网关、会话、格式版本及 seq 合并，得到相同的附件卡片。
+
+推荐保存附件名称、字节数和持久引用，不在消息表内存储大段 Base64。发送设备可继续使用其私有草稿副本进行本地预览；在确认消息已入历史、无需重试后，再按缓存策略释放副本。
+
+本次不增加按 file attachmentId 下载附件的接口。已有 `attachment` 是图片读取接口，`file-download-*` 只读取会话工作目录中的文件，不能把 attachmentId 当路径传给它们。Host 附件存储可以在工作区之外；其他设备即使看见附件卡片，也不能据此假定已有远程预览链路。已有 `deliverables/presented` 文件卡片和本地文件链接仍按原下载协议处理。
+
+## 失败处理与资源生命周期
+
+错误帧为 `kind:"error"`，带 `requestType/requestId/code/message`，并在请求提供时带 sessionId 或 uploadId。错误文案用于显示，分支判断使用 code。
+
+| code | 处理方式 |
+|---|---|
+| `authentication-required` / `wrong-channel` | 检查设备配对和通道；即使调试关闭普通鉴权，也不能匿名上传或发送文件凭证 |
+| `file-upload-disabled` / `file-upload-unavailable` | 关闭当前上传入口或提示管理员检查配置；不可退回上传任意路径 |
+| `bad-request` / `session-not-found` / `subagent/attachment-invalid` | 修正文件名、请求字段或会话目标，子会话不提供此入口 |
+| `file-too-large` | 在选择阶段或 open 失败后提示大小上限，不自动反复上传 |
+| `file-upload-limit` / `file-upload-busy` | 降低并发，等待前一请求完成；不要同时发多个 chunk 或 finish |
+| `file-upload-offset` / `file-upload-invalid-data` / `file-upload-size` | 修正偏移、Base64 和长度；chunk 不是幂等请求，回执状态不明时取消并从头重传 |
+| `file-upload-incomplete` | 补齐剩余块后再 finish；当前已接收字节仍保留 |
+| `file-upload-checksum` | 当前传输已销毁，从固定本地副本重新计算后完整重传 |
+| `file-upload-not-found` / `file-upload-cancelled` | 传输属于其他连接、已取消、已过期或已结束；重新 open，不能从旧偏移续传 |
+| `file-upload-timeout` / `file-upload-failed` / `file-upload-invalid-response` / 文件系统错误码 | 当前操作可能失败；finish 的失败会清理传输，保留本地副本，提示重试；磁盘问题应先处理空间或权限 |
+| `session/attachment-invalid` | Host 不支持文件存储或凭证不属于该 Session、已失效；检查 Host 错误消息并视情况重新上传 |
+
+传输只在当前进程和 socket 内有效，不支持断线、重启后断点续传。socket 关闭或网关停止时中止活动上传并删除网关暂存；空闲传输由定时扫描回收，实际回收可晚于 idleTimeoutMs 一个扫描周期。提交阶段有独立超时，且同一传输的取消、写入和清理串行协调。
+
+finish 失败或取消时，官方附件存储可能已接收部分或全部内容；网关只保证清理自身暂存，不操作 Host 附件 GC。进程被强制杀死时，系统临时目录可能残留 `dsh-mobile-upload-*`，它们不是可恢复传输。
+
+## 网关配置
+
+| 配置 | 默认值 | 作用 |
+|---|---|---|
+| `fileUploadsEnabled` | `true` | 关闭后不公布上传能力，拒绝上传和含文件消息 |
+| `fileUploadMaxBytes` | 512 MiB | 单文件解码后大小上限 |
+| `fileUploadChunkBytes` | 256 KiB | 单块解码后字节上限，实际值还受 maxPayloadBytes 约束 |
+| `fileUploadMaxTransfers` | 4 | 全网关活动上传上限，包含尚未完成的 open 与 Host 提交 |
+| `fileUploadIdleMs` | 120000 | 空闲传输和完成结果缓存的保留时间 |
+| `fileUploadCommitTimeoutMs` | 180000 | 会话查询和 Host 附件提交的单次超时 |
+
+上传开关与 `fileDownloadsEnabled` 独立。手机只需现有 `/ws/mobile` 可达，Cloudflare Quick、命名 Tunnel 和 LAN 入口无需新增 HTTP 路由。网关为每个活动上传使用私有暂存目录，磁盘预算需考虑并发数乘单文件上限，以及官方存储提交时可能同时存在的副本。
+
+## App 实施顺序与验收
+
+KMM 共享层新增上传 DTO、按 requestId 分发的请求协调器、草稿附件 reducer 和有界队列；平台层负责系统文件选择、私有副本、后台摘要计算和文件流读取，UI 订阅共享状态。不要在主线程做文件复制、SHA-256 或 Base64 编码，也不要把每块数据长期存进状态流。
+
+Android 可使用系统文档选择器和 ContentResolver 流，iOS 可使用文档选择器并在授权访问期间复制到私有目录；两端都应保留原始显示文件名、真实字节长度，以及可重新读取的草稿副本。UI 展示“上传中、处理中、可发送、失败重试、取消”，移除附件时主动取消活动上传。
+
+客户端验收应包含：
+
+- PDF、Word、ZIP、音频及含 NUL 的二进制数据上传后与原始 SHA-256 一致；零字节文件可完成。
+- 超限文件、目录路径文件名、错误摘要、错误偏移和非法 Base64 得到可处理错误。
+- 纯文件、文件加文字、图片加文件加文字均能发送；历史恢复与实时消息展示一致。
+- 切 Session、切网关、断线和取消时旧任务不能污染新草稿；另一个 socket 不能操作原 uploadId。
+- 跨 Session 凭证被 Host 拒绝；同一次消息重试沿用 requestId，不重复进入队列。
+- finish 回执丢失时可在原连接缓存有效期内重试；其余未知进度情况从头重传。
+- 最多并发上传数、空闲回收、磁盘写入失败和 Host 取消不会留下仍占用的传输名额。
+- 上传成功不会自动发送给 Agent；App 必须等用户执行发送。
+
+自动验证入口：`npm test` 包含上传单元测试和真实 WebSocket 的鉴权、通道分流、上传到消息与实时文件引用测试。可选官方契约测试使用实际 DSH 流式路由、附件存储、凭证解析及 prompt 准入，所有数据位于测试临时目录：
+
+```bash
+DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/file-upload-official.test.mjs
+```
+
+代码入口：[上传管理器](../lib/file-upload.mjs)、[Host Adapter](../lib/dsh-host-adapter.mjs)、[消息与 WebSocket 接入](../lib/index.mjs)。这次不修改 App 页面，也不发布 npm；客户端完成后还需在设备上验证文件选择、后台编码、进度、取消和卡片展示。

package/lib/dsh-host-adapter.mjs

@@ -1,5 +1,7 @@
 import crypto from 'node:crypto'
 import os from 'node:os'
+import { Readable } from 'node:stream'
+import { sessionAddress } from './session-target.mjs'
 
 function requireRecord(value, endpoint) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
@@ -78,7 +80,7 @@ function sessionListArgs(request) {
  * descriptors. Its public methods intentionally match mobile-gateway domain
  * operations, not the upstream transport envelope.
  */
-export function createDshHostAdapter(typertGateway, peer) {
+export function createDshHostAdapter(typertGateway, peer, connection) {
   if (!typertGateway || typeof typertGateway.invoke !== 'function' || typeof typertGateway.stream !== 'function') {
     throw new Error('mobile-gateway requires the DSH Remote Gateway host service')
   }
@@ -96,6 +98,11 @@ export function createDshHostAdapter(typertGateway, peer) {
   const stream = (namespace, method, args, signal) => typertGateway.stream({
     namespace, method, args, peer, signal,
   })
+  // Dispatch in-process through the official authenticated route; no loopback
+  // HTTP listener, browser cookie, or public /api exposure is required.
+  const uploadHandler = connection?.createSharedFetchHandler?.('/api')
+  const uploadUrl = new URL('http://localhost/api/session/uploadFileBinary')
+  const uploadsAvailable = () => uploadHandler?.requestBodyMode({ method: 'POST', url: uploadUrl }) === 'streaming'
 
   const sessionSnapshot = async (request, signal) => {
     const frame = requireRecord(await firstStreamFrame(
@@ -105,12 +112,13 @@ export function createDshHostAdapter(typertGateway, peer) {
       requestArgs(request),
       signal,
     ), 'session/follow')
-    return readSessionSnapshot(frame, request.address.sessionId)
+    return readSessionSnapshot(frame, request.address.kind === 'subagent'
+      ? request.address.childSessionId : request.address.sessionId)
   }
 
   const history = async (payload, signal) => {
     const request = {
-      address: { kind: 'session', sessionId: payload.sessionId },
+      address: sessionAddress(payload),
       // Older-page requests need only the opening cursor/projections, not another large latest page.
       ...(payload.beforeSeq !== undefined ? { maxMessages: 1 }
         : payload.maxMessages === undefined ? {} : { maxMessages: payload.maxMessages }),
@@ -205,6 +213,33 @@ export function createDshHostAdapter(typertGateway, peer) {
   }
 
   return {
+    files: {
+      available: uploadsAvailable,
+      async upload({ sessionId, name, data }, signal) {
+        if (!uploadsAvailable()) throw Object.assign(new Error('The official file upload service is unavailable'), { code: 'file-upload-unavailable' })
+        const url = new URL(uploadUrl)
+        url.searchParams.set('sessionId', sessionId)
+        url.searchParams.set('name', name)
+        const uploadSignal = signal ? AbortSignal.any([signal, peer.signal]) : peer.signal
+        uploadSignal.throwIfAborted()
+        const source = Readable.from(data, { objectMode: false })
+        try {
+          const response = await uploadHandler.fetch(new Request(url, {
+            method: 'POST', headers: { 'content-type': 'application/octet-stream' },
+            body: Readable.toWeb(source), duplex: 'half',
+            signal: uploadSignal,
+          }), peer)
+          if (!response.ok) throw Object.assign(new Error(`Official file upload returned HTTP ${response.status}`), { code: 'file-upload-unavailable' })
+          const result = await response.json()
+          if (result.ok !== true) throw Object.assign(new Error(result.error?.message || 'Official file upload failed'),
+            { code: result.error?.code || 'file-upload-failed' })
+          return requireRecord(result.value, 'file upload')
+        } catch (error) {
+          uploadSignal.throwIfAborted()
+          throw error
+        } finally { source.destroy() }
+      },
+    },
     speech: {
       catalog: (signal) => invoke('speech', 'catalog', {}, signal),
       follow: (signal) => stream('speech', 'follow', {}, signal),
@@ -216,10 +251,22 @@ export function createDshHostAdapter(typertGateway, peer) {
       transcribe: (request, signal) => invoke('speech', 'transcribe', { request }, signal),
     },
     sessions: {
+      projections: (payload, signal) => invoke('session', 'projections', requestArgs(payload), signal),
       list: (payload = {}, signal) => invoke('session', 'list', sessionListArgs(payload), signal),
       search: (payload, signal) => invoke('session', 'search', requestArgs(payload), signal),
       create: (payload, signal) => invoke('session', 'create', requestArgs(payload), signal),
       prompt: (payload, signal) => serializeSession(payload.sessionId, async () => {
+        if (payload.parentSessionId !== undefined) {
+          if (payload.subagentMode !== 'continuable') {
+            throw Object.assign(new Error('only continuable subagents accept messages'), { code: 'subagent/not-resumable' })
+          }
+          return invoke('subagents', 'prompt', requestArgs({
+            requestId: payload.requestId ?? crypto.randomUUID(),
+            parentSessionId: payload.parentSessionId, childSessionId: payload.sessionId,
+            mode: 'continuable', delivery: payload.mode, content: payload.content,
+            ...(payload.clientTimeZone === undefined ? {} : { clientTimeZone: payload.clientTimeZone }),
+          }), signal)
+        }
         // Accepted input may not have reached turn/start yet. Keep that gap
         // locked; the persistent event or a subsequent read retires the marker.
         const alreadyAdmitted = admittedPrompts.has(payload.sessionId)
@@ -233,7 +280,13 @@ export function createDshHostAdapter(typertGateway, peer) {
       }),
       attachment: (payload, signal) => invoke('session', 'attachment', requestArgs(payload), signal),
       fork: (payload, signal) => invoke('session', 'fork', requestArgs(payload), signal),
-      cancel: (payload, signal) => invoke('session', 'cancel', requestArgs(payload), signal),
+      cancel: (payload, signal) => payload.parentSessionId === undefined
+        ? invoke('session', 'cancel', requestArgs(payload), signal)
+        : payload.subagentMode !== 'continuable'
+          ? Promise.reject(Object.assign(new Error('only continuable subagents accept interrupts'), { code: 'subagent/not-resumable' }))
+          : invoke('subagents', 'interruptByParent', {
+            parentSessionId: payload.parentSessionId, childSessionId: payload.sessionId, mode: 'continuable',
+          }, signal),
       updateQueue: (payload, signal) => invoke('session', 'updateQueue', requestArgs(payload), signal),
       rename: (payload, signal) => invoke('session', 'rename', requestArgs(payload), signal),
       selectModel: (payload, signal) => invoke('session', 'selectModel', requestArgs(payload), signal),
@@ -377,10 +430,10 @@ export function createDshHostAdapter(typertGateway, peer) {
     observeSessionEvent(sessionId, event) {
       if (event.type === 'turn/start') admittedPrompts.delete(sessionId)
     },
-    openSessionStream(sessionId, signal) {
+    openSessionStream(sessionId, signal, target = { sessionId }) {
       return stream('session', 'follow',
         // Bound the opening window at the Host; older records remain available via session.page.
-        requestArgs({ address: { kind: 'session', sessionId }, maxMessages: 12, assistantStream: true }),
+        requestArgs({ address: sessionAddress(target), maxMessages: 12, assistantStream: true }),
         signal,
       )
     },

package/lib/file-upload.mjs

@@ -0,0 +1,205 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+export const FILE_UPLOAD_REQUEST_TYPES = new Set([
+  'file-upload-open', 'file-upload-chunk', 'file-upload-finish', 'file-upload-cancel',
+])
+export const FILE_UPLOAD_DEFAULTS = Object.freeze({
+  fileUploadsEnabled: true,
+  fileUploadMaxBytes: 512 * 1024 * 1024,
+  fileUploadChunkBytes: 256 * 1024,
+  fileUploadMaxTransfers: 4,
+  fileUploadIdleMs: 2 * 60 * 1000,
+  fileUploadCommitTimeoutMs: 180_000,
+})
+
+function failure(code, message) { return Object.assign(new Error(message), { code }) }
+function check(condition, code, message) { if (!condition) throw failure(code, message) }
+function validName(name) {
+  return typeof name === 'string' && name.trim().length > 0 && name.length <= 255
+    && name !== '.' && name !== '..' && !/[\x00-\x1f\x7f/\\]/.test(name)
+}
+
+// Receive bounded chunks in a private spool, verify exact bytes, then use DSH's
+// streaming attachment admission. Never interpret client names as host paths.
+export function createFileUploadManager(api, configuration = {}) {
+  const options = { ...FILE_UPLOAD_DEFAULTS, ...configuration }
+  const payloadLimit = Math.max(0, Math.floor(((options.maxPayloadBytes ?? 144 * 1024 * 1024) - 4096) / 4) * 3)
+  const chunkBytes = Math.min(options.fileUploadChunkBytes, payloadLimit)
+  const transfers = new Map()
+  const completed = new Map()
+  const closedClients = new WeakSet()
+  let disposed = false
+
+  const cleanup = async transfer => {
+    if (transfer.handle) {
+      await transfer.handle.close().catch(() => {})
+      transfer.handle = undefined
+    }
+    if (transfer.directory) await fsp.rm(transfer.directory, { recursive: true, force: true })
+  }
+  const release = async transfer => {
+    try { await cleanup(transfer) } finally { transfers.delete(transfer.id) }
+  }
+  const stop = async transfer => {
+    transfer.abort.abort(failure('file-upload-cancelled', 'File upload cancelled'))
+    // Keep the slot reserved until its writes/Host commit have actually stopped.
+    await transfer.operation?.catch(() => {})
+    await release(transfer)
+  }
+  const assertActive = transfer => {
+    transfer.abort.signal.throwIfAborted()
+    check(!disposed && !closedClients.has(transfer.client), 'file-upload-cancelled', 'Upload connection closed')
+  }
+  const run = (transfer, task) => {
+    check(!transfer.operation, 'file-upload-busy', 'An upload operation is already in progress')
+    const operation = task()
+    transfer.operation = operation
+    return operation.finally(() => { if (transfer.operation === operation) transfer.operation = undefined })
+  }
+
+  const open = async (client, msg) => {
+    check(!disposed && !closedClients.has(client), 'file-upload-cancelled', 'Upload connection closed')
+    check(api.files?.available(), 'file-upload-unavailable', 'The official file upload service is unavailable')
+    check(typeof msg.sessionId === 'string' && msg.sessionId.trim(), 'bad-request', 'An existing sessionId is required')
+    check(msg.parentSessionId === undefined && msg.subagentMode === undefined, 'subagent/attachment-invalid', 'Subagent file uploads are unsupported')
+    check(validName(msg.name), 'bad-request', 'name must be a leaf filename of 1..255 characters without control characters')
+    check(Number.isSafeInteger(msg.size) && msg.size >= 0, 'bad-request', 'size must be a nonnegative safe integer')
+    check(msg.size <= options.fileUploadMaxBytes, 'file-too-large', 'File exceeds the configured upload limit')
+    check(typeof msg.sha256 === 'string' && /^[a-fA-F0-9]{64}$/.test(msg.sha256), 'bad-request', 'sha256 must contain 64 hexadecimal digits')
+    check(transfers.size < options.fileUploadMaxTransfers, 'file-upload-limit', 'Too many active uploads')
+    const transfer = {
+      id: crypto.randomUUID(), client, sessionId: msg.sessionId.trim(), name: msg.name,
+      size: msg.size, sha256: msg.sha256.toLowerCase(), offset: 0, hash: crypto.createHash('sha256'),
+      abort: new AbortController(), lastActiveAt: Date.now(),
+    }
+    transfers.set(transfer.id, transfer)
+    try {
+      return await run(transfer, async () => {
+        const sessions = await api.sessions.list({}, AbortSignal.any([
+          transfer.abort.signal, AbortSignal.timeout(options.fileUploadCommitTimeoutMs),
+        ]))
+        check(sessions.items?.some(item => item.sessionId === transfer.sessionId && item.origin !== 'subagent'),
+          'session-not-found', 'No visible ordinary session exists with this ID')
+        assertActive(transfer)
+        transfer.directory = await fsp.mkdtemp(path.join(os.tmpdir(), 'dsh-mobile-upload-'))
+        transfer.path = path.join(transfer.directory, 'payload')
+        transfer.handle = await fsp.open(transfer.path, 'wx', 0o600)
+        assertActive(transfer)
+        return { kind: 'file-upload-opened', uploadId: transfer.id, sessionId: transfer.sessionId,
+          name: transfer.name, size: transfer.size, chunkBytes, maxBytes: options.fileUploadMaxBytes,
+          idleTimeoutMs: options.fileUploadIdleMs }
+      })
+    } catch (error) {
+      await release(transfer)
+      throw error
+    }
+  }
+
+  const receive = async (client, msg) => {
+    if (msg.type === 'file-upload-open') return open(client, msg)
+    check(typeof msg.uploadId === 'string' && msg.uploadId.length > 0, 'bad-request', 'uploadId is required')
+    const done = completed.get(msg.uploadId)
+    if (done?.client === client && msg.type === 'file-upload-finish') return done.frame
+    const transfer = transfers.get(msg.uploadId)
+    check(transfer?.client === client, 'file-upload-not-found', 'Upload is unknown or belongs to another connection')
+    if (msg.type === 'file-upload-cancel') {
+      await stop(transfer)
+      return { kind: 'file-upload-cancelled', uploadId: msg.uploadId, sessionId: transfer.sessionId }
+    }
+    assertActive(transfer)
+    return run(transfer, async () => {
+      transfer.lastActiveAt = Date.now()
+      if (msg.type === 'file-upload-chunk') {
+        check(Number.isSafeInteger(msg.offset) && msg.offset === transfer.offset,
+          'file-upload-offset', 'offset must equal the next expected byte')
+        check(typeof msg.data === 'string' && msg.data.length > 0 && msg.data.length <= Math.ceil(chunkBytes / 3) * 4,
+          'file-upload-invalid-data', 'Chunk must be nonempty canonical base64 within chunkBytes')
+        const bytes = Buffer.from(msg.data, 'base64')
+        check(bytes.length > 0 && bytes.length <= chunkBytes && bytes.toString('base64') === msg.data,
+          'file-upload-invalid-data', 'Chunk must be nonempty canonical base64 within chunkBytes')
+        check(transfer.offset + bytes.length <= transfer.size, 'file-upload-size', 'Chunk exceeds declared size')
+        try {
+          let written = 0
+          while (written < bytes.length) {
+            assertActive(transfer)
+            const result = await transfer.handle.write(bytes, written, bytes.length - written, transfer.offset + written)
+            check(result.bytesWritten > 0, 'file-upload-write-failed', 'Upload write made no progress')
+            written += result.bytesWritten
+          }
+        } catch (error) {
+          transfer.abort.abort(error)
+          await release(transfer)
+          throw error
+        }
+        assertActive(transfer)
+        transfer.hash.update(bytes)
+        transfer.offset += bytes.length
+        return { kind: 'file-upload-chunk-accepted', uploadId: transfer.id, sessionId: transfer.sessionId, nextOffset: transfer.offset }
+      }
+      check(transfer.offset === transfer.size, 'file-upload-incomplete', 'Not all declared bytes have arrived')
+      try {
+        check(transfer.hash.digest('hex') === transfer.sha256, 'file-upload-checksum', 'SHA-256 does not match the uploaded bytes')
+        await transfer.handle.close()
+        transfer.handle = undefined
+        const signal = AbortSignal.any([transfer.abort.signal, AbortSignal.timeout(options.fileUploadCommitTimeoutMs)])
+        const result = await api.files.upload({ sessionId: transfer.sessionId, name: transfer.name,
+          data: fs.createReadStream(transfer.path, { highWaterMark: chunkBytes }) }, signal)
+        signal.throwIfAborted()
+        assertActive(transfer)
+        check(typeof result.receiptId === 'string' && result.receiptId.length > 0
+          && typeof result.file?.attachmentId === 'string' && result.file.attachmentId.length > 0
+          && typeof result.file.name === 'string' && result.file.bytes === transfer.size,
+        'file-upload-invalid-response', 'Official upload result does not match the declared file')
+        const frame = { kind: 'file-upload-completed', uploadId: transfer.id, sessionId: transfer.sessionId,
+          receiptId: result.receiptId, file: { attachmentId: result.file.attachmentId, name: result.file.name, bytes: result.file.bytes },
+          sha256: transfer.sha256 }
+        completed.set(transfer.id, { client, frame, lastActiveAt: Date.now() })
+        if (completed.size > 128) completed.delete(completed.keys().next().value)
+        return frame
+      } finally {
+        await release(transfer)
+      }
+    })
+  }
+
+  return {
+    async handle(client, msg) {
+      const correlation = {
+        ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}),
+        ...(typeof msg.sessionId === 'string' ? { sessionId: msg.sessionId } : {}),
+        ...(typeof msg.uploadId === 'string' ? { uploadId: msg.uploadId } : {}),
+      }
+      try {
+        check(options.fileUploadsEnabled, 'file-upload-disabled', 'File uploads are disabled')
+        check(typeof msg.requestId === 'string' && msg.requestId.trim().length > 0 && msg.requestId.length <= 128,
+          'bad-request', 'requestId must contain 1..128 characters')
+        const frame = await receive(client, msg)
+        return { ...frame, requestId: msg.requestId }
+      } catch (error) {
+        return { kind: 'error', requestType: msg.type, ...correlation,
+          code: error.name === 'TimeoutError' ? 'file-upload-timeout'
+            : typeof error.code === 'string' ? error.code : 'file-upload-failed',
+          message: error.message || 'File upload failed' }
+      }
+    },
+    async closeClient(client) {
+      closedClients.add(client)
+      await Promise.all([...transfers.values()].filter(transfer => transfer.client === client).map(stop))
+      for (const [id, done] of completed) if (done.client === client) completed.delete(id)
+    },
+    async expire() {
+      const cutoff = Date.now() - options.fileUploadIdleMs
+      await Promise.all([...transfers.values()].filter(transfer => !transfer.operation && transfer.lastActiveAt < cutoff).map(stop))
+      for (const [id, done] of completed) if (done.lastActiveAt < cutoff) completed.delete(id)
+    },
+    async dispose() {
+      disposed = true
+      await Promise.all([...transfers.values()].map(stop))
+      completed.clear()
+    },
+  }
+}