dsh-remote-bridge 2.7.0 → 2.8.0

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.7.0-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.8.0-087f8c">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DeepSeek_Harness-plugin-1f2328">
   <img alt="Platforms" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-586069">
   <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-2da44e">
@@ -102,10 +102,10 @@ dsh plugin --profile web add dsh-remote-bridge
 dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com
 
 # 2. tarball from the GitHub release
-dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.7.1/dsh-remote-bridge-v2.7.1.tgz
 
 # 3. tarball from the Gitee release (faster from mainland China)
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.7.1/dsh-remote-bridge-v2.7.1.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -122,7 +122,7 @@ Restart DSH after installation, then open settings — The section is titled **
 To install a downloaded release archive:
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.7.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.7.1.tgz
 ```
 
 ## First connection
@@ -386,6 +386,10 @@ pnpm pack
 
 v2.5.0 was verified on DSH **0.2.1-rc.2** on real hardware: all 14/14 host services injected, the three jobs endpoints exercised, and the permission catalog returned the kernel's real three presets. The development baseline is upstream `dsh-v0.2.1-rc.2` (commit `687f282e8625c6b8d11ff58211a90524be2e4317`); see `engines.dsh` above for the supported range. CI covers Windows, Ubuntu, and macOS.
 
+**v2.7.1 verification status**: 76 test files / **701 cases** green; `typecheck`, `docs:check`, and the
+build all pass. This release touches only `agentFor` in `src/host/dsh-0.2-bridge.ts` plus its regression
+tests; every other byte is identical to v2.7.0.
+
 **v2.7.0 verification status**: 76 test files / 698 cases green, plus 8 Playwright browser cases
 (including the 375px narrow-viewport contract); `typecheck`, `docs:check`, and the build all pass.
 All four capabilities were exercised on an isolated DSH **0.2.1-rc.3** instance rather than inferred:
@@ -398,7 +402,17 @@ inside the zero-change set, and 4 slots retained with 0 removed.
 
 ## Project
 
-- Version: `v2.7.0`
+- Version: `v2.8.0`
+- **v2.7.1 is a defect-fix release**: the kernel's `sessionController.resolveAgent()` returns an
+  `{ agent }` / `{ error }` **envelope**, not the Agent itself (`dsh-api-session-controller/lib/index.js:365-368`
+  `liveAgent()` and `:221-246` `resolve()` both have that shape). The bridge used to hand the envelope
+  straight to `fileUploads.upload()`, so the kernel reading `agent.session.header.origin` blew up with
+  `DSH_TYPEERROR: Cannot read properties of undefined (reading 'header')` — on a real device this showed up
+  as "sending a file always fails with 400/500 and the message points nowhere", breaking both attachment
+  upload and agent-preset selection. The bridge now detects the envelope, unwraps `.agent` on success, and
+  rethrows `.error` as-is (keeping the kernel's stable code, so "session not found" is no longer flattened
+  into "session not running"), while still accepting a bare object. Three regression tests pin all three
+  return shapes.
 - **v2.7.0 aligns with DSH 0.2.1-rc.3 and lifts four capabilities**: (1) the model catalog now carries
   `contextWindow` / `maxTokens` — the kernel's `ModelCatalogModel` only has id/name/description, so the
   bridge resolves capacity through `llm.resolveModelInfo`, caching per `provider + model` for ten

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.7.0-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.8.0-087f8c">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DeepSeek_Harness-plugin-1f2328">
   <img alt="Platforms" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-586069">
   <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-2da44e">
@@ -93,10 +93,10 @@ dsh plugin --profile web add dsh-remote-bridge
 dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com
 
 # ② GitHub Release 的 tarball
-dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.7.1/dsh-remote-bridge-v2.7.1.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.7.1/dsh-remote-bridge-v2.7.1.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -112,7 +112,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.7.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.7.1.tgz
 ```
 
 ## 第一次使用
@@ -419,6 +419,9 @@ v2.5.0 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部
 权限档位目录返回内核真实三档。开发基线为上游 `dsh-v0.2.1-rc.2`（commit `687f282e8625c6b8d11ff58211a90524be2e4317`），
 兼容范围见上文 `engines.dsh`。CI 覆盖 Windows、Ubuntu 和 macOS。
 
+**v2.7.1 的验证状态**：76 个测试文件 / **701 个用例**全绿、`typecheck`/`docs:check`/构建通过。
+这一版只改 `src/host/dsh-0.2-bridge.ts` 的 `agentFor` 与对应回归测试，其余代码与 v2.7.0 逐字节相同。
+
 **v2.7.0 的验证状态**：76 个测试文件 / 698 个用例全绿、8 个 Playwright 浏览器用例
 （含 375px 窄屏契约）、`typecheck`/`docs:check`/构建通过。这一版的四项能力都在
 DSH **0.2.1-rc.3** 隔离实例上**实跑验过**，不是静态推断：插件清单返回
