ethagent 0.2.1 → 1.0.1

package/src/models/modelRecommendation.ts

@@ -0,0 +1,140 @@
+import {
+  fileFormat,
+  quantizationFromFilename,
+  type HuggingFaceRepoInfo,
+  type HuggingFaceSibling,
+} from './huggingface.js'
+import type { SpecSnapshot } from './runtimeDetection.js'
+
+const GB = 1024 * 1024 * 1024
+
+/** Featured local model repo for first-run setup and the model picker catalog. */
+export const FEATURED_HF_REPO = 'HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive'
+export const FEATURED_HF_REPO_URL = `https://huggingface.co/${FEATURED_HF_REPO}`
+
+export type GgufMachineFit = 'fits' | 'tight' | 'too-large' | 'unknown'
+
+export type GgufFileRecommendation = {
+  file: HuggingFaceSibling
+  fit: GgufMachineFit
+  score: number
+  budgetBytes: number
+  estimatedRequiredBytes?: number
+}
+
+export function recommendGgufFile(
+  repo: HuggingFaceRepoInfo,
+  files: HuggingFaceSibling[],
+  spec: SpecSnapshot,
+): GgufFileRecommendation | null {
+  return orderGgufFilesForSpec(repo, files, spec)[0] ?? null
+}
+
+export function orderGgufFilesForSpec(
+  repo: HuggingFaceRepoInfo,
+  files: HuggingFaceSibling[],
+  spec: SpecSnapshot,
+): GgufFileRecommendation[] {
+  return files
+    .filter(file => fileFormat(file.filename) === 'gguf')
+    .map(file => scoreGgufFile(repo, file, spec))
+    .sort((a, b) =>
+      b.score - a.score
+      || fitRank(b.fit) - fitRank(a.fit)
+      || (a.file.sizeBytes ?? Number.MAX_SAFE_INTEGER) - (b.file.sizeBytes ?? Number.MAX_SAFE_INTEGER)
+      || a.file.filename.localeCompare(b.file.filename),
+    )
+}
+
+export function estimateGgufMachineFit(sizeBytes: number | undefined, spec: SpecSnapshot): {
+  fit: GgufMachineFit
+  budgetBytes: number
+  estimatedRequiredBytes?: number
+} {
+  const budgetBytes = ggufBudgetBytes(spec)
+  if (!sizeBytes || sizeBytes <= 0) return { fit: 'unknown', budgetBytes }
+  const estimatedRequiredBytes = Math.ceil(sizeBytes * 1.25 + GB)
+  if (estimatedRequiredBytes <= budgetBytes) return { fit: 'fits', budgetBytes, estimatedRequiredBytes }
+  if (estimatedRequiredBytes <= budgetBytes * 1.15) return { fit: 'tight', budgetBytes, estimatedRequiredBytes }
+  return { fit: 'too-large', budgetBytes, estimatedRequiredBytes }
+}
+
+function scoreGgufFile(
+  repo: HuggingFaceRepoInfo,
+  file: HuggingFaceSibling,
+  spec: SpecSnapshot,
+): GgufFileRecommendation {
+  const fit = estimateGgufMachineFit(file.sizeBytes, spec)
+  const lower = `${repo.repoId} ${file.filename} ${repo.tags.join(' ')}`.toLowerCase()
+  const score =
+    fitScore(fit.fit)
+    + taskScore(lower)
+    + quantizationScore(quantizationFromFilename(file.filename))
+    + sizeScore(file.sizeBytes, fit.fit)
+
+  return {
+    file,
+    fit: fit.fit,
+    budgetBytes: fit.budgetBytes,
+    estimatedRequiredBytes: fit.estimatedRequiredBytes,
+    score,
+  }
+}
+
+function ggufBudgetBytes(spec: SpecSnapshot): number {
+  if (spec.isAppleSilicon) return Math.floor(spec.effectiveRamBytes * 0.7)
+  const cpuBudget = Math.floor(spec.effectiveRamBytes * 0.55)
+  if (spec.gpuVramBytes !== null && spec.gpuVramBytes >= 8 * GB) {
+    return Math.max(cpuBudget, Math.floor(spec.gpuVramBytes * 0.85))
+  }
+  return cpuBudget
+}
+
+function fitScore(fit: GgufMachineFit): number {
+  switch (fit) {
+    case 'fits': return 1000
+    case 'tight': return 600
+    case 'unknown': return 250
+    case 'too-large': return -1000
+  }
+}
+
+function fitRank(fit: GgufMachineFit): number {
+  switch (fit) {
+    case 'fits': return 3
+    case 'tight': return 2
+    case 'unknown': return 1
+    case 'too-large': return 0
+  }
+}
+
+function taskScore(text: string): number {
+  if (/(embed|embedding|rerank)/.test(text)) return -350
+  if (/(vision|vlm|multimodal)/.test(text)) return -250
+  if (/(instruct|chat|assistant)/.test(text)) return 250
+  if (/(code|coder|coding)/.test(text)) return 120
+  if (/(^|[-_\s])base($|[-_\s])/.test(text)) return -100
+  return 0
+}
+
+function quantizationScore(quantization: string | undefined): number {
+  if (!quantization) return 0
+  if (quantization === 'Q8_0') return 210
+  if (quantization === 'Q6_K') return 195
+  if (quantization === 'Q5_K_M') return 185
+  if (quantization === 'Q5_K_S') return 175
+  if (quantization.startsWith('Q5')) return 165
+  if (quantization === 'Q4_K_M') return 155
+  if (quantization === 'Q4_K_S') return 140
+  if (quantization.startsWith('Q4')) return 125
+  if (quantization.startsWith('IQ4')) return 115
+  if (quantization.startsWith('IQ3') || quantization.startsWith('Q3')) return 85
+  if (quantization === 'F16' || quantization === 'BF16') return 150
+  if (quantization === 'F32') return 90
+  return 50
+}
+
+function sizeScore(sizeBytes: number | undefined, fit: GgufMachineFit): number {
+  if (!sizeBytes || fit === 'too-large') return 0
+  return Math.min(sizeBytes / GB, 20) * 4
+}

