type cleanup and cruft removal

Author: mattapperson

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

@@ -98,7 +98,7 @@ async function main() {
     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
+    stopWhen: ({ steps }) => steps.length >= 0, // Stop immediately - don't auto-execute, just get the tool calls
   });
 
   // Tool calls are now typed based on the tool definitions!
@@ -117,7 +117,7 @@ async function main() {
     model: "openai/gpt-4o-mini",
     input: "What's the weather in Tokyo?",
     tools: [weatherTool] as const,
-    maxToolRounds: 0,
+    stopWhen: ({ steps }) => steps.length >= 0, // Stop immediately
   });
 
   // Stream tool calls with typed arguments

examples/tools-example.ts

@@ -6,22 +6,20 @@
  * 1. Validated using Zod schemas
  * 2. Executed when the model calls them
  * 3. Results sent back to the model
- * 4. Process repeats until no more tool calls (up to maxToolRounds)
+ * 4. Process repeats until stopWhen condition is met (default: stepCountIs(5))
  *
  * The API is simple: just call callModel() with tools, and await the result.
  * Tools are executed transparently before getMessage() or getText() returns!
  *
- * maxToolRounds can be:
- * - A number: Maximum number of tool execution rounds (default: 5)
- * - A function: (context: TurnContext) => boolean
- *   - Return true to allow another turn
- *   - Return false to stop execution
- *   - Context includes: numberOfTurns, messageHistory, model/models
+ * stopWhen can be:
+ * - A single condition: stepCountIs(3), hasToolCall('finalize'), maxCost(0.50)
+ * - An array of conditions: [stepCountIs(10), maxCost(1.00)] (OR logic - stops if ANY is true)
+ * - A custom function: ({ steps }) => steps.length >= 5 || steps.some(s => s.finishReason === 'length')
  */
 
 import * as dotenv from 'dotenv';
 import { z } from 'zod/v4';
-import { OpenRouter, ToolType } from '../src/index.js';
+import { OpenRouter, ToolType, stepCountIs } from '../src/index.js';
 
 // Type declaration for ShadowRealm (TC39 Stage 3 proposal)
 // See: https://tc39.es/proposal-shadowrealm/
@@ -78,10 +76,8 @@ async function basicToolExample() {
     tools: [
       weatherTool,
     ],
-    // Example: limit to 3 turns using a function
-    maxToolRounds: (context) => {
-      return context.numberOfTurns < 3; // Allow up to 3 turns
-    },
+    // Example: limit to 3 steps
+    stopWhen: stepCountIs(3),
   });
 
   // Tools are automatically executed! Just get the final message

src/funcs/call-model.ts

