@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/dist/workspace-path.d.ts

@@ -0,0 +1,12 @@
+export interface WorkspacePath {
+    readonly root: string;
+    readonly target: string;
+    readonly relativePath: string;
+}
+export interface WorkspaceFilePath extends WorkspacePath {
+    readonly exists: boolean;
+}
+export declare function isPathInside(root: string, target: string): boolean;
+export declare function resolveExistingWorkspacePath(root: string, requested: string, message: string): Promise<WorkspacePath>;
+export declare function prepareWorkspaceFile(root: string, requested: string, message: string): Promise<WorkspaceFilePath>;
+//# sourceMappingURL=workspace-path.d.ts.map

package/packages/core/dist/workspace-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-path.d.ts","sourceRoot":"","sources":["../src/workspace-path.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGlE;AAMD,wBAAsB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAO3H;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqCvH"}

package/packages/core/dist/workspace-path.js

@@ -0,0 +1,62 @@
+import { lstat, mkdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+export function isPathInside(root, target) {
+    const remainder = relative(root, target);
+    return remainder === "" || (remainder !== ".." && !remainder.startsWith(`..${sep}`) && !isAbsolute(remainder));
+}
+function assertInside(root, target, message) {
+    if (!isPathInside(root, target))
+        throw new Error(message);
+}
+export async function resolveExistingWorkspacePath(root, requested, message) {
+    const canonicalRoot = await realpath(resolve(root));
+    const lexicalTarget = resolve(canonicalRoot, requested);
+    assertInside(canonicalRoot, lexicalTarget, message);
+    const target = await realpath(lexicalTarget);
+    assertInside(canonicalRoot, target, message);
+    return { root: canonicalRoot, target, relativePath: relative(canonicalRoot, target) || "." };
+}
+export async function prepareWorkspaceFile(root, requested, message) {
+    const canonicalRoot = await realpath(resolve(root));
+    const lexicalTarget = resolve(canonicalRoot, requested);
+    assertInside(canonicalRoot, lexicalTarget, message);
+    let ancestor = dirname(lexicalTarget);
+    const missing = [];
+    let canonicalAncestor;
+    for (;;) {
+        try {
+            canonicalAncestor = await realpath(ancestor);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            missing.unshift(basename(ancestor));
+            ancestor = parent;
+        }
+    }
+    assertInside(canonicalRoot, canonicalAncestor, message);
+    if (!(await stat(canonicalAncestor)).isDirectory())
+        throw new Error(message);
+    const parent = join(canonicalAncestor, ...missing);
+    await mkdir(parent, { recursive: true });
+    const canonicalParent = await realpath(parent);
+    assertInside(canonicalRoot, canonicalParent, message);
+    const target = join(canonicalParent, basename(lexicalTarget));
+    let exists = false;
+    try {
+        const metadata = await lstat(target);
+        if (metadata.isSymbolicLink() || !metadata.isFile())
+            throw new Error(message);
+        exists = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return { root: canonicalRoot, target, relativePath: relative(canonicalRoot, target), exists };
+}
+//# sourceMappingURL=workspace-path.js.map

package/packages/core/dist/workspace-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-path.js","sourceRoot":"","sources":["../src/workspace-path.ts"],"names":[],"mappings":"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"}

package/packages/core/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@pi-harness/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Cordis boot and Pi runtime plugins for Pi Harness",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pi-harness/pi-harness.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/pi-harness/pi-harness#readme",
+  "bugs": {
+    "url": "https://github.com/pi-harness/pi-harness/issues"
+  },
+  "files": [
+    "dist",
+    "profiles"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,13 +30,6 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "profiles"
-  ],
-  "engines": {
-    "node": ">=22.19.0"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -40,5 +47,8 @@
     "@earendil-works/pi-agent-core": "0.84.4",
     "@earendil-works/pi-ai": "0.84.4",
     "@earendil-works/pi-coding-agent": "0.84.4"
+  },
+  "engines": {
+    "node": ">=22.19.0"
   }
 }

package/packages/core/profiles/default/cordis.yml

@@ -26,10 +26,95 @@
           - bash
           - edit
           - write
+    - id: agent-teams
+      name: "@pi-harness/core/plugins/agent-teams"
+      config: {}
+    - id: modlens
+      name: "@pi-harness/core/plugins/modlens"
+      config: {}
+    - id: vision-toolkit
+      name: "@pi-harness/core/plugins/vision-toolkit"
+      config: {}
+    - id: git-time-capsule
+      name: "@pi-harness/core/plugins/git-time-capsule"
+      config: {}
+    - id: dependency-checker
+      name: "@pi-harness/core/plugins/dependency-checker"
+      config: {}
+    - id: at-file
+      name: "@pi-harness/core/plugins/at-file"
+      config: {}
+    - id: test-harness
+      name: "@pi-harness/core/plugins/test-harness"
+      config: {}
+    - id: session-insights
+      name: "@pi-harness/core/plugins/session-insights"
+      config: {}
+    - id: readme-gen
+      name: "@pi-harness/core/plugins/readme-gen"
+      config: {}
+    - id: i18n-pair
+      name: "@pi-harness/core/plugins/i18n-pair"
+      config: {}
+    - id: cleaner
+      name: "@pi-harness/core/plugins/cleaner"
+      config: {}
+    - id: sql-lens
+      name: "@pi-harness/core/plugins/sql-lens"
+      config: {}
+    - id: docker-sandbox
+      name: "@pi-harness/core/plugins/docker-sandbox"
+      config: {}
+    - id: mcp-client
+      name: "@pi-harness/core/plugins/mcp-client"
+      config: {}
+    - id: browser-fetch
+      name: "@pi-harness/core/plugins/browser-fetch"
+      config: {}
+    - id: browser-session
+      name: "@pi-harness/core/plugins/browser-session"
+      config: {}
+    - id: plugin-stars
+      name: "@pi-harness/core/plugins/plugin-stars"
+      config: {}
+    - id: yaml-validator
+      name: "@pi-harness/core/plugins/yaml-validator"
+      config: {}
+    - id: plugin-dev
+      name: "@pi-harness/core/plugins/plugin-dev"
+      config: {}
+    - id: openpets
+      name: "@pi-harness/core/plugins/openpets"
+      config: {}
+    - id: session-bridge
+      name: "@pi-harness/core/plugins/session-bridge"
+      config: {}
+    - id: skill-guard
+      name: "@pi-harness/core/plugins/skill-guard"
+      config: {}
+    - id: recall-unread
+      name: "@pi-harness/core/plugins/recall-unread"
+      config: {}
+    - id: turn-rewind
+      name: "@pi-harness/core/plugins/turn-rewind"
+      config: {}
+    - id: context-doctor
+      name: "@pi-harness/core/plugins/context-doctor"
+      config: {}
     - id: runtime
       name: "@pi-harness/core/plugins/runtime"
       config:
         thinkingLevel: medium
+    - id: context
+      name: "@pi-harness/core/plugins/context"
+      config: {}
+    - id: token-guard
+      name: "@pi-harness/core/plugins/token-guard"
+      config:
+        maxPercent: 90
+    - id: fail-logger
+      name: "@pi-harness/core/plugins/fail-logger"
+      config: {}
     - id: stdio
       name: "@pi-harness/core/plugins/stdio"
       config: {}

package/packages/core/profiles/development/cordis.yml

@@ -7,7 +7,7 @@
 - id: hmr
   name: "@deepseek-ai/cordis-plugin-hmr"
   config:
-    base: !!js piHarnessLaunch.cwd
+    base: !!js piHarnessLaunch.cwdUrl
     root:
       - .
 - id: agent

package/packages/core/src/boot.ts

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Context, type FiberState } from "@deepseek-ai/cordis";
@@ -5,8 +6,39 @@ import Group from "@deepseek-ai/cordis-plugin-group";
 import Include from "@deepseek-ai/cordis-plugin-include";
 import Loader, { type EntryOptions } from "@deepseek-ai/cordis-plugin-loader";
 
