@clinebot/agents 0.0.0 → 0.0.2

package/src/teams/multi-agent.ts

@@ -84,6 +84,7 @@ export type TeamEvent =
 			agentId: string;
 			result?: AgentResult;
 			error?: Error;
+			messages?: AgentResult["messages"];
 	  }
 	| { type: TeamMessageType.AgentEvent; agentId: string; event: AgentEvent }
 	| {
@@ -242,7 +243,12 @@ export class AgentTeam {
 			return result;
 		} catch (error) {
 			const err = error instanceof Error ? error : new Error(String(error));
-			this.emitEvent({ type: TeamMessageType.TaskEnd, agentId, error: err });
+			this.emitEvent({
+				type: TeamMessageType.TaskEnd,
+				agentId,
+				error: err,
+				messages: agent.getMessages(),
+			});
 			throw error;
 		}
 	}
@@ -268,7 +274,12 @@ export class AgentTeam {
 			return result;
 		} catch (error) {
 			const err = error instanceof Error ? error : new Error(String(error));
-			this.emitEvent({ type: TeamMessageType.TaskEnd, agentId, error: err });
+			this.emitEvent({
+				type: TeamMessageType.TaskEnd,
+				agentId,
+				error: err,
+				messages: agent.getMessages(),
+			});
 			throw error;
 		}
 	}
