claude-token-saver 3.44.0 → 3.55.0

package/presets/model-rules.json

@@ -21,7 +21,10 @@
       "agent": "haiku-runner",
       "example": "npm test 돌려봐",
       "exampleEn": "run npm test",
-      "budget": { "calls": 8, "out": 1500 }
+      "budget": {
+        "calls": 8,
+        "out": 1500
+      }
     },
     {
       "id": "run-t1",
@@ -32,7 +35,10 @@
       "agent": "sonnet",
       "example": "빌드하고 실패한 테스트만 보여줘",
       "exampleEn": "build it and show only the failing tests",
-      "budget": { "calls": null, "out": 6000 }
+      "budget": {
+        "calls": null,
+        "out": 6000
+      }
     },
     {
       "id": "explore-t2",
@@ -43,7 +49,10 @@
       "agent": "haiku-explore",
       "example": "이 설정값 어느 파일에 있어?",
       "exampleEn": "which file holds this config value?",
-      "budget": { "calls": 8, "out": 1500 }
+      "budget": {
+        "calls": 8,
+        "out": 1500
+      }
     },
     {
       "id": "explore-t1",
@@ -54,7 +63,10 @@
       "agent": "sonnet",
       "example": "이 함수를 호출하는 곳 전부 찾아줘",
       "exampleEn": "find every caller of this function",
-      "budget": { "calls": null, "out": 6000 }
+      "budget": {
+        "calls": null,
+        "out": 6000
+      }
     },
     {
       "id": "check-t2",
@@ -65,7 +77,10 @@
       "agent": "haiku-explore",
       "example": "지금 배포된 버전이 뭔지 확인해줘",
       "exampleEn": "check which version is deployed right now",
-      "budget": { "calls": 8, "out": 1500 }
+      "budget": {
+        "calls": 8,
+        "out": 1500
+      }
     },
     {
       "id": "check-t1",
@@ -76,7 +91,10 @@
       "agent": "sonnet",
       "example": "마이그레이션이 실제로 적용됐는지 확인해줘",
       "exampleEn": "verify the migration actually applied",
-      "budget": { "calls": null, "out": 6000 }
+      "budget": {
+        "calls": null,
+        "out": 6000
+      }
     },
     {
       "id": "paste-t2",
@@ -87,7 +105,10 @@
       "agent": "haiku-explore",
       "example": "이 에러 로그는 무슨 뜻이야?",
       "exampleEn": "what does this error log mean?",
-      "budget": { "calls": 8, "out": 1500 }
+      "budget": {
+        "calls": 8,
+        "out": 1500
+      }
     },
     {
       "id": "paste-t1",
@@ -98,7 +119,10 @@
       "agent": "sonnet",
       "example": "이 스택트레이스에서 어느 모듈이 죽은 건지 짚어줘",
       "exampleEn": "point out which module failed in this stack trace",
-      "budget": { "calls": null, "out": 8000 }
+      "budget": {
+        "calls": null,
+        "out": 8000
+      }
     },
     {
       "id": "read-t2",
@@ -109,7 +133,24 @@
       "agent": "haiku-explore",
       "example": "이 README 요약해줘",
       "exampleEn": "summarize this README",
-      "budget": { "calls": 8, "out": 1900 }
+      "budget": {
+        "calls": 8,
+        "out": 1900
+      }
+    },
+    {
+      "id": "read-t1",
+      "tier": "T1",
+      "category": "read",
+      "label": "읽기·요약·설명",
+      "labelEn": "reading / summarizing / explaining",
+      "agent": "sonnet",
+      "example": "이 함수가 하는 일을 단계별로 정리해줘",
+      "exampleEn": "walk through what this function does, step by step",
+      "budget": {
+        "calls": null,
+        "out": 8000
+      }
     }
   ]
 }

package/presets/ratchet-rules.json

@@ -32,7 +32,10 @@
     },
     {
       "ko": "탐색·조회·상태 확인·명령 실행 같은 단순 요청은 `model: haiku` 서브에이전트로 위임해 상위 모델 토큰을 아낀다 (읽기 전용 preset 에이전트가 이미 있으면 그걸 쓰고, 없으면 티어만 내려서 위임)",
-      "en": "Delegate simple requests — lookup, status checks, running commands — to a `model: haiku` subagent to keep the expensive model's tokens for real work (use an existing read-only preset agent when there is one; otherwise delegate with the tier lowered)"
+      "en": "Delegate simple requests — lookup, status checks, running commands — to a `model: haiku` subagent to keep the expensive model's tokens for real work (use an existing read-only preset agent when there is one; otherwise delegate with the tier lowered)",
+      "agents": [
+        "claude"
+      ]
     },
     {
       "ko": "지침이나 룰이 지켜지지 않아 같은 품질 문제가 재발하면 문구를 다시 쓰지 말 것 → 그 조항이 기계로 판정 가능한지부터 따지고(문자열 비교나 정규식으로 결정되면 판정 가능), 가능하면 쓰기 시점 훅이나 테스트 같은 차단 지점을 추가한다. 판단이 필요한 잔여 부분만 지침에 남기고 그 경계를 지침에 적는다. 실제 코퍼스에 돌려 오탐 건수를 센 뒤 좁히고, 회귀 테스트를 같은 커밋에 넣는다",

package/src/agent.js

@@ -0,0 +1,33 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { parse } from 'smol-toml';
+
+export function codexUserDir() {
+  return process.env.CODEX_HOME ? resolve(process.env.CODEX_HOME) : join(homedir(), '.codex');
+}
+
+export function codexProviderName({ home = codexUserDir() } = {}) {
+  try {
+    const cfg = parse(readFileSync(join(home, 'config.toml'), 'utf8'));
+    return cfg.profiles?.[cfg.profile]?.model_provider || cfg.model_provider || 'openai';
+  } catch (e) { return e.code === 'ENOENT' ? 'openai' : null; }
+}
+
+/** Remove the global selector before positional subcommand parsers see it. */
+export function selectAgent(argv) {
+  const args = [];
+  let agent = 'claude';
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') { args.push(...argv.slice(i)); break; }
+    if (arg === '--agent' || arg.startsWith('--agent=')) {
+      const value = arg === '--agent' ? argv[++i] : arg.slice('--agent='.length);
+      if (!['claude', 'codex'].includes(value)) {
+        throw new Error('--agent expects claude or codex');
+      }
+      agent = value;
+    } else args.push(arg);
+  }
+  return { agent, args };
+}

