dsh-cherry-bridge 0.1.5 → 0.1.6

package/README.en.md

@@ -37,14 +37,14 @@ flowchart TB
 > **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).
 
 ```bash
-# From GitHub (recommended)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge
+# From npm (recommended, pinned)
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.6
 
-# Pinned to a version tag (recommended for production)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.5
+# Install the latest npm release
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
-# Or from the npm registry
-dsh plugin --profile <name> 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.6
 ```
 
 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). |
-| `cherry_workspaces` | List an agent's **registered** workspaces, and whether a system workspace exists. |
-| `cherry_sessions` | List an agent's sessions, optionally filtered by workspace. |
+| `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_events` | Read the session's buffered events newer than `cursor`, acking them after delivery. |
+| `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). |
+| `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_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. |
@@ -224,7 +224,7 @@ npm run typecheck      # server + UI projects
 npm run build          # tsdown → dist/index.mjs + dist/index.d.mts
 npm run build:client   # vite → lib/client.js
 npm run dev:ui         # settings-page dev server (host must run at 127.0.0.1:23023)
-npm run prepublishOnly # pre-publish gate: typecheck + test + build + build:client
+npm run prepublishOnly # pre-publish gate: typecheck + test + build + build:client + npm pack --dry-run
 ```
 
 `dist/` and `lib/` are **committed** artifacts: after changing `src/` or `ui/`

package/README.md

@@ -35,14 +35,14 @@ flowchart TB
 > **DSH 版本需求**：`>=0.2.0-rc.2 <0.3.0-0`（由 `package.json` 的 `engines.dsh` 声明；不满足时 bundle 被跳过、设置页里该插件的行被禁用，确需在区间外使用可用 `dsh plugin allow-version` 精确豁免。0.3.0 需重新评估兼容性后再放开）。
 
 ```bash
-# 从 GitHub 安装（推荐）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge
+# 从 npm 安装（推荐，钉住版本）
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.6
 
-# 钉住版本标签（生产推荐）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.5
+# 安装 npm 最新发布版
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
-# 或从 npm registry 安装
-dsh plugin --profile <name> add dsh-cherry-bridge
+# 从 GitHub 源码安装（与 npm 发布同一提交）
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.6
 ```
 
 本包自带 `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（分页）。 |
-| `cherry_workspaces` | 列出某 agent 的**已注册**工作区，以及是否存在系统工作区。 |
-| `cherry_sessions` | 列出某 agent 的会话，可按工作区过滤。 |
+| `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_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。 |
+| `cherry_events` | 读取该会话缓冲区内比 `cursor` 更新的事件，并在投递后 ack。返回 `{events, nextCursor}`；把 `nextCursor` 作为下次的 `cursor` 传回即可续读。 |
 | `cherry_create` | 在 agent 工作区创建会话（工作区选择**必填**；创建后回读身份）。 |
 | `cherry_send` | 向会话发消息，默认等待运行到终态并返回助手文本；`wait: false` 立即返回命令回执。内容被截断时 `messagesTruncated`/`messagesTruncationReason` 说的是**消息**被截断（丢更旧的）；`deadline` 表示**回答自身的装配时限**到了（见下），已读到的内容照常返回。 |
 | `cherry_wait` | 只等待该会话在途执行收敛（不发送新消息）。 |
-| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。 |
+| `cherry_interactions` | 列出该会话**待答**的交互卡（提问 / 审批）。被截断时必带 `truncated`+`truncationReason`，并给出 `resumeCursor`——用 `sessionId` 相同的调用回传为 `cursor` 即可续读（`limit` 计的是过滤**前**的对端条目）。 |
 | `cherry_respond` | 应答交互卡：提问必须全量作答，审批走 `decision`。 |
 | `cherry_cancel` | 取消会话在途执行（`expectedExecutionId` 必填）。 |
 | `cherry_pair` | 用「扫码后页面显示的配对信息」建立与桌面端的配对。 |
@@ -176,7 +176,7 @@ npm run typecheck      # 服务端 + UI 两侧
 npm run build          # tsdown → dist/index.mjs + dist/index.d.mts
 npm run build:client   # vite → lib/client.js
 npm run dev:ui         # 设置页 dev server（需宿主在 127.0.0.1:23023 运行）
-npm run prepublishOnly # 发布前闸门：typecheck + test + build + build:client
+npm run prepublishOnly # 发布前闸门：typecheck + test + build + build:client + npm pack --dry-run
 ```
 
 `dist/` 与 `lib/` 是**随仓库提交**的产物：改完 `src/` 或 `ui/` 必须重跑

