@tmustier/pi-agent-teams 0.4.0 → 0.5.1

package/extensions/teams/leader.ts

@@ -9,15 +9,17 @@ import { TEAM_MAILBOX_NS, taskAssignmentPayload } from "./protocol.js";
 import { createTask, listTasks, unassignTasksForAgent, updateTask, type TeamTask } from "./task-store.js";
 import { TeammateRpc } from "./teammate-rpc.js";
 import { ensureTeamConfig, loadTeamConfig, setMemberStatus, upsertMember, type TeamConfig } from "./team-config.js";
-import { getTeamDir } from "./paths.js";
-import { heartbeatTeamAttachClaim, releaseTeamAttachClaim } from "./team-attach-claim.js";
-import { ensureWorktreeCwd } from "./worktree.js";
+import { getTeamDir, getTeamsRootDir } from "./paths.js";
+import { assessAttachClaimFreshness, heartbeatTeamAttachClaim, readTeamAttachClaim, releaseTeamAttachClaim } from "./team-attach-claim.js";
+import { cleanupTeamDir, gcStaleTeamDirs } from "./cleanup.js";
+import { ensureWorktreeCwd, cleanupWorktrees } from "./worktree.js";
 import { ActivityTracker, TranscriptTracker } from "./activity-tracker.js";
 import { openInteractiveWidget } from "./teams-panel.js";
+import { isTeamDone } from "./teams-ui-shared.js";
 import { createTeamsWidget } from "./teams-widget.js";
 import { resolveTeammateModelSelection, formatProviderModel } from "./model-policy.js";
 import { getTeamsStyleFromEnv, type TeamsStyle, formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
-import { pollLeaderInbox as pollLeaderInboxImpl } from "./leader-inbox.js";
+import { DelegationTracker, pollLeaderInbox as pollLeaderInboxImpl } from "./leader-inbox.js";
 import {
 	getHookBaseName,
 	getTeamsHookFailureAction,
@@ -105,6 +107,29 @@ async function createSessionForTeammate(
 	}
 }
 
+/** Check if a team dir has any task files across all task-list namespaces. */
+async function teamDirHasAnyTasks(teamDir: string): Promise<boolean> {
+	const tasksDir = path.join(teamDir, "tasks");
+	let taskListDirs: string[];
+	try {
+		taskListDirs = await fs.promises.readdir(tasksDir);
+	} catch {
+		return false;
+	}
+	for (const listDir of taskListDirs) {
+		const listPath = path.join(tasksDir, listDir);
+		try {
+			const stat = await fs.promises.stat(listPath);
+			if (!stat.isDirectory()) continue;
+			const files = await fs.promises.readdir(listPath);
+			if (files.some((f) => f.endsWith(".json") && !f.startsWith("."))) return true;
+		} catch {
+			continue;
+		}
+	}
+	return false;
+}
+
 // Message parsers are shared with the worker implementation.
 export function runLeader(pi: ExtensionAPI): void {
 	const teammates = new Map<string, TeammateRpc>();
@@ -116,6 +141,7 @@ export function runLeader(pi: ExtensionAPI): void {
 	let tasks: TeamTask[] = [];
 	let teamConfig: TeamConfig | null = null;
 	const pendingPlanApprovals = new Map<string, { requestId: string; name: string; taskId?: string }>();
+	const delegationTracker = new DelegationTracker();
 	// Task list namespace. By default we keep it aligned with the current session id.
 	// (Do NOT read PI_TEAMS_TASK_LIST_ID for the leader; that env var is intended for workers
 	// and can easily be set globally, which makes the leader "lose" its tasks.)
@@ -160,6 +186,7 @@ export function runLeader(pi: ExtensionAPI): void {
 		);
 		currentTeamId = sessionTeamId;
 		taskListId = sessionTeamId;
+		delegationTracker.clear();
 		await refreshTasks();
 		renderWidget();
 	};
@@ -411,8 +438,16 @@ export function runLeader(pi: ExtensionAPI): void {
 		isDelegateMode: () => delegateMode,
 		getActiveTeamId: () => currentTeamId,
 		getSessionTeamId: () => currentCtx?.sessionManager.getSessionId() ?? null,
+		getLeaderModel: () => {
+			const model = currentCtx?.model;
+			if (!model) return null;
+			return { provider: model.provider, modelId: model.id };
+		},
 	});
 
+	// Auto-done detection: notify once when all tasks complete and teammates idle.
+	let autoDoneNotified = false;
+
 	const refreshTasks = async () => {
 		if (!currentCtx || !currentTeamId) return;
 		const teamDir = getTeamDir(currentTeamId);
@@ -429,6 +464,17 @@ export function runLeader(pi: ExtensionAPI): void {
 				style,
 			}));
 		style = teamConfig.style ?? style;
