llm-cli-gateway 2.16.0 → 2.17.0

package/dist/lcr-telemetry.d.ts

@@ -0,0 +1,2 @@
+export type TelemetryTier = "T1" | "T2" | "T3" | "T4";
+export declare function telemetryTierFor(provider: string): TelemetryTier;

package/dist/lcr-telemetry.js

@@ -0,0 +1,17 @@
+import { CLI_TYPES } from "./provider-types.js";
+const CLI_TELEMETRY_TIERS = {
+    claude: "T1",
+    codex: "T2",
+    gemini: "T2",
+    grok: "T3",
+    mistral: "T1",
+    devin: "T4",
+    cursor: "T4",
+};
+const DEFAULT_TELEMETRY_TIER = "T2";
+export function telemetryTierFor(provider) {
+    if (CLI_TYPES.includes(provider)) {
+        return CLI_TELEMETRY_TIERS[provider];
+    }
+    return DEFAULT_TELEMETRY_TIER;
+}

package/dist/least-cost-router.d.ts

@@ -0,0 +1,86 @@
+import type { ModelCost, CostBasis, Confidence, QualityTier, PriceSource } from "./least-cost-types.js";
+export interface Candidate {
+    provider: string;
+    model: string;
+}
+export interface CandidateCapabilities {
+    acceptsImages: boolean;
+    acceptsAttachments: boolean;
+    toolCalling: boolean;
+    jsonSchema: boolean;
+    outputFormats: readonly string[];
+    capabilityScope: string;
+    effortLevels: readonly string[];
+}
+export interface RouterEnv {
+    providers(): readonly string[];
+    models(provider: string): readonly string[];
+    isAuthed(provider: string): boolean;
+    breakerState(provider: string): string;
+    atCapacity(provider: string): boolean;
+    capabilities(provider: string): CandidateCapabilities;
+    modelCost(provider: string, model: string): ModelCost;
+    successRate(provider: string, model: string): number;
+    meanLatencyMs(provider: string, model: string): number;
+    calibrationK(prompt: string, family: string): number;
+    outputPrior(provider: string, model: string): {
+        median: number;
+        p90: number;
+    } | null;
+    confidenceBand(prompt: string, family: string): Confidence;
+}
+export interface RequiredCapabilities {
+    images?: boolean;
+    attachments?: boolean;
+    toolCalling?: boolean;
+    jsonSchema?: boolean;
+    outputFormat?: string;
+    effort?: string;
+}
+export interface RouteRequestInput {
+    prompt: string;
+    candidates?: Candidate[];
+    minTier?: QualityTier;
+    maxCostUsd?: number;
+    expectedOutputTokens?: number;
+    maxOutputTokens?: number;
+    requiredCapabilities?: RequiredCapabilities;
+    allowUnpriced?: boolean;
+    budgetWaiver?: boolean;
+    fallback?: Candidate;
+}
+export interface RouterConfig {
+    minTier: QualityTier;
+    maxCostUsd: number;
+    defaultExpectedOutputTokens: number;
+    budgetOutputSafetyFactor: number;
+    allowUnpriced: boolean;
+    tiers: Record<string, QualityTier>;
+    candidates: {
+        allow: string[];
+        deny: string[];
+    };
+    preferenceOrder?: string[];
+}
+export interface RejectedCandidate {
+    candidate: Candidate;
+    reason: string;
+}
+export interface RouteDecision {
+    chosen: Candidate | null;
+    tier?: QualityTier;
+    estCostUsd?: number;
+    costBasis?: CostBasis;
+    confidence?: Confidence;
+    nearTie?: boolean;
+    estInputTokens?: number;
+    estOutputTokens?: number;
+    priceAsOf?: string;
+    priceSource?: PriceSource;
+    consideredCount: number;
+    rejected: RejectedCandidate[];
+    reroutes: number;
+    error?: "NoEligibleCandidate" | "BudgetExceeded";
+}
+export declare function selectCandidate(req: RouteRequestInput, env: RouterEnv, config: RouterConfig, excluded?: ReadonlySet<string>): RouteDecision;
+export declare function selectCheapestPerTier(req: RouteRequestInput, env: RouterEnv, config: RouterConfig, excluded?: ReadonlySet<string>): RouteDecision[];

package/dist/least-cost-router.js

