catherd-cli 1.1.1 → 1.2.1

package/src/infra/sources/arena.ts

@@ -0,0 +1,87 @@
+import { effortWord } from "../../domain/sources.ts";
+import { type SourceTransport, sourceGet } from "./http.ts";
+import { isoDay, num, type SourceRow } from "./rows.ts";
+
+/** Spec 1.2 §3.1: the Agent Arena boards and WebDev (CC-BY-4.0). */
+export const ARENA_CONFIGS = [
+  "agent",
+  "agent_task_outcome_explicit",
+  "agent_bash_recovery_steps",
+  "agent_steerability",
+  "agent_tool_hallucination",
+  "webdev",
+] as const;
+export type ArenaConfig = (typeof ARENA_CONFIGS)[number];
+
+export const ARENA_PAGE = "https://huggingface.co/datasets/lmarena-ai/leaderboard-dataset";
+
+export const arenaUrl = (config: ArenaConfig): string =>
+  `https://datasets-server.huggingface.co/rows?dataset=lmarena-ai/leaderboard-dataset&config=${config}&split=latest&length=100`;
+
+/** Every config, in parallel; one failure fails the source, which keeps its last answer. */
+export async function fetchArena(t: SourceTransport = {}): Promise<Record<ArenaConfig, unknown>> {
+  const got = await Promise.all(
+    ARENA_CONFIGS.map(async (c) => [c, (await sourceGet(arenaUrl(c), t)).json()]),
+  );
+  return Object.fromEntries(got) as Record<ArenaConfig, unknown>;
+}
+
+/**
+ * Spec 1.2 §3.4: an Arena model name as `<name>#<effort>`: the effort from a `(Max)`/`(xHigh)`/`(High)`
+ * suffix, or from a trailing `-max`/`-xhigh`/`-high` (WebDev's ids). A harness note such as
+ * `(codex-harness)` is dropped; any other parenthesis stays part of the name.
+ */
+export function arenaRung(name: string): string {
+  let rest = name.replace(/\s*\([^()]*harness\)/gi, "").trim();
+  let effort: string | null = null;
+  rest = rest
+    .replace(/\s*\(([^()]*)\)/g, (whole, inner: string) => {
+      const e = effort === null ? effortWord(inner) : null;
+      if (e === null) return whole;
+      effort = e;
+      return "";
+    })
+    .trim();
+  if (effort === null) {
+    const m = /^(.*)-([A-Za-z]+)$/.exec(rest);
+    const e = m ? effortWord(m[2] as string) : null;
+    if (m && e) {
+      effort = e;
+      rest = m[1] as string;
+    }
+  }
+  return effort === null ? rest : `${rest}#${effort}`;
+}
+
+interface ArenaRow {
+  model_name?: unknown;
+  score?: unknown;
+  rating?: unknown;
+  leaderboard_publish_date?: unknown;
+}
+
+/**
+ * One row per model and config: `field` is the config, `value` the agent boards' `score` (net improvement) or
+ * WebDev's `rating`, dated by the board's publish date.
+ */
+export function parseArena(raw: Record<string, unknown>, fetchedAt: string): SourceRow[] {
+  const rows: SourceRow[] = [];
+  for (const config of ARENA_CONFIGS) {
+    const list = (raw[config] as { rows?: { row?: ArenaRow }[] } | undefined)?.rows;
+    if (!Array.isArray(list)) continue;
+    for (const { row } of list) {
+      if (!row || typeof row.model_name !== "string") continue;
+      const value = num(config === "webdev" ? row.rating : row.score);
+      if (value === null) continue;
+      const published = typeof row.leaderboard_publish_date === "string" ? row.leaderboard_publish_date : "";
+      rows.push({
+        rung: arenaRung(row.model_name),
+        field: config,
+        value,
+        date: /^\d{4}-\d{2}-\d{2}$/.test(published) ? published : isoDay(fetchedAt),
+        url: ARENA_PAGE,
+      });
+    }
+  }
+  return rows;
+}