@@ -323,6 +334,7 @@ export class AgentTeam {
 					type: TeamMessageType.TaskEnd,
 					agentId: task.agentId,
 					error: err,
+					messages: agent.getMessages(),
 				});
 				return {
 					agentId: task.agentId,
@@ -384,6 +396,7 @@ export class AgentTeam {
 					type: TeamMessageType.TaskEnd,
 					agentId: task.agentId,
 					error: err,
+					messages: agent.getMessages(),
 				});
 				results.push({
 					agentId: task.agentId,
@@ -462,7 +475,12 @@ export class AgentTeam {
 				}
 			} catch (error) {
 				const err = error instanceof Error ? error : new Error(String(error));
-				this.emitEvent({ type: TeamMessageType.TaskEnd, agentId, error: err });
+				this.emitEvent({
+					type: TeamMessageType.TaskEnd,
+					agentId,
+					error: err,
+					messages: agent.getMessages(),
+				});
 				results.push({
 					agentId,
 					result: undefined as unknown as AgentResult,
@@ -733,6 +751,9 @@ export interface TeamRunRecord {
 	endedAt?: Date;
 	leaseOwner?: string;
 	heartbeatAt?: Date;
+	lastProgressAt?: Date;
+	lastProgressMessage?: string;
+	currentActivity?: string;
 	result?: AgentResult;
 	error?: string;
 }
@@ -1274,7 +1295,12 @@ export class AgentTeamsRuntime {
 			return result;
 		} catch (error) {
 			const err = error instanceof Error ? error : new Error(String(error));
-			this.emitEvent({ type: TeamMessageType.TaskEnd, agentId, error: err });
+			this.emitEvent({
+				type: TeamMessageType.TaskEnd,
+				agentId,
+				error: err,
+				messages: member.agent.getMessages(),
+			});
 			this.appendMissionLog({
 				agentId,
 				taskId: options?.taskId,
@@ -1316,6 +1342,9 @@ export class AgentTeamsRuntime {
 			startedAt: new Date(0),
 			leaseOwner: options?.leaseOwner,
 			heartbeatAt: undefined,
+			lastProgressAt: new Date(),
+			lastProgressMessage: "queued",
+			currentActivity: "queued",
 		};
 		this.runs.set(runId, record);
 		this.runQueue.push(runId);
@@ -1369,18 +1398,14 @@ export class AgentTeamsRuntime {
 		run.status = "running";
 		run.startedAt = new Date();
 		run.heartbeatAt = new Date();
+		run.currentActivity = "run_started";
 		this.emitEvent({ type: TeamMessageType.RunStarted, run: { ...run } });
 
 		const heartbeatTimer = setInterval(() => {
 			if (run.status !== "running") {
 				return;
 			}
-			run.heartbeatAt = new Date();
-			this.emitEvent({
-				type: TeamMessageType.RunProgress,
-				run: { ...run },
-				message: "heartbeat",
-			});
+			this.recordRunProgress(run, "heartbeat");
 		}, 2000);
 
 		try {
@@ -1391,6 +1416,7 @@ export class AgentTeamsRuntime {
 			run.status = "completed";
 			run.result = result;
 			run.endedAt = new Date();
+			run.currentActivity = "completed";
 			this.emitEvent({ type: TeamMessageType.RunCompleted, run: { ...run } });
 		} catch (error) {
 			const message =
@@ -1406,13 +1432,10 @@ export class AgentTeamsRuntime {
 					Date.now() + Math.min(30000, 1000 * 2 ** run.retryCount),
 				);
 				this.runQueue.push(run.id);
-				this.emitEvent({
-					type: TeamMessageType.RunProgress,
-					run: { ...run },
-					message: `retry_scheduled_${run.retryCount}`,
-				});
+				this.recordRunProgress(run, `retry_scheduled_${run.retryCount}`);
 			} else {
 				run.status = "failed";
+				run.currentActivity = "failed";
 				this.emitEvent({ type: TeamMessageType.RunFailed, run: { ...run } });
 			}
 		} finally {
@@ -1481,6 +1504,7 @@ export class AgentTeamsRuntime {
 		run.status = "cancelled";
 		run.error = reason;
 		run.endedAt = new Date();
+		run.currentActivity = "cancelled";
 		const queueIndex = this.runQueue.indexOf(runId);
 		if (queueIndex >= 0) {
 			this.runQueue.splice(queueIndex, 1);
@@ -1502,6 +1526,7 @@ export class AgentTeamsRuntime {
 			run.status = "interrupted";
 			run.error = reason;
 			run.endedAt = new Date();
+			run.currentActivity = "interrupted";
 			interrupted.push({ ...run });
 			this.emitEvent({
 				type: TeamMessageType.RunInterrupted,
@@ -1764,6 +1789,8 @@ export class AgentTeamsRuntime {
 	}
 
 	private trackMeaningfulEvent(agentId: string, event: AgentEvent): void {
+		this.recordRunActivityFromAgentEvent(agentId, event);
+
 		if (event.type === "iteration_end" && event.hadToolCalls) {
 			this.recordProgressStep(
 				agentId,
@@ -1802,6 +1829,60 @@ export class AgentTeamsRuntime {
 		}
 	}
 
+	private recordRunActivityFromAgentEvent(
+		agentId: string,
+		event: AgentEvent,
+	): void {
+		let activity: string | undefined;
+		switch (event.type) {
+			case "iteration_start":
+				activity = `iteration_${event.iteration}_started`;
+				break;
+			case "content_start":
+				if (event.contentType === "tool") {
+					activity = `running_tool_${event.toolName ?? "unknown"}`;
+				}
+				break;
+			case "content_end":
+				if (event.contentType === "tool") {
+					activity = event.error
+						? `tool_${event.toolName ?? "unknown"}_error`
+						: `finished_tool_${event.toolName ?? "unknown"}`;
+				}
+				break;
+			case "done":
+				activity = "finalizing_response";
+				break;
+			case "error":
+				activity = "run_error";
+				break;
+			default:
+				break;
+		}
+		if (!activity) {
+			return;
+		}
+		for (const run of this.runs.values()) {
+			if (run.agentId !== agentId || run.status !== "running") {
+				continue;
+			}
+			this.recordRunProgress(run, activity);
+		}
+	}
+
+	private recordRunProgress(run: TeamRunRecord, message: string): void {
+		const now = new Date();
+		run.heartbeatAt = now;
+		run.lastProgressAt = now;
+		run.lastProgressMessage = message;
+		run.currentActivity = message;
+		this.emitEvent({
+			type: TeamMessageType.RunProgress,
+			run: { ...run },
+			message,
+		});
+	}
+
 	private recordProgressStep(
 		agentId: string,
 		summary: string,

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

@@ -169,4 +169,96 @@ describe("createSpawnAgentTool", () => {
 			}),
 		);
 	});
+
+	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({
+			providerId: "cline",
+			modelId: "anthropic/claude-sonnet-4.6",
+			cwd: "/repo/demo",
+			clineWorkspaceMetadata: 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({
+			providerId: "cline",
+			modelId: "anthropic/claude-sonnet-4.6",
+			cwd: "/repo/demo",
+			clineWorkspaceMetadata: "# 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,
+			}),
+		);
+	});
 });

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

@@ -2,14 +2,17 @@
  * Reusable spawn_agent tool for delegating tasks to sub-agents.
  */
 
+import { basename, resolve } from "node:path";
 import type { providers as LlmsProviders } from "@clinebot/llms";
-import type {
-	Tool,
-	ToolApprovalRequest,
-	ToolApprovalResult,
-	ToolContext,
-	ToolPolicy,
+import {
+	type Tool,
+	type ToolApprovalRequest,
+	type ToolApprovalResult,
+	type ToolContext,
+	type ToolPolicy,
+	zodToJsonSchema,
 } from "@clinebot/shared";
+import { z } from "zod";
 import { Agent } from "../agent.js";
 import { createTool } from "../tools/create.js";
 import type {
@@ -21,11 +24,20 @@ import type {
 	HookErrorMode,
 } from "../types.js";
 
-export interface SpawnAgentInput {
-	systemPrompt: string;
-	task: string;
-	maxIterations?: number;
-}
+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;
@@ -56,11 +68,13 @@ export interface SubAgentEndContext {
 export interface SpawnAgentToolConfig {
 	providerId: string;
 	modelId: string;
+	cwd?: string;
 	apiKey?: string;
 	baseUrl?: string;
 	providerConfig?: LlmsProviders.ProviderConfig;
 	knownModels?: Record<string, LlmsProviders.ModelInfo>;
 	thinking?: boolean;
+	clineWorkspaceMetadata?: string;
 	defaultMaxIterations?: number;
 	subAgentTools?: Tool[];
 	createSubAgentTools?: (
@@ -106,6 +120,44 @@ export interface SpawnAgentToolConfig {
 	logger?: BasicLogger;
 }
 
+const WORKSPACE_CONFIGURATION_MARKER = "# Workspace Configuration";
+
+function buildFallbackWorkspaceMetadata(cwd: string): string {
+	const rootPath = resolve(cwd);
+	return `# Workspace Configuration\n${JSON.stringify(
+		{
+			workspaces: {
+				[rootPath]: {
+					hint: basename(rootPath),
+				},
+			},
+		},
+		null,
+		2,
+	)}`;
+}
+
+function normalizeSubAgentSystemPrompt(
+	inputSystemPrompt: string,
+	config: SpawnAgentToolConfig,
+): string {
+	if (config.providerId !== "cline") {
+		return inputSystemPrompt;
+	}
+	const trimmedPrompt = inputSystemPrompt.trim();
+	if (trimmedPrompt.includes(WORKSPACE_CONFIGURATION_MARKER)) {
+		return trimmedPrompt;
+	}
+	const cwd = config.cwd?.trim() || process.cwd();
+	const workspaceMetadata =
+		config.clineWorkspaceMetadata?.trim() ||
+		buildFallbackWorkspaceMetadata(cwd);
+	if (!workspaceMetadata) {
+		return trimmedPrompt;
+	}
+	return `${trimmedPrompt}\n\n${workspaceMetadata}`;
+}
+
 /**
  * Create a spawn_agent tool that can run a delegated task with a focused sub-agent.
  */
@@ -115,25 +167,7 @@ export function createSpawnAgentTool(
 	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"],
-		},
+		inputSchema: zodToJsonSchema(SpawnAgentInputSchema),
 		execute: async (input, context) => {
 			const tools = config.createSubAgentTools
 				? await config.createSubAgentTools(input, context)
@@ -147,7 +181,7 @@ export function createSpawnAgentTool(
 				providerConfig: config.providerConfig,
 				knownModels: config.knownModels,
 				thinking: config.thinking,
-				systemPrompt: input.systemPrompt,
+				systemPrompt: normalizeSubAgentSystemPrompt(input.systemPrompt, config),
 				tools,
 				maxIterations: input.maxIterations ?? config.defaultMaxIterations,
 				parentAgentId: context.agentId,

package/src/teams/team-tools.test.ts

@@ -445,4 +445,22 @@ describe("createAgentTeamsTools runtime behavior", () => {
 			"One or more runs did not complete successfully: run_bad:failed(Auth expired)",
 		);
 	});
+
+	it("sets long timeout for team await tools", () => {
+		const runtime = new AgentTeamsRuntime({ teamName: "test-team" });
+		const tools = createAgentTeamsTools({
+			runtime,
+			requesterId: "lead",
+			teammateRuntime: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-5-20250929",
+			},
+		});
+		const awaitRun = tools.find((tool) => tool.name === "team_await_run");
+		const awaitAllRuns = tools.find(
+			(tool) => tool.name === "team_await_all_runs",
+		);
+		expect(awaitRun?.timeoutMs).toBe(60 * 60 * 1000);
+		expect(awaitAllRuns?.timeoutMs).toBe(60 * 60 * 1000);
+	});
 });

package/src/teams/team-tools.ts

@@ -40,7 +40,10 @@ const TeamStatusInputSchema = z.object({});
 const TeamCreateTaskInputSchema = z.object({
 	title: z.string().min(1).describe("Task title"),
 	description: z.string().min(1).describe("Task details"),
-	dependsOn: z.array(z.string()).optional().describe("Dependency task IDs"),
+	dependsOn: z
+		.array(z.string().describe("Dependency task ID"))
+		.optional()
+		.describe("Array of the dependency task IDs"),
 	assignee: z.string().min(1).optional().describe("Optional assignee"),
 });
 
@@ -154,6 +157,7 @@ const DEFAULT_OUTCOME_REQUIRED_SECTIONS = [
 	"boundary_analysis",
 	"interface_proposal",
 ];
+const TEAM_AWAIT_TIMEOUT_MS = 60 * 60 * 1000;
 
 const TeamCreateOutcomeInputSchema = z.object({
 	title: z.string().describe("Outcome title"),
@@ -598,7 +602,7 @@ export function createAgentTeamsTools(
 		createTool<TeamListRunsInput, ReturnType<AgentTeamsRuntime["listRuns"]>>({
 			name: "team_list_runs",
 			description:
-				"List teammate runs started with team_run_task in async mode.",
+				"List teammate runs started with team_run_task in async mode, including live activity/progress fields when available.",
 			inputSchema: zodToJsonSchema(TeamListRunsInputSchema),
 			execute: async (input) =>
 				options.runtime.listRuns(
@@ -613,8 +617,10 @@ export function createAgentTeamsTools(
 			Awaited<ReturnType<AgentTeamsRuntime["awaitRun"]>>
 		>({
 			name: "team_await_run",
-			description: "Wait for one async run by runId.",
+			description:
+				"Wait for one async run by runId. Uses a long timeout for legitimate teammate work.",
 			inputSchema: zodToJsonSchema(TeamAwaitRunInputSchema),
+			timeoutMs: TEAM_AWAIT_TIMEOUT_MS,
 			execute: async (input) => {
 				const validatedInput = validateWithZod(TeamAwaitRunInputSchema, input);
 				const run = await options.runtime.awaitRun(validatedInput.runId);
@@ -644,8 +650,10 @@ export function createAgentTeamsTools(
 			Awaited<ReturnType<AgentTeamsRuntime["awaitAllRuns"]>>
 		>({
 			name: "team_await_all_runs",
-			description: "Wait for all active async runs to complete.",
+			description:
+				"Wait for all active async runs to complete. Uses a long timeout for legitimate teammate work.",
 			inputSchema: zodToJsonSchema(TeamAwaitAllRunsInputSchema),
+			timeoutMs: TEAM_AWAIT_TIMEOUT_MS,
 			execute: async (input) => {
 				validateWithZod(TeamAwaitAllRunsInputSchema, input);
 				const runs = await options.runtime.awaitAllRuns();

package/src/types.ts

@@ -126,6 +126,8 @@ export interface AgentDoneEvent {
 	text: string;
 	/** Total number of iterations */
 	iterations: number;
+	/** Aggregated usage information */
+	usage?: AgentUsage;
 }
 
 export interface AgentErrorEvent {
@@ -138,6 +140,30 @@ export interface AgentErrorEvent {
 	iteration: number;
 }
 
+export interface ConsecutiveMistakeLimitContext {
+	iteration: number;
+	consecutiveMistakes: number;
+	maxConsecutiveMistakes: number;
+	reason: "api_error" | "invalid_tool_call" | "tool_execution_failed";
+	details?: string;
+}
+
+export type ConsecutiveMistakeLimitDecision =
+	| {
+			action: "continue";
+			/**
+			 * Optional guidance appended as a user message before continuing.
+			 */
+			guidance?: string;
+	  }
+	| {
+			action: "stop";
+			/**
+			 * Optional reason surfaced when stopping due to the limit.
+			 */
+			reason?: string;
+	  };
+
 // =============================================================================
 // Hooks
 // =============================================================================
@@ -658,9 +684,9 @@ export const AgentResultSchema = z.object({
 /**
  * Reasoning effort level for capable models
  */
-export type ReasoningEffort = "low" | "medium" | "high";
+export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
 
-export const ReasoningEffortSchema = z.enum(["low", "medium", "high"]);
+export const ReasoningEffortSchema = z.enum(["low", "medium", "high", "xhigh"]);
 
 /**
  * Configuration for creating an Agent
@@ -729,6 +755,13 @@ export interface AgentConfig {
 	 * @default 120000 (2 minutes)
 	 */
 	apiTimeoutMs?: number;
+	/**
+	 * Maximum consecutive internal mistakes before escalation.
+	 * Mistakes include API turn failures, invalid/missing tool-call arguments,
+	 * and iterations where every executed tool call fails.
+	 * @default 3
+	 */
+	maxConsecutiveMistakes?: number;
 	/**
 	 * Optional runtime file-content loader used when user files are attached.
 	 * When omitted, attached files will be represented as loader errors.
@@ -797,6 +830,14 @@ export interface AgentConfig {
 	requestToolApproval?: (
 		request: ToolApprovalRequest,
 	) => Promise<ToolApprovalResult> | ToolApprovalResult;
+	/**
+	 * Optional callback invoked when consecutive mistakes reach maxConsecutiveMistakes.
+	 */
+	onConsecutiveMistakeLimitReached?: (
+		context: ConsecutiveMistakeLimitContext,
+	) =>
+		| Promise<ConsecutiveMistakeLimitDecision>
+		| ConsecutiveMistakeLimitDecision;
 	/**
 	 * Optional logger for tracing agent loop lifecycle and recoverable failures.
 	 */
@@ -845,6 +886,7 @@ export const AgentConfigSchema = z.object({
 	maxParallelToolCalls: z.number().int().positive().default(8),
 	maxTokensPerTurn: z.number().positive().optional(),
 	apiTimeoutMs: z.number().positive().default(120000),
+	maxConsecutiveMistakes: z.number().int().positive().default(3),
 	userFileContentLoader: z
 		.function()
 		.input([z.string()])
@@ -911,6 +953,46 @@ export const AgentConfigSchema = z.object({
 			]),
 		)
 		.optional(),
+	onConsecutiveMistakeLimitReached: z
+		.function()
+		.input([
+			z.object({
+				iteration: z.number().int().positive(),
+				consecutiveMistakes: z.number().int().positive(),
+				maxConsecutiveMistakes: z.number().int().positive(),
+				reason: z.enum([
+					"api_error",
+					"invalid_tool_call",
+					"tool_execution_failed",
+				]),
+				details: z.string().optional(),
+			}),
+		])
+		.output(
+			z.union([
+				z.object({
+					action: z.literal("continue"),
+					guidance: z.string().optional(),
+				}),
+				z.object({
+					action: z.literal("stop"),
+					reason: z.string().optional(),
+				}),
+				z.promise(
+					z.union([
+						z.object({
+							action: z.literal("continue"),
+							guidance: z.string().optional(),
+						}),
+						z.object({
+							action: z.literal("stop"),
+							reason: z.string().optional(),
+						}),
+					]),
+				),
+			]),
+		)
+		.optional(),
 	logger: z.custom<BasicLogger>().optional(),
 
 	// Cancellation
@@ -942,6 +1024,12 @@ export interface ProcessedTurn {
 	reasoning?: string;
 	/** Tool calls requested by the model */
 	toolCalls: PendingToolCall[];
+	/** Model-emitted tool calls that were invalid or missing required fields */
+	invalidToolCalls: Array<{
+		id: string;
+		name?: string;
+		reason: "missing_name" | "missing_arguments" | "invalid_arguments";
+	}>;
 	/** Token usage for this turn */
 	usage: {
 		inputTokens: number;