@@ -430,7 +433,15 @@ DSH **0.2.1-rc.3** 隔离实例上**实跑验过**，不是静态推断：插件
 
 ## 项目信息
 
-- 当前版本：`v2.7.0`
+- 当前版本：`v2.8.0`
+- **v2.7.1 是缺陷修复版**：内核 `sessionController.resolveAgent()` 返回的是 `{ agent }` / `{ error }`
+  **包装对象**而非 Agent 本体（`dsh-api-session-controller/lib/index.js:365-368` 的 `liveAgent()` 与
+  `:221-246` 的 `resolve()` 都是这个形状），桥此前把包装对象直接当 Agent 传给 `fileUploads.upload()`，
+  内核读 `agent.session.header.origin` 就炸成
+  `DSH_TYPEERROR: Cannot read properties of undefined (reading 'header')` —— 真机表现是
+  「发文件永远 400/500，报错信息完全指不到原因」，附件上传与 agent preset 选择两条路径都挂在这里。
+  现在识别包装形状、成功解出 `.agent`、失败原样抛 `.error`（保留内核稳定 code，「会话不存在」不再
+  被压成「会话没在跑」），同时保留裸对象兼容。新增 3 条回归测试钉住三种返回形状。
 - **v2.7.0 是对齐 DSH 0.2.1-rc.3 的能力提升版**：四项 —— ①模型目录补上 `contextWindow` / `maxTokens`
   （内核的 `ModelCatalogModel` 只有 id/name/description，容量得另走 `llm.resolveModelInfo`，桥按
   `provider + model` 缓存 10 分钟、失败不缓存、内核自己给了就不覆盖）；②插件清单多了右侧栏形态

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.7.0
+  version: 2.8.0
   description: |
     Live file and authorized DSH chat events. Reconnect clients must refresh
     REST state; unbounded replay is not provided.

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.7.0
+  version: 2.8.0
   description: Versioned file and chat BFF for mobile and third-party DSH clients. HTTP and HTTPS are both supported.
 servers:
   - url: http://127.0.0.1:3090/api/v1
@@ -24,7 +24,7 @@ paths:
                 properties:
                   ok: { type: boolean, const: true }
                   version: { type: string, const: v1 }
-                  pluginVersion: { type: string, const: 2.7.0 }
+                  pluginVersion: { type: string, const: 2.8.0 }
   /debug/host-services:
     get:
       operationId: hostServices
@@ -1319,6 +1319,332 @@ paths:
           schema: { type: string }
       responses:
         '202': { description: Cancellation accepted. }
