@kangyishuai/dsh-session-rewind 0.2.0 → 0.3.0

package/README.md

@@ -22,6 +22,17 @@ Long conversations drift. A few turns later you wish you had answered a prompt d
 - **Composer.** The target message's text (and images) is put back into the composer, ready to edit and send again. An existing draft is never overwritten. Tick **Send this message again right after rewinding** in the confirmation dialog to retry the turn in one click (conversation-only rewinds).
 - **Rewind panel.** A new header action opens a panel with four tabs: **Withdrawn** (every message each rewind removed, searchable, copy or put back in the composer), **History** (audit of each rewind: scope, message count, tokens, file results), **Rescue points** (restore files from an earlier rescue), and **Settings** (default scope, page size, confirm-on-list, diagnostics).
 
+## Read-only agent tool
+
+The plugin also registers one **read-only** tool, `session_rewind_candidates`, so the model can reason about rewinding without performing it:
+
+| Call                                       | Result                                                                                                                                         |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session_rewind_candidates {}`             | Newest-first list of messages this conversation can be rewound to (`query` filters, `limit` caps at 50).                                       |
+| `session_rewind_candidates { target_seq }` | Impact preview for one message: how many messages would be withdrawn, whether an unfinished tool call would be truncated, and the target text. |
+
+The tool never rewinds, never edits files and never appends to the session log — the rewind itself stays a user action (that is the point of the ADR 0006 design). Set `readOnlyTool: false` to unregister it; **Settings → Diagnostics** reports whether it registered.
+
 ## Install
 
 ```bash

package/README.zh-CN.md

@@ -22,6 +22,17 @@
 - **输入框**：目标消息文本（以及图片）放回输入框，改完可直接重发；已有草稿绝不覆盖。勾选「回退后立即重发」可一键重试这一轮（仅对话模式）。
 - **回溯面板**：会话头部新增一个入口，四个页签：**已撤回**（每次回溯撤回的全部消息，可搜索、复制、放回输入框）、**回溯记录**（审计：范围、条数、token、文件结果）、**救援点**（手动恢复文件）、**设置**（默认范围、每页数量、列表确认、诊断）。
 
