portable-agent-layer 0.34.0 → 0.36.0

package/src/hooks/lib/context.ts

@@ -3,21 +3,21 @@
  * Used by LoadContext.ts (Claude Code) and the opencode plugin.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { parse } from "./frontmatter";
-import { readFailures, readLearnings } from "./learning-store";
+import { readLearnings } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { paths } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
 import { loadRecentNotes } from "./relationship";
+import { loadFailurePatterns, loadSynthesisRecommendations } from "./semi-static";
 import { readSessionNames } from "./session-names";
 import * as settings from "./settings";
 import { isSetupComplete, readSetupState, remainingSteps, STEP_ORDER } from "./setup";
 import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
-import { readProjectHistory, readSessions, recentSessions } from "./work-tracking";
+import { readProjectHistory, readSessions } from "./work-tracking";
 
 /** Load and concatenate loadAtStartup files */
 function loadStartupFiles(): string {
@@ -53,47 +53,6 @@ export function countSignals(filename: string): number {
   }
 }
 
-/** Load structured session history + project dashboard */
-export function loadActiveWork(): { text: string; summary: string | null } | null {
-  try {
-    const cwd = process.cwd();
-    const allRecent = recentSessions(48);
-
-    if (allRecent.length === 0) return null;
-
-    const lines: string[] = [];
-
-    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
-    const cwdSessions = allRecent.filter((s) => s.cwd === cwd);
-    const last = cwdSessions.length > 0 ? cwdSessions[cwdSessions.length - 1] : null;
-    const summary = last?.summary?.slice(0, 60) || null;
-
-    return {
-      text: lines.join("\n"),
-      summary: summary ? `"${summary}"` : null,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Format a timestamp as a human-readable "X ago" string */
-function formatAgo(ts: string): string {
-  const diff = Date.now() - new Date(ts).getTime();
-  const hours = Math.floor(diff / (1000 * 60 * 60));
-  if (hours < 1) return "just now";
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  return `${days}d ago`;
-}
-
 /** Load the N most recent session names (fallback for greeting) */
 export function loadRecentSessions(count: number): string[] {
   try {
@@ -140,7 +99,6 @@ function loadCachedCounts(): {
 /** Build the visible greeting lines for stderr */
 export function buildGreeting(): string[] {
   const counts = loadCachedCounts();
-  const work = loadActiveWork();
   const setupState = readSetupState();
   const setupIncomplete = setupState && !isSetupComplete(setupState);
 
@@ -157,10 +115,6 @@ export function buildGreeting(): string[] {
     );
   }
 
-  if (work?.summary) {
-    greeting.push(`📋 Previous: ${work.summary}`);
-  }
-
   // Show recent session names for quick context
   const recent = loadRecentSessions(3);
   if (recent.length > 0) {
@@ -217,78 +171,6 @@ export function loadSelfModel(): string {
   }
 }
 
-/** Load 5 most recent failure contexts as an "avoid" list */
-export function loadFailurePatterns(): string {
-  try {
-    const entries = readFailures(paths.failures(), 5);
-    if (entries.length === 0) return "";
-
-    const lines = entries.map((e) => {
-      const label = e.rating ? `[${e.rating}/10]` : "";
-      const text = e.principle || e.context;
-      return `- ${label} ${text}`.trim();
-    });
-
-    return ["## Lessons from Recent Failures — Apply These Now", ...lines].join("\n");
-  } catch {
-    return "";
-  }
-}
-
-/** Load recommendations from the most recent synthesis report */
-export function loadSynthesisRecommendations(): string {
-  try {
-    const synthDir = paths.synthesis();
-    if (!existsSync(synthDir)) return "";
-
-    // Find most recent month directory
-    const months = readdirSync(synthDir).sort().reverse();
-    for (const month of months) {
-      const monthDir = resolve(synthDir, month);
-      try {
-        const files = readdirSync(monthDir)
-          .filter((f) => f.endsWith(".md"))
-          .sort()
-          .reverse();
-        if (files.length === 0) continue;
-
-        const content = readFileSync(resolve(monthDir, files[0]), "utf-8");
-
-        // Extract recommendations section
-        const recMatch = content.match(/## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/);
-        if (!recMatch?.[1]?.trim()) continue;
-
-        const recs = recMatch[1]
-          .trim()
-          .split("\n")
-          .filter((l) => l.trim())
-          .slice(0, 4);
-
-        if (recs.length === 0) continue;
-
-        const { meta } = parse<{
-          period?: string;
-          average_rating?: string;
-        }>(content);
-        const period = meta.period || "";
-        const avgRating = meta.average_rating ? `${meta.average_rating}/10` : "";
-
-        const header = [
-          "## Pattern Synthesis",
-          period ? `*${period} — ${avgRating}*` : "",
-        ]
-          .filter(Boolean)
-          .join("\n");
-
-        return [header, ...recs].join("\n");
-      } catch {}
-    }
-    return "";
-  } catch {
-    return "";
-  }
-}
-
 /** Load signal trends as a formatted string */
 export function loadSignalTrends(): string {
   try {
@@ -322,7 +204,12 @@ export function loadRelationshipContext(): string {
   try {
     const notes = loadRecentNotes(2);
     if (!notes) return "";
-    return `## Recent Interaction Notes\n${notes}`;
+    // Strip O entries (opinions loaded natively via digest) and HTML comment lines
+    const filtered = notes
+      .split("\n")
+      .filter((l) => !/^\s*- O\(/.test(l) && !/^\s*<!--/.test(l))
+      .join("\n");
+    return capSection(`## Recent Interaction Notes\n${filtered}`, 1500);
   } catch {
     return "";
   }
@@ -337,11 +224,10 @@ export function loadSessionIntelligence(): string {
 
     const lines: string[] = ["## Session Intelligence"];
 
-    // Open Threads — project-specific first, then global
+    // Open Threads — project-specific only
     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("");
@@ -350,11 +236,10 @@ export function loadSessionIntelligence(): string {
           lines.push(`- ${t.title} (opened ${t.opened})`);
           if (t.context) lines.push(`  ${t.context}`);
         }
-        lines.push("→ These are directly relevant to your current work.");
+        lines.push(
+          "→ Continue this work or explicitly close it before starting something new."
+        );
       }
-      // Cross-project threads intentionally omitted — they were noise in 90%+ of sessions.
-      // To surface them on demand, add a `threads` slash-command or a flag in pal-settings.
-      void other;
     }
 
     // Rating Trend
@@ -403,7 +288,7 @@ export function loadSessionIntelligence(): string {
       }
     }
 
-    return lines.length > 1 ? lines.join("\n") : "";
+    return lines.length > 1 ? capSection(lines.join("\n"), 2000) : "";
   } catch {
     return "";
   }
@@ -434,17 +319,46 @@ export function loadHandoff(): string {
   }
 }
 
+/** Truncate text to maxChars at the last complete line boundary */
+function capSection(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const lines = text.split("\n");
+  const kept: string[] = [];
+  let total = 0;
+  for (const line of lines) {
+    const next = total + line.length + 1;
+    if (next > maxChars) break;
+    kept.push(line);
+    total = next;
+  }
+  return kept.join("\n");
+}
+
+/** Agent targets — determines which context sections are skipped due to native loading. */
+export type AgentTarget = "claude" | "opencode" | "cursor" | "copilot";
+
 /**
  * Build the <system-reminder> content for the AI.
  *
  * Static context (TELOS, setup prompt) lives in AGENTS.md / CLAUDE.md and is
  * loaded natively by Claude Code / opencode. This injects dynamic context only —
  * things that change per-session and can't live in a static file.
+ *
+ * opts.agent — agent target; Claude Code skips semi-static sections (self-model,
+ * wisdom, opinions) that load natively via @imports in CLAUDE.md.
  */
-export function buildSystemReminder(): string {
+export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string {
+  // Semi-static sections loaded natively via @imports (Claude Code) or
+  // instructions[] (opencode). Skip them from hook output for those agents.
+  const skipSemiStatic =
+    opts.agent === "claude" ||
+    opts.agent === "opencode" ||
+    opts.agent === "cursor" ||
+    opts.agent === "copilot";
+
   const startup = loadStartupFiles();
-  const work = settings.isEnabled("activeWork") ? loadActiveWork() : null;
-  const wisdom = settings.isEnabled("wisdom") ? loadWisdomContext() : "";
+  const wisdom =
+    !skipSemiStatic && settings.isEnabled("wisdom") ? loadWisdomContext() : "";
   const relationship = settings.isEnabled("relationship")
     ? loadRelationshipContext()
     : "";
@@ -456,10 +370,16 @@ export function buildSystemReminder(): string {
     ? loadActiveProjectsContext()
     : "";
   const trends = settings.isEnabled("signalTrends") ? loadSignalTrends() : "";
-  const failures = settings.isEnabled("failurePatterns") ? loadFailurePatterns() : "";
-  const synthesis = settings.isEnabled("synthesis") ? loadSynthesisRecommendations() : "";
-  const opinions = settings.isEnabled("opinions") ? loadOpinionContext() : "";
-  const selfModel = settings.isEnabled("selfModel") ? loadSelfModel() : "";
+  const failures =
+    settings.isEnabled("failurePatterns") && !skipSemiStatic ? loadFailurePatterns() : "";
+  const synthesis =
+    settings.isEnabled("synthesis") && !skipSemiStatic
+      ? loadSynthesisRecommendations()
+      : "";
+  const opinions =
+    !skipSemiStatic && settings.isEnabled("opinions") ? loadOpinionContext() : "";
+  const selfModel =
+    !skipSemiStatic && settings.isEnabled("selfModel") ? loadSelfModel() : "";
   const intelligence = settings.isEnabled("sessionIntelligence")
     ? loadSessionIntelligence()
     : "";
@@ -478,8 +398,6 @@ export function buildSystemReminder(): string {
   if (synthesis) parts.push(synthesis);
   if (trends) parts.push(trends);
   if (failures) parts.push(failures);
-  if (work) parts.push(work.text);
-
   if (parts.length === 0) return "";
 
   const now = new Date();

package/src/hooks/lib/relationship.ts

@@ -5,7 +5,7 @@
  * Notes live at memory/relationship/YYYY-MM/YYYY-MM-DD.md
  * W = world (facts about user's situation)
  * O = opinion (preference with confidence)
- * B = biographical (what the AI did this session, first-person)
+ * Session = what the AI did this session (first-person)
  *
  * Extraction is handled by the relationship handler via Haiku inference.
  * This lib provides storage and reading utilities only.
@@ -15,7 +15,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
 
-export type NoteType = "W" | "O" | "B";
+export type NoteType = "W" | "O" | "Session";
 
 export interface RelationshipNote {
   type: NoteType;
@@ -31,7 +31,7 @@ function dailyFilePath(date: Date): string {
   return resolve(monthDir, `${yyyy}-${mm}-${dd}.md`);
 }
 
-/** Check if a session already has notes in today's file */
+/** @deprecated No longer called — relationship notes are written in ALGORITHM LEARN phase */
 export function hasSessionNotes(sessionId: string): boolean {
   const filepath = dailyFilePath(new Date());
   if (!existsSync(filepath)) return false;

package/src/hooks/lib/security.ts

@@ -63,6 +63,8 @@ export const PROTECTED_PATHS: RegExp[] = [
   /^\/System\//,
   /\.ssh\/(?!config)/,
   /\.gnupg\//,
+  // Claude Code auto-memory — PAL owns memory; writes here indicate wrong system is being used
+  /\.claude\/projects\/[^/]+\/memory\//,
   // Derived from HOOK_MANAGED_FILES — scoped to managed roots only
   ...HOOK_MANAGED_FILES.map(
     (name) =>

package/src/hooks/lib/semi-static.ts

@@ -0,0 +1,186 @@
+/**
+ * Semi-static context source registry.
+ *
+ * One entry here = the only change needed to add a new source across all consumers:
+ * CLAUDE.md @imports, opencode instructions[], Cursor .mdc, Copilot .instructions.md,
+ * and the session-stop digest writer.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "./frontmatter";
+import { readFailures } from "./learning-store";
+import { loadOpinionContext } from "./opinions";
+import { palHome, paths } from "./paths";
+import { readFramePrinciples } from "./wisdom";
+
+/** A single semi-static context source — built at session stop, loaded natively at session start. */
+export interface SemiStaticSource {
+  /** Absolute path used in @imports (CLAUDE.md), instructions[] (opencode), and digest writes. */
+  readonly path: string;
+  /** When true, session-stop handler writes build result to path. */
+  readonly writesDigest: boolean;
+  /** Returns current content — builds fresh when writesDigest is true, reads the file otherwise. */
+  load(): string;
+  /** Slug for ~/.cursor/rules/pal-${slug}.mdc and ~/.copilot/instructions/pal-${slug}.instructions.md */
+  readonly slug: string;
+  /** Human-readable description for Cursor .mdc frontmatter. */
+  readonly description: string;
+}
+
+/** Returns the Cursor rules filename for a source. */
+export function cursorFilename(src: SemiStaticSource): string {
+  return `pal-${src.slug}.mdc`;
+}
+
+/** Returns the Copilot instructions filename for a source. */
+export function copilotFilename(src: SemiStaticSource): string {
+  return `pal-${src.slug}.instructions.md`;
+}
+
+function readFileSafe(path: string): string {
+  try {
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8").trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Build recommendations from the most recent synthesis report. */
+export function loadSynthesisRecommendations(): string {
+  try {
+    const synthDir = paths.synthesis();
+    if (!existsSync(synthDir)) return "";
+
+    const months = readdirSync(synthDir).sort().reverse();
+    for (const month of months) {
+      const monthDir = resolve(synthDir, month);
+      try {
+        const files = readdirSync(monthDir)
+          .filter((f) => f.endsWith(".md"))
+          .sort()
+          .reverse();
+        if (files.length === 0) continue;
+
+        const content = readFileSync(resolve(monthDir, files[0]), "utf-8");
+
+        const recMatch = content.match(/## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/);
+        if (!recMatch?.[1]?.trim()) continue;
+
+        const recs = recMatch[1]
+          .trim()
+          .split("\n")
+          .filter((l) => l.trim())
+          .slice(0, 4);
+
+        if (recs.length === 0) continue;
+
+        const { meta } = parse<{ period?: string; average_rating?: string }>(content);
+        const period = meta.period ?? "";
+        const avgRating = meta.average_rating ? `${meta.average_rating}/10` : "";
+
+        const header = [
+          "## Pattern Synthesis",
+          period ? `*${period} — ${avgRating}*` : "",
+        ]
+          .filter(Boolean)
+          .join("\n");
+
+        return [header, ...recs].join("\n");
+      } catch {
+        /* try next month */
+      }
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/** Build the 5 most recent failure lessons as an avoid-list. */
+export function loadFailurePatterns(): string {
+  try {
+    const entries = readFailures(paths.failures(), 5);
+    if (entries.length === 0) return "";
+
+    const lines = entries.map((e) => {
+      const label = e.rating ? `[${e.rating}/10]` : "";
+      const text = e.principle || e.context;
+      return `- ${label} ${text}`.trim();
+    });
+
+    return ["## Lessons from Recent Failures — Apply These Now", ...lines].join("\n");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * All semi-static context sources in load order.
+ * Adding one entry here is the only change needed to extend coverage to all consumers.
+ */
+export function getSemiStaticSources(): SemiStaticSource[] {
+  const memory = paths.memory();
+  const home = palHome();
+  return [
+    {
+      path: resolve(memory, "self-model", "current.md"),
+      writesDigest: false,
+      load: () => readFileSafe(resolve(memory, "self-model", "current.md")),
+      slug: "self-model",
+      description: "PAL self-model",
+    },
+    {
+      path: resolve(memory, "wisdom", "context.md"),
+      writesDigest: true,
+      load: () => {
+        try {
+          const principles = readFramePrinciples();
+          if (principles.length === 0) return "";
+          return ["## Crystallized Principles", ...principles.map((p) => `- ${p}`)].join(
+            "\n"
+          );
+        } catch {
+          return "";
+        }
+      },
+      slug: "wisdom",
+      description: "PAL wisdom",
+    },
+    {
+      path: resolve(memory, "relationship", "opinions-context.md"),
+      writesDigest: true,
+      load: () => {
+        try {
+          return loadOpinionContext();
+        } catch {
+          return "";
+        }
+      },
+      slug: "opinions",
+      description: "PAL opinions",
+    },
+    {
+      path: resolve(memory, "learning", "synthesis-digest.md"),
+      writesDigest: true,
+      load: loadSynthesisRecommendations,
+      slug: "synthesis",
+      description: "PAL pattern synthesis",
+    },
+    {
+      path: resolve(memory, "learning", "failures-digest.md"),
+      writesDigest: true,
+      load: loadFailurePatterns,
+      slug: "failures",
+      description: "PAL recent failure lessons",
+    },
+    {
+      path: resolve(home, "docs", "STEERING_RULES.md"),
+      writesDigest: false,
+      load: () => readFileSafe(resolve(home, "docs", "STEERING_RULES.md")),
+      slug: "steering",
+      description: "PAL steering rules",
+    },
+  ];
+}

package/src/hooks/lib/setup.ts

@@ -36,11 +36,6 @@ export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
       "What are your current goals? (short-term, medium-term, long-term) (~/.pal/telos/GOALS.md)",
     hint: "e.g. Ship v2 by Q3, learn Rust, get promoted to staff engineer",
   },
-  projects: {
-    file: "telos/PROJECTS.md",
-    question: "What projects are you currently working on? (~/.pal/telos/PROJECTS.md)",
-    hint: "e.g. PAL (active, high priority), personal blog (paused), side SaaS (early stage)",
-  },
   beliefs: {
     file: "telos/BELIEFS.md",
     question: "What principles or values guide your work? (~/.pal/telos/BELIEFS.md)",

package/src/hooks/lib/stop.ts

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { autoGraduate } from "../handlers/auto-graduate";
 import { autoBackup } from "../handlers/backup";
+import { writeContextDigests } from "../handlers/context-digests";
 import { notifyDesktop } from "../handlers/desktop-notify";
 import { captureFailure } from "../handlers/failure";
 import { projectTouch } from "../handlers/project-touch";
@@ -56,6 +57,7 @@ export async function runStopHandlers(
     autoGraduate(),
     projectTouch(options.lastAssistantMessage),
     notifyDesktop(options.sessionId),
+    Promise.resolve(writeContextDigests()),
   ]);
 
   const handlerNames = [
@@ -71,6 +73,7 @@ export async function runStopHandlers(
     "auto-graduate",
     "project-touch",
     "desktop-notify",
+    "context-digests",
   ];
   for (let i = 0; i < results.length; i++) {
     const r = results[i];

package/src/targets/claude/uninstall.ts

@@ -57,7 +57,7 @@ if (removedAgents.length > 0) {
 // --- Remove PAL system docs ---
 removePalDocs();
 
-// --- Remove AGENTS.md and CLAUDE.md symlink ---
+// --- Remove AGENTS.md and CLAUDE.md ---
 const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
 const claudeMd = resolve(CLAUDE_DIR, "CLAUDE.md");
 try {

package/src/targets/copilot/install.ts

@@ -1,11 +1,13 @@
 /**
  * PAL — Copilot target installer
  * Writes hooks to ~/.copilot/hooks/pal-hooks.json.
- * Copies skills and agents. Symlinks copilot-instructions.md to AGENTS.md.
+ * Copies skills and agents. Writes ~/.copilot/instructions/pal-*.instructions.md.
+ * Enables ~/.copilot/instructions in VS Code chat.instructionsFilesLocations.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { writeContextDigests } from "../../hooks/handlers/context-digests";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palPkg, platform } from "../../hooks/lib/paths";
 import {
@@ -16,7 +18,10 @@ import {
   generateSkillIndex,
   loadCopilotHooksTemplate,
   log,
+  readJson,
   scaffoldPalSettings,
+  vscodeSettingsFile,
+  writeJson,
 } from "../lib";
 
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
@@ -50,16 +55,42 @@ log.success(`Installed ${palDocsCount} PAL docs to ~/.pal/docs/`);
 // --- Scaffold PAL settings ---
 scaffoldPalSettings();
 
-// --- Generate AGENTS.md + copilot-instructions.md symlink ---
-// ensureSymlinks() inside regenerateIfNeeded() handles the symlink once ~/.copilot/ exists
+// --- Generate AGENTS.md ---
 regenerateIfNeeded();
-const instructionsPath = resolve(COPILOT_DIR, "copilot-instructions.md");
+log.success("Generated AGENTS.md");
+
+// --- Write ~/.copilot/instructions/pal-*.instructions.md ---
+mkdirSync(resolve(COPILOT_DIR, "instructions"), { recursive: true });
+writeContextDigests();
 log.success(
-  existsSync(instructionsPath)
-    ? "copilot-instructions.md symlink present"
-    : "Generated AGENTS.md (copilot-instructions.md symlink will be created on next session)"
+  "Written ~/.copilot/instructions/pal-self-model + pal-wisdom + pal-opinions.instructions.md"
 );
 
+// --- Enable ~/.copilot/instructions in VS Code settings ---
+const vsSettingsPath = vscodeSettingsFile();
+const manualHint =
+  'Add manually: { "chat.instructionsFilesLocations": { "~/.copilot/instructions": true } }';
+if (vsSettingsPath) {
+  try {
+    const settings = readJson<Record<string, unknown>>(vsSettingsPath, {});
+    const existing =
+      typeof settings["chat.instructionsFilesLocations"] === "object" &&
+      settings["chat.instructionsFilesLocations"] !== null
+        ? (settings["chat.instructionsFilesLocations"] as Record<string, unknown>)
+        : {};
+    settings["chat.instructionsFilesLocations"] = {
+      ...existing,
+      "~/.copilot/instructions": true,
+    };
+    writeJson(vsSettingsPath, settings);
+    log.success("Enabled ~/.copilot/instructions in VS Code settings");
+  } catch {
+    log.warn(`Could not update VS Code settings — ${manualHint}`);
+  }
+} else {
+  log.warn(`Could not detect VS Code settings path — ${manualHint}`);
+}
+
 log.success("Copilot installation complete");
 console.log("");
 log.info(`Skills: ${countSkills()}`);