portable-agent-layer 0.103.1 → 0.104.0

package/assets/templates/PAL/MEMORY_SYSTEM.md

@@ -15,8 +15,7 @@ memory/
 │   ├── pending-failure.json            # Deferred failure capture
 │   ├── captured-learnings.json         # Session-intelligence dedup map
 │   ├── session-names.json              # Generated session titles
-│   ├── debug.log[.1-.5]                # Rotated hook execution logs
-│   └── token-usage.jsonl               # Per-call inference token usage
+│   └── debug.log[.1-.5]                # Rotated hook execution logs
 │
 ├── signals/
 │   ├── ratings.jsonl                   # Append-only rating signals (explicit + implicit)

package/package.json

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

package/src/hooks/handlers/agenda.ts

@@ -20,7 +20,6 @@ import { logDebug, logError } from "../lib/log";
 import { readAllProjects } from "../lib/projects";
 import { isServesKind, SERVES_KINDS, setServes } from "../lib/serves";
 import { readTelosGoals } from "../lib/telos-goals";
-import { logTokenUsage } from "../lib/token-usage";
 
 const FRESH_HOURS = 6;
 const MAX_PROJECTS_PER_GUESS = 40;
@@ -181,7 +180,6 @@ async function guessMissingServes(sessionId?: string): Promise<number> {
     caller: "agenda-serves",
     sessionId,
   });
-  logTokenUsage("agenda-serves", result);
   if (!result.success || !result.output) return 0;
 
   const parsed = parsePayload<{
@@ -255,7 +253,6 @@ async function refreshGoalLinks(
     caller: "agenda-goal-links",
     sessionId,
   });
-  logTokenUsage("agenda-goal-links", result);
   if (!result.success || !result.output) return "failed";
 
   const parsed = parsePayload<{ links: { goalId: string; projects: unknown }[] }>(
@@ -309,7 +306,6 @@ async function extractWaitingOn(sessionId?: string): Promise<number> {
       caller: "agenda-waiting-on",
       sessionId,
     });
-    logTokenUsage("agenda-waiting-on", result);
     if (!result.success || !result.output) continue;
 
     const parsed = parsePayload<{ question: string }>(result.output, "agenda:waiting-on");
@@ -355,7 +351,6 @@ async function writeMoves(sessionId?: string): Promise<boolean> {
     caller: "agenda-moves",
     sessionId,
   });
-  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

@@ -23,7 +23,6 @@ import { newResearchTargets, researchNewEntities } from "../lib/entity-research"
 import { canInfer, inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
 import { identity, isEnabled, isOptedIn } from "../lib/settings";
-import { logTokenUsage } from "../lib/token-usage";
 import { parseMessages } from "../lib/transcript";
 
 function sourceId(sessionId: string, count: number): string {
@@ -56,7 +55,6 @@ export async function extractSessionEntities(
     caller: "entity-extraction",
     sessionId,
   });
-  logTokenUsage("entity-extraction", result);
   if (!result.success || !result.output) return;
 
   const source = sourceId(sessionId, count);

package/src/hooks/handlers/rating.ts

@@ -43,7 +43,6 @@ import {
 } from "../lib/rule-drafter";
 import { emitRating } from "../lib/signals";
 import { now } from "../lib/time";
-import { logTokenUsage } from "../lib/token-usage";
 
 /** Read cached last assistant response (written by StopOrchestrator), looked up by session */
 function getLastResponse(sessionId?: string): string {
@@ -224,13 +223,11 @@ 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));
-  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));
-  logTokenUsage("rating", result);
   return result.success ? parseCorrectionCheck(result.output) : null;
 }
 
@@ -249,7 +246,6 @@ 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));
-  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

@@ -27,7 +27,6 @@ import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
 import { sessionDir } from "../lib/session-dir";
 import { fileTimestamp, monthPath } from "../lib/time";
-import { logTokenUsage } from "../lib/token-usage";
 import {
   extractContent,
   extractLastAssistant,
@@ -162,8 +161,6 @@ export async function captureSessionIntelligence(
       sessionId,
     });
 
-    logTokenUsage("session-intelligence", result);
-
     if (result.success && result.output) {
       output = JSON.parse(result.output) as IntelligenceOutput;
     }

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

