@pi-harness/pi-harness 0.1.13 → 0.1.15

package/packages/core/src/plugins/vision-toolkit.ts

@@ -1,153 +0,0 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { extname, resolve } from "node:path";
-import type { Context } from "@deepseek-ai/cordis";
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
-import { resolveExistingWorkspacePath } from "../workspace-path.js";
-
-const maxImages = 100;
-const maxImageBytes = 20 * 1024 * 1024;
-const mimeByExtension: Readonly<Record<string, string>> = {
-  ".gif": "image/gif",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".png": "image/png",
-  ".webp": "image/webp",
-};
-const skippedDirectories = new Set([".git", "node_modules"]);
-
-export interface VisionAsset {
-  path: string;
-  mimeType: string;
-  bytes: number;
-  width: number | null;
-  height: number | null;
-}
-
-function dimensions(data: Buffer, mimeType: string): { width: number; height: number } | undefined {
-  if (mimeType === "image/png" && data.length >= 24 && data.subarray(0, 8).equals(Buffer.from("\x89PNG\r\n\x1a\n", "binary")))
-    return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
-  if (mimeType === "image/gif" && data.length >= 10 && data.subarray(0, 3).toString("ascii") === "GIF")
-    return { width: data.readUInt16LE(6), height: data.readUInt16LE(8) };
-  if (mimeType === "image/webp" && data.length >= 30 && data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP") {
-    const chunk = data.subarray(12, 16).toString("ascii");
-    if (chunk === "VP8X") return { width: 1 + data.readUIntLE(24, 3), height: 1 + data.readUIntLE(27, 3) };
-  }
-  if (mimeType !== "image/jpeg" || data.length < 4 || data.readUInt16BE(0) !== 0xffd8) return undefined;
-  let offset = 2;
-  while (offset + 9 < data.length) {
-    if (data[offset] !== 0xff) {
-      offset += 1;
-      continue;
-    }
-    const marker = data[offset + 1] ?? 0;
-    offset += 2;
-    if (marker === 0xd8 || marker === 0xd9) continue;
-    if (offset + 2 > data.length) return undefined;
-    const segmentLength = data.readUInt16BE(offset);
-    if (segmentLength < 2 || offset + segmentLength > data.length) return undefined;
-    const isSof =
-      (marker >= 0xc0 && marker <= 0xc3) || (marker >= 0xc5 && marker <= 0xc7) || (marker >= 0xc9 && marker <= 0xcb) || (marker >= 0xcd && marker <= 0xcf);
-    if (isSof && segmentLength >= 7) return { width: data.readUInt16BE(offset + 5), height: data.readUInt16BE(offset + 3) };
-    offset += segmentLength;
-  }
-  return undefined;
-}
-
-async function imagePath(root: string, requested: string): Promise<{ absolute: string; relativePath: string }> {
-  const resolved = await resolveExistingWorkspacePath(root, requested, "Image path must stay inside the workspace");
-  const mimeType = mimeByExtension[extname(resolved.target).toLowerCase()];
-  if (mimeType === undefined) throw new Error("Unsupported image type; use png, jpeg, gif, or webp");
-  return { absolute: resolved.target, relativePath: resolved.relativePath };
-}
-
-export async function imageInfo(root: string, requested: string): Promise<VisionAsset> {
-  const { absolute, relativePath } = await imagePath(root, requested);
-  const mimeType = mimeByExtension[extname(absolute).toLowerCase()]!;
-  const metadata = await stat(absolute);
-  if (!metadata.isFile()) throw new Error("Image path is not a file");
-  if (metadata.size > maxImageBytes) throw new Error("Image exceeds the 20 MiB inspection limit");
-  const data = await readFile(absolute);
-  const size = dimensions(data, mimeType);
-  return { path: relativePath, mimeType, bytes: metadata.size, width: size?.width ?? null, height: size?.height ?? null };
-}
-
-async function walkImages(root: string, directory: string, prefix: string, output: VisionAsset[]): Promise<void> {
-  if (output.length >= maxImages) return;
-  const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
-  for (const entry of entries) {
-    if (output.length >= maxImages) return;
-    if (entry.isDirectory() && !skippedDirectories.has(entry.name)) {
-      await walkImages(root, resolve(directory, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name, output);
-      continue;
-    }
-    if (!entry.isFile() || mimeByExtension[extname(entry.name).toLowerCase()] === undefined) continue;
-    const item = await imageInfo(root, prefix ? `${prefix}/${entry.name}` : entry.name);
-    output.push(item);
-  }
-}
-
-export async function catalogImages(root: string): Promise<VisionAsset[]> {
-  const output: VisionAsset[] = [];
-  await walkImages(resolve(root), resolve(root), "", output);
-  return output;
-}
-
-export default {
-  name: "pi-vision-toolkit",
-  inject: ["piHarnessLaunch", "piTools", "piPluginUi"],
-  apply(context: Context) {
-    let latest: { root: string; assets: VisionAsset[] } = { root: context.piHarnessLaunch.cwd, assets: [] };
-    const unregisterCatalog = context.piTools.register(
-      defineTool({
-        name: "vision_catalog",
-        label: "Vision catalog",
-        description: "List local workspace images with safe relative paths, MIME types, byte sizes, and dimensions.",
-        promptSnippet: "catalog the images in the current workspace",
-        parameters: Type.Object({}),
-        async execute(): Promise<AgentToolResult<{ root: string; assets: VisionAsset[] }>> {
-          latest = { root: context.piHarnessLaunch.cwd, assets: await catalogImages(context.piHarnessLaunch.cwd) };
-          return {
-            content: [
-              {
-                type: "text",
-                text: latest.assets.map((asset) => `${asset.path} ${asset.width ?? "?"}x${asset.height ?? "?"}`).join("\n") || "No supported images found.",
-              },
-            ],
-            details: latest,
-          };
-        },
-      }),
-    );
-    const unregisterInfo = context.piTools.register(
-      defineTool({
-        name: "vision_image_info",
-        label: "Image info",
-        description: "Inspect one workspace image without exposing its contents or reading outside the workspace.",
-        promptSnippet: "inspect the dimensions and type of a local image",
-        parameters: Type.Object({ path: Type.String({ description: "Image path relative to the workspace" }) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<VisionAsset>> {
-          const asset = await imageInfo(context.piHarnessLaunch.cwd, params.path);
-          latest = { root: context.piHarnessLaunch.cwd, assets: [asset] };
-          return {
-            content: [{ type: "text", text: `${asset.path}: ${asset.mimeType}, ${asset.bytes} bytes, ${asset.width ?? "?"}x${asset.height ?? "?"}` }],
-            details: asset,
-          };
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "vision-toolkit-panel",
-      pluginId: "@pi-harness/core/plugins/vision-toolkit",
-      title: "视觉素材",
-      description: "盘点工作区图片的类型、尺寸和大小，再交由视觉模型分析内容。",
-      icon: "◉",
-      read: () => ({ root: latest.root, count: latest.assets.length, assets: [...latest.assets] }),
-    });
-    context.effect(() => () => {
-      unregisterCatalog();
-      unregisterInfo();
-      disposePanel();
-    });
-  },
-};

package/packages/core/src/plugins/web-research.ts

@@ -1,289 +0,0 @@
-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 defaultBaseUrl = "https://api.firecrawl.dev";
-const maxQueryLength = 500;
-const maxResponseBytes = 1024 * 1024;
-
-type WebSearchItem = { title: string; url: string; snippet: string; source: string; publishedAt?: string };
-type WebSearchReport = {
-  query: string;
-  source: "firecrawl";
-  status: "ok" | "degraded";
-  summary: string;
-  items: WebSearchItem[];
-  uncertainty: string[];
-  durationMs: number;
-};
-
-interface FirecrawlPayload {
-  success?: unknown;
-  data?: { web?: unknown };
-}
-
-function normalizeBaseUrl(value: string | undefined): string {
-  let url: URL;
-  try {
-    url = new URL((value ?? defaultBaseUrl).trim());
-  } catch {
-    throw new Error("Web research base URL is invalid");
-  }
-  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("Web research base URL must use http or https");
-  if (url.username !== "" || url.password !== "") throw new Error("Web research base URL must not contain credentials");
-  return url.toString().replace(/\/+$/u, "");
-}
-
-function boundedInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number {
-  const normalized = Math.trunc(value ?? fallback);
-  if (!Number.isFinite(normalized)) return fallback;
-  return Math.max(minimum, Math.min(maximum, normalized));
-}
-
-function stringValue(value: unknown, maxLength: number): string {
-  return typeof value === "string" ? value.trim().slice(0, maxLength) : "";
-}
-
-function httpUrl(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  try {
-    const url = new URL(value);
-    if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
-    return url.toString();
-  } catch {
-    return undefined;
-  }
-}
-
-function normalizeSearchItems(payload: FirecrawlPayload, limit: number): WebSearchItem[] {
-  if (payload.data === undefined || payload.data === null || typeof payload.data !== "object" || !Array.isArray(payload.data.web)) return [];
-  return payload.data.web.slice(0, limit).flatMap((entry): WebSearchItem[] => {
-    if (entry === null || typeof entry !== "object") return [];
-    const item = entry as { title?: unknown; url?: unknown; description?: unknown; publishedDate?: unknown };
-    const url = httpUrl(item.url);
-    if (url === undefined) return [];
-    return [
-      {
-        title: stringValue(item.title, 500) || url,
-        url,
-        snippet: stringValue(item.description, 4_000),
-        source: new URL(url).hostname,
-        ...(stringValue(item.publishedDate, 100) === "" ? {} : { publishedAt: stringValue(item.publishedDate, 100) }),
-      },
-    ];
-  });
-}
-
-async function readBoundedText(response: Response): Promise<string> {
-  const declaredLength = Number(response.headers.get("content-length"));
-  if (Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) throw new Error("Web research response exceeded the 1 MiB limit");
-  if (response.body === null) throw new Error("Web research returned an empty response");
-  const reader = response.body.getReader();
-  const chunks: Uint8Array[] = [];
-  let bytes = 0;
-  try {
-    while (true) {
-      const next = await reader.read();
-      if (next.done) break;
-      bytes += next.value.byteLength;
-      if (bytes > maxResponseBytes) {
-        await reader.cancel();
-        throw new Error("Web research response exceeded the 1 MiB limit");
-      }
-      chunks.push(next.value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
-}
-
-async function readBoundedJson(response: Response): Promise<FirecrawlPayload> {
-  const text = await readBoundedText(response);
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    throw new Error("Web research returned invalid JSON");
-  }
-  if (parsed === null || typeof parsed !== "object") throw new Error("Web research returned an invalid payload");
-  return parsed;
-}
-
-function redactSecret(value: string, secret: string): string {
-  return secret === "" ? value : value.split(secret).join("[REDACTED]");
-}
-
-function sanitizedCause(error: unknown, secret: string): Error {
-  const message = redactSecret(error instanceof Error ? error.message : String(error), secret);
-  if (!(error instanceof Error)) return new Error(message);
-  const sanitized = new Error(message);
-  sanitized.name = error.name;
-  if (error.stack !== undefined) sanitized.stack = redactSecret(error.stack, secret);
-  return sanitized;
-}
-
-function searchError(message: string, cause: Error): Error {
-  return new Error(message, { cause });
-}
-
-function validateApiKeyTransport(baseUrl: string, apiKey: string): void {
-  if (apiKey === "") return;
-  const url = new URL(baseUrl);
-  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
-  if (url.protocol !== "https:" && !loopback) throw new Error("Web research requires HTTPS when an API key is configured");
-}
-
-export interface WebResearchPluginConfig {
-  baseUrl?: string;
-  apiKey?: string;
-  maxResults?: number;
-  timeoutMs?: number;
-}
-
-export const Config: z<WebResearchPluginConfig> = z.object({
-  baseUrl: z.string().default(defaultBaseUrl),
-  apiKey: z.string().default(""),
-  maxResults: z.number().default(8),
-  timeoutMs: z.number().default(20_000),
-});
-
-export default {
-  name: "pi-web-research",
-  inject: ["piPluginUi", "piTools"],
-  Config,
-  apply(context: Context, config: WebResearchPluginConfig) {
-    const baseUrl = normalizeBaseUrl(config.baseUrl);
-    const apiKey = config.apiKey?.trim() || process.env.FIRECRAWL_API_KEY?.trim() || "";
-    validateApiKeyTransport(baseUrl, apiKey);
-    const maxResults = boundedInteger(config.maxResults, 8, 1, 20);
-    const timeoutMs = boundedInteger(config.timeoutMs, 20_000, 1_000, 120_000);
-    let latest: WebSearchReport | undefined;
-    const unregisterSearch = context.piTools.register(
-      defineTool({
-        name: "web_search",
-        label: "Web search",
-        description: "Search the public web and return bounded, structured source evidence with direct URLs.",
-        promptSnippet: "search the public web for current source evidence",
-        parameters: Type.Object({ query: Type.String({ description: "Search query" }) }),
-        async execute(_toolCallId, params, signal): Promise<AgentToolResult<WebSearchReport>> {
-          const query = params.query.trim();
-          if (query.length < 2 || query.length > maxQueryLength) throw new Error(`Web search query must contain 2-${maxQueryLength} characters`);
-          if (signal?.aborted === true) throw new Error("Web search was cancelled");
-          const controller = new AbortController();
-          let timedOut = false;
-          const abortFromCaller = (): void => controller.abort(signal?.reason);
-          signal?.addEventListener("abort", abortFromCaller, { once: true });
-          const timer = setTimeout(() => {
-            timedOut = true;
-            controller.abort();
-          }, timeoutMs);
-          timer.unref();
-          const startedAt = Date.now();
-          try {
-            const response = await fetch(`${baseUrl}/v2/search`, {
-              method: "POST",
-              signal: controller.signal,
-              headers: { "content-type": "application/json", ...(apiKey === "" ? {} : { authorization: `Bearer ${apiKey}` }) },
-              body: JSON.stringify({ query, limit: maxResults, sources: ["web"], timeout: timeoutMs }),
-            });
-            if (!response.ok) {
-              const detail = redactSecret((await readBoundedText(response)).trim().slice(0, 1_000), apiKey);
-              throw new Error(`Web search returned HTTP ${response.status}${detail === "" ? "" : `: ${detail}`}`);
-            }
-            const payload = await readBoundedJson(response);
-            const items = normalizeSearchItems(payload, maxResults);
-            const status = payload.success === false || items.length === 0 ? "degraded" : "ok";
-            latest = {
-              query,
-              source: "firecrawl",
-              status,
-              summary:
-                items.length === 0
-                  ? `No web results found for ${query}.`
-                  : `Found ${items.length} ranked web result${items.length === 1 ? "" : "s"} for ${query}.`,
-              items,
-              uncertainty: items.length === 0 ? ["The provider returned no usable public HTTP or HTTPS results."] : [],
-              durationMs: Date.now() - startedAt,
-            };
-            return {
-              content: [
-                {
-                  type: "text",
-                  text:
-                    items.length === 0
-                      ? latest.summary
-                      : items.map((item, index) => `[${index + 1}] ${item.title}\n${item.url}${item.snippet === "" ? "" : `\n${item.snippet}`}`).join("\n\n"),
-                },
-              ],
-              details: latest,
-            };
-          } catch (error) {
-            const cause = sanitizedCause(error, apiKey);
-            if (timedOut) throw searchError(`Web search timed out after ${timeoutMs} ms`, cause);
-            if (controller.signal.aborted) throw searchError("Web search was cancelled", cause);
-            if (cause.message.startsWith("Web search returned") || cause.message.startsWith("Web research")) throw searchError(cause.message, cause);
-            throw searchError(`Web search request failed: ${cause.message}`, cause);
-          } finally {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", abortFromCaller);
-          }
-        },
-      }),
-    );
-    let unregisterRead: (() => void) | undefined;
-    let disposePanel: (() => void) | undefined;
-    try {
-      unregisterRead = context.piTools.register(
-        defineTool({
-          name: "read_page",
-          label: "Read page",
-          description: "Read a public page with the existing bounded browser fetch tool, optionally recording a research focus.",
-          promptSnippet: "read one public source page for focused evidence",
-          parameters: Type.Object({
-            url: Type.String({ description: "Public HTTP or HTTPS page URL" }),
-            focus: Type.Optional(Type.String({ description: "Question or topic to focus on while reading" })),
-          }),
-          async execute(toolCallId, params, signal, onUpdate, toolContext) {
-            const browserFetch = context.piTools.snapshot().customTools.find((tool) => tool.name === "browser_fetch");
-            if (browserFetch === undefined) throw new Error("read_page requires the Browser Fetch plugin to be enabled");
-            const result = await browserFetch.execute(toolCallId, { url: params.url }, signal, onUpdate, toolContext);
-            return {
-              ...result,
-              details: {
-                ...(result.details !== null && typeof result.details === "object" ? result.details : {}),
-                focus: params.focus?.trim() || null,
-              },
-            };
-          },
-        }),
-      );
-      disposePanel = context.piPluginUi.register({
-        id: "web-research-panel",
-        pluginId: "@pi-harness/core/plugins/web-research",
-        title: "Web Research",
-        description: "搜索公开网页并返回带直达链接的结构化证据；单页读取复用 Browser Fetch。",
-        icon: "⌕",
-        read: () => ({
-          source: "firecrawl",
-          keyless: apiKey === "",
-          maxResults,
-          timeoutMs,
-          readPageAvailable: context.piTools.snapshot().customTools.some((tool) => tool.name === "browser_fetch"),
-          latest: latest ?? null,
-        }),
-      });
-    } catch (error) {
-      disposePanel?.();
-      unregisterRead?.();
-      unregisterSearch();
-      throw error;
-    }
-    context.effect(() => () => {
-      unregisterSearch();
-      unregisterRead?.();
-      disposePanel?.();
-    });
-  },
-};

package/packages/core/src/plugins/workspace-navigator.ts

@@ -1,164 +0,0 @@
-import { lstat, readdir } from "node:fs/promises";
-import { execFile } from "node:child_process";
-import { relative, resolve } 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";
-import { resolveExistingWorkspacePath } from "../workspace-path.js";
-
-const maxDepthLimit = 8;
-const maxNodesLimit = 500;
-const ignoredDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
-
-export type WorkspaceNode = { kind: "directory" | "file"; name: string; path: string; depth: number };
-export type WorkspaceNodeOptions = { maxDepth?: number; maxNodes?: number };
-export type WorkspaceNodeReport = { nodes: WorkspaceNode[]; directoryCount: number; fileCount: number; truncated: boolean };
-export type WorkspaceGitStatusEntry = { path: string; status: string };
-export type WorkspaceGitStatus = { available: boolean; branch: string | null; clean: boolean; entries: WorkspaceGitStatusEntry[] };
-
-const execFileAsync = promisify(execFile);
-
-export async function readWorkspaceGitStatus(root: string): Promise<WorkspaceGitStatus> {
-  try {
-    const [branchResult, statusResult] = await Promise.all([
-      execFileAsync("git", ["-C", root, "branch", "--show-current"], { maxBuffer: 1024 * 1024 }),
-      execFileAsync("git", ["-C", root, "status", "--short", "--untracked-files=all"], { maxBuffer: 4 * 1024 * 1024 }),
-    ]);
-    const entries = statusResult.stdout
-      .split("\n")
-      .filter((line) => line.length >= 4)
-      .map((line) => ({ status: line.slice(0, 2), path: line.slice(3) }));
-    return { available: true, branch: branchResult.stdout.trim() || null, clean: entries.length === 0, entries };
-  } catch {
-    return { available: false, branch: null, clean: false, entries: [] };
-  }
-}
-
-function normalizeOptions(options: WorkspaceNodeOptions): { maxDepth: number; maxNodes: number } {
-  return {
-    maxDepth: Math.max(1, Math.min(maxDepthLimit, Math.trunc(options.maxDepth ?? 4))),
-    maxNodes: Math.max(1, Math.min(maxNodesLimit, Math.trunc(options.maxNodes ?? 200))),
-  };
-}
-
-export async function listWorkspaceNodes(root: string, options: WorkspaceNodeOptions = {}): Promise<WorkspaceNodeReport> {
-  const workspace = resolve(root);
-  const { maxDepth, maxNodes } = normalizeOptions(options);
-  const nodes: WorkspaceNode[] = [];
-  let truncated = false;
-  const visit = async (directory: string, depth: number): Promise<void> => {
-    if (depth > maxDepth || nodes.length >= maxNodes) {
-      if (nodes.length >= maxNodes) truncated = true;
-      return;
-    }
-    const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
-    for (const entry of entries) {
-      if (nodes.length >= maxNodes) {
-        truncated = true;
-        return;
-      }
-      if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
-      const target = resolve(directory, entry.name);
-      if (!relative(workspace, target) || relative(workspace, target).startsWith(`..${"/"}`)) continue;
-      const metadata = await lstat(target);
-      if (metadata.isSymbolicLink()) continue;
-      const path = relative(workspace, target);
-      if (metadata.isDirectory()) {
-        nodes.push({ kind: "directory", name: entry.name, path, depth });
-        await visit(target, depth + 1);
-      } else if (metadata.isFile()) {
-        nodes.push({ kind: "file", name: entry.name, path, depth });
-      }
-    }
-  };
-  await visit(workspace, 1);
-  return {
-    nodes,
-    directoryCount: nodes.filter((node) => node.kind === "directory").length,
-    fileCount: nodes.filter((node) => node.kind === "file").length,
-    truncated,
-  };
-}
-
-export default {
-  name: "pi-workspace-navigator",
-  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  apply(context: Context) {
-    let latest: (WorkspaceNodeReport & { path: string; maxDepth: number; maxNodes: number }) | undefined;
-    let latestGit: WorkspaceGitStatus | undefined;
-    const inspect = async (requestedPath: string | undefined, requestedDepth: number | undefined, requestedNodes: number | undefined) => {
-      const requested = requestedPath?.trim() ?? ".";
-      if (requested.length > 512 || requested.includes("\\"))
-        throw new Error("Workspace navigator path must be a relative POSIX path of at most 512 characters");
-      const resolved = await resolveExistingWorkspacePath(
-        context.piHarnessLaunch.cwd,
-        requested,
-        "Workspace navigator path must stay inside the current workspace",
-      );
-      const root = resolved.root;
-      const target = resolved.target;
-      const options = normalizeOptions({
-        ...(requestedDepth === undefined ? {} : { maxDepth: requestedDepth }),
-        ...(requestedNodes === undefined ? {} : { maxNodes: requestedNodes }),
-      });
-      const report = await listWorkspaceNodes(target, options);
-      latest = { ...report, path: relative(root, target) || ".", ...options };
-      return latest;
-    };
-    const unregister = context.piTools.register(
-      defineTool({
-        name: "workspace_tree",
-        label: "Workspace tree",
-        description: "Show a bounded, read-only workspace tree while skipping dependency and build directories.",
-        promptSnippet: "inspect the workspace directory tree",
-        parameters: Type.Object({
-          path: Type.Optional(Type.String({ description: "Relative directory path" })),
-          maxDepth: Type.Optional(Type.Number({ description: "Tree depth, 1-8" })),
-          maxNodes: Type.Optional(Type.Number({ description: "Maximum nodes, 1-500" })),
-        }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<WorkspaceNodeReport & { path: string; maxDepth: number; maxNodes: number }>> {
-          const report = await inspect(params.path, params.maxDepth, params.maxNodes);
-          return {
-            content: [
-              {
-                type: "text",
-                text: report.nodes.map((node) => `${node.kind === "directory" ? "[dir]" : "[file]"} ${node.path}`).join("\n") || "Workspace is empty.",
-              },
-            ],
-            details: report,
-          };
-        },
-      }),
-    );
-    const unregisterGit = context.piTools.register(
-      defineTool({
-        name: "workspace_status",
-        label: "Workspace status",
-        description: "Show the current workspace Git branch and changed files without modifying the repository.",
-        promptSnippet: "inspect the workspace Git status",
-        parameters: Type.Object({}),
-        async execute(): Promise<AgentToolResult<WorkspaceGitStatus>> {
-          latestGit = await readWorkspaceGitStatus(context.piHarnessLaunch.cwd);
-          const summary = latestGit.available
-            ? `${latestGit.branch ?? "detached HEAD"}: ${latestGit.clean ? "clean" : `${latestGit.entries.length} changed file(s)`}`
-            : "Not a Git workspace.";
-          return { content: [{ type: "text", text: summary }], details: latestGit };
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "workspace-navigator-panel",
-      pluginId: "@pi-harness/core/plugins/workspace-navigator",
-      title: "Workspace Navigator",
-      description: "以受限目录树快速浏览当前工作区，不执行写操作。",
-      icon: "⌘",
-      read: () => ({ latest: latest ?? null, git: latestGit ?? null, nodeCount: latest?.nodes.length ?? 0 }),
-    });
-    context.effect(() => () => {
-      unregister();
-      unregisterGit();
-      disposePanel();
-    });
-  },
-};