@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/src/plugins/mock-server.ts

@@ -0,0 +1,158 @@
+import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
+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";
+
+type MockRoute = { path: string; method?: string; status?: number; headers?: Record<string, string>; body?: string };
+type MockServerState = { running: boolean; url: string | null; routes: number; lastRequest: string | null };
+
+const maxRoutes = 64;
+const maxBodyBytes = 128 * 1024;
+const allowedMethods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+
+export interface MockServerPluginConfig {
+  port?: number;
+  routes?: MockRoute[];
+}
+
+const routeConfig = z.object({
+  path: z.string(),
+  method: z.string().default("GET"),
+  status: z.number().default(200),
+  headers: z.dict(z.string()).default({}),
+  body: z.string().default(""),
+});
+
+export const Config: z<MockServerPluginConfig> = z.object({ port: z.number().default(0), routes: z.array(routeConfig).default([]) });
+
+function normalizeRoutes(routes: MockRoute[]): MockRoute[] {
+  if (routes.length > maxRoutes) throw new Error(`Mock server cannot exceed ${maxRoutes} routes`);
+  return routes.map((route) => {
+    const path = route.path.trim();
+    if (!path.startsWith("/") || path.length > 2048 || path.includes("#")) throw new Error("Mock route path must start with / and be at most 2048 characters");
+    const method = (route.method ?? "GET").trim().toUpperCase();
+    if (!allowedMethods.has(method)) throw new Error(`Mock route method is not allowed: ${method}`);
+    const status = route.status ?? 200;
+    if (!Number.isInteger(status) || status < 100 || status > 599) throw new Error("Mock route status must be an integer between 100 and 599");
+    const body = route.body ?? "";
+    if (Buffer.byteLength(body, "utf8") > maxBodyBytes) throw new Error(`Mock route body cannot exceed ${maxBodyBytes} bytes`);
+    const headers = Object.fromEntries(Object.entries(route.headers ?? {}).map(([name, value]) => [name, String(value)]));
+    return { path, method, status, headers, body };
+  });
+}
+
+function routeKey(method: string, path: string): string {
+  return `${method} ${path}`;
+}
+
+export default {
+  name: "pi-mock-server",
+  inject: ["piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: MockServerPluginConfig) {
+    const routes = normalizeRoutes(config.routes ?? []);
+    let server: Server | undefined;
+    let state: MockServerState = { running: false, url: null, routes: routes.length, lastRequest: null };
+    const start = async (requestedPort?: number): Promise<MockServerState> => {
+      if (server !== undefined) throw new Error("Mock server is already running");
+      const port = requestedPort ?? config.port ?? 0;
+      if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("Mock server port must be an integer between 0 and 65535");
+      const routeMap = new Map(routes.map((route) => [routeKey(route.method ?? "GET", route.path), route]));
+      server = createServer((request: IncomingMessage, response: ServerResponse) => {
+        const method = (request.method ?? "GET").toUpperCase();
+        const pathname = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+        state = { ...state, lastRequest: routeKey(method, pathname) };
+        const route = routeMap.get(routeKey(method, pathname));
+        if (route === undefined) {
+          response.statusCode = 404;
+          response.setHeader("content-type", "text/plain; charset=utf-8");
+          response.end("Not found");
+          return;
+        }
+        response.statusCode = route.status ?? 200;
+        for (const [name, value] of Object.entries(route.headers ?? {})) response.setHeader(name, value);
+        if (!response.hasHeader("content-type")) response.setHeader("content-type", "text/plain; charset=utf-8");
+        response.end(route.body ?? "");
+      });
+      await new Promise<void>((resolve, reject) => {
+        const onError = (error: Error): void => {
+          server?.off("listening", onListening);
+          reject(error);
+        };
+        const onListening = (): void => {
+          server?.off("error", onError);
+          resolve();
+        };
+        server!.once("error", onError);
+        server!.once("listening", onListening);
+        server!.listen(port, "127.0.0.1");
+      });
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Mock server did not expose a TCP address");
+      state = { ...state, running: true, url: `http://127.0.0.1:${address.port}` };
+      return state;
+    };
+    const stop = async (): Promise<boolean> => {
+      if (server === undefined) return false;
+      const current = server;
+      server = undefined;
+      await new Promise<void>((resolve, reject) => current.close((error) => (error ? reject(error) : resolve())));
+      state = { ...state, running: false, url: null };
+      return true;
+    };
+    const unregisterStart = context.piTools.register(
+      defineTool({
+        name: "mock_server_start",
+        label: "Mock server start",
+        description: "Start a local deterministic HTTP mock server from configured routes.",
+        promptSnippet: "start the local mock HTTP server",
+        parameters: Type.Object({ port: Type.Optional(Type.Number({ description: "Bind port; 0 selects a free local port" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<MockServerState>> {
+          const result = await start(params.port);
+          return { content: [{ type: "text", text: `Mock server listening at ${result.url}` }], details: result };
+        },
+      }),
+    );
+    const unregisterStop = context.piTools.register(
+      defineTool({
+        name: "mock_server_stop",
+        label: "Mock server stop",
+        description: "Stop the local HTTP mock server.",
+        promptSnippet: "stop the local mock HTTP server",
+        parameters: Type.Object({}),
+        async execute(): Promise<AgentToolResult<{ stopped: boolean }>> {
+          const stopped = await stop();
+          return { content: [{ type: "text", text: stopped ? "Mock server stopped." : "Mock server was not running." }], details: { stopped } };
+        },
+      }),
+    );
+    const unregisterStatus = context.piTools.register(
+      defineTool({
+        name: "mock_server_status",
+        label: "Mock server status",
+        description: "Show local HTTP mock server status and route count.",
+        promptSnippet: "check the local mock server status",
+        parameters: Type.Object({}),
+        execute(): Promise<AgentToolResult<MockServerState>> {
+          return Promise.resolve({ content: [{ type: "text", text: `${state.running ? "running" : "stopped"} ${state.url ?? ""}`.trim() }], details: state });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "mock-server-panel",
+      pluginId: "@pi-harness/core/plugins/mock-server",
+      title: "Mock Server",
+      description: "在本机回环地址提供可控的 HTTP mock 路由。",
+      icon: "⇄",
+      read: () => state,
+    });
+    context.effect(() => () => {
+      unregisterStart();
+      unregisterStop();
+      unregisterStatus();
+      disposePanel();
+      void stop();
+    });
+  },
+};

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

@@ -1,9 +1,11 @@
 import type { Context } from "@deepseek-ai/cordis";
+import { assertKnownConfigKeys } from "../config.js";
 
 export default {
   name: "pi-model",
   inject: ["piModelRuntime", "piResources"],
-  apply(context: Context) {
+  apply(context: Context, config: unknown) {
+    assertKnownConfigKeys("pi-model", config, []);
     const { runtime, provider, model: modelId } = context.piModelRuntime;
     const model = runtime.getModel(provider, modelId);
     if (model === undefined) throw new Error(`Pi model is not registered: ${provider}/${modelId}`);

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

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { assertKnownConfigKeys } from "../config.js";
 
 export interface ModelsPluginConfig {
   provider: string;
@@ -10,8 +11,8 @@ export interface ModelsPluginConfig {
 }
 
 export const Config: z<ModelsPluginConfig> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
+  provider: z.string().required().min(1),
+  model: z.string().required().min(1),
   refreshOnCreate: z.boolean().default(false),
 });
 
@@ -20,12 +21,14 @@ export default {
   inject: ["piHarnessLaunch"],
   Config,
   async apply(context: Context, config: ModelsPluginConfig) {
+    assertKnownConfigKeys("pi-models", config, ["provider", "model", "refreshOnCreate"]);
     const agentDir = context.piHarnessLaunch.agentDir;
     const runtime = await ModelRuntime.create({
       authPath: join(agentDir, "auth.json"),
       modelsPath: join(agentDir, "models.json"),
       modelsStorePath: join(agentDir, "models-store.json"),
       refreshOnCreate: config.refreshOnCreate ?? false,
+      allowModelNetwork: config.refreshOnCreate ?? false,
     });
     context.provide("piModelRuntime", { runtime, provider: config.provider, model: config.model });
   },

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

@@ -0,0 +1,63 @@
+import { readFile, stat } from "node:fs/promises";
+import { extname, relative, resolve } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+const mimeByExtension: Readonly<Record<string, string>> = {
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+};
+
+export default {
+  name: "pi-modlens",
+  inject: ["piHarnessLaunch", "piTools", "piPluginUi"],
+  apply(context: Context) {
+    let lastImage: { path: string; mimeType: string; bytes: number } | undefined;
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "vision_inspect",
+        label: "Vision inspect",
+        description: "Attach a local image from the current workspace so a vision-capable model can inspect it.",
+        promptSnippet: "attach a local image for visual inspection",
+        parameters: Type.Object({ path: Type.String({ description: "Image path relative to the workspace" }) }),
+        async execute(_toolCallId, params) {
+          const workspace = resolve(context.piHarnessLaunch.cwd);
+          const target = resolve(workspace, params.path);
+          const relativePath = relative(workspace, target);
+          if (relativePath.startsWith("..") || relativePath.includes("/..")) throw new Error("Image path must stay inside the current workspace");
+          const mimeType = mimeByExtension[extname(target).toLowerCase()];
+          if (mimeType === undefined) throw new Error("Unsupported image type; use png, jpeg, gif, or webp");
+          const metadata = await stat(target);
+          if (!metadata.isFile()) throw new Error("Image path is not a file");
+          if (metadata.size > 10 * 1024 * 1024) throw new Error("Image exceeds the 10 MiB attachment limit");
+          const data = (await readFile(target)).toString("base64");
+          lastImage = { path: relativePath || ".", mimeType, bytes: metadata.size };
+          return {
+            content: [{ type: "image", data, mimeType }],
+            details: lastImage,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "modlens-panel",
+      pluginId: "@pi-harness/core/plugins/modlens",
+      title: "视觉桥接",
+      description: "将工作区内的图片安全附加到当前对话，交由支持视觉的模型分析。",
+      icon: "◉",
+      read: () => ({
+        attached: lastImage !== undefined,
+        image: lastImage ?? null,
+        supportedTypes: Object.keys(mimeByExtension).map((extension) => extension.slice(1)),
+      }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/module-search.ts

@@ -0,0 +1,201 @@
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { 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";
+import { resolveExistingWorkspacePath } from "../workspace-path.js";
+
+const maxQueryLength = 120;
+const maxPathLength = 512;
+const maxFileBytes = 2 * 1024 * 1024;
+const maxFiles = 1_000;
+const maxResults = 100;
+const ignoredDirectories = new Set([".git", "node_modules", ".pi", "dist", "build"]);
+const sourceExtensions = new Set([".cjs", ".js", ".jsx", ".mjs", ".ts", ".tsx"]);
+
+export type ModuleMatchKind = "import" | "export" | "symbol";
+export type ModuleMatch = { kind: ModuleMatchKind; name: string; path: string; line: number; text: string };
+export type ModuleSearchKind = ModuleMatchKind | "all";
+export type ModuleSearchReport = {
+  query: string;
+  kind: ModuleSearchKind;
+  path: string;
+  matches: ModuleMatch[];
+  scannedFiles: number;
+  skippedFiles: number;
+  truncated: boolean;
+};
+
+function moduleNames(source: string, kind: ModuleMatchKind): string[] {
+  if (kind === "import") {
+    const named = [...source.matchAll(/\bimport\s*\{([^}]*)\}/gu)].flatMap(
+      (match) =>
+        match[1]
+          ?.split(",")
+          .map(
+            (item) =>
+              item
+                .trim()
+                .split(/\s+as\s+/iu)[0]
+                ?.trim() ?? "",
+          )
+          .filter(Boolean) ?? [],
+    );
+    const defaults = [...source.matchAll(/\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*["']/gu)].map((match) => match[1]!).filter(Boolean);
+    const namespaces = [...source.matchAll(/\bimport\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*["']/gu)].map((match) => match[1]!).filter(Boolean);
+    return [...named, ...defaults, ...namespaces];
+  }
+  if (kind === "export") {
+    const declarations = [...source.matchAll(/\bexport\s+(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\s+([A-Za-z_$][\w$]*)/gu)].map(
+      (match) => match[1]!,
+    );
+    const named = [...source.matchAll(/\bexport\s*\{([^}]*)\}/gu)].flatMap(
+      (match) =>
+        match[1]
+          ?.split(",")
+          .map(
+            (item) =>
+              item
+                .trim()
+                .split(/\s+as\s+/iu)
+                .at(-1)
+                ?.trim() ?? "",
+          )
+          .filter(Boolean) ?? [],
+    );
+    return [...declarations, ...named];
+  }
+  return [...source.matchAll(/\b(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\s+([A-Za-z_$][\w$]*)/gu)]
+    .map((match) => match[1]!)
+    .filter(Boolean);
+}
+
+export function extractModuleMatches(source: string, path: string, query: string, kind: ModuleSearchKind): ModuleMatch[] {
+  const normalizedQuery = query.trim().toLocaleLowerCase();
+  if (normalizedQuery.length < 1 || normalizedQuery.length > maxQueryLength) throw new Error("Module search query must contain 1-120 characters");
+  const kinds: ModuleMatchKind[] = kind === "all" ? ["import", "export", "symbol"] : [kind];
+  return source.split(/\r?\n/u).flatMap((line, index) => {
+    const matches: ModuleMatch[] = [];
+    for (const entryKind of kinds) {
+      if (kind === "all" && entryKind === "symbol" && /\bexport\b/u.test(line)) continue;
+      for (const name of moduleNames(line, entryKind)) {
+        if (!name.toLocaleLowerCase().includes(normalizedQuery)) continue;
+        matches.push({ kind: entryKind, name, path, line: index + 1, text: line });
+      }
+    }
+    return matches;
+  });
+}
+
+async function filesUnder(target: string, root: string, files: string[]): Promise<void> {
+  if (files.length >= maxFiles) return;
+  const metadata = await lstat(target);
+  if (metadata.isSymbolicLink()) return;
+  if (metadata.isFile()) {
+    if (sourceExtensions.has(target.slice(target.lastIndexOf(".")).toLocaleLowerCase())) files.push(target);
+    return;
+  }
+  if (!metadata.isDirectory()) return;
+  const entries = (await readdir(target, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    if (files.length >= maxFiles) return;
+    if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
+    const child = resolve(target, entry.name);
+    await filesUnder(child, root, files);
+  }
+}
+
+export default {
+  name: "pi-module-search",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: ModuleSearchReport | undefined;
+    const search = async (
+      query: string,
+      requestedPath: string | undefined,
+      kind: ModuleSearchKind,
+      requestedLimit: number | undefined,
+    ): Promise<ModuleSearchReport> => {
+      const normalizedQuery = query.trim();
+      if (normalizedQuery.length < 1 || normalizedQuery.length > maxQueryLength) throw new Error("Module search query must contain 1-120 characters");
+      const normalizedKind = kind === "import" || kind === "export" || kind === "symbol" ? kind : "all";
+      const requested = requestedPath?.trim() ?? ".";
+      if (requested.length > maxPathLength || requested.includes("\\"))
+        throw new Error("Module search path must be a relative POSIX path of at most 512 characters");
+      const resolved = await resolveExistingWorkspacePath(context.piHarnessLaunch.cwd, requested, "Module search path must stay inside the current workspace");
+      const root = resolved.root;
+      const target = resolved.target;
+      const targetMetadata = await stat(target);
+      const files: string[] = [];
+      await filesUnder(target, root, files);
+      const limit = Math.max(1, Math.min(maxResults, Math.trunc(requestedLimit ?? maxResults)));
+      const matches: ModuleMatch[] = [];
+      let truncated = false;
+      let scannedFiles = 0;
+      let skippedFiles = targetMetadata.isFile() && targetMetadata.size > maxFileBytes ? 1 : 0;
+      for (const file of files) {
+        if (matches.length >= limit) break;
+        const metadata = await stat(file);
+        if (metadata.size > maxFileBytes) {
+          skippedFiles += 1;
+          continue;
+        }
+        const source = await readFile(file, "utf8");
+        scannedFiles += 1;
+        const fileMatches = extractModuleMatches(source, relative(root, file), normalizedQuery, normalizedKind);
+        const remaining = limit - matches.length;
+        matches.push(...fileMatches.slice(0, remaining));
+        if (fileMatches.length > remaining) truncated = true;
+      }
+      const report: ModuleSearchReport = {
+        query: normalizedQuery,
+        kind: normalizedKind,
+        path: relative(root, target) || ".",
+        matches,
+        scannedFiles,
+        skippedFiles,
+        truncated: truncated || (matches.length >= limit && files.length > scannedFiles + skippedFiles),
+      };
+      latest = report;
+      return report;
+    };
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "module_search",
+        label: "Search modules",
+        description: "Find imports, exports, or declared symbols in bounded workspace source files without modifying them.",
+        promptSnippet: "find a module import, export, or symbol in the workspace",
+        parameters: Type.Object({
+          query: Type.String({ description: "Name fragment to find, 1-120 characters" }),
+          kind: Type.Optional(Type.Union([Type.Literal("all"), Type.Literal("import"), Type.Literal("export"), Type.Literal("symbol")])),
+          path: Type.Optional(Type.String({ description: "Relative workspace path" })),
+          maxResults: Type.Optional(Type.Number({ description: "Maximum matches, 1-100" })),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<ModuleSearchReport>> {
+          const report = await search(params.query, params.path, params.kind ?? "all", params.maxResults);
+          return {
+            content: [
+              {
+                type: "text",
+                text: report.matches.map((match) => `${match.path}:${match.line} ${match.kind} ${match.name}`).join("\n") || "No module matches found.",
+              },
+            ],
+            details: report,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "module-search-panel",
+      pluginId: "@pi-harness/core/plugins/module-search",
+      title: "Module Search",
+      description: "按导入、导出和声明符号检索工作区源码。",
+      icon: "⌕",
+      read: () => ({ latest: latest ?? null, matchCount: latest?.matches.length ?? 0 }),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/obsidian-sync.ts

@@ -0,0 +1,83 @@
+import { lstat, mkdir, realpath, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const maxContentBytes = 512 * 1024;
+const maxRelativePathLength = 512;
+type SyncResult = { relativePath: string; absolutePath: string; bytes: number };
+
+export interface ObsidianSyncPluginConfig {
+  vaultPath?: string;
+}
+
+export const Config: z<ObsidianSyncPluginConfig> = z.object({ vaultPath: z.string().default("") });
+
+function isInside(root: string, target: string): boolean {
+  const remainder = relative(root, target);
+  return remainder === "" || (remainder !== ".." && !remainder.startsWith(`..${"/"}`) && !remainder.startsWith(`..${"\\"}`) && !remainder.startsWith("/"));
+}
+
+export default {
+  name: "pi-obsidian-sync",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: ObsidianSyncPluginConfig) {
+    const configuredVault = config.vaultPath?.trim() ?? "";
+    let last: SyncResult | undefined;
+    const sync = async (relativePath: string, content: string, confirm: boolean): Promise<SyncResult> => {
+      if (configuredVault === "") throw new Error("Obsidian sync requires vaultPath in the plugin configuration");
+      if (!confirm) throw new Error("Obsidian sync requires confirm=true before writing a note");
+      if (relativePath.length === 0 || relativePath.length > maxRelativePathLength || !relativePath.toLowerCase().endsWith(".md"))
+        throw new Error("Obsidian note path must be a relative .md path of at most 512 characters");
+      if (content.length === 0 || Buffer.byteLength(content, "utf8") > maxContentBytes)
+        throw new Error(`Obsidian note content must be between 1 and ${maxContentBytes} bytes`);
+      await mkdir(configuredVault, { recursive: true });
+      const vault = await realpath(configuredVault);
+      const target = resolve(vault, relativePath);
+      if (!isInside(vault, target)) throw new Error("Obsidian note path must stay inside the configured vault");
+      const parent = dirname(target);
+      await mkdir(parent, { recursive: true });
+      if (!isInside(vault, await realpath(parent))) throw new Error("Obsidian note path must stay inside the configured vault");
+      try {
+        if ((await lstat(target)).isSymbolicLink()) throw new Error("Obsidian note target cannot be a symbolic link");
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      await writeFile(target, content, { encoding: "utf8", mode: 0o600 });
+      last = { relativePath, absolutePath: target, bytes: Buffer.byteLength(content, "utf8") };
+      return last;
+    };
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "obsidian_sync",
+        label: "Obsidian sync",
+        description: "Write a confirmed Markdown note inside the configured Obsidian vault.",
+        promptSnippet: "save this result as a Markdown note in the Obsidian vault",
+        parameters: Type.Object({
+          relativePath: Type.String({ description: "Relative .md path inside the configured vault" }),
+          content: Type.String({ description: "Markdown note content" }),
+          confirm: Type.Boolean({ description: "Must be true to write the note" }),
+        }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<SyncResult>> {
+          const result = await sync(params.relativePath, params.content, params.confirm);
+          return { content: [{ type: "text", text: `Obsidian note written: ${result.relativePath}` }], details: result };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "obsidian-sync-panel",
+      pluginId: "@pi-harness/core/plugins/obsidian-sync",
+      title: "Obsidian Sync",
+      description: "将 Agent 产出的 Markdown 安全写入指定 Obsidian vault。",
+      icon: "▤",
+      read: () => ({ configured: configuredVault !== "", vaultPath: configuredVault || null, last: last ?? null }),
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};

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

@@ -0,0 +1,109 @@
+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 customType = "pi-harness/openpets";
+type PetMood = "idle" | "focused" | "happy" | "concerned";
+type PetState = { name: string; mood: PetMood; energy: number; interactions: number; lastEvent: string; updatedAt: string };
+
+export interface OpenPetsPluginConfig {
+  name?: string;
+}
+
+export const Config: z<OpenPetsPluginConfig> = z.object({ name: z.string().default("Pi") });
+
+function clampEnergy(value: number): number {
+  return Math.max(0, Math.min(100, Math.round(value)));
+}
+
+function initialState(name: string): PetState {
+  return { name, mood: "idle", energy: 80, interactions: 0, lastEvent: "session_start", updatedAt: new Date(0).toISOString() };
+}
+
+function readState(context: Context, name: string): PetState {
+  const entry = [...context.piSession.manager.getEntries()].reverse().find((item) => item.type === "custom" && item.customType === customType);
+  if (entry?.type !== "custom" || entry.data === undefined || typeof entry.data !== "object" || entry.data === null) return initialState(name);
+  const value = entry.data as Partial<PetState>;
+  const mood: PetMood = value.mood === "focused" || value.mood === "happy" || value.mood === "concerned" ? value.mood : "idle";
+  return {
+    name: typeof value.name === "string" && value.name.trim() !== "" ? value.name : name,
+    mood,
+    energy: typeof value.energy === "number" ? clampEnergy(value.energy) : 80,
+    interactions: typeof value.interactions === "number" && Number.isFinite(value.interactions) ? Math.max(0, Math.trunc(value.interactions)) : 0,
+    lastEvent: typeof value.lastEvent === "string" ? value.lastEvent : "session_start",
+    updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date(0).toISOString(),
+  };
+}
+
+function persist(context: Context, state: PetState): void {
+  context.piSession.manager.appendCustomEntry(customType, state);
+}
+
+export default {
+  name: "pi-openpets",
+  inject: ["piSession", "piPluginUi", "piTools"],
+  Config,
+  apply(context: Context, config: OpenPetsPluginConfig) {
+    const name = config.name?.trim() || "Pi";
+    let state = readState(context, name);
+    const update = (next: Partial<PetState>, persistState = true): PetState => {
+      state = { ...state, ...next, name, updatedAt: new Date().toISOString() };
+      if (persistState) persist(context, state);
+      return state;
+    };
+    const unsubscribe = context.on("pi/session-event", (event) => {
+      if (event.type === "agent_start") update({ mood: "focused", energy: clampEnergy(state.energy - 5), lastEvent: event.type });
+      else if (event.type === "agent_end") update({ mood: "happy", energy: clampEnergy(state.energy + 5), lastEvent: event.type });
+      else if (event.type === "tool_execution_end" && "isError" in event && event.isError === true) update({ mood: "concerned", lastEvent: event.type });
+    });
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "pet_react",
+        label: "Pet companion",
+        description: "Read or update the local OpenPets companion state for the current Pi session.",
+        promptSnippet: "check the companion state or let the pet react",
+        parameters: Type.Object({
+          action: Type.Union([Type.Literal("status"), Type.Literal("feed"), Type.Literal("play"), Type.Literal("set_mood")]),
+          mood: Type.Optional(Type.String()),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<PetState>> {
+          return Promise.resolve().then(() => {
+            if (params.action === "status")
+              return { content: [{ type: "text" as const, text: `${state.name}: ${state.mood}, energy ${state.energy}` }], details: state };
+            if (params.action === "feed")
+              return {
+                content: [{ type: "text" as const, text: `${state.name} is refreshed.` }],
+                details: update({ mood: "happy", energy: 100, interactions: state.interactions + 1, lastEvent: "feed" }),
+              };
+            if (params.action === "play")
+              return {
+                content: [{ type: "text" as const, text: `${state.name} had a play break.` }],
+                details: update({ mood: "happy", energy: clampEnergy(state.energy + 10), interactions: state.interactions + 1, lastEvent: "play" }),
+              };
+            const mood = params.mood?.trim();
+            if (mood !== "idle" && mood !== "focused" && mood !== "happy" && mood !== "concerned")
+              throw new Error("mood must be idle, focused, happy, or concerned");
+            return {
+              content: [{ type: "text" as const, text: `${state.name} mood set to ${mood}.` }],
+              details: update({ mood, interactions: state.interactions + 1, lastEvent: "set_mood" }),
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "openpets-panel",
+      pluginId: "@pi-harness/core/plugins/openpets",
+      title: "OpenPets",
+      description: "根据 Pi 会话事件反应的本地桌面伙伴状态。",
+      icon: "◉",
+      read: () => state,
+    });
+    context.effect(() => () => {
+      unsubscribe();
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};