@clinebot/core 0.0.34 → 0.0.35

package/src/extensions/tools/team/multi-agent.lifecycle.test.ts

@@ -0,0 +1,455 @@
+import type { AgentEvent } from "@clinebot/shared";
+import { describe, expect, it, vi } from "vitest";
+import {
+	AgentTeamsRuntime,
+	type TeamEvent,
+	TeamMessageType,
+} from "./multi-agent";
+
+const { createAgentMock } = vi.hoisted(() => ({
+	createAgentMock: vi.fn(),
+}));
+
+vi.mock("@clinebot/agents", async () => {
+	const actual =
+		await vi.importActual<typeof import("@clinebot/agents")>(
+			"@clinebot/agents",
+		);
+
+	return {
+		...actual,
+		createAgent: createAgentMock,
+	};
+});
+
+describe("AgentTeamsRuntime teammate lifecycle events", () => {
+	it("spawns teammates with a 10 minute API timeout", () => {
+		createAgentMock.mockReturnValueOnce({
+			abort: vi.fn(),
+			run: vi.fn(),
+			continue: vi.fn(),
+			canStartRun: vi.fn(() => true),
+			getAgentId: vi.fn(() => "teammate-1"),
+			getConversationId: vi.fn(() => "conv-1"),
+			getMessages: vi.fn(() => []),
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+		});
+
+		runtime.spawnTeammate({
+			agentId: "python-poet",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Write concise Python-focused haiku",
+				tools: [],
+			},
+		});
+
+		expect(createAgentMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				apiTimeoutMs: 10 * 60 * 1000,
+			}),
+		);
+	});
+
+	it("does not emit task_start when teammate is already busy", async () => {
+		const events: TeamEvent[] = [];
+		createAgentMock.mockReturnValueOnce({
+			abort: vi.fn(),
+			run: vi.fn(),
+			continue: vi.fn(),
+			canStartRun: vi.fn(() => false),
+			getAgentId: vi.fn(() => "teammate-1"),
+			getConversationId: vi.fn(() => "conv-1"),
+			getMessages: vi.fn(() => []),
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+			onTeamEvent: (event) => events.push(event),
+		});
+
+		runtime.spawnTeammate({
+			agentId: "python-poet",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Write concise Python-focused haiku",
+				maxIterations: 7,
+				tools: [],
+			},
+		});
+
+		await expect(
+			runtime.routeToTeammate("python-poet", "write something"),
+		).rejects.toThrow(
+			"Cannot start a new run while another run is already in progress",
+		);
+		expect(
+			events.some((event) => event.type === TeamMessageType.TaskStart),
+		).toBe(false);
+	});
+
+	it("emits teammate_spawned with lifecycle payload", () => {
+		const events: TeamEvent[] = [];
+		createAgentMock.mockReturnValueOnce({
+			abort: vi.fn(),
+			run: vi.fn(),
+			continue: vi.fn(),
+			canStartRun: vi.fn(() => true),
+			getAgentId: vi.fn(() => "teammate-1"),
+			getConversationId: vi.fn(() => "conv-1"),
+			getMessages: vi.fn(() => []),
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+			onTeamEvent: (event) => events.push(event),
+		});
+
+		runtime.spawnTeammate({
+			agentId: "python-poet",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Write concise Python-focused haiku",
+				maxIterations: 7,
+				tools: [],
+			},
+		});
+
+		expect(events).toContainEqual({
+			type: TeamMessageType.TeammateSpawned,
+			agentId: "python-poet",
+			role: undefined,
+			teammate: {
+				rolePrompt: "Write concise Python-focused haiku",
+				modelId: "claude-sonnet-4-5-20250929",
+				maxIterations: 7,
+				runtimeAgentId: "teammate-1",
+				conversationId: "conv-1",
+				parentAgentId: null,
+			},
+		});
+	});
+
+	it("swallows abort-like shutdown errors from teammates", () => {
+		const events: TeamEvent[] = [];
+		createAgentMock.mockReturnValueOnce({
+			abort: vi.fn(() => {
+				throw new DOMException("This operation was aborted", "AbortError");
+			}),
+			run: vi.fn(),
+			continue: vi.fn(),
+			canStartRun: vi.fn(() => true),
+			getAgentId: vi.fn(() => "teammate-1"),
+			getConversationId: vi.fn(() => "conv-1"),
+			getMessages: vi.fn(() => []),
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+			onTeamEvent: (event) => events.push(event),
+		});
+
+		runtime.spawnTeammate({
+			agentId: "python-poet",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Write concise Python-focused haiku",
+				tools: [],
+			},
+		});
+
+		expect(() =>
+			runtime.shutdownTeammate("python-poet", "manual_restart"),
+		).not.toThrow();
+		expect(runtime.getSnapshot().members).toContainEqual(
+			expect.objectContaining({
+				agentId: "python-poet",
+				status: "stopped",
+			}),
+		);
+		expect(events).toContainEqual({
+			type: TeamMessageType.TeammateShutdown,
+			agentId: "python-poet",
+			reason: "manual_restart",
+		});
+	});
+
+	it("prepends unread mailbox notification to teammate message", async () => {
+		let routedMessage: string | undefined;
+		createAgentMock.mockReturnValueOnce({
+			abort: vi.fn(),
+			run: vi.fn(async (message) => {
+				routedMessage = message;
+				return {
+					text: "Task completed",
+					iterations: 1,
+					finishReason: "end_turn",
+					durationMs: 100,
+					usage: {
+						inputTokens: 10,
+						outputTokens: 20,
+						cacheReadTokens: 0,
+						cacheWriteTokens: 0,
+						totalCost: 0,
+					},
+					messages: [],
+				};
+			}),
+			continue: vi.fn(),
+			canStartRun: vi.fn(() => true),
+			getAgentId: vi.fn(() => "teammate-1"),
+			getConversationId: vi.fn(() => "conv-1"),
+			getMessages: vi.fn(() => []),
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+		});
+
+		runtime.spawnTeammate({
+			agentId: "alice",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Helper teammate",
+				tools: [],
+			},
+		});
+
+		// Send message from lead to alice
+		runtime.sendMessage(
+			"lead",
+			"alice",
+			"Status check",
+			"How is your work going?",
+		);
+
+		// Route task to alice
+		await runtime.routeToTeammate("alice", "Complete your task");
+
+		// Verify the routed message includes mailbox notification
+		expect(routedMessage).toBeDefined();
+		expect(routedMessage).toContain("[MAILBOX]");
+		expect(routedMessage).toContain("You have 1 unread message(s)");
+		expect(routedMessage).toContain(
+			"Message from lead | subject: Status check",
+		);
+		expect(routedMessage).toContain("How is your work going?");
+		expect(routedMessage).toContain("Complete your task");
+
+		// Verify message is marked as read
+		const unreadAfter = runtime.listMailbox("alice", { unreadOnly: true });
+		expect(unreadAfter).toHaveLength(0);
+	});
+
+	it("does not prepend notification when no unread mail", async () => {
+		let routedMessage: string | undefined;
+		createAgentMock.mockReturnValueOnce({
+			abort: vi.fn(),
+			run: vi.fn(async (message) => {
+				routedMessage = message;
+				return {
+					text: "Task completed",
+					iterations: 1,
+					finishReason: "end_turn",
+					durationMs: 100,
+					usage: {
+						inputTokens: 10,
+						outputTokens: 20,
+						cacheReadTokens: 0,
+						cacheWriteTokens: 0,
+						totalCost: 0,
+					},
+					messages: [],
+				};
+			}),
+			continue: vi.fn(),
+			canStartRun: vi.fn(() => true),
+			getAgentId: vi.fn(() => "teammate-1"),
+			getConversationId: vi.fn(() => "conv-1"),
+			getMessages: vi.fn(() => []),
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+		});
+
+		runtime.spawnTeammate({
+			agentId: "bob",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Helper teammate",
+				tools: [],
+			},
+		});
+
+		// Route task to bob with no prior messages
+		await runtime.routeToTeammate("bob", "Complete your task");
+
+		// Verify the routed message does not contain mailbox notification
+		expect(routedMessage).toBeDefined();
+		expect(routedMessage).toBe("Complete your task");
+		expect(routedMessage).not.toContain("[MAILBOX]");
+	});
+
+	it("queues steer message notification when recipient is running", () => {
+		let consumePendingMessage: (() => string | undefined) | undefined;
+		createAgentMock.mockImplementationOnce((config) => {
+			consumePendingMessage = config.consumePendingUserMessage;
+			return {
+				abort: vi.fn(),
+				run: vi.fn(),
+				continue: vi.fn(),
+				canStartRun: vi.fn(() => true),
+				getAgentId: vi.fn(() => "teammate-1"),
+				getConversationId: vi.fn(() => "conv-1"),
+				getMessages: vi.fn(() => []),
+			};
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+		});
+
+		runtime.spawnTeammate({
+			agentId: "charlie",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Helper teammate",
+				tools: [],
+			},
+		});
+
+		// Simulate teammate is running by incrementing runningCount
+		const runtimeMembers = (
+			runtime as unknown as { members: Map<string, { runningCount: number }> }
+		).members;
+		const member = runtimeMembers.get("charlie");
+		if (member) {
+			member.runningCount = 1;
+		}
+
+		// Send message from lead while charlie is running
+		runtime.sendMessage("lead", "charlie", "urgent update", "Fix the bug now!");
+
+		// Verify steer message is queued
+		expect(consumePendingMessage).toBeDefined();
+		const steerMsg = consumePendingMessage?.();
+		expect(steerMsg).toBeDefined();
+		expect(steerMsg).toContain("[MAILBOX]");
+		expect(steerMsg).toContain("lead");
+		expect(steerMsg).toContain("urgent update");
+		expect(steerMsg).toContain("team_read_mailbox");
+
+		// Verify consuming again returns undefined
+		expect(consumePendingMessage?.()).toBeUndefined();
+	});
+
+	it("does not queue steer message when recipient is idle", () => {
+		let consumePendingMessage: (() => string | undefined) | undefined;
+		createAgentMock.mockImplementationOnce((config) => {
+			consumePendingMessage = config.consumePendingUserMessage;
+			return {
+				abort: vi.fn(),
+				run: vi.fn(),
+				continue: vi.fn(),
+				canStartRun: vi.fn(() => true),
+				getAgentId: vi.fn(() => "teammate-1"),
+				getConversationId: vi.fn(() => "conv-1"),
+				getMessages: vi.fn(() => []),
+			};
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+		});
+
+		runtime.spawnTeammate({
+			agentId: "diana",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Helper teammate",
+				tools: [],
+			},
+		});
+
+		// Send message from lead while diana is idle (runningCount = 0)
+		runtime.sendMessage("lead", "diana", "hello", "Hi there");
+
+		// Verify no steer message is queued
+		expect(consumePendingMessage?.()).toBeUndefined();
+
+		// Message should still be in mailbox for next route
+		const mailbox = runtime.listMailbox("diana", { unreadOnly: true });
+		expect(mailbox).toHaveLength(1);
+		expect(mailbox[0].subject).toBe("hello");
+	});
+
+	it("includes tool and run error details in run_progress activity", async () => {
+		const events: TeamEvent[] = [];
+		let wrappedOnEvent: ((event: AgentEvent) => void) | undefined;
+		createAgentMock.mockImplementationOnce((config) => {
+			wrappedOnEvent = config.onEvent;
+			return {
+				abort: vi.fn(),
+				run: vi.fn(async () => {
+					wrappedOnEvent?.({
+						type: "content_end",
+						contentType: "tool",
+						toolName: "team_mission_log",
+						error: "RPC backend returned 500 while appending mission log",
+					});
+					wrappedOnEvent?.({
+						type: "error",
+						error: new Error("API request timed out after 120000ms"),
+						recoverable: false,
+						iteration: 11,
+					});
+					throw new Error("API request timed out after 120000ms");
+				}),
+				continue: vi.fn(),
+				canStartRun: vi.fn(() => true),
+				getAgentId: vi.fn(() => "teammate-1"),
+				getConversationId: vi.fn(() => "conv-1"),
+				getMessages: vi.fn(() => []),
+			};
+		});
+		const runtime = new AgentTeamsRuntime({
+			teamName: "test-team",
+			onTeamEvent: (event) => events.push(event),
+		});
+
+		runtime.spawnTeammate({
+			agentId: "providers-investigator",
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+				systemPrompt: "Investigate providers thoroughly",
+				tools: [],
+			},
+		});
+
+		const run = runtime.startTeammateRun(
+			"providers-investigator",
+			"Investigate providers",
+		);
+		const settled = await runtime.awaitRun(run.id);
+
+		expect(settled.status).toBe("failed");
+		expect(events).toContainEqual(
+			expect.objectContaining({
+				type: TeamMessageType.RunProgress,
+				message:
+					"tool_team_mission_log_error: RPC backend returned 500 while appending mission log",
+			}),
+		);
+		expect(events).toContainEqual(
+			expect.objectContaining({
+				type: TeamMessageType.RunProgress,
+				message: "run_error: API request timed out after 120000ms",
+			}),
+		);
+	});
+});

