sprag-cli 3.52.0 → 3.54.0

package/src/codex-brief.js

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { codexUserDir } from './agent.js';
+import { userDataDir } from './paths.js';
+import { readCodexSnapshot } from './codex-parser.js';
+
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const stateDir = (dir) => join(dir, 'codex', hash(codexUserDir()), 'sessions');
+const fresh = (value, now) => {
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && timestamp <= now + 60000 && now - timestamp < 300000;
+};
+
+export function codexIssues(snapshot, { now = Date.now() } = {}) {
+  if (!snapshot) return [];
+  const issues = [];
+  const fraction = snapshot.contextWindow > 0 && Number.isFinite(snapshot.lastContextTokens)
+    ? snapshot.lastContextTokens / snapshot.contextWindow : null;
+  if (fraction >= 0.8 && fresh(snapshot.contextAt, now)) {
+    const tier = fraction >= 0.95 ? 2 : 1;
+    issues.push({ key: 'context', tier, signature: `context:${tier}`, level: tier === 2 ? 'critical' : 'warning',
+      message: `Recorded input context is ${Math.round(fraction * 100)}% (${snapshot.lastContextTokens}/${snapshot.contextWindow} tokens).`,
+      advice: 'Preserve decisions, verification results, and next steps before compaction. Use sprag handoff --agent codex when a handoff is needed.' });
+  }
+  if (fresh(snapshot.rateLimitsAt, now)) {
+    for (const key of ['primary', 'secondary']) {
+      const win = snapshot.rateLimits?.[key];
+      if (!Number.isFinite(win?.used_percent) || win.used_percent < 90) continue;
+      if (Number.isFinite(win.resets_at) && win.resets_at * 1000 <= now) continue;
+      const label = Number.isFinite(win.window_minutes) && win.window_minutes > 0 ? `${win.window_minutes}m` : key;
+      issues.push({ key: `limit:${key}`, tier: 1, signature: `limit:${key}:${win.resets_at ?? 'unknown'}`,
+        level: 'warning', message: `Recorded ${label} rate limit is ${win.used_percent}% used.`,
+        advice: 'Finish the current step and preserve the remaining work with sprag handoff --agent codex. This is a usage snapshot, not a billing estimate.' });
+    }
+  }
+  return issues;
+}
+
+function readState(file) {
+  try {
+    const state = JSON.parse(readFileSync(file, 'utf8'));
+    return state && Array.isArray(state.events) ? state : { events: [] };
+  } catch { return { events: [] }; }
+}
+
+/** One file per home/session keeps unrelated sessions out of the same dedup state. */
+export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now(), dir = userDataDir() } = {}) {
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  const snapshot = readCodexSnapshot(transcriptPath);
+  if (!snapshot || (snapshot.sessionId && snapshot.sessionId !== sessionId)) return null;
+  const issues = codexIssues(snapshot, { now });
+  const directory = stateDir(dir);
+  const file = join(directory, `${hash(sessionId)}.json`);
+  const state = readState(file);
+  const active = Array.isArray(state.active) ? state.active.filter((sig) => typeof sig === 'string') : [];
+  const next = issues.filter((issue) => !active.includes(issue.signature) &&
+    !(issue.key === 'context' && issue.tier === 1 && active.includes('context:2')));
+  // Missing or stale measurements do not resolve an earlier warning. A fresh
+  // lower measurement does, so a refill after compaction can warn again.
+  const observed = new Set();
+  if (fresh(snapshot.contextAt, now) && snapshot.contextWindow > 0 && Number.isFinite(snapshot.lastContextTokens)) observed.add('context');
+  if (fresh(snapshot.rateLimitsAt, now)) {
+    for (const key of ['primary', 'secondary']) {
+      if (Number.isFinite(snapshot.rateLimits?.[key]?.used_percent)) observed.add(`limit:${key}`);
+    }
+  }
+  const remaining = active.filter((sig) => ![...observed].some((key) => sig.startsWith(`${key}:`)));
+  const nextActive = [...new Set([...remaining, ...issues.map((issue) => issue.signature)])];
+  if (!next.length && JSON.stringify(nextActive) === JSON.stringify(active)) return null;
+  const at = new Date(now).toISOString();
+  const events = [...state.events, ...next.map((issue) => ({ ...issue, at, sessionId, project: cwd || snapshot.projectDir || '' }))].slice(-200);
+  mkdirSync(directory, { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ active: nextActive, events }) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+  return next.length ? ['[Sprag Codex briefing]', ...next.map((issue) => `${issue.message} ${issue.advice}`)].join('\n') : null;
+}
+
+export function readCodexHistory({ days = 7, sessionId, project, dir = userDataDir(), now = Date.now() } = {}) {
+  const directory = stateDir(dir);
+  let files;
+  try { files = readdirSync(directory); } catch { return []; }
+  const cutoff = now - days * 86400000;
+  return files.filter((file) => /^[a-f0-9]{64}\.json$/.test(file)).flatMap((file) => readState(join(directory, file)).events)
+    .filter((event) => event && typeof event.message === 'string' && Date.parse(event.at) >= cutoff && Date.parse(event.at) <= now &&
+      (!sessionId || event.sessionId === sessionId) && (!project || (typeof event.project === 'string' && event.project.includes(project))))
+    .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+}