@@ -18,7 +18,6 @@ import {
   readSessionNames,
   writeSessionName,
 } from "../lib/session-names";
-import { logTokenUsage } from "../lib/token-usage";
 
 const NAME_PROMPT =
   "You generate concise 4-word session titles for AI assistant sessions. " +
@@ -76,7 +75,6 @@ async function upgradeWithInference(
       sessionId,
     });
 
-    logTokenUsage("session-name", result);
     if (!result.success || !result.output) return;
 
     const label = labelFromModel(result.output);

package/src/hooks/handlers/update-counts.ts

@@ -9,24 +9,11 @@ import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { assets, ensureDir, paths } from "../lib/paths";
 
-interface TokenSummary {
-  input: number;
-  output: number;
-}
-
-interface TokenUsage {
-  today: TokenSummary;
-  week: TokenSummary;
-  month: TokenSummary;
-  total: TokenSummary;
-}
-
 interface Counts {
   signals: number;
   telos: number;
   skills: number;
   sessions: number;
-  tokens: TokenUsage;
   updatedAt: string;
 }
 
@@ -49,60 +36,6 @@ function countMdFiles(dir: string): number {
   }
 }
 
-function getTokenUsage(): TokenUsage {
-  const today: TokenSummary = { input: 0, output: 0 };
-  const week: TokenSummary = { input: 0, output: 0 };
-  const month: TokenSummary = { input: 0, output: 0 };
-  const total: TokenSummary = { input: 0, output: 0 };
-
-  const filepath = resolve(paths.signals(), "token-usage.jsonl");
-  if (!existsSync(filepath)) return { today, week, month, total };
-
-  try {
-    const content = readFileSync(filepath, "utf-8").trim();
-    if (!content) return { today, week, month, total };
-
-    const now = new Date();
-    const todayPrefix = now.toISOString().slice(0, 10);
-    const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
-    const monthAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
-
-    for (const line of content.split("\n")) {
-      try {
-        const entry = JSON.parse(line) as {
-          ts?: string;
-          inputTokens?: number;
-          outputTokens?: number;
-        };
-        const input = entry.inputTokens ?? 0;
-        const output = entry.outputTokens ?? 0;
-        const ts = entry.ts ?? "";
-
-        total.input += input;
-        total.output += output;
-        if (ts >= monthAgo) {
-          month.input += input;
-          month.output += output;
-        }
-        if (ts >= weekAgo) {
-          week.input += input;
-          week.output += output;
-        }
-        if (ts.startsWith(todayPrefix)) {
-          today.input += input;
-          today.output += output;
-        }
-      } catch {
-        /* skip malformed line */
-      }
-    }
-  } catch {
-    /* file read error */
-  }
-
-  return { today, week, month, total };
-}
-
 function getCounts(): Counts {
   const signalsDir = paths.signals();
   const signals = countJsonlLines(resolve(signalsDir, "ratings.jsonl"));
@@ -133,14 +66,11 @@ function getCounts(): Counts {
     /* skip */
   }
 
-  const tokens = getTokenUsage();
-
   return {
     signals,
     telos,
     skills,
     sessions,
-    tokens,
     updatedAt: new Date().toISOString(),
   };
 }

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

@@ -14,7 +14,6 @@ import {
 } from "./entity-extraction";
 import type { inference } from "./inference";
 import { logDebug, logError } from "./log";
-import { logTokenUsage } from "./token-usage";
 
 export interface ResearchTarget {
   kind: ExtractedEntity["kind"];
@@ -180,7 +179,6 @@ export async function researchEntity(
     caller: "entity-research",
     web: true,
   });
-  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/inference-usage.ts

@@ -193,13 +193,63 @@ export function copilotSpawnUsage(raw: string): InferenceUsage | undefined {
   );
   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),
