portable-agent-layer 0.22.0 → 0.23.1

package/src/hooks/lib/context.ts

@@ -231,10 +231,11 @@ export function loadFailurePatterns(): string {
 
     const lines = entries.map((e) => {
       const label = e.rating ? `[${e.rating}/10]` : "";
-      return `- ${label} ${e.context}`.trim();
+      const text = e.principle || e.context;
+      return `- ${label} ${text}`.trim();
     });
 
-    return ["## Recent Failure Patterns (Avoid)", ...lines].join("\n");
+    return ["## Lessons from Recent Failures — Apply These Now", ...lines].join("\n");
   } catch {
     return "";
   }
@@ -333,6 +334,116 @@ export function loadRelationshipContext(): string {
   }
 }
 
+/** Load session intelligence from compact synthesis state */
+export function loadSessionIntelligence(): string {
+  try {
+    const p = resolve(paths.state(), "synthesis.json");
+    if (!existsSync(p)) return "";
+    const state = JSON.parse(readFileSync(p, "utf-8"));
+
+    const lines: string[] = ["## Session Intelligence"];
+
+    // Open Threads — project-specific first, then global
+    if (state.threads?.length > 0) {
+      const cwd = process.cwd();
+      const here = state.threads.filter((t: { cwd?: string }) => t.cwd === cwd);
+      const other = state.threads.filter((t: { cwd?: string }) => t.cwd !== cwd);
+
+      if (here.length > 0) {
+        lines.push("");
+        lines.push(`**Open threads — this project (${here.length}):**`);
+        for (const t of here) {
+          lines.push(`- ${t.title} (opened ${t.opened})`);
+          if (t.context) lines.push(`  ${t.context}`);
+        }
+        lines.push("→ These are directly relevant to your current work.");
+      }
+      if (other.length > 0) {
+        lines.push("");
+        lines.push(`**Open threads — other projects (${other.length}):**`);
+        for (const t of other) {
+          lines.push(`- ${t.title} (opened ${t.opened})`);
+        }
+      }
+    }
+
+    // Rating Trend
+    if (state.ratings?.count > 0) {
+      const r = state.ratings;
+      lines.push("");
+      lines.push(
+        `**Rating trend:** ${r.avg}/10 avg (last 10: ${r.recentAvg}/10, ${r.trend}).${r.lowCount > 0 ? ` ${r.lowCount} low ratings.` : ""}`
+      );
+      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("");
+      lines.push(
+        `**Algorithm:** ${a.reflectionCount} reflections, ${a.passRate}% criteria pass rate, ${a.avgSentiment}/10 sentiment.`
+      );
+      if (a.passRate < 80) {
+        lines.push(
+          "→ Criteria pass rate is low. Invest more time in OBSERVE and PLAN phases."
+        );
+      }
+      if (a.recentObservations?.length > 0) {
+        const cwd = process.cwd();
+        const relevant = a.recentObservations.filter(
+          (o: { cwd?: string }) => !o.cwd || o.cwd === cwd
+        );
+        if (relevant.length > 0) {
+          lines.push("Recent self-observations (this project):");
+          for (const o of relevant) {
+            lines.push(`- [${o.date}] ${o.task}: "${o.observation}"`);
+          }
+        }
+      }
+    }
+
+    return lines.length > 1 ? lines.join("\n") : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Load handoff state for the current project */
+export function loadHandoff(): string {
+  try {
+    const p = resolve(paths.state(), "last-handoff.json");
+    if (!existsSync(p)) return "";
+    const handoffs = JSON.parse(readFileSync(p, "utf-8"));
+    const cwd = process.cwd();
+    const entry = handoffs[cwd];
+    if (!entry?.handoff || entry.status !== "in-progress") return "";
+
+    const age = Date.now() - new Date(entry.timestamp).getTime();
+    if (age > 7 * 24 * 60 * 60 * 1000) return ""; // stale after 7 days
+
+    return [
+      "## Pick Up Where You Left Off",
+      `*Previous session: ${entry.title}*`,
+      "",
+      entry.handoff,
+      "→ Continue this work or explicitly close it before starting something new.",
+    ].join("\n");
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Build the <system-reminder> content for the AI.
  *
@@ -358,10 +469,16 @@ export function buildSystemReminder(): string {
     ? loadSynthesisRecommendations()
     : "";
   const opinions = isEnabled(settings, "opinions") ? loadOpinionContext() : "";
+  const intelligence = isEnabled(settings, "sessionIntelligence")
+    ? loadSessionIntelligence()
+    : "";
+  const handoff = isEnabled(settings, "handoff") ? loadHandoff() : "";
   const parts: string[] = [];
   if (startup) parts.push(startup);
+  if (handoff) parts.push(handoff);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
+  if (intelligence) parts.push(intelligence);
   if (relationship) parts.push(relationship);
   if (projectHistory) parts.push(projectHistory);
   if (digest) parts.push(digest);

package/src/hooks/lib/paths.ts

@@ -12,20 +12,12 @@ export function palPkg(): string {
 }
 
 /**
- * Root of the user's personal state (telos, memory, etc.).
- * In repo mode: same as palPkg() (the repo root).
- * In package mode: ~/.pal/ (or PAL_HOME override).
- *
- * Repo mode is detected by the presence of .palroot next to the package.
- * This file is not included in the npm package, so it only exists in cloned repos.
+ * Root of the user's personal state (telos, memory, docs, tools, skills).
+ * Always resolves to ~/.pal/ regardless of where the package lives.
+ * Power users who want memory/telos versioned in a repo can override via PAL_HOME.
  */
 export function palHome(): string {
-  if (process.env.PAL_HOME) return process.env.PAL_HOME;
-
-  const pkgRoot = palPkg();
-  if (existsSync(resolve(pkgRoot, ".palroot"))) return pkgRoot;
-
-  return resolve(homedir(), ".pal");
+  return process.env.PAL_HOME || resolve(homedir(), ".pal");
 }
 
 /** Ensure a directory exists, creating it recursively if needed */

package/src/hooks/lib/security.ts

@@ -47,8 +47,6 @@ export const HOOK_MANAGED_DIRS = [
   "memory/relationship",
   "memory/wisdom/state",
   "memory/projects",
-  ".agents/PAL/memory",
-  ".agents/PAL/telos",
 ];
 
 /** Escape a string for use in a RegExp */
@@ -63,8 +61,11 @@ export const PROTECTED_PATHS: RegExp[] = [
   /^\/System\//,
   /\.ssh\/(?!config)/,
   /\.gnupg\//,
-  // Derived from HOOK_MANAGED_FILES
-  ...HOOK_MANAGED_FILES.map((name) => new RegExp(`[/\\\\]${escapeRegExp(name)}$`)),
+  // Derived from HOOK_MANAGED_FILES — scoped to managed roots only
+  ...HOOK_MANAGED_FILES.map(
+    (name) =>
+      new RegExp(`[/\\\\]\\.(?:pal|claude|agents|cursor)[/\\\\].*${escapeRegExp(name)}$`)
+  ),
 ];
 
 /** Patterns that warrant a warning (logged but not blocked) */
@@ -75,38 +76,44 @@ export const WARN_COMMANDS: RegExp[] = [
   /truncate\s+table/i,
 ];
 
+/** Roots where managed files/dirs are protected (user state, not repo templates) */
+const MANAGED_ROOTS = [".pal/", ".claude/", ".agents/", ".config/opencode/", ".cursor/"];
+
+function isUnderManagedRoot(path: string): boolean {
+  const normalized = path.replace(/\\/g, "/");
+  return MANAGED_ROOTS.some(
+    (root) => normalized.includes(`/${root}`) || normalized.includes(`\\.${root}`)
+  );
+}
+
 /** Read-only commands allowed to reference protected files */
 const READ_ONLY_COMMANDS =
-  /^\s*(?:cat|head|tail|less|more|grep|rg|wc|diff|stat|file|ls|dir|git\s+(?:log|diff|blame|show|status)|bat)\b/;
+  /^\s*(?:cat|head|tail|less|more|grep|rg|wc|diff|stat|file|ls|dir|find|git\s+(?:log|diff|blame|show|status)|bat)\b/;
 
 /** Check a bash command against blocked patterns. Returns reason string or null. */
 export function checkBashCommand(cmd: string): string | null {
   for (const [pattern, reason] of BLOCKED_COMMANDS) {
     if (pattern.test(cmd)) return reason;
   }
-  // If command mentions a protected file, block unless it's read-only
+  // If command references a managed file in a managed root path, block unless read-only.
+  // The filename must appear IN the same path as the managed root (e.g. .pal/.../file.json).
+  const segments = cmd.split(/[|;&&]/).map((s) => s.trim());
   for (const name of HOOK_MANAGED_FILES) {
-    if (cmd.includes(name)) {
-      // Check each piped segment — if any segment is not read-only, block
-      const segments = cmd.split(/[|;&&]/).map((s) => s.trim());
-      const allReadOnly = segments
-        .filter((s) => s.includes(name))
-        .every((s) => READ_ONLY_COMMANDS.test(s));
-      if (!allReadOnly) {
-        return `${name} is managed automatically by hooks — do not edit directly`;
-      }
+    const pattern = new RegExp(
+      `\\.(?:pal|claude|agents|cursor|config/opencode)[/\\\\]\\S*${escapeRegExp(name)}`
+    );
+    const managed = segments.filter((s) => pattern.test(s));
+    if (managed.length > 0 && !managed.every((s) => READ_ONLY_COMMANDS.test(s))) {
+      return `${name} is managed automatically by hooks — do not edit directly`;
     }
   }
-  // If command mentions a hook-managed directory, block unless it's read-only
   for (const dir of HOOK_MANAGED_DIRS) {
-    if (cmd.includes(dir)) {
-      const segments = cmd.split(/[|;&&]/).map((s) => s.trim());
-      const allReadOnly = segments
-        .filter((s) => s.includes(dir))
-        .every((s) => READ_ONLY_COMMANDS.test(s));
-      if (!allReadOnly) {
-        return `${dir} is managed automatically by hooks — do not edit directly`;
-      }
+    const pattern = new RegExp(
+      `\\.(?:pal|claude|agents|cursor|config/opencode)[/\\\\]\\S*${escapeRegExp(dir)}`
+    );
+    const managed = segments.filter((s) => pattern.test(s));
+    if (managed.length > 0 && !managed.every((s) => READ_ONLY_COMMANDS.test(s))) {
+      return `${dir} is managed automatically by hooks — do not edit directly`;
     }
   }
   return null;
@@ -115,10 +122,14 @@ export function checkBashCommand(cmd: string): string | null {
 /** Check a file path against protected patterns. Returns a reason string or null. */
 export function checkFilePath(filePath: string): string | null {
   const normalized = filePath.replace(/\\/g, "/");
-  // Check hook-managed files first (more specific message)
-  const matchedFile = HOOK_MANAGED_FILES.find((name) => normalized.endsWith(`/${name}`));
-  if (matchedFile) {
-    return `${matchedFile} is managed automatically by hooks — do not edit directly`;
+  // Check hook-managed files — only under managed roots (not repo templates)
+  if (isUnderManagedRoot(normalized)) {
+    const matchedFile = HOOK_MANAGED_FILES.find((name) =>
+      normalized.endsWith(`/${name}`)
+    );
+    if (matchedFile) {
+      return `${matchedFile} is managed automatically by hooks — do not edit directly`;
+    }
   }
   // Check hook-managed directories
   const matchedDir = HOOK_MANAGED_DIRS.find((dir) => normalized.includes(`/${dir}/`));

package/src/hooks/lib/stop.ts

@@ -8,11 +8,12 @@ import { resolve } from "node:path";
 import { autoBackup } from "../handlers/backup";
 import { captureFailure } from "../handlers/failure";
 import { checkReflectTrigger } from "../handlers/reflect-trigger";
-import { captureRelationship } from "../handlers/relationship";
+import { captureSessionIntelligence } from "../handlers/session-intelligence";
+import { runSynthesis } from "../handlers/synthesis";
 import { resetTab } from "../handlers/tab";
 import { updateCounts } from "../handlers/update-counts";
-import { captureWorkLearning } from "../handlers/work-learning";
 import { captureWorkSession } from "../handlers/work-session";
+import { inference } from "./inference";
 import { logDebug, logError } from "./log";
 import { ensureDir, paths } from "./paths";
 import { extractContent, extractLastAssistant, parseMessages } from "./transcript";
@@ -39,23 +40,23 @@ export async function runStopHandlers(
   const results = await Promise.allSettled([
     captureWorkSession(transcript, options.sessionId),
     resetTab(),
-    captureRelationship(transcript, options.sessionId),
-    captureWorkLearning(transcript, options.sessionId),
+    captureSessionIntelligence(transcript, options.sessionId),
     checkPendingFailure(transcript),
     updateCounts(),
     autoBackup(),
     checkReflectTrigger(),
+    runSynthesis(),
   ]);
 
   const handlerNames = [
     "work-session",
     "tab",
-    "relationship",
-    "work-learning",
+    "session-intelligence",
     "pending-failure",
     "update-counts",
     "backup",
     "reflect-trigger",
+    "synthesis",
   ];
   for (let i = 0; i < results.length; i++) {
     const r = results[i];
@@ -137,15 +138,63 @@ async function checkPendingFailure(transcript: string): Promise<void> {
       rating: number;
       context: string;
       detailedContext?: string;
+      principle?: string;
       responsePreview?: string;
       userPreview?: string;
     };
     unlinkSync(pendingPath);
+
+    // Extract principle from full transcript if not already present
+    let { principle, detailedContext } = pending;
+    if (!principle) {
+      try {
+        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. The user rated it ${pending.rating}/10.
+
+Return JSON:
+{
+  "principle": "<one actionable rule the AI should follow, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>",
+  "detailed_context": "<what went wrong and why, 50-150 words>"
+}`,
+          user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
+          maxTokens: 400,
+          timeout: 10000,
+          jsonSchema: {
+            type: "object" as const,
+            properties: {
+              principle: { type: "string" as const },
+              detailed_context: { type: "string" as const },
+            },
+            required: ["principle", "detailed_context"],
+            additionalProperties: false,
+          },
+        });
+
+        if (result.success && result.output) {
+          const parsed = JSON.parse(result.output) as {
+            principle?: string;
+            detailed_context?: string;
+          };
+          principle = parsed.principle || undefined;
+          if (!detailedContext) detailedContext = parsed.detailed_context || undefined;
+        }
+      } catch {
+        /* graceful fallback — capture without principle */
+      }
+    }
+
     await captureFailure(
       pending.rating,
       pending.context,
       transcript,
-      pending.detailedContext
+      detailedContext,
+      principle
     );
   } catch {
     // Non-critical

package/src/hooks/lib/token-usage.ts

@@ -13,6 +13,7 @@ export type TokenCaller =
   | "failure"
   | "work-learning"
   | "session-name"
+  | "session-intelligence"
   | "relationship";
 
 interface TokenUsageEntry {

package/src/targets/claude/install.ts

@@ -58,7 +58,7 @@ copyAgents();
 
 // --- Copy PAL system docs ---
 const palDocsCount = copyPalDocs();
-log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
 
 // --- Scaffold PAL settings ---
 scaffoldPalSettings();

package/src/targets/cursor/install.ts

@@ -9,6 +9,7 @@ import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
+  copyAgentsForCursor,
   copyPalDocs,
   copySkills,
   countSkills,
@@ -47,9 +48,14 @@ const cursorSkillsDir = resolve(CURSOR_DIR, "skills");
 copySkills(cursorSkillsDir);
 generateSkillIndex();
 
+// --- Copy agents to ~/.cursor/agents/ ---
+const cursorAgentsDir = resolve(CURSOR_DIR, "agents");
+const agentCount = copyAgentsForCursor(cursorAgentsDir);
+if (agentCount > 0) log.success(`Installed ${agentCount} agents to ~/.cursor/agents/`);
+
 // --- Copy PAL system docs ---
 const palDocsCount = copyPalDocs();
-log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
+log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
 
 // --- Scaffold PAL settings ---
 scaffoldPalSettings();

package/src/targets/cursor/uninstall.ts

@@ -11,6 +11,7 @@ import {
   loadCursorHooksTemplate,
   log,
   readJson,
+  removeAgentsFromCursor,
   removePalDocs,
   removeSkills,
   unmergeCursorHooks,
@@ -46,6 +47,12 @@ if (removed.length > 0) {
   log.info("No PAL skills found");
 }
 
+// --- Remove PAL agents ---
+const removedAgents = removeAgentsFromCursor(resolve(CURSOR_DIR, "agents"));
+if (removedAgents.length > 0) {
+  log.success(`Removed ${removedAgents.length} agent(s): ${removedAgents.join(", ")}`);
+}
+
 // --- Remove PAL system docs ---
 removePalDocs();