codeblog-app 2.3.2 → 2.3.4

package/src/ai/chat.ts

@@ -0,0 +1,336 @@
+import { streamText, stepCountIs } from "ai"
+import { AIProvider } from "./provider"
+import { getChatTools } from "./tools"
+import { Log } from "../util/log"
+import { createRunEventFactory, type StreamEvent } from "./stream-events"
+
+const log = Log.create({ service: "ai-chat" })
+
+const SYSTEM_PROMPT = `You are CodeBlog AI — an assistant for the CodeBlog developer forum (codeblog.ai).
+
+You help developers with everything on the platform:
+- Scan and analyze their local IDE coding sessions
+- Write and publish blog posts from coding sessions
+- Browse, search, read, comment, vote on forum posts
+- Manage bookmarks, notifications, debates, tags, trending topics
+- Manage agents, view dashboard, follow users
+- Generate weekly digests
+
+You have 20+ tools. Use them whenever the user's request matches. Chain multiple tools if needed.
+After a tool returns results, summarize them naturally for the user.
+
+CRITICAL: When using tools, ALWAYS use the EXACT data returned by previous tool calls.
+- If scan_sessions returns a path like "/Users/zhaoyifei/...", use that EXACT path
+- NEVER modify, guess, or infer file paths — use them exactly as returned
+- If a tool call fails with "file not found", the path is wrong — check the scan results again
+
+Write casually like a dev talking to another dev. Be specific, opinionated, and genuine.
+Use code examples when relevant. Think Juejin / HN / Linux.do vibes — not a conference paper.`
+
+const IDLE_TIMEOUT_MS = 60_000
+const TOOL_TIMEOUT_MS = 45_000
+const DEFAULT_MAX_STEPS = 10
+
+export namespace AIChat {
+  export interface Message {
+    role: "user" | "assistant" | "system"
+    content: string
+  }
+
+  export interface StreamCallbacks {
+    onToken?: (token: string) => void
+    onFinish?: (text: string) => void
+    onError?: (error: Error) => void
+    onToolCall?: (name: string, args: unknown, callID: string) => void
+    onToolResult?: (name: string, result: unknown, callID: string) => void
+  }
+
+  export interface StreamOptions {
+    maxSteps?: number
+    runId?: string
+    idleTimeoutMs?: number
+    toolTimeoutMs?: number
+  }
+
+  export async function* streamEvents(
+    messages: Message[],
+    modelID?: string,
+    signal?: AbortSignal,
+    options?: StreamOptions,
+  ): AsyncGenerator<StreamEvent> {
+    const history = messages
+      .filter((m) => m.role === "user" || m.role === "assistant")
+      .map((m) => ({ role: m.role as "user" | "assistant", content: m.content }))
+
+    const routeCompat = await AIProvider.resolveModelCompat(modelID).catch(() => undefined)
+    const tools = await getChatTools(routeCompat || "default")
+    const model = await AIProvider.getModel(modelID)
+    const maxSteps = options?.maxSteps ?? DEFAULT_MAX_STEPS
+    const idleTimeoutMs = options?.idleTimeoutMs ?? IDLE_TIMEOUT_MS
+    const toolTimeoutMs = options?.toolTimeoutMs ?? TOOL_TIMEOUT_MS
+
+    const run = createRunEventFactory(options?.runId)
+    let full = ""
+    let aborted = false
+    let externalAbort = false
+    let abortError: Error | undefined
+    let errorEmitted = false
+    const toolQueue = new Map<string, string[]>()
+    const activeTools = new Map<string, { name: string; timer?: ReturnType<typeof setTimeout> }>()
+
+    const internalAbort = new AbortController()
+    const abortRun = (error?: Error) => {
+      if (aborted) return
+      aborted = true
+      if (error) abortError = error
+      internalAbort.abort()
+    }
+    const onExternalAbort = () => {
+      externalAbort = true
+      abortRun()
+    }
+    signal?.addEventListener("abort", onExternalAbort)
+
+    yield run.next("run-start", {
+      modelID: modelID || AIProvider.DEFAULT_MODEL,
+      messageCount: history.length,
+    })
+
+    let idleTimer: ReturnType<typeof setTimeout> | undefined
+    const clearAllToolTimers = () => {
+      for (const entry of activeTools.values()) {
+        if (entry.timer) clearTimeout(entry.timer)
+      }
+    }
+
+    const pushToolID = (name: string, callID: string) => {
+      const queue = toolQueue.get(name)
+      if (!queue) {
+        toolQueue.set(name, [callID])
+        return
+      }
+      queue.push(callID)
+    }
+
+    const shiftToolID = (name: string) => {
+      const queue = toolQueue.get(name)
+      if (!queue || queue.length === 0) return undefined
+      const callID = queue.shift()
+      if (queue.length === 0) toolQueue.delete(name)
+      return callID
+    }
+
+    const dropToolID = (name: string, callID: string) => {
+      const queue = toolQueue.get(name)
+      if (!queue || queue.length === 0) return
+      const next = queue.filter((id) => id !== callID)
+      if (next.length === 0) {
+        toolQueue.delete(name)
+        return
+      }
+      toolQueue.set(name, next)
+    }
+
+    const armToolTimeout = (name: string, callID: string) => {
+      if (toolTimeoutMs <= 0) return
+      const timer = setTimeout(() => {
+        abortRun(new Error(`Tool call "${name}" timed out after ${toolTimeoutMs}ms`))
+      }, toolTimeoutMs)
+      const active = activeTools.get(callID)
+      if (!active) return
+      if (active.timer) clearTimeout(active.timer)
+      active.timer = timer
+    }
+
+    const startTool = (name: string, callID: string) => {
+      activeTools.set(callID, { name })
+      armToolTimeout(name, callID)
+    }
+
+    const finishTool = (callID?: string) => {
+      if (!callID) return
+      const active = activeTools.get(callID)
+      if (!active) return
+      if (active.timer) clearTimeout(active.timer)
+      activeTools.delete(callID)
+    }
+
+    const resetIdle = () => {
+      if (idleTimer) clearTimeout(idleTimer)
+      if (activeTools.size > 0) return
+      idleTimer = setTimeout(() => {
+        abortRun(new Error(`Stream idle timeout after ${idleTimeoutMs}ms`))
+      }, idleTimeoutMs)
+    }
+
+    try {
+      const result = streamText({
+        model,
+        system: SYSTEM_PROMPT,
+        messages: history,
+        tools,
+        stopWhen: stepCountIs(maxSteps),
+        toolChoice: "auto",
+        abortSignal: internalAbort.signal,
+      })
+      resetIdle()
+      for await (const part of result.fullStream) {
+        if (internalAbort.signal.aborted) {
+          break
+        }
+        resetIdle()
+
+        switch (part.type) {
+          case "text-delta": {
+            const delta = (part as any).text ?? (part as any).textDelta ?? ""
+            if (!delta) break
+            full += delta
+            yield run.next("text-delta", { text: delta })
+            break
+          }
+          case "tool-call": {
+            if (idleTimer) {
+              clearTimeout(idleTimer)
+              idleTimer = undefined
+            }
+            const name = (part as any).toolName || "unknown"
+            const args = (part as any).args ?? (part as any).input ?? {}
+            const callID = (part as any).toolCallId || (part as any).id || `${run.runId}:tool:${crypto.randomUUID()}`
+            pushToolID(name, callID)
+            startTool(name, callID)
+            yield run.next("tool-start", { callID, name, args })
+            break
+          }
+          case "tool-result": {
+            const name = (part as any).toolName || "unknown"
+            const callID = (part as any).toolCallId || (part as any).id || shiftToolID(name) || `${run.runId}:tool:${crypto.randomUUID()}`
+            dropToolID(name, callID)
+            finishTool(callID)
+            resetIdle()
+            const result = (part as any).output ?? (part as any).result ?? {}
+            yield run.next("tool-result", { callID, name, result })
+            break
+          }
+          case "tool-error" as any: {
+            const name = (part as any).toolName || "unknown"
+            const callID = (part as any).toolCallId || (part as any).id || shiftToolID(name)
+            if (callID) {
+              dropToolID(name, callID)
+              finishTool(callID)
+            }
+            resetIdle()
+            const error = new Error(String((part as any).error || "tool error"))
+            errorEmitted = true
+            yield run.next("error", { error })
+            abortRun(error)
+            break
+          }
+          case "error": {
+            const err = (part as any).error
+            errorEmitted = true
+            yield run.next("error", { error: err instanceof Error ? err : new Error(String(err)) })
+            break
+          }
+          default:
+            break
+        }
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      if (error.name === "AbortError") {
+        if (abortError && !externalAbort) {
+          errorEmitted = true
+          yield run.next("error", { error: abortError })
+        }
+      } else {
+        log.error("stream error", { error: error.message })
+        errorEmitted = true
+        yield run.next("error", { error })
+      }
+    } finally {
+      if (idleTimer) clearTimeout(idleTimer)
+      clearAllToolTimers()
+      signal?.removeEventListener("abort", onExternalAbort)
+      if (abortError && !externalAbort && !errorEmitted) {
+        yield run.next("error", { error: abortError })
+      }
+      yield run.next("run-finish", { text: full, aborted })
+    }
+  }
+
+  export async function stream(
+    messages: Message[],
+    callbacks: StreamCallbacks,
+    modelID?: string,
+    signal?: AbortSignal,
+    options?: StreamOptions,
+  ) {
+    let full = ""
+    try {
+      for await (const event of streamEvents(messages, modelID, signal, options)) {
+        switch (event.type) {
+          case "text-delta":
+            full += event.text
+            callbacks.onToken?.(event.text)
+            break
+          case "tool-start":
+            callbacks.onToolCall?.(event.name, event.args, event.callID)
+            break
+          case "tool-result":
+            callbacks.onToolResult?.(event.name, event.result, event.callID)
+            break
+          case "error":
+            callbacks.onError?.(event.error)
+            break
+          case "run-finish":
+            callbacks.onFinish?.(event.text || "(No response)")
+            return event.text || "(No response)"
+        }
+      }
+      callbacks.onFinish?.(full || "(No response)")
+      return full || "(No response)"
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      callbacks.onError?.(error)
+      callbacks.onFinish?.(full || "(No response)")
+      return full || "(No response)"
+    }
+  }
+
+  export async function generate(prompt: string, modelID?: string) {
+    let result = ""
+    await stream([{ role: "user", content: prompt }], { onFinish: (text) => (result = text) }, modelID)
+    return result
+  }
+
+  export async function analyzeAndPost(sessionContent: string, modelID?: string) {
+    const prompt = `Analyze this coding session and write a blog post about it.
+
+The post should:
+- Have a catchy, dev-friendly title (like HN or Juejin)
+- Tell a story: what you were doing, what went wrong/right, what you learned
+- Include relevant code snippets
+- Be casual and genuine, written in first person
+- End with key takeaways
+
+Also provide:
+- 3-8 relevant tags (lowercase, hyphenated)
+- A one-line summary/hook
+
+Session content:
+${sessionContent.slice(0, 50000)}
+
+Respond in this exact JSON format:
+{
+  "title": "...",
+  "content": "... (markdown)",
+  "tags": ["tag1", "tag2"],
+  "summary": "..."
+}`
+
+    const raw = await generate(prompt, modelID)
+    const jsonMatch = raw.match(/\{[\s\S]*\}/)
+    if (!jsonMatch) throw new Error("AI did not return valid JSON")
+    return JSON.parse(jsonMatch[0])
+  }
+}

package/src/ai/configure.ts

@@ -0,0 +1,144 @@
+// AI provider auto-detection and configuration
+
+function looksLikeApi(r: Response) {
+  const ct = r.headers.get("content-type") || ""
+  return ct.includes("json") || ct.includes("text/plain")
+}
+
+export async function probe(base: string, key: string): Promise<"openai" | "anthropic" | null> {
+  const clean = base.replace(/\/+$/, "")
+  try {
+    const r = await fetch(`${clean}/v1/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(8000),
+    })
+    if (r.ok || ((r.status === 401 || r.status === 403) && looksLikeApi(r))) return "openai"
+  } catch {}
+  try {
+    const r = await fetch(`${clean}/v1/messages`, {
+      method: "POST",
+      headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "content-type": "application/json" },
+      body: JSON.stringify({ model: "test", max_tokens: 1, messages: [] }),
+      signal: AbortSignal.timeout(8000),
+    })
+    if (r.status !== 404 && looksLikeApi(r)) return "anthropic"
+  } catch {}
+  return null
+}
+
+const KEY_PREFIX_MAP: Record<string, string> = {
+  "sk-ant-": "anthropic",
+  "AIza": "google",
+  "xai-": "xai",
+  "gsk_": "groq",
+  "sk-or-": "openrouter",
+  "pplx-": "perplexity",
+}
+
+const ENV_MAP: Record<string, string> = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  google: "GOOGLE_GENERATIVE_AI_API_KEY",
+  xai: "XAI_API_KEY",
+  groq: "GROQ_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  perplexity: "PERPLEXITY_API_KEY",
+  "openai-compatible": "OPENAI_COMPATIBLE_API_KEY",
+}
+
+async function fetchFirstModel(base: string, key: string): Promise<string | null> {
+  try {
+    const clean = base.replace(/\/+$/, "")
+    const r = await fetch(`${clean}/v1/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(8000),
+    })
+    if (!r.ok) return null
+    const data = await r.json() as { data?: Array<{ id: string }> }
+    if (!data.data || data.data.length === 0) return null
+
+    // Prefer stable defaults first; avoid niche/legacy IDs unless explicitly chosen.
+    const ids = data.data.map((m) => m.id)
+    const preferred = [/^gpt-5\.2$/, /^claude-sonnet-4(?:-5)?/, /^gpt-5(?:\.|$|-)/, /^gpt-4o$/, /^claude-opus-4/, /^gpt-4o-mini$/, /^gemini-2\.5-flash$/]
+    for (const pattern of preferred) {
+      const match = ids.find((id) => pattern.test(id))
+      if (match) return match
+    }
+    return ids[0] ?? null
+  } catch {}
+  return null
+}
+
+export function detectProvider(key: string) {
+  for (const [prefix, provider] of Object.entries(KEY_PREFIX_MAP)) {
+    if (key.startsWith(prefix)) return provider
+  }
+  return "openai"
+}
+
+export async function saveProvider(url: string, key: string): Promise<{ provider: string; error?: string }> {
+  const { Config } = await import("../config")
+
+  if (url) {
+    const detected = await probe(url, key)
+    if (!detected) return { provider: "", error: "Could not connect. Check URL and key." }
+
+    const provider = detected === "anthropic" ? "anthropic" : "openai-compatible"
+    const envKey = detected === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_COMPATIBLE_API_KEY"
+    const envBase = detected === "anthropic" ? "ANTHROPIC_BASE_URL" : "OPENAI_COMPATIBLE_BASE_URL"
+    process.env[envKey] = key
+    process.env[envBase] = url
+
+    const cfg = await Config.load()
+    const providers = cfg.providers || {}
+    providers[provider] = {
+      api_key: key,
+      base_url: url,
+      api: detected === "anthropic" ? "anthropic" : "openai-compatible",
+      compat_profile: detected === "anthropic" ? "anthropic" : "openai-compatible",
+    }
+
+    // Auto-set model if not already configured
+    const update: Record<string, unknown> = { providers, default_provider: provider }
+    if (!cfg.model) {
+      const { defaultModelForProvider } = await import("./models")
+      if (detected === "anthropic") {
+        update.model = defaultModelForProvider("anthropic")
+      } else {
+        // For openai-compatible with custom URL, try to fetch available models
+        const model = await fetchFirstModel(url, key)
+        if (model) update.model = `openai-compatible/${model}`
+        else update.model = `openai-compatible/${defaultModelForProvider("openai-compatible")}`
+      }
+    }
+
+    await Config.save(update)
+    return { provider: `${detected} format` }
+  }
+
+  const provider = detectProvider(key)
+  if (ENV_MAP[provider]) process.env[ENV_MAP[provider]] = key
+
+  const cfg = await Config.load()
+  const providers = cfg.providers || {}
+  providers[provider] = {
+    api_key: key,
+    api: provider === "anthropic" ? "anthropic" : provider === "google" ? "google" : provider === "openai" ? "openai" : "openai-compatible",
+    compat_profile: provider === "anthropic" ? "anthropic" : provider === "google" ? "google" : provider === "openai" ? "openai" : "openai-compatible",
+  }
+
+  // Auto-set model for known providers
+  const update: Record<string, unknown> = { providers, default_provider: provider }
+  if (!cfg.model) {
+    const { defaultModelForProvider } = await import("./models")
+    update.model = defaultModelForProvider(provider)
+  }
+
+  await Config.save(update)
+  return { provider }
+}
+
+export function mask(s: string) {
+  if (s.length <= 8) return s
+  return s.slice(0, 4) + "\u2022".repeat(Math.min(s.length - 8, 20)) + s.slice(-4)
+}

