auto-model-router 0.17.0 → 0.18.0

package/.claude/skills/agentdox/SKILL.md

@@ -5,7 +5,7 @@ description: "Use agentdox — the shared memory, docs, and context server — t
 
 # agentdox — the standard interaction protocol
 
-agentdox is a shared memory + docs + conversation store at `http://localhost:3003`. It is what
+agentdox is a shared memory + docs + conversation store at `http://localhost:8790/agentdox`. It is what
 stops you rediscovering the same project facts every session.
 
 **Follow this protocol identically every time.** Consistency is the point: the value of the
@@ -55,7 +55,7 @@ Deterministic, so the same folder always resolves to the same slug:
    repo root:
 
    ```ini
-   AGENTDOX_URL=http://localhost:3003
+   AGENTDOX_URL=http://localhost:8790/agentdox
    AGENTDOX_SCOPE=<slug>
    AGENTDOX_TOKEN=<the global PAT>
    ```
@@ -104,6 +104,16 @@ determine the scope, ask — do not guess, and do not fall back to a default.
 
 ## 1. Pick your transport — MCP or REST
 
+> **Where the store lives (since 2026-09-10).** The store is the team edition's embedded agentdox,
+> reached through the team: REST at `http://localhost:8790/agentdox/...` and MCP at
+> `http://localhost:8790/mcp`, with a **team member key** (`amrt_…`) as `AGENTDOX_TOKEN`. The team maps
+> the key to the member's grants (write on every project of their groups, read on the group's
+> context), so a 401 means the key and a 403 means the project belongs to another group — not a PAT.
+> agentdox's own `/auth` routes are not reachable through the team; projects are created on the
+> team's Groups page or appear on a workspace's first turn. The old dev container on :3003 is retired.
+> A member key updates entries (`PATCH /memory/:id`) but cannot delete them (agentdox wants admin on the
+> scope for that): to retire a fact, lower its importance or leave it to the team's retention pass.
+
 Both hit the same live store with the same RBAC. **Check which you have, then use it:**
 
 - **MCP tools present** — use them. Claude Code and Cursor mount them as `memory_add`,
@@ -129,7 +139,7 @@ inline JSON and avoids quoting pain in `curl`:
 ```ts
 const tok = /AGENTDOX_TOKEN=(.+)/.exec(await Bun.file(".env.agentdox").text())?.[1]?.trim() ?? "";
 const H = { Authorization: `Bearer ${tok}`, "content-type": "application/json" };
-await fetch("http://localhost:3003/memory", { method: "POST", headers: H,
+await fetch("http://localhost:8790/agentdox/memory", { method: "POST", headers: H,
   body: JSON.stringify({ content: "…", category: "<scope>", importance: 0.9 }) });
 ```
 

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "agentdox": {
       "type": "http",
-      "url": "http://localhost:3003/mcp",
+      "url": "http://localhost:8790/mcp",
       "headers": {
         "Authorization": "Bearer ${AGENTDOX_TOKEN}"
       }

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.17.0",
+    "version": "0.18.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.17.0",
+      "version": "0.18.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/CLAUDE.md

@@ -24,7 +24,7 @@ tips). Read it before using agentdox; do not improvise from this summary.
 | --- | --- |
 | Token, URL, scope | `.env.agentdox` in this repo root (gitignored — never commit) |
 | What `.mcp.json` reads | the `AGENTDOX_TOKEN` **environment variable** (Windows *User* scope; shells opened before it was set lack it) |
-| Server | `http://localhost:3003` — Docker container `agentdox-server`; endpoints in `E:/projects/agentdox/packages/server/src/index.ts` |
+| Server | `http://localhost:8790/agentdox` — the team edition's embedded agentdox (the `agentdox-server` container is retired); endpoints in `E:/projects/agentdox/packages/server/src/index.ts` |
 | Admin token (re-mint) | `E:/projects/agentdox/deploy/.env` |
 
 Two rules that cause silent mistakes: **memory calls take `category`, everything else takes
@@ -46,7 +46,7 @@ behind them are recorded there as they are made.
 Turning the bridge on for the router itself (distinct from the MCP wiring above):
 
 ```bash
-export AGENTDOX_URL=http://localhost:3003
+export AGENTDOX_URL=http://localhost:8790/agentdox
 export AGENTDOX_TOKEN=<the global PAT, same value .mcp.json uses>
 export AGENTDOX_SCOPE=omp-router
 ```

package/README.md

@@ -716,6 +716,16 @@ escalation signal, error. Three views aggregate it, all from the same
   bill, escalation signal and verdicts (`?session=` narrows to one omp session, as `/router
   why` does). These are what a front door such as the team edition reads instead of the
   ledger file.
