dsh-rewind-plugin 0.1.1 → 0.1.3

package/README.md

@@ -2,9 +2,9 @@
 
 DeepSeek Harness 插件：**同一会话窗口的 in-place 对话回退**（Claude Code `/rewind` 语义）。主交互为**用户消息旁的「回退」按钮**，点击后选择回退模式；命令仅作辅助。
 
-> 状态：v0.1.0 已实现（host + client 双面插件）。交互以 Claude Code 行为为参考，并贴合 dsh Web 实际 UI（利用现有 DOM 锚点与运行时快照，纯插件、不改仓库核心）。
+> 状态：v0.1.3 已实现并发布（`dsh-rewind-plugin`，npm + GitHub Actions Trusted Publishing）。交互以 Claude Code 行为为参考，并贴合 dsh Web 实际 UI（利用现有 DOM 锚点与运行时快照，纯插件、不改仓库核心）。
 
-## 实现状态（v0.1.0）
+## 实现状态（v0.1.3）
 
 - ✅ host 端 `/rewind` 命令（两步文本引导 + 直接执行 + `preview` 影响清单）
 - ✅ host 端变更台账（`tools/execute` 捕获 before、`tools/post-execute` 提交），按会话隔离
@@ -39,7 +39,8 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ## 发布（维护者，CI + Trusted Publishing）
 
