@thispointon/kondi-chat 0.1.2

package/src/providers/llm-caller.ts

@@ -0,0 +1,943 @@
+/**
+ * Multi-provider LLM caller — direct HTTP, no SDKs.
+ *
+ * Supports:
+ * - Simple single-turn (systemPrompt + userMessage)
+ * - Multi-turn with tool use (messages array + tools)
+ * - Anthropic, OpenAI-compatible, and Gemini providers
+ */
+
+import type {
+  ProviderId, LLMRequest, LLMResponse,
+  ToolDefinition, ToolCall, LLMMessage,
+} from '../types.ts';
+import { getRateLimiter, RateLimitOverflowError } from './rate-limiter.ts';
+import { estimateTokens } from '../context/budget.ts';
+import { LlmCallError, type ErrorSeverity } from '../engine/errors.ts';
+
+/**
+ * Classify an HTTP status as recoverable (worth retrying) vs. fatal.
+ * 5xx + throttling codes are recoverable; everything else is treated as
+ * a hard failure (wrong key, bad request, unknown model, …).
+ */
+function severityForStatus(status: number): ErrorSeverity {
+  if (status === 429) return 'recoverable';
+  if (status >= 500 && status < 600) return 'recoverable';
+  return 'fatal';
+}
+
+// ---------------------------------------------------------------------------
+// SSE stream parser
+// ---------------------------------------------------------------------------
+
+async function* parseSSE(resp: Response): AsyncGenerator<{ type?: string; data?: any }> {
+  const reader = resp.body?.getReader();
+  if (!reader) return;
+
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let eventType: string | undefined;
+  let dataLines: string[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+          // Blank line = end of SSE event
+          if (dataLines.length > 0) {
+            const joined = dataLines.join('\n');
+            let parsed: any;
+            try {
+              parsed = JSON.parse(joined);
+            } catch {
+              parsed = joined;
+            }
+            yield { type: eventType, data: parsed };
+          }
+          eventType = undefined;
+          dataLines = [];
+        } else if (trimmed.startsWith('event:') || trimmed.startsWith('event :')) {
+          eventType = trimmed.replace(/^event\s*:\s*/, '');
+        } else if (trimmed.startsWith('data:') || trimmed.startsWith('data :')) {
+          const raw = trimmed.replace(/^data\s*:\s*/, '');
+          if (raw === '[DONE]') continue;
+          dataLines.push(raw);
+        }
+        // Ignore other lines (comments starting with :, id:, retry:, etc.)
+      }
+    }
+
+    // Flush any remaining event at end of stream
+    if (dataLines.length > 0) {
+      const joined = dataLines.join('\n');
+      let parsed: any;
+      try {
+        parsed = JSON.parse(joined);
+      } catch {
+        parsed = joined;
+      }
+      yield { type: eventType, data: parsed };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DeepSeek JSON sanitizer
+// ---------------------------------------------------------------------------
+
+/**
+ * DeepSeek's JSON body parser is stricter than OpenAI/Anthropic — it
+ * interprets `\x` inside JSON string values as a hex escape and fails
+ * if the hex digits are missing or invalid. This happens when file
+ * content containing ANSI escape codes (e.g. `\x1b[31m`) or other
+ * `\xNN` sequences is embedded in the conversation context.
+ *
+ * JSON.stringify already escapes backslashes to `\\`, so the JSON
+ * contains `\\x1b` (literal backslash + x + 1 + b). But DeepSeek
+ * appears to double-parse the string, treating `\x` as a hex escape.
+ *
+ * Fix: replace `\\x` with `\\\\x` so after DeepSeek's extra parse
+ * pass it becomes the literal `\x` the model sees. Also strip null
+ * bytes and other control chars that can corrupt JSON parsing.
+ */
+function sanitizeJsonForDeepSeek(json: string): string {
+  return json
+    // \\x (escaped backslash + x) → \\\\x (double-escaped)
+    .replace(/\\\\x/g, '\\\\\\\\x')
+    // Bare control characters that snuck through (shouldn't happen
+    // with JSON.stringify, but belt-and-suspenders)
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
+}
+
+// ---------------------------------------------------------------------------
+// Default models per provider
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_MODELS: Record<ProviderId, string> = {
+  'anthropic': 'claude-sonnet-4-5-20250929',
+  'openai': 'gpt-4o',
+  'deepseek': 'deepseek-chat',
+  'google': 'models/gemini-2.5-flash',
+  'xai': 'grok-3',
+  'zai': 'glm-4.6',
+  'ollama': 'llama3.1',
+  'nvidia-router': 'auto',
+};
+
+// ---------------------------------------------------------------------------
+// API key resolution
+// ---------------------------------------------------------------------------
+
+function getApiKey(provider: ProviderId): string | undefined {
+  switch (provider) {
+    case 'anthropic': return process.env.ANTHROPIC_API_KEY;
+    case 'openai': return process.env.OPENAI_API_KEY;
+    case 'deepseek': return process.env.DEEPSEEK_API_KEY;
+    case 'xai': return process.env.XAI_API_KEY;
+    case 'zai': return process.env.ZAI_API_KEY;
+    case 'google': return process.env.GOOGLE_API_KEY;
+    case 'nvidia-router': return process.env.NVIDIA_API_KEY;
+    default: return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic
+// ---------------------------------------------------------------------------
+
+async function callAnthropic(
+  apiKey: string,
+  model: string,
+  req: LLMRequest,
+): Promise<LLMResponse> {
+  const start = Date.now();
+
+  const systemContent: Array<{ type: string; text: string; cache_control?: { type: string } }> = [];
+  if (req.cacheablePrefix) {
+    systemContent.push({
+      type: 'text',
+      text: req.cacheablePrefix,
+      cache_control: { type: 'ephemeral' },
+    });
+  }
+  systemContent.push({ type: 'text', text: req.systemPrompt });
+
+  let messages: any[];
+  if (req.messages) {
+    messages = anthropicMessages(req.messages);
+  } else {
+    messages = [{ role: 'user', content: req.userMessage || '' }];
+  }
+
+  const tools = req.tools?.map(t => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.parameters,
+  }));
+
+  const body: any = {
+    model,
+    max_tokens: req.maxOutputTokens ?? 8192,
+    system: systemContent,
+    messages,
+    ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
+    ...(tools ? { tools } : {}),
+    ...(req.stream ? { stream: true } : {}),
+  };
+
+  const resp = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'anthropic-version': '2023-06-01',
+      'anthropic-beta': 'prompt-caching-2024-07-31',
+      'x-api-key': apiKey,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new LlmCallError(
+      `Anthropic API ${resp.status}: ${text.substring(0, 500)}`,
+      { provider: 'anthropic', model, status: resp.status, severity: severityForStatus(resp.status) },
+    );
+  }
+
+  // Streaming path
+  if (req.stream && req.onToken) {
+    let content = '';
+    let reasoningContent = '';
+    const toolCalls: ToolCall[] = [];
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cached = false;
+    let cachedInputTokens = 0;
+
+    // Track tool_use blocks being built
+    let currentToolId = '';
+    let currentToolName = '';
+    let currentToolJson = '';
+    let inThinkingBlock = false;
+
+    for await (const event of parseSSE(resp)) {
+      try {
+      if (event.type === 'message_start') {
+        const usage = event.data?.message?.usage;
+        if (usage) {
+          inputTokens = usage.input_tokens || 0;
+          cachedInputTokens = usage.cache_read_input_tokens || 0;
+          cached = cachedInputTokens > 0;
+        }
+      } else if (event.type === 'content_block_start') {
+        const block = event.data?.content_block;
+        if (block?.type === 'tool_use') {
+          currentToolId = block.id;
+          currentToolName = block.name;
+          currentToolJson = '';
+        } else if (block?.type === 'thinking') {
+          inThinkingBlock = true;
+          if (block.thinking) reasoningContent += block.thinking;
+        }
+      } else if (event.type === 'content_block_delta') {
+        const delta = event.data?.delta;
+        if (delta?.type === 'text_delta' && delta.text) {
+          content += delta.text;
+          req.onToken(delta.text);
+        } else if (delta?.type === 'input_json_delta' && delta.partial_json) {
+          currentToolJson += delta.partial_json;
+        } else if (delta?.type === 'thinking_delta' && delta.thinking) {
+          reasoningContent += delta.thinking;
+        }
+      } else if (event.type === 'content_block_stop') {
+        if (inThinkingBlock) {
+          inThinkingBlock = false;
+        }
+        if (currentToolId) {
+          try {
+            toolCalls.push({
+              id: currentToolId,
+              name: currentToolName,
+              arguments: currentToolJson ? JSON.parse(currentToolJson) : {},
+            });
+          } catch {
+            toolCalls.push({ id: currentToolId, name: currentToolName, arguments: {} });
+          }
+          currentToolId = '';
+          currentToolName = '';
+          currentToolJson = '';
+        }
+      } else if (event.type === 'message_delta') {
+        const usage = event.data?.usage;
+        if (usage) outputTokens = usage.output_tokens || 0;
+      }
+      } catch { /* skip malformed SSE event */ }
+    }
+
+    return {
+      content, model, provider: 'anthropic',
+      inputTokens, outputTokens,
+      latencyMs: Date.now() - start, cached,
+      ...(cachedInputTokens > 0 ? { cachedInputTokens } : {}),
+      ...(toolCalls.length > 0 ? { toolCalls } : {}),
+      ...(reasoningContent ? { reasoningContent } : {}),
+    };
+  }
+
+  // Non-streaming path
+  const data: any = await resp.json();
+  const usage = data.usage || {};
+
+  let content = '';
+  let reasoningContent = '';
+  const toolCalls: ToolCall[] = [];
+
+  for (const block of data.content || []) {
+    if (block.type === 'text') {
+      content += block.text;
+    } else if (block.type === 'thinking') {
+      reasoningContent += block.thinking || '';
+    } else if (block.type === 'tool_use') {
+      toolCalls.push({
+        id: block.id,
+        name: block.name,
+        arguments: block.input || {},
+      });
+    }
+  }
+
+  return {
+    content, model, provider: 'anthropic',
+    inputTokens: usage.input_tokens || 0,
+    outputTokens: usage.output_tokens || 0,
+    latencyMs: Date.now() - start,
+    cached: (usage.cache_read_input_tokens || 0) > 0,
+    ...((usage.cache_read_input_tokens || 0) > 0 ? { cachedInputTokens: usage.cache_read_input_tokens } : {}),
+    ...(toolCalls.length > 0 ? { toolCalls } : {}),
+    ...(reasoningContent ? { reasoningContent } : {}),
+  };
+}
+
+/** Convert abstract LLMMessage[] to Anthropic message format */
+function anthropicMessages(messages: LLMMessage[]): any[] {
+  const result: any[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      result.push({ role: 'user', content: msg.content || '' });
+    } else if (msg.role === 'assistant') {
+      // Assistant message may have text + tool_use blocks
+      const content: any[] = [];
+      if (msg.content) {
+        content.push({ type: 'text', text: msg.content });
+      }
+      if (msg.toolCalls) {
+        for (const tc of msg.toolCalls) {
+          content.push({
+            type: 'tool_use',
+            id: tc.id,
+            name: tc.name,
+            input: tc.arguments,
+          });
+        }
+      }
+      result.push({ role: 'assistant', content });
+    } else if (msg.role === 'tool') {
+      // Anthropic: tool results are sent as user messages with tool_result content blocks
+      const content: any[] = [];
+      if (msg.toolResults) {
+        for (const tr of msg.toolResults) {
+          content.push({
+            type: 'tool_result',
+            tool_use_id: tr.toolCallId,
+            content: tr.content,
+            ...(tr.isError ? { is_error: true } : {}),
+          });
+        }
+      }
+      result.push({ role: 'user', content });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI-compatible (OpenAI, DeepSeek, xAI, NVIDIA router, Ollama)
+// ---------------------------------------------------------------------------
+
+async function callOpenAICompatible(
+  baseUrl: string,
+  apiKey: string,
+  model: string,
+  provider: ProviderId,
+  req: LLMRequest,
+): Promise<LLMResponse> {
+  const start = Date.now();
+
+  const systemContent = req.cacheablePrefix
+    ? `${req.cacheablePrefix}\n\n${req.systemPrompt}`
+    : req.systemPrompt;
+
+  // Messages — multi-turn or single-turn
+  let messages: any[];
+  if (req.messages) {
+    messages = [
+      { role: 'system', content: systemContent },
+      ...openaiMessages(req.messages),
+    ];
+  } else {
+    messages = [
+      { role: 'system', content: systemContent },
+      { role: 'user', content: req.userMessage || '' },
+    ];
+  }
+
+  // Tools
+  const tools = req.tools?.map(t => ({
+    type: 'function' as const,
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  }));
+
+  const max = req.maxOutputTokens ?? 8192;
+  const body: any = {
+    model,
+    messages,
+    ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
+    ...(tools ? { tools } : {}),
+    ...(req.stream ? { stream: true } : {}),
+  };
+
+  if (provider === 'openai') {
+    body.max_completion_tokens = max; // new OpenAI param
+  } else {
+    body.max_tokens = max; // legacy / compatible providers
+  }
+
+  // DeepSeek's JSON parser is stricter than most — it rejects bare \x
+  // hex escapes and broken \u sequences that appear in file content
+  // (ANSI codes, binary fragments, CSV artifacts). Sanitize the body
+  // JSON string to replace these with safe placeholders.
+  let bodyJson = JSON.stringify(body);
+  if (provider === 'deepseek') {
+    bodyJson = sanitizeJsonForDeepSeek(bodyJson);
+  }
+
+  const resp = await fetch(`${baseUrl}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: bodyJson,
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new LlmCallError(
+      `${provider} API ${resp.status}: ${text.substring(0, 500)}`,
+      { provider, model, status: resp.status, severity: severityForStatus(resp.status) },
+    );
+  }
+
+  // Streaming path
+  if (req.stream && req.onToken) {
+    let content = '';
+    let reasoningContent = '';
+    const toolCalls: ToolCall[] = [];
+    const toolJsonBuffers: Map<number, { id: string; name: string; json: string }> = new Map();
+    let actualModel = model;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cachedInputTokens = 0;
+
+    for await (const event of parseSSE(resp)) {
+      if (!event.data || event.data === '[DONE]') continue;
+
+      let chunk: any;
+      try {
+        if (typeof event.data === 'string') {
+          const raw = event.data.trim();
+          const clean = raw.startsWith('data:') ? raw.slice(5).trim() : raw;
+          chunk = JSON.parse(clean);
+        } else {
+          chunk = event.data;
+        }
+      } catch {
+        continue; // Skip unparseable chunks
+      }
+      if (chunk.model) actualModel = chunk.model;
+
+      const delta = chunk.choices?.[0]?.delta;
+      if (!delta) continue;
+
+      // Text content
+      if (delta.content) {
+        content += delta.content;
+        req.onToken(delta.content);
+      }
+
+      // Reasoning content (z.ai GLM-5.x, OpenAI o-series, DeepSeek-R1, Ollama Qwopus).
+      // Ollama uses `delta.reasoning`; others use `delta.reasoning_content`.
+      const reasoning = delta.reasoning_content || delta.reasoning;
+      if (reasoning) {
+        reasoningContent += reasoning;
+      }
+
+      // Tool calls (streamed incrementally)
+      if (delta.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index ?? 0;
+          if (tc.id) {
+            toolJsonBuffers.set(idx, { id: tc.id, name: tc.function?.name || '', json: '' });
+          }
+          const buf = toolJsonBuffers.get(idx);
+          if (buf && tc.function?.arguments) {
+            buf.json += tc.function.arguments;
+          }
+        }
+      }
+
+      // Usage (some providers send this in the final chunk)
+      if (chunk.usage) {
+        inputTokens = chunk.usage.prompt_tokens || 0;
+        outputTokens = chunk.usage.completion_tokens || 0;
+        cachedInputTokens = chunk.usage.prompt_tokens_details?.cached_tokens || 0;
+      }
+    }
+
+    // Finalize tool calls
+    for (const buf of toolJsonBuffers.values()) {
+      try {
+        toolCalls.push({ id: buf.id, name: buf.name, arguments: buf.json ? JSON.parse(buf.json) : {} });
+      } catch {
+        toolCalls.push({ id: buf.id, name: buf.name, arguments: {} });
+      }
+    }
+
+    return {
+      content, model: actualModel, provider,
+      inputTokens, outputTokens,
+      latencyMs: Date.now() - start,
+      ...(cachedInputTokens > 0 ? { cachedInputTokens, cached: true } : {}),
+      ...(toolCalls.length > 0 ? { toolCalls } : {}),
+      ...(reasoningContent ? { reasoningContent } : {}),
+    };
+  }
+
+  // Non-streaming path
+  const data: any = await resp.json();
+  const choice = data.choices?.[0]?.message || {};
+  const usage = data.usage || {};
+  const cachedInputTokensNs = usage.prompt_tokens_details?.cached_tokens || 0;
+  const actualModel = data.model || model;
+
+  const toolCalls: ToolCall[] = [];
+  if (choice.tool_calls) {
+    for (const tc of choice.tool_calls) {
+      toolCalls.push({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: typeof tc.function.arguments === 'string'
+          ? JSON.parse(tc.function.arguments)
+          : tc.function.arguments,
+      });
+    }
+  }
+
+  return {
+    content: choice.content || '',
+    model: actualModel,
+    provider,
+    inputTokens: usage.prompt_tokens || 0,
+    outputTokens: usage.completion_tokens || 0,
+    latencyMs: Date.now() - start,
+    ...(cachedInputTokensNs > 0 ? { cachedInputTokens: cachedInputTokensNs, cached: true } : {}),
+    ...(toolCalls.length > 0 ? { toolCalls } : {}),
+    ...((choice.reasoning_content || choice.reasoning) ? { reasoningContent: choice.reasoning_content || choice.reasoning } : {}),
+  };
+}
+
+/** Convert abstract LLMMessage[] to OpenAI message format */
+function openaiMessages(messages: LLMMessage[]): any[] {
+  const result: any[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      result.push({ role: 'user', content: msg.content || '' });
+    } else if (msg.role === 'assistant') {
+      const entry: any = { role: 'assistant' };
+      if (msg.content) entry.content = msg.content;
+      // DeepSeek requires reasoning_content to be passed back in multi-turn.
+      if (msg.reasoningContent) entry.reasoning_content = msg.reasoningContent;
+      if (msg.toolCalls) {
+        entry.tool_calls = msg.toolCalls.map(tc => ({
+          id: tc.id,
+          type: 'function',
+          function: {
+            name: tc.name,
+            arguments: JSON.stringify(tc.arguments),
+          },
+        }));
+      }
+      result.push(entry);
+    } else if (msg.role === 'tool') {
+      // OpenAI: each tool result is a separate message with role: 'tool'
+      if (msg.toolResults) {
+        for (const tr of msg.toolResults) {
+          result.push({
+            role: 'tool',
+            tool_call_id: tr.toolCallId,
+            content: tr.content,
+          });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Gemini
+// ---------------------------------------------------------------------------
+
+async function callGemini(
+  apiKey: string,
+  model: string,
+  req: LLMRequest,
+): Promise<LLMResponse> {
+  const start = Date.now();
+
+  const systemText = req.cacheablePrefix
+    ? `${req.cacheablePrefix}\n\n${req.systemPrompt}`
+    : req.systemPrompt;
+
+  // Gemini tool use: function_declarations
+  const tools = req.tools ? [{
+    function_declarations: req.tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    })),
+  }] : undefined;
+
+  // Messages — multi-turn or single-turn
+  let contents: any[];
+  if (req.messages) {
+    contents = geminiMessages(req.messages);
+  } else {
+    contents = [{ role: 'user', parts: [{ text: req.userMessage || '' }] }];
+  }
+
+  const body: any = {
+    system_instruction: { parts: [{ text: systemText }] },
+    contents,
+    generationConfig: {
+      maxOutputTokens: req.maxOutputTokens ?? 8192,
+      ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
+    },
+    ...(tools ? { tools } : {}),
+  };
+
+  const resp = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/${model}:generateContent?key=${apiKey}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    },
+  );
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new LlmCallError(
+      `Gemini API ${resp.status}: ${text.substring(0, 500)}`,
+      { provider: 'google', model, status: resp.status, severity: severityForStatus(resp.status) },
+    );
+  }
+
+  const data: any = await resp.json();
+  const usage = data.usageMetadata || {};
+
+  let content = '';
+  const toolCalls: ToolCall[] = [];
+
+  const parts = data.candidates?.[0]?.content?.parts || [];
+  for (const part of parts) {
+    if (part.text) {
+      content += part.text;
+    } else if (part.functionCall) {
+      toolCalls.push({
+        id: `gemini-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        name: part.functionCall.name,
+        arguments: part.functionCall.args || {},
+      });
+    }
+  }
+
+  return {
+    content,
+    model,
+    provider: 'google',
+    inputTokens: usage.promptTokenCount || 0,
+    outputTokens: usage.candidatesTokenCount || 0,
+    latencyMs: Date.now() - start,
+    ...(toolCalls.length > 0 ? { toolCalls } : {}),
+  };
+}
+
+/** Convert abstract LLMMessage[] to Gemini contents format */
+function geminiMessages(messages: LLMMessage[]): any[] {
+  const result: any[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      result.push({ role: 'user', parts: [{ text: msg.content || '' }] });
+    } else if (msg.role === 'assistant') {
+      const parts: any[] = [];
+      if (msg.content) parts.push({ text: msg.content });
+      if (msg.toolCalls) {
+        for (const tc of msg.toolCalls) {
+          parts.push({
+            functionCall: { name: tc.name, args: tc.arguments },
+          });
+        }
+      }
+      result.push({ role: 'model', parts });
+    } else if (msg.role === 'tool') {
+      // Gemini: functionResponse parts
+      const parts: any[] = [];
+      if (msg.toolResults) {
+        for (const tr of msg.toolResults) {
+          parts.push({
+            functionResponse: {
+              name: tr.toolCallId, // Gemini uses name, not id
+              response: { content: tr.content },
+            },
+          });
+        }
+      }
+      result.push({ role: 'function', parts });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Unified router
+// ---------------------------------------------------------------------------
+
+const MAX_RETRIES = 2;
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504, 529]);
+// Per-call LLM timeout. Reasoning models (GLM-5.x, o-series, R1) routinely
+// burn 60–180s of hidden CoT before producing a visible byte, so the cap
+// has to accommodate them. Non-reasoning models still return in seconds;
+// raising the ceiling just removes a false-positive timeout, it doesn't
+// slow anything down.
+// Spec 13 — per-call timeout and per-turn wall-clock cap.
+const LLM_TIMEOUT_MS = 240_000;
+const TURN_WALL_CLOCK_MS = 600_000;
+
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timeout after ${ms}ms`)), ms);
+    p.then(v => { clearTimeout(timer); resolve(v); },
+           e => { clearTimeout(timer); reject(e); });
+  });
+}
+
+function parseRetryAfter(msg: string): number | null {
+  const m = msg.match(/retry[- ]?after[^0-9]*(\d+)/i);
+  if (!m) return null;
+  return parseInt(m[1], 10) * 1000;
+}
+
+/**
+ * Fallback chains: when a model is overloaded (529) or rate-limited (429),
+ * try the next model in the chain before giving up.
+ */
+const FALLBACK_CHAINS: Record<string, { provider: ProviderId; model: string }[]> = {
+  'claude-opus-4-20250514': [
+    { provider: 'anthropic', model: 'claude-sonnet-4-5-20250929' },
+    { provider: 'openai', model: 'gpt-5.4' },
+  ],
+  'claude-sonnet-4-5-20250929': [
+    { provider: 'openai', model: 'gpt-5.4' },
+    { provider: 'anthropic', model: 'claude-haiku-4-5-20251001' },
+  ],
+  'gpt-5.4': [
+    { provider: 'anthropic', model: 'claude-sonnet-4-5-20250929' },
+    { provider: 'openai', model: 'gpt-5.4-mini' },
+  ],
+};
+
+export async function callLLM(req: LLMRequest): Promise<LLMResponse> {
+  const provider = req.provider || 'anthropic';
+  const model = req.model || DEFAULT_MODELS[provider] || 'claude-sonnet-4-5-20250929';
+
+  const apiKey = getApiKey(provider);
+  if (!apiKey && provider !== 'ollama') {
+    const envVars: Record<string, string> = {
+      'anthropic': 'ANTHROPIC_API_KEY',
+      'openai': 'OPENAI_API_KEY',
+      'deepseek': 'DEEPSEEK_API_KEY',
+      'xai': 'XAI_API_KEY',
+      'zai': 'ZAI_API_KEY',
+      'google': 'GOOGLE_API_KEY',
+      'nvidia-router': 'NVIDIA_API_KEY',
+    };
+    throw new LlmCallError(
+      `No API key for "${provider}". Set ${envVars[provider] || 'API_KEY'} in environment or .env file.`,
+      { provider, model, severity: 'fatal' },
+    );
+  }
+
+  // Try the requested model first
+  let lastError: Error | null = null;
+
+  const limiter = getRateLimiter();
+  const estTokens = estimateTokens(
+    (req.systemPrompt || '') +
+    (req.userMessage || '') +
+    (req.messages?.map(m => m.content || '').join('\n') || ''),
+  ) + (req.maxOutputTokens || 2048);
+
+  const turnDeadline = Date.now() + TURN_WALL_CLOCK_MS;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      if (limiter) {
+        try { await limiter.acquire(provider, estTokens); }
+        catch (e) {
+          if (e instanceof RateLimitOverflowError) {
+            // Surface as retryable error so the existing fallback kicks in.
+            throw new LlmCallError(
+              `API 503: ${e.message}`,
+              { provider, model, status: 503, severity: 'recoverable', cause: e },
+            );
+          }
+          throw e;
+        }
+      }
+      const response = await withTimeout(callProvider(provider, apiKey, model, req), LLM_TIMEOUT_MS, `${provider}/${model}`);
+      if (limiter) {
+        limiter.recordResponse(provider, response.inputTokens, response.outputTokens, estTokens, response.responseHeaders);
+      }
+      return response;
+    } catch (error) {
+      lastError = error as Error;
+      // Prefer the typed status from LlmCallError; fall back to parsing
+      // the message for legacy errors (anything thrown as bare Error).
+      let statusCode = 0;
+      if (lastError instanceof LlmCallError && typeof lastError.status === 'number') {
+        statusCode = lastError.status;
+      } else {
+        const statusMatch = lastError.message.match(/API (\d+):/);
+        if (statusMatch) statusCode = parseInt(statusMatch[1]);
+      }
+      const retryAfter = parseRetryAfter(lastError.message);
+      const isTimeout = /timeout after/.test(lastError.message);
+      const retryable = RETRYABLE_STATUS_CODES.has(statusCode) || isTimeout;
+      if (limiter && (statusCode === 429 || statusCode === 503)) {
+        limiter.recordThrottle(provider, retryAfter ?? 5000);
+      }
+
+      if (attempt < MAX_RETRIES && retryable && Date.now() < turnDeadline) {
+        const baseDelay = retryAfter ?? Math.min(1000 * Math.pow(2, attempt), 8_000);
+        const delay = Math.min(baseDelay, Math.max(0, turnDeadline - Date.now()));
+        // Do NOT write to stderr here — the Rust TUI renders to stderr and
+        // any stray bytes corrupt the frame. Details land in backend.log.
+        await new Promise(resolve => setTimeout(resolve, delay));
+        continue;
+      }
+
+      // Not retryable — break to fallback
+      break;
+    }
+  }
+
+  // Try fallback models
+  const fallbacks = FALLBACK_CHAINS[model] || [];
+  for (const fb of fallbacks) {
+    const fbKey = getApiKey(fb.provider);
+    if (!fbKey && fb.provider !== 'ollama') continue;
+
+    try {
+      const fbReq = { ...req, provider: fb.provider, model: fb.model };
+      // Wrap fallback in the same timeout as the primary call — otherwise
+      // a hung fallback provider can block the turn forever.
+      const fbResponse = await withTimeout(
+        callProvider(fb.provider, fbKey, fb.model, fbReq),
+        LLM_TIMEOUT_MS,
+        `${fb.provider}/${fb.model}`,
+      );
+      fbResponse.wasFallback = true;
+      fbResponse.requestedModel = model;
+      return fbResponse;
+    } catch {
+      // Fallback also failed — try next
+      continue;
+    }
+  }
+
+  // All retries and fallbacks exhausted
+  throw lastError ?? new Error('All retry attempts and fallbacks exhausted');
+}
+
+function callProvider(
+  provider: ProviderId,
+  apiKey: string | undefined,
+  model: string,
+  req: LLMRequest,
+): Promise<LLMResponse> {
+  switch (provider) {
+    case 'anthropic':
+      return callAnthropic(apiKey!, model, req);
+
+    case 'openai':
+      return callOpenAICompatible('https://api.openai.com/v1', apiKey!, model, provider, req);
+
+    case 'deepseek':
+      return callOpenAICompatible('https://api.deepseek.com/v1', apiKey!, model, provider, req);
+
+    case 'xai':
+      return callOpenAICompatible('https://api.x.ai/v1', apiKey!, model, provider, req);
+
+    case 'zai':
+      // Coding Plan endpoint — required for GLM Coding Plan subscriptions.
+      // The general-purpose /api/paas/v4 endpoint returns 1113 for coding-plan keys.
+      return callOpenAICompatible('https://api.z.ai/api/coding/paas/v4', apiKey!, model, provider, req);
+
+    case 'nvidia-router': {
+      const routerUrl = process.env.NVIDIA_ROUTER_URL || 'http://localhost:8001/v1';
+      return callOpenAICompatible(routerUrl, apiKey!, model, provider, req);
+    }
+
+    case 'google':
+      return callGemini(apiKey!, model, req);
+
+    case 'ollama':
+      return callOpenAICompatible('http://localhost:11434/v1', 'ollama', model, provider, req);
+
+    default:
+      throw new LlmCallError(
+        `Unknown provider "${provider}". Supported: anthropic, openai, deepseek, xai, zai, google, ollama, nvidia-router`,
+        { provider, model, severity: 'fatal' },
+      );
+  }
+}