@strav/brain 1.0.0-alpha.22 → 1.0.0-alpha.25

package/src/{providers/openai_provider.ts → drivers/openai/openai_brain_driver.ts}

@@ -1,5 +1,5 @@
 /**
- * `OpenAIProvider` — implementation of `Provider` backed by the
+ * `OpenAIBrainDriver` — implementation of `Provider` backed by the
  * official `openai` SDK (chat completions API).
  *
  * Maps framework shapes to OpenAI's wire format:
@@ -48,23 +48,21 @@
  */
 
 import OpenAI from 'openai'
-import type { AgentResult } from '../agent_result.ts'
-import { BrainError } from '../brain_error.ts'
-import type { OpenAIProviderConfig } from '../brain_config.ts'
-import type { MCPServer } from '../mcp_server.ts'
-import type { AgentGenerateResult } from '../agent_generate_result.ts'
-import type { AgentStreamEvent } from '../agent_stream_event.ts'
-import { resolveMcpTools, type ResolveMcpToolsOptions } from '../mcp/resolve_mcp_tools.ts'
-import { parseGenerated, type OutputSchema } from '../output_schema.ts'
-import { recoverOrThrow, runToolWithRecovery } from '../tool_runner.ts'
+import type { AgentResult } from '../../agent_result.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { OpenAIProviderConfig } from '../../brain_config.ts'
+import type { MCPServer } from '../../mcp_server.ts'
+import type { AgentGenerateResult } from '../../agent_generate_result.ts'
+import type { AgentStreamEvent } from '../../agent_stream_event.ts'
+import { resolveMcpTools, type ResolveMcpToolsOptions } from '../../mcp/resolve_mcp_tools.ts'
+import { parseGenerated, type OutputSchema } from '../../output_schema.ts'
 import type {
-  Provider,
+  BrainDriver,
   RunWithToolsOptions,
   RunWithToolsOptionsWithSuspend,
-} from '../provider.ts'
-import type { SuspendedRun } from '../suspended_run.ts'
-import type { Tool } from '../tool.ts'
-import { ToolExecutionError } from '../tool_execution_error.ts'
+} from '../../brain_driver.ts'
+import type { SuspendedRun } from '../../suspended_run.ts'
+import type { Tool } from '../../tool.ts'
 import type {
   AudioSource,
   ChatOptions,
@@ -74,16 +72,38 @@ import type {
   EmbedOptions,
   EmbedResult,
   GenerateResult,
-  ImageBlock,
   Message,
   StreamEvent,
-  SystemPrompt,
-  TextBlock,
   ToolResultBlock,
   ToolUseBlock,
   TranscribeOptions,
   TranscribeResult,
-} from '../types.ts'
+} from '../../types.ts'
+import {
+  audioSourceToFile,
+  checkAborted,
+  reqOpts,
+} from './openai_helpers.ts'
+import {
+  buildOpenAIChatParams,
+  toOpenAIMessages,
+} from './openai_message_builder.ts'
+import {
+  addOpenAIUsage,
+  toOpenAIChatResult,
+  toOpenAIUsage,
+} from './openai_response_mapper.ts'
+import {
+  assistantTurnFromStream,
+  executeToolCall,
+  orderStreamedCalls,
+  parseToolCallArgs,
+  type StreamedCallEntry,
+} from './openai_tool_dispatch.ts'
+import {
+  createNonStreamLoopState,
+  runOpenAINonStreamIteration,
+} from './openai_tool_loop.ts'
 
 const DEFAULT_OPENAI_MODEL = 'gpt-5'
 const DEFAULT_OPENAI_EMBED_MODEL = 'text-embedding-3-small'
@@ -109,10 +129,10 @@ export interface OpenAIProviderOptions {
   mcpPool?: ResolveMcpToolsOptions['pool']
 }
 
