portable-agent-layer 0.79.1 → 0.79.3

package/assets/schema/pal-settings.schema.json

@@ -58,9 +58,7 @@
         "opinions": { "type": "boolean", "description": "Tracked user opinions." },
         "relationship": { "type": "boolean", "description": "Recent relationship notes." },
         "failurePatterns": { "type": "boolean", "description": "Recurring failure patterns." },
-        "projectHistory": { "type": "boolean", "description": "Per-project session history." },
         "projects": { "type": "boolean", "description": "Active projects list." },
-        "sessionIntelligence": { "type": "boolean", "description": "Rating trends and session signals." },
         "handoff": { "type": "boolean", "description": "Handoff note from the previous session." },
         "selfModel": { "type": "boolean", "description": "The assistant's self-model synthesis." },
         "contextualSteering": { "type": "boolean", "description": "Prompt-time steering self-checks (see the steering section)." },

package/assets/templates/pal-settings.json

@@ -20,9 +20,7 @@
     "opinions": true,
     "relationship": true,
     "failurePatterns": true,
-    "projectHistory": true,
     "projects": true,
-    "sessionIntelligence": true,
     "handoff": true,
     "selfModel": true,
     "contextualSteering": true,

package/package.json

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

package/src/hooks/handlers/persist-last-exchange.ts

@@ -71,8 +71,20 @@ function readHandoffs(): Record<string, StoredHandoff> {
   }
 }
 
