portable-agent-layer 0.99.2 → 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.99.2",
+  "version": "0.101.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -48,6 +48,7 @@
     "check-write": "bun .agents/scripts/check-write.ts",
     "knip": "knip-bun",
     "klint": "klint && klint --config test",
+    "klint:hook": "klint --json --hook && klint --config test --json --hook",
     "jscpd": "jscpd --noTips",
     "madge": "madge --circular --extensions ts --ts-config tsconfig.json src",
     "lf": "bun .agents/scripts/check-lf.ts",
@@ -80,7 +81,7 @@
     "@commitlint/cli": "21.0.1",
     "@commitlint/config-conventional": "21.0.1",
     "@hughescr/stryker-bun-runner": "1.3.8",
-    "@konvert7/klint": "0.35.1",
+    "@konvert7/klint": "0.35.2",
     "@opencode-ai/plugin": "latest",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.2",
     "@semantic-release/changelog": "^6.0.3",

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/handlers/agenda.ts

@@ -17,7 +17,6 @@ import { type AgendaMove, readAgenda, writeAgenda } from "../lib/agenda-store";
 import { linkInputs, readGoalLinks, writeGoalLinks } from "../lib/goal-links";
 import { canInfer, inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
-import { SONNET_MODEL } from "../lib/models";
 import { readAllProjects } from "../lib/projects";
 import { isServesKind, SERVES_KINDS, setServes } from "../lib/serves";
 import { readTelosGoals } from "../lib/telos-goals";
@@ -182,7 +181,7 @@ async function guessMissingServes(sessionId?: string): Promise<number> {
     caller: "agenda-serves",
     sessionId,
   });
-  if (result.usage) logTokenUsage("agenda-serves", result.usage, SONNET_MODEL);
+  logTokenUsage("agenda-serves", result);
   if (!result.success || !result.output) return 0;
 
   const parsed = parsePayload<{
@@ -256,7 +255,7 @@ async function refreshGoalLinks(
     caller: "agenda-goal-links",
     sessionId,
   });
-  if (result.usage) logTokenUsage("agenda-goal-links", result.usage, SONNET_MODEL);
+  logTokenUsage("agenda-goal-links", result);
   if (!result.success || !result.output) return "failed";
 
   const parsed = parsePayload<{ links: { goalId: string; projects: unknown }[] }>(
@@ -310,7 +309,7 @@ async function extractWaitingOn(sessionId?: string): Promise<number> {
       caller: "agenda-waiting-on",
       sessionId,
     });
-    if (result.usage) logTokenUsage("agenda-waiting-on", result.usage, SONNET_MODEL);
+    logTokenUsage("agenda-waiting-on", result);
     if (!result.success || !result.output) continue;
 
     const parsed = parsePayload<{ question: string }>(result.output, "agenda:waiting-on");
@@ -356,7 +355,7 @@ async function writeMoves(sessionId?: string): Promise<boolean> {
     caller: "agenda-moves",
     sessionId,
   });
-  if (result.usage) logTokenUsage("agenda-moves", result.usage, SONNET_MODEL);
+  logTokenUsage("agenda-moves", result);
   if (!result.success || !result.output) return false;
 
   const parsed = parsePayload<{ moves: (AgendaMove & { project?: unknown })[] }>(

package/src/hooks/handlers/entity-extraction.ts

@@ -56,7 +56,7 @@ export async function extractSessionEntities(
     caller: "entity-extraction",
     sessionId,
   });
-  if (result.usage) logTokenUsage("entity-extraction", result.usage);
+  logTokenUsage("entity-extraction", result);
   if (!result.success || !result.output) return;
 
   const source = sourceId(sessionId, count);

package/src/hooks/handlers/rating.ts

@@ -21,7 +21,6 @@ import { spawnDetachedInference } from "../lib/detached-inference";
 import { canInfer, inference } from "../lib/inference";
 import { replyEnd } from "../lib/interaction-samples";
 import { logDebug } from "../lib/log";
