portable-agent-layer 0.71.0 → 0.72.0

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

@@ -9,9 +9,15 @@
  *
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import {
+  isRecaptureWorthwhile,
+  learningSlug,
+  markCaptured,
+  readCapture,
+} from "../lib/capture-store";
 import { stringify } from "../lib/frontmatter";
 import { canInfer, inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
@@ -27,68 +33,6 @@ import {
 } from "../lib/transcript";
 import { appendProjectHistory, detectStatus } from "../lib/work-tracking";
 
-// ── Dedup tracking ──
-
-interface CaptureEntry {
-  filepath: string;
-  messageCount: number;
-}
-
-const MIN_NEW_MESSAGES = 10;
-
-function capturedPath(): string {
-  return resolve(paths.state(), "captured-learnings.json");
-}
-
-function getPreviousCapture(sessionId: string): CaptureEntry | null {
-  const p = capturedPath();
-  if (!existsSync(p)) return null;
-  try {
-    const raw = JSON.parse(readFileSync(p, "utf-8"));
-    if (Array.isArray(raw)) return null;
-    const entry = raw[sessionId];
-    if (!entry) return null;
-    if (typeof entry === "string") return { filepath: entry, messageCount: 0 };
-    return entry as CaptureEntry;
-  } catch {
-    return null;
-  }
-}
-
-function markCaptured(sessionId: string, filepath: string, messageCount: number): void {
-  const p = capturedPath();
-  let data: Record<string, CaptureEntry> = {};
-  try {
-    if (existsSync(p)) {
-      const raw = JSON.parse(readFileSync(p, "utf-8"));
-      if (!Array.isArray(raw) && typeof raw === "object") {
-        for (const [k, v] of Object.entries(raw)) {
-          data[k] =
-            typeof v === "string"
-              ? { filepath: v, messageCount: 0 }
-              : (v as CaptureEntry);
-        }
-      }
-    }
-  } catch {
-    /* start fresh */
-  }
-  data[sessionId] = { filepath, messageCount };
-  const entries = Object.entries(data);
-  if (entries.length > 50) data = Object.fromEntries(entries.slice(-50));
-  writeFileSync(p, JSON.stringify(data, null, 2), "utf-8");
-}
-
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]/g, "")
-    .trim()
-    .split(/\s+/)
-    .slice(0, 4)
-    .join("-");
-}
-
 // ── JSON schema for merged Haiku call ──
 
 const INTELLIGENCE_SCHEMA = {
@@ -124,17 +68,16 @@ interface IntelligenceOutput {
 
 // ── Main handler ──
 
-async function captureSessionIntelligence(
+/** @lintignore exercised directly by test/session-intelligence.test.ts */
+export async function captureSessionIntelligence(
   transcript: string,
   sessionId?: string
 ): Promise<void> {
   const messages = parseMessages(transcript);
   if (messages.length < 6 || transcript.length < 2000) return;
 
-  // Dedup check
-  if (sessionId) {
-    const prev = getPreviousCapture(sessionId);
-    if (prev && messages.length - prev.messageCount < MIN_NEW_MESSAGES) return;
+  if (sessionId && !isRecaptureWorthwhile(readCapture(sessionId), messages.length)) {
+    return;
   }
 
   // Skip if no inference path is available (no CLI binary AND no API key)
@@ -200,7 +143,7 @@ async function captureSessionIntelligence(
   // ── Write session learning file ──
 
   const category = categorizeLearning(title, summary);
-  const slug = slugify(title);
+  const slug = learningSlug(title);
   const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
   const filename = `${fileTimestamp()}_${category}_${slug}.md`;
 
@@ -224,7 +167,7 @@ async function captureSessionIntelligence(
 
   // Remove previous capture for this session
   if (sessionId) {
-    const prev = getPreviousCapture(sessionId);
+    const prev = readCapture(sessionId);
     if (prev?.filepath && existsSync(prev.filepath)) {
       try {
         await unlink(prev.filepath);

package/src/hooks/lib/capture-store.ts

@@ -0,0 +1,103 @@
+/**
+ * Which sessions have already had their learning captured, and where the file went.
+ *
+ * A session's Stop event fires after every response, so the same session reaches
+ * the capture handler many times. Without a record of what was already written,
+ * each pass would produce another near-identical learning file for one session.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+export interface CaptureEntry {
+  filepath: string;
+  messageCount: number;
+}
+
+/** Below this many new messages, a re-capture would restate what was already written. */
+const MIN_NEW_MESSAGES = 10;
+
+/** How many sessions the file remembers before the oldest are dropped. */
+const MAX_REMEMBERED = 50;
+
+/** @lintignore exercised directly by test/capture-store.test.ts */
+export function capturedPath(): string {
+  return resolve(paths.state(), "captured-learnings.json");
+}
+
+/**
+ * Entries were once a bare filepath string. One is read as a capture at message
+ * zero, which makes any later session look new enough to re-capture — the safe
+ * direction for a record whose message count was never written down.
+ */
+function asEntry(value: unknown): CaptureEntry | null {
+  if (typeof value === "string") return { filepath: value, messageCount: 0 };
+  if (value && typeof value === "object") return value as CaptureEntry;
+  return null;
+}
+
+function readAll(): Record<string, CaptureEntry> {
+  const path = capturedPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    if (Array.isArray(raw) || !raw || typeof raw !== "object") return {};
+    const entries: Record<string, CaptureEntry> = {};
+    for (const [id, value] of Object.entries(raw)) {
+      const entry = asEntry(value);
+      if (entry) entries[id] = entry;
+    }
+    return entries;
+  } catch {
+    return {};
+  }
+}
+
+export function readCapture(sessionId: string): CaptureEntry | null {
+  return readAll()[sessionId] ?? null;
+}
+
+/**
+ * A session with no previous capture is always worth writing. One that has grown
+ * by fewer than MIN_NEW_MESSAGES since is not: the transcript window the summary
+ * is drawn from has barely moved, so the second file would say the same thing.
+ */
+export function isRecaptureWorthwhile(
+  previous: CaptureEntry | null,
+  messageCount: number
+): boolean {
+  if (!previous) return true;
+  return messageCount - previous.messageCount >= MIN_NEW_MESSAGES;
+}
+
+export function markCaptured(
+  sessionId: string,
+  filepath: string,
+  messageCount: number
+): void {
+  const data = readAll();
+  data[sessionId] = { filepath, messageCount };
+  const entries = Object.entries(data);
+  const kept = entries.length > MAX_REMEMBERED ? entries.slice(-MAX_REMEMBERED) : entries;
+  writeFileSync(
+    capturedPath(),
+    JSON.stringify(Object.fromEntries(kept), null, 2),
+    "utf-8"
+  );
+}
+
+/**
+ * The readable half of a learning file's name. Four words, because the rest of
+ * the name is already a timestamp and a category and the whole thing has to stay
+ * a filename.
+ */
+export function learningSlug(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 4)
+    .join("-");
+}

package/src/hooks/lib/compact-recall.ts

@@ -0,0 +1,89 @@
+/**
+ * The last exchange before a compaction, and what is safe to do with it after.
+ *
+ * A summary can collapse the turn that was in flight when the window filled, so
+ * the originals are re-injected verbatim on the next session. Everything here
+ * used to sit inside the spawned hook: the budget split, the order the candidate
+ * files are tried in, and whether the file just read may be deleted.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+/** Hook output is capped at 10,000 chars; the rest is headroom for the framing. */
+const MAX_OUTPUT = 9_000;
+
+/** The user's half. The assistant's reply is the longer of the two in most turns. */
+const USER_SHARE = 0.4;
+
+/** Held back for the reminder's headings and framing text. */
+const FRAMING_RESERVE = 300;
+
+export interface SavedExchange {
+  sessionId: string;
+  timestamp: string;
+  trigger: string | null;
+  customInstructions: string | null;
+  userMessage: string;
+  assistantMessage: string;
+}
+
+export interface RecallBudget {
+  user: number;
+  assistant: number;
+}
+
+export function recallBudget(max: number = MAX_OUTPUT): RecallBudget {
+  const user = Math.floor(max * USER_SHARE);
+  return { user, assistant: max - user - FRAMING_RESERVE };
+}
+
+/** Says how much was dropped, so a truncated message cannot read as a complete one. */
+export function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}\n[... truncated ${s.length - max} chars]`;
+}
+
+function exchangeDir(): string {
+  return resolve(paths.state(), "last-exchange");
+}
+
+/**
+ * The session's own file first, then the fallback. latest.json is overwritten by
+ * every compaction, so it is right only when nothing more specific exists.
+ */
+export function findSavedExchange(sessionId?: string): string | null {
+  const candidates = [
+    sessionId ? resolve(exchangeDir(), `${sessionId}.json`) : null,
+    resolve(exchangeDir(), "latest.json"),
+  ].filter((path): path is string => path !== null);
+  return candidates.find((path) => existsSync(path)) ?? null;
+}
+
+/**
+ * Consume-on-read, but only for the session's own file: latest.json is the
+ * safety fallback and deleting it would leave the next compaction with nothing.
+ */
+export function isConsumable(file: string, sessionId?: string): boolean {
+  if (!sessionId) return false;
+  return file === resolve(exchangeDir(), `${sessionId}.json`);
+}
+
+export function buildRecall(saved: SavedExchange, budget = recallBudget()): string {
+  return [
+    "<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)", budget.user),
+    "",
+    "**Assistant:**",
+    truncate(
+      saved.assistantMessage || "(no assistant message captured)",
+      budget.assistant
+    ),
+    "</system-reminder>",
+  ].join("\n");
+}

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

@@ -0,0 +1,98 @@
+/**
+ * What a low-rated session is asked about, and what is kept from the answer.
+ *
+ * The handler around this is spawned detached — claude --print's cold start
+ * outruns the Stop hook's budget — so none of it was reachable from a test. The
+ * decisions are here instead: how much of the transcript the question carries,
+ * what the question is, and which of the two sources wins for each field.
+ */
+
+import { extractContent, parseMessages } from "./transcript";
+
+/** Enough of the ending to see what went wrong, without paying for the whole session. */
+const MAX_MESSAGES = 10;
+
+/** Per message, so one long tool dump cannot crowd out the other nine. */
+const MAX_CHARS_PER_MESSAGE = 300;
+
+export interface PendingFailure {
+  rating: number;
+  context: string;
+  detailedContext?: string;
+  principle?: string;
+  responsePreview?: string;
+  userPreview?: string;
+  cwd?: string;
+}
+
+export interface InferredPrinciple {
+  principle?: string;
+  detailedContext?: string;
+}
+
+export function recentExchange(transcript: string): string {
+  return parseMessages(transcript)
+    .slice(-MAX_MESSAGES)
+    .map(
+      (message) =>
+        `${message.role.toUpperCase()}: ${extractContent(message).slice(0, MAX_CHARS_PER_MESSAGE)}`
+    )
+    .join("\n\n");
+}
+
+/** The parent may already have a principle, in which case there is nothing to ask. */
+export function needsInference(pending: PendingFailure): boolean {
+  return !pending.principle;
+}
+
+export function principleRequest(pending: PendingFailure, recent: string) {
+  return {
+    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: 90_000,
+    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",
+  };
+}
+
+function parseInferred(output: string | null): InferredPrinciple {
+  if (!output) return {};
+  try {
+    const parsed = JSON.parse(output) as {
+      principle?: string;
+      detailed_context?: string;
+    };
+    return {
+      principle: parsed.principle || undefined,
+      detailedContext: parsed.detailed_context || undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The two fields resolve differently on purpose. A principle the parent already
+ * had means inference never ran, so there is nothing to lose to; a detailed
+ * context it already had was written from the full session and outranks one
+ * inferred from ten messages.
+ */
+export function mergeInferredPrinciple(
+  pending: PendingFailure,
+  output: string | null
+): InferredPrinciple {
+  const inferred = parseInferred(output);
+  return {
+    principle: pending.principle || inferred.principle,
+    detailedContext: pending.detailedContext ?? inferred.detailedContext,
+  };
+}

package/src/hooks/lib/ledger-hook.ts

@@ -13,6 +13,7 @@ import {
   claimPending,
   type LedgerEntry,
   type LedgerOutcome,
+  type PendingSnapshot,
   reapStalePending,
   recordAction,
   savePending,
@@ -245,6 +246,40 @@ export function commitApplied(call: LedgeredCall): LedgerEntry | null {
   return entry;
 }
 
+/**
+ * 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.
+ */
+export function unappliedBefore(
+  pending: PendingSnapshot | null,
+  target: string
+): string | null {
+  if (pending) return pending.before;
+  return contentsOf(target);
+}
+
+/**
+ * Record a call that did not land. Unlike the applied half this writes with or
+ * without a parked snapshot, because a missing snapshot here is recoverable and
+ * dropping the entry would lose the only record that the attempt happened.
+ */
+export function commitUnapplied(
+  call: LedgeredCall,
+  verdict: UnappliedVerdict
+): LedgerEntry {
+  return recordAction({
+    tool: call.tool,
+    target: call.target,
+    outcome: verdict.outcome,
+    before: unappliedBefore(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,
+  });
+}
+
 export function toolUseIdOf(payload: Record<string, unknown>): string | null {
   for (const key of ["tool_use_id", "toolUseId", "tool_call_id"]) {
     const value = payload[key];

package/src/hooks/lib/ledger.ts

@@ -46,8 +46,14 @@ import { isSensitivePath } from "./sensitive-path";
  * lose the only signal in the record that says where the boundary was drawn,
  * and "what did I try that was refused" is a question worth being able to ask
  * separately from "what did I try that broke".
+ *
+ * `blocked` is a rule refusing, on the same reasoning: a person can be asked to
+ * reconsider and a rule cannot, so "PAL would not let me" and "you would not
+ * let me" are different facts about where the boundary sits. It is also the
+ * only outcome PAL itself decides, which is what makes the declare-enforce-record
+ * triad demonstrable rather than merely wired.
  */
-export type LedgerOutcome = "applied" | "failed" | "denied";
+export type LedgerOutcome = "applied" | "failed" | "denied" | "blocked";
 
 /**
  * One side of a change, identified rather than reproduced. The hash ties the
@@ -107,6 +113,12 @@ export interface LedgerEntry extends RecordAttribution {
   delta?: LedgerDelta;
   /** Why the action did not land. Absent on an applied one. */
   reason?: string;
+  /**
+   * The shell command a rule refused. Only a blocked shell action carries one:
+   * it has no file to name, so without this the entry could say a command was
+   * refused but not which.
+   */
+  command?: string;
 }
 
 export interface RecordActionInput {
@@ -121,6 +133,7 @@ export interface RecordActionInput {
   /** Resulting content; null when nothing landed. */
   after: string | null;
   reason?: string;
+  command?: string;
 }
 
 /**
@@ -254,6 +267,7 @@ export function recordAction(input: RecordActionInput): LedgerEntry {
     after: stateOf(input.after),
     ...(delta ? { delta } : {}),
     ...(input.reason ? { reason: input.reason } : {}),
+    ...(input.command ? { command: input.command } : {}),
   };
 
   const file = ledgerPath();
@@ -262,6 +276,39 @@ export function recordAction(input: RecordActionInput): LedgerEntry {
   return entry;
 }
 
+/** A refused command is quoted back, not stored whole. */
+const MAX_COMMAND_CHARS = 500;
+
+export interface RecordBlockedInput {
+  tool: string;
+  /** Absolute path of the file, or of the directory a refused command ran in. */
+  target: string;
+  /** The refused command, when the tool was a shell rather than an editor. */
+  command?: string;
+  /** What the rule told the agent — the same words, so both records agree. */
+  reason: string;
+}
+
+/**
+ * A rule refused this before it ran. Written by whoever enforces the rule, at
+ * the moment it fires, because a refusal produces no other event: nothing runs,
+ * so no post-tool hook reports it and nothing downstream can infer it happened.
+ *
+ * There is no before or after. The file is untouched, and a delta claiming
+ * otherwise would be the ledger describing a change that never occurred.
+ */
+export function recordBlocked(input: RecordBlockedInput): LedgerEntry {
+  return recordAction({
+    tool: input.tool,
+    target: input.target,
+    outcome: "blocked",
+    before: null,
+    after: null,
+    reason: input.reason,
+    ...(input.command ? { command: input.command.slice(0, MAX_COMMAND_CHARS) } : {}),
+  });
+}
+
 /**
  * The before-state, held between the two halves of one tool call.
  *