portable-agent-layer 0.96.1 → 0.98.0

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

@@ -0,0 +1,134 @@
+/**
+ * What each month cost against what the same calls would have cost at API
+ * prices, read off the model_call events. A call is priced exactly as
+ * pal cli usage prices it, so the two never disagree about the same data.
+ */
+
+import type { LoggedEvent } from "../../hooks/lib/events";
+import { costOfUsage } from "../../hooks/lib/models";
+import { planPriceFor } from "./plan-prices";
+import { fmtCost } from "./token-report";
+
+export interface AgentMonth {
+  calls: number;
+  unpriced: number;
+  apiEquivalent: number;
+  billing: Set<string>;
+  plans: Map<string, string>;
+  apiBilled: number;
+  extraUsage: boolean;
+}
+
+export type CostMonths = Map<string, Map<string, AgentMonth>>;
+
+const numberOf = (value: unknown) => (typeof value === "number" ? value : 0);
+
+/** Claude Code at its dated rates, opencode at the cost it recorded, anything else unknown. */
+function apiPriceOf(event: LoggedEvent): number | null {
+  if (event.runtime === "opencode")
+    return typeof event.costUsd === "number" ? event.costUsd : null;
+  if (event.runtime !== "claude" || typeof event.model !== "string") return null;
+  return costOfUsage(
+    event.model,
+    {
+      input: numberOf(event.inputTokens),
+      output: numberOf(event.outputTokens),
+      cacheWrite5m: numberOf(event.cacheWrite5m),
+      cacheWrite1h: numberOf(event.cacheWrite1h),
+      cacheRead: numberOf(event.cacheRead),
+    },
+    event.ts
+  );
+}
+
+function emptyAgentMonth(): AgentMonth {
+  return {
+    calls: 0,
+    unpriced: 0,
+    apiEquivalent: 0,
+    billing: new Set(),
+    plans: new Map(),
+    apiBilled: 0,
+    extraUsage: false,
+  };
+}
+
+function addCall(month: AgentMonth, event: LoggedEvent): void {
+  const price = apiPriceOf(event);
+  const billing = typeof event.billing === "string" ? event.billing : "unknown";
+  month.calls++;
+  month.billing.add(billing);
+  if (price === null) month.unpriced++;
+  else month.apiEquivalent += price;
+  if (billing === "api") month.apiBilled += price ?? 0;
+  if (billing === "subscription" && typeof event.plan === "string")
+    month.plans.set(event.plan, month.plans.get(event.plan) ?? event.ts);
+  if (event.extraUsage === true) month.extraUsage = true;
+}
+
+export function costMonths(events: LoggedEvent[]): CostMonths {
+  const months: CostMonths = new Map();
+  for (const event of events) {
+    const month = event.ts.slice(0, 7);
+    const agents = months.get(month) ?? new Map<string, AgentMonth>();
+    months.set(month, agents);
+    const agent = agents.get(event.runtime) ?? emptyAgentMonth();
+    agents.set(event.runtime, agent);
+    addCall(agent, event);
+  }
+  return months;
+}
+
+/** Null when any part of what was paid is unknown. */
+function paidFor(month: AgentMonth): number | null {
+  if (month.billing.has("unknown")) return null;
+  let paid = month.billing.has("api") ? month.apiBilled : 0;
+  if (!month.billing.has("subscription")) return paid;
+  if (month.plans.size === 0) return null;
+  for (const [plan, since] of month.plans) {
+    const price = planPriceFor(plan, since);
+    if (price === null) return null;
+    paid += price;
+  }
+  return paid;
+}
+
+/** Null unless both sides are known and something was paid. */
+function leverageOf(month: AgentMonth): number | null {
+  const paid = paidFor(month);
+  if (paid === null || paid === 0 || month.unpriced > 0) return null;
+  return month.apiEquivalent / paid;
+}
+
+function apiEquivalentLabel(month: AgentMonth): string {
+  if (month.unpriced === month.calls) return "unknown";
+  const priced = fmtCost(month.apiEquivalent);
+  return month.unpriced > 0 ? `${priced} + ${month.unpriced} unpriced calls` : priced;
+}
+
+function paidLabel(month: AgentMonth): string {
+  const paid = paidFor(month);
+  if (paid === null) return "unknown";
+  const extra = month.extraUsage ? " + extra usage (unknown)" : "";
+  return `${fmtCost(paid)}${extra}`;
+}
+
+function agentLine(label: string, month: AgentMonth): string {
+  const leverage = leverageOf(month);
+  const bound = month.extraUsage ? "up to " : "";
+  const leverageText =
+    leverage === null ? "" : `   leverage ${bound}${leverage.toFixed(1)}x`;
+  return `    ${label.padEnd(16)} paid ${paidLabel(month)}   API-equivalent ${apiEquivalentLabel(month)}${leverageText}`;
+}
+
+export function costLines(months: CostMonths, labelOf: (runtime: string) => string) {
+  if (months.size === 0) return ["\n  No model calls in the event log yet\n"];
+  return [...months.keys()]
+    .sort()
+    .flatMap((month) => [
+      `\n  ${month}\n`,
+      ...[...(months.get(month) ?? [])]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([runtime, agent]) => agentLine(labelOf(runtime), agent)),
+    ]);
+}