@@ -144,6 +144,8 @@ export function callModel<TOOLS extends readonly Tool[] = readonly Tool[]>(
     client,
     request: finalRequest,
     options: options ?? {},
+    // Cast to Tool[] because ModelResult expects mutable array internally
+    // The readonly constraint is maintained at the callModel interface level
     tools: (tools ?? []) as Tool[],
     ...(stopWhen !== undefined && {
       stopWhen,

src/lib/async-params.ts

@@ -37,7 +37,6 @@ export type CallModelInput<TOOLS extends readonly Tool[] = readonly Tool[]> = {
  */
 export type ResolvedCallModelInput = Omit<models.OpenResponsesRequest, 'stream' | 'tools'> & {
   tools?: never;
-  maxToolRounds?: never;
 };
 
 /**
@@ -77,8 +76,9 @@ export async function resolveAsyncFunctions(
     if (typeof value === 'function') {
       try {
         // Execute the function with context and store the result
-        // Type guard ensures value is a function
-        const fn = value as (context: TurnContext) => unknown;
+        // We've already filtered out stopWhen at line 73, so this is a parameter function
+        // that accepts TurnContext (not a StopCondition which needs steps)
+        const fn = value as (context: TurnContext) => unknown | Promise<unknown>;
         const result = await Promise.resolve(fn(context));
         resolvedEntries.push([key, result] as const);
       } catch (error) {
@@ -95,8 +95,9 @@ export async function resolveAsyncFunctions(
   }
 
   // Use type-safe fromEntries - the result type is inferred from the entries
-  // We still need the final cast to ResolvedCallModelInput because TypeScript can't prove
-  // that the dynamic keys match the static type, but this is safer than before
+  // TypeScript can't prove that dynamic keys match the static type at compile time,
+  // but we know all keys come from the input object (minus stopWhen/tools)
+  // and all values are properly resolved through the function above
   return typeSafeObjectFromEntries(resolvedEntries) as ResolvedCallModelInput;
 }
 

src/lib/model-result.ts

@@ -6,7 +6,6 @@ import type { RequestOptions } from './sdks.js';
 import type {
   ChatStreamEvent,
   EnhancedResponseStreamEvent,
-  MaxToolRounds,
   ParsedToolCall,
   Tool,
   ToolStreamEvent,
@@ -90,7 +89,6 @@ export interface GetResponseOptions {
   client: OpenRouterCore;
   options?: RequestOptions;
   tools?: Tool[];
-  maxToolRounds?: MaxToolRounds;
 }
 
 /**
@@ -159,7 +157,7 @@ export class ModelResult {
       // Build initial turn context (turn 0 for initial request)
       const initialContext: TurnContext = {
         numberOfTurns: 0,
-        messageHistory: [],
+        input: [],
         model: undefined,
         models: undefined,
       };
@@ -248,9 +246,6 @@ export class ModelResult {
         return;
       }
 
-      // Get maxToolRounds configuration
-      const maxToolRounds = this.options.maxToolRounds ?? 5;
-
       let currentResponse = initialResponse;
       let currentRound = 0;
       let currentInput: models.OpenResponsesInput =
@@ -272,30 +267,6 @@ export class ModelResult {
           break;
         }
 
-        // Check if we should continue based on maxToolRounds
-        if (typeof maxToolRounds === 'number') {
-          if (currentRound >= maxToolRounds) {
-            break;
-          }
-        } else if (typeof maxToolRounds === 'function') {
-          // Function signature: (context: TurnContext) => boolean
-          const resolvedRequest = this.options.request as models.OpenResponsesRequest;
-          const turnContext: TurnContext = {
-            numberOfTurns: currentRound + 1,
-            messageHistory: currentInput,
-            ...(resolvedRequest.model && {
-              model: resolvedRequest.model,
-            }),
-            ...(resolvedRequest.models && {
-              models: resolvedRequest.models,
-            }),
-          };
-          const shouldContinue = maxToolRounds(turnContext);
-          if (!shouldContinue) {
-            break;
-          }
-        }
-
         // Store execution round info
         this.allToolExecutionRounds.push({
           round: currentRound,
@@ -307,7 +278,7 @@ export class ModelResult {
         const resolvedRequest = this.options.request as models.OpenResponsesRequest;
         const turnContext: TurnContext = {
           numberOfTurns: currentRound + 1, // 1-indexed
-          messageHistory: currentInput,
+          input: currentInput,
           ...(resolvedRequest.model && {
             model: resolvedRequest.model,
           }),
@@ -348,8 +319,8 @@ export class ModelResult {
             callId: toolCall.id,
             output: result.error
               ? JSON.stringify({
-                  error: result.error.message,
-                })
+                error: result.error.message,
+              })
               : JSON.stringify(result.result),
           });
         }
@@ -377,8 +348,8 @@ export class ModelResult {
           ...(Array.isArray(currentResponse.output)
             ? currentResponse.output
             : [
-                currentResponse.output,
-              ]),
+              currentResponse.output,
+            ]),
           ...toolResults,
         ];
 

src/lib/next-turn-params.ts

@@ -25,7 +25,7 @@ export function buildNextTurnParamsContext(
     temperature: request.temperature ?? null,
     maxOutputTokens: request.maxOutputTokens ?? null,
     topP: request.topP ?? null,
-    topK: request.topK ?? 0,
+    topK: request.topK,
     instructions: request.instructions ?? null,
   };
 }
@@ -66,13 +66,16 @@ export async function executeNextTurnParamsFunctions(
 
       // Validate that call.arguments is a record using type guard
       if (!isRecord(call.arguments)) {
+        const typeStr = Array.isArray(call.arguments)
+          ? 'array'
+          : typeof call.arguments;
         throw new Error(
-          `Tool call arguments for ${tool.function.name} must be an object, got ${typeof call.arguments}`
+          `Tool call arguments for ${tool.function.name} must be an object, got ${typeStr}`
         );
       }
 
       // Process each parameter key with proper typing
-      await processNextTurnParamsForCall(nextParams, call.arguments, workingContext, result);
+      await processNextTurnParamsForCall(nextParams, call.arguments, workingContext, result, tool.function.name);
     }
   }
 
@@ -86,7 +89,8 @@ async function processNextTurnParamsForCall(
   nextParams: Record<string, unknown>,
   params: Record<string, unknown>,
   workingContext: NextTurnParamsContext,
-  result: Partial<NextTurnParamsContext>
+  result: Partial<NextTurnParamsContext>,
+  toolName: string
 ): Promise<void> {
   // Type-safe processing for each known parameter key
   // We iterate through keys and use runtime checks instead of casts
@@ -99,15 +103,20 @@ async function processNextTurnParamsForCall(
 
     // Validate that paramKey is actually a key of NextTurnParamsContext
     if (!isValidNextTurnParamKey(paramKey)) {
-      // Skip invalid keys silently - they're not part of the API
+      console.warn(
+        `Invalid nextTurnParams key "${paramKey}" in tool "${toolName}". ` +
+        `Valid keys: input, model, models, temperature, maxOutputTokens, topP, topK, instructions`
+      );
       continue;
     }
 
     // Execute the function and await the result
     const newValue = await Promise.resolve(fn(params, workingContext));
 
-    // Update the result using type-safe assignment
+    // Update both result and workingContext to enable composition
+    // Later tools will see modifications made by earlier tools
     setNextTurnParam(result, paramKey, newValue);
+    setNextTurnParam(workingContext, paramKey, newValue);
   }
 }
 
@@ -130,7 +139,8 @@ function isValidNextTurnParamKey(key: string): key is keyof NextTurnParamsContex
 
 /**
  * Type-safe setter for NextTurnParamsContext
- * Ensures the value type matches the key type
+ * This wrapper is needed because TypeScript doesn't properly narrow the type
+ * after the type guard, even though we've validated the key
  */
 function setNextTurnParam<K extends keyof NextTurnParamsContext>(
   target: Partial<NextTurnParamsContext>,

src/lib/reusable-stream.ts

@@ -83,26 +83,27 @@ export class ReusableReadableStream<T> {
           throw self.sourceError;
         }
 
-        // Wait for more data - but check conditions after setting up the promise
-        // to avoid race condition where source completes between check and wait
+        // Set up the waiting promise FIRST to avoid race condition
+        // where source completes after the check but before promise is set
         const waitPromise = new Promise<void>((resolve, reject) => {
           consumer.waitingPromise = {
             resolve,
             reject,
           };
-        });
 
-        // Double-check conditions after setting up promise to handle race
-        if (self.sourceComplete || self.sourceError || consumer.position < self.buffer.length) {
-          // Resolve immediately if conditions changed
-          if (consumer.waitingPromise) {
-            consumer.waitingPromise.resolve();
-            consumer.waitingPromise = null;
+          // Immediately check if we should resolve after setting up the promise
+          // This handles the case where data arrived or source completed
+          // between our initial checks and promise creation
+          if (self.sourceComplete || self.sourceError || consumer.position < self.buffer.length) {
+            resolve();
           }
-        }
+        });
 
         await waitPromise;
 
+        // Clear the promise reference after it resolves
+        consumer.waitingPromise = null;
+
         // Recursively try again after waking up
         return this.next();
       },

src/lib/stop-conditions.ts

@@ -79,7 +79,7 @@ export async function isStopConditionMet<TOOLS extends readonly Tool[]>(options:
  * stopWhen: maxTokensUsed(10000) // Stop when total tokens exceed 10,000
  * ```
  */
-export function maxTokensUsed(maxTokens: number): StopCondition<any> {
+export function maxTokensUsed(maxTokens: number): StopCondition {
   return ({ steps }: { readonly steps: ReadonlyArray<StepResult> }) => {
     const totalTokens = steps.reduce(
       (sum: number, step: StepResult) => sum + (step.usage?.totalTokens ?? 0),

src/lib/stream-transformers.ts

@@ -364,7 +364,12 @@ export function extractToolCallsFromResponse(
           name: functionCallItem.name,
           arguments: parsedArguments,
         });
-      } catch (_error) {
+      } catch (error) {
+        console.warn(
+          `Failed to parse tool call arguments for ${functionCallItem.name}:`,
+          error instanceof Error ? error.message : String(error),
+          `\nArguments: ${functionCallItem.arguments.substring(0, 100)}${functionCallItem.arguments.length > 100 ? '...' : ''}`
+        );
         // Include the tool call with unparsed arguments
         toolCalls.push({
           id: functionCallItem.callId,
@@ -439,7 +444,12 @@ export async function* buildToolCallStream(
               name: doneEvent.name,
               arguments: parsedArguments,
             };
-          } catch (_error) {
+          } catch (error) {
+            console.warn(
+              `Failed to parse tool call arguments for ${doneEvent.name}:`,
+              error instanceof Error ? error.message : String(error),
+              `\nArguments: ${doneEvent.arguments.substring(0, 100)}${doneEvent.arguments.length > 100 ? '...' : ''}`
+            );
             // Yield with unparsed arguments if parsing fails
             yield {
               id: toolCall.id,
@@ -557,10 +567,11 @@ function mapAnnotationsToCitations(
       default: {
         // Exhaustiveness check - TypeScript will error if we don't handle all annotation types
         const exhaustiveCheck: never = annotation;
+        // Cast to unknown for runtime debugging if type system bypassed
         // This should never execute - throw with JSON of the unhandled value
         throw new Error(
           `Unhandled annotation type. This indicates a new annotation type was added. ` +
-          `Annotation: ${JSON.stringify(exhaustiveCheck)}`
+          `Annotation: ${JSON.stringify(exhaustiveCheck as unknown)}`
         );
       }
     }
@@ -683,12 +694,12 @@ export function convertToClaudeMessage(
         try {
           parsedInput = JSON.parse(fnCall.arguments);
         } catch (error) {
+          console.warn(
+            `Failed to parse tool call arguments for ${fnCall.name}:`,
+            error instanceof Error ? error.message : String(error),
+            `\nArguments: ${fnCall.arguments.substring(0, 100)}${fnCall.arguments.length > 100 ? '...' : ''}`
+          );
           // Preserve raw arguments if JSON parsing fails
-          // Log warning in development/debug environments
-          if (typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development') {
-            // biome-ignore lint/suspicious/noConsole: needed for debugging in development
-            console.warn(`Failed to parse tool call arguments for ${fnCall.name}:`, error);
-          }
           parsedInput = {
             _raw_arguments: fnCall.arguments,
           };