jeo-code 0.1.0

package/src/ai/index.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./model-manager";
+export * from "./provider-status";
+export * from "./model-discovery";
+export * from "./model-picker";
+export * from "./model-catalog";
+export * from "./model-enrich";
+export { anthropicAdapter } from "./providers/anthropic";
+export { openaiAdapter } from "./providers/openai";
+export { geminiAdapter } from "./providers/gemini";
+export { ollamaAdapter } from "./providers/ollama";

package/src/ai/model-catalog-compat.ts

@@ -0,0 +1,119 @@
+/**
+ * Compatibility adapter over `model-catalog.ts`.
+ *
+ * The canonical catalog (`CatalogModel`: canonical/providerModel/contextTokens/
+ * thinking/images) is owned elsewhere. The model picker, setup flow, registry,
+ * router, and autocomplete were written against a simpler `{ id, provider,
+ * contextWindow, reasoning, recommended, note }` shape — this module adapts the
+ * canonical catalog into that shape (and adds `recommendedModel` / `validateModelId`
+ * / `suggestModels`) so those consumers stay decoupled from catalog churn.
+ */
+import { MODEL_CATALOG, findCatalogModel, catalogByProvider, formatTokens, type CatalogModel } from "./model-catalog";
+import type { ProviderName } from "./types";
+
+export interface ModelCatalogEntry {
+  id: string;
+  provider: ProviderName;
+  contextWindow: number;
+  reasoning: boolean;
+  recommended?: boolean;
+  note?: string;
+}
+
+/** Canonical ids that should be surfaced as a provider's recommended default. */
+const RECOMMENDED = new Set(["claude-3-5-sonnet", "gpt-4o", "gemini-2.0-flash", "qwen2.5"]);
+
+export function normalizeModelId(id: string): string {
+  return (id ?? "").trim().toLowerCase();
+}
+
+function adapt(m: CatalogModel): ModelCatalogEntry {
+  const reasoning = m.thinking.length > 0;
+  return {
+    id: m.canonical,
+    provider: m.provider,
+    contextWindow: m.contextTokens,
+    reasoning,
+    recommended: RECOMMENDED.has(m.canonical),
+    note: `${formatTokens(m.contextTokens)} ctx${reasoning ? ", reasoning" : ""}`,
+  };
+}
+
+/** Exact (then normalized) catalog lookup; undefined when uncatalogued. */
+export function findCatalogEntry(id: string): ModelCatalogEntry | undefined {
+  const direct = findCatalogModel(id);
+  if (direct) return adapt(direct);
+  const n = normalizeModelId(id);
+  const hit = MODEL_CATALOG.find(m => normalizeModelId(m.canonical) === n || normalizeModelId(m.providerModel) === n);
+  return hit ? adapt(hit) : undefined;
+}
+
+/** Entries for a provider, recommended first then by id. */
+export function catalogForProvider(provider: ProviderName): ModelCatalogEntry[] {
+  return catalogByProvider(provider)
+    .map(adapt)
+    .sort((a, b) => {
+      if (!!b.recommended !== !!a.recommended) return b.recommended ? 1 : -1;
+      return a.id.localeCompare(b.id);
+    });
+}
+
+/** The recommended model id for a provider (first recommended, else first listed). */
+export function recommendedModel(provider: ProviderName): string | undefined {
+  const list = catalogForProvider(provider);
+  return (list.find(e => e.recommended) ?? list[0])?.id;
+}
+
+export interface ModelValidation {
+  known: boolean;
+  entry?: ModelCatalogEntry;
+  providerMatch?: boolean;
+}
+
+/** Validate a model id against the catalog (and optionally an expected provider). */
+export function validateModelId(id: string, expectedProvider?: ProviderName): ModelValidation {
+  const entry = findCatalogEntry(id);
+  const result: ModelValidation = { known: !!entry, entry };
+  if (expectedProvider && entry) result.providerMatch = entry.provider === expectedProvider;
+  return result;
+}
+
+/** Levenshtein edit distance (small strings; iterative DP). */
+export function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array<number>(n + 1);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n]!;
+}
+
+/** "Did you mean" suggestions for an unrecognized model id (nearest canonical ids). */
+export function suggestModels(input: string, limit = 3): string[] {
+  const n = normalizeModelId(input);
+  if (!n) return [];
+  const scored = MODEL_CATALOG.map(m => {
+    const id = normalizeModelId(m.canonical);
+    const contains = id.includes(n) || n.includes(id);
+    return { id: m.canonical, score: contains ? -1 : editDistance(n, id) };
+  });
+  return scored
+    .filter(s => s.score <= Math.max(3, Math.floor(n.length / 2)))
+    .sort((a, b) => a.score - b.score)
+    .slice(0, limit)
+    .map(s => s.id);
+}
+
+/** All canonical catalog ids (for autocomplete). */
+export function catalogIds(): string[] {
+  return MODEL_CATALOG.map(m => m.canonical);
+}

