portable-agent-layer 0.71.0 → 0.72.0

package/src/tools/lib/token-report.ts

@@ -0,0 +1,173 @@
+/**
+ * The usage report, as lines rather than as console output.
+ *
+ * Every judgement about what the report shows — which sections appear at all,
+ * how a model is named, what "no data" looks like — was written straight into
+ * console.log inside a spawned tool, so none of it could be read back.
+ */
+
+import {
+  type Bucket,
+  type ClaudeCodeUsage,
+  grandTotal,
+  type PalInferenceUsage,
+  totalTokens,
+} from "./usage-buckets";
+
+export interface RtkSummary {
+  total_commands: number;
+  total_saved: number;
+  avg_savings_pct: number;
+}
+
+/**
+ * `installed: false` means rtk isn't on PATH; `summary: null` with
+ * `installed: true` means rtk is present but has nothing to report — the two
+ * cases print differently.
+ */
+export interface RtkGain {
+  installed: boolean;
+  summary: RtkSummary | null;
+}
+
+const DEFAULT_LABEL_WIDTH = 14;
+
+export function fmt(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return n.toLocaleString("en-US");
+}
+
+/** Two decimals reads as money; a sub-dollar total needs four to say anything. */
+export function fmtCost(n: number): string {
+  if (n >= 1) return `$${n.toFixed(2)}`;
+  return `$${n.toFixed(4)}`;
+}
+
+export function rowLine(
+  label: string,
+  b: Bucket,
+  labelWidth = DEFAULT_LABEL_WIDTH
+): string {
+  const tokens = fmt(totalTokens(b)).padStart(8);
+  const calls = fmt(b.calls).padStart(5);
+  const cost = fmtCost(b.cost).padStart(8);
+  return `  ${label.padEnd(labelWidth)} ${tokens} tok  ${calls} calls  ${cost}`;
+}
+
+export function detailedLine(
+  label: string,
+  b: Bucket,
+  labelWidth = DEFAULT_LABEL_WIDTH
+): string {
+  const input = fmt(b.input).padStart(8);
+  const output = fmt(b.output).padStart(8);
+  const write5m = fmt(b.cacheWrite5m).padStart(7);
+  const write1h = fmt(b.cacheWrite1h).padStart(7);
+  const read = fmt(b.cacheRead).padStart(8);
+  const cost = fmtCost(b.cost).padStart(8);
+  return `  ${label.padEnd(labelWidth)} ${input} in  ${output} out  ${write5m} cw5m  ${write1h} cw1h  ${read} cr  ${cost}`;
+}
+
+function windowLines(buckets: {
+  today: Bucket;
+  week: Bucket;
+  month: Bucket;
+  total: Bucket;
+}): string[] {
+  return [
+    rowLine("Today", buckets.today),
+    rowLine("7d", buckets.week),
+    rowLine("30d", buckets.month),
+    rowLine("Total", buckets.total),
+  ];
+}
+
+/** Costliest first — the point of the section is what to look at. */
+function byCost<T>(entries: [string, T][], costOf: (value: T) => number): [string, T][] {
+  return entries.sort((a, b) => costOf(b[1]) - costOf(a[1]));
+}
+
+function byModelLines(byModel: ClaudeCodeUsage["byModel"]): string[] {
+  const sorted = byCost(Object.entries(byModel), (bucket) => bucket.cost);
+  if (sorted.length === 0) return [];
+  const names = sorted.map(([model]) => model.replace("claude-", ""));
+  const width = Math.max(DEFAULT_LABEL_WIDTH, ...names.map((name) => name.length + 2));
+  return [
+    "\n  By Model (all time)\n",
+    ...sorted.map(([, bucket], i) => detailedLine(names[i], bucket, width)),
+  ];
+}
+
+/** One project is the project you are in; a breakdown of it says nothing new. */
+function byProjectLines(byProject: ClaudeCodeUsage["byProject"]): string[] {
+  const entries = Object.entries(byProject);
+  if (entries.length <= 1) return [];
+  const sorted = byCost(entries, (buckets) => buckets.total.cost);
+  return [
+    "\n  By Project (all time)\n",
+    ...sorted.map(([project, buckets]) => rowLine(project, buckets.total)),
+  ];
+}
+
+function inferenceLabel(model: string): string {
+  if (model.includes("haiku")) return "Haiku";
+  if (model.includes("sonnet")) return "Sonnet";
+  return model.replace("claude-", "");
+}
+
+function palInferenceLines(byModel: PalInferenceUsage["byModel"]): string[] {
+  const lines: string[] = [];
+  for (const [model, buckets] of Object.entries(byModel)) {
+    if (buckets.total.calls === 0) continue;
+    lines.push(`\n  PAL Inference (${inferenceLabel(model)})\n`, ...windowLines(buckets));
+  }
+  return lines;
+}
+
+export function rtkLines(gain: RtkGain): string[] {
+  const heading = "\n  rtk Compression\n";
+  if (!gain.installed) return [heading, "  rtk not installed"];
+  const summary = gain.summary;
+  if (!summary || summary.total_commands === 0) {
+    return [heading, "  rtk installed — no savings recorded yet"];
+  }
+  const saved = fmt(summary.total_saved).padStart(8);
+  const pct = summary.avg_savings_pct.toFixed(1);
+  const commands = fmt(summary.total_commands);
+  return [
+    heading,
+    `  Tokens saved   ${saved} tok  ${pct}% avg  across ${commands} commands`,
+  ];
+}
+
+/** Null for anything rtk did not answer cleanly — the report says so either way. */
+export function parseRtkSummary(
+  status: number | null,
+  stdout: string
+): RtkSummary | null {
+  if (status !== 0 || !stdout) return null;
+  try {
+    const parsed = JSON.parse(stdout) as { summary?: RtkSummary };
+    return parsed.summary ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function usageLines(
+  claudeCode: ClaudeCodeUsage,
+  pal: PalInferenceUsage,
+  rtk: RtkGain
+): string[] {
+  const grand = grandTotal([claudeCode.buckets.total, pal.buckets.total]);
+  return [
+    "\n  Claude Code Usage\n",
+    ...windowLines(claudeCode.buckets),
+    ...byModelLines(claudeCode.byModel),
+    ...byProjectLines(claudeCode.byProject),
+    ...palInferenceLines(pal.byModel),
+    ...rtkLines(rtk),
+    `\n  Grand Total: ${fmtCost(grand.cost)}\n`,
+  ];
+}

package/src/tools/lib/transcript-usage.ts

@@ -0,0 +1,42 @@
+/**
+ * The usage record a Claude Code transcript carries, and the one thing that is
+ * not obvious about reading it.
+ *
+ * Shared by the two tools that price a transcript — the per-session summary and
+ * the usage report — because reading it differently in the two would mean the
+ * same session cost two different amounts depending on which was asked.
+ */
+
+export interface TranscriptUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+  cache_creation?: {
+    ephemeral_5m_input_tokens?: number;
+    ephemeral_1h_input_tokens?: number;
+  };
+}
+
+export interface CacheWrites {
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+}
+
+/**
+ * Older transcripts report one cache-write total; newer ones break it into the
+ * two TTLs, which are priced differently. A transcript carrying the breakdown
+ * still carries the old total, so reading both would count those tokens twice —
+ * and the older total is billed as 5m, which is what it was.
+ */
+export function cacheWritesOf(usage: TranscriptUsage): CacheWrites {
+  const fiveMinute = usage.cache_creation?.ephemeral_5m_input_tokens;
+  const oneHour = usage.cache_creation?.ephemeral_1h_input_tokens;
+  const hasBreakdown = fiveMinute !== undefined || oneHour !== undefined;
+  return {
+    cacheWrite5m: hasBreakdown
+      ? (fiveMinute ?? 0)
+      : (usage.cache_creation_input_tokens ?? 0),
+    cacheWrite1h: oneHour ?? 0,
+  };
+}

package/src/tools/lib/usage-buckets.ts

@@ -0,0 +1,329 @@
+/**
+ * What has been spent, across the two places PAL can learn it from: Claude Code's
+ * own transcripts and PAL's inference log.
+ *
+ * The tool around this is spawned, so the arithmetic that decides what a month
+ * costs was never checked. Both readers take the directory to read rather than
+ * finding it themselves, which is the only thing that made them testable.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { costOfUsage } from "../../hooks/lib/models";
+import { cacheWritesOf, type TranscriptUsage } from "./transcript-usage";
+
+export interface Bucket {
+  input: number;
+  output: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+  cost: number;
+  calls: number;
+}
+
+export interface TimeBuckets {
+  today: Bucket;
+  week: Bucket;
+  month: Bucket;
+  total: Bucket;
+}
+
+/** The tokens of one call, before they are priced. */
+export interface Tokens {
+  input: number;
+  output: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+}
+
+export interface Horizons {
+  todayPrefix: string;
+  weekAgo: string;
+  monthAgo: string;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function emptyBucket(): Bucket {
+  return {
+    input: 0,
+    output: 0,
+    cacheWrite5m: 0,
+    cacheWrite1h: 0,
+    cacheRead: 0,
+    cost: 0,
+    calls: 0,
+  };
+}
+
+export function emptyTimeBuckets(): TimeBuckets {
+  return {
+    today: emptyBucket(),
+    week: emptyBucket(),
+    month: emptyBucket(),
+    total: emptyBucket(),
+  };
+}
+
+/**
+ * The cutoffs, as strings, because an ISO timestamp sorts lexically and
+ * comparing strings avoids parsing a Date per transcript line.
+ */
+export function horizonsFrom(now: Date): Horizons {
+  return {
+    todayPrefix: now.toISOString().slice(0, 10),
+    weekAgo: new Date(now.getTime() - 7 * DAY_MS).toISOString(),
+    monthAgo: new Date(now.getTime() - 30 * DAY_MS).toISOString(),
+  };
+}
+
+export function addToBucket(bucket: Bucket, model: string, tokens: Tokens): void {
+  bucket.input += tokens.input;
+  bucket.output += tokens.output;
+  bucket.cacheWrite5m += tokens.cacheWrite5m;
+  bucket.cacheWrite1h += tokens.cacheWrite1h;
+  bucket.cacheRead += tokens.cacheRead;
+  bucket.cost += costOfUsage(model, tokens);
+  bucket.calls++;
+}
+
+/**
+ * The windows nest: everything in today is also in the week, the month and the
+ * total, so a call is added to every window it falls inside rather than to one.
+ */
+export function addToTimeBuckets(
+  buckets: TimeBuckets,
+  ts: string,
+  model: string,
+  tokens: Tokens,
+  horizons: Horizons
+): void {
+  addToBucket(buckets.total, model, tokens);
+  if (ts >= horizons.monthAgo) addToBucket(buckets.month, model, tokens);
+  if (ts >= horizons.weekAgo) addToBucket(buckets.week, model, tokens);
+  if (ts.startsWith(horizons.todayPrefix)) addToBucket(buckets.today, model, tokens);
+}
+
+export function totalTokens(bucket: Bucket): number {
+  return (
+    bucket.input +
+    bucket.output +
+    bucket.cacheWrite5m +
+    bucket.cacheWrite1h +
+    bucket.cacheRead
+  );
+}
+
+/** Claude Code names a project directory after its path; the last segment is the repo. */
+export function projectNameOf(dirName: string): string {
+  const segments = dirName.replace(/^-/, "").split("-");
+  return segments.length > 1 ? segments.slice(-1)[0] : dirName;
+}
+
+export interface ClaudeCodeUsage {
+  buckets: TimeBuckets;
+  byModel: Record<string, Bucket>;
+  byProject: Record<string, TimeBuckets>;
+}
+
+interface TranscriptLine {
+  type?: string;
+  timestamp?: string;
+  message?: { model?: string; usage?: TranscriptUsage };
+}
+
+/**
+ * Every transcript under a project directory, including the ones a subagent
+ * wrote — those sit one level down and are billed to the same project, so
+ * missing them undercounts every session that spawned one.
+ */
+function transcriptsIn(projPath: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(projPath, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      files.push(resolve(projPath, entry.name));
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+    const subagentsDir = resolve(projPath, entry.name, "subagents");
+    try {
+      for (const sub of readdirSync(subagentsDir)) {
+        if (sub.endsWith(".jsonl")) files.push(resolve(subagentsDir, sub));
+      }
+    } catch {
+      /* no subagents dir */
+    }
+  }
+  return files;
+}
+
+interface PricedCall {
+  ts: string;
+  model: string;
+  tokens: Tokens;
+}
+
+/** Null for anything that is not a priced assistant turn. */
+function pricedCallOf(line: string): PricedCall | null {
+  let entry: TranscriptLine;
+  try {
+    entry = JSON.parse(line) as TranscriptLine;
+  } catch {
+    return null;
+  }
+  if (entry.type !== "assistant") return null;
+
+  const usage = entry.message?.usage;
+  const model = entry.message?.model;
+  const ts = entry.timestamp;
+  if (!usage || !model || !ts) return null;
+
+  return {
+    ts,
+    model,
+    tokens: {
+      input: usage.input_tokens ?? 0,
+      output: usage.output_tokens ?? 0,
+      cacheRead: usage.cache_read_input_tokens ?? 0,
+      ...cacheWritesOf(usage),
+    },
+  };
+}
+
+export function readClaudeCode(
+  claudeDir: string,
+  projectFilter?: string,
+  now: Date = new Date()
+): ClaudeCodeUsage {
+  const horizons = horizonsFrom(now);
+  const result: ClaudeCodeUsage = {
+    buckets: emptyTimeBuckets(),
+    byModel: {},
+    byProject: {},
+  };
+  if (!existsSync(claudeDir)) return result;
+
+  const projectDirs = readdirSync(claudeDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  for (const dirName of projectDirs) {
+    const projName = projectNameOf(dirName);
+    if (typeof projectFilter === "string" && !projName.includes(projectFilter)) continue;
+
+    for (const filepath of transcriptsIn(resolve(claudeDir, dirName))) {
+      let content: string;
+      try {
+        content = readFileSync(filepath, "utf-8");
+      } catch {
+        continue;
+      }
+
+      for (const line of content.split("\n")) {
+        // Cheap reject before the parse: most lines are not model turns.
+        if (!line.includes('"usage"')) continue;
+        const call = pricedCallOf(line);
+        if (!call) continue;
+
+        addToTimeBuckets(result.buckets, call.ts, call.model, call.tokens, horizons);
+
+        result.byModel[call.model] ??= emptyBucket();
+        addToBucket(result.byModel[call.model], call.model, call.tokens);
+
+        result.byProject[projName] ??= emptyTimeBuckets();
+        addToTimeBuckets(
+          result.byProject[projName],
+          call.ts,
+          call.model,
+          call.tokens,
+          horizons
+        );
+      }
+    }
+  }
+
+  return result;
+}
+
+export interface PalInferenceUsage {
+  buckets: TimeBuckets;
+  byModel: Record<string, TimeBuckets>;
+  byCaller: Record<string, Bucket>;
+}
+
+interface InferenceLine {
+  ts: string;
+  caller: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/** PAL's own calls are plain prompts: no cache to write and none to read. */
+function inferenceTokens(entry: InferenceLine): Tokens {
+  return {
+    input: entry.inputTokens,
+    output: entry.outputTokens,
+    cacheWrite5m: 0,
+    cacheWrite1h: 0,
+    cacheRead: 0,
+  };
+}
+
+export function readPalInference(
+  filepath: string,
+  now: Date = new Date()
+): PalInferenceUsage {
+  const horizons = horizonsFrom(now);
+  const result: PalInferenceUsage = {
+    buckets: emptyTimeBuckets(),
+    byModel: {},
+    byCaller: {},
+  };
+  if (!existsSync(filepath)) return result;
+
+  const content = readFileSync(filepath, "utf-8").trim();
+  if (!content) return result;
+
+  for (const line of content.split("\n")) {
+    let entry: InferenceLine;
+    try {
+      entry = JSON.parse(line) as InferenceLine;
+    } catch {
+      continue;
+    }
+    const tokens = inferenceTokens(entry);
+
+    addToTimeBuckets(result.buckets, entry.ts, entry.model, tokens, horizons);
+
+    result.byModel[entry.model] ??= emptyTimeBuckets();
+    addToTimeBuckets(
+      result.byModel[entry.model],
+      entry.ts,
+      entry.model,
+      tokens,
+      horizons
+    );
+
+    result.byCaller[entry.caller] ??= emptyBucket();
+    addToBucket(result.byCaller[entry.caller], entry.model, tokens);
+  }
+
+  return result;
+}
+
+export function grandTotal(buckets: Bucket[]): Bucket {
+  const grand = emptyBucket();
+  for (const bucket of buckets) {
+    grand.input += bucket.input;
+    grand.output += bucket.output;
+    grand.cacheWrite5m += bucket.cacheWrite5m;
+    grand.cacheWrite1h += bucket.cacheWrite1h;
+    grand.cacheRead += bucket.cacheRead;
+    grand.cost += bucket.cost;
+    grand.calls += bucket.calls;
+  }
+  return grand;
+}