feat: Multi-turn conversation state management with type safety (#124)

## Summary

- Add multi-turn conversation state management with `StateAccessor`
pattern for pluggable persistence
- Add approval workflow for tool execution (`requireApproval`,
`approveToolCalls`, `rejectToolCalls`)
- Improve type safety by replacing type casts with type guards
- Refactor `executeToolsIfNeeded` from ~400 lines to ~110 lines by
extracting 14 focused helper methods

## Key Changes

### New State Management Features
- `StateAccessor` interface for pluggable state persistence (in-memory,
database, etc.)
- `ConversationState` type for tracking conversation status, messages,
pending approvals
- `createInitialState()`, `updateState()` utilities for state management
- Support for interruption handling and resumption

### Approval Workflow
- Tools can specify `requireApproval: true` to pause execution
- Call-level `requireApproval` function for dynamic approval logic
- `approveToolCalls` and `rejectToolCalls` arrays to resume with
decisions
- `getPendingToolCalls()` and `requiresApproval()` methods on
`ModelResult`

### Type Safety Improvements
- Type guards (`isValidUnsentToolResult`, `isValidParsedToolCall`)
instead of type casts
- Made `resolveAsyncFunctions` generic to eliminate double-casting
- `isEventStream` type guard handles both streaming and non-streaming
responses

## Examples

### Basic State Management

```typescript
import { callModel, type ConversationState, type StateAccessor } from '@openrouter/sdk';

// In-memory state storage (use database in production)
const conversations = new Map<string, ConversationState>();

const stateAccessor: StateAccessor = {
  load: async () => conversations.get('conv-123') ?? null,
  save: async (state) => { conversations.set('conv-123', state); },
};

const result = client.callModel({
  model: 'anthropic/claude-sonnet-4',
  input: [{ type: 'text', text: 'Hello!' }],
  state: stateAccessor,
});

const text = await result.getText();
const state = await result.getState(); // Access conversation state
```

### Tool with Approval Required

```typescript
import { tool } from '@openrouter/sdk';

const deleteFileTool = tool({
  name: 'delete_file',
  description: 'Delete a file from the filesystem',
  inputSchema: z.object({
    path: z.string().describe('File path to delete'),
  }),
  outputSchema: z.object({ success: z.boolean() }),
  requireApproval: true, // Pause for human approval
  execute: async ({ path }) => {
    await fs.unlink(path);
    return { success: true };
  },
});

const result = client.callModel({
  model: 'anthropic/claude-sonnet-4',
  input: [{ type: 'text', text: 'Delete the temp.txt file' }],
  tools: [deleteFileTool],
  state: stateAccessor,
});

// Check if approval is needed
if (await result.requiresApproval()) {
  const pending = await result.getPendingToolCalls();
  console.log('Pending approval:', pending);
  // Show to user, get decision...
}
```

### Resume with Approval Decision

```typescript
// After user approves/rejects...
const result = client.callModel({
  model: 'anthropic/claude-sonnet-4',
  input: [], // Empty - resuming from state
  tools: [deleteFileTool],
  state: stateAccessor,
  approveToolCalls: ['call_abc123'],  // Approve specific tool calls
  rejectToolCalls: ['call_def456'],   // Reject others
});

const text = await result.getText(); // Continues execution
```

### Dynamic Approval Logic

```typescript
const result = client.callModel({
  model: 'anthropic/claude-sonnet-4',
  input: [{ type: 'text', text: 'Process these files' }],
  tools: [readFileTool, writeFileTool, deleteFileTool],
  state: stateAccessor,
  // Dynamic approval based on tool and context
  requireApproval: (toolCall, context) => {
    // Always approve read operations
    if (toolCall.name === 'read_file') return false;
    // Require approval for destructive operations
    if (toolCall.name === 'delete_file') return true;
    // Require approval after 3 turns
    return context.numberOfTurns > 3;
  },
});
```

### Stop Conditions

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

const result = client.callModel({
  model: 'anthropic/claude-sonnet-4',
  input: [{ type: 'text', text: 'Research this topic thoroughly' }],
  tools: [searchTool, summarizeTool],
  // Stop when any condition is met
  stopWhen: [
    stepCountIs(10),           // Max 10 tool execution rounds
    hasToolCall('summarize'),  // Stop when summarize is called
    maxCost(0.50),             // Budget limit
  ],
});
```

## Test plan

- [x] All 320 existing tests pass
- [x] New unit tests for conversation state utilities (21 tests)
- [x] New E2E tests for state management integration (5 tests)
- [x] Build passes with no TypeScript errors
- [x] Lint passes with no warnings

Author: mattapperson

src/funcs/call-model.ts

@@ -124,7 +124,16 @@ export function callModel<TTools extends readonly Tool[]>(
   request: CallModelInput<TTools>,
   options?: RequestOptions,
 ): ModelResult<TTools> {
-  const { tools, stopWhen, ...apiRequest } = request;
+  // Destructure state management options along with tools and stopWhen
+  const {
+    tools,
+    stopWhen,
+    state,
+    requireApproval,
+    approveToolCalls,
+    rejectToolCalls,
+    ...apiRequest
+  } = request;
 
   // Convert tools to API format - no cast needed now that convertToolsToAPIFormat accepts readonly
   const apiTools = tools ? convertToolsToAPIFormat(tools) : undefined;
@@ -144,10 +153,12 @@ export function callModel<TTools extends readonly Tool[]>(
     client,
     request: finalRequest,
     options: options ?? {},
-    // Preserve the exact TTools type instead of widening to Tool[]
-    tools: tools as TTools | undefined,
-    ...(stopWhen !== undefined && {
-      stopWhen,
-    }),
+    tools,
+    ...(stopWhen !== undefined && { stopWhen }),
+    // Pass state management options
+    ...(state !== undefined && { state }),
+    ...(requireApproval !== undefined && { requireApproval }),
+    ...(approveToolCalls !== undefined && { approveToolCalls }),
+    ...(rejectToolCalls !== undefined && { rejectToolCalls }),
   } as GetResponseOptions<TTools>);
 }

src/index.ts

@@ -5,14 +5,18 @@
 // Async params support
 export type {
   CallModelInput,
+  CallModelInputWithState,
   FieldOrAsyncFunction,
   ResolvedCallModelInput,
 } from './lib/async-params.js';
 export type { Fetcher, HTTPClientOptions } from './lib/http.js';
 // Tool types
 export type {
   ChatStreamEvent,
+  ConversationState,
+  ConversationStatus,
   ResponseStreamEvent as EnhancedResponseStreamEvent,
+  HasApprovalTools,
   InferToolEvent,
   InferToolEventsUnion,
   InferToolInput,
@@ -21,19 +25,24 @@ export type {
   NextTurnParamsContext,
   NextTurnParamsFunctions,
   ParsedToolCall,
+  PartialResponse,
+  StateAccessor,
   StepResult,
   StopCondition,
   StopWhen,
   Tool,
+  ToolApprovalCheck,
   ToolExecutionResult,
   ToolExecutionResultUnion,
+  ToolHasApproval,
   ToolPreliminaryResultEvent,
   ToolStreamEvent,
   ToolWithExecute,
   ToolWithGenerator,
   TurnContext,
   TypedToolCall,
   TypedToolCallUnion,
+  UnsentToolResult,
   Warning,
 } from './lib/tool-types.js';
 export type { BuildTurnContextOptions } from './lib/turn-context.js';
@@ -101,14 +110,27 @@ export {
 // Tool creation helpers
 export { tool } from './lib/tool.js';
 export {
+  hasApprovalRequiredTools,
   hasExecuteFunction,
   isGeneratorTool,
   isRegularExecuteTool,
   isToolPreliminaryResultEvent,
+  toolHasApprovalConfigured,
   ToolType,
 } from './lib/tool-types.js';
 // Turn context helpers
 export { buildTurnContext, normalizeInputToArray } from './lib/turn-context.js';
+// Conversation state helpers
+export {
+  appendToMessages,
+  createInitialState,
+  createRejectedResult,
+  createUnsentResult,
+  generateConversationId,
+  partitionToolCalls,
+  toolRequiresApproval,
+  updateState,
+} from './lib/conversation-state.js';
 // Real-time tool event broadcasting
 export { ToolEventBroadcaster } from './lib/tool-event-broadcaster.js';
 export * from './sdk/sdk.js';

src/lib/async-params.ts

@@ -1,5 +1,8 @@
 import type * as models from '../models/index.js';
-import type { StopWhen, Tool, TurnContext } from './tool-types.js';
+import type { ParsedToolCall, StateAccessor, StopWhen, Tool, TurnContext } from './tool-types.js';
+
+// Re-export Tool type for convenience
+export type { Tool } from './tool-types.js';
 
 /**
  * Type guard to check if a value is a parameter function
@@ -29,19 +32,67 @@ function buildResolvedRequest(
 export type FieldOrAsyncFunction<T> = T | ((context: TurnContext) => T | Promise<T>);
 
 /**
- * Input type for callModel function
- * Each field can independently be a static value or a function that computes the value
- * Generic over TTools to enable proper type inference for stopWhen conditions
+ * Base input type for callModel without approval-related fields
  */
-export type CallModelInput<TTools extends readonly Tool[] = readonly Tool[]> = {
+type BaseCallModelInput<TTools extends readonly Tool[] = readonly Tool[]> = {
   [K in keyof Omit<models.OpenResponsesRequest, 'stream' | 'tools'>]?: FieldOrAsyncFunction<
     models.OpenResponsesRequest[K]
   >;
 } & {
   tools?: TTools;
   stopWhen?: StopWhen<TTools>;
+  /**
+   * Call-level approval check - overrides tool-level requireApproval setting
+   * Receives the tool call and turn context, can be sync or async
+   */
+  requireApproval?: (
+    toolCall: ParsedToolCall<TTools[number]>,
+    context: TurnContext
+  ) => boolean | Promise<boolean>;
+};
+
+/**
+ * Approval params when state is provided (allows approve/reject)
+ */
+type ApprovalParamsWithState<TTools extends readonly Tool[] = readonly Tool[]> = {
+  /** State accessor for multi-turn persistence and approval gates */
+  state: StateAccessor<TTools>;
+  /** Tool call IDs to approve (for resuming from awaiting_approval status) */
+  approveToolCalls?: string[];
+  /** Tool call IDs to reject (for resuming from awaiting_approval status) */
+  rejectToolCalls?: string[];
+};
+
+/**
+ * Approval params when state is NOT provided (forbids approve/reject)
+ */
+type ApprovalParamsWithoutState = {
+  /** State accessor for multi-turn persistence and approval gates */
+  state?: undefined;
+  /** Not allowed without state - will cause type error */
+  approveToolCalls?: never;
+  /** Not allowed without state - will cause type error */
+  rejectToolCalls?: never;
 };
 
+/**
+ * Input type for callModel function
+ * Each field can independently be a static value or a function that computes the value
+ * Generic over TTools to enable proper type inference for stopWhen conditions
+ *
+ * Type enforcement:
+ * - `approveToolCalls` and `rejectToolCalls` are only valid when `state` is provided
+ * - Using these without `state` will cause a TypeScript error
+ */
+export type CallModelInput<TTools extends readonly Tool[] = readonly Tool[]> =
+  BaseCallModelInput<TTools> & (ApprovalParamsWithState<TTools> | ApprovalParamsWithoutState);
+
+/**
+ * CallModelInput variant that requires state - use when approval workflows are needed
+ */
+export type CallModelInputWithState<TTools extends readonly Tool[] = readonly Tool[]> =
+  BaseCallModelInput<TTools> & ApprovalParamsWithState<TTools>;
+
 /**
  * Resolved CallModelInput (all functions evaluated to values)
  * This is the type after all async functions have been resolved to their values
@@ -70,8 +121,8 @@ export type ResolvedCallModelInput = Omit<models.OpenResponsesRequest, 'stream'
  * // resolved.temperature === 0.2
  * ```
  */
-export async function resolveAsyncFunctions(
-  input: CallModelInput,
+export async function resolveAsyncFunctions<TTools extends readonly Tool[] = readonly Tool[]>(
+  input: CallModelInput<TTools>,
   context: TurnContext,
 ): Promise<ResolvedCallModelInput> {
   // Build array of resolved entries