@clinebot/core 0.0.27 → 0.0.29

package/src/team/projections.ts

@@ -1,13 +1,11 @@
 import type {
-	TeamEvent,
 	TeamOutcome,
 	TeamOutcomeFragment,
-	TeamRuntimeState,
-} from "@clinebot/agents";
-import type {
 	TeamProgressLifecycleEvent,
 	TeamProgressSummary,
+	TeamRuntimeState,
 } from "@clinebot/shared";
+import type { TeamEvent } from "./multi-agent";
 
 function toIsoNow(): string {
 	return new Date().toISOString();

package/src/team/runtime.ts

@@ -0,0 +1,54 @@
+export {
+	buildDelegatedAgentConfig,
+	createDelegatedAgent,
+	createDelegatedAgentConfigProvider,
+	type DelegatedAgentConfigProvider,
+	type DelegatedAgentConnectionConfig,
+	type DelegatedAgentKind,
+	type DelegatedAgentRuntimeConfig,
+} from "./delegated-agent";
+
+// =============================================================================
+// Spawn Agent Tool
+// =============================================================================
+
+export {
+	createSpawnAgentTool,
+	type SpawnAgentInput,
+	type SpawnAgentOutput,
+	type SpawnAgentToolConfig,
+	type SubAgentEndContext,
+	type SubAgentStartContext,
+} from "./spawn-agent-tool";
+
+// =============================================================================
+// Multi-Agent
+// =============================================================================
+
+export {
+	type AgentTask,
+	AgentTeam,
+	AgentTeamsRuntime,
+	type AgentTeamsRuntimeOptions,
+	createAgentTeam,
+	createWorkerReviewerTeam,
+	type SpawnTeammateOptions,
+	type TaskResult,
+	type TeamEvent,
+	type TeamMemberConfig,
+} from "./multi-agent";
+
+// =============================================================================
+// Team Tools
+// =============================================================================
+
+export {
+	type BootstrapAgentTeamsOptions,
+	type BootstrapAgentTeamsResult,
+	bootstrapAgentTeams,
+	type CreateAgentTeamsToolsOptions,
+	createAgentTeamsTools,
+	reviveTeamStateDates,
+	sanitizeTeamName,
+	type TeamTeammateRuntimeConfig,
+} from "./team-tools";

package/src/team/spawn-agent-tool.test.ts

@@ -0,0 +1,387 @@
+import type { AgentConfig } from "@clinebot/shared";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createDelegatedAgentConfigProvider } from "./delegated-agent";
+
+type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
+
+const runMock = vi.fn();
+const getAgentIdMock = vi.fn(() => "sub-agent-1");
+const getConversationIdMock = vi.fn(() => "conv-sub-1");
+const agentConstructorSpy = vi.fn();
+
+vi.mock("@clinebot/agents", async () => {
+	const actual =
+		await vi.importActual<typeof import("@clinebot/agents")>(
+			"@clinebot/agents",
+		);
+
+	return {
+		...actual,
+		Agent: class MockAgent {
+			constructor(config: unknown) {
+				agentConstructorSpy(config);
+			}
+
+			getAgentId(): string {
+				return getAgentIdMock();
+			}
+
+			getConversationId(): string {
+				return getConversationIdMock();
+			}
+
+			async run(input: string): Promise<unknown> {
+				return runMock(input);
+			}
+		},
+	};
+});
+
+describe("createSpawnAgentTool", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("creates a sub-agent, forwards callbacks, and returns normalized output", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockResolvedValue({
+			text: "sub-agent result",
+			iterations: 2,
+			finishReason: "completed",
+			usage: { inputTokens: 11, outputTokens: 7 },
+		});
+
+		const onSubAgentStart = vi.fn();
+		const onSubAgentEnd = vi.fn();
+		const createSubAgentTools = vi.fn().mockResolvedValue([]);
+		const extensions = [
+			{
+				name: "sample-ext",
+				manifest: { capabilities: ["hooks"], hookStages: ["runtime_event"] },
+				onRuntimeEvent: vi.fn(),
+			} as AgentExtension,
+		];
+
+		const tool = createSpawnAgentTool({
+			configProvider: createDelegatedAgentConfigProvider({
+				providerId: "anthropic",
+				modelId: "mock-model",
+				extensions,
+			}),
+			defaultMaxIterations: 4,
+			createSubAgentTools,
+			onSubAgentStart,
+			onSubAgentEnd,
+		});
+
+		const output = await tool.execute(
+			{
+				systemPrompt: "You are focused",
+				task: "Do delegated work",
+			},
+			{
+				agentId: "parent-1",
+				conversationId: "conv-parent",
+				iteration: 3,
+			},
+		);
+
+		expect(createSubAgentTools).toHaveBeenCalledTimes(1);
+		expect(runMock).toHaveBeenCalledWith("Do delegated work");
+		expect(onSubAgentStart).toHaveBeenCalledTimes(1);
+		expect(onSubAgentEnd).toHaveBeenCalledTimes(1);
+		expect(output).toEqual({
+			text: "sub-agent result",
+			iterations: 2,
+			finishReason: "completed",
+			usage: {
+				inputTokens: 11,
+				outputTokens: 7,
+			},
+		});
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				parentAgentId: "parent-1",
+				maxIterations: 4,
+				extensions,
+			}),
+		);
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.not.objectContaining({
+				prepareTurn: expect.anything(),
+			}),
+		);
+	});
+
+	it("passes extension hooks through delegated config", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockResolvedValue({
+			text: "sub-agent result",
+			iterations: 1,
+			finishReason: "completed",
+			usage: { inputTokens: 1, outputTokens: 1 },
+		});
+
+		const extensions = [
+			{
+				name: "before-start-ext",
+				manifest: {
+					capabilities: ["hooks"],
+					hookStages: ["before_agent_start"],
+				},
+				onBeforeAgentStart: vi.fn(),
+			} as AgentExtension,
+		];
+
+		const tool = createSpawnAgentTool({
+			configProvider: createDelegatedAgentConfigProvider({
+				providerId: "anthropic",
+				modelId: "mock-model",
+				extensions,
+			}),
+			subAgentTools: [],
+		});
+
+		await tool.execute(
+			{
+				systemPrompt: "You are focused",
+				task: "Do delegated work",
+			},
+			{
+				agentId: "parent-1",
+				conversationId: "conv-parent",
+				iteration: 3,
+			},
+		);
+
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				extensions,
+			}),
+		);
+	});
+
+	it("propagates sub-agent errors and still reports onSubAgentEnd", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockRejectedValue(new Error("sub-agent failed"));
+		const onSubAgentEnd = vi.fn();
+
+		const tool = createSpawnAgentTool({
+			configProvider: createDelegatedAgentConfigProvider({
+				providerId: "anthropic",
+				modelId: "mock-model",
+			}),
+			subAgentTools: [],
+			onSubAgentEnd,
+		});
+
+		await expect(
+			tool.execute(
+				{
+					systemPrompt: "System",
+					task: "Fail task",
+					maxIterations: 6,
+				},
+				{
+					agentId: "parent-2",
+					conversationId: "conv-parent",
+					iteration: 1,
+				},
+			),
+		).rejects.toThrow("sub-agent failed");
+
+		expect(onSubAgentEnd).toHaveBeenCalledTimes(1);
+		expect(onSubAgentEnd).toHaveBeenCalledWith(
+			expect.objectContaining({
+				parentAgentId: "parent-2",
+				error: expect.any(Error),
+			}),
+		);
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				maxIterations: 6,
+			}),
+		);
+	});
+
+	it("leaves maxIterations unset when neither input nor default is provided", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockResolvedValue({
+			text: "sub-agent result",
+			iterations: 1,
+			finishReason: "completed",
+			usage: { inputTokens: 1, outputTokens: 1 },
+		});
+
+		const tool = createSpawnAgentTool({
+			configProvider: createDelegatedAgentConfigProvider({
+				providerId: "anthropic",
+				modelId: "mock-model",
+			}),
+			subAgentTools: [],
+		});
+
+		await tool.execute(
+			{
+				systemPrompt: "System",
+				task: "Do task",
+			},
+			{
+				agentId: "parent-3",
+				conversationId: "conv-parent",
+				iteration: 1,
+			},
+		);
+
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				maxIterations: undefined,
+			}),
+		);
+	});
+
+	it("appends workspace metadata for cline sub-agents when missing", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockResolvedValue({
+			text: "ok",
+			iterations: 1,
+			finishReason: "completed",
+			usage: { inputTokens: 1, outputTokens: 1 },
+		});
+
+		const workspaceMetadata = `# Workspace Configuration
+{
+  "workspaces": {
+    "/repo/demo": {
+      "hint": "demo"
+    }
+  }
+}`;
+
+		const tool = createSpawnAgentTool({
+			configProvider: createDelegatedAgentConfigProvider({
+				providerId: "cline",
+				modelId: "anthropic/claude-sonnet-4.6",
+				cwd: "/repo/demo",
+				workspaceMetadata,
+			}),
+			subAgentTools: [],
+		});
+
+		await tool.execute(
+			{
+				systemPrompt: "You are a specialist teammate.",
+				task: "Investigate module boundaries",
+			},
+			{
+				agentId: "parent-4",
+				conversationId: "conv-parent",
+				iteration: 1,
+			},
+		);
+
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				systemPrompt: expect.stringContaining(workspaceMetadata),
+			}),
+		);
+	});
+
+	it("does not duplicate workspace metadata for cline sub-agents", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockResolvedValue({
+			text: "ok",
+			iterations: 1,
+			finishReason: "completed",
+			usage: { inputTokens: 1, outputTokens: 1 },
+		});
+
+		const inputSystemPrompt = `You are a specialist teammate.
+
+# Workspace Configuration
+{
+  "workspaces": {
+    "/repo/demo": {
+      "hint": "demo"
+    }
+  }
+}`;
+
+		const tool = createSpawnAgentTool({
+			configProvider: createDelegatedAgentConfigProvider({
+				providerId: "cline",
+				modelId: "anthropic/claude-sonnet-4.6",
+				cwd: "/repo/demo",
+				workspaceMetadata: "# Workspace Configuration\n{}",
+			}),
+			subAgentTools: [],
+		});
+
+		await tool.execute(
+			{
+				systemPrompt: inputSystemPrompt,
+				task: "Investigate module boundaries",
+			},
+			{
+				agentId: "parent-5",
+				conversationId: "conv-parent",
+				iteration: 1,
+			},
+		);
+
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				systemPrompt: inputSystemPrompt,
+			}),
+		);
+	});
+
+	it("resolves connection settings lazily at execution time", async () => {
+		const { createSpawnAgentTool } = await import("./spawn-agent-tool.js");
+		runMock.mockResolvedValue({
+			text: "ok",
+			iterations: 1,
+			finishReason: "completed",
+			usage: { inputTokens: 1, outputTokens: 1 },
+		});
+
+		const configProvider = createDelegatedAgentConfigProvider({
+			providerId: "cline",
+			modelId: "stale-model",
+			apiKey: "oauth-access-old",
+		});
+		const updateConnectionDefaults = vi.spyOn(
+			configProvider,
+			"updateConnectionDefaults",
+		);
+		configProvider.updateConnectionDefaults({
+			apiKey: "oauth-access-new",
+			modelId: "updated-model",
+		});
+
+		const tool = createSpawnAgentTool({
+			configProvider,
+			subAgentTools: [],
+		});
+
+		await tool.execute(
+			{
+				systemPrompt: "System",
+				task: "Do task",
+			},
+			{
+				agentId: "parent-6",
+				conversationId: "conv-parent",
+				iteration: 1,
+			},
+		);
+
+		expect(updateConnectionDefaults).toHaveBeenCalledTimes(1);
+		expect(agentConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				apiKey: "oauth-access-new",
+				modelId: "updated-model",
+			}),
+		);
+	});
+});