-发布走 GitHub Actions + npm **Trusted Publishing**（OIDC，无 npm token）：
+已发布版本：`0.1.0`（本地 2FA 首发）、`0.1.1`（CI OIDC + Sigstore provenance）。
+后续发版走 CI：
 
 ```sh
 npm version patch    # 或 minor / major；同步更新 README 版本说明
@@ -60,24 +61,32 @@ git push --tags      # push v<version> tag → 触发 .github/workflows/publish.
      （本 workflow 无 `environment` 块，OIDC subject 携带 ref，此为已验证组合）·
      **Allowed actions：`npm publish`**（2026-05-20 起必选）。
 - 质量门禁（PR / push main）：`.github/workflows/ci.yml` 跑 typecheck + 测试
-  + 构建 + `verify-host`。
+  + 构建 + `verify-host` + tarball 完整性检查（`lib/` 与 `LICENSE` 必须在包内）。
+- 包内附带 `.d.ts` 类型声明（`exports` 已声明 `types`，源码级 `./src/*` 亦可导入）。
 
 ## 使用
 
 - 每条用户消息 hover 出现「↶ 回退」按钮：点击 → 选择「仅回退对话」或
   「回退对话和代码」（后者先展示影响清单再确认）。
+- **撤回最近消息**：对**最后一条**用户消息回退（按钮或 `/rewind <目标>`），效果是
+  **撤回该消息本身**（发错了立即重发的常见场景）——上下文回到它之前，命令结果
+  提示"已撤回 seq N，可重新发送"。
 - 键盘流：`/rewind` → 选消息 → `/rewind <序号> chat|both`；`/rewind preview <目标>`
   只输出影响清单不执行。
-- 回退后：模型上下文从目标消息重新开始；会话日志与可见对话完整保留
-  （append-only）；标记节点不渲染为气泡（非 append surface 事件），结果以命令节点呈现。
+- **回退后前端与 Agent 一致**：回退/撤回后，client 端自动隐藏回退标记、`/rewind`
+  命令结果以及被回退范围内的消息（含 agent 回复），可见对话回到回退点之前的样子；
+  之后新发的消息正常显示。会话日志（append-only 审计）不受影响。
 
 ## 已知限制（v0.1）
 
 - 台账只覆盖插件运行期间、经 `write` / `edit` / `str_replace_editor` 的变更；
-  bash 或外部程序的修改无法还原（二期可加 git-first 快照层）。
+  bash 或外部程序的修改无法还原（二期可加 git-first 快照层）。台账按会话有界
+  （每会话保留最近 2000 条，最旧先丢弃）。
 - 文件删除走 `processPath` 直删（本地 backend）；sandbox/远程 backend 下还原
   可能受限。
 - 回退本身可再回退（标记进入日志），但文件还原动作不再重新入台账。
+- 回退按钮只出现在**当前会话**渲染的用户消息行上（DOM 注入范围即当前视图）；
+  subagent/分屏等非当前会话的对话需要先切到该会话再回退。
 
 ## 背景与定位
 

package/lib/client.js

@@ -298,7 +298,7 @@ function renderImpactStep(root, opts, back) {
       session,
       (node) => {
         const args = node.args ?? "";
-        return node.name === "rewind" && args.includes("preview") && args.includes(`@${seq}`);
+        return node.name === "rewind" && args.includes("preview") && new RegExp(`(?:^|\\s)@${seq}(?=\\s|$)`).test(args);
       }
     );
     if (outcome === null) {
@@ -385,10 +385,43 @@ var name = "dsh-rewind";
 var inject = ["sessions", "locale"];
 var NS = "rewind";
 var USER_SEAT_SELECTOR = '[data-chat-flow-kind="user"]';
+var CHAT_SEAT_SELECTOR = "[data-chat-anchor-key]";
 var ACTIONS_ROOT_SELECTOR = "[data-time-hover-root]";
+var REWIND_MARKER_RE = /__DSH_REWIND__:\{"target":(\d+)\}/;
 function messagePreviewOf(node) {
   return node.content.map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "").join("").replace(/\s+/g, " ").trim().slice(0, 80);
 }
+function hiddenSeqsOf(session) {
+  const hidden = /* @__PURE__ */ new Set();
+  const snap = session.getSnapshot();
+  let latest = null;
+  for (const key of snap.chat.order) {
+    const node = snap.chat.nodes.get(key);
+    if (node === void 0) continue;
+    if (node.kind === "command") {
+      const command = node.data;
+      if (command.name === "rewind") hidden.add(command.seq);
+    } else if (node.kind === "user") {
+      const user = node.data;
+      const text = user.content.map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "").join("");
+      const match = text.match(REWIND_MARKER_RE);
+      if (match !== null) {
+        hidden.add(user.seq);
+        const target = Number(match[1]);
+        if (latest === null || user.seq > latest.marker) latest = { marker: user.seq, target };
+      }
+    }
+  }
+  if (latest !== null) {
+    for (const key of snap.chat.order) {
+      const node = snap.chat.nodes.get(key);
+      if (node === void 0) continue;
+      const anchor = node.anchorSeq;
+      if (anchor > latest.target && anchor <= latest.marker) hidden.add(anchor);
+    }
+  }
+  return hidden;
+}
 function apply(ctx) {
   ctx.effect(function* () {
     yield ctx.locale.register(NS, { zh, en });
@@ -398,6 +431,7 @@ function apply(ctx) {
     style.textContent = STYLE;
     document.head.appendChild(style);
     const attached = /* @__PURE__ */ new WeakSet();
+    const hidden = /* @__PURE__ */ new WeakSet();
     const buttons = /* @__PURE__ */ new Map();
     let observer = null;
     const sessionFor = () => {
@@ -449,7 +483,22 @@ function apply(ctx) {
       for (const [key, button] of buttons) {
         if (!button.isConnected) buttons.delete(key);
       }
-      for (const seat of document.querySelectorAll(USER_SEAT_SELECTOR)) attach(seat);
+      const session = sessionFor();
+      const hiddenSeqs = session !== void 0 ? hiddenSeqsOf(session) : /* @__PURE__ */ new Set();
+      for (const seat of document.querySelectorAll(CHAT_SEAT_SELECTOR)) {
+        const key = seat.dataset.chatAnchorKey;
+        const anchor = key !== void 0 && session !== void 0 ? session.getSnapshot().chat.nodes.get(key)?.anchorSeq : void 0;
+        if (anchor !== void 0 && hiddenSeqs.has(anchor)) {
+          seat.style.display = "none";
+          hidden.add(seat);
+        } else if (hidden.has(seat)) {
+          seat.style.display = "";
+          hidden.delete(seat);
+        }
+      }
+      for (const seat of document.querySelectorAll(USER_SEAT_SELECTOR)) {
+        if (!hidden.has(seat)) attach(seat);
+      }
     };
     observer = new MutationObserver(scan);
     observer.observe(document.body, { childList: true, subtree: true });

package/lib/index.js

@@ -14,11 +14,13 @@ function execSessionCwd(exec, requestedPath) {
 }
 
 // src/ledger.ts
+var MAX_LEDGER_ENTRIES = 2e3;
 var RewindLedger = class {
   entries = [];
-  /** Record one committed mutation. */
+  /** Record one committed mutation, dropping the oldest entry when over the cap. */
   record(entry) {
     this.entries.push(entry);
+    if (this.entries.length > MAX_LEDGER_ENTRIES) this.entries.shift();
   }
   /**
    * All entries anchored at or after `targetSeq`, newest first. The boundary
@@ -168,10 +170,13 @@ function planRewind(events, surface, target) {
     );
   }
   if (targetIndex === surface.length - 1) {
-    throw new RewindError(
-      "nothing-after",
-      `user message at seq ${targetSeq} is already the last context item; nothing to rewind`
-    );
+    return {
+      targetSeq,
+      targetIndex,
+      shadowedSeqs: [targetSeq],
+      surfaceStart: targetSeq,
+      surfaceEnd: targetSeq
+    };
   }
   const shadowedSeqs = surface.slice(targetIndex + 1);
   return {
@@ -279,7 +284,8 @@ function buildMarker(targetSeq) {
   return createUserMessage({
     content: [{
       type: "text",
-      text: `[\u56DE\u9000\u6807\u8BB0 / rewind marker] \u5BF9\u8BDD\u5DF2\u56DE\u9000\u5230 seq ${targetSeq}\uFF0C\u6B64\u6807\u8BB0\u4E4B\u540E\u7684\u5386\u53F2\u5DF2\u4ECE\u6A21\u578B\u4E0A\u4E0B\u6587\u4E2D\u79FB\u9664\u3002\u8BF7\u5FFD\u7565\u6B64\u6807\u8BB0\u672C\u8EAB\uFF0C\u7B49\u5F85\u7528\u6237\u7684\u4E0B\u4E00\u6761\u6D88\u606F\u3002`
+      text: `__DSH_REWIND__:{"target":${targetSeq}}
+[\u56DE\u9000\u6807\u8BB0 / rewind marker] \u5BF9\u8BDD\u5DF2\u56DE\u9000\u5230 seq ${targetSeq}\uFF0C\u6B64\u6807\u8BB0\u4E4B\u540E\u7684\u5386\u53F2\u5DF2\u4ECE\u6A21\u578B\u4E0A\u4E0B\u6587\u4E2D\u79FB\u9664\u3002\u8BF7\u5FFD\u7565\u6B64\u6807\u8BB0\u672C\u8EAB\uFF0C\u7B49\u5F85\u7528\u6237\u7684\u4E0B\u4E00\u6761\u6D88\u606F\u3002`
     }],
     source: { kind: "user" }
   });
@@ -351,9 +357,10 @@ async function executeRewind(ctx, ledger, invocation, rawTarget, mode) {
       restore = `\uFF1B\u8FD8\u539F ${outcome.restored.length} \u4E2A\u6587\u4EF6\u3001\u5220\u9664 ${outcome.deleted.length} \u4E2A\u6587\u4EF6${renderFailures(outcome.failed)}`;
     }
   }
+  const withdrewLatest = plan.shadowedSeqs[0] === plan.targetSeq;
   return {
     kind: "success",
-    text: `\u5DF2\u56DE\u9000\u5230 seq ${plan.targetSeq}\uFF0C\u79FB\u9664 ${plan.shadowedSeqs.length} \u6761\u4E0A\u4E0B\u6587\uFF08\u65E5\u5FD7\u4FDD\u7559\uFF09${restore}\u3002`,
+    text: withdrewLatest ? `\u5DF2\u64A4\u56DE seq ${plan.targetSeq}\uFF08\u6700\u8FD1\u4E00\u6761\u6D88\u606F\uFF09\uFF0C\u53EF\u91CD\u65B0\u53D1\u9001${restore}\u3002` : `\u5DF2\u56DE\u9000\u5230 seq ${plan.targetSeq}\uFF0C\u79FB\u9664 ${plan.shadowedSeqs.length} \u6761\u4E0A\u4E0B\u6587\uFF08\u65E5\u5FD7\u4FDD\u7559\uFF09${restore}\u3002`,
     sourceEventSeq: event.seq
   };
 }
@@ -363,8 +370,7 @@ function rewindErrorResult(error) {
       "no-user-messages": "\u5F53\u524D\u4F1A\u8BDD\u8FD8\u6CA1\u6709\u53EF\u56DE\u9000\u7684\u7528\u6237\u6D88\u606F\u3002",
       "invalid-index": error.message,
       "not-a-user-message": error.message,
-      "not-on-surface": error.message,
-      "nothing-after": error.message
+      "not-on-surface": error.message
     }[error.code];
     return { kind: "error", text };
   }

package/lib/types/client/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * dsh-rewind client half: the per-user-message ↶ rewind button and the
+ * mode-selection popover, injected into the conversation DOM (pure plugin —
+ * no harness source patches).
+ *
+ * Anchoring: each chat node seat renders `[data-chat-flow-kind]` with
+ * `data-chat-anchor-key`; a `MutationObserver` tracks newly rendered user
+ * seats and appends the rewind button into the message's IconActions row.
+ * The seq is never parsed from DOM text — the key is looked up in the runtime
+ * snapshot (`session.getSnapshot().chat.nodes.get(key)`) to get the durable
+ * `UserMessageNode.seq`.
+ *
+ * Interaction: clicking a message's button fixes the target (step one), the
+ * popover offers the two modes (step two); "rewind conversation and code"
+ * first fetches the impact list via `/rewind preview @seq both` and confirms
+ * before executing. Execution always goes through `session.command(...)`, the
+ * same host path the `/rewind` command uses.
+ *
+ * @module dsh-rewind/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export declare const name = "dsh-rewind";
+export declare const inject: string[];
+/**
+ * Client plugin body: button injection + popover wiring.
+ * @param ctx - client root context carrying `sessions` and `locale`.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,43 @@
+/** `rewind` namespace dictionaries for the client plugin. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'button.aria': string;
+    'button.title': string;
+    'popover.title': string;
+    'popover.target': string;
+    'popover.chat': string;
+    'popover.chat.hint': string;
+    'popover.both': string;
+    'popover.both.hint': string;
+    'popover.cancel': string;
+    'popover.impact.loading': string;
+    'popover.impact.failed': string;
+    'popover.impact.none': string;
+    'popover.confirm': string;
+    'popover.back': string;
+};
+/** The rewind namespace key union. */
+export type RewindKey = keyof typeof zh;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The in-place rewind controls' copy. */
+        rewind: RewindKey;
+    }
+}
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'button.aria': string;
+    'button.title': string;
+    'popover.title': string;
+    'popover.target': string;
+    'popover.chat': string;
+    'popover.chat.hint': string;
+    'popover.both': string;
+    'popover.both.hint': string;
+    'popover.cancel': string;
+    'popover.impact.loading': string;
+    'popover.impact.failed': string;
+    'popover.impact.none': string;
+    'popover.confirm': string;
+    'popover.back': string;
+};

package/lib/types/client/popover.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The rewind mode-selection popover (plain DOM, no React). Step two of the
+ * interaction: the target is already fixed (the clicked message); the popover
+ * offers the two modes. Choosing "both" first fetches the impact list through
+ * the `/rewind preview @seq both` command and shows it before confirming.
+ *
+ * @module dsh-rewind/client/popover
+ */
+import type { SessionFace } from '@deepseek-ai/dsh-client-runtime/client';
+import type { RewindKey } from './locales.ts';
+type Translate = (key: RewindKey, params?: Record<string, unknown>) => string;
+export interface PopoverOptions {
+    readonly session: SessionFace;
+    readonly seq: number;
+    readonly time: number;
+    readonly preview: string;
+    /** The button that opened the popover (outside-click ignore target). */
+    readonly anchor: HTMLElement;
+    readonly t: Translate;
+}
+/** Close the current popover, if any. */
+export declare function closePopover(): void;
+/** Open the mode-selection popover anchored near the given button. */
+export declare function openPopover(opts: PopoverOptions): void;
+export {};

package/lib/types/client/styles.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Client plugin styling: one injected `<style>` tag (scoped class names),
+ * following the dsh design tokens (`--dsw-*`) so the button and popover blend
+ * with the conversation chrome.
+ *
+ * @module dsh-rewind/client/styles
+ */
+/** Marker attribute set on a seat row once its rewind button is attached. */
+export declare const REWIND_ATTACHED = "data-dsh-rewind-attached";
+/** Class names shared between the injected DOM and the stylesheet. */
+export declare const CLASS: {
+    readonly button: 'dsh-rewind-btn';
+    readonly popover: 'dsh-rewind-popover';
+    readonly popoverTitle: 'dsh-rewind-popover-title';
+    readonly popoverTarget: 'dsh-rewind-popover-target';
+    readonly popoverOption: 'dsh-rewind-popover-option';
+    readonly popoverOptionLabel: 'dsh-rewind-popover-option-label';
+    readonly popoverOptionHint: 'dsh-rewind-popover-option-hint';
+    readonly popoverImpact: 'dsh-rewind-popover-impact';
+    readonly popoverActions: 'dsh-rewind-popover-actions';
+    readonly popoverPrimary: 'dsh-rewind-popover-primary';
+    readonly popoverGhost: 'dsh-rewind-popover-ghost';
+};
+/** The ↶ glyph, drawn inline so the bundle stays dependency-free. */
+export declare const REWIND_ICON_SVG: string;
+/** One injected stylesheet (scoped under `.dsh-rewind-*`). */
+export declare const STYLE = "\n.dsh-rewind-btn {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  padding: 6px;\n  border: none;\n  border-radius: 28px;\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-btn:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-secondary);\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1000;\n  width: 288px;\n  padding: 12px;\n  border-radius: 12px;\n  background: var(--dsw-specific-surface-1, var(--dsw-alias-surface-1, #1f2127));\n  box-shadow: 0 8px 28px rgba(0, 0, 0, 0.32);\n  font-size: 14px;\n  line-height: 20px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 14px;\n  font-weight: 600;\n  line-height: 20px;\n}\n.dsh-rewind-popover-target {\n  margin: 4px 0 10px;\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 6px;\n  padding: 8px 10px;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  text-align: left;\n  cursor: pointer;\n}\n.dsh-rewind-popover-option:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n.dsh-rewind-popover-option-label {\n  font-weight: 500;\n}\n.dsh-rewind-popover-option-hint {\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-impact {\n  margin: 4px 0 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  background: var(--dsw-alias-interactive-bg-hover);\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-secondary);\n  white-space: pre-wrap;\n  max-height: 160px;\n  overflow: auto;\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  padding: 5px 12px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\n  font-size: 13px;\n  line-height: 18px;\n  cursor: pointer;\n}\n.dsh-rewind-popover-primary {\n  background: var(--dsw-alias-accent, var(--dsw-accent, #5b8cff));\n  color: var(--dsw-alias-on-accent, #fff);\n}\n.dsh-rewind-popover-primary:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-ghost {\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-popover-ghost:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n";

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * dsh-rewind host half: the `/rewind` command and the write-class change
+ * ledger, composed as one dual-face bundle row (the browser half lives in
+ * `src/client/`).
+ *
+ * Rewind mechanism: planning is pure (`src/rewind.ts`); execution appends a
+ * marker `user/message` into the session log whose `surfaceOp` replaces every
+ * surface node after the target message with the marker. The append-only log
+ * (and the rendered transcript) is untouched — only the model-visible surface
+ * is cut, so the next request derives its context from the target onward.
+ * Mode `both` additionally reverses every ledger-recorded file change that
+ * followed the target.
+ *
+ * @module dsh-rewind
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-rewind";
+export declare const inject: string[];
+/**
+ * Register the `/rewind` command and the tools-pipeline ledger hooks.
+ *
+ * The command is fs-independent and registers immediately. The ledger needs
+ * `fs`, so its hooks mount through a dynamic `ctx.inject(['fs'])` — they take
+ * effect whenever the fs service becomes available (and never fail the
+ * plugin's load when a deployment has no fs).
+ *
+ * Capture runs in `tools/execute` (the around-dispatch stage), NOT in
+ * `tools/pre-execute`: a pre-execute `{ kind: 'ask' }` short-circuit from
+ * another plugin (e.g. dsh-edit-approval) skips later pre-execute listeners,
+ * and a denied call never dispatches — so approved calls are still captured,
+ * denied calls never leave a pending entry behind.
+ *
+ * @param ctx - context carrying `commands`, `tools`, and an optional `fs`.
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/ledger.d.ts

@@ -0,0 +1,88 @@
+/**
+ * In-memory change ledger: records every write-class tool mutation that
+ * happened while the plugin was running, so a "rewind conversation and code"
+ * can reverse the changes that followed a target message.
+ *
+ * Scope (v0.1): the ledger covers only `write` / `edit` / `str_replace_editor`
+ * mutations observed through the tools pipeline while the plugin is loaded.
+ * Changes made by bash or external programs are not recorded and cannot be
+ * restored; a git-first snapshot layer is a v2 option.
+ *
+ * @module dsh-rewind/ledger
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+/** One recorded write-class mutation. */
+export interface LedgerEntry {
+    /** Tool that made the change: `write` | `edit` | `str_replace_editor`. */
+    readonly toolName: string;
+    /** Seq of the user message anchoring the turn in which the change happened. */
+    readonly anchorSeq: number;
+    /** Display path (model/UI-facing), as resolved at record time. */
+    readonly path: string;
+    /** Full file content before the change; undefined when the file was created. */
+    readonly before: string | undefined;
+    /** Full file content after the change. */
+    readonly after: string;
+}
+/** Unique per-file impact of rewinding past a target message. */
+export interface FileImpact {
+    readonly path: string;
+    /** `restore` = the file existed before the target; `delete` = created after it. */
+    readonly action: 'restore' | 'delete';
+}
+/** Result of one reverse restore pass. */
+export interface RestoreOutcome {
+    readonly restored: readonly string[];
+    readonly deleted: readonly string[];
+    readonly failed: readonly {
+        path: string;
+        message: string;
+    }[];
+}
+/** Deletes one file by its process path (the host supplies the backend-appropriate delete). */
+export type DeleteFile = (processPath: string) => Promise<void>;
+/**
+ * Per-session cap on recorded entries. The ledger is intentionally bounded so
+ * an extremely long session cannot grow one entry list without limit; the
+ * oldest entries are dropped first, so rewinds to very early messages in a
+ * pathological session may lose the earliest file history (a declared
+ * tradeoff, see README).
+ */
+export declare const MAX_LEDGER_ENTRIES = 2000;
+/**
+ * Append-only change ledger. Entries are recorded in commit order; a rewind
+ * replays them in reverse for the affected range. Bounded per session to
+ * {@link MAX_LEDGER_ENTRIES} (oldest dropped first).
+ */
+export declare class RewindLedger {
+    private readonly entries;
+    /** Record one committed mutation, dropping the oldest entry when over the cap. */
+    record(entry: LedgerEntry): void;
+    /**
+     * All entries anchored at or after `targetSeq`, newest first. The boundary
+     * is inclusive: rewinding to a message also reverts the changes its own
+     * turn caused (the rewind cut removes that turn's assistant response and
+     * tool calls), so only changes anchored at earlier messages survive.
+     */
+    changesAfter(targetSeq: number): readonly LedgerEntry[];
+    /**
+     * Unique per-file impact for preview. A file whose earliest affected change
+     * created it (`before === undefined`) is deleted on restore; any other file
+     * is written back to its pre-target content.
+     */
+    impactsAfter(targetSeq: number): readonly FileImpact[];
+    /**
+     * Reverse every change anchored at or after `targetSeq`. Each entry writes
+     * its pre-change content back; a file that did not exist before the target
+     * is deleted instead. Failures are collected per file and never abort the pass.
+     * @param fs - the filesystem service (resolve/readText/writeText/processPath).
+     * @param deleteFile - backend-appropriate file deletion by process path.
+     * @param targetSeq - the rewind target; only later changes are reverted.
+     * @param options - session workspace cwd (relative ledger paths resolve
+     *   against it, mirroring the fs tools) and an optional abort signal.
+     */
+    restoreAfter(fs: FileSystem, deleteFile: DeleteFile, targetSeq: number, options?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<RestoreOutcome>;
+}

package/lib/types/rewind.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure rewind planning: target resolution and surface-range computation.
+ * No I/O and no `Session` dependency — everything derives from the event log
+ * and the ordered surface, so this module stays unit-testable.
+ *
+ * Rewind semantics (see README): rewinding to a user message appends a marker
+ * node into the session log whose `surfaceOp` replaces every surface node
+ * AFTER the target with itself. The log (the audit trail and the rendered
+ * transcript) is untouched; only the model-visible surface is cut, so the
+ * next request derives its context from the target message onward.
+ *
+ * @module dsh-rewind/rewind
+ */
+import type { SessionEvent, UserMessage } from '@deepseek-ai/dsh-session';
+/** Which of the two rewind modes a rewind executes. */
+export type RewindMode = 'chat' | 'both';
+/**
+ * Parse-level rewind target. The command line accepts both forms:
+ * - `@<seq>` — an absolute log seq (what the UI button always sends);
+ * - `<index>` — a 1-based recency index into the listed candidates
+ *   (1 = most recent user message; the step-by-step command flow uses this).
+ */
+export type RewindTarget = {
+    kind: 'seq';
+    seq: number;
+} | {
+    kind: 'index';
+    index: number;
+};
+/** Expected failure codes; each maps to a concise human outcome. */
+export type RewindErrorCode = 'no-user-messages' | 'invalid-index' | 'not-a-user-message' | 'not-on-surface';
+/** A typed rewind failure. The host renders `code` into user-facing copy. */
+export declare class RewindError extends Error {
+    readonly code: RewindErrorCode;
+    constructor(code: RewindErrorCode, message: string);
+}
+/** One selectable rewind candidate: a user message currently on the surface. */
+export interface RewindCandidate {
+    /** Absolute log seq of the `user/message` event. */
+    readonly seq: number;
+    /** Unix epoch ms of the event. */
+    readonly time: number;
+    /** Truncated plain-text preview of the message content. */
+    readonly preview: string;
+    /** 1-based recency index in the candidate list (1 = most recent). */
+    readonly index: number;
+}
+/** A validated rewind: the target plus the exact surface range to shadow. */
+export interface RewindPlan {
+    /** Target user message seq (stays on the surface). */
+    readonly targetSeq: number;
+    /** The target's ordered position in the surface. */
+    readonly targetIndex: number;
+    /** Ordered surface node seqs the rewind shadows (everything after the target). */
+    readonly shadowedSeqs: readonly number[];
+    /** First surface node after the target — the replace range start (inclusive). */
+    readonly surfaceStart: number;
+    /** Last surface node — the replace range end (inclusive). */
+    readonly surfaceEnd: number;
+}
+/** Preview length cap for candidate listings. */
+export declare const CANDIDATE_PREVIEW_CHARS = 80;
+/** Narrow an event to a user message. */
+export declare function isUserMessageEvent(event: SessionEvent): event is SessionEvent<'user/message'>;
+/** Join the text blocks of a message into one plain string. */
+export declare function messagePreview(message: UserMessage): string;
+/**
+ * Parse a raw command token into a rewind target.
+ * @param raw - one token: `@123` (absolute seq) or `12` (recency index).
+ * @returns the parsed target, or undefined when the token is malformed.
+ */
+export declare function parseRewindTarget(raw: string): RewindTarget | undefined;
+/**
+ * List the selectable rewind candidates: user messages currently on the
+ * surface, most recent first. Shadowed (compacted-away) user messages are
+ * intentionally excluded — the rewind boundary cannot be placed where the
+ * model context no longer reaches.
+ * @param events - the full session event log.
+ * @param surface - the ordered surface node seqs (`session.surface.nodes`).
+ * @param limit - maximum number of candidates to return.
+ * @returns candidates numbered 1..N by recency.
+ */
+export declare function listRewindCandidates(events: readonly SessionEvent[], surface: readonly number[], limit?: number): RewindCandidate[];
+/**
+ * Resolve a target against the session log and surface into a validated plan.
+ * @param events - the full session event log.
+ * @param surface - the ordered surface node seqs.
+ * @param target - the parsed target.
+ * @returns the validated rewind plan.
+ * @throws {RewindError} with a typed code when the target is unusable.
+ */
+export declare function planRewind(events: readonly SessionEvent[], surface: readonly number[], target: RewindTarget): RewindPlan;
+/** Human rendering of a candidate list line (`/rewind` step 1). */
+export declare function formatCandidate(candidate: RewindCandidate): string;

package/lib/types/session-cwd.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Session-cwd resolution for ledger reads/restores, mirroring the fs tools'
+ * own rule (`@deepseek-ai/dsh-tool-fs/session-cwd.ts`): relative paths
+ * resolve against the calling agent's session workspace
+ * (`exec.agent.session.header.cwd`), not the server's launch dir.
+ *
+ * Pure functions: the only runtime dependency is `canonicalPath`, applied
+ * when either the cwd or the requested path contains a parent traversal so a
+ * symlinked cwd's filesystem identity stays observable — identical to the
+ * tool boundary behavior.
+ *
+ * @module dsh-rewind/session-cwd
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/**
+ * The session workspace cwd to resolve `requestedPath` against, or undefined
+ * when no session cwd applies (the filesystem backend then uses its own
+ * default base).
+ * @param cwd - the session's `header.cwd`, if any.
+ * @param requestedPath - the path the provider will resolve.
+ * @returns the cwd, canonicalized when traversal could expose a symlink.
+ */
+export declare function sessionCwd(cwd: string | undefined, requestedPath: string): string | undefined;
+/**
+ * Session cwd for one tool execution (same rule as the fs tools).
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @param requestedPath - the path the provider will resolve.
+ */
+export declare function execSessionCwd(exec: ToolExecution, requestedPath: string): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "DeepSeek Harness plugin: in-place conversation rewind in the same session window (Claude Code /rewind semantics) with optional workspace file restore",
   "keywords": [
     "deepseek-harness",
@@ -22,9 +22,17 @@
   },
   "type": "module",
   "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
   "exports": {
-    ".": "./lib/index.js",
-    "./client": "./lib/client.js",
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [

package/scripts/build.mjs

@@ -18,6 +18,7 @@
  * parse, and the host half must import with the expected plugin shape.
  */
 import { build } from 'esbuild'
+import { execSync } from 'node:child_process'
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -27,6 +28,10 @@ const pkg = JSON.parse(await readFile(join(ROOT, 'package.json'), 'utf8'))
 
 await mkdir(join(ROOT, 'lib'), { recursive: true })
 
+// ---- type declarations: host (lib/types) + client (lib/types/client) ----
+execSync('npx tsc -p tsconfig.build.json', { cwd: ROOT, stdio: 'inherit' })
+execSync('npx tsc -p tsconfig.client.json', { cwd: ROOT, stdio: 'inherit' })
+
 // ---- host half: bundled TS -> ESM (@deepseek-ai/* stays external) ----
 await build({
   entryPoints: [join(ROOT, 'src', 'index.ts')],
@@ -77,4 +82,8 @@ for (const needle of ['name', 'inject', 'apply']) {
 for (const needle of ['window.__ModuleLoader__.load', `id: ${JSON.stringify(pkg.name)}`]) {
   if (!bundle.includes(needle)) throw new Error(`client bundle missing ${needle}`)
 }
-console.log('build ok: lib/index.js (host), lib/client.js (client)')
+// Declarations must exist (published tarball carries them).
+for (const dts of ['lib/types/index.d.ts', 'lib/types/client/index.d.ts']) {
+  await readFile(join(ROOT, dts), 'utf8')
+}
+console.log('build ok: lib/index.js (host), lib/client.js (client), lib/types/ (declarations)')