dsh-cherry-bridge 0.1.10 → 0.2.0

package/README.en.md

@@ -28,23 +28,25 @@ flowchart TB
 ```
 
 - Package: `dsh-cherry-bridge`, plugin id: `cherry-remote`
-- Transport: `ws://` + Noise XX (encryption lives in the Noise record layer; no TLS termination required)
+- Transport: `ws://` + Noise XX by default (encryption lives in the Noise record layer); a desktop behind a TLS front is reached over `wss://`, with `wsTls` supplying the private-CA trust
 - Tool face: 14 `cherry_*` tools, enabled **per workspace**, and by default **nobody has them** (see “Scope”)
 - Settings page and HTTP face: the same-origin prefix `/cherry-remote/api` on the host web server
 
 ## Install
 
 > **DSH version requirement**: `>=0.2.0-rc.2 <0.3.0-0` (declared via `engines.dsh` in `package.json`; when unmet the bundle is skipped and its settings-page row disabled — `dsh plugin allow-version` grants an explicit exemption; 0.3.0 needs a fresh compatibility pass before the range widens).
+>
+> **Cherry Studio compatibility**: desktop **2.1.4 – 2.1.8 is tested** — the `v3` custom-address QR needs **2.1.8+**, and the `v2` QR of 2.1.4 – 2.1.7 works too. Outside that range is unverified: the handshake negotiates protocol version `[1]` only, so an incompatible peer fails loudly as `unreachable` instead of misbehaving. The protocol packages are pinned to `0.7.0` / `0.2.5` — the versions desktop 2.1.8 ships.
 
 ```bash
 # From npm (recommended, pinned)
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.10
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.0
 
 # Install the latest npm release
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # From GitHub source (same commit as the npm release)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.10
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.0
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points
@@ -93,6 +95,9 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 | `dataDir` | string | `$DSH_HOME/cherry-remote` (fallback `~/.dsh/cherry-remote`) | Plugin data directory holding `identity.key` and `devices.json` (both `0600`). |
 | `perSessionCacheBytes` | number | `2097152` (2 MiB) | Per-session cap on the **local** subscription event cache; beyond it the oldest events are dropped LRU-style with a `warn`. |
 | `rateBudgetPerSecond` | number | `32` | Per-device smoothed request budget (req/s). The desktop's shared allowance is 64 req/s through 2.1.6 and 256 req/s from 2.1.7, and only the newer generation downgrades an overrun to a single `RATE_LIMITED` refusal (the older one terminates the session with close `1011`) — hence a value sized for the harsher generation. Content reads (`agent.content.read`) derive their own tier at 8:1, **capped at 512/s** (that allowance is the same in both generations). |
+| `wsTls` | object | — | **Flat** `tls.connect` options for every `wss` dial (`rejectUnauthorized` / `ca` only): operator-supplied trust for a desktop behind a private CA or a self-signed TLS front. Applied to BOTH dial sites — pairing and reconnect. **Never written to the device archive, never logged, never in diagnostics.** The whole object applies as written or is ignored entirely: an unknown key or unusable value warns by name and falls back to Node's default trust store (no partial application). |
+
+> `wsTls.ca` is **PEM CONTENT** (the certificate text itself), not a file path.
 
 > ⚠️ `cordis.patch.yml`'s `config` is **whole-replace**, not merged with the
 > defaults. Removing a key gets you the plugin default; a key that exists but is
@@ -106,7 +111,7 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 | `cherry_agents` | List the agents available on a device (paginated). A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`, the latter the 1000-item internal ceiling); when the stop point can be named it also carries a `resumeCursor`: replay it as `cursor` with the same device and filters to continue from that stop point (`limit` then bounds the next answer). A token from another tool, device or filter set is refused **locally**, never forwarded. |
 | `cherry_workspaces` | List an agent's **registered** workspaces, and whether a system workspace exists. A truncated answer always carries `truncated` + `truncationReason`; when the stop point can be named it also carries a `resumeCursor` — replay it as `cursor` with the same filters to continue. |
 | `cherry_sessions` | List an agent's sessions, optionally filtered by workspace. A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`); when the stop point can be named it also carries a `resumeCursor`: replay it as `cursor` with the same device and **identical filters** to continue (`limit` then bounds the next answer); a token from another tool, device or filter set is refused **locally**. |