+## 只读 agent 工具
+
+插件还会注册一个**只读**工具 `session_rewind_candidates`，让模型能自己判断「能退回到哪、退回去会丢什么」，但**不执行**回溯：
+
+| 调用                                       | 结果                                                                 |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| `session_rewind_candidates {}`             | 按新→旧列出可回退的消息（`query` 过滤，`limit` 上限 50）。           |
+| `session_rewind_candidates { target_seq }` | 单条消息的影响面：会撤回多少条、是否截断未完成的工具调用、目标文本。 |
+
+这个工具不回溯、不碰文件、不写会话日志——真正的回退始终由用户在界面确认（这是 ADR 0006 的设计前提）。设 `readOnlyTool: false` 可关闭；**设置 → 诊断**里能看到它是否注册成功。
+
 ## 安装
 
 ```bash

package/lib/service.js

@@ -29,6 +29,7 @@ import {
 } from "./operations.js";
 import { findOrphans, pruneOrphans } from "./orphans.js";
 import { cutsOf, hasOpenToolCalls, listCandidatesPage, targetContent } from "./plan.js";
+import { describeToolImpact, installRewindTool, listToolCandidates } from "./tool.js";
 
 /**
  * 在 decorator 语法不可用（V8 装饰器关闭）的运行时里登记一个 Remote 方法。
@@ -162,6 +163,18 @@ export class SessionRewindService extends TypertRemoteService {
     this._store = null;
     this.installFileTracking();
     this.installCommand();
+    // 只读 agent 工具：让模型自己看清候选与影响面（绝不执行回溯）。
+    this.readOnlyToolInstalled = false;
+    if (this.config.readOnlyTool !== false) {
+      installRewindTool({
+        ctx: this.ctx,
+        logger: this.ctx?.logger ?? console,
+        host: { call: (sessionId, request) => this.toolPayload(sessionId, request) },
+        onInstalled: () => {
+          this.readOnlyToolInstalled = true;
+        },
+      });
+    }
     // 启动时清一次已删除会话的残留数据（失败只告警，不阻塞插件）。
     if (this.config.cleanupOrphans !== false) void this.cleanupOrphans();
   }
@@ -398,6 +411,58 @@ export class SessionRewindService extends TypertRemoteService {
     }
   }
 
+  /**
+   * 只读工具的数据面：候选列表 / 单条影响面。绝不写日志。
+   * @param {string} sessionId
+   * @param {{query?: string, limit?: number, targetSeq?: number}} [request]
+   * @returns {Promise<any>}
+   */
+  async toolPayload(sessionId, request) {
+    try {
+      const deps = this.deps();
+      const { session } = sessionEvents(deps, sessionId);
+      const events = session.snapshotEvents();
+      const nodes = Array.isArray(session.surface?.nodes) ? session.surface.nodes : [];
+      if (typeof request?.targetSeq === "number") {
+        const impact = describeToolImpact(events, nodes, request.targetSeq);
+        if (impact.ok !== true)
+          return { ok: true, value: { kind: "error", session_id: sessionId, error: impact.error } };
+        return {
+          ok: true,
+          value: {
+            kind: "impact",
+            session_id: sessionId,
+            impact: {
+              target_seq: impact.targetSeq,
+              removed_messages: impact.removedCount,
+              crosses_open_tool_call: impact.crossesOpenToolCall,
+              text: impact.text,
+            },
+          },
+        };
+      }
+      const listed = listToolCandidates(events, nodes, {
+        ...(typeof request?.query === "string" ? { query: request.query } : {}),
+        ...(typeof request?.limit === "number" ? { limit: request.limit } : {}),
+      });
+      return {
+        ok: true,
+        value: {
+          kind: "list",
+          session_id: sessionId,
+          total: listed.total,
+          candidates: listed.items.map((item) => ({
+            seq: item.seq,
+            ...(typeof item.time === "number" ? { time: item.time } : {}),
+            preview: item.preview,
+          })),
+        },
+      };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
   /**
    * 回溯预览（dry-run）：不写任何东西。
    * @param {{sessionId?: string, targetSeq?: number}} [request]
@@ -837,6 +902,15 @@ export class SessionRewindService extends TypertRemoteService {
     } catch (error) {
       push("审计日志", false, error instanceof Error ? error.message : String(error));
     }
+    push(
+      "只读工具",
+      this.config.readOnlyTool === false ? true : this.readOnlyToolInstalled === true,
+      this.config.readOnlyTool === false
+        ? "disabled by config"
+        : this.readOnlyToolInstalled === true
+          ? "enabled"
+          : "not registered",
+    );
     try {
       const orphans = await findOrphans({ dataRoot: this.dataRoot });
       const count = orphans.sessionIds.length + orphans.trashIds.length + orphans.rescueIds.length;

package/lib/tool.js

@@ -0,0 +1,254 @@
+// @ts-check
+// 只读 agent 工具 `session_rewind_candidates`：让模型自己看清「能退回到哪几步、退回去会丢什么」。
+//
+// 设计约束：
+//   - 只读：绝不写日志、绝不执行回溯。真正的回退仍由用户点确认框触发（ADR 0006）。
+//   - 不 import 宿主包（defineTool 在 @deepseek-ai/dsh-tools 里，插件不能依赖）；这里直接
+//     构造 registry 需要的普通对象，`parameters` 与 `output.schema` 都是标准 JSON Schema。
+//   - 形状不符就静默跳过：老版本没有 `tools` 服务时，插件其余功能照常工作。
+import { hasOpenToolCalls, listCandidatesPage, planRewind } from "./plan.js";
+
+/** 工具名（小写下划线，符合宿主 run_code 之外的自定义工具习惯）。 */
+export const TOOL_NAME = "session_rewind_candidates";
+
+/** 一次最多列多少条候选。 */
+export const TOOL_MAX_LIMIT = 50;
+/** 默认条数。 */
+export const TOOL_DEFAULT_LIMIT = 10;
+
+/**
+ * 把面向模型的省略描述压成一行。
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function oneLine(text, max) {
+  const flat = String(text ?? "")
+    .replace(/\s+/gu, " ")
+    .trim();
+  return flat.length <= max ? flat : `${flat.slice(0, Math.max(max - 1, 1))}…`;
+}
+
+/**
+ * 列出可回退的候选消息。
+ * @param {any[]} events
+ * @param {number[]} surfaceNodes
+ * @param {{query?: string, limit?: number}} [options]
+ * @returns {{sessionId?: string, total: number, items: Array<{seq: number, time: number, preview: string, text: string}>}}
+ */
+export function listToolCandidates(events, surfaceNodes, options = {}) {
+  const limit =
+    Number.isSafeInteger(options.limit) && Number(options.limit) > 0
+      ? Math.min(Number(options.limit), TOOL_MAX_LIMIT)
+      : TOOL_DEFAULT_LIMIT;
+  const page = listCandidatesPage(events, surfaceNodes, {
+    limit,
+    q: typeof options.query === "string" ? options.query : "",
+  });
+  return {
+    total: page.candidates.length,
+    items: page.candidates.map((candidate) => ({
+      seq: candidate.seq,
+      time: candidate.time,
+      preview: oneLine(candidate.preview ?? candidate.text ?? "", 160),
+      text: String(candidate.text ?? ""),
+    })),
+  };
+}
+
+/**
+ * 评估「退回到这条消息」的影响面：撤回多少条消息、有没有未完成的工具调用。
+ * @param {any[]} events
+ * @param {number[]} surfaceNodes
+ * @param {number} targetSeq
+ * @returns {{ok: true, targetSeq: number, removedCount: number, crossesOpenToolCall: boolean, text: string} | {ok: false, error: string}}
+ */
+export function describeToolImpact(events, surfaceNodes, targetSeq) {
+  const plan = planRewind(events, surfaceNodes, targetSeq);
+  if ("error" in plan) return { ok: false, error: String(plan.error?.code ?? plan.error) };
+  return {
+    ok: true,
+    targetSeq,
+    removedCount: plan.shadowedSeqs.length,
+    crossesOpenToolCall: hasOpenToolCalls(events, targetSeq),
+    // planRewind 已经把目标消息的文本拼好（`user/message` 的 data 本身就是 message）。
+    text: typeof plan.text === "string" ? plan.text : "",
+  };
+}
+
+/**
+ * 构造工具定义（不依赖宿主 defineTool）。
+ * @param {{call: (sessionId: string, request: any) => Promise<any>}} host
+ * @returns {any}
+ */
+export function createRewindToolDefinition(host) {
+  return {
+    name: TOOL_NAME,
+    description:
+      "List the user messages this conversation can be rewound to, or preview the impact of rewinding to one of them. Read-only: it never rewinds, never edits files and never appends to the session log. The user performs the actual rewind from the UI.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        query: {
+          type: "string",
+          description: "Optional case-insensitive substring filter over message text.",
+        },
+        limit: {
+          type: "integer",
+          description: `How many candidates to return (default ${TOOL_DEFAULT_LIMIT}, max ${TOOL_MAX_LIMIT}; clamped).`,
+        },
+        target_seq: {
+          type: "integer",
+          description:
+            "Preview the impact of rewinding to this message sequence instead of listing candidates.",
+        },
+      },
+    },
+    output: {
+      // 标准 JSON Schema（宿主的受支持子集）：`required` 必须是字符串数组，
+      // 不接受 defineTool 那种 `required: true` 的属性级写法。
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["kind"],
+        properties: {
+          kind: { type: "string", enum: ["list", "impact", "error"] },
+          session_id: { type: "string" },
+          total: { type: "integer" },
+          candidates: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              required: ["seq"],
+              properties: {
+                seq: { type: "integer" },
+                time: { type: "integer" },
+                preview: { type: "string" },
+              },
+            },
+          },
+          impact: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              target_seq: { type: "integer" },
+              removed_messages: { type: "integer" },
+              crosses_open_tool_call: { type: "boolean" },
+              text: { type: "string" },
+            },
+          },
+          error: { type: "string" },
+        },
+      },
+      /**
+       * @param {any} _args
+       * @param {any} value
+       * @returns {any[]}
+       */
+      render: (_args, value) => {
+        const lines = [];
+        if (value?.error) {
+          lines.push(`Rewind preview failed: ${value.error}`);
+        } else if (value?.kind === "impact" && value.impact) {
+          lines.push(
+            `Rewinding to message #${value.impact.target_seq} would withdraw ${value.impact.removed_messages} message(s) from the model context.`,
+          );
+          if (value.impact.crosses_open_tool_call) {
+            lines.push(
+              "Warning: an unfinished tool call follows this message; rewinding truncates it.",
+            );
+          }
+          if (value.impact.text) lines.push(`Target message: ${oneLine(value.impact.text, 400)}`);
+          lines.push("The user must confirm the rewind in the UI; this tool does not perform it.");
+        } else {
+          const candidates = Array.isArray(value?.candidates) ? value.candidates : [];
+          if (candidates.length === 0) {
+            lines.push("No messages can be rewound to in this conversation.");
+          } else {
+            lines.push(
+              `Messages this conversation can be rewound to (${candidates.length} shown):`,
+            );
+            for (const item of candidates) {
+              lines.push(`- #${item.seq}: ${oneLine(item.preview, 160)}`);
+            }
+            lines.push(
+              "Call again with target_seq to preview the impact of one message. Rewinding itself is a user action in the UI.",
+            );
+          }
+        }
+        return [{ type: "text", text: lines.join("\n") }];
+      },
+    },
+    /**
+     * @param {any} args
+     * @param {any} exec
+     * @returns {Promise<any>}
+     */
+    async execute(args, exec) {
+      const sessionId = exec?.agent?.session?.id;
+      if (typeof sessionId !== "string" || sessionId === "") {
+        return { kind: "error", error: "no active session" };
+      }
+      try {
+        const payload = await host.call(sessionId, {
+          query: typeof args?.query === "string" ? args.query : undefined,
+          limit: typeof args?.limit === "number" ? args.limit : undefined,
+          targetSeq: typeof args?.target_seq === "number" ? args.target_seq : undefined,
+        });
+        if (payload?.ok !== true) {
+          return { kind: "error", error: String(payload?.error ?? "unavailable") };
+        }
+        return payload.value;
+      } catch (error) {
+        return {
+          kind: "error",
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}
+
+/**
+ * 注册只读工具。`tools` 服务缺失或注册失败时静默跳过。
+ * @param {{ctx: any, host: {call: (sessionId: string, request: any) => Promise<any>}, logger?: any, onInstalled?: () => void}} input
+ * @returns {boolean} 是否注册成功（`tools` 服务就绪时会返回 true）
+ */
+export function installRewindTool(input) {
+  const { ctx, host, logger, onInstalled } = input;
+  const install = (/** @type {any} */ scope) => {
+    try {
+      const tools = scope?.tools ?? scope?.get?.("tools");
+      if (!tools || typeof tools.register !== "function") return;
+      const definition = createRewindToolDefinition(host);
+      const disposer = tools.register(definition);
+      scope?.effect?.(() => disposer, "session-rewind: read-only tool");
+      if (typeof onInstalled === "function") onInstalled();
+      return true;
+    } catch (error) {
+      logger?.warn?.(
+        `session-rewind: failed to register ${TOOL_NAME}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return false;
+    }
+  };
+  try {
+    if (typeof ctx.inject === "function") {
+      ctx.inject(["tools"], install);
+      return true;
+    }
+    const tools = ctx.get?.("tools");
+    if (tools && typeof tools.register === "function") {
+      install({ tools, effect: ctx.effect?.bind(ctx) });
+      return true;
+    }
+    return false;
+  } catch (error) {
+    logger?.warn?.(
+      `session-rewind: cannot install ${TOOL_NAME}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangyishuai/dsh-session-rewind",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "In-place conversation rewind for DSH: withdraw a user message and everything after it, then refill the composer",
   "keywords": [
     "dsh",