@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/plugin-check.ts

@@ -1,15 +1,29 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
+import { opendir, readdir, stat } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { parse } from "yaml";
+import { BoundedFileSizeError, BoundedFileTypeError, readBoundedTextFile } from "../bounded-file.js";
+import { resolveExistingWorkspacePath } from "../workspace-path.js";
 
 const maxScanEntries = 50;
+const maxSourceEntries = 2_000;
+const maxSourceFiles = 500;
+const maxSourceFileBytes = 1024 * 1024;
+const maxSourceBytes = 8 * 1024 * 1024;
+const maxMetadataBytes = 1024 * 1024;
 const packageNamePattern = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
 const coreRowIds = new Set(["tools", "session", "llm", "web", "permission", "agent"]);
 const ignoredScanDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
 
+export interface PluginCheckConfig {
+  scanLimit?: number;
+}
+
+export const Config: z<PluginCheckConfig> = z.object({ scanLimit: z.number().default(maxScanEntries) });
+
 export function isPluginRepositoryName(name: string): boolean {
   return (
     name.length > 0 &&
@@ -31,6 +45,7 @@ const schemaChecks = [
   { code: "core-modification-required", label: "installation does not require changing host source" },
   { code: "no-build-script", label: "package declares a build script" },
   { code: "missing-ts-ext-imports", label: "TypeScript relative imports include extensions" },
+  { code: "source-scan-incomplete", label: "Source scan stayed within bounded resource limits" },
 ] as const;
 
 type CheckStatus = "passed" | "failed" | "warning";
@@ -44,6 +59,7 @@ export interface PluginCheckReport {
   errors: Array<{ code: string; message: string }>;
   warnings: Array<{ code: string; message: string }>;
   suggestions: string[];
+  sourceScan?: { checked: number; skipped: number; truncated: boolean };
 }
 export interface PluginCheckScanReport {
   root: string;
@@ -65,16 +81,70 @@ function asObject(value: unknown): Record<string, unknown> | undefined {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
 }
 
+async function readBoundedText(path: string): Promise<string> {
+  return readBoundedTextFile(path, maxMetadataBytes, "Plugin metadata file");
+}
+
+async function scanTypeScriptSources(sourceDir: string): Promise<{ sources: string[]; checked: number; skipped: number; truncated: boolean }> {
+  const sources: string[] = [];
+  let checked = 0;
+  let skipped = 0;
+  let entries = 0;
+  let totalBytes = 0;
+  let truncated = false;
+  const directory = await opendir(sourceDir, { recursive: true });
+  for await (const entry of directory) {
+    entries += 1;
+    if (entries > maxSourceEntries) {
+      truncated = true;
+      break;
+    }
+    if (!/\.(?:ts|tsx)$/u.test(entry.name)) continue;
+    if (!entry.isFile()) {
+      skipped += 1;
+      continue;
+    }
+    if (checked >= maxSourceFiles) {
+      skipped += 1;
+      truncated = true;
+      continue;
+    }
+    const remaining = maxSourceBytes - totalBytes;
+    if (remaining <= 0) {
+      skipped += 1;
+      truncated = true;
+      continue;
+    }
+    try {
+      const source = await readBoundedTextFile(join(entry.parentPath, entry.name), Math.min(maxSourceFileBytes, remaining), "Plugin source file");
+      sources.push(source);
+      checked += 1;
+      totalBytes += Buffer.byteLength(source, "utf8");
+    } catch (error) {
+      if (!(error instanceof BoundedFileSizeError || error instanceof BoundedFileTypeError)) throw error;
+      skipped += 1;
+      if (remaining < maxSourceFileBytes) truncated = true;
+    }
+  }
+  return { sources, checked, skipped, truncated };
+}
+
 async function checkRepository(path: string, strict: boolean): Promise<PluginCheckReport> {
   const root = resolve(path);
   const checks: Check[] = [];
   const suggestions: string[] = [];
+  let sourceScan: PluginCheckReport["sourceScan"];
   let manifest: Record<string, unknown> | undefined;
   try {
-    const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as unknown;
+    const parsed = JSON.parse(await readBoundedText(join(root, "package.json"))) as unknown;
     manifest = asObject(parsed);
-  } catch {
-    addIssue(checks, "no-manifest", "failed", "package.json is missing or invalid JSON");
+  } catch (error) {
+    addIssue(
+      checks,
+      "no-manifest",
+      "failed",
+      error instanceof BoundedFileSizeError ? "package.json exceeds the 1 MiB metadata limit" : "package.json is missing or invalid JSON",
+    );
   }
   if (manifest !== undefined) checks.push({ code: "no-manifest", status: "passed", message: "package.json is readable" });
   const packageName = typeof manifest?.name === "string" ? manifest.name : "";
@@ -93,14 +163,14 @@ async function checkRepository(path: string, strict: boolean): Promise<PluginChe
   else addIssue(checks, "no-build-script", "warning", "package has no build script");
   let readme: string;
   try {
-    readme = await readFile(join(root, "README.md"), "utf8");
+    readme = await readBoundedText(join(root, "README.md"));
   } catch {
     readme = "";
   }
   let patchSource: string | undefined;
   for (const filename of ["cordis.patch.yml", "dsh.bundle.patch"]) {
     try {
-      patchSource = await readFile(join(root, filename), "utf8");
+      patchSource = await readBoundedText(join(root, filename));
       break;
     } catch {
       // Try the next supported patch filename.
@@ -134,11 +204,15 @@ async function checkRepository(path: string, strict: boolean): Promise<PluginChe
   else checks.push({ code: "core-modification-required", status: "passed", message: "README does not require host source changes" });
   if (await isDirectory(join(root, "src"))) {
     const sourceDir = join(root, "src");
-    const files = (await readdir(sourceDir, { recursive: true })).filter((entry): entry is string => typeof entry === "string" && /\.(?:ts|tsx)$/u.test(entry));
-    const sources = await Promise.all(files.map((file) => readFile(join(sourceDir, file), "utf8")));
+    const scan = await scanTypeScriptSources(sourceDir);
+    sourceScan = { checked: scan.checked, skipped: scan.skipped, truncated: scan.truncated };
+    const { sources } = scan;
     if (sources.some((source) => /from\s+["'][.][^"']*["']/u.test(source)))
       addIssue(checks, "missing-ts-ext-imports", "warning", "a TypeScript relative import omits its file extension");
     else checks.push({ code: "missing-ts-ext-imports", status: "passed", message: "relative imports include extensions or no source files were found" });
+    if (scan.skipped > 0 || scan.truncated)
+      addIssue(checks, "source-scan-incomplete", "warning", `source scan skipped ${scan.skipped} file(s)${scan.truncated ? " and was truncated" : ""}`);
+    else checks.push({ code: "source-scan-incomplete", status: "passed", message: "source scan completed within bounded resource limits" });
   }
   const errors = checks.filter((check) => check.status === "failed").map(({ code, message }) => ({ code, message }));
   const warnings = checks.filter((check) => check.status === "warning").map(({ code, message }) => ({ code, message }));
@@ -159,6 +233,7 @@ async function checkRepository(path: string, strict: boolean): Promise<PluginChe
     errors,
     warnings,
     suggestions,
+    ...(sourceScan === undefined ? {} : { sourceScan }),
   };
 }
 
@@ -169,7 +244,8 @@ function schemaReport(): { checks: Array<{ code: string; label: string }>; verdi
 export default {
   name: "pi-plugin-check",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  apply(context: Context, config: { scanLimit?: number }) {
+  Config,
+  apply(context: Context, config: PluginCheckConfig = {}) {
     const scanLimit = Math.max(1, Math.min(maxScanEntries, Math.trunc(config.scanLimit ?? maxScanEntries)));
     let latest: PluginCheckReport | PluginCheckScanReport | ReturnType<typeof schemaReport> | undefined;
     const run = async (action: "check" | "scan" | "schema", requestedPath: string | undefined, strict: boolean): Promise<unknown> => {
@@ -177,7 +253,11 @@ export default {
         latest = schemaReport();
         return latest;
       }
-      const target = resolve(context.piHarnessLaunch.cwd, requestedPath ?? ".");
+      const requested = requestedPath ?? ".";
+      const workspaceRequest = isAbsolute(requested) ? relative(resolve(context.piHarnessLaunch.cwd), resolve(requested)) || "." : requested;
+      const target = (
+        await resolveExistingWorkspacePath(context.piHarnessLaunch.cwd, workspaceRequest, "Plugin repository path must stay inside the current workspace")
+      ).target;
       if (action === "check") {
         latest = await checkRepository(target, strict);
         return latest;
@@ -197,11 +277,15 @@ export default {
         label: "Check plugins",
         description: "Read-only health checks for Pi Harness plugin repositories; never modifies or builds the inspected path.",
         promptSnippet: "check a Pi Harness plugin repository",
-        parameters: Type.Object({
-          action: Type.Union(["check", "scan", "schema"]),
-          path: Type.Optional(Type.String({ description: "Repository path for check, parent directory for scan" })),
-          strict: Type.Optional(Type.Boolean({ description: "Treat warnings as errors" })),
-        }),
+        parameters: Type.Object(
+          {
+            action: Type.Union(["check", "scan", "schema"]),
+            path: Type.Optional(Type.String({ description: "Repository path for check, parent directory for scan" })),
+            strict: Type.Optional(Type.Boolean({ description: "Treat warnings as errors" })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
           const action = params.action;
           if (action !== "check" && action !== "scan" && action !== "schema") throw new Error("plugin_check action must be check, scan, or schema");

package/packages/core/src/plugins/plugin-dev.ts

@@ -1,45 +1,189 @@
 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 { EmptyConfig } from "../config.js";
 
-type ReloadState = { status: "idle" | "reloaded" | "failed"; reason: string; reloadedAt?: string; error?: string };
+type ReloadState = {
+  status: "idle" | "queued" | "running" | "reloaded" | "failed" | "cancelled";
+  reason: string;
+  requestedAt?: string;
+  startedAt?: string;
+  reloadedAt?: string;
+  error?: string;
+};
+
+const maxReasonLength = 1_000;
+const maxErrorLength = 2_000;
+const parameterNames = new Set(["reason"]);
+
+function reloadReason(value: unknown): string {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Plugin Dev parameters must be an object");
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  if (prototype !== Object.prototype && prototype !== null) throw new Error("Plugin Dev parameters must be a plain object");
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !parameterNames.has(key)))
+    throw new Error("Plugin Dev parameters contain an unknown property");
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("Plugin Dev parameters must use data properties");
+  const reason: unknown = descriptors.reason?.value as unknown;
+  if (reason === undefined) return "manual plugin reload";
+  if (typeof reason !== "string") throw new Error("Plugin Dev reason must be a string");
+  if (reason.length > maxReasonLength) throw new Error(`Plugin Dev reason must contain 0-${maxReasonLength} characters`);
+  if (reason.includes("\0")) throw new Error("Plugin Dev reason must not contain NUL characters");
+  return reason.trim() || "manual plugin reload";
+}
+
+function boundedError(error: unknown): string {
+  if (typeof error === "string") return error.slice(0, maxErrorLength);
+  if (error !== null && typeof error === "object") {
+    const descriptor = Object.getOwnPropertyDescriptor(error, "message");
+    if (descriptor !== undefined && "value" in descriptor && typeof descriptor.value === "string") return descriptor.value.slice(0, maxErrorLength);
+  }
+  return "Unknown plugin reload error";
+}
+
+function cancellationError(signal: AbortSignal): Error {
+  return new Error("Plugin reload wait was cancelled", { cause: signal.reason });
+}
+
+function waitForReload<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(cancellationError(signal));
+  return new Promise<T>((resolve, reject) => {
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      cleanup();
+      reject(cancellationError(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (result) => {
+        cleanup();
+        resolve(result);
+      },
+      (error: unknown) => {
+        cleanup();
+        reject(error instanceof Error ? error : new Error("Plugin reload failed with a non-Error reason", { cause: error }));
+      },
+    );
+  });
+}
 
 export default {
   name: "pi-plugin-dev",
   inject: ["piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
+    const lifecycle = new AbortController();
     let latest: ReloadState = { status: "idle", reason: "" };
+    let queued: { reason: string; requestedAt: string } | undefined;
+    let active: Promise<ReloadState> | undefined;
+    const startReload = (request: { reason: string; requestedAt: string }): Promise<ReloadState> => {
+      if (lifecycle.signal.aborted) {
+        latest = { status: "cancelled", ...request, error: "Plugin reload was cancelled before it started" };
+        return Promise.reject(cancellationError(lifecycle.signal));
+      }
+      const runtime = context.get("piRuntime") as { session: { reload(): Promise<void> } } | undefined;
+      if (runtime === undefined) {
+        const error = new Error("Pi runtime is not available; enable the runtime plugin before reloading");
+        latest = { status: "failed", ...request, error: error.message };
+        return Promise.reject(error);
+      }
+      const startedAt = new Date().toISOString();
+      latest = { status: "running", ...request, startedAt };
+      const operation = Promise.resolve()
+        .then(() => runtime.session.reload())
+        .then(
+          () => {
+            const result: ReloadState = { status: "reloaded", ...request, startedAt, reloadedAt: new Date().toISOString() };
+            latest = { ...result };
+            return result;
+          },
+          (error: unknown) => {
+            latest = { status: "failed", ...request, startedAt, error: boundedError(error) };
+            throw error;
+          },
+        );
+      active = operation;
+      void operation.then(
+        () => {
+          if (active === operation) active = undefined;
+        },
+        () => {
+          if (active === operation) active = undefined;
+        },
+      );
+      return operation;
+    };
+    const unsubscribe = context.on("pi/session-event", (event) => {
+      if (event.type !== "agent_settled" || queued === undefined) return;
+      const request = queued;
+      queued = undefined;
+      void startReload(request).catch(() => undefined);
+    });
     const unregisterTool = context.piTools.register(
       defineTool({
         name: "plugin_dev_reload",
-        label: "Reload Pi plugins",
-        description: "Reload the current Pi session so local extension and plugin changes take effect.",
-        promptSnippet: "reload the live Pi session after changing a local plugin",
-        parameters: Type.Object({ reason: Type.Optional(Type.String({ description: "Why the reload is being requested" })) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<ReloadState>> {
-          const reason = params.reason?.trim() || "manual plugin reload";
-          try {
-            const runtime = context.get("piRuntime") as { session: { reload(): Promise<void> } } | undefined;
-            if (runtime === undefined) throw new Error("Pi runtime is not available; enable the runtime plugin before reloading");
-            await runtime.session.reload();
-            latest = { status: "reloaded", reason, reloadedAt: new Date().toISOString() };
-            return { content: [{ type: "text", text: `Pi plugins reloaded: ${reason}` }], details: latest };
-          } catch (error) {
-            latest = { status: "failed", reason, error: error instanceof Error ? error.message : String(error) };
+        label: "Reload Pi session resources",
+        description: "Reload the current Pi session extensions, skills, prompts, themes, and context files after local development changes.",
+        promptSnippet: "reload live Pi session resources after local development changes",
+        parameters: Type.Object(
+          { reason: Type.Optional(Type.String({ description: "Why the reload is being requested", maxLength: maxReasonLength })) },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<ReloadState>> {
+          const reason = reloadReason(params);
+          const operationSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+          const requestedAt = new Date().toISOString();
+          if (operationSignal.aborted) {
+            latest = { status: "cancelled", reason, requestedAt, error: "Plugin reload was cancelled before it started" };
+            throw cancellationError(operationSignal);
+          }
+          if (active !== undefined || queued !== undefined) throw new Error("A plugin reload is already in progress");
+          const runtime = context.get("piRuntime") as { session: { isIdle?: boolean; reload(): Promise<void> } } | undefined;
+          if (runtime === undefined) {
+            const error = new Error("Pi runtime is not available; enable the runtime plugin before reloading");
+            latest = { status: "failed", reason, requestedAt, error: error.message };
             throw error;
           }
+          if (runtime.session.isIdle === false) {
+            queued = { reason, requestedAt };
+            latest = { status: "queued", ...queued };
+            return {
+              content: [{ type: "text", text: `Pi session resource reload queued until the current agent run settles: ${reason}` }],
+              details: { ...latest },
+            };
+          }
+          const result = await waitForReload(startReload({ reason, requestedAt }), operationSignal);
+          return { content: [{ type: "text", text: `Pi session resources reloaded: ${reason}` }], details: { ...result } };
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "plugin-dev-panel",
-      pluginId: "@pi-harness/core/plugins/plugin-dev",
-      title: "Plugin Dev",
-      description: "在本地插件改动后重载当前 Pi session。",
-      icon: "↻",
-      read: () => latest,
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "plugin-dev-panel",
+        pluginId: "@pi-harness/core/plugins/plugin-dev",
+        title: "Plugin Dev",
+        description: "在本地开发改动后安全重载当前 Pi session 的扩展、技能、提示词、主题和上下文文件。",
+        icon: "↻",
+        read: () => ({
+          ...latest,
+          limits: { reasonCharacters: maxReasonLength, errorCharacters: maxErrorLength },
+        }),
+      });
+    } catch (error) {
+      lifecycle.abort(new Error("Plugin Dev plugin activation failed", { cause: error }));
+      unsubscribe();
+      unregisterTool();
+      throw error;
+    }
     context.effect(() => () => {
+      lifecycle.abort(new Error("Plugin Dev plugin was disposed"));
+      if (queued !== undefined) {
+        latest = { status: "cancelled", ...queued, error: "Plugin reload was cancelled before it started" };
+        queued = undefined;
+      }
+      unsubscribe();
       unregisterTool();
       disposePanel();
     });

package/packages/core/src/plugins/plugin-finder.ts

@@ -6,8 +6,11 @@ import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agen
 const defaultRegistryUrl = "https://registry.npmjs.org";
 const defaultSearchKeyword = "pi-harness";
 const defaultLimit = 10;
+const defaultTimeoutMs = 15_000;
+const maxResponseBytes = 1024 * 1024;
 const maxQueryLength = 120;
 const maxKeywordLength = 64;
+const queryParameterNames = new Set(["query"]);
 
 type PluginSearchResult = { name: string; version: string; description: string; score: number; npm: string };
 type PluginSearchReport = { query: string; total: number; results: PluginSearchResult[] };
@@ -22,12 +25,14 @@ export interface PluginFinderConfig {
   registryUrl?: string;
   limit?: number;
   keyword?: string;
+  timeoutMs?: number;
 }
 
 export const Config: z<PluginFinderConfig> = z.object({
   registryUrl: z.string().default(defaultRegistryUrl),
   limit: z.number().default(defaultLimit),
   keyword: z.string().default(defaultSearchKeyword),
+  timeoutMs: z.number().default(defaultTimeoutMs),
 });
 
 function normalizeSearchKeyword(keyword: string | undefined): string {
@@ -37,6 +42,98 @@ function normalizeSearchKeyword(keyword: string | undefined): string {
   return value;
 }
 
+function queryParameter(value: unknown): string {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Plugin finder parameters must be an object");
+  let descriptors: PropertyDescriptorMap;
+  try {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) throw new Error("Plugin finder parameters must be a plain object");
+    descriptors = Object.getOwnPropertyDescriptors(value);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Plugin finder parameters must be a plain object") throw error;
+    throw new Error("Plugin finder parameters must be an accessible plain object", { cause: error });
+  }
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !queryParameterNames.has(key)))
+    throw new Error("Plugin finder parameters contain an unknown property");
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("Plugin finder parameters must use data properties");
+  const query: unknown = descriptors.query?.value;
+  if (typeof query !== "string") throw new Error("Plugin finder query must be a string");
+  return query;
+}
+
+async function cancelResponseBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel?.();
+  } catch {
+    // Response cleanup is best effort and must not hide the protocol error.
+  }
+}
+
+async function readBoundedJson(response: Response): Promise<{ total?: unknown; objects?: unknown }> {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) {
+    await cancelResponseBody(response);
+    throw new Error("Plugin registry response exceeded the 1 MiB limit");
+  }
+  if (response.body === null) throw new Error("Plugin registry 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("Plugin registry response exceeded the 1 MiB limit");
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))));
+  } catch (error) {
+    throw new Error("Plugin registry response must contain valid UTF-8", { cause: error });
+  }
+  try {
+    return JSON.parse(text) as { total?: unknown; objects?: unknown };
+  } catch (error) {
+    throw new Error(`Plugin registry returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+async function searchRegistry(url: string, timeoutMs: number, signal?: AbortSignal): Promise<{ total?: unknown; objects?: unknown }> {
+  if (signal?.aborted === true) throw new Error("Plugin 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();
+  try {
+    const response = await fetch(url, { signal: controller.signal, headers: { accept: "application/json" } });
+    if (!response.ok) {
+      await cancelResponseBody(response);
+      throw new Error(`Plugin registry returned HTTP ${response.status}`);
+    }
+    return await readBoundedJson(response);
+  } catch (error) {
+    if (timedOut) throw new Error(`Plugin search timed out after ${timeoutMs} ms`, { cause: error });
+    if (controller.signal.aborted) throw new Error("Plugin search was cancelled", { cause: error });
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", abortFromCaller);
+  }
+}
+
 export default {
   name: "pi-plugin-finder",
   inject: ["piPluginUi", "piTools"],
@@ -45,6 +142,7 @@ export default {
     const registryUrl = normalizeRegistryUrl(config.registryUrl);
     const limit = Math.max(1, Math.min(25, Math.trunc(config.limit ?? defaultLimit)));
     const keyword = normalizeSearchKeyword(config.keyword);
+    const timeoutMs = Math.max(1_000, Math.min(60_000, Math.trunc(config.timeoutMs ?? defaultTimeoutMs)));
     let latest: PluginSearchReport | undefined;
     const unregisterTool = context.piTools.register(
       defineTool({
@@ -52,16 +150,15 @@ export default {
         label: "Search plugins",
         description: "Search the configured npm registry for Pi Harness plugins. This is read-only and never installs packages.",
         promptSnippet: "search the plugin registry for an extension",
-        parameters: Type.Object({ query: Type.String({ description: "Plugin name or capability keywords" }) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<PluginSearchReport>> {
-          const query = params.query.trim();
+        parameters: Type.Object({ query: Type.String({ description: "Plugin name or capability keywords" }) }, { additionalProperties: false }),
+        executionMode: "sequential",
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<PluginSearchReport>> {
+          const query = queryParameter(params).trim();
           if (query.length < 2 || query.length > maxQueryLength) throw new Error(`Plugin search query must contain 2-${maxQueryLength} characters`);
           const search = new URLSearchParams({ text: `keywords:${keyword} ${query}`, size: String(limit) });
-          const response = await fetch(`${registryUrl}/-/v1/search?${search.toString()}`, { headers: { accept: "application/json" } });
-          if (!response.ok) throw new Error(`Plugin registry returned HTTP ${response.status}`);
-          const payload = (await response.json()) as { total?: unknown; objects?: unknown };
+          const payload = await searchRegistry(`${registryUrl}/-/v1/search?${search.toString()}`, timeoutMs, signal);
           const objects = Array.isArray(payload.objects) ? payload.objects : [];
-          const results = objects.flatMap((entry): PluginSearchResult[] => {
+          const results = objects.slice(0, limit).flatMap((entry): PluginSearchResult[] => {
             if (entry === null || typeof entry !== "object") return [];
             const item = entry as { package?: unknown; score?: unknown };
             if (item.package === null || typeof item.package !== "object") return [];
@@ -69,13 +166,14 @@ export default {
             if (typeof pkg.name !== "string" || typeof pkg.version !== "string") return [];
             const links = pkg.links !== null && typeof pkg.links === "object" ? (pkg.links as { npm?: unknown }) : {};
             const score = item.score !== null && typeof item.score === "object" ? (item.score as { final?: unknown }).final : undefined;
+            const name = pkg.name.slice(0, 256);
             return [
               {
-                name: pkg.name,
-                version: pkg.version,
-                description: typeof pkg.description === "string" ? pkg.description : "",
+                name,
+                version: pkg.version.slice(0, 128),
+                description: typeof pkg.description === "string" ? pkg.description.slice(0, 4_096) : "",
                 score: typeof score === "number" && Number.isFinite(score) ? score : 0,
-                npm: typeof links.npm === "string" ? links.npm : `${registryUrl}/${pkg.name}`,
+                npm: typeof links.npm === "string" ? links.npm.slice(0, 4_096) : `${registryUrl}/${name}`,
               },
             ];
           });
@@ -98,7 +196,16 @@ export default {
       title: "Plugin Finder",
       description: "只读搜索 npm Registry 中的 Pi Harness 插件，不会自动安装或执行未审核代码。",
       icon: "⌕",
-      read: () => ({ registryUrl, keyword, limit, query: latest?.query ?? null, total: latest?.total ?? 0, results: latest?.results ?? [] }),
+      read: () => ({
+        registryUrl,
+        keyword,
+        limit,
+        timeoutMs,
+        maxResponseBytes,
+        query: latest?.query ?? null,
+        total: latest?.total ?? 0,
+        results: latest?.results ?? [],
+      }),
     });
     context.effect(() => () => {
       unregisterTool();