package/src/infra/sources/artificial-analysis.ts

@@ -0,0 +1,112 @@
+import { effortWord } from "../../domain/sources.ts";
+import { rateLimitRemaining, SourceError, type SourceTransport, sourceGet } from "./http.ts";
+import { isoDay, num, type SourceRow } from "./rows.ts";
+
+/** Spec 1.2 §3.1: the legacy v2 route a free key reads today, one row per effort. */
+export const AA_MODELS_URL = "https://artificialanalysis.ai/api/v2/data/llms/models";
+/** Spec 1.2 §3.1: the fallback when the first path answers 403 or 404, a page at a time. */
+export const aaFreeUrl = (page: number): string =>
+  `https://artificialanalysis.ai/api/v2/language/models/free?page=${page}`;
+export const AA_PAGE = "https://artificialanalysis.ai";
+/** The free path had 4 pages on 2026-09-27; this bounds a runaway pagination. */
+const MAX_FREE_PAGES = 10;
+
+/** What catherd caches for Artificial Analysis: the path that answered, each page, the requests left. */
+export interface AaAnswer {
+  path: "models" | "free";
+  pages: unknown[];
+  rateLimitRemaining: number | null;
+}
+
+/**
+ * Spec 1.2 §3.1: the models path with the user's key; on a 403 or 404 there, the free path's pages until an
+ * empty page or the last one. Throws a SourceError (carrying the last answer's headers) on any other failure.
+ */
+export async function fetchArtificialAnalysis(key: string, t: SourceTransport = {}): Promise<AaAnswer> {
+  const o = { ...t, headers: { "x-api-key": key } };
+  try {
+    const r = await sourceGet(AA_MODELS_URL, o);
+    return { path: "models", pages: [r.json()], rateLimitRemaining: rateLimitRemaining(r.headers) };
+  } catch (e) {
+    if (!(e instanceof SourceError) || (e.status !== 403 && e.status !== 404)) throw e;
+  }
+  const pages: unknown[] = [];
+  let remaining: number | null = null;
+  for (let page = 1; page <= MAX_FREE_PAGES; page++) {
+    const r = await sourceGet(aaFreeUrl(page), o);
+    remaining = rateLimitRemaining(r.headers) ?? remaining;
+    const body = r.json() as { data?: unknown; pagination?: { total_pages?: unknown } } | null;
+    if (!Array.isArray(body?.data) || body.data.length === 0) break;
+    pages.push(body);
+    const total = num(body.pagination?.total_pages);
+    if (total !== null && page >= total) break;
+  }
+  return { path: "free", pages, rateLimitRemaining: remaining };
+}
+
+/**
+ * Spec 1.2 §9: tests a key with one request to the free path's first page. `ok` on a 200, `refused` on a 401;
+ * anything else (a network error, a 5xx) leaves the key `unchecked`.
+ */
+export async function testAaKey(
+  key: string,
+  t: SourceTransport = {},
+): Promise<{ result: "ok" | "refused" | "unchecked"; error?: string; rateLimitRemaining: number | null }> {
+  try {
+    const r = await sourceGet(aaFreeUrl(1), {
+      attemptMs: 10_000,
+      deadlineMs: 20_000,
+      ...t,
+      headers: { "x-api-key": key },
+    });
+    return { result: "ok", rateLimitRemaining: rateLimitRemaining(r.headers) };
+  } catch (e) {
+    const err = e instanceof SourceError ? e : new SourceError(String(e));
+    return {
+      result: err.status === 401 ? "refused" : "unchecked",
+      error: err.message,
+      rateLimitRemaining: rateLimitRemaining(err.headers),
+    };
+  }
+}
+
+/** Spec 1.2 §3.4: an AA slug as `<id>#<effort>`: its effort suffix, and `max` for a bare slug. */
+export function aaRung(slug: string): string {
+  const m = /^(.*)-([a-z]+)$/.exec(slug);
+  const effort = m ? effortWord(m[2] as string) : null;
+  return m && effort ? `${m[1]}#${effort}` : `${slug}#max`;
+}
+
+const TOP = [
+  "median_output_tokens_per_second",
+  "median_time_to_first_token_seconds",
+  "cost_per_task",
+] as const;
+
+/**
+ * One row per slug and number: every evaluation (`livecodebench`, `terminalbench_v2_1`, the indexes, …), every
+ * price, speed and `cost_per_task`, named as AA names them. Nulls are left out.
+ */
+export function parseArtificialAnalysis(answer: AaAnswer, fetchedAt: string): SourceRow[] {
+  const rows: SourceRow[] = [];
+  const date = isoDay(fetchedAt);
+  for (const page of answer.pages) {
+    const data = (page as { data?: unknown } | null)?.data;
+    if (!Array.isArray(data)) continue;
+    for (const m of data as Record<string, unknown>[]) {
+      if (typeof m?.slug !== "string") continue;
+      const rung = aaRung(m.slug);
+      const url = `${AA_PAGE}/models/${m.slug}`;
+      const push = (field: string, v: unknown) => {
+        const value = num(v);
+        if (value !== null) rows.push({ rung, field, value, date, url });
+      };
+      for (const group of ["evaluations", "pricing"] as const) {
+        const g = m[group];
+        if (g && typeof g === "object") for (const [field, v] of Object.entries(g)) push(field, v);
+      }
+      for (const field of TOP) push(field, m[field]);
+    }
+  }
+  return rows;
+}