+    inputTokens: uncachedInput(
+      sum(models.map((m) => m.prompt_tokens)),
+      cacheRead,
+      cacheWrite
+    ),
+    cacheWrite5m: cacheWrite,
+    cacheRead,
+  };
+}
+
+function uncachedInput(
+  prompt: number | undefined,
+  cacheRead: number | undefined,
+  cacheWrite: number | undefined
+): number | undefined {
+  return prompt === undefined ? undefined : prompt - (cacheRead ?? 0) - (cacheWrite ?? 0);
+}
+
+const COPILOT_SESSION_ID = /^[\w-]+$/;
+
+export function copilotSessionId(raw: string): string | undefined {
+  const id = jsonLines(raw).findLast((event) => event.type === "result")?.sessionId;
+  return typeof id === "string" && COPILOT_SESSION_ID.test(id) ? id : undefined;
+}
+
+interface CopilotRunUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+}
+
+/** A run's session.shutdown carries all of its usage, output included; inputTokens folds in cache reads and writes. */
+export function copilotShutdownUsage(eventsJsonl: string): InferenceUsage | undefined {
+  const shutdown = jsonLines(eventsJsonl).findLast(
+    (event) => event.type === "session.shutdown"
+  );
+  const data = shutdown?.data as
+    | { modelMetrics?: Record<string, { usage?: CopilotRunUsage }> }
+    | undefined;
+  const runs = Object.values(data?.modelMetrics ?? {}).map((model) => model.usage ?? {});
+  if (runs.length === 0) return undefined;
+  const cacheRead = sum(runs.map((u) => u.cacheReadTokens));
+  const cacheWrite = sum(runs.map((u) => u.cacheWriteTokens));
+  return {
+    inputTokens: uncachedInput(
+      sum(runs.map((u) => u.inputTokens)),
+      cacheRead,
+      cacheWrite
+    ),
+    outputTokens: sum(runs.map((u) => u.outputTokens)),
     cacheWrite5m: cacheWrite,
     cacheRead,
+    thinkingTokens: sum(runs.map((u) => u.reasoningTokens)),
   };
 }

package/src/hooks/lib/inference.ts

@@ -20,6 +20,7 @@
  * yet wired and currently fall through to the API path.
  */
 
