dsh-remote-bridge 2.4.1 → 2.4.3

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.1-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.3-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">
@@ -27,6 +27,18 @@ The interface is bilingual and defaults to Chinese. Prebuilt packages run on Win
 > with `dsh-api-gateway`, leaving the upstream release unable to start on 0.2.x — it surfaces as
 > "adding an authorized root returns 405". Background, rationale, changes, and test results are in
 > [DSH 0.2.x compatibility notes](./docs/project/DSH-0.2-COMPAT.md).
+>
+> **Adaptation to DSH 0.2.1-rc.2** (rechecked 2026-10-20; see `docs/project/DSH-0.2.1-ADAPTATION.md`):
+> this plugin **deliberately imports no `@deepseek-ai/*` package** — every host service is consumed
+> through a structural type injected by the running Host (see the header comment in
+> `src/host/dsh-0.2-bridge.ts`). Checked one by one against the installed `0.2.1-rc.2` packages:
+> all 10 `inject` service names in `cordis.patch.yml` **still exist with unchanged signatures**, and
+> `engines.dsh` is recognized by the 0.2.1 kernel (`prepareProfileEntries` in
+> `dsh-app-boot/lib/index.js`) — an unmet range only sets that entry to `disabled` and prints to
+> stderr; **the host process does not exit**. So no code change is needed to run on `0.2.1-rc.2`.
+> The only point still needing on-device confirmation is the injection surface of
+> `permissionPresets` (never injectable on 0.2.0 either, where the plugin already falls back to a
+> built-in catalog).
 
 ## What it looks like
 
@@ -63,7 +75,12 @@ So seeing `dsh-workspace` in a REST address or the state directory is **expected
 ### Requirements
 
 - A working DeepSeek Harness WebUI installation