package/dist/index.mjs

@@ -5445,6 +5445,30 @@ var CherryToolEngine = class {
 			...pageOverflow === void 0 ? {} : { pageOverflow }
 		};
 	}
+	/** Decode one list `cursor` argument, or undefined when none was given. */
+	#listResume(raw, binding) {
+		if (raw === void 0 || raw === null) return void 0;
+		return {
+			kind: "cursor",
+			cursor: parseListResumeCursor(raw, binding)
+		};
+	}
+	/**
+	* The public shape of a list walk's result: items, the stop verdict, and — only
+	* when the walk really stopped at a peer position — the RESUMABLE token.
+	*
+	* The peer's own position never leaves this method: it is opaque, unusable as
+	* an input on its own, and exposing it invited callers to replay it (issue
+	* #65). What a caller can act on is a token, so that is what is emitted.
+	*/
+	#listPage(page, binding) {
+		return {
+			items: page.items,
+			truncated: page.truncated,
+			...page.truncationReason === void 0 ? {} : { truncationReason: page.truncationReason },
+			...page.truncated && page.nextCursor !== void 0 ? { resumeCursor: encodeListResumeCursor(binding, page.nextCursor) } : {}
+		};
+	}
 	#devicesTool() {
 		return defineCherryTool({
 			name: "cherry_devices",
@@ -5521,7 +5545,7 @@ var CherryToolEngine = class {
 	#agentsTool() {
 		return defineCherryTool({
 			name: "cherry_agents",
-			description: "List the Cherry Studio agents available on a device. Paginated: `limit` bounds the TOTAL across pages (default 100, max 1000) and is aggregated internally.",
+			description: "List the Cherry Studio agents available on a device. Paginated: `limit` bounds the TOTAL across pages (default 100, max 1000) and is aggregated internally. A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). A truncated answer also carries `resumeCursor`: replay it as `cursor` with the same tool, device and filters to continue from that stop point (`limit` then bounds the next answer).",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5534,7 +5558,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of agents to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device"],
 				additionalProperties: false
@@ -5542,18 +5567,28 @@ var CherryToolEngine = class {
 			execute: async (args) => {
 				const resolved = this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
-				const { connection } = resolved.link;
-				return this.#aggregate(connection, "agent.agents.list", {}, (page) => ({
-					...arrayOf(page["items"]),
-					nextCursor: page["nextCursor"]
-				}), { limit: aggregateLimit(args["limit"]) });
+				const { connection, record } = resolved.link;
+				const binding = {
+					method: "agent.agents.list",
+					deviceId: record.deviceId,
+					params: {}
+				};
+				const resume = this.#listResume(args["cursor"], binding);
+				const page = await this.#aggregate(connection, "agent.agents.list", {}, (result) => ({
+					...arrayOf(result["items"]),
+					nextCursor: result["nextCursor"]
+				}), {
+					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume }
+				});
+				return this.#listPage(page, binding);
 			}
 		});
 	}
 	#workspacesTool() {
 		return defineCherryTool({
 			name: "cherry_workspaces",
-			description: "List an agent's REGISTERED workspaces, plus whether a system workspace exists. The system workspace has no enumerable id: it is not in `items`, and its identity is only observable by creating a session in it and reading it back.",
+			description: "List an agent's REGISTERED workspaces, plus whether a system workspace exists. The system workspace has no enumerable id: it is not in `items`, and its identity is only observable by creating a session in it and reading it back. A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran out and carries `resumeCursor`: replay it as `cursor` with the same filters to continue.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5570,7 +5605,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of workspaces to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device", "agentId"],
 				additionalProperties: false
@@ -5578,21 +5614,28 @@ var CherryToolEngine = class {
 			execute: async (args) => {
 				const resolved = this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
-				const { connection } = resolved.link;
-				const agentId = requiredString(args, "agentId");
+				const { connection, record } = resolved.link;
+				const params = { agentId: requiredString(args, "agentId") };
+				const binding = {
+					method: "agent.workspaces.list",
+					deviceId: record.deviceId,
+					params
+				};
+				const resume = this.#listResume(args["cursor"], binding);
 				let systemWorkspace = false;
-				const page = await this.#aggregate(connection, "agent.workspaces.list", { agentId }, (result) => {
+				const page = await this.#aggregate(connection, "agent.workspaces.list", params, (result) => {
 					if (typeof result["systemWorkspace"] === "boolean") systemWorkspace = result["systemWorkspace"];
 					return {
 						...arrayOf(result["items"]),
 						nextCursor: result["nextCursor"]
 					};
-				}, { limit: aggregateLimit(args["limit"]) });
+				}, {
+					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume }
+				});
 				return {
-					items: page.items,
-					systemWorkspace,
-					truncated: page.truncated,
-					...page.truncationReason === void 0 ? {} : { truncationReason: page.truncationReason }
+					...this.#listPage(page, binding),
+					systemWorkspace
 				};
 			}
 		});
