@pi-harness/pi-harness 0.1.2 → 0.1.3

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

@@ -0,0 +1,61 @@
+import { readdir, stat, unlink } from "node:fs/promises";
+import { 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 capsuleDirectory = "capsules";
+type Capsule = { name: string; bytes: number };
+
+async function listCapsules(directory: string): Promise<Capsule[]> {
+  const names = (await readdir(directory).catch(() => [] as string[]))
+    .filter((name) => name.endsWith(".patch"))
+    .sort()
+    .reverse();
+  return Promise.all(names.map(async (name) => ({ name, bytes: (await stat(join(directory, name))).size })));
+}
+
+export default {
+  name: "pi-cleaner",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    const directory = join(context.piHarnessLaunch.agentDir, capsuleDirectory);
+    let lastRemoved = 0;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "clean_harness_artifacts",
+        label: "Clean harness artifacts",
+        description: "Remove only Pi Harness Git capsule patch files from the agent data directory. Confirmation is required.",
+        promptSnippet: "clean old Pi Harness rollback artifacts",
+        parameters: Type.Object({
+          confirm: Type.Boolean({ description: "Must be true to remove files" }),
+          keep: Type.Optional(Type.Number({ description: "Number of newest capsules to keep" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<{ removed: number; kept: number }>> {
+          if (params.confirm !== true) throw new Error("Cleaning requires confirm=true");
+          const keep = Math.max(0, Math.trunc(params.keep ?? 5));
+          const capsules = await listCapsules(directory);
+          const remove = capsules.slice(keep);
+          await Promise.all(remove.map((capsule) => unlink(join(directory, capsule.name))));
+          lastRemoved = remove.length;
+          return {
+            content: [{ type: "text", text: `Removed ${remove.length} Pi Harness capsule(s); kept ${capsules.length - remove.length}.` }],
+            details: { removed: remove.length, kept: capsules.length - remove.length },
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "cleaner-panel",
+      pluginId: "@pi-harness/core/plugins/cleaner",
+      title: "Harness Cleaner",
+      description: "清理 Pi Harness 自己生成的 Git 快照；默认不会触碰项目文件。",
+      icon: "⌫",
+      read: async () => ({ directory, capsules: await listCapsules(directory), lastRemoved }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/cli-notifier.ts

@@ -0,0 +1,125 @@
+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 maxMessageLength = 2048;
+const maxNotifications = 20;
+type Notification = { time: string; title: string; message: string; delivered: boolean; reason?: string };
+type NotificationResult = { title: string; message: string; delivered: boolean; platform: NodeJS.Platform; reason?: string };
+
+export interface CliNotifierPluginConfig {
+  enabled?: boolean;
+  title?: string;
+}
+
+export const Config: z<CliNotifierPluginConfig> = z.object({ enabled: z.boolean().default(true), title: z.string().default("Pi Harness") });
+
+function appleScriptString(value: string): string {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", " ")}"`;
+}
+
+async function deliver(title: string, message: string): Promise<NotificationResult> {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    await execFileAsync("osascript", ["-e", `display notification ${appleScriptString(message)} with title ${appleScriptString(title)}`]);
+    return { title, message, delivered: true, platform };
+  }
+  if (platform === "linux") {
+    await execFileAsync("notify-send", [title, message]);
+    return { title, message, delivered: true, platform };
+  }
+  if (platform === "win32") {
+    const script = `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; $xml = New-Object Windows.Data.Xml.Dom.XmlDocument; $xml.LoadXml('<toast><visual><binding template="ToastText02"><text id="1">${message.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}</text><text id="2">${title.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}</text></binding></visual></toast>'); [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Pi Harness').Show([Windows.UI.Notifications.ToastNotification]::new($xml))`;
+    await execFileAsync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script]);
+    return { title, message, delivered: true, platform };
+  }
+  return { title, message, delivered: false, platform, reason: "unsupported-platform" };
+}
+
+export default {
+  name: "pi-cli-notifier",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: CliNotifierPluginConfig) {
+    const enabled = config.enabled !== false;
+    const defaultTitle = config.title?.trim() || "Pi Harness";
+    const notifications: Notification[] = [];
+    const notify = async (message: string, title = defaultTitle): Promise<NotificationResult> => {
+      if (message.length === 0 || message.length > maxMessageLength)
+        throw new Error(`Notification message must be between 1 and ${maxMessageLength} characters`);
+      if (title.length === 0 || title.length > 256) throw new Error("Notification title must be between 1 and 256 characters");
+      if (!enabled) {
+        const result: NotificationResult = { title, message, delivered: false, platform: process.platform, reason: "disabled" };
+        notifications.unshift({ time: new Date().toISOString(), ...result });
+        notifications.splice(maxNotifications);
+        return result;
+      }
+      try {
+        const result = await deliver(title, message);
+        notifications.unshift({ time: new Date().toISOString(), ...result });
+        notifications.splice(maxNotifications);
+        return result;
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const result: NotificationResult = { title, message, delivered: false, platform: process.platform, reason };
+        notifications.unshift({ time: new Date().toISOString(), ...result });
+        notifications.splice(maxNotifications);
+        return result;
+      }
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "cli_notify",
+        label: "CLI notify",
+        description: "Send a local desktop notification without invoking a shell.",
+        promptSnippet: "send a desktop notification when this task finishes",
+        parameters: Type.Object({
+          message: Type.String({ description: "Notification body" }),
+          title: Type.Optional(Type.String({ description: "Notification title" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<NotificationResult>> {
+          const result = await notify(params.message, params.title ?? defaultTitle);
+          return {
+            content: [
+              { type: "text", text: result.delivered ? "Desktop notification sent." : `Desktop notification not sent: ${result.reason ?? "unknown reason"}` },
+            ],
+            details: result,
+          };
+        },
+      }),
+    );
+    const unsubscribeSession = context.on("pi/session-event", (event) => {
+      const current = event as {
+        type?: string;
+        messages?: readonly { role?: string; stopReason?: string; errorMessage?: string }[];
+        errorMessage?: string;
+      };
+      if (current.type === "agent_end") {
+        const last = current.messages?.at(-1);
+        if (last?.role === "assistant") {
+          const message = last.stopReason === "error" ? `Agent failed: ${last.errorMessage ?? "unknown error"}` : "Agent turn completed.";
+          void notify(message);
+        }
+      } else if (current.type === "compaction_end" && current.errorMessage) {
+        void notify(`Context compaction failed: ${current.errorMessage}`);
+      }
+    });
+    const disposePanel = context.piPluginUi.register({
+      id: "cli-notifier-panel",
+      pluginId: "@pi-harness/core/plugins/cli-notifier",
+      title: "CLI Notifier",
+      description: "长任务完成后发送本机桌面通知。",
+      icon: "♢",
+      read: () => ({ enabled, platform: process.platform, notifications: [...notifications] }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      unsubscribeSession();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,96 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, join, 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 maxFiles = 32;
+const maxFileBytes = 256 * 1024;
+const maxTotalBytes = 2 * 1024 * 1024;
+
+type SkillFile = { path: string; bytes: number };
+type SkillReport = { slug: string; directory: string; files: SkillFile[]; bytes: number };
+
+function slugify(name: string): string {
+  const slug = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, 64);
+  if (slug.length === 0) throw new Error("Skill name must contain at least one letter or number");
+  return slug;
+}
+
+function resolveWorkspaceFile(cwd: string, input: string): { absolute: string; display: string } {
+  if (typeof input !== "string" || input.trim() === "" || isAbsolute(input)) throw new Error("Skill files must be non-empty relative paths");
+  const absolute = resolve(cwd, input);
+  const display = relative(cwd, absolute);
+  if (display === "" || display.startsWith("..") || isAbsolute(display)) throw new Error(`Skill file must stay inside the workspace: ${input}`);
+  return { absolute, display };
+}
+
+async function createSkill(context: Context, params: { name: string; description: string; files: string[] }): Promise<SkillReport> {
+  if (!Array.isArray(params.files) || params.files.length === 0) throw new Error("At least one source file is required");
+  if (params.files.length > maxFiles) throw new Error(`A skill can include at most ${maxFiles} files`);
+  const cwd = context.piHarnessLaunch.cwd;
+  const slug = slugify(params.name);
+  const sources = params.files.map((file) => resolveWorkspaceFile(cwd, file));
+  const unique = new Set(sources.map((source) => source.display));
+  if (unique.size !== sources.length) throw new Error("Skill files must be unique");
+  let bytes = 0;
+  const files: SkillFile[] = [];
+  const output = join(cwd, ".pi", "skills", slug);
+  for (const source of sources) {
+    const content = await readFile(source.absolute);
+    if (content.byteLength > maxFileBytes) throw new Error(`Skill file exceeds ${maxFileBytes} bytes: ${source.display}`);
+    bytes += content.byteLength;
+    if (bytes > maxTotalBytes) throw new Error(`Skill sources exceed ${maxTotalBytes} bytes`);
+    const target = join(output, "references", source.display);
+    await mkdir(resolve(target, ".."), { recursive: true });
+    await writeFile(target, content);
+    files.push({ path: source.display, bytes: content.byteLength });
+  }
+  const description = params.description.trim();
+  if (description.length === 0) throw new Error("Skill description must not be empty");
+  const references = files.map((file) => `- [${file.path}](references/${file.path})`).join("\n");
+  const markdown = `---\nname: ${slug}\ndescription: ${description.replaceAll("\n", " ")}\n---\n\n# ${params.name.trim()}\n\n${description}\n\n## Reference files\n\n${references}\n`;
+  await mkdir(output, { recursive: true });
+  await writeFile(join(output, "SKILL.md"), markdown, "utf8");
+  return { slug, directory: output, files, bytes };
+}
+
+export default {
+  name: "pi-code2skill",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let generated = 0;
+    let latest: SkillReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "skill_pack_create",
+        label: "Create skill pack",
+        description: "Package selected workspace source files into a local .pi/skills skill with a manifest and references.",
+        promptSnippet: "turn selected project files into a reusable skill pack",
+        parameters: Type.Object({ name: Type.String(), description: Type.String(), files: Type.Array(Type.String()) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<SkillReport>> {
+          latest = await createSkill(context, params);
+          generated += 1;
+          return { content: [{ type: "text", text: `Skill pack created: ${latest.slug} (${latest.files.length} file(s)).` }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "code2skill-panel",
+      pluginId: "@pi-harness/core/plugins/code2skill",
+      title: "Code2Skill",
+      description: "把工作区代码打包为可复用的 Pi Skill，保留来源文件并生成 SKILL.md。",
+      icon: "✦",
+      read: () => ({ generated, latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/colleague-skill.ts

@@ -0,0 +1,122 @@
+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 customType = "pi-harness/colleague-handoff";
+const maxTextLength = 4_000;
+const maxListItems = 20;
+
+export interface ColleagueHandoffInput {
+  toRole: string;
+  objective: string;
+  context?: string;
+  constraints?: string[];
+  files?: string[];
+  acceptance?: string[];
+}
+
+export interface ColleagueHandoff {
+  id: string;
+  toRole: string;
+  objective: string;
+  context: string;
+  constraints: string[];
+  files: string[];
+  acceptance: string[];
+  createdAt: string;
+}
+
+function boundedText(value: string | undefined, field: string): string {
+  const text = value?.trim() ?? "";
+  if (text.length > maxTextLength) throw new Error(`${field} must be ${maxTextLength} characters or fewer`);
+  return text;
+}
+
+function boundedList(values: string[] | undefined, field: string): string[] {
+  const list = values ?? [];
+  if (list.length > maxListItems) throw new Error(`${field} must contain ${maxListItems} items or fewer`);
+  return list.map((value) => boundedText(value, `${field} item`)).filter(Boolean);
+}
+
+export function createColleagueHandoff(input: ColleagueHandoffInput, id: string, createdAt: string): ColleagueHandoff {
+  const toRole = boundedText(input.toRole, "toRole");
+  const objective = boundedText(input.objective, "objective");
+  if (!toRole) throw new Error("toRole is required");
+  if (!objective) throw new Error("objective is required");
+  return {
+    id,
+    toRole,
+    objective,
+    context: boundedText(input.context, "context"),
+    constraints: boundedList(input.constraints, "constraints"),
+    files: boundedList(input.files, "files"),
+    acceptance: boundedList(input.acceptance, "acceptance"),
+    createdAt,
+  };
+}
+
+function readLatest(context: Context): ColleagueHandoff | undefined {
+  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 || entry.data === null || typeof entry.data !== "object") return undefined;
+  const value = entry.data as Partial<ColleagueHandoff>;
+  if (typeof value.id !== "string" || typeof value.toRole !== "string" || typeof value.objective !== "string" || typeof value.createdAt !== "string")
+    return undefined;
+  return {
+    id: value.id,
+    toRole: value.toRole,
+    objective: value.objective,
+    context: typeof value.context === "string" ? value.context : "",
+    constraints: Array.isArray(value.constraints) ? value.constraints.filter((item): item is string => typeof item === "string") : [],
+    files: Array.isArray(value.files) ? value.files.filter((item): item is string => typeof item === "string") : [],
+    acceptance: Array.isArray(value.acceptance) ? value.acceptance.filter((item): item is string => typeof item === "string") : [],
+    createdAt: value.createdAt,
+  };
+}
+
+export default {
+  name: "pi-colleague-skill",
+  inject: ["piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest = readLatest(context);
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "colleague_handoff",
+        label: "Colleague handoff",
+        description: "Create a durable, structured handoff packet for another role without starting a hidden agent or sending external messages.",
+        promptSnippet: "prepare a structured handoff for a colleague role",
+        parameters: Type.Object({
+          toRole: Type.String({ description: "Receiving role, for example reviewer or frontend" }),
+          objective: Type.String({ description: "The concrete outcome the colleague should deliver" }),
+          context: Type.Optional(Type.String()),
+          constraints: Type.Optional(Type.Array(Type.String())),
+          files: Type.Optional(Type.Array(Type.String())),
+          acceptance: Type.Optional(Type.Array(Type.String())),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<ColleagueHandoff>> {
+          return Promise.resolve().then(() => {
+            const handoff = createColleagueHandoff(params, `handoff-${Date.now()}`, new Date().toISOString());
+            context.piSession.manager.appendCustomEntry(customType, handoff);
+            latest = handoff;
+            return {
+              content: [{ type: "text" as const, text: `Handoff ${handoff.id} prepared for ${handoff.toRole}.` }],
+              details: handoff,
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "colleague-skill-panel",
+      pluginId: "@pi-harness/core/plugins/colleague-skill",
+      title: "Colleague Skill",
+      description: "把任务、上下文、约束和验收条件整理成可追踪的角色交接包。",
+      icon: "⇄",
+      read: () => ({ latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/context-doctor.ts

@@ -0,0 +1,117 @@
+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";
+
+type ContextDoctorReport = {
+  status: "ok" | "warning";
+  usagePercent: number | null;
+  tokens: number | null;
+  contextWindow: number | null;
+  messageCount: number;
+  oversizedMessages: number;
+  toolErrors: number;
+  recommendations: string[];
+};
+
+export interface ContextDoctorPluginConfig {
+  warnPercent?: number;
+  maxMessageBytes?: number;
+}
+
+export const Config: z<ContextDoctorPluginConfig> = z.object({ warnPercent: z.number().default(75), maxMessageBytes: z.number().default(64 * 1024) });
+
+function byteLength(value: unknown): number {
+  try {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+  } catch {
+    return 0;
+  }
+}
+
+export function inspectMessages(
+  messages: readonly unknown[],
+  usage: { percent?: number | null; tokens?: number | null; contextWindow?: number | null } | undefined,
+  warnPercent: number,
+  maxMessageBytes: number,
+): ContextDoctorReport {
+  const oversizedMessages = messages.filter((message) => byteLength(message) > maxMessageBytes).length;
+  const toolErrors = messages.filter(
+    (message) =>
+      typeof message === "object" &&
+      message !== null &&
+      (message as Record<string, unknown>).role === "toolResult" &&
+      (message as Record<string, unknown>).isError === true,
+  ).length;
+  const usagePercent = typeof usage?.percent === "number" ? usage.percent : null;
+  const recommendations: string[] = [];
+  if (usagePercent !== null && usagePercent >= warnPercent) recommendations.push("压缩较早的会话历史，释放上下文空间。");
+  if (oversizedMessages > 0) recommendations.push(`检查 ${oversizedMessages} 条超大消息，优先引用摘要或文件路径。`);
+  if (toolErrors > 0) recommendations.push(`处理 ${toolErrors} 个工具错误后再继续长任务。`);
+  return {
+    status: recommendations.length === 0 ? "ok" : "warning",
+    usagePercent,
+    tokens: typeof usage?.tokens === "number" ? usage.tokens : null,
+    contextWindow: typeof usage?.contextWindow === "number" ? usage.contextWindow : null,
+    messageCount: messages.length,
+    oversizedMessages,
+    toolErrors,
+    recommendations,
+  };
+}
+
+export default {
+  name: "pi-context-doctor",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: ContextDoctorPluginConfig) {
+    const warnPercent = Math.max(1, Math.min(100, config.warnPercent ?? 75));
+    const maxMessageBytes = Math.max(1024, Math.min(1024 * 1024, Math.trunc(config.maxMessageBytes ?? 64 * 1024)));
+    const runtime = () => context.get("piRuntime");
+    const report = (): ContextDoctorReport => {
+      const service = runtime();
+      if (service === undefined) return inspectMessages([], undefined, warnPercent, maxMessageBytes);
+      return inspectMessages(service.session.messages, service.session.getContextUsage(), warnPercent, maxMessageBytes);
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "context_doctor",
+        label: "Context doctor",
+        description: "Audit context pressure, oversized messages, and tool errors; optionally compact after confirmation.",
+        promptSnippet: "audit context pressure and recommend safe cleanup",
+        parameters: Type.Object({
+          compact: Type.Optional(Type.Boolean({ description: "Compact the session after the audit" })),
+          confirm: Type.Optional(Type.Boolean({ description: "Must be true when compact is requested" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<ContextDoctorReport & { compacted: boolean }>> {
+          if (params.compact === true && params.confirm !== true) throw new Error("Context compaction requires confirm=true");
+          const service = runtime();
+          if (service === undefined) throw new Error("Pi runtime is not ready");
+          if (params.compact === true) await service.session.compact();
+          const details = { ...report(), compacted: params.compact === true };
+          return {
+            content: [
+              {
+                type: "text",
+                text: `${details.status}: ${details.messageCount} messages, ${details.oversizedMessages} oversized, ${details.toolErrors} tool errors.`,
+              },
+            ],
+            details,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "context-doctor-panel",
+      pluginId: "@pi-harness/core/plugins/context-doctor",
+      title: "Context Doctor",
+      description: "审计上下文压力、超大消息和工具错误，并给出压缩建议。",
+      icon: "⌁",
+      read: report,
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,102 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+type RuntimeEvent = AgentSessionEvent & { readonly type?: string };
+type MessageRole = "user" | "assistant" | "toolResult" | "system" | "other";
+type ContextComposition = Record<MessageRole, number>;
+type ContextInsightReport = {
+  tokens: number | null;
+  contextWindow: number | null;
+  percent: number | null;
+  messages: number;
+  events: number;
+  compactions: number;
+  composition: ContextComposition;
+  eventTypes: Record<string, number>;
+  recentEvents: { type: string; at: number }[];
+};
+
+function messageRole(message: unknown): MessageRole {
+  if (typeof message !== "object" || message === null) return "other";
+  const role = (message as { role?: unknown }).role;
+  if (role === "user" || role === "assistant" || role === "toolResult" || role === "system") return role;
+  return "other";
+}
+
+export default {
+  name: "pi-context",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let eventCount = 0;
+    let compactionCount = 0;
+    const eventTypes = new Map<string, number>();
+    const recentEvents: { type: string; at: number }[] = [];
+    const onEvent = (event: RuntimeEvent) => {
+      eventCount += 1;
+      const type = event.type ?? "unknown";
+      eventTypes.set(type, (eventTypes.get(type) ?? 0) + 1);
+      recentEvents.push({ type, at: Date.now() });
+      if (recentEvents.length > 50) recentEvents.shift();
+      if (type.startsWith("compaction_")) compactionCount += 1;
+    };
+    const unsubscribe = context.on("pi/session-event", onEvent);
+    const report = (): ContextInsightReport => {
+      const runtime = context.get("piRuntime");
+      if (runtime === undefined) {
+        return {
+          tokens: null,
+          contextWindow: null,
+          percent: null,
+          messages: 0,
+          events: eventCount,
+          compactions: compactionCount,
+          composition: { user: 0, assistant: 0, toolResult: 0, system: 0, other: 0 },
+          eventTypes: Object.fromEntries(eventTypes),
+          recentEvents: recentEvents.map((event) => ({ ...event })),
+        };
+      }
+      const usage = runtime.session.getContextUsage();
+      const composition: ContextComposition = { user: 0, assistant: 0, toolResult: 0, system: 0, other: 0 };
+      for (const message of runtime.session.messages) composition[messageRole(message)] += 1;
+      return {
+        tokens: usage?.tokens ?? null,
+        contextWindow: usage?.contextWindow ?? null,
+        percent: usage?.percent ?? null,
+        messages: runtime.session.messages.length,
+        events: eventCount,
+        compactions: compactionCount,
+        composition,
+        eventTypes: Object.fromEntries(eventTypes),
+        recentEvents: recentEvents.map((event) => ({ ...event })),
+      };
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "context_inspect",
+        label: "Context inspect",
+        description: "Inspect current context usage, message composition, and recent lifecycle events.",
+        promptSnippet: "inspect the current context composition and recent events",
+        parameters: Type.Object({}),
+        execute(): Promise<AgentToolResult<ContextInsightReport>> {
+          const details = report();
+          return Promise.resolve({ content: [{ type: "text", text: `${details.messages} messages, ${details.events} context events.` }], details });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "context-insight-panel",
+      pluginId: "@pi-harness/core/plugins/context",
+      title: "上下文洞察",
+      description: "查看当前上下文占用、消息规模和压缩事件。",
+      icon: "◒",
+      read: report,
+    });
+    context.effect(() => () => {
+      unsubscribe();
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};