package/src/models/runtimeDetection.ts

@@ -0,0 +1,81 @@
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+
+export type SpecSnapshot = {
+  platform: NodeJS.Platform
+  arch: string
+  cpuCores: number
+  totalRamBytes: number
+  effectiveRamBytes: number
+  isAppleSilicon: boolean
+  gpuVramBytes: number | null
+}
+
+function runCommand(cmd: string, args: string[], timeoutMs = 2000): Promise<{ code: number; stdout: string; stderr: string } | null> {
+  return new Promise(resolve => {
+    let settled = false
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(cmd, args, { windowsHide: true })
+    } catch {
+      resolve(null)
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      try { child.kill() } catch { void 0 }
+      resolve(null)
+    }, timeoutMs)
+
+    child.stdout?.on('data', d => { stdout += d.toString() })
+    child.stderr?.on('data', d => { stderr += d.toString() })
+    child.on('error', () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(null)
+    })
+    child.on('close', code => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ code: code ?? -1, stdout, stderr })
+    })
+  })
+}
+
+async function detectNvidiaVram(): Promise<number | null> {
+  const result = await runCommand('nvidia-smi', ['--query-gpu=memory.total', '--format=csv,noheader,nounits'])
+  if (!result || result.code !== 0) return null
+  const firstLine = result.stdout.split('\n').map(l => l.trim()).find(Boolean)
+  if (!firstLine) return null
+  const mib = Number.parseInt(firstLine, 10)
+  if (!Number.isFinite(mib) || mib <= 0) return null
+  return mib * 1024 * 1024
+}
+
+export async function detectSpec(): Promise<SpecSnapshot> {
+  const platform = process.platform
+  const arch = process.arch
+  const cpuCores = os.cpus().length
+  const totalRamBytes = os.totalmem()
+  const isAppleSilicon = platform === 'darwin' && arch === 'arm64'
+  const effectiveRamBytes = isAppleSilicon ? Math.floor(totalRamBytes * 0.75) : totalRamBytes
+
+  const [gpuVramBytes] = await Promise.all([
+    isAppleSilicon ? Promise.resolve(null) : detectNvidiaVram(),
+  ])
+
+  return {
+    platform,
+    arch,
+    cpuCores,
+    totalRamBytes,
+    effectiveRamBytes,
+    isAppleSilicon,
+    gpuVramBytes,
+  }
+}

