pi-teams 0.9.5 → 0.9.8

package/README.md

@@ -45,6 +45,8 @@ pi install npm:pi-teams
 - **Beautiful UI**: Optimized vertical splits in `tmux` with clear labels so you always know who is doing what.
 
 ### Advanced Features
+- **Predefined Teams**: Define team templates in `teams.yaml` and spawn entire teams with a single command.
+- **Save Teams as Templates**: Convert any runtime team into a reusable template with a single command.
 - **Isolated OS Windows**: Launch teammates in true separate OS windows instead of panes.
 - **Persistent Window Titles**: Windows are automatically titled `[team-name]: [agent-name]` for easy identification in your window manager.
 - **Plan Approval Mode**: Require teammates to submit their implementation plans for your approval before they touch any code.
@@ -106,6 +108,147 @@ Teammates in `planning` mode will use `task_submit_plan`. As the lead, review th
 ### 5. Shut Down Team
 > **You:** "We're done. Shut down the team and close the panes."
 
+**Automatic Cleanup:**
+When you shut down a team, pi-teams automatically cleans up orphaned agent session folders from `~/.pi/agent/teams/` that are older than 1 hour. This prevents accumulation of stale session data over time.
+
+**Manual Cleanup:**
+If you need to clean up agent sessions without shutting down a team, or want to use a different age threshold:
+> **You:** "Clean up agent session folders older than 24 hours."
+
+---
+
+## 🏗️ Predefined Teams
+
+Predefined teams let you define reusable team templates in a `teams.yaml` file. This is perfect for common workflows where you always want the same set of specialists.
+
+### Define Team Templates
+
+Create `~/.pi/teams.yaml` (global) or `.pi/teams.yaml` in your project:
+
+```yaml
+# Full development team
+full:
+  - scout
+  - planner
+  - builder
+  - reviewer
+  - documenter
+
+# Quick plan-build cycle
+plan-build:
+  - planner
+  - builder
+  - reviewer
+
+# Research and documentation
+research:
+  - scout
+  - documenter
+
+# Frontend specialists
+frontend:
+  - planner
+  - builder
+  - bowser
+```
+
+### Define Agent Definitions
+
+Create agent definitions in `~/.pi/agent/agents/` (global) or `.pi/agents/` (project-local):
+
+**scout.md:**
+```markdown
+---
+name: scout
+description: Fast recon and codebase exploration
+tools: read,grep,find,ls
+---
+You are a scout agent. Investigate the codebase quickly and report findings concisely. Do NOT modify any files. Focus on structure, patterns, and key entry points.
+```
+
+**builder.md:**
+```markdown
+---
+name: builder
+description: Implementation specialist
+tools: read,write,edit,bash
+model: claude-sonnet-4
+thinking: medium
+---
+You are a builder agent. Implement code following the plan provided. Write clean, tested code.
+```
+
+**Agent Definition Fields:**
+- `name` (required): The agent's name
+- `description` (required): What the agent does
+- `tools` (optional): Comma or space-separated list of allowed tools
+- `model` (optional): Model to use (e.g., `claude-sonnet-4`, `gpt-4o`)
+- `thinking` (optional): Thinking level (`off`, `minimal`, `low`, `medium`, `high`)
+
+### Use Predefined Teams
+
+**List available team templates:**
+> **You:** "List all predefined teams I can use."
+
+**List available agent definitions:**
+> **You:** "Show me all predefined agents."
+
+**Create a team from a template:**
+> **You:** "Create a team named 'my-project' from the 'plan-build' predefined team in the current directory."
+
+This single command:
+1. Creates the team
+2. Spawns all agents defined in the template
+3. Each agent gets its predefined prompt, tools, model, and thinking settings
+
+**With options:**
+> **You:** "Create a team named 'big-team' from 'full' predefined team using 'gpt-4o' as default model and separate windows."
+
+---
+
+## 💾 Save Teams as Templates
+
+Sometimes you create a team with custom prompts and settings that you'd like to reuse later. Instead of manually creating `teams.yaml` and agent definition files, you can save any runtime team as a template.
+
+### The Workflow
+
+```
+CREATE → USE → SAVE → REUSE
+```
+
+1. **Create** a team with custom teammates and prompts
+2. **Use** the team for your task
+3. **Save** the team as a reusable template
+4. **Reuse** the template later (even on different projects)
+
+### List Runtime Teams
+
+See which teams you have that can be saved:
+
+> **You:** "List all runtime teams."
+
+### Save a Team as a Template
+
+> **You:** "Save team 'my-modularization-team' as template 'code-modularization'"
+
+This creates:
+- Agent definition files in `~/.pi/agent/agents/` for each teammate
+- Updates `~/.pi/teams.yaml` with the new template
+
+### Save to Project-Local Scope
+
+To save a template that's specific to the current project:
+
+> **You:** "Save team 'my-frontend-team' as template 'frontend-sprint' with scope 'project'"
+
+This creates files in `.pi/agents/` and `.pi/teams.yaml` in the current project directory.
+
+### Reuse Your Template
+
+Once saved, use it just like any predefined team:
+
+> **You:** "Create a team named 'auth-refactor' from the 'code-modularization' template in the current directory"
+
 ---
 
 ## 📚 Learn More