package/src/infra/sources/cache.ts

@@ -0,0 +1,124 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { errorMessage } from "../../domain/errors.ts";
+import { type Derived, DerivedSchema, type SourceId } from "../../domain/sources.ts";
+import { tryLock } from "../filelock.ts";
+import { log } from "../log.ts";
+import { sourcesDir } from "../paths.ts";
+import { ensurePrivateDir, readVersioned, writeJsonAtomic, writeTextAtomic } from "../store.ts";
+
+// Spec 1.2 §3.3: `<data>/sources/<source>.json` holds a source's last good answer with its fetch time; a
+// failed fetch never touches it. `state.json` holds each source's last attempt and error.
+
+export const cachePath = (id: SourceId): string => join(sourcesDir(), `${id}.json`);
+
+const CachedSchema = z.looseObject({
+  schema: z.literal(1),
+  source: z.string(),
+  fetchedAt: z.iso.datetime(),
+  /** the answer as fetched (Epoch: the CSV tables catherd reads out of its zip) */
+  data: z.unknown(),
+  meta: z.record(z.string(), z.unknown()).default({}),
+});
+export type Cached = z.infer<typeof CachedSchema>;
+
+/** A source's last good answer; null when there is none, or when it cannot be read (the next sync rewrites it). */
+export function readCached(id: SourceId): Cached | null {
+  const file = cachePath(id);
+  if (!existsSync(file)) return null;
+  try {
+    return readVersioned(file, CachedSchema, 1);
+  } catch (e) {
+    log("debug", "sources", { source: id, error: errorMessage(e) });
+    return null;
+  }
+}
+
+/** Writes a source's answer atomically (mode 600), compact: models.dev alone is 5 MB. */
+export function writeCached(
+  id: SourceId,
+  data: unknown,
+  fetchedAt: number,
+  meta: Record<string, unknown> = {},
+): Cached {
+  const c: Cached = { schema: 1, source: id, fetchedAt: new Date(fetchedAt).toISOString(), data, meta };
+  writeTextAtomic(cachePath(id), `${JSON.stringify(c)}\n`);
+  return c;
+}
+
+const StateSchema = z.looseObject({
+  schema: z.literal(1),
+  sources: z
+    .record(
+      z.string(),
+      z.looseObject({
+        /** when the cached answer was fetched (its TTL runs from here); null before a first success */
+        fetchedAt: z.iso.datetime().nullable().default(null),
+        lastAttemptAt: z.iso.datetime(),
+        error: z.string().nullable(),
+        /** Artificial Analysis: `x-ratelimit-remaining` of its last answer */
+        rateLimitRemaining: z.number().nullable().default(null),
+      }),
+    )
+    .default({}),
+});
+export type SyncState = z.infer<typeof StateSchema>;
+
+export const statePath = (): string => join(sourcesDir(), "state.json");
+
+/** Each source's last attempt; empty when never synced or unreadable. */
+export function readSyncState(): SyncState {
+  const empty: SyncState = { schema: 1, sources: {} };
+  if (!existsSync(statePath())) return empty;
+  try {
+    return readVersioned(statePath(), StateSchema, 1);
+  } catch (e) {
+    log("debug", "sources", { state: errorMessage(e) });
+    return empty;
+  }
+}
+
+export const writeSyncState = (s: SyncState): void => writeJsonAtomic(statePath(), s);
+
+/** Spec 1.2 §3.2: one sync at a time on this machine. Its release, or null while another live process syncs. */
+export function tryLockSync(): (() => void) | null {
+  ensurePrivateDir(sourcesDir());
+  return tryLock(join(sourcesDir(), "sync"));
+}
+
+export const derivedPath = (): string => join(sourcesDir(), "derived.json");
+/** Spec 1.2 §4.2: every fit with its R², used or not. */
+export const calibrationPath = (): string => join(sourcesDir(), "calibration.json");
+
+let memo: { mtimeMs: number; size: number; file: string; derived: Derived | null } | null = null;
+
+/**
+ * What the last sync derived; null when never synced or unreadable (routing then reads the shipped values
+ * alone). Read on every catalog load, so it is parsed again only when the file changes.
+ */
+export function readDerived(): Derived | null {
+  const file = derivedPath();
+  let st: { mtimeMs: number; size: number };
+  try {
+    st = statSync(file);
+  } catch {
+    return null;
+  }
+  if (memo?.file === file && memo.mtimeMs === st.mtimeMs && memo.size === st.size) return memo.derived;
+  let derived: Derived | null = null;
+  try {
+    derived = readVersioned(file, DerivedSchema, 1);
+  } catch (e) {
+    log("debug", "sources", { derived: errorMessage(e) });
+  }
+  memo = { file, mtimeMs: st.mtimeMs, size: st.size, derived };
+  return derived;
+}
+
+/** Writes derived.json and calibration.json atomically. */
+export function writeDerived(d: Derived): void {
+  memo = null;
+  writeTextAtomic(derivedPath(), `${JSON.stringify(d)}\n`);
+  writeJsonAtomic(calibrationPath(), { schema: 1, builtAt: d.builtAt, fits: d.fits });
+}