+function isWithinReadWindow(entry: StoredHandoff): boolean {
+  if (!entry.timestamp) return false;
+  return Date.now() - new Date(entry.timestamp).getTime() <= HANDOFF_STALE_MS;
+}
+
 function writeHandoffs(handoffs: Record<string, StoredHandoff>): void {
-  writeFileSync(handoffPath(), JSON.stringify(handoffs, null, 2), "utf-8");
+  const readable = Object.entries(handoffs).filter(([, entry]) =>
+    isWithinReadWindow(entry)
+  );
+  writeFileSync(
+    handoffPath(),
+    JSON.stringify(Object.fromEntries(readable), null, 2),
+    "utf-8"
+  );
 }
 
 export function structuredHandoff(parts: {

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

@@ -13,6 +13,8 @@ import { existsSync } from "node:fs";
 import { unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import {
+  claimHandoffSummary,
+  isHandoffStale,
   isRecaptureWorthwhile,
   learningSlug,
   markCaptured,
@@ -109,9 +111,10 @@ export async function captureSessionIntelligence(
   const messages = parseMessages(transcript);
   if (messages.length < 6 || transcript.length < 2000) return;
 
-  if (sessionId && !isRecaptureWorthwhile(readCapture(sessionId), messages.length)) {
-    return;
-  }
+  const userMessageCount = messages.filter((m) => m.role === "user").length;
+  const previous = sessionId ? readCapture(sessionId) : null;
+  const learningDue = isRecaptureWorthwhile(previous, messages.length);
+  if (!learningDue && !isHandoffStale(previous, userMessageCount)) return;
 
   // Skip if no inference path is available (no CLI binary AND no API key)
   if (!canInfer()) {
@@ -134,6 +137,8 @@ export async function captureSessionIntelligence(
 
   if (userWindow.length < 3) return;
 
+  if (sessionId) claimHandoffSummary(sessionId, userMessageCount);
+
   // Single Haiku call
   logDebug("session-intelligence", "Calling inference...");
   const numberedMessages = userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n");
@@ -179,6 +184,8 @@ export async function captureSessionIntelligence(
       sessionId,
     });
   }
+  if (!learningDue) return;
+
   // ── Write session learning file ──
 
   const category = categorizeLearning(title, summary);
@@ -219,13 +226,15 @@ export async function captureSessionIntelligence(
   const filepath = resolve(dir, filename);
   await writeFile(filepath, content, "utf-8");
 
-  // Append to per-project history
-  appendProjectHistory(process.cwd(), {
-    date: new Date().toISOString().slice(0, 10),
-    title,
-    summary,
-    insights,
-  });
+  if (output) {
+    appendProjectHistory(sessionDir(), {
+      date: new Date().toISOString().slice(0, 10),
+      title,
+      summary,
+      insights,
+      session: sessionId,
+    });
+  }
 
   if (sessionId) markCaptured(sessionId, filepath, messages.length);
   logDebug("session-intelligence", `Learning captured: ${title}`);

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

@@ -13,6 +13,7 @@ import { paths } from "./paths";
 export interface CaptureEntry {
   filepath: string;
   messageCount: number;
+  userMessageCount?: number;
 }
 
 /** Below this many new messages, a re-capture would restate what was already written. */
@@ -71,13 +72,22 @@ export function isRecaptureWorthwhile(
   return messageCount - previous.messageCount >= MIN_NEW_MESSAGES;
 }
 
-export function markCaptured(
-  sessionId: string,
-  filepath: string,
-  messageCount: number
-): void {
+/**
+ * The handoff describes the latest turn, so any new message from the user makes
+ * it stale, however little the transcript grew.
+ */
+export function isHandoffStale(
+  previous: CaptureEntry | null,
+  userMessageCount: number
+): boolean {
+  if (!previous) return true;
+  return userMessageCount > (previous.userMessageCount ?? 0);
+}
+
+function updateCapture(sessionId: string, update: Partial<CaptureEntry>): void {
   const data = readAll();
-  data[sessionId] = { filepath, messageCount };
+  const current = data[sessionId] ?? { filepath: "", messageCount: 0 };
+  data[sessionId] = { ...current, ...update };
   const entries = Object.entries(data);
   const kept = entries.length > MAX_REMEMBERED ? entries.slice(-MAX_REMEMBERED) : entries;
   writeFileSync(
@@ -87,6 +97,19 @@ export function markCaptured(
   );
 }
 
+export function markCaptured(
+  sessionId: string,
+  filepath: string,
+  messageCount: number
+): void {
+  updateCapture(sessionId, { filepath, messageCount });
+}
+
+/** Claimed before the model call, so a second Stop for the same turn finds it taken. */
+export function claimHandoffSummary(sessionId: string, userMessageCount: number): void {
+  updateCapture(sessionId, { userMessageCount });
+}
+
 /**
  * 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

package/src/hooks/lib/context.ts

@@ -9,6 +9,7 @@ import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
 import { resolveAnchor } from "./anchor";
+import { oncePerDay } from "./daily-nudge";
 import { loadHandoffContext } from "./handoff-context";
 import { loadOpinionContext } from "./opinions";
 import { paths, toPath } from "./paths";
@@ -18,7 +19,7 @@ import { loadFailurePatterns } from "./semi-static";
 import { sessionDir } from "./session-dir";
 import * as settings from "./settings";
 import { readFramePrinciples } from "./wisdom";
-import { lastSessionTitle, readProjectHistory } from "./work-tracking";
+import { lastSessionTitle } from "./work-tracking";
 
 /** Load and concatenate loadAtStartup files */
 function loadStartupFiles(): string {
@@ -65,25 +66,6 @@ function loadSelfModel(): string {
   }
 }
 
-/** Load per-project session history for the current working directory */
-function loadProjectHistoryContext(): string {
-  try {
-    const cwd = process.cwd();
-    const entries = readProjectHistory(cwd, 3);
-    if (entries.length === 0) return "";
-
-    const lines: string[] = ["## This Project — Session History"];
-    for (const e of entries) {
-      lines.push(`- **${e.title}** (${e.date})`);
-      if (e.summary) lines.push(`  ${e.summary.split("\n")[0].slice(0, 150)}`);
-    }
-
-    return lines.join("\n");
-  } catch {
-    return "";
-  }
-}
-
 function stampedPath(stamp: string): string {
   const resolved = resolveAnchor(stamp);
   return resolved.state === "unresolvable" ? stamp : resolved.path;
@@ -135,8 +117,11 @@ export function loadRelationshipContext(): string {
   }
 }
 
-/** Load session intelligence from compact synthesis state */
-function loadSessionIntelligence(): string {
+/**
+ * Off the startup context until the reflection stats are reliable enough to act on.
+ * @lintignore exercised directly by test/context-build.test.ts
+ */
+export function loadSessionIntelligence(): string {
   try {
     const p = resolve(paths.state(), "synthesis.json");
     if (!existsSync(p)) return "";
@@ -144,28 +129,6 @@ function loadSessionIntelligence(): string {
 
     const lines: string[] = ["## Session Intelligence"];
 
-    // Rating Trend
-    if (state.ratings?.count > 0) {
-      const r = state.ratings;
-      const lowNote = r.lowCount > 0 ? ` ${r.lowCount} low ratings.` : "";
-      lines.push(
-        "",
-        `**Rating trend:** ${r.avg}/10 avg (last 10: ${r.recentAvg}/10, ${r.trend}).${lowNote}`
-      );
-      if (r.trend === "declining") {
-        lines.push(
-          "→ Trend is declining. Be extra careful with assumptions. Confirm before acting."
-        );
-      } else if (r.trend === "improving") {
-        lines.push("→ Trend is improving. Maintain current approach.");
-      } else if (r.lowCount > 5) {
-        lines.push(
-          "→ Multiple low ratings. Slow down, verify before acting, ask when uncertain."
-        );
-      }
-    }
-
-    // Algorithm Performance
     if (state.algorithm?.reflectionCount > 0) {
       const a = state.algorithm;
       lines.push(
@@ -242,11 +205,8 @@ export function buildSystemReminder(
   const relationship = settings.isEnabled("relationship")
     ? loadRelationshipContext()
     : "";
-  const projectHistory = settings.isEnabled("projectHistory")
-    ? loadProjectHistoryContext()
-    : "";
   const activeProjects = settings.isEnabled("projects")
-    ? loadActiveProjectsContext(process.cwd(), lastSessionTitle)
+    ? loadActiveProjectsContext(sessionDir(), lastSessionTitle)
     : "";
   const failures =
     settings.isEnabled("failurePatterns") && !skipSemiStatic ? loadFailurePatterns() : "";
@@ -254,17 +214,14 @@ export function buildSystemReminder(
     !skipSemiStatic && settings.isEnabled("opinions") ? loadOpinionContext() : "";
   const selfModel =
     !skipSemiStatic && settings.isEnabled("selfModel") ? loadSelfModel() : "";
-  const intelligence = settings.isEnabled("sessionIntelligence")
-    ? loadSessionIntelligence()
-    : "";
   const handoff =
     !opts.withoutHandoff && settings.isEnabled("handoff")
       ? loadHandoffContext(sessionDir())
       : "";
   // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
-  const algoReview = loadAlgorithmReviewNudge();
-  const reflectNudge = loadReflectNudge();
-  const analyzeNudge = loadAnalyzeNudge();
+  const algoReview = oncePerDay("algorithm-review", loadAlgorithmReviewNudge());
+  const reflectNudge = oncePerDay("reflect", loadReflectNudge());
+  const analyzeNudge = oncePerDay("analyze", loadAnalyzeNudge());
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
@@ -274,10 +231,8 @@ export function buildSystemReminder(
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
-  if (intelligence) parts.push(intelligence);
   if (relationship) parts.push(relationship);
   if (activeProjects) parts.push(activeProjects);
-  if (projectHistory) parts.push(projectHistory);
   if (failures) parts.push(failures);
   if (parts.length === 0) return "";
 

package/src/hooks/lib/daily-nudge.ts

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+import { localDay } from "./wall-clock";
+
+type ShownOn = Record<string, string>;
+
+function shownPath(): string {
+  return resolve(ensureDir(paths.state()), "nudges-shown.json");
+}
+
+function readShownOn(): ShownOn {
+  try {
+    return JSON.parse(readFileSync(shownPath(), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * A reminder asks the user for something, so it belongs in the first session
+ * of the day, not in every session, resume and compaction after it.
+ */
+export function oncePerDay(
+  key: string,
+  reminder: string,
+  now: Date = new Date()
+): string {
+  if (!reminder) return "";
+  const today = localDay(now);
+  const shownOn = readShownOn();
+  if (shownOn[key] === today) return "";
+  writeFileSync(shownPath(), JSON.stringify({ ...shownOn, [key]: today }), "utf-8");
+  return reminder;
+}

package/src/hooks/lib/projects.ts

@@ -386,6 +386,27 @@ function formatAgo(ts: string): string {
 }
 
 const MAX_INLINE_BULLETS = 3;
+const FACTS_BUDGET = 600;
+
+function factLines(context: string): string[] {
+  return context
+    .split("\n")
+    .map((l) => l.replace(/^[-*]\s*/, "").trim())
+    .filter((l) => l && !l.startsWith("#"));
+}
+
+/** Whole facts in written order, so none is cut mid-sentence; the first always fits. */
+function factsLine(project: string, context: string): string {
+  const facts = factLines(context);
+  const shown = facts.slice(0, 1);
+  for (const fact of facts.slice(1)) {
+    if ([...shown, fact].join("; ").length > FACTS_BUDGET) break;
+    shown.push(fact);
+  }
+  const more =
+    shown.length < facts.length ? ` (more: \`pal cli project resume ${project}\`)` : "";
+  return `  Facts: ${shown.join("; ")}${more}`;
+}
 
 /**
  * Format the SessionStart "Active Projects" section.
@@ -425,13 +446,7 @@ export function loadActiveProjectsContext(
 
       if (isResolved) {
         lines.push(`- **${p.name}** (${statusPrefix}${ago})${stale}${here}`);
-        if (p.context) {
-          const bullets = p.context
-            .split("\n")
-            .map((l) => l.replace(/^[-*]\s*/, "").trim())
-            .filter(Boolean);
-          lines.push(`  Facts: ${bullets.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
-        }
+        if (p.context) lines.push(factsLine(p.name, p.context));
         if (p.goal) {
           const bullets = p.goal
             .split("\n")

package/src/hooks/lib/stop.ts

@@ -22,7 +22,12 @@ import { captureWorkSession } from "../handlers/work-session";
 import { spawnDetachedInference } from "./detached-inference";
 import { logDebug, logError } from "./log";
 import { assets, ensureDir, paths } from "./paths";
-import { extractContent, extractLastAssistant, parseMessages } from "./transcript";
+import {
+  extractContent,
+  extractLastAssistant,
+  parseMessages,
+  withFinalReply,
+} from "./transcript";
 
 interface RunStopHandlersOptions {
   lastAssistantMessage?: string;
@@ -31,11 +36,13 @@ interface RunStopHandlersOptions {
 
 /** Run all stop handlers with a transcript string */
 export async function runStopHandlers(
-  transcript: string,
+  fileTranscript: string,
   options: RunStopHandlersOptions = {}
 ): Promise<void> {
-  const messages = parseMessages(transcript);
-  if (messages.length < 2) return;
+  const fileMessages = parseMessages(fileTranscript);
+  if (fileMessages.length < 2) return;
+  const messages = withFinalReply(fileMessages, options.lastAssistantMessage);
+  const transcript = JSON.stringify(messages);
 
   logDebug("runStopHandlers", `Running handlers (${messages.length} messages)`);
 

package/src/hooks/lib/transcript.ts

@@ -89,6 +89,15 @@ export function extractLastAssistant(messages: Message[]): Message | undefined {
   return messages.filter((m) => m.role === "assistant").pop();
 }
 
+/** The agent hands its final reply to the Stop hook before that reply reaches the transcript file. */
+export function withFinalReply(messages: Message[], finalReply?: string): Message[] {
+  const reply = finalReply?.trim();
+  if (!reply) return messages;
+  const last = messages.at(-1);
+  if (last?.role === "assistant" && extractContent(last).includes(reply)) return messages;
+  return [...messages, { role: "assistant", content: reply }];
+}
+
 /** Get the last user message from a messages array */
 export function extractLastUser(messages: Message[]): Message | undefined {
   return messages.filter((m) => m.role === "user").pop();

package/src/hooks/lib/wall-clock.ts

@@ -51,6 +51,12 @@ export function wallClockLine(now: Date, configuredZone: string): string {
   return `Now: ${f.weekday} ${f.year}-${f.month}-${f.day} ${f.hour}:${f.minute} ${zone}`;
 }
 
+/** The calendar date in the principal's timezone, YYYY-MM-DD. */
+export function localDay(now: Date = new Date()): string {
+  const f = fieldsIn(now, zoneOrUtc(identity().principal.timezone));
+  return `${f.year}-${f.month}-${f.day}`;
+}
+
 export function getWallClockReminder(now: Date = new Date()): string | null {
   if (!isEnabled("wallClock")) return null;
   const line = wallClockLine(now, identity().principal.timezone);

package/src/hooks/lib/work-tracking.ts

@@ -145,6 +145,7 @@ interface ProjectHistoryEntry {
   title: string;
   summary: string;
   insights: string;
+  session?: string;
 }
 
 /**
@@ -160,11 +161,28 @@ function historyFileFor(cwd: string): string {
     : resolve(paths.unboundHistory(), `${defaultSlug(cwd)}.jsonl`);
 }
 
-/** Append a learning entry to the history file owning this cwd */
+function withoutSession(lines: string[], session: string): string[] {
+  return lines.filter((line) => {
+    try {
+      return (JSON.parse(line) as ProjectHistoryEntry).session !== session;
+    } catch {
+      return true;
+    }
+  });
+}
+
+/** A session is summarised again as it grows; its entry is replaced, not repeated. */
 export function appendProjectHistory(cwd: string, entry: ProjectHistoryEntry): void {
   const historyPath = historyFileFor(cwd);
   ensureDir(dirname(historyPath));
-  appendFileSync(historyPath, `${JSON.stringify(entry)}\n`, "utf-8");
+  const line = JSON.stringify(entry);
+  if (!entry.session || !existsSync(historyPath)) {
+    appendFileSync(historyPath, `${line}\n`, "utf-8");
+    return;
+  }
+  const lines = readFileSync(historyPath, "utf-8").split("\n").filter(Boolean);
+  const kept = withoutSession(lines, entry.session);
+  writeFileSync(historyPath, `${[...kept, line].join("\n")}\n`, "utf-8");
 }
 
 /** Read the session history for a given cwd */