feat: enable real-time streaming of generator tool preliminary results

[mattapperson]

Summary

This PR enables real-time streaming of generator tool preliminary results - yields are streamed AS they happen during execution, instead of being batched after tool execution completes.

Key changes:

• ToolEventBroadcaster: New push-based multi-consumer event broadcaster following the ReusableReadableStream pattern
• Real-time streaming: getToolStream() and getFullResponsesStream() now yield preliminary results as generator tools emit them
• Bug fix: Fixed toJSONSchema target from invalid 'openapi-3.0' to 'draft-7' (Zod v4 compatibility)

How it works

1. When a generator tool executes, each yield is immediately pushed to ToolEventBroadcaster
2. Consumers created via createConsumer() receive events in real-time as they're pushed
3. Multiple consumers can be created and each gets all events from position 0
4. The broadcaster buffers events for late-joining consumers

Example Usage

Define a generator tool with progress events

import { tool } from "@openrouter/sdk";
import { z } from "zod";

const searchTool = tool({
  name: "search_database",
  description: "Search with progress updates",
  inputSchema: z.object({ query: z.string() }),
  // eventSchema defines the type of intermediate yields
  eventSchema: z.object({
    progress: z.number(),
    message: z.string(),
  }),
  // outputSchema defines the final result sent to the model
  outputSchema: z.object({
    results: z.array(z.string()),
    totalFound: z.number(),
  }),
  // Generator function yields progress, final yield is the result
  execute: async function* (params) {
    yield { progress: 25, message: "Searching..." };
    yield { progress: 50, message: "Processing results..." };
    yield { progress: 75, message: "Almost done..." };
    // Final yield must match outputSchema
    yield { results: ["doc1", "doc2"], totalFound: 2 };
  },
});

Consume real-time events with getToolStream()

const result = client.callModel({
  model: "anthropic/claude-sonnet-4",
  input: [{ role: "user", content: "Search for documents about TypeScript" }],
  tools: [searchTool],
});

for await (const event of result.getToolStream()) {
  if (event.type === "preliminary_result") {
    // Real-time progress as generator yields
    console.log(`Progress: ${event.result.progress}% - ${event.result.message}`);
  } else if (event.type === "delta") {
    // Tool argument deltas from API
    process.stdout.write(event.content);
  }
}

Consume with getFullResponsesStream()

for await (const event of result.getFullResponsesStream()) {
  if (event.type === "tool.preliminary_result") {
    // Real-time tool progress events
    console.log(`Tool ${event.toolCallId}: ${JSON.stringify(event.result)}`);
  } else {
    // Handle other API stream events (response.created, response.delta, etc.)
    console.log(event.type);
  }
}

Files changed

File	Changes
src/lib/tool-event-broadcaster.ts	NEW - Push-based multi-consumer broadcaster
src/lib/model-result.ts	Wire broadcaster into tool execution and streaming methods
src/lib/tool-executor.ts	Fix toJSONSchema target, add typeguard for zod schema
src/index.ts	Export ToolEventBroadcaster
tests/unit/tool-event-broadcaster.test.ts	NEW - 13 unit tests
tests/e2e/call-model-tools.test.ts	Fix test toJSONSchema targets

Test plan

• Unit tests for ToolEventBroadcaster (13 tests)
• E2E tests for tool execution (23 tests)
• Build passes
• Lint passes

[louisgv]

Otherwise lgtm!