@pi-harness/pi-harness 0.1.2 → 0.1.3

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

@@ -0,0 +1,190 @@
+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

@@ -0,0 +1,176 @@
+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

@@ -0,0 +1,179 @@
+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();
+    });
+  },
+};