@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/llm/client-base.js

@@ -0,0 +1,137 @@
+/**
+ * Abstract base class for all LLM provider clients.
+ */
+import { LLMError, ContextLimitError, LLMRateLimitError } from "../exceptions.js";
+import { logger } from "../logging/logger.js";
+export class LLMClientBase {
+    config;
+    provider;
+    model;
+    temperature;
+    maxTokens;
+    timeout;
+    retryMaxAttempts;
+    enableStreaming;
+    /**
+     * Process-wide hook fired on every LLM response. The CLI installs this in
+     * main.ts to feed the cost tracker; lives on the base class so every code
+     * path (REPL, run, arena, sub-agents) reports through one funnel without
+     * each call site needing to remember.
+     */
+    static onUsage;
+    usage = {
+        records: [],
+        totalPromptTokens: 0,
+        totalCompletionTokens: 0,
+        totalTokens: 0,
+        requestCount: 0,
+    };
+    constructor(config) {
+        this.config = config;
+        this.provider = config.provider;
+        this.model = config.model;
+        this.temperature = config.temperature ?? 0.3;
+        this.maxTokens = config.maxTokens ?? 8192;
+        this.timeout = config.timeout ?? 120_000;
+        this.retryMaxAttempts = config.retryMaxAttempts ?? 3;
+        this.enableStreaming = config.enableStreaming ?? true;
+        this.initClient();
+    }
+    recordUsage(usage, options) {
+        if (options?.recordUsage === false)
+            return;
+        this.usage.records.push(usage);
+        this.usage.totalPromptTokens += usage.promptTokens;
+        this.usage.totalCompletionTokens += usage.completionTokens;
+        this.usage.totalTokens += usage.totalTokens;
+        this.usage.requestCount++;
+        LLMClientBase.onUsage?.(this.model, usage);
+    }
+    getUsage() {
+        return { ...this.usage };
+    }
+    async withRetry(fn, maxAttempts) {
+        const attempts = maxAttempts ?? this.retryMaxAttempts;
+        let lastError;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastError = err;
+                if (err instanceof ContextLimitError)
+                    throw err;
+                if (err instanceof LLMRateLimitError) {
+                    const waitMs = (err.retryAfter ?? attempt * 2) * 1000;
+                    logger.warn("llm.retry", {
+                        cat: "llm",
+                        provider: this.provider,
+                        model: this.model,
+                        attempt,
+                        of: attempts,
+                        reason: "rate_limit",
+                        waitMs,
+                    });
+                    await new Promise((r) => setTimeout(r, waitMs));
+                    continue;
+                }
+                // 4xx (except 429, handled above as LLMRateLimitError) is a
+                // deterministic client-side mistake — bad message sequence,
+                // unauthorized, model not found, prompt too long. Retrying
+                // gives the same answer 3 times with growing backoff and
+                // burns ~9 s of user time. Surface immediately.
+                if (isClientError(err)) {
+                    logger.warn("llm.client_error_no_retry", {
+                        cat: "llm",
+                        provider: this.provider,
+                        model: this.model,
+                        status: err.status,
+                        error: err.message,
+                    });
+                    throw err;
+                }
+                if (attempt === attempts) {
+                    logger.error("llm.exhausted", {
+                        cat: "llm",
+                        provider: this.provider,
+                        model: this.model,
+                        attempts,
+                        error: err.message,
+                    });
+                    break;
+                }
+                const backoff = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
+                logger.warn("llm.retry", {
+                    cat: "llm",
+                    provider: this.provider,
+                    model: this.model,
+                    attempt,
+                    of: attempts,
+                    reason: "error",
+                    error: err.message,
+                    backoffMs: backoff,
+                });
+                await new Promise((r) => setTimeout(r, backoff));
+            }
+        }
+        throw lastError ?? new LLMError("Unknown LLM error");
+    }
+}
+/**
+ * Detect HTTP 4xx errors from provider SDKs so withRetry can bail
+ * without burning backoff time. OpenAI/Anthropic SDKs both attach a
+ * numeric `status` to their error objects; we treat 400-499 as
+ * non-retryable (429 is handled separately above as a rate-limit).
+ *
+ * Network errors and 5xx fall through and remain retryable.
+ */
+function isClientError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const status = err.status;
+    if (typeof status !== "number")
+        return false;
+    if (status === 429)
+        return false;
+    return status >= 400 && status < 500;
+}