@@ -5600,7 +5643,7 @@ var CherryToolEngine = class {
 	#sessionsTool() {
 		return defineCherryTool({
 			name: "cherry_sessions",
-			description: "List an agent's sessions, optionally filtered by workspace. The `agentId` and `workspaceId` filters pass straight through to the peer. Paginated: `limit` bounds the TOTAL across pages (default 100, max 1000) and is aggregated internally.",
+			description: "List an agent's sessions, optionally filtered by workspace. The `agentId` and `workspaceId` filters pass straight through to the peer. Paginated: `limit` bounds the TOTAL across pages (default 100, max 1000) and is aggregated internally. A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). A truncated answer also carries `resumeCursor`: replay it as `cursor` with the same tool, device and filters to continue from that stop point (`limit` then bounds the next answer).",
 			parameters: {
 				type: "object",
 				properties: {
@@ -5621,7 +5664,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of sessions to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device"],
 				additionalProperties: false
@@ -5629,16 +5673,27 @@ var CherryToolEngine = class {
 			execute: async (args) => {
 				const resolved = this.#linkOr(requiredString(args, "device"));
 				if (resolved.link === void 0) return resolved.verdict;
-				const { connection } = resolved.link;
+				const { connection, record } = resolved.link;
 				const agentId = optionalString(args["agentId"]);
 				const workspaceId = optionalString(args["workspaceId"]);
-				return this.#aggregate(connection, "agent.sessions.list", {
+				const params = {
 					...agentId === void 0 ? {} : { agentId },
 					...workspaceId === void 0 ? {} : { workspaceId }
-				}, (page) => ({
-					...arrayOf(page["items"]),
-					nextCursor: page["nextCursor"]
-				}), { limit: aggregateLimit(args["limit"]) });
+				};
+				const binding = {
+					method: "agent.sessions.list",
+					deviceId: record.deviceId,
+					params
+				};
+				const resume = this.#listResume(args["cursor"], binding);
+				const page = await this.#aggregate(connection, "agent.sessions.list", params, (result) => ({
+					...arrayOf(result["items"]),
+					nextCursor: result["nextCursor"]
+				}), {
+					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume }
+				});
+				return this.#listPage(page, binding);
 			}
 		});
 	}
