@strav/brain 1.0.0-alpha.9 → 1.0.1

package/src/drivers/openai/openai_helpers.ts

@@ -0,0 +1,58 @@
+/**
+ * Small utilities shared by `OpenAIBrainDriver` and its subclasses.
+ * Kept separate from the message builder / response mapper because
+ * these are content-agnostic — SDK request-options forwarding, MIME
+ * sniffing, abort-signal probing, and the audio-source upload helper
+ * used by `transcribe`.
+ */
+
+import { BrainError } from '../../brain_error.ts'
+import type { AudioSource } from '../../types.ts'
+
+/** Build the request-options bag forwarded to the SDK. Only `signal` for now. */
+export function reqOpts(options: { signal?: AbortSignal }): { signal?: AbortSignal } | undefined {
+  return options.signal !== undefined ? { signal: options.signal } : undefined
+}
+
+/** Throw a DOMException-shaped abort error if the signal has fired. */
+export function checkAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('Aborted', 'AbortError')
+  }
+}
+
+export function extFromMime(mime: string): string {
+  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'
+}
+
+/**
+ * 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.
+ */
+export 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(
+      `OpenAIBrainDriver.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 })
+}

package/src/drivers/openai/openai_message_builder.ts

@@ -0,0 +1,187 @@
+/**
+ * Pure-function builders for the OpenAI chat-completions request
+ * payload. Separated from `OpenAIBrainDriver` so the wire-shape
+ * translation can be unit-tested without instantiating an SDK
+ * client, and so OpenAI-compat subclasses can reuse the same
+ * primitives without inheriting through a 1000+ LOC base file.
+ */
+
+import type OpenAI from 'openai'
+import { BrainError } from '../../brain_error.ts'
+import type { ChatOptions } from '../../types.ts'
+import type { Tool } from '../../tool.ts'
+import type {
+  ImageBlock,
+  Message,
+  SystemPrompt,
+  TextBlock,
+  ToolUseBlock,
+} from '../../types.ts'
+
+/** Defaults the driver injects when the call site omits them. */
+export interface OpenAIBuildDefaults {
+  defaultModel: string
+  defaultMaxTokens: number
+}
+
+export 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
+}
+
+export 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
+  }
+
+  for (const block of message.content) {
+    if (block.type === 'document') {
+      throw new BrainError(
+        "OpenAIBrainDriver: 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(
+        "OpenAIBrainDriver: 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' } },
+      )
+    }
+  }
+
+  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 } })
+      }
+    }
+    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 }
+}
+
+export function toOpenAIMessages(
+  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
+}
+
+export function buildOpenAIChatParams(
+  messages: readonly Message[],
+  options: ChatOptions,
+  tools: readonly Tool[],
+  defaults: OpenAIBuildDefaults,
+): OpenAI.Chat.ChatCompletionCreateParamsNonStreaming {
+  if (options.serverTools && options.serverTools.length > 0) {
+    throw new BrainError(
+      "OpenAIBrainDriver: 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 OpenAIResponsesBrainDriver slice.",
+      { context: { provider: 'openai' } },
+    )
+  }
+  const model = options.model ?? defaults.defaultModel
+  const params: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming = {
+    model,
+    max_completion_tokens: options.maxTokens ?? defaults.defaultMaxTokens,
+    messages: toOpenAIMessages(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.
+  return params
+}

package/src/drivers/openai/openai_response_mapper.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure-function mappers for OpenAI chat-completions responses back
+ * into framework shapes (`ContentBlock[]`, `ChatUsage`, `ChatResult`).
+ * Extracted from `OpenAIBrainDriver` so the response-shape translation
+ * can be unit-tested in isolation and reused by the OpenAI-compat
+ * subclasses without going through the driver class.
+ */
+
+import type OpenAI from 'openai'
+import type {
+  ChatResult,
+  ChatUsage,
+  ContentBlock,
+  ToolUseBlock,
+} from '../../types.ts'
+
+export 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
+}
+
+export function toOpenAIUsage(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,
+  }
+}
+
+export function addOpenAIUsage(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
+}
+
+export function toOpenAIChatResult(
+  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: toOpenAIUsage(response.usage),
+    raw: response,
+  }
+}

package/src/drivers/openai/openai_tool_dispatch.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared tool-dispatch helpers for the OpenAI loops
+ * (`_runLoop`, `_runLoopWithSchema`, `_streamLoop`,
+ * `_streamLoopWithSchema`).
+ *
+ * The 4 loops each iterate an agentic round-trip with subtly different
+ * control flow — suspend-aware vs not, streaming vs not, schema vs not
+ * — but the inner "parse JSON args, recover, run with recovery" and
+ * the "materialize assistant turn from streamed chunks" sequences are
+ * identical. They live here so each loop is the orchestrator, not the
+ * implementer.
+ */
+
+import type { RunWithToolsOptions } from '../../brain_driver.ts'
+import type { Tool } from '../../tool.ts'
+import { ToolExecutionError } from '../../tool_execution_error.ts'
+import { recoverOrThrow, runToolWithRecovery } from '../../tool_runner.ts'
+import type { ContentBlock, TextBlock, ToolUseBlock } from '../../types.ts'
+
+/** Outcome of `parseToolCallArgs`. `parseFailed` is set if JSON.parse threw and the error recovered. */
+export interface ParsedToolCall {
+  parsedInput: unknown
+  parseFailed: { content: string; isError: boolean } | undefined
+}
+
+/**
+ * Parse a tool call's JSON-encoded arguments. On parse failure, runs
+ * `onToolError` recovery — when it returns a string, that becomes the
+ * `tool_result` content; when it returns undefined, the inner
+ * `recoverOrThrow` rethrows and the loop aborts. Callers either short-
+ * circuit on `parseFailed` (skipping the actual tool call) or proceed
+ * with `parsedInput`.
+ */
+export function parseToolCallArgs(
+  callName: string,
+  callId: string,
+  callArgs: string,
+  options: RunWithToolsOptions,
+): ParsedToolCall {
+  try {
+    const parsedInput = callArgs ? JSON.parse(callArgs) : {}
+    return { parsedInput, parseFailed: undefined }
+  } catch (err) {
+    const parseFailed = recoverOrThrow(
+      new ToolExecutionError(
+        callName,
+        callId,
+        new Error(`Failed to parse tool input JSON: ${(err as Error).message}`),
+      ),
+      options,
+    )
+    return { parsedInput: callArgs, parseFailed }
+  }
+}
+
+/**
+ * Execute one parsed tool call. If `parseFailed` is present (from
+ * `parseToolCallArgs`), short-circuits with the recovered error content.
+ * Otherwise dispatches via `runToolWithRecovery`.
+ */
+export async function executeToolCall(
+  callName: string,
+  callId: string,
+  parsedInput: unknown,
+  parseFailed: ParsedToolCall['parseFailed'],
+  toolMap: Map<string, Tool>,
+  options: RunWithToolsOptions,
+): Promise<{ content: string; isError: boolean }> {
+  if (parseFailed) return parseFailed
+  return runToolWithRecovery(
+    toolMap.get(callName),
+    callName,
+    callId,
+    parsedInput,
+    options,
+  )
+}
+
+/** One streamed-chunk entry, accumulated across deltas by index. */
+export interface StreamedCallEntry {
+  id?: string
+  name?: string
+  args: string
+  started: boolean
+}
+
+/** Sort the chunked tool_calls map by index and drop the bookkeeping. */
+export function orderStreamedCalls(
+  toolCallsByIndex: Map<number, StreamedCallEntry>,
+): StreamedCallEntry[] {
+  return [...toolCallsByIndex.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([, v]) => v)
+}
+
+/**
+ * Build the assistant-turn content from a streaming round-trip's
+ * accumulated text + ordered tool calls. Mirrors what
+ * `fromOpenAIAssistantMessage` does for non-streaming responses.
+ *
+ * Collapses to a bare string when there's only text — keeps the
+ * `messages` array on simple turns clean.
+ */
+export function assistantTurnFromStream(
+  textBuf: string,
+  orderedCalls: readonly StreamedCallEntry[],
+): string | ContentBlock[] {
+  const blocks: ContentBlock[] = []
+  if (textBuf.length > 0) blocks.push({ type: 'text', text: textBuf } satisfies TextBlock)
+  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
+    }
+    blocks.push({
+      type: 'tool_use',
+      id: call.id,
+      name: call.name,
+      input: parsedInput,
+    } satisfies ToolUseBlock)
+  }
+  if (blocks.length === 1 && blocks[0]?.type === 'text') return blocks[0].text
+  return blocks
+}

package/src/drivers/openai/openai_tool_loop.ts

@@ -0,0 +1,191 @@
+/**
+ * Shared non-streaming tool-loop iteration for OpenAI.
+ *
+ * The 4 OpenAI agentic loops (`_runLoop`, `_runLoopWithSchema`,
+ * `_streamLoop`, `_streamLoopWithSchema`) all run the same outer
+ * sequence: build params → call SDK → push assistant turn → check
+ * terminal → dispatch tool calls → push tool results → increment
+ * iteration. This module extracts the non-streaming half so
+ * `_runLoop` and `_runLoopWithSchema` become thin orchestrators
+ * that handle only their own terminal return shape
+ * (`AgentResult | SuspendedRun` vs `AgentGenerateResult<T>`).
+ *
+ * Streaming variants are not unified here yet — yielding events
+ * mid-iteration requires an async-generator wrapper that's a bigger
+ * structural change.
+ */
+
+import type OpenAI from 'openai'
+import type { RunWithToolsOptions } from '../../brain_driver.ts'
+import { BrainError } from '../../brain_error.ts'
+import type { Tool } from '../../tool.ts'
+import type {
+  ChatUsage,
+  ContentBlock,
+  Message,
+  ToolResultBlock,
+  ToolUseBlock,
+} from '../../types.ts'
+import { checkAborted, reqOpts } from './openai_helpers.ts'
+import { addOpenAIUsage, fromOpenAIAssistantMessage } from './openai_response_mapper.ts'
+import { executeToolCall, parseToolCallArgs } from './openai_tool_dispatch.ts'
+
+/** Per-iteration mutable state. The helper mutates this in place. */
+export interface NonStreamLoopState {
+  workingMessages: Message[]
+  aggregated: ChatUsage
+  iterations: number
+}
+
+export function createNonStreamLoopState(messages: readonly Message[]): NonStreamLoopState {
+  return {
+    workingMessages: [...messages],
+    aggregated: {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+    },
+    iterations: 0,
+  }
+}
+
+/**
+ * Per-iteration outcome the orchestrator branches on. `stop` and
+ * `max_iterations` both terminate; the caller maps them to its own
+ * return type (e.g. setting `stopReason: 'max_iterations'`).
+ */
+export type NonStreamIterationOutcome =
+  | { kind: 'continue' }
+  | { kind: 'stop'; assistantText: string; stopReason: string }
+  | { kind: 'max_iterations'; assistantText: string }
+  | { kind: 'suspended'; pendingToolCalls: ToolUseBlock[] }
+
+export interface NonStreamIterationArgs {
+  state: NonStreamLoopState
+  toolMap: Map<string, Tool>
+  maxIterations: number
+  client: OpenAI
+  /**
+   * Built per iteration because `workingMessages` grows each round.
+   * The schema variant's closure adds `response_format` after the
+   * driver's base `buildParams` runs.
+   */
+  buildParams: (msgs: readonly Message[]) => OpenAI.Chat.ChatCompletionCreateParamsNonStreaming
+  options: RunWithToolsOptions
+  /**
+   * Human-in-the-loop gate. Pass `options.shouldSuspend` to enable;
+   * pass `undefined` to disable (schema callers don't support
+   * suspension — the manager throws before reaching the loop).
+   */
+  suspendCheck: NonNullable<RunWithToolsOptions['shouldSuspend']> | undefined
+}
+
+/**
+ * One round-trip of the OpenAI agentic loop. Returns a discriminated
+ * outcome the orchestrator branches on; `state` is mutated in place
+ * (workingMessages append, aggregated usage, iteration counter).
+ */
+export async function runOpenAINonStreamIteration(
+  args: NonStreamIterationArgs,
+): Promise<NonStreamIterationOutcome> {
+  const { state, toolMap, maxIterations, client, buildParams, options, suspendCheck } = args
+  checkAborted(options.signal)
+  const params = buildParams(state.workingMessages)
+  const response = await client.chat.completions.create(params, reqOpts(options))
+  addOpenAIUsage(state.aggregated, response.usage)
+
+  const choice = response.choices[0]
+  if (!choice) {
+    throw new BrainError('OpenAIBrainDriver: response had no choices.')
+  }
+  const assistantMessage = choice.message
+  const assistantText = assistantMessage.content ?? ''
+
+  // Append assistant turn so the next round-trip sends it back verbatim.
+  state.workingMessages.push({
+    role: 'assistant',
+    content: fromOpenAIAssistantMessage(assistantMessage),
+  })
+
+  const toolCalls = assistantMessage.tool_calls ?? []
+  if (toolCalls.length === 0 || choice.finish_reason !== 'tool_calls') {
+    return { kind: 'stop', assistantText, stopReason: choice.finish_reason ?? 'stop' }
+  }
+
+  const resultBlocks: ContentBlock[] = []
+  for (let i = 0; i < toolCalls.length; i++) {
+    const call = toolCalls[i]!
+    if (call.type !== 'function') continue
+    const { parsedInput, parseFailed } = parseToolCallArgs(
+      call.function.name,
+      call.id,
+      call.function.arguments,
+      options,
+    )
+    if (suspendCheck && !parseFailed) {
+      const frameworkCall: ToolUseBlock = {
+        type: 'tool_use',
+        id: call.id,
+        name: call.function.name,
+        input: (parsedInput ?? {}) as Record<string, unknown>,
+      }
+      if (await suspendCheck(frameworkCall, options.context)) {
+        return {
+          kind: 'suspended',
+          pendingToolCalls: collectPendingToolCalls(toolCalls, i),
+        }
+      }
+    }
+    const { content, isError } = await executeToolCall(
+      call.function.name,
+      call.id,
+      parsedInput,
+      parseFailed,
+      toolMap,
+      options,
+    )
+    resultBlocks.push({
+      type: 'tool_result',
+      toolUseId: call.id,
+      content,
+      ...(isError ? { isError: true } : {}),
+    } satisfies ToolResultBlock)
+  }
+  state.workingMessages.push({ role: 'user', content: resultBlocks })
+
+  state.iterations++
+  if (state.iterations >= maxIterations) {
+    return { kind: 'max_iterations', assistantText }
+  }
+  return { kind: 'continue' }
+}
+
+/**
+ * Collect the suspended-mid-batch pending calls. The suspend path
+ * doesn't run `onToolError` for unparsable args — the human-in-the-
+ * loop reviewer sees the raw string and decides what to do.
+ */
+function collectPendingToolCalls(
+  toolCalls: readonly OpenAI.Chat.ChatCompletionMessageToolCall[],
+  startIndex: number,
+): ToolUseBlock[] {
+  const pending: ToolUseBlock[] = []
+  for (let j = startIndex; 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 pending
+}

package/src/drivers/openai_compat/index.ts

@@ -0,0 +1 @@
+export { OpenAICompatBrainDriver } from './openai_compat_brain_driver.ts'