@clinebot/agents 0.0.0 → 0.0.3

package/src/agent.ts

@@ -5,6 +5,7 @@
  */
 
 import { providers } from "@clinebot/llms";
+import { nanoid } from "nanoid";
 import { buildInitialUserContent } from "./agent-input.js";
 import {
 	type ContributionRegistry,
@@ -26,6 +27,7 @@ import type {
 	AgentResult,
 	AgentUsage,
 	BasicLogger,
+	ConsecutiveMistakeLimitDecision,
 	PendingToolCall,
 	Tool,
 	ToolApprovalResult,
@@ -37,6 +39,36 @@ import type {
 const DEFAULT_REMINDER_TEXT =
 	"REMINDER: If you have gathered enough information to answer the user's question, please provide your final answer now without using any more tools.";
 
+function isNonRecoverableApiError(error: Error): boolean {
+	const message = error.message.toLowerCase();
+
+	const nonRecoverableStatusCodes = [
+		400, 401, 403, 404, 405, 406, 409, 410, 429,
+	];
+	if (
+		nonRecoverableStatusCodes.some((code) =>
+			new RegExp(`(?:\\b|\\"code\\"\\s*:\\s*)${code}(?:\\b|\\s)`).test(message),
+		)
+	) {
+		return true;
+	}
+
+	if (
+		[
+			"not found",
+			"unsupported for",
+			"invalid api key",
+			"authentication",
+			"unauthorized",
+			"forbidden",
+		].some((s) => message.includes(s))
+	) {
+		return true;
+	}
+
+	return false;
+}
+
 function resolveKnownModelsFromConfig(
 	config: AgentConfig,
 ): Record<string, providers.ModelInfo> | undefined {
@@ -71,6 +103,7 @@ export class Agent {
 			| "tools"
 			| "maxParallelToolCalls"
 			| "apiTimeoutMs"
+			| "maxConsecutiveMistakes"
 			| "maxTokensPerTurn"
 			| "reminderAfterIterations"
 			| "reminderText"
@@ -102,15 +135,16 @@ export class Agent {
 			maxIterations: config.maxIterations,
 			maxParallelToolCalls: config.maxParallelToolCalls ?? 8,
 			apiTimeoutMs: config.apiTimeoutMs ?? 120000,
+			maxConsecutiveMistakes: config.maxConsecutiveMistakes ?? 0,
 			maxTokensPerTurn: config.maxTokensPerTurn ?? 8192,
-			reminderAfterIterations: config.reminderAfterIterations ?? 50,
+			reminderAfterIterations: config.reminderAfterIterations ?? 0,
 			reminderText: config.reminderText ?? DEFAULT_REMINDER_TEXT,
 			hookErrorMode: config.hookErrorMode ?? "ignore",
 			extensions: config.extensions ?? [],
 			toolPolicies: config.toolPolicies ?? {},
 		};
 
-		this.agentId = `agent_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+		this.agentId = `agent_${Date.now()}_${nanoid(6)}`;
 		this.parentAgentId = config.parentAgentId ?? null;
 		this.conversationStore = new ConversationStore(
 			config.initialMessages ?? [],
@@ -410,6 +444,7 @@ export class Agent {
 			cacheWriteTokens: 0,
 			totalCost: undefined,
 		};
+		let consecutiveMistakes = 0;
 
 		try {
 			if (!this.conversationStore.isSessionStarted()) {
@@ -536,12 +571,49 @@ export class Agent {
 					);
 				}
 
-				const { turn, assistantMessage } = await this.turnProcessor.processTurn(
-					this.conversationStore.getMessages(),
-					turnSystemPrompt,
-					this.config.tools,
-					abortSignal,
-				);
+				let turn: Awaited<ReturnType<TurnProcessor["processTurn"]>>["turn"];
+				let assistantMessage:
+					| Awaited<
+							ReturnType<TurnProcessor["processTurn"]>
+					  >["assistantMessage"]
+					| undefined;
+				try {
+					({ turn, assistantMessage } = await this.turnProcessor.processTurn(
+						this.conversationStore.getMessages(),
+						turnSystemPrompt,
+						this.config.tools,
+						abortSignal,
+					));
+				} catch (error) {
+					const errorObj =
+						error instanceof Error ? error : new Error(String(error));
+					const message = errorObj.message;
+					if (isNonRecoverableApiError(errorObj)) {
+						throw errorObj;
+					}
+					this.conversationStore.appendMessage({
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: `The previous turn failed with an API/runtime error: ${message}. Retry and continue from the latest state.`,
+							},
+						],
+					});
+					const shouldContinue = await this.recordMistake({
+						iteration,
+						reason: "api_error",
+						details: message,
+						consecutiveMistakes: () => consecutiveMistakes,
+						setConsecutiveMistakes: (value) => {
+							consecutiveMistakes = value;
+						},
+					});
+					if (shouldContinue) {
+						continue;
+					}
+					throw errorObj;
+				}
 				if (assistantMessage) {
 					this.conversationStore.appendMessage(assistantMessage);
 				}
@@ -586,7 +658,35 @@ export class Agent {
 					totalCost: totalUsage.totalCost,
 				});
 
+				if (turn.invalidToolCalls.length > 0) {
+					this.conversationStore.appendMessage({
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: this.buildInvalidToolCallFeedback(turn.invalidToolCalls),
+							},
+						],
+					});
+					const shouldContinue = await this.recordMistake({
+						iteration,
+						reason: "invalid_tool_call",
+						details: `${turn.invalidToolCalls.length} invalid tool call(s)`,
+						consecutiveMistakes: () => consecutiveMistakes,
+						setConsecutiveMistakes: (value) => {
+							consecutiveMistakes = value;
+						},
+					});
+					if (shouldContinue) {
+						continue;
+					}
+					throw new Error(
+						`maximum consecutive mistakes reached (${this.config.maxConsecutiveMistakes})`,
+					);
+				}
+
 				if (turn.toolCalls.length === 0) {
+					consecutiveMistakes = 0;
 					// Check completion guard before allowing the loop to end.
 					// If the guard returns a nudge string, inject it and continue.
 					const guardNudge = this.config.completionGuard?.();
@@ -648,6 +748,32 @@ export class Agent {
 						text: this.config.reminderText,
 					}),
 				);
+				const successfulToolCalls = toolResults.filter(
+					(record) => !record.error,
+				).length;
+				const failedToolCalls = toolResults.length - successfulToolCalls;
+				if (successfulToolCalls > 0) {
+					consecutiveMistakes = 0;
+				} else if (failedToolCalls > 0) {
+					const failedToolCallDetails =
+						this.buildFailedToolCallFeedback(toolResults);
+					const shouldContinue = await this.recordMistake({
+						iteration,
+						reason: "tool_execution_failed",
+						details: `${failedToolCalls} tool call(s) failed${
+							failedToolCallDetails ? `: ${failedToolCallDetails}` : ""
+						}`,
+						consecutiveMistakes: () => consecutiveMistakes,
+						setConsecutiveMistakes: (value) => {
+							consecutiveMistakes = value;
+						},
+					});
+					if (!shouldContinue) {
+						throw new Error(
+							`maximum consecutive mistakes reached (${this.config.maxConsecutiveMistakes})`,
+						);
+					}
+				}
 
 				this.emit({
 					type: "iteration_end",
@@ -770,6 +896,127 @@ export class Agent {
 		return result;
 	}
 
+	private buildInvalidToolCallFeedback(
+		invalidToolCalls: Array<{
+			id: string;
+			name?: string;
+			reason: "missing_name" | "missing_arguments" | "invalid_arguments";
+		}>,
+	): string {
+		const details = invalidToolCalls
+			.map((call) => {
+				const name = call.name?.trim() || "(unknown tool)";
+				const reason =
+					call.reason === "missing_name"
+						? "missing tool name"
+						: call.reason === "missing_arguments"
+							? "missing arguments"
+							: "arguments were invalid JSON";
+				return `${name} [${call.id}]: ${reason}`;
+			})
+			.join("; ");
+		return `One or more tool calls were invalid or missing required parameters (${details}). Retry with valid tool names and arguments.`;
+	}
+
+	private buildFailedToolCallFeedback(toolResults: ToolCallRecord[]): string {
+		const failed = toolResults.filter((record) => !!record.error);
+		if (failed.length === 0) {
+			return "";
+		}
+		const details = failed
+			.slice(0, 3)
+			.map((record) => {
+				const message = String(record.error ?? "unknown tool error")
+					.replace(/\s+/g, " ")
+					.trim();
+				return `${record.name}: ${message}`;
+			})
+			.join("; ");
+		return failed.length > 3
+			? `${details}; +${failed.length - 3} more failed tool call(s)`
+			: details;
+	}
+
+	private async recordMistake(input: {
+		iteration: number;
+		reason: "api_error" | "invalid_tool_call" | "tool_execution_failed";
+		details?: string;
+		consecutiveMistakes: () => number;
+		setConsecutiveMistakes: (value: number) => void;
+	}): Promise<boolean> {
+		const next = input.consecutiveMistakes() + 1;
+		input.setConsecutiveMistakes(next);
+		const errorMessage =
+			input.details?.trim() || `consecutive mistake (${input.reason})`;
+		this.emit({
+			type: "error",
+			error: new Error(errorMessage),
+			recoverable: true,
+			iteration: input.iteration,
+		});
+		this.log("warn", "Recorded consecutive mistake", {
+			agentId: this.agentId,
+			conversationId: this.conversationStore.getConversationId(),
+			runId: this.activeRunId || this.conversationStore.getConversationId(),
+			iteration: input.iteration,
+			reason: input.reason,
+			details: input.details,
+			consecutiveMistakes: next,
+			maxConsecutiveMistakes: this.config.maxConsecutiveMistakes,
+		});
+		const maxConsecutiveMistakes = this.config.maxConsecutiveMistakes;
+		if (!maxConsecutiveMistakes || next < maxConsecutiveMistakes) {
+			return true;
+		}
+
+		const decision = await this.resolveConsecutiveMistakeDecision({
+			iteration: input.iteration,
+			consecutiveMistakes: next,
+			maxConsecutiveMistakes,
+			reason: input.reason,
+			details: input.details,
+		});
+		if (decision.action === "continue") {
+			const guidance = decision.guidance?.trim();
+			if (guidance) {
+				this.conversationStore.appendMessage({
+					role: "user",
+					content: [{ type: "text", text: guidance }],
+				});
+			}
+			input.setConsecutiveMistakes(0);
+			return true;
+		}
+		return false;
+	}
+
+	private async resolveConsecutiveMistakeDecision(input: {
+		iteration: number;
+		consecutiveMistakes: number;
+		maxConsecutiveMistakes: number;
+		reason: "api_error" | "invalid_tool_call" | "tool_execution_failed";
+		details?: string;
+	}): Promise<ConsecutiveMistakeLimitDecision> {
+		const callback = this.config.onConsecutiveMistakeLimitReached;
+		if (!callback) {
+			return {
+				action: "stop",
+				reason: `maximum consecutive mistakes reached (${input.maxConsecutiveMistakes})`,
+			};
+		}
+		try {
+			return await callback(input);
+		} catch (error) {
+			return {
+				action: "stop",
+				reason:
+					error instanceof Error
+						? error.message
+						: `maximum consecutive mistakes reached (${input.maxConsecutiveMistakes})`,
+			};
+		}
+	}
+
 	private async ensureExtensionsInitialized(): Promise<void> {
 		if (this.extensionsInitialized) {
 			return;

package/src/hooks/engine.test.ts

@@ -42,6 +42,7 @@ describe("HookEngine", () => {
 		expect(calls).toEqual(["a-high", "z-low"]);
 		expect(result.control).toEqual({
 			cancel: true,
+			review: false,
 			context: "from-a\nfrom-z",
 			overrideInput: { safe: true },
 		});

package/src/index.ts

@@ -118,6 +118,8 @@ export {
 	type AgentUsage,
 	AgentUsageSchema,
 	type BasicLogger,
+	type ConsecutiveMistakeLimitContext,
+	type ConsecutiveMistakeLimitDecision,
 	type ContentBlock,
 	type HookErrorMode,
 	type Message,

package/src/runtime/tool-orchestrator.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import type { ToolCallRecord } from "../index.js";
+import { ToolOrchestrator } from "./tool-orchestrator.js";
+
+function createOrchestrator(): ToolOrchestrator {
+	return new ToolOrchestrator({
+		getAgentId: () => "agent-1",
+		getConversationId: () => "conversation-1",
+		getParentAgentId: () => null,
+		emit: () => {},
+		dispatchLifecycle: async () => undefined,
+		authorizeToolCall: async () => ({ allowed: true }),
+	});
+}
+
+describe("ToolOrchestrator reminder cadence", () => {
+	it("injects reminder only once per interval after threshold", () => {
+		const orchestrator = createOrchestrator();
+		const results = [
+			{
+				id: "tool-1",
+				name: "example-tool",
+				input: {},
+				durationMs: 100,
+				startedAt: new Date(),
+				endedAt: new Date(),
+				output: { ok: true },
+			},
+		] satisfies ToolCallRecord[];
+
+		const at50 = orchestrator.buildToolResultMessage(results, 50, {
+			afterIterations: 50,
+			text: "reminder",
+		});
+		const at51 = orchestrator.buildToolResultMessage(results, 51, {
+			afterIterations: 50,
+			text: "reminder",
+		});
+		const at52 = orchestrator.buildToolResultMessage(results, 52, {
+			afterIterations: 50,
+			text: "reminder",
+		});
+		const at101 = orchestrator.buildToolResultMessage(results, 101, {
+			afterIterations: 50,
+			text: "reminder",
+		});
+
+		expect(at50.content).toHaveLength(1);
+		expect(at51.content).toHaveLength(2);
+		expect(at52.content).toHaveLength(1);
+		expect(at101.content).toHaveLength(2);
+	});
+});

package/src/runtime/tool-orchestrator.ts

@@ -162,7 +162,7 @@ export class ToolOrchestrator {
 			});
 		}
 
-		if (reminder.afterIterations > 0 && iteration >= reminder.afterIterations) {
+		if (shouldInjectReminder(iteration, reminder.afterIterations)) {
 			content.push({
 				type: "text" as const,
 				text: reminder.text,
@@ -175,3 +175,14 @@ export class ToolOrchestrator {
 		};
 	}
 }
+
+function shouldInjectReminder(
+	iteration: number,
+	afterIterations: number,
+): boolean {
+	return (
+		afterIterations > 0 &&
+		iteration > afterIterations &&
+		(iteration - 1) % afterIterations === 0
+	);
+}

package/src/runtime/turn-processor.ts

@@ -59,6 +59,7 @@ export class TurnProcessor {
 			string,
 			{ name?: string; arguments: string; signature?: string }
 		>();
+		const toolCallIdAliases = new Map<string, string>();
 
 		for await (const chunk of stream) {
 			if (abortSignal.aborted) {
@@ -96,7 +97,11 @@ export class TurnProcessor {
 					});
 					break;
 				case "tool_calls":
-					this.processToolCallChunk(chunk, pendingToolCallsMap);
+					this.processToolCallChunk(
+						chunk,
+						pendingToolCallsMap,
+						toolCallIdAliases,
+					);
 					break;
 				case "usage":
 					usage.inputTokens = chunk.inputTokens;
@@ -115,6 +120,7 @@ export class TurnProcessor {
 		}
 
 		const toolCalls = this.finalizePendingToolCalls(pendingToolCallsMap);
+		const invalidToolCalls = this.collectInvalidToolCalls(pendingToolCallsMap);
 		const assistantContent: providers.ContentBlock[] = [];
 
 		if (text) {
@@ -168,6 +174,7 @@ export class TurnProcessor {
 				text,
 				reasoning: reasoning || undefined,
 				toolCalls,
+				invalidToolCalls,
 				usage,
 				truncated,
 				responseId,
@@ -182,15 +189,28 @@ export class TurnProcessor {
 			string,
 			{ name?: string; arguments: string; signature?: string }
 		>,
+		aliasMap: Map<string, string>,
 	): void {
 		const { tool_call } = chunk;
-		const callId =
-			tool_call.call_id ?? tool_call.function.id ?? `call_${Date.now()}`;
+		const functionId = tool_call.function.id;
+		const callId = tool_call.call_id;
+		const canonicalId =
+			(functionId ? aliasMap.get(functionId) : undefined) ??
+			(callId ? aliasMap.get(callId) : undefined) ??
+			functionId ??
+			callId ??
+			`call_${Date.now()}`;
+		if (functionId) {
+			aliasMap.set(functionId, canonicalId);
+		}
+		if (callId) {
+			aliasMap.set(callId, canonicalId);
+		}
 
-		let pending = pendingMap.get(callId);
+		let pending = pendingMap.get(canonicalId);
 		if (!pending) {
 			pending = { name: undefined, arguments: "" };
-			pendingMap.set(callId, pending);
+			pendingMap.set(canonicalId, pending);
 		}
 
 		if (tool_call.function.name) {
@@ -243,6 +263,37 @@ export class TurnProcessor {
 		return toolCalls;
 	}
 
+	private collectInvalidToolCalls(
+		pendingMap: Map<
+			string,
+			{ name?: string; arguments: string; signature?: string }
+		>,
+	): Array<{
+		id: string;
+		name?: string;
+		reason: "missing_name" | "missing_arguments" | "invalid_arguments";
+	}> {
+		const invalid: Array<{
+			id: string;
+			name?: string;
+			reason: "missing_name" | "missing_arguments" | "invalid_arguments";
+		}> = [];
+		for (const [id, pending] of pendingMap.entries()) {
+			if (!pending.name) {
+				invalid.push({ id, reason: "missing_name" });
+				continue;
+			}
+			if (!pending.arguments) {
+				invalid.push({ id, name: pending.name, reason: "missing_arguments" });
+				continue;
+			}
+			if (this.tryParseJson(pending.arguments) === undefined) {
+				invalid.push({ id, name: pending.name, reason: "invalid_arguments" });
+			}
+		}
+		return invalid;
+	}
+
 	private tryParseJson(value: string): unknown | undefined {
 		const parsed = parseJsonStream(value);
 		return parsed === value ? undefined : parsed;