package/src/caps-cache.js

@@ -9,7 +9,7 @@
  * than `maxAgeMs` the loader returns null and the table view stays quiet.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 
@@ -38,7 +38,11 @@ export function persistSnapshot(snapshot) {
       caps: snapshot.caps || null,
       model: snapshot.model || null,
     };
-    writeFileSync(CACHE_PATH, JSON.stringify(payload) + '\n');
+    // tmp + rename: the statusline reads this every tick and must never see a
+    // half-written file.
+    const tmp = `${CACHE_PATH}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(payload) + '\n');
+    renameSync(tmp, CACHE_PATH);
   } catch {
     // best-effort cache, never blocks the statusline
   }

package/src/changelog.js

@@ -0,0 +1,70 @@
+/**
+ * changelog — read one version's section out of CHANGELOG.md, and say whether a
+ * notes draft is still waiting on a person.
+ *
+ * Separate from scripts/release-notes.mjs, which is a CLI: importing that file
+ * runs its argument parsing and exits, so the extraction it depends on cannot be
+ * tested through it. The boundary logic is the part worth pinning — a section
+ * pulled one line short drops the release's last item, and one line long carries
+ * the previous release's first, and the upgrade offer shows either without
+ * complaint.
+ *
+ * The draft marker lives here for a reason. Two scripts gate on it — the one that
+ * writes drafts and the one that deploys — and they used to carry the string
+ * separately. Renaming it in one left the other looking for text that no longer
+ * existed, and a gate that greps for an absent string does not fail: it passes,
+ * and an unreviewed draft goes out as the release. One definition, imported.
+ */
+
+/**
+ * The body of one version's section, heading excluded.
+ *
+ * @param {string} changelog - CHANGELOG.md contents
+ * @param {string} version - e.g. "3.45.0"
+ * @returns {string|null} the section text, or null when that version has none
+ */
+export function sectionFor(changelog, version) {
+  const lines = String(changelog).split(/\r?\n/);
+  // The version has to match to its end: without the boundary, "3.42.0" would
+  // also match the "### v3.42.7" heading and publish the wrong notes.
+  const head = new RegExp(`^### v${String(version).replace(/\./g, '\\.')}(\\s|$|\\()`);
+  const start = lines.findIndex((l) => head.test(l));
+  if (start < 0) return null;
+  const out = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    // The next version heading ends this section, and so does a shallower one:
+    // "## All releases" is a container, not part of any release.
+    if (/^### v/.test(lines[i]) || /^## /.test(lines[i])) break;
+    out.push(lines[i]);
+  }
+  return out.join('\n').trim();
+}
+
+/**
+ * The line `release-notes.mjs` writes at the top of a fresh draft, and the line
+ * every gate refuses on. A draft still carrying it has not been through a person.
+ */
+export const DRAFT_MARKER =
+  '<!-- REVIEW: edit this draft, add the English half, then delete this line -->';
+
+/** Heading that opens the Korean half of a bilingual release body. */
+export const KO_HEADING = '## 한국어';
+
+/**
+ * The opening of the marker, which is what the gate actually matches. Spelled out
+ * rather than sliced off `DRAFT_MARKER`, so that editing the marker's front does
+ * not silently change what is being tested for.
+ */
+const REVIEW_OPENING = '<!-- REVIEW:';
+
+/**
+ * Whether a draft still needs review. Matches on the `<!-- REVIEW:` opening
+ * rather than the whole line, so editing the wording of the instruction does not
+ * quietly disarm the gate.
+ *
+ * @param {string} draft - the draft file's contents
+ * @returns {boolean} true while the draft is unreviewed
+ */
+export function needsReview(draft) {
+  return String(draft || '').includes(REVIEW_OPENING);
+}

package/src/cli-name.js

@@ -0,0 +1,25 @@
+/**
+ * cli-name — the name this tool tells the user to type.
+ *
+ * One definition, because the alternative was measured: the marker string in the
+ * release scripts lived in two files, one was renamed, and the gate that grepped
+ * for the other silently stopped gating. A command name printed for the user to
+ * copy fails more quietly still — nothing errors, the user simply types a name
+ * that is not the package they installed.
+ *
+ * `sprag-cli` is the package; `claude-token-saver` is the deprecated name it
+ * shipped under, and both binaries are still in `package.json`'s `bin`, so the
+ * old name keeps working for anyone whose settings or notes carry it.
+ *
+ * NOT the same thing as the on-disk identifiers. The state directory, the harness
+ * block markers, and the skill directory are all still spelled with the old name
+ * on purpose: renaming those would orphan existing users' ledgers and stop the
+ * harness markers matching text already in their CLAUDE.md. Those are addresses,
+ * not instructions, and an address only has to be stable.
+ */
+
+/** The command name to print in anything a user is expected to type or read. */
+export const CLI_NAME = 'sprag';
+
+/** The deprecated name. Still a working binary; recognised, never printed. */
+export const LEGACY_CLI_NAME = 'claude-token-saver';

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;
+  };
+}