-| `cherry_read` | Read a session's message history snapshot, **newest-first** (`limit` drops the **oldest** messages). A failed message carries `failure: {reasonCode, retryable, message}` when the peer sent one (its classification, whether a retry is worthwhile, and its own bounded summary; the peer's `source`/`context` are not projected). Attachment parts come back as `name`/`mediaType`/`byteLength` with an empty `content` — the bytes are never fetched. A truncated walk always says so (`truncated` + `truncationReason`): `limit` means your own ceiling was reached and raising `limit` helps; `aggregate-bytes` means the answer hit its **output size limit** — independent of `limit` (a larger `limit` only costs more round trips and stops at the same budget). **The older messages are reached by the resume token**: pass the `messagesResumeCursor` a truncated answer returned as this tool's own `messagesResumeCursor` argument to continue from that stop point (`limit` then bounds how many messages come back **from there**), walking a long history in successive answers. When the stop point cannot be named the token is **absent** (`truncated` stays `true`, and the absence does **not** mean the history ended); a wider `limit` is not a general remedy — it moves a `limit` stop only, while an `aggregate-bytes` stop leaves the older messages unreachable in that answer (see [Errors and limits](#errors-and-limits)). Two token forms: `cursor:<peer position>` (the peer page position after a whole window was consumed) and `after:<messageId>` (the walk stopped inside its window; the resume scans from the newest end to that message and returns the older ones). A token this tool did not emit is **refused locally** (never forwarded — the desktop silently falls back to the newest page for one), and an `after:` anchor that is no longer in the history is an **error**, not an empty result. |
+| `cherry_read` | Read a session's message history snapshot, **newest-first** (`limit` drops the **oldest** messages). A failed message carries `failure: {reasonCode, retryable, message}` when the peer sent one (its classification, whether a retry is worthwhile, and its own bounded summary; the peer's `source`/`context` are not projected). Attachment parts come back as `name`/`mediaType`/`byteLength` with an empty `content` — the bytes are never fetched. That covers both shapes a desktop can send: a `file` part (`name` is the filename, `byteLength` comes from its ref), and the legacy `data` part the desktop uses for an attachment it did not upload — `name: "file"` with the metadata as JSON in `content.text` (`{"mediaType":…,"filename":…}`); the same fields are lifted out, `filename: null` reports no `name`, and `content` is emptied only when every key in that record is one of the two reported fields (a record with extra keys keeps its raw text). A `data` part under any other `name` — a task event, say — is not an attachment and passes through untouched. A truncated walk always says so (`truncated` + `truncationReason`): `limit` means your own ceiling was reached and raising `limit` helps; `aggregate-bytes` means the answer hit its **output size limit** — independent of `limit` (a larger `limit` only costs more round trips and stops at the same budget). **The older messages are reached by the resume token**: pass the `messagesResumeCursor` a truncated answer returned as this tool's own `messagesResumeCursor` argument to continue from that stop point (`limit` then bounds how many messages come back **from there**), walking a long history in successive answers. When the stop point cannot be named the token is **absent** (`truncated` stays `true`, and the absence does **not** mean the history ended); a wider `limit` is not a general remedy — it moves a `limit` stop only, while an `aggregate-bytes` stop leaves the older messages unreachable in that answer (see [Errors and limits](#errors-and-limits)). Two token forms: `cursor:<peer position>` (the peer page position after a whole window was consumed) and `after:<messageId>` (the walk stopped inside its window; the resume scans from the newest end to that message and returns the older ones). A token this tool did not emit is **refused locally** (never forwarded — the desktop silently falls back to the newest page for one), and an `after:` anchor that is no longer in the history is an **error**, not an empty result. |
 | `cherry_events` | Read the session's buffered events newer than `cursor`, acking them after delivery. The answer is `{events, nextCursor}`; pass that `nextCursor` back as `cursor` to continue from it. |
 | `cherry_create` | Create a session in an agent workspace (workspace selection is **required**; identity is read back). |
 | `cherry_send` | Send a message, by default waiting for a terminal state and returning the assistant text; `wait: false` returns the command receipt immediately. `messagesTruncated`/`messagesTruncationReason` report a **message**-level cut (older messages dropped); `deadline` means the **answer's own assembly budget** ran out (see below), with the content read so far still returned. |
@@ -200,7 +205,9 @@ subscription was lost and could not be rebuilt, so the outcome is
 - **Known limitations**: `cherry_respond` lets a DSH agent approve Cherry-side
   approval cards on the user's behalf (the MVP adds no interception layer and
   trusts DSH's own tool-call approvals); only the `agent` capability is