+import { readFileSync } from "node:fs";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
@@ -48,6 +49,8 @@ import {
   claudeResult,
   claudeSpawnUsage,
   codexSpawnUsage,
+  copilotSessionId,
+  copilotShutdownUsage,
   copilotSpawnUsage,
   type InferenceUsage,
   jsonLines,
@@ -64,6 +67,7 @@ import {
 } from "./models";
 import { opencodeTierModel, writeInstructionFreeConfig } from "./opencode-config";
 import { withPalEnv } from "./pal-env";
+import { platform } from "./paths";
 import { buildSpawnGuardEnv, getInferenceDepth, SPAWN_GUARD_ENV } from "./spawn-guard";
 import { findBinaryOnPath } from "./which";
 
@@ -703,6 +707,26 @@ const COPILOT_REPLY: CliReply = {
   usage: copilotSpawnUsage,
 };
 
+function copilotSessionUsage(home: string, raw: string): InferenceUsage | undefined {
+  const id = copilotSessionId(raw);
+  if (!id) return undefined;
+  try {
+    return copilotShutdownUsage(
+      readFileSync(join(home, "session-state", id, "events.jsonl"), "utf-8")
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+/** stdout reports only the prompt side; the run's own session file in its home has the rest. */
+function copilotReply(home: string): CliReply {
+  return {
+    ...COPILOT_REPLY,
+    usage: (raw) => copilotSessionUsage(home, raw) ?? copilotSpawnUsage(raw),
+  };
+}
+
 const COPILOT_TOKEN_ENV = ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"];
 
 /** A /login account lives in COPILOT_HOME's config.json; only a token variable logs in without it. */
@@ -715,19 +739,21 @@ async function inferenceViaCopilotSpawn(
   bin: string,
   opts: InferenceOptions
 ): Promise<InferenceResult> {
-  const spawn = (place?: SpawnPlace) =>
+  const spawn = (home: string, place?: SpawnPlace) =>
     inferenceViaCliSpawn(
       bin,
       buildCopilotArgs(opts),
       buildCliPrompt(opts),
       opts,
-      COPILOT_REPLY,
+      copilotReply(home),
       place
     );
-  if (!copilotLogsInWithoutHome(withPalEnv(process.env))) return spawn();
+  const env = withPalEnv(process.env);
+  if (!copilotLogsInWithoutHome(env))
+    return spawn(env.COPILOT_HOME || platform.copilotDir());
   const dir = await mkdtemp(join(tmpdir(), "pal-copilot-"));
   try {
-    return await spawn({ cwd: dir, env: { COPILOT_HOME: dir } });
+    return await spawn(dir, { cwd: dir, env: { COPILOT_HOME: dir } });
   } finally {
     await rm(dir, { recursive: true, force: true });
   }

package/src/hooks/lib/security.ts

@@ -122,7 +122,6 @@ const HOOK_MANAGED_FILES = [
   "last-responses.json",
   "signal-cache.json",
   "pending-failure.json",
-  "token-usage.jsonl",
   "graduated.json",
   "update-available.json",
   "opinions.json",

package/src/tools/lib/agent-usage.ts

@@ -218,13 +218,14 @@ interface CopilotEvent {
   };
 }
 
-/** Copilot counts cache reads inside inputTokens. */
+/** Copilot counts cache reads and writes inside inputTokens. */
 function copilotTokens(usage: CopilotModelMetrics["usage"] = {}): Tokens {
   const cacheRead = usage.cacheReadTokens ?? 0;
+  const cacheWrite = usage.cacheWriteTokens ?? 0;
   return {
-    input: (usage.inputTokens ?? 0) - cacheRead,
+    input: (usage.inputTokens ?? 0) - cacheRead - cacheWrite,
     output: usage.outputTokens ?? 0,
-    cacheWrite5m: usage.cacheWriteTokens ?? 0,
+    cacheWrite5m: cacheWrite,
     cacheWrite1h: 0,
     cacheRead,
   };

package/src/tools/lib/usage-buckets.ts

@@ -6,6 +6,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import type { LoggedEvent } from "../../hooks/lib/events";
 import { costOfUsage } from "../../hooks/lib/models";
 import { cacheWritesOf, finalPerMessage, type TranscriptUsage } from "./transcript-usage";
 
@@ -307,27 +308,27 @@ export interface PalInferenceUsage {
   byCaller: Record<string, Bucket>;
 }
 
-interface InferenceLine {
-  ts: string;
-  caller: string;
-  model: string;
-  inputTokens: number;
-  outputTokens: number;
-}
+const countOf = (value: unknown) => (typeof value === "number" ? value : null);
 
-/** PAL's own calls are plain prompts: no cache to write and none to read. */
-function inferenceTokens(entry: InferenceLine): Tokens {
+/** A call whose input or output went unreported has no tokens to count. */
+function inferenceTokens(call: LoggedEvent): Tokens | null {
+  const input = countOf(call.inputTokens);
+  const output = countOf(call.outputTokens);
+  if (input === null || output === null) return null;
   return {
-    input: entry.inputTokens,
-    output: entry.outputTokens,
-    cacheWrite5m: 0,
-    cacheWrite1h: 0,
-    cacheRead: 0,
+    input,
+    output,
+    cacheWrite5m: countOf(call.cacheWrite5m) ?? 0,
+    cacheWrite1h: countOf(call.cacheWrite1h) ?? 0,
+    cacheRead: countOf(call.cacheRead) ?? 0,
   };
 }
 
+const textOr = (value: unknown, fallback: string) =>
+  typeof value === "string" ? value : fallback;
+
 export function readPalInference(
-  filepath: string,
+  events: LoggedEvent[],
   now: Date = new Date()
 ): PalInferenceUsage {
   const horizons = horizonsFrom(now);
@@ -336,33 +337,20 @@ export function readPalInference(
     byModel: {},
     byCaller: {},
   };
-  if (!existsSync(filepath)) return result;
-
-  const content = readFileSync(filepath, "utf-8").trim();
-  if (!content) return result;
 
-  for (const line of content.split("\n")) {
-    let entry: InferenceLine;
-    try {
-      entry = JSON.parse(line) as InferenceLine;
-    } catch {
-      continue;
-    }
-    const tokens = inferenceTokens(entry);
+  for (const call of events.filter((e) => e.type === "inference_call")) {
+    const tokens = inferenceTokens(call);
+    if (tokens === null) continue;
+    const model = textOr(call.model, "unknown");
+    const caller = textOr(call.caller, "anonymous");
 
-    addToTimeBuckets(result.buckets, entry.ts, entry.model, tokens, horizons);
+    addToTimeBuckets(result.buckets, call.ts, model, tokens, horizons);
 
-    result.byModel[entry.model] ??= emptyTimeBuckets();
-    addToTimeBuckets(
-      result.byModel[entry.model],
-      entry.ts,
-      entry.model,
-      tokens,
-      horizons
-    );
+    result.byModel[model] ??= emptyTimeBuckets();
+    addToTimeBuckets(result.byModel[model], call.ts, model, tokens, horizons);
 
-    result.byCaller[entry.caller] ??= emptyBucket();
-    addToBucket(result.byCaller[entry.caller], entry.model, tokens, entry.ts);
+    result.byCaller[caller] ??= emptyBucket();
+    addToBucket(result.byCaller[caller], model, tokens, call.ts);
   }
 
   return result;

package/src/tools/self-model.ts

@@ -21,7 +21,6 @@ import { parseArgs } from "node:util";
 import { inference } from "../hooks/lib/inference";
 import { ensureDir, paths } from "../hooks/lib/paths";
 import { identity as loadSettingsIdentity } from "../hooks/lib/settings";
-import { logTokenUsage } from "../hooks/lib/token-usage";
 import {
   archiveDateOf,
   buildPrompt,
@@ -89,7 +88,6 @@ async function composeSelfModel(days: number): Promise<string> {
     caller: "self-model",
   });
 
-  logTokenUsage("self-model", result);
   if (result.success && result.output) {
     return result.output.trimEnd() + metaFooter(data);
   }

package/src/tools/token-cost.ts

@@ -6,7 +6,8 @@
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { AGENT_REGISTRY, type AgentName } from "../hooks/lib/agent-registry";
-import { palHome, platform } from "../hooks/lib/paths";
+import { eventsSince } from "../hooks/lib/events";
+import { platform } from "../hooks/lib/paths";
 import { findBinaryOnPath } from "../hooks/lib/which";
 import {
   opencodeDatabase,
@@ -60,7 +61,7 @@ function rtkGain(): RtkGain {
 export function collectUsage(project: string | undefined): UsageData {
   return {
     agents: agentReports(project),
-    pal: readPalInference(resolve(palHome(), "memory", "signals", "token-usage.jsonl")),
+    pal: readPalInference(eventsSince("inference_call", new Date(0))),
     rtk: rtkGain(),
     untracked: installedUntracked(),
   };

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

@@ -1,53 +0,0 @@
-/**
- * Append-only JSONL logger for inference token usage.
- * Writes to memory/signals/token-usage.jsonl
- */
-
-import { appendFileSync } from "node:fs";
-import { resolve } from "node:path";
-import type { InferenceUsage } from "./inference-usage";
-import { ensureDir, paths } from "./paths";
-
-type TokenCaller =
-  | "rating"
-  | "rule-drafter"
-  | "failure"
-  | "session-name"
-  | "session-intelligence"
-  | "entity-extraction"
-  | "entity-research"
-  | "relationship"
-  | "self-model"
-  | "agenda-serves"
-  | "agenda-goal-links"
-  | "agenda-waiting-on"
-  | "agenda-moves";
-
-const UNKNOWN_MODEL = "unknown";
-
-interface TokenUsageEntry {
-  ts: string;
-  caller: TokenCaller;
-  model: string;
-  inputTokens: number;
-  outputTokens: number;
-}
-
-export function logTokenUsage(
-  caller: TokenCaller,
-  call: { usage?: InferenceUsage; model?: string }
-): void {
-  const { inputTokens, outputTokens } = call.usage ?? {};
-  if (inputTokens === undefined || outputTokens === undefined) return;
-  const entry: TokenUsageEntry = {
-    ts: new Date().toISOString(),
-    caller,
-    model: call.model ?? UNKNOWN_MODEL,
-    inputTokens,
-    outputTokens,
-  };
-
-  const dir = ensureDir(paths.signals());
-  const filepath = resolve(dir, "token-usage.jsonl");
-  appendFileSync(filepath, `${JSON.stringify(entry)}\n`, "utf-8");
-}