portable-agent-layer 0.102.0 → 0.103.0

package/package.json

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

package/src/cli/cost.ts

@@ -1,11 +1,31 @@
 import { labelOfRuntime } from "../hooks/lib/agent-registry";
-import { eventsSince } from "../hooks/lib/events";
+import { allEventsSince } from "../hooks/lib/events";
 import { leaf } from "../tools/lib/command";
+import { efficiency } from "../tools/lib/cost/efficiency";
+import { leaderboards } from "../tools/lib/cost/leaderboards";
+import { modelMix, palSpend } from "../tools/lib/cost/mix";
+import { contextOverhead } from "../tools/lib/cost/overhead";
+import {
+  efficiencyLines,
+  leaderboardLines,
+  overheadLines,
+  shareLines,
+} from "../tools/lib/cost/render";
 import { costLines, costMonths } from "../tools/lib/cost-report";
+import { ofType } from "../tools/lib/wrapped/year";
 
 function printCost(): undefined {
-  const months = costMonths(eventsSince("model_call", new Date(0)));
-  for (const line of costLines(months, labelOfRuntime)) console.log(line);
+  const events = allEventsSince(new Date(0));
+  const months = costMonths(ofType(events, "model_call"));
+  const lines = [
+    ...costLines(months, labelOfRuntime),
+    ...leaderboardLines(leaderboards(events)),
+    ...efficiencyLines(efficiency(events)),
+    ...shareLines("Model mix", modelMix(events)),
+    ...shareLines("PAL's own spend per caller, already in the totals", palSpend(events)),
+    ...overheadLines(contextOverhead(events)),
+  ];
+  for (const line of lines) console.log(line);
 }
 
 export const costCommand = leaf({

package/src/hooks/LoadContext.ts

@@ -8,23 +8,21 @@
  * Which agent gets what, in which envelope, is in lib/session-context.ts.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
 import { getActiveAgent } from "./lib/agent";
 import { autoUpdateOnStart } from "./lib/auto-update";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
+import { logContextInjected } from "./lib/context-overhead";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logContextSnapshot, logDebug, logError } from "./lib/log";
-import { platform } from "./lib/paths";
 import {
   contextEnvelope,
   contextForSource,
-  copilotInstructions,
   isSubagentSession,
   needsAgentsMd,
+  writeCopilotInstructions,
 } from "./lib/session-context";
-import { logSessionStart } from "./lib/session-events";
+import { logSessionStart, type SessionStartPayload } from "./lib/session-events";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -49,7 +47,7 @@ try {
 
 try {
   const active = getActiveAgent();
-  const input = await readStdinJSON<{ source?: string }>();
+  const input = await readStdinJSON<SessionStartPayload>();
   logSessionStart(input);
   const wanted = contextForSource(active, input?.source);
   if (wanted === "none") {
@@ -75,15 +73,11 @@ try {
   );
   if (!envelope) process.exit(0);
 
-  if (envelope.file) {
-    const dir = resolve(platform.copilotDir(), "instructions");
-    mkdirSync(dir, { recursive: true });
-    const path = resolve(dir, "pal-session.instructions.md");
-    writeFileSync(path, copilotInstructions(envelope.file), "utf-8");
-  }
+  if (envelope.file) writeCopilotInstructions(envelope.file);
 
   if (envelope.kind === "text") console.log(envelope.payload);
   else process.stdout.write(envelope.payload);
+  logContextInjected(input, reminder);
   logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
 } catch (err) {
   logError("LoadContext:reminder", err);

package/src/hooks/lib/context-overhead.ts

@@ -0,0 +1,30 @@
+import { buildClaudeMd } from "./claude-md";
+import { appendEvent, logQuietly } from "./events";
+import { type HookTurnPayload, hookSessionId } from "./hook-turn";
+import { getSemiStaticSources, readFileSafe } from "./semi-static";
+
+function semiStaticChars(): number {
+  return getSemiStaticSources().reduce(
+    (sum, source) => sum + readFileSafe(source.path).length,
+    0
+  );
+}
+
+/** Chars, not tokens: no tokenizer runs at session start. */
+export function logContextInjected(
+  payload: HookTurnPayload | null,
+  reminder: string,
+  now: Date = new Date()
+): void {
+  logQuietly("context_injected", () =>
+    appendEvent(
+      "context_injected",
+      {
+        instructionsChars: buildClaudeMd().length,
+        semiStaticChars: semiStaticChars(),
+        dynamicChars: reminder.length,
+      },
+      { ts: now.toISOString(), session: hookSessionId(payload) ?? null }
+    )
+  );
+}

package/src/hooks/lib/events.ts

@@ -54,6 +54,7 @@ export const EVENT_FIELDS = {
   ],
   session_end: ["reason", "durationSec", "turns", "messages", "status"],
   compaction: ["trigger", "withInstructions", "contextTokens"],
+  context_injected: ["instructionsChars", "semiStaticChars", "dynamicChars"],
   hook_timing: ["hook", "totalMs", "handlers"],
   inference_call: [
     "caller",

package/src/hooks/lib/semi-static.ts

@@ -48,7 +48,7 @@ export function antigravityRule(description: string, content: string): string {
   return `---\ntrigger: always_on\ndescription: ${description}\n---\n\n${content}`;
 }
 
-function readFileSafe(path: string): string {
+export function readFileSafe(path: string): string {
   try {
     if (!existsSync(path)) return "";
     return readFileSync(path, "utf-8").trim();

package/src/hooks/lib/session-context.ts

@@ -7,7 +7,10 @@
  * context for weeks — and none of it was reachable from a test.
  */
 
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
 import type { AgentName } from "./agent-registry";
+import { platform } from "./paths";
 
 export interface ContextEnvelope {
   /** Whether the agent parses stdout as JSON or reads it as raw text. */
@@ -96,3 +99,10 @@ export function contextEnvelope(
 export function copilotInstructions(context: string): string {
   return `---\napplyTo: "**"\n---\n\n${context}`;
 }
+
+export function writeCopilotInstructions(context: string): void {
+  const dir = resolve(platform.copilotDir(), "instructions");
+  mkdirSync(dir, { recursive: true });
+  const path = resolve(dir, "pal-session.instructions.md");
+  writeFileSync(path, copilotInstructions(context), "utf-8");
+}

package/src/hooks/lib/session-events.ts

@@ -20,7 +20,7 @@ const SESSION_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
 const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
 const MAX_FIELD = 64;
 
-interface SessionStartPayload extends HookTurnPayload {
+export interface SessionStartPayload extends HookTurnPayload {
   source?: string;
   model?: unknown;
 }

package/src/tools/lib/cost/efficiency.ts

@@ -0,0 +1,58 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { dayOf, numberOf, ofType } from "../wrapped/year";
+
+export interface PerUnit {
+  cost: number;
+  units: number;
+  lowerBound: boolean;
+}
+
+export interface Efficiency {
+  since: string;
+  perCommit: PerUnit | null;
+  perClosedIsc: PerUnit | null;
+  cacheHitRate: number | null;
+}
+
+const PROMPT_FIELDS = [
+  "inputTokens",
+  "cacheRead",
+  "cacheWrite5m",
+  "cacheWrite1h",
+] as const;
+
+function cacheHitRate(calls: LoggedEvent[]): number | null {
+  let read = 0;
+  let prompt = 0;
+  for (const call of calls) {
+    for (const field of PROMPT_FIELDS) prompt += numberOf(call[field]) ?? 0;
+    read += numberOf(call.cacheRead) ?? 0;
+  }
+  return prompt === 0 ? null : read / prompt;
+}
+
+function perUnit(spent: number, unpriced: number, units: number): PerUnit | null {
+  return units === 0 ? null : { cost: spent / units, units, lowerBound: unpriced > 0 };
+}
+
+/** Only since the first logged model call: older commits and ISCs cost nothing PAL saw. */
+export function efficiency(events: LoggedEvent[]): Efficiency | null {
+  const calls = ofType(events, "model_call");
+  const [first] = [...calls].sort((a, b) => a.ts.localeCompare(b.ts));
+  if (first === undefined) return null;
+  const since = (e: LoggedEvent) => e.ts >= first.ts;
+  const prices = calls.map(apiPriceOf);
+  const spent = prices.reduce<number>((sum, p) => sum + (p ?? 0), 0);
+  const unpriced = prices.filter((p) => p === null).length;
+  const commits = ofType(events, "commit").filter(since).length;
+  const closed = ofType(events, "commitment").filter(
+    (e) => since(e) && e.outcome === "kept"
+  ).length;
+  return {
+    since: dayOf(first),
+    perCommit: perUnit(spent, unpriced, commits),
+    perClosedIsc: perUnit(spent, unpriced, closed),
+    cacheHitRate: cacheHitRate(calls),
+  };
+}

package/src/tools/lib/cost/leaderboards.ts

@@ -0,0 +1,81 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { turnCost, turnSpans, whereAndWhen } from "../wrapped/records";
+import { dayOf, ofType, tally } from "../wrapped/year";
+
+export interface Entry {
+  label: string;
+  cost: number;
+  unpriced: number;
+}
+
+export interface Leaderboards {
+  projects: Entry[];
+  sessions: Entry[];
+  days: Entry[];
+  turns: Entry[];
+}
+
+const TOP = 5;
+
+const mostExpensive = (entries: Entry[]) =>
+  entries.sort((a, b) => b.cost - a.cost || a.label.localeCompare(b.label)).slice(0, TOP);
+
+function board(calls: LoggedEvent[], labelOf: (call: LoggedEvent) => string): Entry[] {
+  const entries = new Map<string, Entry>();
+  for (const call of calls) {
+    const label = labelOf(call);
+    const entry = entries.get(label) ?? { label, cost: 0, unpriced: 0 };
+    entries.set(label, entry);
+    const price = apiPriceOf(call);
+    if (price === null) entry.unpriced++;
+    else entry.cost += price;
+  }
+  return mostExpensive([...entries.values()]);
+}
+
+const projectOf = (call: LoggedEvent) => call.project ?? "no project";
+
+function sessionLabel(session: string | null, own: LoggedEvent[]): string {
+  const [project] = tally(
+    own.filter((call) => call.project !== null),
+    projectOf
+  );
+  const [first] = own.sort((a, b) => a.ts.localeCompare(b.ts));
+  const id = session?.slice(0, 8) ?? "no session";
+  return `${id} (${project?.name ?? "no project"}, ${dayOf(first)})`;
+}
+
+/** A session is named by the project most of its calls ran in, and the day it started. */
+function sessionLabels(calls: LoggedEvent[]): Map<string | null, string> {
+  const bySession = new Map<string | null, LoggedEvent[]>();
+  for (const call of calls) {
+    const own = bySession.get(call.session) ?? [];
+    bySession.set(call.session, own);
+    own.push(call);
+  }
+  return new Map(
+    [...bySession].map(([session, own]) => [session, sessionLabel(session, own)])
+  );
+}
+
+function turnBoard(events: LoggedEvent[]): Entry[] {
+  return mostExpensive(
+    turnSpans(events).flatMap((span) => {
+      const cost = turnCost(span);
+      return cost === null ? [] : [{ label: whereAndWhen(span.turn), cost, unpriced: 0 }];
+    })
+  );
+}
+
+/** Every model call counts, PAL's own spawns included; its inference_call twins never do. */
+export function leaderboards(events: LoggedEvent[]): Leaderboards {
+  const calls = ofType(events, "model_call");
+  const sessions = sessionLabels(calls);
+  return {
+    projects: board(calls, projectOf),
+    sessions: board(calls, (call) => String(sessions.get(call.session))),
+    days: board(calls, dayOf),
+    turns: turnBoard(events),
+  };
+}

package/src/tools/lib/cost/mix.ts

@@ -0,0 +1,50 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { numberOf, ofType } from "../wrapped/year";
+
+export interface Share {
+  label: string;
+  calls: number;
+  cost: number;
+  unpriced: number;
+}
+
+function shares(
+  calls: LoggedEvent[],
+  labelOf: (call: LoggedEvent) => string,
+  priceOf: (call: LoggedEvent) => number | null
+): Share[] {
+  const byLabel = new Map<string, Share>();
+  for (const call of calls) {
+    const label = labelOf(call);
+    const share = byLabel.get(label) ?? { label, calls: 0, cost: 0, unpriced: 0 };
+    byLabel.set(label, share);
+    share.calls++;
+    const price = priceOf(call);
+    if (price === null) share.unpriced++;
+    else share.cost += price;
+  }
+  return [...byLabel.values()].sort(
+    (a, b) => b.cost - a.cost || b.calls - a.calls || a.label.localeCompare(b.label)
+  );
+}
+
+const textOr = (value: unknown, fallback: string) =>
+  typeof value === "string" ? value : fallback;
+
+export function modelMix(events: LoggedEvent[]): Share[] {
+  return shares(
+    ofType(events, "model_call"),
+    (call) => textOr(call.model, "unknown model"),
+    apiPriceOf
+  );
+}
+
+/** Already inside the model calls PAL spawned; never add it to a total. */
+export function palSpend(events: LoggedEvent[]): Share[] {
+  return shares(
+    ofType(events, "inference_call"),
+    (call) => textOr(call.caller, "unknown caller"),
+    (call) => numberOf(call.costUsd)
+  );
+}

package/src/tools/lib/cost/overhead.ts

@@ -0,0 +1,29 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { dayOf, numberOf, ofType } from "../wrapped/year";
+
+type Tier = "instructionsChars" | "semiStaticChars" | "dynamicChars";
+
+export interface Overhead {
+  since: string;
+  sessions: number;
+  perSession: Record<Tier, number>;
+}
+
+/** A compacted session is injected again; its injections add up. */
+export function contextOverhead(events: LoggedEvent[]): Overhead | null {
+  const injections = ofType(events, "context_injected");
+  const [first] = [...injections].sort((a, b) => a.ts.localeCompare(b.ts));
+  if (first === undefined) return null;
+  const sessions = new Set(injections.map((e) => e.session ?? e.id)).size;
+  const average = (tier: Tier) =>
+    injections.reduce((sum, e) => sum + (numberOf(e[tier]) ?? 0), 0) / sessions;
+  return {
+    since: dayOf(first),
+    sessions,
+    perSession: {
+      instructionsChars: average("instructionsChars"),
+      semiStaticChars: average("semiStaticChars"),
+      dynamicChars: average("dynamicChars"),
+    },
+  };
+}

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

@@ -0,0 +1,70 @@
+import { count, counted } from "../report-rows";
+import { fmtCost } from "../token-report";
+import type { Efficiency, PerUnit } from "./efficiency";
+import type { Entry, Leaderboards } from "./leaderboards";
+import type { Share } from "./mix";
+import type { Overhead } from "./overhead";
+
+function entryLine({ label, cost, unpriced }: Entry): string {
+  const extra = unpriced > 0 ? ` + ${count(unpriced)} unpriced calls` : "";
+  return `    ${fmtCost(cost).padStart(10)}  ${label}${extra}`;
+}
+
+function boardLines(title: string, entries: Entry[]): string[] {
+  const lines = entries.length === 0 ? ["    unknown"] : entries.map(entryLine);
+  return [`\n  Most expensive ${title}\n`, ...lines];
+}
+
+export function leaderboardLines(boards: Leaderboards): string[] {
+  return [
+    ...boardLines("projects", boards.projects),
+    ...boardLines("sessions", boards.sessions),
+    ...boardLines("days", boards.days),
+    ...boardLines("turns", boards.turns),
+  ];
+}
+
+function perUnitText(per: PerUnit | null, unit: string): string {
+  if (per === null) return "unknown";
+  const atLeast = per.lowerBound ? "at least " : "";
+  return `${atLeast}${fmtCost(per.cost)} over ${counted(per.units, unit)}`;
+}
+
+const percent = (rate: number | null) =>
+  rate === null ? "unknown" : `${(rate * 100).toFixed(1)}%`;
+
+export function efficiencyLines(efficiency: Efficiency | null): string[] {
+  if (efficiency === null) return [];
+  return [
+    `\n  Since ${efficiency.since}\n`,
+    `    Per commit       ${perUnitText(efficiency.perCommit, "commit")}`,
+    `    Per closed ISC   ${perUnitText(efficiency.perClosedIsc, "ISC")}`,
+    `    Cache hit rate   ${percent(efficiency.cacheHitRate)}`,
+  ];
+}
+
+function shareLine({ label, calls, cost, unpriced }: Share): string {
+  const price = unpriced === calls ? "unknown" : fmtCost(cost);
+  const extra = unpriced > 0 && unpriced < calls ? `, ${count(unpriced)} unpriced` : "";
+  return `    ${price.padStart(10)}  ${label}  ${counted(calls, "call")}${extra}`;
+}
+
+const chars = (n: number) => `${count(Math.round(n))} chars`.padStart(14);
+
+export function overheadLines(overhead: Overhead | null): string[] {
+  const title = "\n  PAL context per session\n";
+  if (overhead === null) return [title, "    unknown"];
+  const { instructionsChars, semiStaticChars, dynamicChars } = overhead.perSession;
+  return [
+    `\n  PAL context per session, over ${counted(overhead.sessions, "session")} since ${overhead.since}\n`,
+    `    Instructions ${chars(instructionsChars)}`,
+    `    Semi-static  ${chars(semiStaticChars)}`,
+    `    Dynamic      ${chars(dynamicChars)}`,
+    `    Total        ${chars(instructionsChars + semiStaticChars + dynamicChars)}`,
+  ];
+}
+
+export function shareLines(title: string, shares: Share[]): string[] {
+  const lines = shares.length === 0 ? ["    unknown"] : shares.map(shareLine);
+  return [`\n  ${title}\n`, ...lines];
+}

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

@@ -11,4 +11,7 @@ export function tallyLabel(tallies: Tally[]): string {
   return tallies.map((t) => `${t.name} ${count(t.count)}`).join(" · ");
 }
 
-export const days = (n: number) => `${count(n)} ${n === 1 ? "day" : "days"}`;
+export const counted = (n: number, noun: string) =>
+  `${count(n)} ${noun}${n === 1 ? "" : "s"}`;
+
+export const days = (n: number) => counted(n, "day");

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

@@ -65,13 +65,13 @@ function longestAgentRun(events: LoggedEvent[]): Best | null {
   );
 }
 
-interface TurnSpan {
+export interface TurnSpan {
   turn: LoggedEvent;
   inside: LoggedEvent[];
 }
 
 /** Each user turn and what happened in its session until the next one. */
-function turnSpans(events: LoggedEvent[]): TurnSpan[] {
+export 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));
@@ -86,11 +86,11 @@ function turnSpans(events: LoggedEvent[]): TurnSpan[] {
   return spans;
 }
 
-const whereAndWhen = (turn: LoggedEvent) =>
+export 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 {
+export 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);