package/extensions/index.ts

@@ -9,8 +9,10 @@ import * as runtime from "../src/utils/runtime";
 import { Member } from "../src/utils/models";
 import { getTerminalAdapter } from "../src/adapters/terminal-registry";
 import { Iterm2Adapter } from "../src/adapters/iterm2-adapter";
+import * as predefined from "../src/utils/predefined-teams";
 import * as path from "node:path";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 
 // Cache for available models
@@ -262,6 +264,45 @@ function cleanupStaleTeam(teamName: string, terminal: any): boolean {
   return false;
 }
 
+/**
+ * Clean up orphaned agent session folders from ~/.pi/agent/teams/
+ * These are created by the pi core system when agents are spawned.
+ * We remove folders that are older than 24 hours to avoid deleting active sessions.
+ * Returns the number of folders cleaned up.
+ */
+function cleanupAgentSessionFolders(maxAgeMs: number = 24 * 60 * 60 * 1000): number {
+  const agentTeamsDir = path.join(os.homedir(), ".pi", "agent", "teams");
+  if (!fs.existsSync(agentTeamsDir)) return 0;
+
+  let cleaned = 0;
+  const now = Date.now();
+
+  for (const dir of fs.readdirSync(agentTeamsDir)) {
+    const sessionDir = path.join(agentTeamsDir, dir);
+    const configFile = path.join(sessionDir, "config.json");
+
+    try {
+      // Check if this is a directory with a config.json
+      if (!fs.statSync(sessionDir).isDirectory()) continue;
+      if (!fs.existsSync(configFile)) continue;
+
+      // Read the config to check the creation time
+      const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+      const createdAt = config.createdAt ? new Date(config.createdAt).getTime() : 0;
+
+      // If the folder is older than maxAgeMs, delete it
+      if (createdAt > 0 && (now - createdAt) > maxAgeMs) {
+        fs.rmSync(sessionDir, { recursive: true });
+        cleaned++;
+      }
+    } catch {
+      // Ignore errors for individual folders
+    }
+  }
+
+  return cleaned;
+}
+
 export default function (pi: ExtensionAPI) {
   const isTeammate = !!process.env.PI_AGENT_NAME;
   const agentName = process.env.PI_AGENT_NAME || "team-lead";
@@ -793,13 +834,44 @@ export default function (pi: ExtensionAPI) {
         const tasksDir = paths.taskDir(teamName);
         if (fs.existsSync(tasksDir)) fs.rmSync(tasksDir, { recursive: true });
         if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true });
