feat: add nextTurnParams feature for dynamic conversation steering

Implements configuration-based nextTurnParams allowing tools to influence
subsequent conversation turns by modifying request parameters.

Key features:
- Tools can specify nextTurnParams functions in their configuration
- Functions receive tool input params and current request state
- Multiple tools' params compose in tools array order
- Support for modifying input, model, temperature, and other parameters

New files:
- src/lib/claude-constants.ts - Claude-specific content type constants
- src/lib/claude-type-guards.ts - Type guards for Claude message format
- src/lib/next-turn-params.ts - NextTurnParams execution logic
- src/lib/turn-context.ts - Turn context building helpers

Updates:
- src/lib/tool-types.ts - Add NextTurnParamsContext and NextTurnParamsFunctions
- src/lib/tool.ts - Add nextTurnParams to all tool config types
- src/lib/tool-orchestrator.ts - Execute nextTurnParams after tool execution
- src/index.ts - Export new types and functions

Author: mattapperson

src/index.ts

@@ -61,6 +61,9 @@ export type {
   ChatStreamEvent,
   EnhancedResponseStreamEvent,
   ToolPreliminaryResultEvent,
+  NextTurnParamsContext,
+  NextTurnParamsFunctions,
+  ToolCallInfo,
 } from "./lib/tool-types.js";
 
 export {
@@ -70,3 +73,18 @@ export {
   isRegularExecuteTool,
   isToolPreliminaryResultEvent,
 } from "./lib/tool-types.js";
+
+// Turn context helpers
+export { buildTurnContext, normalizeInputToArray } from "./lib/turn-context.js";
+export type { BuildTurnContextOptions } from "./lib/turn-context.js";
+
+// Next turn params helpers
+export {
+  buildNextTurnParamsContext,
+  executeNextTurnParamsFunctions,
+  applyNextTurnParamsToRequest,
+} from "./lib/next-turn-params.js";
+
+// Claude constants and type guards
+export { ClaudeContentBlockType, NonClaudeMessageRole } from "./lib/claude-constants.js";
+export { isClaudeStyleMessages } from "./lib/claude-type-guards.js";

src/lib/claude-constants.ts

@@ -0,0 +1,26 @@
+/**
+ * Claude-specific content block types
+ * Used for detecting Claude message format
+ */
+export const ClaudeContentBlockType = {
+  Text: "text",
+  Image: "image",
+  ToolUse: "tool_use",
+  ToolResult: "tool_result",
+} as const;
+
+export type ClaudeContentBlockType =
+  (typeof ClaudeContentBlockType)[keyof typeof ClaudeContentBlockType];
+
+/**
+ * Message roles that are NOT supported in Claude format
+ * Used for distinguishing Claude vs OpenAI format
+ */
+export const NonClaudeMessageRole = {
+  System: "system",
+  Developer: "developer",
+  Tool: "tool",
+} as const;
+
+export type NonClaudeMessageRole =
+  (typeof NonClaudeMessageRole)[keyof typeof NonClaudeMessageRole];

src/lib/claude-type-guards.ts

@@ -0,0 +1,83 @@
+import type * as models from "../models/index.js";
+import {
+  ClaudeContentBlockType,
+  NonClaudeMessageRole,
+} from "./claude-constants.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonClaudeRole(role: unknown): boolean {
+  return (
+    role === NonClaudeMessageRole.System ||
+    role === NonClaudeMessageRole.Developer ||
+    role === NonClaudeMessageRole.Tool
+  );
+}
+
+function isClaudeToolResultBlock(block: unknown): boolean {
+  if (!isRecord(block)) return false;
+  return block["type"] === ClaudeContentBlockType.ToolResult;
+}
+
+function isClaudeImageBlockWithSource(block: unknown): boolean {
+  if (!isRecord(block)) return false;
+  return (
+    block["type"] === ClaudeContentBlockType.Image &&
+    "source" in block &&
+    isRecord(block["source"])
+  );
+}
+
+function isClaudeToolUseBlockWithId(block: unknown): boolean {
+  if (!isRecord(block)) return false;
+  return (
+    block["type"] === ClaudeContentBlockType.ToolUse &&
+    "id" in block &&
+    typeof block["id"] === "string"
+  );
+}
+
+function hasClaudeSpecificBlocks(content: unknown[]): boolean {
+  for (const block of content) {
+    if (isClaudeToolResultBlock(block)) return true;
+    if (isClaudeImageBlockWithSource(block)) return true;
+    if (isClaudeToolUseBlockWithId(block)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if input is in Claude message format
+ * Uses structural analysis to detect Claude-specific patterns
+ *
+ * @param input - Input to check
+ * @returns True if input appears to be Claude format
+ */
+export function isClaudeStyleMessages(
+  input: unknown
+): input is models.ClaudeMessageParam[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    return false;
+  }
+
+  for (const msg of input) {
+    if (!isRecord(msg)) continue;
+    if (!("role" in msg)) continue;
+    if ("type" in msg) continue; // Claude messages don't have top-level "type"
+
+    // If we find a non-Claude role, it's not Claude format
+    if (isNonClaudeRole(msg["role"])) {
+      return false;
+    }
+
+    // If we find Claude-specific content blocks, it's Claude format
+    const content = msg["content"];
+    if (Array.isArray(content) && hasClaudeSpecificBlocks(content)) {
+      return true;
+    }
+  }
+
+  return false;
+}

src/lib/next-turn-params.ts

@@ -0,0 +1,110 @@
+import type * as models from '../models/index.js';
+import type { NextTurnParamsContext, ParsedToolCall, Tool } from './tool-types.js';
+
+/**
+ * Build a NextTurnParamsContext from the current request
+ * Extracts relevant fields that can be modified by nextTurnParams functions
+ *
+ * @param request - The current OpenResponsesRequest
+ * @returns Context object with current parameter values
+ */
+export function buildNextTurnParamsContext(
+  request: models.OpenResponsesRequest
+): NextTurnParamsContext {
+  return {
+    input: request.input ?? [],
+    model: request.model ?? '',
+    models: request.models ?? [],
+    temperature: request.temperature ?? null,
+    maxOutputTokens: request.maxOutputTokens ?? null,
+    topP: request.topP ?? null,
+    topK: request.topK ?? 0,
+    instructions: request.instructions ?? null,
+  };
+}
+
+/**
+ * Execute nextTurnParams functions for all called tools
+ * Composes functions when multiple tools modify the same parameter
+ *
+ * @param toolCalls - Tool calls that were executed in this turn
+ * @param tools - All available tools
+ * @param currentRequest - The current request
+ * @returns Object with computed parameter values
+ */
+export async function executeNextTurnParamsFunctions(
+  toolCalls: ParsedToolCall[],
+  tools: Tool[],
+  currentRequest: models.OpenResponsesRequest
+): Promise<Partial<NextTurnParamsContext>> {
+  // Build initial context from current request
+  const context = buildNextTurnParamsContext(currentRequest);
+
+  // Group tool calls by parameter they modify
+  const paramFunctions = new Map<
+    keyof NextTurnParamsContext,
+    Array<{ params: unknown; fn: Function }>
+  >();
+
+  // Collect all nextTurnParams functions from tools (in tools array order)
+  for (const tool of tools) {
+    if (!tool.function.nextTurnParams) continue;
+
+    // Find tool calls for this tool
+    const callsForTool = toolCalls.filter(tc => tc.name === tool.function.name);
+
+    for (const call of callsForTool) {
+      // For each parameter function in this tool's nextTurnParams
+      for (const [paramKey, fn] of Object.entries(tool.function.nextTurnParams)) {
+        if (!paramFunctions.has(paramKey as keyof NextTurnParamsContext)) {
+          paramFunctions.set(paramKey as keyof NextTurnParamsContext, []);
+        }
+        paramFunctions.get(paramKey as keyof NextTurnParamsContext)!.push({
+          params: call.arguments,
+          fn,
+        });
+      }
+    }
+  }
+
+  // Compose and execute functions for each parameter
+  const result: Partial<NextTurnParamsContext> = {};
+  let workingContext = { ...context };
+
+  for (const [paramKey, functions] of paramFunctions.entries()) {
+    // Compose all functions for this parameter
+    let currentValue = workingContext[paramKey];
+
+    for (const { params, fn } of functions) {
+      // Update context with current value
+      workingContext = { ...workingContext, [paramKey]: currentValue };
+
+      // Execute function with composition
+      currentValue = await Promise.resolve(fn(params, workingContext));
+    }
+
+    // TypeScript can't infer that paramKey corresponds to the correct value type
+    // so we use a type assertion here
+    (result as any)[paramKey] = currentValue;
+  }
+
+  return result;
+}
+
+/**
+ * Apply computed nextTurnParams to the current request
+ * Returns a new request object with updated parameters
+ *
+ * @param request - The current request
+ * @param computedParams - Computed parameter values from nextTurnParams functions
+ * @returns New request with updated parameters
+ */
+export function applyNextTurnParamsToRequest(
+  request: models.OpenResponsesRequest,
+  computedParams: Partial<NextTurnParamsContext>
+): models.OpenResponsesRequest {
+  return {
+    ...request,
+    ...computedParams,
+  };
+}

src/lib/tool-orchestrator.ts

@@ -4,6 +4,8 @@ import type { APITool, Tool, ToolExecutionResult } from './tool-types.js';
 import { extractToolCallsFromResponse, responseHasToolCalls } from './stream-transformers.js';
 import { executeTool, findToolByName } from './tool-executor.js';
 import { hasExecuteFunction } from './tool-types.js';
+import { buildTurnContext } from './turn-context.js';
+import { executeNextTurnParamsFunctions, applyNextTurnParamsToRequest } from './next-turn-params.js';
 
 /**
  * Options for tool execution
@@ -29,6 +31,7 @@ export interface ToolOrchestrationResult {
  *
  * @param sendRequest - Function to send a request and get a response
  * @param initialInput - Starting input for the conversation
+ * @param initialRequest - Full initial request with all parameters
  * @param tools - Enhanced tools with Zod schemas and execute functions
  * @param apiTools - Converted tools in API format (JSON Schema)
  * @param options - Execution options
@@ -40,6 +43,7 @@ export async function executeToolLoop(
     tools: APITool[],
   ) => Promise<models.OpenResponsesNonStreamingResponse>,
   initialInput: models.OpenResponsesInput,
+  initialRequest: models.OpenResponsesRequest,
   tools: Tool[],
   apiTools: APITool[],
   options: ToolExecutionOptions = {},
@@ -50,6 +54,7 @@ export async function executeToolLoop(
   const allResponses: models.OpenResponsesNonStreamingResponse[] = [];
   const toolExecutionResults: ToolExecutionResult[] = [];
   let conversationInput: models.OpenResponsesInput = initialInput;
+  let currentRequest: models.OpenResponsesRequest = { ...initialRequest };
 
   let currentRound = 0;
   let currentResponse: models.OpenResponsesNonStreamingResponse;
@@ -100,10 +105,12 @@ export async function executeToolLoop(
       }
 
       // Build turn context
-      const turnContext: import('./tool-types.js').TurnContext = {
+      const turnContext = buildTurnContext({
         numberOfTurns: currentRound,
         messageHistory: conversationInput,
-      };
+        model: currentRequest.model,
+        models: currentRequest.models,
+      });
 
       // Execute the tool
       return executeTool(tool, toolCall, turnContext, onPreliminaryResult);
@@ -137,10 +144,23 @@ export async function executeToolLoop(
 
     toolExecutionResults.push(...roundResults);
 
+    // Execute nextTurnParams functions for tools that were called
+    const computedParams = await executeNextTurnParamsFunctions(
+      toolCalls,
+      tools,
+      currentRequest
+    );
+
+    // Apply computed parameters to request
+    if (Object.keys(computedParams).length > 0) {
+      currentRequest = applyNextTurnParamsToRequest(currentRequest, computedParams);
+      conversationInput = currentRequest.input ?? conversationInput;
+    }
+
     // Build array input with all output from previous response plus tool results
     // The API expects continuation via previousResponseId, not by including outputs
     // For now, we'll keep the conversation going via previousResponseId
-    conversationInput = initialInput; // Keep original input
+    // conversationInput is updated above if nextTurnParams modified it
 
     // Note: The OpenRouter Responses API uses previousResponseId for continuation
     // Tool results are automatically associated with the previous response's tool calls

src/lib/tool-types.ts

@@ -20,9 +20,54 @@ export interface TurnContext {
   /** Current message history being sent to the API */
   messageHistory: models.OpenResponsesInput;
   /** Model name if request.model is set */
-  model?: string;
+  model?: string | undefined;
   /** Model names if request.models is set */
-  models?: string[];
+  models?: string[] | undefined;
+}
+
+/**
+ * Context passed to nextTurnParams functions
+ * Contains current request state for parameter computation
+ * Allows modification of key request parameters between turns
+ */
+export type NextTurnParamsContext = {
+  /** Current input (messages) */
+  input: models.OpenResponsesInput;
+  /** Current model selection */
+  model: string;
+  /** Current models array */
+  models: string[];
+  /** Current temperature */
+  temperature: number | null;
+  /** Current maxOutputTokens */
+  maxOutputTokens: number | null;
+  /** Current topP */
+  topP: number | null;
+  /** Current topK */
+  topK: number;
+  /** Current instructions */
+  instructions: string | null;
+};
+
+/**
+ * Functions to compute next turn parameters
+ * Each function receives the tool's input params and current request context
+ */
+export type NextTurnParamsFunctions<TInput> = {
+  [K in keyof NextTurnParamsContext]?: (
+    params: TInput,
+    context: NextTurnParamsContext
+  ) => NextTurnParamsContext[K] | Promise<NextTurnParamsContext[K]>;
+};
+
+/**
+ * Information about a tool call needed for nextTurnParams execution
+ */
+export interface ToolCallInfo {
+  id: string;
+  name: string;
+  arguments: unknown;
+  tool: Tool;
 }
 
 /**
@@ -32,6 +77,7 @@ export interface BaseToolFunction<TInput extends ZodObject<ZodRawShape>> {
   name: string;
   description?: string;
   inputSchema: TInput;
+  nextTurnParams?: NextTurnParamsFunctions<z.infer<TInput>>;
 }
 
 /**