feat: add multi-turn conversation state management with type safety improvements

- Add StateAccessor interface for pluggable state persistence
- Add ConversationState type with status tracking (complete, interrupted, awaiting_approval, in_progress)
- Add approval workflow support with requireApproval tool option and partitionToolCalls helper
- Add type guards (isValidUnsentToolResult, isValidParsedToolCall) to replace unsafe type assertions
- Make resolveAsyncFunctions generic over TTools to eliminate double-casting
- Fix isEventStream to check constructor name on prototype chain
- Handle both streaming and non-streaming API responses gracefully
- Add conversation-state.ts with helper functions for state management
- Add unit tests for conversation state utilities (21 tests)
- Add e2e tests for state management integration (5 tests)

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;
@@ -146,8 +155,11 @@ export function callModel<TTools extends readonly Tool[]>(
     options: options ?? {},
     // Preserve the exact TTools type instead of widening to Tool[]
     tools: tools as TTools | undefined,
-    ...(stopWhen !== undefined && {
-      stopWhen,
-    }),
+    ...(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

@@ -12,6 +12,8 @@ export type { Fetcher, HTTPClientOptions } from './lib/http.js';
 // Tool types
 export type {
   ChatStreamEvent,
+  ConversationState,
+  ConversationStatus,
   ResponseStreamEvent as EnhancedResponseStreamEvent,
   InferToolEvent,
   InferToolEventsUnion,
@@ -21,6 +23,8 @@ export type {
   NextTurnParamsContext,
   NextTurnParamsFunctions,
   ParsedToolCall,
+  PartialResponse,
+  StateAccessor,
   StepResult,
   StopCondition,
   StopWhen,
@@ -34,6 +38,7 @@ export type {
   TurnContext,
   TypedToolCall,
   TypedToolCallUnion,
+  UnsentToolResult,
   Warning,
 } from './lib/tool-types.js';
 export type { BuildTurnContextOptions } from './lib/turn-context.js';
@@ -109,4 +114,15 @@ export {
 } 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';
 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
@@ -40,6 +43,14 @@ export type CallModelInput<TTools extends readonly Tool[] = readonly Tool[]> = {
 } & {
   tools?: TTools;
   stopWhen?: StopWhen<TTools>;
+  /** State accessor for multi-turn persistence and approval gates */
+  state?: StateAccessor<TTools>;
+  /** Call-level approval check - overrides tool-level requireApproval setting */
+  requireApproval?: (toolCall: ParsedToolCall<TTools[number]>) => boolean;
+  /** 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[];
 };
 
 /**
@@ -70,8 +81,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

src/lib/conversation-state.ts

@@ -0,0 +1,248 @@
+import type * as models from '../models/index.js';
+import type {
+  ConversationState,
+  ParsedToolCall,
+  Tool,
+  UnsentToolResult,
+} from './tool-types.js';
+import { normalizeInputToArray } from './turn-context.js';
+
+/**
+ * Type guard to verify an object is a valid UnsentToolResult
+ */
+function isValidUnsentToolResult<TTools extends readonly Tool[]>(
+  obj: unknown
+): obj is UnsentToolResult<TTools> {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const candidate = obj as Record<string, unknown>;
+  return (
+    typeof candidate['callId'] === 'string' &&
+    typeof candidate['name'] === 'string' &&
+    'output' in candidate
+  );
+}
+
+/**
+ * Type guard to verify an object is a valid ParsedToolCall
+ */
+function isValidParsedToolCall<TTools extends readonly Tool[]>(
+  obj: unknown
+): obj is ParsedToolCall<TTools[number]> {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const candidate = obj as Record<string, unknown>;
+  return (
+    typeof candidate['id'] === 'string' &&
+    typeof candidate['name'] === 'string' &&
+    'arguments' in candidate
+  );
+}
+
+/**
+ * Generate a unique ID for a conversation
+ * Uses crypto.randomUUID if available, falls back to timestamp + random
+ */
+export function generateConversationId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return `conv_${crypto.randomUUID()}`;
+  }
+  // Fallback for environments without crypto.randomUUID
+  return `conv_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+}
+
+/**
+ * Create an initial conversation state
+ * @param id - Optional custom ID, generates one if not provided
+ */
+export function createInitialState<TTools extends readonly Tool[] = readonly Tool[]>(
+  id?: string
+): ConversationState<TTools> {
+  const now = Date.now();
+  return {
+    id: id ?? generateConversationId(),
+    messages: [],
+    status: 'in_progress',
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * Update a conversation state with new values
+ * Automatically updates the updatedAt timestamp
+ */
+export function updateState<TTools extends readonly Tool[] = readonly Tool[]>(
+  state: ConversationState<TTools>,
+  updates: Partial<Omit<ConversationState<TTools>, 'id' | 'createdAt' | 'updatedAt'>>
+): ConversationState<TTools> {
+  return {
+    ...state,
+    ...updates,
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * Append new items to the message history
+ */
+export function appendToMessages(
+  current: models.OpenResponsesInput,
+  newItems: models.OpenResponsesInput1[]
+): models.OpenResponsesInput {
+  const currentArray = normalizeInputToArray(current);
+  return [...currentArray, ...newItems];
+}
+
+/**
+ * Check if a tool call requires approval
+ * @param toolCall - The tool call to check
+ * @param tools - Available tools
+ * @param callLevelCheck - Optional call-level approval function (overrides tool-level)
+ */
+export function toolRequiresApproval<TTools extends readonly Tool[]>(
+  toolCall: ParsedToolCall<TTools[number]>,
+  tools: TTools,
+  callLevelCheck?: (toolCall: ParsedToolCall<TTools[number]>) => boolean
+): boolean {
+  // Call-level check takes precedence
+  if (callLevelCheck) {
+    return callLevelCheck(toolCall);
+  }
+
+  // Fall back to tool-level setting
+  const tool = tools.find(t => t.function.name === toolCall.name);
+  return tool?.function.requireApproval ?? false;
+}
+
+/**
+ * Partition tool calls into those requiring approval and those that can auto-execute
+ */
+export function partitionToolCalls<TTools extends readonly Tool[]>(
+  toolCalls: ParsedToolCall<TTools[number]>[],
+  tools: TTools,
+  callLevelCheck?: (toolCall: ParsedToolCall<TTools[number]>) => boolean
+): {
+  requiresApproval: ParsedToolCall<TTools[number]>[];
+  autoExecute: ParsedToolCall<TTools[number]>[];
+} {
+  const requiresApproval: ParsedToolCall<TTools[number]>[] = [];
+  const autoExecute: ParsedToolCall<TTools[number]>[] = [];
+
+  for (const tc of toolCalls) {
+    if (toolRequiresApproval(tc, tools, callLevelCheck)) {
+      requiresApproval.push(tc);
+    } else {
+      autoExecute.push(tc);
+    }
+  }
+
+  return { requiresApproval, autoExecute };
+}
+
+/**
+ * Create an unsent tool result from a successful execution
+ */
+export function createUnsentResult<TTools extends readonly Tool[] = readonly Tool[]>(
+  callId: string,
+  name: string,
+  output: unknown
+): UnsentToolResult<TTools> {
+  const result = { callId, name, output };
+  if (!isValidUnsentToolResult<TTools>(result)) {
+    throw new Error('Invalid UnsentToolResult structure');
+  }
+  return result;
+}
+
+/**
+ * Create an unsent tool result from a rejection
+ */
+export function createRejectedResult<TTools extends readonly Tool[] = readonly Tool[]>(
+  callId: string,
+  name: string,
+  reason?: string
+): UnsentToolResult<TTools> {
+  const result = {
+    callId,
+    name,
+    output: null,
+    error: reason ?? 'Tool call rejected by user',
+  };
+  if (!isValidUnsentToolResult<TTools>(result)) {
+    throw new Error('Invalid UnsentToolResult structure');
+  }
+  return result;
+}
+
+/**
+ * Convert unsent tool results to API format for sending to the model
+ */
+export function unsentResultsToAPIFormat(
+  results: UnsentToolResult[]
+): models.OpenResponsesFunctionCallOutput[] {
+  return results.map(r => ({
+    type: 'function_call_output' as const,
+    id: `output_${r.callId}`,
+    callId: r.callId,
+    output: r.error
+      ? JSON.stringify({ error: r.error })
+      : JSON.stringify(r.output),
+  }));
+}
+
+/**
+ * Extract text content from a response
+ */
+export function extractTextFromResponse(
+  response: models.OpenResponsesNonStreamingResponse
+): string {
+  if (!response.output) {
+    return '';
+  }
+
+  const outputs = Array.isArray(response.output) ? response.output : [response.output];
+  const textParts: string[] = [];
+
+  for (const item of outputs) {
+    if (item.type === 'message' && item.content) {
+      for (const content of item.content) {
+        if (content.type === 'output_text' && content.text) {
+          textParts.push(content.text);
+        }
+      }
+    }
+  }
+
+  return textParts.join('');
+}
+
+/**
+ * Extract tool calls from a response
+ */
+export function extractToolCallsFromResponse<TTools extends readonly Tool[]>(
+  response: models.OpenResponsesNonStreamingResponse
+): ParsedToolCall<TTools[number]>[] {
+  if (!response.output) {
+    return [];
+  }
+
+  const outputs = Array.isArray(response.output) ? response.output : [response.output];
+  const toolCalls: ParsedToolCall<TTools[number]>[] = [];
+
+  for (const item of outputs) {
+    if (item.type === 'function_call') {
+      const toolCall = {
+        id: item.callId ?? item.id ?? '',
+        name: item.name ?? '',
+        arguments: typeof item.arguments === 'string'
+          ? JSON.parse(item.arguments)
+          : item.arguments,
+      };
+      if (!isValidParsedToolCall<TTools>(toolCall)) {
+        throw new Error(`Invalid tool call structure for tool: ${item.name}`);
+      }
+      toolCalls.push(toolCall);
+    }
+  }
+
+  return toolCalls;
+}