@clinebot/agents 0.0.0

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

@@ -0,0 +1,172 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentExtension } from "../types.js";
+
+const runMock = vi.fn();
+const getAgentIdMock = vi.fn(() => "sub-agent-1");
+const getConversationIdMock = vi.fn(() => "conv-sub-1");
+const agentConstructorSpy = vi.fn();
+
+vi.mock("../agent.js", () => ({
+	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({
+			providerId: "anthropic",
+			modelId: "mock-model",
+			defaultMaxIterations: 4,
+			createSubAgentTools,
+			extensions,
+			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,
+			}),
+		);
+	});
+
+	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({
+			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({
+			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,
+			}),
+		);
+	});
+});

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

@@ -0,0 +1,223 @@
+/**
+ * Reusable spawn_agent tool for delegating tasks to sub-agents.
+ */
+
+import type { providers as LlmsProviders } from "@clinebot/llms";
+import type {
+	Tool,
+	ToolApprovalRequest,
+	ToolApprovalResult,
+	ToolContext,
+	ToolPolicy,
+} from "@clinebot/shared";
+import { Agent } from "../agent.js";
+import { createTool } from "../tools/create.js";
+import type {
+	AgentEvent,
+	AgentExtension,
+	AgentFinishReason,
+	AgentHooks,
+	BasicLogger,
+	HookErrorMode,
+} from "../types.js";
+
+export interface SpawnAgentInput {
+	systemPrompt: string;
+	task: string;
+	maxIterations?: number;
+}
+
+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 {
+	providerId: string;
+	modelId: string;
+	apiKey?: string;
+	baseUrl?: string;
+	providerConfig?: LlmsProviders.ProviderConfig;
+	knownModels?: Record<string, LlmsProviders.ModelInfo>;
+	thinking?: boolean;
+	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;
+}
+
+/**
+ * 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: {
+			type: "object",
+			properties: {
+				systemPrompt: {
+					type: "string",
+					description: "System prompt defining the sub-agent's behavior",
+				},
+				task: {
+					type: "string",
+					description: "Task for the sub-agent to complete",
+				},
+				maxIterations: {
+					type: "integer",
+					description: "Max iterations for the sub-agent",
+					minimum: 1,
+				},
+			},
+			required: ["systemPrompt", "task"],
+		},
+		execute: async (input, context) => {
+			const tools = config.createSubAgentTools
+				? await config.createSubAgentTools(input, context)
+				: (config.subAgentTools ?? []);
+
+			const subAgent = new Agent({
+				providerId: config.providerId,
+				modelId: config.modelId,
+				apiKey: config.apiKey,
+				baseUrl: config.baseUrl,
+				providerConfig: config.providerConfig,
+				knownModels: config.knownModels,
+				thinking: config.thinking,
+				systemPrompt: input.systemPrompt,
+				tools,
+				maxIterations: input.maxIterations ?? config.defaultMaxIterations,
+				parentAgentId: context.agentId,
+				abortSignal: context.abortSignal,
+				onEvent: config.onSubAgentEvent,
+				hooks: config.hooks,
+				extensions: config.extensions,
+				hookErrorMode: config.hookErrorMode,
+				toolPolicies: config.toolPolicies,
+				requestToolApproval: config.requestToolApproval,
+				logger: config.logger,
+			});
+			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,
+	});
+}