feat: require outputSchema for generator tools with dual-schema validation

Generator tools now require both eventSchema and outputSchema:
- Preliminary events are validated against eventSchema
- The last emitted value is validated against outputSchema (final result)
- Generator must emit at least one value (errors if empty)
- Last emission is always treated as final output sent to model
- Preliminary results exclude the final output

Updated type definitions, execution logic, tests, and examples.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Matt Apperson

examples/tools-example.ts

@@ -98,14 +98,22 @@ async function generatorToolExample() {
       inputSchema: z.object({
         data: z.string().describe("Data to process"),
       }),
+      // Events emitted during processing (validated against eventSchema)
       eventSchema: z.object({
-        type: z.enum(["start", "progress", "complete"]),
+        type: z.enum(["start", "progress"]),
         message: z.string(),
         progress: z.number().min(0).max(100).optional(),
       }),
+      // Final output (validated against outputSchema - different structure)
+      outputSchema: z.object({
+        result: z.string(),
+        processingTime: z.number(),
+      }),
       execute: async function* (params: { data: string }, context) {
         console.log(`Generator tool - Turn ${context.numberOfTurns}`);
-        // Preliminary result 1
+        const startTime = Date.now();
+
+        // Preliminary event 1
         yield {
           type: "start" as const,
           message: `Started processing: ${params.data}`,
@@ -114,7 +122,7 @@ async function generatorToolExample() {
 
         await new Promise((resolve) => setTimeout(resolve, 500));
 
-        // Preliminary result 2
+        // Preliminary event 2
         yield {
           type: "progress" as const,
           message: "Processing halfway done",
@@ -123,11 +131,10 @@ async function generatorToolExample() {
 
         await new Promise((resolve) => setTimeout(resolve, 500));
 
-        // Final result (last yield)
+        // Final output (different schema - sent to model)
         yield {
-          type: "complete" as const,
-          message: `Completed processing: ${params.data.toUpperCase()}`,
-          progress: 100,
+          result: params.data.toUpperCase(),
+          processingTime: Date.now() - startTime,
         };
       },
     },

src/lib/tool-executor.ts

@@ -123,9 +123,9 @@ export async function executeRegularTool(
 
 /**
  * Execute a generator tool and collect preliminary and final results
- * Following Vercel AI SDK pattern:
- * - All yielded values are preliminary results (for streaming to UI)
- * - Last yielded value is the final result (sent to model)
+ * - Intermediate yields are validated against eventSchema (preliminary events)
+ * - Last yield is validated against outputSchema (final result sent to model)
+ * - Generator must emit at least one value
  */
 export async function executeGeneratorTool(
   tool: EnhancedTool,
@@ -146,22 +146,40 @@ export async function executeGeneratorTool(
 
     // Execute generator and collect all results
     const preliminaryResults: unknown[] = [];
-    let finalResult: unknown = null;
+    let lastEmittedValue: unknown = null;
+    let hasEmittedValue = false;
 
     for await (const event of tool.function.execute(validatedInput as any, context)) {
+      hasEmittedValue = true;
+
       // Validate event against eventSchema
       const validatedEvent = validateToolOutput(tool.function.eventSchema, event);
 
       preliminaryResults.push(validatedEvent);
-      finalResult = validatedEvent;
+      lastEmittedValue = validatedEvent;
 
       // Emit preliminary result via callback
       if (onPreliminaryResult) {
         onPreliminaryResult(toolCall.id, validatedEvent);
       }
     }
 
-    // The last yielded value is the final result sent to model
+    // Generator must emit at least one value
+    if (!hasEmittedValue) {
+      throw new Error(
+        `Generator tool "${toolCall.name}" completed without emitting any values`
+      );
+    }
+
+    // Validate the last emitted value against outputSchema (this is the final result)
+    const finalResult = validateToolOutput(
+      tool.function.outputSchema,
+      lastEmittedValue
+    );
+
+    // Remove last item from preliminaryResults since it's the final output
+    preliminaryResults.pop();
+
     return {
       toolCallId: toolCall.id,
       toolName: toolCall.name,

src/lib/tool-types.ts

@@ -47,16 +47,30 @@ export interface ToolFunctionWithExecute<
 }
 
 /**
- * Generator-based tool with async generator execute function and eventSchema
- * Follows Vercel AI SDK pattern:
- * - All yielded values are "preliminary results" (streamed to UI)
- * - Last yielded value is the "final result" (sent to model)
+ * Generator-based tool with async generator execute function
+ * Emits preliminary events (validated by eventSchema) during execution
+ * and a final output (validated by outputSchema) as the last emission
+ *
+ * @example
+ * ```typescript
+ * {
+ *   eventSchema: z.object({ status: z.string() }),  // For progress events
+ *   outputSchema: z.object({ result: z.number() }), // For final output
+ *   execute: async function* (params) {
+ *     yield { status: "processing..." };  // Event
+ *     yield { status: "almost done..." }; // Event
+ *     yield { result: 42 };               // Final output (must be last)
+ *   }
+ * }
+ * ```
  */
 export interface ToolFunctionWithGenerator<
   TInput extends ZodObject<ZodRawShape>,
-  TEvent extends ZodType = ZodType<any>
+  TEvent extends ZodType = ZodType<any>,
+  TOutput extends ZodType = ZodType<any>
 > extends BaseToolFunction<TInput> {
   eventSchema: TEvent;
+  outputSchema: TOutput;
   execute: (
     params: z.infer<TInput>,
     context?: TurnContext
@@ -89,10 +103,11 @@ export type ToolWithExecute<
  */
 export type ToolWithGenerator<
   TInput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>,
-  TEvent extends ZodType = ZodType<any>
+  TEvent extends ZodType = ZodType<any>,
+  TOutput extends ZodType = ZodType<any>
 > = {
   type: ToolType.Function;
-  function: ToolFunctionWithGenerator<TInput, TEvent>;
+  function: ToolFunctionWithGenerator<TInput, TEvent, TOutput>;
 };
 
 /**

tests/e2e/getResponse-tools.test.ts

@@ -188,8 +188,8 @@ describe("Enhanced Tool Support for getResponse", () => {
 
   describe("Generator Tools (Preliminary Results)", () => {
     it("should collect all yielded values as preliminary results", async () => {
-      const weatherSchema = z.object({
-        type: z.enum(["start", "update", "end"]),
+      const eventSchema = z.object({
+        type: z.enum(["start", "update"]),
         data: z
           .object({
             location: z.string().optional(),
@@ -199,6 +199,12 @@ describe("Enhanced Tool Support for getResponse", () => {
           .optional(),
       });
 
+      const outputSchema = z.object({
+        temperature: z.number(),
+        description: z.string(),
+        location: z.string(),
+      });
+
       const generatorTool = {
         type: ToolType.Function,
         function: {
@@ -207,14 +213,20 @@ describe("Enhanced Tool Support for getResponse", () => {
           inputSchema: z.object({
             location: z.string(),
           }),
-          eventSchema: weatherSchema,
+          eventSchema,
+          outputSchema,
           execute: async function* (params: { location: string }, context) {
             yield { type: "start" as const, data: { location: params.location } };
             yield {
               type: "update" as const,
               data: { temperature: 20, description: "Clear skies" },
             };
-            yield { type: "end" as const };
+            // Final output (different schema)
+            yield {
+              temperature: 20,
+              description: "Clear skies",
+              location: params.location,
+            };
           },
         },
       };
@@ -224,17 +236,17 @@ describe("Enhanced Tool Support for getResponse", () => {
         messageHistory: [],
         model: "test-model",
       };
-      const results: Array<z.infer<typeof weatherSchema>> = [];
+      const results: unknown[] = [];
       for await (const result of generatorTool.function.execute({
         location: "Tokyo",
       }, mockContext)) {
         results.push(result);
       }
 
       expect(results).toHaveLength(3);
-      expect(results[0].type).toBe("start");
-      expect(results[1].type).toBe("update");
-      expect(results[2].type).toBe("end");
+      expect(results[0]).toEqual({ type: "start", data: { location: "Tokyo" } });
+      expect(results[1]).toEqual({ type: "update", data: { temperature: 20, description: "Clear skies" } });
+      expect(results[2]).toEqual({ temperature: 20, description: "Clear skies", location: "Tokyo" });
     });
 
     it("should send only final (last) yield to model", async () => {
@@ -245,12 +257,15 @@ describe("Enhanced Tool Support for getResponse", () => {
           inputSchema: z.object({ data: z.string() }),
           eventSchema: z.object({
             status: z.string(),
-            result: z.any().optional(),
+          }),
+          outputSchema: z.object({
+            result: z.string(),
           }),
           execute: async function* (params: { data: string }, context) {
             yield { status: "processing" };
             yield { status: "almost_done" };
-            yield { status: "complete", result: `Processed: ${params.data}` };
+            // Final output (different schema)
+            yield { result: `Processed: ${params.data}` };
           },
         },
       };
@@ -266,8 +281,7 @@ describe("Enhanced Tool Support for getResponse", () => {
       }
 
       const finalResult = results[results.length - 1];
-      expect(finalResult.status).toBe("complete");
-      expect(finalResult.result).toBe("Processed: test");
+      expect(finalResult).toEqual({ result: "Processed: test" });
     });
 
     it("should validate all events against eventSchema", async () => {
@@ -311,10 +325,12 @@ describe("Enhanced Tool Support for getResponse", () => {
           name: "streaming_tool",
           inputSchema: z.object({ input: z.string() }),
           eventSchema: z.object({ progress: z.number(), message: z.string() }),
+          outputSchema: z.object({ completed: z.boolean(), finalProgress: z.number() }),
           execute: async function* (params: { input: string }, context) {
             yield { progress: 25, message: "Quarter done" };
             yield { progress: 50, message: "Half done" };
-            yield { progress: 100, message: "Complete" };
+            // Final output (different schema)
+            yield { completed: true, finalProgress: 100 };
           },
         },
       };
@@ -330,9 +346,37 @@ describe("Enhanced Tool Support for getResponse", () => {
       }
 
       expect(preliminaryResults).toHaveLength(3);
-      expect(preliminaryResults[0].progress).toBe(25);
-      expect(preliminaryResults[1].progress).toBe(50);
-      expect(preliminaryResults[2].progress).toBe(100);
+      expect(preliminaryResults[0]).toEqual({ progress: 25, message: "Quarter done" });
+      expect(preliminaryResults[1]).toEqual({ progress: 50, message: "Half done" });
+      expect(preliminaryResults[2]).toEqual({ completed: true, finalProgress: 100 });
+    });
+
+    it("should throw error if generator completes without emitting values", async () => {
+      const generatorTool = {
+        type: ToolType.Function,
+        function: {
+          name: "empty_generator",
+          inputSchema: z.object({}),
+          eventSchema: z.object({ status: z.string() }),
+          outputSchema: z.object({ result: z.string() }),
+          execute: async function* (params, context) {
+            // Emit nothing
+          },
+        },
+      };
+
+      const mockContext = {
+        numberOfTurns: 1,
+        messageHistory: [],
+        model: "test-model",
+      };
+
+      const results = [];
+      for await (const result of generatorTool.function.execute({}, mockContext)) {
+        results.push(result);
+      }
+
+      expect(results).toHaveLength(0);
     });
   });