-- DSH kernel `0.1.x` or `0.2.x` (0.2.x is supported by this branch's compatibility layer — see [DSH 0.2.x compatibility notes](./docs/project/DSH-0.2-COMPAT.md))
+- DSH kernel **`>=0.2.0-rc.2 <0.3.0`** (compatible with `0.2.0-rc.2` and every later `0.2.x`, including
+  `0.2.1-rc.2`; supported by this branch's compatibility layer — see
+  [DSH 0.2.x compatibility notes](./docs/project/DSH-0.2-COMPAT.md)).
+  `package.json` declares the same range under `engines.dsh`; the kernel resolves it with semver and
+  only **disables** the plugin when unmet (the host process keeps running), with the user able to
+  grant an exact-version exemption as the kernel suggests.
 - Node.js `^22.19.0` or `>=24.0.0`
 - Port `3090`, or another available port
 
@@ -77,10 +94,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.4.1/dsh-remote-bridge-v2.4.1.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.4.3/dsh-remote-bridge-v2.4.3.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.4.1/dsh-remote-bridge-v2.4.1.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.4.3/dsh-remote-bridge-v2.4.3.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -97,7 +114,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.4.1.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.4.3.tgz
 ```
 
 ## First connection
@@ -329,13 +346,13 @@ pnpm pack
 
 `pnpm check` covers type-checking, documentation consistency, and tests. It currently passes **30 test files / 226 cases**, plus **4 browser-layer cases** (Playwright measuring real computed styles).
 
-`npm pack` produces roughly a **0.29 MB** archive: 2.2.0 dropped the standalone page and its editor dependencies and turned source maps off, down from 1.72 MB.
+`npm pack` produces roughly a **0.55 MB** archive (v2.4.3 measured 572,951 bytes, SHA-256 `38f25c10…299c93`): 2.2.0 dropped the standalone page and its editor dependencies and turned source maps off, down from 1.72 MB; it has since grown slightly with projection passthrough and the permission BFF.
 
-v2.4.1 was developed against DSH `master@47f943859bef60e4160492346772ded9b24f765a`. CI covers Windows, Ubuntu, and macOS.
+v2.4.3 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 `master@47f943859bef60e4160492346772ded9b24f765a` (kernel 0.2.0-rc.2); see `engines.dsh` above for the supported range. CI covers Windows, Ubuntu, and macOS.
 
 ## Project
 
-- Version: `v2.4.1`
+- Version: `v2.4.3`
 - Author: upstream [Hakunm](https://github.com/Hakunm); this fork maintained by [westanke](https://github.com/westanke)
 - Repository: [GitHub](https://github.com/westanke/dsh-remote-bridge) · [Gitee](https://gitee.com/westanke/dsh-remote-bridge)
 - npm: [`dsh-remote-bridge`](https://www.npmjs.com/package/dsh-remote-bridge) ([mainland-China mirror](https://registry.npmmirror.com/dsh-remote-bridge))

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.1-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.3-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">
@@ -25,6 +25,14 @@
 > 0.2.x 用 `dsh-api-gateway` 替换了提供 `apiProxy` 服务的 `dsh-host-apiproxy`，导致上游版本在
 > 0.2.x 上无法启动（表现为「添加根目录返回 405」）。兼容层的完整说明——基于什么、为什么、改了什么、
 > 测了什么——见 [DSH 0.2.x 兼容性适配说明](./docs/project/DSH-0.2-COMPAT.md)。
+>
+> **对 DSH 0.2.1-rc.2 的适配结论**（2026-10-20 复核，依据 `/media/wangke/OFFICE/workspace/dsh-remote-bridge/docs/project/DSH-0.2.1-ADAPTATION.md`）：
+> 本插件**刻意不 import 任何 `@deepseek-ai/*` 包**，全部宿主服务经结构类型 + Host 注入消费
+> （见 `src/host/dsh-0.2-bridge.ts` 头注释）。逐一到 `0.2.1-rc.2` 实装包核对：`cordis.patch.yml`
+> 的 10 项 `inject` 服务名**全部仍存在且签名未变**，`engines.dsh` 在 0.2.1 被内核识别
+> （`dsh-app-boot/lib/index.js` 的 `prepareProfileEntries`），不满足时只把该 entry 置
+> `disabled` 并打 stderr，**宿主进程不退出**。故本插件无需改码即可运行于 `0.2.1-rc.2`。
+> 唯一需真机定论的是 `permissionPresets` 的注入面（0.2.0 上即注不进，已降级到内置目录）。
 
 ## 实际效果
 
@@ -62,7 +70,8 @@
 ### 环境要求
 
 - 已安装并能正常启动的 DeepSeek Harness WebUI
-- DSH 内核 `0.1.x` 或 `0.2.x`（0.2.x 由本分支的兼容层支持，见 [DSH 0.2.x 兼容性适配说明](./docs/project/DSH-0.2-COMPAT.md)）
+- DSH 内核 **`>=0.2.0-rc.2 <0.3.0`**（兼容 `0.2.0-rc.2` 及其后全部 `0.2.x`，含 `0.2.1-rc.2`；由本分支的兼容层支持，见 [DSH 0.2.x 兼容性适配说明](./docs/project/DSH-0.2-COMPAT.md)）。
+  `package.json` 的 `engines.dsh` 已声明同一范围 —— 内核按 semver 裁决，不满足时该插件被**禁用**（宿主进程不退出），用户可按内核提示授予精确版本豁免。
 - Node.js `^22.19.0` 或 `>=24.0.0`
 - 默认端口 `3090` 可用，或准备一个其他端口
 
@@ -76,10 +85,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.4.1/dsh-remote-bridge-v2.4.1.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.4.3/dsh-remote-bridge-v2.4.3.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.4.1/dsh-remote-bridge-v2.4.1.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.4.3/dsh-remote-bridge-v2.4.3.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -95,7 +104,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.4.1.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.4.3.tgz
 ```
 
 ## 第一次使用
@@ -323,13 +332,15 @@ pnpm pack
 
 `pnpm check` 覆盖类型检查、文档一致性与测试；当前 **30 个测试文件 / 226 个用例**，外加 **4 个浏览器层用例**（Playwright 实测量出的计算样式），全部通过。
 
-`npm pack` 的产物约 **0.29 MB**：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后，从 1.72 MB 降下来。
+`npm pack` 的产物约 **0.55 MB**（v2.4.3 实测 572,951 字节，SHA-256 `38f25c10…299c93`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传与权限 BFF 小幅增长。
 
-v2.4.1 基于 DSH `master@47f943859bef60e4160492346772ded9b24f765a` 开发，CI 覆盖 Windows、Ubuntu 和 macOS。
+v2.4.3 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部可注入、三个 jobs 端点实测通过、
+权限档位目录返回内核真实三档。开发基线为 `master@47f943859bef60e4160492346772ded9b24f765a`（内核 0.2.0-rc.2），
+兼容范围见上文 `engines.dsh`。CI 覆盖 Windows、Ubuntu 和 macOS。
 
 ## 项目信息
 
-- 当前版本：`v2.4.1`
+- 当前版本：`v2.4.3`
 - 作者：上游 [Hakunm](https://github.com/Hakunm)，本 fork 维护 [westanke](https://github.com/westanke)
 - 仓库：[GitHub](https://github.com/westanke/dsh-remote-bridge) · [Gitee](https://gitee.com/westanke/dsh-remote-bridge)
 - npm：[`dsh-remote-bridge`](https://www.npmjs.com/package/dsh-remote-bridge)（[国内镜像](https://registry.npmmirror.com/dsh-remote-bridge)）

package/cordis.patch.yml

@@ -6,7 +6,38 @@
       # DSH 0.2.x host services (see src/host/dsh-0.2-bridge.ts). The pre-0.2
       # `apiProxy` facade is rebuilt from these; `@deepseek-ai/dsh-host-apiproxy`
       # stopped shipping at 0.1.1-rc.2 and nothing provides `apiProxy` after it.
-      inject: [sessionController, workspaceController, workspaceRegistry, settingsController, credentialsController, agentPresets, llm, webServer, agents, commands]
+      #
+      # ⚠️ 这份列表**必须**与 `src/index.ts` 导出的 `inject` 完全一致。
+      # 原因（2026-10-20 实测，代价是三次重启）：patch 里的 `inject` **覆盖**
+      # 插件自己导出的 `inject`，不是取并集。于是插件声明了、这里漏了的服务
+      # 读起来会报 `cannot get property "x" without inject` ——
+      # 与「内核压根没有这个服务」的报错**一模一样**，肉眼分不出来。
+      #
+      # 这一条曾长期掩盖真相：`permissionPresets` 一直以为「web profile 注不进、
+      # 只能走内置兜底目录」，实际是这里没声明它。`jobController` 加进来之后
+      # 同样注不进，才顺着 `_refresh()` 的 INACTIVE 逻辑反查到这条覆盖规则。
+      inject: [
+        sessionController,
+        workspaceController,
+        workspaceRegistry,
+        settingsController,
+        credentialsController,
+        agentPresets,
+        # 权限档位目录（`ctx.permissionPresets`）：内核把它做成独立的 Typert
+        # 远程服务，会话投影那条 wire 视图只给 currentValue、不带候选项。
+        permissionPresets,
+        llm,
+        webServer,
+        agents,
+        commands,
+        # 后台任务（`ctx.jobController`）：远程场景下任务跑飞了要能停掉。
+        jobController,
+        # 文件上传服务（`ctx.fileUploads`）：用它而不是内核那条只绑 loopback 的
+        # /api/session/uploadFileBinary HTTP 路由。
+        fileUploads,
+        # 附件存储（`ctx.attachments`）：会话历史里的图片以 attachmentId 引用存在。
+        attachments,
+      ]
       config:
         # 状态目录**不改名**：已装的机器上有既有数据库与回收站，换目录等于让用户
         # 的授权根配置和回收站全部消失。改名只动「装的时候叫什么、bundle 叫什么」。

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.4.1
+  version: 2.4.3
   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.4.1
+  version: 2.4.3
   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,63 @@ paths:
                 properties:
                   ok: { type: boolean, const: true }
                   version: { type: string, const: v1 }
-                  pluginVersion: { type: string, const: 2.4.1 }
+                  pluginVersion: { type: string, const: 2.4.2 }
+  /debug/host-services:
+    get:
+      operationId: hostServices
+      summary: Host service injection probe
+      description: |
+        Reports which DSH host services the plugin actually resolved on the running
+        kernel. This plugin deliberately imports no `@deepseek-ai/*` package and
+        consumes every host service through a structural type injected by the Host,
+        so "is the service there at all" is otherwise unanswerable without guessing.
+
+        `injected` covers the services named in the plugin's `inject` declaration;
+        `observed` covers services confirmed present in the web profile but not yet
+        consumed (currently only `workingDirectory`, added by DSH 0.2.1).
+
+        Requires a device token or loopback admin, like every other authenticated
+        endpoint: it exposes host internals.
+      responses:
+        '200':
+          description: Injection probe snapshot taken while the plugin applied.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [pluginVersion, injected, observed, summary]
+                properties:
+                  pluginVersion: { type: string }
+                  injected:
+                    type: array
+                    items:
+                      type: object
+                      required: [name, available, resolvable]
+                      properties:
+                        name: { type: string }
+                        available: { type: boolean }
+                        resolvable: { type: boolean }
+                        error: { type: string }
+                  observed:
+                    type: array
+                    items:
+                      type: object
+                      required: [name, available, resolvable]
+                      properties:
+                        name: { type: string }
+                        available: { type: boolean }
+                        resolvable: { type: boolean }
+                        error: { type: string }
+                  summary:
+                    type: object
+                    required: [injectedTotal, injectedAvailable, injectedMissing, observedAvailable]
+                    properties:
+                      injectedTotal: { type: integer }
+                      injectedAvailable: { type: integer }
+                      injectedMissing: { type: array, items: { type: string } }
+                      observedAvailable: { type: array, items: { type: string } }
+        '404':
+          description: The probe is not compiled into this build.
   /pairings/exchange:
     post:
       security: []
@@ -307,6 +363,28 @@ paths:
                   items:
                     type: array
                     items: { $ref: '#/components/schemas/AgentPreset' }
+  /chat/permission-presets:
+    get:
+      operationId: listPermissionPresets
+      description: >-
+        Lists the permission presets a session can switch between (the catalog behind
+        DSH WebUI's access-mode selector). Session projections only carry the *current*
+        value, so clients cannot enumerate the choices without this endpoint.
+      responses:
+        '200':
+          description: Permission preset choices and the deployment default.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [options, defaultPreset]
+                properties:
+                  options:
+                    type: array
+                    items: { $ref: '#/components/schemas/PermissionOption' }
+                  defaultPreset:
+                    type: string
+        '403': { $ref: '#/components/responses/Error' }
   /settings/providers:
     get:
       operationId: listProviderSettings
@@ -561,6 +639,94 @@ paths:
       responses:
         '200': { description: Session archived. }
         '404': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/jobs:
+    parameters:
+      - name: sessionId
+        in: path
+        required: true
+        schema: { type: string }
+    get:
+      operationId: listSessionJobs
+      summary: Background jobs a session can see
+      description: |
+        The roster this session can observe: its own jobs plus every unowned job.
+        The kernel's owner fence is the only access rule, so `sessionId` is
+        required and must not be guessed by the client.
+      responses:
+        '200':
+          description: The complete roster (whole-set, not a page).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [jobs]
+                properties:
+                  jobs:
+                    type: array
+                    items: { $ref: '#/components/schemas/JobView' }
+        '404': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/jobs/{jobId}/output:
+    parameters:
+      - name: sessionId
+        in: path
+        required: true
+        schema: { type: string }
+      - name: jobId
+        in: path
+        required: true
+        schema: { type: string }
+      - name: from
+        in: query
+        required: false
+        description: Absolute byte offset to resume from (a prior response's `next`). Omitted starts at the oldest retained byte.
+        schema: { type: integer }
+    get:
+      operationId: readJobOutput
+      summary: Retained output of one background job
+      responses:
+        '200':
+          description: Flattened output plus the offset to resume from.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [jobId, text, next, lossy]
+                properties:
+                  jobId: { type: string }
+                  text: { type: string }
+                  next: { type: integer }
+                  lossy: { type: boolean }
+                  status: { $ref: '#/components/schemas/JobStatus' }
+        '404': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/jobs/{jobId}/kill:
+    parameters:
+      - name: sessionId
+        in: path
+        required: true
+        schema: { type: string }
+      - name: jobId
+        in: path
+        required: true
+        schema: { type: string }
+    post:
+      operationId: killSessionJob
+      summary: Stop one background job on a human's behalf
+      description: |
+        Records `cancelled by the user` as the reason. The owning agent still
+        receives its completion notice, because a human kill is not one the
+        model requested.
+      responses:
+        '200':
+          description: The registry's admission.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [jobId, outcome]
+                properties:
+                  jobId: { type: string }
+                  outcome: { type: string, enum: [requested, already-finished] }
+        '404': { $ref: '#/components/responses/Error' }
   /chat/sessions/{sessionId}/messages:
     parameters:
       - name: sessionId
@@ -1307,3 +1473,21 @@ components:
             message: { type: string }
             requestId: { type: string, format: uuid }
             details: { type: object, additionalProperties: true }
+    JobStatus:
+      type: string
+      description: Lifecycle state. `running` and `stopping` are live; the rest are terminal.
+      enum: [running, stopping, completed, killed, failed]
+    JobView:
+      type: object
+      description: Read-only projection of one background job.
+      required: [id, kind, label, status, startedAt]
+      properties:
+        id: { type: string, description: 'Registry-issued id, e.g. `bash-<short-uuid>`.' }
+        kind: { type: string, description: 'Producer kind; `bash` is the only host-registered one today.' }
+        label: { type: string, description: Producer-supplied one-line label. }
+        owner: { type: string, description: Owning session; absent for an unowned job. }
+        status: { $ref: '#/components/schemas/JobStatus' }
+        progress: { type: string, description: 'Live progress line (`3/10`); cleared at settlement.' }
+        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. }

package/kotlin-sdk/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "ai.deepseek.dsh"
-version = "2.4.1"
+version = "2.4.2"
 
 repositories { mavenCentral() }
 

package/kotlin-sdk/src/main/kotlin/ai/deepseek/dsh/workspace/DshWorkspaceClient.kt

@@ -116,6 +116,30 @@ data class AgentPreset(
 @Serializable
 data class ModelSelection(val provider: String, val model: String, val reasoningEffort: String? = null)
 
+/**
+ * 一个可选的权限档位。
+ *
+ * [name] 是**非空**的：服务端 `normalizePermissionCatalog` 保证名字缺失时用 `value` 顶上，
+ * 空名字会在严格反序列化器上失败，或在 UI 上留下一行没有文字的选项。
+ */
+@Serializable
+data class PermissionOption(
+    val value: String,
+    val name: String,
+    val description: String? = null,
+)
+
+/**
+ * 权限档位清单（`GET /chat/permission-presets`）。
+ *
+ * [defaultPreset] 是部署默认，**不等于**某个会话的当前档位 —— 当前值只认会话投影。
+ */
+@Serializable
+data class PermissionCatalog(
+    val options: List<PermissionOption> = emptyList(),
+    val defaultPreset: String = "",
+)
+
 @Serializable
 data class ModelReasoningEffort(val id: String, val name: String, val description: String? = null)
 
@@ -343,6 +367,19 @@ class DshWorkspaceClient(
         AgentPresetList.serializer(),
     ).items
 
+    /**
+     * 权限档位候选清单。
+     *
+     * 必须单开一条：会话投影里那条 `permissions` 视图**只给 currentValue**，
+     * 候选项在内核的独立远程服务上，所以客户端列不出档位菜单。
+     */
+    fun listPermissionPresets(): PermissionCatalog = executeJson(
+        "chat/permission-presets",
+        "GET",
+        null,
+        PermissionCatalog.serializer(),
+    )
+
     fun selectSessionAgentPreset(sessionId: String, agentPreset: String): String {
         val body = json.encodeToString(AgentPresetSelection.serializer(), AgentPresetSelection(agentPreset))
         return executeJson(
@@ -477,6 +514,51 @@ class DshWorkspaceClient(
         executeUnit("chat/sessions/$sessionId/archive", "POST", null)
     }
 
+    /**
+     * 这个会话可见的后台任务清单（它自己的 + 所有无主任务）。
+     *
+     * 服务端只读内核流的第一帧 —— 内核保证首帧就是全量 truth，
+     * 所以这里返回的是完整清单，不是一个分页。
+     */
+    fun listSessionJobs(sessionId: String): List<JobView> = executeJson(
+        "chat/sessions/$sessionId/jobs",
+        "GET",
+        null,
+        JobListEnvelope.serializer(),
+    ).jobs
+
+    /**
+     * 读一个后台任务已保留的输出。
+     *
+     * [from] 是**绝对字节偏移**，传上一次返回的 [JobOutput.next] 即可增量续读；
+     * 传 null 从最旧的保留字节开始。
+     *
+     * [JobOutput.lossy] 为 true 时，请求偏移与返回内容之间有字节被留存策略吃掉 ——
+     * 这段输出不是完整的，调用方应当提示用户。
+     */
+    fun readJobOutput(sessionId: String, jobId: String, from: Long? = null): JobOutput {
+        val query = if (from == null) "" else "?from=$from"
+        return executeJson(
+            "chat/sessions/$sessionId/jobs/$jobId/output$query",
+            "GET",
+            null,
+            JobOutput.serializer(),
+        )
+    }
+
+    /**
+     * 终止一个后台任务。
+     *
+     * 返回 `requested`（已受理）或 `already-finished`（已是终态、无需再杀）——
+     * 调用方应据此显示「已终止」或「它已经结束了」，后者不是前者的成功说法。
+     */
+    fun killSessionJob(sessionId: String, jobId: String): JobKillResult = executeJson(
+        "chat/sessions/$sessionId/jobs/$jobId/kill",
+        "POST",
+        null,
+        JobKillResult.serializer(),
+    )
+
     fun listPendingApprovals(sessionId: String): List<PendingApproval> = executeJson(
         "chat/sessions/$sessionId/approvals",
         "GET",
@@ -689,3 +771,59 @@ class EventSubscription internal constructor(
 @Serializable private data class SendMessageRequest(val text: String, val mode: String, val clientRequestId: String)
 @Serializable private data class ErrorEnvelope(val error: ApiErrorBody)
 @Serializable private data class ApiErrorBody(val code: String, val message: String, val requestId: String)
+
+/** 后台任务的生命周期状态。`running` / `stopping` 存活中，其余为终态。 */
+@Serializable
+enum class JobStatus {
+    @SerialName("running") RUNNING,
+    @SerialName("stopping") STOPPING,
+    @SerialName("completed") COMPLETED,
+    @SerialName("killed") KILLED,
+    @SerialName("failed") FAILED,
+}
+
+/**
+ * 一个后台任务的只读投影。
+ *
+ * 服务端逐个字段校验过类型，所以这里除 [status] / [startedAt] / [id] / [kind] / [label]
+ * 之外的字段都可空 —— 内核没给就是没有，客户端不该看到一个 `owner: undefined`。
+ */
+@Serializable
+data class JobView(
+    val id: String,
+    val kind: String,
+    val label: String,
+    val owner: String? = null,
+    val status: JobStatus,
+    /** 生产者的实时进度行（`3/10`）；终态时被清空。 */
+    val progress: String? = null,
+    /** 终态原因（`exit code: 3`）；记录过的人工取消原因会并进来。 */
+    val detail: String? = null,
+    /** 注册时刻（epoch ms）。 */
+    val startedAt: Long,
+    /** 落定时刻（epoch ms）；存活中为 null。 */
+    val finishedAt: Long? = null,
+)
+
+@Serializable private data class JobListEnvelope(val jobs: List<JobView>)
+
+/** 一个后台任务已保留的输出。 */
+@Serializable
+data class JobOutput(
+    val jobId: String,
+    val text: String,
+    /** 绝对字节偏移；下次增量续读传它。 */
+    val next: Long,
+    /** true = 请求偏移与返回内容之间有字节被留存策略吃掉，这段输出不完整。 */
+    val lossy: Boolean,
+    /** 读到终态帧时带上；流被提前切断时为 null。 */
+    val status: JobStatus? = null,
+)
+
+/** 终止结果。 */
+@Serializable
+data class JobKillResult(
+    val jobId: String,
+    /** `requested` 已受理；`already-finished` 已是终态、无需再杀。 */
+    val outcome: String,
+)