-        return { content: [{ type: "text", text: `Team ${teamName} shut down.` }], details: {} };
+
+        // Clean up orphaned agent session folders (older than 1 hour)
+        const cleanedSessions = cleanupAgentSessionFolders(60 * 60 * 1000);
+
+        return {
+          content: [{
+            type: "text",
+            text: `Team ${teamName} shut down.${cleanedSessions > 0 ? ` Cleaned up ${cleanedSessions} orphaned agent session folder(s).` : ""}`
+          }],
+          details: { cleanedSessions }
+        };
       } catch (e) {
         throw new Error(`Failed to shutdown team: ${e}`);
       }
     },
   });
 
+  pi.registerTool({
+    name: "cleanup_agent_sessions",
+    label: "Cleanup Agent Sessions",
+    description: "Clean up orphaned agent session folders from ~/.pi/agent/teams/ that are older than a specified age.",
+    parameters: Type.Object({
+      max_age_hours: Type.Optional(Type.Number()),
+    }),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      const maxAgeHours = params.max_age_hours ?? 24;
+      const maxAgeMs = maxAgeHours * 60 * 60 * 1000;
+      const cleaned = cleanupAgentSessionFolders(maxAgeMs);
+      return {
+        content: [{
+          type: "text",
+          text: `Cleaned up ${cleaned} orphaned agent session folder(s) older than ${maxAgeHours} hour(s).`
+        }],
+        details: { cleaned, maxAgeHours }
+      };
+    },
+  });
+
   pi.registerTool({
     name: "task_read",
     label: "Read Task",
@@ -897,4 +969,313 @@ export default function (pi: ExtensionAPI) {
       };
     },
   });