@@ -0,0 +1,296 @@
+import { modelIdToFamily, composeCost } from "./pricing.js";
+import { estimateInputTokens } from "./token-estimator.js";
+const TIER_ORDER = {
+    economy: 0,
+    standard: 1,
+    frontier: 2,
+};
+function candidateKey(c) {
+    return `${c.provider}:${c.model}`;
+}
+function isExplicitlyListed(c, explicit) {
+    if (!explicit)
+        return false;
+    return explicit.some(e => e.provider === c.provider && e.model === c.model);
+}
+function passesAllowDeny(c, config) {
+    const providerKey = c.provider;
+    const pairKey = candidateKey(c);
+    const matches = (entry) => entry === providerKey || entry === pairKey;
+    if (config.candidates.deny.some(matches))
+        return false;
+    if (config.candidates.allow.length === 0)
+        return true;
+    return config.candidates.allow.some(matches);
+}
+function buildPool(req, env, config) {
+    const source = req.candidates && req.candidates.length > 0
+        ? req.candidates
+        : env
+            .providers()
+            .flatMap(provider => env.models(provider).map(model => ({ provider, model })));
+    return source.filter(c => passesAllowDeny(c, config));
+}
+function checkCapabilities(caps, required) {
+    if (!required)
+        return { ok: true };
+    if (required.images === true && !caps.acceptsImages) {
+        return { ok: false, reason: "capability:images" };
+    }
+    if (required.attachments === true && !caps.acceptsAttachments) {
+        return { ok: false, reason: "capability:attachments" };
+    }
+    if (required.toolCalling === true && !caps.toolCalling) {
+        return { ok: false, reason: "capability:toolCalling" };
+    }
+    if (required.jsonSchema === true && !caps.jsonSchema) {
+        return { ok: false, reason: "capability:jsonSchema" };
+    }
+    if (required.outputFormat !== undefined && !caps.outputFormats.includes(required.outputFormat)) {
+        return { ok: false, reason: "capability:outputFormat" };
+    }
+    if (required.effort !== undefined && !caps.effortLevels.includes(required.effort)) {
+        return { ok: false, reason: "capability:effort" };
+    }
+    return { ok: true };
+}
+function checkTier(candidate, req, config) {
+    const family = modelIdToFamily(candidate.model);
+    const tierKey = `${candidate.provider}:${family}`;
+    const tier = config.tiers[tierKey];
+    if (tier === undefined) {
+        if (isExplicitlyListed(candidate, req.candidates)) {
+            return { ok: true, tier: undefined };
+        }
+        return { ok: false, reason: "untiered" };
+    }
+    const effectiveMinTier = req.minTier ?? config.minTier;
+    if (TIER_ORDER[tier] < TIER_ORDER[effectiveMinTier]) {
+        return { ok: false, reason: "below-min-tier" };
+    }
+    return { ok: true, tier };
+}
+function evaluateBaseEligibility(candidate, req, env) {
+    if (!env.isAuthed(candidate.provider)) {
+        return { ok: false, reason: "auth" };
+    }
+    if (env.breakerState(candidate.provider) !== "CLOSED") {
+        return { ok: false, reason: "breaker" };
+    }
+    if (env.atCapacity(candidate.provider)) {
+        return { ok: false, reason: "capacity" };
+    }
+    const caps = env.capabilities(candidate.provider);
+    const capResult = checkCapabilities(caps, req.requiredCapabilities);
+    if (!capResult.ok) {
+        return { ok: false, reason: capResult.reason };
+    }
+    if (caps.capabilityScope === "maintain-only" && !isExplicitlyListed(candidate, req.candidates)) {
+        return { ok: false, reason: "maintain-only" };
+    }
+    return { ok: true };
+}
+const CONFIDENCE_ORDER = { low: 0, medium: 1, high: 2 };
+function minConfidence(a, b) {
+    return CONFIDENCE_ORDER[a] <= CONFIDENCE_ORDER[b] ? a : b;
+}
+function rankCandidate(candidate, tier, modelCost, req, config, env) {
+    const family = modelCost.family !== "unknown" ? modelCost.family : modelIdToFamily(candidate.model);
+    const calibrationK = env.calibrationK(req.prompt, family);
+    const estInputTokens = estimateInputTokens(req.prompt, { family, calibrationK });
+    const prior = env.outputPrior(candidate.provider, candidate.model);
+    const estOutputTokens = req.expectedOutputTokens ??
+        (prior ? Math.max(1, Math.round(prior.median)) : config.defaultExpectedOutputTokens);
+    const budgetOutputTokens = req.maxOutputTokens ??
+        (prior
+            ? Math.max(1, Math.round(prior.p90))
+            : config.defaultExpectedOutputTokens * config.budgetOutputSafetyFactor);
+    const rankResult = composeCost(null, { estInputTokens, estOutputTokens }, modelCost);
+    const band = env.confidenceBand(req.prompt, family);
+    return {
+        candidate,
+        tier,
+        modelCost,
+        estInputTokens,
+        estOutputTokens,
+        rankCostUsd: rankResult.costUsd,
+        rankKey: modelCost.source === "unknown" ? Number.POSITIVE_INFINITY : rankResult.costUsd,
+        costBasis: rankResult.cost_basis,
+        confidence: minConfidence(rankResult.confidence, band),
+        budgetOutputTokens,
+    };
+}
+function preferenceIndex(provider, preferenceOrder) {
+    if (!preferenceOrder)
+        return Number.MAX_SAFE_INTEGER;
+    const idx = preferenceOrder.indexOf(provider);
+    return idx === -1 ? Number.MAX_SAFE_INTEGER : idx;
+}
+function compareCandidates(a, b, env, config) {
+    if (a.rankKey !== b.rankKey)
+        return a.rankKey - b.rankKey;
+    const successA = env.successRate(a.candidate.provider, a.candidate.model);
+    const successB = env.successRate(b.candidate.provider, b.candidate.model);
+    if (successA !== successB)
+        return successB - successA;
+    const latencyA = env.meanLatencyMs(a.candidate.provider, a.candidate.model);
+    const latencyB = env.meanLatencyMs(b.candidate.provider, b.candidate.model);
+    if (latencyA !== latencyB)
+        return latencyA - latencyB;
+    const prefA = preferenceIndex(a.candidate.provider, config.preferenceOrder);
+    const prefB = preferenceIndex(b.candidate.provider, config.preferenceOrder);
+    if (prefA !== prefB)
+        return prefA - prefB;
+    const lexA = `${a.candidate.provider}/${a.candidate.model}`;
+    const lexB = `${b.candidate.provider}/${b.candidate.model}`;
+    return lexA.localeCompare(lexB);
+}
+function checkBudget(ranked, req, config, isFallback) {
+    const { modelCost, estInputTokens } = ranked;
+    const allowUnpriced = req.allowUnpriced ?? config.allowUnpriced;
+    const budgetWaiver = req.budgetWaiver ?? false;
+    if (modelCost.source === "unknown") {
+        if (allowUnpriced && budgetWaiver)
+            return { ok: true };
+        return { ok: false, reason: "budget" };
+    }
+    const budgetResult = composeCost(null, { estInputTokens, estOutputTokens: ranked.budgetOutputTokens }, modelCost);
+    const budgetCost = budgetResult.costUsd;
+    const effectiveMax = req.maxCostUsd ?? config.maxCostUsd;
+    if (budgetCost > effectiveMax) {
+        if (isFallback && budgetWaiver)
+            return { ok: true };
+        return { ok: false, reason: "budget" };
+    }
+    return { ok: true };
+}
+function toDecisionFromRanked(ranked, consideredCount, rejected, nearTie) {
+    return {
+        chosen: ranked.candidate,
+        tier: ranked.tier,
+        estCostUsd: ranked.rankCostUsd,
+        costBasis: ranked.costBasis,
+        confidence: ranked.confidence,
+        nearTie,
+        estInputTokens: ranked.estInputTokens,
+        estOutputTokens: ranked.estOutputTokens,
+        priceAsOf: ranked.modelCost.asOf,
+        priceSource: ranked.modelCost.source,
+        consideredCount,
+        rejected,
+        reroutes: 0,
+    };
+}
+function buildRankedPool(req, env, config, excluded) {
+    const pool = buildPool(req, env, config).filter(c => !excluded?.has(candidateKey(c)));
+    const rejected = [];
+    const eligible = [];
+    for (const candidate of pool) {
+        const baseEligibility = evaluateBaseEligibility(candidate, req, env);
+        if (!baseEligibility.ok) {
+            rejected.push({ candidate, reason: baseEligibility.reason });
+            continue;
+        }
+        const tierResult = checkTier(candidate, req, config);
+        if (!tierResult.ok) {
+            rejected.push({ candidate, reason: tierResult.reason });
+            continue;
+        }
+        const modelCost = env.modelCost(candidate.provider, candidate.model);
+        const allowUnpriced = req.allowUnpriced ?? config.allowUnpriced;
+        if (modelCost.source === "unknown" && !allowUnpriced) {
+            rejected.push({ candidate, reason: "unpriced" });
+            continue;
+        }
+        eligible.push({ candidate, tier: tierResult.tier, modelCost });
+    }
+    const ranked = eligible.map(e => rankCandidate(e.candidate, e.tier, e.modelCost, req, config, env));
+    ranked.sort((a, b) => compareCandidates(a, b, env, config));
+    return { ranked, rejected };
+}
+export function selectCandidate(req, env, config, excluded) {
+    const { ranked, rejected } = buildRankedPool(req, env, config, excluded);
+    if (ranked.length === 0) {
+        if (req.fallback) {
+            const fallbackReq = {
+                ...req,
+                candidates: [...(req.candidates ?? []), req.fallback],
+            };
+            const fbBase = evaluateBaseEligibility(req.fallback, fallbackReq, env);
+            if (!fbBase.ok) {
+                return {
+                    chosen: null,
+                    consideredCount: 0,
+                    rejected: [...rejected, { candidate: req.fallback, reason: fbBase.reason }],
+                    reroutes: 0,
+                    error: "NoEligibleCandidate",
+                };
+            }
+            const fbTier = checkTier(req.fallback, fallbackReq, config);
+            if (!fbTier.ok) {
+                return {
+                    chosen: null,
+                    consideredCount: 0,
+                    rejected: [...rejected, { candidate: req.fallback, reason: fbTier.reason }],
+                    reroutes: 0,
+                    error: "NoEligibleCandidate",
+                };
+            }
+            const fallbackModelCost = env.modelCost(req.fallback.provider, req.fallback.model);
+            const fallbackRanked = rankCandidate(req.fallback, fbTier.tier, fallbackModelCost, req, config, env);
+            const budget = checkBudget(fallbackRanked, req, config, true);
+            if (!budget.ok) {
+                return {
+                    chosen: null,
+                    consideredCount: 0,
+                    rejected: [...rejected, { candidate: req.fallback, reason: budget.reason }],
+                    reroutes: 0,
+                    error: "BudgetExceeded",
+                };
+            }
+            return toDecisionFromRanked(fallbackRanked, 0, rejected, false);
+        }
+        return {
+            chosen: null,
+            consideredCount: 0,
+            rejected,
+            reroutes: 0,
+            error: "NoEligibleCandidate",
+        };
+    }
+    const best = ranked[0];
+    const secondBest = ranked.length > 1 ? ranked[1] : undefined;
+    const nearTie = secondBest !== undefined &&
+        Number.isFinite(best.rankKey) &&
+        best.rankKey > 0 &&
+        Math.abs(secondBest.rankKey - best.rankKey) / best.rankKey <= 0.01;
+    const budget = checkBudget(best, req, config, false);
+    if (!budget.ok) {
+        return {
+            chosen: null,
+            consideredCount: ranked.length,
+            rejected: [...rejected, { candidate: best.candidate, reason: budget.reason }],
+            reroutes: 0,
+            error: "BudgetExceeded",
+        };
+    }
+    return toDecisionFromRanked(best, ranked.length, rejected, nearTie);
+}
+export function selectCheapestPerTier(req, env, config, excluded) {
+    const { ranked, rejected } = buildRankedPool(req, env, config, excluded);
+    const decidedTiers = new Set();
+    const decisions = [];
+    for (const candidate of ranked) {
+        const tier = candidate.tier;
+        if (tier === undefined)
+            continue;
+        if (decidedTiers.has(tier))
+            continue;
+        decidedTiers.add(tier);
+        const budget = checkBudget(candidate, req, config, false);
+        if (!budget.ok)
+            continue;
+        decisions.push(toDecisionFromRanked(candidate, ranked.length, rejected, false));
+    }
+    return decisions.sort((a, b) => TIER_ORDER[a.tier] - TIER_ORDER[b.tier]);
+}

