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/test/generate.test.ts

@@ -3,8 +3,9 @@ import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { complete, stream } from "../src/generate.js";
+import { z } from "zod";
 import { getModel } from "../src/models.js";
+import { complete, stream } from "../src/stream.js";
 import type { Api, Context, ImageContent, Model, OptionsForApi, Tool, ToolResultMessage } from "../src/types.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -14,19 +15,13 @@ const __dirname = dirname(__filename);
 const calculatorTool: Tool = {
 	name: "calculator",
 	description: "Perform basic arithmetic operations",
-	parameters: {
-		type: "object",
-		properties: {
-			a: { type: "number", description: "First number" },
-			b: { type: "number", description: "Second number" },
-			operation: {
-				type: "string",
-				enum: ["add", "subtract", "multiply", "divide"],
-				description: "The operation to perform. One of 'add', 'subtract', 'multiply', 'divide'.",
-			},
-		},
-		required: ["a", "b", "operation"],
-	},
+	parameters: z.object({
+		a: z.number().describe("First number"),
+		b: z.number().describe("Second number"),
+		operation: z
+			.enum(["add", "subtract", "multiply", "divide"])
+			.describe("The operation to perform. One of 'add', 'subtract', 'multiply', 'divide'."),
+	}),
 };
 
 async function basicTextGeneration<TApi extends Api>(model: Model<TApi>, options?: OptionsForApi<TApi>) {