package/src/tools/lib/plan-prices.ts

@@ -0,0 +1,24 @@
+/**
+ * What a subscription costs per month, keyed by the plan recorded on each
+ * model_call. Prices from support.claude.com's Max plan article, checked
+ * 2026-10-12; the Max launch date from Bloomberg, 2025-04-09.
+ */
+
+interface PlanPrice {
+  from: string;
+  monthlyUsd: number;
+}
+
+export const PLAN_PRICES: Record<string, PlanPrice[]> = {
+  default_claude_max_5x: [{ from: "2025-04-09", monthlyUsd: 100 }],
+  default_claude_max_20x: [{ from: "2025-04-09", monthlyUsd: 200 }],
+};
+
+/** The monthly price in force at `at`, or null when the plan or its price then is unknown. */
+export function planPriceFor(plan: string | null, at: string): number | null {
+  const when = Date.parse(at);
+  const inForce = (PLAN_PRICES[plan ?? ""] ?? []).filter(
+    (p) => Date.parse(p.from) <= when
+  );
+  return inForce.at(-1)?.monthlyUsd ?? null;
+}

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

@@ -147,13 +147,17 @@ export function accumulateUsage(transcript: string, sessionId: string): SessionU
     const cacheRead = usage.cache_read_input_tokens ?? 0;
     const { cacheWrite5m, cacheWrite1h } = cacheWritesOf(usage);
 
-    total.cost += costOfUsage(model, {
-      input,
-      output,
-      cacheWrite5m,
-      cacheWrite1h,
-      cacheRead,
-    });
+    total.cost += costOfUsage(
+      model,
+      {
+        input,
+        output,
+        cacheWrite5m,
+        cacheWrite1h,
+        cacheRead,
+      },
+      entry.timestamp
+    );
     total.input += input;
     total.output += output;
     total.cacheWrite5m += cacheWrite5m;

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

@@ -90,8 +90,13 @@ function addCall(bucket: Bucket, tokens: Tokens, cost: number | null, calls = 1)
   if (cost === null) bucket.unpriced += calls;
 }
 
-export function addToBucket(bucket: Bucket, model: string, tokens: Tokens): void {
-  addCall(bucket, tokens, costOfUsage(model, tokens));
+export function addToBucket(
+  bucket: Bucket,
+  model: string,
+  tokens: Tokens,
+  ts: string
+): void {
+  addCall(bucket, tokens, costOfUsage(model, tokens, ts));
 }
 
 /**
@@ -117,7 +122,7 @@ export function addToTimeBuckets(
   tokens: Tokens,
   horizons: Horizons
 ): void {
-  addToWindows(buckets, ts, horizons, (bucket) => addToBucket(bucket, model, tokens));
+  addToWindows(buckets, ts, horizons, (bucket) => addToBucket(bucket, model, tokens, ts));
 }
 
 export function totalTokens(bucket: Bucket): number {
@@ -290,7 +295,7 @@ export function readClaudeCode(
       model: call.model,
       tokens: call.tokens,
       project: call.project,
-      cost: costOfUsage(call.model, call.tokens),
+      cost: costOfUsage(call.model, call.tokens, call.ts),
     });
   }
   return tally.usage;
@@ -357,7 +362,7 @@ export function readPalInference(
     );
 
     result.byCaller[entry.caller] ??= emptyBucket();
-    addToBucket(result.byCaller[entry.caller], entry.model, tokens);
+    addToBucket(result.byCaller[entry.caller], entry.model, tokens, entry.ts);
   }
 
   return result;