refactor: replace type casts with proper type guards

- Create claude-constants.ts with constants for Claude block types
- Create claude-type-guards.ts with isClaudeStyleMessages type guard
- Replace `as Record<string, unknown>` casts with proper type narrowing
- Remove `as unknown as TTools` double assertion in callModel.ts
- Consolidate duplicate normalizeInputToArray functions
- Consolidate createTurnContext and createTurnContextWithMutations methods
- Add isGeneratorConfig type guard in create-tool.ts
- Fix non-null assertion in tool-orchestrator.ts with resultHasError guard
- Extend normalizeInputToArray to handle undefined input
- Add comprehensive tests for new type guards

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mattapperson

src/funcs/callModel.ts

@@ -3,6 +3,7 @@ import type { RequestOptions } from "../lib/sdks.js";
 import type { Tool, MaxToolRounds } from "../lib/tool-types.js";
 import type * as models from "../models/index.js";
 
+import { isClaudeStyleMessages } from "../lib/claude-type-guards.js";
 import { ResponseWrapper } from "../lib/response-wrapper.js";
 import { convertToolsToAPIFormat } from "../lib/tool-executor.js";
 
@@ -25,81 +26,30 @@ export type CallModelTools =
   | models.ToolDefinitionJson[]
   | models.OpenResponsesRequest["tools"];
 
+// isClaudeStyleMessages is imported from "../lib/claude-type-guards.js"
+
 /**
- * Check if input is Anthropic Claude-style messages (ClaudeMessageParam[])
- *
- * Claude messages have only 'user' or 'assistant' roles (no 'system', 'tool', 'developer')
- * and may contain Claude-specific block types in content arrays.
- *
- * We check for Claude-ONLY features to distinguish from OpenAI format:
- * - 'tool_result' blocks (Claude-specific; OpenAI uses role: 'tool')
- * - 'image' blocks with 'source' object (Claude-specific structure)
+ * Check if input is chat-style messages (Message[])
  */
