@pi-harness/pi-harness 0.1.2 → 0.1.3

package/packages/core/src/plugins/theme-studio.ts

@@ -0,0 +1,165 @@
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const customType = "pi-harness/theme-studio";
+
+export type ThemeId = "light" | "midnight" | "paper" | "high-contrast";
+export type ThemePreset = { label: string; description: string; tokens: Readonly<Record<string, string>> };
+export type ThemeState = {
+  theme: ThemeId;
+  label: string;
+  description: string;
+  tokens: Readonly<Record<string, string>>;
+  changed: boolean;
+  changedAt: string | null;
+};
+
+export const themePresets: Readonly<Record<ThemeId, ThemePreset>> = {
+  light: {
+    label: "Light",
+    description: "默认浅色界面，适合长时间编码。",
+    tokens: {
+      "--color-ink": "#0f1115",
+      "--color-muted": "#65707b",
+      "--color-faint": "#8a949f",
+      "--color-line": "rgba(15,17,21,0.12)",
+      "--color-soft": "#f6f8fa",
+      "--color-blue": "#4176e6",
+      "--color-blue-soft": "#edf3fe",
+      "--color-green": "#22c55e",
+      "--color-red": "#ec1313",
+      "--color-amber": "#f59e0b",
+      "--color-empty": "#9aa0a6",
+      "--color-starter-border": "rgba(15,17,21,0.14)",
+    },
+  },
+  midnight: {
+    label: "Midnight",
+    description: "深色工作台，降低夜间屏幕亮度。",
+    tokens: {
+      "--color-ink": "#f8fafc",
+      "--color-muted": "#b7c2d1",
+      "--color-faint": "#8290a3",
+      "--color-line": "rgba(226,232,240,0.18)",
+      "--color-soft": "#111827",
+      "--color-blue": "#8ab4ff",
+      "--color-blue-soft": "#1e3a67",
+      "--color-green": "#58d68d",
+      "--color-red": "#ff8a8a",
+      "--color-amber": "#f6c56a",
+      "--color-empty": "#778399",
+      "--color-starter-border": "rgba(226,232,240,0.22)",
+    },
+  },
+  paper: {
+    label: "Paper",
+    description: "暖白纸张色调，适合阅读和文档整理。",
+    tokens: {
+      "--color-ink": "#332b24",
+      "--color-muted": "#76695d",
+      "--color-faint": "#a09589",
+      "--color-line": "rgba(82,63,45,0.16)",
+      "--color-soft": "#f5f0e8",
+      "--color-blue": "#876334",
+      "--color-blue-soft": "#eee2d0",
+      "--color-green": "#5f8b61",
+      "--color-red": "#b85b4f",
+      "--color-amber": "#b17b36",
+      "--color-empty": "#a59a8e",
+      "--color-starter-border": "rgba(82,63,45,0.18)",
+    },
+  },
+  "high-contrast": {
+    label: "High Contrast",
+    description: "更清晰的文本和边界，适合低视力场景。",
+    tokens: {
+      "--color-ink": "#000000",
+      "--color-muted": "#262626",
+      "--color-faint": "#4a4a4a",
+      "--color-line": "rgba(0,0,0,0.36)",
+      "--color-soft": "#eeeeee",
+      "--color-blue": "#0047b3",
+      "--color-blue-soft": "#dbeafe",
+      "--color-green": "#0b6b2d",
+      "--color-red": "#a40000",
+      "--color-amber": "#754c00",
+      "--color-empty": "#5c5c5c",
+      "--color-starter-border": "rgba(0,0,0,0.42)",
+    },
+  },
+};
+
+export interface ThemeStudioPluginConfig {
+  theme?: ThemeId;
+}
+
+export const Config: z<ThemeStudioPluginConfig> = z.object({
+  theme: z.union(["light", "midnight", "paper", "high-contrast"]).default("light"),
+});
+
+function isThemeId(value: unknown): value is ThemeId {
+  return typeof value === "string" && Object.hasOwn(themePresets, value);
+}
+
+function initialTheme(context: Context, fallback: ThemeId): ThemeId {
+  const entries = context.piSession.manager.getEntries();
+  const entry = [...entries].reverse().find((item) => item.type === "custom" && item.customType === customType);
+  if (entry?.type !== "custom" || entry.data === undefined || typeof entry.data !== "object" || entry.data === null) return fallback;
+  const selected = (entry.data as { theme?: unknown }).theme;
+  return isThemeId(selected) ? selected : fallback;
+}
+
+export default {
+  name: "pi-theme-studio",
+  inject: ["piSession", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: ThemeStudioPluginConfig) {
+    let theme = initialTheme(context, config.theme ?? "light");
+    let changedAt: string | null = null;
+    const state = (): ThemeState => ({ ...themePresets[theme], theme, changed: changedAt !== null, changedAt });
+    const unregisterSet = context.piTools.register(
+      defineTool({
+        name: "theme_set",
+        label: "Set UI theme",
+        description: "Select one of the bounded Pi Harness theme presets and persist it in the current session.",
+        promptSnippet: "switch the Pi Harness UI theme",
+        parameters: Type.Object({ theme: Type.Union([Type.Literal("light"), Type.Literal("midnight"), Type.Literal("paper"), Type.Literal("high-contrast")]) }),
+        execute(_toolCallId, params): Promise<AgentToolResult<ThemeState>> {
+          theme = params.theme;
+          changedAt = new Date().toISOString();
+          context.piSession.manager.appendCustomEntry(customType, { theme });
+          const details = state();
+          return Promise.resolve({ content: [{ type: "text", text: `Theme selected: ${details.label}` }], details });
+        },
+      }),
+    );
+    const unregisterStatus = context.piTools.register(
+      defineTool({
+        name: "theme_status",
+        label: "Theme status",
+        description: "Show the active theme preset and its UI color tokens.",
+        promptSnippet: "inspect the active Pi Harness theme",
+        parameters: Type.Object({}),
+        execute(): Promise<AgentToolResult<ThemeState>> {
+          const details = state();
+          return Promise.resolve({ content: [{ type: "text", text: `${details.label}: ${details.description}` }], details });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "theme-studio-panel",
+      pluginId: "@pi-harness/core/plugins/theme-studio",
+      title: "Theme Studio",
+      description: "切换可审计的界面主题预设，选择会保存到当前 session。",
+      icon: "◐",
+      read: () => ({ ...state(), presets: Object.entries(themePresets).map(([id, preset]) => ({ id, label: preset.label, description: preset.description })) }),
+    });
+    context.effect(() => () => {
+      unregisterSet();
+      unregisterStatus();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/token-guard.ts

@@ -0,0 +1,84 @@
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+
+export interface TokenGuardPluginConfig {
+  maxPercent?: number;
+  maxRunTokens?: number;
+}
+
+export const Config: z<TokenGuardPluginConfig> = z.object({ maxPercent: z.number().default(90), maxRunTokens: z.number().default(0) });
+
+export default {
+  name: "pi-token-guard",
+  inject: ["piRuntime", "piPluginUi"],
+  Config,
+  apply(context: Context, config: TokenGuardPluginConfig) {
+    const maxPercent = Math.max(1, Math.min(100, config.maxPercent ?? 90));
+    const maxRunTokens = Math.max(0, Math.min(10_000_000, Math.trunc(config.maxRunTokens ?? 0)));
+    let abortCount = 0;
+    let lastPercent: number | null = null;
+    let lastTokens: number | null = null;
+    let lastContextWindow = 0;
+    let lastExceeded = false;
+    let abortIssued = false;
+    let runStartTokens: number | null = null;
+    let runTokens: number | null = null;
+    let runExceeded = false;
+    const sessionTokens = (): number | null => {
+      const stats = context.piRuntime.session.getSessionStats?.();
+      const total = stats?.tokens?.total;
+      return typeof total === "number" && Number.isFinite(total) && total >= 0 ? total : null;
+    };
+    const inspect = (): void => {
+      const usage = context.piRuntime.session.getContextUsage();
+      lastPercent = usage?.percent ?? null;
+      lastTokens = usage?.tokens ?? null;
+      lastContextWindow = usage?.contextWindow ?? 0;
+      lastExceeded = lastPercent !== null && lastPercent >= maxPercent;
+      const currentTokens = sessionTokens();
+      runTokens = runStartTokens === null || currentTokens === null ? null : Math.max(0, currentTokens - runStartTokens);
+      runExceeded = maxRunTokens > 0 && runTokens !== null && runTokens >= maxRunTokens;
+      lastExceeded = lastExceeded || runExceeded;
+      if (!lastExceeded) abortIssued = false;
+      if (lastExceeded && context.piRuntime.session.isStreaming && !abortIssued) {
+        abortIssued = true;
+        abortCount += 1;
+        void context.piRuntime.abort();
+      }
+    };
+    const unsubscribe = context.on("pi/session-event", (event) => {
+      if (event.type === "agent_start") {
+        runStartTokens = sessionTokens();
+        runTokens = runStartTokens === null ? null : 0;
+        runExceeded = false;
+        abortIssued = false;
+      }
+      inspect();
+    });
+    const disposePanel = context.piPluginUi.register({
+      id: "token-guard-panel",
+      pluginId: "@pi-harness/core/plugins/token-guard",
+      title: "Token Guard",
+      description: "在上下文达到预算阈值时自动停止当前运行，避免继续消耗上下文。",
+      icon: "◌",
+      read: () => {
+        inspect();
+        return {
+          maxPercent,
+          maxRunTokens,
+          percent: lastPercent,
+          tokens: lastTokens,
+          contextWindow: lastContextWindow,
+          runTokens,
+          runExceeded,
+          exceeded: lastExceeded,
+          aborts: abortCount,
+        };
+      },
+    });
+    context.effect(() => () => {
+      unsubscribe();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/tools.ts

@@ -1,6 +1,7 @@
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { PiToolRegistry } from "../services.js";
+import { PiPluginUiRegistry, PiToolRegistry } from "../services.js";
+import { assertKnownConfigKeys } from "../config.js";
 
 export interface ToolsPluginConfig {
   names?: string[];
@@ -9,15 +10,17 @@ export interface ToolsPluginConfig {
 const DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
 
 export const Config: z<ToolsPluginConfig> = z.object({
-  names: z.array(z.string()).default(DEFAULT_TOOLS),
+  names: z.array(z.string().min(1)).default(DEFAULT_TOOLS),
 });
 
 export default {
   name: "pi-tools",
   Config,
   apply(context: Context, config: ToolsPluginConfig) {
+    assertKnownConfigKeys("pi-tools", config, ["names"]);
     const names = config.names ?? DEFAULT_TOOLS;
     if (new Set(names).size !== names.length) throw new Error("Pi core tool names must be unique");
     context.provide("piTools", new PiToolRegistry(names));
+    context.provide("piPluginUi", new PiPluginUiRegistry());
   },
 };

package/packages/core/src/plugins/turn-rewind.ts

@@ -0,0 +1,86 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const maxCandidates = 50;
+const maxText = 500;
+
+export interface RewindCandidate {
+  entryId: string;
+  text: string;
+}
+
+export interface RewindResult {
+  target: RewindCandidate;
+  cancelled: boolean;
+  editorText?: string;
+  summarized: boolean;
+}
+
+export function selectRewindTarget(candidates: readonly RewindCandidate[], turns: number): RewindCandidate | undefined {
+  if (!Number.isInteger(turns) || turns < 1 || turns > 20) throw new Error("Turn rewind count must be between 1 and 20");
+  if (turns >= candidates.length) return undefined;
+  return candidates[candidates.length - turns];
+}
+
+function currentCandidates(context: Context): RewindCandidate[] {
+  const runtime = context.get("piRuntime");
+  if (runtime === undefined) return [];
+  return runtime.session
+    .getUserMessagesForForking()
+    .slice(-maxCandidates)
+    .map((item) => ({ entryId: item.entryId, text: item.text.slice(0, maxText) }));
+}
+
+export default {
+  name: "pi-turn-rewind",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: RewindResult | undefined;
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "session_rewind",
+        label: "Rewind session turn",
+        description: "Navigate the native Pi session tree back to a prior user turn while preserving the abandoned branch.",
+        promptSnippet: "rewind the current session to a previous user turn without deleting history",
+        parameters: Type.Object({
+          turns: Type.Optional(Type.Number({ description: "How many user turns to rewind, from 1 to 20" })),
+          entryId: Type.Optional(Type.String({ description: "Exact native session entry ID to navigate to" })),
+          summarize: Type.Optional(Type.Boolean({ description: "Ask Pi to summarize the abandoned branch" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<RewindResult>> {
+          const runtime = context.get("piRuntime");
+          if (runtime === undefined) throw new Error("Pi runtime is not ready");
+          if (runtime.session.isStreaming) throw new Error("Cannot rewind while a prompt is running");
+          const candidates = currentCandidates(context);
+          const requestedId = params.entryId?.trim();
+          const target = requestedId ? candidates.find((candidate) => candidate.entryId === requestedId) : selectRewindTarget(candidates, params.turns ?? 1);
+          if (target === undefined) throw new Error("No matching previous user turn was found");
+          const result = await runtime.session.navigateTree(target.entryId, { summarize: params.summarize === true });
+          latest = {
+            target,
+            cancelled: result.cancelled,
+            ...(result.editorText === undefined ? {} : { editorText: result.editorText }),
+            summarized: params.summarize === true,
+          };
+          return {
+            content: [{ type: "text", text: result.cancelled ? "Session rewind was cancelled." : `Session rewound to: ${target.text}` }],
+            details: latest,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "turn-rewind-panel",
+      pluginId: "@pi-harness/core/plugins/turn-rewind",
+      title: "Turn Rewind",
+      description: "回到之前的用户轮次并保留原分支，不直接删除会话历史。",
+      icon: "↶",
+      read: () => ({ candidates: currentCandidates(context), latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/undo-savepoint.ts

@@ -0,0 +1,284 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { basename, extname, join, relative, resolve, sep } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { isPathInside, prepareWorkspaceFile, resolveExistingWorkspacePath } from "../workspace-path.js";
+
+const defaultStoreName = "undo-savepoints";
+const defaultTrackedPaths = ["."];
+const maxSnapshotBytes = 2 * 1024 * 1024;
+const sensitiveNames = new Set([".env", ".env.local", ".env.production", ".credentials", ".credentials.yaml", ".credentials.json"]);
+const ignoredDirectories = new Set([".git", "node_modules", "dist", "build", ".next", ".turbo"]);
+
+export interface UndoSavepointPluginConfig {
+  storeName?: string;
+  trackedPaths?: string[];
+  maxFiles?: number;
+  maxFileBytes?: number;
+}
+
+export const Config: z<UndoSavepointPluginConfig> = z.object({
+  storeName: z.string().default(defaultStoreName),
+  trackedPaths: z.array(z.string()).default(defaultTrackedPaths),
+  maxFiles: z.number().default(400),
+  maxFileBytes: z.number().default(256 * 1024),
+});
+
+interface SavepointFile {
+  path: string;
+  bytes: number;
+  sha256: string;
+  content: string;
+}
+
+interface SavepointManifest {
+  version: 1;
+  id: string;
+  reason: string;
+  createdAt: string;
+  files: SavepointFile[];
+}
+
+interface SavepointSummary {
+  id: string;
+  reason: string;
+  createdAt: string;
+  fileCount: number;
+}
+
+interface SavepointDiff {
+  id: string;
+  changed: string[];
+  missing: string[];
+  unchanged: number;
+}
+
+function safeStoreName(value: string | undefined): string {
+  const name = (value ?? defaultStoreName).trim();
+  if (name === "" || basename(name) !== name || name.includes(sep) || name === "." || name === "..")
+    throw new Error("storeName must be a single directory name");
+  return name;
+}
+
+function withinRoot(root: string, candidate: string): boolean {
+  return isPathInside(root, candidate);
+}
+
+async function normalizedTrackedPaths(cwd: string, paths: readonly string[]): Promise<string[]> {
+  const values = paths.length === 0 ? defaultTrackedPaths : paths;
+  const resolved = await Promise.all(values.map((item) => resolveExistingWorkspacePath(cwd, item, "Tracked paths must stay inside the current workspace")));
+  return [...new Set(resolved.map((item) => item.target))];
+}
+
+function relativePath(cwd: string, path: string): string {
+  return relative(cwd, path).split(sep).join("/");
+}
+
+function isSensitivePath(path: string): boolean {
+  const name = basename(path).toLowerCase();
+  return sensitiveNames.has(name) || name.endsWith(".pem") || name.endsWith(".key") || name.endsWith(".p12");
+}
+
+function isIgnoredPath(path: string): boolean {
+  return path.split(sep).some((part) => ignoredDirectories.has(part));
+}
+
+function hash(content: Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function collectFiles(root: string, trackedPaths: readonly string[], maxFiles: number, maxFileBytes: number): Promise<SavepointFile[]> {
+  const files: SavepointFile[] = [];
+  const seen = new Set<string>();
+  const visit = async (path: string): Promise<void> => {
+    if (files.length >= maxFiles || isIgnoredPath(path) || isSensitivePath(path)) return;
+    const info = await lstat(path).catch(() => undefined);
+    if (info === undefined) return;
+    if (info.isSymbolicLink()) return;
+    if (info.isDirectory()) {
+      for (const entry of await readdir(path, { withFileTypes: true })) {
+        if (entry.isSymbolicLink()) continue;
+        await visit(join(path, entry.name));
+        if (files.length >= maxFiles) return;
+      }
+      return;
+    }
+    if (!info.isFile() || info.size > maxFileBytes) return;
+    const content = await readFile(path);
+    if (content.includes(0)) return;
+    const relativeName = relativePath(root, path);
+    if (relativeName === "" || seen.has(relativeName)) return;
+    seen.add(relativeName);
+    files.push({ path: relativeName, bytes: content.byteLength, sha256: hash(content), content: content.toString("base64") });
+  };
+  for (const path of trackedPaths) {
+    await visit(path);
+    if (files.length >= maxFiles) break;
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+async function readManifest(path: string): Promise<SavepointManifest> {
+  const parsed = JSON.parse(await readFile(path, "utf8")) as Partial<SavepointManifest>;
+  if (parsed.version !== 1 || typeof parsed.id !== "string" || !Array.isArray(parsed.files)) throw new Error(`Invalid savepoint: ${basename(path)}`);
+  return {
+    version: 1,
+    id: parsed.id,
+    reason: typeof parsed.reason === "string" ? parsed.reason : "",
+    createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
+    files: parsed.files.filter(
+      (file): file is SavepointFile =>
+        typeof file === "object" &&
+        file !== null &&
+        typeof file.path === "string" &&
+        typeof file.bytes === "number" &&
+        typeof file.sha256 === "string" &&
+        typeof file.content === "string",
+    ),
+  };
+}
+
+async function listManifests(directory: string): Promise<SavepointSummary[]> {
+  const names = (await readdir(directory).catch(() => [] as string[]))
+    .filter((name) => extname(name) === ".json")
+    .sort()
+    .reverse();
+  const summaries: SavepointSummary[] = [];
+  for (const name of names) {
+    const manifest = await readManifest(join(directory, name)).catch(() => undefined);
+    if (manifest !== undefined) summaries.push({ id: manifest.id, reason: manifest.reason, createdAt: manifest.createdAt, fileCount: manifest.files.length });
+  }
+  return summaries;
+}
+
+async function diffManifest(root: string, manifest: SavepointManifest): Promise<SavepointDiff> {
+  const changed: string[] = [];
+  const missing: string[] = [];
+  let unchanged = 0;
+  for (const file of manifest.files) {
+    const path = await resolveExistingWorkspacePath(root, file.path, "Savepoint path must stay inside the workspace").catch(() => undefined);
+    if (path === undefined) {
+      missing.push(file.path);
+      continue;
+    }
+    const content = await readFile(path.target).catch(() => undefined);
+    if (content === undefined) {
+      missing.push(file.path);
+    } else if (hash(content) === file.sha256) {
+      unchanged += 1;
+    } else {
+      changed.push(file.path);
+    }
+  }
+  return { id: manifest.id, changed, missing, unchanged };
+}
+
+export default {
+  name: "pi-undo-savepoint",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config,
+  async apply(context: Context, config: UndoSavepointPluginConfig) {
+    const cwd = (await resolveExistingWorkspacePath(context.piHarnessLaunch.cwd, ".", "Workspace path is invalid")).root;
+    const store = join(context.piHarnessLaunch.agentDir, safeStoreName(config.storeName));
+    const trackedPaths = await normalizedTrackedPaths(cwd, config.trackedPaths ?? defaultTrackedPaths);
+    const maxFiles = Math.max(1, Math.min(2_000, Math.trunc(config.maxFiles ?? 400)));
+    const maxFileBytes = Math.max(1, Math.min(maxSnapshotBytes, Math.trunc(config.maxFileBytes ?? 256 * 1024)));
+    const manifestPath = (id: string): string => {
+      if (!/^\d{17}-[0-9a-f]{8}$/u.test(id)) throw new Error("Invalid savepoint id");
+      return join(store, `${id}.json`);
+    };
+    const load = async (id: string): Promise<SavepointManifest> => readManifest(manifestPath(id));
+    const save = async (reason: string): Promise<SavepointManifest> => {
+      const createdAt = new Date().toISOString();
+      const id = `${createdAt.replace(/[-:.TZ]/gu, "").slice(0, 17)}-${randomUUID().slice(0, 8)}`;
+      const manifest: SavepointManifest = {
+        version: 1,
+        id,
+        reason: reason.trim() || "manual savepoint",
+        createdAt,
+        files: await collectFiles(cwd, trackedPaths, maxFiles, maxFileBytes),
+      };
+      await mkdir(store, { recursive: true });
+      const temporary = join(store, `.${id}.tmp`);
+      await writeFile(temporary, JSON.stringify(manifest, null, 2), { encoding: "utf8", mode: 0o600 });
+      await rename(temporary, manifestPath(id));
+      return manifest;
+    };
+    const restore = async (manifest: SavepointManifest): Promise<string[]> => {
+      const restored: string[] = [];
+      for (const file of manifest.files) {
+        const lexicalPath = resolve(cwd, ...file.path.split("/"));
+        if (!withinRoot(cwd, lexicalPath) || isSensitivePath(lexicalPath)) continue;
+        const content = Buffer.from(file.content, "base64");
+        if (hash(content) !== file.sha256) throw new Error(`Savepoint integrity check failed: ${file.path}`);
+        const prepared = await prepareWorkspaceFile(cwd, file.path, `Savepoint path must stay inside the workspace and target a regular file: ${file.path}`);
+        const temporary = `${prepared.target}.${randomUUID()}.tmp`;
+        await writeFile(temporary, content, { mode: 0o600 });
+        await rename(temporary, prepared.target);
+        restored.push(file.path);
+      }
+      return restored;
+    };
+    const report = async (): Promise<{ store: string; trackedPaths: string[]; count: number; savepoints: SavepointSummary[] }> => {
+      const savepoints = await listManifests(store);
+      return { store, trackedPaths: trackedPaths.map((path) => relativePath(cwd, path) || "."), count: savepoints.length, savepoints };
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "undo_savepoint",
+        label: "Undo savepoint",
+        description: "Create, inspect, diff, list, and explicitly restore safe local workspace savepoints.",
+        promptSnippet: "save or restore a workspace savepoint before risky changes",
+        parameters: Type.Object({
+          action: Type.Union([Type.Literal("save"), Type.Literal("list"), Type.Literal("diff"), Type.Literal("restore")]),
+          id: Type.Optional(Type.String({ description: "Savepoint id for diff or restore" })),
+          reason: Type.Optional(Type.String({ description: "Why this savepoint is being created" })),
+          confirm: Type.Optional(Type.Boolean({ description: "Must be true before restoring files" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+          if (params.action === "save") {
+            const manifest = await save(params.reason ?? "manual savepoint");
+            return {
+              content: [{ type: "text", text: `Savepoint ${manifest.id} saved (${manifest.files.length} files).` }],
+              details: { action: "save", id: manifest.id, fileCount: manifest.files.length },
+            };
+          }
+          if (params.action === "list") {
+            const details = await report();
+            return { content: [{ type: "text", text: `${details.savepoints.length} savepoints available.` }], details: { action: "list", ...details } };
+          }
+          if (params.id === undefined || params.id.trim() === "") throw new Error(`action ${params.action} requires id`);
+          const manifest = await load(params.id);
+          if (params.action === "diff") {
+            const details = await diffManifest(cwd, manifest);
+            return {
+              content: [{ type: "text", text: `${details.changed.length} changed, ${details.missing.length} missing, ${details.unchanged} unchanged.` }],
+              details: { action: "diff", ...details },
+            };
+          }
+          if (params.confirm !== true) throw new Error("Restoring a savepoint requires confirm=true");
+          const restored = await restore(manifest);
+          return {
+            content: [{ type: "text", text: `Restored ${restored.length} files from ${manifest.id}.` }],
+            details: { action: "restore", id: manifest.id, restored },
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "undo-savepoint-panel",
+      pluginId: "@pi-harness/core/plugins/undo-savepoint",
+      title: "Undo Savepoints",
+      description: "保存工作区文件快照，查看列表与变更，并在确认后恢复。",
+      icon: "↶",
+      read: report,
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};