portable-agent-layer 0.93.0 → 0.95.0

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

@@ -0,0 +1,59 @@
+/**
+ * opencode's bus events as PAL events. The plugin lives as long as opencode,
+ * so a permission's tool is remembered from its ask until its reply.
+ */
+
+import { logCompaction, logSessionStart } from "./session-events";
+import { logToolCall } from "./tool-events";
+
+interface OpencodeSession {
+  id?: string;
+  parentID?: string;
+}
+
+interface OpencodePermission {
+  id?: string;
+  type?: string;
+}
+
+/** v1 of opencode's SDK names these permissionID/response, v2 requestID/reply. */
+interface OpencodePermissionReply {
+  sessionID?: string;
+  permissionID?: string;
+  requestID?: string;
+  response?: string;
+  reply?: string;
+}
+
+const askedTools = new Map<string, string>();
+
+export function logOpencodeSessionCreated(session: OpencodeSession | undefined): void {
+  if (!session?.id || session.parentID) return;
+  logSessionStart({ session_id: session.id, source: "startup" });
+}
+
+export function logOpencodeCompaction(sessionID: string | undefined): void {
+  logCompaction({ session_id: sessionID });
+}
+
+export function rememberAskedTool(permission: OpencodePermission): void {
+  if (permission.id && permission.type) askedTools.set(permission.id, permission.type);
+}
+
+function takeAskedTool(reply: OpencodePermissionReply): string | undefined {
+  const id = reply.permissionID ?? reply.requestID;
+  if (!id) return undefined;
+  const tool = askedTools.get(id);
+  askedTools.delete(id);
+  return tool;
+}
+
+export function logOpencodePermissionReply(reply: OpencodePermissionReply): void {
+  const tool = takeAskedTool(reply);
+  if ((reply.response ?? reply.reply) !== "reject" || !tool) return;
+  logToolCall({
+    hook_event_name: "PermissionDenied",
+    tool_name: tool,
+    session_id: reply.sessionID,
+  });
+}

package/src/hooks/lib/paths.ts

@@ -111,6 +111,7 @@ export const paths = {
     home("memory", "learning", "reflections", "algorithm-reflections.jsonl"),
   retrievalIndex: () => home("memory", "learning", ".retrieval-index.json"),
   ledger: () => ensureDir(home("memory", "ledger")),
+  content: () => ensureDir(home("memory", "content")),
   progress: () => ensureDir(home("memory", "state", "progress")),
   projectHistory: () => ensureDir(home("memory", "projects")),
   unboundHistory: () => ensureDir(home("memory", "state", "unbound-history")),

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

@@ -0,0 +1,66 @@
+/**
+ * Everything PAL does once a tool call has ended: the tool_call event, and the
+ * ledger's second half. A failure or a denial is recorded as unapplied, anything
+ * else as applied.
+ *
+ * Not every attempt that fails to land reaches here. A manual denial at the
+ * permission dialog, a `deny` rule and a PreToolUse block fire nothing after
+ * PreToolUse, and a schema rejection fires no hook at all; the reaper in
+ * ledger.ts claims the snapshots those leave behind.
+ */
+
+import { reapStalePending } from "./ledger";
+import {
+  commitApplied,
+  commitUnapplied,
+  landedCalls,
+  ledgeredCalls,
+  type UnappliedVerdict,
+  unappliedVerdictOf,
+} from "./ledger-hook";
+import { logDebug } from "./log";
+import { logToolCall } from "./tool-events";
+
+type Payload = Record<string, unknown>;
+
+function recordApplied(payload: Payload): void {
+  for (const call of landedCalls(payload)) {
+    const entry = commitApplied(call);
+    if (entry) logDebug("post-tool", `applied ${entry.id} ${entry.tool} ${entry.target}`);
+  }
+}
+
+function recordUnapplied(payload: Payload, verdict: UnappliedVerdict): void {
+  const calls = ledgeredCalls(payload);
+  if (calls.length === 0) return;
+  for (const call of calls) {
+    const entry = commitUnapplied(call, verdict);
+    logDebug("post-tool", `${entry.outcome} ${entry.id} ${entry.target}`);
+  }
+  reapStalePending();
+}
+
+function recordInLedger(payload: Payload): void {
+  const verdict = unappliedVerdictOf(payload);
+  if (verdict) recordUnapplied(payload, verdict);
+  else recordApplied(payload);
+}
+
+const HANDLERS: Record<string, (payload: Payload) => void> = {
+  events: logToolCall,
+  ledger: recordInLedger,
+};
+
+/**
+ * Runs every handler, or the one an `--only=<name>` registration asks for:
+ * Claude Code runs the ledger sync on edits and the events async on every tool.
+ */
+export function runPostToolHandlers(
+  payload: Payload,
+  argv: string[] = process.argv
+): void {
+  const only = argv.find((a) => a.startsWith("--only="))?.slice("--only=".length);
+  for (const [name, handle] of Object.entries(HANDLERS)) {
+    if (!only || only === name) handle(payload);
+  }
+}

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/token-usage.ts

@@ -15,6 +15,7 @@ type TokenCaller =
   | "session-name"
   | "session-intelligence"
   | "entity-extraction"
+  | "entity-research"
   | "relationship"
   | "self-model"
   | "agenda-serves"

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 },
+    });
+  });
+}