package/src/models/uncensoredCatalog.ts

@@ -0,0 +1,86 @@
+import {
+  fetchHuggingFaceRepoInfo,
+  ggufFiles,
+  localModelId,
+  type HuggingFaceRepoInfo,
+  type HuggingFaceSibling,
+  type LocalHfModel,
+} from './huggingface.js'
+import {
+  FEATURED_HF_REPO,
+  estimateGgufMachineFit,
+  recommendGgufFile,
+  type GgufMachineFit,
+} from './modelRecommendation.js'
+import type { SpecSnapshot } from './runtimeDetection.js'
+
+export type UncensoredCatalogEntry = {
+  repo: HuggingFaceRepoInfo
+  file: HuggingFaceSibling
+  fit: GgufMachineFit
+  recommended: boolean
+  installed: boolean
+}
+
+type FetchImpl = typeof fetch
+
+const GB = 1024 * 1024 * 1024
+const FEATURED_FILE_ORDER = [
+  { filename: 'Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-BF16.gguf', fallbackSizeBytes: Math.round(17 * GB) },
+  { filename: 'Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q8_0.gguf', fallbackSizeBytes: Math.round(8.9 * GB) },
+  { filename: 'Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q6_K.gguf', fallbackSizeBytes: Math.round(6.9 * GB) },
+  { filename: 'Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf', fallbackSizeBytes: Math.round(5.3 * GB) },
+  { filename: 'mmproj-Qwen3.5-9B-Uncensored-HauhauCS-Aggressive-BF16.gguf', fallbackSizeBytes: Math.round(0.88 * GB) },
+] as const
+
+export async function fetchUncensoredGgufCatalog(args: {
+  machineSpec?: SpecSnapshot
+  installedModels: LocalHfModel[]
+  fetchImpl?: FetchImpl
+  limit?: number
+}): Promise<UncensoredCatalogEntry[]> {
+  const fetchImpl = args.fetchImpl ?? fetch
+  const repos = await Promise.allSettled([
+    fetchHuggingFaceRepoInfo({ repoId: FEATURED_HF_REPO }, fetchImpl),
+  ])
+  const installed = new Set(args.installedModels.filter(model => model.status === 'ready').map(model => model.id))
+  const entries: UncensoredCatalogEntry[] = []
+
+  for (const result of repos) {
+    if (result.status !== 'fulfilled') continue
+    const repo = result.value
+    if (repo.repoId !== FEATURED_HF_REPO) continue
+    const files = pickFeaturedFiles(repo)
+    if (files.length === 0) continue
+    const runnable = files.filter(file => !isVisionEncoder(file.filename))
+    const recommendedFilename = args.machineSpec
+      ? recommendGgufFile(repo, runnable, args.machineSpec)?.file.filename
+      : undefined
+    for (const file of files.slice(0, args.limit ?? FEATURED_FILE_ORDER.length)) {
+      const recommended = recommendedFilename === file.filename
+      entries.push({
+        repo,
+        file,
+        fit: args.machineSpec ? estimateGgufMachineFit(file.sizeBytes, args.machineSpec).fit : 'unknown',
+        recommended,
+        installed: installed.has(localModelId(repo.repoId, file.filename)),
+      })
+    }
+  }
+
+  return entries
+}
+
+function pickFeaturedFiles(repo: HuggingFaceRepoInfo): HuggingFaceSibling[] {
+  const byName = new Map(ggufFiles(repo).map(file => [file.filename, file] as const))
+  return FEATURED_FILE_ORDER
+    .map(spec => {
+      const file = byName.get(spec.filename)
+      if (file) return file
+      return { filename: spec.filename, sizeBytes: spec.fallbackSizeBytes } satisfies HuggingFaceSibling
+    })
+}
+
+function isVisionEncoder(filename: string): boolean {
+  return filename.toLowerCase().startsWith('mmproj-')
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,259 @@
+import { getKey } from '../storage/secrets.js'
+import type { Message, MessageContentBlock, Provider, ProviderCompleteOptions, StreamEvent } from './contracts.js'
+import { ProviderError } from './contracts.js'
+import { providerErrorFromResponse } from './errors.js'
+import { fetchWithRetryStreamEvents } from './retry.js'
+import { iterSseEvents } from './sse.js'
+
+export type AnthropicToolDefinition = {
+  name: string
+  description: string
+  input_schema: {
+    type: 'object'
+    properties?: Record<string, unknown>
+    required?: string[]
+  }
+}
+
+type AnthropicStreamMessage = {
+  type?: string
+  message?: {
+    usage?: {
+      input_tokens?: number
+      output_tokens?: number
+    }
+  }
+  usage?: {
+    input_tokens?: number
+    output_tokens?: number
+  }
+  delta?: {
+    type?: string
+    text?: string
+    thinking?: string
+    stop_reason?: string
+    partial_json?: string
+  }
+  content_block?: {
+    type?: string
+    id?: string
+    name?: string
+    input?: Record<string, unknown>
+  }
+  index?: number
+  error?: {
+    type?: string
+    message?: string
+  }
+}
+
+const ANTHROPIC_VERSION = '2023-06-01'
+const READ_TIMEOUT_MS = 45_000
+const DEFAULT_MAX_TOKENS = 4096
+
+export class AnthropicProvider implements Provider {
+  readonly id = 'anthropic' as const
+  readonly model: string
+  readonly supportsTools: boolean
+  private readonly tools: AnthropicToolDefinition[]
+
+  constructor(opts: { model: string; tools?: AnthropicToolDefinition[] }) {
+    this.model = opts.model
+    this.tools = opts.tools ?? []
+    this.supportsTools = this.tools.length > 0
+  }
+
+  async *complete(
+    messages: Message[],
+    signal: AbortSignal,
+    options: ProviderCompleteOptions = {},
+  ): AsyncIterable<StreamEvent> {
+    const apiKey = await getKey('anthropic')
+    if (!apiKey) {
+      const error = new ProviderError('missing API key for anthropic (/doctor to verify)')
+      yield { type: 'error', message: error.message }
+      return
+    }
+
+    const { system, conversation } = splitMessages(messages)
+
+    let response: Response
+    try {
+      response = yield* fetchWithRetryStreamEvents('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'text/event-stream',
+          'anthropic-version': ANTHROPIC_VERSION,
+          'x-api-key': apiKey,
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+          stream: true,
+          system,
+          messages: conversation,
+          tools: this.tools.length > 0 ? this.tools : undefined,
+        }),
+      }, { signal, rateLimitResetProvider: 'anthropic' })
+    } catch (err: unknown) {
+      if (signal.aborted) return
+      yield { type: 'error', message: (err as Error).message || 'network error' }
+      return
+    }
+
+    if (!response.ok) {
+      const error = await providerErrorFromResponse(this.id, response)
+      yield { type: 'error', message: error.message }
+      return
+    }
+    if (!response.body) {
+      yield { type: 'error', message: 'empty response body' }
+      return
+    }
+
+    let inputTokens: number | undefined
+    let outputTokens: number | undefined
+    let stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'unknown' = 'unknown'
+    const toolBuffers = new Map<number, { id: string; name: string; json: string }>()
+
+    try {
+      for await (const frame of iterSseEvents(response.body, signal, READ_TIMEOUT_MS)) {
+        const eventType = frame.event
+        let parsed: AnthropicStreamMessage
+        try {
+          parsed = JSON.parse(frame.data) as AnthropicStreamMessage
+        } catch {
+          continue
+        }
+
+        const type = parsed.type ?? eventType ?? ''
+        if (type === 'message_start') {
+          inputTokens = parsed.message?.usage?.input_tokens ?? inputTokens
+          outputTokens = parsed.message?.usage?.output_tokens ?? outputTokens
+          continue
+        }
+        if (type === 'content_block_start' && parsed.content_block?.type === 'tool_use') {
+          const id = parsed.content_block.id ?? `tool-${parsed.index ?? 0}`
+          const name = parsed.content_block.name ?? 'unknown'
+          const json = parsed.content_block.input ? JSON.stringify(parsed.content_block.input) : ''
+          toolBuffers.set(parsed.index ?? 0, { id, name, json })
+          yield { type: 'tool_use_start', id, name }
+          continue
+        }
+        if (type === 'content_block_delta') {
+          if (parsed.delta?.type === 'text_delta' && parsed.delta.text) {
+            yield { type: 'text', delta: parsed.delta.text }
+          } else if (parsed.delta?.type === 'thinking_delta' && parsed.delta.thinking) {
+            yield { type: 'thinking', delta: parsed.delta.thinking }
+          } else if (parsed.delta?.type === 'input_json_delta' && typeof parsed.delta.partial_json === 'string') {
+            const buffer = toolBuffers.get(parsed.index ?? 0)
+            if (buffer) {
+              buffer.json += parsed.delta.partial_json
+              yield { type: 'tool_use_delta', id: buffer.id, delta: parsed.delta.partial_json }
+            }
+          }
+          continue
+        }
+        if (type === 'content_block_stop') {
+          const buffer = toolBuffers.get(parsed.index ?? 0)
+          if (buffer) {
+            let input: Record<string, unknown> = {}
+            try {
+              input = buffer.json.trim() ? JSON.parse(buffer.json) as Record<string, unknown> : {}
+            } catch {
+              input = {}
+            }
+            yield { type: 'tool_use_stop', id: buffer.id, name: buffer.name, input }
+            toolBuffers.delete(parsed.index ?? 0)
+          }
+          continue
+        }
+        if (type === 'message_delta') {
+          inputTokens = parsed.usage?.input_tokens ?? inputTokens
+          outputTokens = parsed.usage?.output_tokens ?? outputTokens
+          stopReason = normalizeStopReason(parsed.delta?.stop_reason)
+          continue
+        }
+        if (type === 'error') {
+          const message = parsed.error?.message || 'anthropic stream error'
+          const transient = parsed.error?.type === 'overloaded_error' || parsed.error?.type === 'rate_limit_error'
+          throw new ProviderError(message, { transient })
+        }
+        if (type === 'message_stop') {
+          break
+        }
+      }
+    } catch (err: unknown) {
+      if (signal.aborted) return
+      yield { type: 'error', message: (err as Error).message || 'stream error' }
+      return
+    }
+
+    if (signal.aborted) return
+    yield { type: 'done', inputTokens, outputTokens, stopReason }
+  }
+}
+
+function splitMessages(messages: Message[]): {
+  system?: string
+  conversation: Array<{
+    role: 'user' | 'assistant'
+    content: Array<
+      | { type: 'text'; text: string }
+      | { type: 'tool_use'; id: string; name: string; input: Record<string, unknown> }
+      | { type: 'tool_result'; tool_use_id: string; content: string; is_error?: boolean }
+    >
+  }>
+} {
+  const systemParts: string[] = []
+  const conversation: Array<{
+    role: 'user' | 'assistant'
+    content: Array<
+      | { type: 'text'; text: string }
+      | { type: 'tool_use'; id: string; name: string; input: Record<string, unknown> }
+      | { type: 'tool_result'; tool_use_id: string; content: string; is_error?: boolean }
+    >
+  }> = []
+
+  for (const message of messages) {
+    const blocks = normalizeBlocks(message.content)
+    if (blocks.length === 0) continue
+    if (message.role === 'system') {
+      const systemText = blocks.filter(block => block.type === 'text').map(block => block.text).join('\n\n').trim()
+      if (systemText) systemParts.push(systemText)
+      continue
+    }
+    conversation.push({
+      role: message.role,
+      content: blocks.map(block => {
+        if (block.type === 'text') return { type: 'text', text: block.text }
+        if (block.type === 'tool_use') return { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+        return { type: 'tool_result', tool_use_id: block.toolUseId, content: block.content, is_error: block.isError }
+      }),
+    })
+  }
+
+  return {
+    system: systemParts.length > 0 ? systemParts.join('\n\n') : undefined,
+    conversation,
+  }
+}
+
+function normalizeBlocks(content: Message['content']): MessageContentBlock[] {
+  if (typeof content === 'string') {
+    const text = content.trim()
+    return text ? [{ type: 'text', text }] : []
+  }
+  return content.filter(block => {
+    if (block.type === 'text') return block.text.trim().length > 0
+    return true
+  })
+}
+
+function normalizeStopReason(value?: string): 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'unknown' {
+  if (value === 'end_turn' || value === 'tool_use' || value === 'max_tokens' || value === 'stop_sequence') {
+    return value
+  }
+  return 'unknown'
+}

package/src/providers/contracts.ts

@@ -0,0 +1,62 @@
+import type { ProviderId } from '../storage/config.js'
+import type { RetryEvent } from '../utils/withRetry.js'
+
+export type Role = 'system' | 'user' | 'assistant'
+
+export type TextBlock = {
+  type: 'text'
+  text: string
+}
+
+export type ToolUseBlock = {
+  type: 'tool_use'
+  id: string
+  name: string
+  input: Record<string, unknown>
+}
+
+export type ToolResultBlock = {
+  type: 'tool_result'
+  toolUseId: string
+  content: string
+  isError?: boolean
+}
+
+export type MessageContentBlock = TextBlock | ToolUseBlock | ToolResultBlock
+
+export type Message = {
+  role: Role
+  content: string | MessageContentBlock[]
+}
+
+export type ProviderRetryStreamEvent = { type: 'retry' } & RetryEvent
+
+export type StreamEvent =
+  | { type: 'text'; delta: string }
+  | { type: 'thinking'; delta: string }
+  | ProviderRetryStreamEvent
+  | { type: 'tool_use_start'; id: string; name: string }
+  | { type: 'tool_use_delta'; id: string; delta: string }
+  | { type: 'tool_use_stop'; id: string; name: string; input: Record<string, unknown> }
+  | { type: 'done'; inputTokens?: number; outputTokens?: number; stopReason?: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'unknown' }
+  | { type: 'error'; message: string }
+
+export type ProviderCompleteOptions = {
+  maxTokens?: number
+}
+
+export interface Provider {
+  readonly id: ProviderId
+  readonly model: string
+  readonly supportsTools: boolean
+  complete(messages: Message[], signal: AbortSignal, options?: ProviderCompleteOptions): AsyncIterable<StreamEvent>
+}
+
+export class ProviderError extends Error {
+  readonly transient: boolean
+  constructor(message: string, options: { transient?: boolean } = {}) {
+    super(message)
+    this.name = 'ProviderError'
+    this.transient = options.transient ?? false
+  }
+}

package/src/providers/errors.ts

@@ -0,0 +1,62 @@
+import type { ProviderId } from '../storage/config.js'
+import { ProviderError } from './contracts.js'
+
+type ErrorBody =
+  | string
+  | {
+      error?: {
+        message?: string
+        type?: string
+      }
+      message?: string
+      detail?: string
+    }
+
+export async function providerErrorFromResponse(
+  provider: ProviderId,
+  response: Response,
+): Promise<ProviderError> {
+  const detail = await readErrorDetail(response)
+
+  if (provider !== 'llamacpp') {
+    if (response.status === 401 || response.status === 403) {
+      return new ProviderError(`auth failed: check your ${provider} key (/doctor to verify)`)
+    }
+    if (response.status === 429) {
+      return new ProviderError(detail || `${provider} rate limit exceeded`, { transient: true })
+    }
+    if (response.status >= 500) {
+      return new ProviderError(detail || `${provider} server error (${response.status})`, { transient: true })
+    }
+  }
+
+  return new ProviderError(
+    detail ? `HTTP ${response.status}: ${detail}` : `HTTP ${response.status}`,
+    { transient: response.status === 429 || response.status >= 500 },
+  )
+}
+
+async function readErrorDetail(response: Response): Promise<string> {
+  let text = ''
+  try {
+    text = (await response.text()).trim()
+  } catch {
+    return ''
+  }
+  if (!text) return ''
+
+  try {
+    const parsed = JSON.parse(text) as ErrorBody
+    const nestedMessage =
+      typeof parsed === 'object' && parsed !== null
+        ? parsed.error?.message ?? parsed.message ?? parsed.detail ?? ''
+        : ''
+    return normalizeDetail(nestedMessage || text)
+  } catch {
+    return normalizeDetail(text)
+  }
+}
+
+function normalizeDetail(detail: string): string {
+  return detail.replace(/\s+/g, ' ').trim().slice(0, 400)
+}