portable-agent-layer 0.94.0 → 0.95.0

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

@@ -0,0 +1,211 @@
+/**
+ * Session boundaries as events: when a session opened and why, when and why it
+ * closed, and when its context was compacted.
+ */
+
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readFileSync,
+  readSync,
+  statSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+import { appendEvent, eventsSince, type LoggedEvent, logQuietly } from "./events";
+import { type HookTurnPayload, hookSessionId } from "./hook-turn";
+import { palPkg } from "./paths";
+
+const SESSION_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+const MAX_FIELD = 64;
+
+interface SessionStartPayload extends HookTurnPayload {
+  source?: string;
+  model?: unknown;
+}
+
+interface SessionEndPayload extends HookTurnPayload {
+  reason?: string;
+}
+
+interface CompactionPayload extends HookTurnPayload {
+  trigger?: string;
+  custom_instructions?: string;
+  customInstructions?: string;
+  transcript_path?: string;
+  transcriptPath?: string;
+  context_tokens?: number;
+}
+
+function palVersion(): string | null {
+  try {
+    return JSON.parse(readFileSync(resolve(palPkg(), "package.json"), "utf-8")).version;
+  } catch {
+    return null;
+  }
+}
+
+function timezone(now: Date) {
+  return {
+    tz: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    utcOffsetMin: 0 - now.getTimezoneOffset(),
+  };
+}
+
+function modelOf(model: unknown): string | null {
+  if (typeof model === "string") return model;
+  const id = (model as { id?: unknown } | null)?.id;
+  return typeof id === "string" ? id : null;
+}
+
+function gitDirOf(start: string): string | null {
+  let dir = resolve(start);
+  while (true) {
+    const dotGit = resolve(dir, ".git");
+    if (existsSync(dotGit)) {
+      if (statSync(dotGit).isDirectory()) return dotGit;
+      const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf-8"))?.[1];
+      return pointer ? resolve(dir, pointer.trim()) : null;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function gitBranchOf(cwd: string): string | null {
+  try {
+    const gitDir = gitDirOf(cwd);
+    if (!gitDir) return null;
+    const head = readFileSync(resolve(gitDir, "HEAD"), "utf-8").trim();
+    const branch = /^ref: refs\/heads\/(.+)$/.exec(head)?.[1] ?? "detached";
+    return branch.slice(0, MAX_FIELD);
+  } catch {
+    return null;
+  }
+}
+
+function runtimeSettings() {
+  return {
+    effort: process.env.CLAUDE_EFFORT || null,
+    entrypoint: process.env.CLAUDE_CODE_ENTRYPOINT || null,
+  };
+}
+
+export function logSessionStart(
+  payload: SessionStartPayload | null,
+  now: Date = new Date()
+): void {
+  logQuietly("session_start", () =>
+    appendEvent(
+      "session_start",
+      {
+        source: payload?.source ?? null,
+        model: modelOf(payload?.model),
+        ...runtimeSettings(),
+        branch: gitBranchOf(process.cwd()),
+        palVersion: palVersion(),
+        ...timezone(now),
+      },
+      { ts: now.toISOString(), session: hookSessionId(payload) ?? null }
+    )
+  );
+}
+
+function sessionEvents(session: string, now: Date) {
+  const since = new Date(now.getTime() - SESSION_LOOKBACK_MS);
+  const ofSession = (e: LoggedEvent) => e.session === session;
+  return {
+    start: eventsSince("session_start", since).find(ofSession),
+    turns: eventsSince("turn", since).filter(ofSession).length,
+  };
+}
+
+function sessionSummary(session: string | null, now: Date) {
+  if (!session) return { durationSec: null, turns: null };
+  const { start, turns } = sessionEvents(session, now);
+  const durationSec = start
+    ? Math.round((now.getTime() - Date.parse(start.ts)) / 1000)
+    : null;
+  return { durationSec, turns };
+}
+
+export function logSessionEnd(
+  payload: SessionEndPayload | null,
+  now: Date = new Date()
+): void {
+  const session = hookSessionId(payload) ?? null;
+  logQuietly("session_end", () =>
+    appendEvent(
+      "session_end",
+      { reason: payload?.reason ?? null, ...sessionSummary(session, now) },
+      { ts: now.toISOString(), session }
+    )
+  );
+}
+
+function transcriptTail(path: string): string {
+  const size = statSync(path).size;
+  const length = Math.min(size, TRANSCRIPT_TAIL_BYTES);
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(path, "r");
+  try {
+    readSync(fd, buffer, 0, length, size - length);
+  } finally {
+    closeSync(fd);
+  }
+  return buffer.toString("utf-8");
+}
+
+interface ContextUsage {
+  input_tokens?: number;
+  cache_read_input_tokens?: number;
+  cache_creation_input_tokens?: number;
+}
+
+function usageOfLine(line: string): ContextUsage | null {
+  try {
+    return JSON.parse(line)?.message?.usage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function contextTokensOf(transcriptPath: string | undefined): number | null {
+  if (!transcriptPath || !existsSync(transcriptPath)) return null;
+  const lines = transcriptTail(transcriptPath).split("\n").reverse();
+  const usage = lines.map(usageOfLine).find((u) => u !== null);
+  if (!usage) return null;
+  return (
+    (usage.input_tokens ?? 0) +
+    (usage.cache_read_input_tokens ?? 0) +
+    (usage.cache_creation_input_tokens ?? 0)
+  );
+}
+
+function instructionsOf(payload: CompactionPayload | null): string | undefined {
+  return payload?.custom_instructions ?? payload?.customInstructions;
+}
+
+function compactedTokensOf(payload: CompactionPayload | null): number | null {
+  if (typeof payload?.context_tokens === "number") return payload.context_tokens;
+  return contextTokensOf(payload?.transcript_path ?? payload?.transcriptPath);
+}
+
+export function logCompaction(
+  payload: CompactionPayload | null,
+  now: Date = new Date()
+): void {
+  logQuietly("compaction", () =>
+    appendEvent(
+      "compaction",
+      {
+        trigger: payload?.trigger ?? null,
+        withInstructions: Boolean(instructionsOf(payload)?.trim()),
+        contextTokens: compactedTokensOf(payload),
+      },
+      { ts: now.toISOString(), session: hookSessionId(payload) ?? null }
+    )
+  );
+}

package/src/hooks/lib/settings.ts

@@ -32,6 +32,8 @@ export interface PalSettingsData {
    * paths whose contents are never stored; it cannot shrink it.
    */
   ledger?: { redactPaths?: string[] };
+  /** Local event log (memory/events) and content store (memory/content). On unless disabled. */
+  eventLog?: { enabled?: boolean };
   /** Control-room ranking knobs and attention sources — see src/tools/control-room/prefs.ts. */
   controlRoom?: Record<string, unknown>;
   /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
@@ -120,6 +122,10 @@ export function isOptedIn(key: string): boolean {
   return load().dynamicContext?.[key] === true;
 }
 
+export function eventLogEnabled(): boolean {
+  return load().eventLog?.enabled !== false;
+}
+
 /** Get the loadAtStartup file list */
 export function startupFiles(): string[] {
   return load().loadAtStartup?.files ?? [];

package/src/hooks/lib/stop.ts

@@ -21,6 +21,7 @@ import { updateCounts } from "../handlers/update-counts";
 import { captureWorkSession } from "../handlers/work-session";
 import { acknowledgeMentioned } from "./daily-nudge";
 import { spawnDetachedInference } from "./detached-inference";
+import { startHookTiming } from "./hook-timing";
 import {
   fileFinalReply,
   type HookTurnPayload,
@@ -150,6 +151,7 @@ export async function runStopHandlers(
   fileTranscript: string,
   options: RunStopHandlersOptions = {}
 ): Promise<void> {
+  const timing = startHookTiming("stop");
   const fileMessages = parseMessages(fileTranscript);
   if (fileMessages.length < 2) return;
   const messages = withFinalReply(fileMessages, options.lastAssistantMessage);
@@ -167,10 +169,12 @@ export async function runStopHandlers(
   // Detach inference-bearing handlers — claude --print cold-start can exceed
   // any in-hook budget. These spawn detached bun subprocesses that run the
   // inference and write results to disk; they don't block this hook.
-  await detachSessionIntelligence(transcript, options.sessionId);
-  await detachEntityExtraction(transcript, options.sessionId);
-  await detachFailurePrinciple(transcript);
-  detachAgenda(options.sessionId);
+  await timing.time("detach-inference", async () => {
+    await detachSessionIntelligence(transcript, options.sessionId);
+    await detachEntityExtraction(transcript, options.sessionId);
+    await detachFailurePrinciple(transcript);
+    detachAgenda(options.sessionId);
+  });
   // Failure auto-graduation is intentionally NOT wired here: every pattern it
   // ever promoted was a frustration log, not a principle. Wisdom frames are
   // populated by Claude in-conversation (see wisdom.ts header). The handler
@@ -178,37 +182,29 @@ export async function runStopHandlers(
 
   // Run remaining (non-inference) handlers concurrently.
   // project-touch only fires when cwd resolves to an active registered project.
-  const results = await Promise.allSettled([
-    captureWorkSession(transcript, options.sessionId),
-    resetTab(),
-    updateCounts(),
-    autoBackup(),
-    checkReflectTrigger(),
-    checkSelfModelTrigger(),
-    runSynthesis(),
-    projectTouch(options.lastAssistantMessage),
-    notifyDesktop(options.sessionId),
-    Promise.resolve(writeContextDigests()),
-  ]);
-
-  const handlerNames = [
-    "work-session",
-    "tab",
-    "update-counts",
-    "backup",
-    "reflect-trigger",
-    "self-model-trigger",
-    "synthesis",
-    "project-touch",
-    "desktop-notify",
-    "context-digests",
-  ];
+  const handlers: Record<string, unknown> = {
+    "work-session": captureWorkSession(transcript, options.sessionId),
+    tab: resetTab(),
+    "update-counts": updateCounts(),
+    backup: autoBackup(),
+    "reflect-trigger": checkReflectTrigger(),
+    "self-model-trigger": checkSelfModelTrigger(),
+    synthesis: runSynthesis(),
+    "project-touch": projectTouch(options.lastAssistantMessage),
+    "desktop-notify": notifyDesktop(options.sessionId),
+    "context-digests": Promise.resolve(writeContextDigests()),
+  };
+  const names = Object.keys(handlers);
+  const results = await Promise.allSettled(
+    names.map((name) => timing.time(name, Promise.resolve(handlers[name])))
+  );
   for (let i = 0; i < results.length; i++) {
     const r = results[i];
-    if (r.status === "rejected") {
-      logError(`runStopHandlers:${handlerNames[i]}`, r.reason);
+    if (r?.status === "rejected") {
+      logError(`runStopHandlers:${names[i]}`, r.reason);
     }
   }
+  timing.log(options.sessionId);
 }
 
 /**

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

@@ -0,0 +1,106 @@
+/**
+ * One event per tool call, on every agent: which tool, how it ended, and the
+ * cheap facts about it. The call's arguments go to the content store.
+ */
+
+import { basename, extname } from "node:path";
+import { FILE_TARGET_KEYS, normalizeToolUse, type ToolUseRequest } from "./agent";
+import { appendEvent, logQuietly } from "./events";
+import { hookSessionId } from "./hook-turn";
+import { unappliedVerdictOf } from "./ledger-hook";
+import { isPalSpawnedInference } from "./spawn-guard";
+import { permissionWaitSec } from "./waiting-on-user";
+
+const RESULT_KEYS = ["tool_response", "toolResult", "tool_output", "result"];
+const DURATION_KEYS = ["duration_ms", "durationMs"];
+const COMMAND_KEYS = ["command", "commandLine", "CommandLine", "script"];
+
+function stringIn(input: Record<string, unknown>, keys: string[]): string | null {
+  const found = keys.map((k) => input[k]).find((v) => typeof v === "string" && v);
+  return (found as string | undefined) ?? null;
+}
+
+function numberIn(source: unknown, keys: string[]): number | null {
+  if (typeof source !== "object" || source === null) return null;
+  const record = source as Record<string, unknown>;
+  const found = keys.map((k) => record[k]).find((v) => typeof v === "number");
+  return (found as number | undefined) ?? null;
+}
+
+function resultOf(payload: Record<string, unknown>): unknown {
+  return RESULT_KEYS.map((k) => payload[k]).find((v) => v !== undefined);
+}
+
+function sizeOf(value: unknown): number {
+  if (value === undefined || value === null) return 0;
+  return typeof value === "string" ? value.length : JSON.stringify(value).length;
+}
+
+function hostOf(url: string | null): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+function mcpServerOf(tool: string): string | null {
+  return tool.startsWith("mcp__") ? (tool.split("__")[1] ?? null) : null;
+}
+
+function programOf(command: string | null): string | null {
+  const first = command?.trim().split(/\s+/)[0];
+  return first ? basename(first) : null;
+}
+
+function outcomeOf(payload: Record<string, unknown>): string {
+  const verdict = unappliedVerdictOf(payload);
+  if (verdict) return verdict.outcome;
+  return typeof payload.error === "string" && payload.error ? "failed" : "ok";
+}
+
+function subagentRun(result: unknown) {
+  return {
+    subagentTokens: numberIn(result, ["totalTokens"]),
+    subagentTools: numberIn(result, ["totalToolUseCount"]),
+  };
+}
+
+function toolCallFields(payload: Record<string, unknown>, call: ToolUseRequest) {
+  const input = call.toolInput;
+  const result = resultOf(payload);
+  const file = stringIn(input, FILE_TARGET_KEYS);
+  return {
+    tool: call.toolName,
+    outcome: outcomeOf(payload),
+    durationMs: numberIn(payload, DURATION_KEYS) ?? numberIn(result, ["totalDurationMs"]),
+    inputChars: sizeOf(input),
+    outputChars: sizeOf(result),
+    fileExt: file ? extname(file) || null : null,
+    program: programOf(stringIn(input, COMMAND_KEYS)),
+    skill: stringIn(input, ["skill"]),
+    subagent: stringIn(input, ["subagent_type"]),
+    ...subagentRun(result),
+    mcpServer: mcpServerOf(call.toolName),
+    host: hostOf(stringIn(input, ["url"])),
+  };
+}
+
+/** Logs the call a post-tool, failure or denial payload describes; ignores anything else. */
+export function logToolCall(payload: Record<string, unknown> | null): void {
+  if (isPalSpawnedInference()) return;
+  logQuietly("tool_call", () => {
+    const call = normalizeToolUse(payload);
+    if (!payload || !call) return;
+    const session = hookSessionId(payload) ?? null;
+    const fields = {
+      ...toolCallFields(payload, call),
+      promptWaitSec: permissionWaitSec(session, call.toolName),
+    };
+    appendEvent("tool_call", fields, {
+      session,
+      content: { tool: call.toolName, input: call.toolInput },
+    });
+  });
+}

package/src/hooks/lib/transcript-preserve.ts

@@ -0,0 +1,133 @@
+/**
+ * PAL's own gzipped copy of every Claude Code transcript, taken before Claude
+ * Code's cleanupPeriodDays (30 days by default) deletes the originals.
+ */
+
+import { spawn } from "node:child_process";
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { logDebug, logError } from "./log";
+import { assets, ensureDir, paths, platform } from "./paths";
+
+const STALE_LOCK_MS = 30 * 60 * 1000;
+
+export interface PreserveResult {
+  copied: number;
+  unchanged: number;
+  failed: number;
+}
+
+interface PreserveLocations {
+  source: string;
+  target: string;
+  manifest: string;
+}
+
+type Manifest = Record<string, string>;
+
+function defaultLocations(): PreserveLocations {
+  return {
+    source: resolve(platform.claudeDir(), "projects"),
+    target: resolve(paths.content(), "claude"),
+    manifest: resolve(paths.state(), "transcript-copies.json"),
+  };
+}
+
+function readManifest(path: string): Manifest {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as Manifest;
+  } catch {
+    return {};
+  }
+}
+
+function filesUnder(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => resolve(entry.parentPath, entry.name));
+}
+
+function versionOf(file: string): string {
+  const stat = statSync(file);
+  return `${stat.size}:${Math.trunc(stat.mtimeMs)}`;
+}
+
+function gzipCopy(file: string, destination: string): void {
+  ensureDir(dirname(destination));
+  writeFileSync(destination, Bun.gzipSync(readFileSync(file)));
+}
+
+export function preserveTranscripts(at: PreserveLocations): PreserveResult {
+  const manifest = readManifest(at.manifest);
+  const result: PreserveResult = { copied: 0, unchanged: 0, failed: 0 };
+  for (const file of filesUnder(at.source)) {
+    const key = relative(at.source, file).replaceAll("\\", "/");
+    try {
+      const version = versionOf(file);
+      if (manifest[key] === version) {
+        result.unchanged++;
+        continue;
+      }
+      gzipCopy(file, resolve(at.target, `${key}.gz`));
+      manifest[key] = version;
+      result.copied++;
+    } catch (err) {
+      result.failed++;
+      logError("transcript-preserve", err);
+    }
+  }
+  ensureDir(dirname(at.manifest));
+  writeFileSync(at.manifest, JSON.stringify(manifest), "utf-8");
+  return result;
+}
+
+function lockPath(): string {
+  return resolve(paths.state(), "transcript-preserve.lock");
+}
+
+function takeLock(path: string, now = Date.now()): boolean {
+  if (existsSync(path) && now - statSync(path).mtimeMs < STALE_LOCK_MS) return false;
+  rmSync(path, { force: true });
+  try {
+    closeSync(openSync(path, "wx"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function preserveTranscriptsOnce(
+  at: PreserveLocations = defaultLocations()
+): PreserveResult | null {
+  const lock = lockPath();
+  if (!takeLock(lock)) return null;
+  try {
+    return preserveTranscripts(at);
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}
+
+export function spawnTranscriptPreserve(): void {
+  try {
+    const child = spawn("bun", [resolve(assets.hooks(), "PreserveTranscripts.ts")], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+    logDebug("transcript-preserve", "detached copy spawned");
+  } catch (err) {
+    logError("transcript-preserve:spawn", err);
+  }
+}

package/src/hooks/lib/turn-extras.ts

@@ -0,0 +1,78 @@
+/**
+ * Cheap facts about a prompt and a reply, measured in code: no inference, no text kept.
+ */
+
+const STOPWORDS: Record<string, readonly string[]> = {
+  en: [
+    "the",
+    "and",
+    "is",
+    "to",
+    "of",
+    "it",
+    "that",
+    "this",
+    "with",
+    "for",
+    "you",
+    "what",
+  ],
+  hu: ["és", "hogy", "nem", "egy", "az", "de", "meg", "van", "is", "mit", "ez", "csak"],
+};
+
+const MIN_STOPWORD_HITS = 2;
+const PASTED_RE = /<pasted_content\b[^>]*>([\s\S]*?)<\/pasted_content[^>]*>/gi;
+const IMAGE_RE = /\[Image #\d+\]/g;
+const COMMAND_TAG_RE = /<command-name>\s*\/?([\w:-]+)\s*<\/command-name>/;
+const SLASH_RE = /^\/([\w:-]+)(?:\s|$)/;
+const MODE_RE = /═+\s*PAL(?:\s*\|\s*([A-Z]+))?\s*═+/;
+
+function tokens(text: string): string[] {
+  return text.toLowerCase().match(/[\p{L}']+/gu) ?? [];
+}
+
+export function languageOf(text: string): string | null {
+  const words = new Set(tokens(text));
+  let best: string | null = null;
+  let bestHits = MIN_STOPWORD_HITS - 1;
+  for (const [language, stopwords] of Object.entries(STOPWORDS)) {
+    const hits = stopwords.filter((w) => words.has(w)).length;
+    if (hits > bestHits) {
+      best = language;
+      bestHits = hits;
+    }
+  }
+  return best;
+}
+
+export function pastedChars(prompt: string): number {
+  return Array.from(prompt.matchAll(PASTED_RE), (m) => m[1]?.length ?? 0).reduce(
+    (a, b) => a + b,
+    0
+  );
+}
+
+export function imageCount(prompt: string): number {
+  return prompt.match(IMAGE_RE)?.length ?? 0;
+}
+
+export function slashCommandOf(prompt: string): string | null {
+  const tagged = COMMAND_TAG_RE.exec(prompt)?.[1];
+  if (tagged) return tagged;
+  return SLASH_RE.exec(prompt.trim())?.[1] ?? null;
+}
+
+export function turnExtras(prompt: string, text: string) {
+  return {
+    language: languageOf(text),
+    pastedChars: pastedChars(prompt),
+    images: imageCount(prompt),
+    command: slashCommandOf(prompt),
+  };
+}
+
+export function responseModeOf(reply: string): string | null {
+  const match = MODE_RE.exec(reply.slice(0, 400));
+  if (!match) return null;
+  return match[1] ?? "MINIMAL";
+}