-import { HAIKU_5_5_MODEL } from "../lib/models";
 import { paths } from "../lib/paths";
 import { isSystemText, stripInjectedTags } from "../lib/prompt-text";
 import {
@@ -225,13 +224,13 @@ function handleImplicitReaction(message: string, sentAt: Date, sessionId?: strin
 
 async function labelReaction(reply: string, message: string, sessionId?: string) {
   const result = await inference(reactionRequest(reply, message, sessionId));
-  if (result.usage) logTokenUsage("rating", result.usage);
+  logTokenUsage("rating", result);
   return result.success ? parseReactionLabel(result.output) : null;
 }
 
 async function checkCorrection(reply: string, message: string, sessionId?: string) {
   const result = await inference(correctionCheckRequest(reply, message, sessionId));
-  if (result.usage) logTokenUsage("rating", result.usage);
+  logTokenUsage("rating", result);
   return result.success ? parseCorrectionCheck(result.output) : null;
 }
 
@@ -250,7 +249,7 @@ async function draftRuleCandidate(sessionId?: string): Promise<void> {
   const known = knownRules();
   if (!canRepeat(corrections) && !canWiden(corrections, known)) return;
   const result = await inference(drafterRequest(corrections, known, sessionId));
-  if (result.usage) logTokenUsage("rule-drafter", result.usage, HAIKU_5_5_MODEL);
+  logTokenUsage("rule-drafter", result);
   const candidate = result.success ? parseDraft(result.output, corrections, known) : null;
   if (candidate) recordCandidate(candidate, turns);
   else logDebug("rule-drafter", `no candidate: ${result.output ?? result.error ?? ""}`);

package/src/hooks/handlers/session-intelligence.ts

@@ -162,7 +162,7 @@ export async function captureSessionIntelligence(
       sessionId,
     });
 
-    if (result.usage) logTokenUsage("session-intelligence", result.usage);
+    logTokenUsage("session-intelligence", result);
 
     if (result.success && result.output) {
       output = JSON.parse(result.output) as IntelligenceOutput;

package/src/hooks/handlers/session-name.ts

@@ -76,7 +76,7 @@ async function upgradeWithInference(
       sessionId,
     });
 
-    if (result.usage) logTokenUsage("session-name", result.usage);
+    logTokenUsage("session-name", result);
     if (!result.success || !result.output) return;
 
     const label = labelFromModel(result.output);

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/entity-research.ts

@@ -180,7 +180,7 @@ export async function researchEntity(
     caller: "entity-research",
     web: true,
   });
-  if (result.usage) logTokenUsage("entity-research", result.usage);
+  logTokenUsage("entity-research", result);
   const profile = result.success ? parseProfile(result.output) : null;
   if (!profile) return { found: false, reason: result.error ?? "no usable reply" };
   if (profile.match !== "sure")

package/src/hooks/lib/events.ts

@@ -8,6 +8,7 @@ import { appendFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { currentAttribution, type RecordAttribution } from "./actor";
 import type { AgentType } from "./agent";
+import { USAGE_FIELDS } from "./inference-usage";
 import { logError } from "./log";
 import { ensureDir, paths } from "./paths";
 import { readAllProjects, resolveProjectFromCwd } from "./projects";
@@ -62,8 +63,7 @@ export const EVENT_FIELDS = {
     "web",
     "latencyMs",
     "failure",
-    "inputTokens",
-    "outputTokens",
+    ...USAGE_FIELDS,
   ],
   pal_update: ["outcome", "from", "to", "durationSec", "skipReason"],
   commitment: ["iscProject", "isc", "outcome", "surface", "snoozeDays"],
@@ -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/inference-events.ts

@@ -4,6 +4,7 @@
  */
 
 import { appendEvent, logQuietly } from "./events";
+import { type InferenceUsage, USAGE_FIELDS } from "./inference-usage";
 
 interface InferenceCall {
   caller?: string;
@@ -16,7 +17,11 @@ interface InferenceOutcome {
   success: boolean;
   output?: string;
   error?: string;
-  usage?: { inputTokens: number; outputTokens: number };
+  usage?: InferenceUsage;
+}
+
+function knownOrNull(usage: InferenceUsage = {}) {
+  return Object.fromEntries(USAGE_FIELDS.map((field) => [field, usage[field] ?? null]));
 }
 
 export const SCHEMA_MISMATCH = "the reply does not match the schema";
@@ -47,8 +52,7 @@ export function logInferenceCall(
         web: Boolean(call.web),
         latencyMs: Math.round(latencyMs),
         failure: failureOf(outcome, planned.route),
-        inputTokens: outcome.usage?.inputTokens ?? null,
-        outputTokens: outcome.usage?.outputTokens ?? null,
+        ...knownOrNull(outcome.usage),
       },
       { session: call.sessionId ?? null }
     )

package/src/hooks/lib/inference-usage.ts

@@ -0,0 +1,205 @@
+/**
+ * What one inference cost, in the token fields model_call uses, read from each
+ * route's own usage report. A field the route does not report stays undefined.
+ */
+
+import { cacheWritesOf, type TranscriptUsage } from "../../tools/lib/transcript-usage";
+
+export interface InferenceUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheWrite5m?: number;
+  cacheWrite1h?: number;
+  cacheRead?: number;
+  thinkingTokens?: number;
+  costUsd?: number;
+}
+
+export const USAGE_FIELDS = [
+  "inputTokens",
+  "outputTokens",
+  "cacheWrite5m",
+  "cacheWrite1h",
+  "cacheRead",
+  "thinkingTokens",
+  "costUsd",
+] as const satisfies readonly (keyof InferenceUsage)[];
+
+export function jsonLines(raw: string): Record<string, unknown>[] {
+  return raw.split("\n").flatMap((line) => {
+    try {
+      const value: unknown = JSON.parse(line);
+      return value && typeof value === "object" ? [value as Record<string, unknown>] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+const sum = (values: (number | undefined)[]) =>
+  values.some((v) => v !== undefined)
+    ? values.reduce<number>((total, v) => total + (v ?? 0), 0)
+    : undefined;
+
+export function anthropicUsage(usage: TranscriptUsage, costUsd?: number): InferenceUsage {
+  return {
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    ...cacheWritesOf(usage),
+    cacheRead: usage.cache_read_input_tokens,
+    thinkingTokens: usage.output_tokens_details?.thinking_tokens,
+    costUsd,
+  };
+}
+
+export interface OpenAiUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  prompt_tokens_details?: { cached_tokens?: number };
+  completion_tokens_details?: { reasoning_tokens?: number };
+}
+
+/** OpenAI counts cached tokens inside prompt_tokens. */
+export function openAiUsage(usage: OpenAiUsage): InferenceUsage {
+  const cacheRead = usage.prompt_tokens_details?.cached_tokens;
+  return {
+    inputTokens:
+      usage.prompt_tokens === undefined
+        ? undefined
+        : usage.prompt_tokens - (cacheRead ?? 0),
+    outputTokens: usage.completion_tokens,
+    cacheRead,
+    thinkingTokens: usage.completion_tokens_details?.reasoning_tokens,
+  };
+}
+
+export function claudeResult(raw: string): Record<string, unknown> | undefined {
+  return jsonLines(raw).find((event) => event.type === "result");
+}
+
+export function claudeSpawnUsage(raw: string): InferenceUsage | undefined {
+  const result = claudeResult(raw);
+  if (!result?.usage) return undefined;
+  return anthropicUsage(result.usage as TranscriptUsage, result.total_cost_usd as number);
+}
+
+interface CodexUsage {
+  input_tokens?: number;
+  cached_input_tokens?: number;
+  cache_write_input_tokens?: number;
+  output_tokens?: number;
+  reasoning_output_tokens?: number;
+}
+
+/** Codex counts cache reads and writes inside input_tokens. */
+export function codexSpawnUsage(raw: string): InferenceUsage | undefined {
+  const turns = jsonLines(raw)
+    .filter((event) => event.type === "turn.completed" && event.usage)
+    .map((event) => event.usage as CodexUsage);
+  if (turns.length === 0) return undefined;
+  const cacheRead = sum(turns.map((u) => u.cached_input_tokens));
+  const cacheWrite = sum(turns.map((u) => u.cache_write_input_tokens));
+  const input = sum(turns.map((u) => u.input_tokens));
+  return {
+    inputTokens:
+      input === undefined ? undefined : input - (cacheRead ?? 0) - (cacheWrite ?? 0),
+    outputTokens: sum(turns.map((u) => u.output_tokens)),
+    thinkingTokens: sum(turns.map((u) => u.reasoning_output_tokens)),
+    cacheWrite5m: cacheWrite,
+    cacheRead,
+  };
+}
+
+interface OpencodeTokens {
+  input?: number;
+  output?: number;
+  reasoning?: number;
+  cache?: { read?: number; write?: number };
+}
+
+interface OpencodeStep {
+  tokens?: OpencodeTokens | null;
+  cost?: number | null;
+}
+
+function opencodeSteps(raw: string): (OpencodeTokens & { cost?: number })[] {
+  return jsonLines(raw)
+    .filter((event) => event.type === "step_finish")
+    .flatMap((event) => {
+      const { tokens, cost } = (event.part ?? {}) as OpencodeStep;
+      return tokens ? [{ ...tokens, cost: cost ?? undefined }] : [];
+    });
+}
+
+/** opencode reports reasoning apart from output; model_call counts it in both. */
+export function opencodeSpawnUsage(raw: string): InferenceUsage | undefined {
+  const steps = opencodeSteps(raw);
+  if (steps.length === 0) return undefined;
+  const output = sum(steps.map((s) => s.output));
+  const reasoning = sum(steps.map((s) => s.reasoning));
+  return {
+    inputTokens: sum(steps.map((s) => s.input)),
+    outputTokens: sum([output, reasoning]),
+    thinkingTokens: reasoning,
+    cacheWrite5m: sum(steps.map((s) => s.cache?.write)),
+    cacheRead: sum(steps.map((s) => s.cache?.read)),
+    costUsd: sum(steps.map((s) => s.cost)),
+  };
+}
+
+interface AntigravityUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  thinking_tokens?: number;
+  cache_read_tokens?: number;
+}
+
+export function antigravitySpawnUsage(raw: string): InferenceUsage | undefined {
+  const result = jsonLines(raw).find((event) => event.event === "result")?.result as
+    | { usage?: AntigravityUsage }
+    | undefined;
+  const usage = result?.usage;
+  if (!usage) return undefined;
+  return {
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    thinkingTokens: usage.thinking_tokens,
+    cacheRead: usage.cache_read_tokens,
+  };
+}
+
+interface CopilotModelCache {
+  prompt_tokens?: number;
+  cache_read?: number;
+  cache_write?: number;
+}
+
+function copilotModelCaches(event: Record<string, unknown>): CopilotModelCache[] {
+  const data = event.data as
+    | { promptCacheBreakState?: { models?: Record<string, CopilotModelCache> }[] }
+    | undefined;
+  return (data?.promptCacheBreakState ?? []).flatMap((state) =>
+    Object.values(state.models ?? {})
+  );
+}
+
+/**
+ * Copilot's JSON output reports the prompt side of a call only, in its last
+ * usage checkpoint, and counts cache reads and writes inside prompt_tokens.
+ */
+export function copilotSpawnUsage(raw: string): InferenceUsage | undefined {
+  const checkpoint = jsonLines(raw).findLast(
+    (event) => event.type === "session.usage_checkpoint"
+  );
+  const models = checkpoint ? copilotModelCaches(checkpoint) : [];
+  if (models.length === 0) return undefined;
+  const prompt = sum(models.map((m) => m.prompt_tokens));
+  const cacheRead = sum(models.map((m) => m.cache_read));
+  const cacheWrite = sum(models.map((m) => m.cache_write));
+  return {
+    inputTokens:
+      prompt === undefined ? undefined : prompt - (cacheRead ?? 0) - (cacheWrite ?? 0),
+    cacheWrite5m: cacheWrite,
+    cacheRead,
+  };
+}