@pi-harness/pi-harness 0.1.14 → 0.1.16

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

@@ -1,301 +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) {
-    await response.body?.cancel?.();
-    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();
-  }
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))));
-  } catch (error) {
-    throw new Error("Web research response must contain valid UTF-8", { cause: error });
-  }
-}
-
-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" }) }, { additionalProperties: false }),
-        executionMode: "sequential",
-        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" })),
-            },
-            { additionalProperties: false },
-          ),
-          executionMode: "sequential",
-          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,189 +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 z from "@deepseek-ai/schemastery";
-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 defaultGitTimeoutMs = 10_000;
-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, requestedTimeoutMs = defaultGitTimeoutMs): Promise<WorkspaceGitStatus> {
-  const timeoutMs = Math.max(100, Math.min(60_000, Math.trunc(requestedTimeoutMs)));
-  try {
-    const [branchResult, statusResult] = await Promise.all([
-      execFileAsync("git", ["-C", root, "branch", "--show-current"], { maxBuffer: 1024 * 1024, timeout: timeoutMs }),
-      execFileAsync("git", ["-C", root, "status", "--short", "--untracked-files=all"], { maxBuffer: 4 * 1024 * 1024, timeout: timeoutMs }),
-    ]);
-    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: [] };
-  }
-}
-
-export interface WorkspaceNavigatorPluginConfig {
-  gitTimeoutMs?: number;
-}
-
-export const Config: z<WorkspaceNavigatorPluginConfig> = z.object({ gitTimeoutMs: z.number().default(defaultGitTimeoutMs) });
-
-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 (nodes.length >= maxNodes) {
-      truncated = true;
-      return;
-    }
-    if (depth > maxDepth) {
-      try {
-        const hiddenEntries = await readdir(directory, { withFileTypes: true });
-        if (hiddenEntries.some((entry) => (entry.isDirectory() ? !ignoredDirectories.has(entry.name) : entry.isFile()))) truncated = true;
-      } catch {
-        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"],
-  Config,
-  apply(context: Context, config: WorkspaceNavigatorPluginConfig) {
-    const gitTimeoutMs = Math.max(100, Math.min(60_000, Math.trunc(config.gitTimeoutMs ?? defaultGitTimeoutMs)));
-    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" })),
-          },
-          { additionalProperties: false },
-        ),
-        executionMode: "sequential",
-        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({}, { additionalProperties: false }),
-        executionMode: "sequential",
-        async execute(): Promise<AgentToolResult<WorkspaceGitStatus>> {
-          latestGit = await readWorkspaceGitStatus(context.piHarnessLaunch.cwd, gitTimeoutMs);
-          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, gitTimeoutMs }),
-    });
-    context.effect(() => () => {
-      unregister();
-      unregisterGit();
-      disposePanel();
-    });
-  },
-};

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

