@pi-harness/pi-harness 0.1.13 → 0.1.15

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

@@ -1,205 +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 defaultSourceUrl = "https://raw.githubusercontent.com/ywsldxk/dsh-plugin-stars/main/data/plugins.json";
-const maxResponseBytes = 2 * 1024 * 1024;
-const maxQueryLength = 120;
-const maxLimit = 50;
-
-export interface PluginStarsEntry {
-  id: string;
-  name: string;
-  fullName: string;
-  description: string;
-  htmlUrl: string;
-  homepage?: string;
-  npmName?: string;
-  stars: number;
-  updatedAt: string;
-  license?: string;
-  topics: string[];
-}
-
-export interface PluginStarsReport {
-  source: string;
-  generatedAt: string;
-  total: number;
-  query: string;
-  results: PluginStarsEntry[];
-  fetchedAt: string;
-}
-
-function record(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
-}
-
-function text(value: unknown): string {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function nonNegativeInteger(value: unknown): number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : -1;
-}
-
-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 normalizedEntry(value: unknown): PluginStarsEntry | undefined {
-  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);
-  return {
-    id,
-    name,
-    fullName,
-    description: text(item.description),
-    htmlUrl,
-    ...(homepage === "" ? {} : { homepage }),
-    ...(npmName === "" ? {} : { npmName }),
-    stars,
-    updatedAt: text(item.updatedAt),
-    ...(license === "" ? {} : { license }),
-    topics: topics(item.topics),
-  };
-}
-
-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 };
-}
-
-export function searchPluginStars(report: { plugins: readonly PluginStarsEntry[] }, query = ""): PluginStarsEntry[] {
-  const normalizedQuery = query.trim().toLowerCase();
-  if (normalizedQuery.length > maxQueryLength) throw new Error(`Plugin stars query must contain 0-${maxQueryLength} characters`);
-  return [...report.plugins]
-    .filter(
-      (entry) => normalizedQuery === "" || [entry.name, entry.fullName, entry.description, ...entry.topics].join(" ").toLowerCase().includes(normalizedQuery),
-    )
-    .sort((left, right) => right.stars - left.stars || left.fullName.localeCompare(right.fullName));
-}
-
-function sourceUrl(raw: string): string {
-  let url: URL;
-  try {
-    url = new URL(raw.trim());
-  } catch {
-    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");
-  return url.toString();
-}
-
-async function fetchReport(
-  url: string,
-  timeoutMs: number,
-  signal?: AbortSignal,
-): Promise<{ source: string; generatedAt: string; plugins: PluginStarsEntry[] }> {
-  const controller = new AbortController();
-  const onAbort = (): void => controller.abort(signal?.reason);
-  signal?.addEventListener("abort", onAbort, { once: true });
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  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 });
-    }
-    return parsePluginStarsPayload(payload);
-  } 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 });
-    throw error;
-  } finally {
-    clearTimeout(timer);
-    signal?.removeEventListener("abort", onAbort);
-  }
-}
-
-export interface PluginStarsConfig {
-  sourceUrl?: string;
-  limit?: number;
-  timeoutMs?: number;
-}
-
-export const Config: z<PluginStarsConfig> = z.object({
-  sourceUrl: z.string().default(defaultSourceUrl),
-  limit: z.number().default(10),
-  timeoutMs: z.number().default(15_000),
-});
-
-export default {
-  name: "pi-plugin-stars",
-  inject: ["piPluginUi", "piTools"],
-  Config,
-  apply(context: Context, config: PluginStarsConfig) {
-    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)));
-    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() };
-          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,
-          };
-        },
-      }),
-    );
-    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 }),
-    });
-    context.effect(() => () => {
-      unregister();
-      disposePanel();
-    });
-  },
-};

package/packages/core/src/plugins/prompt-guard.ts

