@tmustier/pi-agent-teams 0.4.0-beta.3 → 0.5.0

package/extensions/teams/leader.ts

@@ -11,13 +11,14 @@ 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 { 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 { isDeprecatedTeammateModelId } from "./model-policy.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,
@@ -116,6 +117,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 +162,7 @@ export function runLeader(pi: ExtensionAPI): void {
 		);
 		currentTeamId = sessionTeamId;
 		taskListId = sessionTeamId;
+		delegationTracker.clear();
 		await refreshTasks();
 		renderWidget();
 	};
@@ -411,8 +414,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 +440,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 +461,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";
@@ -453,49 +485,15 @@ export function runLeader(pi: ExtensionAPI): void {
 
 		// Spawn-time model / thinking overrides (optional).
 		const thinkingLevel = opts.thinking ?? pi.getThinkingLevel();
-		let childProvider: string | undefined;
-		let childModelId: string | undefined;
-
-		const modelOverrideRaw = opts.model?.trim();
-		if (modelOverrideRaw) {
-			const slashIdx = modelOverrideRaw.indexOf("/");
-			if (slashIdx >= 0) {
-				const provider = modelOverrideRaw.slice(0, slashIdx).trim();
-				const id = modelOverrideRaw.slice(slashIdx + 1).trim();
-				if (!provider || !id) {
-					return {
-						ok: false,
-						error: `Invalid model override '${modelOverrideRaw}'. Expected <provider>/<modelId>.`,
-					};
-				}
-				if (isDeprecatedTeammateModelId(id)) {
-					return {
-						ok: false,
-						error: `Model override '${modelOverrideRaw}' is deprecated. Choose a current model id.`,
-					};
-				}
-				childProvider = provider;
-				childModelId = id;
-			} else {
-				if (isDeprecatedTeammateModelId(modelOverrideRaw)) {
-					return {
-						ok: false,
-						error: `Model override '${modelOverrideRaw}' is deprecated. Choose a current model id.`,
-					};
-				}
-				childModelId = modelOverrideRaw;
-				childProvider = ctx.model?.provider;
-				if (!childProvider) {
-					warnings.push(
-						`Model override '${modelOverrideRaw}' provided without a provider. ` +
-							`Teammate will use its default provider; use <provider>/<modelId> to force one.`,
-					);
-				}
-			}
-		} else if (ctx.model && !isDeprecatedTeammateModelId(ctx.model.id)) {
-			childProvider = ctx.model.provider;
-			childModelId = ctx.model.id;
-		}
+
+		const modelResolution = resolveTeammateModelSelection({
+			modelOverride: opts.model,
+			leaderProvider: ctx.model?.provider,
+			leaderModelId: ctx.model?.id,
+		});
+		if (!modelResolution.ok) return { ok: false, error: modelResolution.error };
+		const { provider: childProvider, modelId: childModelId, warnings: modelWarnings } = modelResolution.value;
+		warnings.push(...modelWarnings);
 
 		const teamId = currentTeamId ?? ctx.sessionManager.getSessionId();
 		const teamDir = getTeamDir(teamId);
@@ -506,10 +504,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();
@@ -614,6 +623,7 @@ export function runLeader(pi: ExtensionAPI): void {
 		}
 
 		await ensureTeamConfig(teamDir, { teamId, taskListId: taskListId ?? teamId, leadName: "team-lead", style });
+		const childModel = formatProviderModel(childProvider, childModelId);
 		await upsertMember(teamDir, {
 			name,
 			role: "worker",
@@ -624,14 +634,24 @@ export function runLeader(pi: ExtensionAPI): void {
 				workspaceMode,
 				sessionName,
 				thinkingLevel,
-				...(childModelId ? { model: childProvider ? `${childProvider}/${childModelId}` : childModelId } : {}),
+				...(childModel ? { model: childModel } : {}),
 			},
 		});
 
 		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 () => {
@@ -647,6 +667,10 @@ export function runLeader(pi: ExtensionAPI): void {
 			style,
 			pendingPlanApprovals,
 			enqueueHook,
+			sendLeaderLlmMessage: (content, options) => {
+				pi.sendUserMessage(content, options);
+			},
+			delegationTracker,
 		});
 	};
 
