portable-agent-layer 0.94.0 → 0.95.1

package/README.md

@@ -85,6 +85,8 @@ 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 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 |
 | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |

package/assets/templates/hooks.antigravity.json

@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=antigravity"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=antigravity"
           }
         ]
       }

package/assets/templates/hooks.codex.json

@@ -39,7 +39,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=codex"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=codex"
           }
         ]
       }
@@ -54,6 +54,16 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts --agent=codex"
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/assets/templates/hooks.copilot.json

@@ -47,15 +47,15 @@
     "postToolUse": [
       {
         "type": "command",
-        "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=copilot",
-        "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=copilot"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=copilot"
       }
     ],
     "postToolUseFailure": [
       {
         "type": "command",
-        "bash": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=copilot --event=postToolUseFailure",
-        "powershell": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=copilot --event=postToolUseFailure"
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=copilot --event=postToolUseFailure",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=copilot --event=postToolUseFailure"
       }
     ],
     "agentStop": [
@@ -65,6 +65,13 @@
         "powershell": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=copilot"
       }
     ],
+    "preCompact": [
+      {
+        "type": "command",
+        "bash": "bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts --agent=copilot",
+        "powershell": "bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts --agent=copilot"
+      }
+    ],
     "sessionEnd": [
       {
         "type": "command",

package/assets/templates/hooks.cursor.json

@@ -34,13 +34,13 @@
     "postToolUse": [
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=cursor"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=cursor"
       }
     ],
     "postToolUseFailure": [
       {
         "type": "command",
-        "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=cursor"
+        "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=cursor"
       }
     ],
     "beforeShellExecution": [
@@ -61,6 +61,12 @@
         "command": "bun run {{PKG_ROOT}}/src/hooks/StopOrchestrator.ts --agent=cursor"
       }
     ],
+    "preCompact": [
+      {
+        "type": "command",
+        "command": "bun run {{PKG_ROOT}}/src/hooks/PreCompactPersist.ts --agent=cursor"
+      }
+    ],
     "sessionEnd": [
       {
         "type": "command",

package/assets/templates/settings.claude.json

@@ -158,7 +158,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts --agent=claude"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=claude --only=ledger"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=claude --only=events",
+            "async": true
           }
         ]
       }
@@ -169,7 +179,39 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=claude --only=ledger"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=claude --only=events",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/AttentionEvent.ts --agent=claude"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/AttentionEvent.ts --agent=claude"
           }
         ]
       }
@@ -180,7 +222,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts --agent=claude"
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=claude --only=ledger"
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run {{PKG_ROOT}}/src/hooks/PostToolOrchestrator.ts --agent=claude --only=events",
+            "async": true
           }
         ]
       }

package/package.json

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

package/src/cli/content.ts

@@ -0,0 +1,23 @@
+import { preserveTranscriptsOnce } from "../hooks/lib/transcript-preserve";
+import { group, leaf } from "../tools/lib/command";
+
+function printPreserve(): undefined {
+  const result = preserveTranscriptsOnce();
+  if (!result) {
+    console.log("Another copy is already running.");
+    return;
+  }
+  console.log(
+    `Copied ${result.copied}, unchanged ${result.unchanged}, failed ${result.failed}`
+  );
+}
+
+export const contentCommand = group({
+  summary: "PAL's local content store (never exported)",
+  commands: {
+    preserve: leaf({
+      summary: "Copy Claude Code transcripts, gzipped, before Claude Code deletes them",
+      run: printPreserve,
+    }),
+  },
+});

package/src/cli/events.ts

@@ -0,0 +1,47 @@
+import { isNagStage, logDiscordNag, NAG_STAGES } from "../hooks/lib/discord-events";
+import { group, leaf, UsageError } from "../tools/lib/command";
+
+function secondsFrom(raw: string | undefined): number | null {
+  if (raw === undefined) return null;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new UsageError(`--after-sec must be a number of seconds, got "${raw}"`);
+  }
+  return Math.round(seconds);
+}
+
+function recordDiscordNag(
+  stage: string | undefined,
+  kind: string | undefined,
+  afterSec: string | undefined
+): undefined {
+  if (!isNagStage(stage)) {
+    throw new UsageError(`the stage is one of ${NAG_STAGES.join(", ")}`);
+  }
+  const responseSec = secondsFrom(afterSec);
+  if (stage === "answered" && responseSec === null) {
+    throw new UsageError("an answered nag needs --after-sec");
+  }
+  const id = logDiscordNag(stage, kind ?? null, responseSec);
+  console.log(id ? `Recorded ${id}` : "The event log is off; nothing recorded.");
+}
+
+export const eventsCommand = group({
+  summary: "PAL's local event log",
+  commands: {
+    "discord-nag": leaf({
+      summary: "Record a nag the Discord bot sent, or how long its answer took",
+      args: "<sent|answered>",
+      options: {
+        kind: { type: "string", value: "<kind>", description: "What the nag was about" },
+        "after-sec": {
+          type: "string",
+          value: "<n>",
+          description: "Seconds from the nag to the answer",
+        },
+      },
+      run: ({ positionals, values }) =>
+        recordDiscordNag(positionals[0], values.kind, values["after-sec"]),
+    }),
+  },
+});

