portable-agent-layer 0.100.0 → 0.102.0

package/README.md

@@ -86,6 +86,8 @@ 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 patterns` | How you work across projects, 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.102.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/patterns.ts

@@ -0,0 +1,31 @@
+import { allEventsSince } from "../hooks/lib/events";
+import { localDay } from "../hooks/lib/wall-clock";
+import { leaf } from "../tools/lib/command";
+import { projectActivity } from "../tools/lib/patterns/activity";
+import { contextSwitches, dayShape } from "../tools/lib/patterns/days";
+import { focusBlocks } from "../tools/lib/patterns/focus";
+import { projectProfiles } from "../tools/lib/patterns/profiles";
+import {
+  daysLines,
+  focusLines,
+  momentumLines,
+  projectsLines,
+} from "../tools/lib/patterns/render";
+import { currentSprint, quietAfterBurst } from "../tools/lib/patterns/sprint";
+
+function printPatterns(): undefined {
+  const activity = projectActivity(allEventsSince(new Date(0)));
+  console.log("\n  PAL Patterns");
+  const lines = [
+    ...momentumLines(currentSprint(activity), quietAfterBurst(activity, localDay())),
+    ...daysLines(dayShape(activity), contextSwitches(activity)),
+    ...focusLines(focusBlocks(activity)),
+    ...projectsLines(projectProfiles(activity)),
+  ];
+  for (const line of lines) console.log(line);
+}
+
+export const patternsCommand = leaf({
+  summary: "How you work across projects, read from the event log",
+  run: () => printPatterns(),
+});

package/src/cli/tree.ts

@@ -22,12 +22,14 @@ import { inferCommand } from "./infer";
 import { knowledgeCommand } from "./knowledge";
 import { ledgerCommand } from "./ledger-command";
 import { runMigrate } from "./migrate";
+import { patternsCommand } from "./patterns";
 import { telosCommand, timezoneCommand } from "./personal-context";
 import { ruleCommand } from "./rule";
 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 +157,8 @@ export function cliTree(admin: AdminHandlers): Group {
       ...adminCommands(admin),
       usage: usageCommand,
       cost: costCommand,
+      wrapped: wrappedCommand,
+      patterns: patternsCommand,
       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/patterns/activity.ts

@@ -0,0 +1,41 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { dayOf, isUserActivity } from "../wrapped/year";
+
+export interface Activity {
+  ms: number;
+  day: string;
+  project: string;
+  event: LoggedEvent;
+}
+
+/** The user's own work that landed in a project, oldest first. */
+export function projectActivity(events: LoggedEvent[]): Activity[] {
+  return events
+    .filter(isUserActivity)
+    .flatMap((event) =>
+      typeof event.project === "string"
+        ? [{ ms: Date.parse(event.ts), day: dayOf(event), project: event.project, event }]
+        : []
+    )
+    .sort((a, b) => a.ms - b.ms);
+}
+
+export const movesAttention = ({ event }: Activity) =>
+  event.type === "turn" || event.type === "commit";
+
+export function projectsByDay(activity: Activity[]): Map<string, Set<string>> {
+  const byDay = new Map<string, Set<string>>();
+  for (const { day, project } of activity) {
+    byDay.set(day, (byDay.get(day) ?? new Set()).add(project));
+  }
+  return byDay;
+}
+
+/** Oldest day first, as the activity is. */
+export function daysByProject(activity: Activity[]): Map<string, string[]> {
+  const byProject = new Map<string, Set<string>>();
+  for (const { day, project } of activity) {
+    byProject.set(project, (byProject.get(project) ?? new Set()).add(day));
+  }
+  return new Map([...byProject].map(([project, days]) => [project, [...days]]));
+}

package/src/tools/lib/patterns/days.ts

@@ -0,0 +1,38 @@
+import type { Best } from "../wrapped/records";
+import { type Activity, movesAttention, projectsByDay } from "./activity";
+
+export interface DayShape {
+  oneProject: number;
+  manyProjects: number;
+}
+
+export interface Switches {
+  perDay: number;
+  mostInADay: Best;
+}
+
+export function dayShape(activity: Activity[]): DayShape {
+  const sizes = [...projectsByDay(activity).values()].map((projects) => projects.size);
+  return {
+    oneProject: sizes.filter((n) => n === 1).length,
+    manyProjects: sizes.filter((n) => n > 1).length,
+  };
+}
+
+/** Model calls are left out: two sessions running side by side interleave theirs without the user moving. */
+export function contextSwitches(activity: Activity[]): Switches | null {
+  const moves = activity.filter(movesAttention);
+  const perDay = new Map<string, number>();
+  moves.forEach((a, i) => {
+    const previous = moves[i - 1];
+    const switched = previous?.day === a.day && previous.project !== a.project;
+    perDay.set(a.day, (perDay.get(a.day) ?? 0) + (switched ? 1 : 0));
+  });
+  const counts = [...perDay];
+  if (counts.length === 0) return null;
+  const [day, most] = counts.reduce((top, c) => (c[1] > top[1] ? c : top));
+  return {
+    perDay: counts.reduce((sum, [, n]) => sum + n, 0) / counts.length,
+    mostInADay: { value: most, label: day },
+  };
+}

package/src/tools/lib/patterns/focus.ts

@@ -0,0 +1,59 @@
+import type { Best } from "../wrapped/records";
+import { type Activity, movesAttention } from "./activity";
+
+export interface Focus {
+  blocks: number;
+  minutes: number;
+  longest: Best | null;
+}
+
+interface Block {
+  first: Activity;
+  last: Activity;
+}
+
+const MINUTE_MS = 60_000;
+const FOCUS_MINUTES = 90;
+const MAX_GAP_MINUTES = 30;
+
+const minutesOf = ({ first, last }: Block) => (last.ms - first.ms) / MINUTE_MS;
+
+function continues(block: Block, next: Activity): boolean {
+  return (
+    next.project === block.last.project &&
+    (next.ms - block.last.ms) / MINUTE_MS <= MAX_GAP_MINUTES
+  );
+}
+
+/** A parallel session's model calls in another project leave the block alone; the user moving there ends it. */
+function blocksOf(activity: Activity[]): Block[] {
+  const blocks: Block[] = [];
+  for (const next of activity) {
+    const current = blocks.at(-1);
+    if (current && continues(current, next)) current.last = next;
+    else if (!current || current.last.project === next.project || movesAttention(next))
+      blocks.push({ first: next, last: next });
+  }
+  return blocks;
+}
+
+/** 90 minutes or more on one project with no gap over 30. */
+export function focusBlocks(activity: Activity[]): Focus | null {
+  if (activity.length === 0) return null;
+  const focused = blocksOf(activity).filter((b) => minutesOf(b) >= FOCUS_MINUTES);
+  const longest = focused.reduce<Block | null>(
+    (top, b) => (top === null || minutesOf(b) > minutesOf(top) ? b : top),
+    null
+  );
+  return {
+    blocks: focused.length,
+    minutes: focused.reduce((sum, b) => sum + minutesOf(b), 0),
+    longest:
+      longest === null
+        ? null
+        : {
+            value: minutesOf(longest),
+            label: `${longest.first.project}, ${longest.first.day}`,
+          },
+  };
+}

package/src/tools/lib/patterns/profiles.ts

@@ -0,0 +1,59 @@
+import { labelOfRuntime } from "../../../hooks/lib/agent-registry";
+import { localClock } from "../../../hooks/lib/wall-clock";
+import { channelOf } from "../wrapped/habits";
+import { type Tally, tally } from "../wrapped/year";
+import type { Activity } from "./activity";
+
+export interface ProjectProfile {
+  project: string;
+  activeDays: number;
+  hour: string;
+  weekday: string;
+  agents: Tally[];
+  channels: Tally[];
+}
+
+interface Slot {
+  hour: string;
+  weekday: string;
+}
+
+/** One slot per local hour the project saw work, however busy it was. */
+function slotsOf(activity: Activity[]): Slot[] {
+  const slots = new Map<string, Slot>();
+  for (const a of activity) {
+    const clock = localClock(new Date(a.ms));
+    const hour = `${String(clock.hour).padStart(2, "0")}:00`;
+    slots.set(`${a.day} ${hour}`, { hour, weekday: clock.weekday });
+  }
+  return [...slots.values()];
+}
+
+const topOf = (slots: Slot[], labelOf: (slot: Slot) => string) =>
+  tally(slots, labelOf)[0].name;
+
+function profileOf(project: string, activity: Activity[]): ProjectProfile {
+  const slots = slotsOf(activity);
+  const turns = activity.filter((a) => a.event.type === "turn").map((a) => a.event);
+  return {
+    project,
+    activeDays: new Set(activity.map((a) => a.day)).size,
+    hour: topOf(slots, (s) => s.hour),
+    weekday: topOf(slots, (s) => s.weekday),
+    agents: tally(turns, (t) => labelOfRuntime(t.runtime)),
+    channels: tally(turns, channelOf),
+  };
+}
+
+/** Most worked-on first. */
+export function projectProfiles(activity: Activity[]): ProjectProfile[] {
+  const byProject = new Map<string, Activity[]>();
+  for (const a of activity) {
+    const own = byProject.get(a.project) ?? [];
+    byProject.set(a.project, own);
+    own.push(a);
+  }
+  return [...byProject]
+    .map(([project, own]) => profileOf(project, own))
+    .sort((a, b) => b.activeDays - a.activeDays || a.project.localeCompare(b.project));
+}

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

@@ -0,0 +1,89 @@
+import { count, days, row, tallyLabel } from "../report-rows";
+import type { DayShape, Switches } from "./days";
+import type { Focus } from "./focus";
+import type { ProjectProfile } from "./profiles";
+import type { QuietProject, Sprint } from "./sprint";
+
+function shapeLabel({ oneProject, manyProjects }: DayShape): string {
+  const total = oneProject + manyProjects;
+  if (total === 0) return "unknown";
+  return `${days(oneProject)} on one project, ${days(manyProjects)} on several (${Math.round((oneProject / total) * 100)}% focused)`;
+}
+
+function switchesLabel(switches: Switches | null): string {
+  if (switches === null) return "unknown";
+  const { value, label } = switches.mostInADay;
+  return `${switches.perDay.toFixed(1)} a day, at most ${count(value)} (${label})`;
+}
+
+function hoursAndMinutes(minutes: number): string {
+  const whole = Math.round(minutes);
+  return `${Math.floor(whole / 60)}h ${String(whole % 60).padStart(2, "0")}m`;
+}
+
+function longestLabel(focus: Focus): string {
+  const longest = focus.longest;
+  return longest === null
+    ? "none"
+    : `${hoursAndMinutes(longest.value)} (${longest.label})`;
+}
+
+export function focusLines(focus: Focus | null): string[] {
+  if (focus === null)
+    return ["\n  Focus\n", row("focus blocks", "unknown"), row("longest", "unknown")];
+  return [
+    "\n  Focus\n",
+    row(
+      "focus blocks",
+      `${count(focus.blocks)}, ${hoursAndMinutes(focus.minutes)} in all`
+    ),
+    row("longest", longestLabel(focus)),
+  ];
+}
+
+function profileLines(profile: ProjectProfile): string[] {
+  return [
+    row(
+      profile.project,
+      `${days(profile.activeDays)}, most at ${profile.hour} on ${profile.weekday}`
+    ),
+    row("  agents", tallyLabel(profile.agents)),
+    row("  channels", tallyLabel(profile.channels)),
+  ];
+}
+
+export function projectsLines(profiles: ProjectProfile[]): string[] {
+  if (profiles.length === 0) return ["\n  Projects\n", row("projects", "unknown")];
+  return ["\n  Projects\n", ...profiles.flatMap(profileLines)];
+}
+
+export function daysLines(shape: DayShape, switches: Switches | null): string[] {
+  return [
+    "\n  Days\n",
+    row("project days", shapeLabel(shape)),
+    row("context switches", switchesLabel(switches)),
+  ];
+}
+
+function quietLabel(quiet: QuietProject[]): string {
+  if (quiet.length === 0) return "none";
+  return quiet.map((q) => `${q.project} (quiet ${days(q.quietDays)})`).join(" · ");
+}
+
+/** With no activity at all, there is no telling which projects went quiet. */
+export function momentumLines(sprint: Sprint | null, quiet: QuietProject[]): string[] {
+  if (sprint === null)
+    return [
+      "\n  Momentum\n",
+      row("current sprint", "unknown"),
+      row("quiet after a burst", "unknown"),
+    ];
+  return [
+    "\n  Momentum\n",
+    row(
+      "current sprint",
+      `${sprint.project}, ${days(sprint.days)} of work since ${sprint.since}`
+    ),
+    row("quiet after a burst", quietLabel(quiet)),
+  ];
+}

package/src/tools/lib/patterns/sprint.ts

@@ -0,0 +1,58 @@
+import { daysBetween } from "../wrapped/year";
+import { type Activity, daysByProject, projectsByDay } from "./activity";
+
+export interface Sprint {
+  project: string;
+  days: number;
+  since: string;
+}
+
+export interface QuietProject {
+  project: string;
+  lastActive: string;
+  quietDays: number;
+  burstDays: number;
+}
+
+const BURST_DAYS = 3;
+const BURST_WINDOW_DAYS = 7;
+const QUIET_DAYS = 14;
+
+/** Counted in the days the user worked at all, so a weekend off does not end it. */
+export function currentSprint(activity: Activity[]): Sprint | null {
+  const days = [...projectsByDay(activity)];
+  const latest = days.at(-1);
+  if (latest === undefined) return null;
+  const sprints = [...latest[1]].map((project) => {
+    let start = days.length - 1;
+    while (start > 0 && days[start - 1][1].has(project)) start--;
+    return { project, days: days.length - start, since: days[start][0] };
+  });
+  return sprints.sort((a, b) => b.days - a.days || a.project.localeCompare(b.project))[0];
+}
+
+function busiestWindow(days: string[]): number {
+  let most = 0;
+  let start = 0;
+  for (let end = 0; end < days.length; end++) {
+    while (daysBetween(days[start], days[end]) >= BURST_WINDOW_DAYS) start++;
+    most = Math.max(most, end - start + 1);
+  }
+  return most;
+}
+
+/** A burst is 3 active days within 7; quiet is 14 days without any. */
+export function quietAfterBurst(activity: Activity[], today: string): QuietProject[] {
+  return [...daysByProject(activity)]
+    .map(([project, days]) => {
+      const lastActive = days.at(-1) ?? today;
+      return {
+        project,
+        lastActive,
+        quietDays: daysBetween(lastActive, today),
+        burstDays: busiestWindow(days),
+      };
+    })
+    .filter((p) => p.burstDays >= BURST_DAYS && p.quietDays >= QUIET_DAYS)
+    .sort((a, b) => b.lastActive.localeCompare(a.lastActive));
+}

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

@@ -0,0 +1,14 @@
+import type { Tally } from "./wrapped/year";
+
+export const count = (n: number) => n.toLocaleString("en-US");
+
+export function row(label: string, value: string): string {
+  return `    ${label.padEnd(20)} ${value}`;
+}
+
+export function tallyLabel(tallies: Tally[]): string {
+  if (tallies.length === 0) return "unknown";
+  return tallies.map((t) => `${t.name} ${count(t.count)}`).join(" · ");
+}
+
+export const days = (n: number) => `${count(n)} ${n === 1 ? "day" : "days"}`;

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,72 @@
+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;
+  mostActiveWeekday: Best | null;
+  mostActiveMonth: Best | null;
+  nightShare: number | null;
+  weekendShare: number | null;
+  channels: Tally[];
+  skimRate: number | null;
+  correctionRate: number | null;
+}
+
+interface HourSlot {
+  day: string;
+  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 day = dayOf(e);
+    const clock = localClock(new Date(e.ts));
+    slots.set(`${day} ${clock.hour}`, { day, ...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;
+}
+
+/** Ties go to the first label, which for hours and months is the earliest. */
+function busiest(slots: HourSlot[], labelOf: (slot: HourSlot) => string): Best | null {
+  const [top] = tally(slots, labelOf);
+  return top ? { value: top.count, label: top.name } : null;
+}
+
+const hourOf = ({ hour }: HourSlot) => `${String(hour).padStart(2, "0")}:00`;
+
+const isNight = ({ hour }: HourSlot) => hour >= NIGHT_FROM || hour < NIGHT_UNTIL;
+
+export 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: busiest(slots, hourOf),
+    mostActiveWeekday: busiest(slots, (s) => s.weekday),
+    mostActiveMonth: busiest(slots, (s) => s.day.slice(0, 7)),
+    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,131 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { dayOf, daysBetween, 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;
+}
+
+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 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,140 @@
+import { labelOfRuntime } from "../../../hooks/lib/agent-registry";
+import type { CostTotals } from "../cost-report";
+import { count, days, row, tallyLabel } from "../report-rows";
+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";
+
+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}`;
+}
+
+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)}%`;
+
+const hours = (n: number) => `${count(n)} active ${n === 1 ? "hour" : "hours"}`;
+
+function busiestLabel(best: Best | null, unit: (n: number) => string): string {
+  return best === null ? "unknown" : `${best.label}  (${unit(best.value)})`;
+}
+
+export function habitsLines(habits: WrappedHabits): string[] {
+  return [
+    "\n  Habits\n",
+    row(
+      "most active hour",
+      busiestLabel(habits.mostActiveHour, (n) => `active on ${days(n)}`)
+    ),
+    row("most active weekday", busiestLabel(habits.mostActiveWeekday, hours)),
+    row("most active month", busiestLabel(habits.mostActiveMonth, hours)),
+    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,51 @@
+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));
+}
+
+const DAY_MS = 86_400_000;
+
+export function daysBetween(from: string, to: string): number {
+  return Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS);
+}
+
+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}-`));
+}