@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/src/plugins/browser-fetch.ts

@@ -0,0 +1,171 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+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 maxResponseBytes = 512 * 1024;
+const maxRedirects = 3;
+const requestTimeoutMs = 20_000;
+
+type BrowserFetchResult = { url: string; finalUrl: string; status: number; contentType: string; bytes: number; truncated: boolean; text: string };
+
+function privateIpv4(address: string): boolean {
+  const octets = address.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) return true;
+  const first = octets[0] ?? -1;
+  const second = octets[1] ?? -1;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 0) ||
+    (first === 192 && second === 168) ||
+    (first === 198 && (second === 18 || second === 19)) ||
+    first >= 224
+  );
+}
+
+function privateIp(address: string): boolean {
+  if (isIP(address) === 4) return privateIpv4(address);
+  const normalized = address.toLowerCase();
+  return (
+    normalized === "::1" ||
+    normalized.startsWith("fc") ||
+    normalized.startsWith("fd") ||
+    normalized.startsWith("fe8") ||
+    normalized.startsWith("fe9") ||
+    normalized.startsWith("fea") ||
+    normalized.startsWith("feb") ||
+    normalized.startsWith("::ffff:10.") ||
+    normalized.startsWith("::ffff:192.168.") ||
+    normalized.startsWith("::ffff:127.")
+  );
+}
+
+async function validateTarget(rawUrl: string, allowPrivate: boolean): Promise<URL> {
+  if (rawUrl.length === 0 || rawUrl.length > 4096) throw new Error("Browser URL must be between 1 and 4096 characters");
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error("Browser URL is invalid");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("Browser fetch only supports http and https URLs");
+  if (url.username !== "" || url.password !== "") throw new Error("Browser URL must not contain credentials");
+  if (!allowPrivate) {
+    const addresses = await lookup(url.hostname, { all: true, verbatim: true });
+    if (addresses.some(({ address }) => privateIp(address))) throw new Error("Browser fetch blocked a private or local network target");
+  }
+  return url;
+}
+
+async function readBody(response: Response): Promise<{ bytes: number; truncated: boolean; text: string }> {
+  if (response.body === null) return { bytes: 0, truncated: false, text: "" };
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  let truncated = false;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      const chunk = next.value;
+      if (bytes + chunk.byteLength > maxResponseBytes) {
+        const remaining = maxResponseBytes - bytes;
+        if (remaining > 0) chunks.push(chunk.subarray(0, remaining));
+        bytes = maxResponseBytes;
+        truncated = true;
+        await reader.cancel();
+        break;
+      }
+      chunks.push(chunk);
+      bytes += chunk.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return { bytes, truncated, text: Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8") };
+}
+
+async function fetchPage(rawUrl: string, allowPrivate: boolean): Promise<BrowserFetchResult> {
+  let current = await validateTarget(rawUrl, allowPrivate);
+  const original = current.toString();
+  for (let redirect = 0; redirect <= maxRedirects; redirect += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+    let response: Response;
+    try {
+      response = await fetch(current, {
+        redirect: "manual",
+        signal: controller.signal,
+        headers: { accept: "text/html, text/plain, application/json;q=0.9, */*;q=0.1", "user-agent": "pi-harness-browser-fetch/0.1" },
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") throw new Error("Browser fetch timed out after 20 seconds", { cause: error });
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (location === null) throw new Error(`Browser redirect ${response.status} has no Location header`);
+      if (redirect === maxRedirects) throw new Error(`Browser fetch exceeded the ${maxRedirects}-redirect limit`);
+      current = await validateTarget(new URL(location, current).toString(), allowPrivate);
+      continue;
+    }
+    const body = await readBody(response);
+    return {
+      url: original,
+      finalUrl: current.toString(),
+      status: response.status,
+      contentType: (response.headers.get("content-type") ?? "text/plain").split(";", 1)[0]!.trim(),
+      ...body,
+    };
+  }
+  throw new Error("Browser fetch did not produce a response");
+}
+
+export interface BrowserFetchPluginConfig {
+  allowPrivate?: boolean;
+}
+
+export const Config: z<BrowserFetchPluginConfig> = z.object({ allowPrivate: z.boolean().default(false) });
+
+export default {
+  name: "pi-browser-fetch",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: BrowserFetchPluginConfig) {
+    let latest: BrowserFetchResult | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "browser_fetch",
+        label: "Browser fetch",
+        description: "Fetch a public HTTP or HTTPS page as bounded text without executing page scripts.",
+        promptSnippet: "fetch a public web page for inspection",
+        parameters: Type.Object({ url: Type.String({ description: "HTTP or HTTPS URL" }) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<BrowserFetchResult>> {
+          latest = await fetchPage(params.url, config.allowPrivate === true);
+          return { content: [{ type: "text", text: latest.text }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "browser-fetch-panel",
+      pluginId: "@pi-harness/core/plugins/browser-fetch",
+      title: "Browser Fetch",
+      description: "受限抓取公开网页文本，不执行页面脚本。",
+      icon: "◎",
+      read: () => ({ latest: latest ?? null, allowPrivate: config.allowPrivate === true, maxResponseBytes }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/browser-session.ts

@@ -0,0 +1,287 @@
+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 JsonObject = Record<string, unknown>;
+type BrowserTab = { targetId: string; title: string; url: string; type: string; webSocketDebuggerUrl?: string };
+type BrowserSessionResult = {
+  targetId: string;
+  url: string;
+  title: string;
+  status?: string;
+  truncated?: boolean;
+  text?: string;
+  clicked?: boolean;
+  screenshot?: { data: string; mimeType: string };
+};
+
+const requestTimeoutMs = 15_000;
+const maxTextBytes = 128 * 1024;
+const maxSelectorLength = 512;
+
+function endpointUrl(raw: string): URL {
+  let endpoint: URL;
+  try {
+    endpoint = new URL(raw);
+  } catch {
+    throw new Error("Browser session endpoint is invalid");
+  }
+  const host = endpoint.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (endpoint.protocol !== "http:" || (host !== "localhost" && host !== "127.0.0.1" && host !== "::1"))
+    throw new Error("Browser session endpoint must be a local http://localhost, 127.0.0.1, or ::1 address");
+  endpoint.pathname = endpoint.pathname.replace(/\/$/, "");
+  return endpoint;
+}
+
+async function tabs(endpoint: URL): Promise<BrowserTab[]> {
+  const response = await fetch(new URL("/json/list", endpoint));
+  if (!response.ok) throw new Error(`Chrome DevTools returned HTTP ${response.status}`);
+  const payload = (await response.json()) as unknown;
+  if (!Array.isArray(payload)) throw new Error("Chrome DevTools returned an invalid tab list");
+  return payload
+    .filter((tab): tab is BrowserTab => typeof tab === "object" && tab !== null && typeof (tab as JsonObject).id === "string")
+    .map((tab) => {
+      const item = tab as JsonObject;
+      return {
+        targetId: String(item.id),
+        title: typeof item.title === "string" ? item.title : "",
+        url: typeof item.url === "string" ? item.url : "",
+        type: typeof item.type === "string" ? item.type : "",
+        ...(typeof item.webSocketDebuggerUrl === "string" ? { webSocketDebuggerUrl: item.webSocketDebuggerUrl } : {}),
+      };
+    });
+}
+
+async function target(endpoint: URL, targetId: string): Promise<BrowserTab> {
+  const tab = (await tabs(endpoint)).find((item) => item.targetId === targetId);
+  if (tab === undefined) throw new Error(`Browser tab was not found: ${targetId}`);
+  if (tab.webSocketDebuggerUrl === undefined) throw new Error(`Browser tab is not debuggable: ${targetId}`);
+  return tab;
+}
+
+async function cdp(tab: BrowserTab, method: string, params?: JsonObject): Promise<JsonObject> {
+  if (tab.webSocketDebuggerUrl === undefined) throw new Error(`Browser tab is not debuggable: ${tab.targetId}`);
+  const socket = new WebSocket(tab.webSocketDebuggerUrl);
+  return new Promise((resolve, reject) => {
+    const id = 1;
+    const timer = setTimeout(() => {
+      cleanup();
+      socket.close();
+      reject(new Error(`Chrome DevTools request timed out: ${method}`));
+    }, requestTimeoutMs);
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      socket.removeEventListener("open", onOpen);
+      socket.removeEventListener("message", onMessage);
+      socket.removeEventListener("error", onError);
+      socket.removeEventListener("close", onClose);
+    };
+    const onOpen = (): void => {
+      socket.send(JSON.stringify({ id, method, ...(params === undefined ? {} : { params }) }));
+    };
+    const onMessage = (event: MessageEvent): void => {
+      let message: unknown;
+      try {
+        message = JSON.parse(typeof event.data === "string" ? event.data : String(event.data));
+      } catch {
+        return;
+      }
+      if (typeof message !== "object" || message === null || (message as JsonObject).id !== id) return;
+      cleanup();
+      socket.close();
+      const payload = message as JsonObject;
+      if (typeof payload.error === "object" && payload.error !== null) {
+        const errorMessage = (payload.error as JsonObject).message;
+        reject(new Error(typeof errorMessage === "string" ? errorMessage : "Chrome DevTools request failed"));
+      } else if (typeof payload.result === "object" && payload.result !== null) resolve(payload.result as JsonObject);
+      else reject(new Error("Chrome DevTools returned an invalid response"));
+    };
+    const onError = (): void => {
+      cleanup();
+      reject(new Error("Could not connect to the Chrome DevTools tab"));
+    };
+    const onClose = (): void => {
+      cleanup();
+      reject(new Error("Chrome DevTools tab connection closed before responding"));
+    };
+    socket.addEventListener("open", onOpen);
+    socket.addEventListener("message", onMessage);
+    socket.addEventListener("error", onError);
+    socket.addEventListener("close", onClose);
+  });
+}
+
+function resultValue(result: JsonObject): unknown {
+  const exception = result.exceptionDetails;
+  if (exception !== undefined) {
+    const exceptionText = typeof exception === "object" && exception !== null ? (exception as JsonObject).text : undefined;
+    throw new Error(typeof exceptionText === "string" ? exceptionText : "Page evaluation failed");
+  }
+  const value = result.result;
+  if (typeof value !== "object" || value === null) throw new Error("Page evaluation returned no value");
+  return (value as JsonObject).value;
+}
+
+async function ready(endpoint: URL, tab: BrowserTab): Promise<void> {
+  const deadline = Date.now() + requestTimeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const result = await cdp(tab, "Runtime.evaluate", { expression: "document.readyState", returnByValue: true });
+      if (resultValue(result) === "complete" || resultValue(result) === "interactive") return;
+    } catch {
+      // The navigation may replace the target briefly; poll until it is ready or the deadline expires.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error("Browser navigation did not become ready within 15 seconds");
+}
+
+async function evaluate(tab: BrowserTab, expression: string): Promise<unknown> {
+  const result = await cdp(tab, "Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true });
+  return resultValue(result);
+}
+
+export interface BrowserSessionPluginConfig {
+  endpoint?: string;
+}
+
+export const Config: z<BrowserSessionPluginConfig> = z.object({ endpoint: z.string().default("http://127.0.0.1:9222") });
+
+export default {
+  name: "pi-browser-session",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: BrowserSessionPluginConfig) {
+    const endpoint = endpointUrl(config.endpoint ?? "http://127.0.0.1:9222");
+    let latest: BrowserSessionResult | undefined;
+    const listTabs = async (): Promise<BrowserTab[]> => tabs(endpoint);
+    const getTab = async (targetId: string): Promise<BrowserTab> => target(endpoint, targetId);
+    const unregisterTabs = context.piTools.register(
+      defineTool({
+        name: "browser_tabs",
+        label: "Browser tabs",
+        description: "List pages in an already-running local Chrome DevTools session.",
+        promptSnippet: "list tabs in the connected local browser",
+        parameters: Type.Object({}),
+        async execute(): Promise<AgentToolResult<{ tabs: BrowserTab[] }>> {
+          const items = (await listTabs()).filter((tab) => tab.type === "page");
+          return {
+            content: [{ type: "text", text: items.map((tab) => `${tab.targetId} ${tab.title} ${tab.url}`).join("\n") || "No browser pages are open." }],
+            details: { tabs: items },
+          };
+        },
+      }),
+    );
+    const unregisterNavigate = context.piTools.register(
+      defineTool({
+        name: "browser_navigate",
+        label: "Browser navigate",
+        description: "Navigate a connected browser tab to an HTTP or HTTPS URL.",
+        promptSnippet: "navigate the connected browser tab",
+        parameters: Type.Object({ targetId: Type.String(), url: Type.String() }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<BrowserSessionResult>> {
+          const url = new URL(params.url);
+          if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("Browser navigation only supports http and https URLs");
+          const tab = await getTab(params.targetId);
+          await cdp(tab, "Page.enable");
+          await cdp(tab, "Page.navigate", { url: url.toString() });
+          await ready(endpoint, { ...tab, url: url.toString() });
+          latest = { targetId: tab.targetId, url: url.toString(), title: tab.title };
+          return { content: [{ type: "text", text: `Navigated to ${url.toString()}` }], details: { ...latest, status: "navigated" } };
+        },
+      }),
+    );
+    const unregisterRead = context.piTools.register(
+      defineTool({
+        name: "browser_read",
+        label: "Browser read",
+        description: "Read bounded visible text from a connected browser tab.",
+        promptSnippet: "read visible text from the connected browser tab",
+        parameters: Type.Object({ targetId: Type.String() }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<BrowserSessionResult>> {
+          const tab = await getTab(params.targetId);
+          const value = await evaluate(tab, "document.body?.innerText ?? ''");
+          const text = typeof value === "string" ? value : "";
+          const bytes = Buffer.byteLength(text, "utf8");
+          const bounded = Buffer.from(text, "utf8").subarray(0, maxTextBytes).toString("utf8");
+          latest = { targetId: tab.targetId, url: tab.url, title: tab.title, text: bounded };
+          return { content: [{ type: "text", text: bounded }], details: { ...latest, truncated: bytes > maxTextBytes } };
+        },
+      }),
+    );
+    const unregisterClick = context.piTools.register(
+      defineTool({
+        name: "browser_click",
+        label: "Browser click",
+        description: "Click one visible HTML element in a connected browser tab by CSS selector.",
+        promptSnippet: "click a page element in the connected browser",
+        parameters: Type.Object({ targetId: Type.String(), selector: Type.String() }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<BrowserSessionResult>> {
+          if (params.selector.length === 0 || params.selector.length > maxSelectorLength)
+            throw new Error("Browser selector must be between 1 and 512 characters");
+          const tab = await getTab(params.targetId);
+          const selector = JSON.stringify(params.selector);
+          const value = await evaluate(
+            tab,
+            `(() => { const element = document.querySelector(${selector}); if (!(element instanceof HTMLElement)) throw new Error('Element was not found'); element.click(); return true; })()`,
+          );
+          if (value !== true) throw new Error("Browser click did not complete");
+          latest = { targetId: tab.targetId, url: tab.url, title: tab.title, clicked: true };
+          return { content: [{ type: "text", text: `Clicked ${params.selector}` }], details: latest };
+        },
+      }),
+    );
+    const unregisterScreenshot = context.piTools.register(
+      defineTool({
+        name: "browser_screenshot",
+        label: "Browser screenshot",
+        description: "Capture the visible viewport of a connected browser tab as PNG.",
+        promptSnippet: "capture a screenshot of the connected browser tab",
+        parameters: Type.Object({ targetId: Type.String() }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<BrowserSessionResult>> {
+          const tab = await getTab(params.targetId);
+          const result = await cdp(tab, "Page.captureScreenshot", { format: "png" });
+          const data = typeof result.data === "string" ? result.data : "";
+          if (data === "") throw new Error("Chrome DevTools returned an empty screenshot");
+          latest = { targetId: tab.targetId, url: tab.url, title: tab.title, screenshot: { data, mimeType: "image/png" } };
+          return { content: [{ type: "image", data, mimeType: "image/png" }], details: latest };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "browser-session-panel",
+      pluginId: "@pi-harness/core/plugins/browser-session",
+      title: "Browser Session",
+      description: "通过 Chrome DevTools Protocol 连接已启动的本地浏览器。",
+      icon: "◉",
+      read: async () => {
+        try {
+          return {
+            endpoint: endpoint.toString(),
+            tabs: (await listTabs()).filter((tab) => tab.type === "page").map((tab) => ({ targetId: tab.targetId, title: tab.title, url: tab.url })),
+            latest: latest ?? null,
+            connected: true,
+            error: null,
+          };
+        } catch (error) {
+          return {
+            endpoint: endpoint.toString(),
+            tabs: [],
+            latest: latest ?? null,
+            connected: false,
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      },
+    });
+    context.effect(() => () => {
+      unregisterTabs();
+      unregisterNavigate();
+      unregisterRead();
+      unregisterClick();
+      unregisterScreenshot();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/canvas-draw.ts

@@ -0,0 +1,90 @@
+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 maxNodes = 100;
+const maxEdges = 200;
+const maxLabelLength = 256;
+const nodeIdPattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+type Direction = "TD" | "LR" | "BT" | "RL";
+type CanvasNode = { id: string; label: string };
+type CanvasEdge = { from: string; to: string; label?: string };
+type CanvasReport = { direction: Direction; nodes: CanvasNode[]; edges: CanvasEdge[]; nodeCount: number; edgeCount: number; mermaid: string };
+
+function label(value: string, field: string): string {
+  const result = value.trim();
+  if (result.length === 0 || result.length > maxLabelLength) throw new Error(`${field} must contain 1-${maxLabelLength} characters`);
+  return result;
+}
+
+function render(direction: Direction, nodes: CanvasNode[], edges: CanvasEdge[]): string {
+  const escape = (value: string): string => value.replace(/["\r\n]/g, (character) => (character === '"' ? """ : " "));
+  const lines = [`flowchart ${direction}`];
+  for (const node of nodes) lines.push(`    ${node.id}["${escape(node.label)}"]`);
+  for (const edge of edges) lines.push(`    ${edge.from} -->${edge.label === undefined ? "" : `|${escape(edge.label)}|`} ${edge.to}`);
+  return lines.join("\n");
+}
+
+export default {
+  name: "pi-canvas-draw",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: CanvasReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "canvas_draw",
+        label: "Draw canvas",
+        description: "Generate a validated Mermaid flowchart from structured nodes and edges without executing or writing files.",
+        promptSnippet: "draw a flowchart from these nodes and relationships",
+        parameters: Type.Object({
+          direction: Type.Optional(Type.Union([Type.Literal("TD"), Type.Literal("LR"), Type.Literal("BT"), Type.Literal("RL")])),
+          nodes: Type.Array(Type.Object({ id: Type.String(), label: Type.String() })),
+          edges: Type.Array(Type.Object({ from: Type.String(), to: Type.String(), label: Type.Optional(Type.String()) })),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<CanvasReport>> {
+          return Promise.resolve().then(() => {
+            const nodes = params.nodes.map((node) => ({ id: node.id.trim(), label: label(node.label, "Node label") }));
+            const edges = params.edges.map((edge) => ({
+              from: edge.from.trim(),
+              to: edge.to.trim(),
+              ...(edge.label === undefined ? {} : { label: label(edge.label, "Edge label") }),
+            }));
+            if (nodes.length === 0 || nodes.length > maxNodes) throw new Error(`Canvas must contain 1-${maxNodes} nodes`);
+            if (edges.length > maxEdges) throw new Error(`Canvas must contain at most ${maxEdges} edges`);
+            const ids = new Set<string>();
+            for (const node of nodes) {
+              if (!nodeIdPattern.test(node.id)) throw new Error(`Invalid node id: ${node.id}`);
+              if (ids.has(node.id)) throw new Error(`Duplicate node id: ${node.id}`);
+              ids.add(node.id);
+            }
+            for (const edge of edges) {
+              if (!ids.has(edge.from) || !ids.has(edge.to)) throw new Error(`Canvas edge references an unknown node: ${edge.from} -> ${edge.to}`);
+            }
+            const report: CanvasReport = {
+              direction: params.direction ?? "TD",
+              nodes,
+              edges,
+              nodeCount: nodes.length,
+              edgeCount: edges.length,
+              mermaid: render(params.direction ?? "TD", nodes, edges),
+            };
+            latest = report;
+            return { content: [{ type: "text" as const, text: report.mermaid }], details: report };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "canvas-draw-panel",
+      pluginId: "@pi-harness/core/plugins/canvas-draw",
+      title: "Canvas Draw",
+      description: "将结构化节点和边转换为可复制的 Mermaid 流程图源码。",
+      icon: "⌘",
+      read: () => ({ latest: latest ?? null, nodeCount: latest?.nodeCount ?? 0, edgeCount: latest?.edgeCount ?? 0 }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/change-verifier.ts

@@ -0,0 +1,79 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+type GateStatus = "pass" | "warning" | "fail";
+type GateReport = {
+  status: GateStatus;
+  script: string;
+  tests: { exitCode: number; durationMs: number };
+  review: { status: string; findings: number };
+  checkedAt: string;
+};
+
+function detailsOf(result: unknown): Record<string, unknown> {
+  if (result === null || typeof result !== "object") return {};
+  const details = (result as { details?: unknown }).details;
+  return details !== null && typeof details === "object" ? (details as Record<string, unknown>) : {};
+}
+
+function requiredTool(context: Context, name: string): ToolDefinition {
+  const tool = context.piTools.snapshot().customTools.find((candidate) => candidate.name === name);
+  if (tool === undefined) throw new Error(`Change Verifier requires the ${name} tool; enable its provider plugin before pi-runtime`);
+  return tool;
+}
+
+export default {
+  name: "pi-change-verifier",
+  inject: ["piPluginUi", "piTools"],
+  apply(context: Context) {
+    let runs = 0;
+    let latest: GateReport | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "verify_change_gate",
+        label: "Verify change gate",
+        description: "Combine the existing project test and Git review tools into one deterministic release gate.",
+        promptSnippet: "run the project test and review gate before declaring the change complete",
+        parameters: Type.Object({ script: Type.Optional(Type.String({ description: "Approved npm script handled by run_project_tests" })) }),
+        async execute(toolCallId, params, signal, _onUpdate, toolContext): Promise<AgentToolResult<GateReport>> {
+          const script = params.script?.trim() || "test";
+          const reviewTool = requiredTool(context, "review_changes");
+          const testTool = requiredTool(context, "run_project_tests");
+          const reviewResult = await reviewTool.execute(`${toolCallId}:review`, {}, signal, undefined, toolContext);
+          const testResult = await testTool.execute(`${toolCallId}:tests`, { script }, signal, undefined, toolContext);
+          const review = detailsOf(reviewResult);
+          const tests = detailsOf(testResult);
+          const exitCode = typeof tests.exitCode === "number" ? tests.exitCode : 1;
+          const reviewStatus = typeof review.status === "string" ? review.status : "error";
+          const findings = Array.isArray(review.findings) ? review.findings.length : 0;
+          const status: GateStatus = exitCode !== 0 || reviewStatus === "error" ? "fail" : reviewStatus === "warning" ? "warning" : "pass";
+          latest = {
+            status,
+            script,
+            tests: { exitCode, durationMs: typeof tests.durationMs === "number" ? tests.durationMs : 0 },
+            review: { status: reviewStatus, findings },
+            checkedAt: new Date().toISOString(),
+          };
+          runs += 1;
+          return {
+            content: [{ type: "text", text: `${status}: tests exit ${exitCode}; review ${reviewStatus} with ${findings} finding(s).` }],
+            details: latest,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "change-verifier-panel",
+      pluginId: "@pi-harness/core/plugins/change-verifier",
+      title: "Change Verifier",
+      description: "复用真实测试和代码审查工具，形成统一发布门禁。",
+      icon: "✓",
+      read: () => ({ runs, latest: latest ?? null }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};