@archal/cli 0.5.0 → 0.6.0

package/harnesses/_lib/providers.mjs

@@ -0,0 +1,874 @@
+/**
+ * Shared provider detection and LLM calling for bundled harnesses.
+ * Supports Gemini, OpenAI, and Anthropic provider APIs.
+ *
+ * Env var overrides:
+ *   ARCHAL_MAX_TOKENS         — Max completion tokens (default from model-configs)
+ *   ARCHAL_TEMPERATURE        — Sampling temperature
+ *   ARCHAL_LLM_TIMEOUT        — Per-call timeout in seconds (default 120)
+ *   ARCHAL_OPENAI_BASE_URL    — Override OpenAI base URL (for proxies, Azure, etc.)
+ *   ARCHAL_ANTHROPIC_BASE_URL — Override Anthropic base URL
+ *   ARCHAL_GEMINI_BASE_URL    — Override Gemini base URL
+ *   ARCHAL_THINKING_BUDGET    — Control extended thinking for supported models.
+ *                                Default (not set) = "adaptive" (thinking ON).
+ *                                "adaptive" = adaptive (Anthropic) / default (Gemini).
+ *                                Number = budget_tokens for Anthropic, thinkingBudget for Gemini.
+ *                                "off" or "0" = disable thinking.
+ */
+
+import { getModelConfig, isReasoningModel, isThinkingModel, getModelCapabilities } from './model-configs.mjs';
+
+// ── Provider detection ──────────────────────────────────────────────
+
+/**
+ * Detect the LLM provider from the model name.
+ * @param {string} model
+ * @returns {'gemini' | 'anthropic' | 'openai'}
+ */
+export function detectProvider(model) {
+  if (model.startsWith('gemini-')) return 'gemini';
+  if (model.startsWith('claude-')) return 'anthropic';
+  if (
+    model.startsWith('gpt-') ||
+    /^o[134]/.test(model)
+  ) return 'openai';
+  // Default to OpenAI-compatible for unknown models
+  return 'openai';
+}
+
+const PROVIDER_ENV_VARS = {
+  gemini: 'GEMINI_API_KEY',
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+};
+
+/**
+ * Resolve the API key for the detected provider.
+ * Priority: ARCHAL_ENGINE_API_KEY > provider-specific env var.
+ * @param {string} provider
+ * @returns {string}
+ */
+export function resolveApiKey(provider) {
+  const engineKey = process.env['ARCHAL_ENGINE_API_KEY']?.trim();
+  if (engineKey) return engineKey;
+
+  const envVar = PROVIDER_ENV_VARS[provider] ?? 'OPENAI_API_KEY';
+  const key = process.env[envVar]?.trim();
+  if (key) return key;
+
+  throw new Error(
+    `No API key found for provider "${provider}". ` +
+    `Set ${envVar} or ARCHAL_ENGINE_API_KEY environment variable, ` +
+    `or run: archal config set engine.apiKey <your-key>`
+  );
+}
+
+// ── Base URL resolution ─────────────────────────────────────────────
+
+const DEFAULT_BASE_URLS = {
+  openai: 'https://api.openai.com/v1',
+  anthropic: 'https://api.anthropic.com',
+  gemini: 'https://generativelanguage.googleapis.com/v1beta',
+};
+
+/**
+ * Resolve the base URL for a provider.
+ * Checks provider-specific env var override, then falls back to default.
+ * @param {'openai' | 'anthropic' | 'gemini'} provider
+ * @returns {string}
+ */
+export function resolveBaseUrl(provider) {
+  const envVars = {
+    openai: 'ARCHAL_OPENAI_BASE_URL',
+    anthropic: 'ARCHAL_ANTHROPIC_BASE_URL',
+    gemini: 'ARCHAL_GEMINI_BASE_URL',
+  };
+  const override = process.env[envVars[provider]]?.trim();
+  if (override) {
+    // Strip trailing slash for consistency
+    return override.replace(/\/+$/, '');
+  }
+  return DEFAULT_BASE_URLS[provider];
+}
+
+// ── Timeout ─────────────────────────────────────────────────────────
+
+/**
+ * Get the LLM call timeout in milliseconds.
+ * @returns {number}
+ */
+function getLlmTimeoutMs() {
+  const envVal = process.env['ARCHAL_LLM_TIMEOUT'];
+  if (envVal !== undefined && envVal !== '') {
+    const parsed = parseInt(envVal, 10);
+    if (!Number.isNaN(parsed) && parsed > 0) {
+      return parsed * 1000;
+    }
+  }
+  return 120_000; // 120 seconds default
+}
+
+// ── Thinking configuration ──────────────────────────────────────────
+
+/**
+ * Parse the ARCHAL_THINKING_BUDGET env var.
+ * Defaults to "adaptive" (thinking on). Set to "off" to disable.
+ * @returns {null | 'adaptive' | number}
+ */
+function parseThinkingBudget() {
+  const val = process.env['ARCHAL_THINKING_BUDGET']?.trim();
+  if (!val) return 'adaptive'; // thinking on by default
+  if (val.toLowerCase() === 'off' || val === '0') return null;
+  if (val.toLowerCase() === 'adaptive') return 'adaptive';
+  const parsed = parseInt(val, 10);
+  if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+  return 'adaptive';
+}
+
+/**
+ * Build the Anthropic `thinking` request parameter for a model.
+ * Returns null if thinking should not be enabled.
+ *
+ * Opus 4.6: must use { type: "adaptive" } (type: "enabled" is deprecated).
+ * Other Claude models: use { type: "enabled", budget_tokens: N } or { type: "adaptive" }.
+ *
+ * @param {string} model
+ * @returns {object | null}
+ */
+function getAnthropicThinkingParam(model) {
+  if (!isThinkingModel(model)) return null;
+  const budget = parseThinkingBudget();
+  if (budget === null) return null;
+
+  // Opus 4.6 only supports adaptive thinking
+  const isOpus = model.startsWith('claude-opus');
+  if (budget === 'adaptive' || isOpus) {
+    return { type: 'adaptive' };
+  }
+
+  // Other Claude models: explicit budget
+  return { type: 'enabled', budget_tokens: budget };
+}
+
+/**
+ * Build the Gemini thinkingConfig for generationConfig.
+ * Returns null if thinking should not be configured.
+ *
+ * @param {string} model
+ * @returns {object | null}
+ */
+function getGeminiThinkingConfig(model) {
+  if (!isThinkingModel(model)) return null;
+  const budget = parseThinkingBudget();
+  if (budget === null) return null;
+
+  // Gemini 2.5 models think by default. An explicit budget overrides the default.
+  if (typeof budget === 'number') {
+    return { thinkingBudget: budget };
+  }
+  // "adaptive" — let Gemini use its default thinking behavior (no explicit config needed)
+  return null;
+}
+
+/**
+ * Check if extended thinking is enabled for the current run.
+ * @returns {boolean}
+ */
+export function isThinkingEnabled() {
+  return parseThinkingBudget() !== null;
+}
+
+// ── Token usage tracking ────────────────────────────────────────────
+
+/**
+ * @typedef {Object} TokenUsage
+ * @property {number} inputTokens  - Input/prompt tokens used
+ * @property {number} outputTokens - Output/completion tokens used
+ */
+
+/**
+ * @typedef {Object} LlmResponse
+ * @property {object} body  - The raw API response body
+ * @property {TokenUsage} usage - Token usage for this call
+ */
+
+/**
+ * Extract token usage from a provider's response body.
+ * @param {'gemini' | 'anthropic' | 'openai'} provider
+ * @param {object} body
+ * @returns {TokenUsage}
+ */
+export function extractTokenUsage(provider, body) {
+  switch (provider) {
+    case 'gemini': {
+      const meta = body.usageMetadata ?? {};
+      return {
+        inputTokens: meta.promptTokenCount ?? 0,
+        outputTokens: meta.candidatesTokenCount ?? 0,
+      };
+    }
+    case 'anthropic': {
+      const usage = body.usage ?? {};
+      return {
+        inputTokens: usage.input_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? 0,
+      };
+    }
+    case 'openai': {
+      const usage = body.usage ?? {};
+      return {
+        inputTokens: usage.prompt_tokens ?? 0,
+        outputTokens: usage.completion_tokens ?? 0,
+      };
+    }
+    default:
+      return { inputTokens: 0, outputTokens: 0 };
+  }
+}
+
+// ── Tool formatting ─────────────────────────────────────────────────
+
+/**
+ * Convert MCP tool schemas to the format expected by each provider.
+ */
+export function formatToolsForProvider(provider, mcpTools) {
+  switch (provider) {
+    case 'gemini':
+      return [{
+        functionDeclarations: mcpTools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          parameters: t.inputSchema,
+        })),
+      }];
+    case 'openai':
+      return mcpTools.map((t) => ({
+        type: 'function',
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.inputSchema,
+        },
+      }));
+    case 'anthropic':
+      return mcpTools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+      }));
+    default:
+      return mcpTools;
+  }
+}
+
+// ── LLM calling ─────────────────────────────────────────────────────
+
+/**
+ * Call the LLM with the given messages and tools.
+ * Returns an LlmResponse with the raw body and token usage.
+ * @param {'gemini' | 'anthropic' | 'openai'} provider
+ * @param {string} model
+ * @param {string} apiKey
+ * @param {Array | object} messages
+ * @param {Array} tools
+ * @returns {Promise<LlmResponse>}
+ */
+export async function callLlm(provider, model, apiKey, messages, tools) {
+  switch (provider) {
+    case 'gemini':
+      return callGemini(model, apiKey, messages, tools);
+    case 'anthropic':
+      return callAnthropic(model, apiKey, messages, tools);
+    case 'openai':
+      return callOpenAi(model, apiKey, messages, tools);
+    default:
+      return callOpenAi(model, apiKey, messages, tools);
+  }
+}
+
+/**
+ * Make an HTTP request with timeout via AbortController.
+ * @param {string} url
+ * @param {RequestInit} init
+ * @returns {Promise<Response>}
+ */
+async function fetchWithTimeout(url, init) {
+  const timeoutMs = getLlmTimeoutMs();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      throw new LlmApiError('timeout', 0, `LLM call timed out after ${timeoutMs / 1000}s`, null);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function callGemini(model, apiKey, messages, tools) {
+  const baseUrl = resolveBaseUrl('gemini');
+  const url = `${baseUrl}/models/${model}:generateContent?key=${apiKey}`;
+  const config = getModelConfig(model);
+
+  const generationConfig = { maxOutputTokens: config.maxTokens };
+  if (config.temperature !== undefined && !isReasoningModel(model)) {
+    generationConfig.temperature = config.temperature;
+  }
+  const thinkingConfig = getGeminiThinkingConfig(model);
+  if (thinkingConfig) {
+    generationConfig.thinkingConfig = thinkingConfig;
+  }
+
+  const body = {
+    contents: messages,
+    generationConfig,
+  };
+  if (tools && tools.length > 0) {
+    body.tools = tools;
+  }
+  const res = await fetchWithTimeout(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new LlmApiError('Gemini', res.status, text, res.headers);
+  }
+  const responseBody = await res.json();
+  return {
+    body: responseBody,
+    usage: extractTokenUsage('gemini', responseBody),
+  };
+}
+
+async function callAnthropic(model, apiKey, messages, tools) {
+  const baseUrl = resolveBaseUrl('anthropic');
+  const url = `${baseUrl}/v1/messages`;
+  const config = getModelConfig(model);
+  const thinkingParam = getAnthropicThinkingParam(model);
+
+  const reqBody = {
+    model,
+    messages,
+    max_tokens: config.maxTokens,
+  };
+  if (thinkingParam) {
+    reqBody.thinking = thinkingParam;
+    // With thinking enabled, temperature must not be set
+  } else if (config.temperature !== undefined && !isReasoningModel(model)) {
+    reqBody.temperature = config.temperature;
+  }
+  if (tools && tools.length > 0) {
+    reqBody.tools = tools;
+    // With thinking enabled, tool_choice must be "auto" (not a specific tool)
+    if (thinkingParam) {
+      reqBody.tool_choice = { type: 'auto' };
+    }
+  }
+  const res = await fetchWithTimeout(url, {
+    method: 'POST',
+    headers: {
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(reqBody),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new LlmApiError('Anthropic', res.status, text, res.headers);
+  }
+  const responseBody = await res.json();
+  return {
+    body: responseBody,
+    usage: extractTokenUsage('anthropic', responseBody),
+  };
+}
+
+async function callOpenAi(model, apiKey, messages, tools) {
+  const baseUrl = resolveBaseUrl('openai');
+  const url = `${baseUrl}/chat/completions`;
+  const config = getModelConfig(model);
+  const reasoning = isReasoningModel(model);
+
+  const reqBody = { model, messages };
+
+  // Reasoning models use max_completion_tokens and reasoning_effort, not temperature
+  if (reasoning) {
+    reqBody.max_completion_tokens = config.maxTokens;
+    if (config.reasoningEffort) {
+      reqBody.reasoning_effort = config.reasoningEffort;
+    }
+  } else {
+    reqBody.max_completion_tokens = config.maxTokens;
+    if (config.temperature !== undefined) {
+      reqBody.temperature = config.temperature;
+    }
+  }
+
+  if (tools && tools.length > 0) {
+    reqBody.tools = tools;
+    reqBody.tool_choice = 'auto';
+  }
+
+  const res = await fetchWithTimeout(url, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(reqBody),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new LlmApiError('OpenAI', res.status, text, res.headers);
+  }
+  const responseBody = await res.json();
+  return {
+    body: responseBody,
+    usage: extractTokenUsage('openai', responseBody),
+  };
+}
+
+// ── Error handling ──────────────────────────────────────────────────
+
+/**
+ * Structured LLM API error with status code and retry-after support.
+ */
+export class LlmApiError extends Error {
+  /**
+   * @param {string} provider
+   * @param {number} status
+   * @param {string} responseText
+   * @param {Headers | null} [headers]
+   */
+  constructor(provider, status, responseText, headers) {
+    super(`${provider} API error ${status}: ${responseText.slice(0, 500)}`);
+    this.name = 'LlmApiError';
+    this.status = status;
+    this.provider = provider;
+    this.responseText = responseText;
+    this.retryAfterMs = parseRetryAfter(headers);
+  }
+}
+
+/**
+ * Parse the Retry-After header value into milliseconds.
+ * Supports both seconds (integer) and HTTP-date formats.
+ * Returns null if no valid Retry-After header is present.
+ * @param {Headers | null} [headers]
+ * @returns {number | null}
+ */
+function parseRetryAfter(headers) {
+  if (!headers) return null;
+  const value = headers.get?.('retry-after');
+  if (!value) return null;
+
+  // Try as integer (seconds)
+  const seconds = parseInt(value, 10);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return seconds * 1000;
+  }
+
+  // Try as HTTP-date
+  const date = new Date(value);
+  if (!Number.isNaN(date.getTime())) {
+    const delayMs = date.getTime() - Date.now();
+    return Math.max(0, delayMs);
+  }
+
+  return null;
+}
+
+// ── Response parsing ────────────────────────────────────────────────
+
+/**
+ * Parse tool calls from the provider's response.
+ * Returns an array of { id, name, arguments } or null if no tool calls.
+ *
+ * Accepts either a raw response body or an LlmResponse wrapper.
+ */
+export function parseToolCalls(provider, responseOrWrapper) {
+  const response = responseOrWrapper?.body ?? responseOrWrapper;
+  switch (provider) {
+    case 'gemini':
+      return parseGeminiToolCalls(response);
+    case 'anthropic':
+      return parseAnthropicToolCalls(response);
+    case 'openai':
+      return parseOpenAiToolCalls(response);
+    default:
+      return parseOpenAiToolCalls(response);
+  }
+}
+
+function parseGeminiToolCalls(response) {
+  const parts = response.candidates?.[0]?.content?.parts ?? [];
+  const calls = parts
+    .filter((p) => p.functionCall)
+    .map((p) => ({
+      id: p.functionCall.name + '-' + Date.now(),
+      name: p.functionCall.name,
+      arguments: p.functionCall.args ?? {},
+    }));
+  return calls.length > 0 ? calls : null;
+}
+
+function parseAnthropicToolCalls(response) {
+  const content = response.content ?? [];
+  const calls = content
+    .filter((c) => c.type === 'tool_use')
+    .map((c) => ({
+      id: c.id,
+      name: c.name,
+      arguments: c.input ?? {},
+    }));
+  return calls.length > 0 ? calls : null;
+}
+
+function parseOpenAiToolCalls(response) {
+  const message = response.choices?.[0]?.message;
+  if (!message?.tool_calls?.length) return null;
+  return message.tool_calls.map((tc) => ({
+    id: tc.id,
+    name: tc.function.name,
+    arguments: typeof tc.function.arguments === 'string'
+      ? JSON.parse(tc.function.arguments)
+      : tc.function.arguments ?? {},
+  }));
+}
+
+/**
+ * Get the text content from the provider's response (if any).
+ *
+ * Accepts either a raw response body or an LlmResponse wrapper.
+ */
+export function getResponseText(provider, responseOrWrapper) {
+  const response = responseOrWrapper?.body ?? responseOrWrapper;
+  switch (provider) {
+    case 'gemini': {
+      const parts = response.candidates?.[0]?.content?.parts ?? [];
+      // Exclude thinking parts (thought === true) — those go to getThinkingContent()
+      const textParts = parts.filter((p) => p.text && !p.thought).map((p) => p.text);
+      return textParts.join('') || null;
+    }
+    case 'anthropic': {
+      const content = response.content ?? [];
+      const textBlocks = content.filter((c) => c.type === 'text').map((c) => c.text);
+      return textBlocks.join('') || null;
+    }
+    case 'openai': {
+      return response.choices?.[0]?.message?.content ?? null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Extract thinking/reasoning content from the provider's response.
+ * Returns the model's internal reasoning (Anthropic thinking blocks,
+ * Gemini thinking parts) or null if none.
+ *
+ * Note: OpenAI Chat Completions API does NOT expose reasoning content.
+ * Reasoning tokens are hidden. Only the Responses API (not used here)
+ * can surface reasoning summaries.
+ *
+ * @param {'gemini' | 'anthropic' | 'openai'} provider
+ * @param {object} responseOrWrapper
+ * @returns {string | null}
+ */
+export function getThinkingContent(provider, responseOrWrapper) {
+  const response = responseOrWrapper?.body ?? responseOrWrapper;
+  switch (provider) {
+    case 'anthropic': {
+      const content = response.content ?? [];
+      const blocks = content
+        .filter((c) => c.type === 'thinking')
+        .map((c) => c.thinking);
+      return blocks.length > 0 ? blocks.join('\n') : null;
+    }
+    case 'openai': {
+      // Chat Completions API does not expose reasoning content.
+      // OpenAI reasoning tokens are hidden by design.
+      return null;
+    }
+    case 'gemini': {
+      const parts = response.candidates?.[0]?.content?.parts ?? [];
+      const thinkingParts = parts
+        .filter((p) => p.thought === true)
+        .map((p) => p.text);
+      return thinkingParts.length > 0 ? thinkingParts.join('\n') : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Get the stop reason from the provider's response.
+ * @param {'gemini' | 'anthropic' | 'openai'} provider
+ * @param {object} responseOrWrapper
+ * @returns {string | null}
+ */
+export function getStopReason(provider, responseOrWrapper) {
+  const response = responseOrWrapper?.body ?? responseOrWrapper;
+  switch (provider) {
+    case 'gemini':
+      return response.candidates?.[0]?.finishReason ?? null;
+    case 'anthropic':
+      return response.stop_reason ?? null;
+    case 'openai':
+      return response.choices?.[0]?.finish_reason ?? null;
+    default:
+      return null;
+  }
+}
+
+// ── Message formatting ──────────────────────────────────────────────
+
+/**
+ * Build the initial messages array with system prompt and task for the provider.
+ * For reasoning models that don't support system prompts, the system prompt
+ * is prepended to the user message automatically.
+ *
+ * @param {'gemini' | 'anthropic' | 'openai'} provider
+ * @param {string} systemPrompt
+ * @param {string} task
+ * @param {string} [model] - Optional model name for capability checking
+ */
+export function buildInitialMessages(provider, systemPrompt, task, model) {
+  const capabilities = model ? getModelCapabilities(model) : null;
+  const supportsSystem = capabilities ? capabilities.supportsSystemPrompt : true;
+
+  switch (provider) {
+    case 'gemini':
+      return [
+        { role: 'user', parts: [{ text: (systemPrompt ? systemPrompt + '\n\n' : '') + task }] },
+      ];
+    case 'anthropic':
+      return {
+        system: systemPrompt || undefined,
+        messages: [{ role: 'user', content: task }],
+      };
+    case 'openai': {
+      if (!supportsSystem || !systemPrompt) {
+        // Reasoning models (o1, o3, o4) don't support system prompts.
+        // Merge system prompt into user message.
+        const combined = systemPrompt ? systemPrompt + '\n\n' + task : task;
+        return [{ role: 'user', content: combined }];
+      }
+      return [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: task },
+      ];
+    }
+    default:
+      return [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: task },
+      ];
+  }
+}
+
+/**
+ * Append the assistant response to the conversation for the next turn.
+ *
+ * Accepts either a raw response body or an LlmResponse wrapper.
+ */
+export function appendAssistantResponse(provider, messages, responseOrWrapper) {
+  const response = responseOrWrapper?.body ?? responseOrWrapper;
+  switch (provider) {
+    case 'gemini': {
+      const content = response.candidates?.[0]?.content;
+      if (content) messages.push(content);
+      return messages;
+    }
+    case 'anthropic': {
+      messages.messages.push({ role: 'assistant', content: response.content });
+      return messages;
+    }
+    case 'openai': {
+      messages.push(response.choices?.[0]?.message ?? { role: 'assistant', content: '' });
+      return messages;
+    }
+    default:
+      return messages;
+  }
+}
+
+/**
+ * Append tool results to the conversation for the next turn.
+ */
+export function appendToolResults(provider, messages, toolCalls, results) {
+  switch (provider) {
+    case 'gemini': {
+      const parts = toolCalls.map((tc, i) => ({
+        functionResponse: {
+          name: tc.name,
+          response: { content: results[i] },
+        },
+      }));
+      messages.push({ role: 'user', parts });
+      return messages;
+    }
+    case 'anthropic': {
+      const content = toolCalls.map((tc, i) => ({
+        type: 'tool_result',
+        tool_use_id: tc.id,
+        content: results[i],
+      }));
+      messages.messages.push({ role: 'user', content });
+      return messages;
+    }
+    case 'openai': {
+      for (let i = 0; i < toolCalls.length; i++) {
+        messages.push({
+          role: 'tool',
+          tool_call_id: toolCalls[i].id,
+          content: results[i],
+        });
+      }
+      return messages;
+    }
+    default:
+      return messages;
+  }
+}
+
+/**
+ * Extract the messages array and system prompt for the callLlm function.
+ * For Anthropic, the system prompt is separate from messages.
+ */
+export function extractCallArgs(provider, messages) {
+  if (provider === 'anthropic') {
+    return { system: messages.system, messages: messages.messages };
+  }
+  return { messages };
+}
+
+/**
+ * Call the LLM with provider-appropriate message format.
+ * Returns an LlmResponse with body and token usage.
+ * @returns {Promise<LlmResponse>}
+ */
+export async function callLlmWithMessages(provider, model, apiKey, messagesOrWrapper, tools) {
+  if (provider === 'anthropic') {
+    const baseUrl = resolveBaseUrl('anthropic');
+    const url = `${baseUrl}/v1/messages`;
+    const config = getModelConfig(model);
+    const thinkingParam = getAnthropicThinkingParam(model);
+
+    const reqBody = {
+      model,
+      max_tokens: config.maxTokens,
+      messages: messagesOrWrapper.messages,
+    };
+    if (messagesOrWrapper.system) {
+      reqBody.system = messagesOrWrapper.system;
+    }
+    if (thinkingParam) {
+      reqBody.thinking = thinkingParam;
+      // With thinking enabled, temperature must not be set
+    } else if (config.temperature !== undefined && !isReasoningModel(model)) {
+      reqBody.temperature = config.temperature;
+    }
+    if (tools && tools.length > 0) {
+      reqBody.tools = tools;
+      if (thinkingParam) {
+        reqBody.tool_choice = { type: 'auto' };
+      }
+    }
+
+    const res = await fetchWithTimeout(url, {
+      method: 'POST',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(reqBody),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new LlmApiError('Anthropic', res.status, text, res.headers);
+    }
+    const responseBody = await res.json();
+    return {
+      body: responseBody,
+      usage: extractTokenUsage('anthropic', responseBody),
+    };
+  }
+
+  // Gemini and OpenAI use flat message arrays
+  return callLlm(provider, model, apiKey, messagesOrWrapper, tools);
+}
+
+// ── Retry helper ────────────────────────────────────────────────────
+
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 529]);
+
+/**
+ * Retry a function on transient errors with exponential backoff.
+ * Respects Retry-After headers from LlmApiError when available.
+ *
+ * @param {() => Promise<T>} fn
+ * @param {number} [maxRetries=3]
+ * @returns {Promise<T>}
+ * @template T
+ */
+export async function withRetry(fn, maxRetries = 3) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      let isRetryable = false;
+
+      if (err instanceof LlmApiError) {
+        isRetryable = RETRYABLE_STATUS_CODES.has(err.status);
+        // Also retry on timeouts
+        if (err.status === 0 && err.message.includes('timed out')) {
+          isRetryable = true;
+        }
+      } else if (err.message) {
+        // Fallback: parse status from error message for backward compat
+        const statusMatch = err.message.match(/error (\d+)/);
+        if (statusMatch) {
+          isRetryable = RETRYABLE_STATUS_CODES.has(parseInt(statusMatch[1], 10));
+        }
+        if (err.message.includes('timed out')) {
+          isRetryable = true;
+        }
+      }
+
+      if (!isRetryable || attempt === maxRetries) throw err;
+
+      // Use retry-after header if available, otherwise exponential backoff
+      let delay;
+      if (err instanceof LlmApiError && err.retryAfterMs !== null) {
+        delay = err.retryAfterMs;
+        // Cap retry-after at 60 seconds to avoid unreasonable waits
+        delay = Math.min(delay, 60_000);
+      } else {
+        // Exponential backoff: 1s, 2s, 4s, 8s, 16s (capped at 30s)
+        delay = Math.min(1000 * Math.pow(2, attempt), 30_000);
+      }
+
+      // Add jitter: +/- 20%
+      const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+      delay = Math.max(0, Math.round(delay + jitter));
+
+      process.stderr.write(
+        `[retry] Attempt ${attempt + 1}/${maxRetries} failed` +
+        `${err.status ? ` (${err.status})` : ''}, ` +
+        `retrying in ${(delay / 1000).toFixed(1)}s...\n`
+      );
+
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+}