@verevoir/review 0.3.1 → 0.3.2

package/node_modules/@verevoir/llm/dist/index.d.ts

@@ -0,0 +1,751 @@
+/**
+ * @verevoir/llm — provider-agnostic LLM call surface.
+ *
+ * The core export holds shared types, accounting helpers, and the
+ * `chat()` contract that every provider adapter implements. SDK
+ * adapters live in subpaths (./anthropic, ./google planned). Consumers
+ * import the subpath(s) they use; the unused SDK never enters their
+ * bundle.
+ */
+/**
+ * Model-class semantic — what kind of work the call is doing.
+ *
+ * - `reasoning`: open-ended judgement, cross-document synthesis,
+ *   nuanced chat. The conservative default for sites that have to
+ *   think across context.
+ * - `drafting`: produce substantial new content — code, prose, drafts.
+ *   The mid-tier workhorse, between reasoning and extraction. Maps to
+ *   Sonnet on Anthropic; on providers with no distinct mid it resolves
+ *   up to the reasoning model.
+ * - `extraction`: structured turn-text-into-shape tasks (URLs from a
+ *   conversation, config from a paragraph). Quick, predictable,
+ *   constrained output. Smallest competent model.
+ *
+ * Adapters map each class to a concrete provider model id (e.g.
+ * `reasoning` → `claude-opus-4-7` on Anthropic). The class travels
+ * through to {@link TokenUsage} as `direction` so cost rollups can
+ * break down spend per direction natively.
+ */
+export type ModelClass = 'reasoning' | 'drafting' | 'extraction';
+export * from './pricing.js';
+export { setModelSpanSink, emitModelSpan, type ModelSpan, type ModelSpanSink, } from './audit-hook.js';
+export { withAdvisor, type AdvisorConfig, type ConsultInfo } from './pair.js';
+/**
+ * Per-turn content. Plain `string` is the convenient v0 shape for
+ * pure-text conversations. `ContentBlock[]` carries structured
+ * content needed for multi-turn tool loops (tool_use + tool_result
+ * blocks) and lays the schema for future multimodal blocks (image,
+ * document) without a second migration.
+ *
+ * Adapters accept either form; pass a string if you have no
+ * structure to preserve.
+ */
+export type TurnContent = string | ContentBlock[];
+/**
+ * Discriminated union of message-content blocks. Mirrors Anthropic's
+ * native shape so the adapter doesn't have to translate. `image` and
+ * `document` carry inline base64 data the same way Anthropic's own
+ * SDK does, so `@verevoir/llm/anthropic` passes them through unchanged
+ * — both as user-turn content and inside a `tool_result`'s own
+ * `content`. Adapters that don't support a given block kind (every
+ * adapter except Anthropic, for `image`/`document`; Google for
+ * `tool_result`, etc.) surface {@link UnsupportedContentBlockError}
+ * rather than silently dropping or stringifying it — see {@link
+ * collapseContentToText}.
+ */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+        data: string;
+    };
+} | {
+    type: 'document';
+    source: {
+        type: 'base64';
+        media_type: 'application/pdf';
+        data: string;
+    };
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    /**
+     * Result returned by the tool. A plain `string` behaves exactly
+     * as before this field widened — use JSON for structured text
+     * results. `ContentBlock[]` lets a tool return an `image` or
+     * `document` (or `text`) block straight through on an adapter
+     * that can carry it (currently only `@verevoir/llm/anthropic` —
+     * see {@link ToolExecutor}); an adapter that cannot carry a
+     * block found here throws {@link UnsupportedContentBlockError}
+     * rather than silently dropping or stringifying it.
+     */
+    content: string | ContentBlock[];
+    /** True when the tool errored; the model treats it as a failure. */
+    is_error?: boolean;
+};
+/**
+ * Thrown by {@link collapseContentToText} when a provider that can
+ * only carry text content — every adapter except
+ * `@verevoir/llm/anthropic` — is handed a {@link ContentBlock} it
+ * cannot represent (an `image`, `document`, `tool_use`, or
+ * `tool_result` block appearing where only `text` is meaningful).
+ * Named by `provider` and `blockType` so the failure is attributable,
+ * never a silent drop or a stringified block object.
+ */
+export declare class UnsupportedContentBlockError extends Error {
+    readonly provider: string;
+    readonly blockType: string;
+    constructor(provider: string, blockType: string);
+}
+/**
+ * Collapse {@link TurnContent} — or a {@link ContentBlock}'s own
+ * `tool_result.content` — to the plain string a text-only provider
+ * needs. A `string` passes through unchanged. A `ContentBlock[]`
+ * collapses to its concatenated `text` when EVERY block is `type:
+ * 'text'`; the first block of any other type throws {@link
+ * UnsupportedContentBlockError} naming `provider` and that block's
+ * type, rather than silently dropping it or stringifying the block
+ * object.
+ *
+ * Used by every adapter except `@verevoir/llm/anthropic`, whose own
+ * native wire shape already mirrors `ContentBlock` — it passes
+ * `image` and `document` blocks through unchanged instead of calling
+ * this.
+ */
+export declare function collapseContentToText(provider: string, content: TurnContent): string;
+/** A single message in a conversation. */
+export interface Turn {
+    role: 'user' | 'assistant';
+    content: TurnContent;
+}
+/**
+ * Which credential mechanism actually authenticated a call — reported
+ * POSITIVELY on every {@link TokenUsage}, never left to be inferred from
+ * what is absent. Every adapter sets this at the exact point it already
+ * knows the answer (e.g. the Anthropic adapter's `resolveClient` already
+ * computes whether a call used the subscription token or the metered key;
+ * before this field existed, that fact was computed and discarded rather
+ * than reported).
+ *
+ * `'api-key'` covers every metered-key provider, and — for now — any
+ * adapter with only one credential path (Google, the OpenAI-compatible
+ * factory). `'subscription-oauth'` is the Anthropic Claude subscription
+ * token path. `'mixed'` is for an AGGREGATED result (e.g.
+ * {@link ChatWithToolLoopResult.usage}, which sums usage across several
+ * underlying calls) whose calls did not all use the same route — reported
+ * rather than picking one arbitrarily and hiding that the other happened.
+ *
+ * New adapters or new mechanisms add new values here rather than reusing
+ * one that does not describe them.
+ */
+export type CredentialRoute = 'api-key' | 'subscription-oauth' | 'mixed';
+/**
+ * Per-call token + provenance record. Returned alongside every reply.
+ * The (provider, model, direction) triple is the model-direction grid
+ * used for cost rollups.
+ */
+export interface TokenUsage {
+    /** Provider id, e.g. `anthropic`, `google`. */
+    provider: string;
+    /** Concrete model id used for the call, e.g. `claude-opus-4-7`. */
+    model: string;
+    /** The model-class semantic the caller asked for. */
+    direction: ModelClass;
+    /** Which credential mechanism served this call — see {@link CredentialRoute}. */
+    route: CredentialRoute;
+    /**
+     * The version of the SUBSTRATE that served this call, when the substrate
+     * is an external program whose version can drift independently of this
+     * package's own release — e.g. the installed `claude` CLI binary
+     * (`@verevoir/llm/claude-cli`). `undefined` for a direct API adapter
+     * (Anthropic, Google, OpenAI-compatible): there the wire protocol is
+     * this package's own responsibility, so nothing about "which version
+     * answered" is unknown or needs reporting the same way.
+     *
+     * Same field family as {@link route}, one level down: `route` answers
+     * WHICH credential mechanism served a call; this answers WHICH VERSION
+     * of that mechanism did. Recorded for the same reason `route` is — a
+     * call whose substrate version is not attributable cannot be compared
+     * across a version change. Concretely, this is what lets a controlled
+     * CLI upgrade be isolated as the one variable that changed between two
+     * otherwise-identical runs, rather than an unrecorded confound.
+     */
+    substrateVersion?: string;
+    /** Standard input tokens. */
+    inputTokens: number;
+    /** Output tokens (completion + tool-use args). */
+    outputTokens: number;
+    /** Tokens written to provider cache on this call. */
+    cacheCreationInputTokens: number;
+    /** Tokens read from provider cache on this call. */
+    cacheReadInputTokens: number;
+    /**
+     * Anthropic's 5-minute-TTL cache-write tokens, when the call used extended
+     * cache TTLs and the provider reported the split. `undefined` on every
+     * other call — most calls don't use extended TTLs, and no adapter besides
+     * Anthropic's reports this split. See `src/otel.ts` for the matching span
+     * attribute (not part of the GenAI semconv, so it's a custom one there).
+     */
+    cacheCreationEphemeral5mInputTokens?: number;
+    /**
+     * Anthropic's 1-hour-TTL cache-write tokens — see
+     * {@link cacheCreationEphemeral5mInputTokens}.
+     */
+    cacheCreationEphemeral1hInputTokens?: number;
+    /**
+     * The provider's own id for this call, when `chat()`'s adapter can get
+     * one — real, but not always a literal HTTP `request-id` header: the
+     * Anthropic adapter uses the message id (its streaming surface doesn't
+     * expose response headers); the OpenAI, DeepSeek and OpenAI-compatible
+     * adapters use the SDK response object's own `id` field. `undefined`
+     * when the adapter has none to offer (currently: Google), and on every
+     * adapter's `chatWithTools` / `chatWithToolLoop` paths, which don't yet
+     * wire this through.
+     */
+    providerRequestId?: string;
+    /**
+     * The provider's own reported cost for this call, in USD, when the
+     * provider's payload carries one (e.g. Claude Code's terminal result
+     * event's `total_cost_usd`). NEVER COMPUTED from a price table — this
+     * is the provider's own figure, relayed as-is, or `undefined` when the
+     * adapter's transport doesn't see one.
+     */
+    costUsdReported?: number;
+    /**
+     * claude-cli only: the CLI's own session id for this call, kept purely
+     * for correlation. Reused across EVERY turn on a held session, so —
+     * unlike {@link providerRequestId} — it is never unique per call, and
+     * must never be read as one. `undefined` on every other adapter, and
+     * on claude-cli's own one-shot path too (there it would just duplicate
+     * `providerRequestId`'s own value).
+     */
+    sessionId?: string;
+}
+/** Live-progress narration emitted by the model during a long call. */
+export interface ProgressInfo {
+    /** Progress in 5–90 (the system handles 0 and 100). */
+    percent: number;
+    /** Short customer-facing status message. */
+    message: string;
+}
+/** Information passed to {@link ChatOptions.onRetry} before each retry. */
+export interface ChatRetryInfo {
+    /** 1-indexed retry attempt; the original call is attempt 0. */
+    attempt: number;
+    /** Total retries that will be made before giving up. */
+    maxAttempts: number;
+    /** Milliseconds we're about to wait before this retry. */
+    delayMs: number;
+    /** Short human-readable reason — suitable for chat narration. */
+    reason: string;
+}
+/** Options for a single LLM call. */
+export interface ChatOptions {
+    systemPrompt: string;
+    turns: Turn[];
+    /**
+     * Per-user (BYOK) API key. When null/undefined the adapter falls
+     * back to the platform default (e.g. an env var).
+     */
+    apiKey?: string | null;
+    /** Defaults to `'reasoning'` — the conservative choice. */
+    modelClass?: ModelClass;
+    /**
+     * Optional per-call output-token ceiling override. Each adapter has an
+     * internal default appropriate to its own transport (the Anthropic
+     * adapter's is documented at its `MAX_TOKENS` constant, itself raised
+     * once already on direct evidence — a real diff that truncated four of
+     * five review lenses at the previous ceiling). `undefined` uses the
+     * adapter's own default, so an existing caller sees no change.
+     *
+     * Not every adapter has an equivalent lever: `@verevoir/llm/claude-cli`
+     * shells out to `claude -p`, which has no confirmed flag for an
+     * output-token ceiling (unlike `--model`, nothing in its own `--help`
+     * documents one) — that adapter accepts and silently ignores this
+     * field rather than throwing, so the shared `ChatOptions` shape stays
+     * uniform across adapters; its own file header discloses the gap
+     * rather than leaving a caller to discover it by the field quietly
+     * doing nothing.
+     */
+    maxTokens?: number;
+    /**
+     * Optional EXACT model id, bypassing `modelClass` resolution entirely.
+     *
+     * `modelClass` is deliberately class-based — a family-level semantic
+     * ("reasoning", "drafting", "extraction") that each adapter resolves to
+     * its own current id, so decisions key on provider/family and a
+     * version bump upgrades every caller in one place (see
+     * {@link ModelCatalogEntry}'s own doc comment). That is the right
+     * default for almost every caller, and stays the default here: setting
+     * only `modelClass` (or nothing) behaves exactly as before this field
+     * existed.
+     *
+     * `model` exists for the narrow, real exception: a caller for whom the
+     * SAME model answering across two different transports of the SAME
+     * provider is itself the thing being verified. Two substrates of one
+     * provider — a direct API call (`@verevoir/llm/anthropic`) and
+     * `claude -p` (`@verevoir/llm/claude-cli`) — can each resolve
+     * `modelClass` to a different concrete id: the API path takes whatever
+     * `models[modelClass]` currently is in its own catalog; the CLI path,
+     * having no model catalog of its own by design (see that adapter's own
+     * file header — it is deliberately never registered into the shared
+     * catalog), takes whatever the local `claude` install defaults to. A
+     * caller that judges the same commit twice, once through each
+     * transport, and treats disagreement between the two as a signal,
+     * needs BOTH calls to have used the identical model — not two models
+     * that merely share a class label. `model`, set identically on both
+     * calls, is that guarantee.
+     *
+     * When set, this WINS over `modelClass` for the id an adapter actually
+     * sends/reports — `modelClass` may still be read for other purposes
+     * (e.g. `TokenUsage.direction`, which stays a class semantic even when
+     * the id is pinned) but is never used to choose the id once `model` is
+     * present. Reaching for this as the DEFAULT way to select a model
+     * forfeits the catalog's forward-compatibility — a pinned id stays
+     * pinned until the caller updates it by hand, which is exactly what
+     * `modelClass` exists to avoid for everyone without this specific
+     * need.
+     */
+    model?: string;
+    /**
+     * Optional hook invoked before each retry. Best-effort; the adapter
+     * never lets a callback failure block the retry.
+     */
+    onRetry?: (info: ChatRetryInfo) => Promise<void>;
+    /** Optional hook invoked after a successful call with token usage. */
+    onUsage?: (usage: TokenUsage) => Promise<void>;
+    /**
+     * Optional hook invoked LIVE during the call when the model emits
+     * `report_progress`. When set, the adapter auto-injects the
+     * `report_progress` tool into the request.
+     */
+    onProgress?: (info: ProgressInfo) => Promise<void>;
+    /**
+     * Optional `AbortSignal` for cancelling the call. When the signal
+     * is aborted, the adapter throws the signal's `reason` (or a
+     * generic AbortError when none was provided). Checked between
+     * loop iterations in `chatWithToolLoop` — in-flight LLM calls
+     * complete and their tokens are still recorded, but no further
+     * iterations start once the signal is aborted.
+     *
+     * The canonical use case: an `onUsage` hook that aborts the
+     * controller when an aggregate budget is exceeded. The hook's own
+     * throws are still swallowed by the adapter for back-compat;
+     * abort is the supported escape hatch.
+     */
+    abortSignal?: AbortSignal;
+}
+/** Result of a single LLM call via {@link chat}. */
+export interface ChatReply {
+    /** The assembled text content of the reply. */
+    content: string;
+    /** Token usage for the call. */
+    usage: TokenUsage;
+    /** The provider's stop reason — `'end_turn'` for normal completion. */
+    stopReason: string;
+}
+/** Definition of a tool the model can choose to invoke. */
+export interface ToolDef {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description?: string;
+        }>;
+        required?: string[];
+    };
+}
+/** A single tool_use the model emitted in its reply. */
+export interface ToolUse {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/** Options for {@link chatWithTools}. */
+export interface ChatWithToolsOptions extends ChatOptions {
+    tools: ToolDef[];
+}
+/** Result of a single LLM call via {@link chatWithTools}. */
+export interface ChatWithToolsResult {
+    toolUses: ToolUse[];
+    text: string;
+    stopReason: string;
+    usage: TokenUsage;
+}
+/**
+ * Caller-supplied function that executes a single tool_use the model
+ * emitted, returning what the model will see as the matching
+ * `tool_result`. A plain `string` behaves exactly as before this type
+ * widened. Returning `ContentBlock[]` lets a tool hand back an
+ * `image` or `document` (e.g. a screenshot, a generated PDF) instead
+ * of text — `@verevoir/llm/anthropic` passes it through to the model
+ * unchanged; an adapter that cannot carry the block throws {@link
+ * UnsupportedContentBlockError} (via {@link collapseContentToText})
+ * naming the provider and the block type, rather than silently
+ * dropping it or stringifying it. Throw to indicate a tool FAILURE —
+ * the loop will surface it to the model with `is_error: true` so the
+ * model can react (apologise, try a different approach, etc.) rather
+ * than crashing the entire conversation.
+ */
+export type ToolExecutor = (toolUse: ToolUse) => Promise<string | ContentBlock[]>;
+/** Options for {@link chatWithToolLoop}. */
+export interface ChatWithToolLoopOptions extends ChatWithToolsOptions {
+    /** Runs each tool_use the model emits. Required. */
+    executor: ToolExecutor;
+    /**
+     * Cap on tool-call iterations. The loop exits after this many
+     * tool-using assistant turns regardless of whether the model would
+     * have continued. Default 5 — generous for typical conversations
+     * (each tool round costs a full LLM call + execution).
+     */
+    maxIterations?: number;
+    /**
+     * Optional hook fired after each iteration with a compact summary —
+     * useful for narrating progress into a chat surface ("Looking up
+     * issues...", "Reading file...").
+     */
+    onIteration?: (info: {
+        iteration: number;
+        toolUses: ToolUse[];
+        stopReason: string;
+    }) => Promise<void>;
+}
+/** Result of a multi-turn tool conversation. */
+export interface ChatWithToolLoopResult {
+    /** The model's final text response (after all tool iterations). */
+    text: string;
+    /** All tool_uses across every iteration of the loop, in order. */
+    toolUses: ToolUse[];
+    /** Per-tool-use, what the executor returned (or the error message as a
+     * plain string) — {@link ContentBlock}[] only ever appears here on
+     * `@verevoir/llm/anthropic`; every other adapter has already collapsed
+     * it to text via {@link collapseContentToText} by this point, or thrown
+     * {@link UnsupportedContentBlockError}. */
+    toolResults: {
+        toolUseId: string;
+        content: string | ContentBlock[];
+        isError: boolean;
+    }[];
+    /** How many model calls happened (1 = pure text, no tools used). */
+    iterations: number;
+    /** Aggregated usage across all iterations of the loop. */
+    usage: TokenUsage;
+}
+/**
+ * Per-model rollup keyed by concrete model id. Produced by
+ * {@link sumUsages}; consumed by display + cost helpers.
+ *
+ * `cacheRead` / `cacheWrite` are optional so older persisted rollups
+ * (which carried only `in` / `out`) still parse — every helper coalesces
+ * a missing cache field to 0. Keeping cache tokens *separate* from `in`
+ * is what lets {@link estimateCostUSD} price them at their real rates
+ * (a cache read is ~0.1× the input rate) instead of burying them in the
+ * standard input figure.
+ */
+export type PerModelUsage = Record<string, {
+    in: number;
+    out: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}>;
+/**
+ * Parse a JSON-serialised {@link PerModelUsage} produced by a previous
+ * call, returning an empty rollup on malformed/empty input.
+ */
+export declare function parseUsage(json: string): PerModelUsage;
+/**
+ * Sum multiple {@link PerModelUsage} rollups into one. Output entries
+ * always carry all four counters (a missing input field counts as 0).
+ */
+export declare function sumUsages(usages: PerModelUsage[]): PerModelUsage;
+/**
+ * Total tokens across all models in a rollup — input + output + cache
+ * read + cache write, all at face value. This is the right figure for a
+ * runaway-loop budget guard: a cache *read* costs less in dollars but is
+ * still a token the model had to process.
+ */
+export declare function totalTokens(usage: PerModelUsage): number;
+/**
+ * Compact token total — `123`, `12.3k`, `12k`, `1.2M`. Drops trailing
+ * `.0` so round numbers don't look gawky.
+ */
+export declare function formatTokensCompact(n: number): string;
+/**
+ * Per-model USD rates per million tokens:
+ * `[input, output, cacheRead?, cacheWrite?]`. The cache entries are
+ * optional; when an adapter omits them {@link estimateCostUSD} falls
+ * back to the Anthropic-standard multipliers (cache read 0.1×, cache
+ * write 1.25× of the input rate). Existing two-element tables stay
+ * valid.
+ *
+ * @deprecated Part of the old static-rates cost API. Use
+ * `createPriceBook(...)` / `book.costOf(...)` (see `src/pricing.ts`),
+ * which prices from LiteLLM's live table (the bundled snapshot as
+ * fallback) and reports an unmatched model as `unpriced` rather than
+ * `0`. Kept, unchanged, while the 5 provider adapters still call
+ * `estimateCostUSD`.
+ */
+export type RateTuple = readonly [number, number, number?, number?];
+/**
+ * Per-model rate table — `model id → RateTuple`.
+ * @deprecated Part of the old static-rates cost API — use
+ * `createPriceBook(...)` / `book.costOf(...)` instead.
+ */
+export type RatesTable = Readonly<Record<string, RateTuple>>;
+/**
+ * Estimate the USD cost of a per-model rollup against an adapter's rate
+ * table. Input + output price at the table's standard rates; cache reads
+ * and cache writes price at their own rates — either the explicit 3rd /
+ * 4th rate-tuple entries, or the Anthropic-standard fallbacks (read
+ * 0.1×, write 1.25× of input). Pricing cache tokens separately is what
+ * makes prompt-cache savings *visible* in the estimate, rather than
+ * hidden behind a worst-case full-input-rate treatment.
+ *
+ * Unknown models contribute 0 to the total — the caller can detect
+ * coverage gaps by checking that every model in the rollup is in the
+ * rates table.
+ *
+ * @deprecated Static per-adapter rate tables, silent on an unknown model
+ * (contributes `0`, never surfaced as missing). Use
+ * `createPriceBook(...)` / `book.costOf(...)` instead (see
+ * `src/pricing.ts`) — it prices from LiteLLM's live table (the bundled
+ * snapshot as fallback) and reports an unmatched model as `unpriced`.
+ * Kept, unchanged, for now: all 5 provider adapters still call this.
+ * Decision recorded in the PR body ("Decision: two cost APIs") and the
+ * 0.33.0 CHANGELOG entry.
+ */
+export declare function estimateCostUSD(usage: PerModelUsage, rates: RatesTable): number;
+/** Register friendly labels for the given model ids. Idempotent. */
+export declare function registerModelLabels(labels: Record<string, string>): void;
+/** Display label for a model id, falling back to the catalog's family label
+ * (so a new, unregistered version of a known family still labels sensibly)
+ * and finally to the bare id. */
+export declare function modelLabel(id: string): string;
+/**
+ * A version-free model identity — `{ provider, family }`, e.g.
+ * `{ anthropic, haiku }`. This is the **decision key**: routing, tier pools,
+ * and pricing branch on it, never on the exact versioned id. The concrete
+ * version (`claude-haiku-4-5-20251001`) is reporting metadata only.
+ */
+export interface ModelIdentity {
+    provider: string;
+    family: string;
+}
+/**
+ * A catalog entry — the single source of truth for one model family. An
+ * adapter registers its families once (via {@link registerModelCatalog}) and
+ * derives its `models` / `rates` / labels from the same entries, so a version
+ * bump is a one-line `currentId` change rather than edits rippling across
+ * three hand-maintained tables.
+ */
+export interface ModelCatalogEntry {
+    /** Provider id, e.g. `anthropic`. */
+    provider: string;
+    /** Decision-key family, e.g. `opus` | `sonnet` | `haiku`. */
+    family: string;
+    /** The concrete versioned id used for the actual API call + reporting. */
+    currentId: string;
+    /** Pricing at the family level (version-stable). */
+    rates: RateTuple;
+    /** Display label, e.g. `Haiku`. */
+    label: string;
+    /** Which model-class this family serves, if the adapter routes by class. */
+    modelClass?: ModelClass;
+    /** Older / alternate exact ids that also normalise to this family, so
+     * historical usage still prices and labels. */
+    aliases?: string[];
+    /** Id prefixes that resolve **forward** to this family — a new, unseen
+     * version of a known family (e.g. `claude-haiku-…`) still normalises
+     * rather than dropping to "unknown". */
+    prefixes?: string[];
+}
+/**
+ * Register model families into the catalog. Idempotent per `provider/family`
+ * (re-registering replaces). Also registers each entry's `currentId` and
+ * `aliases` as labels, so the existing {@link modelLabel} path keeps working
+ * without a separate {@link registerModelLabels} call.
+ */
+export declare function registerModelCatalog(entries: ModelCatalogEntry[]): void;
+/**
+ * Normalise a concrete model id to its `{ provider, family }`, or `null` when
+ * no registered family claims it (the **loud-on-miss** signal: callers should
+ * surface a null rather than silently mis-route). Match order: exact
+ * `currentId`, exact `alias`, then `prefix` — the prefix pass is what lets a
+ * brand-new version of a known family resolve forward instead of falling off.
+ */
+export declare function normalizeModelId(id: string): ModelIdentity | null;
+/**
+ * The catalog entry a concrete id normalises to, or `null`.
+ * @deprecated Part of the old static-rates cost API (used by
+ * `estimateCostUSD` / `uncoveredModels`). Use `createPriceBook(...)` /
+ * `book.costOf(...)` instead.
+ */
+export declare function catalogEntryFor(id: string): ModelCatalogEntry | null;
+/**
+ * The model ids in a usage rollup that price to nothing — neither in the
+ * supplied `rates` table nor resolvable via the catalog. This is the **loud**
+ * surface for "we billed something we can't price": a cost display should warn
+ * on a non-empty result rather than quietly showing an under-count. Distinct
+ * from {@link estimateCostUSD}, which stays silent (back-compat) and treats an
+ * uncovered model as $0.
+ *
+ * @deprecated Part of the old static-rates cost API. `createPriceBook(...)`
+ * / `book.costOf(...)` makes this unnecessary: an unmatched model there is
+ * always `unpriced`, so there's no silent-zero case left to surface.
+ */
+export declare function uncoveredModels(usage: PerModelUsage, rates?: RatesTable): string[];
+/**
+ * Resolve a client base URL: the `<PROVIDER>_BASE_URL` env override when set
+ * (and non-empty), else the provider's `fallback` (or `undefined` to use the
+ * SDK default). Lets any provider be pointed at a gateway, proxy, regional, or
+ * self-hosted endpoint without a code change — keyed by provider/endpoint, the
+ * same convention as `<PROVIDER>_API_KEY`.
+ */
+export declare function resolveBaseUrl(envVar?: string, fallback?: string): string | undefined;
+/**
+ * A placeholder API key for a keyless LOCAL endpoint. When a provider's base-URL
+ * override is set but its API key is blank, the endpoint is presumed local — LM
+ * Studio / Ollama / vLLM expose OpenAI-compatible servers that need no key, yet
+ * the SDK still wants a non-empty string. Returns `undefined` when no base-URL
+ * override is set, so a missing key against the *canonical* endpoint still errors
+ * loudly rather than silently building an unauthenticated client.
+ */
+export declare function localEndpointKey(baseUrlEnv?: string): string | undefined;
+/** How to connect to a provider: the envs that hold its credential + endpoint. */
+export interface ProviderConnection {
+    provider: string;
+    /** Env var holding the API key (e.g. `SAMBA_NOVA_API_KEY`). */
+    apiKeyEnv: string;
+    /**
+     * Additional env vars whose presence ALSO makes this provider usable — a
+     * credential that is not the API key but authenticates just as well. Anthropic
+     * declares `CLAUDE_CODE_OAUTH_TOKEN` here: the adapter prefers that token over
+     * the metered key, so a caller holding only the subscription token has a
+     * perfectly usable provider. Without this, {@link isProviderConfigured} would
+     * look only at `apiKeyEnv`, report the provider unconfigured, and routing would
+     * refuse to pick it — even though every call would have succeeded. The credential
+     * CHECK must recognise every credential the CALL path accepts, or the two
+     * disagree and the caller is told to set a key it does not need.
+     */
+    altKeyEnvs?: readonly string[];
+    /** Env var that overrides the base URL (e.g. `SAMBA_NOVA_BASE_URL`), if any. */
+    baseUrlEnv?: string;
+    /**
+     * The provider's default OpenAI-compatible base URL, for a raw caller (a
+     * delegate worker) that drives the endpoint directly rather than via the SDK.
+     * Set for the OpenAI-compatible providers (OpenAI, DeepSeek, SambaNova,
+     * Mistral); omitted for SDK-only providers (Anthropic, Gemini) — which a raw
+     * OpenAI-compatible caller cannot drive, so they resolve to no connection.
+     */
+    defaultBaseUrl?: string;
+    /**
+     * Whether a base-URL override **without a key** makes this provider usable —
+     * true only for the generic OpenAI-compatible client pointed at a keyless
+     * LOCAL server (LM Studio / Ollama / vLLM). Hosted providers (Anthropic,
+     * Gemini, SambaNova, Mistral, DeepSeek) always need a key, so a base-URL
+     * override alone (a regional/proxy endpoint) does NOT make them usable.
+     * Default false.
+     */
+    keylessCapable?: boolean;
+}
+/** Register how to connect to a provider. Idempotent per provider. */
+export declare function registerProviderConnection(c: ProviderConnection): void;
+/** The registered connection for a provider, or `undefined`. */
+export declare function providerConnection(provider: string): ProviderConnection | undefined;
+/**
+ * Whether a provider is usable right now: its API key is set, one of its
+ * alternative credentials ({@link ProviderConnection.altKeyEnvs} — e.g.
+ * Anthropic's `CLAUDE_CODE_OAUTH_TOKEN`) is set, or a base-URL override points it
+ * at a keyless local endpoint. Routing must never pick an endpoint with no
+ * credential — but it must equally never refuse one that HAS a credential the
+ * call path accepts, which is why the alt keys are consulted here.
+ */
+export declare function isProviderConfigured(provider: string): boolean;
+/** The providers that are configured right now (have a usable connection). */
+export declare function configuredProviders(): string[];
+/** Every catalog entry serving a family, across providers — the inverse of the
+ * per-provider catalog. Empty when no registered provider serves it. */
+export declare function providersForFamily(family: string): ModelCatalogEntry[];
+/** How to pick when several providers serve the same model. */
+export interface ResolveModelOptions {
+    /** Restrict to one family (e.g. `deepseek-v3`). */
+    family?: string;
+    /** Restrict to one class (reasoning / drafting / extraction). */
+    modelClass?: ModelClass;
+    /** Only consider providers configured right now. Default true. */
+    configuredOnly?: boolean;
+    /** Provider priority — earlier wins; overrides cheapest. */
+    prefer?: string[];
+}
+/**
+ * Resolve a desired model — by family and/or class — to a concrete catalog
+ * entry, across all providers. This is what lets "I want DeepSeek-V3" pick
+ * deepseek.com *or* SambaNova by policy, rather than the caller knowing which
+ * providers serve it. Policy: a `prefer` provider order if given, else cheapest
+ * by input rate; configured providers only unless told otherwise. Returns
+ * `null` when nothing matches (loud-on-miss, like {@link normalizeModelId}).
+ */
+export declare function resolveModel(opts?: ResolveModelOptions): ModelCatalogEntry | null;
+/**
+ * Resolve a loose human term ("deepseek") OR an exact family/id to a catalog
+ * entry, across providers — so config can name a model by family, not a pinned
+ * version. Matches the term (case-insensitive) against family, currentId, label,
+ * and prefixes; exact family/id wins over a substring, then `prefer` order, then
+ * cheapest, then newest id. Configured providers only unless told otherwise.
+ * Null on no match (loud-on-miss, like {@link normalizeModelId}).
+ *
+ * IT REFUSES A VERSION IT CANNOT SERVE, rather than resolving to a neighbour.
+ * This is SELECTION — every caller takes `entry.currentId` and calls it — and
+ * selection and normalisation want opposite rules from the same `prefixes`
+ * field. Normalising is backward-looking: an id that was *already used* must
+ * still price and label, so `claude-opus-9-1` arriving in a usage report should
+ * fall to the opus family rather than "unknown", and {@link modelLabel} matches
+ * forward for exactly that reason. Selecting is forward-looking: `claude-opus-6`
+ * asked *for* is a request the catalog cannot fill, and answering it with
+ * `claude-opus-5` runs a different model with no symptom at all — not a
+ * warning, not a slower answer, just a different mind doing the work while
+ * every log says otherwise.
+ *
+ * So a term carrying a version the catalog does not hold is null — including a
+ * PARTIAL one: `claude-opus-4` is refused while `claude-opus-4-8` resolves (as a
+ * superseded alias), because 4 is not 4-8 and answering it with 4-8 is the same
+ * substitution one digit smaller. A term naming no version is unaffected:
+ * "opus", "claude" and
+ * the bare prefix `claude-opus-` all ask for a class and get the current member
+ * of it, which is the naming to prefer and the only one that stays true across
+ * a release.
+ */
+export declare function resolveModelByTerm(term: string, opts?: Omit<ResolveModelOptions, 'family'>): ModelCatalogEntry | null;
+/** A usable OpenAI-compatible connection for a resolved model — everything a
+ * raw caller (a delegate worker, a per-tier model slot) needs to make the call,
+ * without importing the provider's SDK. */
+export interface ModelConnection {
+    provider: string;
+    /** The concrete current model id (e.g. `DeepSeek-V3.2`). */
+    modelId: string;
+    /** The OpenAI-compatible base URL (env override, else the provider default). */
+    baseUrl: string;
+    /** The API key from env, a local placeholder, or null. */
+    apiKey: string | null;
+}
+/**
+ * Resolve a term ("deepseek", or an exact id) to a usable OpenAI-compatible
+ * connection: provider + concrete model id + endpoint + key, read from the
+ * registered connection + env. This is what lets a config name a model by
+ * family and have it bind to a real endpoint at resolve time. Null when nothing
+ * matches, the provider isn't configured, or it has no OpenAI-compatible
+ * endpoint (Anthropic / Gemini are SDK-only and can't be driven raw).
+ */
+export declare function modelConnection(term: string, opts?: Omit<ResolveModelOptions, 'family'>): ModelConnection | null;
+//# sourceMappingURL=index.d.ts.map