package/src/team/spawn-agent-tool.ts

@@ -0,0 +1,207 @@
+/**
+ * Reusable spawn_agent tool for delegating tasks to sub-agents.
+ */
+
+import {
+	type AgentConfig,
+	type AgentEvent,
+	type AgentHooks,
+	type AgentResult,
+	type BasicLogger,
+	createTool,
+	type HookErrorMode,
+	type ITelemetryService,
+	type Tool,
+	type ToolApprovalRequest,
+	type ToolApprovalResult,
+	type ToolContext,
+	type ToolPolicy,
+	zodToJsonSchema,
+} from "@clinebot/shared";
+import { z } from "zod";
+import {
+	createDelegatedAgent,
+	type DelegatedAgentConfigProvider,
+} from "./delegated-agent";
+
+type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
+type AgentFinishReason = AgentResult["finishReason"];
+
+export const SpawnAgentInputSchema = z.object({
+	systemPrompt: z
+		.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>;
+
+export interface SpawnAgentOutput {
+	text: string;
+	iterations: number;
+	finishReason: AgentFinishReason;
+	usage: {
+		inputTokens: number;
+		outputTokens: number;
+	};
+}
+
+export interface SubAgentStartContext {
+	subAgentId: string;
+	conversationId: string;
+	parentAgentId: string;
+	input: SpawnAgentInput;
+}
+
+export interface SubAgentEndContext {
+	subAgentId: string;
+	conversationId: string;
+	parentAgentId: string;
+	input: SpawnAgentInput;
+	result?: SpawnAgentOutput;
+	error?: Error;
+}
+
+export interface SpawnAgentToolConfig {
+	configProvider: DelegatedAgentConfigProvider;
+	defaultMaxIterations?: number;
+	subAgentTools?: Tool[];
+	createSubAgentTools?: (
+		input: SpawnAgentInput,
+		context: ToolContext,
+	) => Tool[] | Promise<Tool[]>;
+	onSubAgentEvent?: (event: AgentEvent) => void;
+	/**
+	 * Lifecycle hooks forwarded to spawned sub-agent runs.
+	 */
+	hooks?: AgentHooks;
+	/**
+	 * Extension list forwarded to spawned sub-agent runs.
+	 */
+	extensions?: AgentExtension[];
+	/**
+	 * Error handling mode for forwarded lifecycle hooks.
+	 */
+	hookErrorMode?: HookErrorMode;
+	/**
+	 * Called after a sub-agent instance is created and before it starts running.
+	 * Errors are ignored so lifecycle observers cannot break task execution.
+	 */
+	onSubAgentStart?: (context: SubAgentStartContext) => void | Promise<void>;
+	/**
+	 * Called once a sub-agent run finishes (success or error).
+	 * Errors are ignored so lifecycle observers cannot break task execution.
+	 */
+	onSubAgentEnd?: (context: SubAgentEndContext) => void | Promise<void>;
+	/**
+	 * Optional per-tool policy for spawned sub-agents.
+	 */
+	toolPolicies?: Record<string, ToolPolicy>;
+	/**
+	 * Optional approval callback for spawned sub-agent tool calls.
+	 */
+	requestToolApproval?: (
+		request: ToolApprovalRequest,
+	) => Promise<ToolApprovalResult> | ToolApprovalResult;
+	/**
+	 * Optional logger forwarded to spawned sub-agent runs.
+	 */
+	logger?: BasicLogger;
+	telemetry?: ITelemetryService;
+}
+
+/**
+ * Create a spawn_agent tool that can run a delegated task with a focused sub-agent.
+ */
+export function createSpawnAgentTool(
+	config: SpawnAgentToolConfig,
+): Tool<SpawnAgentInput, SpawnAgentOutput> {
+	return createTool<SpawnAgentInput, SpawnAgentOutput>({
+		name: "spawn_agent",
+		description: `Spawn a sub-agent with a custom system prompt for specialized tasks. Use when delegating work that benefits from focused expertise.`,
+		inputSchema: zodToJsonSchema(SpawnAgentInputSchema),
+		execute: async (input, context) => {
+			const tools = config.createSubAgentTools
+				? await config.createSubAgentTools(input, context)
+				: (config.subAgentTools ?? []);
+
+			const subAgent = createDelegatedAgent({
+				kind: "subagent",
+				prompt: input.systemPrompt,
+				configProvider: config.configProvider,
+				tools,
+				maxIterations: input.maxIterations ?? config.defaultMaxIterations,
+				parentAgentId: context.agentId,
+				abortSignal: context.abortSignal,
+				onEvent: config.onSubAgentEvent,
+				hookErrorMode: config.hookErrorMode,
+				toolPolicies: config.toolPolicies,
+				requestToolApproval: config.requestToolApproval,
+			});
+			const subAgentId = subAgent.getAgentId();
+			const conversationId = subAgent.getConversationId();
+			const parentAgentId = context.agentId;
+			if (config.onSubAgentStart) {
+				try {
+					await config.onSubAgentStart({
+						subAgentId,
+						conversationId,
+						parentAgentId,
+						input,
+					});
+				} catch {
+					// Best-effort observer callback.
+				}
+			}
+			try {
+				const result = await subAgent.run(input.task);
+				const output: SpawnAgentOutput = {
+					text: result.text,
+					iterations: result.iterations,
+					finishReason: result.finishReason,
+					usage: {
+						inputTokens: result.usage.inputTokens,
+						outputTokens: result.usage.outputTokens,
+					},
+				};
+				if (config.onSubAgentEnd) {
+					try {
+						await config.onSubAgentEnd({
+							subAgentId,
+							conversationId,
+							parentAgentId,
+							input,
+							result: output,
+						});
+					} catch {
+						// Best-effort observer callback.
+					}
+				}
+				return output;
+			} catch (error) {
+				if (config.onSubAgentEnd) {
+					try {
+						await config.onSubAgentEnd({
+							subAgentId,
+							conversationId,
+							parentAgentId,
+							input,
+							error: error instanceof Error ? error : new Error(String(error)),
+						});
+					} catch {
+						// Best-effort observer callback.
+					}
+				}
+				throw error;
+			}
+		},
+		timeoutMs: 300000,
+		retryable: false,
+	});
+}

package/src/team/subagent-prompts.ts

@@ -0,0 +1,41 @@
+import { buildClineSystemPrompt } from "@clinebot/shared";
+import type { DelegatedAgentRuntimeConfig } from "./delegated-agent";
+
+export function buildTeammateSystemPrompt(
+	prompt: string,
+	config: DelegatedAgentRuntimeConfig,
+): string {
+	const trimmedPrompt = prompt.trim();
+	if (config.providerId.toLowerCase() !== "cline") {
+		return trimmedPrompt;
+	}
+
+	return buildClineSystemPrompt({
+		ide: config.clineIdeName?.trim() || "Terminal Shell",
+		workspaceRoot: config.cwd?.trim() || "/",
+		providerId: config.providerId,
+		rules: `# Team Teammate Role\n${trimmedPrompt}`,
+		platform: config.clinePlatform,
+		metadata: config.workspaceMetadata,
+	});
+}
+
+export function buildSubAgentSystemPrompt(
+	// The prompt provided when spawning the subagent
+	prompt: string,
+	config: DelegatedAgentRuntimeConfig,
+): string {
+	const trimmedPrompt = prompt.trim();
+	if (config.providerId.toLowerCase() !== "cline") {
+		return trimmedPrompt;
+	}
+
+	return buildClineSystemPrompt({
+		ide: "Terminal Shell",
+		workspaceRoot: config.cwd?.trim() || "/",
+		providerId: config.providerId,
+		overridePrompt: trimmedPrompt,
+		metadata: config.workspaceMetadata,
+		platform: config.clinePlatform,
+	});
+}