portable-agent-layer 0.21.0 → 0.23.0

package/src/hooks/lib/context.ts

@@ -15,13 +15,7 @@ import { readSessionNames } from "./session-names";
 import { buildSetupPrompt, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
 import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
-import {
-  activeProjects,
-  readProjectHistory,
-  readSessions,
-  recentSessions,
-  staleProjects,
-} from "./work-tracking";
+import { readProjectHistory, readSessions, recentSessions } from "./work-tracking";
 
 interface PalSettings {
   loadAtStartup?: { files?: string[] };
@@ -83,44 +77,16 @@ export function loadActiveWork(): { text: string; summary: string | null } | nul
   try {
     const cwd = process.cwd();
     const allRecent = recentSessions(48);
-    const projects = activeProjects();
-    const stale = staleProjects(7);
 
-    if (allRecent.length === 0 && projects.length === 0) return null;
+    if (allRecent.length === 0) return null;
 
     const lines: string[] = [];
 
-    if (allRecent.length > 0) {
-      lines.push("## Recent Work (last 48h)");
-      for (const s of allRecent.slice(-10).reverse()) {
-        const ago = formatAgo(s.ts);
-        const here = s.cwd === cwd ? " *" : "";
-        lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
-      }
-    }
-
-    if (projects.length > 0) {
-      lines.push("", "### Active Projects");
-      for (const p of projects) {
-        const sessionCount = p.sessions.length;
-        const ago = formatAgo(p.updated);
-        lines.push(`- **${p.name}** (${sessionCount} sessions, last: ${ago})`);
-        if (p.nextSteps.length > 0) {
-          lines.push(`  Next: ${p.nextSteps[0]}`);
-        }
-        if (p.blockers.length > 0) {
-          lines.push(`  Blockers: ${p.blockers.join(", ")}`);
-        } else {
-          lines.push("  Blockers: None");
-        }
-      }
-    }
-
-    if (stale.length > 0) {
-      lines.push("", "### Stale Projects (>7d inactive)");
-      for (const p of stale) {
-        lines.push(`- **${p.name}** — last active ${formatAgo(p.updated)}`);
-      }
+    lines.push("## Recent Work (last 48h)");
+    for (const s of allRecent.slice(-10).reverse()) {
+      const ago = formatAgo(s.ts);
+      const here = s.cwd === cwd ? " *" : "";
+      lines.push(`- [${s.status}] ${s.name} — ${ago}${here}`);
     }
 
     // Summary from most recent session
@@ -367,6 +333,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.
  *
@@ -392,10 +468,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/graduation.ts

@@ -214,7 +214,7 @@ async function generateRecommendations(
   ratings: RatingsSummary | null
 ): Promise<string[]> {
   if (candidates.length === 0 && !ratings) return [];
-  if (!process.env.ANTHROPIC_API_KEY) {
+  if (!process.env.PAL_ANTHROPIC_API_KEY) {
     return candidates
       .slice(0, 3)
       .map(

package/src/hooks/lib/inference.ts

@@ -21,7 +21,7 @@ export interface InferenceResult {
 }
 
 export async function inference(opts: InferenceOptions): Promise<InferenceResult> {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
+  const apiKey = process.env.PAL_ANTHROPIC_API_KEY;
   if (!apiKey) return { success: false };
 
   const {

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/readme-sync.ts

@@ -58,12 +58,12 @@ function extractEnvVars(): string[] {
     }
   }
 
-  // ANTHROPIC_API_KEY from inference.ts
+  // PAL_ANTHROPIC_API_KEY from inference.ts
   const inferenceFile = resolve(pkg, "src", "hooks", "lib", "inference.ts");
   if (existsSync(inferenceFile)) {
     const content = readFileSync(inferenceFile, "utf-8");
-    if (content.includes("ANTHROPIC_API_KEY")) {
-      vars.add("ANTHROPIC_API_KEY");
+    if (content.includes("PAL_ANTHROPIC_API_KEY")) {
+      vars.add("PAL_ANTHROPIC_API_KEY");
     }
   }
 

package/src/hooks/lib/security.ts

@@ -34,6 +34,8 @@ export const HOOK_MANAGED_FILES = [
   "debug.log.prev",
   "opinions.json",
   "pal-settings.json",
+  "skill-index.json",
+  "algorithm-reflections.jsonl",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */
@@ -45,7 +47,6 @@ export const HOOK_MANAGED_DIRS = [
   "memory/relationship",
   "memory/wisdom/state",
   "memory/projects",
-  ".agents/PAL",
 ];
 
 /** Escape a string for use in a RegExp */
@@ -60,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) */
@@ -72,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;
@@ -112,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,10 +8,10 @@ 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 { logDebug, logError } from "./log";
 import { ensureDir, paths } from "./paths";
@@ -39,23 +39,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];

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/hooks/lib/work-tracking.ts

@@ -1,12 +1,11 @@
 /**
- * Structured work tracking: session history + persistent projects.
+ * Structured work tracking: session history + per-project history.
  * Used by both Claude Code (StopOrchestrator) and opencode (plugin).
  */
 
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
-import { now } from "./time";
 
 // ── Session Records ──────────────────────────────────────────────
 
@@ -179,52 +178,3 @@ export function readProjectHistory(cwd: string, limit = 15): ProjectHistoryEntry
     return [];
   }
 }
-
-// ── Persistent Projects ──────────────────────────────────────────
-
-export interface Project {
-  id: string;
-  name: string;
-  created: string;
-  updated: string;
-  status: "active" | "paused" | "completed";
-  objectives: string[];
-  decisions: string[];
-  completed: string[];
-  blockers: string[];
-  nextSteps: string[];
-  handoff: string;
-  sessions: string[];
-}
-
-function projectsPath(): string {
-  return resolve(ensureDir(paths.state()), "projects.json");
-}
-
-export function readProjects(): Record<string, Project> {
-  const p = projectsPath();
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-export function writeProject(project: Project): void {
-  const projects = readProjects();
-  project.updated = now();
-  projects[project.id] = project;
-  writeFileSync(projectsPath(), JSON.stringify(projects, null, 2), "utf-8");
-}
-
-export function activeProjects(): Project[] {
-  return Object.values(readProjects()).filter((p) => p.status === "active");
-}
-
-export function staleProjects(days = 7): Project[] {
-  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
-  return Object.values(readProjects()).filter(
-    (p) => p.status === "active" && new Date(p.updated).getTime() < cutoff
-  );
-}

package/src/targets/claude/install.ts

@@ -15,6 +15,7 @@ import {
   countAgents,
   countMd,
   countSkills,
+  generateSkillIndex,
   loadSettingsTemplate,
   log,
   mergeSettings,
@@ -50,13 +51,14 @@ log.success("Merged PAL settings into settings.json");
 // --- Copy skills ---
 const skillsDir = resolve(CLAUDE_DIR, "skills");
 copySkills(skillsDir);
+generateSkillIndex();
 
 // --- Copy agents ---
 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,9 +9,11 @@ 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,
+  generateSkillIndex,
   loadCursorHooksTemplate,
   log,
   mergeCursorHooks,
@@ -44,10 +46,16 @@ log.success("Merged PAL hooks into hooks.json");
 // --- Symlink skills to ~/.cursor/skills/ ---
 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();