@pi-harness/pi-harness 0.1.13 → 0.1.15

package/packages/core/src/plugins/mcp-panel.ts

@@ -1,190 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, 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, type ToolDefinition } from "@earendil-works/pi-coding-agent";
-import type { PiMcpServerSnapshot } from "../services.js";
-
-type McpPanelServer = Omit<PiMcpServerSnapshot, "command"> & { executable: string; toolCount: number; statusSource: "runtime" };
-type McpPanelHealth = { serverId: string; status: string; severity: "ok" | "warning"; suggestions: string[] };
-
-export interface McpPanelPluginConfig {
-  patchPath?: string;
-}
-
-export const Config: z<McpPanelPluginConfig> = z.object({ patchPath: z.string().default("") });
-
-function mcpToolPrefix(serverId: string): string {
-  return `mcp__${serverId}__`;
-}
-
-function serverTools(serverId: string, tools: readonly ToolDefinition[]): ToolDefinition[] {
-  const prefix = mcpToolPrefix(serverId);
-  return tools.filter((tool) => tool.name.startsWith(prefix));
-}
-
-function healthFor(server: McpPanelServer | undefined): McpPanelHealth {
-  if (server === undefined) throw new Error("MCP server was not found");
-  if (server.status === "running") return { serverId: server.id, status: server.status, severity: "ok", suggestions: [] };
-  return { serverId: server.id, status: server.status, severity: "warning", suggestions: ["使用 mcp_server_start 启动该服务器，再重新检查健康状态。"] };
-}
-
-function validateServerId(serverId: string): string {
-  const normalized = serverId.trim();
-  if (!/^[a-z0-9][a-z0-9_-]{0,63}$/iu.test(normalized)) throw new Error("MCP server id must use letters, numbers, _ or -");
-  return normalized;
-}
-
-function validateCommand(command: readonly string[]): string[] {
-  if (command.length === 0 || command.length > 32 || command.some((part) => part.trim() === "" || part.length > 4096))
-    throw new Error("MCP command must contain 1-32 non-empty arguments");
-  return [...command];
-}
-
-function patchFragment(serverId: string, command: readonly string[], autoStart: boolean): string {
-  const rowId = `mcp-${serverId}`;
-  const commandRows = command.map((part) => `          - ${JSON.stringify(part)}`).join("\n");
-  return [
-    `- id: ${rowId}`,
-    `  name: "@pi-harness/core/plugins/mcp-client"`,
-    "  config:",
-    "    servers:",
-    `      - id: ${JSON.stringify(serverId)}`,
-    "        command:",
-    commandRows,
-    `        autoStart: ${autoStart ? "true" : "false"}`,
-    "",
-  ].join("\n");
-}
-
-export default {
-  name: "pi-mcp-panel",
-  inject: ["piHarnessLaunch", "piMcp", "piPluginUi", "piTools"],
-  Config,
-  apply(context: Context, config: McpPanelPluginConfig) {
-    const configuredPatchPath = config.patchPath?.trim() ?? "";
-    const patchTarget =
-      configuredPatchPath === ""
-        ? undefined
-        : isAbsolute(configuredPatchPath)
-          ? resolve(configuredPatchPath)
-          : resolve(context.piHarnessLaunch.agentDir, configuredPatchPath);
-    const snapshot = (): McpPanelServer[] => {
-      const customTools = context.piTools.snapshot().customTools;
-      return context.piMcp.snapshot().servers.map((server) => ({
-        id: server.id,
-        status: server.status,
-        startedAt: server.startedAt,
-        executable: basename(server.command[0] ?? ""),
-        toolCount: serverTools(server.id, customTools).length,
-        statusSource: "runtime",
-      }));
-    };
-    const buildPatch = (serverId: string, command: readonly string[], autoStart: boolean): string =>
-      patchFragment(validateServerId(serverId), validateCommand(command), autoStart);
-    let patchWriteQueue = Promise.resolve();
-    const applyPatch = async (fragment: string, serverId: string): Promise<string> => {
-      const write = patchWriteQueue.then(async () => {
-        if (patchTarget === undefined) throw new Error("MCP profile writes are disabled; configure patchPath first");
-        await mkdir(dirname(patchTarget), { recursive: true });
-        const metadata = await lstat(patchTarget).catch((error: unknown) => {
-          if (error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-          throw error;
-        });
-        if (metadata?.isSymbolicLink() || (metadata !== undefined && !metadata.isFile()))
-          throw new Error("MCP profile patch target must be a regular file and cannot be a symbolic link");
-        const existing = metadata === undefined ? "" : await readFile(patchTarget, "utf8");
-        const rowPattern = new RegExp(`^- id: mcp-${serverId}\\s*$`, "mu");
-        if (rowPattern.test(existing)) throw new Error(`MCP server patch already exists: ${serverId}`);
-        const backup = `${patchTarget}.bak`;
-        await writeFile(backup, existing, { encoding: "utf8", mode: 0o600, flag: "wx" }).catch((error: unknown) => {
-          if (!(error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST")) throw error;
-        });
-        const temporary = `${patchTarget}.${randomUUID()}.tmp`;
-        let renamed = false;
-        try {
-          await writeFile(temporary, `${existing.trimEnd()}${existing.trimEnd() === "" ? "" : "\n"}${fragment}`, { encoding: "utf8", mode: 0o600, flag: "wx" });
-          await rename(temporary, patchTarget);
-          renamed = true;
-        } finally {
-          if (!renamed) await unlink(temporary).catch(() => {});
-        }
-        return patchTarget;
-      });
-      patchWriteQueue = write.then(
-        () => undefined,
-        () => undefined,
-      );
-      return write;
-    };
-    const unregister = context.piTools.register(
-      defineTool({
-        name: "mcp_panel",
-        label: "MCP panel",
-        description: "Inspect MCP status and tools, derive health suggestions, and preview or explicitly apply a backed-up profile patch.",
-        promptSnippet: "inspect MCP status or preview a server profile patch",
-        parameters: Type.Object({
-          action: Type.Union([Type.Literal("status"), Type.Literal("tools"), Type.Literal("health"), Type.Literal("preview"), Type.Literal("apply")]),
-          serverId: Type.Optional(Type.String({ description: "Configured or running MCP server id" })),
-          command: Type.Optional(Type.Array(Type.String(), { description: "MCP server executable and arguments" })),
-          autoStart: Type.Optional(Type.Boolean({ description: "Start the configured server with the runtime" })),
-          confirm: Type.Optional(Type.Boolean({ description: "Must be true before applying a patch" })),
-        }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
-          await Promise.resolve();
-          const servers = snapshot();
-          if (params.action === "status") {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: servers.map((server) => `${server.id}: ${server.status} · ${server.toolCount} tools`).join("\n") || "No MCP servers configured.",
-                },
-              ],
-              details: { action: "status", servers },
-            };
-          }
-          if (params.serverId === undefined || params.serverId.trim() === "") throw new Error(`action ${params.action} requires serverId`);
-          if (params.action === "preview" || params.action === "apply") {
-            if (params.command === undefined) throw new Error(`action ${params.action} requires command`);
-            const serverId = validateServerId(params.serverId);
-            const fragment = buildPatch(serverId, params.command, params.autoStart === true);
-            if (params.action === "preview")
-              return { content: [{ type: "text", text: fragment }], details: { action: "preview", serverId, path: patchTarget ?? null, fragment } };
-            if (params.confirm !== true) throw new Error("Applying an MCP profile patch requires confirm=true");
-            const path = await applyPatch(fragment, serverId);
-            return {
-              content: [{ type: "text", text: `MCP server patch appended to ${path}.` }],
-              details: { action: "apply", serverId, path, backup: `${path}.bak` },
-            };
-          }
-          const server = servers.find((item) => item.id === params.serverId);
-          if (params.action === "health") {
-            const health = healthFor(server);
-            return { content: [{ type: "text", text: `${health.serverId}: ${health.status} (${health.severity})` }], details: { action: "health", ...health } };
-          }
-          if (server === undefined) throw new Error(`MCP server was not found: ${params.serverId}`);
-          const tools = serverTools(server.id, context.piTools.snapshot().customTools).map((tool) => ({ name: tool.name, description: tool.description }));
-          return {
-            content: [{ type: "text", text: tools.map((tool) => `${tool.name}: ${tool.description ?? ""}`).join("\n") || "No bridged tools." }],
-            details: { action: "tools", serverId: server.id, tools },
-          };
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "mcp-panel",
-      pluginId: "@pi-harness/core/plugins/mcp-panel",
-      title: "MCP Console",
-      description: "查看 MCP 服务器状态、桥接工具和健康建议。",
-      icon: "⌘",
-      read: () => ({ servers: snapshot(), statusSource: "runtime", writesEnabled: patchTarget !== undefined, patchPath: patchTarget ?? null }),
-    });
-    context.effect(() => () => {
-      unregister();
-      disposePanel();
-    });
-  },
-};

package/packages/core/src/plugins/memory.ts

@@ -1,176 +0,0 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { basename, dirname, join, 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";
-
-const defaultFileName = "memory.json";
-const maxKeyLength = 128;
-const maxValueBytes = 64 * 1024;
-const maxTagLength = 64;
-const maxTags = 16;
-const maxEntries = 500;
-
-type Memory = { id: string; key: string; value: string; tags: string[]; createdAt: string; updatedAt: string };
-type MemoryFile = { version: 1; memories: Memory[] };
-type MemorySearchReport = { query: string; total: number; memories: Memory[] };
-
-export interface MemoryPluginConfig {
-  fileName?: string;
-  maxEntries?: number;
-}
-
-export const Config: z<MemoryPluginConfig> = z.object({ fileName: z.string().default(defaultFileName), maxEntries: z.number().default(maxEntries) });
-
-function normalizeFilePath(agentDir: string, fileName: string | undefined): string {
-  const name = (fileName ?? defaultFileName).trim();
-  if (name === "" || basename(name) !== name || !name.toLowerCase().endsWith(".json")) throw new Error("Memory fileName must be a single .json filename");
-  return resolve(agentDir, name);
-}
-
-function normalizeKey(key: string): string {
-  const value = key.trim();
-  if (value.length === 0 || value.length > maxKeyLength) throw new Error(`Memory key must contain 1-${maxKeyLength} characters`);
-  return value;
-}
-
-function normalizeValue(value: string): string {
-  if (value.trim() === "" || Buffer.byteLength(value, "utf8") > maxValueBytes)
-    throw new Error(`Memory value must be non-empty and at most ${maxValueBytes} bytes`);
-  return value;
-}
-
-function normalizeTags(tags: readonly string[] | undefined): string[] {
-  const values = [...new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
-  if (values.length > maxTags || values.some((tag) => tag.length > maxTagLength))
-    throw new Error(`Memory tags must contain at most ${maxTags} entries of ${maxTagLength} characters`);
-  return values;
-}
-
-export default {
-  name: "pi-memory",
-  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  Config,
-  apply(context: Context, config: MemoryPluginConfig) {
-    const filePath = normalizeFilePath(context.piHarnessLaunch.agentDir, config.fileName);
-    const entryLimit = Math.max(1, Math.min(maxEntries, Math.trunc(config.maxEntries ?? maxEntries)));
-    let memories: Memory[] = [];
-    let loaded = false;
-    let loading: Promise<void> | undefined;
-    let writeQueue = Promise.resolve();
-    let last: MemorySearchReport | undefined;
-    const load = async (): Promise<void> => {
-      if (loaded) return;
-      if (loading !== undefined) return loading;
-      loading = (async () => {
-        try {
-          const parsed = JSON.parse(await readFile(filePath, "utf8")) as Partial<MemoryFile>;
-          if (parsed.version !== 1 || !Array.isArray(parsed.memories)) throw new Error("Memory file has an unsupported format");
-          memories = parsed.memories.filter(
-            (item): item is Memory => typeof item === "object" && item !== null && typeof item.key === "string" && typeof item.value === "string",
-          );
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-          memories = [];
-        }
-        loaded = true;
-      })();
-      return loading;
-    };
-    const persist = async (): Promise<void> => {
-      const payload = JSON.stringify({ version: 1, memories } satisfies MemoryFile, null, 2);
-      writeQueue = writeQueue.then(async () => {
-        await mkdir(dirname(filePath), { recursive: true });
-        const temporary = join(dirname(filePath), `.${basename(filePath)}.${randomUUID()}.tmp`);
-        await writeFile(temporary, payload, { encoding: "utf8", mode: 0o600 });
-        await rename(temporary, filePath);
-      });
-      await writeQueue;
-    };
-    const unregisterSet = context.piTools.register(
-      defineTool({
-        name: "memory_set",
-        label: "Remember fact",
-        description: "Persist one explicit fact in the Pi Harness memory store, replacing an existing value with the same key.",
-        promptSnippet: "save an explicit fact for future sessions",
-        parameters: Type.Object({ key: Type.String(), value: Type.String(), tags: Type.Optional(Type.Array(Type.String())) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<Memory>> {
-          await load();
-          const key = normalizeKey(params.key);
-          const value = normalizeValue(params.value);
-          const tags = normalizeTags(params.tags);
-          const now = new Date().toISOString();
-          const existing = memories.find((item) => item.key === key);
-          const memory: Memory =
-            existing === undefined ? { id: randomUUID(), key, value, tags, createdAt: now, updatedAt: now } : { ...existing, value, tags, updatedAt: now };
-          memories = [memory, ...memories.filter((item) => item.key !== key)].slice(0, entryLimit);
-          await persist();
-          return { content: [{ type: "text", text: `Memory saved: ${key}` }], details: memory };
-        },
-      }),
-    );
-    const unregisterSearch = context.piTools.register(
-      defineTool({
-        name: "memory_search",
-        label: "Search memories",
-        description: "Search explicit cross-session memories by key, value, or tag.",
-        promptSnippet: "search remembered facts from earlier sessions",
-        parameters: Type.Object({ query: Type.String() }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<MemorySearchReport>> {
-          await load();
-          const query = params.query.trim().toLocaleLowerCase();
-          if (query.length < 2 || query.length > maxKeyLength) throw new Error(`Memory search query must contain 2-${maxKeyLength} characters`);
-          const results = memories.filter((item) => [item.key, item.value, ...item.tags].some((field) => field.toLocaleLowerCase().includes(query)));
-          last = { query: params.query.trim(), total: results.length, memories: results };
-          return {
-            content: [
-              {
-                type: "text",
-                text: results.length === 0 ? `No memories found for ${params.query.trim()}.` : results.map((item) => `${item.key}: ${item.value}`).join("\n"),
-              },
-            ],
-            details: last,
-          };
-        },
-      }),
-    );
-    const unregisterDelete = context.piTools.register(
-      defineTool({
-        name: "memory_delete",
-        label: "Forget memory",
-        description: "Delete one explicit memory by key. Confirmation is required.",
-        promptSnippet: "forget a stored memory after confirmation",
-        parameters: Type.Object({ key: Type.String(), confirm: Type.Boolean() }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<{ key: string; removed: boolean }>> {
-          await load();
-          const key = normalizeKey(params.key);
-          if (params.confirm !== true) throw new Error("Deleting a memory requires confirm=true");
-          const before = memories.length;
-          memories = memories.filter((item) => item.key !== key);
-          const removed = memories.length !== before;
-          if (removed) await persist();
-          return { content: [{ type: "text", text: removed ? `Memory deleted: ${key}` : `Memory not found: ${key}` }], details: { key, removed } };
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "memory-panel",
-      pluginId: "@pi-harness/core/plugins/memory",
-      title: "Memory",
-      description: "只保存 Agent 明确写入的事实，跨会话持久化并支持检索与删除。",
-      icon: "▣",
-      read: async () => {
-        await load();
-        return { filePath, count: memories.length, last: last ?? null, memories: memories.slice(0, 8) };
-      },
-    });
-    context.effect(() => () => {
-      unregisterSet();
-      unregisterSearch();
-      unregisterDelete();
-      disposePanel();
-    });
-  },
-};

package/packages/core/src/plugins/mirage-bridge.ts

@@ -1,179 +0,0 @@
-import { execFile } from "node:child_process";
-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";
-
-const execFileAsync = promisify(execFile);
-const defaultExecutable = "mirage";
-const defaultTimeoutMs = 60_000;
-const maxCommandLength = 4_000;
-const maxOutputBytes = 128 * 1024;
-
-export interface MirageBridgeConfig {
-  executable?: string;
-  workspaceId?: string;
-  timeoutMs?: number;
-}
-
-export type MirageRun = {
-  workspaceId: string;
-  command: string;
-  exitCode: number | null;
-  durationMs: number;
-  output: string;
-};
-
-type MirageBridgeState = {
-  executable: string;
-  workspaceId: string | null;
-  available: boolean | null;
-  version: string | null;
-  lastError: string | null;
-  lastRun: MirageRun | null;
-};
-
-export const Config: z<MirageBridgeConfig> = z.object({
-  executable: z.string().default(defaultExecutable),
-  workspaceId: z.string().default(""),
-  timeoutMs: z.number().default(defaultTimeoutMs),
-});
-
-function normalizeExecutable(input: string | undefined): string {
-  const executable = (input ?? defaultExecutable).trim();
-  if (executable.length < 1 || executable.length > 512 || executable.includes("\0")) throw new Error("Mirage executable must contain 1-512 characters");
-  return executable;
-}
-
-function normalizeWorkspaceId(input: string | undefined): string | null {
-  const workspaceId = input?.trim() ?? "";
-  if (workspaceId === "") return null;
-  if (!/^[a-z0-9][a-z0-9._-]{0,127}$/iu.test(workspaceId))
-    throw new Error("Mirage workspaceId must contain 1-128 letters, numbers, dots, underscores, or hyphens");
-  return workspaceId;
-}
-
-function normalizeCommand(input: string): string {
-  const command = input.trim();
-  if (command.length < 1 || command.length > maxCommandLength) throw new Error(`Mirage command must contain 1-${maxCommandLength} characters`);
-  return command;
-}
-
-function errorMessage(error: unknown): string {
-  if (error instanceof Error) return error.message;
-  return String(error);
-}
-
-export default {
-  name: "pi-mirage-bridge",
-  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  Config,
-  apply(context: Context, config: MirageBridgeConfig) {
-    const executable = normalizeExecutable(config.executable);
-    const workspaceId = normalizeWorkspaceId(config.workspaceId);
-    const timeoutMs = Math.max(1_000, Math.min(120_000, Math.trunc(config.timeoutMs ?? defaultTimeoutMs)));
-    let state: MirageBridgeState = { executable, workspaceId, available: null, version: null, lastError: null, lastRun: null };
-
-    const doctor = async (): Promise<MirageBridgeState> => {
-      try {
-        const result = await execFileAsync(executable, ["--version"], {
-          cwd: context.piHarnessLaunch.cwd,
-          timeout: Math.min(timeoutMs, 10_000),
-          maxBuffer: maxOutputBytes,
-        });
-        const version = `${result.stdout}${result.stderr}`.trim().split(/\r?\n/u)[0]?.slice(0, 256) || "Mirage CLI detected";
-        state = { ...state, available: true, version, lastError: null };
-      } catch (error) {
-        state = { ...state, available: false, version: null, lastError: errorMessage(error).slice(0, 1_000) };
-      }
-      return state;
-    };
-
-    const run = async (commandInput: string): Promise<MirageRun> => {
-      if (workspaceId === null) throw new Error("Mirage workspaceId is not configured");
-      const command = normalizeCommand(commandInput);
-      const startedAt = Date.now();
-      try {
-        const result = await execFileAsync(executable, ["execute", "--workspace_id", workspaceId, "--command", command], {
-          cwd: context.piHarnessLaunch.cwd,
-          timeout: timeoutMs,
-          maxBuffer: maxOutputBytes,
-        });
-        state = {
-          ...state,
-          available: true,
-          lastError: null,
-          lastRun: { workspaceId, command, exitCode: 0, durationMs: Date.now() - startedAt, output: `${result.stdout}${result.stderr}`.slice(-maxOutputBytes) },
-        };
-      } catch (error) {
-        const failure = error as { code?: number | string; stdout?: string; stderr?: string; message?: string };
-        const unavailable = failure.code === "ENOENT";
-        const output = `${failure.stdout ?? ""}${failure.stderr ?? failure.message ?? ""}`.slice(-maxOutputBytes);
-        state = {
-          ...state,
-          available: unavailable ? false : state.available,
-          lastError: unavailable ? output : null,
-          lastRun: {
-            workspaceId,
-            command,
-            exitCode: typeof failure.code === "number" ? failure.code : null,
-            durationMs: Date.now() - startedAt,
-            output,
-          },
-        };
-      }
-      return state.lastRun!;
-    };
-
-    const unregisterDoctor = context.piTools.register(
-      defineTool({
-        name: "mirage_doctor",
-        label: "Check Mirage CLI",
-        description: "Check whether the official Mirage virtual-terminal CLI is available and report its configured workspace.",
-        promptSnippet: "check the official Mirage virtual terminal integration",
-        parameters: Type.Object({}),
-        async execute(): Promise<AgentToolResult<MirageBridgeState>> {
-          const details = await doctor();
-          return {
-            content: [
-              {
-                type: "text",
-                text: details.available
-                  ? `${details.version}; workspace ${details.workspaceId ?? "not configured"}`
-                  : `Mirage unavailable: ${details.lastError}`,
-              },
-            ],
-            details,
-          };
-        },
-      }),
-    );
-    const unregisterExecute = context.piTools.register(
-      defineTool({
-        name: "mirage_execute",
-        label: "Execute in Mirage",
-        description: "Pass one command to the official Mirage virtual terminal in the configured virtual workspace.",
-        promptSnippet: "run a command inside the configured Mirage virtual workspace",
-        parameters: Type.Object({ command: Type.String({ description: "Command interpreted by Mirage, not the host shell" }) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<MirageRun>> {
-          const details = await run(params.command);
-          return { content: [{ type: "text", text: `Mirage exited with ${details.exitCode ?? "unknown"}.\n${details.output}` }], details };
-        },
-      }),
-    );
-    const disposePanel = context.piPluginUi.register({
-      id: "mirage-bridge-panel",
-      pluginId: "@pi-harness/core/plugins/mirage-bridge",
-      title: "Mirage Bridge",
-      description: "连接官方 Mirage 虚拟终端，在配置的虚拟工作区中执行命令。",
-      icon: "◇",
-      read: () => ({ ...state, timeoutMs }),
-    });
-    context.effect(() => () => {
-      unregisterDoctor();
-      unregisterExecute();
-      disposePanel();
-    });
-  },
-};