-  requested per device; `ws://` only (Noise encryption), no direct TLS.
+  requested per device; transport is `ws://` by default, and `wss://` requires a
+  TLS front in front of the desktop (this plugin never terminates TLS; `wsTls`
+  carries the private-CA trust).
 
 > Engineering detail — replay rules, the 32 MiB/≈3× memory contract, empty-page
 > and cursor tolerance, integrity semantics — lives in [`AGENTS.md`](AGENTS.md).

package/README.md

@@ -26,23 +26,25 @@ flowchart TB
 ```
 
 - 包名：`dsh-cherry-bridge`，插件 id：`cherry-remote`
-- 传输：`ws://` + Noise XX（加密由 Noise 记录层提供，不依赖 TLS 终止）
+- 传输：默认 `ws://` + Noise XX（加密由 Noise 记录层提供）；桌面端位于 TLS 前置之后时拨 `wss://`，私有 CA 的信任由 `wsTls` 提供
 - 工具面：14 个 `cherry_*` 工具，**按工作区**启用，默认**谁都没有**（见「启用范围」）
 - 设置页与 HTTP 面：宿主 Web 服务器上的同源前缀 `/cherry-remote/api`
 
 ## 安装
 
 > **DSH 版本需求**：`>=0.2.0-rc.2 <0.3.0-0`（由 `package.json` 的 `engines.dsh` 声明；不满足时 bundle 被跳过、设置页里该插件的行被禁用，确需在区间外使用可用 `dsh plugin allow-version` 精确豁免。0.3.0 需重新评估兼容性后再放开）。
