dsh-cherry-bridge 0.1.7 → 0.1.9

package/README.en.md

@@ -38,13 +38,13 @@ flowchart TB
 
 ```bash
 # From npm (recommended, pinned)
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.7
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.9
 
 # 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.7
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.9
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points
@@ -103,15 +103,15 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 | Tool | What it does |
 | --- | --- |
 | `cherry_devices` | List every paired device and its connection state (`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`). |
-| `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), plus 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` and 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`) plus 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). 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. 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_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). 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_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. |
 | `cherry_wait` | Wait only for the session's in-flight execution to settle (sends nothing). |
-| `cherry_interactions` | List the session's **pending** interaction cards (questions / approvals). A truncated answer always carries `truncated` + `truncationReason` and a `resumeCursor` — replay it as `cursor` to continue (`limit` counts the peer's pre-filter rows). |
+| `cherry_interactions` | List the session's **pending** interaction cards (questions / approvals). A truncated answer always carries `truncated` + `truncationReason`; when the stop point can be named it also carries a `resumeCursor` — replay it as `cursor` from the same `sessionId` to continue (`limit` counts the peer's pre-filter rows). |
 | `cherry_respond` | Answer an interaction card: questions must be answered in full; approvals take `decision`. |
 | `cherry_cancel` | Cancel the session's in-flight execution (`expectedExecutionId` required). |
 | `cherry_pair` | Pair with a desktop using the pairing information shown by the scanned page. |
@@ -124,12 +124,12 @@ The `device` argument accepts an **exact `deviceId`**, or a **prefix of a
 `cherry_send(wait: true)` / `cherry_wait` results carry one of **8 `status`
 values**: the four protocol terminal states
 (`completed`/`failed`/`cancelled`/`interrupted`), plus `awaiting-interaction`
-(a pending card appeared while the run is still alive), `timeout` (the window ran
-out, **not a failure** — partial content plus a stop-point cursor come back),
-`idle` (`cherry_wait` met a session with nothing in flight and returned the
-snapshot immediately), and `subscription-lost` (the subscription was lost and
-could not be rebuilt, so the outcome is **unknowable**; repair guidance ships
-with it).
+(a pending card appeared while the run is still alive), `timeout` (the window
+ran out, **not a failure** — partial content comes back, plus a stop-point
+cursor when one can be named), `idle` (`cherry_wait` met a session with nothing
+in flight and returned the snapshot immediately), and `subscription-lost` (the
+subscription was lost and could not be rebuilt, so the outcome is
+**unknowable**; repair guidance ships with it).
 
 ## Errors and limits
 
@@ -152,9 +152,23 @@ with it).
 - A truncated history walk always says so (`truncationReason`; `limit`,
   `aggregate-bytes` and `deadline` mean different things, see above) and,
   whenever a stop point can be named honestly, carries a `messagesResumeCursor`
