pi-cost 0.1.0 → 0.2.0

package/lib/net-guard.js

@@ -0,0 +1,178 @@
+'use strict';
+
+// Network boundary for a local-only server, adapted from claude-code-cost.
+//
+// Binding loopback stops LAN peers. Two attacks still reach a loopback bind:
+//   * DNS rebinding: a page on evil.com re-resolves its name to 127.0.0.1 and reads the API
+//     same-origin. Only the Host header differs, and script cannot forge it, so Host is allowlisted.
+//   * CSRF: evil.com POSTs straight at 127.0.0.1. Host is real, so state-changing methods also need
+//     a loopback Origin (or no Origin and no cross-site Sec-Fetch-Site).
+//
+// pi-kanban frames this page from its own loopback port, which is dynamic, so any loopback port
+// may frame it and X-Frame-Options (which has no multi-origin form) is not sent.
+
+const http = require('node:http');
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0:0:0:0:0:0:0:1', '::ffff:127.0.0.1']);
+const PORT_RE = /^[0-9]{1,5}$/;
+const validPort = (p) => PORT_RE.test(p) && Number(p) >= 1 && Number(p) <= 65535;
+const KEEP_ALIVE_MS = 65000;
+// A whole IPv4 literal: a prefix test would let a rebinding name like 127.evil.com through.
+const LOOPBACK_V4_RE = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+// Chrome rejects an IPv6 literal as a frame-ancestors source.
+const FRAME_CSP = "frame-ancestors 'self' http://localhost:* http://127.0.0.1:*";
+
+function isLoopbackAddress(host) {
+  if (!host) return false;
+  const h = String(host).toLowerCase().replace(/^\[(.*)\]$/, '$1');
+  return LOOPBACK_HOSTS.has(h) || LOOPBACK_V4_RE.test(h);
+}
+
+// Hand-parsed: new URL() accepts far more than a real client sends. Returns the lowercased
+// hostname, or null when malformed. The port is not compared, because a busy port falls back to a
+// random one.
+function parseHostHeader(value) {
+  if (typeof value !== 'string') return null;
+  const raw = value.trim();
+  if (!raw || raw.length > 259) return null;
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f) return null;
+  }
+  if (raw.includes('@')) return null;
+
+  let host;
+  if (raw.startsWith('[')) {
+    const end = raw.indexOf(']');
+    if (end === -1) return null;
+    host = raw.slice(1, end);
+    const rest = raw.slice(end + 1);
+    if (rest && !(rest.startsWith(':') && validPort(rest.slice(1)))) return null;
+  } else {
+    const parts = raw.split(':');
+    if (parts.length > 2) return null;
+    host = parts[0];
+    if (parts.length === 2 && !validPort(parts[1])) return null;
+  }
+  if (host.endsWith('.')) host = host.slice(0, -1);
+  if (!host) return null;
+  return host.toLowerCase();
+}
+
+function parseList(value) {
+  return String(value || '').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+
+/**
+ * @param {{appName?: string, bindHost?: string, allowedHosts?: string}} [config]
+ */
+function createNetGuard(config = {}) {
+  const appName = config.appName || 'This app';
+  const BIND_HOST = config.bindHost || '127.0.0.1';
+  const BIND_HOST_LC = BIND_HOST.toLowerCase();
+  const EXPOSED = !isLoopbackAddress(BIND_HOST);
+  const extraHosts = new Set(parseList(config.allowedHosts));
+  let actualPort = null;
+
+  function hostAllowed(host) {
+    if (!host) return false;
+    if (isLoopbackAddress(host) || extraHosts.has(host)) return true;
+    return EXPOSED && host === BIND_HOST_LC;
+  }
+
+  function hostGuard(req, res, next) {
+    const host = parseHostHeader(req.headers.host);
+    if (hostAllowed(host)) return next();
+    res.status(403).type('text/plain').send(
+      `403 Forbidden - unrecognized Host header: ${req.headers.host || '(none)'}\n\n` +
+      `${appName} only answers requests addressed to localhost. This protects you from DNS\n` +
+      `rebinding, where a website re-points its own hostname at 127.0.0.1 to read local data.\n\n` +
+      `To reach it from another machine, restart with:\n` +
+      `  --host 0.0.0.0 --allowed-hosts=${host || '<your-hostname>'}\n\n` +
+      `Only do that on a network you trust - there is no authentication.\n`,
+    );
+  }
+
+  // true = allow, false = block, null = no Origin header.
+  function originVerdict(origin) {
+    if (!origin || origin === 'null') return null;
+    let parsed;
+    try { parsed = new URL(origin); } catch { return false; }
+    if (!isLoopbackAddress(parsed.hostname)) return false;
+    // A different local port is a different app and has no business driving this one.
+    if (actualPort && parsed.port && Number(parsed.port) !== Number(actualPort)) return false;
+    return true;
+  }
+
+  function originGuard(req, res, next) {
+    if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next();
+    const verdict = originVerdict(req.headers.origin);
+    if (verdict === true) return next();
+    if (verdict === false) {
+      return res.status(403).type('text/plain')
+        .send(`403 Forbidden - cross-origin ${req.method} from ${req.headers.origin} is not allowed.\n`);
+    }
+    // No Origin: a non-browser client (curl, the CLI). Trust it unless the browser says otherwise.
+    const site = req.headers['sec-fetch-site'];
+    if (site && site !== 'same-origin' && site !== 'none') {
+      return res.status(403).type('text/plain')
+        .send(`403 Forbidden - cross-site ${req.method} (Sec-Fetch-Site: ${site}) is not allowed.\n`);
+    }
+    return next();
+  }
+
+  function frameGuard(_req, res, next) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('Content-Security-Policy', FRAME_CSP);
+    next();
+  }
+
+  /**
+   * Bind BIND_HOST, then serve the other loopback family on the same port, so
+   * http://localhost:<port> works whichever family the resolver returns first. A family the host
+   * does not have is skipped. If another process holds the port on the other family, the primary
+   * closes and emits EADDRINUSE, because that process would answer localhost:<port> in our name.
+   * @returns {http.Server} the primary server; attach the 'error' handler to it.
+   */
+  function listenLoopback(app, port, onReady, opts = {}) {
+    const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
+    const makeServer = () => {
+      const s = http.createServer(serverOpts, app);
+      s.keepAliveTimeout = KEEP_ALIVE_MS;
+      return s;
+    };
+    const server = makeServer();
+    let secondary = null;
+    let randomTries = 0;
+
+    server.on('listening', () => {
+      const boundPort = server.address().port;
+      actualPort = boundPort;
+      const ready = () => { if (onReady) onReady(boundPort); };
+      if (EXPOSED) return ready();
+      const otherFamily = BIND_HOST.includes(':') ? '127.0.0.1' : '::1';
+      secondary = makeServer();
+      secondary.once('listening', ready);
+      secondary.on('error', (err) => {
+        if (err.code !== 'EADDRINUSE') return ready();
+        if (port === 0 && ++randomTries < 5) return server.close(() => server.listen(0, BIND_HOST));
+        server.close();
+        server.emit('error', err);
+      });
+      secondary.listen({ host: otherFamily, port: boundPort, ipv6Only: otherFamily === '::1' });
+    });
+    server.on('close', () => { if (secondary) secondary.close(() => {}); });
+
+    server.listen(port, BIND_HOST);
+    return server;
+  }
+
+  function exposureWarning() {
+    return EXPOSED ? `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.` : null;
+  }
+
+  return { BIND_HOST, EXPOSED, hostGuard, originGuard, frameGuard, listenLoopback, exposureWarning };
+}
+
+module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress, FRAME_CSP, KEEP_ALIVE_MS };

