@tmustier/pi-agent-teams 0.1.2 → 0.2.0

package/extensions/teams/leader-task-commands.ts

@@ -0,0 +1,417 @@
+import * as path from "node:path";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { writeToMailbox } from "./mailbox.js";
+import { sanitizeName } from "./names.js";
+import { getTeamDir } from "./paths.js";
+import { TEAM_MAILBOX_NS } from "./protocol.js";
+import {
+	addTaskDependency,
+	clearTasks,
+	createTask,
+	formatTaskLine,
+	getTask,
+	isTaskBlocked,
+	removeTaskDependency,
+	updateTask,
+	type TeamTask,
+} from "./task-store.js";
+import { ensureTeamConfig } from "./team-config.js";
+import type { TeamsStyle } from "./teams-style.js";
+import { formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
+
+export async function handleTeamTaskCommand(opts: {
+	ctx: ExtensionCommandContext;
+	rest: string[];
+	leadName: string;
+	style: TeamsStyle;
+	getTaskListId: () => string | null;
+	setTaskListId: (id: string) => void;
+	getTasks: () => TeamTask[];
+	refreshTasks: () => Promise<void>;
+	renderWidget: () => void;
+	parseAssigneePrefix: (text: string) => { assignee?: string; text: string };
+	taskAssignmentPayload: (task: TeamTask, assignedBy: string) => unknown;
+}): Promise<void> {
+	const {
+		ctx,
+		rest,
+		leadName,
+		style,
+		getTaskListId,
+		setTaskListId,
+		getTasks,
+		refreshTasks,
+		renderWidget,
+		parseAssigneePrefix,
+		taskAssignmentPayload,
+	} = opts;
+	const strings = getTeamsStrings(style);
+
+	const [taskSub, ...taskRest] = rest;
+	const teamId = ctx.sessionManager.getSessionId();
+	const teamDir = getTeamDir(teamId);
+	const effectiveTlId = getTaskListId() ?? teamId;
+
+	if (!taskSub || taskSub === "help") {
+		ctx.ui.notify(
+			[
+				"Usage:",
+				"  /team task add <text...>",
+				"  /team task assign <id> <agent>",
+				"  /team task unassign <id>",
+				"  /team task list",
+				"  /team task clear [completed|all] [--force]",
+				"  /team task show <id>",
+				"  /team task dep add <id> <depId>",
+				"  /team task dep rm <id> <depId>",
+				"  /team task dep ls <id>",
+				"  /team task use <taskListId>",
+				"Tip: prefix with assignee, e.g. 'alice: review the API surface'",
+			].join("\n"),
+			"info",
+		);
+		return;
+	}
+
+	switch (taskSub) {
+		case "add": {
+			const raw = taskRest.join(" ").trim();
+			if (!raw) {
+				ctx.ui.notify("Usage: /team task add <text...>", "error");
+				return;
+			}
+
+			const parsed = parseAssigneePrefix(raw);
+			const owner = parsed.assignee ? sanitizeName(parsed.assignee) : undefined;
+			const description = parsed.text.trim();
+			const firstLine = description.split("\n").at(0) ?? "";
+			const subject = firstLine.slice(0, 120);
+
+			const task = await createTask(teamDir, effectiveTlId, { subject, description, owner });
+
+			if (owner) {
+				const payload = taskAssignmentPayload(task, leadName);
+				await writeToMailbox(teamDir, effectiveTlId, owner, {
+					from: leadName,
+					text: JSON.stringify(payload),
+					timestamp: new Date().toISOString(),
+				});
+			}
+
+			ctx.ui.notify(
+				`Created task #${task.id}${owner ? ` (assigned to ${formatMemberDisplayName(style, owner)})` : ""}`,
+				"info",
+			);
+			await refreshTasks();
+			renderWidget();
+			return;
+		}
+
+		case "assign": {
+			const taskId = taskRest[0];
+			const agent = taskRest[1];
+			if (!taskId || !agent) {
+				ctx.ui.notify("Usage: /team task assign <id> <agent>", "error");
+				return;
+			}
+
+			const owner = sanitizeName(agent);
+			const updated = await updateTask(teamDir, effectiveTlId, taskId, (cur) => {
+				if (cur.status !== "completed") {
+					return { ...cur, owner, status: "pending" };
+				}
+				return { ...cur, owner };
+			});
+			if (!updated) {
+				ctx.ui.notify(`Task not found: ${taskId}`, "error");
+				return;
+			}
+
+			await writeToMailbox(teamDir, effectiveTlId, owner, {
+				from: leadName,
+				text: JSON.stringify(taskAssignmentPayload(updated, leadName)),
+				timestamp: new Date().toISOString(),
+			});
+
+			ctx.ui.notify(`Assigned task #${updated.id} to ${formatMemberDisplayName(style, owner)}`, "info");
+			await refreshTasks();
+			renderWidget();
+			return;
+		}
+
+		case "unassign": {
+			const taskId = taskRest[0];
+			if (!taskId) {
+				ctx.ui.notify("Usage: /team task unassign <id>", "error");
+				return;
+			}
+
+			const updated = await updateTask(teamDir, effectiveTlId, taskId, (cur) => {
+				if (cur.status !== "completed") {
+					return { ...cur, owner: undefined, status: "pending" };
+				}
+				return { ...cur, owner: undefined };
+			});
+			if (!updated) {
+				ctx.ui.notify(`Task not found: ${taskId}`, "error");
+				return;
+			}
+
+			ctx.ui.notify(`Unassigned task #${updated.id}`, "info");
+			await refreshTasks();
+			renderWidget();
+			return;
+		}
+
+		case "show": {
+			const taskId = taskRest[0];
+			if (!taskId) {
+				ctx.ui.notify("Usage: /team task show <id>", "error");
+				return;
+			}
+
+			const task = await getTask(teamDir, effectiveTlId, taskId);
+			if (!task) {
+				ctx.ui.notify(`Task not found: ${taskId}`, "error");
+				return;
+			}
+
+			const blocked = task.status !== "completed" && (await isTaskBlocked(teamDir, effectiveTlId, task));
+
+			const lines: string[] = [];
+			lines.push(`#${task.id} ${task.subject}`);
+			lines.push(
+				`status: ${task.status}${blocked ? " (blocked)" : ""}${task.owner ? ` • owner: ${task.owner}` : ""}`,
+			);
+			if (task.blockedBy.length) lines.push(`deps: ${task.blockedBy.join(", ")}`);
+			if (task.blocks.length) lines.push(`blocks: ${task.blocks.join(", ")}`);
+			lines.push("");
+			lines.push(task.description);
+
+			const result = typeof task.metadata?.result === "string" ? task.metadata.result : undefined;
+			if (result) {
+				lines.push("");
+				lines.push("result:");
+				lines.push(result);
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+			return;
+		}
+
+		case "dep": {
+			const [depSub, ...depRest] = taskRest;
+			if (!depSub || depSub === "help") {
+				ctx.ui.notify(
+					[
+						"Usage:",
+						"  /team task dep add <id> <depId>",
+						"  /team task dep rm <id> <depId>",
+						"  /team task dep ls <id>",
+					].join("\n"),
+					"info",
+				);
+				return;
+			}
+
+			switch (depSub) {
+				case "add": {
+					const taskId = depRest[0];
+					const depId = depRest[1];
+					if (!taskId || !depId) {
+						ctx.ui.notify("Usage: /team task dep add <id> <depId>", "error");
+						return;
+					}
+
+					const res = await addTaskDependency(teamDir, effectiveTlId, taskId, depId);
+					if (!res.ok) {
+						ctx.ui.notify(res.error, "error");
+						return;
+					}
+
+					ctx.ui.notify(`Added dependency: #${taskId} depends on #${depId}`, "info");
+					await refreshTasks();
+					renderWidget();
+					return;
+				}
+
+				case "rm": {
+					const taskId = depRest[0];
+					const depId = depRest[1];
+					if (!taskId || !depId) {
+						ctx.ui.notify("Usage: /team task dep rm <id> <depId>", "error");
+						return;
+					}
+
+					const res = await removeTaskDependency(teamDir, effectiveTlId, taskId, depId);
+					if (!res.ok) {
+						ctx.ui.notify(res.error, "error");
+						return;
+					}
+
+					ctx.ui.notify(`Removed dependency: #${taskId} no longer depends on #${depId}`, "info");
+					await refreshTasks();
+					renderWidget();
+					return;
+				}
+
+				case "ls": {
+					const taskId = depRest[0];
+					if (!taskId) {
+						ctx.ui.notify("Usage: /team task dep ls <id>", "error");
+						return;
+					}
+
+					await refreshTasks();
+					const tasks = getTasks();
+					const task = tasks.find((t) => t.id === taskId) ?? (await getTask(teamDir, effectiveTlId, taskId));
+					if (!task) {
+						ctx.ui.notify(`Task not found: ${taskId}`, "error");
+						return;
+					}
+
+					const blocked = task.status !== "completed" && (await isTaskBlocked(teamDir, effectiveTlId, task));
+
+					const lines: string[] = [];
+					lines.push(`#${task.id} ${task.subject}`);
+					lines.push(`${blocked ? "blocked" : "unblocked"} • deps:${task.blockedBy.length} • blocks:${task.blocks.length}`);
+
+					lines.push("");
+					lines.push("blockedBy:");
+					if (!task.blockedBy.length) {
+						lines.push("  (none)");
+					} else {
+						for (const id of task.blockedBy) {
+							const dep = tasks.find((t) => t.id === id) ?? (await getTask(teamDir, effectiveTlId, id));
+							lines.push(dep ? `  - #${id} ${dep.status} ${dep.subject}` : `  - #${id} (missing)`);
+						}
+					}
+
+					lines.push("");
+					lines.push("blocks:");
+					if (!task.blocks.length) {
+						lines.push("  (none)");
+					} else {
+						for (const id of task.blocks) {
+							const child = tasks.find((t) => t.id === id) ?? (await getTask(teamDir, effectiveTlId, id));
+							lines.push(child ? `  - #${id} ${child.status} ${child.subject}` : `  - #${id} (missing)`);
+						}
+					}
+
+					ctx.ui.notify(lines.join("\n"), "info");
+					return;
+				}
+
+				default: {
+					ctx.ui.notify(`Unknown dep subcommand: ${depSub}`, "error");
+					return;
+				}
+			}
+		}
+
+		case "clear": {
+			const flags = taskRest.filter((a) => a.startsWith("--"));
+			const argsOnly = taskRest.filter((a) => !a.startsWith("--"));
+			const force = flags.includes("--force");
+
+			const unknownFlags = flags.filter((f) => f !== "--force");
+			if (unknownFlags.length) {
+				ctx.ui.notify(`Unknown flag(s): ${unknownFlags.join(", ")}`, "error");
+				return;
+			}
+
+			if (argsOnly.length > 1) {
+				ctx.ui.notify("Usage: /team task clear [completed|all] [--force]", "error");
+				return;
+			}
+
+			const modeArg = argsOnly[0];
+			if (modeArg && modeArg !== "completed" && modeArg !== "all") {
+				ctx.ui.notify("Usage: /team task clear [completed|all] [--force]", "error");
+				return;
+			}
+			const mode = modeArg === "all" ? "all" : "completed";
+
+			await refreshTasks();
+			const tasks = getTasks();
+			const toDelete = mode === "all" ? tasks.length : tasks.filter((t) => t.status === "completed").length;
+
+			if (!force) {
+				// Only prompt in interactive TTY mode. In RPC mode, confirm() would require
+				// the host to send extension_ui_response messages.
+				if (process.stdout.isTTY && process.stdin.isTTY) {
+					const title = mode === "all" ? "Clear task list" : "Clear completed tasks";
+					const body =
+						mode === "all"
+							? `Delete ALL ${toDelete} task(s) from the task list? This cannot be undone.`
+							: `Delete ${toDelete} completed task(s) from the task list? This cannot be undone.`;
+					const ok = await ctx.ui.confirm(title, body);
+					if (!ok) return;
+				} else {
+					ctx.ui.notify("Refusing to clear tasks in non-interactive mode without --force", "error");
+					return;
+				}
+			}
+
+			const res = await clearTasks(teamDir, effectiveTlId, mode);
+			const deleted = res.deletedTaskIds.length;
+
+			if (res.errors.length) {
+				ctx.ui.notify(`Cleared ${deleted} task(s) (${mode}) with ${res.errors.length} error(s)`, "warning");
+				const preview = res.errors
+					.slice(0, 8)
+					.map((e) => `- ${path.basename(e.file)}: ${e.error}`)
+					.join("\n");
+				ctx.ui.notify(
+					`Errors:\n${preview}${res.errors.length > 8 ? `\n... +${res.errors.length - 8} more` : ""}`,
+					"warning",
+				);
+			} else if (deleted === 0) {
+				ctx.ui.notify(`No task(s) cleared (${mode})`, "info");
+			} else {
+				ctx.ui.notify(`Cleared ${deleted} task(s) (${mode})`, "warning");
+			}
+
+			await refreshTasks();
+			renderWidget();
+			return;
+		}
+
+		case "list": {
+			await refreshTasks();
+			const tasks = getTasks();
+			if (!tasks.length) {
+				ctx.ui.notify("No tasks", "info");
+				return;
+			}
+
+			const slice = tasks.slice(-30);
+			const blocked = await Promise.all(
+				slice.map(async (t) => (t.status === "completed" ? false : await isTaskBlocked(teamDir, effectiveTlId, t))),
+			);
+
+			const preview = slice.map((t, i) => formatTaskLine(t, { blocked: blocked[i] })).join("\n");
+			ctx.ui.notify(preview, "info");
+			return;
+		}
+
+		case "use": {
+			const newId = taskRest[0];
+			if (!newId) {
+				ctx.ui.notify("Usage: /team task use <taskListId>", "error");
+				return;
+			}
+			setTaskListId(newId);
+			await ensureTeamConfig(teamDir, { teamId, taskListId: newId, leadName, style });
+			ctx.ui.notify(`Task list ID set to: ${newId}`, "info");
+			await refreshTasks();
+			renderWidget();
+			return;
+		}
+
+		default: {
+			ctx.ui.notify(`Unknown task subcommand: ${taskSub}`, "error");
+			return;
+		}
+	}
+}

package/extensions/teams/leader-teams-tool.ts

@@ -0,0 +1,238 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type, type Static } from "@sinclair/typebox";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { writeToMailbox } from "./mailbox.js";
+import { pickAgentNames, pickComradeNames, sanitizeName } from "./names.js";
+import { getTeamDir } from "./paths.js";
+import { ensureTeamConfig } from "./team-config.js";
+import { getTeamsStyleFromEnv, type TeamsStyle, formatMemberDisplayName } from "./teams-style.js";
+import { createTask, type TeamTask } from "./task-store.js";
+import type { TeammateRpc } from "./teammate-rpc.js";
+
+export type ContextMode = "fresh" | "branch";
+export type WorkspaceMode = "shared" | "worktree";
+
+type TeamsToolDelegateTask = { text: string; assignee?: string };
+
+type SpawnTeammateResult =
+	| { ok: true; name: string; warnings: string[] }
+	| { ok: false; error: string };
+
+export type SpawnTeammateFn = (
+	ctx: ExtensionContext,
+	opts: { name: string; mode?: ContextMode; workspaceMode?: WorkspaceMode; planRequired?: boolean },
+) => Promise<SpawnTeammateResult>;
+
+const TeamsActionSchema = StringEnum(["delegate"] as const, {
+	description: "Teams tool action. Currently only 'delegate' is supported.",
+	default: "delegate",
+});
+
+const TeamsContextModeSchema = StringEnum(["fresh", "branch"] as const, {
+	description: "How to initialize comrade session context. 'branch' clones the leader session branch.",
+	default: "fresh",
+});
+
+const TeamsWorkspaceModeSchema = StringEnum(["shared", "worktree"] as const, {
+	description: "Workspace isolation mode. 'shared' matches Claude Teams; 'worktree' creates a git worktree per comrade.",
+	default: "shared",
+});
+
+const TeamsDelegateTaskSchema = Type.Object({
+	text: Type.String({ description: "Task / TODO text." }),
+	assignee: Type.Optional(Type.String({ description: "Optional comrade name. If omitted, assigned round-robin." })),
+});
+
+const TeamsToolParamsSchema = Type.Object({
+	action: Type.Optional(TeamsActionSchema),
+	tasks: Type.Optional(Type.Array(TeamsDelegateTaskSchema, { description: "Tasks to delegate (action=delegate)." })),
+	teammates: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Explicit comrade names to use/spawn. If omitted, uses existing or auto-generates.",
+		}),
+	),
+	maxTeammates: Type.Optional(
+		Type.Integer({
+			description: "If comrades list is omitted and none exist, spawn up to this many.",
+			default: 4,
+			minimum: 1,
+			maximum: 16,
+		}),
+	),
+	contextMode: Type.Optional(TeamsContextModeSchema),
+	workspaceMode: Type.Optional(TeamsWorkspaceModeSchema),
+});
+
+type TeamsToolParamsType = Static<typeof TeamsToolParamsSchema>;
+
+export function registerTeamsTool(opts: {
+	pi: ExtensionAPI;
+	teammates: Map<string, TeammateRpc>;
+	spawnTeammate: SpawnTeammateFn;
+	getTaskListId: () => string | null;
+	taskAssignmentPayload: (task: TeamTask, assignedBy: string) => unknown;
+	refreshTasks: () => Promise<void>;
+	renderWidget: () => void;
+}): void {
+	const { pi, teammates, spawnTeammate, getTaskListId, taskAssignmentPayload, refreshTasks, renderWidget } = opts;
+
+	pi.registerTool({
+		name: "teams",
+		label: "Teams",
+		description: [
+			"Spawn comrade agents and delegate tasks. Each comrade is a child Pi process that executes work autonomously and reports back.",
+			"Provide a list of tasks with optional assignees; comrades are spawned automatically and assigned round-robin if unspecified.",
+			"Options: contextMode=branch (clone session context), workspaceMode=worktree (git worktree isolation).",
+			"For governance, the user can run /team delegate on (leader restricted to coordination) or /team spawn <name> plan (worker needs plan approval).",
+		].join(" "),
+		parameters: TeamsToolParamsSchema,
+
+		async execute(_toolCallId, params: TeamsToolParamsType, signal, _onUpdate, ctx): Promise<AgentToolResult<unknown>> {
+			const action = params.action ?? "delegate";
+			if (action !== "delegate") {
+				return {
+					content: [{ type: "text", text: `Unsupported action: ${String(action)}` }],
+					details: { action },
+				};
+			}
+
+			const inputTasks: TeamsToolDelegateTask[] = params.tasks ?? [];
+			if (inputTasks.length === 0) {
+				return {
+					content: [{ type: "text", text: "No tasks provided. Provide tasks: [{text, assignee?}, ...]" }],
+					details: { action },
+				};
+			}
+
+			const contextMode: ContextMode = params.contextMode === "branch" ? "branch" : "fresh";
+			const requestedWorkspaceMode: WorkspaceMode = params.workspaceMode === "worktree" ? "worktree" : "shared";
+
+			const teamId = ctx.sessionManager.getSessionId();
+			const teamDir = getTeamDir(teamId);
+			const taskListId = getTaskListId();
+			const cfg = await ensureTeamConfig(teamDir, {
+				teamId,
+				taskListId: taskListId ?? teamId,
+				leadName: "team-lead",
+				style: getTeamsStyleFromEnv(),
+			});
+			const style: TeamsStyle = cfg.style ?? getTeamsStyleFromEnv();
+
+			let teammateNames: string[] = [];
+			const explicit = params.teammates;
+			if (explicit && explicit.length) {
+				teammateNames = explicit.map((n) => sanitizeName(n)).filter((n) => n.length > 0);
+			}
+
+			if (teammateNames.length === 0 && teammates.size > 0) {
+				teammateNames = Array.from(teammates.keys());
+			}
+
+			if (teammateNames.length === 0) {
+				const maxTeammates = Math.max(1, Math.min(16, params.maxTeammates ?? 4));
+				const count = Math.min(maxTeammates, inputTasks.length);
+				const taken = new Set(teammates.keys());
+				teammateNames = style === "soviet" ? pickComradeNames(count, taken) : pickAgentNames(count, taken);
+			}
+
+			const spawned: string[] = [];
+			const warnings: string[] = [];
+
+			for (const name of teammateNames) {
+				if (signal?.aborted) break;
+				if (teammates.has(name)) continue;
+				const res = await spawnTeammate(ctx, {
+					name,
+					mode: contextMode,
+					workspaceMode: requestedWorkspaceMode,
+				});
+				if (!res.ok) {
+					warnings.push(`Failed to spawn '${name}': ${res.error}`);
+					continue;
+				}
+				spawned.push(res.name);
+				warnings.push(...res.warnings);
+			}
+
+			// Assign tasks (explicit assignee wins; otherwise round-robin)
+			const assignments: Array<{ taskId: string; assignee: string; subject: string }> = [];
+			let rr = 0;
+			for (const t of inputTasks) {
+				if (signal?.aborted) break;
+
+				const text = t.text.trim();
+				if (!text) {
+					warnings.push("Skipping empty task");
+					continue;
+				}
+
+				const explicitAssignee = t.assignee ? sanitizeName(t.assignee) : undefined;
+				const assignee = explicitAssignee ?? teammateNames[rr++ % teammateNames.length];
+				if (!assignee) {
+					warnings.push(`No assignee available for task: ${text.slice(0, 60)}`);
+					continue;
+				}
+
+				// Ensure assignee exists
+				if (!teammates.has(assignee)) {
+					const res = await spawnTeammate(ctx, {
+						name: assignee,
+						mode: contextMode,
+						workspaceMode: requestedWorkspaceMode,
+					});
+					if (res.ok) {
+						spawned.push(res.name);
+						warnings.push(...res.warnings);
+					} else {
+						warnings.push(`Failed to spawn assignee '${assignee}': ${res.error}`);
+						continue;
+					}
+				}
+
+				const description = text;
+				const firstLine = description.split("\n").at(0) ?? "";
+				const subject = firstLine.slice(0, 120);
+				const effectiveTlId = taskListId ?? teamId;
+				const task = await createTask(teamDir, effectiveTlId, { subject, description, owner: assignee });
+
+				await writeToMailbox(teamDir, effectiveTlId, assignee, {
+					from: cfg.leadName,
+					text: JSON.stringify(taskAssignmentPayload(task, cfg.leadName)),
+					timestamp: new Date().toISOString(),
+				});
+
+				assignments.push({ taskId: task.id, assignee, subject });
+			}
+
+			// Best-effort widget refresh
+			void refreshTasks().finally(renderWidget);
+
+			const lines: string[] = [];
+			if (spawned.length) {
+				lines.push(`Spawned: ${spawned.map((n) => formatMemberDisplayName(style, n)).join(", ")}`);
+			}
+			lines.push(`Delegated ${assignments.length} task(s):`);
+			for (const a of assignments) {
+				lines.push(`- #${a.taskId} → ${formatMemberDisplayName(style, a.assignee)}: ${a.subject}`);
+			}
+			if (warnings.length) {
+				lines.push("\nWarnings:");
+				for (const w of warnings) lines.push(`- ${w}`);
+			}
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: {
+					action,
+					teamId,
+					contextMode,
+					workspaceMode: requestedWorkspaceMode,
+					spawned,
+					assignments,
+					warnings,
+				},
+			};
+		},
+	});
+}