champollion-mcp-server 0.1.0

package/src/tools/languages.js

@@ -0,0 +1,329 @@
+/**
+ * Language tools — search and browse Champollion language cards.
+ *
+ * Card data comes from ONE of three sources, tried in order:
+ *   1. CHAMPOLLION_CARDS_DIR — explicit override (same variable the CLI and
+ *      the Python harness honor). Set-but-unusable is an immediate error:
+ *      the user pointed somewhere specific, and silently reading a different
+ *      corpus would be worse than failing.
+ *   2. The monorepo checkout's cli/shared/language-cards/ (full corpus).
+ *   3. The champollion package's bundled shared/cards-fallback.json — the
+ *      same bundle the published CLI runs on: 1,157 full cards plus a
+ *      manifest of every concrete code → name/aliases, so the FULL catalogue
+ *      is searchable by name offline, with rich fields on the core set and
+ *      honest absences elsewhere.
+ *
+ * NOTHING is hardcoded and nothing degrades silently. This file used to
+ * carry a hand-written 40-language FALLBACK_INDEX served with only a stderr
+ * note — an agent outside the repo was told "No languages found" for ~7,887
+ * real languages, indistinguishable from an authoritative answer (and the
+ * published install crashed before even reaching it, because the adapter
+ * import was a static repo-relative path). When no source resolves, the
+ * server now REFUSES TO START, listing every path tried and the fix — the
+ * same posture as translate.js's "refusing to start with an empty or
+ * hand-guessed method surface". With `champollion` a real dependency, a
+ * missing card surface always means a broken install, never a legitimate
+ * degraded mode.
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const require = createRequire(import.meta.url);
+
+// Monorepo layout: mcp-server/src/tools/ → repo root is three up.
+const REPO_CLI = resolve(__dirname, '../../../cli');
+
+/**
+ * Resolve the ONE card adapter (cli/lib/cards/reader.js), monorepo checkout
+ * first so development never resolves a stale registry install, then the
+ * `champollion` dependency for published installs. A ninth private reader is
+ * how this server came to serve "[object Object]" — the adapter is not
+ * optional, so failing to find it is a startup error, not a fallback.
+ *
+ * @returns {Promise<{reader: object, packageRoot: string, source: string}>}
+ */
+async function resolveAdapter() {
+  const attempts = [];
+
+  const repoReader = resolve(REPO_CLI, 'lib/cards/reader.js');
+  if (existsSync(repoReader)) {
+    const reader = await import(pathToFileURL(repoReader).href);
+    return { reader, packageRoot: REPO_CLI, source: 'monorepo checkout' };
+  }
+  attempts.push(`${repoReader} (monorepo checkout — not present)`);
+
+  try {
+    const entry = require.resolve('champollion');
+    const reader = await import('champollion');
+    return {
+      reader,
+      packageRoot: dirname(entry),
+      source: 'champollion package',
+    };
+  } catch (err) {
+    attempts.push(`champollion package (${err.code ?? err.message})`);
+  }
+
+  throw new Error(
+    'Cannot resolve the champollion card adapter — refusing to start with no '
+    + 'card surface. Tried:\n'
+    + attempts.map((a) => `  - ${a}`).join('\n')
+    + '\nFix: run inside the Champollion monorepo, or `npm install` in the '
+    + 'MCP server directory so the `champollion` dependency is present.',
+  );
+}
+
+/** One index entry from a full (normalized) card. */
+function entryFromCard(card, { display, isDisputed }) {
+  // Speaker estimates: ONE claim answers as itself; several claims answer as
+  // the DISAGREEMENT, every value shown. Taking estimates[0] silently elected
+  // ELCat's British-Columbia-only count as Plains Cree's total — 'speakers:
+  // 10-99' on the flagship card, which is exactly the pick-a-winner move the
+  // card boundary forbids.
+  const claims = Array.isArray(card.speakerEstimates) ? card.speakerEstimates : [];
+  const counts = [...new Set(claims.map((e) => e?.count).filter((c) => c != null && c !== ''))];
+  const speakers = card.vitality?.speakerCount
+    || (counts.length === 1 ? counts[0]
+      : counts.length > 1 ? `${counts.join(' / ')} (sources differ)` : '');
+  const fam = card.classification?.family;
+  return {
+    code: card.code || card.iso639_3 || card.bcp47 || '',
+    name: card.name || '',
+    endonym: card.nativeName || card.endonym || '',
+    // display() yields the agreed value and nothing on a real dispute —
+    // but 'disputed' and 'unknown' are different claims, so a genuine
+    // disagreement says so instead of reading as ignorance.
+    family: display(fam) || (isDisputed?.(fam) ? 'disputed' : ''),
+    speakers,
+    script: card.script || (Array.isArray(card.scripts) ? card.scripts[0] : '') || '',
+    region: card.macroarea || '',
+    typology: card.typologicalProfile?.verbSynthesis
+      || card.typologicalProfile?.morphologicalSynthesis || '',
+    // Documented alternate names so a language is findable by ANY of its
+    // names — the same alias set the Atlas searches.
+    aliases: [
+      ...(Array.isArray(card.alternateNames) ? card.alternateNames : []),
+      ...(Array.isArray(card.aliases) ? card.aliases : []),
+    ],
+    // Keep the full card for detailed lookups
+    _raw: card,
+  };
+}
+
+/** Build the index from a language-cards directory (full corpus). */
+async function indexFromDir(dir, ctx) {
+  const { normalizeCard } = ctx;
+  const files = await readdir(dir);
+  const jsonFiles = files.filter((f) => f.endsWith('.json') && !f.startsWith('.'));
+
+  const index = [];
+  const cards = await Promise.allSettled(
+    jsonFiles.map(async (f) => {
+      const raw = await readFile(join(dir, f), 'utf-8');
+      // THROUGH THE ONE ADAPTER, like every other consumer.
+      return normalizeCard(JSON.parse(raw));
+    }),
+  );
+
+  for (const result of cards) {
+    if (result.status !== 'fulfilled') continue;
+    const card = result.value;
+    // The cards dir also holds generated reference files (language-tree.json)
+    // that are not cards — a card always carries a code and a name.
+    if (!(card.code || card.iso639_3 || card.bcp47) || !card.name) continue;
+    // A LOCALE IS NOT A LANGUAGE: fra-CA carries French's name and facts;
+    // indexing the 8,675 locale cards would return one language a dozen
+    // times for one query.
+    if (card.locale?.language) continue;
+    index.push(entryFromCard(card, ctx));
+  }
+  return index;
+}
+
+/**
+ * Build the index from the CLI's bundled cards-fallback.json: full entries
+ * for the ~1,157 bundled core cards, lean name/alias entries for every other
+ * concrete language in the manifest. Lean entries answer "does Champollion
+ * know this language, and by what name" honestly — with empty strings, never
+ * invented facts — and the full card remains fetchable through the CLI.
+ */
+async function indexFromFallbackFile(file, ctx) {
+  const { normalizeCard } = ctx;
+  const bundle = JSON.parse(await readFile(file, 'utf-8'));
+  const index = [];
+  const seen = new Set();
+
+  for (const raw of Object.values(bundle.cards ?? {})) {
+    const card = normalizeCard(raw);
+    if (!(card.code || card.iso639_3 || card.bcp47) || !card.name) continue;
+    // The bundle deliberately carries locale-variant cards (fra-CA,
+    // cmn-Hant) for the CLI's resolution needs; a language index excludes
+    // them by locale block AND by dashed code — some variant cards predate
+    // the locale block.
+    if (card.locale?.language) continue;
+    const entry = entryFromCard(card, ctx);
+    if (entry.code.includes('-')) continue;
+    index.push(entry);
+    seen.add(entry.code);
+  }
+  const parents = new Set(Object.keys(bundle.parents ?? {}));
+  for (const [code, m] of Object.entries(bundle.manifest ?? {})) {
+    if (seen.has(code) || parents.has(code)) continue;
+    // Dashed codes are locale projections (fra-CA) — not languages. (This
+    // also skips the x-* constructed-script variants; their base cards are
+    // in the bundled core set.)
+    if (code.includes('-')) continue;
+    if (!m?.n) continue;
+    index.push({
+      code,
+      name: m.n,
+      endonym: '',
+      family: '',
+      speakers: '',
+      script: '',
+      region: '',
+      typology: '',
+      aliases: Array.isArray(m.a) ? m.a : [],
+    });
+  }
+  return index;
+}
+
+/**
+ * Load the language index. Resolution ladder in the module docstring; every
+ * miss is recorded and a total miss THROWS with the full list — startup is
+ * the right place to fail, because index.js awaits this before the MCP
+ * handshake and a server that starts without languages would answer
+ * "No languages found" as if it were a fact about the world.
+ *
+ * @param {object} [opts]  Test injection: `cardsDir` (strict, same semantics
+ *   as CHAMPOLLION_CARDS_DIR), `fallbackFile`, `repoDir` (override the
+ *   monorepo candidate).
+ * @returns {Promise<object[]>}  Language index array
+ */
+export async function loadLanguageIndex(opts = {}) {
+  const { reader, packageRoot, source } = await resolveAdapter();
+  const { normalizeCard, display, isDisputed } = reader;
+  const adapterCtx = { normalizeCard, display, isDisputed };
+  const attempts = [];
+
+  // Tier 1 — explicit override: obey it or fail, never fall past it.
+  const explicit = opts.cardsDir ?? process.env.CHAMPOLLION_CARDS_DIR;
+  if (explicit) {
+    const label = opts.cardsDir ? 'cardsDir option' : 'CHAMPOLLION_CARDS_DIR';
+    let index;
+    try {
+      index = await indexFromDir(explicit, adapterCtx);
+    } catch (err) {
+      throw new Error(
+        `${label} points at ${explicit}, which is not a readable card `
+        + `directory (${err.code ?? err.message}). The override names a `
+        + 'specific corpus; silently reading a different one would be worse '
+        + 'than failing.',
+      );
+    }
+    if (index.length === 0) {
+      throw new Error(
+        `${label} points at ${explicit}, which contains no language cards — `
+        + 'a broken corpus, not a missing one.',
+      );
+    }
+    process.stderr.write(`Loaded ${index.length} language cards from ${explicit} (${label})\n`);
+    return index;
+  }
+
+  // Tier 2 — the monorepo's full corpus.
+  const repoDir = opts.repoDir ?? resolve(REPO_CLI, 'shared/language-cards');
+  if (existsSync(repoDir)) {
+    const index = await indexFromDir(repoDir, adapterCtx);
+    if (index.length === 0) {
+      throw new Error(
+        `${repoDir} exists but contains no language cards — a broken corpus `
+        + '(a half-applied cutover?), not a missing one. Rebuild the cards or '
+        + 'set CHAMPOLLION_CARDS_DIR.',
+      );
+    }
+    process.stderr.write(`Loaded ${index.length} language cards from ${repoDir}\n`);
+    return index;
+  }
+  attempts.push(`${repoDir} (monorepo corpus — not present)`);
+
+  // Tier 3 — the champollion package's bundled fallback.
+  const fallbackFile = opts.fallbackFile
+    ?? process.env.CHAMPOLLION_CARDS_FALLBACK
+    ?? join(packageRoot, 'shared', 'cards-fallback.json');
+  if (existsSync(fallbackFile)) {
+    const index = await indexFromFallbackFile(fallbackFile, adapterCtx);
+    if (index.length === 0) {
+      throw new Error(
+        `${fallbackFile} parsed but yielded no language entries — a broken `
+        + 'bundle, not a missing one.',
+      );
+    }
+    process.stderr.write(
+      `Loaded ${index.length} languages from the bundled fallback ${fallbackFile}\n`,
+    );
+    return index;
+  }
+  attempts.push(`${fallbackFile} (bundled cards-fallback.json — not present)`);
+
+  throw new Error(
+    'No language-card source resolved — refusing to start with an empty or '
+    + `hand-guessed language surface (adapter came from the ${source}). Tried:\n`
+    + attempts.map((a) => `  - ${a}`).join('\n')
+    + '\nFix: set CHAMPOLLION_CARDS_DIR to a language-cards directory, run '
+    + 'inside the Champollion monorepo, or reinstall so the champollion '
+    + "dependency's bundled cards ship intact.",
+  );
+}
+
+/**
+ * Search the language index for matches against a query string.
+ *
+ * Matches against: code, name, endonym, family, region.
+ * Case-insensitive substring match, ranked: exact code match first, then
+ * exact name/endonym, then name-prefix, then everything else in file order.
+ *
+ * @param {object[]} index   Language index from loadLanguageIndex()
+ * @param {string}   query   Search term
+ * @param {number}   limit   Max results
+ * @returns {object[]}       Matching languages
+ */
+export function searchLanguages(index, query, limit = 10) {
+  const q = query.toLowerCase();
+  const tiers = [[], [], [], []];
+
+  for (const lang of index) {
+    const aliases = Array.isArray(lang.aliases) ? lang.aliases : [];
+    const searchable = [
+      lang.code, lang.name, lang.endonym, lang.family,
+      lang.region, lang.typology, ...aliases,
+    ].filter(Boolean).join(' ').toLowerCase();
+
+    if (!searchable.includes(q)) continue;
+
+    if (lang.code && lang.code.toLowerCase() === q) {
+      tiers[0].push(lang);
+    } else if (
+      (lang.name && lang.name.toLowerCase() === q) ||
+      (lang.endonym && lang.endonym.toLowerCase() === q) ||
+      aliases.some((a) => a.toLowerCase() === q)
+    ) {
+      tiers[1].push(lang);
+    } else if (lang.name && lang.name.toLowerCase().startsWith(q)) {
+      tiers[2].push(lang);
+    } else {
+      tiers[3].push(lang);
+    }
+
+    // Enough candidates to fill the limit from the best tiers alone.
+    if (tiers[0].length >= limit) break;
+  }
+
+  return tiers.flat().slice(0, limit);
+}