@@ -6061,7 +6116,7 @@ var CherryToolEngine = class {
 	#eventsTool() {
 		return defineCherryTool({
 			name: "cherry_events",
-			description: "Read the session's buffered events newer than `cursor`, delivering them and then acknowledging the advanced cursor to the peer. While the window has dropped no events, every cursor this plugin handed out is servable, including the baseline `cherry_send`/`cherry_wait` report on an empty window. Once the window DISCARDS events, the boundary it reports is not: that boundary and everything below it answer a structured `cursor-out-of-window` verdict, and only positions strictly past it are served — rebuild the baseline with `cherry_read` and resume from that instead.",
+			description: "Read the session's buffered events newer than `cursor`, delivering them and then acknowledging the advanced cursor to the peer. While the window has dropped no events, every cursor this plugin handed out is servable, including the baseline `cherry_send`/`cherry_wait` report on an empty window. Once the window DISCARDS events, the boundary it reports is not: that boundary and everything below it answer a structured `cursor-out-of-window` verdict, and only positions strictly past it are served — rebuild the baseline with `cherry_read` and resume from that instead. The answer is `{events, nextCursor}`; pass that `nextCursor` back as `cursor` on the next call to continue from it.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6419,7 +6474,7 @@ var CherryToolEngine = class {
 	#interactionsTool() {
 		return defineCherryTool({
 			name: "cherry_interactions",
-			description: "List the session's PENDING interactions (questions and approval decisions) that need an answer. The peer serves the full four-state set (pending/approved/denied/expired) — the pending filter is applied here. Each entry carries its `kind` (question|decision) and a summary; answer questions with cherry_respond's `response` form and decisions with `decision`.",
+			description: "List the session's PENDING interactions (questions and approval decisions) that need an answer. The peer serves the full four-state set (pending/approved/denied/expired) — the pending filter is applied here. Each entry carries its `kind` (question|decision) and a summary; answer questions with cherry_respond's `response` form and decisions with `decision`. A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran out and carries `resumeCursor`: replay it as `cursor` with the same filters to continue.",
 			parameters: {
 				type: "object",
 				properties: {
@@ -6440,7 +6495,8 @@ var CherryToolEngine = class {
 						minimum: 1,
 						maximum: MAX_AGGREGATE_LIMIT,
 						description: "Maximum number of interactions to return in total across pages (default 100)."
-					}
+					},
+					cursor: LIST_CURSOR_PARAMETER
 				},
 				required: ["device", "sessionId"],
 				additionalProperties: false
@@ -6450,12 +6506,20 @@ var CherryToolEngine = class {
 				if (resolved.link === void 0) return resolved.verdict;
 				const { connection, record } = resolved.link;
 				const sessionId = requiredString(args, "sessionId");
+				const params = { sessionId };
+				const binding = {
+					method: "agent.interactions.list",
+					deviceId: record.deviceId,
+					params
+				};
+				const resume = this.#listResume(args["cursor"], binding);
 				await this.#ensureSubscription(record.deviceId, sessionId);
-				const page = await this.#aggregate(connection, "agent.interactions.list", { sessionId }, (result) => ({
+				const page = await this.#aggregate(connection, "agent.interactions.list", params, (result) => ({
 					...arrayOf(result["items"]),
 					nextCursor: result["nextCursor"]
 				}), {
 					limit: aggregateLimit(args["limit"]),
+					...resume === void 0 ? {} : { resume },
 					safetyBound: MAX_AGGREGATE_LIMIT,
 					maxPerPage: INTERACTIONS_LIST_PAGE_CLAMP
 				});
@@ -6463,9 +6527,8 @@ var CherryToolEngine = class {
 				const items = page.items.filter((item) => includeAnswered || item["status"] === "pending").map((item) => this.#interactionView(item));
 				for (const item of page.items) this.#rememberInteraction(record.deviceId, sessionId, item);
 				return {
-					items,
-					truncated: page.truncated,
-					...page.truncationReason === void 0 ? {} : { truncationReason: page.truncationReason }
+					...this.#listPage(page, binding),
+					items
 				};
 			}
 		});
@@ -8187,6 +8250,69 @@ function parseMessageResume(value) {
 	return refuse();
 }
 /**
+* The LIST face's stop point (issue #65): a self-describing token that the SAME
+* tool accepts back, bound to the query that produced it.
+*
+* The message face wraps the peer position in `cursor:` / `after:` and is done,
+* because a message walk is scoped by its session. A list walk is scoped by
+* (method, device, filters), and the peer position is opaque: a position from
+* another query is a perfectly valid number that reads the WRONG slice with no
+* error anywhere. So this token carries a fingerprint of the binding and a
+* mismatched replay is refused HERE — before any RPC.
+*/
+const LIST_RESUME_PREFIX = "cursor:";
+/** The `cursor` parameter every list tool shares (issue #65). */
+const LIST_CURSOR_PARAMETER = {
+	type: "string",
+	description: "A `resumeCursor` a previous TRUNCATED answer of this tool returned: replay it with the SAME device and filters to continue from that stop point (`limit` then bounds this answer). A token from another tool, device or filter set is refused locally."
+};
+/** Canonical, key-sorted rendering of the caller's filters (undefined keys dropped). */
+function listParamsFingerprint(params) {
+	const entries = Object.keys(params).sort().filter((key) => params[key] !== void 0).map((key) => [key, params[key]]);
+	return createHash("sha256").update(JSON.stringify(entries)).digest("hex").slice(0, 16);
+}
+function encodeListResumeCursor(binding, peerPosition) {
+	const payload = {
+		v: 1,
+		m: binding.method,
+		d: binding.deviceId,
+		h: listParamsFingerprint(binding.params),
+		p: peerPosition
+	};
+	return LIST_RESUME_PREFIX + Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+/**
+* Decode a list token, refusing anything that is not one this tool emitted for
+* THIS binding. The refusal names the dimension that differs (tool / device /
+* filters) and never echoes the peer position, which is peer-supplied data.
+*
+* An `after:` token is refused by the prefix check: list walks have no anchor
+* form (they never trim a page, so a peer position always exists for a stop the
+* peer reported).
+*/
+function parseListResumeCursor(value, binding) {
+	const refuse = (why) => {
+		throw new Error(`cursor ${why}; omit \`cursor\` to read from the start, or replay the token with the same tool, device and filters.`);
+	};
+	if (typeof value !== "string" || !value.startsWith(LIST_RESUME_PREFIX)) refuse("must be a `cursor:` token this tool emitted");
+	const raw = value.slice(7);
+	let decoded;
+	try {
+		decoded = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+	} catch {
+		refuse("is not a token this tool emitted");
+	}
+	if (typeof decoded !== "object" || decoded === null) refuse("is not a token this tool emitted");
+	const payload = decoded;
+	if (payload["v"] !== 1 || typeof payload["m"] !== "string" || typeof payload["d"] !== "string" || typeof payload["h"] !== "string" || typeof payload["p"] !== "string") refuse("is not a token this tool emitted");
+	if (payload["m"] !== binding.method) refuse("was issued for a different tool");
+	if (payload["d"] !== binding.deviceId) refuse("was issued for a different device");
+	if (payload["h"] !== listParamsFingerprint(binding.params)) refuse("was issued for a different filter set");
+	const peerPosition = payload["p"];
+	if (mangledRemainder(peerPosition)) refuse("is not a token this tool emitted");
+	return peerPosition;
+}
+/**
 * The assistant text a terminal aggregate reports: the awaited RUN's assistant
 * message text parts, joined.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cherry-bridge",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "private": false,
   "packageManager": "npm@10.9.9",

package/src/tools.ts

@@ -2082,6 +2082,31 @@ class CherryToolEngine {
     }
   }
 
+  /** Decode one list `cursor` argument, or undefined when none was given. */
+  #listResume(raw: unknown, binding: ListResumeBinding): { kind: 'cursor'; cursor: string } | undefined {
+    if (raw === undefined || raw === null) return undefined
+    return { kind: 'cursor', cursor: parseListResumeCursor(raw, binding) }
+  }
+
+  /**
+   * The public shape of a list walk's result: items, the stop verdict, and — only
+   * when the walk really stopped at a peer position — the RESUMABLE token.
+   *
+   * The peer's own position never leaves this method: it is opaque, unusable as
+   * an input on its own, and exposing it invited callers to replay it (issue
+   * #65). What a caller can act on is a token, so that is what is emitted.
+   */
+  #listPage(page: CherryPage<Record<string, unknown>>, binding: ListResumeBinding): Record<string, unknown> {
+    return {
+      items: page.items,
+      truncated: page.truncated,
+      ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
+      ...(page.truncated && page.nextCursor !== undefined
+        ? { resumeCursor: encodeListResumeCursor(binding, page.nextCursor) }
+        : {}),
+    }
+  }
+
   // -------------------------------------------------------------------------
   // ① cherry_devices
   // -------------------------------------------------------------------------
@@ -2179,7 +2204,11 @@ class CherryToolEngine {
       name: 'cherry_agents',
       description:
         'List the Cherry Studio agents available on a device. Paginated: `limit` bounds ' +
-        'the TOTAL across pages (default 100, max 1000) and is aggregated internally.',
+        'the TOTAL across pages (default 100, max 1000) and is aggregated internally. ' +
+        'A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran ' +
+        'out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). A truncated ' +
+        'answer also carries `resumeCursor`: replay it as `cursor` with the same tool, device and ' +
+        'filters to continue from that stop point (`limit` then bounds the next answer).',
       parameters: {
         type: 'object',
         properties: {
@@ -2190,6 +2219,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of agents to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device'],
         additionalProperties: false,
@@ -2197,14 +2227,17 @@ class CherryToolEngine {
       execute: async (args) => {
         const resolved = this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
-        const { connection } = resolved.link
-        return this.#aggregate(
+        const { connection, record } = resolved.link
+        const binding: ListResumeBinding = { method: 'agent.agents.list', deviceId: record.deviceId, params: {} }
+        const resume = this.#listResume(args['cursor'], binding)
+        const page = await this.#aggregate(
           connection,
           'agent.agents.list',
           {},
-          (page) => ({ ...arrayOf(page['items']), nextCursor: page['nextCursor'] }),
-          { limit: aggregateLimit(args['limit']) },
+          (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
+          { limit: aggregateLimit(args['limit']), ...(resume === undefined ? {} : { resume }) },
         )
+        return this.#listPage(page, binding)
       },
     })
   }
@@ -2215,7 +2248,9 @@ class CherryToolEngine {
       description:
         'List an agent\'s REGISTERED workspaces, plus whether a system workspace exists. ' +
         'The system workspace has no enumerable id: it is not in `items`, and its identity ' +
-        'is only observable by creating a session in it and reading it back.',
+        'is only observable by creating a session in it and reading it back. A truncated ' +
+        'answer (`truncated` + `truncationReason`) stopped before the peer ran out and carries ' +
+        '`resumeCursor`: replay it as `cursor` with the same filters to continue.',
       parameters: {
         type: 'object',
         properties: {
@@ -2227,6 +2262,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of workspaces to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device', 'agentId'],
         additionalProperties: false,
@@ -2234,27 +2270,25 @@ class CherryToolEngine {
       execute: async (args) => {
         const resolved = this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
-        const { connection } = resolved.link
+        const { connection, record } = resolved.link
         const agentId = requiredString(args, 'agentId')
+        const params = { agentId }
+        const binding: ListResumeBinding = { method: 'agent.workspaces.list', deviceId: record.deviceId, params }
+        const resume = this.#listResume(args['cursor'], binding)
         let systemWorkspace = false
         const page = await this.#aggregate(
           connection,
           'agent.workspaces.list',
-          { agentId },
+          params,
           (result) => {
             // The flag rides on every page; the last page read wins, and the
             // real peer always sends it.
             if (typeof result['systemWorkspace'] === 'boolean') systemWorkspace = result['systemWorkspace']
             return { ...arrayOf(result['items']), nextCursor: result['nextCursor'] }
           },
-          { limit: aggregateLimit(args['limit']) },
+          { limit: aggregateLimit(args['limit']), ...(resume === undefined ? {} : { resume }) },
         )
-        return {
-          items: page.items,
-          systemWorkspace,
-          truncated: page.truncated,
-          ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
-        }
+        return { ...this.#listPage(page, binding), systemWorkspace }
       },
     })
   }
@@ -2265,7 +2299,11 @@ class CherryToolEngine {
       description:
         'List an agent\'s sessions, optionally filtered by workspace. The `agentId` and ' +
         '`workspaceId` filters pass straight through to the peer. Paginated: `limit` bounds ' +
-        'the TOTAL across pages (default 100, max 1000) and is aggregated internally.',
+        'the TOTAL across pages (default 100, max 1000) and is aggregated internally. ' +
+        'A truncated answer (`truncated` + `truncationReason`) stopped before the peer ran ' +
+        'out (`limit` is your ceiling, `safety-bound` the 1000-item internal one). A truncated ' +
+        'answer also carries `resumeCursor`: replay it as `cursor` with the same tool, device and ' +
+        'filters to continue from that stop point (`limit` then bounds the next answer).',
       parameters: {
         type: 'object',
         properties: {
@@ -2278,6 +2316,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of sessions to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device'],
         additionalProperties: false,
@@ -2285,21 +2324,27 @@ class CherryToolEngine {
       execute: async (args) => {
         const resolved = this.#linkOr(requiredString(args, 'device'))
         if (resolved.link === undefined) return resolved.verdict
-        const { connection } = resolved.link
+        const { connection, record } = resolved.link
         const agentId = optionalString(args['agentId'])
         const workspaceId = optionalString(args['workspaceId'])
         // Filter passthrough: the params carry the caller's filters verbatim,
-        // and `#aggregate` adds only `limit`/`cursor`.
-        return this.#aggregate(
+        // and `#aggregate` adds only `limit`/`cursor`. The SAME object is the
+        // token's binding, so a replay with other filters cannot read another
+        // query's page position.
+        const params = {
+          ...(agentId === undefined ? {} : { agentId }),
+          ...(workspaceId === undefined ? {} : { workspaceId }),
+        }
+        const binding: ListResumeBinding = { method: 'agent.sessions.list', deviceId: record.deviceId, params }
+        const resume = this.#listResume(args['cursor'], binding)
+        const page = await this.#aggregate(
           connection,
           'agent.sessions.list',
-          {
-            ...(agentId === undefined ? {} : { agentId }),
-            ...(workspaceId === undefined ? {} : { workspaceId }),
-          },
-          (page) => ({ ...arrayOf(page['items']), nextCursor: page['nextCursor'] }),
-          { limit: aggregateLimit(args['limit']) },
+          params,
+          (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
+          { limit: aggregateLimit(args['limit']), ...(resume === undefined ? {} : { resume }) },
         )
+        return this.#listPage(page, binding)
       },
     })
   }
@@ -3064,7 +3109,9 @@ class CherryToolEngine {
         '`cherry_send`/`cherry_wait` report on an empty window. Once the window DISCARDS events, ' +
         'the boundary it reports is not: that boundary and everything below it answer a structured ' +
         '`cursor-out-of-window` verdict, and only positions strictly past it are served — rebuild ' +
-        'the baseline with `cherry_read` and resume from that instead.',
+        'the baseline with `cherry_read` and resume from that instead. The answer is ' +
+        '`{events, nextCursor}`; pass that `nextCursor` back as `cursor` on the next call to ' +
+        'continue from it.',
       parameters: {
         type: 'object',
         properties: {
@@ -3694,7 +3741,9 @@ class CherryToolEngine {
         'answer. The peer serves the full four-state set (pending/approved/denied/expired) — the ' +
         'pending filter is applied here. Each entry carries its `kind` (question|decision) and a ' +
         'summary; answer questions with cherry_respond\'s `response` form and decisions with ' +
-        '`decision`.',
+        '`decision`. A truncated answer (`truncated` + `truncationReason`) stopped before the ' +
+        'peer ran out and carries `resumeCursor`: replay it as `cursor` with the same filters to ' +
+        'continue.',
       parameters: {
         type: 'object',
         properties: {
@@ -3712,6 +3761,7 @@ class CherryToolEngine {
             maximum: MAX_AGGREGATE_LIMIT,
             description: 'Maximum number of interactions to return in total across pages (default 100).',
           },
+          cursor: LIST_CURSOR_PARAMETER,
         },
         required: ['device', 'sessionId'],
         additionalProperties: false,
@@ -3721,6 +3771,9 @@ class CherryToolEngine {
         if (resolved.link === undefined) return resolved.verdict
         const { connection, record } = resolved.link
         const sessionId = requiredString(args, 'sessionId')
+        const params = { sessionId }
+        const binding: ListResumeBinding = { method: 'agent.interactions.list', deviceId: record.deviceId, params }
+        const resume = this.#listResume(args['cursor'], binding)
 
         await this.#ensureSubscription(record.deviceId, sessionId)
 
@@ -3730,10 +3783,11 @@ class CherryToolEngine {
         const page = await this.#aggregate(
           connection,
           'agent.interactions.list',
-          { sessionId },
+          params,
           (result) => ({ ...arrayOf(result['items']), nextCursor: result['nextCursor'] }),
           {
             limit: aggregateLimit(args['limit']),
+            ...(resume === undefined ? {} : { resume }),
             safetyBound: MAX_AGGREGATE_LIMIT,
             // An interaction record carries an inline input AND an inline
             // summary, the fattest item of the plain lists.
@@ -3752,11 +3806,7 @@ class CherryToolEngine {
         // docblock): priming from it is what makes every listed card answerable.
         for (const item of page.items) this.#rememberInteraction(record.deviceId, sessionId, item)
 
-        return {
-          items,
-          truncated: page.truncated,
-          ...(page.truncationReason === undefined ? {} : { truncationReason: page.truncationReason }),
-        }
+        return { ...this.#listPage(page, binding), items }
       },
     })
   }
@@ -6187,6 +6237,100 @@ function parseMessageResume(value: unknown): MessageResume | undefined {
   return refuse()
 }
 
+/**
+ * The LIST face's stop point (issue #65): a self-describing token that the SAME
+ * tool accepts back, bound to the query that produced it.
+ *
+ * The message face wraps the peer position in `cursor:` / `after:` and is done,
+ * because a message walk is scoped by its session. A list walk is scoped by
+ * (method, device, filters), and the peer position is opaque: a position from
+ * another query is a perfectly valid number that reads the WRONG slice with no
+ * error anywhere. So this token carries a fingerprint of the binding and a
+ * mismatched replay is refused HERE — before any RPC.
+ */
+const LIST_RESUME_PREFIX = 'cursor:'
+
+/** The `cursor` parameter every list tool shares (issue #65). */
+const LIST_CURSOR_PARAMETER = {
+  type: 'string',
+  description:
+    'A `resumeCursor` a previous TRUNCATED answer of this tool returned: replay it with the SAME ' +
+    'device and filters to continue from that stop point (`limit` then bounds this answer). A token ' +
+    'from another tool, device or filter set is refused locally.',
+} as const
+
+/** What a list token is valid for. `params` are the CALLER's filters, not the wire page params. */
+interface ListResumeBinding {
+  method: string
+  deviceId: string
+  params: Record<string, unknown>
+}
+
+/** Canonical, key-sorted rendering of the caller's filters (undefined keys dropped). */
+function listParamsFingerprint(params: Record<string, unknown>): string {
+  const entries = Object.keys(params)
+    .sort()
+    .filter((key) => params[key] !== undefined)
+    .map((key) => [key, params[key]] as const)
+  return createHash('sha256').update(JSON.stringify(entries)).digest('hex').slice(0, 16)
+}
+
+function encodeListResumeCursor(binding: ListResumeBinding, peerPosition: string): string {
+  const payload = {
+    v: 1,
+    m: binding.method,
+    d: binding.deviceId,
+    h: listParamsFingerprint(binding.params),
+    p: peerPosition,
+  }
+  return LIST_RESUME_PREFIX + Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')
+}
+
+/**
+ * Decode a list token, refusing anything that is not one this tool emitted for
+ * THIS binding. The refusal names the dimension that differs (tool / device /
+ * filters) and never echoes the peer position, which is peer-supplied data.
+ *
+ * An `after:` token is refused by the prefix check: list walks have no anchor
+ * form (they never trim a page, so a peer position always exists for a stop the
+ * peer reported).
+ */
+function parseListResumeCursor(value: unknown, binding: ListResumeBinding): string {
+  const refuse = (why: string): never => {
+    throw new Error(
+      `cursor ${why}; omit \`cursor\` to read from the start, or replay the token with the same tool, ` +
+        'device and filters.',
+    )
+  }
+  if (typeof value !== 'string' || !value.startsWith(LIST_RESUME_PREFIX)) {
+    refuse('must be a `cursor:` token this tool emitted')
+  }
+  const raw = (value as string).slice(LIST_RESUME_PREFIX.length)
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'))
+  } catch {
+    refuse('is not a token this tool emitted')
+  }
+  if (typeof decoded !== 'object' || decoded === null) refuse('is not a token this tool emitted')
+  const payload = decoded as Record<string, unknown>
+  if (
+    payload['v'] !== 1 ||
+    typeof payload['m'] !== 'string' ||
+    typeof payload['d'] !== 'string' ||
+    typeof payload['h'] !== 'string' ||
+    typeof payload['p'] !== 'string'
+  ) {
+    refuse('is not a token this tool emitted')
+  }
+  if (payload['m'] !== binding.method) refuse('was issued for a different tool')
+  if (payload['d'] !== binding.deviceId) refuse('was issued for a different device')
+  if (payload['h'] !== listParamsFingerprint(binding.params)) refuse('was issued for a different filter set')
+  const peerPosition = payload['p'] as string
+  if (mangledRemainder(peerPosition)) refuse('is not a token this tool emitted')
+  return peerPosition
+}
+
 /**
  * The assistant text a terminal aggregate reports: the awaited RUN's assistant
  * message text parts, joined.