package/src/ai/models.ts

@@ -0,0 +1,67 @@
+export interface ModelInfo {
+  id: string
+  providerID: string
+  name: string
+  contextWindow: number
+  outputTokens: number
+}
+
+export const BUILTIN_MODELS: Record<string, ModelInfo> = {
+  "claude-sonnet-4-20250514": { id: "claude-sonnet-4-20250514", providerID: "anthropic", name: "Claude Sonnet 4", contextWindow: 200000, outputTokens: 16384 },
+  "claude-3-5-haiku-20241022": { id: "claude-3-5-haiku-20241022", providerID: "anthropic", name: "Claude 3.5 Haiku", contextWindow: 200000, outputTokens: 8192 },
+  "gpt-5.2": { id: "gpt-5.2", providerID: "openai", name: "GPT-5.2", contextWindow: 400000, outputTokens: 128000 },
+  "gpt-4o": { id: "gpt-4o", providerID: "openai", name: "GPT-4o", contextWindow: 128000, outputTokens: 16384 },
+  "gpt-4o-mini": { id: "gpt-4o-mini", providerID: "openai", name: "GPT-4o Mini", contextWindow: 128000, outputTokens: 16384 },
+  "o3-mini": { id: "o3-mini", providerID: "openai", name: "o3-mini", contextWindow: 200000, outputTokens: 100000 },
+  "gemini-2.5-flash": { id: "gemini-2.5-flash", providerID: "google", name: "Gemini 2.5 Flash", contextWindow: 1048576, outputTokens: 65536 },
+  "gemini-2.5-pro": { id: "gemini-2.5-pro", providerID: "google", name: "Gemini 2.5 Pro", contextWindow: 1048576, outputTokens: 65536 },
+}
+
+export const DEFAULT_MODEL = "claude-sonnet-4-20250514"
+const LEGACY_MODEL_MAP: Record<string, string> = {
+  "4.0Ultra": "gpt-5.2",
+  "4.0ultra": "gpt-5.2",
+}
+
+const PROVIDER_DEFAULT_MODEL: Record<string, string> = {
+  anthropic: "claude-sonnet-4-20250514",
+  openai: "gpt-5.2",
+  google: "gemini-2.5-flash",
+  "openai-compatible": "gpt-5.2",
+}
+
+export function normalizeModelID(modelID?: string): string | undefined {
+  if (!modelID) return undefined
+  const trimmed = modelID.trim()
+  if (!trimmed) return undefined
+  if (LEGACY_MODEL_MAP[trimmed]) return LEGACY_MODEL_MAP[trimmed]
+  if (!trimmed.includes("/")) return trimmed
+  const [providerID, ...rest] = trimmed.split("/")
+  const raw = rest.join("/")
+  if (!raw) return trimmed
+  const mapped = LEGACY_MODEL_MAP[raw]
+  if (!mapped) return trimmed
+  return `${providerID}/${mapped}`
+}
+
+export function defaultModelForProvider(providerID?: string): string {
+  if (!providerID) return DEFAULT_MODEL
+  return PROVIDER_DEFAULT_MODEL[providerID] || DEFAULT_MODEL
+}
+
+export function resolveModelFromConfig(cfg: { model?: string; default_provider?: string }): string {
+  const model = normalizeModelID(cfg.model)
+  if (model) return model
+  const fallback = defaultModelForProvider(cfg.default_provider)
+  if (cfg.default_provider === "openai-compatible" && !fallback.includes("/")) {
+    return `openai-compatible/${fallback}`
+  }
+  return fallback
+}
+
+export function inferProviderByModelPrefix(modelID: string): string | undefined {
+  if (modelID.startsWith("claude-")) return "anthropic"
+  if (modelID.startsWith("gpt-") || modelID.startsWith("o1-") || modelID.startsWith("o3-")) return "openai"
+  if (modelID.startsWith("gemini-")) return "google"
+  return undefined
+}

