pi-extended-teams 2.1.16

package/extensions/tools/predefined-tools.ts

@@ -0,0 +1,331 @@
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "../internal/schema";
+import { buildPiCommand, getPiLaunchCommand } from "../internal/pi-command";
+import { getModelSelectionState, requireQualifiedKnownModel } from "../internal/model-selection";
+import * as predefined from "../../src/utils/predefined-teams";
+import * as teams from "../../src/utils/teams";
+import * as messaging from "../../src/utils/messaging";
+import * as runtime from "../../src/utils/runtime";
+import * as paths from "../../src/utils/paths";
+import { loadSettings, normalizeFavoriteModelSlot, requireFavoriteModelLevel } from "../../src/utils/settings";
+import type { Member } from "../../src/utils/models";
+import { requestLeadForTeammateSpawn } from "./delegation-guard";
+import { createSpawnResourcePlan, parentProjectTrustForSpawn } from "../resources/spawn-resource-plan";
+import { generateExtensionInstanceId, withLifecycleTombstoneLock } from "../../src/utils/lifecycle-tombstone";
+import { cleanupPrivateAgentSessionDirectory, preparePrivateAgentSessionDirectory } from "../internal/agent-session-files";
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function stopAndVerifySpawnedPane(terminal: any, paneId: string): string | null {
+  let killError: unknown;
+  try {
+    terminal.kill(paneId);
+  } catch (error) {
+    killError = error;
+  }
+
+  if (typeof terminal.isAlive !== "function") {
+    return `Could not verify termination of spawned pane ${paneId}: terminal.isAlive is unavailable${killError ? ` after kill failed: ${errorText(killError)}` : ""}.`;
+  }
+
+  try {
+    const alive = terminal.isAlive(paneId);
+    if (alive === false) return null;
+    if (alive === true) {
+      return `Could not verify termination of spawned pane ${paneId}: the terminal still reports it alive${killError ? ` after kill failed: ${errorText(killError)}` : ""}.`;
+    }
+    return `Could not verify termination of spawned pane ${paneId}: terminal.isAlive returned a non-boolean result.`;
+  } catch (error) {
+    return `Could not verify termination of spawned pane ${paneId}: terminal.isAlive failed: ${errorText(error)}${killError ? `; kill also failed: ${errorText(killError)}` : ""}.`;
+  }
+}
+
+export interface PredefinedToolsOptions {
+  terminal: any;
+  adoptTeamAsLead(teamName: string, ctx?: any): void;
+  isTeammate: boolean;
+  agentName: string;
+  getTeamName(): string | null | undefined;
+}
+
+export function registerPredefinedTools(pi: any, options: PredefinedToolsOptions): void {
+  const extensionInstanceId = generateExtensionInstanceId();
+
+  pi.registerTool({
+    name: "list_predefined_teams",
+    label: "List Predefined Teams",
+    description: "List all available predefined team configurations from teams.yaml files. These are team templates that can be instantiated with create_predefined_team.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId: string, _params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
+      const projectDir = ctx.cwd;
+      const predefinedTeams = predefined.getAllPredefinedTeams(projectDir);
+      const agents = predefined.getAllAgentDefinitions(projectDir);
+      const result = predefinedTeams.map(team => ({
+        name: team.name,
+        agents: team.agents.map(agentName => {
+          const agentDef = agents.find(a => a.name === agentName);
+          return { name: agentName, description: agentDef?.description || "(agent definition not found)", found: !!agentDef };
+        }),
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: { teams: result } };
+    },
+  });
+
+  pi.registerTool({
+    name: "list_predefined_agents",
+    label: "List Predefined Agents",
+    description: "List all available predefined agent definitions from .md files. These can be used individually or as part of predefined teams.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId: string, _params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
+      const projectDir = ctx.cwd;
+      const agents = predefined.getAllAgentDefinitions(projectDir);
+      const result = agents.map(agent => ({ name: agent.name, description: agent.description, tools: agent.tools, model: agent.model, thinking: agent.thinking }));
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: { agents: result } };
+    },
+  });
+
+  pi.registerTool({
+    name: "create_predefined_team",
+    label: "Create Predefined Team",
+    description: "Create a team from a predefined team configuration by configured intent tier only. model_slot selects write-agent behavior, model, and thinking; it defaults to write-critical. Canonical tiers are reported outward; minor-release compatibility aliases remain accepted. Direct model/thinking/default_model overrides are not allowed.",
+    parameters: Type.Object({
+      team_name: Type.String({ description: "Name for the new team instance" }),
+      predefined_team: Type.String({ description: "Name of the predefined team template from teams.yaml" }),
+      cwd: Type.String({ description: "Working directory for spawned agents" }),
+      model_slot: Type.Optional(Type.String({ description: "Configured write-* intent tier from /agents-favorite-models. Defaults to write-critical; legacy compatibility aliases are accepted." })),
+    }),
+    async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
+      if (options.isTeammate) {
+        return requestLeadForTeammateSpawn(options, {
+          action: "create_predefined_team",
+          params,
+          reason: "Teammate attempted to create a predefined team directly.",
+        });
+      }
+
+      const projectDir = ctx.cwd;
+      const predefinedTeam = predefined.getPredefinedTeam(params.predefined_team, projectDir);
+      if (!predefinedTeam) {
+        const available = predefined.getAllPredefinedTeams(projectDir).map(t => t.name);
+        throw new Error(`Predefined team "${params.predefined_team}" not found. Available teams: ${available.join(", ") || "none"}`);
+      }
+      if (!options.terminal) throw new Error("pi-extended-teams requires running inside tmux.");
+
+      if (params.default_model || params.model || params.thinking || params.role) {
+        throw new Error("create_predefined_team must use model_slot only; direct model, thinking, role, or default_model is not allowed.");
+      }
+      const settings = loadSettings({ projectDir: ctx.cwd });
+      const agentSettings = loadSettings({ projectDir: params.cwd });
+      const requestedSlot = params.model_slot ?? "write-critical";
+      const canonicalSlot = normalizeFavoriteModelSlot(requestedSlot);
+      const level = requireFavoriteModelLevel(settings, canonicalSlot ?? requestedSlot);
+      if (level.role !== "write") throw new Error(`create_predefined_team requires a write-* intent tier configured via /agents-favorite-models, got ${level.slot}.`);
+      const { availableModels } = await getModelSelectionState(ctx, ctx.cwd, [level.model]);
+      const defaultModel = requireQualifiedKnownModel(level.model, availableModels, "model_slot");
+      if (!defaultModel) throw new Error(`Intent tier ${level.slot} resolved to unavailable model ${level.model}.`);
+      const resourcePlan = createSpawnResourcePlan({
+        cwd: params.cwd,
+        projectTrusted: parentProjectTrustForSpawn(ctx, params.cwd),
+        pi,
+      });
+
+      let config;
+      try {
+        config = teams.createTeamIfAbsent(params.team_name, "local-session", "lead-agent", `Predefined team: ${params.predefined_team}`, defaultModel);
+      } catch (error) {
+        if (!(error instanceof teams.TeamAlreadyExistsError)) throw error;
+        throw new Error(`Team "${params.team_name}" already exists. Choose a different team_name, or stop that team first.`);
+      }
+      options.adoptTeamAsLead(paths.sanitizeName(params.team_name), ctx);
+
+      const agentDefinitions = predefined.getAllAgentDefinitions(projectDir);
+      const spawnResults: Array<{ name: string; status: string; error?: string }> = [];
+      for (const agentName of predefinedTeam.agents) {
+        const agentDef = agentDefinitions.find(a => a.name === agentName);
+        if (!agentDef) {
+          spawnResults.push({ name: agentName, status: "skipped", error: "Agent definition not found" });
+          continue;
+        }
+
+        try {
+          const safeName = paths.sanitizeName(agentName);
+          const safeTeamName = paths.sanitizeName(params.team_name);
+          if (agentDef.model || agentDef.thinking) {
+            throw new Error(`Predefined agent \"${agentName}\" must not declare direct model or thinking; choose model_slot when creating the team.`);
+          }
+          const chosenModel = defaultModel || config.defaultModel;
+          if (!chosenModel) throw new Error(`No configured model found for intent tier ${level.slot}.`);
+
+          const member: Member = {
+            agentId: `${safeName}@${safeTeamName}`,
+            name: safeName,
+            agentType: "teammate",
+            role: "write",
+            model: chosenModel,
+            joinedAt: Date.now(),
+            tmuxPaneId: "",
+            cwd: params.cwd,
+            subscriptions: [],
+            prompt: agentDef.prompt,
+            color: "blue",
+            thinking: level.thinking,
+            modelSlot: level.slot,
+          };
+
+          await teams.addMember(safeTeamName, member);
+          const runId = member.lifecycleRunId!;
+          const bootstrapOperationId = `bootstrap:${runId}:initial-prompt`;
+          let spawnedTerminalId: string | undefined;
+
+          try {
+            const sessionDir = agentSettings.agentSessions.showInResume
+              ? undefined
+              : preparePrivateAgentSessionDirectory(safeTeamName, safeName, runId);
+            await runtime.writeRuntimeStatus(safeTeamName, safeName, runId, {
+              startedAt: member.joinedAt,
+              lastHeartbeatAt: member.joinedAt,
+              ready: false,
+              currentAction: "starting",
+            });
+            await messaging.sendPlainMessageOnceIfRunning(
+              safeTeamName,
+              "team-lead",
+              safeName,
+              agentDef.prompt,
+              "Initial prompt from predefined team",
+              {
+                operationId: bootstrapOperationId,
+                expectedRecipientRunId: runId,
+              }
+            );
+            const piBinary = getPiLaunchCommand();
+            const piCmd = buildPiCommand(
+              piBinary,
+              chosenModel,
+              member.thinking,
+              resourcePlan.extensionPaths,
+              resourcePlan.trust.projectTrusted,
+              resourcePlan.selfExtensionPath,
+              sessionDir,
+            );
+            const env: Record<string, string> = {
+              ...process.env,
+              PI_TEAM_NAME: safeTeamName,
+              PI_AGENT_NAME: safeName,
+              PI_LIFECYCLE_RUN_ID: runId,
+            };
+
+            const leadMember = (await teams.readConfig(safeTeamName)).members.find(m => m.name === "team-lead");
+            const anchorPaneId = leadMember?.tmuxPaneId || process.env.TMUX_PANE || undefined;
+            spawnedTerminalId = options.terminal.spawn({ name: safeName, cwd: params.cwd, command: piCmd, env, anchorPaneId });
+            await teams.updateMember(safeTeamName, safeName, { tmuxPaneId: spawnedTerminalId });
+            spawnResults.push({ name: agentName, status: "spawned", error: undefined });
+          } catch (e) {
+            // A pane returned by spawn belongs to this run even if roster ownership
+            // has already moved on. Stop and synchronously verify that exact process
+            // before lifecycle/roster ownership checks can yield or return early.
+            const terminationError = spawnedTerminalId === undefined
+              ? null
+              : stopAndVerifySpawnedPane(options.terminal, spawnedTerminalId);
+
+            spawnResults.push({ name: agentName, status: "error", error: `Failed to spawn: ${e}` });
+            await withLifecycleTombstoneLock(safeTeamName, safeName, async lifecycleLock => {
+              const fence = lifecycleLock.read();
+              if (fence.status === "corrupt") return;
+              if (fence.status === "occupied" && fence.tombstone.runId !== runId) return;
+
+              const currentConfig = await teams.readConfig(safeTeamName).catch(() => null);
+              const currentMember = currentConfig?.members.find(item => item.name === safeName);
+              if (!currentMember || currentMember.lifecycleRunId !== runId) return;
+
+              if (terminationError) {
+                lifecycleLock.occupy({
+                  team: safeTeamName,
+                  agent: safeName,
+                  runId,
+                  role: "write",
+                  reason: "spawn_rollback",
+                  phase: "cleanup_failed",
+                  extensionInstanceId,
+                });
+                lifecycleLock.updateMatching(runId, {
+                  phase: "cleanup_failed",
+                  error: terminationError,
+                });
+                return;
+              }
+
+              await messaging.removeInboxMessagesByOperationUnderLifecycleLock(safeTeamName, safeName, bootstrapOperationId);
+              await runtime.deleteRuntimeStatusUnderLifecycleLock(safeTeamName, safeName, runId);
+              await teams.removeMemberMatchingRun(safeTeamName, safeName, runId);
+              if (!agentSettings.agentSessions.showInResume) {
+                try {
+                  cleanupPrivateAgentSessionDirectory(safeTeamName, safeName, runId);
+                } catch {
+                  // A later private-session janitor can retry cleanup.
+                }
+              }
+            });
+          }
+        } catch (e) {
+          spawnResults.push({ name: agentName, status: "error", error: String(e) });
+        }
+      }
+
+      const summary = spawnResults.map(r => `${r.name}: ${r.status}${r.error ? ` (${r.error})` : ""}`).join("\n");
+      return {
+        content: [{ type: "text", text: `Team "${params.team_name}" created from predefined team "${params.predefined_team}".\n\nAgent spawn results:\n${summary}` }],
+        details: { teamName: params.team_name, predefinedTeam: params.predefined_team, modelSlot: level.slot, results: spawnResults },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "save_team_as_template",
+    label: "Save Team as Template",
+    description: "Save a runtime team as a reusable predefined team template. Creates agent definition files and updates teams.yaml. Use this when you've created a team with custom prompts and want to reuse it later.",
+    parameters: Type.Object({
+      team_name: Type.String({ description: "Name of the runtime team to save" }),
+      template_name: Type.String({ description: "Name for the template (e.g., 'modularization', 'frontend-team')" }),
+      description: Type.Optional(Type.String({ description: "Description for the template" })),
+      scope: Type.Optional(StringEnum(["user", "project"], { description: "Where to save: 'user' for global (~/.pi), 'project' for project-local (.pi). Defaults to 'user'." })),
+    }),
+    async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
+      const teamName = params.team_name;
+      if (!teams.teamExists(teamName)) throw new Error(`Team "${teamName}" does not exist. Use list_runtime_teams to see available teams.`);
+      const config = await teams.readConfig(teamName);
+      const teammates = config.members.filter(m => m.agentType === "teammate");
+      if (teammates.length === 0) throw new Error(`Team "${teamName}" has no teammates to save. Only teams with spawned teammates can be saved as templates.`);
+
+      const result = predefined.saveTeamTemplate(config, { templateName: params.template_name, description: params.description, scope: params.scope || "user", projectDir: ctx.cwd });
+      const agentSummary = result.savedAgents.map(a => `  - ${a.name}: ${a.existed ? "updated" : "created"} at ${a.path}`).join("\n");
+      const message = `Team "${teamName}" saved as template "${params.template_name}".
+
+Agents saved:
+${agentSummary}
+
+Template location: ${result.teamsYamlPath}
+
+You can now use this template with:
+  create_predefined_team({ team_name: "new-team", predefined_team: "${params.template_name}", cwd: "..." })`;
+
+      return { content: [{ type: "text", text: message }], details: { teamName, templateName: params.template_name, agentsDir: result.agentsDir, teamsYamlPath: result.teamsYamlPath, savedAgents: result.savedAgents, templateExisted: result.templateExisted } };
+    },
+  });
+
+  pi.registerTool({
+    name: "list_runtime_teams",
+    label: "List Runtime Teams",
+    description: "List all runtime team configurations that can be saved as templates. These are active or saved teams from ~/.pi/teams/.",
+    parameters: Type.Object({}),
+    async execute() {
+      const runtimeTeams = predefined.listRuntimeTeams();
+      if (runtimeTeams.length === 0) return { content: [{ type: "text", text: "No runtime teams found. Create a team with team_create first." }], details: { teams: [] } };
+      const result = runtimeTeams.map(team => ({ name: team.name, description: team.description, memberCount: team.memberCount, createdAt: team.createdAt ? new Date(team.createdAt).toISOString() : undefined }));
+      const summary = result.map(t => `- ${t.name}: ${t.memberCount} teammate(s)${t.description ? ` - ${t.description}` : ""}`).join("\n");
+      return { content: [{ type: "text", text: `Runtime teams:\n${summary}` }], details: { teams: result } };
+    },
+  });
+}

