@guenbankhai/tools 0.0.0-stage → 0.1.0

package/agentmoni/lib/agents/codex/index.js

@@ -0,0 +1,280 @@
+// Codex adapter: rollout files under ~/.codex/sessions and archived_sessions.
+const os = require('node:os');
+const path = require('node:path');
+const { files, scan, cached } = require('../../jsonl.js');
+const fs = require('node:fs');
+const { launchKind, launchOf, launchCwd, resultJob, resultSessions } = require('../../launch.js');
+const { readBilling } = require('./billing.js');
+const declaration = require('../../catalog.json').agents.codex;
+
+const codexHome = () => process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+const WANT = ['"type":"session_meta"', '"type":"turn_context"', '"type":"task_started"', '"type":"task_complete', '"type":"turn_aborted"',
+  '"type":"token_usage_record"', '"type":"token_count"', '"type":"user_message"', '"type":"thread_settings_applied"', '"role":"user"'];
+// Tool results are many and large: parse only those that can carry a launch job id.
+const wantLine = l => WANT.some(w => l.includes(w)) || (l.includes('"function_call_output"') && (l.includes('task-') || l.includes('session_id'))) || l.includes('"function_call"') || l.includes('"custom_tool_call"');
+const validUsage = u => u && typeof u === 'object' &&
+  ['input_tokens', 'output_tokens'].every(k => Number.isSafeInteger(u[k]) && u[k] >= 0) &&
+  ['cached_input_tokens', 'cache_write_input_tokens', 'reasoning_output_tokens', 'total_tokens'].every(k => u[k] === undefined || (Number.isSafeInteger(u[k]) && u[k] >= 0)) &&
+  (u.cached_input_tokens ?? 0) <= u.input_tokens;
+// Injected context ("<...>" tags, the AGENTS.md preamble) is not what the user typed.
+const clip = text => typeof text === 'string' && !/^\s*(<|# AGENTS\.md)/.test(text) ? text.replace(/\s+/g, ' ').trim().slice(0, 80) || null : null;
+const firstText = content => Array.isArray(content) ? content.find(c => typeof c?.text === 'string')?.text : null;
+
+function parseRollout(file) {
+  const s = { provider: 'codex', id: path.basename(file, '.jsonl'), parentId: null, model: null, effort: null, cwd: null, name: null,
+    startedAt: null, lastActivityAt: null, kind: 'main', tokens: null, context: null, turn: null, launches: [], usage: [], billing: 'unknown', source: { file } };
+  const records = [], fallback = [];
+  let hasRecords = false, previousTotal;
+  const seen = new Set(), calls = new Map();
+  let historyStart = null, skipping = false, fallbackName = null;
+  function addUsage(u, at, entries, costUSD) {
+    if (!validUsage(u) || !Number.isFinite(at)) return false;
+    const cached = u.cached_input_tokens ?? 0;
+    entries.push({ at, model: s.model, tokens: { input: u.input_tokens - cached, cacheRead: cached,
+      cacheWrite: u.cache_write_input_tokens ?? null, output: u.output_tokens },
+      ...(Number.isFinite(costUSD) && costUSD >= 0 ? { costUSD } : {}) });
+    s.context = u.input_tokens;
+    return true;
+  }
+  s.bad = scan(file, wantLine, r => {
+    const p = r.payload ?? {};
+    if (r.type === 'session_meta') {
+      if (s.startedAt != null) return;   // a forked rollout repeats its parent meta; the first one is ours
+      s.id = p.id ?? p.session_id ?? s.id; s.cwd = typeof p.cwd === 'string' ? p.cwd : null;
+      s.originator = p.originator ?? null; s.agentPath = typeof p.agent_path === 'string' ? p.agent_path : null;
+      s.hostSource = typeof p.source === 'string' ? p.source : p.source?.subagent ? 'subagent' : null;
+      s.parentId = p.parent_thread_id ?? p.source?.subagent?.thread_spawn?.parent_thread_id ?? null;
+      historyStart = Number.isSafeInteger(p.subagent_history_start_ordinal) ? p.subagent_history_start_ordinal : null;
+      // Forked threads begin with a copy of the parent history; skip it until the fork's own first turn.
+      skipping = historyStart != null || !!p.forked_from_id;
+      if (s.parentId) s.kind = 'sub';
+      else if (s.hostSource === 'exec') s.kind = 'standalone';
+      else if (declaration.pluginOrigins.includes(s.originator)) s.kind = 'sub';   // started by the Claude Code Codex plugin; parent is linked later
+      const at = Date.parse(p.timestamp ?? r.timestamp);
+      if (Number.isFinite(at)) { s.startedAt = at; s.lastActivityAt = at; }
+      return;
+    }
+    const isRecord = r.type === 'token_usage_record' || p.type === 'token_usage_record';
+    const record = r.payload ?? r;
+    const hasThread = isRecord && record.thread_id != null;
+    if (hasThread && record.thread_id !== s.id) return;
+    if (!hasThread && historyStart != null && (!Number.isSafeInteger(r.ordinal) || r.ordinal < historyStart)) return;
+    if (skipping && !hasThread) {
+      if (historyStart != null && Number.isSafeInteger(r.ordinal)) { if (r.ordinal >= historyStart) skipping = false; }
+      else if (p.type === 'thread_settings_applied' || p.type === 'task_started') skipping = false;
+      if (skipping) return;
+    }
+    const at = Date.parse(r.timestamp);
+    if (Number.isFinite(at)) { s.startedAt ??= at; s.lastActivityAt = at; }
+    if (r.type === 'turn_context') {
+      if (typeof p.model === 'string') s.model = p.model;
+      s.effort = p.effort ?? p.reasoning_effort ?? s.effort;
+      s.cwd ??= typeof p.cwd === 'string' ? p.cwd : null;
+    } else if (isRecord) {
+      hasRecords = true;
+      const id = record.response_id ?? r.response_id;
+      if (typeof id !== 'string' || seen.has(id)) return;
+      if (addUsage(record.usage ?? r.usage, at, records, record.costUSD ?? r.costUSD)) seen.add(id);
+    } else if (r.type === 'event_msg') {
+      if (p.type === 'task_started') s.turn = 'open';
+      else if (p.type === 'task_complete' || p.type === 'task_completed') s.turn = 'done';
+      else if (p.type === 'turn_aborted') s.turn = 'aborted';
+      else if (p.type === 'user_message') s.name ??= clip(p.message);
+      else if (p.type === 'token_count') {
+        // Other limit ids (e.g. premium) are separate meters.
+        const quota = quotaFromRecord(p, at);
+        if (quota) s.quota = quota;
+        const key = p.info?.total_token_usage?.total_tokens;
+        const repeated = key != null && key === previousTotal;
+        previousTotal = key;
+        if (!repeated) addUsage(p.info?.last_token_usage, at, fallback);
+      }
+    } else if (r.type === 'response_item') {
+      if (p.type === 'message' && p.role === 'user') fallbackName ??= clip(firstText(p.content));
+      else if (p.type === 'function_call' || p.type === 'custom_tool_call') {
+        for (const cmd of codexCommands(p)) {
+          const kind = launchKind(cmd);
+          if (kind) {
+            const l = launchOf(at, kind, cmd);
+            let args; try { args = JSON.parse(p.arguments); } catch {}
+            l.cwd = launchCwd(cmd, args?.workdir ?? s.cwd, kind === 'codex plugin' ? ['--cwd'] : ['-C', '--cd']);
+            l.toolUseId = p.call_id;
+            s.launches.push(l);
+            if (typeof p.call_id === 'string') calls.set(p.call_id, l);
+          }
+        }
+      }
+      else if (p.type === 'function_call_output' && calls.has(p.call_id)) {
+        const l = calls.get(p.call_id);
+        l.job = resultJob(p.output);
+        if (l.kind === 'claude -p') l.sessionIds = resultSessions(p.output);
+      }
+    }
+  });
+  if (s.startedAt == null) return null;
+  // Sub-agent task text is encrypted in the rollout, so the agent path is the best label.
+  s.prompt = s.name ?? fallbackName;   // the thread title (session_index.jsonl) replaces name in readSessions
+  s.name = s.prompt ?? s.agentPath?.split('/').filter(Boolean).at(-1) ?? null;
+  s.usage = hasRecords ? records : fallback;
+  s.tokens = { input: 0, cacheRead: 0, cacheWrite: null, output: 0 };
+  for (const e of s.usage) for (const k of ['input', 'cacheRead', 'cacheWrite', 'output']) {
+    if (e.tokens[k] != null) s.tokens[k] = (s.tokens[k] ?? 0) + e.tokens[k];
+  }
+  return s;
+}
+
+// shortcut: a changed rollout is re-read whole (unchanged ones come from the cache); upgrade to offset reads if one gets huge.
+function readSessions({ codexHome: home = codexHome(), dirs = ['sessions', 'archived_sessions'].map(d => path.join(home, d)), since = 0, index = path.join(home, 'session_index.jsonl'), ...options } = {}) {
+  const billing = readBilling({ ...options, codexHome: home });
+  const titles = readTitles(index);
+  return dirs.flatMap(d => files(d, since)).map(f => cached(f, parseRollout)).filter(Boolean).map(s => ({ ...s, billing, ...(titles.has(s.id) ? { name: titles.get(s.id) } : {}) }));
+}
+
+// The thread names Codex gives its sessions: id -> thread_name (the last line of an id wins).
+function readTitles(file) {
+  const titles = new Map();
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { /* no index yet */ }
+  for (const line of text.split('\n')) {
+    try { const r = JSON.parse(line); if (typeof r.id === 'string' && typeof r.thread_name === 'string' && r.thread_name.trim()) titles.set(r.id, r.thread_name.replace(/\s+/g, ' ').trim().slice(0, 120)); } catch { /* blank or partial line */ }
+  }
+  return titles;
+}
+
+// The companion records the exact Claude session and Codex thread, including jobs still running.
+// Read both copies: state.json may omit old jobs or be mid-write while jobs/<id>.json is available.
+function pluginDataDir() {
+  const host = Object.values(require('../../catalog.json').agents).find(a => a.originators?.some(o => declaration.pluginOrigins.includes(o)) && a.pluginData)?.pluginData;
+  if (!host) return null;
+  return path.join(process.env[host.homeEnv] ?? path.join(os.homedir(), host.home), host.relative);
+}
+function readPluginJobs({ dir, dataDir = pluginDataDir(), tempDir = path.join(os.tmpdir(), 'codex-companion') } = {}) {
+  const read = file => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+  const entries = dir => { try { return fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; } };
+  const roots = dir ? [dir] : [...new Set([...(dataDir ? [path.join(dataDir, 'codex-openai-codex/state'), ...entries(dataDir).filter(e => e.isDirectory() && /codex/i.test(e.name)).map(e => path.join(dataDir, e.name, 'state'))] : []), tempDir])];
+  return roots.flatMap(dir => entries(dir).filter(e => e.isDirectory()).flatMap(e => {
+    const root = path.join(dir, e.name), stateFile = path.join(root, 'state.json'), state = cached(stateFile, read);
+    const jobs = (Array.isArray(state?.jobs) ? state.jobs : []).map(job => ({ job, file: stateFile }));
+    for (const f of entries(path.join(root, 'jobs')).filter(f => f.isFile() && f.name.endsWith('.json'))) {
+      const file = path.join(root, 'jobs', f.name);
+      jobs.push({ job: cached(file, read), file });
+    }
+    return jobs.filter(({ job }) => job && ['id', 'threadId'].every(k => typeof job[k] === 'string' && job[k])
+        && (job.sessionId == null || (typeof job.sessionId === 'string' && job.sessionId))
+        && ['startedAt', 'createdAt'].every(k => job[k] == null || typeof job[k] === 'string')
+        && Number.isFinite(Date.parse(job.startedAt ?? job.createdAt)))
+      .map(({ job, file }) => ({ id: job.id, threadId: job.threadId, sessionId: job.sessionId, at: Date.parse(job.startedAt ?? job.createdAt), file }));
+  }));
+}
+
+const isCodex = p => p.name === 'codex.exe' || p.name === 'codex';
+
+// First positional argument of a codex command line (after the exe), skipping options and the values of -c/-m/...
+const VALUE_FLAGS = new Set(['-c', '--config', '-m', '--model', '-p', '--profile', '-C', '--cd', '-s', '--sandbox', '-a', '--ask-for-approval', '-i', '--image']);
+function subcommand(p) {
+  const args = (p.cmd.match(/"[^"]*"|\S+/g) ?? []).slice(1).map(a => a.replace(/^"|"$/g, ''));
+  for (let i = 0; i < args.length; i++) {
+    if (VALUE_FLAGS.has(args[i])) i++;
+    else if (!args[i].startsWith('-')) return args[i];
+  }
+  return null;
+}
+const isAppServer = p => isCodex(p) && subcommand(p) === 'app-server';
+const isExec = p => isCodex(p) && subcommand(p) === 'exec';
+// Only the interactive TUI; mcp-server, proxy, sandbox helpers and the like are not sessions.
+const isTui = p => isCodex(p) && [null, 'resume', 'fork'].includes(subcommand(p));
+
+// Hosted in the shared Codex app-server: no per-thread process, so the rollout is the evidence.
+// A host is valid only if an app-server was already running when the thread last wrote; a newer one cannot hold it.
+// shortcut: a thread reopened after a restart that has not written yet looks ended; no log shows it until it writes.
+function hostedState(s, servers) {
+  if (!servers.some(p => p.startMs <= s.lastActivityAt)) return 'ended';
+  if (s.turn === 'open') return 'running';
+  return s.kind === 'main' ? 'waiting' : 'ended';
+}
+
+function liveness({ sessions, procs, pidFiles, now, owners = new Map(), claim }) {
+  const out = new Map(), claimed = new Set(), key = s => `${s.provider}:${s.id}`;
+  const byId = new Map(sessions.map(s => [key(s), s]));
+  const servers = procs.filter(isAppServer);
+  // A nested sub-thread follows the state of the topmost Codex session found on disk above it.
+  const rootOf = s => {
+    let cur = byId.get(`codex:${s.parentId}`), seen = new Set();
+    while (cur && !seen.has(cur) && byId.has(`codex:${cur.parentId}`)) { seen.add(cur); cur = byId.get(`codex:${cur.parentId}`); }
+    return cur ?? null;
+  };
+  const ownProcess = s => s.kind === 'standalone' || s.hostSource === 'cli';
+  const set = (s, state, pid = null) => out.set(key(s), { state, pid });
+  // Newest first, so when two sessions compete for one process the live one wins.
+  const order = [...sessions].sort((a, b) => b.startedAt - a.startedAt);
+
+  for (const s of order.filter(x => x.provider === 'codex')) {
+    let p = null;
+    if (s.kind === 'standalone') p = claim(procs.filter(isExec), s, claimed, owners);
+    else if (s.hostSource === 'cli') {
+      // A TUI is its own process; "codex resume <id>" names the thread, otherwise match by start time.
+      const tui = procs.filter(isTui);
+      p = tui.find(x => x.cmd.includes(s.id) && !claimed.has(x.pid)) ?? claim(tui, s, claimed, owners);
+      if (p) claimed.add(p.pid);
+    }
+    if (p) set(s, s.turn === 'open' ? 'running' : 'waiting', p.pid);
+    else if (ownProcess(s)) set(s, 'ended');   // own process is gone
+    else {
+      const top = rootOf(s);
+      if (!top || !ownProcess(top)) set(s, hostedState(s, servers));   // else: decided below from the parent
+    }
+  }
+
+  // A Codex sub-thread under a TUI/exec root lives and dies with that root, like a Claude sub-agent.
+  for (const s of order.filter(x => x.provider === 'codex' && !out.has(key(x)))) {
+    set(s, s.turn === 'open' && out.get(key(rootOf(s))).state !== 'ended' ? 'running' : 'ended');
+  }
+
+  return out;
+}
+
+const readJson = file => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+
+// Window ids and lengths are declared, independent of primary/secondary ordering.
+const { quotaFromRecord, quotaFromLimits, codexQuota } = require('./sources/rollout.js');
+
+function loadLimits({ codexHome = process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex') } = {}) {
+  const table = new Map();
+  const models = readJson(path.join(codexHome, 'models_cache.json'))?.models;
+  for (const m of Array.isArray(models) ? models : []) if (typeof m?.slug === 'string' && Number.isSafeInteger(m.context_window) && m.context_window > 0) table.set(m.slug, m.context_window);
+  return table;
+}
+
+// Commands inside a Codex tool call: JSON arguments (cmd/command) or a custom tool's JS text (cmd:"...").
+function codexCommands(payload) {
+  const out = [];
+  if (typeof payload.arguments === 'string') {
+    try {
+      const a = JSON.parse(payload.arguments), c = a?.cmd ?? a?.command;
+      out.push(Array.isArray(c) ? String(c.at(-1)) : c);
+    } catch { /* not JSON */ }
+  }
+  if (typeof payload.input === 'string') {
+    for (const m of payload.input.matchAll(/\bcmd:\s*"((?:[^"\\]|\\.)*)"/g)) {
+      try { out.push(JSON.parse(`"${m[1]}"`)); } catch { /* bad escape */ }
+    }
+  }
+  return out.filter(c => typeof c === 'string');
+}
+
+const launchPatterns = [
+  ['codex plugin', /^(?:node\s+)?["']?\S*codex-companion[^\s"']*["']?\s+(?:task|review|adversarial-review)(?=\s|$)/],   // not task-resume-candidate, task-status ...
+  ['codex exec', /^["']?\S*\bcodex(?:\.exe|\.cmd)?["']?\s+(?:\S+\s+)*?exec\b/],
+];
+
+module.exports = { readTimeline: require('./timeline.js').readTimeline, readSessions, parseRollout, codexCommands, codexHome, readPluginJobs, codexQuota, quotaFromLimits, readBilling,
+  processNames: ['codex.exe', 'codex'], liveness, loadLimits, launchPatterns,
+  launchLine: line => line.includes('"function_call"') || line.includes('"custom_tool_call"'),
+  launchCalls: r => ['function_call', 'custom_tool_call'].includes(r.payload?.type) ? [[r.payload.call_id, codexCommands(r.payload)]] : [],
+  readJobs: readPluginJobs,
+  parentLabel: 'Codex agent',
+  launchKindOf: s => s.parentId ? null : declaration.pluginOrigins.includes(s.originator) ? 'codex plugin' : s.hostSource === 'exec' ? 'codex exec' : null,
+  launchPolicy: (kind, s) => kind === 'codex plugin' ? { process: false, parentOrigin: s.originator } : { process: true },
+  provenLinks: (s, jobs) => jobs.filter(j => j.threadId === s.id && typeof j.sessionId === 'string' && j.sessionId).map(j => ({ parentId: j.sessionId, parentOrigin: s.originator, evidence: { jobId: j.id, file: j.file, at: j.at } })),
+  launchProofs: (s, jobs, sessions) => sessions.filter(a => a.provider !== s.provider || a.id !== s.id).flatMap(a => (a.launches ?? []).filter(l => l.kind === 'codex plugin' && l.job && jobs.some(j => j.id === l.job && j.threadId === s.id)).map(l => ({ parent: `${a.provider}:${a.id}`, label: 'codex plugin', evidence: { job: l.job, toolUseId: l.toolUseId } })))
+};

package/agentmoni/lib/agents/codex/sources/rollout.js

@@ -0,0 +1,26 @@
+const declaration = require('../../../catalog.json').agents.codex;
+const validPercent = v => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const afterReset = (at, now) => at != null && at <= now;
+function quotaFromLimits(limits, at) {
+  const windows = [];
+  for (const w of [limits.primary, limits.secondary]) {
+    if (!Number.isFinite(w?.window_minutes) || !validPercent(w.used_percent)) continue;
+    const declared = declaration.windows.find(d => d.minutes === w.window_minutes);
+    if (!declared) continue;
+    const resetsAt = Number.isFinite(w.resets_at) ? w.resets_at * 1000 : null;
+    windows.push({ id: declared.id, label: declared.label, usedPercent: w.used_percent, resetsAt });
+  }
+  return { windows, readAt: at, source: 'log' };
+}
+function quotaFromRecord(payload, at) {
+  const limits = payload?.rate_limits;
+  return Number.isFinite(at) && (limits?.primary || limits?.secondary) && (limits.limit_id ?? 'codex') === 'codex' ? quotaFromLimits(limits, at) : null;
+}
+function codexQuota(sessions, now = Date.now()) {
+  let latest = null;
+  for (const s of sessions) if (s.provider === 'codex' && s.quota && (!latest || s.quota.readAt > latest.readAt)) latest = s.quota;
+  if (!latest) return { windows: [], readAt: null, source: 'log', error: 'no Codex rate limits in the rollouts read' };
+  return { ...latest, windows: latest.windows.map(w => ({ ...w, usedPercent: afterReset(w.resetsAt, now) ? null : w.usedPercent })) };
+}
+
+module.exports = { quotaFromRecord, quotaFromLimits, codexQuota, createQuota: () => ({ read: codexQuota }) };

package/agentmoni/lib/agents/codex/timeline.js

@@ -0,0 +1,22 @@
+const { read, clip, typed, toolText, n } = require('../../timeline.js');
+function readTimeline(file) {
+  return read(file, (r, { out, add, lastOf, seen }) => {
+    const p = r.payload ?? {};
+    if (r.type === 'response_item') {
+      const first = Array.isArray(p.content) ? p.content.find(c => typeof c?.text === 'string')?.text : null;
+      if (p.type === 'message' && p.role === 'user' && typed(first)) add(r, 'user', clip(first));
+      else if (p.type === 'message' && p.role === 'assistant') add(r, 'assistant', clip(first));
+      else if (p.type === 'function_call' || p.type === 'custom_tool_call') add(r, 'tool', toolText(p.name, p.arguments ?? p.input));
+    } else if (r.type === 'event_msg') {
+      if (p.type === 'task_started') add(r, 'turn', 'turn started');
+      else if (p.type === 'task_complete' || p.type === 'task_completed') add(r, 'turn', 'turn done');
+      else if (p.type === 'turn_aborted') add(r, 'turn', 'turn aborted');
+      else if (p.type === 'token_count' && p.info?.last_token_usage && out.length) {
+        const last = p.info.last_token_usage, total = p.info.total_token_usage?.total_tokens, e = out[out.length - 1];
+        if (total != null) { if (seen.has(total)) return; seen.add(total); }
+        if (e.kind !== 'user' && !e.tokens) e.tokens = { input: Math.max(0, n(last.input_tokens) - n(last.cached_input_tokens)), cacheRead: n(last.cached_input_tokens), cacheWrite: null, output: n(last.output_tokens) };
+      }
+    }
+  });
+}
+module.exports = { readTimeline };

package/agentmoni/lib/agents/index.js

@@ -0,0 +1,13 @@
+// The core imports only this registry. Identity, windows and models come from catalog.json.
+const path = require('node:path');
+const { load } = require('../catalog.js');
+function discover(catalog = load(), directory = __dirname) {
+  return Object.values(catalog.agents).map(a => ({
+    ...require(path.join(directory, a.id, 'index.js')),
+    ...a, hue: a.color,
+    createQuota: options => require('../quota.js').orderedSources(a.quotaSources.map(source => require(path.join(directory, a.id, 'sources', source + '.js')).createQuota(options))),
+    models: Object.entries(catalog.models).filter(([, m]) => m.agent === a.id).map(([id, m]) => ({ id, ...m }))
+  }));
+}
+module.exports = discover();
+module.exports.discover = discover;

package/agentmoni/lib/catalog.js

@@ -0,0 +1,96 @@
+// Loads catalog.json (hand-edited, so every field is checked before use).
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SOURCES = ['measured', 'community', 'doc', 'estimated', 'assumed', 'unmeasured'];
+
+const fail = (file, where, why) => { throw new Error(`${file}: ${where}: ${why}`); };
+const isObject = v => v != null && typeof v === 'object' && !Array.isArray(v);
+const isNumber = v => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const isDate = v => typeof v === 'string' && Number.isFinite(Date.parse(v));
+
+// Dated entries: values change over time, and old records must be priced with the values valid then.
+function checkHistory(file, where, list, checkValue) {
+  if (!Array.isArray(list) || list.length === 0) fail(file, where, 'must be a non-empty array of dated entries');
+  list.forEach((e, i) => {
+    const at = `${where}[${i}]`;
+    if (!isObject(e)) fail(file, at, 'must be an object');
+    if (!SOURCES.includes(e.source)) fail(file, `${at}.source`, `must be one of ${SOURCES.join(', ')}`);
+    if (!isDate(e.at)) fail(file, `${at}.at`, 'must be a date');
+    if (!isDate(e.validFrom)) fail(file, `${at}.validFrom`, 'must be a date');
+    checkValue(e, at);
+  });
+}
+
+function checkCatalog(c, file = 'catalog.json') {
+  if (!isObject(c)) fail(file, '(root)', 'must be an object');
+  if (!(isNumber(c.contextWarn) && c.contextWarn > 0 && c.contextWarn <= 1)) fail(file, 'contextWarn', 'must be a fraction in (0, 1]');
+  if (!Array.isArray(c.tokenTypes) || !c.tokenTypes.length || c.tokenTypes.some(t => typeof t !== 'string') || new Set(c.tokenTypes).size !== c.tokenTypes.length) fail(file, 'tokenTypes', 'must list distinct token fields');
+  if (!Array.isArray(c.priceSchema?.fields) || c.priceSchema.fields.some(t => typeof t !== 'string')) fail(file, 'priceSchema.fields', 'must list price fields');
+  if (!isObject(c.agents) || Object.keys(c.agents).length === 0) fail(file, 'agents', 'must be a non-empty object');
+  for (const [name, p] of Object.entries(c.agents)) {
+    if (!/^[a-z][a-z0-9_-]*$/.test(name) || p?.id !== name) fail(file, name, "id must match the agent folder name");
+    if (typeof p.name !== "string" || !p.name || !isNumber(p.color)) fail(file, name, "must declare name and color hue");
+    if (!Array.isArray(p.efforts) || !p.efforts.length || p.efforts.some(e => !isObject(e) || typeof e.id !== 'string' || !/^[a-z][a-z0-9_-]*$/.test(e.id) || !(e.color === null || (isNumber(e.color) && e.color < 360))) || new Set(p.efforts.map(e => e.id)).size !== p.efforts.length) fail(file, name + '.efforts', 'must list distinct efforts with id and color hue (or null for grey)');
+    if (!Array.isArray(p.windows) || p.windows.some(w => !isObject(w) || typeof w.id !== "string" || !w.id || typeof w.label !== "string" || !w.label || !isNumber(w.durationMs) || w.durationMs <= 0) || new Set(p.windows.map(w => w.id)).size !== p.windows.length) fail(file, name, "must list distinct windows with id, label and durationMs");
+    if (!Array.isArray(p.quotaSources) || p.quotaSources.some(x => typeof x !== 'string' || !/^[a-z][a-z0-9_-]*$/.test(x)) || new Set(p.quotaSources).size !== p.quotaSources.length) fail(file, `${name}.quotaSources`, 'must list distinct source names');
+    for (const source of p.quotaSources) if (!fs.existsSync(path.join(__dirname, 'agents', name, 'sources', `${source}.js`))) fail(file, `${name}.quotaSources`, `missing source file: ${source}`);
+    if (!p.plan && !p.tokenWeights && !p.plans) continue;
+    const at = `agents.${name}`;
+    if (!isObject(p?.plans?.[p.plan])) fail(file, `${at}.plan`, `must name an entry of ${at}.plans`);
+    for (const [plan, body] of Object.entries(p.plans)) for (const { id: w } of p.windows)
+      checkHistory(file, `${at}.plans.${plan}.windows.${w}`, body?.windows?.[w], (e, a) => { if (!(isNumber(e.capacity) && e.capacity > 0)) fail(file, `${a}.capacity`, 'must be a positive number'); });
+    checkHistory(file, `${at}.tokenWeights`, p.tokenWeights, (e, a) => { for (const t of c.tokenTypes) if (!isNumber(e[t])) fail(file, `${a}.${t}`, 'must be a non-negative number'); });
+  }
+  if (!isObject(c.models)) fail(file, 'models', 'must be an object');
+  for (const [id, m] of Object.entries(c.models)) {
+    const at = `models.${id}`;
+    if (!c.agents[m?.agent]) fail(file, `${at}.agent`, `must be one of ${Object.keys(c.agents).join(', ')}`);
+    if (!isNumber(m.tier) || !isNumber(m.color)) fail(file, at, "must declare tier and color hue");
+    if (!(Number.isSafeInteger(m.context) && m.context > 0)) fail(file, `${at}.context`, 'must be a positive token count');
+    checkHistory(file, `${at}.weights`, m.weights, (e, a) => {
+      if (e.value === null ? e.source !== 'unmeasured' : !(isNumber(e.value) && e.value > 0)) fail(file, `${a}.value`, 'must be a positive number, or null with source "unmeasured"');
+    });
+    if (m.prices !== undefined) {
+      if (!Array.isArray(m.prices)) fail(file, `${at}.prices`, 'must be an array');
+      for (const [i, e] of m.prices.entries()) {
+        const a = `${at}.prices[${i}]`;
+        if (!isObject(e) || typeof e.source !== 'string' || !isDate(e.at) || !isDate(e.validFrom)) fail(file, a, 'must have source, at and validFrom');
+        for (const t of c.priceSchema.fields) if (!(isNumber(e[t]) || (e[t] === null && c.priceSchema.nullable?.includes(t)))) fail(file, `${a}.${t}`, 'must be a non-negative number');
+        if (e.fastMultiplier !== undefined && (!isNumber(e.fastMultiplier) || e.fastMultiplier <= 0)) fail(file, a, 'invalid fastMultiplier');
+        if (e.geoMultipliers !== undefined && (!isObject(e.geoMultipliers) || Object.values(e.geoMultipliers).some(v => !isNumber(v) || v <= 0))) fail(file, a, 'invalid geoMultipliers');
+        if (e.long !== undefined) {
+          if (!isObject(e.long) || !isNumber(e.long.above)) fail(file, `${a}.long.above`, 'must be a token count');
+          for (const t of c.priceSchema.fields) if (!(isNumber(e.long[t]) || (e.long[t] === null && c.priceSchema.nullable?.includes(t)))) fail(file, `${a}.long.${t}`, 'must be a non-negative number');
+        }
+      }
+    }
+  }
+  return c;
+}
+
+function load(file = path.join(__dirname, 'catalog.json')) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch (e) { throw new Error(`${file}: cannot read (${e.code ?? e.message})`); }
+  try { return checkCatalog(JSON.parse(text), file); } catch (e) { if (e instanceof SyntaxError) throw new Error(`${file}: invalid JSON (${e.message})`); throw e; }
+}
+
+// The newest entry whose validFrom is not after `at`; falls back to the oldest entry for earlier dates.
+function pick(list, at = Date.now()) {
+  const sorted = [...list].sort((a, b) => Date.parse(a.validFrom) - Date.parse(b.validFrom));
+  return sorted.filter(e => Date.parse(e.validFrom) <= at).pop() ?? sorted[0];
+}
+
+// An unmeasured model is priced like the costliest measured model of the same provider, and flagged.
+// With no such peer the weight stays unknown (null): guessing low would hide real cost.
+function modelWeight(catalog, id, at = Date.now()) {
+  const m = catalog.models[id];
+  if (!m) throw new Error(`Unknown model: ${id}`);
+  const own = pick(m.weights, at);
+  if (own.value != null) return { value: own.value, assumed: false, source: own.source };
+  const peers = Object.values(catalog.models).filter(o => o.agent === m.agent).map(o => pick(o.weights, at).value).filter(v => v != null);
+  return { value: peers.length ? Math.max(...peers) : null, assumed: true, source: 'unmeasured' };
+}
+
+const windowIds = (c, agent) => (c.agents[agent]?.windows ?? []).map(w => w.id);
+module.exports = { load, checkCatalog, pick, modelWeight, windowIds };