feat(ai): Implement Zod-based tool validation and improve Agent API

- Replace JSON Schema with Zod schemas for tool parameter definitions
- Add runtime validation for all tool calls at provider level
- Create shared validation module with detailed error formatting
- Update Agent API with comprehensive event system
- Add agent tests with calculator tool for multi-turn execution
- Add abort test to verify proper handling of aborted requests
- Update documentation with detailed event flow examples
- Rename generate.ts to stream.ts for clarity

packages/ai/src/validation.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { Tool, ToolCall } from "./types.js";
+
+/**
+ * Validates tool call arguments against the tool's Zod schema
+ * @param tool The tool definition with Zod schema
+ * @param toolCall The tool call from the LLM
+ * @returns The validated arguments
+ * @throws ZodError with formatted message if validation fails
+ */
+export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {
+	try {
+		// Validate arguments with Zod schema
+		return tool.parameters.parse(toolCall.arguments);
+	} catch (e) {
+		if (e instanceof z.ZodError) {
+			// Format validation errors nicely
+			const errors = e.issues
+				.map((err) => {
+					const path = err.path.length > 0 ? err.path.join(".") : "root";
+					return `  - ${path}: ${err.message}`;
+				})
+				.join("\n");
+
+			const errorMessage = `Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`;
+
+			// Throw a new error with the formatted message
+			throw new Error(errorMessage);
+		}
+		throw e;
+	}
+}