@@ -1,122 +0,0 @@
-import type { Context } from "@deepseek-ai/cordis";
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
-
-const maxPromptBytes = 128 * 1024;
-type Risk = "safe" | "review" | "blocked";
-type Finding = { code: string; severity: "medium" | "high"; message: string };
-type PromptGuardReport = { source: string; risk: Risk; score: number; scannedChars: number; findings: Finding[] };
-type Pattern = { code: string; severity: Finding["severity"]; score: number; message: string; pattern: RegExp };
-
-const patterns: readonly Pattern[] = [
-  {
-    code: "instruction_override",
-    severity: "high",
-    score: 5,
-    message: "检测到试图覆盖已有指令的文本。",
-    pattern: /\bignore\s+(?:all\s+)?(?:previous|earlier|above)\s+instructions\b/iu,
-  },
-  {
-    code: "secret_exfiltration",
-    severity: "high",
-    score: 5,
-    message: "检测到可能要求外传 API key、token 或密码的文本。",
-    pattern: /\b(?:api[\s_-]?key|token|password|secret)\b.{0,120}\b(?:send|upload|post|share|curl|wget)\b/iu,
-  },
-  { code: "remote_payload", severity: "medium", score: 2, message: "检测到从远程地址加载或执行内容的文本。", pattern: /\b(?:curl|wget)\s+https?:\/\//iu },
-  {
-    code: "system_prompt_probe",
-    severity: "medium",
-    score: 2,
-    message: "检测到探测系统或开发者提示词的文本。",
-    pattern: /\b(?:system|developer)\s+(?:prompt|message|instruction)s?\b/iu,
-  },
-  {
-    code: "hidden_instruction",
-    severity: "medium",
-    score: 2,
-    message: "检测到要求隐藏执行意图或绕过披露的文本。",
-    pattern: /\b(?:do not|don't)\s+(?:tell|show|disclose)\s+(?:the\s+)?(?:user|human)\b/iu,
-  },
-];
-
-function inspect(text: string, source: string): PromptGuardReport {
-  if (Buffer.byteLength(text, "utf8") > maxPromptBytes) throw new Error(`Prompt guard input must be at most ${maxPromptBytes} bytes`);
-  const findings = patterns.filter((item) => item.pattern.test(text)).map(({ code, severity, message }) => ({ code, severity, message }));
-  const score = findings.reduce((total, finding) => total + (patterns.find((item) => item.code === finding.code)?.score ?? 0), 0);
-  const highFindings = findings.filter((finding) => finding.severity === "high").length;
-  const risk: Risk = highFindings >= 2 || score >= 8 ? "blocked" : findings.length > 0 ? "review" : "safe";
-  return { source: source.trim().slice(0, 64) || "unknown", risk, score, scannedChars: text.length, findings };
-}
-
-function messageText(message: unknown): string {
-  if (message === null || typeof message !== "object") return "";
-  const content = (message as { content?: unknown }).content;
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .filter(
-      (item): item is { type: "text"; text: string } =>
-        item !== null && typeof item === "object" && (item as { type?: unknown }).type === "text" && typeof (item as { text?: unknown }).text === "string",
-    )
-    .map((item) => item.text)
-    .join("\n");
-}
-
-export default {
-  name: "pi-prompt-guard",
-  inject: ["piPluginUi", "piTools"],
-  apply(context: Context) {
-    let scans = 0;
-    let latest: PromptGuardReport | undefined;
-    const onSessionEvent = context.on("pi/session-event", (event) => {
-      if (event.type !== "message_start" || event.message.role !== "user") return;
-      try {
-        latest = inspect(messageText(event.message), "message_start");
-        scans += 1;
-      } catch {
-        latest = {
-          source: "message_start",
-          risk: "review",
-          score: 0,
-          scannedChars: 0,
-          findings: [{ code: "input_limit", severity: "medium", message: "输入超过 Prompt Guard 扫描上限。" }],
-        };
-        scans += 1;
-      }
-    });
-    const unregisterTool = context.piTools.register(
-      defineTool({
-        name: "prompt_guard_scan",
-        label: "Prompt guard scan",
-        description: "Scan text for prompt injection, secret exfiltration, and remote payload indicators without retaining the source text.",
-        promptSnippet: "scan untrusted text for prompt injection risks",
-        parameters: Type.Object({ text: Type.String(), source: Type.Optional(Type.String()) }),
-        execute(_toolCallId, params): Promise<AgentToolResult<PromptGuardReport>> {
-          return Promise.resolve().then(() => {
-            const report = inspect(params.text, params.source ?? "tool");
-            latest = report;
-            scans += 1;
-            return {
-              content: [{ type: "text" as const, text: `${report.risk}: ${report.findings.length} finding(s), score ${report.score}.` }],
-              details: report,
-            };
-          });
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "prompt-guard-panel",
-      pluginId: "@pi-harness/core/plugins/prompt-guard",
-      title: "Prompt Guard",
-      description: "扫描潜在提示词注入和秘密外传风险，只保留摘要，不保存原文。",
-      icon: "⊘",
-      read: () => ({ scans, risk: latest?.risk ?? "safe", latest: latest ?? null }),
-    });
-    context.effect(() => () => {
-      onSessionEvent();
-      unregisterTool();
-      disposePanel();
-    });
-  },
-};

package/packages/core/src/plugins/prompt-library.ts

@@ -1,165 +0,0 @@
-import type { Context } from "@deepseek-ai/cordis";
-import { Type } from "@earendil-works/pi-ai";
-import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
-
-const customType = "pi-harness/prompt-library";
-const maxTitleLength = 120;
-const maxPromptLength = 8_000;
-const maxTagLength = 40;
-const maxTags = 10;
-const maxTemplates = 100;
-
-export interface PromptTemplateInput {
-  title: string;
-  prompt: string;
-  tags?: string[];
-}
-
-export interface PromptTemplate {
-  id: string;
-  title: string;
-  prompt: string;
-  tags: string[];
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface PromptLibraryState {
-  templates: PromptTemplate[];
-}
-
-function bounded(value: string, field: string, maxLength: number): string {
-  const text = value.trim();
-  if (!text) throw new Error(`${field} is required`);
-  if (text.length > maxLength) throw new Error(`${field} must be ${maxLength.toLocaleString()} characters or fewer`);
-  return text;
-}
-
-function normalizeTags(values: string[] | undefined): string[] {
-  const tags = values ?? [];
-  if (tags.length > maxTags) throw new Error(`tags must contain ${maxTags} items or fewer`);
-  return [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))].map((tag) => bounded(tag, "tag", maxTagLength));
-}
-
-export function createPromptTemplate(input: PromptTemplateInput, id: string, timestamp: string): PromptTemplate {
-  return {
-    id,
-    title: bounded(input.title, "title", maxTitleLength),
-    prompt: bounded(input.prompt, "prompt", maxPromptLength),
-    tags: normalizeTags(input.tags),
-    createdAt: timestamp,
-    updatedAt: timestamp,
-  };
-}
-
-function readState(context: Context): PromptLibraryState {
-  const entry = [...context.piSession.manager.getEntries()].reverse().find((item) => item.type === "custom" && item.customType === customType);
-  if (entry?.type !== "custom" || entry.data === undefined || entry.data === null || typeof entry.data !== "object") return { templates: [] };
-  const value = entry.data as { templates?: unknown };
-  if (!Array.isArray(value.templates)) return { templates: [] };
-  const templates = value.templates.flatMap((item): PromptTemplate[] => {
-    if (item === null || typeof item !== "object") return [];
-    const candidate = item as Partial<PromptTemplate>;
-    if (typeof candidate.id !== "string" || typeof candidate.title !== "string" || typeof candidate.prompt !== "string") return [];
-    return [
-      {
-        id: candidate.id,
-        title: candidate.title,
-        prompt: candidate.prompt,
-        tags: Array.isArray(candidate.tags) ? candidate.tags.filter((tag): tag is string => typeof tag === "string") : [],
-        createdAt: typeof candidate.createdAt === "string" ? candidate.createdAt : new Date(0).toISOString(),
-        updatedAt: typeof candidate.updatedAt === "string" ? candidate.updatedAt : new Date(0).toISOString(),
-      },
-    ];
-  });
-  return { templates: templates.slice(-maxTemplates) };
-}
-
-function persist(context: Context, state: PromptLibraryState): void {
-  context.piSession.manager.appendCustomEntry(customType, state);
-}
-
-function filterTemplates(state: PromptLibraryState, query: string | undefined): PromptTemplate[] {
-  const normalized = query?.trim().toLocaleLowerCase() ?? "";
-  if (!normalized) return state.templates;
-  return state.templates.filter((template) => `${template.title} ${template.prompt} ${template.tags.join(" ")}`.toLocaleLowerCase().includes(normalized));
-}
-
-export default {
-  name: "pi-prompt-library",
-  inject: ["piSession", "piPluginUi", "piTools"],
-  apply(context: Context) {
-    let sequence = 0;
-    let latest = readState(context);
-    const unregister = context.piTools.register(
-      defineTool({
-        name: "prompt_library",
-        label: "Prompt library",
-        description: "Save, search, update, and delete reusable prompt templates in the current Pi session.",
-        promptSnippet: "manage reusable prompts for the current project",
-        parameters: Type.Object({
-          action: Type.Union([Type.Literal("save"), Type.Literal("list"), Type.Literal("delete")]),
-          id: Type.Optional(Type.String()),
-          title: Type.Optional(Type.String()),
-          prompt: Type.Optional(Type.String()),
-          tags: Type.Optional(Type.Array(Type.String())),
-          query: Type.Optional(Type.String()),
-        }),
-        execute(_toolCallId, params): Promise<AgentToolResult<PromptLibraryState & { selected?: PromptTemplate }>> {
-          return Promise.resolve().then(() => {
-            const state = readState(context);
-            if (params.action === "save") {
-              const now = new Date().toISOString();
-              const existing = params.id?.trim() ? state.templates.find((template) => template.id === params.id?.trim()) : undefined;
-              const template = existing
-                ? {
-                    ...existing,
-                    title: bounded(params.title ?? existing.title, "title", maxTitleLength),
-                    prompt: bounded(params.prompt ?? existing.prompt, "prompt", maxPromptLength),
-                    tags: normalizeTags(params.tags ?? existing.tags),
-                    updatedAt: now,
-                  }
-                : createPromptTemplate(
-                    { title: params.title ?? "", prompt: params.prompt ?? "", ...(params.tags === undefined ? {} : { tags: params.tags }) },
-                    `prompt-${Date.now()}-${++sequence}`,
-                    now,
-                  );
-              const templates = existing
-                ? state.templates.map((item) => (item.id === existing.id ? template : item))
-                : [...state.templates, template].slice(-maxTemplates);
-              latest = { templates };
-              persist(context, latest);
-              return { content: [{ type: "text" as const, text: `Prompt ${template.id} saved.` }], details: { ...latest, selected: template } };
-            }
-            if (params.action === "delete") {
-              const id = params.id?.trim();
-              if (!id) throw new Error("id is required when action is delete");
-              if (!state.templates.some((template) => template.id === id)) throw new Error(`Prompt was not found: ${id}`);
-              latest = { templates: state.templates.filter((template) => template.id !== id) };
-              persist(context, latest);
-              return { content: [{ type: "text" as const, text: `Prompt ${id} deleted.` }], details: latest };
-            }
-            latest = state;
-            const templates = filterTemplates(state, params.query);
-            return {
-              content: [{ type: "text" as const, text: templates.map((template) => `${template.id}: ${template.title}`).join("\n") || "No prompts found." }],
-              details: { templates },
-            };
-          });
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "prompt-library-panel",
-      pluginId: "@pi-harness/core/plugins/prompt-library",
-      title: "Prompt Library",
-      description: "保存和检索可复用的提示词模板，数据跟随当前会话。",
-      icon: "✎",
-      read: () => ({ total: latest.templates.length, templates: latest.templates }),
-    });
-    context.effect(() => () => {
-      unregister();
-      disposePanel();
-    });
-  },
-};

package/packages/core/src/plugins/readme-gen.ts

@@ -1,147 +0,0 @@
-import { lstat, mkdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { basename, dirname, join, relative, 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";
-
-export type ReadmeMetadata = { name: string; version: string; description: string; scripts: string[]; plugins: string[] };
-export type ReadmeReport = ReadmeMetadata & { markdown: string };
-export type ReadmeWriteReport = { path: string; bytes: number; overwritten: boolean };
-
-export function renderReadme(metadata: ReadmeMetadata): string {
-  const { name, version, description, scripts, plugins } = metadata;
-  return [
-    `# ${name}`,
-    "",
-    description,
-    "",
-    `Version: ${version}`,
-    "",
-    "## Scripts",
-    "",
-    ...(scripts.length ? scripts.map((script) => `- \`npm run ${script}\``) : ["- No npm scripts declared."]),
-    "",
-    "## Runtime plugins",
-    "",
-    ...(plugins.length ? plugins.map((plugin) => `- \`${plugin}\``) : ["- No runtime plugins reported."]),
-    "",
-  ].join("\n");
-}
-
-async function generate(context: Context): Promise<ReadmeReport> {
-  const path = join(context.piHarnessLaunch.cwd, "package.json");
-  const source = await readFile(path, "utf8");
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(source) as unknown;
-  } catch (error) {
-    throw new Error(`Invalid package.json: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-  }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("package.json root must be an object");
-  const packageJson = parsed as Record<string, unknown>;
-  const name = typeof packageJson.name === "string" ? packageJson.name : "Unnamed project";
-  const version = typeof packageJson.version === "string" ? packageJson.version : "unknown";
-  const description = typeof packageJson.description === "string" ? packageJson.description : "";
-  const scripts =
-    packageJson.scripts !== null && typeof packageJson.scripts === "object" && !Array.isArray(packageJson.scripts)
-      ? Object.keys(packageJson.scripts).sort()
-      : [];
-  const loader = context.get("loader") as { entries(): Iterable<{ disabled?: boolean | null; options: { name: string } }> } | undefined;
-  const plugins =
-    loader === undefined
-      ? []
-      : [...loader.entries()]
-          .filter((entry) => !entry.disabled)
-          .map((entry) => entry.options.name)
-          .filter((plugin) => !plugin.startsWith("cordis:"))
-          .sort();
-  const metadata = { name, version, description, scripts, plugins };
-  return { ...metadata, markdown: renderReadme(metadata) };
-}
-
-function outputPath(root: string, requested: string): string {
-  const value = requested.trim() || "README.generated.md";
-  if (value.length > 512 || value.includes("\\")) throw new Error("README output path must be a relative POSIX path of at most 512 characters");
-  const resolvedRoot = resolve(root);
-  const target = resolve(resolvedRoot, value);
-  const remainder = relative(resolvedRoot, target);
-  if (remainder === ".." || remainder.startsWith(`..${"/"}`) || remainder.startsWith("/")) throw new Error("README output path must stay inside the workspace");
-  return target;
-}
-
-export async function writeReadmeFile(root: string, markdown: string, requestedPath: string, confirm: boolean): Promise<ReadmeWriteReport> {
-  if (!confirm) throw new Error("Writing a README requires confirm=true");
-  const workspace = await realpath(resolve(root));
-  const target = outputPath(workspace, requestedPath);
-  const parent = dirname(target);
-  await mkdir(parent, { recursive: true });
-  const realParent = await realpath(parent);
-  const parentRemainder = relative(workspace, realParent);
-  if (parentRemainder === ".." || parentRemainder.startsWith(`..${"/"}`) || parentRemainder.startsWith("/"))
-    throw new Error("README output path must stay inside the workspace");
-  let overwritten = false;
-  try {
-    const metadata = await lstat(target);
-    if (metadata.isSymbolicLink() || !metadata.isFile()) throw new Error("README output path must be a regular file and cannot be a symbolic link");
-    overwritten = true;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
-  const temporary = join(parent, `.${basename(target)}.${randomUUID()}.tmp`);
-  await writeFile(temporary, markdown, { encoding: "utf8", mode: 0o600 });
-  await rename(temporary, target);
-  return { path: relative(workspace, target), bytes: Buffer.byteLength(markdown, "utf8"), overwritten };
-}
-
-export default {
-  name: "pi-readme-gen",
-  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  apply(context: Context) {
-    let latest: ReadmeReport | undefined;
-    let lastWrite: ReadmeWriteReport | undefined;
-    const unregisterTool = context.piTools.register(
-      defineTool({
-        name: "readme_report",
-        label: "README report",
-        description: "Generate a Markdown project overview from the local package manifest and active Pi runtime plugins.",
-        promptSnippet: "generate a project README overview",
-        parameters: Type.Object({}),
-        async execute(): Promise<AgentToolResult<ReadmeReport>> {
-          latest = await generate(context);
-          return { content: [{ type: "text", text: latest.markdown }], details: latest };
-        },
-      }),
-    );
-    const unregisterWrite = context.piTools.register(
-      defineTool({
-        name: "readme_write",
-        label: "Write README",
-        description: "Write the generated Markdown to a workspace file only after explicit confirmation; defaults to README.generated.md.",
-        promptSnippet: "write the generated README to a confirmed workspace path",
-        parameters: Type.Object({ outputPath: Type.Optional(Type.String()), confirm: Type.Boolean() }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<ReadmeWriteReport>> {
-          const report = latest ?? (latest = await generate(context));
-          lastWrite = await writeReadmeFile(context.piHarnessLaunch.cwd, report.markdown, params.outputPath ?? "README.generated.md", params.confirm);
-          return { content: [{ type: "text", text: `README written: ${lastWrite.path} (${lastWrite.bytes} bytes)` }], details: lastWrite };
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "readme-gen-panel",
-      pluginId: "@pi-harness/core/plugins/readme-gen",
-      title: "README Generator",
-      description: "从当前项目清单生成 Markdown 概览；写入文件需要显式确认，默认不会覆盖 README。",
-      icon: "▰",
-      read: () =>
-        latest === undefined
-          ? { generated: false, lastWrite: lastWrite ?? null }
-          : { generated: true, name: latest.name, scripts: latest.scripts.length, plugins: latest.plugins.length, lastWrite: lastWrite ?? null },
-    });
-    context.effect(() => () => {
-      unregisterTool();
-      unregisterWrite();
-      disposePanel();
-    });
-  },
-};