portable-agent-layer 0.100.0 → 0.101.0

package/README.md

@@ -86,6 +86,7 @@ pal cli status        # check your setup
 | `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli cost` | What each month was paid against its API-equivalent cost, per agent |
+| `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium`, `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/cost.ts

@@ -1,15 +1,11 @@
-import { AGENT_REGISTRY, type AgentName } from "../hooks/lib/agent-registry";
+import { labelOfRuntime } from "../hooks/lib/agent-registry";
 import { eventsSince } from "../hooks/lib/events";
 import { leaf } from "../tools/lib/command";
 import { costLines, costMonths } from "../tools/lib/cost-report";
 
-function labelOf(runtime: string): string {
-  return AGENT_REGISTRY[runtime as AgentName]?.label ?? runtime;
-}
-
 function printCost(): undefined {
   const months = costMonths(eventsSince("model_call", new Date(0)));
-  for (const line of costLines(months, labelOf)) console.log(line);
+  for (const line of costLines(months, labelOfRuntime)) console.log(line);
 }
 
 export const costCommand = leaf({

package/src/cli/tree.ts

@@ -28,6 +28,7 @@ import { serverCommand } from "./server";
 import { skillCommand } from "./skill";
 import { subagentCommand } from "./subagent";
 import { usageCommand } from "./usage";
+import { wrappedCommand } from "./wrapped";
 
 type Handler = Leaf["run"];
 export type DebugState = "on" | "off" | "status";
@@ -155,6 +156,7 @@ export function cliTree(admin: AdminHandlers): Group {
       ...adminCommands(admin),
       usage: usageCommand,
       cost: costCommand,
+      wrapped: wrappedCommand,
       content: contentCommand,
       events: eventsCommand,
       infer: inferCommand,

package/src/cli/wrapped.ts

@@ -0,0 +1,50 @@
+import { readSkillIndex } from "../hooks/lib/skill-match";
+import { leaf, UsageError } from "../tools/lib/command";
+import { wrappedAgents } from "../tools/lib/wrapped/agents";
+import { wrappedHabits } from "../tools/lib/wrapped/habits";
+import { wrappedPal } from "../tools/lib/wrapped/pal";
+import { wrappedRecords } from "../tools/lib/wrapped/records";
+import {
+  agentsLines,
+  habitsLines,
+  palLines,
+  recordsLines,
+  totalsLines,
+} from "../tools/lib/wrapped/render";
+import { wrappedTotals } from "../tools/lib/wrapped/totals";
+import { eventsOfYear } from "../tools/lib/wrapped/year";
+
+function yearFrom(value: string | undefined): number {
+  if (value === undefined) return new Date().getFullYear();
+  if (!/^\d{4}$/.test(value)) throw new UsageError(`--year takes a year, got: ${value}`);
+  return Number(value);
+}
+
+function printWrapped(year: number): undefined {
+  const events = eventsOfYear(year);
+  console.log(`\n  PAL Wrapped ${year}`);
+  if (events.length === 0) {
+    console.log(`\n  No events logged in ${year}\n`);
+    return;
+  }
+  const lines = [
+    ...totalsLines(wrappedTotals(events)),
+    ...recordsLines(wrappedRecords(events)),
+    ...habitsLines(wrappedHabits(events)),
+    ...agentsLines(wrappedAgents(events)),
+    ...palLines(wrappedPal(events, readSkillIndex())),
+  ];
+  for (const line of lines) console.log(line);
+}
+
+export const wrappedCommand = leaf({
+  summary: "A year of your work in numbers, read from the event log",
+  options: {
+    year: {
+      type: "string",
+      value: "<yyyy>",
+      description: "Which year (default: this one)",
+    },
+  },
+  run: ({ values }) => printWrapped(yearFrom(values.year)),
+});

package/src/hooks/lib/agent-registry.ts

@@ -86,3 +86,7 @@ export function skillsDirOf(agent: AgentName): string {
 export function isAgentName(value: string): value is AgentName {
   return Object.hasOwn(AGENT_REGISTRY, value);
 }
+
+export function labelOfRuntime(runtime: string): string {
+  return isAgentName(runtime) ? AGENT_REGISTRY[runtime].label : runtime;
+}

package/src/hooks/lib/events.ts

@@ -322,7 +322,7 @@ export function eventsInMonth(type: EventType, month: Date): LoggedEvent[] {
   return parseLines(file).filter((e) => e.type === type);
 }
 
-export function eventsSince(type: EventType, since: Date): LoggedEvent[] {
+export function allEventsSince(since: Date): LoggedEvent[] {
   const dir = eventsDir();
   const sinceTs = since.toISOString();
   const fromMonth = monthOf(sinceTs);
@@ -330,5 +330,9 @@ export function eventsSince(type: EventType, since: Date): LoggedEvent[] {
     .filter((f) => f.endsWith(".jsonl") && f.slice(0, 7) >= fromMonth)
     .sort()
     .flatMap((f) => parseLines(resolve(dir, f)))
-    .filter((e) => e.type === type && e.ts >= sinceTs);
+    .filter((e) => e.ts >= sinceTs);
+}
+
+export function eventsSince(type: EventType, since: Date): LoggedEvent[] {
+  return allEventsSince(since).filter((e) => e.type === type);
 }

package/src/hooks/lib/skill-match.ts

@@ -45,7 +45,7 @@ function normalize(text: string): string {
     .trim()} `;
 }
 