+function assertUniqueEntryIds(entries: readonly EntryOptions[], seen = new Map<string, string>()): void {
+  for (const entry of entries) {
+    if (typeof entry.id === "string" && entry.id.length > 0) {
+      const previous = seen.get(entry.id);
+      if (previous !== undefined) throw new Error(`Duplicate loader entry id "${entry.id}" is used by both ${previous} and ${entry.name}; ids must be unique across the whole profile because nested groups share their tree's entry store`);
+      seen.set(entry.id, entry.name);
+    }
+    if (entry.group === true && Array.isArray(entry.config)) assertUniqueEntryIds(entry.config as EntryOptions[], seen);
+  }
+}
+
 class ReadonlyInclude extends Include {
+  constructor(ctx: Context, config: Include.Config) {
+    super(ctx, config);
+    const update = this.root.update.bind(this.root);
+    this.root.update = async (entries: EntryOptions[]) => {
+      assertUniqueEntryIds(entries);
+      await update(entries);
+    };
+  }
+
   override write(): void {}
+
+  override import(name: string, getOuterStack?: () => string[]): unknown {
+    if (this.ctx.loader.internal !== undefined || name.startsWith("cordis:") || name.startsWith(".") || name.startsWith("/") || name.includes("://")) return super.import(name, getOuterStack);
+    let resolved: string;
+    try {
+      resolved = createRequire(this.filename).resolve(name);
+    } catch {
+      return super.import(name, getOuterStack);
+    }
+    return super.import(pathToFileURL(resolved).href, getOuterStack);
+  }
 }
 
 export interface BootHarnessOptions {
@@ -26,7 +58,10 @@ const FIBER_ACTIVE = 2 as FiberState.ACTIVE;
 const FIBER_FAILED = 3 as FiberState.FAILED;
 
 function formatError(error: unknown): string {
-  return error instanceof Error ? error.stack ?? error.message : String(error);
+  if (error instanceof AggregateError) return error.errors.map(formatError).join("\n");
+  if (!(error instanceof Error)) return String(error);
+  const own = error.stack ?? error.message;
+  return error.cause === undefined ? own : `${own}\ncaused by: ${formatError(error.cause)}`;
 }
 
 async function assertEntriesActivated(context: Context): Promise<void> {
@@ -87,7 +122,8 @@ export async function bootHarness(options: BootHarnessOptions): Promise<BootedHa
     stage = "plugin tree activation";
     await mountProfile(context, configPath);
     await context.get("loader")?.await();
-    if (context.get("loader") !== undefined) await assertEntriesActivated(context);
+    await assertEntriesActivated(context);
+    if (options.signal?.aborted === true) throw new Error("Pi Harness startup was aborted", { cause: options.signal.reason });
   } catch (cause) {
     await context.fiber.dispose();
     throw new Error(`Pi Harness ${stage} failed: ${formatError(cause)}`, { cause });

package/packages/core/src/config.ts

@@ -0,0 +1,5 @@
+export function assertKnownConfigKeys(plugin: string, config: unknown, known: readonly string[]): void {
+  if (config === undefined || config === null || typeof config !== "object") return;
+  const unknown = Object.keys(config).filter((key) => !known.includes(key));
+  if (unknown.length > 0) throw new Error(`Unknown ${plugin} config keys: ${unknown.join(", ")}; supported keys are ${known.length === 0 ? "(none)" : known.join(", ")}`);
+}

package/packages/core/src/http.ts

@@ -0,0 +1,32 @@
+import type { AgentSessionServices } from "@earendil-works/pi-coding-agent";
+
+interface HttpDispatcherModule {
+  applyHttpProxySettings(httpProxy: string | undefined): void;
+  configureHttpDispatcher(timeoutMs?: number): void;
+}
+
+// Pi installs an undici EnvHttpProxyAgent so provider calls honour HTTP(S)_PROXY and the
+// settings-level httpProxy. Its package exports map does not expose that module, so it is
+// imported by the file URL derived from the package entry: that keeps one undici instance
+// shared with Pi, which a direct undici dependency of our own would not.
+async function loadHttpDispatcher(): Promise<HttpDispatcherModule> {
+  const entry = import.meta.resolve("@earendil-works/pi-coding-agent");
+  return await import(new URL("./core/http-dispatcher.js", entry).href) as HttpDispatcherModule;
+}
+
+/**
+ * Route provider traffic through the proxy the environment or Pi's settings configure.
+ *
+ * @returns undefined on success, or a diagnostic message when Pi's dispatcher module could not be loaded.
+ */
+export async function configureHttpProxy(services?: AgentSessionServices): Promise<string | undefined> {
+  let dispatcher: HttpDispatcherModule;
+  try {
+    dispatcher = await loadHttpDispatcher();
+  } catch (cause) {
+    return `Pi HTTP dispatcher is unavailable, so HTTP_PROXY, HTTPS_PROXY and the httpProxy setting are ignored: ${cause instanceof Error ? cause.message : String(cause)}`;
+  }
+  if (services !== undefined) dispatcher.applyHttpProxySettings(services.settingsManager.getGlobalSettings().httpProxy);
+  dispatcher.configureHttpDispatcher(services?.settingsManager.getHttpIdleTimeoutMs());
+  return undefined;
+}

package/packages/core/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./boot.js";
+export * from "./config.js";
+export * from "./http.js";
 export type * from "./context.js";
 export * from "./profile.js";
 export * from "./runtime.js";

package/packages/core/src/plugins/agent-teams.ts

@@ -0,0 +1,291 @@
+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/agent-teams";
+export type TeamTask = { id: string; title: string; assignee: string; status: string; dependsOn: string[] };
+type TeamMessage = { id: string; from: string; to: string; body: string; timestamp: string; read: boolean };
+type TeamState = {
+  members: { id: string; name: string; role: string; status: string }[];
+  tasks: TeamTask[];
+  messages: TeamMessage[];
+};
+
+export function dependencyCycle(tasks: readonly TeamTask[]): string[] | null {
+  const byId = new Map(tasks.map((task) => [task.id, task]));
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const path: string[] = [];
+  const visit = (id: string): string[] | null => {
+    if (visiting.has(id)) {
+      const start = path.indexOf(id);
+      return start >= 0 ? [...path.slice(start), id] : [id, id];
+    }
+    if (visited.has(id)) return null;
+    const task = byId.get(id);
+    if (task === undefined) {
+      visited.add(id);
+      return null;
+    }
+    visiting.add(id);
+    path.push(id);
+    for (const dependency of task.dependsOn) {
+      const cycle = visit(dependency);
+      if (cycle !== null) return cycle;
+    }
+    path.pop();
+    visiting.delete(id);
+    visited.add(id);
+    return null;
+  };
+  for (const task of tasks) {
+    const cycle = visit(task.id);
+    if (cycle !== null) return cycle;
+  }
+  return null;
+}
+
+export function readyTeamTasks(tasks: readonly TeamTask[]): TeamTask[] {
+  const completed = new Set(tasks.filter((task) => task.status === "done").map((task) => task.id));
+  return tasks.filter((task) => task.status === "todo" && task.dependsOn.every((dependency) => completed.has(dependency)));
+}
+
+const initialState = (): TeamState => ({
+  members: [
+    { id: "planner", name: "Planner", role: "拆解任务", status: "idle" },
+    { id: "builder", name: "Builder", role: "实现改动", status: "idle" },
+    { id: "reviewer", name: "Reviewer", role: "验证结果", status: "idle" },
+  ],
+  tasks: [],
+  messages: [],
+});
+
+function readState(context: Context): TeamState {
+  const entries = context.piSession.manager.getEntries();
+  const entry = [...entries].reverse().find((item) => item.type === "custom" && item.customType === customType);
+  if (entry?.type !== "custom" || entry.data === undefined) return initialState();
+  const value = entry.data as Partial<TeamState>;
+  if (!Array.isArray(value.members) || !Array.isArray(value.tasks)) return initialState();
+  const tasks = value.tasks.map((task, index) => {
+    const item = task as Partial<TeamTask>;
+    return {
+      id: typeof item.id === "string" && item.id.trim() !== "" ? item.id : `task-${index + 1}`,
+      title: typeof item.title === "string" ? item.title : "未命名任务",
+      assignee: typeof item.assignee === "string" ? item.assignee : "unassigned",
+      status: typeof item.status === "string" ? item.status : "todo",
+      dependsOn: Array.isArray(item.dependsOn) ? item.dependsOn.filter((id): id is string => typeof id === "string" && id.trim() !== "") : [],
+    };
+  });
+  const messages = Array.isArray(value.messages)
+    ? value.messages.flatMap((message, index) => {
+        const item = message as Partial<TeamMessage>;
+        if (typeof item.from !== "string" || typeof item.to !== "string" || typeof item.body !== "string") return [];
+        return [
+          {
+            id: typeof item.id === "string" && item.id.trim() !== "" ? item.id : `message-${index + 1}`,
+            from: item.from,
+            to: item.to,
+            body: item.body,
+            timestamp: typeof item.timestamp === "string" ? item.timestamp : new Date(0).toISOString(),
+            read: item.read === true,
+          },
+        ];
+      })
+    : [];
+  return structuredClone({ members: value.members, tasks, messages });
+}
+
+function persist(context: Context, state: TeamState): void {
+  context.piSession.manager.appendCustomEntry(customType, state);
+}
+
+function refreshTaskReadiness(state: TeamState): void {
+  const completed = new Set(state.tasks.filter((task) => task.status === "done").map((task) => task.id));
+  for (const task of state.tasks) {
+    if (task.status === "blocked" && task.dependsOn.every((id) => completed.has(id))) task.status = "todo";
+    if ((task.status === "todo" || task.status === "blocked") && task.dependsOn.some((id) => !completed.has(id))) task.status = "blocked";
+  }
+}
+
+function syncMemberStatuses(state: TeamState): void {
+  const activeAssignees = new Set(state.tasks.filter((task) => task.status === "in_progress").map((task) => task.assignee));
+  for (const member of state.members) {
+    if (member.status === "working" || activeAssignees.has(member.id)) member.status = activeAssignees.has(member.id) ? "working" : "idle";
+  }
+}
+
+function nextReadyTask(state: TeamState, assignee: string): TeamTask {
+  refreshTaskReadiness(state);
+  const task = readyTeamTasks(state.tasks)[0];
+  if (task === undefined) throw new Error("No ready team task is available");
+  task.status = "in_progress";
+  task.assignee = assignee || task.assignee;
+  return task;
+}
+
+export default {
+  name: "pi-agent-teams",
+  inject: ["piSession", "piTools", "piPluginUi"],
+  apply(context: Context) {
+    const unregisterTool = context.piTools.register(
+      defineTool({
+        name: "team_task",
+        label: "Team task",
+        description: "Create or update durable agent-team members, tasks, and mailbox messages in the current Pi session.",
+        promptSnippet: "manage durable team members, tasks, and mailbox messages",
+        parameters: Type.Object({
+          action: Type.String({ description: "add_task, update_task, claim_task, add_member, send_message, or read_messages" }),
+          id: Type.Optional(Type.String()),
+          title: Type.Optional(Type.String()),
+          assignee: Type.Optional(Type.String()),
+          name: Type.Optional(Type.String()),
+          role: Type.Optional(Type.String()),
+          status: Type.Optional(Type.String()),
+          dependsOn: Type.Optional(Type.Array(Type.String())),
+          from: Type.Optional(Type.String()),
+          to: Type.Optional(Type.String()),
+          body: Type.Optional(Type.String()),
+          unreadOnly: Type.Optional(Type.Boolean()),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<unknown>> {
+          return Promise.resolve().then(() => {
+            const state = readState(context);
+            if (params.action === "add_task") {
+              const title = params.title?.trim();
+              if (!title) throw new Error("title is required when action is add_task");
+              const id = params.id?.trim() || `task-${state.tasks.length + 1}`;
+              if (state.tasks.some((item) => item.id === id)) throw new Error(`Task already exists: ${id}`);
+              const dependsOn = [...new Set((params.dependsOn ?? []).map((item) => item.trim()).filter(Boolean))];
+              if (dependsOn.includes(id)) throw new Error("A task cannot depend on itself");
+              if (dependsOn.some((dependency) => !state.tasks.some((item) => item.id === dependency)))
+                throw new Error("All task dependencies must already exist");
+              const task = {
+                id,
+                title,
+                assignee: params.assignee?.trim() || "unassigned",
+                status: params.status?.trim() || "todo",
+                dependsOn,
+              };
+              state.tasks.push(task);
+              const cycle = dependencyCycle(state.tasks);
+              if (cycle !== null) {
+                state.tasks.pop();
+                throw new Error(`Task dependency cycle detected: ${cycle.join(" → ")}`);
+              }
+              refreshTaskReadiness(state);
+              syncMemberStatuses(state);
+              persist(context, state);
+              return { content: [{ type: "text" as const, text: `Task ${task.id} created.` }], details: { kind: "task", item: task } };
+            }
+            if (params.action === "update_task") {
+              const task = state.tasks.find((item) => item.id === params.id);
+              if (!task) throw new Error(`Task not found: ${params.id ?? ""}`);
+              if (params.title?.trim()) task.title = params.title.trim();
+              if (params.assignee?.trim()) task.assignee = params.assignee.trim();
+              if (params.dependsOn !== undefined) {
+                const dependsOn = [...new Set(params.dependsOn.map((item) => item.trim()).filter(Boolean))];
+                if (dependsOn.includes(task.id)) throw new Error("A task cannot depend on itself");
+                if (dependsOn.some((dependency) => !state.tasks.some((item) => item.id === dependency)))
+                  throw new Error("All task dependencies must already exist");
+                const previous = task.dependsOn;
+                task.dependsOn = dependsOn;
+                const cycle = dependencyCycle(state.tasks);
+                if (cycle !== null) {
+                  task.dependsOn = previous;
+                  throw new Error(`Task dependency cycle detected: ${cycle.join(" → ")}`);
+                }
+              }
+              if (params.status?.trim()) {
+                if (
+                  params.status.trim() === "done" &&
+                  task.dependsOn.some((dependency) => state.tasks.find((item) => item.id === dependency)?.status !== "done")
+                )
+                  throw new Error("A task cannot be completed before its dependencies");
+                task.status = params.status.trim();
+              }
+              refreshTaskReadiness(state);
+              syncMemberStatuses(state);
+              persist(context, state);
+              return { content: [{ type: "text" as const, text: `Task ${task.id} updated.` }], details: { kind: "task", item: task } };
+            }
+            if (params.action === "claim_task") {
+              const task = nextReadyTask(state, params.assignee?.trim() || "unassigned");
+              const member = state.members.find((item) => item.id === task.assignee);
+              if (member !== undefined) member.status = "working";
+              syncMemberStatuses(state);
+              persist(context, state);
+              return { content: [{ type: "text" as const, text: `Task ${task.id} claimed.` }], details: { kind: "task", item: task } };
+            }
+            if (params.action === "add_member") {
+              const name = params.name?.trim();
+              if (!name) throw new Error("name is required when action is add_member");
+              const member = {
+                id: params.id?.trim() || name.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
+                name,
+                role: params.role?.trim() || "协作成员",
+                status: params.status?.trim() || "idle",
+              };
+              if (state.members.some((item) => item.id === member.id)) throw new Error(`Member already exists: ${member.id}`);
+              state.members.push(member);
+              persist(context, state);
+              return { content: [{ type: "text" as const, text: `Member ${member.name} added.` }], details: { kind: "member", item: member } };
+            }
+            if (params.action === "send_message") {
+              const from = params.from?.trim();
+              const to = params.to?.trim();
+              const body = params.body?.trim();
+              if (!from || !to || !body) throw new Error("from, to, and body are required when action is send_message");
+              if (!state.members.some((item) => item.id === from)) throw new Error(`Unknown sender: ${from}`);
+              if (!state.members.some((item) => item.id === to)) throw new Error(`Unknown recipient: ${to}`);
+              if (body.length > 4000) throw new Error("Message body must be 4000 characters or fewer");
+              const message: TeamMessage = {
+                id: `message-${state.messages.length + 1}`,
+                from,
+                to,
+                body,
+                timestamp: new Date().toISOString(),
+                read: false,
+              };
+              state.messages.push(message);
+              persist(context, state);
+              return { content: [{ type: "text" as const, text: `Message ${message.id} sent.` }], details: { kind: "message", item: message } };
+            }
+            if (params.action === "read_messages") {
+              const to = params.to?.trim();
+              if (!to) throw new Error("to is required when action is read_messages");
+              if (!state.members.some((item) => item.id === to)) throw new Error(`Unknown recipient: ${to}`);
+              const messages = state.messages.filter((message) => message.to === to && (!params.unreadOnly || !message.read));
+              for (const message of messages) message.read = true;
+              if (messages.length > 0) persist(context, state);
+              return {
+                content: [{ type: "text" as const, text: `${messages.length} message${messages.length === 1 ? "" : "s"} read.` }],
+                details: { kind: "mailbox", messages },
+              };
+            }
+            throw new Error(`Unknown team action: ${params.action}`);
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "agent-teams-panel",
+      pluginId: "@pi-harness/core/plugins/agent-teams",
+      title: "Agent Teams",
+      description: "查看协作成员、任务状态和当前会话中的持久化任务队列。",
+      icon: "◎",
+      read: () => {
+        const state = readState(context);
+        const cycle = dependencyCycle(state.tasks);
+        return {
+          ...state,
+          readyTasks: readyTeamTasks(state.tasks).map((task) => task.id),
+          dependencyCycle: cycle,
+        };
+      },
+    });
+    context.effect(() => () => {
+      unregisterTool();
+      disposePanel();
+    });
+  },
+};