package/dist/least-cost-types.d.ts

@@ -0,0 +1,34 @@
+export type AccountingMode = "inclusive" | "disjoint";
+export type CostBasis = "provider-reported" | "derived-from-tokens" | "pre-flight-estimate";
+export type Confidence = "high" | "medium" | "low";
+export type QualityTier = "economy" | "standard" | "frontier";
+export type PriceSource = "table" | "api-catalog" | "unknown";
+export interface ModelCost {
+    inputUsdPerMTok: number;
+    outputUsdPerMTok: number;
+    cacheReadMultiplier: number;
+    cacheWriteUsdPerMTok: number;
+    accountingMode: AccountingMode;
+    family: string;
+    source: PriceSource;
+    asOf: string;
+}
+export interface TokenCounts {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    reasoningTokens?: number;
+    reportedCostUsd?: number;
+}
+export interface TokenEstimate {
+    estInputTokens: number;
+    estOutputTokens: number;
+    estCacheReadTokens?: number;
+    estCacheWriteTokens?: number;
+}
+export interface CostResult {
+    costUsd: number;
+    cost_basis: CostBasis;
+    confidence: Confidence;
+}

package/dist/least-cost-types.js

@@ -0,0 +1 @@
+export {};

package/dist/migrate-sessions.js

@@ -22,7 +22,7 @@ export async function migrateFromFile(filePath, pgManager) {
         fileData = JSON.parse(fileContent);
     }
     catch (error) {
-        throw new Error(`Failed to read sessions file: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Failed to read sessions file: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
     console.error(`Found ${Object.keys(fileData.sessions).length} sessions to migrate`);
     for (const [id, session] of Object.entries(fileData.sessions)) {

package/dist/migrate.js

@@ -86,7 +86,7 @@ async function importOptionalPg() {
     }
     catch (error) {
         if (error?.code === "ERR_MODULE_NOT_FOUND" || error?.code === "MODULE_NOT_FOUND") {
-            throw new Error("PostgreSQL migrations require optional peer dependency 'pg'. Install it alongside llm-cli-gateway before running migrate.");
+            throw new Error("PostgreSQL migrations require optional peer dependency 'pg'. Install it alongside llm-cli-gateway before running migrate.", { cause: error });
         }
         throw error;
     }

package/dist/model-registry.js

@@ -192,7 +192,7 @@ function addWarning(info, warning) {
     }
 }
 function isValidModelName(model) {
-    return model.length > 0 && !/[\u0000-\u001f\u007f]/.test(model) && !/\s/.test(model);
+    return model.length > 0 && !/[\s\p{Cc}]/u.test(model);
 }
 function addModel(info, model, description, metadata, options = {}) {
     const normalized = model.trim();

package/dist/postgres-job-store-worker.js

@@ -1,7 +1,21 @@
-import { writeFileSync } from "node:fs";
 import { parentPort, workerData } from "node:worker_threads";
 let pool = null;
 const PG_NOW_MS = "(EXTRACT(EPOCH FROM now()) * 1000)::bigint";
+const PG_BOOTSTRAP_LOCK_KEY = 13_920_260_713;
+const PG_POOL_MAX = 1;
+const PG_STATEMENT_TIMEOUT_MS = 25_000;
+const PG_LOCK_TIMEOUT_MS = 5_000;
+const PG_QUERY_TIMEOUT_MS = 27_000;
+function reportDiagnostic(kind, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    parentPort?.postMessage({
+        type: "postgres-job-store-diagnostic",
+        kind,
+        message,
+        stack,
+    });
+}
 function signal(shared, status) {
     const view = new Int32Array(shared);
     Atomics.store(view, 0, status);
@@ -48,9 +62,22 @@ async function init() {
     pool = new pg.Pool({
         connectionString: workerData.dsn,
         connectionTimeoutMillis: workerData.connectionTimeoutMillis,
+        max: PG_POOL_MAX,
+        idleTimeoutMillis: 30_000,
+        statement_timeout: PG_STATEMENT_TIMEOUT_MS,
+        lock_timeout: PG_LOCK_TIMEOUT_MS,
+        query_timeout: PG_QUERY_TIMEOUT_MS,
+        application_name: "llm-cli-gateway-job-store",
     });
+    getPool().on("error", error => reportDiagnostic("pool_error", error));
     await getPool().query("SELECT 1");
-    await getPool().query(`
+    await withClient(async (client) => {
+        await client.query("BEGIN");
+        try {
+            await client.query("SET LOCAL lock_timeout = 0");
+            await client.query("SELECT pg_advisory_xact_lock($1::bigint)", [PG_BOOTSTRAP_LOCK_KEY]);
+            await client.query(`SET LOCAL lock_timeout = '${PG_LOCK_TIMEOUT_MS}ms'`);
+            await client.query(`
     CREATE TABLE IF NOT EXISTS jobs (
       id TEXT PRIMARY KEY,
       correlation_id TEXT NOT NULL,
@@ -125,14 +152,26 @@ async function init() {
       confidence TEXT NOT NULL
     );
     CREATE INDEX IF NOT EXISTS idx_validation_receipts_owner ON validation_receipts(owner_principal);
-  `);
-    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS owner_principal TEXT");
-    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS transport TEXT NOT NULL DEFAULT 'process'");
-    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS http_status INTEGER");
-    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS payload_json TEXT");
-    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS owner_instance TEXT");
-    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS lease_deadline BIGINT");
-    await getPool().query("CREATE INDEX IF NOT EXISTS idx_jobs_owner_status ON jobs(owner_instance, status)");
+      `);
+            await client.query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS owner_principal TEXT");
+            await client.query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS transport TEXT NOT NULL DEFAULT 'process'");
+            await client.query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS http_status INTEGER");
+            await client.query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS payload_json TEXT");
+            await client.query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS owner_instance TEXT");
+            await client.query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS lease_deadline BIGINT");
+            await client.query("CREATE INDEX IF NOT EXISTS idx_jobs_owner_status ON jobs(owner_instance, status)");
+            await client.query("COMMIT");
+        }
+        catch (error) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch (rollbackError) {
+                reportDiagnostic("bootstrap_rollback_error", rollbackError);
+            }
+            throw error;
+        }
+    });
 }
 async function op(method, args) {
     switch (method) {
@@ -426,7 +465,7 @@ async function op(method, args) {
     }
 }
 parentPort?.on("message", async (message) => {
-    const { method, args, resultPath, shared } = message;
+    const { method, args, shared, responsePort } = message;
     let payload;
     try {
         payload = ok(await op(method, args));
@@ -435,10 +474,14 @@ parentPort?.on("message", async (message) => {
         payload = fail(error);
     }
     try {
-        writeFileSync(resultPath, JSON.stringify(payload));
+        responsePort.postMessage(payload);
         signal(shared, 1);
     }
-    catch {
+    catch (error) {
+        reportDiagnostic("response_transport_error", error);
         signal(shared, 2);
     }
+    finally {
+        responsePort.close();
+    }
 });

package/dist/pricing.d.ts

@@ -1,4 +1,5 @@
 import type { CliType } from "./provider-types.js";
+import type { ModelCost, TokenCounts, TokenEstimate, CostResult, AccountingMode } from "./least-cost-types.js";
 export interface PricePerMillion {
     inputUsd: number;
     outputUsd: number;
@@ -7,3 +8,19 @@ export interface PricePerMillion {
 export declare const PRICING_AS_OF = "2026-06-13";
 export declare function getPricing(cli: CliType, model: string): PricePerMillion;
 export declare function estimateCacheSavingsUsd(cli: CliType, model: string, cacheReadTokens: number): number;
+export declare function modelIdToFamily(model: string): string;
+export declare const API_CATALOG_AS_OF = "2026-07-11";
+export interface ApiCatalogEntry {
+    inputUsdPerMTok: number;
+    outputUsdPerMTok: number;
+    cacheReadMultiplier: number;
+    accountingMode?: AccountingMode;
+    family?: string;
+}
+export type ApiCatalog = ReadonlyMap<string, ApiCatalogEntry>;
+export declare const API_CATALOG: ApiCatalog;
+export declare function getModelCost(provider: string, model: string, opts?: {
+    catalog?: ApiCatalog;
+    preferCatalog?: boolean;
+}): ModelCost;
+export declare function composeCost(counts: TokenCounts | null, estimate: TokenEstimate, modelCost: ModelCost): CostResult;