package/src/{team → extensions/tools/team}/multi-agent.ts

@@ -138,6 +138,23 @@ export interface SpawnTeammateOptions {
 	config: TeamMemberConfig;
 }
 
+function isAbortLikeError(error: unknown): boolean {
+	if (
+		typeof DOMException !== "undefined" &&
+		error instanceof DOMException &&
+		error.name === "AbortError"
+	) {
+		return true;
+	}
+	if (!(error instanceof Error)) {
+		return false;
+	}
+	return (
+		error.name === "AbortError" ||
+		error.message.toLowerCase().includes("aborted")
+	);
+}
+
 // =============================================================================
 // AgentTeam
 // =============================================================================
@@ -484,6 +501,7 @@ interface TeamMemberState extends TeamMemberSnapshot {
 	runningCount: number;
 	lastMissionStep: number;
 	lastMissionAt: number;
+	pendingSteerMessage?: string;
 }
 
 export class AgentTeamsRuntime {
@@ -568,8 +586,6 @@ export class AgentTeamsRuntime {
 	listTaskItems(options?: {
 		status?: TeamTaskStatus;
 		assignee?: string;
-		unassignedOnly?: boolean;
-		readyOnly?: boolean;
 	}): TeamTaskListItem[] {
 		return Array.from(this.tasks.values())
 			.map((task) => {
@@ -590,12 +606,6 @@ export class AgentTeamsRuntime {
 				if (options?.assignee && task.assignee !== options.assignee) {
 					return false;
 				}
-				if (options?.unassignedOnly && !!task.assignee) {
-					return false;
-				}
-				if (options?.readyOnly && !task.isReady) {
-					return false;
-				}
 				return true;
 			});
 	}
@@ -825,6 +835,15 @@ export class AgentTeamsRuntime {
 		const wrappedConfig: TeamMemberConfig = {
 			...config,
 			apiTimeoutMs: TEAMMATE_API_TIMEOUT_MS,
+			consumePendingUserMessage: () => {
+				const member = this.members.get(agentId);
+				if (!member || !member.pendingSteerMessage) {
+					return undefined;
+				}
+				const message = member.pendingSteerMessage;
+				member.pendingSteerMessage = undefined;
+				return message;
+			},
 			onEvent: (event: AgentEvent) => {
 				config.onEvent?.(event);
 				this.emitEvent({ type: TeamMessageType.AgentEvent, agentId, event });
@@ -870,7 +889,13 @@ export class AgentTeamsRuntime {
 		if (!member || member.role !== "teammate") {
 			throw new Error(`Teammate "${agentId}" was not found`);
 		}
-		member.agent?.abort();
+		try {
+			member.agent?.abort();
+		} catch (error) {
+			if (!isAbortLikeError(error)) {
+				throw error;
+			}
+		}
 		member.status = "stopped";
 		this.emitEvent({ type: TeamMessageType.TeammateShutdown, agentId, reason });
 	}
@@ -986,9 +1011,17 @@ export class AgentTeamsRuntime {
 		this.emitEvent({ type: TeamMessageType.TaskStart, agentId, message });
 
 		try {
+			const unreadMail = this.listMailbox(agentId, {
+				unreadOnly: true,
+				markRead: true,
+			});
+			const enrichedMessage =
+				unreadMail.length > 0
+					? `${this.buildMailboxNotification(unreadMail)}\n\n${message}`
+					: message;
 			const result = options?.continueConversation
-				? await member.agent.continue(message)
-				: await member.agent.run(message);
+				? await member.agent.continue(enrichedMessage)
+				: await member.agent.run(enrichedMessage);
 			this.emitEvent({ type: TeamMessageType.TaskEnd, agentId, result });
 			this.recordProgressStep(
 				agentId,
@@ -1254,7 +1287,8 @@ export class AgentTeamsRuntime {
 		if (!this.members.has(fromAgentId)) {
 			throw new Error(`Unknown sender "${fromAgentId}"`);
 		}
-		if (!this.members.has(toAgentId)) {
+		const recipient = this.members.get(toAgentId);
+		if (!recipient) {
 			throw new Error(`Unknown recipient "${toAgentId}"`);
 		}
 		const message: TeamMailboxMessage = {
@@ -1272,6 +1306,13 @@ export class AgentTeamsRuntime {
 			type: TeamMessageType.TeamMessage,
 			message: { ...message },
 		});
+		if (
+			recipient.role === "teammate" &&
+			recipient.runningCount > 0 &&
+			recipient.agent
+		) {
+			recipient.pendingSteerMessage = `[MAILBOX] You got a message from ${fromAgentId}. Subject: "${subject}". Use the team_read_mailbox tool to read it at your convenience.`;
+		}
 		return { ...message };
 	}
 
@@ -1279,15 +1320,14 @@ export class AgentTeamsRuntime {
 		fromAgentId: string,
 		subject: string,
 		body: string,
-		options?: { includeLead?: boolean; taskId?: string },
+		options?: { taskId?: string },
 	): TeamMailboxMessage[] {
-		const includeLead = options?.includeLead ?? false;
 		const messages: TeamMailboxMessage[] = [];
 		for (const member of this.members.values()) {
 			if (member.agentId === fromAgentId) {
 				continue;
 			}
-			if (!includeLead && member.role === "lead") {
+			if (member.role === "lead") {
 				continue;
 			}
 			messages.push(
@@ -1458,7 +1498,13 @@ export class AgentTeamsRuntime {
 
 		for (const member of this.members.values()) {
 			if (member.role === "teammate") {
-				member.agent?.abort();
+				try {
+					member.agent?.abort();
+				} catch (error) {
+					if (!isAbortLikeError(error)) {
+						throw error;
+					}
+				}
 			}
 		}
 
@@ -1526,7 +1572,7 @@ export class AgentTeamsRuntime {
 			this.appendMissionLog({
 				agentId,
 				kind: "done",
-				summary: `Run completed after ${event.iterations} iteration(s)`,
+				summary: `Completed a delegated run (${event.iterations} iterations)`,
 			});
 			return;
 		}
@@ -1638,6 +1684,23 @@ export class AgentTeamsRuntime {
 		});
 	}
 
+	private buildMailboxNotification(messages: TeamMailboxMessage[]): string {
+		if (messages.length === 0) {
+			return "";
+		}
+		const lines: string[] = [
+			`[MAILBOX] You have ${messages.length} unread message(s):`,
+		];
+		for (const msg of messages) {
+			lines.push(
+				`--- Message from ${msg.fromAgentId} | subject: ${msg.subject} ---`,
+			);
+			lines.push(msg.body);
+		}
+		lines.push("---");
+		return lines.join("\n");
+	}
+
 	private emitEvent(event: TeamEvent): void {
 		try {
 			this.onTeamEvent?.(event);

package/src/{team → extensions/tools/team}/spawn-agent-tool.test.ts

@@ -180,7 +180,6 @@ describe("createSpawnAgentTool", () => {
 				{
 					systemPrompt: "System",
 					task: "Fail task",
-					maxIterations: 6,
 				},
 				{
 					agentId: "parent-2",
@@ -197,11 +196,6 @@ describe("createSpawnAgentTool", () => {
 				error: expect.any(Error),
 			}),
 		);
-		expect(agentConstructorSpy).toHaveBeenCalledWith(
-			expect.objectContaining({
-				maxIterations: 6,
-			}),
-		);
 	});
 
 	it("leaves maxIterations unset when neither input nor default is provided", async () => {

package/src/{team → extensions/tools/team}/spawn-agent-tool.ts

@@ -32,12 +32,6 @@ export const SpawnAgentInputSchema = z.object({
 		.string()
 		.describe("System prompt defining the sub-agent's behavior"),
 	task: z.string().describe("Task for the sub-agent to complete"),
-	maxIterations: z
-		.number()
-		.int()
-		.min(1)
-		.optional()
-		.describe("Max iterations for the sub-agent"),
 });
 
 export type SpawnAgentInput = z.infer<typeof SpawnAgentInputSchema>;
@@ -136,7 +130,7 @@ export function createSpawnAgentTool(
 				prompt: input.systemPrompt,
 				configProvider: config.configProvider,
 				tools,
-				maxIterations: input.maxIterations ?? config.defaultMaxIterations,
+				maxIterations: config.defaultMaxIterations,
 				parentAgentId: context.agentId,
 				abortSignal: context.abortSignal,
 				onEvent: config.onSubAgentEvent,

package/src/{team → extensions/tools/team}/subagent-prompts.ts

@@ -11,7 +11,7 @@ export function buildTeammateSystemPrompt(
 	}
 
 	return buildClineSystemPrompt({
-		ide: config.clineIdeName?.trim() || "Terminal Shell",
+		ide: config.clineIdeName?.trim() || "Terminal",
 		workspaceRoot: config.cwd?.trim() || "/",
 		providerId: config.providerId,
 		rules: `# Team Teammate Role\n${trimmedPrompt}`,
@@ -31,7 +31,7 @@ export function buildSubAgentSystemPrompt(
 	}
 
 	return buildClineSystemPrompt({
-		ide: "Terminal Shell",
+		ide: config.clineIdeName || "Terminal",
 		workspaceRoot: config.cwd?.trim() || "/",
 		providerId: config.providerId,
 		overridePrompt: trimmedPrompt,