portable-agent-layer 0.71.0 → 0.72.0

package/package.json

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

package/src/cli/migrate.ts

@@ -26,7 +26,6 @@ import {
   readProject,
   writeProject,
 } from "../hooks/lib/projects";
-import { readThreads, type Thread, writeThreads } from "../tools/agent/thread";
 import { appendSourceLog } from "../tools/knowledge/ingest";
 import {
   type Entity,
@@ -35,6 +34,7 @@ import {
   save as knowledgeSave,
   slugify,
 } from "../tools/knowledge/lib";
+import { readThreads, type Thread, writeThreads } from "../tools/lib/thread";
 
 // ── Types ─────────────────────────────────────────────────────────
 

package/src/cli/skill.ts

@@ -16,7 +16,7 @@ import { getActiveAgent } from "../hooks/lib/agent";
 import { flagshipAuthorModel } from "../hooks/lib/models";
 import { palHome } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
-import { formatReport, formatSummary, lintSkill } from "../tools/skill-doctor";
+import { formatReport, formatSummary, lintSkill } from "../tools/lib/skill-doctor";
 
 /** Entry names under ~/.pal/skills/, sorted; dangling links included. */
 function skillEntries(dir: string): string[] {

package/src/hooks/CompactRecover.ts

@@ -1,19 +1,20 @@
 /**
- * Hook: SessionStart with matcher "compact" — Re-injects the last exchange after compaction.
+ * Hook: SessionStart(compact) — re-injects the exchange that was in flight when
+ * the window filled, since the summary may have collapsed it.
  *
- * Reads the state file written by PreCompactPersist.ts and prints a system-reminder to
- * stdout. SessionStart stdout is added as context that Claude can see, per Claude Code
- * hook docs.
- *
- * Storage: ~/.pal/memory/state/last-exchange/{session_id}.json (with latest.json fallback).
+ * What to inject and what may then be deleted is in lib/compact-recall.ts, where
+ * a test can import it.
  */
 
-import { existsSync } from "node:fs";
 import { readFile, unlink } from "node:fs/promises";
-import { resolve } from "node:path";
 import { isCursor } from "./lib/agent";
+import {
+  buildRecall,
+  findSavedExchange,
+  isConsumable,
+  type SavedExchange,
+} from "./lib/compact-recall";
 import { logDebug, logError } from "./lib/log";
-import { paths } from "./lib/paths";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -26,90 +27,31 @@ interface SessionStartInput {
   source?: "startup" | "resume" | "clear" | "compact" | string;
 }
 
-interface SavedExchange {
-  sessionId: string;
-  timestamp: string;
-  trigger: string | null;
-  customInstructions: string | null;
-  userMessage: string;
-  assistantMessage: string;
-}
-
-// Hook output cap is 10,000 chars per Claude Code docs; leave headroom for framing.
-const MAX_OUTPUT = 9_000;
-
-function truncate(s: string, max: number): string {
-  if (s.length <= max) return s;
-  return `${s.slice(0, max)}\n[... truncated ${s.length - max} chars]`;
-}
-
-const main = async () => {
+try {
   const input = await readStdinJSON<SessionStartInput>();
 
-  // The matcher gates this hook to "compact" sessions, but verify defensively in case
-  // the matcher is misconfigured or the hook is invoked manually.
+  // The matcher gates this hook to "compact" sessions, but verify defensively in
+  // case the matcher is misconfigured or the hook is invoked manually.
   if (input?.source && input.source !== "compact") {
     logDebug("CompactRecover", `source=${input.source} — not compact, skipping`);
     process.exit(0);
   }
 
-  try {
-    const stateDir = resolve(paths.state(), "last-exchange");
-    const sessionId = input?.session_id;
-    const candidates = [
-      sessionId ? resolve(stateDir, `${sessionId}.json`) : null,
-      resolve(stateDir, "latest.json"),
-    ].filter((p): p is string => p !== null);
-
-    const file = candidates.find((p) => existsSync(p));
-    if (!file) {
-      logDebug("CompactRecover", "No saved exchange found — silent no-op");
-      process.exit(0);
-    }
-
-    const saved = JSON.parse(await readFile(file, "utf-8")) as SavedExchange;
-    const userBudget = Math.floor(MAX_OUTPUT * 0.4);
-    const assistantBudget = MAX_OUTPUT - userBudget - 300; // reserve for framing
-
-    const out = [
-      "<system-reminder>",
-      "## Last exchange before compaction",
-      "_Restored verbatim from PAL state. The compaction summary may have collapsed this; the originals are below._",
-      "",
-      "**User:**",
-      truncate(saved.userMessage || "(no user message captured)", userBudget),
-      "",
-      "**Assistant:**",
-      truncate(
-        saved.assistantMessage || "(no assistant message captured)",
-        assistantBudget
-      ),
-      "</system-reminder>",
-    ].join("\n");
-
-    if (isCursor()) {
-      process.stdout.write(JSON.stringify({ additional_context: out }));
-    } else {
-      process.stdout.write(out);
-    }
-    logDebug("CompactRecover", `Re-injected ${out.length} chars from ${file}`);
-
-    // Consume-on-read: drop the session-keyed file after a successful injection so it
-    // doesn't sit on disk forever. latest.json is preserved as a safety fallback and
-    // gets overwritten on the next compaction.
-    const sessionFile = sessionId ? resolve(stateDir, `${sessionId}.json`) : null;
-    if (sessionFile && file === sessionFile) {
-      try {
-        await unlink(sessionFile);
-      } catch (err) {
-        logError("CompactRecover:cleanup", err);
-      }
-    }
-  } catch (err) {
-    logError("CompactRecover", err);
+  const sessionId = input?.session_id;
+  const file = findSavedExchange(sessionId);
+  if (!file) {
+    logDebug("CompactRecover", "No saved exchange found — silent no-op");
+    process.exit(0);
   }
 
-  process.exit(0);
-};
+  const saved = JSON.parse(await readFile(file, "utf-8")) as SavedExchange;
+  const out = buildRecall(saved);
+  process.stdout.write(isCursor() ? JSON.stringify({ additional_context: out }) : out);
+  logDebug("CompactRecover", `Re-injected ${out.length} chars from ${file}`);
+
+  if (isConsumable(file, sessionId)) await unlink(file);
+} catch (err) {
+  logError("CompactRecover", err);
+}
 
-await main();
+process.exit(0);

package/src/hooks/LedgerUnapplied.ts

@@ -20,27 +20,11 @@
  * Silent and fail-open, for the same reason as the other halves.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import {
-  claimPending,
-  type PendingSnapshot,
-  reapStalePending,
-  recordAction,
-} from "./lib/ledger";
-import { ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
+import { reapStalePending } from "./lib/ledger";
+import { commitUnapplied, ledgeredCalls, unappliedVerdictOf } from "./lib/ledger-hook";
 import { logDebug } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 
-/**
- * The snapshot is the trustworthy source, but its absence is recoverable here
- * in a way it never is after a successful edit: nothing landed, so whatever is
- * on disk now is still the before-state.
- */
-function beforeState(pending: PendingSnapshot | null, target: string): string | null {
-  if (pending) return pending.before;
-  return existsSync(target) ? readFileSync(target, "utf-8") : null;
-}
-
 try {
   const input = await readStdinJSON<Record<string, unknown>>();
   if (!input) process.exit(0);
@@ -50,16 +34,7 @@ try {
   if (!verdict) process.exit(0);
 
   for (const call of calls) {
-    const entry = recordAction({
-      tool: call.tool,
-      target: call.target,
-      outcome: verdict.outcome,
-      before: beforeState(claimPending(call.toolUseId), call.target),
-      // Nothing landed. That is what this event means, and it is the difference
-      // between this entry and an applied one.
-      after: null,
-      reason: verdict.reason,
-    });
+    const entry = commitUnapplied(call, verdict);
     logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
   }
 

package/src/hooks/LoadContext.ts

@@ -1,97 +1,70 @@
 /**
  * Hook: SessionStart — Injects dynamic context + regenerates AGENTS.md if stale.
  *
- * Static context (TELOS, setup prompt) is loaded natively from AGENTS.md / CLAUDE.md.
- * This hook injects dynamic context only: wisdom principles, relationship notes,
- * learning digest, signal trends, failure patterns, active work state.
+ * Static context (TELOS, setup prompt) is loaded natively from AGENTS.md /
+ * CLAUDE.md. This hook injects dynamic context only: wisdom principles,
+ * relationship notes, learning digest, signal trends, failure patterns, work state.
  *
- * Copilot: the CLI reads additionalContext from this hook's stdout, while
- * ~/.copilot/instructions/ is read only by the VS Code extension. The merged
- * context goes to both so either surface picks it up.
+ * Which agent gets what, in which envelope, is in lib/session-context.ts.
  */
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { getActiveAgent, isCodex, isCopilot, isCursor } from "./lib/agent";
+import { getActiveAgent } from "./lib/agent";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
 import { logContextSnapshot, logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
+import {
+  contextEnvelope,
+  copilotInstructions,
+  isSubagentSession,
+  needsAgentsMd,
+} from "./lib/session-context";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 
 // 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);
 
-// --- Skip heavy context for subagents ---
-const isSubagent =
-  process.env.CLAUDE_PROJECT_DIR?.includes("/.claude/Agents/") ||
-  process.env.CLAUDE_AGENT_TYPE !== undefined;
-
-if (isSubagent) {
+if (isSubagentSession(process.env)) {
   logDebug("LoadContext", "Subagent session — skipping context loading");
   process.exit(0);
 }
 
-// --- Regenerate CLAUDE.md if telos or setup changed ---
 try {
-  const rebuilt = regenerateIfNeeded();
-  if (rebuilt) logDebug("LoadContext", "AGENTS.md regenerated");
+  if (regenerateIfNeeded()) logDebug("LoadContext", "AGENTS.md regenerated");
 } catch (err) {
   logError("LoadContext:regenerate", err);
 }
 
-// --- Context to stdout (or file for Copilot) ---
 try {
-  // Determine agent target — controls which sections are skipped (loaded natively instead).
   const active = getActiveAgent();
-  const agent: AgentTarget =
+  // The reminder is built for one of three targets; every other agent reads the
+  // same shape Claude Code does.
+  const target: AgentTarget =
     active === "copilot" || active === "cursor" ? active : "claude";
-  const reminder = buildSystemReminder({ agent });
+  const reminder = buildSystemReminder({ agent: target });
   if (!reminder) process.exit(0);
   logContextSnapshot(reminder);
 
-  if (isCopilot()) {
-    // Copilot: semi-static in ~/.copilot/instructions/pal-*.instructions.md (written at stop).
-    // Write AGENTS.md + dynamic context to pal-session.instructions.md on each session start.
-    const instructionsDir = resolve(platform.copilotDir(), "instructions");
-    mkdirSync(instructionsDir, { recursive: true });
-    const agentsMd = buildClaudeMd();
-    const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
-    if (context) {
-      writeFileSync(
-        resolve(instructionsDir, "pal-session.instructions.md"),
-        `---\napplyTo: "**"\n---\n\n${context}`,
-        "utf-8"
-      );
-      process.stdout.write(JSON.stringify({ additionalContext: context }));
-    }
-    logDebug(
-      "LoadContext",
-      `Copilot session instructions written: ${context.length} chars`
-    );
-  } else if (isCursor()) {
-    // Cursor: semi-static in ~/.cursor/rules/pal-context.mdc; inject AGENTS.md + dynamic here
-    const agentsMd = buildClaudeMd();
-    const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
-    process.stdout.write(JSON.stringify({ additional_context: context }));
-    logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
-  } else if (isCodex()) {
-    // Codex: AGENTS.md already loaded via symlink; inject only dynamic context
-    process.stdout.write(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "SessionStart",
-          additionalContext: reminder,
-        },
-      })
-    );
-    logDebug("LoadContext", `Codex reminder injected: ${reminder.length} chars`);
-  } else {
-    // Claude Code (and opencode, which uses the plugin path not this hook): raw text
-    console.log(reminder);
-    logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
+  const envelope = contextEnvelope(
+    active,
+    reminder,
+    needsAgentsMd(active) ? buildClaudeMd() : ""
+  );
+  if (!envelope) process.exit(0);
+
+  if (envelope.file) {
+    const dir = resolve(platform.copilotDir(), "instructions");
+    mkdirSync(dir, { recursive: true });
+    const path = resolve(dir, "pal-session.instructions.md");
+    writeFileSync(path, copilotInstructions(envelope.file), "utf-8");
   }
+
+  if (envelope.kind === "text") console.log(envelope.payload);
+  else process.stdout.write(envelope.payload);
+  logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
 } catch (err) {
   logError("LoadContext:reminder", err);
 }

package/src/hooks/SecurityValidator.ts

@@ -3,125 +3,32 @@
  * Emits the current agent's deny response to block, or exits silently to allow.
  *
  * Fail-open design: if anything goes wrong, the command is allowed through.
+ *
+ * The decision itself is in lib/security-gate.ts, where a test can import it.
  */
 
-import { blockResponse, normalizeToolUse } from "./lib/agent";
-import { logDebug } from "./lib/log";
-import { checkBashCommand, checkFilePath } from "./lib/security";
+import { blockResponse } from "./lib/agent";
+import { recordBlocked } from "./lib/ledger";
+import { logError } from "./lib/log";
+import { decideRefusal, type SecurityInput } from "./lib/security-gate";
 import { readStdinJSON } from "./lib/stdin";
 
-// beforeShellExecution shape (Cursor only) — flat, no tool-name wrapper
-interface ShellExecInput {
-  command: string;
-  sandbox?: boolean;
-}
-
-type SecurityInput = Record<string, unknown> | ShellExecInput;
-
-function isShellExec(input: SecurityInput): input is ShellExecInput {
-  return !("tool_name" in input) && !("toolName" in input) && "command" in input;
-}
-
-// A name this list misses is a command this hook waves through, so both sets mirror
-// the tool names VS Code's own Copilot build ships in its shell and edit tool sets.
-const SHELL_TOOLS = [
-  "bash",
-  "shell",
-  "powershell",
-  "local_shell",
-  "runinterminal",
-  "run_in_terminal",
-  "terminal",
-  "execute_command",
-];
-
-const FILE_WRITE_TOOLS = [
-  "write",
-  "edit",
-  "multiedit",
-  "write_file",
-  "apply_patch",
-  "applypatch",
-  "create",
-  "create_file",
-  "createfile",
-  "str_replace",
-  "str_replace_editor",
-  "insert",
-  "insert_edit_into_file",
-  "replace_string_in_file",
-  "multi_replace_string_in_file",
-  "replacestring",
-  "edit_notebook_file",
-  "notebookedit",
-];
-
-/** First of `keys` present as a non-empty string — agents disagree on argument spelling. */
-function firstStringArg(
-  args: Record<string, unknown>,
-  keys: string[]
-): string | undefined {
-  for (const key of keys) {
-    const value = args[key];
-    if (typeof value === "string" && value.length > 0) return value;
-  }
-  return undefined;
-}
-
-/** Tool names that run a shell command, across every agent's naming. */
-function runsShellCommand(toolName: string): boolean {
-  return SHELL_TOOLS.includes(toolName.toLowerCase());
-}
-
-/** Tool names that write to a file, across every agent's naming. */
-function writesFile(toolName: string): boolean {
-  return FILE_WRITE_TOOLS.includes(toolName.toLowerCase());
-}
-
 try {
   const input = await readStdinJSON<SecurityInput>();
   if (!input) process.exit(0);
 
-  if (isShellExec(input)) {
-    // beforeShellExecution — command is always a shell command
-    const reason = checkBashCommand(input.command);
-    if (reason) {
-      process.stdout.write(blockResponse(`Blocked: ${reason}`));
-    }
-    process.exit(0);
-  }
-
-  const toolUse = normalizeToolUse(input);
-  if (!toolUse) process.exit(0);
+  const refusal = decideRefusal(input, process.cwd());
+  if (!refusal) process.exit(0);
 
-  // Each agent names its shell/write tools differently; log the real name so an
-  // unrecognized one shows up here instead of silently skipping the check.
-  logDebug(
-    "SecurityValidator",
-    `toolName=${toolUse.toolName} args=${Object.keys(toolUse.toolInput).join(",")}`
-  );
-
-  const command = firstStringArg(toolUse.toolInput, ["command", "commandLine", "script"]);
-  if (runsShellCommand(toolUse.toolName) && typeof command === "string") {
-    const reason = checkBashCommand(command);
-    const verdict = reason ? `BLOCK(${reason})` : "ALLOW";
-    // "No output" from a downstream tool is indistinguishable between "denied,
-    // never ran" and "ran, produced nothing" — logging the verdict here, next
-    // to the literal command, is what actually tells the two apart.
-    logDebug("SecurityValidator", `bashVerdict=${verdict} command=${command}`);
-    if (reason) {
-      process.stdout.write(blockResponse(`Blocked: ${reason}`, toolUse.hookEventName));
-      process.exit(0);
-    }
-  }
+  process.stdout.write(blockResponse(refusal.message, refusal.hookEventName));
 
-  const filePath = firstStringArg(toolUse.toolInput, ["file_path", "filePath", "path"]);
-  if (writesFile(toolUse.toolName) && typeof filePath === "string") {
-    const reason = checkFilePath(filePath);
-    if (reason) {
-      process.stdout.write(blockResponse(reason, toolUse.hookEventName));
-      process.exit(0);
-    }
+  // After the deny has gone out, in its own try/catch: this hook is fail-open,
+  // and a ledger that threw on its way to recording a block would turn the
+  // block into an allow.
+  try {
+    recordBlocked(refusal);
+  } catch (err) {
+    logError("SecurityValidator:ledger", err);
   }
 } catch {
   // Fail open

package/src/hooks/handlers/failure-principle.ts

@@ -11,24 +11,22 @@
 
 import { existsSync } from "node:fs";
 import { readFile, unlink } from "node:fs/promises";
-import { extractContent, parseMessages } from "../lib/transcript";
+import {
+  mergeInferredPrinciple,
+  needsInference,
+  type PendingFailure,
+  principleRequest,
+  recentExchange,
+} from "../lib/failure-principle";
 import { captureFailure } from "./failure";
 
-interface PendingFailure {
-  rating: number;
-  context: string;
-  detailedContext?: string;
-  principle?: string;
-  responsePreview?: string;
-  userPreview?: string;
-  cwd?: string;
-}
-
 /**
  * Inference the principle (if missing) and persist the failure record.
  * Reads pending data + transcript from the provided tmp paths and unlinks them.
+ *
+ * @lintignore exercised directly by test/failure-principle.test.ts
  */
-async function processFailurePrinciple(
+export async function processFailurePrinciple(
   pendingPath: string,
   transcriptPath: string
 ): Promise<void> {
@@ -47,42 +45,19 @@ async function processFailurePrinciple(
     logDebug("failure-principle", `processing rating=${pending.rating}`);
 
     let { principle, detailedContext } = pending;
-    if (!principle) {
+    if (needsInference(pending)) {
       try {
         const { inference } = await import("../lib/inference");
-        const msgs = parseMessages(transcript);
-        const recent = msgs
-          .slice(-10)
-          .map((m) => `${m.role.toUpperCase()}: ${extractContent(m).slice(0, 300)}`)
-          .join("\n\n");
-
-        const result = await inference({
-          system: `Analyze this failed AI interaction (rated ${pending.rating}/10). Return JSON: {"principle": "<verb-first actionable rule, 10-20 words — write a full sentence, not a fragment>", "detailed_context": "<root cause and what to do differently, 50-150 words>"}.`,
-          user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
-          maxTokens: 400,
-          timeout: 90000,
-          jsonSchema: {
-            type: "object" as const,
-            properties: {
-              principle: { type: "string" as const },
-              detailed_context: { type: "string" as const },
-            },
-            required: ["principle", "detailed_context"],
-            additionalProperties: false,
-          },
-          caller: "failure-principle",
-        });
-
-        if (result.success && result.output) {
-          const parsed = JSON.parse(result.output) as {
-            principle?: string;
-            detailed_context?: string;
-          };
-          principle = parsed.principle || undefined;
-          detailedContext ??= parsed.detailed_context || undefined;
-        } else {
+        const result = await inference(
+          principleRequest(pending, recentExchange(transcript))
+        );
+        if (!result.success || !result.output) {
           logError("failure-principle", `inference failed (no output)`);
         }
+        ({ principle, detailedContext } = mergeInferredPrinciple(
+          pending,
+          result.output ?? null
+        ));
       } catch (err) {
         logError("failure-principle:inference", err);
       }