package/src/infra/sources/csv.ts

@@ -0,0 +1,38 @@
+/**
+ * RFC 4180 CSV as one object per row, keyed by the header row: quoted fields may hold commas, `""` and line
+ * breaks (Epoch's notes do); CRLF and LF both end a row; blank lines are skipped.
+ */
+export function parseCsv(text: string): Record<string, string>[] {
+  const records: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i] as string;
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') {
+        field += '"';
+        i++;
+      } else if (ch === '"') quoted = false;
+      else field += ch;
+    } else if (ch === '"') quoted = true;
+    else if (ch === ",") {
+      row.push(field);
+      field = "";
+    } else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      row.push(field);
+      records.push(row);
+      row = [];
+      field = "";
+    } else field += ch;
+  }
+  if (field !== "" || row.length) {
+    row.push(field);
+    records.push(row);
+  }
+  const rows = records.filter((r) => r.some((c) => c !== ""));
+  const [header, ...body] = rows;
+  if (!header) return [];
+  return body.map((r) => Object.fromEntries(header.map((h, i) => [h, r[i] ?? ""])));
+}

package/src/infra/sources/epoch.ts

@@ -0,0 +1,82 @@
+import { effortWord } from "../../domain/sources.ts";
+import { parseCsv } from "./csv.ts";
+import { SourceError, type SourceTransport, sourceGet } from "./http.ts";
+import { isoDay, keepHighest, num, type SourceRow, urlOr } from "./rows.ts";
+import { unzip } from "./zip.ts";
+
+/** Spec 1.2 §3.1: one CSV per benchmark in a zip (CC-BY; external tables keep their own license). */
+export const EPOCH_URL = "https://epoch.ai/data/benchmark_data.zip";
+export const EPOCH_PAGE = "https://epoch.ai/benchmarks";
+
+/**
+ * The tables catherd reads, by field: the file, its score column, whether that score is a fraction (read in
+ * percent, as the shipped values are), and the column that dates a row, if any.
+ */
+export const EPOCH_TABLES = {
+  frontiercode: { file: "frontiercode_external.csv", score: "Main score", fraction: true, dated: null },
+  terminalbench: {
+    file: "terminalbench_external.csv",
+    score: "Accuracy mean",
+    fraction: true,
+    dated: "Run date",
+  },
+  webdev: { file: "webdev_arena_external.csv", score: "Arena Score", fraction: false, dated: "Last updated" },
+} as const;
+type EpochField = keyof typeof EPOCH_TABLES;
+const FIELDS = Object.keys(EPOCH_TABLES) as EpochField[];
+
+/** The zip's tables catherd reads, by file name (the answer catherd caches); a missing one fails the source. */
+export async function fetchEpoch(t: SourceTransport = {}): Promise<Record<string, string>> {
+  const r = await sourceGet(EPOCH_URL, t);
+  const wanted = new Set<string>(FIELDS.map((f) => EPOCH_TABLES[f].file));
+  let files: Map<string, Uint8Array>;
+  try {
+    files = unzip(r.bytes, (name) => wanted.has(name));
+  } catch (e) {
+    throw new SourceError(`the answer is not a readable zip: ${(e as Error).message}`, r.status);
+  }
+  const out: Record<string, string> = {};
+  for (const name of wanted) {
+    const data = files.get(name);
+    if (!data) throw new SourceError(`the zip has no ${name}`, r.status);
+    out[name] = new TextDecoder().decode(data);
+  }
+  return out;
+}
+
+/**
+ * Spec 1.2 §3.4: Epoch's `Model version` as `<id>#<effort>`: the effort after the last `_` (`gpt-6-astra_max`),
+ * else the row's `Reasoning effort` column; `_unknown` and suffixes that are not efforts (`_32K`) name none.
+ */
+export function epochRung(version: string, effortColumn = ""): string {
+  const cut = version.lastIndexOf("_");
+  const id = cut < 0 ? version : version.slice(0, cut);
+  const effort = (cut < 0 ? null : effortWord(version.slice(cut + 1))) ?? effortWord(effortColumn);
+  return effort ? `${id}#${effort}` : id;
+}
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+/** One row per model and table, the highest where a model has several (Terminal-Bench: one per agent). */
+export function parseEpoch(tables: Record<string, string>, fetchedAt: string): SourceRow[] {
+  const rows: SourceRow[] = [];
+  for (const field of FIELDS) {
+    const t = EPOCH_TABLES[field];
+    const text = tables[t.file];
+    if (typeof text !== "string") continue;
+    for (const r of parseCsv(text)) {
+      const version = (r["Model version"] ?? "").trim();
+      const raw = num(r[t.score]);
+      if (!version || raw === null) continue;
+      const dated = t.dated ? (r[t.dated] ?? "").trim() : "";
+      rows.push({
+        rung: epochRung(version, r["Reasoning effort"] ?? ""),
+        field,
+        value: t.fraction ? Math.round(raw * 1e6) / 1e4 : raw,
+        date: DAY.test(dated) ? dated : isoDay(fetchedAt),
+        url: urlOr(r.Source, urlOr(r["Source Link"] ?? r["Source link (site from table)"], EPOCH_PAGE)),
+      });
+    }
+  }
+  return keepHighest(rows);
+}