package/src/codex-budget.js

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { parse } from 'smol-toml';
+import { codexUserDir } from './agent.js';
+import { pickBudgetSource } from './litellm-budget.js';
+
+const run = promisify(execFile);
+
+export function codexBudgetProvider({ home = codexUserDir(), env = process.env, providerName } = {}) {
+  try {
+    const cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8'));
+    const profile = cfg.profiles?.[cfg.profile] || {};
+    const name = providerName || profile.model_provider || cfg.model_provider;
+    const provider = cfg.model_providers?.[name];
+    if (!provider || !/litellm/i.test(`${name} ${provider.name || ''}`)) return null;
+    const url = new URL(provider.base_url);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) return null;
+    url.pathname = url.pathname.replace(/\/v1\/?$/, '').replace(/\/$/, '');
+    url.search = ''; url.hash = '';
+    return { name, base: url.toString().replace(/\/$/, ''),
+      key: provider.env_key ? env[provider.env_key] : null,
+      command: provider.auth?.command,
+      args: provider.auth?.args || [] };
+  } catch { return null; }
+}
+
+export async function codexProviderKey(provider, { execute = run } = {}) {
+  let key = provider.key;
+  if (!key && typeof provider.command === 'string') {
+    try {
+      const result = await execute(provider.command, provider.args, { encoding: 'utf8', timeout: 10000, maxBuffer: 64 * 1024 });
+      key = result.stdout.trim().split(/\r?\n/).filter(Boolean).pop();
+    } catch { throw new Error('Codex provider authentication helper failed'); }
+  }
+  if (!key) throw new Error('Codex provider credentials unavailable');
+  return key;
+}
+
+export async function fetchCodexBudget(provider, { fetchImpl = fetch, execute = run, now = Date.now() } = {}) {
+  const key = await codexProviderKey(provider, { execute });
+  // Tokens stay in memory and headers, never in argv, state files or errors.
+  const headers = { authorization: `Bearer ${key}`, accept: 'application/json' };
+  const get = async (path) => {
+    try {
+      const res = await fetchImpl(`${provider.base}${path}`, { headers, signal: AbortSignal.timeout(5000), redirect: 'error' });
+      return res.ok ? await res.json() : null;
+    } catch { return null; }
+  };
+  const [keyResponse, userResponse] = await Promise.all([get('/key/info'), get('/user/info')]);
+  if (!keyResponse && !userResponse) throw new Error('LiteLLM budget endpoints unavailable');
+  const budget = pickBudgetSource(keyResponse?.info, userResponse);
+  return budget ? { ...budget, checkedAt: now } : null;
+}
+
+// Refresh between frames without delaying terminal paint. Cache no credentials.
+export function createCodexBudgetReader({ provider = codexBudgetProvider, fetchBudget = fetchCodexBudget, now = Date.now } = {}) {
+  let base, snapshot = null, pending = false, checked = -Infinity;
+  return function read() {
+    const cfg = provider();
+    if (!cfg) { base = null; snapshot = null; return null; }
+    if (cfg.base !== base) { base = cfg.base; snapshot = null; checked = -Infinity; }
+    if (!pending && now() - checked >= 300000) {
+      checked = now(); pending = true;
+      const requestedBase = base;
+      Promise.resolve().then(() => fetchBudget(cfg)).then((value) => {
+        if (base === requestedBase) snapshot = value;
+      }).catch(() => {}).finally(() => { pending = false; });
+    }
+    return snapshot;
+  };
+}