package/src/ai/provider-registry.ts

@@ -0,0 +1,150 @@
+import { Config } from "../config"
+import { Log } from "../util/log"
+import { BUILTIN_MODELS, inferProviderByModelPrefix, resolveModelFromConfig, normalizeModelID } from "./models"
+import { type ModelCompatConfig, resolveCompat } from "./types"
+
+const log = Log.create({ service: "ai-provider-registry" })
+
+export const PROVIDER_ENV: Record<string, string[]> = {
+  anthropic: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+  openai: ["OPENAI_API_KEY"],
+  google: ["GOOGLE_GENERATIVE_AI_API_KEY", "GOOGLE_API_KEY"],
+  "openai-compatible": ["OPENAI_COMPATIBLE_API_KEY"],
+}
+
+export const PROVIDER_BASE_URL_ENV: Record<string, string[]> = {
+  anthropic: ["ANTHROPIC_BASE_URL"],
+  openai: ["OPENAI_BASE_URL", "OPENAI_API_BASE"],
+  google: ["GOOGLE_API_BASE_URL"],
+  "openai-compatible": ["OPENAI_COMPATIBLE_BASE_URL"],
+}
+
+export interface ProviderRuntimeConfig {
+  id: string
+  apiKey?: string
+  baseURL?: string
+  config?: Config.ProviderConfig
+}
+
+export interface ProviderRegistryView {
+  providers: Record<string, ProviderRuntimeConfig>
+  defaultProvider?: string
+}
+
+export interface ModelRoute {
+  requestedModel: string
+  providerID: string
+  modelID: string
+  apiKey: string
+  baseURL?: string
+  compat: ModelCompatConfig
+}
+
+function readFirstEnv(keys: string[]): string | undefined {
+  for (const key of keys) {
+    if (process.env[key]) return process.env[key]
+  }
+  return undefined
+}
+
+export async function loadProviders(cfgInput?: Config.CodeblogConfig): Promise<ProviderRegistryView> {
+  const cfg = cfgInput || await Config.load()
+  const user = cfg.providers || {}
+  const ids = new Set<string>([
+    ...Object.keys(PROVIDER_ENV),
+    ...Object.keys(user),
+  ])
+
+  const providers: Record<string, ProviderRuntimeConfig> = {}
+
+  for (const id of ids) {
+    const config = user[id]
+    providers[id] = {
+      id,
+      config,
+      apiKey: readFirstEnv(PROVIDER_ENV[id] || []) || config?.api_key,
+      baseURL: readFirstEnv(PROVIDER_BASE_URL_ENV[id] || []) || config?.base_url,
+    }
+  }
+
+  return { providers, defaultProvider: cfg.default_provider }
+}
+
+function availableProvidersWithKeys(providers: Record<string, ProviderRuntimeConfig>): string[] {
+  return Object.values(providers)
+    .filter((p) => p.apiKey)
+    .map((p) => p.id)
+    .sort()
+}
+
+function unknownModelError(modelID: string, providers: Record<string, ProviderRuntimeConfig>): Error {
+  const available = availableProvidersWithKeys(providers)
+  const base = `Unknown model "${modelID}".`
+  if (available.length === 0) {
+    return new Error(`${base} No AI providers are configured. Run: codeblog ai setup`)
+  }
+  return new Error(`${base} Available providers with keys: ${available.join(", ")}. Try: codeblog config --model <provider>/<model>`)
+}
+
+function noKeyError(providerID: string, modelID: string): Error {
+  const envKeys = PROVIDER_ENV[providerID] || []
+  const envHint = envKeys[0] || `${providerID.toUpperCase().replace(/-/g, "_")}_API_KEY`
+  return new Error(`No API key for ${providerID} (model: ${modelID}). Set ${envHint} or run: codeblog config --provider ${providerID} --api-key <key>`)
+}
+
+function routeViaProvider(
+  providers: Record<string, ProviderRuntimeConfig>,
+  requestedModel: string,
+  providerID: string,
+  modelID: string,
+): ModelRoute {
+  const provider = providers[providerID]
+  if (!provider) throw unknownModelError(requestedModel, providers)
+  if (!provider.apiKey) throw noKeyError(providerID, modelID)
+
+  const compat = resolveCompat({ providerID, modelID, providerConfig: provider.config })
+  return {
+    requestedModel,
+    providerID,
+    modelID,
+    apiKey: provider.apiKey,
+    baseURL: provider.baseURL,
+    compat,
+  }
+}
+
+export async function routeModel(inputModel?: string, cfgInput?: Config.CodeblogConfig): Promise<ModelRoute> {
+  const cfg = cfgInput || await Config.load()
+  const requestedModel = normalizeModelID(inputModel) || resolveModelFromConfig(cfg)
+  const loaded = await loadProviders(cfg)
+  const providers = loaded.providers
+
+  if (requestedModel.includes("/")) {
+    const [providerID, ...rest] = requestedModel.split("/")
+    const modelID = rest.join("/")
+    return routeViaProvider(providers, requestedModel, providerID!, modelID)
+  }
+
+  if (BUILTIN_MODELS[requestedModel]) {
+    const providerID = BUILTIN_MODELS[requestedModel]!.providerID
+    return routeViaProvider(providers, requestedModel, providerID, requestedModel)
+  }
+
+  const prefixed = inferProviderByModelPrefix(requestedModel)
+  if (prefixed) {
+    return routeViaProvider(providers, requestedModel, prefixed, requestedModel)
+  }
+
+  if (loaded.defaultProvider) {
+    return routeViaProvider(providers, requestedModel, loaded.defaultProvider, requestedModel)
+  }
+
+  log.warn("route failed", { requestedModel })
+  throw unknownModelError(requestedModel, providers)
+}
+
+export async function resolveProviderCompat(providerID: string, modelID: string, cfgInput?: Config.CodeblogConfig): Promise<ModelCompatConfig> {
+  const loaded = await loadProviders(cfgInput)
+  const provider = loaded.providers[providerID]
+  return resolveCompat({ providerID, modelID, providerConfig: provider?.config })
+}