pi-teams 0.9.6 → 0.9.8

package/README.md

@@ -46,6 +46,7 @@ pi install npm:pi-teams
 
 ### 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.
@@ -107,6 +108,13 @@ 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
@@ -198,6 +206,51 @@ This single command:
 
 ---
 
+## 💾 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
 
 - **[Full Usage Guide](docs/guide.md)** - Detailed examples, hook system, best practices, and troubleshooting

package/extensions/index.ts

@@ -12,6 +12,7 @@ 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
@@ -263,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";
@@ -794,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",
@@ -1110,4 +1181,101 @@ export default function (pi: ExtensionAPI) {
       };
     },
   });
+
+  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.6",
+  "version": "0.9.8",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": {
     "type": "git",

package/src/utils/predefined-teams.ts

@@ -258,4 +258,252 @@ export function getAgentDefinition(name: string, projectDir?: string): AgentDefi
 export function getPredefinedTeam(name: string, projectDir?: string): PredefinedTeam | undefined {
   const teams = getAllPredefinedTeams(projectDir);
   return teams.find(t => t.name === name);
+}
+
+/**
+ * Options for saving a team as a template
+ */
+export interface SaveTeamTemplateOptions {
+  templateName: string;
+  description?: string;
+  scope: "user" | "project";
+  projectDir?: string;
+}
+
+/**
+ * Result of saving a team as a template
+ */
+export interface SaveTeamTemplateResult {
+  templateName: string;
+  agentsDir: string;
+  teamsYamlPath: string;
+  savedAgents: Array<{
+    name: string;
+    path: string;
+    existed: boolean;
+  }>;
+  templateExisted: boolean;
+}
+
+/**
+ * Generate markdown content for an agent definition file
+ */
+export function generateAgentMarkdown(agent: {
+  name: string;
+  description?: string;
+  tools?: string[];
+  model?: string;
+  thinking?: "off" | "minimal" | "low" | "medium" | "high";
+  prompt?: string;
+}): string {
+  const lines: string[] = ["---"];
+  lines.push(`name: ${agent.name}`);
+  if (agent.description) {
+    lines.push(`description: ${agent.description}`);
+  }
+  if (agent.tools && agent.tools.length > 0) {
+    lines.push(`tools: ${agent.tools.join(", ")}`);
+  }
+  if (agent.model) {
+    lines.push(`model: ${agent.model}`);
+  }
+  if (agent.thinking) {
+    lines.push(`thinking: ${agent.thinking}`);
+  }
+  lines.push("---");
+  lines.push("");
+  if (agent.prompt) {
+    lines.push(agent.prompt);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Generate teams.yaml content by adding a new team template
+ */
+export function generateTeamsYamlWithTemplate(
+  existingContent: string,
+  templateName: string,
+  agentNames: string[],
+  description?: string
+): string {
+  // Check if template already exists
+  const lines = existingContent.split("\n");
+  let templateExists = false;
+  let templateStartLine = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === `${templateName}:`) {
+      templateExists = true;
+      templateStartLine = i;
+      break;
+    }
+  }
+
+  if (templateExists) {
+    // Replace existing template - find where it ends
+    let templateEndLine = templateStartLine + 1;
+    while (templateEndLine < lines.length && (lines[templateEndLine].startsWith("  ") || lines[templateEndLine].startsWith("\t"))) {
+      templateEndLine++;
+    }
+    // Remove old template lines
+    lines.splice(templateStartLine, templateEndLine - templateStartLine);
+  }
+
+  // Build new template entry
+  const templateLines: string[] = [];
+  if (description) {
+    templateLines.push(`# ${description}`);
+  }
+  templateLines.push(`${templateName}:`);
+  for (const agentName of agentNames) {
+    templateLines.push(`  - ${agentName}`);
+  }
+  templateLines.push("");
+
+  // Find insertion point (at the end or after existing content)
+  let insertIndex = lines.length;
+  
+  // Remove trailing empty lines to find actual end
+  while (insertIndex > 0 && lines[insertIndex - 1].trim() === "") {
+    insertIndex--;
+  }
+
+  // Insert new template
+  lines.splice(insertIndex, 0, ...templateLines);
+
+  return lines.join("\n");
+}
+
+/**
+ * Save a team configuration as a reusable template.
+ * Creates agent definition files and updates teams.yaml.
+ */
+export function saveTeamTemplate(
+  teamConfig: {
+    name: string;
+    description?: string;
+    members: Array<{
+      name: string;
+      agentType: string;
+      model?: string;
+      thinking?: "off" | "minimal" | "low" | "medium" | "high";
+      prompt?: string;
+    }>;
+    defaultModel?: string;
+  },
+  options: SaveTeamTemplateOptions
+): SaveTeamTemplateResult {
+  // Determine output paths based on scope
+  const baseDir = options.scope === "project"
+    ? path.join(options.projectDir || process.cwd(), ".pi")
+    : path.join(os.homedir(), ".pi", "agent");
+
+  const agentsDir = path.join(baseDir, "agents");
+  const teamsYamlPath = path.join(baseDir, "teams.yaml");
+
+  // Ensure agents directory exists
+  if (!fs.existsSync(agentsDir)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+  }
+
+  // Filter to only teammates (not the lead)
+  const teammates = teamConfig.members.filter(m => m.agentType === "teammate");
+  const agentNames: string[] = [];
+  const savedAgents: SaveTeamTemplateResult["savedAgents"] = [];
+
+  // Save each teammate as an agent definition
+  for (const member of teammates) {
+    const agentFileName = `${member.name}.md`;
+    const agentPath = path.join(agentsDir, agentFileName);
+    const existed = fs.existsSync(agentPath);
+
+    // Use the model from the member, or fall back to the team's default model
+    const model = member.model || teamConfig.defaultModel;
+
+    const content = generateAgentMarkdown({
+      name: member.name,
+      description: `Agent from team '${teamConfig.name}'`,
+      model,
+      thinking: member.thinking,
+      prompt: member.prompt,
+    });
+
+    fs.writeFileSync(agentPath, content);
+    agentNames.push(member.name);
+    savedAgents.push({ name: member.name, path: agentPath, existed });
+  }
+
+  // Update teams.yaml
+  let teamsContent = "";
+  if (fs.existsSync(teamsYamlPath)) {
+    teamsContent = fs.readFileSync(teamsYamlPath, "utf-8");
+  }
+
+  // Check if template already exists
+  const templateExisted = teamsContent.includes(`${options.templateName}:`);
+
+  // Generate updated teams.yaml content
+  const updatedContent = generateTeamsYamlWithTemplate(
+    teamsContent,
+    options.templateName,
+    agentNames,
+    options.description || teamConfig.description
+  );
+
+  fs.writeFileSync(teamsYamlPath, updatedContent);
+
+  return {
+    templateName: options.templateName,
+    agentsDir,
+    teamsYamlPath,
+    savedAgents,
+    templateExisted,
+  };
+}
+
+/**
+ * List all runtime team configurations from ~/.pi/teams/
+ */
+export function listRuntimeTeams(): Array<{
+  name: string;
+  description?: string;
+  memberCount: number;
+  createdAt?: number;
+}> {
+  const teamsDir = path.join(os.homedir(), ".pi", "teams");
+  
+  if (!fs.existsSync(teamsDir)) {
+    return [];
+  }
+
+  const teams: Array<{
+    name: string;
+    description?: string;
+    memberCount: number;
+    createdAt?: number;
+  }> = [];
+
+  for (const teamDir of fs.readdirSync(teamsDir, { withFileTypes: true })) {
+    if (!teamDir.isDirectory()) continue;
+
+    const configFile = path.join(teamsDir.path || teamsDir.name, teamDir.name, "config.json");
+    const configPath = path.join(os.homedir(), ".pi", "teams", teamDir.name, "config.json");
+    
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        teams.push({
+          name: config.name || teamDir.name,
+          description: config.description,
+          memberCount: (config.members || []).filter((m: any) => m.agentType === "teammate").length,
+          createdAt: config.createdAt,
+        });
+      } catch {
+        // Skip invalid config files
+      }
+    }
+  }
+
+  return teams;
 }