package/src/ai/model-catalog.ts

@@ -0,0 +1,97 @@
+/**
+ * Static model catalog — capability metadata for well-known public models, so
+ * the TUI can show context window, max output, supported thinking levels, and
+ * image support next to a model (gjc `--list-models` design parity, reimplemented
+ * in joc's own structure). This is factual capability data about public models,
+ * not a copy of any vendor's catalog source. Live discovery
+ * (`model-discovery.ts`) remains the source of truth for *availability*; this
+ * catalog annotates known ids with capabilities.
+ */
+import type { ProviderName } from "./types";
+
+export type ThinkLevel = "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export const THINK_LEVELS: readonly ThinkLevel[] = ["minimal", "low", "medium", "high", "xhigh"];
+
+export interface CatalogModel {
+  /** joc-facing canonical id (what a user types). */
+  canonical: string;
+  provider: ProviderName;
+  /** Exact provider model id used on the wire. */
+  providerModel: string;
+  /** Approximate context window in tokens. */
+  contextTokens: number;
+  /** Approximate max output tokens. */
+  maxOutputTokens: number;
+  /** Supported thinking/reasoning levels ([] = none). */
+  thinking: ThinkLevel[];
+  /** Whether the model accepts image input. */
+  images: boolean;
+}
+
+const FULL: ThinkLevel[] = ["minimal", "low", "medium", "high", "xhigh"];
+const STD: ThinkLevel[] = ["minimal", "low", "medium", "high"];
+
+/** A curated set of common public models with their documented capabilities. */
+export const MODEL_CATALOG: readonly CatalogModel[] = [
+  // Anthropic
+  { canonical: "claude-3-5-haiku", provider: "anthropic", providerModel: "claude-3-5-haiku-latest", contextTokens: 200_000, maxOutputTokens: 8_192, thinking: [], images: true },
+  { canonical: "claude-3-5-sonnet", provider: "anthropic", providerModel: "claude-3-5-sonnet-20241022", contextTokens: 200_000, maxOutputTokens: 8_192, thinking: [], images: true },
+  { canonical: "claude-3-7-sonnet", provider: "anthropic", providerModel: "claude-3-7-sonnet-20250219", contextTokens: 200_000, maxOutputTokens: 64_000, thinking: FULL, images: true },
+  { canonical: "claude-sonnet-4", provider: "anthropic", providerModel: "claude-sonnet-4-20250514", contextTokens: 200_000, maxOutputTokens: 64_000, thinking: FULL, images: true },
+  { canonical: "claude-opus-4", provider: "anthropic", providerModel: "claude-opus-4-20250514", contextTokens: 200_000, maxOutputTokens: 32_000, thinking: FULL, images: true },
+  // OpenAI
+  { canonical: "gpt-4o", provider: "openai", providerModel: "gpt-4o", contextTokens: 128_000, maxOutputTokens: 16_384, thinking: [], images: true },
+  { canonical: "gpt-4o-mini", provider: "openai", providerModel: "gpt-4o-mini", contextTokens: 128_000, maxOutputTokens: 16_384, thinking: [], images: true },
+  { canonical: "gpt-4.1", provider: "openai", providerModel: "gpt-4.1", contextTokens: 1_000_000, maxOutputTokens: 32_768, thinking: [], images: true },
+  { canonical: "o3", provider: "openai", providerModel: "o3", contextTokens: 200_000, maxOutputTokens: 100_000, thinking: STD, images: true },
+  { canonical: "o3-mini", provider: "openai", providerModel: "o3-mini", contextTokens: 200_000, maxOutputTokens: 100_000, thinking: STD, images: false },
+  { canonical: "o4-mini", provider: "openai", providerModel: "o4-mini", contextTokens: 200_000, maxOutputTokens: 100_000, thinking: STD, images: true },
+  // Google
+  { canonical: "gemini-1.5-pro", provider: "gemini", providerModel: "gemini-1.5-pro", contextTokens: 1_000_000, maxOutputTokens: 8_192, thinking: [], images: true },
+  { canonical: "gemini-2.0-flash", provider: "gemini", providerModel: "gemini-2.0-flash", contextTokens: 1_000_000, maxOutputTokens: 8_192, thinking: [], images: true },
+  { canonical: "gemini-2.5-flash", provider: "gemini", providerModel: "gemini-2.5-flash", contextTokens: 1_000_000, maxOutputTokens: 65_536, thinking: STD, images: true },
+  { canonical: "gemini-2.5-pro", provider: "gemini", providerModel: "gemini-2.5-pro", contextTokens: 1_000_000, maxOutputTokens: 65_536, thinking: STD, images: true },
+  // Ollama (local)
+  { canonical: "qwen2.5", provider: "ollama", providerModel: "ollama/qwen2.5:0.5b", contextTokens: 32_768, maxOutputTokens: 8_192, thinking: [], images: false },
+];
+
+/** Format a token count compactly (1000 → 1K, 1_000_000 → 1M). */
+export function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1_000)}K`;
+  return String(n);
+}
+
+/** Exact lookup by canonical id or provider model id. */
+export function findCatalogModel(idOrModel: string): CatalogModel | undefined {
+  const q = idOrModel.trim();
+  return MODEL_CATALOG.find(m => m.canonical === q || m.providerModel === q || `${m.provider}/${m.providerModel}` === q);
+}
+
+/** Case-insensitive substring match over canonical + provider model id. */
+export function fuzzyMatchCatalog(query: string): CatalogModel[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  return MODEL_CATALOG.filter(m => m.canonical.toLowerCase().includes(q) || m.providerModel.toLowerCase().includes(q) || m.provider.includes(q));
+}
+
+/** Catalog entries for a single provider. */
+export function catalogByProvider(provider: ProviderName): CatalogModel[] {
+  return MODEL_CATALOG.filter(m => m.provider === provider);
+}
+
+/** Annotate a discovered/raw model id with catalog metadata, when known. */
+export function catalogMetadata(modelId: string): CatalogModel | undefined {
+  const direct = findCatalogModel(modelId);
+  if (direct) return direct;
+  // Tolerate provider-prefixed or bare provider model ids.
+  const bare = modelId.replace(/^[a-z-]+\//, "");
+  return MODEL_CATALOG.find(m => m.providerModel === bare || m.providerModel.endsWith(`/${bare}`) || m.canonical === bare);
+}
+
+/** Whether a model supports a given thinking level (per the catalog). */
+export function supportsThinking(modelId: string, level: ThinkLevel): boolean {
+  const meta = catalogMetadata(modelId);
+  return meta ? meta.thinking.includes(level) : false;
+}

package/src/ai/model-discovery.ts

@@ -0,0 +1,148 @@
+/**
+ * Live model discovery — query a provider's `models` endpoint with the resolved
+ * credential (OAuth bearer or API key) and return the model ids the account can
+ * actually use. This powers the TUI `/models` / `/model` / `/provider` flows and
+ * `joc models`, so users pick from the real, logged-in catalog instead of a
+ * static alias guess.
+ *
+ * Network access is injectable (`fetchImpl`) and every call is timeout-bounded so
+ * the TUI never hangs; failures degrade to a tagged result, never a throw.
+ */
+import { readGlobalConfig, type Config } from "../agent/state";
+import { resolveCredential, type AuthProvider, type Credential } from "../auth";
+import type { ProviderName } from "./types";
+import { PROVIDER_NAMES } from "./provider-status";
+
+export interface ProviderModelsResult {
+  provider: ProviderName;
+  /** Discovered model ids (provider-qualified where the router expects it). */
+  models: string[];
+  ok: boolean;
+  /** How the request authenticated (for display). */
+  source: "oauth" | "api_key" | "keyless" | "none";
+  /** Present on failure: a short, human-readable reason. */
+  error?: string;
+}
+
+export interface DiscoveryOptions {
+  baseUrl?: string;
+  /** Injectable fetch (tests). Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Per-request timeout; default 5000ms. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** Cap the number of returned ids per provider; default 100. */
+  limit?: number;
+}
+
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_LIMIT = 100;
+
+function anthropicHeaders(cred: Credential): Record<string, string> {
+  if (cred.kind === "oauth") {
+    return { authorization: `Bearer ${cred.token}`, "anthropic-version": "2023-06-01", "anthropic-beta": "oauth-2025-04-20" };
+  }
+  if (cred.kind === "api_key") {
+    return { "x-api-key": cred.token, "anthropic-version": "2023-06-01" };
+  }
+  return {};
+}
+
+/** Build the discovery request (url + headers) for a provider/credential. */
+export function discoveryRequest(
+  provider: ProviderName,
+  cred: Credential | undefined,
+  baseUrl?: string,
+): { url: string; headers: Record<string, string> } {
+  switch (provider) {
+    case "anthropic":
+      return { url: "https://api.anthropic.com/v1/models", headers: anthropicHeaders(cred!) };
+    case "openai": {
+      const base = (baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+      const token = cred?.kind === "oauth" || cred?.kind === "api_key" ? cred.token : "";
+      return { url: `${base}/models`, headers: token ? { Authorization: `Bearer ${token}` } : {} };
+    }
+    case "gemini": {
+      const oauth = cred?.kind === "oauth" ? cred.token : undefined;
+      const apiKey = cred?.kind === "api_key" ? cred.token : undefined;
+      const url = oauth
+        ? "https://generativelanguage.googleapis.com/v1beta/models"
+        : `https://generativelanguage.googleapis.com/v1beta/models?key=${apiKey ?? ""}`;
+      return { url, headers: oauth ? { authorization: `Bearer ${oauth}` } : {} };
+    }
+    case "ollama": {
+      const base = (baseUrl ?? "http://localhost:11434").replace(/\/$/, "");
+      return { url: `${base}/api/tags`, headers: {} };
+    }
+  }
+}
+
+/** Parse a provider's models response body into normalized model ids. */
+export function parseModelsBody(provider: ProviderName, body: unknown): string[] {
+  const data = body as { data?: { id?: string }[]; models?: { name?: string }[] };
+  if (provider === "ollama") {
+    return (data.models ?? []).map(m => `ollama/${m.name ?? ""}`).filter(s => s !== "ollama/");
+  }
+  if (provider === "gemini") {
+    return (data.models ?? []).map(m => (m.name ?? "").replace(/^models\//, "")).filter(Boolean);
+  }
+  // anthropic / openai: { data: [{ id }] }
+  return (data.data ?? []).map(m => m.id ?? "").filter(Boolean);
+}
+
+/** Discover the live model list for one provider. Never throws. */
+export async function listProviderModels(
+  provider: ProviderName,
+  opts: DiscoveryOptions = {},
+): Promise<ProviderModelsResult> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const limit = opts.limit ?? DEFAULT_LIMIT;
+
+  let cred: Credential | undefined;
+  let source: ProviderModelsResult["source"] = "keyless";
+  if (provider !== "ollama") {
+    cred = await resolveCredential(provider as AuthProvider);
+    source = cred.kind === "oauth" ? "oauth" : cred.kind === "api_key" ? "api_key" : "none";
+    const isLocalOpenAi = provider === "openai" && !!(opts.baseUrl ?? process.env.OPENAI_BASE_URL);
+    if (source === "none" && !isLocalOpenAi) {
+      return { provider, models: [], ok: false, source, error: "not logged in" };
+    }
+  }
+
+  const { url, headers } = discoveryRequest(provider, cred, opts.baseUrl);
+  const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+  const signal = opts.signal ?? AbortSignal.timeout(timeout);
+  try {
+    const res = await fetchImpl(url, { headers, signal });
+    if (!res.ok) {
+      const reason = res.status === 401 || res.status === 403 ? "auth rejected" : `HTTP ${res.status}`;
+      return { provider, models: [], ok: false, source, error: reason };
+    }
+    const body = await res.json();
+    const models = parseModelsBody(provider, body).sort().slice(0, limit);
+    return { provider, models, ok: true, source };
+  } catch (err) {
+    const msg = (err as Error)?.name === "TimeoutError" || (err as Error)?.name === "AbortError" ? "timeout" : "unreachable";
+    return { provider, models: [], ok: false, source, error: msg };
+  }
+}
+
+/**
+ * Discover live models across providers. By default only queries providers that
+ * are logged in / reachable (skips `none` cloud providers); ollama is always
+ * probed. Runs in parallel.
+ */
+export async function discoverModels(
+  opts: DiscoveryOptions & { providers?: ProviderName[]; config?: Config } = {},
+): Promise<ProviderModelsResult[]> {
+  const cfg = opts.config ?? (await readGlobalConfig());
+  const providers = opts.providers ?? [...PROVIDER_NAMES];
+  return Promise.all(
+    providers.map(p =>
+      listProviderModels(p, {
+        ...opts,
+        baseUrl: p === "ollama" ? (cfg.ollamaBaseUrl ?? opts.baseUrl) : p === "openai" ? (cfg.openaiBaseUrl ?? opts.baseUrl) : opts.baseUrl,
+      }),
+    ),
+  );
+}

package/src/ai/model-enrich.ts

@@ -0,0 +1,75 @@
+/**
+ * Live + catalog merge — annotate the OAuth/API-key-discovered model list
+ * (`model-discovery.ts`) with capability metadata from the static catalog
+ * (`model-catalog.ts`). This is the bridge that lets the TUI show context window,
+ * max output, thinking levels, and image support next to the models a user can
+ * *actually* use right now (gjc provider-table parity, applied to live results).
+ * Pure functions over discovery results + catalog; no I/O.
+ */
+import type { ProviderModelsResult } from "./model-discovery";
+import { catalogMetadata, type CatalogModel, type ThinkLevel } from "./model-catalog";
+import type { ProviderName } from "./types";
+
+export interface EnrichedModel {
+  /** Live model id as returned by discovery (provider-qualified where relevant). */
+  id: string;
+  provider: ProviderName;
+  /** Catalog capabilities when the id is known; undefined for unknown ids. */
+  meta?: CatalogModel;
+}
+
+/** Enrich a single (successful) discovery result; failed results yield []. */
+export function enrichResult(result: ProviderModelsResult): EnrichedModel[] {
+  if (!result.ok) return [];
+  return result.models.map(id => ({ id, provider: result.provider, meta: catalogMetadata(id) }));
+}
+
+/** Enrich every successful provider result, preserving provider/order. */
+export function enrichAll(results: ProviderModelsResult[]): EnrichedModel[] {
+  return results.flatMap(enrichResult);
+}
+
+/** Split into known (catalog-annotated) vs unknown counts. */
+export function knownCount(models: EnrichedModel[]): { known: number; unknown: number } {
+  let known = 0;
+  for (const m of models) if (m.meta) known++;
+  return { known, unknown: models.length - known };
+}
+
+/**
+ * Sort by capability: catalog-known models first (largest context window first),
+ * then unknown ids alphabetically. Stable, non-mutating.
+ */
+export function sortByCapability(models: EnrichedModel[]): EnrichedModel[] {
+  return [...models].sort((a, b) => {
+    if (a.meta && b.meta) {
+      if (b.meta.contextTokens !== a.meta.contextTokens) return b.meta.contextTokens - a.meta.contextTokens;
+      return a.id.localeCompare(b.id);
+    }
+    if (a.meta) return -1;
+    if (b.meta) return 1;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+export interface CapabilityFilter {
+  /** Keep only models whose catalog supports this thinking level. */
+  thinking?: ThinkLevel;
+  /** Keep only models with image input (true) / without (false). */
+  images?: boolean;
+  /** Keep only models with at least this context window. */
+  minContext?: number;
+}
+
+/** Filter enriched models by capability. Unknown-meta models are excluded when any filter is set. */
+export function filterCapable(models: EnrichedModel[], filter: CapabilityFilter): EnrichedModel[] {
+  const active = filter.thinking !== undefined || filter.images !== undefined || filter.minContext !== undefined;
+  if (!active) return models;
+  return models.filter(m => {
+    if (!m.meta) return false;
+    if (filter.thinking !== undefined && !m.meta.thinking.includes(filter.thinking)) return false;
+    if (filter.images !== undefined && m.meta.images !== filter.images) return false;
+    if (filter.minContext !== undefined && m.meta.contextTokens < filter.minContext) return false;
+    return true;
+  });
+}

package/src/ai/model-manager.ts

@@ -0,0 +1,178 @@
+import { OAUTH_FLOW_REGISTRY } from "../auth/flows";
+import { readGlobalConfig } from "../agent/state";
+import { resolveCredential, type AuthProvider, type Credential } from "../auth";
+import { anthropicAdapter } from "./providers/anthropic";
+import { openaiAdapter } from "./providers/openai";
+import { geminiAdapter } from "./providers/gemini";
+import { ollamaAdapter } from "./providers/ollama";
+import type { CallOptions, Message, ProviderAdapter, ProviderName } from "./types";
+import { expandAlias, resolveModelId, effectiveAliasesFor } from "./model-registry";
+import { findCatalogEntry, type ModelCatalogEntry } from "./model-catalog-compat";
+import { withRetry, defaultRetryable, type RetryOptions } from "../util/retry";
+import type { Config } from "../agent/state";
+
+const ADAPTERS: Record<ProviderName, ProviderAdapter> = {
+  anthropic: anthropicAdapter,
+  openai: openaiAdapter,
+  gemini: geminiAdapter,
+  ollama: ollamaAdapter,
+};
+
+export function resolveProvider(model: string): ProviderName {
+  // Catalog is authoritative for known ids (correct even when heuristics would
+  // misroute a future/edge id); heuristics handle everything uncatalogued.
+  const entry = findCatalogEntry(model);
+  if (entry) return entry.provider;
+  const m = (model ?? "").toLowerCase();
+  if (m.startsWith("ollama/")) return "ollama";
+  // OpenAI: explicit prefix, any GPT, or a reasoning model (o1/o3/o4-mini, o1-preview…).
+  if (m.startsWith("openai/") || m.includes("gpt") || /(^|\/)o\d/.test(m)) return "openai";
+  if (m.startsWith("google/") || m.includes("gemini")) return "gemini";
+  return "anthropic";
+}
+
+/** Map the configured thinking level to a default max-token budget. */
+export function thinkingMaxTokens(level?: "minimal" | "low" | "medium" | "high" | "xhigh"): number {
+  if (level === "minimal") return 1000;
+  if (level === "low") return 2000;
+  if (level === "high") return 8000;
+  if (level === "xhigh") return 16000;
+  return 4000;
+}
+
+/** Describe a model id: alias expansion + the provider it routes to. For `/model` + diagnostics. */
+export async function describeModel(input: string): Promise<{ input: string; resolved: string; provider: ProviderName }> {
+  const resolved = await resolveModelId(input);
+  return { input, resolved, provider: resolveProvider(resolved) };
+}
+
+export type ModelRole = "smol" | "slow" | "plan";
+
+/** Resolve a model role tier (smol/slow/plan) → configured tier model, else defaultModel. */
+export function resolveRoleModel(role: ModelRole, config: { defaultModel: string; roles?: { smol?: string; slow?: string; plan?: string } }): string {
+  return config.roles?.[role] || config.defaultModel;
+}
+
+export interface ModelDescription {
+  input: string;
+  resolved: string;
+  provider: ProviderName;
+  /** Catalog metadata when the resolved id is known (context window, reasoning…). */
+  entry?: ModelCatalogEntry;
+  /** Alias names that expand to the resolved id. */
+  aliases: string[];
+}
+
+/**
+ * Rich model description for the `/model` panel + diagnostics: alias expansion,
+ * routed provider, catalog metadata (context window, reasoning, recommended),
+ * and the reverse-alias list. Falls back gracefully for uncatalogued ids.
+ */
+export async function describeModelDetailed(input: string): Promise<ModelDescription> {
+  const { resolved, provider } = await describeModel(input);
+  return {
+    input,
+    resolved,
+    provider,
+    entry: findCatalogEntry(resolved),
+    aliases: await effectiveAliasesFor(resolved),
+  };
+}
+
+export interface ModelManager {
+  call(messages: Message[], options?: Partial<CallOptions>): Promise<string>;
+  stream(messages: Message[], options?: Partial<CallOptions>): AsyncIterable<string>;
+  resolveProvider: typeof resolveProvider;
+}
+
+const ALIAS_DEFAULTS = { fast: "ollama/qwen2.5:0.5b", local: "ollama/qwen2.5:0.5b", sonnet: "claude-3-5-sonnet", gpt: "gpt-4o", flash: "gemini-2.5-flash" };
+
+/**
+ * Build retry options from a config `retry` budget (gjc parity). `requestMaxRetries`
+ * counts retries (not the initial request), so total `withRetry` attempts =
+ * requestMaxRetries + 1. When unset, the `withRetry` defaults apply (3 attempts).
+ * `maxDelayMs` caps backoff when provided.
+ */
+export function resolveRetryOptions(retry: Config["retry"]): RetryOptions {
+  const opts: RetryOptions = { isRetryable: defaultRetryable };
+  if (typeof retry?.requestMaxRetries === "number") {
+    opts.retries = retry.requestMaxRetries + 1;
+  }
+  if (typeof retry?.maxDelayMs === "number") {
+    opts.maxDelayMs = retry.maxDelayMs;
+  }
+  return opts;
+}
+
+interface Resolved {
+  adapter: ProviderAdapter;
+  callOptions: CallOptions;
+  credential: Credential;
+  retry: RetryOptions;
+}
+
+async function resolveCall(options: Partial<CallOptions>): Promise<Resolved> {
+  const config = await readGlobalConfig();
+  const aliases = { ...((config as { modelAliases?: Record<string, string> }).modelAliases ?? {}) };
+  const model = expandAlias(options.model ?? config.defaultModel, { ...ALIAS_DEFAULTS, ...aliases });
+  const provider = resolveProvider(model);
+  const adapter = ADAPTERS[provider];
+
+  const baseUrl =
+    options.baseUrl ??
+    (provider === "openai" ? config.openaiBaseUrl : undefined) ??
+    (provider === "ollama" ? config.ollamaBaseUrl : undefined);
+
+  const callOptions: CallOptions = {
+    model,
+    systemPrompt: options.systemPrompt,
+    temperature: options.temperature ?? 0.2,
+    maxTokens: options.maxTokens ?? thinkingMaxTokens(config.thinkingLevel),
+    jsonMode: options.jsonMode,
+    baseUrl,
+    onUsage: options.onUsage,
+    signal: options.signal,
+  };
+
+  if (provider === "ollama") {
+    return { adapter, callOptions, credential: { kind: "none", provider: "openai" }, retry: resolveRetryOptions(config.retry) };
+  }
+
+  const credential = await resolveCredential(provider as AuthProvider);
+  let effective = credential;
+  if (effective.kind === "oauth" && OAUTH_FLOW_REGISTRY[provider as AuthProvider]?.verifiedEndToEnd === false) {
+    const apiKey = config.providers[provider as AuthProvider];
+    if (apiKey) {
+      effective = { kind: "api_key", provider: provider as AuthProvider, token: apiKey };
+    } else {
+      throw new Error(`Provider '${provider}' has only an OAuth token, but its OAuth backend is not compatible with the bundled adapter. Set ${provider.toUpperCase()}_API_KEY (or run 'joc setup') to use ${model}.`);
+    }
+  }
+
+  const isLocalOpenAi = provider === "openai" && !!baseUrl;
+  if (effective.kind === "none" && !isLocalOpenAi) {
+    throw new Error(
+      `No credential for provider '${provider}'. Run 'joc setup', 'joc auth login', or set ${provider.toUpperCase()}_API_KEY / ${provider.toUpperCase()}_OAUTH_TOKEN.`
+    );
+  }
+  return { adapter, callOptions, credential: effective, retry: resolveRetryOptions(config.retry) };
+}
+
+export function createModelManager(): ModelManager {
+  return {
+    resolveProvider,
+    async call(messages, options = {}) {
+      const { adapter, callOptions, credential, retry } = await resolveCall(options);
+      return withRetry(() => adapter.call(messages, callOptions, credential), retry);
+    },
+    async *stream(messages, options = {}) {
+      const { adapter, callOptions, credential, retry } = await resolveCall(options);
+      if (adapter.stream) {
+        yield* adapter.stream(messages, callOptions, credential);
+      } else {
+        // Fallback: providers without streaming yield the full response as one chunk.
+        yield await withRetry(() => adapter.call(messages, callOptions, credential), retry);
+      }
+    },
+  };
+}