package/extensions/tools/read-helper.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from "vitest";
+import { registerCoordinationTools } from "./coordination-tools.js";
+
+describe("coordination public tool surface", () => {
+  it("does not register helper, broadcast, shared-memory, or skill-loading tools", () => {
+    const tools = new Map<string, any>();
+
+    registerCoordinationTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+      agentName: "agent",
+      isTeammate: true,
+      terminal: null,
+      getTeamName: () => "session",
+      requireWriteAgentTeam: async () => "session",
+      requireTeamContext: () => "session",
+      releaseAllClaimsForAgent: vi.fn(async () => []),
+      drainWriteQueue: vi.fn(async () => {}),
+      resolveSkillFile: vi.fn(),
+      adoptTeamAsLead: vi.fn(),
+      renderLeadInboxStatus: vi.fn(async () => {}),
+      resetLeadWakeNotifiedCount: vi.fn(),
+    });
+
+    expect(Array.from(tools.keys()).sort()).toEqual([
+      "claim_file",
+      "list_file_claims",
+      "read_inbox",
+      "release_file",
+      "report_and_exit",
+      "send_message",
+    ]);
+    expect(tools.has("request_read_helper")).toBe(false);
+    expect(tools.has("broadcast_message")).toBe(false);
+    expect(tools.has("use_skill")).toBe(false);
+  });
+});