@pi-harness/pi-harness 0.1.2 → 0.1.3

package/packages/core/src/plugins/anchored-standard.ts

@@ -0,0 +1,88 @@
+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";
+
+export interface AnchoredStandardPluginConfig {
+  maxToolCalls?: number;
+}
+
+export const Config: z<AnchoredStandardPluginConfig> = z.object({ maxToolCalls: z.number().default(64) });
+type AnchorStatus = "idle" | "anchored" | "violated";
+type Violation = { code: "orphan_tool" | "nested_run" | "tool_budget" | "orphan_end"; message: string };
+type AnchorReport = { status: AnchorStatus; events: number; toolCalls: number; maxToolCalls: number; violations: Violation[] };
+
+export default {
+  name: "pi-anchored-standard",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: AnchoredStandardPluginConfig) {
+    const maxToolCalls = Math.max(1, Math.min(512, Math.trunc(config.maxToolCalls ?? 64)));
+    let active = false;
+    let events = 0;
+    let toolCalls = 0;
+    const violations: Violation[] = [];
+    const record = (violation: Violation): void => {
+      if (!violations.some((item) => item.code === violation.code)) violations.push(violation);
+    };
+    const inspect = (event: { type: string }): void => {
+      events += 1;
+      if (event.type === "agent_start") {
+        if (active) record({ code: "nested_run", message: "检测到未结束的 Agent 运行被再次启动。" });
+        active = true;
+        toolCalls = 0;
+      } else if (event.type === "agent_end") {
+        if (!active) record({ code: "orphan_end", message: "检测到没有对应启动事件的 Agent 结束事件。" });
+        active = false;
+      } else if (event.type === "tool_execution_start") {
+        toolCalls += 1;
+        if (!active) record({ code: "orphan_tool", message: "工具调用发生在 Agent 运行锚点之外。" });
+        if (toolCalls > maxToolCalls) record({ code: "tool_budget", message: `单次运行工具调用超过 ${maxToolCalls} 次上限。` });
+      }
+    };
+    const report = (): AnchorReport => ({
+      status: violations.length > 0 ? "violated" : active ? "anchored" : "idle",
+      events,
+      toolCalls,
+      maxToolCalls,
+      violations: [...violations],
+    });
+    const unsubscribe = context.on("pi/session-event", inspect);
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "trajectory_anchor_check",
+        label: "Trajectory anchor check",
+        description: "Audit Agent lifecycle and tool-call ordering against the anchored execution standard.",
+        promptSnippet: "audit the current agent trajectory for lifecycle violations",
+        parameters: Type.Object({}),
+        execute(): Promise<AgentToolResult<AnchorReport>> {
+          return Promise.resolve().then(() => {
+            const result = report();
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: `${result.status}: ${result.events} events, ${result.toolCalls} tool calls, ${result.violations.length} violation(s).`,
+                },
+              ],
+              details: result,
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "anchored-standard-panel",
+      pluginId: "@pi-harness/core/plugins/anchored-standard",
+      title: "Anchored Standard",
+      description: "审计 Agent 生命周期和工具调用顺序，发现脱离运行锚点的执行。",
+      icon: "⌁",
+      read: report,
+    });
+    context.effect(() => () => {
+      unsubscribe();
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,106 @@
+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 maxQuoteLength = 4_000;
+const maxNoteLength = 1_000;
+const maxAnnotations = 50;
+
+export interface Annotation {
+  id: number;
+  quote: string;
+  note: string;
+  createdAt: string;
+}
+
+export interface AnnotationReport {
+  count: number;
+  annotations: Annotation[];
+}
+
+function requiredText(value: string, label: string, max: number): string {
+  const text = value.trim();
+  if (text.length === 0 || text.length > max) throw new Error(`${label} must contain 1-${max} characters`);
+  return text;
+}
+
+function formatPrompt(annotations: readonly Annotation[], question: string): string {
+  const lines = annotations.flatMap((item) => [`${item.id}. ${item.quote}`, ...(item.note === "" ? [] : [`   Note: ${item.note}`])]);
+  const instruction = annotations.map((item) => `Annotation ${item.id}: …`).join("; ");
+  const body = lines.join("\n");
+  const ask = question.trim();
+  return `I annotated the following ${annotations.length} passage(s):\n\n${body}\n\nPlease respond to each annotation using ${instruction}.\n\nAsk:\n${ask}`;
+}
+
+export default {
+  name: "pi-annotation",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let annotations: Annotation[] = [];
+    let lastPrompt: string | undefined;
+    const report = (): AnnotationReport => ({ count: annotations.length, annotations: [...annotations] });
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "annotation_manage",
+        label: "Manage annotations",
+        description: "Collect numbered passage annotations and render them into a model-ready prompt block.",
+        promptSnippet: "collect a passage annotation and prepare it for the next question",
+        parameters: Type.Object({
+          action: Type.Union([Type.Literal("add"), Type.Literal("list"), Type.Literal("remove"), Type.Literal("clear"), Type.Literal("prompt")]),
+          quote: Type.Optional(Type.String()),
+          note: Type.Optional(Type.String()),
+          id: Type.Optional(Type.Number()),
+          question: Type.Optional(Type.String()),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<AnnotationReport | Annotation | { prompt: string }>> {
+          await Promise.resolve();
+          if (params.action === "add") {
+            if (annotations.length >= maxAnnotations) throw new Error(`At most ${maxAnnotations} annotations can be collected`);
+            const quote = requiredText(params.quote ?? "", "Annotation quote", maxQuoteLength);
+            const note = (params.note ?? "").trim();
+            if (note.length > maxNoteLength) throw new Error(`Annotation note must contain 0-${maxNoteLength} characters`);
+            const annotation: Annotation = {
+              id: annotations.length === 0 ? 1 : Math.max(...annotations.map((item) => item.id)) + 1,
+              quote,
+              note,
+              createdAt: new Date().toISOString(),
+            };
+            annotations = [...annotations, annotation];
+            return { content: [{ type: "text", text: `Annotation ${annotation.id} added.` }], details: annotation };
+          }
+          if (params.action === "remove") {
+            if (!Number.isInteger(params.id) || params.id === undefined) throw new Error("Annotation id is required");
+            const before = annotations.length;
+            annotations = annotations.filter((item) => item.id !== params.id);
+            if (annotations.length === before) throw new Error(`Annotation ${params.id} was not found`);
+            return { content: [{ type: "text", text: `Annotation ${params.id} removed.` }], details: report() };
+          }
+          if (params.action === "clear") {
+            annotations = [];
+            lastPrompt = undefined;
+            return { content: [{ type: "text", text: "Annotations cleared." }], details: report() };
+          }
+          if (params.action === "prompt") {
+            if (annotations.length === 0) throw new Error("Add at least one annotation before rendering a prompt");
+            const prompt = formatPrompt(annotations, params.question ?? "");
+            lastPrompt = prompt;
+            return { content: [{ type: "text", text: prompt }], details: { prompt } };
+          }
+          return { content: [{ type: "text", text: `${annotations.length} annotation(s) collected.` }], details: report() };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "annotation-panel",
+      pluginId: "@pi-harness/core/plugins/annotation",
+      title: "Annotations",
+      description: "收集回复片段并生成带编号的提问上下文。",
+      icon: "⌁",
+      read: () => ({ ...report(), lastPrompt }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,124 @@
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { listWorkspaceNodes, type WorkspaceNode } from "./workspace-navigator.js";
+
+const defaultMaxNodes = 300;
+const maxComponents = 40;
+const maxDependencies = 40;
+
+export interface ArchitectureComponent {
+  readonly id: string;
+  readonly label: string;
+  readonly path: string;
+  readonly files: number;
+  readonly directories: number;
+}
+
+export interface ArchitectureReport {
+  readonly workspace: string;
+  readonly components: readonly ArchitectureComponent[];
+  readonly dependencies: readonly string[];
+  readonly truncated: boolean;
+  readonly mermaid: string;
+}
+
+function componentId(path: string): string {
+  const normalized = path.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return `component_${normalized || "root"}`;
+}
+
+function dependencyId(name: string): string {
+  const normalized = name.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return `dependency_${normalized || "package"}`;
+}
+
+function escapeLabel(value: string): string {
+  return value.replace(/["\r\n]/g, (character) => (character === '"' ? """ : " "));
+}
+
+function topLevelComponents(nodes: readonly WorkspaceNode[]): ArchitectureComponent[] {
+  return nodes
+    .filter((node) => node.kind === "directory" && node.depth === 1)
+    .slice(0, maxComponents)
+    .map((directory) => {
+      const prefix = `${directory.path}/`;
+      const descendants = nodes.filter((node) => node.path.startsWith(prefix));
+      return {
+        id: componentId(directory.path),
+        label: directory.name,
+        path: directory.path,
+        files: descendants.filter((node) => node.kind === "file").length,
+        directories: descendants.filter((node) => node.kind === "directory").length,
+      };
+    });
+}
+
+async function packageDependencies(root: string): Promise<string[]> {
+  try {
+    const parsed = JSON.parse(await readFile(resolve(root, "package.json"), "utf8")) as Record<string, unknown>;
+    const sections = [parsed.dependencies, parsed.devDependencies, parsed.peerDependencies, parsed.optionalDependencies];
+    return [...new Set(sections.flatMap((section) => (section !== null && typeof section === "object" && !Array.isArray(section) ? Object.keys(section) : [])))]
+      .sort((left, right) => left.localeCompare(right))
+      .slice(0, maxDependencies);
+  } catch {
+    return [];
+  }
+}
+
+function render(workspace: string, components: readonly ArchitectureComponent[], dependencies: readonly string[]): string {
+  const lines = [`flowchart LR`, `    project["${escapeLabel(basename(workspace) || "workspace")}"]`];
+  for (const component of components) {
+    lines.push(`    ${component.id}["${escapeLabel(component.label)}\\n${component.files} files · ${component.directories} dirs"]`);
+    lines.push(`    project --> ${component.id}`);
+  }
+  for (const dependency of dependencies) {
+    const id = dependencyId(dependency);
+    lines.push(`    ${id}["${escapeLabel(dependency)}"]`);
+    lines.push(`    project --> ${id}`);
+  }
+  return lines.join("\n");
+}
+
+export async function buildArchitectureReport(root: string, maxNodes = defaultMaxNodes): Promise<ArchitectureReport> {
+  const workspace = resolve(root);
+  const tree = await listWorkspaceNodes(workspace, { maxDepth: 4, maxNodes: Math.max(1, Math.min(500, Math.trunc(maxNodes))) });
+  const components = topLevelComponents(tree.nodes);
+  const dependencies = await packageDependencies(workspace);
+  return { workspace, components, dependencies, truncated: tree.truncated, mermaid: render(workspace, components, dependencies) };
+}
+
+export default {
+  name: "pi-archify",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: ArchitectureReport | undefined;
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "architecture_map",
+        label: "Architecture map",
+        description: "Build a bounded, read-only architecture map from top-level workspace components and package dependencies.",
+        promptSnippet: "map the current workspace architecture",
+        parameters: Type.Object({ maxNodes: Type.Optional(Type.Number({ description: "Maximum scanned workspace nodes, 1-500" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<ArchitectureReport>> {
+          latest = await buildArchitectureReport(context.piHarnessLaunch.cwd, params.maxNodes);
+          return { content: [{ type: "text", text: latest.mermaid }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "archify-panel",
+      pluginId: "@pi-harness/core/plugins/archify",
+      title: "Architecture Map",
+      description: "从工作区目录和 package.json 依赖生成可审计的架构图源码。",
+      icon: "⌘",
+      read: () => ({ latest: latest ?? null, componentCount: latest?.components.length ?? 0, dependencyCount: latest?.dependencies.length ?? 0 }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/at-file.ts

@@ -0,0 +1,54 @@
+import { readFile, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+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 maxBytes = 256 * 1024;
+
+function resolveWorkspaceFile(workspace: string, requested: string): string {
+  const root = resolve(workspace);
+  const target = resolve(root, requested);
+  const path = relative(root, target);
+  if (path.startsWith("..") || path.includes("/..")) throw new Error("File path must stay inside the current workspace");
+  return target;
+}
+
+export default {
+  name: "pi-at-file",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let lastFile: { path: string; bytes: number } | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "file_context",
+        label: "File context",
+        description: "Attach a text file from the current workspace to the model context with a bounded size.",
+        promptSnippet: "attach a workspace file to the current context",
+        parameters: Type.Object({ path: Type.String({ description: "File path relative to the workspace" }) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<{ path: string; bytes: number }>> {
+          const target = resolveWorkspaceFile(context.piHarnessLaunch.cwd, params.path);
+          const metadata = await stat(target);
+          if (!metadata.isFile()) throw new Error("Context path is not a file");
+          if (metadata.size > maxBytes) throw new Error("Context file exceeds the 256 KiB attachment limit");
+          const path = relative(context.piHarnessLaunch.cwd, target) || ".";
+          const text = await readFile(target, "utf8");
+          lastFile = { path, bytes: metadata.size };
+          return { content: [{ type: "text", text: `<file path="${path}">\n${text}\n</file>` }], details: lastFile };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "at-file-panel",
+      pluginId: "@pi-harness/core/plugins/at-file",
+      title: "@file 上下文",
+      description: "将工作区内的文本文件安全附加到当前对话。",
+      icon: "⌁",
+      read: () => ({ lastFile: lastFile ?? null, maxBytes }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/auto-mode.ts

@@ -0,0 +1,123 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+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 execFileAsync = promisify(execFile);
+const maxArgs = 32;
+const maxArgBytes = 4096;
+const maxOutputBytes = 128 * 1024;
+const defaultTimeoutMs = 30_000;
+const shellWrappers = new Set(["sh", "bash", "zsh", "fish", "cmd", "powershell", "pwsh"]);
+const riskyCommands = new Set(["rm", "rmdir", "del", "sudo", "su", "chmod", "chown", "kill", "pkill", "dd", "mkfs"]);
+const riskyWords = new Set(["reset", "clean", "push", "publish", "curl", "wget", "ssh", "scp"]);
+type AutoModeResult = { command: string[]; allowed: boolean; confirmed: boolean; exitCode: number | null; stdout: string; stderr: string; durationMs: number };
+
+export interface AutoModePluginConfig {
+  mode?: "safe" | "confirm";
+  timeoutMs?: number;
+}
+export const Config: z<AutoModePluginConfig> = z.object({
+  mode: z.union(["safe", "confirm"]).default("safe"),
+  timeoutMs: z.number().default(defaultTimeoutMs),
+});
+
+function validateCommand(command: string[]): void {
+  if (command.length === 0 || command.length > maxArgs) throw new Error(`Auto mode command must contain between 1 and ${maxArgs} arguments`);
+  if (command.some((part) => part.length === 0 || Buffer.byteLength(part, "utf8") > maxArgBytes))
+    throw new Error("Auto mode command contains an invalid argument");
+  if (shellWrappers.has((command[0] ?? "").split("/").at(-1)!.toLowerCase()))
+    throw new Error("Auto mode rejects shell wrappers; pass an executable argv directly");
+}
+
+function isRisky(command: string[]): boolean {
+  const executable = (command[0] ?? "").split("/").at(-1)!.toLowerCase();
+  return riskyCommands.has(executable) || command.slice(1).some((part) => riskyWords.has(part.toLowerCase()));
+}
+
+export default {
+  name: "pi-auto-mode",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: AutoModePluginConfig) {
+    const mode = config.mode === "confirm" ? "confirm" : "safe";
+    const timeoutMs = Math.max(1_000, Math.min(120_000, Math.trunc(config.timeoutMs ?? defaultTimeoutMs)));
+    let blocked = 0;
+    let last: AutoModeResult | undefined;
+    const execute = async (command: string[], confirm: boolean): Promise<AutoModeResult> => {
+      try {
+        validateCommand(command);
+      } catch (error) {
+        blocked += 1;
+        throw error;
+      }
+      const risky = isRisky(command);
+      if (risky && !confirm) {
+        blocked += 1;
+        throw new Error("Auto mode blocked a risky command; retry with confirm=true");
+      }
+      if (mode === "confirm" && !confirm) {
+        blocked += 1;
+        throw new Error("Auto mode is configured for confirmation; retry with confirm=true");
+      }
+      const started = Date.now();
+      try {
+        const result = await execFileAsync(command[0]!, command.slice(1), { cwd: context.piHarnessLaunch.cwd, timeout: timeoutMs, maxBuffer: maxOutputBytes });
+        last = {
+          command: [...command],
+          allowed: true,
+          confirmed: confirm,
+          exitCode: 0,
+          stdout: result.stdout.slice(-maxOutputBytes),
+          stderr: result.stderr.slice(-maxOutputBytes),
+          durationMs: Date.now() - started,
+        };
+      } catch (error) {
+        const failure = error as { code?: number | string; stdout?: string; stderr?: string; message?: string };
+        last = {
+          command: [...command],
+          allowed: true,
+          confirmed: confirm,
+          exitCode: typeof failure.code === "number" ? failure.code : 1,
+          stdout: (failure.stdout ?? "").slice(-maxOutputBytes),
+          stderr: (failure.stderr ?? failure.message ?? "").slice(-maxOutputBytes),
+          durationMs: Date.now() - started,
+        };
+      }
+      return last;
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "auto_mode_exec",
+        label: "Auto mode exec",
+        description: "Execute an argv command under the configured safe/confirmation policy without a shell.",
+        promptSnippet: "run a command through the safe auto-mode policy",
+        parameters: Type.Object({
+          command: Type.Array(Type.String()),
+          confirm: Type.Optional(Type.Boolean({ description: "Confirm a risky or confirmation-mode command" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<AutoModeResult>> {
+          const result = await execute(params.command, params.confirm === true);
+          return {
+            content: [{ type: "text", text: `${result.command.join(" ")} exited with ${result.exitCode ?? "unknown"}.\n${result.stdout}${result.stderr}` }],
+            details: result,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "auto-mode-panel",
+      pluginId: "@pi-harness/core/plugins/auto-mode",
+      title: "Auto Mode",
+      description: "按安全策略执行 argv 命令，风险操作需要确认。",
+      icon: "◈",
+      read: () => ({ mode, timeoutMs, blocked, last: last ?? null }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/better-sidebar.ts

@@ -0,0 +1,117 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { listWorkspaceNodes, readWorkspaceGitStatus, type WorkspaceGitStatus, type WorkspaceNodeReport } from "./workspace-navigator.js";
+
+export interface SidebarOverviewInput {
+  readonly cwd: string;
+  readonly gitAvailable: boolean;
+  readonly branch: string | null;
+  readonly clean: boolean;
+  readonly changedFiles: readonly { readonly path: string; readonly status: string }[];
+  readonly directoryCount: number;
+  readonly fileCount: number;
+  readonly truncated: boolean;
+  readonly sessionId: string;
+}
+
+export interface SidebarOverview extends SidebarOverviewInput {
+  readonly changedCount: number;
+  readonly summary: string;
+}
+
+export function summarizeSidebar(input: SidebarOverviewInput): SidebarOverview {
+  const changedCount = input.changedFiles.length;
+  const summary = !input.gitAvailable
+    ? `非 Git 工作区 · ${changedCount > 0 ? `${changedCount} 个变更` : "无变更"}`
+    : `${input.branch ?? "detached HEAD"} · ${changedCount > 0 ? `${changedCount} 个变更` : "clean"}`;
+  return { ...input, changedFiles: input.changedFiles.slice(0, 12), changedCount, summary };
+}
+
+export function createSidebarInspector(input: {
+  readonly cwd: string;
+  readonly getSessionId: () => string;
+  readonly listNodes?: (root: string, options: { maxDepth: number; maxNodes: number }) => Promise<WorkspaceNodeReport>;
+  readonly readGitStatus?: (root: string) => Promise<WorkspaceGitStatus>;
+}): () => Promise<SidebarOverview> {
+  const readNodes = input.listNodes ?? listWorkspaceNodes;
+  const readGit = input.readGitStatus ?? readWorkspaceGitStatus;
+  let tree: WorkspaceNodeReport | undefined;
+  let inFlight: Promise<SidebarOverview> | undefined;
+
+  const inspect = async (): Promise<SidebarOverview> => {
+    const [currentTree, git] = await Promise.all([
+      tree === undefined
+        ? readNodes(input.cwd, { maxDepth: 2, maxNodes: 80 }).then((result) => {
+            tree = result;
+            return result;
+          })
+        : Promise.resolve(tree),
+      readGit(input.cwd),
+    ]);
+    return summarizeSidebar({
+      cwd: input.cwd,
+      gitAvailable: git.available,
+      branch: git.available ? git.branch : null,
+      clean: git.available && git.clean,
+      changedFiles: git.entries,
+      directoryCount: currentTree.directoryCount,
+      fileCount: currentTree.fileCount,
+      truncated: currentTree.truncated,
+      sessionId: input.getSessionId(),
+    });
+  };
+
+  return () => {
+    if (inFlight !== undefined) return inFlight;
+    const current = inspect().finally(() => {
+      if (inFlight === current) inFlight = undefined;
+    });
+    inFlight = current;
+    return current;
+  };
+}
+
+function textSummary(report: SidebarOverview): string {
+  const files = report.changedFiles
+    .slice(0, 8)
+    .map((entry) => `${entry.status} ${entry.path}`)
+    .join(", ");
+  return `${report.summary}; ${report.directoryCount} 个目录，${report.fileCount} 个文件${files ? `; ${files}` : ""}`;
+}
+
+export default {
+  name: "pi-better-sidebar",
+  inject: ["piHarnessLaunch", "piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    const inspect = createSidebarInspector({
+      cwd: context.piHarnessLaunch.cwd,
+      getSessionId: () => context.piSession.manager.getSessionId(),
+    });
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "sidebar_overview",
+        label: "Sidebar overview",
+        description: "Read a compact workspace and Git overview for the current session without modifying files.",
+        promptSnippet: "inspect the workspace overview shown in the sidebar",
+        parameters: Type.Object({}),
+        async execute(): Promise<AgentToolResult<SidebarOverview>> {
+          const report = await inspect();
+          return { content: [{ type: "text", text: textSummary(report) }], details: report };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "better-sidebar-panel",
+      pluginId: "@pi-harness/core/plugins/better-sidebar",
+      title: "Better Sidebar",
+      description: "在会话旁显示当前工作区、Git 变更和文件概览。",
+      icon: "▤",
+      read: inspect,
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};