+>
+> **Cherry Studio 兼容范围**：桌面端 **2.1.4 – 2.1.8 已实测**——`v3` 自定义地址二维码需 **2.1.8+**，2.1.4–2.1.7 的 `v2` 二维码同样可用。区间外未经验证：握手只协商协议版本 `[1]`，不兼容时会以 `unreachable` 明确失败，不会静默出错。协议包钉在 `0.7.0` / `0.2.5`，即桌面端 2.1.8 所携带的版本。
 
 ```bash
 # 从 npm 安装（推荐，钉住版本）
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.10
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.0
 
 # 安装 npm 最新发布版
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # 从 GitHub 源码安装（与 npm 发布同一提交）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.10
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.0
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），
@@ -85,6 +87,9 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 | `dataDir` | string | `$DSH_HOME/cherry-remote`（回退 `~/.dsh/cherry-remote`） | 插件数据目录，存放 `identity.key` 与 `devices.json`（均 `0600`）。 |
 | `perSessionCacheBytes` | number | `2097152`（2 MiB） | 每个会话的**本地**订阅事件缓存上限，超出按 LRU 丢弃最旧事件并 `warn`。 |
 | `rateBudgetPerSecond` | number | `32` | 每设备平滑请求预算（请求/秒）。桌面端共享额度在 ≤2.1.6 是 64 req/s、≥2.1.7 是 256 req/s，且只有新版本才把超限降级为单请求 `RATE_LIMITED`（旧版本直接 close `1011` 终止会话），故按更严格的一代取保守值。内容读取（`agent.content.read`）按 8:1 派生独立一档，且**封顶 512/s**（该额度两代一致）。 |
+| `wsTls` | object | — | 每次 `wss` 拨号的**扁平** `tls.connect` 选项（只接受 `rejectUnauthorized` / `ca`），供桌面端位于私有 CA 或自签 TLS 前置之后时由运维提供信任；配对与重连**两个拨号点**共用。**不写入设备档案、不写日志、不进诊断报告。** 整个对象要么按原样生效、要么整体忽略：未知键或不可用值按名 `warn` 后回退 Node 默认信任库（不部分应用）。 |
+
+> `wsTls.ca` 是 **PEM 内容**（证书文本本身），不是文件路径。
 
 > ⚠️ `cordis.patch.yml` 的 `config` 是**整体替换**，不与默认值合并。删掉一个键得到的是
 > 插件默认值；键存在但值非法（`0`、负数、字符串）会按名 `warn` 后回落默认值。
@@ -97,7 +102,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 | `cherry_agents` | 列出某设备上可用的 agent（分页）。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`，后者是 1000 条内部上限）；停点可命名时还给出 `resumeCursor`——用同一 device 与过滤条件把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**，不会转发给对端。 |
 | `cherry_workspaces` | 列出某 agent 的**已注册**工作区，以及是否存在系统工作区。被截断时必带 `truncated`+`truncationReason`；停点可命名时还给出 `resumeCursor`——用相同过滤条件回传为 `cursor` 即可续读。 |
 | `cherry_sessions` | 列出某 agent 的会话，可按工作区过滤。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`），停点可命名时还给出 `resumeCursor`——用同一 device 与**相同过滤条件**把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**。 |
-| `cherry_read` | 读会话消息历史快照，**从新到旧**返回（`limit` 丢掉的是**最旧**的消息）。失败消息在桌面端给出时附带 `failure: {reasonCode, retryable, message}`（对端分类、是否值得重试、对端自己的有界摘要；其 `source`/`context` 不投影到回答里）。附件 part 只回 `name`/`mediaType`/`byteLength`，`content` 为空——字节不取。被截断时 `truncated` + `truncationReason` 一定说明：`limit` 表示你设的条数到了，提高 `limit` 即可；`aggregate-bytes` 表示单次回答达到了**输出大小上限**——与 `limit` 无关，提高 `limit` 只会多付往返、仍停在同一预算。**被挡下的更旧消息用 `messagesResumeCursor` 续读**：把本次返回的 `messagesResumeCursor` 原样传给下一次调用的 `messagesResumeCursor` 参数即可从停点继续（`limit` 此时约束的是**从停点起**本次最多返回多少条），长历史分几次回答读完。停点不可命名时**没有**这个令牌（`truncated` 仍为 `true`，**缺失本身不代表历史已到底**；补救按 `truncationReason` 分：`limit` 可以提高 `limit`，`aggregate-bytes` 不行——被挡住的旧消息在这一回答里拿不到，详见[错误与限制](#错误与限制)）。两种令牌：`cursor:<peer position>`（整窗读完后的 peer 分页位置）与 `after:<messageId>`（停在窗内，续读从最新端扫到该消息、返回它更旧的那些）。不是本工具发出的令牌会被**本地拒绝**（不转发给桌面端——桌面端会静默回退到最新页）；`after:` 锚点在历史里找不到则**报错**，不会返回空结果。 |
+| `cherry_read` | 读会话消息历史快照，**从新到旧**返回（`limit` 丢掉的是**最旧**的消息）。失败消息在桌面端给出时附带 `failure: {reasonCode, retryable, message}`（对端分类、是否值得重试、对端自己的有界摘要；其 `source`/`context` 不投影到回答里）。附件 part 只回 `name`/`mediaType`/`byteLength`，`content` 为空——字节不取。这覆盖桌面端可能发来的两种形状：`file` part（`name` 即文件名，`byteLength` 取自它的 ref）；以及桌面端用于**未上传**附件的旧式 `data` part——`name: "file"`，元数据以 JSON 形式放在 `content.text` 里（`{"mediaType":…,"filename":…}`），同样字段被取出结构化，`filename: null` 则不报 `name`，且只有当该对象里的每个键都是这两个上报字段时才清空 `content`（带额外键时保留原始文本）。其他 `name` 的 `data` part（例如任务事件）不是附件，原样透传。被截断时 `truncated` + `truncationReason` 一定说明：`limit` 表示你设的条数到了，提高 `limit` 即可；`aggregate-bytes` 表示单次回答达到了**输出大小上限**——与 `limit` 无关，提高 `limit` 只会多付往返、仍停在同一预算。**被挡下的更旧消息用 `messagesResumeCursor` 续读**：把本次返回的 `messagesResumeCursor` 原样传给下一次调用的 `messagesResumeCursor` 参数即可从停点继续（`limit` 此时约束的是**从停点起**本次最多返回多少条），长历史分几次回答读完。停点不可命名时**没有**这个令牌（`truncated` 仍为 `true`，**缺失本身不代表历史已到底**；补救按 `truncationReason` 分：`limit` 可以提高 `limit`，`aggregate-bytes` 不行——被挡住的旧消息在这一回答里拿不到，详见[错误与限制](#错误与限制)）。两种令牌：`cursor:<peer position>`（整窗读完后的 peer 分页位置）与 `after:<messageId>`（停在窗内，续读从最新端扫到该消息、返回它更旧的那些）。不是本工具发出的令牌会被**本地拒绝**（不转发给桌面端——桌面端会静默回退到最新页）；`after:` 锚点在历史里找不到则**报错**，不会返回空结果。 |
 | `cherry_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。返回 `{events, nextCursor}`；把 `nextCursor` 作为下次的 `cursor` 传回即可续读。 |
 | `cherry_create` | 在 agent 工作区创建会话（工作区选择**必填**；创建后回读身份）。 |
 | `cherry_send` | 向会话发消息，默认等待运行到终态并返回助手文本；`wait: false` 立即返回命令回执。内容被截断时 `messagesTruncated`/`messagesTruncationReason` 说的是**消息**被截断（丢更旧的）；`deadline` 表示**回答自身的装配时限**到了（见下），已读到的内容照常返回。 |
