feat: add strongly typed tools with createTool helpers

- Add createTool, createGeneratorTool, createManualTool factory functions
- Add type inference helpers: InferToolInput, InferToolOutput, InferToolEvent
- Add TypedToolCall and TypedToolCallUnion for typed tool call results
- Add InferToolEventsUnion for typed generator event streams
- Make ResponseWrapper generic with TTools parameter
- Make callModel generic to preserve tool types through call chain
- Make event types generic (ToolStreamEvent, ChatStreamEvent, etc.)
- Export all new types from index.ts
- Add example demonstrating typed tool calling

When using 'as const' with tools array, all type information flows through:
- toolCall.arguments is typed based on inputSchema
- event.result in streams is typed based on eventSchema

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

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

Author: mattapperson

examples/callModel-typed-tool-calling.example.ts

@@ -0,0 +1,164 @@
+/*
+ * Example: Typed Tool Calling with callModel
+ *
+ * This example demonstrates how to use createTool and createGeneratorTool for
+ * fully-typed tool definitions where execute params, return types, and event
+ * types are automatically inferred from Zod schemas.
+ *
+ * To run this example from the examples directory:
+ * npm run build && npx tsx callModel-typed-tool-calling.example.ts
+ */
+
+import dotenv from "dotenv";
+dotenv.config();
+
+import { OpenRouter, createTool, createGeneratorTool } from "../src/index.js";
+import z from "zod";
+
+const openRouter = new OpenRouter({
+  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
+});
+
+// Create a typed tool using createTool
+// The execute function params are automatically typed as z.infer<typeof inputSchema>
+// The return type is enforced based on outputSchema
+const weatherTool = createTool({
+  name: "get_weather",
+  description: "Get the current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("The city and country, e.g. San Francisco, CA"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    description: z.string(),
+  }),
+  // params is automatically typed as { location: string }
+  execute: async (params) => {
+    console.log(`Getting weather for: ${params.location}`);
+    // Return type is enforced as { temperature: number; description: string }
+    return {
+      temperature: 20,
+      description: "Sunny",
+    };
+  },
+});
+
+// Create a generator tool with typed progress events
+// The eventSchema defines the type of events yielded during execution
+const searchTool = createGeneratorTool({
+  name: "search_database",
+  description: "Search database with progress updates",
+  inputSchema: z.object({
+    query: z.string().describe("The search query"),
+  }),
+  eventSchema: z.object({
+    progress: z.number(),
+    message: z.string(),
+  }),
+  outputSchema: z.object({
+    results: z.array(z.string()),
+    totalFound: z.number(),
+  }),
+  // execute is a generator that yields typed progress events
+  execute: async function* (params) {
+    console.log(`Searching for: ${params.query}`);
+    // Each yield is typed as { progress: number; message: string }
+    yield { progress: 25, message: "Searching..." };
+    yield { progress: 50, message: "Processing results..." };
+    yield { progress: 75, message: "Almost done..." };
+    // Final result is typed as { results: string[]; totalFound: number }
+    yield { progress: 100, message: "Complete!" };
+  },
+});
+
+async function main() {
+  console.log("=== Typed Tool Calling Example ===\n");
+
+  // Use 'as const' to enable full type inference for tool calls
+  const result = openRouter.callModel({
+    instructions: "You are a helpful assistant. Your name is Mark",
+    model: "openai/gpt-4o-mini",
+    input: "Hello! What is the weather in San Francisco?",
+    tools: [weatherTool] as const,
+  });
+
+  // Get text response (tools are auto-executed)
+  const text = await result.getText();
+  console.log("Response:", text);
+
+  console.log("\n=== Getting Tool Calls ===\n");
+
+  // Create a fresh request for demonstrating getToolCalls
+  const result2 = openRouter.callModel({
+    model: "openai/gpt-4o-mini",
+    input: "What's the weather like in Paris?",
+    tools: [weatherTool] as const,
+    maxToolRounds: 0, // Don't auto-execute, just get the tool calls
+  });
+
+  // Tool calls are now typed based on the tool definitions!
+  const toolCalls = await result2.getToolCalls();
+
+  for (const toolCall of toolCalls) {
+    console.log(`Tool: ${toolCall.name}`);
+    // toolCall.arguments is typed as { location: string }
+    console.log(`Arguments:`, toolCall.arguments);
+  }
+
+  console.log("\n=== Streaming Tool Calls ===\n");
+
+  // Create another request for demonstrating streaming
+  const result3 = openRouter.callModel({
+    model: "openai/gpt-4o-mini",
+    input: "What's the weather in Tokyo?",
+    tools: [weatherTool] as const,
+    maxToolRounds: 0,
+  });
+
+  // Stream tool calls with typed arguments
+  for await (const toolCall of result3.getToolCallsStream()) {
+    console.log(`Streamed tool: ${toolCall.name}`);
+    // toolCall.arguments is typed based on tool definitions
+    console.log(`Streamed arguments:`, toolCall.arguments);
+  }
+
+  console.log("\n=== Generator Tool with Typed Events ===\n");
+
+  // Use generator tool with typed progress events
+  const result4 = openRouter.callModel({
+    model: "openai/gpt-4o-mini",
+    input: "Search for documents about TypeScript",
+    tools: [searchTool] as const,
+  });
+
+  // Stream events from getToolStream - events are fully typed!
+  for await (const event of result4.getToolStream()) {
+    if (event.type === "preliminary_result") {
+      // event.result is typed as { progress: number; message: string }
+      console.log(`Progress: ${event.result.progress}% - ${event.result.message}`);
+    } else if (event.type === "delta") {
+      // Tool argument deltas
+      process.stdout.write(event.content);
+    }
+  }
+
+  console.log("\n=== Mixed Tools with Typed Events ===\n");
+
+  // Use both regular and generator tools together
+  const result5 = openRouter.callModel({
+    model: "openai/gpt-4o-mini",
+    input: "First search for weather data, then get the weather in Seattle",
+    tools: [weatherTool, searchTool] as const,
+  });
+
+  // Events are a union of all generator tool event types
+  for await (const event of result5.getToolStream()) {
+    if (event.type === "preliminary_result") {
+      // event.result is typed as { progress: number; message: string }
+      // (only searchTool has eventSchema, so that's the event type)
+      console.log(`Event:`, event.result);
+    }
+  }
+}
+
+main().catch(console.error);

