@archal/cli 0.7.12 → 0.8.0

package/dist/harnesses/_lib/providers.mjs

@@ -0,0 +1,1083 @@
+/**
+ * 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 180)
+ *   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) {
+  const normalized = String(model ?? '').toLowerCase();
+  if (normalized.startsWith('gemini-')) return 'gemini';
+  if (
+    normalized.startsWith('claude-')
+    || normalized.startsWith('sonnet-')
+    || normalized.startsWith('haiku-')
+    || normalized.startsWith('opus-')
+  ) return 'anthropic';
+  if (
+    normalized.startsWith('gpt-') ||
+    /^o[134]/.test(normalized)
+  ) 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',
+};
+
+function inferKeyProvider(key) {
+  if (!key) return null;
+  if (key.startsWith('AIza')) return 'gemini';
+  if (key.startsWith('sk-ant-')) return 'anthropic';
+  if (key.startsWith('sk-')) return 'openai';
+  return null;
+}
+
+/**
+ * Resolve the API key for the detected provider.
+ * Priority: ARCHAL_ENGINE_API_KEY > provider-specific env var.
+ * If ARCHAL_ENGINE_API_KEY clearly belongs to a different provider, fall back
+ * to provider-specific key when available, otherwise fail with a clear error.
+ * @param {string} provider
+ * @returns {string}
+ */
+export function resolveApiKey(provider) {
+  const envVar = PROVIDER_ENV_VARS[provider] ?? 'OPENAI_API_KEY';
+  const providerKey = process.env[envVar]?.trim();
+  const engineKey = process.env['ARCHAL_ENGINE_API_KEY']?.trim();
+  if (engineKey) {
+    const inferred = inferKeyProvider(engineKey);
+    if (!inferred || inferred === provider) return engineKey;
+    if (providerKey) {
+      process.stderr.write(
+        `[harness] Warning: ARCHAL_ENGINE_API_KEY appears to be for ${inferred}; using ${envVar} for ${provider} model.\n`,
+      );
+      return providerKey;
+    }
+    throw new Error(
+      `ARCHAL_ENGINE_API_KEY appears to be for ${inferred}, but provider "${provider}" requires ${envVar}. ` +
+      `Set ${envVar} or use a ${inferred} model.`
+    );
+  }
+  if (providerKey) return providerKey;
+
+  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 180_000; // 180 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;
+
+  // Only 4.6 series models support adaptive thinking.
+  // Older models (claude-sonnet-4-20250514, claude-haiku-4-5-20251001) need
+  // { type: "enabled", budget_tokens: N } — "adaptive" returns a 400 error.
+  const normalized = String(model ?? '').toLowerCase();
+  const supportsAdaptive = normalized.includes('-4-6') || normalized.includes('4-6-');
+  const isOpus = normalized.startsWith('claude-opus') || normalized.startsWith('opus-');
+
+  if (isOpus || (supportsAdaptive && budget === 'adaptive')) {
+    return { type: 'adaptive' };
+  }
+
+  if (budget === 'adaptive') {
+    // For non-4.6 models with default "adaptive" budget, use a sensible fixed budget
+    return { type: 'enabled', budget_tokens: 10000 };
+  }
+
+  // Explicit numeric 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 {
+        // Responses API uses input_tokens/output_tokens; Chat Completions uses prompt/completion tokens.
+        inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0,
+        outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0,
+      };
+    }
+    default:
+      return { inputTokens: 0, outputTokens: 0 };
+  }
+}
+
+// ── Tool formatting ─────────────────────────────────────────────────
+
+/**
+ * Recursively strip JSON Schema keywords that the Gemini API rejects.
+ * Gemini does not support: additionalProperties, $schema, anyOf, oneOf, allOf.
+ */
+function sanitizeSchemaForGemini(schema) {
+  if (!schema || typeof schema !== 'object') return schema;
+  if (Array.isArray(schema)) return schema.map(sanitizeSchemaForGemini);
+
+  const cleaned = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === 'additionalProperties' || key === '$schema') continue;
+    // Gemini doesn't support anyOf/oneOf/allOf — flatten single-element unions,
+    // otherwise drop the keyword entirely (Gemini treats it as unknown).
+    if (key === 'anyOf' || key === 'oneOf' || key === 'allOf') {
+      if (Array.isArray(value) && value.length === 1) {
+        Object.assign(cleaned, sanitizeSchemaForGemini(value[0]));
+      }
+      // Multi-element unions are unsupported; skip the keyword
+      continue;
+    }
+    cleaned[key] = sanitizeSchemaForGemini(value);
+  }
+  return cleaned;
+}
+
+/**
+ * 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: sanitizeSchemaForGemini(t.inputSchema),
+        })),
+      }];
+    case 'openai':
+      return mcpTools.map((t) => ({
+        type: '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),
+  };
+}
+
+function isGpt5SeriesModel(model) {
+  return model.startsWith('gpt-5');
+}
+
+function shouldSendOpenAiTemperature(model) {
+  return !isReasoningModel(model) && !isGpt5SeriesModel(model);
+}
+
+function normalizeOpenAiConversation(messages) {
+  if (Array.isArray(messages)) {
+    return {
+      input: messages,
+      previousResponseId: undefined,
+    };
+  }
+  if (!messages || typeof messages !== 'object') {
+    return {
+      input: [],
+      previousResponseId: undefined,
+    };
+  }
+  return {
+    input: Array.isArray(messages.input) ? messages.input : [],
+    previousResponseId: typeof messages.previousResponseId === 'string'
+      ? messages.previousResponseId
+      : undefined,
+  };
+}
+
+async function callOpenAi(model, apiKey, messages, tools) {
+  const baseUrl = resolveBaseUrl('openai');
+  const url = `${baseUrl}/responses`;
+  const config = getModelConfig(model);
+  const conversation = normalizeOpenAiConversation(messages);
+
+  const reqBody = {
+    model,
+    input: conversation.input,
+    max_output_tokens: config.maxTokens,
+  };
+
+  if (conversation.previousResponseId) {
+    reqBody.previous_response_id = conversation.previousResponseId;
+  }
+
+  if (config.reasoningEffort && (isReasoningModel(model) || isGpt5SeriesModel(model))) {
+    reqBody.reasoning = { effort: config.reasoningEffort };
+  }
+
+  // GPT-5 series rejects temperature in many variants; never send it for gpt-5*.
+  if (shouldSendOpenAiTemperature(model) && 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 output = Array.isArray(response.output) ? response.output : [];
+  const calls = [];
+  for (const item of output) {
+    if (item?.type !== 'function_call') continue;
+
+    let parsedArguments = {};
+    if (typeof item.arguments === 'string' && item.arguments.trim()) {
+      try {
+        parsedArguments = JSON.parse(item.arguments);
+      } catch {
+        parsedArguments = { _raw: item.arguments };
+      }
+    } else if (item.arguments && typeof item.arguments === 'object') {
+      parsedArguments = item.arguments;
+    }
+
+    calls.push({
+      id: item.call_id ?? item.id ?? `${item.name ?? 'tool'}-${Date.now()}`,
+      name: item.name,
+      arguments: parsedArguments,
+    });
+  }
+
+  return calls.length > 0 ? calls : null;
+}
+
+/**
+ * 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': {
+      if (typeof response.output_text === 'string' && response.output_text.trim()) {
+        return response.output_text;
+      }
+      const output = Array.isArray(response.output) ? response.output : [];
+      const chunks = [];
+      for (const item of output) {
+        if (item?.type === 'output_text' && typeof item.text === 'string') {
+          chunks.push(item.text);
+          continue;
+        }
+        if (item?.type !== 'message' || !Array.isArray(item.content)) continue;
+        for (const part of item.content) {
+          if ((part?.type === 'output_text' || part?.type === 'text') && typeof part.text === 'string') {
+            chunks.push(part.text);
+          }
+        }
+      }
+      return chunks.join('') || 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.
+ *
+ * @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': {
+      const output = Array.isArray(response.output) ? response.output : [];
+      const summaries = [];
+      for (const item of output) {
+        if (item?.type !== 'reasoning') continue;
+        if (Array.isArray(item.summary)) {
+          for (const summary of item.summary) {
+            if (typeof summary?.text === 'string' && summary.text.trim()) {
+              summaries.push(summary.text);
+            }
+          }
+        }
+      }
+      return summaries.length > 0 ? summaries.join('\n') : 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 parseOpenAiToolCalls(response) ? 'tool_calls' : (response.status ?? response.incomplete_details?.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': {
+      let input;
+      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;
+        input = [{ role: 'user', content: combined }];
+      } else {
+        input = [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: task },
+        ];
+      }
+      return {
+        input,
+        previousResponseId: undefined,
+      };
+    }
+    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': {
+      if (Array.isArray(messages)) {
+        const text = getResponseText('openai', response);
+        messages.push({ role: 'assistant', content: text ?? '' });
+        return messages;
+      }
+      messages.previousResponseId = response.id ?? messages.previousResponseId;
+      messages.input = [];
+      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': {
+      const toolOutputs = [];
+      for (let i = 0; i < toolCalls.length; i++) {
+        const output = typeof results[i] === 'string'
+          ? results[i]
+          : JSON.stringify(results[i]);
+        toolOutputs.push({
+          type: 'function_call_output',
+          call_id: toolCalls[i].id,
+          output,
+        });
+      }
+
+      if (Array.isArray(messages)) {
+        for (let i = 0; i < toolCalls.length; i++) {
+          messages.push({
+            role: 'tool',
+            tool_call_id: toolCalls[i].id,
+            content: toolOutputs[i].output,
+          });
+        }
+        return messages;
+      }
+
+      messages.input = toolOutputs;
+      return messages;
+    }
+    default:
+      return messages;
+  }
+}
+
+/**
+ * Append a plain-text user instruction for the next turn.
+ * Used for harness-level recovery nudges (for example, when the model
+ * responds without any tool calls before taking required actions).
+ *
+ * @param {'gemini' | 'anthropic' | 'openai'} provider
+ * @param {Array | object} messages
+ * @param {string} text
+ * @returns {Array | object}
+ */
+export function appendUserInstruction(provider, messages, text) {
+  switch (provider) {
+    case 'gemini': {
+      messages.push({ role: 'user', parts: [{ text }] });
+      return messages;
+    }
+    case 'anthropic': {
+      messages.messages.push({ role: 'user', content: text });
+      return messages;
+    }
+    case 'openai': {
+      if (Array.isArray(messages)) {
+        messages.push({ role: 'user', content: text });
+        return messages;
+      }
+      const nextInput = Array.isArray(messages.input) ? [...messages.input] : [];
+      nextInput.push({ role: 'user', content: text });
+      messages.input = nextInput;
+      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 uses flat message arrays; OpenAI accepts either arrays or wrapper state.
+  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, then message body, then exponential backoff
+      let delay;
+      if (err instanceof LlmApiError && err.retryAfterMs !== null) {
+        delay = err.retryAfterMs;
+        // Cap retry-after at 90 seconds to avoid unreasonable waits
+        delay = Math.min(delay, 90_000);
+      } else if (err instanceof LlmApiError && err.status === 429) {
+        // OpenAI embeds wait time in the message body for TPM limits when
+        // no Retry-After header is present (e.g. batch/embedding endpoints):
+        // "Please try again in 14.902s."
+        const bodyMatch = err.responseText.match(/try again in (\d+(?:\.\d+)?)\s*s/i);
+        if (bodyMatch) {
+          delay = Math.ceil(parseFloat(bodyMatch[1]) * 1000) + 500; // +500ms buffer
+          delay = Math.min(delay, 90_000);
+        } else {
+          // Exponential backoff: 5s, 10s, 20s, 40s (capped at 60s) for 429
+          delay = Math.min(5000 * Math.pow(2, attempt), 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));
+    }
+  }
+}