@@ -1,177 +0,0 @@
-import { lstat, readdir, realpath, stat } from "node:fs/promises";
-import { isAbsolute, relative, resolve, sep } 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 { readBoundedFile } from "../bounded-file.js";
-import { EmptyConfig } from "../config.js";
-
-const maxQueryLength = 256;
-const maxPathLength = 512;
-const maxFileBytes = 2 * 1024 * 1024;
-const maxFiles = 2_000;
-const maxDirectories = 512;
-const maxDepth = 16;
-const maxResults = 100;
-const ignoredDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
-type SearchMatch = { path: string; line: number; text: string };
-type SearchReport = { query: string; path: string; matches: SearchMatch[]; matchCount: number; scannedFiles: number; skippedFiles: number; truncated: boolean };
-
-type PathSemantics = { isAbsolute(path: string): boolean; relative(from: string, to: string): string; sep: string };
-const nativePathSemantics: PathSemantics = { isAbsolute, relative, sep };
-
-export function isWorkspaceSearchPathInside(root: string, target: string, pathSemantics: PathSemantics = nativePathSemantics): boolean {
-  const remainder = pathSemantics.relative(root, target);
-  return remainder === "" || (remainder !== ".." && !remainder.startsWith(`..${pathSemantics.sep}`) && !pathSemantics.isAbsolute(remainder));
-}
-
-function workspacePath(root: string, requested: string): string {
-  if (requested.length > maxPathLength || requested.includes("\\"))
-    throw new Error("Workspace search path must be a relative POSIX path of at most 512 characters");
-  const target = resolve(root, requested || ".");
-  if (!isWorkspaceSearchPathInside(root, target)) throw new Error("Workspace search path must stay inside the current workspace");
-  return target;
-}
-
-type WalkState = { files: string[]; directories: number };
-
-async function filesUnder(target: string, root: string, state: WalkState, depth = 0): Promise<boolean> {
-  if (state.files.length >= maxFiles || state.directories >= maxDirectories || depth > maxDepth) return true;
-  const metadata = await lstat(target);
-  if (metadata.isSymbolicLink()) return false;
-  if (metadata.isFile()) {
-    state.files.push(target);
-    return false;
-  }
-  if (!metadata.isDirectory()) return false;
-  state.directories += 1;
-  if (depth >= maxDepth) return true;
-  const entries = (await readdir(target, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
-  for (const entry of entries) {
-    if (state.files.length >= maxFiles || state.directories >= maxDirectories) return true;
-    if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
-    const child = resolve(target, entry.name);
-    if (!isWorkspaceSearchPathInside(root, child)) continue;
-    if (await filesUnder(child, root, state, depth + 1)) return true;
-  }
-  return false;
-}
-
-export default {
-  name: "pi-workspace-search",
-  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  Config: EmptyConfig,
-  apply(context: Context) {
-    let latest: SearchReport | undefined;
-    const search = async (
-      query: string,
-      requestedPath: string | undefined,
-      caseSensitive: boolean,
-      requestedLimit: number | undefined,
-    ): Promise<SearchReport> => {
-      const normalizedQuery = query.trim();
-      if (normalizedQuery.length === 0 || normalizedQuery.length > maxQueryLength)
-        throw new Error(`Workspace search query must contain 1-${maxQueryLength} characters`);
-      const root = await realpath(context.piHarnessLaunch.cwd);
-      const target = workspacePath(root, requestedPath?.trim() ?? ".");
-      const targetMetadata = await stat(target);
-      const walkState: WalkState = { files: [], directories: 0 };
-      const filesTruncated = await filesUnder(target, root, walkState);
-      const files = walkState.files;
-      const limit = Math.max(1, Math.min(maxResults, Math.trunc(requestedLimit ?? maxResults)));
-      const needle = caseSensitive ? normalizedQuery : normalizedQuery.toLocaleLowerCase();
-      const matches: SearchMatch[] = [];
-      let scannedFiles = 0;
-      let skippedFiles = targetMetadata.isFile() && targetMetadata.size > maxFileBytes ? 1 : 0;
-      let stoppedAtLimit = false;
-      for (const file of files) {
-        if (matches.length >= limit) {
-          stoppedAtLimit = true;
-          break;
-        }
-        const metadata = await stat(file);
-        if (metadata.size > maxFileBytes) {
-          skippedFiles += 1;
-          continue;
-        }
-        let source: string;
-        try {
-          const bytes = await readBoundedFile(file, maxFileBytes, "Workspace search file");
-          if (bytes.includes(0)) {
-            skippedFiles += 1;
-            continue;
-          }
-          source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-        } catch {
-          skippedFiles += 1;
-          continue;
-        }
-        scannedFiles += 1;
-        const lines = source.split(/\r?\n/u);
-        for (const [index, line] of lines.entries()) {
-          if ((caseSensitive ? line : line.toLocaleLowerCase()).includes(needle)) {
-            matches.push({ path: relative(root, file), line: index + 1, text: line });
-            if (matches.length >= limit) {
-              stoppedAtLimit = true;
-              break;
-            }
-          }
-        }
-      }
-      const report: SearchReport = {
-        query: normalizedQuery,
-        path: relative(root, target) || ".",
-        matches,
-        matchCount: matches.length,
-        scannedFiles,
-        skippedFiles,
-        truncated: filesTruncated || stoppedAtLimit,
-      };
-      latest = report;
-      return report;
-    };
-    const unregisterTool = context.piTools.register(
-      defineTool({
-        name: "workspace_search",
-        label: "Search workspace",
-        description: "Search bounded UTF-8 text files in the current workspace without modifying files or invoking a shell.",
-        promptSnippet: "search the workspace for a text pattern",
-        parameters: Type.Object(
-          {
-            query: Type.String(),
-            path: Type.Optional(Type.String()),
-            caseSensitive: Type.Optional(Type.Boolean()),
-            maxResults: Type.Optional(Type.Number()),
-          },
-          { additionalProperties: false },
-        ),
-        executionMode: "sequential",
-        async execute(_toolCallId, params): Promise<AgentToolResult<SearchReport>> {
-          const report = await search(params.query, params.path, params.caseSensitive === true, params.maxResults);
-          return {
-            content: [{ type: "text", text: report.matches.map((match) => `${match.path}:${match.line}: ${match.text}`).join("\n") || "No matches found." }],
-            details: report,
-          };
-        },
-      }),
-    );
-    let disposePanel: () => void;
-    try {
-      disposePanel = context.piPluginUi.register({
-        id: "workspace-search-panel",
-        pluginId: "@pi-harness/core/plugins/workspace-search",
-        title: "Workspace Search",
-        description: "在工作区内安全检索文本，跳过依赖、构建产物和版本库目录。",
-        icon: "⌕",
-        read: () => ({ latest: latest ?? null, query: latest?.query ?? null, matchCount: latest?.matchCount ?? 0, scannedFiles: latest?.scannedFiles ?? 0 }),
-      });
-    } catch (error) {
-      unregisterTool();
-      throw error;
-    }
-    context.effect(() => () => {
-      unregisterTool();
-      disposePanel();
-    });
-  },
-};