-function isClaudeStyleMessages(
-  input: CallModelInput
-): input is models.ClaudeMessageParam[] {
+function isChatStyleMessages(input: CallModelInput): input is models.Message[] {
   if (!Array.isArray(input) || input.length === 0) {
     return false;
   }
 
-  // Check ALL messages for Claude-specific features
-  for (const msg of input) {
-    const m = msg as Record<string, unknown>;
-    if (!m || !("role" in m) || "type" in m) {
-      continue;
-    }
-
-    // OpenAI has 'system', 'developer', 'tool' roles that Claude doesn't have
-    // If we see these roles, it's definitely NOT Claude format
-    const role = m["role"];
-    if (role === "system" || role === "developer" || role === "tool") {
-      return false;
-    }
-
-    const content = m["content"];
-    if (!Array.isArray(content)) {
-      continue;
-    }
-
-    for (const block of content) {
-      const b = block as Record<string, unknown>;
-      const blockType = b?.["type"];
-      // 'tool_result' is Claude-specific (OpenAI uses role: 'tool' messages instead)
-      if (blockType === "tool_result") {
-        return true;
-      }
-      // 'image' with 'source' object is Claude-specific
-      // OpenAI uses 'image_url' structure instead
-      if (blockType === "image" && typeof b?.["source"] === "object") {
-        return true;
-      }
-      // 'tool_use' blocks are Claude-specific (OpenAI uses 'tool_calls' array on message)
-      if (blockType === "tool_use" && typeof b?.["id"] === "string") {
-        return true;
-      }
-    }
+  const first = input[0];
+  // Chat-style messages have role but no 'type' field at top level
+  // Responses-style items have 'type' field (like 'message', 'function_call', etc.)
+  if (first === null || typeof first !== "object") {
+    return false;
   }
-
-  // No Claude-specific features found
-  // Default to NOT Claude (prefer OpenAI chat format as it's more common)
-  return false;
+  return "role" in first && !("type" in first);
 }
 
 /**
- * Check if input is chat-style messages (Message[])
+ * Type guard helper: checks if a value is a non-null object
  */
-function isChatStyleMessages(input: CallModelInput): input is models.Message[] {
-  if (!Array.isArray(input)) {
-    return false;
-  }
-  if (input.length === 0) {
-    return false;
-  }
-
-  const first = input[0] as Record<string, unknown>;
-  // Chat-style messages have role but no 'type' field at top level
-  // Responses-style items have 'type' field (like 'message', 'function_call', etc.)
-  return first && "role" in first && !("type" in first);
+function isNonNullObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 /**
@@ -108,26 +58,28 @@ function isChatStyleMessages(input: CallModelInput): input is models.Message[] {
 function isChatStyleTools(
   tools: CallModelTools
 ): tools is models.ToolDefinitionJson[] {
-  if (!Array.isArray(tools)) {
+  if (!Array.isArray(tools) || tools.length === 0) {
     return false;
   }
-  if (tools.length === 0) {
+
+  const first = tools[0];
+  if (!isNonNullObject(first)) {
     return false;
   }
 
-  const first = tools[0] as Record<string, unknown>;
   // Chat-style tools have nested 'function' property with 'name' inside
   // Enhanced tools have 'function' with 'inputSchema'
   // Responses-style tools have 'name' at top level
-  const fn = first?.["function"] as Record<string, unknown> | undefined;
-  return (
-    first &&
-    "function" in first &&
-    fn !== undefined &&
-    fn !== null &&
-    "name" in fn &&
-    !("inputSchema" in fn)
-  );
+  if (!("function" in first)) {
+    return false;
+  }
+
+  const fn = first.function;
+  if (!isNonNullObject(fn)) {
+    return false;
+  }
+
+  return "name" in fn && !("inputSchema" in fn);
 }
 
 /**
@@ -463,22 +415,21 @@ export function callModel<TTools extends readonly Tool[] = Tool[]>(
   let isChatTools = false;
 
   if (tools && Array.isArray(tools) && tools.length > 0) {
-    const firstTool = tools[0] as Record<string, unknown>;
-    const fn = firstTool?.["function"] as Record<string, unknown> | undefined;
-    isEnhancedTools =
-      "function" in firstTool &&
-      fn !== undefined &&
-      fn !== null &&
-      "inputSchema" in fn;
+    const firstTool = tools[0];
+    if (isNonNullObject(firstTool) && "function" in firstTool) {
+      const fn = firstTool.function;
+      if (isNonNullObject(fn) && "inputSchema" in fn) {
+        isEnhancedTools = true;
+      }
+    }
     isChatTools = !isEnhancedTools && isChatStyleTools(tools);
   }
 
-  const enhancedTools = isEnhancedTools ? (tools as Tool[]) : undefined;
-
   // Convert tools to API format based on their type
   let apiTools: models.OpenResponsesRequest["tools"];
-  if (enhancedTools) {
-    apiTools = convertToolsToAPIFormat(enhancedTools);
+  if (isEnhancedTools) {
+    // Tools are enhanced tools with inputSchema - convert to API format
+    apiTools = convertToolsToAPIFormat(tools as Tool[]);
   } else if (isChatTools) {
     apiTools = convertChatToResponsesTools(
       tools as models.ToolDefinitionJson[]
@@ -507,12 +458,14 @@ export function callModel<TTools extends readonly Tool[] = Tool[]>(
     options: options ?? {},
   };
 
-  // Only pass enhanced tools to wrapper (needed for auto-execution)
-  // Double assertion needed because TTools is a generic extending readonly Tool[],
-  // while enhancedTools is Tool[]. TypeScript can't verify the specific TTools subtype
-  // at runtime, but we know it's safe since we extracted these tools from the input.
-  if (enhancedTools) {
-    wrapperOptions.tools = enhancedTools as unknown as TTools;
+  // Pass enhanced tools to wrapper for auto-execution
+  // The tools parameter is already typed as TTools from the function signature,
+  // so we can assign it directly when we've confirmed it matches the enhanced tools pattern
+  if (isEnhancedTools && tools) {
+    // Type assertion is necessary here because TypeScript cannot track that
+    // isEnhancedTools === true implies tools matches TTools (the enhanced tools type).
+    // We've verified via isNonNullObject checks that tools[0].function.inputSchema exists.
+    wrapperOptions.tools = tools as TTools;
   }
 
   if (maxToolRounds !== undefined) {

src/index.ts

@@ -26,6 +26,8 @@ export type {
   TypedToolCall,
   TypedToolCallUnion,
   TurnContext,
+  TurnChange,
+  NextTurnParams,
   ParsedToolCall,
   // Event type inference helpers
   InferToolEvent,
@@ -35,4 +37,9 @@ export type {
   ToolStreamEvent,
   ChatStreamEvent,
   EnhancedResponseStreamEvent,
+  // Builder types
+  BuildTurnContextOptions,
 } from "./lib/tool-types.js";
+
+// Tool helpers
+export { normalizeInputToArray, buildTurnContext } from "./lib/tool-types.js";

src/lib/claude-constants.ts

@@ -0,0 +1,25 @@
+/**
+ * Claude content block types used in message content arrays
+ */
+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 exist in OpenAI/Chat format but NOT in Claude format.
+ * Used to distinguish between the two message formats.
+ */
+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,115 @@
+import type * as models from "../models/index.js";
+import {
+  ClaudeContentBlockType,
+  NonClaudeMessageRole,
+} from "./claude-constants.js";
+
+/**
+ * Type guard: checks if a value is a valid object (not null, not array)
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Type guard: checks if a role is an OpenAI/Chat-specific role (not Claude)
+ */
+function isNonClaudeRole(role: unknown): boolean {
+  return (
+    role === NonClaudeMessageRole.System ||
+    role === NonClaudeMessageRole.Developer ||
+    role === NonClaudeMessageRole.Tool
+  );
+}
+
+/**
+ * Type guard: checks if a content block is a Claude tool_result block
+ */
+function isClaudeToolResultBlock(block: unknown): boolean {
+  if (!isRecord(block)) return false;
+  return block["type"] === ClaudeContentBlockType.ToolResult;
+}
+
+/**
+ * Type guard: checks if a content block is a Claude image block with source object
+ * (Claude uses 'source' object; OpenAI uses 'image_url' structure)
+ */
+function isClaudeImageBlockWithSource(block: unknown): boolean {
+  if (!isRecord(block)) return false;
+  return (
+    block["type"] === ClaudeContentBlockType.Image &&
+    "source" in block &&
+    isRecord(block["source"])
+  );
+}
+
+/**
+ * Type guard: checks if a content block is a Claude tool_use block with id
+ * (Claude uses 'tool_use' blocks; OpenAI uses 'tool_calls' array on message)
+ */
+function isClaudeToolUseBlockWithId(block: unknown): boolean {
+  if (!isRecord(block)) return false;
+  return (
+    block["type"] === ClaudeContentBlockType.ToolUse &&
+    "id" in block &&
+    typeof block["id"] === "string"
+  );
+}
+
+/**
+ * Checks if a message's content array contains Claude-specific blocks
+ */
+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;
+}
+
+/**
+ * Type guard: checks if input is Anthropic Claude-style messages
+ *
+ * Claude messages have only 'user' or 'assistant' roles (no 'system', 'tool', 'developer')
+ * and may contain Claude-specific block types in content arrays.
+ *
+ * We check for Claude-ONLY features to distinguish from OpenAI format:
+ * - 'tool_result' blocks (Claude-specific; OpenAI uses role: 'tool')
+ * - 'image' blocks with 'source' object (Claude-specific structure)
+ * - 'tool_use' blocks with 'id' (Claude-specific; OpenAI uses 'tool_calls' array on message)
+ */
+export function isClaudeStyleMessages(
+  input: unknown
+): input is models.ClaudeMessageParam[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    return false;
+  }
+
+  for (const msg of input) {
+    // Skip non-object entries
+    if (!isRecord(msg)) continue;
+
+    // Must have role property
+    if (!("role" in msg)) continue;
+
+    // Claude messages don't have top-level 'type' field
+    if ("type" in msg) continue;
+
+    // OpenAI has 'system', 'developer', 'tool' roles that Claude doesn't have
+    // If we see these roles, it's definitely NOT Claude format
+    if (isNonClaudeRole(msg["role"])) {
+      return false;
+    }
+
+    // Check for Claude-specific content blocks
+    const content = msg["content"];
+    if (Array.isArray(content) && hasClaudeSpecificBlocks(content)) {
+      return true;
+    }
+  }
+
+  // No Claude-specific features found
+  // Default to NOT Claude (prefer OpenAI chat format as it's more common)
+  return false;
+}