src/index.ts

@@ -12,3 +12,32 @@ export * from "./sdk/sdk.js";
 export { fromClaudeMessages, toClaudeMessage } from "./lib/anthropic-compat.js";
 export { fromChatMessages, toChatMessage } from "./lib/chat-compat.js";
 export { extractUnsupportedContent, hasUnsupportedContent, getUnsupportedContentSummary } from "./lib/stream-transformers.js";
+
+// Tool creation helpers
+export {
+  createTool,
+  createGeneratorTool,
+  createManualTool,
+} from "./lib/create-tool.js";
+
+// Tool type inference helpers
+export type {
+  Tool,
+  ToolWithExecute,
+  ToolWithGenerator,
+  ManualTool,
+  InferToolInput,
+  InferToolOutput,
+  TypedToolCall,
+  TypedToolCallUnion,
+  TurnContext,
+  ParsedToolCall,
+  // Event type inference helpers
+  InferToolEvent,
+  InferToolEventsUnion,
+  // Stream event types
+  ToolPreliminaryResultEvent,
+  ToolStreamEvent,
+  ChatStreamEvent,
+  EnhancedResponseStreamEvent,
+} from "./lib/tool-types.js";

src/lib/create-tool.ts

@@ -0,0 +1,157 @@
+import type { ZodObject, ZodRawShape, ZodType, z } from 'zod/v4';
+import {
+  ToolType,
+  type TurnContext,
+  type ToolWithExecute,
+  type ToolWithGenerator,
+  type ManualTool,
+} from './tool-types.js';
+
+/**
+ * Creates a tool with full type inference from Zod schemas.
+ *
+ * The execute function parameters are automatically typed based on the inputSchema,
+ * and the return type is enforced based on the outputSchema.
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = createTool({
+ *   name: "get_weather",
+ *   description: "Get weather for a location",
+ *   inputSchema: z.object({ location: z.string() }),
+ *   outputSchema: z.object({ temperature: z.number() }),
+ *   execute: async (params) => {
+ *     // params is typed as { location: string }
+ *     return { temperature: 72 }; // return type is enforced
+ *   },
+ * });
+ * ```
+ */
+export function createTool<
+  TInput extends ZodObject<ZodRawShape>,
+  TOutput extends ZodType = ZodType<unknown>,
+>(config: {
+  name: string;
+  description?: string;
+  inputSchema: TInput;
+  outputSchema?: TOutput;
+  execute: (
+    params: z.infer<TInput>,
+    context?: TurnContext,
+  ) => Promise<z.infer<TOutput>> | z.infer<TOutput>;
+}): ToolWithExecute<TInput, TOutput> {
+  const fn: ToolWithExecute<TInput, TOutput>['function'] = {
+    name: config.name,
+    inputSchema: config.inputSchema,
+    execute: config.execute,
+  };
+
+  if (config.description !== undefined) {
+    fn.description = config.description;
+  }
+
+  if (config.outputSchema !== undefined) {
+    fn.outputSchema = config.outputSchema as TOutput;
+  }
+
+  return {
+    type: ToolType.Function,
+    function: fn,
+  };
+}
+
+/**
+ * Creates a generator tool with streaming capabilities.
+ *
+ * Generator tools can yield intermediate events (validated by eventSchema) during execution
+ * and a final output (validated by outputSchema) as the last emission.
+ *
+ * @example
+ * ```typescript
+ * const progressTool = createGeneratorTool({
+ *   name: "process_data",
+ *   inputSchema: z.object({ data: z.string() }),
+ *   eventSchema: z.object({ progress: z.number() }),
+ *   outputSchema: z.object({ result: z.string() }),
+ *   execute: async function* (params) {
+ *     yield { progress: 50 }; // typed as event
+ *     yield { result: "done" }; // typed as output
+ *   },
+ * });
+ * ```
+ */
+export function createGeneratorTool<
+  TInput extends ZodObject<ZodRawShape>,
+  TEvent extends ZodType,
+  TOutput extends ZodType,
+>(config: {
+  name: string;
+  description?: string;
+  inputSchema: TInput;
+  eventSchema: TEvent;
+  outputSchema: TOutput;
+  execute: (
+    params: z.infer<TInput>,
+    context?: TurnContext,
+  ) => AsyncGenerator<z.infer<TEvent> | z.infer<TOutput>>;
+}): ToolWithGenerator<TInput, TEvent, TOutput> {
+  const fn: ToolWithGenerator<TInput, TEvent, TOutput>['function'] = {
+    name: config.name,
+    inputSchema: config.inputSchema,
+    eventSchema: config.eventSchema,
+    outputSchema: config.outputSchema,
+    execute: config.execute as ToolWithGenerator<TInput, TEvent, TOutput>['function']['execute'],
+  };
+
+  if (config.description !== undefined) {
+    fn.description = config.description;
+  }
+
+  return {
+    type: ToolType.Function,
+    function: fn,
+  };
+}
+
+/**
+ * Creates a manual tool without an execute function.
+ *
+ * Manual tools are useful when you want to handle tool execution yourself,
+ * for example when the tool requires external processing or user interaction.
+ *
+ * @example
+ * ```typescript
+ * const manualTool = createManualTool({
+ *   name: "external_api",
+ *   inputSchema: z.object({ query: z.string() }),
+ *   outputSchema: z.object({ response: z.string() }),
+ * });
+ * ```
+ */
+export function createManualTool<
+  TInput extends ZodObject<ZodRawShape>,
+  TOutput extends ZodType = ZodType<unknown>,
+>(config: {
+  name: string;
+  description?: string;
+  inputSchema: TInput;
+  outputSchema?: TOutput;
+}): ManualTool<TInput, TOutput> {
+  const fn: ManualTool<TInput, TOutput>['function'] = {
+    name: config.name,
+    inputSchema: config.inputSchema,
+  };
+
+  if (config.description !== undefined) {
+    fn.description = config.description;
+  }
+
+  if (config.outputSchema !== undefined) {
+    fn.outputSchema = config.outputSchema as TOutput;
+  }
+
+  return {
+    type: ToolType.Function,
+    function: fn,
+  };
+}