+
+		// Auto-done hint (fire once per "all done" state transition)
+		if (isTeamDone(tasks, teammates)) {
+			if (!autoDoneNotified) {
+				autoDoneNotified = true;
+				currentCtx.ui.notify("All tasks completed. Use /team done to end the team session.", "info");
+			}
+		} else {
+			// Reset when work resumes (new tasks added, etc.)
+			autoDoneNotified = false;
+		}
 	};
 
 	let widgetSuppressed = false;
@@ -439,6 +485,16 @@ export function runLeader(pi: ExtensionAPI): void {
 		currentCtx.ui.setWidget("pi-teams", widgetFactory);
 	};
 
+	const hideWidget = () => {
+		widgetSuppressed = true;
+		if (currentCtx) currentCtx.ui.setWidget("pi-teams", undefined);
+	};
+
+	const restoreWidget = () => {
+		widgetSuppressed = false;
+		renderWidget();
+	};
+
 	const spawnTeammate: SpawnTeammateFn = async (ctx, opts): Promise<SpawnTeammateResult> => {
 		const warnings: string[] = [];
 		const mode: ContextMode = opts.mode ?? "fresh";
@@ -472,10 +528,21 @@ export function runLeader(pi: ExtensionAPI): void {
 
 		const t = new TeammateRpc(name, sessionFile);
 		teammates.set(name, t);
+		// Restore the widget if it was hidden by /team done — new work is starting.
+		restoreWidget();
 		// Track teammate activity for the widget/panel.
+		// Render on status-changing events for a more "live" feel.
 		const unsub = t.onEvent((ev) => {
 			tracker.handleEvent(name, ev);
 			transcriptTracker.handleEvent(name, ev);
+			// Refresh widget on events that change visible state (tool start/end, turn end).
+			if (
+				ev.type === "tool_execution_start" ||
+				ev.type === "tool_execution_end" ||
+				ev.type === "agent_end"
+			) {
+				renderWidget();
+			}
 		});
 		teammateEventUnsubs.set(name, unsub);
 		renderWidget();
@@ -598,7 +665,17 @@ export function runLeader(pi: ExtensionAPI): void {
 		await refreshTasks();
 		renderWidget();
 
-		return { ok: true, name, mode, workspaceMode, childCwd, note, warnings };
+		return {
+			ok: true,
+			name,
+			mode,
+			workspaceMode,
+			childCwd,
+			note,
+			model: childModel ?? undefined,
+			thinking: thinkingLevel,
+			warnings,
+		};
 	};
 
 	const pollLeaderInbox = async () => {
@@ -614,6 +691,10 @@ export function runLeader(pi: ExtensionAPI): void {
 			style,
 			pendingPlanApprovals,
 			enqueueHook,
+			sendLeaderLlmMessage: (content, options) => {
+				pi.sendUserMessage(content, options);
+			},
+			delegationTracker,
 		});
 	};
 
@@ -632,6 +713,9 @@ export function runLeader(pi: ExtensionAPI): void {
 		// use `/team task use <taskListId>` after switching.
 		taskListId = currentTeamId;
 		lastAttachClaimHeartbeatMs = 0;
+		// Clear any /team done suppression from a previous session.
+		widgetSuppressed = false;
+		autoDoneNotified = false;
 
 		// Claude-style: a persisted team config file.
 		await ensureTeamConfig(getTeamDir(currentTeamId), {
@@ -641,6 +725,15 @@ export function runLeader(pi: ExtensionAPI): void {
 			style,
 		});
 
+		// Startup GC: silently remove stale team directories from previous sessions (24h age floor).
+		void gcStaleTeamDirs({
+			teamsRootDir: getTeamsRootDir(),
+			maxAgeMs: 24 * 60 * 60 * 1000,
+			excludeTeamIds: new Set([currentTeamId]),
+		}).catch(() => {
+			// Best-effort; never block the session.
+		});
+
 		await refreshTasks();
 		renderWidget();
 
@@ -671,12 +764,28 @@ export function runLeader(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_switch", async (_event, ctx) => {
+		const prevTeamId = currentTeamId;
+		const prevCwd = currentCtx?.cwd;
+
 		if (currentCtx) {
 			await releaseActiveAttachClaim(currentCtx);
 			const strings = getTeamsStrings(style);
 			await stopAllTeammates(currentCtx, `The ${strings.teamNoun} is dissolved — leader moved on`);
 		}
 		stopLoops();
+		delegationTracker.clear();
+
+		// Clean up worktrees from the old session before switching.
+		// Only clean up teams this session owns — never attached teams.
+		const prevSessionId = currentCtx?.sessionManager.getSessionId();
+		if (prevTeamId && prevTeamId === prevSessionId) {
+			const teamDir = getTeamDir(prevTeamId);
+			try {
+				await cleanupWorktrees({ teamDir, teamId: prevTeamId, repoCwd: prevCwd });
+			} catch {
+				// Best-effort — don't block session switch.
+			}
+		}
 
 		currentCtx = ctx;
 		currentTeamId = currentCtx.sessionManager.getSessionId();
@@ -684,6 +793,9 @@ export function runLeader(pi: ExtensionAPI): void {
 		// use `/team task use <taskListId>` after switching.
 		taskListId = currentTeamId;
 		lastAttachClaimHeartbeatMs = 0;
+		// Clear any /team done suppression — new session context.
+		widgetSuppressed = false;
+		autoDoneNotified = false;
 
 		await ensureTeamConfig(getTeamDir(currentTeamId), {
 			teamId: currentTeamId,
@@ -725,8 +837,45 @@ export function runLeader(pi: ExtensionAPI): void {
 		if (!currentCtx) return;
 		await releaseActiveAttachClaim(currentCtx);
 		stopLoops();
+		const hadTeammates = teammates.size > 0;
 		const strings = getTeamsStrings(style);
 		await stopAllTeammates(currentCtx, `The ${strings.teamNoun} is over`);
+
+		// Clean up worktrees + branches for this team session so they don't accumulate on disk.
+		// Only clean up teams this session owns — never attached teams.
+		const sessionId = currentCtx.sessionManager.getSessionId();
+		if (currentTeamId && currentTeamId === sessionId) {
+			const teamDir = getTeamDir(currentTeamId);
+			try {
+				await cleanupWorktrees({ teamDir, teamId: currentTeamId, repoCwd: currentCtx.cwd });
+			} catch {
+				// Best-effort — don't block shutdown.
+			}
+
+			// Exit cleanup: delete own team directory if it's empty.
+			// Conservative: only if no RPC teammates were active, no online workers in
+			// config (manual/tmux), no tasks in ANY namespace, and no fresh attach claim.
+			// (Dirs with completed tasks are left for the 24h startup GC — intentionally
+			// asymmetric for safety.)
+			if (!hadTeammates) {
+				try {
+					const claim = await readTeamAttachClaim(teamDir);
+					const claimIsLive = claim !== null && !assessAttachClaimFreshness(claim).isStale;
+					if (claimIsLive) {
+						// Another session is using this team — don't delete.
+					} else {
+						// Also check config for online non-lead members (manual/tmux workers).
+						const cfg = await loadTeamConfig(teamDir);
+						const hasOnlineWorkers = cfg?.members.some((m) => m.role !== "lead" && m.status === "online") ?? false;
+						if (!hasOnlineWorkers && !(await teamDirHasAnyTasks(teamDir))) {
+							await cleanupTeamDir(getTeamsRootDir(), teamDir);
+						}
+					}
+				} catch {
+					// Best-effort; never block shutdown.
+				}
+			}
+		}
 	});
 
 	registerTeamsTool({
@@ -735,9 +884,17 @@ export function runLeader(pi: ExtensionAPI): void {
 		spawnTeammate,
 		getTeamId: (ctx) => currentTeamId ?? ctx.sessionManager.getSessionId(),
 		getTaskListId: () => taskListId,
+		getTracker: () => tracker,
+		getTeamConfig: () => teamConfig,
 		refreshTasks,
 		renderWidget,
+		hideWidget,
+		stopAllTeammates: async (reason: string) => {
+			if (!currentCtx) return;
+			await stopAllTeammates(currentCtx, reason);
+		},
 		pendingPlanApprovals,
+		delegationTracker,
 	});
 
 	const openWidget = async (ctx: ExtensionCommandContext) => {
@@ -841,13 +998,16 @@ export function runLeader(pi: ExtensionAPI): void {
 			getSessionTeamId() {
 				return ctx.sessionManager.getSessionId();
 			},
+			getLeaderModel() {
+				const model = currentCtx?.model;
+				if (!model) return null;
+				return { provider: model.provider, modelId: model.id };
+			},
 			suppressWidget() {
-				widgetSuppressed = true;
-				ctx.ui.setWidget("pi-teams", undefined);
+				hideWidget();
 			},
 			restoreWidget() {
-				widgetSuppressed = false;
-				renderWidget();
+				restoreWidget();
 			},
 		});
 	};
@@ -893,16 +1053,21 @@ export function runLeader(pi: ExtensionAPI): void {
 				ctx,
 				teammates,
 				getTeamConfig: () => teamConfig,
+				getTracker: () => tracker,
 				getTasks: () => tasks,
 				refreshTasks,
 				renderWidget,
+				hideWidget,
+				restoreWidget,
 				getTaskListId: () => taskListId,
 				setTaskListId: (id) => {
 					taskListId = id;
+					delegationTracker.clear();
 				},
 				getActiveTeamId: () => currentTeamId ?? ctx.sessionManager.getSessionId(),
 				setActiveTeamId: (teamId) => {
 					currentTeamId = teamId;
+					delegationTracker.clear();
 				},
 				pendingPlanApprovals,
 				getDelegateMode: () => delegateMode,

package/extensions/teams/mailbox.ts

@@ -9,6 +9,9 @@ export interface MailboxMessage {
 	timestamp: string;
 	read: boolean;
 	color?: string;
+	/** When true, the recipient should deliver this message as a steering interrupt
+	 *  even if the agent is mid-turn, rather than queueing for the next idle window. */
+	urgent?: boolean;
 }
 
 function inboxDir(teamDir: string, namespace: string): string {
@@ -38,7 +41,8 @@ function coerceMailboxMessage(v: unknown): MailboxMessage | null {
 	if (typeof v.timestamp !== "string") return null;
 	const read = typeof v.read === "boolean" ? v.read : false;
 	const color = typeof v.color === "string" ? v.color : undefined;
-	return { from: v.from, text: v.text, timestamp: v.timestamp, read, color };
+	const urgent = typeof v.urgent === "boolean" ? v.urgent : undefined;
+	return { from: v.from, text: v.text, timestamp: v.timestamp, read, color, urgent };
 }
 
 async function readJsonArray(file: string): Promise<unknown[]> {
@@ -80,6 +84,7 @@ export async function writeToMailbox(
 				timestamp: msg.timestamp,
 				read: msg.read ?? false,
 				color: msg.color,
+				...(msg.urgent === true ? { urgent: true } : {}),
 			};
 			arr.push(m);
 			await writeJsonAtomic(inboxPath, arr);

package/extensions/teams/spawn-types.ts

@@ -29,6 +29,10 @@ export type SpawnTeammateResult =
 			workspaceMode: WorkspaceMode;
 			childCwd?: string;
 			note?: string;
+			/** The resolved model string (provider/modelId or modelId), if any. */
+			model?: string;
+			/** The effective thinking level for this teammate. */
+			thinking?: ThinkingLevel;
 			warnings: string[];
 	  }
 	| { ok: false; error: string };

package/extensions/teams/teammate-rpc.ts

@@ -86,6 +86,12 @@ export class TeammateRpc {
 	/** Task currently assigned by the team lead (if any). */
 	currentTaskId: string | null = null;
 
+	/** Epoch ms when the current `status` was entered. */
+	lastStatusChangeAt: number = Date.now();
+
+	/** Epoch ms of the most recent agent event received from the child process. */
+	lastEventAt: number = Date.now();
+
 	private proc: ReturnType<typeof spawn> | null = null;
 	private pending = new Map<string, { resolve: (v: RpcResponse) => void; reject: (e: Error) => void }>();
 	private nextId = 0;
@@ -164,6 +170,9 @@ export class TeammateRpc {
 		// Give the child a moment to boot.
 		await new Promise((r) => setTimeout(r, 120));
 		this.status = "idle";
+		const bootNow = Date.now();
+		this.lastStatusChangeAt = bootNow;
+		this.lastEventAt = bootNow;
 	}
 
 	async stop(): Promise<void> {
@@ -224,12 +233,17 @@ export class TeammateRpc {
 		// Agent event
 		if (!isAgentEvent(obj)) return;
 		const ev = obj;
+		const now = Date.now();
+		this.lastEventAt = now;
+
 		if (ev.type === "agent_start") {
 			this.status = "streaming";
+			this.lastStatusChangeAt = now;
 			this.lastAssistantText = "";
 		}
 		if (ev.type === "agent_end") {
 			this.status = "idle";
+			this.lastStatusChangeAt = now;
 		}
 		if (ev.type === "message_update") {
 			const ame = ev.assistantMessageEvent;