@pi-harness/pi-harness 0.1.2 → 0.1.4

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

@@ -0,0 +1,88 @@
+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 maxBlocks = 12;
+const maxTextLength = 4000;
+type BlockType = "text" | "badge" | "progress";
+type Tone = "neutral" | "info" | "success" | "warning" | "danger";
+type GenUiBlock = { type: BlockType; label: string; value: string | number; tone: Tone };
+type GenUiReport = { title: string; blocks: GenUiBlock[]; renderedAt: string };
+
+function cleanText(value: string, field: string): string {
+  const text = value.trim();
+  if (text.length === 0) throw new Error(`${field} must not be empty`);
+  if (text.length > maxTextLength) throw new Error(`${field} must be at most ${maxTextLength} characters`);
+  return text;
+}
+
+function normalizeBlock(block: { type: BlockType; label: string; value: string; tone?: Tone }): GenUiBlock {
+  const label = cleanText(block.label, "Block label");
+  const rawValue = cleanText(block.value, "Block value");
+  if (block.type !== "progress") return { type: block.type, label, value: rawValue, tone: block.tone ?? "neutral" };
+  const value = Number(rawValue);
+  if (!Number.isFinite(value) || value < 0 || value > 100) throw new Error("Progress value must be a number from 0 to 100");
+  return { type: "progress", label, value, tone: block.tone ?? "info" };
+}
+
+export default {
+  name: "pi-genui",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let rendered = 0;
+    let latest: GenUiReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "genui_render",
+        label: "Render structured UI",
+        description: "Render safe structured text, badge, and progress blocks in the GenUI panel; HTML and scripts are treated as plain text.",
+        promptSnippet: "render a structured status card for the user",
+        parameters: Type.Object({
+          title: Type.String(),
+          blocks: Type.Array(
+            Type.Object({
+              type: Type.Union(["text", "badge", "progress"]),
+              label: Type.String(),
+              value: Type.String(),
+              tone: Type.Optional(Type.Union(["neutral", "info", "success", "warning", "danger"])),
+            }),
+          ),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<GenUiReport>> {
+          return Promise.resolve().then(() => {
+            if (params.blocks.length === 0 || params.blocks.length > maxBlocks) throw new Error(`GenUI requires 1 to ${maxBlocks} blocks`);
+            latest = {
+              title: cleanText(params.title, "Title"),
+              blocks: params.blocks.map((block) =>
+                normalizeBlock({
+                  type: block.type as BlockType,
+                  label: block.label,
+                  value: block.value,
+                  ...(block.tone === undefined ? {} : { tone: block.tone as Tone }),
+                }),
+              ),
+              renderedAt: new Date().toISOString(),
+            };
+            rendered += 1;
+            return {
+              content: [{ type: "text" as const, text: `Rendered ${latest.blocks.length} structured UI block(s): ${latest.title}` }],
+              details: latest,
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "genui-panel",
+      pluginId: "@pi-harness/core/plugins/genui",
+      title: "GenUI",
+      description: "渲染安全的结构化状态卡片；文本中的 HTML 和脚本不会被执行。",
+      icon: "▤",
+      read: () => ({ rendered, latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/git-time-capsule.ts

@@ -0,0 +1,97 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { basename, join } 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 execFileAsync = promisify(execFile);
+const capsuleDirectory = "capsules";
+
+async function git(cwd: string, args: readonly string[]): Promise<string> {
+  const result = await execFileAsync("git", [...args], { cwd, maxBuffer: 8 * 1024 * 1024 });
+  return result.stdout;
+}
+
+export async function applyCapsule(cwd: string, capsulePath: string): Promise<void> {
+  try {
+    await git(cwd, ["apply", "--reverse", "--check", "--binary", capsulePath]);
+  } catch (cause) {
+    throw new Error("Git capsule does not apply cleanly", { cause });
+  }
+  await git(cwd, ["apply", "--reverse", "--binary", capsulePath]);
+}
+
+async function listCapsules(directory: string): Promise<{ name: string; bytes: number }[]> {
+  const names = (await readdir(directory).catch(() => [] as string[]))
+    .filter((name) => name.endsWith(".patch"))
+    .sort()
+    .reverse()
+    .slice(0, 20);
+  return Promise.all(names.map(async (name) => ({ name, bytes: (await stat(join(directory, name))).size })));
+}
+
+export default {
+  name: "pi-git-time-capsule",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    const directory = join(context.piHarnessLaunch.agentDir, capsuleDirectory);
+    let latest: { name: string; bytes: number; files: number; restored?: boolean } | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "git_snapshot",
+        label: "Git snapshot",
+        description: "Save the current tracked Git diff as a timestamped patch outside the workspace for rollback or review.",
+        promptSnippet: "save a rollback patch before changing code",
+        parameters: Type.Object({}),
+        async execute(): Promise<AgentToolResult<{ path: string; bytes: number; files: number }>> {
+          const status = await git(context.piHarnessLaunch.cwd, ["status", "--short"]);
+          const patch = await git(context.piHarnessLaunch.cwd, ["diff", "HEAD", "--binary", "--no-ext-diff", "--", ".", ":(exclude).pi-harness/capsules"]);
+          await mkdir(directory, { recursive: true });
+          const timestamp = new Date().toISOString().replace(/[-:.]/g, "");
+          const name = `${timestamp}-${randomUUID().slice(0, 8)}.patch`;
+          const path = join(directory, name);
+          await writeFile(path, patch, { encoding: "utf8", mode: 0o600, flag: "wx" });
+          const files = status.split("\n").filter((line) => line.trim() !== "" && !line.startsWith("??")).length;
+          latest = { name, bytes: Buffer.byteLength(patch), files };
+          return { content: [{ type: "text", text: `Git snapshot saved: ${name}` }], details: { path, bytes: latest.bytes, files } };
+        },
+      }),
+    );
+    const unregisterRestore = context.piTools.register(
+      defineTool({
+        name: "git_restore",
+        label: "Restore Git snapshot",
+        description: "Apply a saved Git time capsule after an explicit confirmation; the patch is checked before it changes the workspace.",
+        promptSnippet: "restore a previously saved Git snapshot",
+        parameters: Type.Object({ name: Type.String({ description: "Capsule filename from the recent snapshots list" }), confirm: Type.Boolean() }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<{ name: string; restored: true }>> {
+          if (!params.confirm) throw new Error("Git capsule restore writes the workspace and requires confirm=true");
+          const name = params.name.trim();
+          if (name.length === 0 || name.length > 255 || basename(name) !== name || !name.endsWith(".patch"))
+            throw new Error("Capsule name must be a .patch filename");
+          const path = join(directory, name);
+          await applyCapsule(context.piHarnessLaunch.cwd, path);
+          const bytes = (await stat(path)).size;
+          latest = { name, bytes, files: 0, restored: true };
+          return { content: [{ type: "text", text: `Git snapshot restored: ${name}` }], details: { name, restored: true } };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "git-time-capsule-panel",
+      pluginId: "@pi-harness/core/plugins/git-time-capsule",
+      title: "Git Time Capsule",
+      description: "查看最近的代码快照；快照保存在工作区之外，不会污染项目文件。",
+      icon: "◫",
+      read: async () => ({ latest: latest ?? null, capsules: await listCapsules(directory) }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      unregisterRestore();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/graph-memory.ts

@@ -0,0 +1,394 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, 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 } from "@earendil-works/pi-coding-agent";
+
+const defaultFileName = "graph-memory.json";
+const absoluteNodeLimit = 2_000;
+const absoluteRelationLimit = 5_000;
+const maxLabelLength = 160;
+const maxSummaryBytes = 16 * 1024;
+const maxSourceLength = 512;
+const maxQueryLength = 160;
+const maxFileBytes = 4 * 1024 * 1024;
+const lockRetryMs = 25;
+const lockTimeoutMs = 10_000;
+
+type NodeKind = "task" | "skill" | "event";
+type RelationKind = "USED_SKILL" | "SOLVED_BY" | "REQUIRES" | "PATCHES" | "CONFLICTS_WITH" | "RELATED_TO";
+type GraphNode = { id: string; kind: NodeKind; label: string; summary: string; source?: string; createdAt: string; updatedAt: string };
+type GraphRelation = { id: string; from: string; to: string; relation: RelationKind; createdAt: string };
+type GraphFile = { version: 1; nodes: GraphNode[]; relations: GraphRelation[] };
+type GraphSearchReport = { query: string; total: number; nodes: GraphNode[]; relations: GraphRelation[] };
+type GraphState = Pick<GraphFile, "nodes" | "relations">;
+
+export interface GraphMemoryPluginConfig {
+  fileName?: string;
+  maxNodes?: number;
+  maxRelations?: number;
+}
+
+export const Config: z<GraphMemoryPluginConfig> = z.object({
+  fileName: z.string().default(defaultFileName),
+  maxNodes: z.number().default(absoluteNodeLimit),
+  maxRelations: z.number().default(absoluteRelationLimit),
+});
+
+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("Graph memory fileName must be a single .json filename");
+  return resolve(agentDir, name);
+}
+
+function normalizeText(value: string, field: string, maxLength: number): string {
+  const normalized = value.trim();
+  if (normalized.length === 0 || normalized.length > maxLength) throw new Error(`${field} must contain 1-${maxLength} characters`);
+  return normalized;
+}
+
+function normalizeSummary(value: string): string {
+  const normalized = value.trim();
+  if (normalized === "" || Buffer.byteLength(normalized, "utf8") > maxSummaryBytes)
+    throw new Error(`Graph memory summary must be non-empty and at most ${maxSummaryBytes} bytes`);
+  return normalized;
+}
+
+function isNodeKind(value: unknown): value is NodeKind {
+  return value === "task" || value === "skill" || value === "event";
+}
+
+function isRelationKind(value: unknown): value is RelationKind {
+  return value === "USED_SKILL" || value === "SOLVED_BY" || value === "REQUIRES" || value === "PATCHES" || value === "CONFLICTS_WITH" || value === "RELATED_TO";
+}
+
+function isGraphNode(value: unknown): value is GraphNode {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const node = value as Record<string, unknown>;
+  return (
+    typeof node.id === "string" &&
+    node.id.length > 0 &&
+    node.id.length <= maxLabelLength &&
+    isNodeKind(node.kind) &&
+    typeof node.label === "string" &&
+    node.label.trim().length > 0 &&
+    node.label.length <= maxLabelLength &&
+    typeof node.summary === "string" &&
+    node.summary.trim().length > 0 &&
+    Buffer.byteLength(node.summary, "utf8") <= maxSummaryBytes &&
+    (node.source === undefined || typeof node.source === "string") &&
+    (node.source === undefined || (node.source.length > 0 && node.source.length <= maxSourceLength)) &&
+    typeof node.createdAt === "string" &&
+    Number.isFinite(Date.parse(node.createdAt)) &&
+    typeof node.updatedAt === "string" &&
+    Number.isFinite(Date.parse(node.updatedAt))
+  );
+}
+
+function isGraphRelation(value: unknown): value is GraphRelation {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const relation = value as Record<string, unknown>;
+  return (
+    typeof relation.id === "string" &&
+    relation.id.length > 0 &&
+    relation.id.length <= maxLabelLength &&
+    typeof relation.from === "string" &&
+    typeof relation.to === "string" &&
+    isRelationKind(relation.relation) &&
+    typeof relation.createdAt === "string" &&
+    Number.isFinite(Date.parse(relation.createdAt))
+  );
+}
+
+async function readGraphFile(filePath: string, nodeLimit: number, relationLimit: number): Promise<GraphState> {
+  let raw: Buffer;
+  try {
+    raw = await readFile(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { nodes: [], relations: [] };
+    throw error;
+  }
+  if (raw.byteLength > maxFileBytes) throw new Error(`Graph memory file exceeds its ${maxFileBytes}-byte limit`);
+  const parsed = JSON.parse(raw.toString("utf8")) as Partial<GraphFile>;
+  if (parsed.version !== 1 || !Array.isArray(parsed.nodes) || !Array.isArray(parsed.relations)) throw new Error("Graph memory file has an unsupported format");
+  if (!parsed.nodes.every(isGraphNode)) throw new Error("Graph memory file contains invalid nodes");
+  if (!parsed.relations.every(isGraphRelation)) throw new Error("Graph memory file contains invalid relations");
+  if (parsed.nodes.length > nodeLimit) throw new Error(`Graph memory file exceeds its ${nodeLimit}-node limit`);
+  if (parsed.relations.length > relationLimit) throw new Error(`Graph memory file exceeds its ${relationLimit}-relation limit`);
+  const nodeIds = new Set(parsed.nodes.map((node) => node.id));
+  const relationIds = new Set<string>();
+  for (const relation of parsed.relations) {
+    if (!nodeIds.has(relation.from) || !nodeIds.has(relation.to)) throw new Error("Graph memory file contains relations with missing nodes");
+    if (relation.from === relation.to) throw new Error("Graph memory file contains self-relations");
+    if (!relationIds.add(relation.id)) throw new Error("Graph memory file contains duplicate relation ids");
+  }
+  if (nodeIds.size !== parsed.nodes.length) throw new Error("Graph memory file contains duplicate node ids");
+  return { nodes: parsed.nodes, relations: parsed.relations };
+}
+
+async function writeGraphFile(filePath: string, state: GraphState): Promise<void> {
+  const payload = JSON.stringify({ version: 1, ...state } satisfies GraphFile, null, 2);
+  await mkdir(dirname(filePath), { recursive: true });
+  const temporary = join(dirname(filePath), `.${basename(filePath)}.${randomUUID()}.tmp`);
+  await writeFile(temporary, payload, { encoding: "utf8", mode: 0o600 });
+  await rename(temporary, filePath);
+}
+
+async function acquireGraphLock(lockPath: string): Promise<() => Promise<void>> {
+  const deadline = Date.now() + lockTimeoutMs;
+  while (true) {
+    try {
+      await mkdir(lockPath);
+      return async () => {
+        await rm(lockPath, { recursive: true, force: true });
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST" || Date.now() >= deadline)
+        throw new Error("Timed out waiting for graph memory file lock", { cause: error });
+      await new Promise<void>((resolve) => setTimeout(resolve, lockRetryMs));
+    }
+  }
+}
+
+export default {
+  name: "pi-graph-memory",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: GraphMemoryPluginConfig) {
+    const filePath = normalizeFilePath(context.piHarnessLaunch.agentDir, config.fileName);
+    const nodeLimit = Math.max(1, Math.min(absoluteNodeLimit, Math.trunc(config.maxNodes ?? absoluteNodeLimit)));
+    const relationLimit = Math.max(1, Math.min(absoluteRelationLimit, Math.trunc(config.maxRelations ?? absoluteRelationLimit)));
+    let nodes: GraphNode[] = [];
+    let relations: GraphRelation[] = [];
+    let loaded = false;
+    let loading: Promise<void> | undefined;
+    let mutationQueue = Promise.resolve();
+    let lastSearch: GraphSearchReport | undefined;
+
+    const load = async (): Promise<void> => {
+      if (loaded) return;
+      if (loading !== undefined) return loading;
+      loading = (async () => {
+        const state = await readGraphFile(filePath, nodeLimit, relationLimit);
+        nodes = state.nodes;
+        relations = state.relations;
+        loaded = true;
+      })();
+      return loading;
+    };
+
+    const mutate = async <T>(operation: (state: GraphState) => T): Promise<T> => {
+      let result: T | undefined;
+      const run = async (): Promise<void> => {
+        const release = await acquireGraphLock(`${filePath}.lock`);
+        try {
+          const state = await readGraphFile(filePath, nodeLimit, relationLimit);
+          result = operation(state);
+          await writeGraphFile(filePath, state);
+          nodes = state.nodes;
+          relations = state.relations;
+          loaded = true;
+        } finally {
+          await release();
+        }
+      };
+      mutationQueue = mutationQueue.catch(() => undefined).then(run);
+      await mutationQueue;
+      return result as T;
+    };
+
+    const recordTool = defineTool({
+      name: "graph_memory_record",
+      label: "Record graph memory",
+      description: "Persist or update one typed task, skill, or event node with explicit provenance in the local graph memory.",
+      promptSnippet: "record durable typed knowledge in the local graph memory",
+      parameters: Type.Object({
+        kind: Type.Union([Type.Literal("task"), Type.Literal("skill"), Type.Literal("event")]),
+        label: Type.String(),
+        summary: Type.String(),
+        source: Type.Optional(Type.String()),
+      }),
+      async execute(_toolCallId, params): Promise<AgentToolResult<GraphNode>> {
+        const label = normalizeText(params.label, "Graph memory label", maxLabelLength);
+        const summary = normalizeSummary(params.summary);
+        const source = params.source === undefined ? undefined : normalizeText(params.source, "Graph memory source", maxSourceLength);
+        const node = await mutate((state) => {
+          const existing = state.nodes.find((candidate) => candidate.kind === params.kind && candidate.label.toLocaleLowerCase() === label.toLocaleLowerCase());
+          if (existing === undefined && state.nodes.length >= nodeLimit) throw new Error(`Graph memory reached its ${nodeLimit}-node limit`);
+          const now = new Date().toISOString();
+          const next: GraphNode =
+            existing === undefined
+              ? { id: randomUUID(), kind: params.kind, label, summary, ...(source === undefined ? {} : { source }), createdAt: now, updatedAt: now }
+              : { ...existing, label, summary, ...(source === undefined ? {} : { source }), updatedAt: now };
+          state.nodes = [next, ...state.nodes.filter((candidate) => candidate.id !== next.id)];
+          return next;
+        });
+        return { content: [{ type: "text", text: `Graph memory recorded: ${node.id} [${node.kind}] ${node.label}` }], details: node };
+      },
+    });
+
+    const linkTool = defineTool({
+      name: "graph_memory_link",
+      label: "Link graph memories",
+      description: "Create one typed directed relation between two existing graph-memory nodes.",
+      promptSnippet: "link two graph memories with a typed relation",
+      parameters: Type.Object({
+        from: Type.String(),
+        to: Type.String(),
+        relation: Type.Union([
+          Type.Literal("USED_SKILL"),
+          Type.Literal("SOLVED_BY"),
+          Type.Literal("REQUIRES"),
+          Type.Literal("PATCHES"),
+          Type.Literal("CONFLICTS_WITH"),
+          Type.Literal("RELATED_TO"),
+        ]),
+      }),
+      async execute(_toolCallId, params): Promise<AgentToolResult<GraphRelation>> {
+        const from = normalizeText(params.from, "Graph relation source id", maxLabelLength);
+        const to = normalizeText(params.to, "Graph relation target id", maxLabelLength);
+        if (from === to) throw new Error("Graph memory relations require two different nodes");
+        const relation = await mutate((state) => {
+          if (!state.nodes.some((node) => node.id === from)) throw new Error(`Graph memory source node not found: ${from}`);
+          if (!state.nodes.some((node) => node.id === to)) throw new Error(`Graph memory target node not found: ${to}`);
+          const existing = state.relations.find((candidate) => candidate.from === from && candidate.to === to && candidate.relation === params.relation);
+          if (existing !== undefined) return existing;
+          if (state.relations.length >= relationLimit) throw new Error(`Graph memory reached its ${relationLimit}-relation limit`);
+          const next: GraphRelation = { id: randomUUID(), from, to, relation: params.relation, createdAt: new Date().toISOString() };
+          state.relations = [next, ...state.relations];
+          return next;
+        });
+        return {
+          content: [{ type: "text", text: `Graph relation ${relation.id} ${relation.relation}: ${relation.from} → ${relation.to}` }],
+          details: relation,
+        };
+      },
+    });
+
+    const searchTool = defineTool({
+      name: "graph_memory_search",
+      label: "Search graph memory",
+      description: "Search typed graph-memory nodes by label, summary, provenance, kind, or connected relation.",
+      promptSnippet: "search the local cross-session knowledge graph",
+      parameters: Type.Object({
+        query: Type.String(),
+        kind: Type.Optional(Type.Union([Type.Literal("task"), Type.Literal("skill"), Type.Literal("event")])),
+        limit: Type.Optional(Type.Number()),
+      }),
+      async execute(_toolCallId, params): Promise<AgentToolResult<GraphSearchReport>> {
+        await load();
+        const query = normalizeText(params.query, "Graph memory query", maxQueryLength);
+        if (query.length < 2) throw new Error(`Graph memory query must contain 2-${maxQueryLength} characters`);
+        const needle = query.toLocaleLowerCase();
+        const limit = Math.max(1, Math.min(50, Math.trunc(params.limit ?? 12)));
+        const ranked = nodes
+          .filter((node) => params.kind === undefined || node.kind === params.kind)
+          .map((node) => {
+            const label = node.label.toLocaleLowerCase();
+            const summary = node.summary.toLocaleLowerCase();
+            const source = node.source?.toLocaleLowerCase() ?? "";
+            const relationHit = relations.some((relation) => {
+              if (relation.from !== node.id && relation.to !== node.id) return false;
+              if (relation.relation.toLocaleLowerCase().includes(needle)) return true;
+              const neighborId = relation.from === node.id ? relation.to : relation.from;
+              return (
+                nodes
+                  .find((candidate) => candidate.id === neighborId)
+                  ?.label.toLocaleLowerCase()
+                  .includes(needle) ?? false
+              );
+            });
+            const score =
+              label === needle ? 100 : label.includes(needle) ? 60 : summary.includes(needle) ? 30 : source.includes(needle) || node.kind === needle ? 15 : 0;
+            return { node, score: score > 0 ? score : relationHit ? 20 : 0 };
+          })
+          .filter((match) => match.score > 0)
+          .sort((left, right) => right.score - left.score || right.node.updatedAt.localeCompare(left.node.updatedAt));
+        const matches = ranked.slice(0, limit).map((match) => match.node);
+        const matchedIds = new Set(matches.map((node) => node.id));
+        const matchedRelations = relations.filter((relation) => matchedIds.has(relation.from) || matchedIds.has(relation.to)).slice(0, limit * 4);
+        lastSearch = { query, total: ranked.length, nodes: matches, relations: matchedRelations };
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                matches.length === 0
+                  ? `No graph memories found for ${query}.`
+                  : matches.map((node) => `${node.id} [${node.kind}] ${node.label}: ${node.summary}`).join("\n"),
+            },
+          ],
+          details: lastSearch,
+        };
+      },
+    });
+
+    const forgetTool = defineTool({
+      name: "graph_memory_forget",
+      label: "Forget graph memory",
+      description: "Delete one graph-memory node and all incident relations after explicit confirmation.",
+      promptSnippet: "forget a graph memory after confirmation",
+      parameters: Type.Object({ id: Type.String(), confirm: Type.Boolean() }),
+      async execute(_toolCallId, params): Promise<AgentToolResult<{ id: string; removed: boolean; removedRelations: number }>> {
+        const id = normalizeText(params.id, "Graph memory node id", maxLabelLength);
+        if (params.confirm !== true) throw new Error("Deleting a graph memory requires confirm=true");
+        const result = await mutate((state) => {
+          const beforeNodes = state.nodes.length;
+          const beforeRelations = state.relations.length;
+          state.nodes = state.nodes.filter((node) => node.id !== id);
+          state.relations = state.relations.filter((relation) => relation.from !== id && relation.to !== id);
+          return { id, removed: state.nodes.length !== beforeNodes, removedRelations: beforeRelations - state.relations.length };
+        });
+        return {
+          content: [{ type: "text", text: result.removed ? `Graph memory deleted: ${id}` : `Graph memory not found: ${id}` }],
+          details: result,
+        };
+      },
+    });
+
+    const disposers: Array<() => void> = [];
+    try {
+      disposers.push(context.piTools.register(recordTool));
+      disposers.push(context.piTools.register(linkTool));
+      disposers.push(context.piTools.register(searchTool));
+      disposers.push(context.piTools.register(forgetTool));
+      disposers.push(
+        context.piPluginUi.register({
+          id: "graph-memory-panel",
+          pluginId: "@pi-harness/core/plugins/graph-memory",
+          title: "Graph Memory",
+          description: "显式记录任务、技能与事件关系，保留来源并跨会话查询。",
+          icon: "⌬",
+          read: async () => {
+            await load();
+            return {
+              filePath,
+              nodes: nodes.length,
+              relations: relations.length,
+              kinds: {
+                task: nodes.filter((node) => node.kind === "task").length,
+                skill: nodes.filter((node) => node.kind === "skill").length,
+                event: nodes.filter((node) => node.kind === "event").length,
+              },
+              recent: nodes.slice(0, 8),
+              recentRelations: relations.slice(0, 8).map((relation) => ({
+                ...relation,
+                fromLabel: nodes.find((node) => node.id === relation.from)?.label ?? relation.from,
+                toLabel: nodes.find((node) => node.id === relation.to)?.label ?? relation.to,
+              })),
+              lastSearch: lastSearch ?? null,
+            };
+          },
+        }),
+      );
+    } catch (error) {
+      for (const dispose of disposers.reverse()) dispose();
+      throw error;
+    }
+    context.effect(() => () => {
+      for (const dispose of disposers.reverse()) dispose();
+    });
+  },
+};

package/packages/core/src/plugins/history-compressor.ts

@@ -0,0 +1,81 @@
+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 z from "@deepseek-ai/schemastery";
+
+type CompressionState = { enabled: boolean; thresholdPercent: number; compactions: number; lastUsagePercent: number | null; lastError: string | null };
+export interface HistoryCompressorPluginConfig {
+  enabled?: boolean;
+  thresholdPercent?: number;
+}
+export const Config: z<HistoryCompressorPluginConfig> = z.object({ enabled: z.boolean().default(true), thresholdPercent: z.number().default(85) });
+
+export default {
+  name: "pi-history-compressor",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: HistoryCompressorPluginConfig) {
+    const enabled = config.enabled !== false;
+    const thresholdPercent = Math.max(1, Math.min(100, config.thresholdPercent ?? 85));
+    const state: CompressionState = { enabled, thresholdPercent, compactions: 0, lastUsagePercent: null, lastError: null };
+    let inFlight = false;
+    const runtime = () => context.get("piRuntime");
+    const compact = async (automatic: boolean): Promise<{ compacted: boolean; automatic: boolean }> => {
+      const service = runtime();
+      if (service === undefined) throw new Error("Pi runtime is not ready");
+      if (automatic && !enabled) return { compacted: false, automatic };
+      if (inFlight) return { compacted: false, automatic };
+      inFlight = true;
+      try {
+        await service.session.compact();
+        state.compactions += 1;
+        state.lastError = null;
+        return { compacted: true, automatic };
+      } catch (error) {
+        state.lastError = error instanceof Error ? error.message : String(error);
+        throw error;
+      } finally {
+        inFlight = false;
+      }
+    };
+    const inspectAndMaybeCompact = (): void => {
+      const service = runtime();
+      const usage = service?.session.getContextUsage();
+      state.lastUsagePercent = typeof usage?.percent === "number" ? usage.percent : null;
+      if (enabled && state.lastUsagePercent !== null && state.lastUsagePercent >= thresholdPercent) void compact(true).catch(() => undefined);
+    };
+    const unsubscribe = context.on("pi/session-event", (event) => {
+      if ((event as { type?: string }).type === "agent_end") inspectAndMaybeCompact();
+    });
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "compress_history",
+        label: "Compress history",
+        description: "Compact the current Pi session after explicit confirmation.",
+        promptSnippet: "compact the current conversation history",
+        parameters: Type.Object({ confirm: Type.Boolean({ description: "Must be true to compact history" }) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<{ compacted: boolean; automatic: boolean }>> {
+          if (params.confirm !== true) throw new Error("History compaction requires confirm=true");
+          const result = await compact(false);
+          return {
+            content: [{ type: "text", text: result.compacted ? "Session history compacted." : "Session compaction is already running." }],
+            details: result,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "history-compressor-panel",
+      pluginId: "@pi-harness/core/plugins/history-compressor",
+      title: "History Compressor",
+      description: "在上下文接近阈值时自动压缩历史消息。",
+      icon: "↯",
+      read: () => ({ ...state }),
+    });
+    context.effect(() => () => {
+      unsubscribe();
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};