package/lib/pi-parsers-cost.js

@@ -5,89 +5,214 @@ const path = require('node:path');
 const os = require('node:os');
 const readline = require('node:readline');
 
-const PI_DIR = process.env.PI_DIR || path.join(os.homedir(), '.pi');
-const SESSIONS_DIR = path.join(PI_DIR, 'agent', 'sessions');
+const ENV_SESSION_DIR = 'PI_CODING_AGENT_SESSION_DIR';
 
-function getPiDir() { return PI_DIR; }
-function getSessionsDir() { return SESSIONS_DIR; }
+// libuv aborts on a watched Windows path that holds an 8.3 short name (NIKIFO~1), because events
+// come back with the long name. Resolve the deepest existing ancestor and re-append the rest.
+function longPath(target) {
+  let cur = path.resolve(target);
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native(cur);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.resolve(target);
+      tail.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+const pathKeys = new Map();
+const PATH_KEYS_MAX = 20_000;
+
+// Comparison key for a file path. pi records paths as it was given them, which may hold 8.3 short
+// names (NIKIFO~1) while listings are long; a short name always has a `~`, so only those hit the disk.
+function pathKey(p) {
+  if (!p) return '';
+  let key = pathKeys.get(p);
+  if (key !== undefined) return key;
+  key = p.includes('~') ? longPath(p) : path.resolve(p);
+  if (process.platform === 'win32') key = key.toLowerCase();
+  if (pathKeys.size >= PATH_KEYS_MAX) pathKeys.clear();
+  pathKeys.set(p, key);
+  return key;
+}
+
+// pi's normalizePath: Git Bash / Cygwin / WSL drive paths on Windows, then ~.
+function normalizePiPath(p) {
+  let s = String(p).trim();
+  if (process.platform === 'win32' && s.startsWith('/') && !s.startsWith('//') && !s.includes('\\')) {
+    const m = s.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+    if (m) s = `${m[1].toUpperCase()}:\\${(m[2] || '').replaceAll('/', '\\')}`;
+  }
+  if (s === '~') return os.homedir();
+  if (/^~[\\/]/.test(s)) return path.join(os.homedir(), s.slice(2));
+  return s;
+}
+
+// Same rule as pi's getAgentDir: PI_CODING_AGENT_DIR, else <PI_DIR>/agent with PI_DIR defaulting to ~/.pi.
+function rawAgentDir(env) {
+  if (env.PI_CODING_AGENT_DIR) return normalizePiPath(env.PI_CODING_AGENT_DIR);
+  return path.join(env.PI_DIR || path.join(os.homedir(), '.pi'), 'agent');
+}
+
+function readSettingsSessionDir(agentDir) {
+  try {
+    const dir = JSON.parse(fs.readFileSync(path.join(agentDir, 'settings.json'), 'utf8'))?.sessionDir;
+    return typeof dir === 'string' && dir.trim() ? normalizePiPath(dir) : null;
+  } catch {
+    return null;
+  }
+}
+
+// pi's precedence: --session-dir, then PI_CODING_AGENT_SESSION_DIR, then settings.sessionDir. A
+// custom dir is flat (<dir>/<ts>_<id>.jsonl). The default nested dir stays in the list, because
+// sessions written before a custom dir was set are still there. pi resolves a relative settings
+// dir against the cwd of each pi run, which pi-cost does not know, so only an absolute one counts.
+function resolveRoots({ env = process.env, sessionDir = null, cwd = process.cwd() } = {}) {
+  const agentDir = longPath(rawAgentDir(env));
+  const nested = { dir: longPath(path.join(agentDir, 'sessions')), flat: false };
+  const forced = sessionDir || env[ENV_SESSION_DIR];
+  const fromSettings = forced ? null : readSettingsSessionDir(agentDir);
+  const custom = forced ? path.resolve(cwd, normalizePiPath(forced))
+    : fromSettings && path.isAbsolute(fromSettings) ? fromSettings : null;
+  const roots = [];
+  if (custom) {
+    const dir = longPath(custom);
+    if (pathKey(dir) !== pathKey(nested.dir)) roots.push({ dir, flat: true });
+  }
+  roots.push(nested);
+  return { agentDir, roots };
+}
+
+let config = resolveRoots();
+
+function configure(opts) {
+  config = resolveRoots(opts);
+  sessionCache.clear();
+  headerCache.clear();
+}
+
+function getPiDir() { return path.dirname(config.agentDir); }
+function getAgentDir() { return config.agentDir; }
+function getCostDir() { return path.join(config.agentDir, 'cost'); }
+function getSessionsDir() { return config.roots[0].dir; }
+function getSessionRoots() { return config.roots; }
+
+function encodeProjectDir(cwd) {
+  return `--${String(cwd).replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+}
 
-// "--C--Users-nikiforovall-dev-pi--" -> "C:\Users\nikiforovall\dev\pi"
+// Lossy: a dash inside a folder name reads back as a separator. Prefer the header cwd.
 function decodeProjectDir(name) {
   let s = name;
   if (s.startsWith('--')) s = s.slice(2);
   if (s.endsWith('--')) s = s.slice(0, -2);
   const m = s.match(/^([A-Za-z])--(.+)$/);
   if (m) return `${m[1]}:\\${m[2].replace(/-/g, '\\')}`;
-  return s.replace(/-/g, path.sep);
+  return `/${s.replace(/-/g, '/')}`;
 }
 
-async function listSessionFiles() {
-  let projDirs;
-  try { projDirs = await fs.promises.readdir(SESSIONS_DIR, { withFileTypes: true }); }
+const HEADER_MAX = 64 * 1024;
+const headerCache = new Map();
+
+async function readSessionHeader(file) {
+  if (headerCache.has(file)) return headerCache.get(file);
+  let header = null;
+  let fh;
+  try {
+    fh = await fs.promises.open(file, 'r');
+    const buf = Buffer.alloc(HEADER_MAX);
+    const { bytesRead } = await fh.read(buf, 0, HEADER_MAX, 0);
+    const nl = buf.subarray(0, bytesRead).indexOf(0x0a);
+    const obj = JSON.parse(buf.toString('utf8', 0, nl === -1 ? bytesRead : nl));
+    if (obj && obj.type === 'session' && obj.id) header = obj;
+  } catch {
+    header = null;
+  } finally {
+    if (fh) await fh.close().catch(() => {});
+  }
+  if (header) headerCache.set(file, header);
+  return header;
+}
+
+async function readdirSafe(dir) {
+  try { return await fs.promises.readdir(dir, { withFileTypes: true }); }
   catch { return []; }
-  const projects = projDirs.filter((d) => d.isDirectory());
-  const perProject = await Promise.all(projects.map(async (d) => {
-    const projDir = d.name;
-    const projPath = path.join(SESSIONS_DIR, projDir);
-    let files;
-    try { files = await fs.promises.readdir(projPath, { withFileTypes: true }); }
-    catch { return []; }
-    const jsonls = files.filter((f) => f.isFile() && f.name.endsWith('.jsonl'));
-    const stats = await Promise.all(jsonls.map(async (f) => {
-      const full = path.join(projPath, f.name);
-      try {
-        const s = await fs.promises.stat(full);
-        return { file: full, projectDir: projDir, cwd: decodeProjectDir(projDir), mtime: s.mtime, mtimeMs: s.mtimeMs, size: s.size };
-      } catch { return null; }
-    }));
-    return stats.filter(Boolean);
+}
+
+async function statJsonls(dir) {
+  const entries = await readdirSafe(dir);
+  const out = await Promise.all(entries.filter((f) => f.isFile() && f.name.endsWith('.jsonl')).map(async (f) => {
+    const file = path.join(dir, f.name);
+    try {
+      const s = await fs.promises.stat(file);
+      return { file, mtime: s.mtime, mtimeMs: s.mtimeMs, size: s.size };
+    } catch { return null; }
   }));
-  return perProject.flat();
+  return out.filter(Boolean);
 }
 
-// Nested subagent JSONLs live under <projectDir>/<parentSessionId>/<runId>/run-N/session.jsonl.
-// Cost is already accounted for inline in the parent's `subagent` toolResult; we list
-// them separately so the UI can drill into a specific run.
-async function listNestedSubagentFiles() {
-  let projDirs;
-  try { projDirs = await fs.promises.readdir(SESSIONS_DIR, { withFileTypes: true }); }
-  catch { return []; }
-  const out = [];
-  await Promise.all(projDirs.filter((d) => d.isDirectory()).map(async (proj) => {
-    const projPath = path.join(SESSIONS_DIR, proj.name);
-    let parentDirs;
-    try { parentDirs = await fs.promises.readdir(projPath, { withFileTypes: true }); }
-    catch { return; }
-    await Promise.all(parentDirs.filter((d) => d.isDirectory()).map(async (parent) => {
-      const parentPath = path.join(projPath, parent.name);
-      let runDirs;
-      try { runDirs = await fs.promises.readdir(parentPath, { withFileTypes: true }); }
-      catch { return; }
-      await Promise.all(runDirs.filter((d) => d.isDirectory()).map(async (run) => {
-        const runPath = path.join(parentPath, run.name);
-        let attempts;
-        try { attempts = await fs.promises.readdir(runPath, { withFileTypes: true }); }
-        catch { return; }
-        await Promise.all(attempts.filter((d) => d.isDirectory()).map(async (attempt) => {
-          const file = path.join(runPath, attempt.name, 'session.jsonl');
-          try {
-            const s = await fs.promises.stat(file);
-            out.push({
-              file,
-              projectDir: proj.name,
-              parentDirName: parent.name,
-              runId: run.name,
-              attempt: attempt.name,
-              mtime: s.mtime, mtimeMs: s.mtimeMs, size: s.size,
-            });
-          } catch {}
-        }));
-      }));
+// In a flat dir the project comes from the header cwd; in the nested dir from the folder name.
+async function withProject(f, projectDirName) {
+  if (projectDirName) return { ...f, projectDir: projectDirName, cwd: decodeProjectDir(projectDirName) };
+  const header = await readSessionHeader(f.file);
+  if (!header || !header.cwd) return null;
+  return { ...f, projectDir: encodeProjectDir(header.cwd), cwd: header.cwd };
+}
+
+async function listSessionFiles() {
+  const perRoot = await Promise.all(config.roots.map(async (root) => {
+    if (root.flat) {
+      const files = await statJsonls(root.dir);
+      return Promise.all(files.map((f) => withProject(f, null)));
+    }
+    const projects = (await readdirSafe(root.dir)).filter((d) => d.isDirectory());
+    const perProject = await Promise.all(projects.map(async (d) => {
+      const files = await statJsonls(path.join(root.dir, d.name));
+      return Promise.all(files.map((f) => withProject(f, d.name)));
     }));
+    return perProject.flat();
   }));
+  return perRoot.flat().filter(Boolean);
+}
+
+async function subdirs(dir) {
+  return (await readdirSafe(dir)).filter((d) => d.isDirectory()).map((d) => path.join(dir, d.name));
+}
+
+// pi-subagents writes <dir of parent jsonl>/<parent basename>/<runId>/<attempt>/session.jsonl.
+// Their cost is already in the parent's `subagent` toolResult; they are listed so a run can be opened.
+async function nestedUnder(parentsDir, projectDirName) {
+  const out = [];
+  for (const parent of await subdirs(parentsDir)) {
+    for (const run of await subdirs(parent)) {
+      for (const attempt of await subdirs(run)) {
+        const file = path.join(attempt, 'session.jsonl');
+        try {
+          const s = await fs.promises.stat(file);
+          const base = { file, parentDirName: path.basename(parent), runId: path.basename(run), attempt: path.basename(attempt), mtime: s.mtime, mtimeMs: s.mtimeMs, size: s.size };
+          const withProj = await withProject(base, projectDirName);
+          if (withProj) out.push(withProj);
+        } catch {}
+      }
+    }
+  }
   return out;
 }
 
+async function listNestedSubagentFiles() {
+  const perRoot = await Promise.all(config.roots.map(async (root) => {
+    if (root.flat) return nestedUnder(root.dir, null);
+    const projects = await subdirs(root.dir);
+    return (await Promise.all(projects.map((p) => nestedUnder(p, path.basename(p))))).flat();
+  }));
+  return perRoot.flat();
+}
+
 async function readJsonlLines(file) {
   return new Promise((resolve, reject) => {
     const lines = [];
@@ -96,6 +221,7 @@ async function readJsonlLines(file) {
     rl.on('line', (l) => { if (l.trim()) lines.push(l); });
     rl.on('close', () => resolve(lines));
     rl.on('error', reject);
+    stream.on('error', reject);
   });
 }
 
@@ -171,7 +297,7 @@ function summarize(entries) {
         userCount++;
         if (!firstUserText) {
           const c = m.content;
-          const txt = Array.isArray(c) ? c.find((x) => x && x.type === 'text')?.text : null;
+          const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.find((x) => x && x.type === 'text')?.text : null;
           if (txt) firstUserText = txt;
         }
       } else if (m.role === 'assistant') {
@@ -230,7 +356,13 @@ function invalidateSessionCache(file) {
   else sessionCache.clear();
 }
 
-// Yields { ts, provider, model, usage, messageId } per assistant message with usage.
+function toolNames(content) {
+  if (!Array.isArray(content)) return [];
+  return content.filter((b) => b && b.type === 'toolCall' && b.name).map((b) => b.name);
+}
+
+// Yields one usage row per assistant message and per compaction that recorded its summarizer usage.
+// A compaction has no model of its own, so it takes the model in effect at that point.
 function* enumerateMessageUsages(entries) {
   let provider = null;
   let model = null;
@@ -240,9 +372,23 @@ function* enumerateMessageUsages(entries) {
       model = e.modelId || model;
       continue;
     }
+    if (e.type === 'compaction') {
+      if (!e.usage) continue;
+      yield {
+        ts: e.timestamp || null,
+        provider,
+        model,
+        usage: e.usage,
+        messageId: e.id || null,
+        compaction: { tokensBefore: e.tokensBefore || 0, fromHook: !!e.fromHook },
+      };
+      continue;
+    }
     if (e.type !== 'message') continue;
     const m = e.message || {};
     if (m.role !== 'assistant') continue;
+    if (m.provider) provider = m.provider;
+    if (m.model) model = m.model;
     const u = m.usage;
     if (!u) continue;
     yield {
@@ -251,10 +397,20 @@ function* enumerateMessageUsages(entries) {
       model: m.model || model,
       usage: u,
       messageId: e.id || null,
+      tools: toolNames(m.content),
+      durationMs: m.durationMs || null,
     };
   }
 }
 
+// Compactions without recorded usage still matter to the timeline, so they are listed apart.
+function* enumerateCompactions(entries) {
+  for (const e of entries) {
+    if (e.type !== 'compaction') continue;
+    yield { ts: e.timestamp || null, tokensBefore: e.tokensBefore || 0, fromHook: !!e.fromHook, hasUsage: !!e.usage, id: e.id || null };
+  }
+}
+
 // Yields { ts, agent, task, model, usage, runId, jsonlPath } per subagent run.
 // pi records subagent invocations as `subagent` tool results in the parent's
 // JSONL; each `details.results[]` entry is one run with its own usage block.
@@ -282,9 +438,20 @@ function* enumerateSubagentRuns(entries) {
 }
 
 module.exports = {
+  ENV_SESSION_DIR,
+  resolveRoots,
+  configure,
+  longPath,
+  pathKey,
+  normalizePiPath,
   getPiDir,
+  getAgentDir,
+  getCostDir,
   getSessionsDir,
+  getSessionRoots,
+  encodeProjectDir,
   decodeProjectDir,
+  readSessionHeader,
   listSessionFiles,
   listNestedSubagentFiles,
   readSessionEntriesUncached,
@@ -292,6 +459,7 @@ module.exports = {
   getCachedSession,
   invalidateSessionCache,
   enumerateMessageUsages,
+  enumerateCompactions,
   enumerateSubagentRuns,
   slugFromFile,
 };

package/lib/pi-pricing.js

@@ -50,9 +50,17 @@ let cachedPricing = null;
 let pricingFetchedAt = 0;
 let pricingSource = 'none';
 
+function useOffline(now) {
+  cachedPricing = new Map(Object.entries(OFFLINE_PRICING));
+  pricingFetchedAt = now;
+  pricingSource = 'offline';
+  return cachedPricing;
+}
+
 async function fetchPricing() {
   const now = Date.now();
   if (cachedPricing && (now - pricingFetchedAt) < PRICING_REFRESH_MS) return cachedPricing;
+  if (process.env.PI_COST_OFFLINE === '1') return useOffline(now);
   try {
     const resp = await fetch(LITELLM_PRICING_URL);
     if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
@@ -67,16 +75,10 @@ async function fetchPricing() {
     cachedPricing = pricing;
     pricingFetchedAt = now;
     pricingSource = 'litellm';
-    console.log(`[pi-cost pricing] loaded ${pricing.size} models from LiteLLM`);
     return pricing;
   } catch (err) {
     console.warn('[pi-cost pricing] fetch failed, using offline fallback:', err.message);
-    if (!cachedPricing) {
-      cachedPricing = new Map(Object.entries(OFFLINE_PRICING));
-      pricingFetchedAt = now;
-      pricingSource = 'offline';
-    }
-    return cachedPricing;
+    return cachedPricing || useOffline(now);
   }
 }
 
@@ -101,8 +103,19 @@ function lookupExact(pricing, key) {
   return null;
 }
 
+// The fuzzy step scans the whole LiteLLM map, so each (provider, model) resolves once per map.
+const resolveMemo = new WeakMap();
+
 function resolveKey(pricing, provider, modelId) {
   if (!pricing || !modelId) return null;
+  let memo = resolveMemo.get(pricing);
+  if (!memo) resolveMemo.set(pricing, (memo = new Map()));
+  const memoKey = `${provider || ''}\0${modelId}`;
+  if (!memo.has(memoKey)) memo.set(memoKey, resolveKeyUncached(pricing, provider, modelId));
+  return memo.get(memoKey);
+}
+
+function resolveKeyUncached(pricing, provider, modelId) {
   const candidates = piIdNormalizations(modelId);
   const providerLower = provider ? String(provider).toLowerCase() : null;
   const isRouting = providerLower ? PI_ROUTING_PROVIDERS.has(providerLower) : false;
@@ -194,4 +207,18 @@ function estimate(pricing, provider, modelId, usage) {
   return { cost, source: 'pricing', modelKey: match.key };
 }
 
-module.exports = { fetchPricing, refresh, getMeta, estimate, resolveKey };
+// What one cache-read token saved against fresh input. pi's own cost split wins over LiteLLM
+// because it reflects the provider pi actually billed through.
+function cacheReadSaving(pricing, provider, modelId, usage) {
+  const read = usage?.cacheRead || 0;
+  if (read <= 0) return 0;
+  const c = usage.cost;
+  if (c && usage.input > 0 && c.input > 0 && typeof c.cacheRead === 'number') {
+    return read * (c.input / usage.input - c.cacheRead / read);
+  }
+  const info = resolveKey(pricing, provider, modelId)?.info;
+  if (info?.input_cost_per_token == null || info?.cache_read_input_token_cost == null) return 0;
+  return read * (info.input_cost_per_token - info.cache_read_input_token_cost);
+}
+
+module.exports = { fetchPricing, refresh, getMeta, estimate, resolveKey, cacheReadSaving };