auto-model-router 0.2.31 → 0.3.0

package/src/catalog/ollama-catalog.ts

@@ -0,0 +1,309 @@
+/**
+ * Ollama Cloud catalog: turns Ollama's model listing into `CatalogModel`s the
+ * router can rank next to OpenRouter's.
+ *
+ * Ollama publishes far less per model than OpenRouter does, so each model is
+ * assembled from three sources:
+ *
+ *  1. The listing itself (`GET /api/tags`, on the daemon or on ollama.com):
+ *     ids, and on the daemon the context length + capabilities of every cloud
+ *     model. ollama.com's listing carries neither, so there `POST /api/show`
+ *     (unauthenticated) fills them, cached per id for the life of the process.
+ *  2. The price table (`ollama-prices.ts` + `ollama.prices` config), since no
+ *     Ollama endpoint publishes rates. Unpriced models are dropped.
+ *  3. The OpenRouter twin — the same model under an OpenRouter slug, matched by
+ *     normalised name (`glm-5.3-flash` ↔ `z-ai/glm-5.3-flash`) — for the
+ *     quality scores that put the model above `trivial`, and as a fallback for
+ *     tokenizer, context and capabilities. `ollama.twins` in config pins a
+ *     match the normaliser cannot make.
+ *
+ * Slugs are `ollama/<id as listed>`, so the daemon's `glm-5.3-flash:cloud` and
+ * ollama.com's `glm-5.3-flash` are distinct catalog entries with the same
+ * price and twin; the dispatch client strips the `ollama/` prefix.
+ */
+
+import type { OllamaConfig } from "../config/types.ts";
+import type { Logger } from "../util/log.ts";
+import { normalizeModelKey } from "./benchmark-feeds.ts";
+import { bareCloudName, ollamaRateFor, type OllamaRate } from "./ollama-prices.ts";
+import type { CatalogModel, CatalogSnapshot, Modality } from "./types.ts";
+
+export const OLLAMA_SLUG_PREFIX = "ollama/";
+
+/** One entry of Ollama's `/api/tags` listing, reduced to what routing needs. */
+export interface OllamaListing {
+	id: string;
+	/** Bare cloud name on ollama.com (`remote_model` on the daemon). */
+	remoteModel: string | null;
+	/** Present when the daemon proxies this model to ollama.com. */
+	isCloud: boolean;
+	contextLength: number | null;
+	capabilities: string[];
+	modifiedAtMs: number;
+}
+
+function asRec(v: unknown): Record<string, unknown> | null {
+	return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+/** Parses one raw `/api/tags` model record. */
+export function parseOllamaListing(raw: unknown, source: "daemon" | "ollama.com"): OllamaListing | null {
+	const rec = asRec(raw);
+	if (rec === null) return null;
+	const id = typeof rec.model === "string" && rec.model !== "" ? rec.model : typeof rec.name === "string" ? rec.name : "";
+	if (id === "") return null;
+	const details = asRec(rec.details);
+	const ctx = details?.context_length;
+	const caps = Array.isArray(rec.capabilities) ? rec.capabilities.filter((c): c is string => typeof c === "string") : [];
+	const remote = typeof rec.remote_model === "string" && rec.remote_model !== "" ? rec.remote_model : null;
+	const modified = typeof rec.modified_at === "string" ? Date.parse(rec.modified_at) : NaN;
+	return {
+		id,
+		remoteModel: remote ?? (source === "ollama.com" ? id : null),
+		// On the daemon only proxied entries are cloud models; on ollama.com
+		// everything listed is.
+		isCloud: source === "ollama.com" || typeof rec.remote_host === "string",
+		contextLength: typeof ctx === "number" && Number.isFinite(ctx) && ctx > 0 ? ctx : null,
+		capabilities: caps,
+		modifiedAtMs: Number.isFinite(modified) ? modified : 0,
+	};
+}
+
+/** `POST /api/show` reduced to the two fields the listing may lack. */
+export function parseOllamaShow(raw: unknown): { contextLength: number | null; capabilities: string[] } {
+	const rec = asRec(raw);
+	const caps = rec !== null && Array.isArray(rec.capabilities) ? rec.capabilities.filter((c): c is string => typeof c === "string") : [];
+	let contextLength: number | null = null;
+	const info = rec === null ? null : asRec(rec.model_info);
+	if (info !== null) {
+		for (const [k, v] of Object.entries(info)) {
+			if (k.endsWith(".context_length") && typeof v === "number" && Number.isFinite(v) && v > 0) {
+				contextLength = v;
+				break;
+			}
+		}
+	}
+	return { contextLength, capabilities: caps };
+}
+
+/**
+ * Normalised match key for an Ollama name. Ollama separates the tag with `:`
+ * (`gpt-oss:120b`) where OpenRouter uses `-` (`openai/gpt-oss-120b`), so the
+ * tag is folded in before the shared normaliser runs.
+ */
+export function ollamaTwinKey(name: string): string {
+	return normalizeModelKey(bareCloudName(name).replace(/:/g, "-"));
+}
+
+/** OpenRouter models indexed by normalised name, first slug wins per key. */
+export function twinIndex(openrouter: readonly CatalogModel[]): Map<string, CatalogModel> {
+	const out = new Map<string, CatalogModel>();
+	for (const m of openrouter) {
+		if (m.provider !== "openrouter") continue;
+		if (m.slug.startsWith("~") || m.slug.endsWith(":batch") || m.slug.includes(":free")) continue;
+		const key = normalizeModelKey(m.slug);
+		if (!out.has(key)) out.set(key, m);
+	}
+	return out;
+}
+
+export interface BuildOllamaArgs {
+	listings: readonly OllamaListing[];
+	openrouter: readonly CatalogModel[];
+	cfg: OllamaConfig;
+	log?: Logger;
+}
+
+/** Builds catalog models from listings + prices + twins. Pure; no I/O. */
+export function buildOllamaModels(args: BuildOllamaArgs): CatalogModel[] {
+	const { listings, openrouter, cfg, log } = args;
+	const twins = twinIndex(openrouter);
+	const bySlug = new Map(openrouter.map((m) => [m.slug, m] as const));
+	const out: CatalogModel[] = [];
+	const skipped: string[] = [];
+	for (const l of listings) {
+		if (!l.isCloud && !cfg.includeLocal) continue;
+		const priceName = l.remoteModel ?? l.id;
+		const rate = ollamaRateFor(priceName, cfg.prices);
+		if (rate === null) {
+			skipped.push(l.id);
+			continue;
+		}
+		// A pin may name the tagged cloud name, its base, or the listed id.
+		const bare = bareCloudName(priceName);
+		const base = bare.includes(":") ? bare.slice(0, bare.indexOf(":")) : bare;
+		const pinned = cfg.twins[bare] ?? cfg.twins[base] ?? cfg.twins[l.id];
+		const twin = (pinned !== undefined ? bySlug.get(pinned) : undefined) ?? twins.get(ollamaTwinKey(priceName)) ?? null;
+		const contextLength = l.contextLength ?? twin?.contextLength ?? null;
+		if (contextLength === null) {
+			skipped.push(`${l.id} (no context length)`);
+			continue;
+		}
+		const caps = new Set(l.capabilities);
+		const hasCaps = caps.size > 0;
+		const modalities: Modality[] = ["text"];
+		if (hasCaps ? caps.has("vision") : (twin?.inputModalities.includes("image") ?? false)) modalities.push("image");
+		const model: CatalogModel = {
+			slug: `${OLLAMA_SLUG_PREFIX}${l.id}`,
+			canonicalSlug: `${OLLAMA_SLUG_PREFIX}${priceName}`,
+			name: `${l.id} (Ollama Cloud)`,
+			provider: "ollama",
+			contextLength,
+			supportsTools: hasCaps ? caps.has("tools") : (twin?.supportsTools ?? false),
+			supportsReasoning: hasCaps ? caps.has("thinking") : (twin?.supportsReasoning ?? false),
+			reasoningMandatory: false,
+			// Ollama's OpenAI-compatible endpoint documents `tool_choice` as unsupported.
+			supportsToolChoice: false,
+			inputModalities: modalities,
+			price: toPrice(rate.rate),
+			priceTiers: [],
+			quality: twin === null ? {} : { ...twin.quality },
+			tokenizer: twin?.tokenizer ?? "Other",
+			isFree: false,
+			createdAtMs: l.modifiedAtMs,
+			author: "ollama",
+		};
+		if (twin?.maxCompletionTokens !== undefined) model.maxCompletionTokens = twin.maxCompletionTokens;
+		out.push(model);
+	}
+	if (skipped.length > 0) log?.debug("ollama models skipped (no price or context)", { skipped: skipped.join(", ") });
+	return out;
+}
+
+function toPrice(rate: OllamaRate): CatalogModel["price"] {
+	const price: CatalogModel["price"] = { prompt: rate.input / 1e6, completion: rate.output / 1e6 };
+	if (rate.cachedInput !== undefined) price.cacheRead = rate.cachedInput / 1e6;
+	return price;
+}
+
+/** Minimal fetch surface, injectable for tests. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface OllamaCatalogSource {
+	/** Cloud models, refreshed when older than `cfg.catalogTtlMs`; last good set on failure. */
+	get(openrouter: readonly CatalogModel[]): Promise<CatalogModel[]>;
+	/** Last built set without touching the network. */
+	peek(): CatalogModel[];
+	/** Forces a re-list on the next `get`. */
+	invalidate(): void;
+}
+
+/** Whether a base URL points at ollama.com (which needs `/api/show` for metadata). */
+export function isOllamaDotCom(baseUrl: string): boolean {
+	try {
+		return new URL(baseUrl).hostname.toLowerCase().endsWith("ollama.com");
+	} catch {
+		return false;
+	}
+}
+
+/** `https://ollama.com/v1` → `https://ollama.com`; the native API lives beside `/v1`. */
+export function ollamaApiRoot(baseUrl: string): string {
+	return baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+export function createOllamaCatalog(cfg: OllamaConfig, log: Logger, fetchImpl: FetchLike = fetch): OllamaCatalogSource {
+	const root = ollamaApiRoot(cfg.baseUrl);
+	const direct = isOllamaDotCom(cfg.baseUrl);
+	const headers: Record<string, string> = {};
+	if (cfg.apiKey !== "") headers.authorization = `Bearer ${cfg.apiKey}`;
+	let models: CatalogModel[] = [];
+	let listedAtMs = 0;
+	let inflight: Promise<CatalogModel[]> | null = null;
+	// `/api/show` results are stable per id; fetched once per process.
+	const shown = new Map<string, { contextLength: number | null; capabilities: string[] }>();
+
+	async function list(): Promise<OllamaListing[]> {
+		const res = await fetchImpl(`${root}/api/tags`, { headers, signal: AbortSignal.timeout(cfg.timeoutMs) });
+		if (!res.ok) throw new Error(`ollama /api/tags HTTP ${res.status}`);
+		const json = asRec(await res.json());
+		const raw = json !== null && Array.isArray(json.models) ? json.models : [];
+		const out: OllamaListing[] = [];
+		for (const r of raw) {
+			const l = parseOllamaListing(r, direct ? "ollama.com" : "daemon");
+			if (l !== null) out.push(l);
+		}
+		// ollama.com's listing has no context/capabilities; ask per model, once.
+		if (direct) {
+			for (const l of out) {
+				if (l.contextLength !== null && l.capabilities.length > 0) continue;
+				let s = shown.get(l.id);
+				if (s === undefined) {
+					try {
+						const r = await fetchImpl(`${root}/api/show`, {
+							method: "POST",
+							headers: { ...headers, "content-type": "application/json" },
+							body: JSON.stringify({ model: l.id }),
+							signal: AbortSignal.timeout(cfg.timeoutMs),
+						});
+						s = r.ok ? parseOllamaShow(await r.json()) : { contextLength: null, capabilities: [] };
+					} catch {
+						s = { contextLength: null, capabilities: [] };
+					}
+					shown.set(l.id, s);
+				}
+				if (l.contextLength === null) l.contextLength = s.contextLength;
+				if (l.capabilities.length === 0) l.capabilities = s.capabilities;
+			}
+		}
+		return out;
+	}
+
+	async function refresh(openrouter: readonly CatalogModel[]): Promise<CatalogModel[]> {
+		try {
+			const listings = await list();
+			const built = buildOllamaModels({ listings, openrouter, cfg, log });
+			if (built.length === 0 && models.length > 0) {
+				log.warn("ollama listing yielded no priced cloud models; keeping the previous set", { listed: listings.length });
+			} else {
+				models = built;
+			}
+			listedAtMs = Date.now();
+		} catch (err) {
+			log.warn("ollama catalog refresh failed; keeping the previous set", {
+				error: err instanceof Error ? err.message : String(err),
+				models: models.length,
+			});
+			// Back off for a full TTL rather than hammering a dead endpoint each turn.
+			listedAtMs = Date.now();
+		}
+		return models;
+	}
+
+	return {
+		async get(openrouter) {
+			if (Date.now() - listedAtMs < cfg.catalogTtlMs) return models;
+			inflight ??= refresh(openrouter).finally(() => {
+				inflight = null;
+			});
+			return inflight;
+		},
+		peek() {
+			return models;
+		},
+		invalidate() {
+			listedAtMs = 0;
+		},
+	};
+}
+
+/** True when a catalog slug is an Ollama model. */
+export function isOllamaSlug(slug: string): boolean {
+	return slug.startsWith(OLLAMA_SLUG_PREFIX);
+}
+
+/** The id Ollama expects in the request body. */
+export function ollamaModelId(slug: string): string {
+	return isOllamaSlug(slug) ? slug.slice(OLLAMA_SLUG_PREFIX.length) : slug;
+}
+
+/** Composite snapshot helper: append Ollama models to an OpenRouter snapshot. */
+export function mergeSnapshots(openrouter: CatalogSnapshot, ollama: readonly CatalogModel[]): CatalogSnapshot {
+	if (ollama.length === 0) return openrouter;
+	const merged: CatalogSnapshot = {
+		...openrouter,
+		models: [...openrouter.models, ...ollama],
+		fetchedAtMs: openrouter.fetchedAtMs,
+	};
+	return merged;
+}

package/src/catalog/ollama-prices.ts

@@ -0,0 +1,85 @@
+/**
+ * Ollama Cloud per-model token rates, USD per million tokens.
+ *
+ * Ollama publishes these on https://ollama.com/pricing and nowhere machine-
+ * readable: neither `/v1/models` nor `/api/tags` carries a price, so the router
+ * ships a snapshot and lets `ollama.prices` in config override or extend it. A
+ * model with no rate from either source is dropped from the catalog — routing
+ * on an unknown price is how budgets silently blow up (same rule as the
+ * OpenRouter `-1` sentinel).
+ *
+ * Keys are the bare cloud model names as ollama.com lists them. Where Ollama
+ * prices a specific tag (`gpt-oss:120b`) the key keeps the tag; otherwise the
+ * base name covers every tag (`deepseek-v4-pro:0813` → `deepseek-v4-pro`).
+ *
+ * Snapshot taken 2026-09-05 from ollama.com/pricing. Cached-input rates are
+ * absent for some rows on that page; those models get no cache-read discount
+ * rather than an invented one.
+ */
+
+export interface OllamaRate {
+	/** USD per million uncached prompt tokens. */
+	input: number;
+	/** USD per million cached prompt tokens. Absent ⇒ no published discount. */
+	cachedInput?: number;
+	/** USD per million completion tokens. */
+	output: number;
+}
+
+export const OLLAMA_PRICE_SNAPSHOT_DATE = "2026-09-05";
+
+export const OLLAMA_BUILTIN_PRICES: Readonly<Record<string, OllamaRate>> = {
+	"deepseek-v4-flash": { input: 0.22, cachedInput: 0.007, output: 0.66 },
+	"deepseek-v4-pro": { input: 0.66, cachedInput: 0.022, output: 1.98 },
+	gemma4: { input: 0.14, cachedInput: 0.05, output: 0.4 },
+	"glm-5.3": { input: 1.4, cachedInput: 0.26, output: 4.4 },
+	"glm-5.3-flash": { input: 0.15, cachedInput: 0.03, output: 0.5 },
+	"glm-5.2": { input: 1.4, cachedInput: 0.26, output: 4.4 },
+	"glm-5.1": { input: 1.0, cachedInput: 0.2, output: 3.2 },
+	"gpt-oss:120b": { input: 0.15, cachedInput: 0.014, output: 0.6 },
+	"gpt-oss:20b": { input: 0.07, cachedInput: 0.035, output: 0.3 },
+	"kimi-k3": { input: 3.0, cachedInput: 0.3, output: 15.0 },
+	"kimi-k2.7-code": { input: 0.95, cachedInput: 0.19, output: 4.0 },
+	"kimi-k2.6": { input: 0.95, cachedInput: 0.16, output: 4.0 },
+	"minimax-m3": { input: 0.6, cachedInput: 0.12, output: 2.4 },
+	"minimax-m2.7": { input: 0.3, cachedInput: 0.06, output: 1.2 },
+	"mistral-large-3": { input: 0.5, output: 1.5 },
+	"nemotron-3-nano": { input: 0.06, output: 0.24 },
+	"nemotron-3-super": { input: 0.015, cachedInput: 0.015, output: 0.6 },
+	"nemotron-3-ultra": { input: 0.1, cachedInput: 0.1, output: 3.0 },
+	"qwen3.5:397b": { input: 0.6, output: 3.6 },
+};
+
+/**
+ * The bare cloud name a listing entry is priced under: the daemon's `:cloud`
+ * / `-cloud` decoration stripped, lower-cased. `glm-5.3-flash:cloud` and
+ * `deepseek-v4-pro:0813-cloud` become `glm-5.3-flash` and
+ * `deepseek-v4-pro:0813`, which is exactly how ollama.com lists them.
+ */
+export function bareCloudName(id: string): string {
+	let s = id.trim().toLowerCase();
+	if (s.endsWith(":cloud")) s = s.slice(0, -":cloud".length);
+	else if (s.endsWith("-cloud")) s = s.slice(0, -"-cloud".length);
+	return s;
+}
+
+/**
+ * Rate for a cloud model: the exact tagged name first (`gpt-oss:120b`), then
+ * the base name before the tag (`deepseek-v4-pro:0813` → `deepseek-v4-pro`).
+ * `overrides` (from config) win over the built-in snapshot at every step.
+ */
+export function ollamaRateFor(
+	id: string,
+	overrides: Readonly<Record<string, OllamaRate>> = {},
+): { key: string; rate: OllamaRate } | null {
+	const bare = bareCloudName(id);
+	const colon = bare.indexOf(":");
+	const candidates = colon === -1 ? [bare] : [bare, bare.slice(0, colon)];
+	for (const key of candidates) {
+		const o = overrides[key];
+		if (o !== undefined) return { key, rate: o };
+		const b = OLLAMA_BUILTIN_PRICES[key];
+		if (b !== undefined) return { key, rate: b };
+	}
+	return null;
+}

package/src/catalog/openrouter-catalog.ts

@@ -12,7 +12,25 @@ import type { Database } from "bun:sqlite";
 import type { RouterConfig } from "../config/types.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
 import { createLogger } from "../util/log.ts";
-import type { CatalogModel, CatalogSnapshot, CatalogSource, Modality, Price, PriceTier, QualityScores } from "./types.ts";
+import type {
+	CatalogModel,
+	CatalogShrink,
+	CatalogSnapshot,
+	CatalogSource,
+	Modality,
+	Price,
+	PriceTier,
+	QualityScores,
+} from "./types.ts";
+
+/**
+ * A refresh that keeps fewer than this fraction of the previous snapshot's
+ * models is a "sharp shrink": logged at warn and surfaced on /health. Only
+ * judged once the previous snapshot is big enough for the ratio to mean
+ * anything (SHRINK_MIN_PREVIOUS).
+ */
+const SHRINK_KEEP_RATIO = 0.5;
+const SHRINK_MIN_PREVIOUS = 20;
 import { applyFeedScores, loadLocalScores, refreshFeedScores } from "./benchmark-feeds.ts";
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -163,6 +181,7 @@ export function normalizeCatalogModel(raw: unknown): CatalogModel | null {
 
 	const model: CatalogModel = {
 		slug: id,
+		provider: "openrouter",
 		canonicalSlug: typeof canonical === "string" && canonical.length > 0 ? canonical : id,
 		name: typeof name === "string" && name.length > 0 ? name : id,
 		contextLength,
@@ -259,6 +278,7 @@ export function createCatalog(cfg: RouterConfig, upstream: UpstreamClient, db: D
 	let bySlug = new Map<string, CatalogModel>();
 	let hydrated = false;
 	let inflight: Promise<CatalogSnapshot> | null = null;
+	let lastShrink: CatalogShrink | null = null;
 	const readCache = db.query("SELECT payload, fetched_at_ms, etag, key_scoped FROM catalog_cache WHERE id = 1");
 	const writeCache = db.query(
 		`INSERT INTO catalog_cache (id, payload, fetched_at_ms, etag, key_scoped) VALUES (1, ?, ?, NULL, ?)
@@ -407,6 +427,21 @@ export function createCatalog(cfg: RouterConfig, upstream: UpstreamClient, db: D
 			return snapshot;
 		}
 		const fetchedAtMs = Date.now();
+		// A sharp shrink is adopted — the key's guardrails are authoritative for
+		// what may be dispatched — but never silently. Measured once: the
+		// admitted set fell 352 → 8 for a day, the cheap default vanished, and a
+		// 10x model served every turn (~$32) with nothing in the log to say why.
+		if (snapshot !== null && snapshot.models.length >= SHRINK_MIN_PREVIOUS && models.length < snapshot.models.length * SHRINK_KEEP_RATIO) {
+			lastShrink = { fromModels: snapshot.models.length, toModels: models.length, atMs: fetchedAtMs };
+			log.warn("catalog shrank sharply; routing narrows to what the key now admits", {
+				from: snapshot.models.length,
+				to: models.length,
+				keyScoped,
+			});
+		} else if (lastShrink !== null && models.length >= lastShrink.fromModels) {
+			log.info("catalog recovered its pre-shrink size", { models: models.length, shrunkTo: lastShrink.toModels });
+			lastShrink = null;
+		}
 		// Persist the RAW payload: normalization improvements apply on the next
 		// boot without a network fetch. The client returns no headers, so no etag.
 		// Only persist the public fallback when keyless: a key-scoped run that fell
@@ -454,5 +489,8 @@ export function createCatalog(cfg: RouterConfig, upstream: UpstreamClient, db: D
 			hydrate();
 			return bySlug.get(slug);
 		},
+		lastShrink(): CatalogShrink | null {
+			return lastShrink;
+		},
 	};
 }

package/src/catalog/types.ts

@@ -45,9 +45,14 @@ export interface QualityScores {
 	agentic?: number;
 }
 
+/** Which upstream serves a catalog model. Slugs are namespaced per provider (`ollama/…`). */
+export type CatalogProvider = "openrouter" | "ollama";
+
 export interface CatalogModel {
-	/** OpenRouter slug, e.g. `anthropic/claude-sonnet-4.5`. Routing identity. */
+	/** OpenRouter slug, e.g. `anthropic/claude-sonnet-4.5`, or `ollama/<id>`. Routing identity. */
 	slug: string;
+	/** Upstream that dispatches this slug. */
+	provider: CatalogProvider;
 	/** Immutable dated slug, e.g. `anthropic/claude-4.5-sonnet-20250929`. */
 	canonicalSlug: string;
 	name: string;
@@ -83,6 +88,12 @@ export interface CatalogSnapshot {
 	models: CatalogModel[];
 	/** When this snapshot was fetched. */
 	fetchedAtMs: number;
+	/**
+	 * Per-provider cost multipliers in force for this snapshot (1 = list price).
+	 * Set by the composite catalog from live plan usage; absent ⇒ the
+	 * configured static bias applies.
+	 */
+	providerBias?: Partial<Record<CatalogProvider, number>>;
 	/**
 	 * True when the snapshot was fetched via key-scoped `GET /models/user`.
 	 * False when fetched from the public `GET /models` endpoint.
@@ -92,6 +103,19 @@ export interface CatalogSnapshot {
 	etag?: string;
 }
 
+/**
+ * A refresh that dropped most of the catalog. Recorded, not resisted: the
+ * router routes over whatever the key admits, but a collapse from hundreds of
+ * models to a handful reroutes every turn onto whatever survived — measured
+ * once at ~$32 in a day when the cheap default vanished and a 10x model served
+ * everything — so it must be visible on `/health` and in the log.
+ */
+export interface CatalogShrink {
+	fromModels: number;
+	toModels: number;
+	atMs: number;
+}
+
 export interface CatalogSource {
 	/** Returns a snapshot, refreshing from upstream when the cached one is older than the TTL. */
 	get(): Promise<CatalogSnapshot>;
@@ -101,4 +125,10 @@ export interface CatalogSource {
 	peek(): CatalogSnapshot | null;
 	/** Slug lookup against the current snapshot. */
 	find(slug: string): CatalogModel | undefined;
+	/**
+	 * The most recent sharp shrink this process observed, or null. Cleared once
+	 * a later refresh restores at least the pre-shrink size. Optional so fakes
+	 * and older sources need not implement it.
+	 */
+	lastShrink?(): CatalogShrink | null;
 }

package/src/cli/args.ts

@@ -29,6 +29,7 @@ const BOOLEAN_FLAGS: Record<string, true> = {
 const COMMANDS: Record<string, true> = {
 	serve: true,
 	stats: true,
+	report: true,
 	models: true,
 	explain: true,
 	config: true,