-  resume token (absent when the walk reached the peer's last page); a message
-  whose own parts could not be fully read carries `incomplete: true` (inside a
-  wait answer, a message cut by the deadline carries
+  resume token. **When it cannot be named the token is absent**: the peer's
+  position is empty, carries leading/trailing whitespace or a control character,
+  looks like a retired v1 token, the token would exceed the 4,096-character
+  ceiling, or there is no message id to anchor on. The absence does **not** mean
+  the history ended (`truncated` stays `true`); the remedy follows the reason —
+  a `limit` stop answers to a wider `limit` only where the caller owns that
+  ceiling (`cherry_read` and the four list tools; a **wait answer's** `limit` is
+  its own fixed allowance, so read further with `cherry_read`), an
+  `aggregate-bytes` stop does not (nothing reaches past it in that answer), a
+  `safety-bound` stop is an internal circuit breaker no caller can move, and a
+  wait answer cut by its deadline is continued with `cherry_read`, which carries
+  no deadline. **Both faces obey one rule**:
+  the message face's `messagesResumeCursor` and the four list tools'
+  `resumeCursor` are emitted only when this tool would accept them back; an
+  interior plain space is legal and is not a reason to withhold one.
+  A message whose own parts could not be fully read carries `incomplete: true`
+  (inside a wait answer, a message cut by the deadline carries
   `partsTruncated: "deadline"`).
 - **A wait answer has an assembly budget of its own.** After the window ends,
   `cherry_send(wait: true)` / `cherry_wait` still read some history (the message
@@ -189,7 +203,7 @@ with it).
 
 The plugin is also a **web client bundle** (`package.json`'s `dsh.client`,
 exporting `./client`). Through the `settings.section` slot it registers a
-**`cherry-remote`** page (nav label “Cherry Studio Bridge”): device cards
+**`cherry-remote`** page (nav label “Cherry Bridge”): device cards
 (enable/disable/remove), a pairing wizard (paste → 6-digit code → verdict), a
 scope panel, and live state pushed over the same-origin SSE feed
 (`/cherry-remote/api/events`).

package/README.md

@@ -36,13 +36,13 @@ flowchart TB
 
 ```bash
 # 从 npm 安装（推荐，钉住版本）
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.7
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.9
 
 # 安装 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.7
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.9
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），
@@ -94,15 +94,15 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 | 工具 | 作用 |
 | --- | --- |
 | `cherry_devices` | 列出已配对设备及连接状态（`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`）。 |
-| `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` 丢掉的是**最旧**的消息）。附件 part 只回 `name`/`mediaType`/`byteLength`，`content` 为空——字节不取。被截断时 `truncated` + `truncationReason` 一定说明：`limit` 表示你设的条数到了，提高 `limit` 即可；`aggregate-bytes` 表示单次回答达到了**输出大小上限**——与 `limit` 无关，提高 `limit` 只会多付往返、仍停在同一预算。**被挡下的更旧消息用 `messagesResumeCursor` 续读**：把本次返回的 `messagesResumeCursor` 原样传给下一次调用的 `messagesResumeCursor` 参数即可从停点继续（`limit` 此时约束的是**从停点起**本次最多返回多少条），长历史分几次回答读完。两种令牌：`cursor:<peer position>`（整窗读完后的 peer 分页位置）与 `after:<messageId>`（停在窗内，续读从最新端扫到该消息、返回它更旧的那些）。不是本工具发出的令牌会被**本地拒绝**（不转发给桌面端——桌面端会静默回退到最新页）；`after:` 锚点在历史里找不到则**报错**，不会返回空结果。 |
+| `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` 丢掉的是**最旧**的消息）。附件 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_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。返回 `{events, nextCursor}`；把 `nextCursor` 作为下次的 `cursor` 传回即可续读。 |
 | `cherry_create` | 在 agent 工作区创建会话（工作区选择**必填**；创建后回读身份）。 |
 | `cherry_send` | 向会话发消息，默认等待运行到终态并返回助手文本；`wait: false` 立即返回命令回执。内容被截断时 `messagesTruncated`/`messagesTruncationReason` 说的是**消息**被截断（丢更旧的）；`deadline` 表示**回答自身的装配时限**到了（见下），已读到的内容照常返回。 |
 | `cherry_wait` | 只等待该会话在途执行收敛（不发送新消息）。 |
-| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。被截断时必带 `truncated`+`truncationReason`，并给出 `resumeCursor`——用 `sessionId` 相同的调用回传为 `cursor` 即可续读（`limit` 计的是过滤**前**的对端条目）。 |
+| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。被截断时必带 `truncated`+`truncationReason`；停点可命名时还给出 `resumeCursor`——用 `sessionId` 相同的调用回传为 `cursor` 即可续读（`limit` 计的是过滤**前**的对端条目）。 |
 | `cherry_respond` | 应答交互卡：提问必须全量作答，审批走 `decision`。 |
 | `cherry_cancel` | 取消会话在途执行（`expectedExecutionId` 必填）。 |
 | `cherry_pair` | 用「扫码后页面显示的配对信息」建立与桌面端的配对。 |
@@ -113,7 +113,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 
 `cherry_send(wait: true)` / `cherry_wait` 的 `status` 有 **8 个取值**：四个协议终态
 （`completed`/`failed`/`cancelled`/`interrupted`），加上 `awaiting-interaction`（出现待答
-交互卡，运行仍活着）、`timeout`（窗口用尽，**不是失败**，随附部分内容与停点游标）、
+交互卡，运行仍活着）、`timeout`（窗口用尽，**不是失败**，随附部分内容，停点可命名时再带游标）、
 `idle`（`cherry_wait` 遇到没有在途执行的会话，立即返回快照）、`subscription-lost`
 （事件订阅丢失且重建失败，运行结局**不可知**，随附修复指引）。
 
@@ -128,9 +128,17 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
   不在这个乘积里（每次并发读最多再带一整条消息，因为输出预算只在消息之间检查），parts 缓存另计。
   等待槽位也计入等待类回答的时限：排到时限就放弃并把这一 part 标 `unavailable`。
 - 历史走查被截断时一定说明（`truncationReason`，`limit` / `aggregate-bytes` / `deadline` 三种含义不同，见上），
-  并在能诚实标出停点时给出 `messagesResumeCursor` 续读令牌（走到对端末页时没有可标的位置，就不给）；
-  某条消息自身 parts 没读全时带 `incomplete: true`（wait 类回答里被时限截断的那条消息会带
-  `partsTruncated: "deadline"`）。
+  并在停点可命名时给出 `messagesResumeCursor` 续读令牌。**停点不可命名时就不给**：对端位置为空、
+  带首尾空白或任意控制字符、形如已停用的 v1 令牌、令牌会超过 4096 字符上限、或没有可当锚点的
+  消息 id——此时 `truncated` 仍为 `true`，**缺失本身不代表历史已到底**。补救按 `truncationReason`
+  分：`limit` 停点只有在调用方自己握着上限时才靠更宽的 `limit`（`cherry_read` 与四个列表工具）；
+  **wait 类回答的 `limit` 是它自己的固定条数额度**，更旧的历史要用 `cherry_read` 去读。
+  `aggregate-bytes` 停点不行——预算是它停下的原因，更宽的 `limit` 只会多付往返，被挡住的旧消息
+  在这一回答里拿不到；`safety-bound` 停点是内部熔断，调用方动不了它；`deadline`（只出现在 wait
+  类回答）同样改用 `cherry_read` 续读，它没有时限。
+  **两个面是同一条规则**：消息面的 `messagesResumeCursor` 与四个列表工具的
+  `resumeCursor` 都只发出本工具会收回的令牌；位置内部的普通空格合法，不会因此被拒。
+  某条消息自身 parts 没读全时带 `incomplete: true`（wait 类回答里被时限截断的那条消息会带 `partsTruncated: "deadline"`）。
 - **等待类回答有自己的装配时限**：`cherry_send(wait: true)` / `cherry_wait` 在窗口结束后仍要读一段历史
   （消息页 + 每条消息的 parts + 每个外置 `{ref}` 内容），这一步现在是**有时限的**——截至「你的窗口 +
   同样长度的时间」，下限 1 秒、上限 15 秒（即窗口 1 秒 → 最多再等 1 秒；窗口 20 秒 → 最多再等 15 秒）。
@@ -151,7 +159,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 ## 设置页与启用范围
 
 插件同时是 **web client bundle**（`package.json` 的 `dsh.client`，导出 `./client`），通过
-`settings.section` 槽位注册 **`cherry-remote`**（导航标签「Cherry Studio 互联」）页面：
+`settings.section` 槽位注册 **`cherry-remote`**（导航标签「Cherry 互联」）页面：
 设备卡片（启用/停用/删除）、配对向导（粘贴 → 6 位验证码 → 终态）、启用范围面板，以及经
 `/cherry-remote/api/events` SSE 推送的实时状态。