package/src/infra/sources/http.ts

@@ -0,0 +1,75 @@
+import { type JevTransport, retryingFetch } from "../jev-client.ts";
+import { VERSION } from "../version.ts";
+
+/** How a source is fetched; tests replace `fetchImpl` and the clock, so no test reaches the network. */
+export type SourceTransport = JevTransport;
+
+/** A source request that failed: the error, and the status and headers of the last answer when there was one. */
+export class SourceError extends Error {
+  constructor(
+    message: string,
+    readonly status: number | null = null,
+    readonly headers: Headers | null = null,
+  ) {
+    super(message);
+    this.name = "SourceError";
+  }
+}
+
+export interface SourceResponse {
+  status: number;
+  headers: Headers;
+  bytes: Uint8Array;
+  text(): string;
+  /** the body as JSON; a SourceError when it is not */
+  json(): unknown;
+}
+
+/** Spec 1.2 §3.3: one timeout per source; the big files (models.dev, LiteLLM, Epoch) need more than Jev's 10 s. */
+const ATTEMPT_MS = 30_000;
+const DEADLINE_MS = 60_000;
+
+/**
+ * Spec 1.2 §3.3: GET `url` with the Jev client's retry policy and the source's own timeout (30 s an attempt,
+ * 60 s in all, unless the transport says otherwise). Throws a SourceError on any failure.
+ */
+export async function sourceGet(
+  url: string,
+  o: SourceTransport & { headers?: Record<string, string> } = {},
+): Promise<SourceResponse> {
+  const { headers = {}, ...t } = o;
+  const r = await retryingFetch(
+    url,
+    {
+      method: "GET",
+      headers: () => ({
+        "user-agent": `catherd-cli/${VERSION} (+https://github.com/47vigen/catherd)`,
+        ...headers,
+      }),
+    },
+    { attemptMs: ATTEMPT_MS, deadlineMs: DEADLINE_MS, ...t },
+  );
+  if (!r.ok) throw new SourceError(r.error, r.status, r.headers);
+  const { bytes, status } = r;
+  const text = () => new TextDecoder().decode(bytes);
+  return {
+    status,
+    headers: r.headers,
+    bytes,
+    text,
+    json() {
+      try {
+        return JSON.parse(text());
+      } catch {
+        throw new SourceError("unexpected response (not JSON)", status, r.headers);
+      }
+    },
+  };
+}
+
+/** `x-ratelimit-remaining` of an answer, when it has one (Artificial Analysis, spec 1.2 §9). */
+export function rateLimitRemaining(h: Headers | null): number | null {
+  const raw = h?.get("x-ratelimit-remaining")?.trim();
+  const v = raw ? Number(raw) : Number.NaN;
+  return Number.isFinite(v) ? v : null;
+}