package/dist/llm/client-factory.d.ts

@@ -0,0 +1,10 @@
+/**
+ * LLM provider factory with registry pattern.
+ */
+import type { LLMConfig } from "../types.js";
+import type { LLMClientBase } from "./client-base.js";
+type ProviderConstructor = new (config: LLMConfig) => LLMClientBase;
+declare const PROVIDER_REGISTRY: Map<string, ProviderConstructor>;
+export declare function registerProvider(name: string, cls: ProviderConstructor): void;
+export declare function createLLMClient(config: LLMConfig): Promise<LLMClientBase>;
+export { PROVIDER_REGISTRY };

package/dist/llm/client-factory.js

@@ -0,0 +1,29 @@
+/**
+ * LLM provider factory with registry pattern.
+ */
+import { LLMError } from "../exceptions.js";
+const PROVIDER_REGISTRY = new Map();
+export function registerProvider(name, cls) {
+    PROVIDER_REGISTRY.set(name, cls);
+}
+export async function createLLMClient(config) {
+    let Cls = PROVIDER_REGISTRY.get(config.provider);
+    if (!Cls) {
+        // Auto-register built-in providers on first use
+        if (config.provider === "anthropic") {
+            const { AnthropicClient } = await import("./providers/anthropic.js");
+            registerProvider("anthropic", AnthropicClient);
+            Cls = AnthropicClient;
+        }
+        else if (config.provider === "openai") {
+            const { OpenAIClient } = await import("./providers/openai.js");
+            registerProvider("openai", OpenAIClient);
+            Cls = OpenAIClient;
+        }
+    }
+    if (!Cls) {
+        throw new LLMError(`Unknown LLM provider: ${config.provider}. Available: ${[...PROVIDER_REGISTRY.keys()].join(", ")}`);
+    }
+    return new Cls(config);
+}
+export { PROVIDER_REGISTRY };

package/dist/llm/model-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cache file IO for per-provider model lists.
+ *
+ * One file per provider key under <cacheDir>/<providerKey>.json. TTL is
+ * 7 days. Callers decide whether to honor staleness — readCache just
+ * reads, isStale just checks. Malformed/missing files yield undefined.
+ */
+export interface CachedModel {
+    id: string;
+    contextLength: number;
+    maxOutputTokens: number;
+}
+export interface ModelCacheFile {
+    fetchedAt: string;
+    providerKey: string;
+    models: CachedModel[];
+}
+export declare function readCache(cacheDir: string, providerKey: string): ModelCacheFile | undefined;
+export declare function writeCache(cacheDir: string, providerKey: string, models: CachedModel[]): ModelCacheFile;
+export declare function isStale(file: ModelCacheFile, now?: number): boolean;
+export declare function defaultCacheDir(): string;

package/dist/llm/model-cache.js

@@ -0,0 +1,46 @@
+/**
+ * Cache file IO for per-provider model lists.
+ *
+ * One file per provider key under <cacheDir>/<providerKey>.json. TTL is
+ * 7 days. Callers decide whether to honor staleness — readCache just
+ * reads, isStale just checks. Malformed/missing files yield undefined.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const TTL_MS = 7 * 24 * 3600 * 1000;
+export function readCache(cacheDir, providerKey) {
+    const path = join(cacheDir, `${providerKey}.json`);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.models))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeCache(cacheDir, providerKey, models) {
+    if (!existsSync(cacheDir))
+        mkdirSync(cacheDir, { recursive: true });
+    const payload = {
+        fetchedAt: new Date().toISOString(),
+        providerKey,
+        models,
+    };
+    writeFileSync(join(cacheDir, `${providerKey}.json`), JSON.stringify(payload, null, 2), "utf-8");
+    return payload;
+}
+export function isStale(file, now = Date.now()) {
+    const ts = Date.parse(file.fetchedAt);
+    if (!Number.isFinite(ts))
+        return true;
+    return now - ts > TTL_MS;
+}
+export function defaultCacheDir() {
+    return join(homedir(), ".code-shell", "cache", "models");
+}

package/dist/llm/model-fetcher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fetch a provider's model list from its official /v1/models endpoint
+ * (or the local OpenRouter snapshot). Normalizes wildly different
+ * response shapes into a uniform `CachedModel[]`, applies the kind's
+ * chat-only filter, and writes to disk cache.
+ *
+ * Network failures don't throw — they return `{ models: [], error }`
+ * so the UI can prompt the user to refresh later or fall back to
+ * manual entry.
+ */
+import { type ProviderKindName } from "./provider-kinds.js";
+import { type ModelCacheFile } from "./model-cache.js";
+export interface FetcherProvider {
+    key: string;
+    kind: ProviderKindName;
+    baseUrl: string;
+    apiKey: string | undefined;
+    modelsPath?: string;
+}
+export interface FetchOptions {
+    cacheDir: string;
+    refresh?: boolean;
+    timeoutMs?: number;
+}
+export interface FetchResult extends ModelCacheFile {
+    error?: string;
+    fromCache?: boolean;
+}
+export declare function fetchModelList(provider: FetcherProvider, opts: FetchOptions): Promise<FetchResult>;

