portable-agent-layer 0.97.0 → 0.99.0

package/README.md

@@ -85,6 +85,7 @@ pal cli status        # check your setup
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `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 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.97.0",
+  "version": "0.99.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -80,7 +80,7 @@
     "@commitlint/cli": "21.0.1",
     "@commitlint/config-conventional": "21.0.1",
     "@hughescr/stryker-bun-runner": "1.3.8",
-    "@konvert7/klint": "0.34.0",
+    "@konvert7/klint": "0.35.1",
     "@opencode-ai/plugin": "latest",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.2",
     "@semantic-release/changelog": "^6.0.3",

package/src/cli/cost.ts

@@ -0,0 +1,18 @@
+import { AGENT_REGISTRY, type AgentName } 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);
+}
+
+export const costCommand = leaf({
+  summary: "What each month was paid against its API-equivalent cost, per agent",
+  run: () => printCost(),
+});

package/src/cli/events.ts

@@ -41,9 +41,31 @@ function reportCollected(): undefined {
   for (const [source, count] of sources) console.log(`${source}: ${count}`);
 }
 
+async function reportBackfilled(since: string | undefined): Promise<undefined> {
+  const { backfillEvents } = await import("../tools/lib/backfill");
+  const appended = backfillEvents(since);
+  const sources = Object.entries(appended);
+  if (sources.length === 0) {
+    console.log("The event log is off; nothing backfilled.");
+    return;
+  }
+  for (const [source, count] of sources) console.log(`${source}: ${count}`);
+}
+
 export const eventsCommand = group({
   summary: "PAL's local event log",
   commands: {
+    backfill: leaf({
+      summary: "Read everything that still exists into the event log, once",
+      options: {
+        since: {
+          type: "string",
+          value: "<date>",
+          description: "Only what happened after this date",
+        },
+      },
+      run: ({ values }) => reportBackfilled(values.since),
+    }),
     collect: leaf({
       summary: "Read every agent's own records into the event log",
       run: () => reportCollected(),

package/src/cli/tree.ts

@@ -15,6 +15,7 @@ import {
 } from "../tools/lib/command";
 import { builtinTools, builtinToolVerbs } from "./builtin-tools";
 import { contentCommand } from "./content";
+import { costCommand } from "./cost";
 import { eventsCommand } from "./events";
 import { identityCommand } from "./identity";
 import { inferCommand } from "./infer";
@@ -153,6 +154,7 @@ export function cliTree(admin: AdminHandlers): Group {
     commands: {
       ...adminCommands(admin),
       usage: usageCommand,
+      cost: costCommand,
       content: contentCommand,
       events: eventsCommand,
       infer: inferCommand,

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

@@ -1,11 +1,11 @@
 /**
- * A commitment is an ISC: completing it keeps it, retiring it drops it, and a
- * snooze puts it off. Each change of state is one event, whichever surface made it.
+ * A commitment is an ISC: adding it opens it, completing it keeps it, retiring
+ * it drops it, and a snooze puts it off. Each change of state is one event, whichever surface made it.
  */
 
 import { appendEvent, logQuietly } from "./events";
 
-export type CommitmentOutcome = "kept" | "dropped" | "snoozed" | "reopened";
+export type CommitmentOutcome = "opened" | "kept" | "dropped" | "snoozed" | "reopened";
 
 export function logCommitment(
   iscProject: string,

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

@@ -3,14 +3,27 @@
  * store. The name stays in the content store; the event carries only its kind.
  */
 
-import { appendEvent, logQuietly } from "./events";
+import { type AppendOptions, appendEvent, logQuietly } from "./events";
+
+export interface SeenEntity {
+  domain: string;
+  slug: string;
+  entityType: string;
+  name: string;
+}
+
+export const entityEventId = (entity: Pick<SeenEntity, "domain" | "slug">) =>
+  `entity:${entity.domain}:${entity.slug}`;
 
 export function logEntityFirstSeen(
-  domain: string,
-  entityType: string,
-  name: string
+  entity: SeenEntity,
+  options: AppendOptions = {}
 ): void {
   logQuietly("entity_first_seen", () =>
-    appendEvent("entity_first_seen", { domain, entityType }, { content: { name } })
+    appendEvent(
+      "entity_first_seen",
+      { domain: entity.domain, entityType: entity.entityType },
+      { id: entityEventId(entity), content: { name: entity.name }, ...options }
+    )
   );
 }

package/src/hooks/lib/events.ts

@@ -6,7 +6,7 @@
 
 import { appendFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { currentAttribution } from "./actor";
+import { currentAttribution, type RecordAttribution } from "./actor";
 import type { AgentType } from "./agent";
 import { logError } from "./log";
 import { ensureDir, paths } from "./paths";
@@ -51,7 +51,7 @@ export const EVENT_FIELDS = {
     "tz",
     "utcOffsetMin",
   ],
-  session_end: ["reason", "durationSec", "turns"],
+  session_end: ["reason", "durationSec", "turns", "messages", "status"],
   compaction: ["trigger", "withInstructions", "contextTokens"],
   hook_timing: ["hook", "totalMs", "handlers"],
   inference_call: [
@@ -70,6 +70,9 @@ export const EVENT_FIELDS = {
   entity_first_seen: ["domain", "entityType"],
   discord_nag: ["stage", "kind", "responseSec"],
   model_call: [
+    "billing",
+    "plan",
+    "extraUsage",
     "model",
     "requestedModel",
     "provider",
@@ -98,6 +101,34 @@ export const EVENT_FIELDS = {
     "host",
   ],
   conversation: ["steps", "status", "depth", "subagent", "killed"],
+  commit: [
+    "hash",
+    "committedAt",
+    "files",
+    "added",
+    "deleted",
+    "commitType",
+    "breaking",
+    "revert",
+    "merge",
+    "tags",
+    "coAuthors",
+    "aiCoAuthored",
+  ],
+  rating: ["rating", "source"],
+  project: ["change", "status"],
+  decision: ["words"],
+  promise: ["change", "dueInSec", "lateSec", "snoozes", "nags"],
+  action: [
+    "tool",
+    "outcome",
+    "fileExt",
+    "change",
+    "linesAdded",
+    "linesRemoved",
+    "beforeBytes",
+    "afterBytes",
+  ],
   permission_prompt: ["tool"],
   notification: ["kind"],
   tool_call: [
@@ -148,7 +179,9 @@ export interface AppendOptions {
   id?: string;
   ts?: string;
   session?: string | null;
-  runtime?: AgentType;
+  runtime?: AgentType | "git" | "unknown";
+  attribution?: Partial<RecordAttribution>;
+  project?: string | null;
   channel?: string | null;
   cwd?: string;
   content?: Record<string, unknown>;
@@ -209,13 +242,19 @@ function envelope(type: EventType, options: AppendOptions): EventEnvelope {
     session: options.session ?? null,
     ...currentAttribution(),
     ...(options.runtime && { runtime: options.runtime }),
+    ...options.attribution,
     channel:
       options.channel !== undefined ? options.channel : process.env.PAL_CHANNEL || null,
-    project: cwd ? projectOf(cwd) : null,
+    project: projectFor(options, cwd),
     cwd,
   };
 }
 
+function projectFor(options: AppendOptions, cwd: string): string | null {
+  if (options.project !== undefined) return options.project;
+  return cwd ? projectOf(cwd) : null;
+}
+
 /** Appends one event and returns its id, or null when the log is off or the write failed. */
 export function appendEvent(
   type: EventType,
@@ -267,6 +306,17 @@ function parseLines(file: string): LoggedEvent[] {
     });
 }
 
+/** Every id already in the log, so a source read twice appends nothing new. */
+export function loggedEventIds(): Set<string> {
+  const dir = eventsDir();
+  return new Set(
+    readdirSync(dir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .flatMap((f) => parseLines(resolve(dir, f)))
+      .map((e) => e.id)
+  );
+}
+
 export function eventsInMonth(type: EventType, month: Date): LoggedEvent[] {
   const file = resolve(eventsDir(), `${monthOf(month.toISOString())}.jsonl`);
   return parseLines(file).filter((e) => e.type === type);

package/src/hooks/lib/interaction.ts

@@ -7,7 +7,13 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { hearsPromptContext } from "./agent";
-import { appendEvent, eventsInMonth, eventsSince, logQuietly } from "./events";
+import {
+  appendEvent,
+  eventsInMonth,
+  eventsSince,
+  type LoggedEvent,
+  logQuietly,
+} from "./events";
 import { asksForLess, followedHint, ignoredHintReminder } from "./interaction-hint-check";
 import {
   type Baseline,
@@ -200,17 +206,31 @@ function legacyTurnsSince(since: Date): TurnEvent[] {
     .filter((e) => e.ts >= sinceTs);
 }
 
+export const legacyTurnId = (turn: TurnEvent) => `turn:${turn.session}:${turn.ts}`;
+
+/** Every turn logged before turns streamed into the event log. */
+export function legacyTurns(): TurnEvent[] {
+  return legacyTurnsSince(new Date(0));
+}
+
+function withStreamed(legacy: TurnEvent[], streamed: LoggedEvent[]): TurnEvent[] {
+  const backfilled = new Set(streamed.map((e) => e.id));
+  const notBackfilled = legacy.filter((turn) => !backfilled.has(legacyTurnId(turn)));
+  return [...notBackfilled, ...(streamed as unknown as TurnEvent[])];
+}
+
 export function turnsSince(since: Date): TurnEvent[] {
-  const streamed = eventsSince("turn", since) as unknown as TurnEvent[];
-  return [...legacyTurnsSince(since), ...streamed].sort((a, b) =>
+  return withStreamed(legacyTurnsSince(since), eventsSince("turn", since)).sort((a, b) =>
     a.ts.localeCompare(b.ts)
   );
 }
 
 function turnsInMonth(month: Date): TurnEvent[] {
   const file = `${month.toISOString().slice(0, 7)}.jsonl`;
-  const streamed = eventsInMonth("turn", month) as unknown as TurnEvent[];
-  return [...readLegacyTurns(resolve(legacyTurnsDir(), file)), ...streamed];
+  return withStreamed(
+    readLegacyTurns(resolve(legacyTurnsDir(), file)),
+    eventsInMonth("turn", month)
+  );
 }
 
 /** This month and last, outside the session being judged. */

package/src/hooks/lib/ledger.ts

@@ -30,10 +30,11 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, extname, resolve } from "node:path";
 import { calcPatch } from "fast-myers-diff";
 import { currentAttribution, type RecordAttribution } from "./actor";
-import { encodeAnchor } from "./anchor";
+import { encodeAnchor, resolveAnchor } from "./anchor";
+import { appendEvent } from "./events";
 import { ensureDir, paths } from "./paths";
 import { isSensitivePath } from "./sensitive-path";
 
@@ -273,9 +274,67 @@ export function recordAction(input: RecordActionInput): LedgerEntry {
   const file = ledgerPath();
   rotateIfFull(file);
   appendFileSync(file, `${JSON.stringify(entry)}\n`, "utf-8");
+  logActionEvent(entry);
   return entry;
 }
 
+export const actionEventId = (entry: LedgerEntry) => `ledger:${entry.id}`;
+
+function changeKindOf(delta: LedgerDelta | undefined): string {
+  if (!delta) return "none";
+  if (delta.redacted) return "redacted";
+  if (delta.truncated) return "truncated";
+  return "hunks";
+}
+
+function changeOf({ delta }: LedgerEntry) {
+  const change = changeKindOf(delta);
+  if (change !== "hunks" || !delta)
+    return { change, linesAdded: null, linesRemoved: null };
+  return {
+    change,
+    linesAdded: delta.hunks.reduce((n, h) => n + h.insert.length, 0),
+    linesRemoved: delta.hunks.reduce((n, h) => n + h.remove, 0),
+  };
+}
+
+function directoryOf(entry: LedgerEntry): string {
+  const resolved = resolveAnchor(entry.target);
+  if (resolved.state === "unresolvable") return "";
+  return entry.command === undefined ? dirname(resolved.path) : resolved.path;
+}
+
+/** The entry as an action event; its target, reason and command are text, so they go to content. */
+export function logActionEvent(
+  entry: LedgerEntry,
+  attribution: Partial<RecordAttribution> = {}
+): string | null {
+  return appendEvent(
+    "action",
+    {
+      tool: entry.tool,
+      outcome: entry.outcome,
+      fileExt: entry.command === undefined ? extname(entry.target) || null : null,
+      ...changeOf(entry),
+      beforeBytes: entry.before?.bytes ?? null,
+      afterBytes: entry.after?.bytes ?? null,
+    },
+    {
+      id: actionEventId(entry),
+      ts: entry.ts,
+      session: null,
+      channel: null,
+      cwd: directoryOf(entry),
+      attribution,
+      content: {
+        target: entry.target,
+        reason: entry.reason ?? null,
+        command: entry.command ?? null,
+      },
+    }
+  );
+}
+
 /** A refused command is quoted back, not stored whole. */
 const MAX_COMMAND_CHARS = 500;
 

package/src/hooks/lib/models.ts

@@ -107,7 +107,15 @@ export interface TokenUsage {
   cacheRead: number;
 }
 
-/** Pricing per million tokens (USD) — from https://platform.claude.com/docs/en/about-claude/pricing */
+interface SupersededRates {
+  until: string;
+  rates: ModelPricing;
+}
+
+/** A model's earlier rates, oldest first; a price change moves today's row here. */
+export const PRICE_HISTORY: Record<string, SupersededRates[]> = {};
+
+/** Pricing per million tokens (USD) in force today — from https://platform.claude.com/docs/en/about-claude/pricing */
 export const MODEL_PRICING: Record<string, ModelPricing> = {
   [HAIKU_MODEL]: {
     input: 1,
@@ -124,6 +132,13 @@ export const MODEL_PRICING: Record<string, ModelPricing> = {
     cacheWrite1h: 0.2,
     cacheRead: 0.01,
   },
+  "claude-fable-5-1": {
+    input: 10,
+    output: 50,
+    cacheWrite5m: 12.5,
+    cacheWrite1h: 20,
+    cacheRead: 0.25,
+  },
   [FABLE_MODEL]: {
     input: 10,
     output: 50,
@@ -131,6 +146,13 @@ export const MODEL_PRICING: Record<string, ModelPricing> = {
     cacheWrite1h: 20,
     cacheRead: 1,
   },
+  "claude-opus-5-5": {
+    input: 4,
+    output: 20,
+    cacheWrite5m: 5,
+    cacheWrite1h: 8,
+    cacheRead: 0.2,
+  },
   "claude-opus-5": {
     input: 5,
     output: 25,
@@ -166,7 +188,13 @@ export const MODEL_PRICING: Record<string, ModelPricing> = {
     cacheWrite1h: 10,
     cacheRead: 0.5,
   },
-  // Claude Sonnet 5 — introductory pricing through 2026-08-31; standard (3/15/3.75/6/0.30) applies from 2026-09-01.
+  "claude-sonnet-5-5": {
+    input: 2,
+    output: 10,
+    cacheWrite5m: 2.5,
+    cacheWrite1h: 4,
+    cacheRead: 0.1,
+  },
   "claude-sonnet-5": {
     input: 2,
     output: 10,
@@ -203,16 +231,20 @@ function longestPrefixKey(model: string): string | null {
  * (`claude-opus-5-20260115`) and context-tagged (`claude-opus-5[1m]`) — so an
  * exact miss falls back to the longest table key the ID starts with.
  */
-export function pricingFor(model: string): ModelPricing | null {
-  const exact = MODEL_PRICING[model];
-  if (exact) return exact;
-  const prefix = longestPrefixKey(model);
-  return prefix ? MODEL_PRICING[prefix] : null;
+export function pricingFor(model: string, at?: string): ModelPricing | null {
+  const key = MODEL_PRICING[model] ? model : longestPrefixKey(model);
+  return key ? ratesInForce(key, at) : null;
+}
+
+function ratesInForce(key: string, at: string | undefined): ModelPricing {
+  const when = Date.parse(at ?? "");
+  const superseded = PRICE_HISTORY[key]?.find((s) => when < Date.parse(s.until));
+  return superseded?.rates ?? MODEL_PRICING[key];
 }
 
-/** USD cost of a token usage record. Unpriced models bill as 0. */
-export function costOfUsage(model: string, usage: TokenUsage): number {
-  const p = pricingFor(model);
+/** USD cost of a token usage record at the rates in force at `at`. Unpriced models bill as 0. */
+export function costOfUsage(model: string, usage: TokenUsage, at?: string): number {
+  const p = pricingFor(model, at);
   if (!p) return 0;
   return (
     (usage.input * p.input +

package/src/hooks/lib/remote.ts

@@ -14,6 +14,9 @@
 
 import { spawnSync } from "node:child_process";
 
+/** Public PAL repository — the link surfaced in commit/PR co-author credits. */
+export const PAL_REPO_URL = "https://github.com/kovrichard/portable-agent-layer";
+
 const GIT_TIMEOUT_MS = 2000;
 
 /**

package/src/hooks/lib/signals.ts

@@ -1,6 +1,7 @@
-import { appendFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { currentAttribution } from "./actor";
+import { currentAttribution, type RecordAttribution } from "./actor";
+import { type AppendOptions, appendEvent } from "./events";
 import { paths } from "./paths";
 import { now } from "./time";
 
@@ -14,10 +15,58 @@ interface Signal {
 function emitSignal(
   filename: string,
   data: { type: string; [key: string]: unknown }
-): void {
+): Signal {
   const signal: Signal = { ts: now(), ...currentAttribution(), ...data };
   const filepath = resolve(paths.signals(), filename);
   appendFileSync(filepath, `${JSON.stringify(signal)}\n`);
+  return signal;
+}
+
+export interface RatingSignal extends Signal, Partial<RecordAttribution> {
+  rating: number;
+  context: string;
+  source: string;
+  response_preview?: string;
+}
+
+export const ratingEventId = (row: RatingSignal) =>
+  `rating:${row.machine ?? "unknown"}:${row.ts}`;
+
+/** Logs a rating row as an event, under an id the row alone determines. */
+export function logRatingEvent(
+  row: RatingSignal,
+  placement: Pick<AppendOptions, "attribution" | "cwd"> = {}
+): string | null {
+  return appendEvent(
+    "rating",
+    { rating: row.rating, source: row.source },
+    {
+      id: ratingEventId(row),
+      ts: row.ts,
+      session: null,
+      channel: null,
+      content: { context: row.context, responsePreview: row.response_preview ?? null },
+      ...placement,
+    }
+  );
+}
+
+function parseSignal(line: string): RatingSignal[] {
+  try {
+    return [JSON.parse(line) as RatingSignal];
+  } catch {
+    return [];
+  }
+}
+
+export function readRatings(): RatingSignal[] {
+  const filepath = resolve(paths.signals(), "ratings.jsonl");
+  if (!existsSync(filepath)) return [];
+  return readFileSync(filepath, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .flatMap(parseSignal)
+    .filter((row) => row.type === "rating");
 }
 
 /** Append a rating signal */
@@ -34,5 +83,6 @@ export function emitRating(
     source,
     ...(responsePreview ? { response_preview: responsePreview } : {}),
   };
-  emitSignal("ratings.jsonl", data);
+  const signal = emitSignal("ratings.jsonl", data) as RatingSignal;
+  logRatingEvent(signal);
 }

package/src/hooks/lib/work-tracking.ts

@@ -3,7 +3,13 @@
  * Used by both Claude Code (StopOrchestrator) and opencode (plugin).
  */
 
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
 import { defaultSlug, readAllProjects, resolveProjectFromCwd } from "./projects";
@@ -41,9 +47,40 @@ function readSessions(): SessionRecord[] {
   }
 }
 
+function sessionArchiveDir(): string {
+  return ensureDir(resolve(paths.state(), "sessions-archive"));
+}
+
 function sessionArchiveFile(record: SessionRecord): string {
   const month = Number.isNaN(Date.parse(record.ts)) ? "undated" : record.ts.slice(0, 7);
-  return resolve(ensureDir(resolve(paths.state(), "sessions-archive")), `${month}.jsonl`);
+  return resolve(sessionArchiveDir(), `${month}.jsonl`);
+}
+
+function parseArchiveLine(line: string): SessionRecord[] {
+  try {
+    return [JSON.parse(line) as SessionRecord];
+  } catch {
+    return [];
+  }
+}
+
+function readArchivedSessions(): SessionRecord[] {
+  const dir = sessionArchiveDir();
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".jsonl"))
+    .flatMap((f) => readFileSync(resolve(dir, f), "utf-8").split("\n"))
+    .filter(Boolean)
+    .flatMap(parseArchiveLine);
+}
+
+/** Every session still on record, archived or current, each at its latest state. */
+export function readSessionHistory(): SessionRecord[] {
+  const latest = new Map<string, SessionRecord>();
+  for (const record of [...readArchivedSessions(), ...readSessions()]) {
+    const seen = latest.get(record.sessionId);
+    if (!seen || seen.ts <= record.ts) latest.set(record.sessionId, record);
+  }
+  return [...latest.values()];
 }
 
 function archiveSessions(records: SessionRecord[]): void {

package/src/targets/lib.ts

@@ -26,6 +26,7 @@ import {
   skillsDirOf,
 } from "../hooks/lib/agent-registry";
 import { agentDirOverrides, assets, palHome, platform } from "../hooks/lib/paths";
+import { PAL_REPO_URL } from "../hooks/lib/remote";
 import { declaredTriggers } from "../hooks/lib/skill-triggers";
 import { agentFileName, renderAgentForPlatform } from "./agent-render";
 
@@ -118,9 +119,6 @@ export function writeJson(path: string, data: unknown): void {
 
 // --- Git attribution ---
 
-/** Public PAL repository — the link surfaced in commit/PR co-author credits. */
-export const PAL_REPO_URL = "https://github.com/kovrichard/portable-agent-layer";
-
 /**
  * Build the commit footer (bare URL, autolinks on GitHub) and PR body line
  * (markdown link). `sessionUrl` is off because Claude Code otherwise appends a