package/src/infra/sources/litellm.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { type SourceTransport, sourceGet } from "./http.ts";
+import { perMillion } from "./openrouter-models.ts";
+import { num } from "./rows.ts";
+
+/** Spec 1.2 §3.1: price and effort support, a cross-check only (MIT). */
+export const LITELLM_URL =
+  "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+
+export const fetchLiteLlm = async (t: SourceTransport = {}): Promise<unknown> =>
+  (await sourceGet(LITELLM_URL, t)).json();
+
+/** The efforts LiteLLM flags per model (`supports_<effort>_reasoning_effort`). */
+export const LITELLM_EFFORTS = ["none", "minimal", "low", "xhigh", "max"] as const;
+
+export interface LiteLlmModel {
+  id: string;
+  provider: string;
+  /** dollars per million tokens */
+  price: { input: number; output: number; cached: number | null } | null;
+  context: number | null;
+  /** effort → whether LiteLLM says the model supports it; absent when it does not say */
+  efforts: Partial<Record<(typeof LITELLM_EFFORTS)[number], boolean>>;
+}
+
+/** Spec 1.2 §3.5: the vendors' own APIs, whose prices the catalog's are. */
+const FIRST_PARTY = new Set(["openai", "anthropic"]);
+
+const EntrySchema = z.looseObject({ litellm_provider: z.string() });
+
+/** The first-party entries of LiteLLM's price file: an OpenAI or Anthropic provider, a key with no `/`. */
+export function parseLiteLlm(raw: unknown): LiteLlmModel[] {
+  if (!raw || typeof raw !== "object") return [];
+  const out: LiteLlmModel[] = [];
+  for (const [id, v] of Object.entries(raw as Record<string, unknown>)) {
+    const e = EntrySchema.safeParse(v);
+    if (!e.success || !FIRST_PARTY.has(e.data.litellm_provider) || id.includes("/")) continue;
+    const entry = e.data as Record<string, unknown>;
+    const input = perMillion(entry.input_cost_per_token);
+    const output = perMillion(entry.output_cost_per_token);
+    const efforts: LiteLlmModel["efforts"] = {};
+    for (const effort of LITELLM_EFFORTS) {
+      const flag = entry[`supports_${effort}_reasoning_effort`];
+      if (typeof flag === "boolean") efforts[effort] = flag;
+    }
+    out.push({
+      id,
+      provider: e.data.litellm_provider,
+      price:
+        input !== null && output !== null
+          ? { input, output, cached: perMillion(entry.cache_read_input_token_cost) }
+          : null,
+      context: num(entry.max_input_tokens),
+      efforts,
+    });
+  }
+  return out;
+}