package/dist/llm/model-fetcher.js

@@ -0,0 +1,282 @@
+/**
+ * Fetch a provider's model list from its official /v1/models endpoint
+ * (or the local OpenRouter snapshot). Normalizes wildly different
+ * response shapes into a uniform `CachedModel[]`, applies the kind's
+ * chat-only filter, and writes to disk cache.
+ *
+ * Network failures don't throw — they return `{ models: [], error }`
+ * so the UI can prompt the user to refresh later or fall back to
+ * manual entry.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { getKindMeta, } from "./provider-kinds.js";
+import { readCache, writeCache, isStale, } from "./model-cache.js";
+import { listStaticModels, hasStaticCatalog, } from "../data/static-catalogs.js";
+import { findOpenRouterModel } from "../data/openrouter-models.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const OPENROUTER_SNAPSHOT = join(HERE, "..", "data", "openrouter-models.json");
+export async function fetchModelList(provider, opts) {
+    const meta = getKindMeta(provider.kind);
+    if (!opts.refresh) {
+        const cached = readCache(opts.cacheDir, provider.key);
+        if (cached && !isStale(cached))
+            return { ...cached, fromCache: true };
+    }
+    if (provider.kind === "openrouter") {
+        return loadOpenRouterSnapshot(provider.key, opts.cacheDir);
+    }
+    try {
+        const path = provider.modelsPath ?? meta.modelsPath;
+        const url = new URL(joinUrl(provider.baseUrl, path));
+        const headers = meta.authHeader(provider.apiKey ?? "");
+        if (meta.authQuery) {
+            const q = meta.authQuery(provider.apiKey ?? "");
+            for (const [k, v] of Object.entries(q))
+                url.searchParams.set(k, v);
+        }
+        const res = await fetch(url.toString(), {
+            headers: { Accept: "application/json", ...headers },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
+        });
+        if (!res.ok) {
+            // 401/403 means the key is wrong (or revoked) — falling back to the
+            // static catalog would show the user a model list they can't actually
+            // call, deferring the real error to the first chat turn. Surface the
+            // auth failure now with an empty list.
+            const isAuth = res.status === 401 || res.status === 403;
+            return errorResult(provider.key, opts.cacheDir, `HTTP ${res.status}`, isAuth ? undefined : provider.kind);
+        }
+        const payload = (await res.json());
+        const raw = normalize(payload, meta.protocol);
+        const filtered = raw.filter((m) => meta.chatFilter(m.id));
+        const sorted = sortByRecency(filtered);
+        const enriched = enrichFromStaticCatalog(provider.kind, sorted);
+        const finalModels = enrichFromOpenRouterSnapshot(provider.kind, enriched);
+        const file = writeCache(opts.cacheDir, provider.key, finalModels);
+        return file;
+    }
+    catch (err) {
+        const msg = err.message || String(err);
+        return errorResult(provider.key, opts.cacheDir, msg, provider.kind);
+    }
+}
+/**
+ * Left-join static-catalog metadata onto live /models results. The live
+ * endpoint is the source of truth for which ids exist; the static table
+ * fills in contextLength / maxOutputTokens / pricing that most vendors
+ * don't expose on /v1/models. Live values are preserved when present.
+ *
+ * Models present only in the static table (not returned by the live API
+ * — e.g. newly-deprecated ids or vendor-hidden previews) are appended at
+ * the end so the picker can still show them.
+ */
+function enrichFromStaticCatalog(kind, live) {
+    if (!hasStaticCatalog(kind))
+        return live;
+    const staticModels = listStaticModels(kind);
+    const staticById = new Map(staticModels.map((m) => [m.id, m]));
+    const liveIds = new Set(live.map((m) => m.id));
+    const merged = live.map((m) => {
+        const stat = staticById.get(m.id);
+        if (!stat)
+            return m;
+        return {
+            id: m.id,
+            contextLength: m.contextLength > 0 ? m.contextLength : stat.contextLength,
+            maxOutputTokens: m.maxOutputTokens > 0 ? m.maxOutputTokens : stat.maxOutputTokens,
+        };
+    });
+    for (const stat of staticModels) {
+        if (!liveIds.has(stat.id)) {
+            merged.push({
+                id: stat.id,
+                contextLength: stat.contextLength,
+                maxOutputTokens: stat.maxOutputTokens,
+            });
+        }
+    }
+    return merged;
+}
+/**
+ * Provider kind → OpenRouter vendor prefix. OpenRouter ids are
+ * `<vendor>/<model>`; native providers return bare model ids
+ * (`gpt-5.5`, `claude-opus-4.6`). To cross-reference, we prepend
+ * the kind's vendor prefix. Kinds that don't map to a single
+ * OpenRouter vendor (groq is infra not a model vendor, ollama is
+ * local, openrouter is itself, custom is unknown) are omitted —
+ * fallback simply does nothing for them.
+ */
+const OPENROUTER_VENDOR_BY_KIND = {
+    openai: "openai",
+    anthropic: "anthropic",
+    deepseek: "deepseek",
+    google: "google",
+    zai: "z-ai",
+    xai: "x-ai",
+    mistral: "mistralai",
+};
+/**
+ * Final fallback: any model still missing contextLength or
+ * maxOutputTokens after the per-provider static catalog merge
+ * gets cross-referenced against the bundled OpenRouter snapshot
+ * (`<vendor>/<id>`). Live values from the upstream `/models`
+ * call always win; this only fills zeros.
+ */
+function enrichFromOpenRouterSnapshot(kind, models) {
+    const vendor = OPENROUTER_VENDOR_BY_KIND[kind];
+    if (!vendor)
+        return models;
+    return models.map((m) => {
+        if (m.contextLength > 0 && m.maxOutputTokens > 0)
+            return m;
+        const hit = findOpenRouterModel(`${vendor}/${m.id}`);
+        if (!hit)
+            return m;
+        return {
+            id: m.id,
+            contextLength: m.contextLength > 0 ? m.contextLength : hit.contextLength,
+            maxOutputTokens: m.maxOutputTokens > 0 ? m.maxOutputTokens : hit.maxOutputTokens,
+        };
+    });
+}
+/**
+ * Newest-first ordering. Vendors reliably encode recency as a version
+ * suffix on the model family name: `gpt-5.5` > `gpt-5.4` > `gpt-5`,
+ * `claude-4.7` > `claude-4.6`, `gemini-2.5` > `gemini-2.0`. We extract
+ * that single "family version" number and sort descending.
+ *
+ * Versions can appear three ways:
+ *   - decimal:        `gpt-5.5`, `claude-4.7`           → 5.5 / 4.7
+ *   - dash-decimal:   `claude-sonnet-4-6`,              → 4.6
+ *                     `claude-3-5-haiku`                → 3.5
+ *   - bare integer:   `gpt-4`, `o3`, `o4-mini`          → 4 / 3 / 4
+ *
+ * Dash-decimal is Anthropic's house style: `claude-<family>-<major>-<minor>`.
+ * We only treat `<small int>-<small int>` as a version when both halves
+ * look like version components (1–2 digits each), so we don't accidentally
+ * turn snapshot-ish `gpt-4-0613` into 4.613.
+ *
+ * What we deliberately ignore:
+ *   - 4-digit date-ish numbers like `0613`, `1106`, `0914` baked into
+ *     legacy ids. These are snapshots, not versions.
+ *
+ * Tie-breaker: shorter id wins (so `gpt-5.5` sorts above `gpt-5.5-pro`),
+ * then alphabetic for stable output.
+ */
+function sortByRecency(models) {
+    const versionOf = (id) => {
+        // Match a version *as a token boundary* — preceded by start or
+        // a non-digit, and not followed by another digit. Decimals win
+        // over bare integers if both match.
+        const decimal = id.match(/(?:^|[^\d])(\d+\.\d+)(?!\d)/);
+        if (decimal)
+            return Number(decimal[1]);
+        // Dash-decimal (Anthropic style): both halves 1–2 digits to avoid
+        // catching dated snapshots like `gpt-4-0613` (4-digit second half).
+        const dashDecimal = id.match(/(?:^|[^\d])(\d{1,2})-(\d{1,2})(?!\d)/);
+        if (dashDecimal)
+            return Number(`${dashDecimal[1]}.${dashDecimal[2]}`);
+        // Bare-integer version: 1–2 digits only (skips `0613`-style dates).
+        const integer = id.match(/(?:^|[^\d])(\d{1,2})(?!\d)/);
+        if (integer)
+            return Number(integer[1]);
+        return -1;
+    };
+    return [...models].sort((a, b) => {
+        const va = versionOf(a.id);
+        const vb = versionOf(b.id);
+        if (va !== vb)
+            return vb - va;
+        if (a.id.length !== b.id.length)
+            return a.id.length - b.id.length;
+        return a.id.localeCompare(b.id);
+    });
+}
+function normalize(payload, protocol) {
+    switch (protocol) {
+        case "ollama": {
+            const p = payload;
+            return (p.models ?? []).map((m) => ({ id: m.name, contextLength: 0, maxOutputTokens: 0 }));
+        }
+        case "anthropic-style": {
+            const p = payload;
+            return (p.data ?? []).map((m) => ({
+                id: m.id,
+                contextLength: m.context_window ?? 200_000,
+                maxOutputTokens: m.max_output_tokens ?? 0,
+            }));
+        }
+        case "gemini": {
+            const p = payload;
+            return (p.models ?? []).map((m) => ({
+                id: m.name.replace(/^models\//, ""),
+                contextLength: m.inputTokenLimit ?? 0,
+                maxOutputTokens: m.outputTokenLimit ?? 0,
+            }));
+        }
+        case "openai-compat": {
+            const p = payload;
+            return (p.data ?? []).map((m) => ({
+                id: m.id,
+                contextLength: m.context_window ?? m.context_length ?? 0,
+                maxOutputTokens: m.max_completion_tokens ?? 0,
+            }));
+        }
+    }
+    // exhaustiveness: TS error if a new ProviderProtocol is added.
+    const _exhaustive = protocol;
+    return _exhaustive;
+}
+function loadOpenRouterSnapshot(providerKey, cacheDir) {
+    if (!existsSync(OPENROUTER_SNAPSHOT)) {
+        return errorResult(providerKey, cacheDir, "openrouter snapshot missing");
+    }
+    try {
+        const snapshot = JSON.parse(readFileSync(OPENROUTER_SNAPSHOT, "utf-8"));
+        const models = (snapshot.models ?? []).map((m) => ({
+            id: m.id,
+            contextLength: m.contextLength ?? 0,
+            maxOutputTokens: m.maxOutputTokens ?? 0,
+        }));
+        return writeCache(cacheDir, providerKey, models);
+    }
+    catch (err) {
+        return errorResult(providerKey, cacheDir, err.message);
+    }
+}
+function errorResult(providerKey, cacheDir, error, kind) {
+    const stale = readCache(cacheDir, providerKey);
+    if (stale)
+        return { ...stale, error, fromCache: true };
+    if (kind && hasStaticCatalog(kind)) {
+        const models = listStaticModels(kind).map((m) => ({
+            id: m.id,
+            contextLength: m.contextLength,
+            maxOutputTokens: m.maxOutputTokens,
+        }));
+        return {
+            fetchedAt: new Date().toISOString(),
+            providerKey,
+            models,
+            error,
+        };
+    }
+    return {
+        fetchedAt: new Date().toISOString(),
+        providerKey,
+        models: [],
+        error,
+    };
+}
+function joinUrl(base, path) {
+    if (!base)
+        return path;
+    // Allow a per-provider override to specify an absolute URL — needed for
+    // providers like Gemini whose chat completions live under /v1beta/openai
+    // but model listing stays on /v1beta/models.
+    if (/^https?:\/\//i.test(path))
+        return path;
+    return `${base.replace(/\/$/, "")}${path.startsWith("/") ? "" : "/"}${path}`;
+}

package/dist/llm/model-pool.d.ts

@@ -0,0 +1,95 @@
+/**
+ * ModelPool — runtime model registry.
+ *
+ * Holds all available models loaded from settings. Provides:
+ *   - `get(key?)` — retrieve a model config by key, or the active one
+ *   - `switch(key)` — change the active model
+ *   - `list()` — list all available models
+ *   - `register(entry)` — add a model at runtime
+ *
+ * Consumers:
+ *   - Engine/TurnLoop: `pool.get()` for the active model
+ *   - Arena: `pool.get("sonnet")` to resolve participants by key
+ *   - /model command: `pool.switch("haiku")` for hot-swap
+ */
+import type { LLMConfig } from "../types.js";
+export interface ModelEntry {
+    /** Short alias: "claude", "sonnet", "haiku", "gpt", "deepseek" */
+    key: string;
+    /** Human-readable label. Auto-generated from model path if not provided. */
+    label?: string;
+    provider: string;
+    /** Full model path: "anthropic/claude-opus-4-6" */
+    model: string;
+    baseUrl?: string;
+    apiKey?: string;
+    maxOutputTokens?: number;
+    /** Per-model context window size. Falls back to config.maxContextTokens → 200_000. */
+    maxContextTokens?: number;
+    /** Optional reference into ProviderCatalog. When set, baseUrl/apiKey
+     *  come from the catalog unless the entry overrides them. */
+    providerKey?: string;
+    /**
+     * Per-model thinking override. Wins over the provider-level setting
+     * (ProviderCatalog entry's `thinking`). Useful when models in the same
+     * provider need different defaults — e.g. DeepSeek V4 Pro off but
+     * V4 Flash on.
+     */
+    thinking?: "enabled" | "disabled";
+}
+export declare class ModelPool {
+    private models;
+    private activeKey;
+    private providerCatalog;
+    private cacheDir;
+    setProviderCatalog(cat: import("./provider-catalog.js").ProviderCatalog): void;
+    setCacheDir(dir: string): void;
+    /**
+     * For each entry that lacks an explicit maxContextTokens but has a
+     * providerKey, fill it in. Lookup order:
+     *   1. The provider's cached /v1/models response (most authoritative —
+     *      it's what the vendor itself returned at last sync).
+     *   2. The bundled OpenRouter snapshot, keyed by `<vendor>/<id>` — covers
+     *      the common case where a direct-provider model (e.g. `gpt-5.5`)
+     *      is also published on OpenRouter with full metadata.
+     *   3. A final 200k floor so unknown models still get *some* context
+     *      window rather than tripping max-token math downstream.
+     *
+     * Entries with an explicit maxContextTokens (set by the user in settings
+     * or by a prior code path) are left alone — we never overwrite what the
+     * user typed in.
+     */
+    reloadCachedContextWindows(): void;
+    private resolveContextWindow;
+    /**
+     * Build a pool from an array of model entries.
+     * The first entry (or the one matching `defaultKey`) becomes active.
+     */
+    constructor(entries?: ModelEntry[], defaultKey?: string);
+    /** Register a model at runtime. */
+    register(entry: ModelEntry): void;
+    /** Fill in known defaults (e.g. context window for DeepSeek V4) when the entry doesn't specify them. */
+    private withBuiltinDefaults;
+    /** Switch the active model. Throws if key not found. */
+    switch(key: string): ModelEntry;
+    /** Get a model by key. No key = active model. Returns undefined if not found. */
+    get(key?: string): ModelEntry | undefined;
+    /** Get the active model key. */
+    getActiveKey(): string | undefined;
+    /** List all registered models. */
+    list(): ModelEntry[];
+    /** Number of registered models. */
+    get size(): number;
+    /** Check if a key exists. */
+    has(key: string): boolean;
+    /**
+     * Build an LLMConfig for a given model entry, merging with a base config
+     * (inherits apiKey, baseUrl, etc. from the base if not set on the entry).
+     */
+    toLLMConfig(entry: ModelEntry, base?: Partial<LLMConfig>): LLMConfig;
+    /**
+     * Build an LLMConfig for the active model (or a specific key),
+     * merging with a base config.
+     */
+    resolveLLMConfig(key?: string, base?: Partial<LLMConfig>): LLMConfig | undefined;
+}