@@ -665,6 +689,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), {
@@ -704,12 +731,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();
@@ -717,6 +760,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,
@@ -760,6 +806,18 @@ export function runLeader(pi: ExtensionAPI): void {
 		stopLoops();
 		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.
+			}
+		}
 	});
 
 	registerTeamsTool({
@@ -768,9 +826,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) => {
@@ -874,13 +940,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();
 			},
 		});
 	};
@@ -926,16 +995,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/model-policy.ts

@@ -12,6 +12,12 @@ function hasAnyMarker(value: string, markers: readonly string[]): boolean {
 	return false;
 }
 
+function trimOrUndefined(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
 export function isDeprecatedTeammateModelId(modelId: string): boolean {
 	const normalized = normalizeModelId(modelId);
 	if (!normalized) return false;
@@ -23,3 +29,114 @@ export function isDeprecatedTeammateModelId(modelId: string): boolean {
 	if (!next) return true;
 	return next === "-" || next === "_" || next === "." || next === ":";
 }
+
+export type TeammateModelSource = "override" | "inherit_leader" | "default";
+
+export interface ResolvedTeammateModel {
+	source: TeammateModelSource;
+	provider?: string;
+	modelId?: string;
+	warnings: string[];
+}
+
+export type ResolveTeammateModelResult =
+	| {
+			ok: true;
+			value: ResolvedTeammateModel;
+	  }
+	| {
+			ok: false;
+			error: string;
+			reason: "invalid_override" | "deprecated_override";
+	  };
+
+export function formatProviderModel(provider: string | undefined, modelId: string | undefined): string | null {
+	if (!modelId) return null;
+	return provider ? `${provider}/${modelId}` : modelId;
+}
+
+export function resolveTeammateModelSelection(input: {
+	modelOverride?: string;
+	leaderProvider?: string;
+	leaderModelId?: string;
+}): ResolveTeammateModelResult {
+	const override = trimOrUndefined(input.modelOverride);
+	if (override) {
+		const slashIdx = override.indexOf("/");
+		if (slashIdx >= 0) {
+			const provider = override.slice(0, slashIdx).trim();
+			const id = override.slice(slashIdx + 1).trim();
+			if (!provider || !id) {
+				return {
+					ok: false,
+					reason: "invalid_override",
+					error: `Invalid model override '${override}'. Expected <provider>/<modelId>.`,
+				};
+			}
+			if (isDeprecatedTeammateModelId(id)) {
+				return {
+					ok: false,
+					reason: "deprecated_override",
+					error: `Model override '${override}' is deprecated. Choose a current model id.`,
+				};
+			}
+			return {
+				ok: true,
+				value: {
+					source: "override",
+					provider,
+					modelId: id,
+					warnings: [],
+				},
+			};
+		}
+
+		if (isDeprecatedTeammateModelId(override)) {
+			return {
+				ok: false,
+				reason: "deprecated_override",
+				error: `Model override '${override}' is deprecated. Choose a current model id.`,
+			};
+		}
+
+		const leaderProvider = trimOrUndefined(input.leaderProvider);
+		const warnings: string[] = [];
+		if (!leaderProvider) {
+			warnings.push(
+				`Model override '${override}' provided without a provider. ` +
+					`Teammate will use its default provider; use <provider>/<modelId> to force one.`,
+			);
+		}
+		return {
+			ok: true,
+			value: {
+				source: "override",
+				provider: leaderProvider,
+				modelId: override,
+				warnings,
+			},
+		};
+	}
+
+	const leaderModelId = trimOrUndefined(input.leaderModelId);
+	const leaderProvider = trimOrUndefined(input.leaderProvider);
+	if (leaderModelId && !isDeprecatedTeammateModelId(leaderModelId)) {
+		return {
+			ok: true,
+			value: {
+				source: "inherit_leader",
+				provider: leaderProvider,
+				modelId: leaderModelId,
+				warnings: [],
+			},
+		};
+	}
+
+	return {
+		ok: true,
+		value: {
+			source: "default",
+			warnings: [],
+		},
+	};
+}

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;