@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/src/plugins/cost-meter.ts

@@ -0,0 +1,231 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } 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, type SessionStats } from "@earendil-works/pi-coding-agent";
+
+const defaultFileName = "cost-meter.json";
+const defaultMaxEntries = 365;
+const maxFileEntries = 2_000;
+
+export interface CostMeterPluginConfig {
+  fileName?: string;
+  dailyBudget?: number;
+  maxEntries?: number;
+}
+
+export const Config: z<CostMeterPluginConfig> = z.object({
+  fileName: z.string().default(defaultFileName),
+  dailyBudget: z.number().default(0),
+  maxEntries: z.number().default(defaultMaxEntries),
+});
+
+export interface CostEntry {
+  sessionId: string;
+  cost: number;
+  tokens: number;
+  messages: number;
+  recordedAt: string;
+}
+
+export interface CostMeterReport {
+  sessionCost: number;
+  todayCost: number;
+  lifetimeCost: number;
+  budget: number | null;
+  budgetPercent: number | null;
+  entries: CostEntry[];
+}
+
+interface CostFile {
+  version: 1;
+  entries: CostEntry[];
+}
+
+function normalizeFilePath(agentDir: string, fileName: string | undefined): string {
+  const name = (fileName ?? defaultFileName).trim();
+  if (name === "" || basename(name) !== name || !name.toLowerCase().endsWith(".json")) throw new Error("Cost meter fileName must be a single .json filename");
+  return resolve(agentDir, name);
+}
+
+function finiteCost(value: number): number {
+  return Number.isFinite(value) && value >= 0 ? Math.round(value * 1_000_000) / 1_000_000 : 0;
+}
+
+function todayKey(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+function reportFor(entries: readonly CostEntry[], current: SessionStats, budget: number | null): CostMeterReport {
+  const today = todayKey(new Date());
+  const todayCost = entries.filter((entry) => entry.recordedAt.slice(0, 10) === today).reduce((sum, entry) => sum + entry.cost, 0);
+  const lifetimeCost = entries.reduce((sum, entry) => sum + entry.cost, 0);
+  const roundedToday = finiteCost(todayCost);
+  return {
+    sessionCost: finiteCost(current.cost),
+    todayCost: roundedToday,
+    lifetimeCost: finiteCost(lifetimeCost),
+    budget,
+    budgetPercent: budget === null || budget === 0 ? null : Math.round((roundedToday / budget) * 10_000) / 100,
+    entries: [...entries],
+  };
+}
+
+export function upsertCostEntry(entries: readonly CostEntry[], entry: CostEntry, limit: number): CostEntry[] {
+  return [entry, ...entries.filter((item) => item.sessionId !== entry.sessionId)].slice(0, limit);
+}
+
+export default {
+  name: "pi-cost-meter",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: CostMeterPluginConfig) {
+    const filePath = normalizeFilePath(context.piHarnessLaunch.agentDir, config.fileName);
+    const budgetValue =
+      typeof config.dailyBudget === "number" && Number.isFinite(config.dailyBudget) && config.dailyBudget > 0 ? finiteCost(config.dailyBudget) : null;
+    const entryLimit = Math.max(1, Math.min(maxFileEntries, Math.trunc(config.maxEntries ?? defaultMaxEntries)));
+    let entries: CostEntry[] = [];
+    let loaded = false;
+    let loading: Promise<void> | undefined;
+    let writeQueue = Promise.resolve();
+    let pendingRecord: Promise<void> | undefined;
+    const runtime = () => {
+      const service = context.get("piRuntime");
+      if (service === undefined) throw new Error("Pi runtime is not ready");
+      return service;
+    };
+    const load = async (): Promise<void> => {
+      if (loaded) return;
+      if (loading !== undefined) return loading;
+      loading = (async () => {
+        try {
+          const parsed = JSON.parse(await readFile(filePath, "utf8")) as Partial<CostFile>;
+          if (parsed.version !== 1 || !Array.isArray(parsed.entries)) throw new Error("Cost meter file has an unsupported format");
+          entries = parsed.entries.filter(
+            (entry): entry is CostEntry =>
+              typeof entry === "object" &&
+              entry !== null &&
+              typeof entry.sessionId === "string" &&
+              typeof entry.recordedAt === "string" &&
+              typeof entry.cost === "number",
+          );
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+          entries = [];
+        }
+        loaded = true;
+      })();
+      return loading;
+    };
+    const persist = async (): Promise<void> => {
+      writeQueue = writeQueue.then(async () => {
+        await mkdir(dirname(filePath), { recursive: true });
+        const lockPath = `${filePath}.lock`;
+        let lock: Awaited<ReturnType<typeof open>> | undefined;
+        for (let attempt = 0; attempt < 80; attempt += 1) {
+          try {
+            lock = await open(lockPath, "wx", 0o600);
+            break;
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST" || attempt === 79) throw error;
+            const lockAge = await stat(lockPath)
+              .then((metadata) => Date.now() - metadata.mtimeMs)
+              .catch(() => 0);
+            if (lockAge > 30_000) await unlink(lockPath).catch(() => {});
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, 25));
+          }
+        }
+        if (lock === undefined) throw new Error("Could not acquire the cost meter persistence lock");
+        try {
+          const diskEntries = await readFile(filePath, "utf8")
+            .then((source) => {
+              const parsed = JSON.parse(source) as Partial<CostFile>;
+              return parsed.version === 1 && Array.isArray(parsed.entries) ? parsed.entries : [];
+            })
+            .catch((error: unknown) => {
+              if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+              throw error;
+            });
+          const merged = new Map(diskEntries.map((entry) => [entry.sessionId, entry]));
+          for (const entry of entries) {
+            const existing = merged.get(entry.sessionId);
+            if (existing === undefined || entry.recordedAt >= existing.recordedAt) merged.set(entry.sessionId, entry);
+          }
+          entries = [...merged.values()].sort((left, right) => right.recordedAt.localeCompare(left.recordedAt)).slice(0, entryLimit);
+          const payload = JSON.stringify({ version: 1, entries } satisfies CostFile, null, 2);
+          const temporary = join(dirname(filePath), `.${basename(filePath)}.${randomUUID()}.tmp`);
+          let renamed = false;
+          try {
+            await writeFile(temporary, payload, { encoding: "utf8", mode: 0o600, flag: "wx" });
+            await rename(temporary, filePath);
+            renamed = true;
+          } finally {
+            if (!renamed) await unlink(temporary).catch(() => {});
+          }
+        } finally {
+          await lock.close();
+          await unlink(lockPath).catch(() => {});
+        }
+      });
+      await writeQueue;
+    };
+    const record = async (): Promise<void> => {
+      await load();
+      const current = runtime().session.getSessionStats();
+      const signature = `${current.sessionId}:${current.totalMessages}:${finiteCost(current.cost)}`;
+      if (entries.some((entry) => `${entry.sessionId}:${entry.messages}:${entry.cost}` === signature)) return;
+      entries = upsertCostEntry(
+        entries,
+        {
+          sessionId: current.sessionId,
+          cost: finiteCost(current.cost),
+          tokens: current.tokens.total,
+          messages: current.totalMessages,
+          recordedAt: new Date().toISOString(),
+        },
+        entryLimit,
+      );
+      await persist();
+    };
+    const readReport = async (): Promise<CostMeterReport> => {
+      await load();
+      await pendingRecord;
+      return reportFor(entries, runtime().session.getSessionStats(), budgetValue);
+    };
+    const unsubscribe = context.on("pi/session-event", (event) => {
+      if (event.type === "agent_end") pendingRecord = record();
+    });
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "cost_report",
+        label: "Cost report",
+        description: "Inspect current-session, daily, and persisted local model cost usage with an optional daily budget.",
+        promptSnippet: "inspect session and daily model cost usage",
+        parameters: Type.Object({ refresh: Type.Optional(Type.Boolean({ description: "Record the current completed session before reporting" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<CostMeterReport>> {
+          if (params.refresh === true) await record();
+          const report = await readReport();
+          return {
+            content: [{ type: "text", text: `Today cost $${report.todayCost.toFixed(4)}; current session $${report.sessionCost.toFixed(4)}.` }],
+            details: report,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "cost-meter-panel",
+      pluginId: "@pi-harness/core/plugins/cost-meter",
+      title: "Cost Meter",
+      description: "查看当前会话、今日和历史成本，并监控每日预算。",
+      icon: "¤",
+      read: readReport,
+    });
+    context.effect(() => () => {
+      unsubscribe();
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/dependency-checker.ts

@@ -0,0 +1,241 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, dirname, join, relative } 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 { resolveExistingWorkspacePath } from "../workspace-path.js";
+
+export type DependencyConflict = {
+  name: string;
+  constraints: string[];
+};
+
+export type DependencyReport = {
+  manifest: string;
+  ecosystem: "npm" | "python";
+  declared: number;
+  installed: number;
+  missing: string[];
+  invalid: string[];
+  conflicts: DependencyConflict[];
+};
+
+export type ParsedRequirements = {
+  names: string[];
+  constraints: DependencyConflict[];
+};
+
+function conflictList(entries: readonly { name: string; constraint: string }[]): DependencyConflict[] {
+  const grouped = new Map<string, string[]>();
+  for (const entry of entries) {
+    const values = grouped.get(entry.name) ?? [];
+    if (!values.includes(entry.constraint)) values.push(entry.constraint);
+    grouped.set(entry.name, values);
+  }
+  return [...grouped.entries()].filter(([, constraints]) => constraintsConflict(constraints)).map(([name, constraints]) => ({ name, constraints }));
+}
+
+type NumericVersion = readonly number[];
+
+function numericVersion(value: string): NumericVersion | undefined {
+  const match = /^v?(\d+(?:\.\d+){0,3})(?:[-+].*)?$/u.exec(value.trim());
+  return match?.[1]?.split(".").map(Number);
+}
+
+function compareVersions(left: NumericVersion, right: NumericVersion): number {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}
+
+function constraintAllows(constraint: string, version: NumericVersion): boolean {
+  const parts = constraint
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return parts.every((part) => {
+    const match = /^(===|==|=|>=|<=|>|<|\^|~)?\s*(v?\d+(?:\.\d+){0,3}(?:[-+][^\s]+)?)$/u.exec(part);
+    if (match === null) return true;
+    const candidate = numericVersion(match[2] ?? "");
+    if (candidate === undefined) return true;
+    const comparison = compareVersions(version, candidate);
+    switch (match[1] ?? "=") {
+      case ">=":
+        return comparison >= 0;
+      case "<=":
+        return comparison <= 0;
+      case ">":
+        return comparison > 0;
+      case "<":
+        return comparison < 0;
+      case "^":
+        return (
+          comparison >= 0 &&
+          version[0] === candidate[0] &&
+          ((candidate[0] ?? 0) > 0 || (version[1] === candidate[1] && ((candidate[1] ?? 0) > 0 || version[2] === candidate[2])))
+        );
+      case "~":
+        return comparison >= 0 && version[0] === candidate[0] && version[1] === candidate[1];
+      default:
+        return comparison === 0;
+    }
+  });
+}
+
+function constraintsConflict(constraints: readonly string[]): boolean {
+  if (constraints.length < 2) return false;
+  const pinned = constraints.flatMap((constraint) => {
+    const match = /^(?:===|==|=)?\s*(v?\d+(?:\.\d+){0,3}(?:[-+][^\s]+)?)$/u.exec(constraint);
+    const version = match === null ? undefined : numericVersion(match[1] ?? "");
+    return version === undefined ? [] : [version];
+  });
+  if (pinned.length === 0) return false;
+  return pinned.some((version) => constraints.some((constraint) => !constraintAllows(constraint, version)));
+}
+
+export function parseRequirements(source: string): ParsedRequirements {
+  const entries: { name: string; constraint: string }[] = [];
+  for (const rawLine of source.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith("-") || line.startsWith("git+") || line.startsWith("http://") || line.startsWith("https://"))
+      continue;
+    const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]+\])?\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const name = match[1]!.toLowerCase().replaceAll("_", "-");
+    entries.push({ name, constraint: match[2]?.trim() ?? "" });
+  }
+  const names = [...new Set(entries.map((entry) => entry.name))];
+  return { names, constraints: conflictList(entries) };
+}
+
+async function installedPythonPackage(workspace: string, name: string): Promise<boolean> {
+  const normalized = name.toLowerCase().replaceAll("-", "_");
+  for (const environment of [".venv", "venv"]) {
+    const lib = join(workspace, environment, "lib");
+    const versions = await readdir(lib, { withFileTypes: true }).catch(() => []);
+    for (const version of versions) {
+      if (!version.isDirectory() || !version.name.startsWith("python")) continue;
+      const sitePackages = join(lib, version.name, "site-packages");
+      const entries = await readdir(sitePackages, { withFileTypes: true }).catch(() => []);
+      if (entries.some((entry) => entry.name === normalized || entry.name.startsWith(`${normalized}-`) || entry.name.startsWith(`${normalized}.`))) return true;
+    }
+  }
+  return false;
+}
+
+async function inspectRequirements(workspace: string, target: string): Promise<DependencyReport> {
+  const parsed = parseRequirements(await readFile(target, "utf8"));
+  const missing: string[] = [];
+  for (const name of parsed.names) {
+    if (!(await installedPythonPackage(dirname(target), name)) && !(await installedPythonPackage(workspace, name))) missing.push(name);
+  }
+  return {
+    manifest: relative(workspace, target) || ".",
+    ecosystem: "python",
+    declared: parsed.names.length,
+    installed: parsed.names.length - missing.length,
+    missing,
+    invalid: [],
+    conflicts: parsed.constraints,
+  };
+}
+
+export async function inspectManifest(workspace: string, requested = "package.json"): Promise<DependencyReport> {
+  const resolved = await resolveExistingWorkspacePath(workspace, requested, "Manifest path must stay inside the current workspace");
+  const target = resolved.target;
+  workspace = resolved.root;
+  const source = await readFile(target, "utf8");
+  if (basename(target).toLowerCase().startsWith("requirements") && target.toLowerCase().endsWith(".txt")) return inspectRequirements(workspace, target);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source) as unknown;
+  } catch (error) {
+    throw new Error(`Invalid JSON manifest: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Manifest root must be an object");
+  const record = parsed as Record<string, unknown>;
+  const sections = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+  const entries = sections.flatMap((section) => {
+    const value = record[section];
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+      ? Object.entries(value).map(([name, constraint]) => ({ name, constraint: typeof constraint === "string" ? constraint : String(constraint) }))
+      : [];
+  });
+  const unique = [...new Set(entries.map((entry) => entry.name))];
+  const moduleRoots: string[] = [];
+  for (let directory = dirname(target); ; directory = dirname(directory)) {
+    moduleRoots.push(join(directory, "node_modules"));
+    if (directory === workspace) break;
+  }
+  const missing: string[] = [];
+  const invalid: string[] = [];
+  for (const name of unique) {
+    let found = false;
+    for (const moduleRoot of moduleRoots) {
+      try {
+        const moduleStat = await stat(join(moduleRoot, ...name.split("/")));
+        if (moduleStat.isDirectory()) {
+          found = true;
+          break;
+        }
+        invalid.push(name);
+        found = true;
+        break;
+      } catch {
+        continue;
+      }
+    }
+    if (!found) missing.push(name);
+  }
+  return {
+    manifest: relative(workspace, target) || ".",
+    ecosystem: "npm",
+    declared: unique.length,
+    installed: unique.length - missing.length - invalid.length,
+    missing,
+    invalid,
+    conflicts: conflictList(entries),
+  };
+}
+
+export default {
+  name: "pi-dependency-checker",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: DependencyReport | undefined;
+    const inspect = async (manifest?: string): Promise<DependencyReport> => {
+      latest = await inspectManifest(context.piHarnessLaunch.cwd, manifest);
+      return latest;
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "dependency_check",
+        label: "Dependency check",
+        description: "Inspect package.json or requirements.txt and report missing dependencies plus conflicting version constraints.",
+        promptSnippet: "check local dependency installation and version conflicts",
+        parameters: Type.Object({ manifest: Type.Optional(Type.String({ description: "package.json or requirements.txt path relative to the workspace" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<DependencyReport>> {
+          const report = await inspect(params.manifest);
+          return {
+            content: [{ type: "text", text: `${report.manifest}: ${report.missing.length} missing dependencies, ${report.conflicts.length} conflicts.` }],
+            details: report,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "dependency-checker-panel",
+      pluginId: "@pi-harness/core/plugins/dependency-checker",
+      title: "Dependency Checker",
+      description: "检查 package.json 或 requirements.txt 的依赖安装状态和版本冲突。",
+      icon: "⊙",
+      read: async () => ({ report: latest ?? (await inspect()) }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/docker-sandbox.ts

@@ -0,0 +1,100 @@
+import { execFile } from "node:child_process";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+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 execFileAsync = promisify(execFile);
+const shellCommands = new Set(["sh", "bash", "zsh", "fish", "cmd", "powershell", "pwsh"]);
+type SandboxRun = { image: string; command: string[]; write: boolean; exitCode: number; output: string };
+
+function validateImage(image: string): void {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._/@:-]*$/.test(image)) throw new Error("Invalid Docker image reference");
+}
+
+export default {
+  name: "pi-docker-sandbox",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: SandboxRun | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "sandbox_exec",
+        label: "Docker sandbox",
+        description: "Run an argv command in a no-network Docker container with the workspace mounted read-only by default.",
+        promptSnippet: "run a command in an isolated no-network Docker sandbox",
+        parameters: Type.Object({
+          command: Type.Array(Type.String(), { description: "Executable and arguments; shell wrappers are rejected" }),
+          image: Type.Optional(Type.String({ description: "Local Docker image, default alpine:3.20" })),
+          write: Type.Optional(Type.Boolean({ description: "Mount the workspace read-write" })),
+          confirmWrite: Type.Optional(Type.Boolean({ description: "Must be true when write is enabled" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<SandboxRun>> {
+          if (params.command.length === 0) throw new Error("Sandbox command cannot be empty");
+          const executable = params.command[0];
+          if (executable === undefined) throw new Error("Sandbox command cannot be empty");
+          if (shellCommands.has(basename(executable).toLowerCase())) throw new Error("Shell wrappers are not allowed; pass an executable argv directly");
+          const image = params.image?.trim() || "alpine:3.20";
+          validateImage(image);
+          const write = params.write === true;
+          if (write && params.confirmWrite !== true) throw new Error("Writable sandbox requires confirmWrite=true");
+          try {
+            await execFileAsync("docker", ["image", "inspect", image], { timeout: 30_000, maxBuffer: 1_000_000 });
+          } catch (error) {
+            const failure = error as { code?: number | string; message?: string };
+            if (failure.code === "ENOENT") throw new Error("Docker executable is not available on PATH", { cause: error });
+            throw new Error(`Docker image is not available locally: ${image}`, { cause: error });
+          }
+          const args = [
+            "run",
+            "--rm",
+            "--network",
+            "none",
+            "--read-only",
+            "--tmpfs",
+            "/tmp:rw,noexec,nosuid",
+            "--cap-drop",
+            "ALL",
+            "--security-opt",
+            "no-new-privileges",
+            "--pids-limit",
+            "256",
+            "--mount",
+            `type=bind,src=${context.piHarnessLaunch.cwd},dst=/workspace${write ? "" : ",readonly"}`,
+            "--workdir",
+            "/workspace",
+            image,
+            ...params.command,
+          ];
+          try {
+            const result = await execFileAsync("docker", args, { cwd: context.piHarnessLaunch.cwd, timeout: 120_000, maxBuffer: 4 * 1024 * 1024 });
+            latest = { image, command: [...params.command], write, exitCode: 0, output: `${result.stdout}${result.stderr}`.slice(-12_000) };
+          } catch (error) {
+            const failure = error as { code?: number | string; stdout?: string; stderr?: string; message?: string };
+            latest = {
+              image,
+              command: [...params.command],
+              write,
+              exitCode: typeof failure.code === "number" ? failure.code : 1,
+              output: `${failure.stdout ?? ""}${failure.stderr ?? failure.message ?? ""}`.slice(-12_000),
+            };
+          }
+          return { content: [{ type: "text", text: `Docker sandbox exited with ${latest.exitCode}.\n${latest.output}` }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "docker-sandbox-panel",
+      pluginId: "@pi-harness/core/plugins/docker-sandbox",
+      title: "Docker Sandbox",
+      description: "无网络、只读挂载、去除 Linux capabilities 的隔离执行环境。",
+      icon: "⬡",
+      read: () => ({ latest: latest ?? null, defaults: { network: "none", workspace: "read-only", image: "alpine:3.20" } }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/fail-logger.ts

@@ -0,0 +1,51 @@
+import type { Context } from "@deepseek-ai/cordis";
+
+type Failure = { time: string; source: string; message: string };
+
+function messageOf(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "object" && error !== null && "error" in error) {
+    const { error: message, extensionPath } = error as { error: unknown; extensionPath?: unknown };
+    const text = typeof message === "string" ? message : String(message);
+    return typeof extensionPath === "string" ? `${extensionPath}: ${text}` : text;
+  }
+  return typeof error === "string" ? error : (JSON.stringify(error) ?? String(error));
+}
+
+export default {
+  name: "pi-fail-logger",
+  inject: ["piPluginUi"],
+  apply(context: Context) {
+    const failures: Failure[] = [];
+    let previous: string | undefined;
+    const record = (source: string, error: unknown): void => {
+      const message = messageOf(error);
+      const fingerprint = `${source}:${message}`;
+      if (fingerprint === previous) return;
+      previous = fingerprint;
+      failures.push({ time: new Date().toISOString(), source, message });
+      if (failures.length > 50) failures.shift();
+    };
+    const unsubscribeExtension = context.on("pi/extension-error", (error) => record("extension", error));
+    const unsubscribeSession = context.on("pi/session-event", (event) => {
+      const last = event.type === "agent_end" ? event.messages.at(-1) : undefined;
+      if (last?.role === "assistant" && last.stopReason === "error") {
+        record("agent", last.errorMessage ?? "Agent turn failed");
+      }
+      if (event.type === "compaction_end" && event.errorMessage) record("compaction", event.errorMessage);
+    });
+    const disposePanel = context.piPluginUi.register({
+      id: "fail-logger-panel",
+      pluginId: "@pi-harness/core/plugins/fail-logger",
+      title: "Failure Logger",
+      description: "集中记录扩展、Agent 和上下文压缩错误，并去重重复故障。",
+      icon: "!",
+      read: () => ({ total: failures.length, failures: [...failures].reverse() }),
+    });
+    context.effect(() => () => {
+      unsubscribeExtension();
+      unsubscribeSession();
+      disposePanel();
+    });
+  },
+};