+  /chat/sessions/{sessionId}/attachments/uploads:
+    post:
+      operationId: openChunkedAttachmentUpload
+      description: |
+        Opens — or resumes — a chunked attachment upload for one DSH session
+        (`docs/project/BFF-REST-CONTRACT.md` §1).
+
+        `chunkSize` is chosen by the server and must be obeyed by the client.
+        Re-posting the same `name` + `size` while an upload is still alive returns the
+        **same** `uploadId` plus `alreadyReceived` (the chunk indexes the server already
+        holds), which is how a dropped connection resumes without re-sending bytes.
+        Tickets expire one hour after opening; an expired or unknown id answers 404.
+
+        Errors: `400 BODY_INVALID` (bad name/size/contentType), `404 NOT_FOUND` (unknown
+        session), `413 PAYLOAD_TOO_LARGE` (`size` above the 256 MiB ceiling).
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ChunkedUploadOpenRequest' }
+      responses:
+        '201':
+          description: Upload ticket opened (or reused).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ChunkedUploadTicket' }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
+        '413': { $ref: '#/components/responses/Error' }
+    get:
+      operationId: listChunkedAttachmentUploads
+      description: |
+        Lists the session's unfinished upload tickets so a cold-started client can
+        resume without re-opening. Expired tickets are omitted; `missing` on each item
+        is the same chunk-index list `complete` would report.
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Unfinished uploads for this session, soonest expiry first.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: '#/components/schemas/ChunkedUploadStatus' }
+        '404': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/attachments/uploads/{uploadId}:
+    get:
+      operationId: getChunkedAttachmentUpload
+      description: |
+        Upload progress. `missing` is the authoritative retry list — the same array
+        `POST …/complete` returns in `details.missing` when chunks are absent.
+        Unknown, expired, or other-session ids all answer `404 NOT_FOUND`
+        (indistinguishable on purpose).
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: uploadId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Current ticket state.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ChunkedUploadStatus' }
+        '404': { $ref: '#/components/responses/Error' }
+    delete:
+      operationId: cancelChunkedAttachmentUpload
+      description: Discards the ticket and its spooled chunks. The id is dead afterwards (404).
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: uploadId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '204': { description: 'Ticket discarded; no body.' }
+        '404': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/attachments/uploads/{uploadId}/chunks/{index}:
+    put:
+      operationId: putChunkedAttachmentChunk
+      description: |
+        Stores one chunk. `index` is zero-based; repeating a `PUT` on the same index is
+        idempotent (the chunk is overwritten), which makes retries safe.
+
+        Byte length must be **exact**: `chunkSize` for every chunk but the last, and
+        `size - index * chunkSize` for the last one. A body longer than `chunkSize`
+        answers `413 PAYLOAD_TOO_LARGE`; a wrong-but-not-oversized length answers
+        `400 BODY_INVALID`; an index outside `[0, count)` answers `400 BODY_INVALID`.
+        The body is `application/octet-stream`, not JSON and not base64.
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: uploadId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: index
+          in: path
+          required: true
+          schema: { type: integer, minimum: 0 }
+      requestBody:
+        required: true
+        content:
+          application/octet-stream:
+            schema: { type: string, format: binary }
+      responses:
+        '200':
+          description: Chunk stored.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ChunkedUploadChunkResult' }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
+        '413': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/attachments/uploads/{uploadId}/complete:
+    post:
+      operationId: completeChunkedAttachmentUpload
+      description: |
+        Assembles the chunks and hands the bytes to the same kernel attachment path the
+        single-shot `POST /chat/sessions/{sessionId}/attachments` uses, so the resulting
+        receipt has the same meaning. On success the ticket is void (a second `complete`
+        answers 404).
+
+        Missing chunks answer `409 CONFLICT` with `details.missing` = the chunk indexes
+        still owed, so the client can send exactly those and retry.
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+        - name: uploadId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '201':
+          description: Attachment stored in the session.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ChunkedUploadReceipt' }
+        '404': { $ref: '#/components/responses/Error' }
+        '409': { $ref: '#/components/responses/Error' }
+  /chat/schedules:
+    get:
+      operationId: listSchedules
+      description: |
+        Lists cron-shaped schedules (`docs/project/BFF-REST-CONTRACT.md` §2).
+
+        Every item is a **cron projection** of the kernel record: `daily`/`weekly`
+        records are converted to their equivalent five-field cron; one-shot (`at`) and
+        fixed-interval (`every`) records cannot be expressed that way and are therefore
+        omitted rather than faked. `createdAt` is always `null` because the kernel record
+        carries no creation timestamp.
+      parameters:
+        - name: sessionId
+          in: query
+          required: false
+          schema: { type: string }
+      responses:
+        '200':
+          description: Schedules, optionally filtered to one session.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items: { $ref: '#/components/schemas/Schedule' }
+        '404': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
+    post:
+      operationId: createSchedule
+      description: |
+        Creates a cron schedule for one DSH session.
+
+        `cron` must be a five-field Vixie expression; `timezone` must be `UTC` or a real
+        IANA `Area/Location` name — anything else is `400 BODY_INVALID` before the kernel
+        is involved. An unknown session is `404 NOT_FOUND`.
+
+        `503 UPSTREAM_UNAVAILABLE` (with `details.reason`) means the kernel does not
+        expose schedule creation to the bridge at all — the client must hide the entry
+        point then, not retry.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ScheduleCreateRequest' }
+      responses:
+        '201':
+          description: Schedule created.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Schedule' }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
+  /chat/schedules/{id}:
+    patch:
+      operationId: updateSchedule
+      description: |
+        Updates only the fields present in the body.
+
+        `enabled: false` (pause) answers `400 BODY_INVALID` with
+        `details.reason: ENABLED_UNSUPPORTED` — this kernel has no pause operation, and a
+        silent success would show a paused reminder that keeps firing. Deleting is the
+        supported way to stop one. `enabled: true` on an already-ended schedule answers
+        `409 CONFLICT` (`details.reason: SCHEDULE_ENDED`).
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SchedulePatch' }
+      responses:
+        '200':
+          description: Updated schedule.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Schedule' }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
+        '409': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
+    delete:
+      operationId: deleteSchedule
+      description: Removes the schedule. Unknown id answers 404.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '204': { description: 'Deleted; no body.' }
+        '404': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
+  /chat/speech/catalog:
+    get:
+      operationId: getSpeechCatalog
+      description: |
+        Official speech input catalog (`docs/project/BFF-REST-CONTRACT.md` §3).
+
+        When the kernel has no speech service this is **not** a 404: it answers `200`
+        with `available: false`, an empty `providers` and a `reason`. That is the same
+        judgement the `/ws/mobile` `speech-catalog` frame makes, and it lets an old
+        client hide the entry point without treating a missing feature as a failure.
+      responses:
+        '200':
+          description: Catalog, or the unavailable view.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SpeechCatalog' }
+  /chat/speech/transcriptions:
+    post:
+      operationId: createSpeechTranscription
+      description: |
+        Transcribes one base64 WAV clip.
+
+        Decoded audio must be ≤ 4 MiB — the same ceiling `/ws/mobile` enforces, so a clip
+        does not become acceptable merely by taking the REST path; over the limit answers
+        `413 PAYLOAD_TOO_LARGE`. Transcription gives up after 180 s. An empty transcript
+        is a **success** (`text: ""`), not an error: silence is a legal answer.
+
+        Upstream failures answer `503 UPSTREAM_UNAVAILABLE` with `details.reason`; the
+        kernel's raw message is never echoed (it can contain host paths).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SpeechTranscriptionRequest' }
+      responses:
+        '200':
+          description: Transcript (possibly empty).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SpeechTranscription' }
+        '400': { $ref: '#/components/responses/Error' }
+        '413': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
+  /chat/speech/config:
+    put:
+      operationId: configureSpeech
+      description: |
+        Changes the selected provider and/or language and returns the catalog view
+        afterwards. At least one of `providerId`/`language` is required
+        (`400 BODY_INVALID` otherwise).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SpeechConfigPatch' }
+      responses:
+        '200':
+          description: Catalog after the change.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SpeechCatalog' }
+        '400': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
 components:
   securitySchemes:
     bearerAuth:
@@ -1889,3 +2215,159 @@ components:
         detail: { type: string, description: 'Terminal reason (`exit code: 3`); a recorded kill reason is merged in.' }
         startedAt: { type: integer, format: epoch-ms }
         finishedAt: { type: integer, format: epoch-ms, description: Absent while live. }
+    ChunkedUploadOpenRequest:
+      type: object
+      description: Opens or resumes a chunked upload. `size` is the exact byte count the client intends to send.
+      required: [name, size]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: 'Leaf file name only — path separators and control characters are refused.'
+        size:
+          type: integer
+          minimum: 1
+          maximum: 268435456
+          description: 'Declared byte count, 1..256 MiB; above the ceiling answers 413.'
+        contentType:
+          type: [string, 'null']
+          description: 'Optional MIME hint. Omitted → derived from the file extension at `complete`.'
+    ChunkedUploadTicket:
+      type: object
+      description: Server-decided ticket for one chunked upload.
+      required: [uploadId, chunkSize, expiresAt, alreadyReceived]
+      properties:
+        uploadId: { type: string, description: 'Opaque id, e.g. `up_9f3a…`; valid for one hour.' }
+        chunkSize: { type: integer, description: 'Fixed server-side slice size (1048576 today); clients must obey it.' }
+        expiresAt: { type: integer, format: epoch-ms }
+        alreadyReceived:
+          type: array
+          description: 'Chunks the server already holds — empty on a fresh open, populated when a resume matched.'
+          items: { type: integer, minimum: 0 }
+    ChunkedUploadStatus:
+      type: object
+      required: [uploadId, name, size, chunkSize, receivedCount, count, expiresAt, missing]
+      properties:
+        uploadId: { type: string }
+        name: { type: string }
+        size: { type: integer }
+        chunkSize: { type: integer }
+        receivedCount: { type: integer, description: 'Distinct chunks held so far.' }
+        count: { type: integer, description: 'Total chunks the declared size needs.' }
+        expiresAt: { type: integer, format: epoch-ms }
+        missing:
+          type: array
+          description: 'Chunk indexes still owed, ascending. Same list `complete` reports in `details.missing`.'
+          items: { type: integer, minimum: 0 }
+    ChunkedUploadChunkResult:
+      type: object
+      required: [uploadId, received, count]
+      properties:
+        uploadId: { type: string }
+        received: { type: integer, description: 'Distinct chunks held after this write.' }
+        count: { type: integer, description: 'Total chunks the declared size needs.' }
+    ChunkedUploadReceipt:
+      type: object
+      description: 'Stored attachment. Same meaning as the single-shot upload receipt; `name`/`contentType` may be server-derived.'
+      required: [id, receiptId, name, size, contentType, uploadedAt]
+      properties:
+        id: { type: string }
+        receiptId: { type: string }
+        name: { type: string }
+        size: { type: integer }
+        contentType: { type: string }
+        uploadedAt: { type: integer, format: epoch-ms }
+    Schedule:
+      type: object
+      description: |
+        Cron projection of one DSH reminder. `createdAt` is always null — the kernel
+        record has no creation timestamp; clients must not sort on it.
+      required: [id, sessionId, text, cron, timezone, enabled, createdAt, lastRunAt, nextRunAt]
+      properties:
+        id: { type: string, description: 'Opaque id, e.g. `sch_…`.' }
+        sessionId: { type: string }
+        text: { type: string, maxLength: 8000, description: 'The reminder body (kernel `prompt`).' }
+        cron: { type: string, description: 'Five-field Vixie expression, `minute hour day-of-month month day-of-week`.' }
+        timezone: { type: string, description: 'IANA zone the expression is evaluated in.' }
+        enabled: { type: boolean, description: 'True while the kernel still schedules it.' }
+        createdAt: { type: [integer, 'null'], format: epoch-ms, description: 'Always null in this kernel generation.' }
+        lastRunAt: { type: [integer, 'null'], format: epoch-ms, description: 'Last delivered occurrence, when the kernel reports one.' }
+        nextRunAt: { type: [integer, 'null'], format: epoch-ms, description: 'Next planned occurrence.' }
+    ScheduleCreateRequest:
+      type: object
+      required: [sessionId, text, cron, timezone]
+      properties:
+        sessionId: { type: string }
+        text: { type: string, minLength: 1, maxLength: 8000 }
+        cron: { type: string, description: 'Five-field Vixie expression; seconds and `@daily`-style macros are refused.' }
+        timezone: { type: string, description: '`UTC` or a real IANA `Area/Location` name.' }
+    SchedulePatch:
+      type: object
+      description: Send only the fields to change; omitted fields keep their stored value.
+      minProperties: 1
+      properties:
+        enabled:
+          type: boolean
+          description: '`false` is refused (400, `details.reason: ENABLED_UNSUPPORTED`) — this kernel cannot pause; delete instead.'
+        text: { type: string, minLength: 1, maxLength: 8000 }
+        cron: { type: string }
+        timezone: { type: string }
+    SpeechCatalog:
+      type: object
+      description: 'Official speech input state. `available: false` is a 200 answer, never a 404 — hide the entry point, do not error.'
+      required: [available, providers, selected, reason, maxAudioBytes, maxDurationSeconds]
+      properties:
+        available: { type: boolean }
+        providers:
+          type: array
+          items: { $ref: '#/components/schemas/SpeechProvider' }
+        selected:
+          oneOf:
+            - $ref: '#/components/schemas/SpeechSelection'
+            - type: 'null'
+        reason: { type: [string, 'null'], description: 'Why the feature is unavailable; null when it is available.' }
+        maxAudioBytes: { type: integer, description: 'Hard ceiling for one clip on this device (4 MiB today).' }
+        maxDurationSeconds: { type: [integer, 'null'], description: 'Kernel-declared clip length ceiling, when it reports one.' }
+    SpeechProvider:
+      type: object
+      required: [id, name, languages, location]
+      properties:
+        id: { type: string, examples: [builtin] }
+        name: { type: string, examples: [内置语音] }
+        languages:
+          type: array
+          items: { type: string }
+          examples: [[zh-CN, en-US]]
+        location: { type: string, enum: [host-local, cloud], description: 'Whether inference runs on the host or in a provider cloud.' }
+    SpeechSelection:
+      type: object
+      required: [providerId, language]
+      properties:
+        providerId: { type: string }
+        language: { type: string }
+    SpeechTranscriptionRequest:
+      type: object
+      required: [audio]
+      properties:
+        audio:
+          type: string
+          format: byte
+          description: 'Base64 WAV (16 kHz PCM16 recommended). Decoded bytes must be ≤ 4 MiB; non-canonical base64 is refused.'
+        providerId: { type: string, description: 'Defaults to the configured provider.' }
+        language: { type: string, description: 'Defaults to the configured language.' }
+    SpeechTranscription:
+      type: object
+      required: [text, providerId, language, durationMs]
+      properties:
+        text: { type: string, description: 'Empty string means "no speech recognised" — a success, not an error.' }
+        providerId: { type: string }
+        language: { type: string }
+        durationMs: { type: integer, description: 'Audio duration reported by the kernel, in milliseconds.' }
+    SpeechConfigPatch:
+      type: object
+      description: At least one field is required.
+      minProperties: 1
+      properties:
+        providerId: { type: string }
+        language: { type: string }