package/src/codex-cache-policy.js

@@ -0,0 +1,203 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { parse } from 'smol-toml';
+import { codexUserDir } from './agent.js';
+import { userDataDir } from './paths.js';
+import { codexBudgetProvider, codexProviderKey } from './codex-budget.js';
+import { codexCachePolicy } from './codex-cache.js';
+
+export const CACHE_POLICY_MAX_AGE_MS = 300000;
+const OPENAI_POLICY = 'https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime';
+const BEDROCK_POLICY = 'https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-openai';
+
+function deploymentPolicy(row) {
+  const params = row?.litellm_params || {}, info = row?.model_info || {};
+  const route = typeof params.model === 'string' ? params.model : '';
+  const base = typeof info.base_model === 'string' ? info.base_model : route;
+  const backend = /^bedrock(?:\/|_mantle\/)/.test(route) ? 'Bedrock'
+    : /^(?:openai\/)?gpt-/.test(route) ? 'OpenAI' : null;
+  if (!backend || info.supports_prompt_caching === false) return null;
+  // An OpenAI-compatible server is not necessarily OpenAI, even with a GPT alias.
+  if (backend === 'OpenAI' && params.api_base) {
+    try { if (new URL(params.api_base).hostname !== 'api.openai.com') return null; }
+    catch { return null; }
+  }
+  const model = backend === 'Bedrock'
+    ? base.replace(/^bedrock(?:\/converse)?\//, '').replace(/^bedrock_mantle\//, '').replace(/^(?:(?:global|us|eu|apac)\.)?openai\./, '')
+    : route.replace(/^openai\//, '');
+  const seconds = codexCachePolicy(model);
+  if (!seconds) return null;
+  const options = params.prompt_cache_options;
+  if (options != null && (typeof options !== 'object' || Array.isArray(options))) return null;
+  if (options?.ttl != null && options.ttl !== '30m') return null;
+  if (options?.mode != null && !['implicit', 'explicit'].includes(options.mode)) return null;
+  if (params.prompt_cache_retention != null) return null;
+  return { backend, model, seconds, mode: options?.mode || 'implicit',
+    reference: backend === 'Bedrock' ? BEDROCK_POLICY : OPENAI_POLICY };
+}
+
+export function gatewayCachePolicies(payload) {
+  if (!Array.isArray(payload?.data)) throw new Error('LiteLLM model/info returned no model list');
+  const groups = new Map();
+  for (const row of payload.data) {
+    if (typeof row?.model_name !== 'string' || row.model_name.length > 256) continue;
+    const group = groups.get(row.model_name) || [];
+    group.push(deploymentPolicy(row));
+    groups.set(row.model_name, group);
+  }
+  // All deployments behind an alias must agree; load balancing must not change TTL.
+  return Object.fromEntries([...groups].map(([name, policies]) => [name,
+    policies[0] && policies.every((p) => JSON.stringify(p) === JSON.stringify(policies[0])) ? policies[0] : null]));
+}
+
+export const PRICE_MAX_AGE_MS = 7 * 86400000;
+const rate = (value) => Number.isFinite(value) && value >= 0 && value < 1 ? value : null;
+
+function deploymentPrice(row) {
+  const info = row?.model_info || {};
+  const mode = typeof info.mode === 'string' ? info.mode : null;
+  if (mode && !['chat', 'responses', 'completion'].includes(mode)) return null;
+  const input = rate(info.input_cost_per_token), output = rate(info.output_cost_per_token);
+  if (input === null || output === null) return null;
+  return { input, output, cacheRead: rate(info.cache_read_input_token_cost), cacheWrite: rate(info.cache_creation_input_token_cost) };
+}
+
+/** Per-token prices by alias. Load-balanced deployments must agree, like cache policy. */
+export function gatewayPrices(payload) {
+  if (!Array.isArray(payload?.data)) throw new Error('LiteLLM model/info returned no model list');
+  const groups = new Map();
+  for (const row of payload.data) {
+    if (typeof row?.model_name !== 'string' || row.model_name.length > 256) continue;
+    groups.set(row.model_name, [...(groups.get(row.model_name) || []), deploymentPrice(row)]);
+  }
+  return Object.fromEntries([...groups].map(([name, prices]) => [name,
+    prices[0] && prices.every((p) => JSON.stringify(p) === JSON.stringify(prices[0])) ? prices[0] : null]));
+}
+
+/**
+ * USD for a token mix at one model's prices, or null when a needed rate is
+ * missing. Cached input without a cache-read rate is unknown, not free.
+ */
+export function codexRunCost({ input = 0, cached = 0, cacheWrite = 0, output = 0 }, price) {
+  if (!price || price.input === null || price.output === null) return null;
+  if (cached > 0 && price.cacheRead === null) return null;
+  // cache_write_input_tokens is billed at the creation rate when one is published, else as input.
+  const uncached = Math.max(0, input - cached - cacheWrite);
+  return uncached * price.input + cached * (price.cacheRead ?? 0) + cacheWrite * (price.cacheWrite ?? price.input) + output * price.output;
+}
+
+function cacheFile(provider, { home = codexUserDir(), dir = userDataDir() } = {}) {
+  const key = createHash('sha256').update(JSON.stringify([resolve(home), provider.name, provider.base])).digest('hex').slice(0, 24);
+  return join(dir, 'codex-cache-policy', `${key}.json`);
+}
+
+function gatewayProvider(session, opts) {
+  if (!session?.provider || session.provider === 'openai') return null;
+  return codexBudgetProvider({ ...opts, providerName: session.provider });
+}
+
+function directPolicy(session, { home = codexUserDir(), now = Date.now() } = {}) {
+  if (session?.provider !== 'openai' || !codexCachePolicy(session.model)) return null;
+  try {
+    let cfg = {};
+    try { cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8')); }
+    catch (e) { if (e.code !== 'ENOENT') return null; }
+    if (cfg.openai_base_url && new URL(cfg.openai_base_url).hostname !== 'api.openai.com') return null;
+  } catch { return null; }
+  return { backend: 'OpenAI', model: session.model, seconds: codexCachePolicy(session.model),
+    requestedModel: session.model, provider: session.provider, checkedAt: now, reference: OPENAI_POLICY };
+}
+
+function selectPolicy(snapshot, session, now) {
+  if (!Number.isFinite(snapshot?.checkedAt) || snapshot.checkedAt > now || now - snapshot.checkedAt >= CACHE_POLICY_MAX_AGE_MS) return null;
+  const policy = Object.hasOwn(snapshot.models || {}, session.model) ? snapshot.models[session.model] : null;
+  if (!policy || !['OpenAI', 'Bedrock'].includes(policy.backend) || policy.seconds !== codexCachePolicy(policy.model) || !policy.seconds) return null;
+  return { ...policy, requestedModel: session.model, provider: session.provider, checkedAt: snapshot.checkedAt };
+}
+
+/** Offline read for statuslines and diagnostics; no auth helper or network calls. */
+export function readCodexCachePolicy(session, opts = {}) {
+  const direct = directPolicy(session, opts);
+  if (direct) return direct;
+  const provider = gatewayProvider(session, opts);
+  if (!provider) return null;
+  try { return selectPolicy(JSON.parse(readFileSync(cacheFile(provider, opts), 'utf8')), session, opts.now ?? Date.now()); }
+  catch { return null; }
+}
+
+/**
+ * Offline price table for the configured gateway, from the snapshot the cache
+ * policy refresh writes. Prices change rarely, so a week-old table still counts;
+ * anything older reads as unknown rather than silently current.
+ */
+export function readCodexPrices({ provider, now = Date.now(), ...opts } = {}) {
+  provider ??= codexBudgetProvider(opts);
+  if (!provider) return null;
+  try {
+    const snapshot = JSON.parse(readFileSync(cacheFile(provider, opts), 'utf8'));
+    if (!Number.isFinite(snapshot?.checkedAt) || snapshot.checkedAt > now || now - snapshot.checkedAt > PRICE_MAX_AGE_MS) return null;
+    if (!snapshot.prices || typeof snapshot.prices !== 'object') return null;
+    return { checkedAt: snapshot.checkedAt, provider: provider.name, base: provider.base, prices: snapshot.prices };
+  } catch { return null; }
+}
+
+/** Fetch prices for the configured gateway without needing a session. */
+export async function refreshCodexPrices({ provider = codexBudgetProvider(), fetchImpl = fetch, execute, ...opts } = {}) {
+  if (!provider) throw new Error('No configured LiteLLM endpoint for Codex');
+  await writeGatewaySnapshot(provider, { fetchImpl, execute, ...opts });
+  return readCodexPrices({ provider, ...opts });
+}
+
+async function writeGatewaySnapshot(provider, { fetchImpl = fetch, execute, ...opts } = {}) {
+  const key = await codexProviderKey(provider, { execute });
+  let payload;
+  try {
+    const res = await fetchImpl(`${provider.base}/model/info`, {
+      headers: { authorization: `Bearer ${key}`, accept: 'application/json' },
+      signal: AbortSignal.timeout(5000), redirect: 'error',
+    });
+    if (!res.ok) throw new Error();
+    payload = await res.json();
+  } catch { throw new Error('LiteLLM model/info unavailable; cache policy was not verified'); }
+  const now = opts.now ?? Date.now();
+  let prices = null;
+  try { prices = gatewayPrices(payload); } catch { /* Prices are optional; the policy stands alone. */ }
+  const snapshot = { checkedAt: now, models: gatewayCachePolicies(payload), prices };
+  const file = cacheFile(provider, opts);
+  // Persist only policy and price fields, never raw model/info (which can contain secrets).
+  mkdirSync(join(opts.dir || userDataDir(), 'codex-cache-policy'), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(snapshot) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+  return snapshot;
+}
+
+export async function refreshCodexCachePolicy(session, { fetchImpl = fetch, execute, ...opts } = {}) {
+  const direct = directPolicy(session, opts);
+  if (direct) return direct;
+  const provider = gatewayProvider(session, opts);
+  if (!provider) throw new Error('No configured LiteLLM endpoint for this session provider');
+  const snapshot = await writeGatewaySnapshot(provider, { fetchImpl, execute, ...opts });
+  return selectPolicy(snapshot, session, snapshot.checkedAt);
+}
+
+/** Refresh between frames. Each provider/model has its own in-flight lookup. */
+export function createCodexCachePolicyReader({ refresh = refreshCodexCachePolicy, now = Date.now, ...opts } = {}) {
+  const attempts = new Map();
+  return function read(session) {
+    const at = now();
+    const policy = readCodexCachePolicy(session, { ...opts, now: at });
+    if (policy || !session) return policy;
+    const provider = gatewayProvider(session, opts);
+    if (!provider) return null;
+    const key = JSON.stringify([provider.name, provider.base, session.model]);
+    const last = attempts.get(key);
+    if (!last || (!last.pending && at - last.at >= CACHE_POLICY_MAX_AGE_MS)) {
+      const attempt = { at, pending: true };
+      attempts.set(key, attempt);
+      Promise.resolve().then(() => refresh(session, { ...opts, now: at })).catch(() => {}).finally(() => { attempt.pending = false; });
+    }
+    return null;
+  };
+}

package/src/codex-cache.js

@@ -0,0 +1,46 @@
+// Minimum retention windows, not exact expiration timestamps. Gateway aliases
+// require a resolved deployment before applying a provider's documented policy.
+// https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime
+export function codexCachePolicy(model) {
+  return /^gpt-(?:5\.6(?:-(?:sol|terra|luna))?|6-(?:astra|sol|luna))(?:-\d{4}-\d{2}-\d{2})?$/i.test(model || '') ? 1800 : null;
+}
+
+export function parseCodexCacheTtl(value) {
+  if (value === 'auto' || value === 'off') return value;
+  const match = /^(\d+)(m|h)$/.exec(value || '');
+  const seconds = match ? Number(match[1]) * (match[2] === 'h' ? 3600 : 60) : NaN;
+  if (!Number.isSafeInteger(seconds) || seconds < 60 || seconds > 86400) {
+    throw new Error('Cache TTL expects auto, off, or 1m through 24h (for example 30m). This changes the display estimate, not provider retention.');
+  }
+  return seconds;
+}
+
+export function codexCacheTimer(session, { now = Date.now(), ttl = 'auto', policy } = {}) {
+  if (ttl === 'off') return null;
+  const activity = session?.cacheActivity;
+  const at = activity?.at ? new Date(activity.at).getTime() : NaN;
+  const sameModel = activity?.model === session?.model;
+  if (!Number.isFinite(at) || at > now || !sameModel || activity?.provider !== session?.provider) {
+    return { text: 'Cache timer n/a', tone: 90, source: 'unavailable' };
+  }
+  const elapsed = Math.floor((now - at) / 1000);
+  const configured = Number.isSafeInteger(ttl) && ttl >= 60 && ttl <= 86400;
+  const resolved = policy && policy.requestedModel === session.model && policy.provider === session.provider &&
+    ['OpenAI', 'Bedrock'].includes(policy.backend) && policy.seconds === codexCachePolicy(policy.model) &&
+    Number.isFinite(policy.checkedAt) && now >= policy.checkedAt && now - policy.checkedAt < 300000;
+  const direct = policy === undefined && session.provider === 'openai' && codexCachePolicy(session.model);
+  const seconds = configured ? ttl : resolved ? policy.seconds : direct;
+  if (!seconds) return { text: `Cache age ${clock(elapsed)} / TTL unknown`, tone: 90, source: 'age', elapsed };
+  const remaining = Math.max(0, seconds - elapsed);
+  const source = configured ? 'configured estimate' : `${resolved ? policy.backend : 'OpenAI'} 30m`;
+  const text = remaining > 0 ? `Cache ${clock(remaining)} (${source})` : `Cache window elapsed (${source}; expiry unknown)`;
+  return { text, tone: remaining <= 0 ? 90 : remaining <= 60 ? 31 : remaining <= 300 ? 33 : 32,
+    source: configured ? 'configured' : 'provider-policy', seconds, elapsed, remaining };
+}
+
+function clock(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = seconds % 60;
+  return h ? `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}` : `${m}:${String(s).padStart(2, '0')}`;
+}

package/src/codex-delegation.js

@@ -0,0 +1,154 @@
+import { readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parse } from 'smol-toml';
+import { userDataDir } from './paths.js';
+import { codexUserDir, codexProviderName } from './agent.js';
+import { categorize, ESCALATE_RE, EDIT_RE } from './route-scan.js';
+import { looksPasted } from './route-inject.js';
+import { newRouteId, recordCodexDelegation } from './codex-ledger.js';
+
+export const CODEX_ROUTE_CATEGORIES = ['paste', 'translate', 'explore', 'read', 'check', 'run'];
+const MARKER = '<!-- sprag:codex:delegation -->';
+const safeId = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(value);
+const validEffort = (value) => value === undefined || ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(value);
+
+export function validateCodexTarget(model, effort) {
+  if (!safeId(model)) throw new Error('Provide a literal Codex model ID.');
+  if (!validEffort(effort)) {
+    throw new Error('Invalid reasoning effort; choose a value supported by the target model.');
+  }
+  return { model, ...(effort === undefined ? {} : { effort }) };
+}
+
+const rulesFile = (dir) => join(dir, 'codex-model-rules.json');
+export function loadCodexModelRules({ dir = userDataDir() } = {}) {
+  try {
+    const data = JSON.parse(readFileSync(rulesFile(dir), 'utf8'));
+    if (data?.version !== 1 || !Array.isArray(data.rules) || data.rules.some((r) => !r ||
+      !CODEX_ROUTE_CATEGORIES.includes(r.category) || !safeId(r.from) || !safeId(r.model) || r.from === r.model ||
+      !validEffort(r.effort) || r.status !== 'active' || !['global', 'project'].includes(r.scope) ||
+      (r.provider != null && !safeId(r.provider)) ||
+      (r.scope === 'project' ? typeof r.targetRoot !== 'string' || resolve(r.targetRoot) !== r.targetRoot : r.targetRoot !== null))) throw new Error();
+    return data.rules;
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw new Error('Cannot parse Codex model rules; file left unchanged.');
+  }
+}
+
+function saveRules(rules, dir) {
+  mkdirSync(dir, { recursive: true });
+  const file = rulesFile(dir), tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, rules }, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+export function addCodexModelRule({ category, model, effort, from, scope, root, provider }, { dir = userDataDir() } = {}) {
+  validateCodexTarget(model, effort);
+  if (!CODEX_ROUTE_CATEGORIES.includes(category)) throw new Error(`Category must be ${CODEX_ROUTE_CATEGORIES.join(', ')}`);
+  if (!safeId(from) || from === model) throw new Error('--from must name a different parent model.');
+  if (!['global', 'project'].includes(scope)) throw new Error('Choose --global or --project for the rule.');
+  if (provider != null && !safeId(provider)) throw new Error('Invalid Codex provider ID.');
+  const rules = loadCodexModelRules({ dir });
+  const targetRoot = scope === 'project' ? resolve(root) : null;
+  const rule = { category, model, effort, from, scope, targetRoot, ...(provider ? { provider } : {}), status: 'active', createdAt: new Date().toISOString() };
+  const old = rules.findIndex((r) => r.category === category && r.from === from && r.scope === scope && r.targetRoot === targetRoot && r.provider === provider);
+  if (old < 0) rules.push(rule); else rules[old] = rule;
+  saveRules(rules, dir);
+  return rule;
+}
+
+export function removeCodexModelRule(index, { dir = userDataDir() } = {}) {
+  const rules = loadCodexModelRules({ dir });
+  if (!Number.isSafeInteger(index) || index < 1 || index > rules.length) throw new Error('Unknown Codex rule index.');
+  rules.splice(index - 1, 1);
+  saveRules(rules, dir);
+}
+
+/**
+ * The category a prompt can be routed under at runtime, or null. The route
+ * scan counts episodes with this same gate, so a rule it proposes is one the
+ * prompt hook can actually match.
+ */
+export function codexPromptCategory(text) {
+  const prompt = typeof text === 'string' ? text.trim() : '';
+  if (prompt.length < 8 || ESCALATE_RE.test(prompt) || EDIT_RE.test(prompt) || /\b(?:implement|modify|fix|delete|push|commit)\b/i.test(prompt)) return null;
+  const category = categorize(prompt, null);
+  if (!category || (category.id === 'paste' && !looksPasted(prompt))) return null;
+  return category;
+}
+
+export function matchCodexModelRule(text, { model, root, provider = codexProviderName(), rules = loadCodexModelRules() } = {}) {
+  const category = codexPromptCategory(text);
+  if (!category) return null;
+  const usable = rules.filter((r) => r?.status === 'active' && r.category === category.id && r.from === model &&
+    (!r.provider || r.provider === provider) &&
+    safeId(r.model) && validEffort(r.effort) && r.model !== model && (r.scope === 'global' || (r.scope === 'project' && r.targetRoot === resolve(root || '.'))));
+  return usable.find((r) => r.scope === 'project') || usable[0] || null;
+}
+
+export function codexRouteHint(payload, opts = {}) {
+  const rule = matchCodexModelRule(payload?.prompt, { provider: payload?.model_provider || codexProviderName(), ...opts, model: payload?.model, root: opts.root || payload?.cwd });
+  if (!rule) return null;
+  return `[Sprag model routing] This request matches the approved ${rule.category} rule: delegate the bounded task to model ${rule.model}`
+    + (rule.effort ? ` with reasoning_effort ${rule.effort}` : '')
+    + '. Use the available native Codex subagent tool and a built-in role. Wait for its result, verify it, and report unfinished work. '
+    + 'Do not spawn another CLI process. If subagent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
+}
+
+function customRole(role, root, home) {
+  // Custom role files override an explicit spawn model. Leave those calls alone.
+  const layers = new Set([home]);
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    layers.add(join(dir, '.codex'));
+    if (dirname(dir) === dir) break;
+  }
+  for (const layer of layers) {
+    try {
+      const cfg = parse(readFileSync(join(layer, 'config.toml'), 'utf8'));
+      if (Object.hasOwn(cfg.agents || {}, role)) return true;
+    } catch (e) { if (e.code !== 'ENOENT') return true; }
+    const dir = join(layer, 'agents');
+    let names;
+    try { names = readdirSync(dir); } catch (e) { if (e.code === 'ENOENT') continue; return true; }
+    for (const name of names.filter((n) => n.endsWith('.toml'))) {
+      try { if (parse(readFileSync(join(dir, name), 'utf8')).name === role) return true; }
+      catch { return true; }
+    }
+  }
+  return false;
+}
+
+export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules, dir = userDataDir(), record = recordCodexDelegation } = {}) {
+  if (cfg.codex?.delegate !== true) return null;
+  const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
+  if (!['spawn_agent', 'Agent'].includes(tool)) return null;
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object' || Array.isArray(input) || typeof input.message !== 'string' || !input.message.trim() || input.message.includes(MARKER)) return null;
+  const role = input.agent_type || 'default';
+  if (!['default', 'worker', 'explorer'].includes(role) || customRole(role, payload.cwd || root, home)) return null;
+  const explicit = Object.hasOwn(input, 'model');
+  const provider = payload.model_provider || codexProviderName({ home });
+  const rule = explicit ? null : matchCodexModelRule(input.message, { model: payload.model, provider, root, rules });
+  const target = rule || (!explicit && cfg.codex?.delegateTarget);
+  const updatedInput = { ...input };
+  let routeLine = '';
+  if (target) {
+    validateCodexTarget(target.model, target.effort);
+    updatedInput.model = target.model;
+    if (target.effort !== undefined && !Object.hasOwn(input, 'reasoning_effort')) updatedInput.reasoning_effort = target.effort;
+    // Only a route Sprag applied, with a known parent, can be credited later.
+    if (safeId(payload.model) && payload.model !== target.model) {
+      const id = newRouteId();
+      try {
+        record({ id, parentSessionId: typeof payload.session_id === 'string' ? payload.session_id : null,
+          source: rule ? 'rule' : 'default', category: rule?.category ?? null, scope: rule?.scope ?? null,
+          from: payload.model, to: target.model, provider, effort: updatedInput.reasoning_effort ?? null }, { dir });
+        routeLine = `\n<!-- sprag:codex:route id=${id} -->`;
+      } catch { /* Accounting is optional; the route itself still applies. */ }
+    }
+  }
+  updatedInput.message += `\n\n${MARKER}${routeLine}\nStay within the assigned task and requested output shape. Back findings with file references or actual command results. State what you could not verify. Honor caller-provided limits; do not invent a budget or assume the parent's model tier. Stop and report partial work when a limit or unavailable dependency prevents completion. Do not recursively delegate this bounded task.`;
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', updatedInput } };
+}

package/src/codex-doc2md-ledger.js

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, realpathSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+import { codexUserDir } from './agent.js';
+import { userDataDir } from './paths.js';
+
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const ledgerDir = ({ home = codexUserDir(), dir = userDataDir() } = {}) => join(dir, 'codex-doc2md', hash(resolve(home)));
+const finite = (n) => Number.isSafeInteger(n) && n >= 0;
+
+// One file per source avoids lost updates when parallel hooks prepare documents.
+export function recordCodexDocument(source, result, opts) {
+  if (!result?.ok) return;
+  try {
+    const dir = ledgerDir(opts);
+    const file = join(dir, `${hash(realpathSync(source))}.json`);
+    const meta = result.meta || {};
+    const event = { version: 1, ext: extname(source).slice(1).toLowerCase(),
+      sourceBytes: finite(meta.size) ? meta.size : null,
+      markdownBytes: finite(meta.markdownBytes) ? meta.markdownBytes : null,
+      clipped: !!(meta.clipped || meta.truncated) };
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(event) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+  } catch { /* Accounting must not prevent document conversion. */ }
+}
+
+export function codexDocumentTotals(opts) {
+  const total = { docs: 0, byExt: [], scope: 'codex-total' };
+  const byExt = new Map();
+  try {
+    const dir = ledgerDir(opts);
+    for (const file of readdirSync(dir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))) {
+      try {
+        const event = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+        if (event?.version !== 1 || !['pdf', 'pptx', 'xlsx', 'xls', 'docx', 'fig'].includes(event.ext)) continue;
+        total.docs++;
+        byExt.set(event.ext, (byExt.get(event.ext) || 0) + 1);
+      } catch { /* Ignore only the damaged record. */ }
+    }
+  } catch { /* No Codex document history yet. */ }
+  total.byExt = [...byExt].map(([ext, docs]) => ({ ext, docs })).sort((a, b) => b.docs - a.docs || a.ext.localeCompare(b.ext));
+  return total;
+}