-export class OpenAIProvider implements Provider {
+export class OpenAIBrainDriver implements BrainDriver {
   readonly name: string
   // Protected (rather than private) so OpenAI-compatible drivers
-  // can subclass — see `DeepSeekProvider`. Apps that want to plug
+  // can subclass — see `DeepSeekBrainDriver`. Apps that want to plug
   // in Groq / Together / Fireworks follow the same pattern: extend,
   // override the constructor's base URL + default model, optionally
   // override `buildParams` to suppress fields the upstream API
@@ -149,7 +169,7 @@ export class OpenAIProvider implements Provider {
   async chat(messages: readonly Message[], options: ChatOptions = {}): Promise<ChatResult> {
     const params = this.buildParams(messages, options, [])
     const response = await this.client.chat.completions.create(params, reqOpts(options))
-    return this.toChatResult(response)
+    return toOpenAIChatResult(response)
   }
 
   async *stream(
@@ -177,7 +197,7 @@ export class OpenAIProvider implements Provider {
     yield {
       type: 'stop',
       stopReason: finishReason,
-      usage: toUsage(aggregatedUsage),
+      usage: toOpenAIUsage(aggregatedUsage),
     }
   }
 
@@ -211,121 +231,37 @@ export class OpenAIProvider implements Provider {
   ): Promise<AgentResult | SuspendedRun> {
     const maxIterations = options.maxIterations ?? 10
     const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
-    const workingMessages: Message[] = [...messages]
-    const aggregated: ChatUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      cacheReadTokens: 0,
-      cacheCreationTokens: 0,
-    }
-    let iterations = 0
+    const state = createNonStreamLoopState(messages)
+    const buildParams = (msgs: readonly Message[]) => this.buildParams(msgs, options, tools)
 
     while (true) {
-      checkAborted(options.signal)
-      const params = this.buildParams(workingMessages, options, tools)
-      const response = await this.client.chat.completions.create(params, reqOpts(options))
-      addUsage(aggregated, response.usage)
-
-      const choice = response.choices[0]
-      if (!choice) {
-        throw new BrainError('OpenAIProvider: response had no choices.')
-      }
-      const assistantMessage = choice.message
-
-      // Append assistant turn to working messages so we send it back
-      // verbatim on the next round-trip.
-      workingMessages.push({
-        role: 'assistant',
-        content: fromOpenAIAssistantMessage(assistantMessage),
+      const outcome = await runOpenAINonStreamIteration({
+        state,
+        toolMap,
+        maxIterations,
+        client: this.client,
+        buildParams,
+        options,
+        suspendCheck: options.shouldSuspend,
       })
-
-      const toolCalls = assistantMessage.tool_calls ?? []
-      if (toolCalls.length === 0 || choice.finish_reason !== 'tool_calls') {
+      if (outcome.kind === 'continue') continue
+      if (outcome.kind === 'suspended') {
         return {
-          text: assistantMessage.content ?? '',
-          messages: workingMessages,
-          iterations,
-          stopReason: choice.finish_reason ?? 'stop',
-          usage: aggregated,
-        }
-      }
-
-      const resultBlocks: ContentBlock[] = []
-      for (let i = 0; i < toolCalls.length; i++) {
-        const call = toolCalls[i]!
-        if (call.type !== 'function') continue
-        let parsedInput: unknown
-        let parseFailed: { content: string; isError: boolean } | undefined
-        try {
-          parsedInput = call.function.arguments ? JSON.parse(call.function.arguments) : {}
-        } catch (err) {
-          parseFailed = recoverOrThrow(
-            new ToolExecutionError(
-              call.function.name,
-              call.id,
-              new Error(`Failed to parse tool input JSON: ${(err as Error).message}`),
-            ),
-            options,
-          )
+          status: 'suspended',
+          pendingToolCalls: outcome.pendingToolCalls,
+          state: {
+            messages: state.workingMessages,
+            iterations: state.iterations,
+            usage: state.aggregated,
+          },
         }
-        if (options.shouldSuspend && !parseFailed) {
-          const frameworkCall: ToolUseBlock = {
-            type: 'tool_use',
-            id: call.id,
-            name: call.function.name,
-            input: (parsedInput ?? {}) as Record<string, unknown>,
-          }
-          if (await options.shouldSuspend(frameworkCall, options.context)) {
-            const pending: ToolUseBlock[] = []
-            for (let j = i; j < toolCalls.length; j++) {
-              const c = toolCalls[j]!
-              if (c.type !== 'function') continue
-              let pInput: unknown = {}
-              try {
-                pInput = c.function.arguments ? JSON.parse(c.function.arguments) : {}
-              } catch {
-                pInput = c.function.arguments ?? {}
-              }
-              pending.push({
-                type: 'tool_use',
-                id: c.id,
-                name: c.function.name,
-                input: pInput as Record<string, unknown>,
-              })
-            }
-            return {
-              status: 'suspended',
-              pendingToolCalls: pending,
-              state: { messages: workingMessages, iterations, usage: aggregated },
-            }
-          }
-        }
-        const { content, isError } = parseFailed
-          ?? (await runToolWithRecovery(
-            toolMap.get(call.function.name),
-            call.function.name,
-            call.id,
-            parsedInput,
-            options,
-          ))
-        resultBlocks.push({
-          type: 'tool_result',
-          toolUseId: call.id,
-          content,
-          ...(isError ? { isError: true } : {}),
-        } satisfies ToolResultBlock)
       }
-      workingMessages.push({ role: 'user', content: resultBlocks })
-
-      iterations++
-      if (iterations >= maxIterations) {
-        return {
-          text: assistantMessage.content ?? '',
-          messages: workingMessages,
-          iterations,
-          stopReason: 'max_iterations',
-          usage: aggregated,
-        }
+      return {
+        text: outcome.assistantText,
+        messages: state.workingMessages,
+        iterations: state.iterations,
+        stopReason: outcome.kind === 'max_iterations' ? 'max_iterations' : outcome.stopReason,
+        usage: state.aggregated,
       }
     }
   }
@@ -352,17 +288,9 @@ export class OpenAIProvider implements Provider {
   ): Promise<AgentGenerateResult<T>> {
     const maxIterations = options.maxIterations ?? 10
     const toolMap = new Map<string, Tool>(tools.map((t) => [t.name, t]))
-    const workingMessages: Message[] = [...messages]
-    const aggregated: ChatUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      cacheReadTokens: 0,
-      cacheCreationTokens: 0,
-    }
-    let iterations = 0
-
-    while (true) {
-      const params = this.buildParams(workingMessages, options, tools)
+    const state = createNonStreamLoopState(messages)
+    const buildParams = (msgs: readonly Message[]) => {
+      const params = this.buildParams(msgs, options, tools)
       params.response_format = {
         type: 'json_schema',
         json_schema: {
@@ -372,77 +300,37 @@ export class OpenAIProvider implements Provider {
           strict: true,
         },
       }
-      const response = await this.client.chat.completions.create(params, reqOpts(options))
-      addUsage(aggregated, response.usage)
+      return params
+    }
 
-      const choice = response.choices[0]
-      if (!choice) {
-        throw new BrainError('OpenAIProvider: response had no choices.')
-      }
-      const assistantMessage = choice.message
-      workingMessages.push({
-        role: 'assistant',
-        content: fromOpenAIAssistantMessage(assistantMessage),
+    while (true) {
+      const outcome = await runOpenAINonStreamIteration({
+        state,
+        toolMap,
+        maxIterations,
+        client: this.client,
+        buildParams,
+        options,
+        // Schema variant doesn't support suspension — the manager
+        // throws BrainError before reaching the loop when shouldSuspend
+        // is set on `runWithToolsAndSchema`. See `brain_driver.ts`.
+        suspendCheck: undefined,
       })
-
-      const toolCalls = assistantMessage.tool_calls ?? []
-      if (toolCalls.length === 0 || choice.finish_reason !== 'tool_calls') {
-        const text = assistantMessage.content ?? ''
-        return {
-          value: parseGenerated(text, schema),
-          text,
-          messages: workingMessages,
-          iterations,
-          stopReason: choice.finish_reason ?? 'stop',
-          usage: aggregated,
-        }
-      }
-
-      const resultBlocks: ContentBlock[] = []
-      for (const call of toolCalls) {
-        if (call.type !== 'function') continue
-        let parsedInput: unknown
-        let parseFailed: { content: string; isError: boolean } | undefined
-        try {
-          parsedInput = call.function.arguments ? JSON.parse(call.function.arguments) : {}
-        } catch (err) {
-          parseFailed = recoverOrThrow(
-            new ToolExecutionError(
-              call.function.name,
-              call.id,
-              new Error(`Failed to parse tool input JSON: ${(err as Error).message}`),
-            ),
-            options,
-          )
-        }
-        const { content, isError } = parseFailed
-          ?? (await runToolWithRecovery(
-            toolMap.get(call.function.name),
-            call.function.name,
-            call.id,
-            parsedInput,
-            options,
-          ))
-        resultBlocks.push({
-          type: 'tool_result',
-          toolUseId: call.id,
-          content,
-          ...(isError ? { isError: true } : {}),
-        } satisfies ToolResultBlock)
+      if (outcome.kind === 'continue') continue
+      if (outcome.kind === 'suspended') {
+        // Unreachable: suspendCheck is undefined so 'suspended' can't
+        // be produced. Defensive throw makes the assumption explicit.
+        throw new BrainError(
+          'OpenAIBrainDriver: runWithToolsAndSchema received a suspension outcome but does not support it.',
+        )
       }
-      workingMessages.push({ role: 'user', content: resultBlocks })
-
-      iterations++
-      if (iterations >= maxIterations) {
-        const text = assistantMessage.content ?? ''
-        return {
-          value: parseGenerated(text, schema),
-          text,
-          messages: workingMessages,
-          iterations,
-          stopReason: 'max_iterations',
-          usage: aggregated,
-        }
+      return {
+        value: parseGenerated(outcome.assistantText, schema),
+        text: outcome.assistantText,
+        messages: state.workingMessages,
+        iterations: state.iterations,
+        stopReason: outcome.kind === 'max_iterations' ? 'max_iterations' : outcome.stopReason,
+        usage: state.aggregated,
       }
     }
   }
@@ -491,10 +379,7 @@ export class OpenAIProvider implements Provider {
       // Tracks: per index, the running entry; and whether
       // `tool_use_start` has already been emitted (we emit once the
       // first chunk brings the id + name).
-      const toolCallsByIndex: Map<
-        number,
-        { id?: string; name?: string; args: string; started: boolean }
-      > = new Map()
+      const toolCallsByIndex: Map<number, StreamedCallEntry> = new Map()
       let finishReason: string | null = null
       let lastUsage: OpenAI.CompletionUsage | undefined
 
@@ -536,35 +421,14 @@ export class OpenAIProvider implements Provider {
         if (chunk.usage) lastUsage = chunk.usage
       }
 
-      addUsage(aggregated, lastUsage)
+      addOpenAIUsage(aggregated, lastUsage)
       yield { type: 'iteration_end', iteration: iterations, stopReason: finishReason }
 
-      // Materialize the assistant turn the same way runWithTools does.
-      const assistantBlocks: ContentBlock[] = []
-      if (textBuf.length > 0) assistantBlocks.push({ type: 'text', text: textBuf })
-      const orderedCalls = [...toolCallsByIndex.entries()]
-        .sort(([a], [b]) => a - b)
-        .map(([, v]) => v)
-      for (const call of orderedCalls) {
-        if (!call.id || !call.name) continue
-        let parsedInput: unknown = {}
-        try {
-          parsedInput = call.args ? JSON.parse(call.args) : {}
-        } catch {
-          parsedInput = call.args
-        }
-        assistantBlocks.push({
-          type: 'tool_use',
-          id: call.id,
-          name: call.name,
-          input: parsedInput,
-        } satisfies ToolUseBlock)
-      }
-      const assistantContent: string | ContentBlock[] =
-        assistantBlocks.length === 1 && assistantBlocks[0]?.type === 'text'
-          ? assistantBlocks[0].text
-          : assistantBlocks
-      workingMessages.push({ role: 'assistant', content: assistantContent })
+      const orderedCalls = orderStreamedCalls(toolCallsByIndex)
+      workingMessages.push({
+        role: 'assistant',
+        content: assistantTurnFromStream(textBuf, orderedCalls),
+      })
 
       if (finishReason !== 'tool_calls' || orderedCalls.length === 0) {
         yield {
@@ -580,30 +444,21 @@ export class OpenAIProvider implements Provider {
       const resultBlocks: ContentBlock[] = []
       for (const call of orderedCalls) {
         if (!call.id || !call.name) continue
-        let parsedInput: unknown
-        let parseFailed: { content: string; isError: boolean } | undefined
-        try {
-          parsedInput = call.args ? JSON.parse(call.args) : {}
-        } catch (err) {
-          parseFailed = recoverOrThrow(
-            new ToolExecutionError(
-              call.name,
-              call.id,
-              new Error(`Failed to parse tool input JSON: ${(err as Error).message}`),
-            ),
-            options,
-          )
-          parsedInput = call.args
-        }
+        const { parsedInput, parseFailed } = parseToolCallArgs(
+          call.name,
+          call.id,
+          call.args,
+          options,
+        )
         yield { type: 'tool_use', id: call.id, name: call.name, input: parsedInput }
-        const { content, isError } = parseFailed
-          ?? (await runToolWithRecovery(
-            toolMap.get(call.name),
-            call.name,
-            call.id,
-            parsedInput,
-            options,
-          ))
+        const { content, isError } = await executeToolCall(
+          call.name,
+          call.id,
+          parsedInput,
+          parseFailed,
+          toolMap,
+          options,
+        )
         resultBlocks.push({
           type: 'tool_result',
           toolUseId: call.id,
@@ -695,10 +550,7 @@ export class OpenAIProvider implements Provider {
       // Tracks: per index, the running entry; and whether
       // `tool_use_start` has already been emitted (we emit once the
       // first chunk brings the id + name).
-      const toolCallsByIndex: Map<
-        number,
-        { id?: string; name?: string; args: string; started: boolean }
-      > = new Map()
+      const toolCallsByIndex: Map<number, StreamedCallEntry> = new Map()
       let finishReason: string | null = null
       let lastUsage: OpenAI.CompletionUsage | undefined
 
@@ -740,34 +592,14 @@ export class OpenAIProvider implements Provider {
         if (chunk.usage) lastUsage = chunk.usage
       }
 
-      addUsage(aggregated, lastUsage)
+      addOpenAIUsage(aggregated, lastUsage)
       yield { type: 'iteration_end', iteration: iterations, stopReason: finishReason }
 
-      const assistantBlocks: ContentBlock[] = []
-      if (textBuf.length > 0) assistantBlocks.push({ type: 'text', text: textBuf })
-      const orderedCalls = [...toolCallsByIndex.entries()]
-        .sort(([a], [b]) => a - b)
-        .map(([, v]) => v)
-      for (const call of orderedCalls) {
-        if (!call.id || !call.name) continue
-        let parsedInput: unknown = {}
-        try {
-          parsedInput = call.args ? JSON.parse(call.args) : {}
-        } catch {
-          parsedInput = call.args
-        }
-        assistantBlocks.push({
-          type: 'tool_use',
-          id: call.id,
-          name: call.name,
-          input: parsedInput,
-        } satisfies ToolUseBlock)
-      }
-      const assistantContent: string | ContentBlock[] =
-        assistantBlocks.length === 1 && assistantBlocks[0]?.type === 'text'
-          ? assistantBlocks[0].text
-          : assistantBlocks
-      workingMessages.push({ role: 'assistant', content: assistantContent })
+      const orderedCalls = orderStreamedCalls(toolCallsByIndex)
+      workingMessages.push({
+        role: 'assistant',
+        content: assistantTurnFromStream(textBuf, orderedCalls),
+      })
 
       if (finishReason !== 'tool_calls' || orderedCalls.length === 0) {
         const text = textBuf
@@ -787,30 +619,21 @@ export class OpenAIProvider implements Provider {
       const resultBlocks: ContentBlock[] = []
       for (const call of orderedCalls) {
         if (!call.id || !call.name) continue
-        let parsedInput: unknown
-        let parseFailed: { content: string; isError: boolean } | undefined
-        try {
-          parsedInput = call.args ? JSON.parse(call.args) : {}
-        } catch (err) {
-          parseFailed = recoverOrThrow(
-            new ToolExecutionError(
-              call.name,
-              call.id,
-              new Error(`Failed to parse tool input JSON: ${(err as Error).message}`),
-            ),
-            options,
-          )
-          parsedInput = call.args
-        }
+        const { parsedInput, parseFailed } = parseToolCallArgs(
+          call.name,
+          call.id,
+          call.args,
+          options,
+        )
         yield { type: 'tool_use', id: call.id, name: call.name, input: parsedInput }
-        const { content, isError } = parseFailed
-          ?? (await runToolWithRecovery(
-            toolMap.get(call.name),
-            call.name,
-            call.id,
-            parsedInput,
-            options,
-          ))
+        const { content, isError } = await executeToolCall(
+          call.name,
+          call.id,
+          parsedInput,
+          parseFailed,
+          toolMap,
+          options,
+        )
         resultBlocks.push({
           type: 'tool_result',
           toolUseId: call.id,
@@ -928,7 +751,7 @@ export class OpenAIProvider implements Provider {
       text,
       model: response.model,
       stopReason: choice?.finish_reason ?? null,
-      usage: toUsage(response.usage),
+      usage: toOpenAIUsage(response.usage),
       raw: response,
     }
   }
@@ -954,282 +777,20 @@ export class OpenAIProvider implements Provider {
 
   // ─── Param translation ──────────────────────────────────────────────────
 
+  /**
+   * Thin wrapper around `buildOpenAIChatParams` so `OpenAICompatBrainDriver`
+   * subclasses can still override the request shape via `super.buildParams(...)`
+   * (e.g. strip `reasoning_effort` for endpoints that reject it). Pure
+   * translation lives in `openai_message_builder.ts`.
+   */
   protected buildParams(
     messages: readonly Message[],
     options: ChatOptions,
     tools: readonly Tool[],
   ): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
-    if (options.serverTools && options.serverTools.length > 0) {
-      throw new BrainError(
-        "OpenAIProvider: server tools (web_search / code_execution / web_fetch / url_context) are not supported on OpenAI's chat completions API. OpenAI's server tools live on the Responses API (separate provider slice). Run them as framework-local tools, route to Anthropic / Gemini, or wait for the OpenAIResponsesProvider slice.",
-        { context: { provider: 'openai' } },
-      )
-    }
-    const model = options.model ?? this.defaultModel
-    const params: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming = {
-      model,
-      max_completion_tokens: options.maxTokens ?? this.defaultMaxTokens,
-      messages: this.toMessages(options.system, messages),
-    }
-
-    if (tools.length > 0) {
-      params.tools = tools.map((t) => ({
-        type: 'function',
-        function: {
-          name: t.name,
-          description: t.description,
-          parameters: t.inputSchema as Record<string, unknown>,
-        },
-      }))
-    }
-
-    // Reasoning controls — only emitted when explicitly set so
-    // non-reasoning models don't get rejected.
-    if (options.effort !== undefined) {
-      params.reasoning_effort = options.effort as OpenAI.ReasoningEffort
-    } else if (options.thinking === 'adaptive') {
-      params.reasoning_effort = 'medium' as OpenAI.ReasoningEffort
-    } else if (options.thinking === 'disabled') {
-      params.reasoning_effort = 'minimal' as OpenAI.ReasoningEffort
-    }
-
-    // `cache` is a no-op on OpenAI — prompt caching is automatic.
-    // We accept the flag silently so apps that target both providers
-    // with the same options object don't have to special-case.
-
-    return params
-  }
-
-  private toMessages(
-    system: SystemPrompt | undefined,
-    messages: readonly Message[],
-  ): OpenAI.Chat.ChatCompletionMessageParam[] {
-    const out: OpenAI.Chat.ChatCompletionMessageParam[] = []
-    const systemText = systemPromptText(system)
-    if (systemText.length > 0) {
-      out.push({ role: 'system', content: systemText })
-    }
-    for (const message of messages) {
-      // User-role messages with tool results in their content fan
-      // out into one `tool`-role message per result — OpenAI's
-      // contract is "one tool_call_id per tool message," not a
-      // single user message carrying multiple results.
-      if (
-        message.role === 'user' &&
-        Array.isArray(message.content) &&
-        message.content.some((b) => b.type === 'tool_result')
-      ) {
-        const remainingText: string[] = []
-        for (const block of message.content) {
-          if (block.type === 'tool_result') {
-            out.push({
-              role: 'tool',
-              tool_call_id: block.toolUseId,
-              content: typeof block.content === 'string'
-                ? block.content
-                : block.content.map((t) => t.text).join(''),
-            })
-          } else if (block.type === 'text') {
-            remainingText.push(block.text)
-          }
-        }
-        if (remainingText.length > 0) {
-          out.push({ role: 'user', content: remainingText.join('') })
-        }
-        continue
-      }
-      out.push(toOpenAIMessage(message))
-    }
-    return out
-  }
-
-  private toChatResult(
-    response: OpenAI.Chat.ChatCompletion,
-  ): ChatResult<OpenAI.Chat.ChatCompletion> {
-    const choice = response.choices[0]
-    return {
-      text: choice?.message?.content ?? '',
-      model: response.model,
-      stopReason: choice?.finish_reason ?? null,
-      usage: toUsage(response.usage),
-      raw: response,
-    }
-  }
-}
-
-// ─── Shape converters ─────────────────────────────────────────────────────
-
-/** Build the request-options bag forwarded to the SDK. Only `signal` for now. */
-function reqOpts(options: { signal?: AbortSignal }): { signal?: AbortSignal } | undefined {
-  return options.signal !== undefined ? { signal: options.signal } : undefined
-}
-
-/**
- * Materialize an `AudioSource` as a `File` the OpenAI SDK's
- * `Uploadable` shape accepts. Base64 → in-memory File; URL →
- * fetch + wrap. The SDK wants a filename; we synthesize one
- * since `AudioSource` doesn't carry one. The extension lets the
- * SDK pick the right content-type for the multipart upload.
- */
-async function audioSourceToFile(audio: AudioSource): Promise<File> {
-  if (audio.type === 'base64') {
-    const bytes = Buffer.from(audio.data, 'base64')
-    const ext = extFromMime(audio.mediaType)
-    return new File([bytes], `audio.${ext}`, { type: audio.mediaType })
-  }
-  const response = await fetch(audio.url)
-  if (!response.ok) {
-    throw new BrainError(
-      `OpenAIProvider.transcribe: failed to fetch audio at ${audio.url}: ${response.status} ${response.statusText}.`,
-      { context: { url: audio.url, status: response.status } },
-    )
-  }
-  const buf = await response.arrayBuffer()
-  const mime = response.headers.get('content-type') ?? 'audio/mpeg'
-  return new File([buf], `audio.${extFromMime(mime)}`, { type: mime })
-}
-
-function extFromMime(mime: string): string {
-  // Strip parameters (`audio/mpeg; codecs=...` → `audio/mpeg`).
-  const m = mime.split(';')[0]?.trim().toLowerCase() ?? ''
-  if (m === 'audio/mp3' || m === 'audio/mpeg' || m === 'audio/mpga') return 'mp3'
-  if (m === 'audio/wav' || m === 'audio/x-wav') return 'wav'
-  if (m === 'audio/ogg') return 'ogg'
-  if (m === 'audio/flac') return 'flac'
-  if (m === 'audio/webm') return 'webm'
-  if (m === 'audio/aac' || m === 'audio/x-aac' || m === 'audio/mp4' || m === 'audio/m4a') return 'm4a'
-  return 'mp3'
-}
-
-/** Throw a DOMException-shaped abort error if the signal has fired. */
-function checkAborted(signal: AbortSignal | undefined): void {
-  if (signal?.aborted) {
-    throw signal.reason ?? new DOMException('Aborted', 'AbortError')
-  }
-}
-
-function systemPromptText(system: SystemPrompt | undefined): string {
-  if (system === undefined) return ''
-  if (typeof system === 'string') return system
-  if (Array.isArray(system)) return system.map((b) => b.text).join('\n')
-  return system.text
-}
-
-function toOpenAIMessage(message: Message): OpenAI.Chat.ChatCompletionMessageParam {
-  if (typeof message.content === 'string') {
-    return { role: message.role, content: message.content } as OpenAI.Chat.ChatCompletionMessageParam
-  }
-
-  // Assistant turns may contain text + tool_use blocks; we need to
-  // split tool_use blocks into the `tool_calls` field and put the
-  // remaining text into `content`.
-  if (message.role === 'assistant') {
-    const text = message.content
-      .filter((b): b is TextBlock => b.type === 'text')
-      .map((b) => b.text)
-      .join('')
-    const toolUses = message.content.filter((b): b is ToolUseBlock => b.type === 'tool_use')
-    const param: OpenAI.Chat.ChatCompletionAssistantMessageParam = { role: 'assistant' }
-    if (text.length > 0) param.content = text
-    if (toolUses.length > 0) {
-      param.tool_calls = toolUses.map((b) => ({
-        id: b.id,
-        type: 'function',
-        function: {
-          name: b.name,
-          arguments: JSON.stringify(b.input ?? {}),
-        },
-      }))
-    }
-    return param
-  }
-
-  // Document / audio aren't supported by OpenAI's chat completions
-  // API. Throw with vendor-specific guidance so apps don't waste a
-  // 400 trying to send a PDF.
-  for (const block of message.content) {
-    if (block.type === 'document') {
-      throw new BrainError(
-        "OpenAIProvider: document blocks are not supported on OpenAI's chat completions API. For PDFs, split the document to images (one per page) and send them as ImageBlocks on a vision-capable model (gpt-5 / gpt-4o family); or route document workloads to Anthropic / Gemini, which accept PDF blocks natively.",
-        { context: { provider: 'openai' } },
-      )
-    }
-    if (block.type === 'audio') {
-      throw new BrainError(
-        "OpenAIProvider: audio blocks are not supported on OpenAI's chat completions API. Transcribe audio upstream via OpenAI's Whisper / gpt-4o-transcribe and send the resulting text; or route audio workloads to Gemini, which accepts audio blocks natively.",
-        { context: { provider: 'openai' } },
-      )
-    }
-  }
-
-  // User-role multi-block content. If any image blocks are present,
-  // emit OpenAI's multi-part content array (text + image_url
-  // entries). Otherwise flatten text — keeps simple text messages
-  // cleanly typed as strings. MCP blocks (read-only,
-  // Anthropic-specific) are silently dropped.
-  const images = message.content.filter((b): b is ImageBlock => b.type === 'image')
-  if (images.length > 0) {
-    const parts: OpenAI.Chat.ChatCompletionContentPart[] = []
-    for (const block of message.content) {
-      if (block.type === 'text') {
-        parts.push({ type: 'text', text: block.text })
-      } else if (block.type === 'image') {
-        const url =
-          block.source.type === 'base64'
-            ? `data:${block.source.mediaType};base64,${block.source.data}`
-            : block.source.url
-        parts.push({ type: 'image_url', image_url: { url } })
-      }
-      // tool_result / tool_use / mcp blocks dropped from user content
-      // (they're handled elsewhere or aren't valid on user turns).
-    }
-    return { role: 'user', content: parts }
-  }
-  const text = message.content
-    .filter((b): b is TextBlock => b.type === 'text')
-    .map((b) => b.text)
-    .join('')
-  return { role: 'user', content: text }
-}
-
-function fromOpenAIAssistantMessage(
-  msg: OpenAI.Chat.ChatCompletionMessage,
-): string | ContentBlock[] {
-  const blocks: ContentBlock[] = []
-  if (msg.content) blocks.push({ type: 'text', text: msg.content })
-  if (msg.tool_calls) {
-    for (const call of msg.tool_calls) {
-      if (call.type !== 'function') continue
-      let parsedInput: unknown = {}
-      try {
-        parsedInput = call.function.arguments ? JSON.parse(call.function.arguments) : {}
-      } catch {
-        parsedInput = call.function.arguments ?? {}
-      }
-      blocks.push({
-        type: 'tool_use',
-        id: call.id,
-        name: call.function.name,
-        input: parsedInput,
-      } satisfies ToolUseBlock)
-    }
-  }
-  if (blocks.length === 1 && blocks[0]?.type === 'text') return blocks[0].text
-  return blocks
-}
-
-function toUsage(u: OpenAI.CompletionUsage | undefined): ChatUsage {
-  return {
-    inputTokens: u?.prompt_tokens ?? 0,
-    outputTokens: u?.completion_tokens ?? 0,
-    cacheReadTokens: u?.prompt_tokens_details?.cached_tokens ?? 0,
-    cacheCreationTokens: 0,
+    return buildOpenAIChatParams(messages, options, tools, {
+      defaultModel: this.defaultModel,
+      defaultMaxTokens: this.defaultMaxTokens,
+    })
   }
 }
-
-function addUsage(acc: ChatUsage, u: OpenAI.CompletionUsage | undefined): void {
-  if (!u) return
-  acc.inputTokens += u.prompt_tokens
-  acc.outputTokens += u.completion_tokens
-  acc.cacheReadTokens += u.prompt_tokens_details?.cached_tokens ?? 0
-}