@pi-harness/pi-harness 0.1.13 → 0.1.14

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

@@ -1,19 +1,29 @@
 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 defaultApiUrl = "https://api.github.com";
 const defaultLimit = 10;
+const defaultTimeoutMs = 15_000;
 const maxLimit = 25;
 const maxQueryLength = 80;
 const maxResponseBytes = 1024 * 1024;
 const radarTopics = ["topic:dsh-plugin", "topic:deepseek-harness"];
+const queryParameterNames = new Set(["query"]);
 
 export interface PluginRadarConfig {
   apiUrl?: string;
   limit?: number;
+  timeoutMs?: number;
 }
 
+export const Config: z<PluginRadarConfig> = z.object({
+  apiUrl: z.string().default(defaultApiUrl),
+  limit: z.number().default(defaultLimit),
+  timeoutMs: z.number().default(defaultTimeoutMs),
+});
+
 export interface PluginRadarResult {
   name: string;
   fullName: string;
@@ -45,6 +55,26 @@ function normalizeQuery(value: string): string {
   return query;
 }
 
+function queryParameter(value: unknown): string {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Plugin radar 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 radar parameters must be a plain object");
+    descriptors = Object.getOwnPropertyDescriptors(value);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Plugin radar parameters must be a plain object") throw error;
+    throw new Error("Plugin radar 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 radar parameters contain an unknown property");
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("Plugin radar parameters must use data properties");
+  const query: unknown = descriptors.query?.value;
+  if (query === undefined) return "";
+  if (typeof query !== "string") throw new Error("Plugin radar query must be a string");
+  return query;
+}
+
 function clampLimit(value: number | undefined): number {
   return Math.max(1, Math.min(maxLimit, Math.trunc(value ?? defaultLimit)));
 }
@@ -94,8 +124,35 @@ function parseResults(payload: unknown): { total: number; results: PluginRadarRe
 }
 
 async function readJson(response: Response): Promise<unknown> {
-  const body = await response.text();
-  if (new TextEncoder().encode(body).byteLength > maxResponseBytes) throw new Error("GitHub plugin radar response exceeded 1 MiB limit");
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) {
+    await response.body?.cancel?.();
+    throw new Error("GitHub plugin radar response exceeded 1 MiB limit");
+  }
+  if (response.body === null) throw new Error("GitHub plugin radar 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("GitHub plugin radar response exceeded 1 MiB limit");
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  let body: string;
+  try {
+    body = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))));
+  } catch (error) {
+    throw new Error("GitHub plugin radar response must contain valid UTF-8", { cause: error });
+  }
   try {
     return JSON.parse(body) as unknown;
   } catch (error) {
@@ -103,25 +160,46 @@ async function readJson(response: Response): Promise<unknown> {
   }
 }
 