package/src/infra/sources/models-dev.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { type SourceTransport, sourceGet } from "./http.ts";
+import { num } from "./rows.ts";
+
+/** Spec 1.2 §3.1: efforts, context, output limit, price, tool calling, modalities, release date (MIT). */
+export const MODELS_DEV_URL = "https://models.dev/api.json";
+
+export const fetchModelsDev = async (t: SourceTransport = {}): Promise<unknown> =>
+  (await sourceGet(MODELS_DEV_URL, t)).json();
+
+/** What catherd reads of one models.dev model; each field null when the source does not say. */
+export interface ModelFacts {
+  efforts: string[] | null;
+  context: number | null;
+  output: number | null;
+  /** dollars per million tokens */
+  price: { input: number; cached: number; output: number } | null;
+  toolUse: boolean | null;
+  imageIn: boolean | null;
+  reasoning: boolean | null;
+  releaseDate: string | null;
+}
+
+const ModelSchema = z.looseObject({
+  reasoning: z.boolean().optional(),
+  reasoning_options: z
+    .array(z.looseObject({ type: z.string(), values: z.array(z.string()).optional() }))
+    .optional(),
+  tool_call: z.boolean().optional(),
+  release_date: z.string().optional(),
+  modalities: z.looseObject({ input: z.array(z.string()).optional() }).optional(),
+  limit: z.looseObject({ context: z.unknown(), output: z.unknown() }).optional(),
+  cost: z.looseObject({ input: z.unknown(), output: z.unknown(), cache_read: z.unknown() }).optional(),
+});
+
+/**
+ * Spec 1.2 §3.5: `provider`'s model `id` in models.dev's api.json (a provider id such as `openai` or
+ * `opencode-go`, and the model id within it); null when absent or unreadable.
+ */
+export function modelsDevFacts(raw: unknown, provider: string, id: string): ModelFacts | null {
+  const p = (raw as Record<string, { models?: Record<string, unknown> }> | null)?.[provider];
+  const parsed = ModelSchema.safeParse(p?.models?.[id]);
+  if (!parsed.success) return null;
+  const m = parsed.data;
+  const efforts = m.reasoning_options?.find((o) => o.type === "effort")?.values ?? null;
+  const input = num(m.cost?.input);
+  const output = num(m.cost?.output);
+  return {
+    efforts,
+    context: num(m.limit?.context),
+    output: num(m.limit?.output),
+    price:
+      input !== null && output !== null ? { input, cached: num(m.cost?.cache_read) ?? input, output } : null,
+    toolUse: m.tool_call ?? null,
+    imageIn: m.modalities?.input ? m.modalities.input.includes("image") : null,
+    reasoning: m.reasoning ?? null,
+    releaseDate: m.release_date ?? null,
+  };
+}