refactor: consolidate tool creation functions into unified tool()

- Rename createTool to tool() as the primary API
- Add support for manual tools with execute: false
- Auto-detect tool type based on configuration:
  - Generator tool: when eventSchema is provided
  - Regular tool: when execute is a function
  - Manual tool: when execute: false
- Keep createTool, createGeneratorTool, createManualTool as deprecated aliases
- Update tests and examples to use new tool() API

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

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

Author: mattapperson

examples/callModel-tool-request-mutations.example.ts

@@ -0,0 +1,208 @@
+/*
+ * Example: Tool Request Mutations with callModel
+ *
+ * This example demonstrates how to use the tool() function with nextTurnParams
+ * for tools that can mutate the request between turns.
+ *
+ * To run this example from the examples directory:
+ * npm run build && npx tsx callModel-tool-request-mutations.example.ts
+ */
+
+import dotenv from "dotenv";
+dotenv.config();
+
+import { OpenRouter, tool } from "../src/index.js";
+import z from "zod";
+import { readFileSync } from "node:fs";
+
+const openRouter = new OpenRouter({
+  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
+});
+
+const SkillsTool = tool({
+  name: "Skill",
+  description: `
+  Execute a skill within the main conversation. Skills provide specialized capabilities and domain knowledge for specific tasks.
+
+  How to invoke:
+  - Use this tool with the skill name only (no arguments)
+  - Examples:
+    - skill: "pdf" - invoke the pdf skill
+    - skill: "xlsx" - invoke the xlsx skill
+    - skill: "ms-office-suite:pdf" - invoke using fully qualified name
+
+  Key behaviors:
+  - When a skill is relevant, I must invoke it IMMEDIATELY as my first action
+  - I should never just mention a skill without actually calling this tool
+  - Only use skills listed in <available_skills>
+  - Cannot invoke a skill that is already running
+  - Not used for built-in CLI commands`,
+  inputSchema: z.object({
+    type: z
+      .string()
+      .describe('The skill name (no arguments). E.g., "pdf" or "xlsx"'),
+  }),
+  outputSchema: z.string(),
+  // these run on on every turn where this tool was called after all tool calls
+  // are executed and before the responses are sent to the model. They are exicuted in the order of the tools array
+  // in the request. nextTurnParams is optional.
+  nextTurnParams: {
+    // allowed keys/params are anything in the normal callModel request
+    input: (params, context) => {
+      // This is a quick and dirty way to check if the skill is already loaded
+      // Not recommended for production use
+      if (
+        JSON.stringify(context.input).includes(
+          `Skill ${params.type} is already loaded`
+        )
+      ) {
+        return context.input;
+      }
+
+      const skill = readFileSync(
+        `~/.claude/skills/${params.type}/SKILL.md`,
+        "utf-8"
+      );
+      // ... mutate / build new instructions based on context
+      return [
+        ...context.input,
+        {
+          role: "user",
+          content: `Base directory for this skill: ~/.claude/skills/${params.type}/
+
+${skill}`,
+        },
+      ];
+    },
+  },
+  // params is automatically typed as { location: string }
+  execute: async (params, context) => {
+    if (JSON.stringify(context.input).includes("")) {
+      return `Skill ${params.type} is already loaded`;
+    }
+
+    return `Laynching skill ${params.type}`;
+  },
+});
+
+// Create a generator tool with typed progress events
+// The eventSchema triggers generator mode
+const searchTool = tool({
+  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: [SkillsTool] 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: [SkillsTool] 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: [SkillsTool] 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: [SkillsTool, 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);

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

@@ -1,28 +1,33 @@
 /*
  * Example: Typed Tool Calling with callModel
  *
- * This example demonstrates how to use createTool and createGeneratorTool for
+ * This example demonstrates how to use the tool() function for
  * fully-typed tool definitions where execute params, return types, and event
  * types are automatically inferred from Zod schemas.
  *
+ * Tool types are auto-detected based on configuration:
+ * - Generator tool: When `eventSchema` is provided
+ * - Regular tool: When `execute` is a function (no `eventSchema`)
+ * - Manual tool: When `execute: false` is set
+ *
  * 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 { OpenRouter, tool } from "../src/index.js";
 import z from "zod";
 
 const openRouter = new OpenRouter({
   apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
 });
 
-// Create a typed tool using createTool
+// Create a typed regular tool using tool()
 // The execute function params are automatically typed as z.infer<typeof inputSchema>
 // The return type is enforced based on outputSchema
-const weatherTool = createTool({
+const weatherTool = tool({
   name: "get_weather",
   description: "Get the current weather for a location",
   inputSchema: z.object({
@@ -43,9 +48,9 @@ const weatherTool = createTool({
   },
 });
 
-// Create a generator tool with typed progress events
-// The eventSchema defines the type of events yielded during execution
-const searchTool = createGeneratorTool({
+// Create a generator tool with typed progress events by providing eventSchema
+// The eventSchema triggers generator mode - execute becomes an async generator
+const searchTool = tool({
   name: "search_database",
   description: "Search database with progress updates",
   inputSchema: z.object({

src/index.ts

@@ -10,6 +10,8 @@ export * from "./sdk/sdk.js";
 
 // Tool creation helpers
 export {
+  tool,
+  // Deprecated - kept for backwards compatibility
   createTool,
   createGeneratorTool,
   createManualTool,