+- `GET /v1/router/catalog[?policy=<X-Omp-Policy JSON>]` — the model catalog as data: every
+  model the router knows, sorted by slug, with provider (`openrouter`, `ollama`, a named
+  upstream's id), vendor, context, capabilities, prices in USD per million tokens and quality
+  scores; a model whose upstream cannot serve right now (no key, disabled, in cooldown) is
+  listed too. With `policy` every model also carries `admitted` and, when out, `reason`
+  (`not in the allow list`, `denied by <glob>`, `pinned to <slug>`, the router's own filters,
+  or the upstream's state), judged by the same matcher a turn uses, so the view never drifts
+  from what a turn gets; tiers are per turn and do not take part. A malformed policy is a
+  400; before the first fetch it answers `{ "fetchedAtMs": 0, "models": [] }` rather than
+  waiting. A team front door reads it for its model governance views.
 - `GET /v1/router/report?days=7&harness=<id>` for dashboards (`harness` may be
   a comma-separated set of ids, for a group).
 - `GET /v1/router/summary?harness=<id>` — the daily summary as JSON (`auto=1`
@@ -1287,7 +1297,8 @@ request allow list replaces the configured one, a deny list adds to it.
 widen it. `pin` forces one model the way `/router pin` does, unless a session
 override already pinned one. Every field is optional; a malformed header is
 ignored rather than failing the turn. The decision trail records what the
-policy changed (`policy: …`).
+policy changed (`policy: …`), and `GET /v1/router/catalog?policy=…` shows what a
+policy admits, model by model, without routing a turn.
 
 ## Using a remote router
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/catalog/composite.ts

@@ -46,7 +46,7 @@ export function createCompositeCatalog(
 	ollama: OllamaCatalogSource,
 	availability: OllamaAvailability,
 	bias: CompositeBias = { costBias: 1, biasUntilUsage: 1, usage: NO_USAGE },
-): CatalogSource & { ollamaModels(): CatalogModel[]; ollamaBias(): number } {
+): CatalogSource & { ollamaModels(): CatalogModel[]; ollamaBias(): number; peekAll(): CatalogSnapshot | null } {
 	let lastBase: CatalogSnapshot | null = null;
 	let lastOllama: readonly CatalogModel[] = [];
 	let lastAvailable = true;
@@ -118,6 +118,17 @@ export function createCompositeCatalog(
 			return combine(base, ollama.peek());
 		},
 		find,
+		/**
+		 * Every model the catalog knows, whether or not its upstream can take a
+		 * turn now: OpenRouter's without a key, Ollama's in cooldown, a named
+		 * upstream's in cooldown. `peek()` is what routes; this is what a front
+		 * door lists so it can say why a model is out. No network.
+		 */
+		peekAll(): CatalogSnapshot | null {
+			const base = openrouter.peek();
+			if (base === null) return null;
+			return { ...base, models: [...base.models, ...ollama.peek(), ...(bias.named?.models(base.models) ?? NO_NAMED)] };
+		},
 		lastShrink(): CatalogShrink | null {
 			return openrouter.lastShrink?.() ?? null;
 		},

package/src/lib.ts

@@ -28,4 +28,5 @@ export { createFeedbackStore, type FeedbackStore, type FeedbackRecord } from "./
 export { buildExecutable, collectPackageFiles, executableFileName, hostTarget, isExecutableTarget, EXECUTABLE_TARGETS, type ExecutableTarget, type BuildExecutableResult } from "./cli/build-executable.ts";
 export { parseSkillsBundle, type SkillsBundle } from "./cli/skills.ts";
 export type { RequestPolicy } from "./wire/types.ts";
+export type { CatalogView, CatalogViewModel } from "./server/catalog-view.ts";
 export type { Ledger, LedgerEntry } from "./cost/types.ts";

package/src/router/candidates.ts

@@ -48,12 +48,37 @@ export interface BuildCandidatesArgs {
 	excludeSlugs?: readonly string[];
 }
 
-/** Tiny glob: `*` matches any run of characters; everything else is literal. */
-function globToRe(glob: string): RegExp {
+/**
+ * Tiny glob: `*` matches any run of characters; everything else is literal.
+ * The one matcher behind `filters.allow`/`filters.deny` and a request
+ * policy's lists; the catalog view (`GET /v1/router/catalog`) judges with it
+ * too, so what a front door shows never drifts from what a turn gets.
+ */
+export function globToRe(glob: string): RegExp {
 	const escaped = glob.replace(/[.*+?^${}()|[\]\\]/g, (ch) => (ch === "*" ? ".*" : `\\${ch}`));
 	return new RegExp(`^${escaped}$`);
 }
 
+/**
+ * The denials that precede any user configuration, as the reason text, or
+ * null when the model may be a candidate. These slugs can never serve an
+ * interactive turn:
+ *  - "~vendor/model-latest": floating aliases whose identity changes
+ *    underneath us, poisoning ledger trust statistics.
+ *  - ":batch": asynchronous batch endpoints, unusable for streaming.
+ *  - "stealth/": cloaked models with no stable identity.
+ *  - "openrouter/": their meta-routers do our job at unknown cost.
+ *  - a negative price: OpenRouter's unknown/dynamic sentinel (-1), never a discount.
+ */
+export function builtInDenial(model: CatalogModel): string | null {
+	const slug = model.slug;
+	if (slug.startsWith("~") || slug.endsWith(":batch") || slug.startsWith("stealth/") || model.author === "openrouter") {
+		return "built-in deny: floating alias, batch endpoint, stealth, or meta-router";
+	}
+	if (model.price.prompt < 0 || model.price.completion < 0) return "dynamic pricing sentinel";
+	return null;
+}
+
 /**
  * Quality fallback chain: score the preferred axis first, then the general
  * intelligence index (the most widely published), then the remaining axis.
@@ -182,20 +207,10 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
-		// Hard-coded denials, before any user configuration. These slugs can
-		// never serve an interactive turn:
-		//  - "~vendor/model-latest": floating aliases whose identity changes
-		//    underneath us, poisoning ledger trust statistics.
-		//  - ":batch": asynchronous batch endpoints, unusable for streaming.
-		//  - "stealth/": cloaked models with no stable identity.
-		//  - "openrouter/": their meta-routers do our job at unknown cost.
-		if (slug.startsWith("~") || slug.endsWith(":batch") || slug.startsWith("stealth/") || model.author === "openrouter") {
-			rejected.push({ slug, reason: "denylisted", detail: "built-in deny: floating alias, batch endpoint, stealth, or meta-router" });
-			continue;
-		}
-		// A negative price is OpenRouter's unknown/dynamic sentinel (-1), never a discount.
-		if (model.price.prompt < 0 || model.price.completion < 0) {
-			rejected.push({ slug, reason: "denylisted", detail: "dynamic pricing sentinel" });
+		// Hard-coded denials, before any user configuration.
+		const builtIn = builtInDenial(model);
+		if (builtIn !== null) {
+			rejected.push({ slug, reason: "denylisted", detail: builtIn });
 			continue;
 		}
 		if (allowRes.length > 0 && !allowRes.some((re) => re.test(slug))) {

package/src/server/catalog-view.ts

@@ -0,0 +1,130 @@
+/**
+ * The router's model catalog as data, with a policy's verdict per model: what
+ * `GET /v1/router/catalog` answers. A team front door renders it for its
+ * governance views ("which models can this group reach, and why not the
+ * rest"), so admission is decided by the SAME matcher and in the SAME order
+ * as `buildCandidates` — the built-in denials, then allow, deny, free and
+ * tool support — over the filters `applyRequestPolicy` produced, and a pin
+ * takes effect only when the pinned model itself survives them, exactly as
+ * `select` treats a forced slug. Tiers are per turn and take no part.
+ */
+
+import type { CatalogModel, Modality, QualityScores } from "../catalog/types.ts";
+import type { FilterConfig } from "../config/types.ts";
+import { builtInDenial, globToRe } from "../router/candidates.ts";
+
+export interface CatalogViewModel {
+	slug: string;
+	canonicalSlug: string;
+	name: string;
+	/** The upstream that serves it: `openrouter`, `ollama`, or a named upstream's id. */
+	provider: string;
+	/**
+	 * The slug's namespace before the first `/` (`anthropic`). For a named
+	 * upstream's `<id>/<model>` the vendor is the model id's own namespace when
+	 * it carries one (`vllm/meta-llama/x` ⇒ `meta-llama`), else the upstream id.
+	 */
+	vendor: string;
+	contextLength: number;
+	maxCompletionTokens?: number;
+	supportsTools: boolean;
+	supportsReasoning: boolean;
+	reasoningMandatory: boolean;
+	inputModalities: Modality[];
+	/** USD per MILLION tokens, the catalog's own units. */
+	price: { prompt: number; completion: number; cacheRead?: number; cacheWrite?: number };
+	quality: QualityScores;
+	isFree: boolean;
+	/** Present only when a policy was asked about. */
+	admitted?: boolean;
+	/** Present only when not admitted: which filter kept the model out. */
+	reason?: string;
+}
+
+export interface CatalogView {
+	/** When the catalog was last fetched; 0 before the first fetch. */
+	fetchedAtMs: number;
+	/** Sorted by slug. */
+	models: CatalogViewModel[];
+}
+
+/** The filters a turn routes under: the configured ones, or those `applyRequestPolicy` merged a policy into. */
+export type AdmissionFilters = Pick<FilterConfig, "allow" | "deny" | "includeFree" | "requireToolSupport">;
+
+export interface CatalogViewArgs {
+	models: readonly CatalogModel[];
+	fetchedAtMs: number;
+	/** When given, every model carries `admitted` and, if out, `reason`. */
+	verdict?: { filters: AdmissionFilters; pin?: string };
+	/** Why a provider cannot take a turn now, or null when it can. */
+	unserved: (provider: string) => string | null;
+}
+
+/** Per-token catalog prices as USD per million, rounded so `0.22` does not come out as `0.22000000000000003`. */
+function perMillion(usdPerToken: number): number {
+	return Math.round(usdPerToken * 1e6 * 1e6) / 1e6;
+}
+
+export function vendorOf(model: Pick<CatalogModel, "slug" | "provider">): string {
+	const slash = model.slug.indexOf("/");
+	const head = slash === -1 ? model.slug : model.slug.slice(0, slash);
+	if (model.provider === "openrouter" || model.provider === "ollama" || head !== model.provider) return head;
+	const rest = model.slug.slice(slash + 1);
+	const inner = rest.indexOf("/");
+	return inner === -1 ? model.provider : rest.slice(0, inner);
+}
+
+/**
+ * Why the filters keep a model out, or null when it passes. The order is
+ * `buildCandidates`' so the first reason is the one a turn would record.
+ */
+function filterReason(model: CatalogModel, filters: AdmissionFilters, allowRes: readonly RegExp[], denyRes: readonly RegExp[]): string | null {
+	const builtIn = builtInDenial(model);
+	if (builtIn !== null) return builtIn;
+	if (allowRes.length > 0 && !allowRes.some((re) => re.test(model.slug))) return "not in the allow list";
+	const denied = denyRes.findIndex((re) => re.test(model.slug));
+	if (denied !== -1) return `denied by ${filters.deny[denied]}`;
+	if (model.isFree && !filters.includeFree) return "free models excluded (filters.includeFree)";
+	if (filters.requireToolSupport && !model.supportsTools) return "no tool support (filters.requireToolSupport)";
+	return null;
+}
+
+export function catalogView(args: CatalogViewArgs): CatalogView {
+	const sorted = [...args.models].sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+	const verdict = args.verdict;
+	const allowRes = verdict === undefined ? [] : verdict.filters.allow.map(globToRe);
+	const denyRes = verdict === undefined ? [] : verdict.filters.deny.map(globToRe);
+	// One reason per slug before the pin is considered: the pin only bites when
+	// the pinned model itself is in, as `select` ignores a pin the filters drop.
+	const reasons = new Map<string, string | null>();
+	if (verdict !== undefined) for (const m of sorted) reasons.set(m.slug, args.unserved(m.provider) ?? filterReason(m, verdict.filters, allowRes, denyRes));
+	const pin = verdict?.pin !== undefined && reasons.get(verdict.pin) === null ? verdict.pin : undefined;
+	const models = sorted.map((m): CatalogViewModel => {
+		const price: CatalogViewModel["price"] = { prompt: perMillion(m.price.prompt), completion: perMillion(m.price.completion) };
+		if (m.price.cacheRead !== undefined) price.cacheRead = perMillion(m.price.cacheRead);
+		if (m.price.cacheWrite !== undefined) price.cacheWrite = perMillion(m.price.cacheWrite);
+		const out: CatalogViewModel = {
+			slug: m.slug,
+			canonicalSlug: m.canonicalSlug,
+			name: m.name,
+			provider: m.provider,
+			vendor: vendorOf(m),
+			contextLength: m.contextLength,
+			...(m.maxCompletionTokens === undefined ? {} : { maxCompletionTokens: m.maxCompletionTokens }),
+			supportsTools: m.supportsTools,
+			supportsReasoning: m.supportsReasoning,
+			reasoningMandatory: m.reasoningMandatory,
+			inputModalities: [...m.inputModalities],
+			price,
+			quality: { ...m.quality },
+			isFree: m.isFree,
+		};
+		if (verdict !== undefined) {
+			const reason = reasons.get(m.slug) ?? (pin !== undefined && m.slug !== pin ? `pinned to ${pin}` : null);
+			out.admitted = reason === null;
+			if (reason !== null) out.reason = reason;
+		}
+		return out;
+	});
+	return { fetchedAtMs: args.fetchedAtMs, models };
+}

package/src/server/http.ts

@@ -6,6 +6,10 @@ import { createBridgeFromConfig } from "../context/index.ts";
 import { createFeedbackStore, type Verdict } from "../cost/feedback.ts";
 import { createLedger } from "../cost/ledger.ts";
 import { createSessionOverrides } from "./overrides.ts";
+import { catalogView } from "./catalog-view.ts";
+import { buildUpstreamModels } from "../catalog/static-catalog.ts";
+import { applyRequestPolicy, resolveProfile } from "../router/index.ts";
+import { parsePolicyHeader } from "../wire/openai/request.ts";
 import { createDigester } from "./digest.ts";
 import { advise } from "./advise.ts";
 import { TIER_ORDER, type Tier } from "../router/types.ts";
@@ -484,6 +488,40 @@ export function startServer(cfg: RouterConfig): StartedServer {
 				if (req.method === "GET" && url.pathname === "/v1/router/stats") {
 					return json(computeStats(ledger));
 				}
+				if (req.method === "GET" && url.pathname === "/v1/router/catalog") {
+					// The catalog as data, judged under `?policy=` (the X-Omp-Policy
+					// JSON) when one is given: a front door's governance view. Never
+					// blocks on a fetch; before the first one it is empty.
+					const rawPolicy = url.searchParams.get("policy");
+					let verdict: { filters: RouterConfig["filters"]; pin?: string } | undefined;
+					if (rawPolicy !== null) {
+						// The header parser forgives a malformed value (a turn must not
+						// fail on it); a view asked about one must say so instead.
+						let parsed: unknown;
+						try {
+							parsed = JSON.parse(rawPolicy);
+						} catch {
+							parsed = undefined;
+						}
+						if (parsed === undefined || parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+							return wireErrorResponse({ status: 400, code: "invalid_request_error", message: "policy must be a JSON object (the X-Omp-Policy shape)" });
+						}
+						const policed = applyRequestPolicy(resolveProfile(cfg, "auto"), cfg, parsePolicyHeader(rawPolicy), undefined);
+						verdict = { filters: policed.cfg.filters, ...(policed.forceSlug === undefined ? {} : { pin: policed.forceSlug }) };
+					}
+					const snap = catalog.peekAll?.() ?? catalog.peek();
+					// A disabled named upstream's models are not built for routing; list them too, so "why not" has an answer.
+					const disabled = snap === null ? [] : cfg.upstreams.filter((u) => !u.enabled).flatMap((u) => buildUpstreamModels(u, snap.models));
+					const unserved = (provider: string): string | null => {
+						if (provider === "openrouter") return cfg.openrouter.apiKey === "" ? "upstream openrouter has no API key" : null;
+						if (provider === "ollama") return !cfg.ollama.enabled ? "upstream ollama is disabled" : ollama.available() ? null : "upstream ollama is in cooldown";
+						const entry = cfg.upstreams.find((u) => u.id === provider);
+						if (entry === undefined) return `upstream ${provider} is not configured`;
+						if (!entry.enabled) return `upstream ${provider} is disabled`;
+						return providers.named(provider)?.available() ?? true ? null : `upstream ${provider} is in cooldown`;
+					};
+					return json(catalogView({ models: snap === null ? [] : [...snap.models, ...disabled], fetchedAtMs: snap?.fetchedAtMs ?? 0, ...(verdict === undefined ? {} : { verdict }), unserved }));
+				}
 				if (req.method === "GET" && url.pathname === "/v1/router/spend") {
 					// Spend since an instant over a harness set: what a front door's
 					// budget check needs when it cannot read the ledger file.

package/src/server/providers.ts

@@ -11,7 +11,7 @@ import { createAnthropicClient } from "../upstream/anthropic.ts";
 import { createCompatClient, type NamedUpstreamClient } from "../upstream/compat.ts";
 import { createOllamaCatalog } from "../catalog/ollama-catalog.ts";
 import { createCatalog } from "../catalog/openrouter-catalog.ts";
-import type { CatalogSource } from "../catalog/types.ts";
+import type { CatalogSnapshot, CatalogSource } from "../catalog/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { createMultiUpstream } from "../upstream/multi.ts";
 import { createOllamaClient, type OllamaClient } from "../upstream/ollama.ts";
@@ -24,7 +24,7 @@ import { createLogger, type Logger } from "../util/log.ts";
 
 export interface Providers {
 	upstream: UpstreamClient;
-	catalog: CatalogSource & { ollamaModels?(): unknown[]; ollamaBias?(): number };
+	catalog: CatalogSource & { ollamaModels?(): unknown[]; ollamaBias?(): number; peekAll?(): CatalogSnapshot | null };
 	/** Always present: it carries the circuit breaker. Whether it SERVES follows `cfg.ollama.enabled`. */
 	ollama: OllamaClient;
 	/** True while Ollama Cloud is enabled and out of cooldown, read live. */

package/test/catalog-view.test.ts

@@ -0,0 +1,249 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { normalizeCatalogModel } from "../src/catalog/openrouter-catalog.ts";
+import { buildUpstreamModels } from "../src/catalog/static-catalog.ts";
+import type { CatalogModel } from "../src/catalog/types.ts";
+import { DEFAULT_CONFIG } from "../src/config/defaults.ts";
+import { completeUpstreamEntry } from "../src/config/upstreams.ts";
+import { catalogView, vendorOf, type CatalogView, type CatalogViewModel } from "../src/server/catalog-view.ts";
+import { startServer, type StartedServer } from "../src/server/http.ts";
+import { openDb } from "../src/util/sqlite.ts";
+
+/**
+ * The catalog as data for a front door's governance views: every model the
+ * router knows, and under a policy whether a turn could reach it and why not.
+ * Pinned over the pure view and over `GET /v1/router/catalog`, which judges
+ * with the router's own matcher — the same globs, the same order as
+ * `buildCandidates`, a pin that only bites when the pinned model is in.
+ */
+
+const FIXTURE = (await Bun.file("test/fixtures/openrouter-models.json").json()) as { data: unknown[] };
+
+function model(over: Partial<CatalogModel> & { slug: string }): CatalogModel {
+	return {
+		provider: "openrouter",
+		canonicalSlug: `${over.slug}-20260101`,
+		name: over.slug,
+		contextLength: 200_000,
+		supportsTools: true,
+		supportsReasoning: false,
+		reasoningMandatory: false,
+		supportsToolChoice: true,
+		inputModalities: ["text"],
+		price: { prompt: 0.000003, completion: 0.000015 },
+		priceTiers: [],
+		quality: { intelligence: 60 },
+		tokenizer: "Claude",
+		isFree: false,
+		createdAtMs: 0,
+		author: over.slug.split("/")[0] ?? "",
+		...over,
+	};
+}
+
+const vllm = completeUpstreamEntry({ id: "vllm", kind: "openai", baseUrl: "http://vllm:8000/v1", apiKey: "", models: [{ id: "meta-llama/Llama-3", input: 0, output: 0, contextLength: 8_000 }] });
+const azure = completeUpstreamEntry({ id: "azure-eu", kind: "azure", enabled: false, baseUrl: "https://r.openai.azure.com", apiKey: "k", models: [{ id: "gpt-4o-deploy", input: 2.5, output: 10, cachedInput: 1.25 }] });
+
+const MODELS: CatalogModel[] = [
+	model({ slug: "openai/gpt-5", quality: { intelligence: 70, coding: 72 }, maxCompletionTokens: 128_000, price: { prompt: 0.00000125, completion: 0.00001, cacheRead: 0.000000125 } }),
+	model({ slug: "anthropic/claude-sonnet-5", supportsReasoning: true }),
+	model({ slug: "anthropic/claude-haiku-5" }),
+	model({ slug: "anthropic/claude-opus-5:batch" }),
+	model({ slug: "liquid/lfm:free", isFree: true, price: { prompt: 0, completion: 0 } }),
+	model({ slug: "tencent/translator", supportsTools: false }),
+	model({ slug: "ollama/glm-5.3-flash", provider: "ollama", author: "ollama" }),
+	...buildUpstreamModels(vllm, []),
+	...buildUpstreamModels(azure, []),
+];
+
+const served = () => null;
+const bySlug = (view: CatalogView): Map<string, CatalogViewModel> => new Map(view.models.map((m) => [m.slug, m]));
+
+describe("catalogView", () => {
+	test("sorted by slug, prices per million, vendor per slug, and no verdict without a policy", () => {
+		const view = catalogView({ models: MODELS, fetchedAtMs: 123, unserved: served });
+		expect(view.fetchedAtMs).toBe(123);
+		expect(view.models.map((m) => m.slug)).toEqual([...MODELS.map((m) => m.slug)].sort());
+		const gpt = bySlug(view).get("openai/gpt-5")!;
+		expect(gpt).toEqual({
+			slug: "openai/gpt-5",
+			canonicalSlug: "openai/gpt-5-20260101",
+			name: "openai/gpt-5",
+			provider: "openrouter",
+			vendor: "openai",
+			contextLength: 200_000,
+			maxCompletionTokens: 128_000,
+			supportsTools: true,
+			supportsReasoning: false,
+			reasoningMandatory: false,
+			inputModalities: ["text"],
+			price: { prompt: 1.25, completion: 10, cacheRead: 0.125 },
+			quality: { intelligence: 70, coding: 72 },
+			isFree: false,
+		});
+		expect("admitted" in gpt).toBe(false);
+		expect("reason" in gpt).toBe(false);
+		expect("maxCompletionTokens" in bySlug(view).get("anthropic/claude-haiku-5")!).toBe(false);
+		// A named upstream's prices are per million already; they round-trip.
+		expect(bySlug(view).get("azure-eu/gpt-4o-deploy")!.price).toEqual({ prompt: 2.5, completion: 10, cacheRead: 1.25 });
+	});
+
+	test("vendor: the namespace before the first slash; a named upstream's model id may carry its own", () => {
+		expect(vendorOf({ slug: "anthropic/claude-sonnet-5", provider: "openrouter" })).toBe("anthropic");
+		expect(vendorOf({ slug: "ollama/glm-5.3-flash", provider: "ollama" })).toBe("ollama");
+		expect(vendorOf({ slug: "vllm/meta-llama/Llama-3", provider: "vllm" })).toBe("meta-llama");
+		expect(vendorOf({ slug: "azure-eu/gpt-4o-deploy", provider: "azure-eu" })).toBe("azure-eu");
+		const view = bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, unserved: served }));
+		expect(view.get("vllm/meta-llama/Llama-3")!.vendor).toBe("meta-llama");
+		expect(view.get("azure-eu/gpt-4o-deploy")!.vendor).toBe("azure-eu");
+	});
+
+	test("an empty policy still judges: the router's own filters and the upstream's state", () => {
+		const unserved = (p: string) => (p === "azure-eu" ? "upstream azure-eu is disabled" : null);
+		const view = bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, verdict: { filters: DEFAULT_CONFIG.filters }, unserved }));
+		expect(view.get("openai/gpt-5")).toMatchObject({ admitted: true });
+		expect("reason" in view.get("openai/gpt-5")!).toBe(false);
+		expect(view.get("anthropic/claude-opus-5:batch")).toMatchObject({ admitted: false, reason: "built-in deny: floating alias, batch endpoint, stealth, or meta-router" });
+		expect(view.get("liquid/lfm:free")).toMatchObject({ admitted: false, reason: "free models excluded (filters.includeFree)" });
+		expect(view.get("tencent/translator")).toMatchObject({ admitted: false, reason: "no tool support (filters.requireToolSupport)" });
+		expect(view.get("azure-eu/gpt-4o-deploy")).toMatchObject({ admitted: false, reason: "upstream azure-eu is disabled" });
+		// A $0 named-upstream model is self-hosted, never "free".
+		expect(view.get("vllm/meta-llama/Llama-3")).toMatchObject({ admitted: true });
+		// Filters relaxed: the same models come in.
+		const open = bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, verdict: { filters: { ...DEFAULT_CONFIG.filters, includeFree: true, requireToolSupport: false } }, unserved: served }));
+		expect(open.get("liquid/lfm:free")!.admitted).toBe(true);
+		expect(open.get("tencent/translator")!.admitted).toBe(true);
+	});
+
+	test("allow list, deny glob and pin, in the order a turn applies them", () => {
+		const filters = { ...DEFAULT_CONFIG.filters, allow: ["anthropic/*", "vllm/*"], deny: ["*haiku*"] };
+		const view = bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, verdict: { filters }, unserved: served }));
+		expect(view.get("openai/gpt-5")).toMatchObject({ admitted: false, reason: "not in the allow list" });
+		expect(view.get("anthropic/claude-haiku-5")).toMatchObject({ admitted: false, reason: "denied by *haiku*" });
+		expect(view.get("anthropic/claude-sonnet-5")).toMatchObject({ admitted: true });
+		expect(view.get("vllm/meta-llama/Llama-3")).toMatchObject({ admitted: true });
+		// A pin keeps every other model out.
+		const pinned = bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, verdict: { filters, pin: "anthropic/claude-sonnet-5" }, unserved: served }));
+		expect(pinned.get("anthropic/claude-sonnet-5")).toMatchObject({ admitted: true });
+		expect(pinned.get("vllm/meta-llama/Llama-3")).toMatchObject({ admitted: false, reason: "pinned to anthropic/claude-sonnet-5" });
+		expect(pinned.get("openai/gpt-5")).toMatchObject({ admitted: false, reason: "not in the allow list" }); // the earlier reason stands
+		// A pin the filters drop is ignored, as select ignores it: nothing else is pinned out.
+		const dropped = bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, verdict: { filters, pin: "anthropic/claude-haiku-5" }, unserved: served }));
+		expect(dropped.get("anthropic/claude-haiku-5")).toMatchObject({ admitted: false, reason: "denied by *haiku*" });
+		expect(dropped.get("anthropic/claude-sonnet-5")).toMatchObject({ admitted: true });
+		// So is a pin naming no model.
+		expect(bySlug(catalogView({ models: MODELS, fetchedAtMs: 0, verdict: { filters, pin: "nobody/here" }, unserved: served })).get("anthropic/claude-sonnet-5")!.admitted).toBe(true);
+	});
+});
+
+describe("GET /v1/router/catalog", () => {
+	let handle: StartedServer;
+	let empty: StartedServer;
+	const dir = mkdtempSync(join(tmpdir(), "amr-catalog-"));
+	const FETCHED = Date.now() - 60_000;
+	beforeAll(() => {
+		const cfg = structuredClone(DEFAULT_CONFIG);
+		cfg.server.host = "127.0.0.1";
+		cfg.server.port = 0;
+		cfg.server.apiKey = "k";
+		cfg.logLevel = "silent";
+		// Nothing reaches the network: the catalog is served from its on-disk
+		// cache (within TTL), the periodic refresh is off, and the base URL is dead.
+		cfg.openrouter.apiKey = "sk-test";
+		cfg.openrouter.baseUrl = "http://127.0.0.1:9/api/v1";
+		cfg.openrouter.catalogRefreshMs = 0;
+		cfg.benchmarks.enabled = false;
+		cfg.upstreams = [vllm, azure];
+		cfg.ledger.path = join(dir, "router.db");
+		const db = openDb(cfg.ledger.path);
+		db.run("INSERT INTO catalog_cache (id, payload, fetched_at_ms, etag, key_scoped) VALUES (1, ?, ?, NULL, 0)", [JSON.stringify(FIXTURE.data), FETCHED]);
+		db.close();
+		handle = startServer(cfg);
+		const bare = structuredClone(cfg);
+		bare.upstreams = [];
+		bare.ledger.path = join(dir, "empty.db");
+		empty = startServer(bare);
+	});
+	afterAll(async () => {
+		await handle.stop();
+		await empty.stop();
+		try {
+			rmSync(dir, { recursive: true, force: true });
+		} catch {
+			/* Windows may hold the WAL briefly */
+		}
+	});
+	const get = (path: string, port = handle.server.port) => fetch(`http://127.0.0.1:${port}${path}`, { headers: { authorization: "Bearer k" } });
+	const view = async (path: string): Promise<Map<string, CatalogViewModel>> => bySlug((await (await get(path)).json()) as CatalogView);
+
+	test("the catalog as data: authenticated, sorted, every upstream's models, no verdict without a policy", async () => {
+		expect((await fetch(`http://127.0.0.1:${handle.server.port}/v1/router/catalog`)).status).toBe(401);
+		const res = await get("/v1/router/catalog");
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as CatalogView;
+		expect(body.fetchedAtMs).toBe(FETCHED);
+		const slugs = body.models.map((m) => m.slug);
+		expect(slugs).toEqual([...slugs].sort());
+		// Every OpenRouter model the fixture normalises to, plus both named upstreams' — the disabled one too.
+		expect(slugs).toHaveLength(FIXTURE.data.filter((m) => normalizeCatalogModel(m) !== null).length + 2);
+		const models = bySlug(body);
+		const opus = models.get("anthropic/claude-opus-5")!;
+		const raw = normalizeCatalogModel(FIXTURE.data.find((m) => (m as { id: string }).id === "anthropic/claude-opus-5"))!;
+		expect(opus).toEqual({
+			slug: "anthropic/claude-opus-5",
+			canonicalSlug: raw.canonicalSlug,
+			name: raw.name,
+			provider: "openrouter",
+			vendor: "anthropic",
+			contextLength: raw.contextLength,
+			maxCompletionTokens: 128_000,
+			supportsTools: true,
+			supportsReasoning: raw.supportsReasoning,
+			reasoningMandatory: raw.reasoningMandatory,
+			inputModalities: raw.inputModalities,
+			price: { prompt: 5, completion: raw.price.completion * 1e6, cacheRead: 0.5, ...(raw.price.cacheWrite === undefined ? {} : { cacheWrite: raw.price.cacheWrite * 1e6 }) },
+			quality: raw.quality,
+			isFree: false,
+		});
+		expect(models.get("vllm/meta-llama/Llama-3")).toMatchObject({ provider: "vllm", vendor: "meta-llama", contextLength: 8_000 });
+		expect(models.get("azure-eu/gpt-4o-deploy")).toMatchObject({ provider: "azure-eu", vendor: "azure-eu", price: { prompt: 2.5, completion: 10, cacheRead: 1.25 } });
+		expect(body.models.some((m) => "admitted" in m || "reason" in m)).toBe(false);
+	});
+
+	test("judged under a policy: allow, deny, pin, the router's filters and the upstream's state", async () => {
+		const allowed = await view(`/v1/router/catalog?policy=${encodeURIComponent(JSON.stringify({ allow: ["anthropic/*", "azure-eu/*"], deny: ["anthropic/claude-opus-5"], maxTier: "simple" }))}`);
+		expect(allowed.get("anthropic/claude-sonnet-4.5")).toMatchObject({ admitted: true });
+		expect(allowed.get("anthropic/claude-opus-5")).toMatchObject({ admitted: false, reason: "denied by anthropic/claude-opus-5" });
+		expect(allowed.get("anthropic/claude-opus-5:batch")).toMatchObject({ admitted: false, reason: "built-in deny: floating alias, batch endpoint, stealth, or meta-router" });
+		expect(allowed.get("openai/gpt-5.6-luna")).toMatchObject({ admitted: false, reason: "not in the allow list" });
+		expect(allowed.get("azure-eu/gpt-4o-deploy")).toMatchObject({ admitted: false, reason: "upstream azure-eu is disabled" });
+		// The configured deny list stays in force under a policy's, as applyRequestPolicy adds rather than replaces.
+		const pinned = await view(`/v1/router/catalog?policy=${encodeURIComponent(JSON.stringify({ pin: "vllm/meta-llama/Llama-3" }))}`);
+		expect(pinned.get("vllm/meta-llama/Llama-3")).toMatchObject({ admitted: true });
+		expect(pinned.get("anthropic/claude-sonnet-4.5")).toMatchObject({ admitted: false, reason: "pinned to vllm/meta-llama/Llama-3" });
+		expect(pinned.get("tencent/hy-mt2-1.8b")).toMatchObject({ admitted: false, reason: "no tool support (filters.requireToolSupport)" });
+		expect(pinned.get("liquid/lfm-2.5-2.6b:free")).toMatchObject({ admitted: false, reason: "free models excluded (filters.includeFree)" });
+		// `{}` is a policy too: every model carries a verdict.
+		const plain = await view("/v1/router/catalog?policy=%7B%7D");
+		expect(plain.get("anthropic/claude-sonnet-4.5")).toMatchObject({ admitted: true });
+		expect([...plain.values()].every((m) => typeof m.admitted === "boolean")).toBe(true);
+	});
+
+	test("a malformed policy is a 400 in the wire error shape", async () => {
+		for (const bad of ["%7B", "not-json", "%5B%5D", "null", "1"]) {
+			const res = await get(`/v1/router/catalog?policy=${bad}`);
+			expect(res.status).toBe(400);
+			const body = (await res.json()) as { error: { message: string; type: string; code: string } };
+			expect(body.error.code).toBe("invalid_request_error");
+			expect(body.error.message).toContain("policy");
+		}
+	});
+
+	test("before the first fetch: empty, never a wait", async () => {
+		expect((await (await get("/v1/router/catalog", empty.server.port)).json()) as CatalogView).toEqual({ fetchedAtMs: 0, models: [] });
+		expect((await (await get("/v1/router/catalog?policy=%7B%7D", empty.server.port)).json()) as CatalogView).toEqual({ fetchedAtMs: 0, models: [] });
+	});
+});