+
+  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, params: any, signal, onUpdate, ctx) {
+      const projectDir = ctx.cwd;
+      const predefinedTeams = predefined.getAllPredefinedTeams(projectDir);
+      const agents = predefined.getAllAgentDefinitions(projectDir);
+      
+      const result = predefinedTeams.map(team => {
+        const teamAgents = 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 {
+          name: team.name,
+          agents: teamAgents,
+        };
+      });
+
+      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, params: any, signal, onUpdate, ctx) {
+      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. Spawns all agents defined in the team template from teams.yaml. Each agent is spawned with its predefined prompt, tools, and settings.",
+    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" }),
+      default_model: Type.Optional(Type.String({ description: "Default model for agents without a specified model" })),
+      separate_windows: Type.Optional(Type.Boolean({ default: false, description: "Open teammates in separate OS windows instead of panes" })),
+    }),
+    async execute(toolCallId, params: any, signal, onUpdate, ctx) {
+      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 (!terminal) {
+        throw new Error("No terminal adapter detected.");
+      }
+
+      // Create the team
+      const config = teams.createTeam(params.team_name, "local-session", "lead-agent", `Predefined team: ${params.predefined_team}`, params.default_model, params.separate_windows);
+      registerLeadSession(params.team_name);
+
+      const agentDefinitions = predefined.getAllAgentDefinitions(projectDir);
+      const spawnResults: Array<{ name: string; status: string; error?: string }> = [];
+
+      // Spawn each agent in the predefined team
+      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);
+          
+          let chosenModel = agentDef.model || params.default_model || config.defaultModel;
+          
+          if (chosenModel && !chosenModel.includes('/')) {
+            const resolved = resolveModelWithProvider(chosenModel);
+            if (resolved) {
+              chosenModel = resolved;
+            } else if (config.defaultModel && config.defaultModel.includes('/')) {
+              const [provider] = config.defaultModel.split('/');
+              chosenModel = `${provider}/${chosenModel}`;
+            }
+          }
+
+          const useSeparateWindow = params.separate_windows ?? config.separateWindows ?? false;
+          if (useSeparateWindow && !terminal.supportsWindows()) {
+            throw new Error(`Separate windows mode is not supported in ${terminal.name}.`);
+          }
+
+          const member: Member = {
+            agentId: `${safeName}@${safeTeamName}`,
+            name: safeName,
+            agentType: "teammate",
+            model: chosenModel,
+            joinedAt: Date.now(),
+            tmuxPaneId: "",
+            cwd: params.cwd,
+            subscriptions: [],
+            prompt: agentDef.prompt,
+            color: "blue",
+            thinking: agentDef.thinking,
+          };
+
+          await teams.addMember(safeTeamName, member);
+          await messaging.sendPlainMessage(safeTeamName, "team-lead", safeName, agentDef.prompt, "Initial prompt from predefined team");
+
+          const piBinary = process.argv[1] ? `node ${process.argv[1]}` : "pi";
+          let piCmd = piBinary;
+
+          if (chosenModel) {
+            if (agentDef.thinking) {
+              piCmd = `${piBinary} --model ${chosenModel}:${agentDef.thinking}`;
+            } else {
+              piCmd = `${piBinary} --model ${chosenModel}`;
+            }
+          } else if (agentDef.thinking) {
+            piCmd = `${piBinary} --thinking ${agentDef.thinking}`;
+          }
+
+          const env: Record<string, string> = {
+            ...process.env,
+            PI_TEAM_NAME: safeTeamName,
+            PI_AGENT_NAME: safeName,
+          };
+
+          let terminalId = "";
+          let isWindow = false;
+
+          try {
+            if (useSeparateWindow) {
+              isWindow = true;
+              terminalId = terminal.spawnWindow({
+                name: safeName,
+                cwd: params.cwd,
+                command: piCmd,
+                env: env,
+                teamName: safeTeamName,
+              });
+              await teams.updateMember(safeTeamName, safeName, { windowId: terminalId });
+            } else {
+              if (terminal instanceof Iterm2Adapter) {
+                const teammates = (await teams.readConfig(safeTeamName)).members.filter(m => m.agentType === "teammate" && m.tmuxPaneId.startsWith("iterm_"));
+                const lastTeammate = teammates.length > 0 ? teammates[teammates.length - 1] : null;
+                if (lastTeammate?.tmuxPaneId) {
+                  terminal.setSpawnContext({ lastSessionId: lastTeammate.tmuxPaneId.replace("iterm_", "") });
+                } else {
+                  terminal.setSpawnContext({});
+                }
+              }
+
+              const leadMember = (await teams.readConfig(safeTeamName)).members.find(m => m.name === "team-lead");
+              const anchorPaneId = terminal.name === "tmux"
+                ? leadMember?.tmuxPaneId || process.env.TMUX_PANE || undefined
+                : undefined;
+
+              terminalId = terminal.spawn({
+                name: safeName,
+                cwd: params.cwd,
+                command: piCmd,
+                env: env,
+                anchorPaneId,
+              });
+              await teams.updateMember(safeTeamName, safeName, { tmuxPaneId: terminalId });
+            }
+
+            spawnResults.push({ name: agentName, status: "spawned", error: undefined });
+          } catch (e) {
+            spawnResults.push({ name: agentName, status: "error", error: `Failed to spawn: ${e}` });
+          }
+        } 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, 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, params: any, signal, onUpdate, ctx) {
+      const teamName = params.team_name;
+      
+      // Verify the team exists
+      if (!teams.teamExists(teamName)) {
+        throw new Error(`Team "${teamName}" does not exist. Use list_runtime_teams to see available teams.`);
+      }
+
+      // Read the team configuration
+      const config = await teams.readConfig(teamName);
+      
+      // Check that there are teammates to save
+      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.`);
+      }
+
+      // Save the team as a template
+      const result = predefined.saveTeamTemplate(config, {
+        templateName: params.template_name,
+        description: params.description,
+        scope: params.scope || "user",
+        projectDir: ctx.cwd,
+      });
+
+      // Build summary message
+      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(toolCallId, params: any, signal, onUpdate, ctx) {
+      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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-teams",
-  "version": "0.9.5",
+  "version": "0.9.8",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": {
     "type": "git",
@@ -9,7 +9,18 @@
   "author": "Mark Burggraf",
   "license": "MIT",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "ai-agent",
+    "multi-agent",
+    "agent-teams",
+    "agent-coordination",
+    "autonomous-agents",
+    "task-management",
+    "team-collaboration",
+    "agent-orchestration",
+    "coding-assistant",
+    "terminal",
+    "tmux"
   ],
   "scripts": {
     "test": "vitest run"