feat: add async function support and nextTurnParams for dynamic parameter control. Also dynamic run stoppage

[mattapperson]

Summary

This PR adds powerful features for dynamic parameter control and intelligent stopping conditions during multi-turn conversations:

1. Async Function Support for CallModelInput

All API parameter fields in CallModelInput can now be async functions that compute values dynamically based on conversation context:

const result = openrouter.callModel({
  // set any parameter as static or a computed value
  temperature: 1,
  // Switch models based on conversation length
  model: (ctx) => ctx.numberOfTurns > 3 ? 'gpt-4' : 'gpt-3.5-turbo',
  
  // Async functions supported too
  instructions: async (ctx) => {
    const prefs = await fetchUserPreferences();
    return `You are a helpful assistant. User preferences: ${prefs}`;
  },
  
  input: [{ type: 'text', text: 'Hello' }],
});

Features:

• Functions receive TurnContext with numberOfTurns, messageHistory, model, models
• Resolved before EVERY turn (initial request + each tool execution round)
• Fully type-safe with TypeScript
• Backward compatible (accepts both static values and functions)

2. NextTurnParams for Tool-Driven Parameter Updates

Tools can now influence subsequent conversation turns using the nextTurnParams option:

const searchTool = tool({
  name: 'search',
  description: 'Search the web',
  parameters: z.object({ query: z.string() }),
  nextTurnParams: {
    // Increase temperature after search for more creative responses
    temperature: (params, ctx) => (ctx.temperature ?? 0.7) + 0.2,
      
    // Add search results to instructions
    instructions: (params, ctx) => 
        `${ctx.instructions ?? ''}\n\nSearch context: User searched for "${params.query}"`,
  },
  execute: async ({ query }) => {
    return await performSearch(query);
  },
});

Features:

• Functions receive tool call parameters and current context
• Multiple tools can modify the same parameter (composed in order)
• Runs after async functions and before API request
• Type-safe with full TypeScript support

3. StopWhen - Intelligent Execution Control

Fine-grained control over when tool execution should stop using flexible stop conditions:

import { stepCountIs, hasToolCall, maxTokensUsed, maxCost } from '@openrouter/sdk';

const result = openrouter.callModel({
  model: 'openai/gpt-4o',
  input: 'Process this complex task',
  tools: [myTool],
  
  // Use built-in helpers
  stopWhen: stepCountIs(5), // Stop after 5 steps
  
  // Or combine multiple conditions (OR logic)
  stopWhen: [
    stepCountIs(10),           // Stop after 10 steps
    hasToolCall('final_answer'), // Stop when final_answer tool is called
    maxTokensUsed(50000),      // Stop when 50k tokens used
    maxCost(1.00),             // Stop when $1.00 spent
  ],
  
  // Or write custom conditions
  stopWhen: ({ steps }) => {
    const hasError = steps.some(s => s.finishReason === 'error');
    return hasError || steps.length >= 20;
  },
});

Built-in Helpers:

• stepCountIs(n) - Stop after N conversation turns
• hasToolCall(name) - Stop when a specific tool is called
• maxTokensUsed(n) - Stop when token usage exceeds threshold
• maxCost(dollars) - Stop when cost exceeds budget
• finishReasonIs(reason) - Stop on specific finish reasons

Custom Conditions:

• Write your own: ({ steps }) => boolean
• Access full step history with usage, cost, and tool call data
• Async conditions supported
• OR logic when using array (stops if ANY condition is true)

Execution Order

Each turn follows this order:

1. Async functions - Resolve dynamic parameter values
2. API request - Send to API with computed values
3. Tool execution - Execute tools called by the model
4. StopWhen check - Evaluate whether to continue
5. nextTurnParams - Apply tool-driven parameter updates
6. Repeat - Continue until stopWhen returns true or no more tool calls

Documentation

• Added comprehensive JSDoc with examples to callModel()
• Type definitions include inline documentation
• New helper functions exported from main index

Related Issues

Implements dynamic parameter control and intelligent stopping conditions for adaptive multi-turn conversations.