package/src/cli/tree.ts

@@ -14,6 +14,8 @@ import {
   type OptionSpecs,
 } from "../tools/lib/command";
 import { builtinTools, builtinToolVerbs } from "./builtin-tools";
+import { contentCommand } from "./content";
+import { eventsCommand } from "./events";
 import { identityCommand } from "./identity";
 import { inferCommand } from "./infer";
 import { knowledgeCommand } from "./knowledge";
@@ -151,6 +153,8 @@ export function cliTree(admin: AdminHandlers): Group {
     commands: {
       ...adminCommands(admin),
       usage: usageCommand,
+      content: contentCommand,
+      events: eventsCommand,
       infer: inferCommand,
       actor: identityCommand("actor"),
       machine: identityCommand("machine"),

package/src/hooks/AttentionEvent.ts

@@ -0,0 +1,22 @@
+/**
+ * Hook: PermissionRequest and Notification — logs that the agent is waiting on
+ * the user. Logging only: it prints nothing, so it never answers the prompt, and
+ * always exits 0.
+ */
+
+import { logAttention } from "./lib/attention-events";
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { enterHookWorkspace } from "./lib/hook-turn";
+import { isPalSpawnedInference } from "./lib/spawn-guard";
+import { readStdinJSON } from "./lib/stdin";
+
+if (isPalSpawnedInference()) process.exit(0);
+if (duplicatesCursorHooks()) process.exit(0);
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  enterHookWorkspace(input);
+  logAttention(input);
+} catch {
+  process.exit(0);
+}

package/src/hooks/LoadContext.ts

@@ -24,11 +24,10 @@ import {
   isSubagentSession,
   needsAgentsMd,
 } from "./lib/session-context";
+import { logSessionStart } from "./lib/session-events";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
-// Recursion guard — when this process is a PAL-spawned inference subprocess,
-// skip all context loading so we don't trigger another inference call.
 if (isPalSpawnedInference()) process.exit(0);
 if (duplicatesCursorHooks()) process.exit(0);
 if (isSubagentSession(process.env)) {
@@ -51,6 +50,7 @@ try {
 try {
   const active = getActiveAgent();
   const input = await readStdinJSON<{ source?: string }>();
+  logSessionStart(input);
   const wanted = contextForSource(active, input?.source);
   if (wanted === "none") {
     logDebug("LoadContext", `source=${input?.source}, context already present`);

package/src/hooks/PostToolOrchestrator.ts

@@ -0,0 +1,20 @@
+/**
+ * Hook: after a tool call, a failed call or a denied one. Silent and fail-open:
+ * it prints nothing and always exits 0, so it can never disturb a turn.
+ */
+
+import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { enterHookWorkspace } from "./lib/hook-turn";
+import { runPostToolHandlers } from "./lib/post-tool";
+import { readStdinJSON } from "./lib/stdin";
+
+if (duplicatesCursorHooks()) process.exit(0);
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+  enterHookWorkspace(input);
+  runPostToolHandlers(input);
+} catch {
+  process.exit(0);
+}

package/src/hooks/PreCompactPersist.ts

@@ -7,8 +7,8 @@
  *
  * Storage: ~/.pal/memory/state/last-exchange/{session_id}.json + latest.json.
  * Path lives under PAL_HOME so other agents (OpenCode, Copilot, Cursor) can read the
- * same state if/when they grow equivalent compaction-recovery hooks. PreCompact itself
- * is currently a Claude Code event.
+ * same state if/when they grow equivalent compaction-recovery hooks. Cursor, Copilot
+ * and Codex run it too, which logs their compactions.
  */
 
 import { existsSync } from "node:fs";
@@ -19,6 +19,7 @@ import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logDebug, logError } from "./lib/log";
 import { paths } from "./lib/paths";
 import { sessionDir } from "./lib/session-dir";
+import { logCompaction } from "./lib/session-events";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 import { readTranscriptFile } from "./lib/transcript";
@@ -37,6 +38,7 @@ interface PreCompactInput {
 
 const main = async () => {
   const input = await readStdinJSON<PreCompactInput>();
+  logCompaction(input);
   if (!input?.transcript_path) {
     logDebug("PreCompactPersist", "No transcript_path in input — skipping");
     process.exit(0);

package/src/hooks/PreserveTranscripts.ts

@@ -0,0 +1,13 @@
+/**
+ * Spawned, never awaited — copies Claude Code transcripts into PAL's content
+ * store in a process of its own, so no session waits on the gzip.
+ */
+
+import { logError } from "./lib/log";
+import { preserveTranscriptsOnce } from "./lib/transcript-preserve";
+
+try {
+  preserveTranscriptsOnce();
+} catch (err) {
+  logError("PreserveTranscripts", err);
+}

package/src/hooks/SessionClose.ts

@@ -13,14 +13,19 @@
 import { autoUpdateOnClose } from "./lib/auto-update";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logError } from "./lib/log";
+import { logSessionEnd } from "./lib/session-events";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
+import { spawnTranscriptPreserve } from "./lib/transcript-preserve";
 
 if (isPalSpawnedInference()) process.exit(0);
 if (duplicatesCursorHooks()) process.exit(0);
 
+spawnTranscriptPreserve();
+
 try {
   const input = await readStdinJSON<{ reason?: string }>();
+  logSessionEnd(input);
   autoUpdateOnClose(input?.reason);
 } catch (err) {
   logError("SessionClose", err);

package/src/hooks/UserPromptOrchestrator.ts

@@ -9,6 +9,7 @@
 
 import { injectPromptContext } from "./handlers/inject-retrieval";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { startHookTiming } from "./lib/hook-timing";
 import { type HookTurnPayload, hookSessionId } from "./lib/hook-turn";
 import { logDebug, logPromptSnapshot } from "./lib/log";
 import { capturePrompt } from "./lib/prompt-capture";
@@ -28,9 +29,15 @@ const input = await readStdinJSON<PromptSubmitInput>();
 logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)}`);
 if (!input?.prompt) process.exit(0);
 
+const timing = startHookTiming("prompt");
 const sentAt = new Date();
 const sessionId = hookSessionId(input);
-const injected = await injectPromptContext(input.prompt, sessionId);
+const injected = await timing.time("inject-context", () =>
+  injectPromptContext(input.prompt, sessionId)
+);
 logPromptSnapshot(input.prompt, injected);
 
-await capturePrompt(input.prompt, sessionId, sentAt, "UserPromptOrchestrator");
+await timing.time("capture", () =>
+  capturePrompt(input.prompt, sessionId, sentAt, "UserPromptOrchestrator")
+);
+timing.log(sessionId);

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

@@ -0,0 +1,43 @@
+/**
+ * When the agent waits on the user: a permission prompt, or a notification that
+ * it needs them.
+ */
+
+import { normalizeToolUse } from "./agent";
+import { appendEvent, logQuietly } from "./events";
+import { hookSessionId } from "./hook-turn";
+import { markWaiting } from "./waiting-on-user";
+
+function logPermissionPrompt(
+  payload: Record<string, unknown> | null,
+  tool: string | null,
+  now: Date = new Date()
+): void {
+  logQuietly("permission_prompt", () => {
+    const session = hookSessionId(payload) ?? null;
+    appendEvent("permission_prompt", { tool }, { ts: now.toISOString(), session });
+    if (session)
+      markWaiting("permission", session, { ts: now.toISOString(), tool: tool ?? "" });
+  });
+}
+
+function logNotification(payload: Record<string, unknown> | null, now: Date): void {
+  logQuietly("notification", () => {
+    const session = hookSessionId(payload) ?? null;
+    const kind =
+      typeof payload?.notification_type === "string" ? payload.notification_type : null;
+    appendEvent("notification", { kind }, { ts: now.toISOString(), session });
+    if (session) markWaiting("notified", session, { ts: now.toISOString() });
+  });
+}
+
+/** Claude's PermissionRequest and Notification share one hook; it prints nothing. */
+export function logAttention(
+  payload: Record<string, unknown> | null,
+  now: Date = new Date()
+): void {
+  const event = payload?.hook_event_name ?? payload?.hookEventName;
+  if (event === "Notification") logNotification(payload, now);
+  if (event === "PermissionRequest")
+    logPermissionPrompt(payload, normalizeToolUse(payload)?.toolName ?? null, now);
+}

package/src/hooks/lib/auto-update.ts

@@ -15,6 +15,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { cachedStatus, getInstalledVersion, isRepoMode } from "../handlers/update-check";
+import { appendEvent, logQuietly } from "./events";
 import { logDebug, logError } from "./log";
 import { assets, palPkg, paths } from "./paths";
 import { raw as rawSettings } from "./settings";
@@ -118,8 +119,23 @@ function hasUncommittedChanges(): boolean {
   return (status.stdout ?? "").trim().length > 0;
 }
 
+function outcomeOf(entry: AutoUpdateLedger): string {
+  if (!entry.ok) return "failed";
+  return entry.from === entry.to ? "unchanged" : "updated";
+}
+
+function secondsBetween(from?: string, to?: string): number | null {
+  if (!from || !to) return null;
+  return Math.round((Date.parse(to) - Date.parse(from)) / 1000);
+}
+
+function logUpdateEvent(fields: Record<string, unknown>): void {
+  logQuietly("pal_update", () => appendEvent("pal_update", fields));
+}
+
 function recordSkip(reason: string): void {
   writeLedger({ ...readLedger(), skippedAt: new Date().toISOString(), skipped: reason });
+  logUpdateEvent({ outcome: "skipped", skipReason: reason });
   logDebug("auto-update", `skipped: ${reason}`);
 }
 
@@ -278,7 +294,7 @@ function update(): AutoUpdateLedger {
 
   const ok = run.status === 0;
   logDebug("auto-update", `update exited ${run.status}`);
-  return writeLedger({
+  const entry = writeLedger({
     ...readLedger(),
     finishedAt: new Date().toISOString(),
     ok,
@@ -286,6 +302,13 @@ function update(): AutoUpdateLedger {
     to: getInstalledVersion(),
     error: ok ? undefined : (run.error?.message ?? `exit ${run.status}`),
   });
+  logUpdateEvent({
+    outcome: outcomeOf(entry),
+    from: entry.from ?? null,
+    to: entry.to ?? null,
+    durationSec: secondsBetween(entry.attemptedAt, entry.finishedAt),
+  });
+  return entry;
 }
 
 /** Hands the update to its own process, which outlives the session that closed. */

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+import { appendEvent, logQuietly } from "./events";
+
+export type CommitmentOutcome = "kept" | "dropped" | "snoozed" | "reopened";
+
+export function logCommitment(
+  iscProject: string,
+  isc: number,
+  outcome: CommitmentOutcome,
+  surface: "cli" | "control-room",
+  snoozeDays: number | null = null
+): void {
+  logQuietly("commitment", () =>
+    appendEvent("commitment", { iscProject, isc, outcome, surface, snoozeDays })
+  );
+}

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

@@ -0,0 +1,25 @@
+/**
+ * A nag the Discord bot sent, and how long the user took to answer it. The bot
+ * runs outside PAL, so it reports both through `pal cli events discord-nag`.
+ */
+
+import { appendEvent } from "./events";
+
+export const NAG_STAGES = ["sent", "answered"] as const;
+export type NagStage = (typeof NAG_STAGES)[number];
+
+export function isNagStage(value: unknown): value is NagStage {
+  return typeof value === "string" && (NAG_STAGES as readonly string[]).includes(value);
+}
+
+export function logDiscordNag(
+  stage: NagStage,
+  kind: string | null,
+  responseSec: number | null
+): string | null {
+  return appendEvent("discord_nag", {
+    stage,
+    kind,
+    responseSec: stage === "answered" ? responseSec : null,
+  });
+}

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

@@ -0,0 +1,16 @@
+/**
+ * The first time a person, company, idea or research topic enters the knowledge
+ * store. The name stays in the content store; the event carries only its kind.
+ */
+
+import { appendEvent, logQuietly } from "./events";
+
+export function logEntityFirstSeen(
+  domain: string,
+  entityType: string,
+  name: string
+): void {
+  logQuietly("entity_first_seen", () =>
+    appendEvent("entity_first_seen", { domain, entityType }, { content: { name } })
+  );
+}