package/src/tools/queue.js

@@ -0,0 +1,313 @@
+/**
+ * Queue tools — fetch, filter, and inspect the Champollion sweep queue.
+ *
+ * Data source (default): the live queue served from Postgres via the queue_top
+ * RPC — a ranked list of (corpus, model, condition) items, coverage-filtered
+ * against VERIFIED runs, so nothing stale or already-done is shown. Items are
+ * paged from the RPC; metadata comes from the small queue-preview.json. If the
+ * DB is unreachable, fetchQueue falls back to the full static queue.json blob,
+ * so the tools never break. Set CHAMPOLLION_QUEUE_SOURCE=blob to force the blob.
+ * An in-memory CACHE_TTL_MS cache avoids re-fetching on every tool call.
+ */
+
+const QUEUE_URL = 'https://champollion.dev/queue.json';
+// DB-as-queue (B1): the live queue is served from Postgres (the queue_top RPC),
+// coverage-filtered against VERIFIED runs, so items are never stale. Metadata
+// (open_items, models, priority_model, cost_basis, how_to_run) comes from the
+// small queue-preview.json companion. The full static blob remains the FALLBACK
+// so this tool never breaks if the DB is unreachable.
+const PREVIEW_URL = 'https://champollion.dev/queue-preview.json';
+const SUPABASE_URL = process.env.MT_EVAL_SUPABASE_URL
+  || 'https://sjdomynysdljkbemupqa.supabase.co';
+const SUPABASE_ANON_KEY = process.env.MT_EVAL_SUPABASE_ANON_KEY
+  || 'sb_publishable_bV6CFNFnzxhQI0wlBx2J0A_5Vm5gFBp';
+const QUEUE_TOP_PAGE = 500; // matches the RPC's hard page cap
+// 'db' (default) serves live from queue_top with a blob fallback; 'blob' forces
+// the legacy static file (used by the existing fetch tests).
+const QUEUE_SOURCE = process.env.CHAMPOLLION_QUEUE_SOURCE || 'db';
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+// Served item fields (what queue.json publishes / consumers rely on). queue_top
+// rows also carry rank_mode/map_value/diagnostics/generation_id/generated_at —
+// projected away so DB-sourced items match the blob shape exactly.
+const SERVED_FIELDS = [
+  'priority', 'id', 'language_pair', 'source_language', 'target_language',
+  'corpus_id', 'corpus_license', 'entry_count', 'contamination', 'domain',
+  'source_length', 'model', 'condition', 'est_cost_usd', 'est_basis',
+  'run_command',
+];
+
+let _cache = null;
+let _cacheTime = 0;
+
+/**
+ * Fetch the queue, returning the cached version if still fresh.
+ *
+ * The static host can serve an HTML holding page with HTTP 200 (site gated,
+ * maintenance, CDN error page) — `resp.json()` would then surface a raw
+ * `SyntaxError: Unexpected token '<'` to every queue-backed tool (list_queue,
+ * get_queue_item, estimate_cost, get_project_info, and run_benchmark's item
+ * lookup all relay err.message verbatim). The body is therefore read as text
+ * and parsed here, so a non-JSON response becomes ONE clean, user-facing
+ * error at this shared choke point. Failures are never cached — the next
+ * call re-fetches.
+ *
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetchImpl]  Injectable fetch (for tests).
+ * @returns {Promise<{ metadata: object, items: object[] }>}
+ */
+export async function fetchQueue({ fetchImpl = fetch, source = QUEUE_SOURCE } = {}) {
+  const now = Date.now();
+  if (_cache && (now - _cacheTime) < CACHE_TTL_MS) {
+    return _cache;
+  }
+
+  let data;
+  if (source === 'blob') {
+    data = await fetchQueueFromBlob(fetchImpl);
+  } else {
+    // Live DB path with a graceful fallback: a DB/preview failure must never
+    // take the tool down when the static blob is still being served.
+    try {
+      data = await fetchQueueFromDb(fetchImpl);
+    } catch {
+      data = await fetchQueueFromBlob(fetchImpl);
+    }
+  }
+
+  _cache = data;
+  _cacheTime = now;
+  return data;
+}
+
+/** Serve the live queue from Postgres: items from the queue_top RPC (paged,
+ *  coverage-filtered against verified runs), metadata from queue-preview.json.
+ *  Throws on any failure so fetchQueue can fall back to the static blob. */
+async function fetchQueueFromDb(fetchImpl) {
+  // Metadata + preview from the companion file (a few hundred KB — ~292 KB
+  // as of 2026-08; it grows with the queue, so never assume it is tiny).
+  const pResp = await fetchImpl(PREVIEW_URL, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!pResp.ok) throw new Error(`preview HTTP ${pResp.status}`);
+  const preview = JSON.parse(await pResp.text());
+  const metadata = preview?.metadata;
+  if (metadata === null || typeof metadata !== 'object') {
+    throw new Error('queue-preview.json missing metadata');
+  }
+  const rankMode = metadata.rank_mode || 'map';
+
+  // Page through the RPC until a short page signals the end.
+  const items = [];
+  for (let offset = 0; ; offset += QUEUE_TOP_PAGE) {
+    const resp = await fetchImpl(`${SUPABASE_URL}/rest/v1/rpc/queue_top`, {
+      method: 'POST',
+      headers: {
+        'apikey': SUPABASE_ANON_KEY,
+        'Authorization': `Bearer ${SUPABASE_ANON_KEY}`,
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+      body: JSON.stringify({
+        p_rank_mode: rankMode, p_limit: QUEUE_TOP_PAGE, p_offset: offset,
+      }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!resp.ok) throw new Error(`queue_top HTTP ${resp.status}`);
+    const page = JSON.parse(await resp.text());
+    if (!Array.isArray(page)) throw new Error('queue_top did not return an array');
+    for (const row of page) {
+      const item = {};
+      for (const f of SERVED_FIELDS) if (row[f] !== undefined) item[f] = row[f];
+      // The restricted-corpus `transmission` stamp is a SERVED extra on
+      // queue.json but not a queue_items COLUMN — the ranker writes it into
+      // the diagnostics JSONB. Projecting columns alone dropped it from every
+      // DB-served item, so agents pulling work through MCP lost the no-train
+      // channel requirement the blob discloses. Lift it back.
+      const stamp = row.diagnostics?.transmission;
+      if (stamp && typeof stamp === 'object' && stamp.policy) item.transmission = stamp;
+      items.push(item);
+    }
+    if (page.length < QUEUE_TOP_PAGE) break;
+  }
+
+  // open_items reflects the LIVE served count, not the last generation's stat.
+  return { metadata: { ...metadata, open_items: items.length }, items };
+}
+
+/** The legacy path: the full static queue.json blob. Also the DB-path fallback. */
+async function fetchQueueFromBlob(fetchImpl) {
+  const resp = await fetchImpl(QUEUE_URL, {
+    headers: { 'Accept': 'application/json' },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!resp.ok) {
+    throw new Error(`Queue fetch failed: HTTP ${resp.status}`);
+  }
+
+  const body = await resp.text();
+  let data;
+  try {
+    data = JSON.parse(body);
+  } catch {
+    const contentType = resp.headers?.get?.('content-type') || 'unknown content-type';
+    throw new Error(
+      'the Champollion queue endpoint is not serving JSON — the site may be '
+      + `gated or down (got ${contentType} from ${QUEUE_URL}). `
+      + 'Try again later, or check https://champollion.dev.',
+    );
+  }
+  // Parsed, but not a queue: a gate/deploy step could serve a JSON error
+  // object with HTTP 200. Fail cleanly here rather than crashing downstream
+  // in filterQueue with a raw TypeError.
+  if (data === null || typeof data !== 'object'
+      || !Array.isArray(data.items)
+      || data.metadata === null || typeof data.metadata !== 'object') {
+    throw new Error(
+      'the Champollion queue endpoint returned JSON without the expected '
+      + '{ metadata, items } queue shape — the site may be gated or '
+      + 'mid-deploy. Try again later, or check https://champollion.dev.',
+    );
+  }
+
+  return data;
+}
+
+/** Clear the in-memory queue cache. For test isolation. */
+export function resetQueueCache() {
+  _cache = null;
+  _cacheTime = 0;
+}
+
+/**
+ * Filter queue items by language, model, budget, and condition.
+ *
+ * Core selection follows the same rules as queue_runner.py select_items:
+ *   - Items are walked in queue order (the ranking IS the priority)
+ *   - Budget mode: only items whose est_cost fits entirely within
+ *     the remaining budget are selected
+ *   - Items without cost estimates are skipped in budget mode
+ *   - Coached items are included only when condition='coached'
+ *
+ * This function adds language/model/source_language filters on top
+ * of the core selection logic (those are MCP-only features).
+ *
+ * SSOT: Canonical implementation is arena/mt_eval_harness/queue_runner.py.
+ * Both are tested against shared/queue-selection-vectors.json — if you
+ * change core selection behavior here, update the vectors and run both
+ * test suites (npm test + pytest).
+ *
+ * @param {object[]} items      All queue items (already sorted by priority)
+ * @param {object}   filters    Filter options
+ * @returns {object[]}          Filtered items
+ */
+export function filterQueue(items, {
+  budget = null,
+  language = null,
+  source_language = null,
+  model = null,
+  condition = null,
+  limit = 20,
+} = {}) {
+  const selected = [];
+  let spend = 0;
+
+  // Normalize filter strings for case-insensitive matching
+  const langLower = language?.toLowerCase();
+  const modelLower = model?.toLowerCase();
+  const srcLower = source_language?.toLowerCase();
+
+  for (const item of items) {
+    if (selected.length >= limit) break;
+
+    // --- Condition filter ---
+    // Skip coached items unless explicitly requested (mirrors queue_runner.py)
+    if (condition) {
+      if (item.condition !== condition) continue;
+    } else if (item.condition === 'coached') {
+      continue;
+    }
+
+    // --- Language filter ---
+    // Matches against target_language name or the target side of the pair code
+    if (langLower) {
+      const targetCode = item.language_pair?.split('>')[1] || '';
+      const targetName = (item.target_language || '').toLowerCase();
+      if (!targetName.includes(langLower) && !targetCode.includes(langLower)) {
+        continue;
+      }
+    }
+
+    // --- Source language filter ---
+    if (srcLower) {
+      const sourceCode = item.language_pair?.split('>')[0] || '';
+      if (sourceCode.toLowerCase() !== srcLower) continue;
+    }
+
+    // --- Model filter ---
+    if (modelLower) {
+      const itemModel = (item.model || '').toLowerCase();
+      if (!itemModel.includes(modelLower)) continue;
+    }
+
+    // --- Budget filter ---
+    if (budget != null) {
+      const est = item.est_cost_usd;
+      if (est == null) continue; // unknown cost — skip in budget mode
+      if (spend + est > budget) continue; // would exceed budget
+      spend += est;
+    }
+
+    selected.push(item);
+  }
+
+  return selected;
+}
+
+/**
+ * Look up a single queue item by ID or priority rank.
+ *
+ * @param {object[]} items     All queue items
+ * @param {{ id?: string, priority?: number }} lookup
+ * @returns {object|null}      The matching item, or null
+ */
+export function getQueueItem(items, { id, priority }) {
+  if (id) {
+    return items.find(it => it.id === id) || null;
+  }
+  if (priority != null) {
+    return items.find(it => it.priority === priority) || null;
+  }
+  return null;
+}
+
+/**
+ * Estimate cost for a set of queue items matching the given filters.
+ *
+ * Returns aggregate statistics without executing anything.
+ *
+ * @param {object[]} items     All queue items
+ * @param {object}   filters   Same filters as filterQueue
+ * @returns {{ count, totalCost, cheapest, mostExpensive, languages }}
+ */
+export function estimateCost(items, filters) {
+  // Use a high limit to get all matching items for cost estimation
+  // Hard cap so a broad filter can't blow up the response; callers see
+  // `capped` and must not read `count` as the queue-wide total.
+  const ESTIMATE_CAP = 500;
+  const matched = filterQueue(items, { ...filters, limit: ESTIMATE_CAP });
+  const costs = matched
+    .map(it => it.est_cost_usd)
+    .filter(c => c != null);
+  const languages = [...new Set(matched.map(it => it.target_language))];
+
+  return {
+    count: matched.length,
+    capped: matched.length >= ESTIMATE_CAP,
+    totalCost: costs.reduce((s, c) => s + c, 0),
+    cheapest: costs.length ? Math.min(...costs) : 0,
+    mostExpensive: costs.length ? Math.max(...costs) : 0,
+    languages,
+  };
+}