-function readSkillIndex(): SkillIndex | null {
+export function readSkillIndex(): SkillIndex | null {
   const path = resolve(paths.state(), "skill-index.json");
   if (!existsSync(path)) return null;
   try {

package/src/hooks/lib/wall-clock.ts

@@ -19,17 +19,25 @@ const FIELDS = {
   hourCycle: "h23",
 } as const;
 
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatterFor(timeZone: string): Intl.DateTimeFormat {
+  const cached = formatters.get(timeZone);
+  if (cached) return cached;
+  const formatter = new Intl.DateTimeFormat("en-US", { ...FIELDS, timeZone });
+  formatters.set(timeZone, formatter);
+  return formatter;
+}
+
 function fieldsIn(now: Date, timeZone: string): Record<string, string> {
-  const parts = new Intl.DateTimeFormat("en-US", { ...FIELDS, timeZone }).formatToParts(
-    now
-  );
+  const parts = formatterFor(timeZone).formatToParts(now);
   return Object.fromEntries(parts.map((p) => [p.type, p.value]));
 }
 
 /** The IANA name Intl settles on, or null when it does not recognise the input. */
 export function canonicalTimeZone(timeZone: string): string | null {
   try {
-    return new Intl.DateTimeFormat("en-US", { timeZone }).resolvedOptions().timeZone;
+    return formatterFor(timeZone).resolvedOptions().timeZone;
   } catch {
     return null;
   }

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

@@ -24,7 +24,7 @@ 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 {
+export 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;
@@ -93,6 +93,25 @@ function paidFor(month: AgentMonth): number | null {
   return paid;
 }
 
+export interface CostTotals {
+  apiEquivalent: number;
+  unpriced: number;
+  paid: number | null;
+}
+
+/** Paid is null when any agent-month's payment is unknown. */
+export function costTotals(months: CostMonths): CostTotals {
+  const agentMonths = [...months.values()].flatMap((agents) => [...agents.values()]);
+  const paids = agentMonths.map(paidFor);
+  return {
+    apiEquivalent: agentMonths.reduce((sum, m) => sum + m.apiEquivalent, 0),
+    unpriced: agentMonths.reduce((sum, m) => sum + m.unpriced, 0),
+    paid: paids.includes(null)
+      ? null
+      : paids.reduce<number>((sum, p) => sum + (p ?? 0), 0),
+  };
+}
+
 /** Null unless both sides are known and something was paid. */
 function leverageOf(month: AgentMonth): number | null {
   const paid = paidFor(month);

package/src/tools/lib/wrapped/agents.ts

@@ -0,0 +1,30 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { type CostTotals, costMonths, costTotals } from "../cost-report";
+import { ofType, type Tally, tally } from "./year";
+
+export interface RuntimeCost {
+  runtime: string;
+  calls: number;
+  cost: CostTotals;
+}
+
+export interface WrappedAgents {
+  messages: Tally[];
+  costs: RuntimeCost[];
+}
+
+const runtimeOf = (e: LoggedEvent) => e.runtime;
+
+function costOf(runtime: string, calls: LoggedEvent[]): RuntimeCost {
+  const own = calls.filter((c) => c.runtime === runtime);
+  return { runtime, calls: own.length, cost: costTotals(costMonths(own)) };
+}
+
+/** Shares are counted on the user's messages: sessions are minutes long on one agent and days long on another. */
+export function wrappedAgents(events: LoggedEvent[]): WrappedAgents {
+  const calls = ofType(events, "model_call");
+  return {
+    messages: tally(ofType(events, "turn"), runtimeOf),
+    costs: tally(calls, runtimeOf).map(({ name }) => costOf(name, calls)),
+  };
+}

package/src/tools/lib/wrapped/habits.ts

@@ -0,0 +1,65 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { localClock } from "../../../hooks/lib/wall-clock";
+import type { Best } from "./records";
+import { dayOf, isUserActivity, ofType, type Tally, tally } from "./year";
+
+export interface WrappedHabits {
+  mostActiveHour: Best | null;
+  nightShare: number | null;
+  weekendShare: number | null;
+  channels: Tally[];
+  skimRate: number | null;
+  correctionRate: number | null;
+}
+
+interface HourSlot {
+  hour: number;
+  weekday: string;
+}
+
+const NIGHT_FROM = 22;
+const NIGHT_UNTIL = 6;
+const WEEKEND = new Set(["Sat", "Sun"]);
+
+/** One slot per local hour with any of the user's own activity, however busy it was. */
+function activeSlots(events: LoggedEvent[]): HourSlot[] {
+  const slots = new Map<string, HourSlot>();
+  for (const e of events.filter(isUserActivity)) {
+    const clock = localClock(new Date(e.ts));
+    slots.set(`${dayOf(e)} ${clock.hour}`, clock);
+  }
+  return [...slots.values()];
+}
+
+function shareOf<T>(items: T[], matches: (item: T) => boolean): number | null {
+  return items.length === 0 ? null : items.filter(matches).length / items.length;
+}
+
+function mostActiveHour(slots: HourSlot[]): Best | null {
+  const perHour = new Map<number, number>();
+  for (const { hour } of slots) perHour.set(hour, (perHour.get(hour) ?? 0) + 1);
+  const [top] = [...perHour].sort(([ha, a], [hb, b]) => b - a || ha - hb);
+  return top ? { value: top[1], label: `${String(top[0]).padStart(2, "0")}:00` } : null;
+}
+
+const isNight = ({ hour }: HourSlot) => hour >= NIGHT_FROM || hour < NIGHT_UNTIL;
+
+const channelOf = (turn: LoggedEvent) =>
+  typeof turn.channel === "string" ? turn.channel : "terminal";
+
+/** Skimming is only measured on a turn that answered a reply. */
+export function wrappedHabits(events: LoggedEvent[]): WrappedHabits {
+  const slots = activeSlots(events);
+  const turns = ofType(events, "turn");
+  return {
+    mostActiveHour: mostActiveHour(slots),
+    nightShare: shareOf(slots, isNight),
+    weekendShare: shareOf(slots, (s) => WEEKEND.has(s.weekday)),
+    channels: tally(turns, channelOf),
+    skimRate: shareOf(
+      turns.filter((t) => t.reply !== null && t.reply !== undefined),
+      (t) => t.skimmed === true
+    ),
+    correctionRate: shareOf(turns, (t) => t.corrected === true),
+  };
+}

package/src/tools/lib/wrapped/pal.ts

@@ -0,0 +1,53 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import type { SkillIndex } from "../../../hooks/lib/skill-match";
+import { dayOf, numberOf, ofType, type Tally, tally } from "./year";
+
+export interface SkillsNeverUsed {
+  names: string[];
+  installed: number;
+  since: string;
+}
+
+export interface WrappedPal {
+  skillsUsed: Tally[];
+  skillsNeverUsed: SkillsNeverUsed | null;
+  promisesOnTime: number | null;
+  promisesKept: number;
+}
+
+const skillOf = (call: LoggedEvent) => String(call.skill);
+
+/** Only as far back as tool calls were logged, and only when the installed skills are known. */
+function neverUsed(
+  calls: LoggedEvent[],
+  used: Tally[],
+  index: SkillIndex | null
+): SkillsNeverUsed | null {
+  const [first] = [...calls].sort((a, b) => a.ts.localeCompare(b.ts));
+  if (index === null || first === undefined) return null;
+  const installed = Object.keys(index.skills).sort();
+  const names = installed.filter((name) => !used.some((u) => u.name === name));
+  return { names, installed: installed.length, since: dayOf(first) };
+}
+
+/** A promise kept by its due time; one closed any other way never counts. */
+function promisesKeptOnTime(events: LoggedEvent[]) {
+  const kept = ofType(events, "promise").filter(
+    (p) => p.change === "done" && numberOf(p.lateSec) !== null
+  );
+  const onTime = kept.filter((p) => Number(p.lateSec) <= 0).length;
+  return { promisesOnTime: kept.length === 0 ? null : onTime, promisesKept: kept.length };
+}
+
+export function wrappedPal(events: LoggedEvent[], index: SkillIndex | null): WrappedPal {
+  const calls = ofType(events, "tool_call");
+  const used = tally(
+    calls.filter((c) => typeof c.skill === "string"),
+    skillOf
+  );
+  return {
+    skillsUsed: used,
+    skillsNeverUsed: neverUsed(calls, used, index),
+    ...promisesKeptOnTime(events),
+  };
+}

package/src/tools/lib/wrapped/records.ts

@@ -0,0 +1,137 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { dayOf, isUserActivity, numberOf, ofType } from "./year";
+
+export interface Best {
+  value: number;
+  label: string;
+}
+
+export interface WrappedRecords {
+  projectsRegisteredInADay: Best | null;
+  commitsInADay: Best | null;
+  longestProject: Best | null;
+  longestStreak: Best | null;
+  longestAgentRun: Best | null;
+  mostExpensiveTurn: Best | null;
+  biggestToolBurst: Best | null;
+}
+
+const DAY_MS = 86_400_000;
+
+function best(candidates: Best[]): Best | null {
+  return candidates.reduce<Best | null>(
+    (top, c) => (top === null || c.value > top.value ? c : top),
+    null
+  );
+}
+
+function countBy(events: LoggedEvent[], keyOf: (e: LoggedEvent) => string): Best[] {
+  const counts = new Map<string, number>();
+  for (const e of events) counts.set(keyOf(e), (counts.get(keyOf(e)) ?? 0) + 1);
+  return [...counts].map(([label, value]) => ({ label, value }));
+}
+
+function daysBetween(from: string, to: string): number {
+  return Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS);
+}
+
+function longestProject(events: LoggedEvent[]): Best | null {
+  const daysOf = new Map<string, string[]>();
+  for (const e of events) {
+    if (e.project === null) continue;
+    daysOf.set(e.project, [...(daysOf.get(e.project) ?? []), dayOf(e)]);
+  }
+  return best(
+    [...daysOf].map(([project, days]) => {
+      const [first, ...rest] = days.sort();
+      return { label: project, value: daysBetween(first, rest.at(-1) ?? first) + 1 };
+    })
+  );
+}
+
+function longestStreak(events: LoggedEvent[]): Best | null {
+  const days = [...new Set(events.filter(isUserActivity).map(dayOf))].sort();
+  const runs: Best[] = [];
+  let start = 0;
+  for (let i = 1; i <= days.length; i++) {
+    if (i < days.length && daysBetween(days[i - 1], days[i]) === 1) continue;
+    runs.push({ value: i - start, label: `${days[start]} → ${days[i - 1]}` });
+    start = i;
+  }
+  return best(runs);
+}
+
+function longestAgentRun(events: LoggedEvent[]): Best | null {
+  return best(
+    ofType(events, "reply").flatMap((e) => {
+      const sec = numberOf(e.latencySec);
+      return sec === null ? [] : [{ value: sec, label: dayOf(e) }];
+    })
+  );
+}
+
+interface TurnSpan {
+  turn: LoggedEvent;
+  inside: LoggedEvent[];
+}
+
+/** Each user turn and what happened in its session until the next one. */
+function turnSpans(events: LoggedEvent[]): TurnSpan[] {
+  const open = new Map<string, TurnSpan>();
+  const spans: TurnSpan[] = [];
+  const inTimeOrder = [...events].sort((a, b) => a.ts.localeCompare(b.ts));
+  for (const e of inTimeOrder) {
+    if (e.session === null) continue;
+    if (e.type === "turn") {
+      const span = { turn: e, inside: [] };
+      open.set(e.session, span);
+      spans.push(span);
+    } else open.get(e.session)?.inside.push(e);
+  }
+  return spans;
+}
+
+const whereAndWhen = (turn: LoggedEvent) =>
+  turn.project === null ? dayOf(turn) : `${dayOf(turn)}, ${turn.project}`;
+
+/** A turn with any call PAL cannot price is left out rather than undercounted. */
+function turnCost({ inside }: TurnSpan): number | null {
+  const prices = ofType(inside, "model_call").map(apiPriceOf);
+  if (prices.length === 0 || prices.includes(null)) return null;
+  return prices.reduce<number>((sum, p) => sum + (p ?? 0), 0);
+}
+
+function mostExpensiveTurn(spans: TurnSpan[]): Best | null {
+  return best(
+    spans.flatMap((span) => {
+      const cost = turnCost(span);
+      return cost === null ? [] : [{ value: cost, label: whereAndWhen(span.turn) }];
+    })
+  );
+}
+
+function biggestToolBurst(spans: TurnSpan[]): Best | null {
+  return best(
+    spans
+      .map((span) => ({
+        value: ofType(span.inside, "tool_call").length,
+        label: whereAndWhen(span.turn),
+      }))
+      .filter((b) => b.value > 0)
+  );
+}
+
+export function wrappedRecords(events: LoggedEvent[]): WrappedRecords {
+  const registered = ofType(events, "project").filter((e) => e.change === "registered");
+  const spans = turnSpans(events);
+  return {
+    projectsRegisteredInADay: best(countBy(registered, dayOf)),
+    commitsInADay: best(countBy(ofType(events, "commit"), dayOf)),
+    longestProject: longestProject(events),
+    longestStreak: longestStreak(events),
+    longestAgentRun: longestAgentRun(events),
+    mostExpensiveTurn: mostExpensiveTurn(spans),
+    biggestToolBurst: biggestToolBurst(spans),
+  };
+}

package/src/tools/lib/wrapped/render.ts

@@ -0,0 +1,145 @@
+import { labelOfRuntime } from "../../../hooks/lib/agent-registry";
+import type { CostTotals } from "../cost-report";
+import { fmtDuration } from "../session-usage";
+import { fmtCost } from "../token-report";
+import type { RuntimeCost, WrappedAgents } from "./agents";
+import type { WrappedHabits } from "./habits";
+import type { SkillsNeverUsed, WrappedPal } from "./pal";
+import type { Best, WrappedRecords } from "./records";
+import type { WrappedTotals } from "./totals";
+import type { Tally } from "./year";
+
+const count = (n: number) => n.toLocaleString("en-US");
+
+function row(label: string, value: string): string {
+  return `    ${label.padEnd(20)} ${value}`;
+}
+
+function recordRow(
+  label: string,
+  record: Best | null,
+  format: (value: number) => string
+): string {
+  const value =
+    record === null ? "unknown" : `${format(record.value)}  (${record.label})`;
+  return `    ${label.padEnd(36)} ${value}`;
+}
+
+const days = (n: number) => `${count(n)} ${n === 1 ? "day" : "days"}`;
+
+export function recordsLines(records: WrappedRecords): string[] {
+  return [
+    "\n  Records\n",
+    recordRow(
+      "most projects registered in a day",
+      records.projectsRegisteredInADay,
+      count
+    ),
+    recordRow("most commits in a day", records.commitsInADay, count),
+    recordRow("longest project", records.longestProject, days),
+    recordRow("longest streak", records.longestStreak, days),
+    recordRow("longest agent-alone run", records.longestAgentRun, (sec) =>
+      fmtDuration(sec * 1000)
+    ),
+    recordRow("most expensive turn", records.mostExpensiveTurn, fmtCost),
+    recordRow(
+      "biggest tool burst",
+      records.biggestToolBurst,
+      (n) => `${count(n)} tool calls`
+    ),
+  ];
+}
+
+const percent = (share: number | null) =>
+  share === null ? "unknown" : `${Math.round(share * 100)}%`;
+
+function tallyLabel(tallies: Tally[]): string {
+  if (tallies.length === 0) return "unknown";
+  return tallies.map((t) => `${t.name} ${count(t.count)}`).join(" · ");
+}
+
+export function habitsLines(habits: WrappedHabits): string[] {
+  const hour = habits.mostActiveHour;
+  return [
+    "\n  Habits\n",
+    row(
+      "most active hour",
+      hour === null ? "unknown" : `${hour.label}  (active on ${days(hour.value)})`
+    ),
+    row("at night (22-06)", percent(habits.nightShare)),
+    row("on weekends", percent(habits.weekendShare)),
+    row("messages by channel", tallyLabel(habits.channels)),
+    row("skimmed replies", percent(habits.skimRate)),
+    row("corrections", percent(habits.correctionRate)),
+  ];
+}
+
+function neverUsedLines(never: SkillsNeverUsed | null): string[] {
+  if (never === null) return [row("skills never used", "unknown")];
+  const summary = `${count(never.names.length)} of ${count(never.installed)} since ${never.since}`;
+  const names = never.names.length > 0 ? [row("", never.names.join(", "))] : [];
+  return [row("skills never used", summary), ...names];
+}
+
+/** Nothing logs a steering rule being approved yet. */
+export function palLines(pal: WrappedPal): string[] {
+  const onTime = pal.promisesOnTime;
+  return [
+    "\n  PAL\n",
+    row("skills used", tallyLabel(pal.skillsUsed)),
+    ...neverUsedLines(pal.skillsNeverUsed),
+    row("rules approved", "unknown"),
+    row(
+      "promises on time",
+      onTime === null ? "unknown" : `${count(onTime)} of ${count(pal.promisesKept)}`
+    ),
+  ];
+}
+
+function tokensLabel(totals: WrappedTotals): string {
+  const unknown = totals.callsWithoutTokens;
+  return unknown > 0
+    ? `${count(totals.tokens)} + ${count(unknown)} calls without counts`
+    : count(totals.tokens);
+}
+
+function apiEquivalentLabel(cost: CostTotals): string {
+  const priced = fmtCost(cost.apiEquivalent);
+  return cost.unpriced > 0
+    ? `${priced} + ${count(cost.unpriced)} unpriced calls`
+    : priced;
+}
+
+const paidLabel = (paid: number | null) => (paid === null ? "unknown" : fmtCost(paid));
+
+function runtimeCostLabel({ runtime, calls, cost }: RuntimeCost): string {
+  const api = cost.unpriced === calls ? "unknown" : apiEquivalentLabel(cost);
+  return `${labelOfRuntime(runtime)}  API-equivalent ${api}, paid ${paidLabel(cost.paid)}`;
+}
+
+const labelled = (tallies: Tally[]) =>
+  tallies.map((t) => ({ ...t, name: labelOfRuntime(t.name) }));
+
+/** No agent reports which of Cursor's lines a human typed yet. */
+export function agentsLines(agents: WrappedAgents): string[] {
+  const [first, ...rest] = agents.costs.map(runtimeCostLabel);
+  return [
+    "\n  Agents\n",
+    row("messages by agent", tallyLabel(labelled(agents.messages))),
+    row("cost by agent", first ?? "unknown"),
+    ...rest.map((label) => row("", label)),
+    row("Cursor human vs AI", "unknown"),
+  ];
+}
+
+export function totalsLines(totals: WrappedTotals): string[] {
+  return [
+    "\n  Totals\n",
+    row("projects", count(totals.projects)),
+    row("sessions", count(totals.sessions)),
+    row("commits", count(totals.commits)),
+    row("tokens", tokensLabel(totals)),
+    row("API-equivalent", apiEquivalentLabel(totals.cost)),
+    row("paid", paidLabel(totals.cost.paid)),
+  ];
+}

package/src/tools/lib/wrapped/totals.ts

@@ -0,0 +1,55 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { type CostTotals, costMonths, costTotals } from "../cost-report";
+import { numberOf, ofType } from "./year";
+
+export interface WrappedTotals {
+  projects: number;
+  sessions: number;
+  commits: number;
+  tokens: number;
+  callsWithoutTokens: number;
+  cost: CostTotals;
+}
+
+const TOKEN_FIELDS = [
+  "inputTokens",
+  "outputTokens",
+  "cacheWrite5m",
+  "cacheWrite1h",
+  "cacheRead",
+] as const;
+
+function tokensOf(call: LoggedEvent): number | null {
+  const known = TOKEN_FIELDS.map((f) => numberOf(call[f])).filter((n) => n !== null);
+  return known.length === 0 ? null : known.reduce((sum, n) => sum + n, 0);
+}
+
+function distinct(values: (string | null)[]): number {
+  return new Set(values.filter((v) => v !== null)).size;
+}
+
+const isSpawnedCall = (e: LoggedEvent) =>
+  e.type === "model_call" && e.entrypoint === "sdk-cli";
+
+const showsTheUser = (e: LoggedEvent) =>
+  e.type === "turn" || (e.type === "model_call" && !isSpawnedCall(e));
+
+/** PAL's own background inference runs as SDK sessions nobody typed into. */
+function sessionsOfTheUser(events: LoggedEvent[]): number {
+  const spawned = new Set(events.filter(isSpawnedCall).map((e) => e.session));
+  for (const e of events.filter(showsTheUser)) spawned.delete(e.session);
+  return distinct(events.map((e) => e.session).filter((s) => !spawned.has(s)));
+}
+
+export function wrappedTotals(events: LoggedEvent[]): WrappedTotals {
+  const calls = ofType(events, "model_call");
+  const tokens = calls.map(tokensOf);
+  return {
+    projects: distinct(events.map((e) => e.project)),
+    sessions: sessionsOfTheUser(events),
+    commits: ofType(events, "commit").length,
+    tokens: tokens.reduce<number>((sum, n) => sum + (n ?? 0), 0),
+    callsWithoutTokens: tokens.filter((n) => n === null).length,
+    cost: costTotals(costMonths(calls)),
+  };
+}

package/src/tools/lib/wrapped/year.ts

@@ -0,0 +1,45 @@
+import {
+  allEventsSince,
+  type EventType,
+  type LoggedEvent,
+} from "../../../hooks/lib/events";
+import { localDay } from "../../../hooks/lib/wall-clock";
+
+export function dayOf(event: LoggedEvent): string {
+  return localDay(new Date(event.ts));
+}
+
+export function ofType(events: LoggedEvent[], type: EventType): LoggedEvent[] {
+  return events.filter((e) => e.type === type);
+}
+
+export const isUserActivity = (e: LoggedEvent) =>
+  e.type === "commit" ||
+  e.type === "turn" ||
+  (e.type === "model_call" && e.entrypoint !== "sdk-cli");
+
+export interface Tally {
+  name: string;
+  count: number;
+}
+
+/** Most frequent first, ties by name. */
+export function tally<T>(items: T[], nameOf: (item: T) => string): Tally[] {
+  const counts = new Map<string, number>();
+  for (const item of items) {
+    const name = nameOf(item);
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return [...counts]
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+
+export function numberOf(value: unknown): number | null {
+  return typeof value === "number" ? value : null;
+}
+
+export function eventsOfYear(year: number): LoggedEvent[] {
+  const dayBeforeInUtc = new Date(Date.UTC(year - 1, 11, 31));
+  return allEventsSince(dayBeforeInUtc).filter((e) => dayOf(e).startsWith(`${year}-`));
+}