auto-model-router 0.1.0

package/src/config/load.ts

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { DEFAULT_CONFIG } from "./defaults.ts";
+import { configInputSchema } from "./schema.ts";
+import { resolveOpenRouterKey, type ResolvedCredential } from "./omp-credentials.ts";
+import type { RouterConfig } from "./types.ts";
+
+const LOG_LEVELS: readonly RouterConfig["logLevel"][] = ["silent", "error", "warn", "info", "debug"];
+
+/** Expands a leading `~` (or `~/`) to the user's home directory. */
+export function resolveTilde(p: string): string {
+	if (p === "~") return homedir();
+	if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+	return p;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Recursive merge with omp's settings semantics: plain objects merge key by
+ * key, arrays REPLACE wholesale (they never union or concatenate), and
+ * scalars overwrite. `undefined` override values leave the base untouched.
+ */
+function mergeValue(base: unknown, override: unknown): unknown {
+	if (override === undefined) return base;
+	if (Array.isArray(override)) return override.slice();
+	if (isPlainObject(override) && isPlainObject(base)) {
+		const out: Record<string, unknown> = { ...base };
+		for (const [k, v] of Object.entries(override)) out[k] = mergeValue(out[k], v);
+		return out;
+	}
+	return override;
+}
+
+function deepMerge(base: RouterConfig, override: unknown): RouterConfig {
+	return mergeValue(base, override) as RouterConfig;
+}
+
+/**
+ * Resolves the effective configuration:
+ *   DEFAULT_CONFIG
+ *   <- `$AUTO_MODEL_ROUTER_HOME/config.yml|config.yaml` (or `opts.path`)
+ *   <- environment (`OPENROUTER_API_KEY`, `AUTO_MODEL_ROUTER_PORT`,
+ *      `AUTO_MODEL_ROUTER_HOST`, `AUTO_MODEL_ROUTER_LOG`, `AUTO_MODEL_ROUTER_DB`)
+ *   <- `opts.overrides`
+ *
+ * A missing OpenRouter API key is NOT an error here: catalog refresh and
+ * config work keyless; an embedded router warns at startup and completions
+ * fail at dispatch time.
+ */
+export function loadConfig(opts?: { path?: string; overrides?: Partial<RouterConfig> }): RouterConfig {
+	const home = resolveTilde(process.env.AUTO_MODEL_ROUTER_HOME ?? "~/.auto-model-router");
+
+	// Config file, when present.
+	const filePath = opts?.path !== undefined
+		? resolveTilde(opts.path)
+		: [join(home, "config.yml"), join(home, "config.yaml")].find((p) => existsSync(p));
+
+	let fileInput: unknown = {};
+	if (filePath !== undefined) {
+		const raw: unknown = parseYaml(readFileSync(filePath, "utf8"));
+		if (raw !== null && raw !== undefined) {
+			const parsed = configInputSchema.safeParse(raw);
+			if (!parsed.success) {
+				const lines = parsed.error.issues.map(
+					(issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`,
+				);
+				throw new Error(`Invalid configuration in ${filePath}:\n${lines.join("\n")}`);
+			}
+			fileInput = parsed.data;
+		}
+	}
+
+	// structuredClone: merge copies only along override paths, so untouched
+	// default branches would otherwise be shared (and mutable) by reference.
+	let cfg = deepMerge(structuredClone(DEFAULT_CONFIG), fileInput);
+
+	// Environment overrides.
+	const envInput: Record<string, unknown> = {};
+	const putSection = (section: string, key: string, value: unknown): void => {
+		const s = (envInput[section] ??= {}) as Record<string, unknown>;
+		s[key] = value;
+	};
+	const envApiKey = process.env.OPENROUTER_API_KEY;
+	if (envApiKey !== undefined && envApiKey !== "") putSection("openrouter", "apiKey", envApiKey);
+	const envPort = process.env.AUTO_MODEL_ROUTER_PORT;
+	if (envPort !== undefined && envPort !== "") {
+		const port = Number.parseInt(envPort, 10);
+		if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+			throw new Error(`AUTO_MODEL_ROUTER_PORT must be an integer between 0 and 65535, got "${envPort}"`);
+		}
+		putSection("server", "port", port);
+	}
+	const envHost = process.env.AUTO_MODEL_ROUTER_HOST;
+	if (envHost !== undefined && envHost !== "") putSection("server", "host", envHost);
+	const envLog = process.env.AUTO_MODEL_ROUTER_LOG;
+	if (envLog !== undefined && envLog !== "") {
+		if (!(LOG_LEVELS as readonly string[]).includes(envLog)) {
+			throw new Error(`AUTO_MODEL_ROUTER_LOG must be one of ${LOG_LEVELS.join(", ")}, got "${envLog}"`);
+		}
+		envInput.logLevel = envLog;
+	}
+	const envDb = process.env.AUTO_MODEL_ROUTER_DB;
+	if (envDb !== undefined && envDb !== "") putSection("ledger", "path", envDb);
+	cfg = deepMerge(cfg, envInput);
+
+	// Explicit programmatic overrides win last.
+	if (opts?.overrides !== undefined) cfg = deepMerge(cfg, opts.overrides);
+
+	// The default ledger path is expressed relative to the resolved home.
+	if (cfg.ledger.path === "") cfg.ledger.path = join(home, "router.db");
+	cfg.ledger.path = resolveTilde(cfg.ledger.path);
+
+	// Last resort for the OpenRouter key: borrow omp's own stored credential, so
+	// `/login openrouter` in omp is all the setup this router needs. Explicit
+	// config and environment already won above, so this only fills a blank.
+	const credential = resolveOpenRouterKey(cfg.openrouter.apiKey);
+	cfg.openrouter.apiKey = credential.apiKey;
+	apiKeyProvenance.set(cfg, credential);
+
+	return cfg;
+}
+
+/**
+ * Where a config's OpenRouter key came from, for startup logs and `/health`.
+ * Keyed weakly off the config object so the provenance never has to travel
+ * through `RouterConfig` itself and risk being serialized next to the secret.
+ */
+const apiKeyProvenance = new WeakMap<RouterConfig, ResolvedCredential>();
+
+export function apiKeySource(cfg: RouterConfig): ResolvedCredential {
+	return (
+		apiKeyProvenance.get(cfg) ?? {
+			apiKey: cfg.openrouter.apiKey,
+			source: cfg.openrouter.apiKey === "" ? "none" : "config",
+			detail: cfg.openrouter.apiKey === "" ? "no key configured" : "config",
+		}
+	);
+}

package/src/config/omp-credentials.ts

@@ -0,0 +1,124 @@
+/**
+ * Borrows a provider credential from omp's own auth store.
+ *
+ * The point is that there is exactly ONE OpenRouter key on the machine, owned
+ * by omp. Once `/login openrouter` has been run there, auto-model-router picks the key
+ * up with no config and no second copy to rotate or leak.
+ *
+ * The store is opened READ-ONLY and never written: omp owns that file, including
+ * OAuth refresh. Every failure path returns null rather than throwing, because a
+ * missing or evolving credential store must degrade to "no key" and let the
+ * caller report it, not crash the router at startup.
+ */
+
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type CredentialSource = "config" | "env" | "omp-auth-store" | "none";
+
+export interface ResolvedCredential {
+	apiKey: string;
+	source: CredentialSource;
+	/** Human-readable provenance for logs and `/health`. Never contains the secret. */
+	detail: string;
+}
+
+/** omp's agent directory. `PI_CODING_AGENT_DIR` relocates it wholesale. */
+export function ompAgentDir(): string {
+	const override = process.env.PI_CODING_AGENT_DIR;
+	if (override !== undefined && override !== "") return override;
+	return join(homedir(), ".omp", "agent");
+}
+
+export function ompAuthStorePath(): string {
+	return join(ompAgentDir(), "agent.db");
+}
+
+interface CredentialRow {
+	credential_type: string;
+	data: string;
+	updated_at: number;
+}
+
+/**
+ * Reads a usable API key for `provider` out of omp's auth store.
+ *
+ * Handles both credential shapes omp persists: `api_key` rows carry
+ * `{ key, source }`, OAuth rows carry `{ access, refresh, expires }`. An
+ * expired OAuth access token is deliberately rejected — refreshing it is omp's
+ * job, and sending a stale bearer upstream would just burn a turn on a 401.
+ */
+export function readOmpCredential(provider: string, storePath = ompAuthStorePath()): string | null {
+	// A remote broker replaces the local SQLite store entirely, so there is
+	// nothing to read here and pretending otherwise would be misleading.
+	const broker = process.env.OMP_AUTH_BROKER_URL;
+	if (broker !== undefined && broker !== "") return null;
+	if (!existsSync(storePath)) return null;
+
+	let db: Database | null = null;
+	try {
+		db = new Database(storePath, { readonly: true });
+		const rows = db
+			.query(
+				`SELECT credential_type, data, updated_at
+				 FROM auth_credentials
+				 WHERE provider = ? AND disabled_cause IS NULL
+				 ORDER BY updated_at DESC`,
+			)
+			.all(provider) as CredentialRow[];
+
+		for (const row of rows) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(row.data);
+			} catch {
+				continue;
+			}
+			if (typeof parsed !== "object" || parsed === null) continue;
+
+			if (row.credential_type === "api_key" && "key" in parsed && typeof parsed.key === "string" && parsed.key !== "") {
+				return parsed.key;
+			}
+			if (row.credential_type === "oauth" && "access" in parsed && typeof parsed.access === "string" && parsed.access !== "") {
+				const expires = "expires" in parsed && typeof parsed.expires === "number" ? parsed.expires : 0;
+				if (expires === 0 || expires > Date.now()) return parsed.access;
+			}
+		}
+		return null;
+	} catch {
+		// Locked, corrupt, or a schema this version does not understand.
+		return null;
+	} finally {
+		db?.close();
+	}
+}
+
+/**
+ * Full precedence chain for the OpenRouter key. Explicit configuration always
+ * beats the borrowed credential, so a project can point at a different account
+ * without touching omp.
+ */
+export function resolveOpenRouterKey(configured: string): ResolvedCredential {
+	if (configured !== "") {
+		const fromEnv = process.env.OPENROUTER_API_KEY;
+		const source: CredentialSource = fromEnv !== undefined && fromEnv === configured ? "env" : "config";
+		return {
+			apiKey: configured,
+			source,
+			detail: source === "env" ? "OPENROUTER_API_KEY" : "config file",
+		};
+	}
+
+	const borrowed = readOmpCredential("openrouter");
+	if (borrowed !== null) {
+		return { apiKey: borrowed, source: "omp-auth-store", detail: `omp auth store (${ompAuthStorePath()})` };
+	}
+
+	return {
+		apiKey: "",
+		source: "none",
+		detail: "no key: set OPENROUTER_API_KEY, or run `/login openrouter` inside omp",
+	};
+}

package/src/config/schema.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+/**
+ * Input schema for `$AUTO_MODEL_ROUTER_HOME/config.yml`: a deep partial of
+ * `RouterConfig` — every field is optional so the file carries only
+ * overrides. Nested objects are strict so a misspelled key fails loudly
+ * instead of being silently dropped.
+ *
+ * Array fields (`profiles`, `probeTiers`, `pin`, `allow`, `deny`,
+ * `triggers`) REPLACE the default wholesale on merge; consequently a
+ * `profiles` entry must be complete — there is nothing to merge it with.
+ */
+
+const tier = z.enum(["trivial", "simple", "moderate", "hard"]);
+const qualityAxis = z.enum(["coding", "agentic", "intelligence"]);
+const logLevel = z.enum(["silent", "error", "warn", "info", "debug"]);
+
+const server = z.strictObject({
+	host: z.string().min(1).optional(),
+	port: z.number().int().min(0).max(65_535).optional(),
+	apiKey: z.string().optional(),
+	harnessId: z.string().optional(),
+});
+
+const openrouter = z.strictObject({
+	baseUrl: z.string().min(1).optional(),
+	apiKey: z.string().optional(),
+	referer: z.string().optional(),
+	title: z.string().optional(),
+	timeoutMs: z.number().positive().optional(),
+	catalogTtlMs: z.number().positive().optional(),
+	catalogRefreshMs: z.number().nonnegative().optional(),
+});
+
+const tierConfig = z.strictObject({
+	minQuality: z.number().min(0).max(100).optional(),
+	maxInputPerMtok: z.number().nonnegative().optional(),
+	maxOutputPerMtok: z.number().nonnegative().optional(),
+	qualityExponent: z.number().nonnegative().optional(),
+	pin: z.array(z.string()).optional(),
+});
+
+const taskConfig = z.strictObject({
+	axis: qualityAxis.optional(),
+	minQuality: z.number().min(0).max(100).optional(),
+	requireImage: z.boolean().optional(),
+	prefer: z.array(z.string()).optional(),
+});
+
+const filters = z.strictObject({
+	allow: z.array(z.string()).optional(),
+	deny: z.array(z.string()).optional(),
+	includeFree: z.boolean().optional(),
+	requireToolSupport: z.boolean().optional(),
+	minTrust: z.number().min(0).max(1).optional(),
+	minTrustSamples: z.number().int().nonnegative().optional(),
+	trustScopedByHarness: z.boolean().optional(),
+	contextHeadroom: z.number().positive().optional(),
+});
+
+const classifier = z.strictObject({
+	ambiguityThreshold: z.number().min(0).max(1).optional(),
+	model: z.string().min(1).optional(),
+	maxCostFraction: z.number().min(0).max(1).optional(),
+	maxCostUsd: z.number().nonnegative().optional(),
+	timeoutMs: z.number().positive().optional(),
+	cacheSize: z.number().int().nonnegative().optional(),
+	toolAxis: qualityAxis.optional(),
+	chatAxis: qualityAxis.optional(),
+	agenticLoopDepth: z.number().int().nonnegative().optional(),
+});
+
+const escalation = z.strictObject({
+	enabled: z.boolean().optional(),
+	probeTokens: z.number().int().positive().optional(),
+	maxHoldMs: z.number().positive().optional(),
+	maxAttempts: z.number().int().positive().optional(),
+	probeTiers: z.array(tier).optional(),
+	triggers: z.array(z.string()).optional(),
+	escalateOnLengthStop: z.boolean().optional(),
+});
+
+const hysteresis = z.strictObject({
+	holdTurns: z.number().int().nonnegative().optional(),
+	holdTurnsAfterEscalation: z.number().int().nonnegative().optional(),
+	switchMargin: z.number().positive().optional(),
+	cacheWarmTtlMs: z.number().nonnegative().optional(),
+	maxDowngradePerTurn: z.number().int().nonnegative().optional(),
+});
+
+const cache = z.strictObject({
+	injectBreakpoints: z.boolean().optional(),
+	maxBreakpoints: z.number().int().positive().optional(),
+	minPromptTokens: z.number().int().nonnegative().optional(),
+});
+
+const budget = z.strictObject({
+	perTurnUsd: z.number().nonnegative().optional(),
+	perConversationUsd: z.number().nonnegative().optional(),
+	perDayUsd: z.number().nonnegative().optional(),
+	onExceeded: z.enum(["downgrade", "reject"]).optional(),
+});
+
+const fallbackBlend = z.strictObject({
+	inputPerMtok: z.number().nonnegative().optional(),
+	outputPerMtok: z.number().nonnegative().optional(),
+});
+
+const ledger = z.strictObject({
+	path: z.string().optional(),
+	blendWindowDays: z.number().positive().optional(),
+	blendMinSamples: z.number().int().nonnegative().optional(),
+	fallbackBlend: fallbackBlend.optional(),
+	conversationTtlMs: z.number().positive().optional(),
+});
+
+// Complete entries: arrays replace wholesale, so a partial profile would
+// produce an invalid resolved config.
+const profile = z.strictObject({
+	id: z.string().min(1),
+	name: z.string().min(1),
+	maxTier: tier,
+	minTier: tier,
+	contextWindow: z.number().int().positive(),
+	maxTokens: z.number().int().positive(),
+	budget: budget.optional(),
+});
+
+export const configInputSchema = z.strictObject({
+	server: server.optional(),
+	openrouter: openrouter.optional(),
+	tiers: z
+		.strictObject({
+			trivial: tierConfig.optional(),
+			simple: tierConfig.optional(),
+			moderate: tierConfig.optional(),
+			hard: tierConfig.optional(),
+		})
+		.optional(),
+	tasks: z
+		.strictObject({
+			coding: taskConfig.optional(),
+			vision: taskConfig.optional(),
+			documentation: taskConfig.optional(),
+			data: taskConfig.optional(),
+			chat: taskConfig.optional(),
+		})
+		.optional(),
+	filters: filters.optional(),
+	classifier: classifier.optional(),
+	escalation: escalation.optional(),
+	hysteresis: hysteresis.optional(),
+	cache: cache.optional(),
+	budget: budget.optional(),
+	profiles: z.array(profile).optional(),
+	ledger: ledger.optional(),
+	adaptiveTierFloors: z.boolean().optional(),
+	logLevel: logLevel.optional(),
+});
+
+export type ConfigInput = z.infer<typeof configInputSchema>;

package/src/config/types.ts

@@ -0,0 +1,244 @@
+/**
+ * Router configuration.
+ *
+ * Layered: built-in defaults <- `$AUTO_MODEL_ROUTER_HOME/config.yml` <- environment
+ * <- CLI flags. Every field is optional on disk; `RouterConfig` is the fully
+ * resolved shape the rest of the code consumes.
+ */
+
+import type { TaskType, Tier } from "../router/types.ts";
+
+export type QualityAxis = "coding" | "agentic" | "intelligence";
+
+/**
+ * Per-task routing envelope. Task type selects the quality axis, capability
+ * filters, and quality floor; the complexity tier's price ceiling and the
+ * budget guard still cap cost (task selects, tier budgets).
+ */
+export interface TaskConfig {
+	/** Quality axis to score candidates against for this task. */
+	axis: QualityAxis;
+	/** Minimum quality on that axis, 0-100. Overrides the tier floor when higher. */
+	minQuality?: number;
+	/** Require image input support. Hard filter for vision tasks. */
+	requireImage?: boolean;
+	/** Slugs always eligible for this task regardless of quality floor. */
+	prefer?: string[];
+}
+
+export interface ServerConfig {
+	host: string;
+	port: number;
+	/** Optional bearer required from clients. Unset ⇒ loopback-only, no auth. */
+	apiKey?: string;
+	/**
+	 * Harness identity emitted as the `X-Omp-Harness` header in the generated
+	 * `models.yml` provider block. Lets multiple coding harnesses share one
+	 * router while keeping per-harness daily budgets and toast scoping. Empty
+	 * ⇒ no header (single-harness default).
+	 */
+	harnessId?: string;
+}
+
+export interface OpenRouterConfig {
+	baseUrl: string;
+	/** Resolved from config, then `OPENROUTER_API_KEY`. */
+	apiKey: string;
+	/** Sent as `HTTP-Referer`, for OpenRouter attribution. */
+	referer?: string;
+	/** Sent as `X-Title`. */
+	title: string;
+	/** Per-request timeout, ms. */
+	timeoutMs: number;
+	/** Catalog freshness threshold, ms: refetch on traffic when older than this. */
+	catalogTtlMs: number;
+	/** Background catalog refresh cadence, ms. 0 disables the periodic refresh. */
+	catalogRefreshMs: number;
+}
+
+/** Quality/price envelope for one complexity tier. */
+export interface TierConfig {
+	/**
+	 * Minimum quality on the request's chosen axis, 0-100 (Artificial Analysis
+	 * index as published by OpenRouter). The tier's capability guarantee.
+	 */
+	minQuality: number;
+	/** Hard ceiling on input price, USD per million tokens. Unset ⇒ unbounded. */
+	maxInputPerMtok?: number;
+	/** Hard ceiling on output price, USD per million tokens. Unset ⇒ unbounded. */
+	maxOutputPerMtok?: number;
+	/**
+	 * Exponent on quality in the ranking score. 0 ⇒ pick the cheapest model
+	 * above the floor (Pareto-style). Higher ⇒ pay for headroom above it.
+	 */
+	qualityExponent: number;
+	/** Slugs always allowed in this tier regardless of the quality floor. */
+	pin: string[];
+}
+
+export interface FilterConfig {
+	/** Glob patterns; a model must match one. Empty ⇒ allow all. */
+	allow: string[];
+	/** Glob patterns; matching models are dropped. Applied after `allow`. */
+	deny: string[];
+	/** Consider zero-price models. Off by default: rate limits make them expensive in retries. */
+	includeFree: boolean;
+	/** Require `supported_parameters` to include `tools` whenever the request offers tools. */
+	requireToolSupport: boolean;
+	/** Drop models whose ledger success rate is below this, once `minTrustSamples` is met. */
+	minTrust: number;
+	/** Attempts required before `minTrust` is enforced against a model. */
+	minTrustSamples: number;
+	/**
+	 * Scope model trust to the requesting harness instead of the whole ledger.
+	 * Off by default: shared trust converges on more samples and keeps the
+	 * demotion guard effective with a small catalog. Enable only when harnesses
+	 * route over meaningfully different model sets and each has enough traffic
+	 * to learn its own reliability.
+	 */
+	trustScopedByHarness: boolean;
+	/**
+	 * Headroom multiplier applied to estimated prompt tokens when checking a
+	 * model's context window, absorbing token-estimate error and the response.
+	 */
+	contextHeadroom: number;
+}
+
+export interface ClassifierConfig {
+	/**
+	 * Heuristic confidence below which the LLM adjudicator is consulted.
+	 * 0 disables the adjudicator entirely.
+	 */
+	ambiguityThreshold: number;
+	/** Slug used for adjudication. Must be cheap and fast. */
+	model: string;
+	/** Skip adjudication when it would exceed this fraction of the forecast turn cost. */
+	maxCostFraction: number;
+	/** Absolute per-call ceiling, USD. */
+	maxCostUsd: number;
+	timeoutMs: number;
+	/** Adjudication verdicts cached per turn fingerprint. */
+	cacheSize: number;
+	/** Which quality axis to score against when the request offers tools. */
+	toolAxis: QualityAxis;
+	/** Axis for plain chat requests. */
+	chatAxis: QualityAxis;
+	/** Tool-loop depth above which the agentic axis takes over. */
+	agenticLoopDepth: number;
+}
+
+export interface EscalationConfig {
+	enabled: boolean;
+	/** Hold this many text tokens before committing the stream to the client. */
+	probeTokens: number;
+	/** Hard ceiling on hold time, ms. Elapsing commits the attempt. */
+	maxHoldMs: number;
+	/** Max escalation retries per turn. */
+	maxAttempts: number;
+	/** Tiers eligible for probing. Frontier tiers are usually excluded. */
+	probeTiers: Tier[];
+	/** Signals that trigger escalation. Narrowing this makes the guard more permissive. */
+	triggers: string[];
+	/**
+	 * Escalate when a `length` finish truncated TOOL-CALL ARGUMENTS, leaving
+	 * structurally unusable output. A length finish on prose never escalates:
+	 * that is the caller's own `max_tokens`, and a retry truncates identically.
+	 */
+	escalateOnLengthStop: boolean;
+}
+
+export interface HysteresisConfig {
+	/** Turns to hold a tier after committing to it. */
+	holdTurns: number;
+	/** Turns to hold after an escalation, so a hard sub-task stays on the strong model. */
+	holdTurnsAfterEscalation: number;
+	/**
+	 * Switch models only when the expected saving exceeds the forfeited cache
+	 * discount by this multiple. 1.0 ⇒ break even; higher ⇒ stickier.
+	 */
+	switchMargin: number;
+	/** Assume a warm cache expires after this long. OpenRouter sticky sessions: 5-10 min. */
+	cacheWarmTtlMs: number;
+	/** Downgrade at most this many tiers per turn, so quality never falls off a cliff. */
+	maxDowngradePerTurn: number;
+}
+
+export interface CacheConfig {
+	/**
+	 * Inject Anthropic-style `cache_control` breakpoints. OpenRouter translates
+	 * them to OpenAI/Google cache primitives, so one mechanism covers every target.
+	 */
+	injectBreakpoints: boolean;
+	/** Max breakpoints per request. Anthropic allows 4. */
+	maxBreakpoints: number;
+	/** Skip injection below this prompt-token estimate; small prompts cannot cache. */
+	minPromptTokens: number;
+}
+
+export interface BudgetConfig {
+	/** Reject or downgrade when a turn's cold forecast exceeds this, USD. */
+	perTurnUsd?: number;
+	/** Force the cheapest viable tier once a conversation exceeds this, USD. */
+	perConversationUsd?: number;
+	/** Rolling 24h ceiling, USD. */
+	perDayUsd?: number;
+	/** At the ceiling: drop to the cheapest viable model, or fail the request outright. */
+	onExceeded: "downgrade" | "reject";
+}
+
+/**
+ * A virtual model exposed to clients. `auto` is the general profile; the
+ * others bias the same machinery toward cost or quality.
+ */
+export interface ProfileConfig {
+	/** Model id as clients see it, e.g. `auto`. */
+	id: string;
+	/** Display name in omp's model picker. */
+	name: string;
+	/** Clamp classification to at most this tier. */
+	maxTier: Tier;
+	/** Floor classification at this tier. */
+	minTier: Tier;
+	/** Context window advertised to omp; drives its compaction threshold. */
+	contextWindow: number;
+	/** Max output tokens advertised to omp. */
+	maxTokens: number;
+	/** Per-profile budget overrides. */
+	budget?: Partial<BudgetConfig>;
+}
+
+export interface LedgerConfig {
+	/** SQLite path. Defaults to `$AUTO_MODEL_ROUTER_HOME/router.db`. */
+	path: string;
+	/** Window for the blended rate published to omp, days. */
+	blendWindowDays: number;
+	/** Requests required before the measured blend replaces `fallbackBlend`. */
+	blendMinSamples: number;
+	/** Blend used before enough samples exist, USD per million tokens. */
+	fallbackBlend: { inputPerMtok: number; outputPerMtok: number };
+	/** Drop conversation state untouched for longer than this, ms. */
+	conversationTtlMs: number;
+}
+
+export interface RouterConfig {
+	server: ServerConfig;
+	openrouter: OpenRouterConfig;
+	tiers: Record<Tier, TierConfig>;
+	tasks: Record<TaskType, TaskConfig>;
+	filters: FilterConfig;
+	classifier: ClassifierConfig;
+	escalation: EscalationConfig;
+	hysteresis: HysteresisConfig;
+	cache: CacheConfig;
+	budget: BudgetConfig;
+	profiles: ProfileConfig[];
+	ledger: LedgerConfig;
+	/**
+	 * Derive each tier's quality floor from the models actually available at
+	 * every catalog refresh, relaxing (never tightening) the configured floors.
+	 * Without this, a narrow OpenRouter guardrail leaves every tier above
+	 * `trivial` permanently empty and the router is stuck on the cheapest model.
+	 */
+	adaptiveTierFloors: boolean;
+	logLevel: "silent" | "error" | "warn" | "info" | "debug";
+}