sprag-cli 3.40.0

package/src/subagent-records.js

@@ -0,0 +1,214 @@
+/**
+ * subagent-records — read the transcripts of subagent runs a session spawned.
+ *
+ * Why this exists: rule-health used to be a PROXY. It measured the error rate
+ * of episodes the expensive model handled DIRECTLY that merely *looked*
+ * delegable by shape — never the outcome of an actual delegation. So a rule
+ * could be quietly failing every time it fired and the signal would not move.
+ * Claude Code writes each subagent run to its own transcript, which makes the
+ * real outcome measurable:
+ *
+ *   ~/.claude/projects/<munged>/<sessionId>/subagents/agent-<id>.jsonl
+ *   ~/.claude/projects/<munged>/<sessionId>/subagents/agent-<id>.meta.json
+ *
+ * The .jsonl is byte-identical in shape to a main transcript (`isSidechain:
+ * true`, assistant entries carrying `message.model` + `message.usage`,
+ * tool_result blocks carrying `is_error`), so collectSessionRecords parses it
+ * unchanged — including the rejection / self-corrected error filters, which
+ * must apply here for the same reason they apply to main sessions.
+ *
+ * The .meta.json carries `{ agentType, description, toolUseId, spawnDepth }`.
+ * `toolUseId` is the join key back to the Task/Agent tool_use block in the
+ * parent transcript, which is how a run is attributed to the episode (and
+ * therefore the category) that caused it.
+ *
+ * Everything is best-effort: this layout is a Claude Code internal, so a
+ * missing directory, an absent meta file, or an unparseable line degrades to
+ * less data, never to a throw. route-scan keeps its proxy signal as fallback.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { collectSessionRecords, normalizeModelId } from './session-records.js';
+
+/** Directory holding a session's subagent transcripts (may not exist). */
+export function subagentDirFor(sessionPath) {
+  return join(dirname(sessionPath), basename(sessionPath, '.jsonl'), 'subagents');
+}
+
+async function readMeta(metaPath) {
+  try {
+    return JSON.parse(await readFile(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A run's model when several appear in one transcript (a harness retry can
+ * switch tiers mid-run): the one that produced the most output, since that is
+ * what dominates both the bill and the counterfactual.
+ */
+function primaryModel(byModelOut) {
+  let best = null;
+  let bestOut = -1;
+  for (const [model, out] of byModelOut) {
+    if (out > bestOut) { best = model; bestOut = out; }
+  }
+  return best;
+}
+
+/**
+ * Aggregate one subagent transcript into a single run record.
+ * Returns null when the file carries no billable API call.
+ */
+export async function collectSubagentRun(jsonlPath) {
+  let records;
+  try {
+    records = await collectSessionRecords(jsonlPath, { includeContent: false });
+  } catch {
+    return null;
+  }
+  if (records.length === 0) return null;
+
+  const run = {
+    path: jsonlPath,
+    agentId: basename(jsonlPath, '.jsonl').replace(/^agent-/, ''),
+    agentType: null,
+    toolUseId: null,
+    spawnDepth: null,
+    model: null,
+    calls: records.length,
+    out: 0,
+    input: 0,
+    cacheCreation: 0,
+    cacheRead: 0,
+    ephemeral5m: 0,
+    ephemeral1h: 0,
+    toolErrors: 0,
+    startedAt: null,
+    endedAt: null,
+    bytes: 0,
+  };
+  const byModelOut = new Map();
+  for (const r of records) {
+    run.out += r.completion_tokens || 0;
+    run.input += r.input_tokens || 0;
+    run.cacheCreation += r.cache_creation_tokens || 0;
+    run.cacheRead += r.cache_read_tokens || 0;
+    run.ephemeral5m += r.ephemeral5m || 0;
+    run.ephemeral1h += r.ephemeral1h || 0;
+    run.toolErrors += r.toolErrors || 0;
+    const model = normalizeModelId(r.model);
+    byModelOut.set(model, (byModelOut.get(model) || 0) + (r.completion_tokens || 0));
+    if (r.timestamp) {
+      const t = Date.parse(r.timestamp);
+      if (Number.isFinite(t)) {
+        if (run.startedAt === null || t < run.startedAt) run.startedAt = t;
+        if (run.endedAt === null || t > run.endedAt) run.endedAt = t;
+      }
+    }
+  }
+  run.model = primaryModel(byModelOut);
+
+  const meta = await readMeta(jsonlPath.replace(/\.jsonl$/, '.meta.json'));
+  if (meta) {
+    run.agentType = meta.agentType ?? null;
+    run.toolUseId = meta.toolUseId ?? null;
+    run.spawnDepth = meta.spawnDepth ?? null;
+  }
+  try {
+    run.bytes = (await stat(jsonlPath)).size;
+  } catch { /* size only feeds the rescan gate — 0 is a safe under-estimate */ }
+
+  return run;
+}
+
+/**
+ * All subagent runs a session spawned. Empty array when the session never
+ * delegated (the common case) or the directory is unreadable.
+ */
+export async function collectSubagentRuns(sessionPath) {
+  const dir = subagentDirFor(sessionPath);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const runs = [];
+  for (const e of entries) {
+    if (!e.endsWith('.jsonl')) continue;
+    const run = await collectSubagentRun(join(dir, e));
+    if (run) runs.push(run);
+  }
+  return runs;
+}
+
+/**
+ * Index a session's runs for attribution: exact join by tool_use id first,
+ * with the un-joinable ones kept aside for the timestamp fallback (a run
+ * whose .meta.json is missing or predates toolUseId still happened, and
+ * dropping it would silently under-count a rule's real error rate).
+ *
+ * `unjoined` is kept for callers that want only the no-id runs; the fallback
+ * itself works off `all` minus whatever the exact pass claimed, because a run
+ * CAN carry an id that no parent episode holds (see fallbackRunsForEpisode).
+ */
+export function indexRuns(runs) {
+  const byToolUse = new Map();
+  const unjoined = [];
+  for (const r of runs) {
+    if (r.toolUseId) byToolUse.set(r.toolUseId, r);
+    else unjoined.push(r);
+  }
+  return { byToolUse, unjoined, all: runs };
+}
+
+/**
+ * Runs attributable to one episode. Exact tool_use ids win; anything left
+ * unjoined is matched by start time falling inside the episode's span. `used`
+ * is a shared Set of run paths across the session so no run is counted twice
+ * (an episode's span can overlap a neighbouring episode's runs).
+ */
+export function runsForEpisode(index, ep, used) {
+  return [...exactRunsForEpisode(index, ep, used), ...fallbackRunsForEpisode(index, ep, used)];
+}
+
+/** Runs this episode's own Task calls spawned. No guessing. */
+export function exactRunsForEpisode(index, ep, used) {
+  const out = [];
+  for (const id of ep.delegationToolUseIds || []) {
+    const r = index.byToolUse.get(id);
+    if (r && !used.has(r.path)) { used.add(r.path); out.push(r); }
+  }
+  return out;
+}
+
+/**
+ * Runs that no episode's tool_use ids claimed, matched by start time falling
+ * inside this episode's span.
+ *
+ * The pool is every unclaimed run, not just the ones without a toolUseId. A
+ * nested delegation — a subagent spawning its own subagent — records the
+ * SIBLING's tool_use id, which appears in no parent transcript and therefore
+ * matches nothing. Gating the fallback on "has no toolUseId" made having one
+ * disqualify the run from the only path that could still attribute it, so
+ * every spawnDepth >= 2 run was dropped forever (measured: 3 of 3 over 14
+ * days, ~$3.42 of savings and three runs of rule-health evidence).
+ *
+ * Run session-wide AFTER every episode's exact join, so a timestamp guess
+ * cannot take a run that another episode can prove is its own.
+ */
+export function fallbackRunsForEpisode(index, ep, used) {
+  const out = [];
+  if (ep.startedAt === null || ep.endedAt === null) return out;
+  for (const r of index.all) {
+    if (used.has(r.path) || r.startedAt === null) continue;
+    if (r.startedAt >= ep.startedAt && r.startedAt <= ep.endedAt) {
+      used.add(r.path);
+      out.push(r);
+    }
+  }
+  return out;
+}

package/src/update-check.js

@@ -0,0 +1,201 @@
+/**
+ * update-check — "is there a newer claude-token-saver?", answered without ever
+ * blocking a render.
+ *
+ * The statusline command runs every ~300ms, so a network call on that path is
+ * out of the question. We use the same shape sindresorhus/update-notifier
+ * settled on: the foreground only ever READS a cached answer, and when that
+ * answer is older than the check interval it spawns a detached, unref'd child
+ * that refreshes the cache for the *next* render. Nothing awaits the network.
+ *
+ * State lives next to the other user-data files:
+ *   { checkedAt: <ms>, latest: "3.25.0", current: "3.24.0",
+ *     dismissedVersion: "3.25.0"|undefined }
+ *
+ * Opt out with CTS_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER (the de-facto
+ * standard env var — anyone who set it for other CLIs meant us too).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { userDataDir } from './paths.js';
+import { debug } from './debug.js';
+
+const PKG_NAME = 'claude-token-saver';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h — the registry is not a health endpoint
+const FETCH_TIMEOUT_MS = 5000;
+
+export function updateStatePath() {
+  return join(userDataDir(), 'update-check.json');
+}
+
+export function updateCheckDisabled() {
+  return process.env.CTS_NO_UPDATE_CHECK === '1' || !!process.env.NO_UPDATE_NOTIFIER;
+}
+
+export function readUpdateState() {
+  try {
+    const s = JSON.parse(readFileSync(updateStatePath(), 'utf8'));
+    return s && typeof s === 'object' ? s : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeUpdateState(next) {
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(updateStatePath(), JSON.stringify(next, null, 2) + '\n');
+}
+
+/**
+ * Compare two semver-ish strings. Returns true when `a` is strictly newer than
+ * `b`. Pre-release tags (`3.25.0-beta.1`) are treated as older than the plain
+ * release, which is what we want: we never nudge anyone onto a pre-release.
+ */
+export function isNewer(a, b) {
+  const parse = (v) => {
+    const m = String(v || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!m) return null;
+    return { nums: [+m[1], +m[2], +m[3]], pre: m[4] || null };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i];
+  }
+  if (pa.pre && !pb.pre) return false; // 3.25.0-beta < 3.25.0
+  if (!pa.pre && pb.pre) return true;
+  return false;
+}
+
+/**
+ * The read-only accessor every render path uses.
+ *
+ * @returns {{current: string, latest: string|null, available: boolean, dismissed: boolean, stale: boolean}}
+ */
+export function updateStatus(currentVersion) {
+  if (updateCheckDisabled()) {
+    return { current: currentVersion, latest: null, available: false, dismissed: false, stale: false };
+  }
+  const s = readUpdateState();
+  const latest = typeof s.latest === 'string' ? s.latest : null;
+  const available = !!latest && isNewer(latest, currentVersion);
+  const age = Date.now() - (Number(s.checkedAt) || 0);
+  return {
+    current: currentVersion,
+    latest,
+    available,
+    // A version the user already declined stays out of the statusline and out
+    // of the session briefing until a newer one ships — otherwise "no thanks"
+    // means "ask me again in five minutes", forever.
+    dismissed: available && s.dismissedVersion === latest,
+    stale: age >= CHECK_INTERVAL_MS,
+  };
+}
+
+/**
+ * Fire the background refresh when the cached answer has aged out. Returns
+ * immediately in every case; the child is detached and unref'd so it cannot
+ * hold the statusline process open.
+ */
+export function maybeSpawnUpdateCheck(currentVersion) {
+  if (updateCheckDisabled()) return false;
+  const { stale } = updateStatus(currentVersion);
+  if (!stale) return false;
+  // Stamp the attempt before spawning. Without this, an offline machine
+  // re-spawns a doomed child on every single statusline render — several per
+  // second — because the cache never gets a fresh timestamp.
+  try {
+    writeUpdateState({ ...readUpdateState(), checkedAt: Date.now(), current: currentVersion });
+  } catch (e) {
+    debug('update-check:stamp', e);
+    return false;
+  }
+  try {
+    spawn(process.execPath, [cliEntryPath(), 'update-check', '--refresh', '--quiet'], {
+      detached: true,
+      stdio: 'ignore',
+      // Without this Windows flashes a console window, and this one
+      // re-spawns from the statusline — several times a minute.
+      windowsHide: true,
+    }).unref();
+    return true;
+  } catch (e) {
+    debug('update-check:spawn', e);
+    return false;
+  }
+}
+
+/** Path to this package's CLI entry point (bin/cli.js). */
+export function cliEntryPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cli.js');
+}
+
+/**
+ * Actually hit the registry and persist the answer. Only the detached child
+ * and the explicit `update-check --refresh` command call this.
+ */
+export async function refreshUpdateState(currentVersion) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    // The `latest` dist-tag endpoint returns a few hundred bytes, unlike the
+    // full packument which is megabytes for a package with this many releases.
+    const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) throw new Error(`registry responded ${res.status}`);
+    const body = await res.json();
+    const latest = typeof body.version === 'string' ? body.version : null;
+    if (!latest) throw new Error('registry response carried no version');
+    const prev = readUpdateState();
+    const next = { ...prev, checkedAt: Date.now(), latest, current: currentVersion };
+    // A newly published version clears an older dismissal: the user declined
+    // 3.25.0, not "all future upgrades".
+    if (prev.dismissedVersion && isNewer(latest, prev.dismissedVersion)) {
+      delete next.dismissedVersion;
+    }
+    writeUpdateState(next);
+    return { ok: true, latest };
+  } catch (e) {
+    debug('update-check:refresh', e);
+    // Keep the timestamp fresh even on failure so an offline machine backs off
+    // for the full interval instead of retrying on every render.
+    try {
+      writeUpdateState({ ...readUpdateState(), checkedAt: Date.now(), current: currentVersion });
+    } catch (e2) {
+      debug('update-check:refresh-stamp', e2);
+    }
+    return { ok: false, error: String(e && e.message ? e.message : e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Record that the user said "not now" for this exact version. */
+export function dismissUpdate(version) {
+  const s = readUpdateState();
+  writeUpdateState({ ...s, dismissedVersion: version });
+}
+
+/**
+ * How this copy was installed, and therefore what command upgrades it.
+ * Best-effort: the install root is the only reliable signal we have, and when
+ * it tells us nothing we fall back to the npm global install, which is how the
+ * overwhelming majority of copies got here.
+ */
+export function upgradeCommand() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  if (here.includes('/pnpm/')) return `pnpm add -g ${PKG_NAME}@latest`;
+  if (here.includes('/.bun/')) return `bun add -g ${PKG_NAME}@latest`;
+  if (here.includes('/.yarn/')) return `yarn global add ${PKG_NAME}@latest`;
+  return `npm install -g ${PKG_NAME}@latest`;
+}
+
+export const UPDATE_CHECK_INTERVAL_MS = CHECK_INTERVAL_MS;
+export const PACKAGE_NAME = PKG_NAME;

package/src/window-labels.js

@@ -0,0 +1,64 @@
+/**
+ * Friendly labels + icons for `rate_limits.*` keys from Claude Code's stdin
+ * payload. Known keys (`five_hour`, `seven_day`) get curated short/long labels
+ * and dedicated icons. Unknown keys are passed through with a derived label so
+ * any future window Anthropic adds (e.g. `seven_day_sonnet`) renders without
+ * a code change.
+ */
+
+// `short` is used by the cap-warn chip and history records (stable shape so
+// parsers/dedup keep working). `usageLabel` is the friendlier word that the
+// always-on usage segment renders next to the icon — empty string means the
+// icon alone carries the meaning (5H 'session/now' is the implicit default).
+const KNOWN = {
+  // ✦ reads as "AI token unit" (Anthropic/OpenAI/Gemini sparkle motif), more
+  // on-theme than the 🪙 coin which suggested in-app currency. Same width as
+  // 📅 in monospace terminals so the chip alignment stays stable.
+  // 'current' mirrors how `weekly` reads next to 7D — names the window in
+  // plain English so a glance at `✦ current ████▒░ 72%` tells the eye what's
+  // being measured without parsing the icon's meaning.
+  five_hour: { short: '5H', long: 'Current session', icon: '✦', usageLabel: 'current' },
+  seven_day: { short: '7D', long: 'Current week', icon: '📅', usageLabel: 'weekly' },
+  // Speculative — `/usage` shows a Sonnet-only weekly bucket, so if Anthropic
+  // ever surfaces it on stdin we render with a sensible default already.
+  seven_day_sonnet: { short: '7D-S', long: 'Current week (Sonnet)', icon: '🅂', usageLabel: 'weekly (Sonnet)' },
+  seven_day_opus: { short: '7D-O', long: 'Current week (Opus)', icon: '🅾', usageLabel: 'weekly (Opus)' },
+  // LiteLLM 게이트웨이 키 예산. rate_limits 가 없는 환경에서 cap 게이지를
+  // 대신하는 합성 윈도우라서, 여기 라벨만 있으면 나머지 렌더는 공용 경로를 탄다.
+  litellm_budget: { short: 'BUDGET', long: 'LiteLLM key budget', icon: '🔑', usageLabel: 'budget' },
+};
+
+function deriveShort(key) {
+  // "five_hour" → "5H"; "seven_day_sonnet" → "7DS"; arbitrary key → uppercase initials
+  const m = key.match(/^(\d+)_?([a-z]+)/);
+  if (m) {
+    const num = m[1];
+    const word = m[2];
+    const letter = word.charAt(0).toUpperCase();
+    const tail = key.slice(m[0].length);
+    const suffix = tail
+      .split('_')
+      .filter(Boolean)
+      .map((s) => s.charAt(0).toUpperCase())
+      .join('');
+    return `${num}${letter}${suffix}`;
+  }
+  return key
+    .split('_')
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase())
+    .join('') || key;
+}
+
+function deriveLong(key) {
+  return key
+    .split('_')
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}
+
+export function labelForKey(key) {
+  if (KNOWN[key]) return KNOWN[key];
+  const short = deriveShort(key);
+  return { short, long: deriveLong(key), icon: '⏱', usageLabel: short };
+}