refactor(ai): improve error handling and stop reason types

- Add 'aborted' as a distinct stop reason separate from 'error'
- Change AssistantMessage.error to errorMessage for clarity
- Update error event to include reason field ('error' | 'aborted')
- Map provider-specific safety/refusal reasons to 'error' stop reason
- Reorganize utility functions into utils/ directory
- Rename agent.ts to agent-loop.ts for better clarity
- Fix error handling in all providers to properly distinguish abort from error

packages/ai/src/agent/agent-loop.ts

@@ -0,0 +1,213 @@
+import { streamSimple } from "../stream.js";
+import type { AssistantMessage, Context, Message, ToolResultMessage, UserMessage } from "../types.js";
+import { EventStream } from "../utils/event-stream.js";
+import { validateToolArguments } from "../utils/validation.js";
+import type { AgentContext, AgentEvent, AgentTool, AgentToolResult, PromptConfig } from "./types.js";
+
+// Main prompt function - returns a stream of events
+export function agentLoop(
+	prompt: UserMessage,
+	context: AgentContext,
+	config: PromptConfig,
+	signal?: AbortSignal,
+	streamFn?: typeof streamSimple,
+): EventStream<AgentEvent, AgentContext["messages"]> {
+	const stream = new EventStream<AgentEvent, AgentContext["messages"]>(
+		(event: AgentEvent) => event.type === "agent_end",
+		(event: AgentEvent) => (event.type === "agent_end" ? event.messages : []),
+	);
+
+	// Run the prompt async
+	(async () => {
+		// Track new messages generated during this prompt
+		const newMessages: AgentContext["messages"] = [];
+		// Create user message for the prompt
+		const messages = [...context.messages, prompt];
+		newMessages.push(prompt);
+
+		stream.push({ type: "agent_start" });
+		stream.push({ type: "turn_start" });
+		stream.push({ type: "message_start", message: prompt });
+		stream.push({ type: "message_end", message: prompt });
+
+		// Update context with new messages
+		const currentContext: AgentContext = {
+			...context,
+			messages,
+		};
+
+		// Keep looping while we have tool calls
+		let hasMoreToolCalls = true;
+		let firstTurn = true;
+		while (hasMoreToolCalls) {
+			if (!firstTurn) {
+				stream.push({ type: "turn_start" });
+			} else {
+				firstTurn = false;
+			}
+			// Stream assistant response
+			const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn);
+			newMessages.push(message);
+
+			if (message.stopReason === "error" || message.stopReason === "aborted") {
+				// Stop the loop on error or abort
+				stream.push({ type: "turn_end", message, toolResults: [] });
+				stream.push({ type: "agent_end", messages: newMessages });
+				stream.end(newMessages);
+				return;
+			}
+
+			// Check for tool calls
+			const toolCalls = message.content.filter((c) => c.type === "toolCall");
+			hasMoreToolCalls = toolCalls.length > 0;
+
+			const toolResults: ToolResultMessage[] = [];
+			if (hasMoreToolCalls) {
+				// Execute tool calls
+				toolResults.push(...(await executeToolCalls(currentContext.tools, message, signal, stream)));
+				currentContext.messages.push(...toolResults);
+				newMessages.push(...toolResults);
+			}
+			stream.push({ type: "turn_end", message, toolResults: toolResults });
+		}
+		stream.push({ type: "agent_end", messages: newMessages });
+		stream.end(newMessages);
+	})();
+
+	return stream;
+}
+
+// Helper functions
+async function streamAssistantResponse(
+	context: AgentContext,
+	config: PromptConfig,
+	signal: AbortSignal | undefined,
+	stream: EventStream<AgentEvent, AgentContext["messages"]>,
+	streamFn?: typeof streamSimple,
+): Promise<AssistantMessage> {
+	// Convert AgentContext to Context for streamSimple
+	// Use a copy of messages to avoid mutating the original context
+	const processedMessages = config.preprocessor
+		? await config.preprocessor(context.messages, signal)
+		: [...context.messages];
+	const processedContext: Context = {
+		systemPrompt: context.systemPrompt,
+		messages: [...processedMessages].map((m) => {
+			if (m.role === "toolResult") {
+				const { details, ...rest } = m;
+				return rest;
+			} else {
+				return m;
+			}
+		}),
+		tools: context.tools, // AgentTool extends Tool, so this works
+	};
+
+	// Use custom stream function if provided, otherwise use default streamSimple
+	const streamFunction = streamFn || streamSimple;
+	const response = await streamFunction(config.model, processedContext, { ...config, signal });
+
+	let partialMessage: AssistantMessage | null = null;
+	let addedPartial = false;
+
+	for await (const event of response) {
+		switch (event.type) {
+			case "start":
+				partialMessage = event.partial;
+				context.messages.push(partialMessage);
+				addedPartial = true;
+				stream.push({ type: "message_start", message: { ...partialMessage } });
+				break;
+
+			case "text_start":
+			case "text_delta":
+			case "text_end":
+			case "thinking_start":
+			case "thinking_delta":
+			case "thinking_end":
+			case "toolcall_start":
+			case "toolcall_delta":
+			case "toolcall_end":
+				if (partialMessage) {
+					partialMessage = event.partial;
+					context.messages[context.messages.length - 1] = partialMessage;
+					stream.push({ type: "message_update", assistantMessageEvent: event, message: { ...partialMessage } });
+				}
+				break;
+
+			case "done":
+			case "error": {
+				const finalMessage = await response.result();
+				if (addedPartial) {
+					context.messages[context.messages.length - 1] = finalMessage;
+				} else {
+					context.messages.push(finalMessage);
+				}
+				stream.push({ type: "message_end", message: finalMessage });
+				return finalMessage;
+			}
+		}
+	}
+
+	return await response.result();
+}
+
+async function executeToolCalls<T>(
+	tools: AgentTool<any, T>[] | undefined,
+	assistantMessage: AssistantMessage,
+	signal: AbortSignal | undefined,
+	stream: EventStream<AgentEvent, Message[]>,
+): Promise<ToolResultMessage<T>[]> {
+	const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+	const results: ToolResultMessage<any>[] = [];
+
+	for (const toolCall of toolCalls) {
+		const tool = tools?.find((t) => t.name === toolCall.name);
+
+		stream.push({
+			type: "tool_execution_start",
+			toolCallId: toolCall.id,
+			toolName: toolCall.name,
+			args: toolCall.arguments,
+		});
+
+		let resultOrError: AgentToolResult<T> | string;
+		let isError = false;
+
+		try {
+			if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
+
+			// Validate arguments using shared validation function
+			const validatedArgs = validateToolArguments(tool, toolCall);
+
+			// Execute with validated, typed arguments
+			resultOrError = await tool.execute(toolCall.id, validatedArgs, signal);
+		} catch (e) {
+			resultOrError = e instanceof Error ? e.message : String(e);
+			isError = true;
+		}
+
+		stream.push({
+			type: "tool_execution_end",
+			toolCallId: toolCall.id,
+			toolName: toolCall.name,
+			result: resultOrError,
+			isError,
+		});
+
+		const toolResultMessage: ToolResultMessage<T> = {
+			role: "toolResult",
+			toolCallId: toolCall.id,
+			toolName: toolCall.name,
+			output: typeof resultOrError === "string" ? resultOrError : resultOrError.output,
+			details: typeof resultOrError === "string" ? ({} as T) : resultOrError.details,
+			isError,
+		};
+
+		results.push(toolResultMessage);
+		stream.push({ type: "message_start", message: toolResultMessage });
+		stream.push({ type: "message_end", message: toolResultMessage });
+	}
+
+	return results;
+}