feat: enforce state requirement for approval workflows

Add type-level and runtime enforcement that approval-related parameters
require a state accessor:

Type-level enforcement:
- CallModelInput now uses conditional types so `approveToolCalls` and
  `rejectToolCalls` are typed as `never` when `state` is not provided
- Added helper types: ToolHasApproval, HasApprovalTools

Runtime enforcement:
- Throws error in ModelResult constructor if approveToolCalls/rejectToolCalls
  provided without state accessor
- Throws error in handleApprovalCheck if tools require approval but no
  state accessor is configured

New exports:
- Type guards: toolHasApprovalConfigured, hasApprovalRequiredTools
- Helper types: ToolHasApproval, HasApprovalTools, CallModelInputWithApprovalTools

Author: mattapperson

src/index.ts

@@ -5,6 +5,7 @@
 // Async params support
 export type {
   CallModelInput,
+  CallModelInputWithApprovalTools,
   FieldOrAsyncFunction,
   ResolvedCallModelInput,
 } from './lib/async-params.js';
@@ -15,6 +16,7 @@ export type {
   ConversationState,
   ConversationStatus,
   ResponseStreamEvent as EnhancedResponseStreamEvent,
+  HasApprovalTools,
   InferToolEvent,
   InferToolEventsUnion,
   InferToolInput,
@@ -32,6 +34,7 @@ export type {
   ToolApprovalCheck,
   ToolExecutionResult,
   ToolExecutionResultUnion,
+  ToolHasApproval,
   ToolPreliminaryResultEvent,
   ToolStreamEvent,
   ToolWithExecute,
@@ -107,10 +110,12 @@ 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

src/lib/async-params.ts

@@ -32,19 +32,15 @@ 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>;
-  /** State accessor for multi-turn persistence and approval gates */
-  state?: StateAccessor<TTools>;
   /**
    * Call-level approval check - overrides tool-level requireApproval setting
    * Receives the tool call and turn context, can be sync or async
@@ -53,12 +49,50 @@ export type CallModelInput<TTools extends readonly Tool[] = readonly Tool[]> = {
     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);
+
+/**
+ * Strict version that requires state - use when tools have approval configured
+ */
+export type CallModelInputWithApprovalTools<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

src/lib/model-result.ts

@@ -154,6 +154,19 @@ export class ModelResult<TTools extends readonly Tool[]> {
 
   constructor(options: GetResponseOptions<TTools>) {
     this.options = options;
+
+    // Runtime validation: approval decisions require state
+    const hasApprovalDecisions =
+      (options.approveToolCalls && options.approveToolCalls.length > 0) ||
+      (options.rejectToolCalls && options.rejectToolCalls.length > 0);
+
+    if (hasApprovalDecisions && !options.state) {
+      throw new Error(
+        'approveToolCalls and rejectToolCalls require a state accessor. ' +
+        'Provide a StateAccessor via the "state" parameter to persist approval decisions.'
+      );
+    }
+
     // Initialize state management
     this.stateAccessor = options.state ?? null;
     this.requireApprovalFn = options.requireApproval ?? null;
@@ -355,11 +368,20 @@ export class ModelResult<TTools extends readonly Tool[]> {
 
     if (needsApproval.length === 0) return false;
 
+    // Validate: approval requires state accessor
+    if (!this.stateAccessor) {
+      const toolNames = needsApproval.map(tc => tc.name).join(', ');
+      throw new Error(
+        `Tool(s) require approval but no state accessor is configured: ${toolNames}. ` +
+        'Provide a StateAccessor via the "state" parameter to enable approval workflows.'
+      );
+    }
+
     // Execute auto-approve tools
     const unsentResults = await this.executeAutoApproveTools(autoExecute, turnContext);
 
     // Save state with pending approvals
-    if (this.stateAccessor && this.currentState) {
+    if (this.currentState) {
       const stateUpdates: Partial<Omit<ConversationState<TTools>, 'id' | 'createdAt' | 'updatedAt'>> = {
         pendingToolCalls: needsApproval,
         status: 'awaiting_approval',

src/lib/tool-types.ts

@@ -514,3 +514,47 @@ export interface StateAccessor<TTools extends readonly Tool[] = readonly Tool[]>
   /** Save the conversation state */
   save: (state: ConversationState<TTools>) => Promise<void>;
 }
+
+// =============================================================================
+// Approval Detection Helper Types
+// =============================================================================
+
+/**
+ * Check if a single tool has approval configured (non-false, non-undefined)
+ * Returns true if the tool definitely requires approval,
+ * false if it definitely doesn't, or boolean if it's uncertain
+ */
+export type ToolHasApproval<T extends Tool> =
+  T extends { function: { requireApproval: true | ToolApprovalCheck<unknown> } }
+    ? true
+    : T extends { function: { requireApproval: false } }
+      ? false
+      : T extends { function: { requireApproval: undefined } }
+        ? false
+        : boolean; // Could be either (optional property)
+
+/**
+ * Check if ANY tool in an array has approval configured
+ * Returns true if at least one tool might require approval
+ */
+export type HasApprovalTools<TTools extends readonly Tool[]> =
+  TTools extends readonly [infer First extends Tool, ...infer Rest extends Tool[]]
+    ? ToolHasApproval<First> extends true
+      ? true
+      : HasApprovalTools<Rest>
+    : false;
+
+/**
+ * Type guard to check if a tool has approval configured at runtime
+ */
+export function toolHasApprovalConfigured(tool: Tool): boolean {
+  const requireApproval = tool.function.requireApproval;
+  return requireApproval === true || typeof requireApproval === 'function';
+}
+
+/**
+ * Type guard to check if any tools in array have approval configured at runtime
+ */
+export function hasApprovalRequiredTools(tools: readonly Tool[]): boolean {
+  return tools.some(toolHasApprovalConfigured);
+}

tests/unit/conversation-state.test.ts

@@ -11,6 +11,10 @@ import {
   appendToMessages,
 } from '../../src/lib/conversation-state.js';
 import { tool } from '../../src/lib/tool.js';
+import {
+  toolHasApprovalConfigured,
+  hasApprovalRequiredTools,
+} from '../../src/lib/tool-types.js';
 
 describe('Conversation State Utilities', () => {
   describe('generateConversationId', () => {
@@ -327,4 +331,77 @@ describe('Conversation State Utilities', () => {
       expect(result).toHaveLength(2);
     });
   });
+
+  describe('Approval Detection Type Guards', () => {
+    const toolWithBooleanApproval = tool({
+      name: 'needs_approval',
+      inputSchema: z.object({}),
+      requireApproval: true,
+      execute: async () => ({}),
+    });
+
+    const toolWithFunctionApproval = tool({
+      name: 'conditional_approval',
+      inputSchema: z.object({ dangerous: z.boolean() }),
+      requireApproval: (params) => params.dangerous,
+      execute: async () => ({}),
+    });
+
+    const toolWithoutApproval = tool({
+      name: 'safe_tool',
+      inputSchema: z.object({}),
+      execute: async () => ({}),
+    });
+
+    const toolWithFalseApproval = tool({
+      name: 'explicitly_safe',
+      inputSchema: z.object({}),
+      requireApproval: false,
+      execute: async () => ({}),
+    });
+
+    describe('toolHasApprovalConfigured', () => {
+      it('should return true for tools with requireApproval: true', () => {
+        expect(toolHasApprovalConfigured(toolWithBooleanApproval)).toBe(true);
+      });
+
+      it('should return true for tools with requireApproval function', () => {
+        expect(toolHasApprovalConfigured(toolWithFunctionApproval)).toBe(true);
+      });
+
+      it('should return false for tools without requireApproval', () => {
+        expect(toolHasApprovalConfigured(toolWithoutApproval)).toBe(false);
+      });
+
+      it('should return false for tools with requireApproval: false', () => {
+        expect(toolHasApprovalConfigured(toolWithFalseApproval)).toBe(false);
+      });
+    });
+
+    describe('hasApprovalRequiredTools', () => {
+      it('should return true if any tool has approval configured', () => {
+        expect(hasApprovalRequiredTools([
+          toolWithoutApproval,
+          toolWithBooleanApproval,
+        ])).toBe(true);
+      });
+
+      it('should return true for function-based approval', () => {
+        expect(hasApprovalRequiredTools([
+          toolWithFunctionApproval,
+        ])).toBe(true);
+      });
+
+      it('should return false if no tools have approval configured', () => {
+        expect(hasApprovalRequiredTools([
+          toolWithoutApproval,
+          toolWithFalseApproval,
+        ])).toBe(false);
+      });
+
+      it('should return false for empty array', () => {
+        expect(hasApprovalRequiredTools([])).toBe(false);
+      });
+    });
+  });
 });