@@ -155,7 +160,8 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
   idle 回答的历史走查仍从那一刻起算自己的预算（慢但成功的快照不会把走查挤成零）；
   代价是两段预算**分开计**，病态调用可能把两段都花掉。
 - **已知限制**：`cherry_respond` 让 DSH agent 可代替用户批准 Cherry 端审批卡（MVP 不加拦截层，
-  信任 DSH 自身的工具审批）；每设备仅申请 `agent` capability；仅 `ws://`（Noise 加密），不做 TLS 直连。
+  信任 DSH 自身的工具审批）；每设备仅申请 `agent` capability；传输默认 `ws://`，
+  `wss://` 要求桌面端位于 TLS 前置之后（本插件不做 TLS 终止；私有 CA 的信任由 `wsTls` 提供）。
 
 > 传输重放、32 MiB/≈3× 内存、空页与游标容忍、完整性语义等工程细节见 [`AGENTS.md`](AGENTS.md)。
 

package/dist/index.d.mts

@@ -1,5 +1,18 @@
 import { connectSecureChannel } from "@cherrystudio/remote-transport";
 import "@cherrystudio/remote-protocol/agent";
+//#region src/connection.d.ts
+/**
+ * Options handed to every `WebSocket` dial (issue #126).
+ *
+ * FLAT `tls.connect` options — `ws` forwards its own option bag straight to
+ * `tls.connect`, so `{ rejectUnauthorized: false }` or `{ ca: <pem> }` belong
+ * at the top level rather than under a `tls:` key.
+ */
+type WsDialOptions = {
+  rejectUnauthorized?: boolean;
+  ca?: string | Buffer | Array<string | Buffer>;
+};
+//#endregion
 //#region src/tools.d.ts
 /**
  * The plugin's tool face: the complete fourteen-tool `cherry_*` family — six
@@ -264,10 +277,24 @@ export interface CherryBridgeConfig {
    * (not a protocol value). Omitted uses {@link DEFAULT_PER_SESSION_CACHE_BYTES}.
    */
   perSessionCacheBytes?: number;
+  /**
+   * FLAT `tls.connect` options for every `wss` dial (issue #133): the operator's
+   * TLS trust for a desktop behind a private CA or a self-signed TLS front.
+   * `ws` forwards this bag straight to Node's TLS layer, so `{ ca: <pem> }` and
+   * `{ rejectUnauthorized: false }` belong at the TOP level — the `{ tls: {…} }`
+   * shape (`https`' wrapper) is not recognised by `ws` and is refused here.
+   * Applied to BOTH dial sites: the steady-state pool and pairing.
+   *
+   * NEVER persisted in the record, never logged, never reported: a `ca` is PEM
+   * CONTENT, and trust is a grant the operator makes, not a fact the desktop
+   * asserts about itself.
+   */
+  wsTls?: WsDialOptions;
 }
 /**
- * The two config values that reach constructor arguments, with their defaults
- * applied.
+ * The plugin-config values that reach constructor arguments, resolved once: the
+ * two numeric budgets with their defaults applied, and the validated TLS trust
+ * bag (see {@link dialOptions}).
  *
  * Resolved ONCE per `apply` and threaded explicitly, rather than re-read at each
  * construction site: a config surface that can change between two constructions
@@ -276,8 +303,9 @@ export interface CherryBridgeConfig {
 export interface ResolvedBridgeConfig {
   rateBudgetPerSecond: number;
   perSessionCacheBytes: number;
+  wsTls: WsDialOptions | undefined;
 }
-/** Applies the documented fallbacks to the plugin config's numeric keys. */
+/** Applies the documented fallbacks and validates the plugin config's keys. */
 export declare function resolveBridgeConfig(config?: CherryBridgeConfig): ResolvedBridgeConfig;
 /** The context slice `apply` touches beyond the HTTP face's own services. */
 export interface CherryBridgeContext extends CherryHttpContext, CherryToolsContext {