sprag-cli 3.40.0

package/src/session-records.js

@@ -0,0 +1,188 @@
+/**
+ * session-records — parse a Claude Code session transcript into per-API-call
+ * records (model, tokens, depth, triggering user prompt, session cwd).
+ *
+ * This is the shared substrate for episode-level analysis (route-scan and the
+ * 3.x tier-classification work): one record per API call, deduplicated by
+ * requestId (last-write-wins, matching parser.js).
+ */
+
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { resolveModelAlias } from './model-alias.js';
+
+/**
+ * Strip context-window suffixes like "[1m]" so model ids compare cleanly, and
+ * turn a gateway inference-profile ARN back into a Claude alias. Ids that are
+ * already Claude aliases pass through untouched.
+ */
+export function normalizeModelId(model) {
+  const resolved = resolveModelAlias(model || 'unknown');
+  return String(resolved).replace(/\[[^\]]*\]$/, '');
+}
+
+/** Extract plain text from a Claude transcript message content field. */
+function contentText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n');
+}
+
+/**
+ * Parse one session transcript into call records.
+ * @returns {Promise<Array<{model, timestamp, prompt_tokens, completion_tokens, depth, userText, assistantText, cwd}>>}
+ */
+const MUTATING_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'Bash']);
+const DELEGATION_TOOLS = new Set(['Task', 'Agent']);
+
+// Permission rejections and harness policy denials arrive as is_error
+// tool_results, but they encode the user's choice / the permission system's
+// policy, not task difficulty — counting them poisons the rule-health error
+// rate. Measured on a 14-day window: 6 user rejections + ~29 auto-mode
+// classifier denials out of 142 is_error results (~25% of the numerator).
+const REJECTION_RE = /doesn't want to proceed|tool use was rejected|doesn't want to take this action|denied by the claude code auto mode classifier|permission for this action was denied|requires approval/i;
+
+// Harness-mechanical / self-corrected tool errors also arrive as is_error
+// tool_results, but they reflect edit-ordering mechanics and the agent's own
+// immediate correction loop — not task difficulty. Counting them poisons the
+// rule-health error rate the same way permission denials do (v3.4.2). Measured
+// on a 14-day window they dominate the numerator (e.g. "File has not been read
+// yet" was 7/65 real errors in one project, edit-races + Task-lifecycle several
+// more). Kept NARROW on purpose: ambiguous shell failures ("Exit code N", "File
+// does not exist" on a Read) stay counted — those are genuine difficulty signal.
+// Tool-argument schema violations (InputValidationError, "does not match the
+// required schema/pattern") are the model mis-building a call, corrected on
+// the next attempt — same self-correction family, not task difficulty.
+// Measured 2026-09-09: they were the single largest numerator item (10/125).
+const SELF_CORRECTED_RE = /File has not been read yet|has been modified since read|String to replace not found|is not running \(status:|<tool_use_error>Blocked:|InputValidationError|does not match the required/i;
+
+// Failures with no diagnosable content — a bare exit code or "no output" —
+// carry no evidence about WHY they failed, so they cannot support a
+// rule-health verdict either way. Excluded from the numerator (16% of it was
+// this plus schema errors, against a 20% review threshold). Anchored: an
+// "Exit code 1" followed by a traceback still counts.
+const NO_SIGNAL_RE = /^\s*(Command failed with no output|Exit code \d+)\s*$/;
+
+// Environment constraints — a sandbox without `curl`/`wc`, a corporate proxy
+// timing a fetch out — are not task difficulty either. The agent routinely
+// routes around them and finishes: one 218-turn run that produced a 9,870-char
+// sourced report was scored a failure on two `command not found` results.
+// NARROW on purpose: only the shell's own "this binary is absent" wording and
+// curl's transport-timeout exit, never a generic non-zero exit.
+const ENVIRONMENT_RE = /command not found|curl: \(28\)|Operation timed out after|ETIMEDOUT|ENOTFOUND|getaddrinfo/i;
+
+function toolResultText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.map((b) => (b && typeof b.text === 'string' ? b.text : '')).join(' ');
+}
+
+function isRealToolError(block) {
+  if (!block || block.type !== 'tool_result' || !block.is_error) return false;
+  const txt = toolResultText(block.content);
+  return !REJECTION_RE.test(txt) && !SELF_CORRECTED_RE.test(txt)
+    && !ENVIRONMENT_RE.test(txt) && !NO_SIGNAL_RE.test(txt);
+}
+
+export async function collectSessionRecords(filePath, { includeContent = true } = {}) {
+  const records = new Map();
+  let depth = 0;
+  let lastUserText = '';
+  let lastCwd = '';
+  let lastRecord = null;
+
+  const rl = createInterface({
+    input: createReadStream(filePath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const msg = entry.message;
+    if (typeof entry.cwd === 'string' && entry.cwd) lastCwd = entry.cwd;
+    if (entry.type === 'user' && msg) {
+      depth += 1;
+      const text = contentText(msg.content);
+      if (text) lastUserText = text;
+      // Tool errors arrive as tool_result blocks in the user entry that
+      // follows the assistant call — attribute them to that call's record.
+      if (lastRecord && Array.isArray(msg.content)) {
+        for (const b of msg.content) {
+          if (isRealToolError(b)) lastRecord.toolErrors += 1;
+        }
+      }
+      continue;
+    }
+    if (entry.type !== 'assistant' || !msg) continue;
+    depth += 1;
+
+    if (!msg.usage || !msg.id) continue;
+    // "<synthetic>" is Claude Code's placeholder for locally-generated
+    // entries (e.g. error stubs) — no real API call, nothing to record.
+    if (msg.model === '<synthetic>') continue;
+    const usage = msg.usage;
+    const reqId = entry.requestId || msg.id;
+
+    let mutatingToolCalls = 0;
+    let delegationCalls = 0;
+    const prev = records.get(reqId);
+    // Per-tool call histogram — what the call actually DID. route-scan's
+    // categorizer trusts this over the prompt's wording (behavior-first).
+    const toolCounts = { ...(prev?.toolCounts || {}) };
+    // tool_use ids of Task/Agent calls: the join key to the subagent
+    // transcripts under <session>/subagents/*.meta.json, which is how the
+    // outcome of a delegation is measured (rule-health v2).
+    const delegationToolUseIds = [...(prev?.delegationToolUseIds || [])];
+    if (Array.isArray(msg.content)) {
+      for (const b of msg.content) {
+        if (!b || b.type !== 'tool_use') continue;
+        if (MUTATING_TOOLS.has(b.name)) mutatingToolCalls += 1;
+        if (DELEGATION_TOOLS.has(b.name)) {
+          delegationCalls += 1;
+          if (typeof b.id === 'string') delegationToolUseIds.push(b.id);
+        }
+        if (typeof b.name === 'string') toolCounts[b.name] = (toolCounts[b.name] || 0) + 1;
+      }
+    }
+
+    lastRecord = {
+      model: normalizeModelId(msg.model),
+      timestamp: entry.timestamp || null,
+      prompt_tokens:
+        (usage.input_tokens || 0) +
+        (usage.cache_creation_input_tokens || 0) +
+        (usage.cache_read_input_tokens || 0),
+      completion_tokens: usage.output_tokens || 0,
+      // Per-bucket split, kept alongside the collapsed prompt_tokens: pricing
+      // differs per bucket, so costing a delegated run against what the
+      // session model would have charged needs them separated.
+      input_tokens: usage.input_tokens || 0,
+      cache_creation_tokens: usage.cache_creation_input_tokens || 0,
+      cache_read_tokens: usage.cache_read_input_tokens || 0,
+      ephemeral5m: usage.cache_creation?.ephemeral_5m_input_tokens || 0,
+      ephemeral1h: usage.cache_creation?.ephemeral_1h_input_tokens || 0,
+      depth,
+      userText: includeContent ? lastUserText : '',
+      assistantText: includeContent ? contentText(msg.content) : '',
+      cwd: lastCwd,
+      // Entries of the same request accumulate tool blocks and errors.
+      mutatingToolCalls: (prev?.mutatingToolCalls || 0) + mutatingToolCalls,
+      delegationCalls: (prev?.delegationCalls || 0) + delegationCalls,
+      delegationToolUseIds,
+      toolErrors: prev?.toolErrors || 0,
+      toolCounts,
+    };
+    records.set(reqId, lastRecord);
+  }
+
+  return [...records.values()];
+}

package/src/stats.js

@@ -0,0 +1,380 @@
+/**
+ * Aggregate session data into daily trends, TTL breakdown, and anomalies.
+ */
+
+function dateKey(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+function hitRate(read, creation, input) {
+  const total = read + creation + input;
+  return total > 0 ? read / total : 0;
+}
+
+/**
+ * Daily cache hit rate trend
+ */
+export function dailyTrend(sessions) {
+  const byDay = new Map();
+
+  for (const s of sessions) {
+    if (!s.startTime) continue;
+    const day = dateKey(s.startTime);
+    if (!byDay.has(day)) {
+      byDay.set(day, {
+        date: day,
+        input: 0,
+        cacheCreation: 0,
+        cacheRead: 0,
+        ephemeral5m: 0,
+        ephemeral1h: 0,
+        output: 0,
+        apiCalls: 0,
+        sessions: 0,
+      });
+    }
+    const d = byDay.get(day);
+    d.input += s.totals.input;
+    d.cacheCreation += s.totals.cacheCreation;
+    d.cacheRead += s.totals.cacheRead;
+    d.ephemeral5m += s.totals.ephemeral5m;
+    d.ephemeral1h += s.totals.ephemeral1h;
+    d.output += s.totals.output;
+    d.apiCalls += s.requestCount;
+    d.sessions += 1;
+  }
+
+  return [...byDay.values()]
+    .sort((a, b) => a.date.localeCompare(b.date))
+    .map((d) => ({
+      ...d,
+      hitRate: hitRate(d.cacheRead, d.cacheCreation, d.input),
+      totalInput: d.cacheRead + d.cacheCreation + d.input,
+    }));
+}
+
+/**
+ * TTL breakdown summary
+ */
+export function ttlBreakdown(sessions) {
+  let total5m = 0;
+  let total1h = 0;
+  let gatewayObserved = false;
+
+  for (const s of sessions) {
+    total5m += s.totals.ephemeral5m;
+    total1h += s.totals.ephemeral1h;
+    if (s.gatewayObserved) gatewayObserved = true;
+  }
+
+  const total = total5m + total1h;
+  return {
+    ephemeral5m: total5m,
+    ephemeral1h: total1h,
+    total,
+    pct5m: total > 0 ? total5m / total : 0,
+    pct1h: total > 0 ? total1h / total : 0,
+    // Bedrock and Vertex fill only the `cache_creation_input_tokens` sum and
+    // leave the per-bucket split at zero, so `total === 0` there means "cannot
+    // tell" rather than "no cache writes happened". Carrying the observation
+    // alongside the numbers lets the display layer tell those two apart
+    // without going back to the environment.
+    gatewayObserved,
+  };
+}
+
+/**
+ * Detect anomalies — days where hit rate drops significantly from rolling average
+ */
+export function detectAnomalies(trend, { threshold = 0.15 } = {}) {
+  const anomalies = [];
+  const windowSize = 7;
+
+  for (let i = 0; i < trend.length; i++) {
+    const day = trend[i];
+    if (day.apiCalls < 5) continue; // skip low-volume days
+
+    // rolling average of prior days
+    const windowStart = Math.max(0, i - windowSize);
+    const window = trend.slice(windowStart, i);
+    if (window.length < 3) continue;
+
+    const avgHitRate =
+      window.reduce((sum, d) => sum + d.hitRate, 0) / window.length;
+
+    const drop = avgHitRate - day.hitRate;
+    if (drop > threshold) {
+      anomalies.push({
+        date: day.date,
+        hitRate: day.hitRate,
+        avgHitRate,
+        drop,
+        apiCalls: day.apiCalls,
+      });
+    }
+  }
+
+  return anomalies;
+}
+
+/**
+ * Per-session metrics used by diagnostics.
+ */
+export function sessionMetrics(session) {
+  const t = session.totals;
+  const totalInput = t.input + t.cacheCreation + t.cacheRead;
+  const reqs = session.requestCount || 0;
+  const avgInputPerReq = reqs > 0 ? totalInput / reqs : 0;
+  const hit = hitRate(t.cacheRead, t.cacheCreation, t.input);
+  const ttlSum = t.ephemeral5m + t.ephemeral1h;
+  const pct5m = ttlSum > 0 ? t.ephemeral5m / ttlSum : 0;
+  const outputRatio = totalInput > 0 ? t.output / totalInput : 0;
+  const writeToReadRatio = t.cacheRead > 0 ? t.cacheCreation / t.cacheRead : (t.cacheCreation > 0 ? Infinity : 0);
+  return {
+    sessionId: session.sessionId,
+    projectDir: session.projectDir,
+    startTime: session.startTime,
+    endTime: session.endTime,
+    requestCount: reqs,
+    totalInput,
+    avgInputPerReq,
+    hitRate: hit,
+    pct5m,
+    outputRatio,
+    writeToReadRatio,
+    maxContextPerRequest: session.maxContextPerRequest || 0,
+    gatewayObserved: !!session.gatewayObserved,
+    totals: t,
+  };
+}
+
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+function percentile(values, p) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.floor(sorted.length * p));
+  return sorted[idx];
+}
+
+/**
+ * Baseline using sessions OUTSIDE the recent window. Recent sessions are what
+ * we're diagnosing — if we let them into the baseline they'd drag the baseline
+ * toward themselves and never register as anomalies.
+ */
+export function computeBaseline(sessions, recentWindowMs = 24 * 60 * 60 * 1000) {
+  const cutoff = Date.now() - recentWindowMs;
+  const older = sessions.filter((s) => s.startTime && s.startTime.getTime() < cutoff && s.requestCount > 0);
+  if (older.length < 3) {
+    return { enough: false, sampleSize: older.length };
+  }
+  const metrics = older.map(sessionMetrics);
+  return {
+    enough: true,
+    sampleSize: older.length,
+    medianAvgInputPerReq: median(metrics.map((m) => m.avgInputPerReq)),
+    p95AvgInputPerReq: percentile(metrics.map((m) => m.avgInputPerReq), 0.95),
+    medianTotalInput: median(metrics.map((m) => m.totalInput)),
+    p95TotalInput: percentile(metrics.map((m) => m.totalInput), 0.95),
+    medianHitRate: median(metrics.map((m) => m.hitRate)),
+    medianRequestCount: median(metrics.map((m) => m.requestCount)),
+    p95RequestCount: percentile(metrics.map((m) => m.requestCount), 0.95),
+    medianMaxContext: median(metrics.map((m) => m.maxContextPerRequest)),
+  };
+}
+
+/**
+ * Diagnose one session against a baseline. Returns issue codes + supporting
+ * numbers so the formatter can render human-readable messages without
+ * re-computing anything.
+ *
+ * Issue codes:
+ *   LARGE_INPUT_PER_REQUEST  — likely 1M context mode; avg input per request
+ *                              is 8x+ baseline or max req context > 250k
+ *   LOW_HIT_RATE             — below 0.5 and baseline was meaningfully higher
+ *   BUCKET_5M_DOMINANT       — 5m TTL writes dominate (>70%); prefix re-writes
+ *   HIGH_OUTPUT_RATIO        — output/input ratio > 0.15 (unusually chatty)
+ *   HIGH_REQUEST_COUNT       — request count > 3x baseline
+ *   FREQUENT_CACHE_REBUILD   — cacheCreation > cacheRead (cache not reused)
+ */
+export function diagnoseSession(metrics, baseline) {
+  const issues = [];
+  if (!metrics || metrics.requestCount === 0) return issues;
+
+  const b = baseline?.enough ? baseline : null;
+
+  if (metrics.maxContextPerRequest > 250_000 ||
+      (b && b.medianAvgInputPerReq > 0 && metrics.avgInputPerReq > b.medianAvgInputPerReq * 8)) {
+    issues.push({
+      code: 'LARGE_INPUT_PER_REQUEST',
+      avgInputPerReq: metrics.avgInputPerReq,
+      maxContextPerRequest: metrics.maxContextPerRequest,
+      baseline: b?.medianAvgInputPerReq,
+    });
+  }
+
+  if (metrics.hitRate < 0.5 && (!b || b.medianHitRate > metrics.hitRate + 0.2)) {
+    issues.push({
+      code: 'LOW_HIT_RATE',
+      hitRate: metrics.hitRate,
+      baseline: b?.medianHitRate,
+    });
+  }
+
+  // The split is only knowable when the provider reports it. Requiring that
+  // sum outright meant gateway users — who are on a 5m-only backend and so
+  // need this warning most — never saw it at all.
+  const ttlSplitKnown = (metrics.totals.ephemeral5m + metrics.totals.ephemeral1h) > 0;
+  if (ttlSplitKnown && metrics.pct5m > 0.7) {
+    issues.push({
+      code: 'BUCKET_5M_DOMINANT',
+      pct5m: metrics.pct5m,
+    });
+  } else if (!ttlSplitKnown && metrics.gatewayObserved && metrics.totals.cacheCreation > 0) {
+    // Bedrock and Vertex offer no 1h bucket, so every write is a 5m write.
+    // The advice differs from the subscription case: no plan change fixes it.
+    issues.push({
+      code: 'BUCKET_5M_DOMINANT_GATEWAY',
+      pct5m: 1.0,
+      inferred: true,
+    });
+  }
+
+  if (metrics.outputRatio > 0.15) {
+    issues.push({
+      code: 'HIGH_OUTPUT_RATIO',
+      outputRatio: metrics.outputRatio,
+    });
+  }
+
+  if (b && metrics.requestCount > b.medianRequestCount * 3 && metrics.requestCount > 30) {
+    issues.push({
+      code: 'HIGH_REQUEST_COUNT',
+      requestCount: metrics.requestCount,
+      baseline: b.medianRequestCount,
+    });
+  }
+
+  if (metrics.writeToReadRatio !== Infinity &&
+      metrics.writeToReadRatio > 1 &&
+      metrics.totals.cacheCreation > 100_000) {
+    issues.push({
+      code: 'FREQUENT_CACHE_REBUILD',
+      writeToReadRatio: metrics.writeToReadRatio,
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Find sessions in the recent window whose token totals are >= multiplier x
+ * the baseline p95. Returns spikes sorted by severity (largest first) with
+ * diagnosis attached.
+ */
+export function detectSpikes(sessions, { recentHours = 24, multiplier = 3 } = {}) {
+  const baseline = computeBaseline(sessions, recentHours * 60 * 60 * 1000);
+  const cutoff = Date.now() - recentHours * 60 * 60 * 1000;
+  const recent = sessions.filter(
+    (s) => s.startTime && s.startTime.getTime() >= cutoff && s.requestCount > 0,
+  );
+
+  const spikes = [];
+  for (const s of recent) {
+    const m = sessionMetrics(s);
+    // Need a floor so tiny sessions with a few hundred tokens don't register
+    // as spikes just because baseline is also small.
+    if (m.totalInput < 1_000_000) continue;
+
+    const ratio = baseline.enough && baseline.p95TotalInput > 0
+      ? m.totalInput / baseline.p95TotalInput
+      : null;
+
+    const isSpike =
+      (ratio !== null && ratio >= multiplier) ||
+      m.maxContextPerRequest > 250_000;
+
+    if (!isSpike) continue;
+
+    spikes.push({
+      metrics: m,
+      ratio,
+      issues: diagnoseSession(m, baseline),
+    });
+  }
+
+  spikes.sort((a, b) => b.metrics.totalInput - a.metrics.totalInput);
+  return { baseline, spikes };
+}
+
+/**
+ * Detect the likely context-window setting from the largest single-request
+ * context seen in the recent window. Claude Code's two modes are 200k (default)
+ * and 1M (Opus 4.7+ auto-enabled on Max). If max single-request context passes
+ * the 200k ceiling, the user has 1M turned on.
+ *
+ * Returns { size: '1M' | '200k' | 'unknown', maxContext, source, overWarn }.
+ * `size` stays informational (which window is in play); `overWarn` is the
+ * alarm condition and uses the much higher CONTEXT_WARN_TOKENS line.
+ */
+export const CONTEXT_WARN_TOKENS = 500_000;
+
+export function detectContextWindow(sessions, { recentHours = 24 } = {}) {
+  const cutoff = Date.now() - recentHours * 60 * 60 * 1000;
+  const recent = sessions.filter(
+    (s) => s.endTime && s.endTime.getTime() >= cutoff && s.requestCount > 0,
+  );
+  const pool = recent.length > 0 ? recent : sessions;
+  const maxContext = pool.reduce(
+    (m, s) => Math.max(m, s.maxContextPerRequest || 0),
+    0,
+  );
+  if (maxContext === 0) return { size: 'unknown', maxContext, source: 'no-data', overWarn: false };
+  // 200_000 is the hard ceiling for the standard window. Anything materially
+  // over that means the 1M context is in play. Use 210k for a small safety
+  // margin against rounding/metadata tokens.
+  const source = recent.length > 0 ? 'recent' : 'all';
+  // `overWarn` is what the statusline and the report actually alarm on. The
+  // 200k line stopped separating careless sessions from ordinary ones: every
+  // current model ships a 1M window, the Claude Code system prompt plus a few
+  // file reads already clears 200k, so a fresh session tripped the warning
+  // right after install and then never stopped tripping it. A warning that is
+  // always on carries no information. 500k is where a context genuinely costs
+  // real money per turn and where /compact is the right answer.
+  const overWarn = maxContext > CONTEXT_WARN_TOKENS;
+  if (maxContext > 210_000) return { size: '1M', maxContext, source, overWarn };
+  return { size: '200k', maxContext, source, overWarn };
+}
+
+/**
+ * Overall summary
+ */
+export function summary(sessions) {
+  const totals = sessions.reduce(
+    (acc, s) => {
+      acc.input += s.totals.input;
+      acc.cacheCreation += s.totals.cacheCreation;
+      acc.cacheRead += s.totals.cacheRead;
+      acc.ephemeral5m += s.totals.ephemeral5m;
+      acc.ephemeral1h += s.totals.ephemeral1h;
+      acc.output += s.totals.output;
+      acc.apiCalls += s.requestCount;
+      acc.sessions += 1;
+      return acc;
+    },
+    { input: 0, cacheCreation: 0, cacheRead: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0, apiCalls: 0, sessions: 0 },
+  );
+
+  const totalInput = totals.cacheRead + totals.cacheCreation + totals.input;
+
+  return {
+    ...totals,
+    totalInput,
+    hitRate: hitRate(totals.cacheRead, totals.cacheCreation, totals.input),
+  };
+}

package/src/stdin-payload.js

@@ -0,0 +1,122 @@
+/**
+ * Claude Code's statusline contract feeds this tool a JSON blob on stdin every
+ * refresh. These helpers own reading and interpreting that payload; everything
+ * else in the CLI takes the extracted values.
+ */
+
+import { readFileSync } from 'node:fs';
+
+/**
+ * Read the JSON blob Claude Code feeds the statusline command on stdin.
+ * Returns null when stdin is a TTY or empty (e.g. user invokes `--statusline`
+ * by hand) so callers can fall back to flag/env config.
+ *
+ * The blob shape (subset we consume):
+ *   {
+ *     "transcript_path": "...",
+ *     "rate_limits": {
+ *       "five_hour":  { "used_percentage": 94, "resets_at": 1777099200 },
+ *       "seven_day":  { "used_percentage": 7,  "resets_at": 1777521600 }
+ *     }
+ *   }
+ *
+ * extractCaps treats `rate_limits` as a generic object so any future window
+ * Anthropic adds (e.g. a Sonnet-only weekly bucket) flows through without code
+ * changes — known keys get curated labels, unknowns get derived ones.
+ */
+export function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  try {
+    const raw = readFileSync(0, 'utf8');
+    if (!raw || !raw.trim()) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A percentage from the payload, or null when the field is absent, empty, or
+ * non-numeric. `Number(null|''|[])` is 0, so a plain Number() call renders
+ * missing data as "0% used" — the most dangerously wrong reading possible for
+ * a cap gauge. Out-of-range values are clamped to 0..100 at this entry point
+ * so every renderer (and caps-cache.js, which persists the value) agrees.
+ */
+function normalizePct(raw) {
+  if (typeof raw !== 'number') {
+    if (typeof raw !== 'string' || raw.trim() === '') return null;
+    raw = Number(raw);
+  }
+  if (!Number.isFinite(raw)) return null;
+  return Math.max(0, Math.min(100, raw));
+}
+
+export function extractCaps(stdinJson) {
+  if (!stdinJson || !stdinJson.rate_limits || typeof stdinJson.rate_limits !== 'object') return null;
+  const windows = [];
+  for (const [key, value] of Object.entries(stdinJson.rate_limits)) {
+    if (!value || typeof value !== 'object') continue;
+    const usedPct = normalizePct(value.used_percentage);
+    if (usedPct === null) continue;
+    const resetsAt = Number(value.resets_at);
+    windows.push({
+      key,
+      usedPct,
+      resetsAt: Number.isFinite(resetsAt) ? resetsAt : null,
+    });
+  }
+  return windows.length ? { windows } : null;
+}
+
+/**
+ * Pull the human-friendly model name out of Claude Code's stdin payload.
+ * `model.display_name` is the contract; fall back to `model.id` when it's
+ * absent. Returns null when nothing usable is in the JSON.
+ */
+// Bedrock/litellm proxies pass model IDs like
+//   global.anthropic.claude-opus-4-7-20251001-v1:0
+//   anthropic.claude-sonnet-4-6-20250930-v1:0
+//   bedrock/anthropic.claude-haiku-4-5
+// while Claude Code's `display_name` collapses these to a generic family
+// label ("Opus 4", "Sonnet 4") that hides the actual minor version. Pull the
+// version out of the id when we can spot it so the statusline shows the real
+// model in use (Opus 4.7 vs 4.6 matters a lot for token budgeting).
+export function bedrockDisplayFromId(id) {
+  if (typeof id !== 'string') return null;
+  const m = id.match(/claude[-_](opus|sonnet|haiku)[-_](\d+)[-_](\d+)/i);
+  if (!m) return null;
+  const family = m[1].charAt(0).toUpperCase() + m[1].slice(1).toLowerCase();
+  return `${family} ${m[2]}.${m[3]}`;
+}
+
+/**
+ * Live context usage from Claude Code's stdin payload (`context_window`).
+ * More accurate than inferring from transcripts: it's the CURRENT session's
+ * real fill level, updated every refresh. Shape (subset):
+ *   "context_window": { "context_window_size": 200000, "used_percentage": 68 }
+ */
+export function extractContextUsage(stdinJson) {
+  const cw = stdinJson && stdinJson.context_window;
+  if (!cw || typeof cw !== 'object') return null;
+  const usedPct = normalizePct(cw.used_percentage);
+  const size = Number(cw.context_window_size);
+  if (usedPct === null) return null;
+  return {
+    usedPct,
+    size: Number.isFinite(size) && size > 0 ? size : null,
+  };
+}
+
+export function extractModel(stdinJson) {
+  if (!stdinJson || !stdinJson.model) return null;
+  const m = stdinJson.model;
+  if (typeof m === 'string') return bedrockDisplayFromId(m) || m;
+  // Prefer the id when it carries a precise version (e.g. Bedrock IDs); fall
+  // back to display_name for the standard Claude Code path where display_name
+  // already says "Claude Opus 4.7".
+  const idDerived = bedrockDisplayFromId(m.id);
+  if (idDerived) return idDerived;
+  if (typeof m.display_name === 'string' && m.display_name) return m.display_name;
+  if (typeof m.id === 'string' && m.id) return m.id;
+  return null;
+}