-async function searchPlugins(apiUrl: string, limit: number, rawQuery: string, signal?: AbortSignal): Promise<PluginRadarReport> {
+async function searchPlugins(apiUrl: string, limit: number, timeoutMs: number, rawQuery: string, signal?: AbortSignal): Promise<PluginRadarReport> {
   const query = normalizeQuery(rawQuery);
+  if (signal?.aborted === true) throw new Error("Plugin radar request was cancelled", { cause: signal.reason });
+  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 keyword = query.replaceAll('"', "");
-  const batches = await Promise.all(
-    radarTopics.map(async (topic) => {
-      const search = new URLSearchParams({
-        q: keyword === "" ? topic : `${topic} "${keyword}"`,
-        sort: "stars",
-        order: "desc",
-        per_page: String(limit),
-      });
-      const response = await fetch(`${apiUrl}/search/repositories?${search.toString()}`, {
-        headers: { accept: "application/vnd.github+json", "user-agent": "pi-harness-plugin-radar", "x-github-api-version": "2022-11-28" },
-        ...(signal === undefined ? {} : { signal }),
-      });
-      if (!response.ok) throw new Error(`GitHub plugin radar returned HTTP ${response.status}`);
-      return parseResults(await readJson(response)).results;
-    }),
-  );
+  let batches: PluginRadarResult[][];
+  try {
+    batches = await Promise.all(
+      radarTopics.map(async (topic) => {
+        const search = new URLSearchParams({
+          q: keyword === "" ? topic : `${topic} "${keyword}"`,
+          sort: "stars",
+          order: "desc",
+          per_page: String(limit),
+        });
+        const response = await fetch(`${apiUrl}/search/repositories?${search.toString()}`, {
+          headers: { accept: "application/vnd.github+json", "user-agent": "pi-harness-plugin-radar", "x-github-api-version": "2022-11-28" },
+          signal: controller.signal,
+        });
+        if (!response.ok) throw new Error(`GitHub plugin radar returned HTTP ${response.status}`);
+        return parseResults(await readJson(response)).results;
+      }),
+    );
+  } catch (error) {
+    if (timedOut) throw new Error(`Plugin radar request timed out after ${timeoutMs} ms`, { cause: error });
+    if (controller.signal.aborted) throw new Error("Plugin radar request was cancelled", { cause: error });
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", abortFromCaller);
+    controller.abort();
+  }
   const unique = new Map<string, PluginRadarResult>();
   for (const item of batches.flat()) {
     const current = unique.get(item.fullName);
@@ -134,9 +212,11 @@ async function searchPlugins(apiUrl: string, limit: number, rawQuery: string, si
 export default {
   name: "pi-plugin-radar",
   inject: ["piPluginUi", "piTools"],
+  Config,
   apply(context: Context, config: PluginRadarConfig) {
     const apiUrl = normalizeApiUrl(config.apiUrl);
     const limit = clampLimit(config.limit);
+    const timeoutMs = Math.max(1_000, Math.min(60_000, Math.trunc(config.timeoutMs ?? defaultTimeoutMs)));
     let latest: PluginRadarReport | undefined;
     const unregisterTool = context.piTools.register(
       defineTool({
@@ -144,33 +224,44 @@ export default {
         label: "Search DSH plugins",
         description: "Search GitHub for DSH and DeepSeek Harness plugins, sorted by stars. Read-only; never installs packages.",
         promptSnippet: "find popular DSH plugins on GitHub",
-        parameters: Type.Object({
-          query: Type.Optional(Type.String({ description: "Capability or repository keywords; empty searches the full DSH ecosystem" })),
-        }),
+        parameters: Type.Object(
+          {
+            query: Type.Optional(Type.String({ description: "Capability or repository keywords; empty searches the full DSH ecosystem" })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params, signal): Promise<AgentToolResult<PluginRadarReport>> {
-          latest = await searchPlugins(apiUrl, limit, params.query ?? "", signal);
+          latest = await searchPlugins(apiUrl, limit, timeoutMs, queryParameter(params), signal);
           const text =
             latest.results.length === 0 ? "No DSH plugins found." : latest.results.map((item) => `${item.fullName} (${item.stars} stars)`).join("\n");
           return { content: [{ type: "text", text }], details: latest };
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "plugin-radar-panel",
-      pluginId: "@pi-harness/core/plugins/plugin-radar",
-      title: "Plugin Radar",
-      description: "只读发现 GitHub 上的 DSH 插件，按 Star 排序，不会自动安装代码。",
-      icon: "⌁",
-      read: () => ({
-        apiUrl,
-        limit,
-        query: latest?.query ?? null,
-        total: latest?.total ?? 0,
-        fetchedAt: latest?.fetchedAt ?? null,
-        sources: latest?.sources ?? [...radarTopics],
-        results: latest?.results ?? [],
-      }),
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "plugin-radar-panel",
+        pluginId: "@pi-harness/core/plugins/plugin-radar",
+        title: "Plugin Radar",
+        description: "只读发现 GitHub 上的 DSH 插件，按 Star 排序，不会自动安装代码。",
+        icon: "⌁",
+        read: () => ({
+          apiUrl,
+          limit,
+          timeoutMs,
+          query: latest?.query ?? null,
+          total: latest?.total ?? 0,
+          fetchedAt: latest?.fetchedAt ?? null,
+          sources: latest?.sources ?? [...radarTopics],
+          results: latest?.results ?? [],
+        }),
+      });
+    } catch (error) {
+      unregisterTool();
+      throw error;
+    }
     context.effect(() => () => {
       unregisterTool();
       disposePanel();

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

@@ -7,6 +7,10 @@ const defaultSourceUrl = "https://raw.githubusercontent.com/ywsldxk/dsh-plugin-s
 const maxResponseBytes = 2 * 1024 * 1024;
 const maxQueryLength = 120;
 const maxLimit = 50;
+const maxSourceUrlLength = 2_048;
+const maxInventoryItems = 1_000;
+const maxPanelItems = 20;
+const queryParameterNames = new Set(["query"]);
 
 export interface PluginStarsEntry {
   id: string;
@@ -32,62 +36,137 @@ export interface PluginStarsReport {
 }
 
 function record(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+  try {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")) return undefined;
+    const output = Object.create(null) as Record<string, unknown>;
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (!("value" in descriptor)) return undefined;
+      output[key] = descriptor.value;
+    }
+    return output;
+  } catch {
+    return undefined;
+  }
+}
+
+function queryParameter(value: unknown): string {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Plugin stars 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 stars parameters must be a plain object");
+    descriptors = Object.getOwnPropertyDescriptors(value);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Plugin stars parameters must be a plain object") throw error;
+    throw new Error("Plugin stars 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 stars parameters contain an unknown property");
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("Plugin stars parameters must use data properties");
+  const query: unknown = descriptors.query?.value as unknown;
+  if (query === undefined) return "";
+  if (typeof query !== "string") throw new Error("Plugin stars query must be a string");
+  const normalized = query.trim();
+  if (normalized.length > maxQueryLength) throw new Error(`Plugin stars query must contain 0-${maxQueryLength} characters`);
+  return normalized;
 }
 
-function text(value: unknown): string {
-  return typeof value === "string" ? value.trim() : "";
+function entryText(value: unknown, index: number, field: string, maximum: number, required = false): string {
+  if (typeof value !== "string") throw new Error(`Plugin stars plugin ${index} ${field} must be a string`);
+  const normalized = value.trim();
+  if (required && normalized === "") throw new Error(`Plugin stars plugin ${index} ${field} must not be empty`);
+  if (normalized.length > maximum) throw new Error(`Plugin stars plugin ${index} ${field} cannot exceed ${maximum} characters`);
+  if (normalized.includes("\0")) throw new Error(`Plugin stars plugin ${index} ${field} must not contain NUL characters`);
+  return normalized;
 }
 
-function nonNegativeInteger(value: unknown): number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : -1;
+function entryTopics(value: unknown, index: number): string[] {
+  if (!Array.isArray(value)) throw new Error(`Plugin stars plugin ${index} topics must be an array`);
+  if (value.length > 24) throw new Error(`Plugin stars plugin ${index} topics cannot exceed 24 items`);
+  return value.map((topic, topicIndex) => entryText(topic, index, `topic ${topicIndex + 1}`, 64, true));
 }
 
-function topics(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value
-        .filter((item): item is string => typeof item === "string" && item.trim() !== "")
-        .map((item) => item.trim())
-        .slice(0, 24)
-    : [];
+function isIsoTimestamp(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u.test(value)) return false;
+  const parsed = new Date(value);
+  return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 19) === value.slice(0, 19);
 }
 
-function normalizedEntry(value: unknown): PluginStarsEntry | undefined {
+function normalizedEntry(value: unknown, index: number): PluginStarsEntry {
   const item = record(value);
-  if (item === undefined) return undefined;
-  const id = text(item.id);
-  const name = text(item.name);
-  const fullName = text(item.fullName);
-  const htmlUrl = text(item.htmlUrl);
-  const stars = nonNegativeInteger(item.stars);
-  if (id === "" || name === "" || !/^[^/\s]+\/[^/\s]+$/u.test(fullName) || !/^https:\/\/github\.com\//iu.test(htmlUrl) || stars < 0) return undefined;
-  const homepage = text(item.homepage);
-  const npmName = text(item.npmName);
-  const license = text(item.license);
+  if (item === undefined) throw new Error(`Plugin stars plugin ${index} must be an object`);
+  const id = entryText(item.id, index, "ID", 64, true);
+  const name = entryText(item.name, index, "name", 256, true);
+  const fullName = entryText(item.fullName, index, "fullName", 512, true);
+  if (!/^[^/\s]+\/[^/\s]+$/u.test(fullName)) throw new Error(`Plugin stars plugin ${index} fullName must be an owner/repository pair`);
+  const htmlUrl = entryText(item.htmlUrl, index, "repository URL", 4_096, true);
+  let repositoryUrl: URL;
+  try {
+    repositoryUrl = new URL(htmlUrl);
+  } catch {
+    throw new Error(`Plugin stars plugin ${index} repository URL is invalid`);
+  }
+  const repositoryPath = repositoryUrl.pathname.replace(/\/$/u, "");
+  if (
+    repositoryUrl.protocol !== "https:" ||
+    repositoryUrl.hostname.toLowerCase() !== "github.com" ||
+    repositoryUrl.port !== "" ||
+    repositoryUrl.username !== "" ||
+    repositoryUrl.password !== "" ||
+    repositoryUrl.search !== "" ||
+    repositoryUrl.hash !== "" ||
+    repositoryPath.toLowerCase() !== `/${fullName}`.toLowerCase()
+  )
+    throw new Error(`Plugin stars plugin ${index} repository URL must be an uncredentialed GitHub URL matching fullName`);
+  if (typeof item.stars !== "number" || !Number.isSafeInteger(item.stars) || item.stars < 0)
+    throw new Error(`Plugin stars plugin ${index} stars must be a non-negative safe integer`);
+  const stars = item.stars;
+  const updatedAt = entryText(item.updatedAt, index, "updatedAt", 64, true);
+  if (!isIsoTimestamp(updatedAt)) throw new Error(`Plugin stars plugin ${index} updatedAt must be an ISO timestamp`);
+  const homepage = item.homepage === undefined ? "" : entryText(item.homepage, index, "homepage", 4_096);
+  const npmName = item.npmName === undefined ? "" : entryText(item.npmName, index, "npmName", 256);
+  const license = item.license === undefined ? "" : entryText(item.license, index, "license", 64);
   return {
     id,
     name,
     fullName,
-    description: text(item.description),
+    description: item.description === undefined ? "" : entryText(item.description, index, "description", 4_096),
     htmlUrl,
     ...(homepage === "" ? {} : { homepage }),
     ...(npmName === "" ? {} : { npmName }),
     stars,
-    updatedAt: text(item.updatedAt),
+    updatedAt,
     ...(license === "" ? {} : { license }),
-    topics: topics(item.topics),
+    topics: entryTopics(item.topics, index),
   };
 }
 
 export function parsePluginStarsPayload(payload: unknown): { source: string; generatedAt: string; plugins: PluginStarsEntry[] } {
   const root = record(payload);
-  const plugins = Array.isArray(root?.plugins)
-    ? root.plugins.flatMap((item) => {
-        const entry = normalizedEntry(item);
-        return entry === undefined ? [] : [entry];
-      })
-    : [];
-  return { source: text(root?.source) || "dsh-plugin-stars", generatedAt: text(root?.generatedAt), plugins };
+  if (root === undefined || !Array.isArray(root.plugins)) throw new Error("Plugin stars ranking must be an object with a plugins array");
+  if (typeof root.source !== "string") throw new Error("Plugin stars source must be a string");
+  const source = root.source.trim();
+  if (source === "" || source.length > 256) throw new Error("Plugin stars source must contain 1-256 characters");
+  if (source.includes("\0")) throw new Error("Plugin stars source must not contain NUL characters");
+  if (typeof root.generatedAt !== "string") throw new Error("Plugin stars generatedAt must be a string");
+  const generatedAt = root.generatedAt.trim();
+  if (generatedAt.length > 64 || !isIsoTimestamp(generatedAt))
+    throw new Error("Plugin stars generatedAt must be a valid ISO timestamp of at most 64 characters");
+  if (root.plugins.length > maxInventoryItems) throw new Error(`Plugin stars inventory cannot exceed ${maxInventoryItems} plugins`);
+  const plugins = root.plugins.map((item, index) => normalizedEntry(item, index + 1));
+  const ids = new Set<string>();
+  const repositories = new Set<string>();
+  for (const plugin of plugins) {
+    const repository = plugin.fullName.toLowerCase();
+    if (ids.has(plugin.id) || repositories.has(repository)) throw new Error(`Plugin stars ranking contains a duplicate plugin: ${plugin.fullName}`);
+    ids.add(plugin.id);
+    repositories.add(repository);
+  }
+  return { source, generatedAt, plugins };
 }
 
 export function searchPluginStars(report: { plugins: readonly PluginStarsEntry[] }, query = ""): PluginStarsEntry[] {
@@ -101,6 +180,7 @@ export function searchPluginStars(report: { plugins: readonly PluginStarsEntry[]
 }
 
 function sourceUrl(raw: string): string {
+  if (raw.length === 0 || raw.length > maxSourceUrlLength) throw new Error(`Plugin stars source URL must contain 1-${maxSourceUrlLength} characters`);
   let url: URL;
   try {
     url = new URL(raw.trim());
@@ -108,33 +188,85 @@ function sourceUrl(raw: string): string {
     throw new Error("Plugin stars source URL is invalid");
   }
   if (url.protocol !== "https:" || url.username !== "" || url.password !== "") throw new Error("Plugin stars source URL must be HTTPS without credentials");
+  if (url.hostname.toLowerCase() !== "raw.githubusercontent.com" || url.port !== "")
+    throw new Error("Plugin stars source URL must use https://raw.githubusercontent.com");
   return url.toString();
 }
 
+async function cancelResponseBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel?.();
+  } catch {
+    // Cleanup is best effort while preserving the original protocol error.
+  }
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) {
+    await cancelResponseBody(response);
+    throw new Error("Plugin stars source exceeded the 2 MiB limit");
+  }
+  if (response.body === null) throw new Error("Plugin stars source 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 stars source exceeded the 2 MiB limit");
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  let body: string;
+  try {
+    body = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))));
+  } catch (error) {
+    throw new Error("Plugin stars source must contain valid UTF-8", { cause: error });
+  }
+  try {
+    return JSON.parse(body) as unknown;
+  } catch (error) {
+    throw new Error(`Plugin stars source returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
 async function fetchReport(
   url: string,
   timeoutMs: number,
   signal?: AbortSignal,
 ): Promise<{ source: string; generatedAt: string; plugins: PluginStarsEntry[] }> {
+  if (signal?.aborted === true) throw new Error("Plugin stars request was cancelled", { cause: signal.reason });
   const controller = new AbortController();
+  let timedOut = false;
   const onAbort = (): void => controller.abort(signal?.reason);
   signal?.addEventListener("abort", onAbort, { once: true });
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  timer.unref();
   try {
-    const response = await fetch(url, { signal: controller.signal, headers: { accept: "application/json", "user-agent": "pi-harness-plugin-stars" } });
-    if (!response.ok) throw new Error(`Plugin stars source returned HTTP ${response.status}`);
-    const body = await response.text();
-    if (Buffer.byteLength(body, "utf8") > maxResponseBytes) throw new Error("Plugin stars source exceeded the 2 MiB limit");
-    let payload: unknown;
-    try {
-      payload = JSON.parse(body) as unknown;
-    } catch (error) {
-      throw new Error(`Plugin stars source returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    const response = await fetch(url, {
+      signal: controller.signal,
+      redirect: "error",
+      headers: { accept: "application/json", "user-agent": "pi-harness-plugin-stars" },
+    });
+    if (!response.ok) {
+      await cancelResponseBody(response);
+      throw new Error(`Plugin stars source returned HTTP ${response.status}`);
     }
-    return parsePluginStarsPayload(payload);
+    return parsePluginStarsPayload(await readBoundedJson(response));
   } catch (error) {
-    if (controller.signal.aborted)
-      throw new Error(signal?.aborted ? "Plugin stars request was cancelled" : `Plugin stars request timed out after ${timeoutMs} ms`, { cause: error });
+    if (timedOut) throw new Error(`Plugin stars request timed out after ${timeoutMs} ms`, { cause: error });
+    if (controller.signal.aborted) throw new Error("Plugin stars request was cancelled", { cause: error });
     throw error;
   } finally {
     clearTimeout(timer);
@@ -149,9 +281,9 @@ export interface PluginStarsConfig {
 }
 
 export const Config: z<PluginStarsConfig> = z.object({
-  sourceUrl: z.string().default(defaultSourceUrl),
-  limit: z.number().default(10),
-  timeoutMs: z.number().default(15_000),
+  sourceUrl: z.string().min(1).max(maxSourceUrlLength).default(defaultSourceUrl),
+  limit: z.number().min(1).max(maxLimit).step(1).default(10),
+  timeoutMs: z.number().min(1_000).max(60_000).step(1).default(15_000),
 });
 
 export default {
@@ -162,42 +294,82 @@ export default {
     const source = sourceUrl(config.sourceUrl ?? defaultSourceUrl);
     const limit = Math.max(1, Math.min(maxLimit, Math.trunc(config.limit ?? 10)));
     const timeoutMs = Math.max(1_000, Math.min(60_000, Math.trunc(config.timeoutMs ?? 15_000)));
+    const lifecycle = new AbortController();
+    const executionSignal = (signal?: AbortSignal): AbortSignal => (signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]));
     let latest: PluginStarsReport | undefined;
-    const unregister = context.piTools.register(
-      defineTool({
-        name: "plugin_stars_search",
-        label: "Plugin Stars",
-        description: "Read the curated DSH Plugin Stars ranking, filter it locally, and return sorted repository evidence. Never installs plugins.",
-        promptSnippet: "search the curated DSH plugin ranking",
-        parameters: Type.Object({ query: Type.Optional(Type.String({ description: "Plugin name, repository, capability, or topic" })) }),
-        async execute(_toolCallId, params, signal): Promise<AgentToolResult<PluginStarsReport>> {
-          const payload = await fetchReport(source, timeoutMs, signal);
-          const query = params.query?.trim() ?? "";
-          const results = searchPluginStars(payload, query).slice(0, limit);
-          latest = { source: payload.source, generatedAt: payload.generatedAt, total: results.length, query, results, fetchedAt: new Date().toISOString() };
+    let unregister: () => void = () => undefined;
+    let disposePanel: () => void = () => undefined;
+    try {
+      unregister = context.piTools.register(
+        defineTool({
+          name: "plugin_stars_search",
+          label: "Plugin Stars",
+          description: "Read the curated DSH Plugin Stars ranking, filter it locally, and return sorted repository evidence. Never installs plugins.",
+          promptSnippet: "search the curated DSH plugin ranking",
+          parameters: Type.Object(
+            {
+              query: Type.Optional(Type.String({ description: "Plugin name, repository, capability, or topic", maxLength: maxQueryLength })),
+            },
+            { additionalProperties: false },
+          ),
+          executionMode: "sequential",
+          async execute(_toolCallId, params, signal): Promise<AgentToolResult<PluginStarsReport>> {
+            const query = queryParameter(params);
+            const payload = await fetchReport(source, timeoutMs, executionSignal(signal));
+            const matches = searchPluginStars(payload, query);
+            const results = matches.slice(0, limit);
+            latest = { source: payload.source, generatedAt: payload.generatedAt, total: matches.length, query, results, fetchedAt: new Date().toISOString() };
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    results.map((entry, index) => `${index + 1}. ${entry.fullName} · ${entry.stars} stars\n${entry.htmlUrl}`).join("\n\n") ||
+                    "No ranked plugins matched.",
+                },
+              ],
+              details: structuredClone(latest),
+            };
+          },
+        }),
+      );
+      disposePanel = context.piPluginUi.register({
+        id: "plugin-stars-panel",
+        pluginId: "@pi-harness/core/plugins/plugin-stars",
+        title: "Plugin Stars",
+        description: "读取 dsh-plugin-stars 策展榜单，按 Star 和关键词查看社区插件，不自动安装。",
+        icon: "★",
+        read: () => {
+          const panelResults = structuredClone(latest?.results.slice(0, maxPanelItems) ?? []);
           return {
-            content: [
-              {
-                type: "text",
-                text:
-                  results.map((entry, index) => `${index + 1}. ${entry.fullName} · ${entry.stars} stars\n${entry.htmlUrl}`).join("\n\n") ||
-                  "No ranked plugins matched.",
-              },
-            ],
-            details: latest,
+            source,
+            limit,
+            timeoutMs,
+            latest: latest === undefined ? null : { ...structuredClone(latest), results: panelResults },
+            inventory: {
+              total: latest?.total ?? 0,
+              shown: panelResults.length,
+              truncated: (latest?.total ?? 0) > panelResults.length,
+            },
+            limits: {
+              responseBytes: maxResponseBytes,
+              sourceItems: maxInventoryItems,
+              resultItems: limit,
+              panelItems: maxPanelItems,
+              queryCharacters: maxQueryLength,
+              timeoutMs,
+            },
           };
         },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "plugin-stars-panel",
-      pluginId: "@pi-harness/core/plugins/plugin-stars",
-      title: "Plugin Stars",
-      description: "读取 dsh-plugin-stars 策展榜单，按 Star 和关键词查看社区插件，不自动安装。",
-      icon: "★",
-      read: () => ({ source, limit, timeoutMs, latest: latest ?? null }),
-    });
+      });
+    } catch (error) {
+      unregister();
+      disposePanel();
+      lifecycle.abort(new Error("Plugin stars plugin registration failed"));
+      throw error;
+    }
     context.effect(() => () => {
+      lifecycle.abort(new Error("Plugin stars plugin disposed"));
       unregister();
       disposePanel();
     });