portable-agent-layer 0.35.0 → 0.37.0

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

@@ -0,0 +1,188 @@
+/**
+ * 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. */
+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 = new RegExp(
+          /## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/
+        ).exec(content);
+        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/session-names.ts

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { paths } from "./paths";
 
-export interface SessionNames {
+interface SessionNames {
   [sessionId: string]: string;
 }
 

package/src/hooks/lib/settings.ts

@@ -11,7 +11,7 @@ import { paths } from "./paths";
 
 // ── Types ──
 
-export interface Identity {
+interface Identity {
   ai: { name: string; fullName: string; displayName: string; catchphrase: string };
   principal: { name: string; timezone: string };
 }

package/src/hooks/lib/setup.ts

@@ -5,23 +5,15 @@
  * The AI is instructed to mark steps done after writing each file.
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { ensureDir, palHome, paths } from "./paths";
+import { existsSync, readFileSync } from "node:fs";
 
-export interface SetupStep {
+interface SetupStep {
   done: boolean;
   file: string;
   question: string;
   hint: string;
 }
 
-export interface SetupState {
-  version: number;
-  completed: boolean;
-  steps: Record<string, SetupStep>;
-}
-
 /** Ordered setup steps — defines the wizard flow */
 export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
   mission: {
@@ -36,11 +28,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)",
@@ -55,10 +42,6 @@ export const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
 
 export const STEP_ORDER = Object.keys(SETUP_STEPS);
 
-function setupPath(): string {
-  return resolve(ensureDir(paths.state()), "setup.json");
-}
-
 /** Check if a TELOS file has real content (not just template scaffolding) */
 export function hasRealContent(filePath: string): boolean {
   if (!existsSync(filePath)) return false;
@@ -75,49 +58,3 @@ export function hasRealContent(filePath: string): boolean {
     return false;
   }
 }
-
-/** Create initial setup state, auto-detecting already-populated TELOS files */
-export function createInitialState(): SetupState {
-  const steps: Record<string, SetupStep> = {};
-  for (const [key, def] of Object.entries(SETUP_STEPS)) {
-    const populated = hasRealContent(resolve(palHome(), def.file));
-    steps[key] = { done: populated, ...def };
-  }
-  const allDone = Object.values(steps).every((s) => s.done);
-  return { version: 1, completed: allDone, steps };
-}
-
-/** Read setup state, or return null if no setup.json exists */
-export function readSetupState(): SetupState | null {
-  const p = setupPath();
-  if (!existsSync(p)) return null;
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-/** Write setup state to disk */
-export function writeSetupState(state: SetupState): void {
-  writeFileSync(setupPath(), `${JSON.stringify(state, null, 2)}\n`);
-}
-
-/** Seed setup.json if it doesn't exist yet. Returns the state. */
-export function ensureSetupState(): SetupState {
-  const existing = readSetupState();
-  if (existing) return existing;
-  const fresh = createInitialState();
-  writeSetupState(fresh);
-  return fresh;
-}
-
-/** Get the list of remaining (not done) step keys, in order */
-export function remainingSteps(state: SetupState): string[] {
-  return STEP_ORDER.filter((k) => !state.steps[k]?.done);
-}
-
-/** Check if setup is fully completed */
-export function isSetupComplete(state: SetupState): boolean {
-  return state.completed;
-}

package/src/hooks/lib/signals.ts

@@ -3,14 +3,14 @@ import { resolve } from "node:path";
 import { paths } from "./paths";
 import { now } from "./time";
 
-export interface Signal {
+interface Signal {
   ts: string;
   type: string;
   [key: string]: unknown;
 }
 
 /** Append a signal to a JSONL file in the signals directory */
-export function emitSignal(
+function emitSignal(
   filename: string,
   data: { type: string; [key: string]: unknown }
 ): void {

package/src/hooks/lib/stdin.ts

@@ -1,5 +1,5 @@
 /** Read all of stdin as a string */
-export async function readStdin(): Promise<string> {
+async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
   for await (const chunk of Bun.stdin.stream()) {
     chunks.push(Buffer.from(chunk));

package/src/hooks/lib/stop.ts

@@ -3,12 +3,15 @@
  * Used by StopOrchestrator.ts (Claude Code) and opencode plugin.
  */
 
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile, unlink } from "node:fs/promises";
 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 { persistLastExchange } from "../handlers/persist-last-exchange";
 import { projectTouch } from "../handlers/project-touch";
 import { checkReflectTrigger } from "../handlers/reflect-trigger";
 import { checkSelfModelTrigger } from "../handlers/self-model-trigger";
@@ -22,7 +25,7 @@ import { logDebug, logError } from "./log";
 import { ensureDir, paths } from "./paths";
 import { extractContent, extractLastAssistant, parseMessages } from "./transcript";
 
-export interface RunStopHandlersOptions {
+interface RunStopHandlersOptions {
   lastAssistantMessage?: string;
   sessionId?: string;
 }
@@ -40,6 +43,9 @@ export async function runStopHandlers(
   // Cache last assistant response (session-scoped)
   cacheLastResponse(messages, options.lastAssistantMessage, options.sessionId);
 
+  // Always persist last exchange — drives CompactRecover + "Pick Up Where You Left Off"
+  if (options.sessionId) persistLastExchange(messages, options.sessionId);
+
   // Run all handlers concurrently. Auto-graduate is idempotent (24h TTL +
   // state-dedup + content-dedup) so it's safe to fire on every Stop.
   // project-touch only fires when cwd resolves to an active registered project.
@@ -56,6 +62,7 @@ export async function runStopHandlers(
     autoGraduate(),
     projectTouch(options.lastAssistantMessage),
     notifyDesktop(options.sessionId),
+    Promise.resolve(writeContextDigests()),
   ]);
 
   const handlerNames = [
@@ -71,6 +78,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];
@@ -148,15 +156,16 @@ async function checkPendingFailure(transcript: string): Promise<void> {
   if (!existsSync(pendingPath)) return;
 
   try {
-    const pending = JSON.parse(readFileSync(pendingPath, "utf-8")) as {
+    const pending = JSON.parse(await readFile(pendingPath, "utf-8")) as {
       rating: number;
       context: string;
       detailedContext?: string;
       principle?: string;
       responsePreview?: string;
       userPreview?: string;
+      cwd?: string;
     };
-    unlinkSync(pendingPath);
+    await unlink(pendingPath);
 
     // Extract principle from full transcript if not already present
     let { principle, detailedContext } = pending;
@@ -196,7 +205,7 @@ Return JSON:
             detailed_context?: string;
           };
           principle = parsed.principle || undefined;
-          if (!detailedContext) detailedContext = parsed.detailed_context || undefined;
+          detailedContext ??= parsed.detailed_context || undefined;
         }
       } catch {
         /* graceful fallback — capture without principle */
@@ -208,7 +217,8 @@ Return JSON:
       pending.context,
       transcript,
       detailedContext,
-      principle
+      principle,
+      pending.cwd
     );
   } catch {
     // Non-critical

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

@@ -8,10 +8,9 @@ import { resolve } from "node:path";
 import { HAIKU_MODEL } from "./models";
 import { ensureDir, paths } from "./paths";
 
-export type TokenCaller =
+type TokenCaller =
   | "rating"
   | "failure"
-  | "work-learning"
   | "session-name"
   | "session-intelligence"
   | "relationship"

package/src/hooks/lib/transcript.ts

@@ -5,7 +5,7 @@
 
 import { readFileSync } from "node:fs";
 
-export interface Message {
+interface Message {
   role: string;
   content: string | unknown;
 }

package/src/hooks/lib/wisdom.ts

@@ -63,13 +63,13 @@ function existingCrystalPrinciples(content: string): string[] {
     if (m[1]) out.push(m[1].trim());
   }
   for (const line of content.split("\n")) {
-    const m = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*\d+%\]\s*$/);
+    const m = new RegExp(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*\d+%\]\s*$/).exec(line);
     if (m?.[1]) out.push(m[1].trim());
   }
   return out;
 }
 
-export interface PromoteCrystalResult {
+interface PromoteCrystalResult {
   domain: string;
   principle: string;
   confidence: number;
@@ -123,7 +123,7 @@ export function promoteCrystal(
   return { domain, principle, confidence, framePath, skipped: null };
 }
 
-export interface FrameDoc {
+interface FrameDoc {
   domain: string;
   principle: string;
   body: string;
@@ -153,7 +153,7 @@ export function readFramesForRetrieval(): FrameDoc[] {
     }
 
     for (const line of content.split("\n")) {
-      const m = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/);
+      const m = new RegExp(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/).exec(line);
       if (!m) continue;
       const name = m[1]?.trim();
       const pct = parseInt(m[2] ?? "", 10);
@@ -188,7 +188,7 @@ export function readFramePrinciples(): string[] {
 
     // legacy fallback: bullet lines "- X [CRYSTAL: N%]"
     for (const line of content.split("\n")) {
-      const match = line.match(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/);
+      const match = new RegExp(/^\s*-\s*(.+?)\s*\[CRYSTAL:\s*(\d+)%\]\s*$/).exec(line);
       if (!match) continue;
       const name = match[1]?.trim();
       const pct = parseInt(match[2] ?? "", 10);

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

@@ -29,7 +29,7 @@ function sessionsPath(): string {
   return resolve(ensureDir(paths.state()), "sessions.json");
 }
 
-export function readSessions(): SessionRecord[] {
+function readSessions(): SessionRecord[] {
   const p = sessionsPath();
   if (!existsSync(p)) return [];
   try {
@@ -54,12 +54,6 @@ export function writeSession(record: SessionRecord): void {
   writeFileSync(sessionsPath(), JSON.stringify(pruned, null, 2), "utf-8");
 }
 
-/** Filter sessions within the last N hours */
-export function recentSessions(hours: number): SessionRecord[] {
-  const cutoff = Date.now() - hours * 60 * 60 * 1000;
-  return readSessions().filter((s) => new Date(s.ts).getTime() > cutoff);
-}
-
 /** Detect session completion status from last assistant message */
 export function detectStatus(lastAssistant: string): SessionRecord["status"] {
   const completionSignals =
@@ -118,15 +112,15 @@ function cleanForHandoff(text: string): string {
 /** Extract handoff notes from last assistant message */
 export function extractHandoff(lastAssistant: string): string {
   // Look for explicit next-steps / TODO / remaining sections
-  const sectionMatch = lastAssistant.match(
+  const sectionMatch = new RegExp(
     /(?:next steps?|todo|remaining|what's left|still need|want me to)[:\s]*\n([\s\S]{10,300}?)(?:\n\n|\n(?=[A-Z#]))/i
-  );
+  ).exec(lastAssistant);
   if (sectionMatch) return cleanForHandoff(sectionMatch[1]);
 
   // Look for closing question/offer (common assistant pattern)
-  const closingMatch = lastAssistant.match(
+  const closingMatch = new RegExp(
     /(?:want (?:me to|to)|shall I|should I|ready to|anything else|let me know)[^\n]*$/im
-  );
+  ).exec(lastAssistant);
 
   const cleaned = cleanForHandoff(lastAssistant);
 
@@ -144,7 +138,7 @@ export function extractHandoff(lastAssistant: string): string {
 
 // ── Per-Project History ──────────────────────────────────────────
 
-export interface ProjectHistoryEntry {
+interface ProjectHistoryEntry {
   date: string;
   title: string;
   summary: string;
@@ -152,8 +146,8 @@ export interface ProjectHistoryEntry {
 }
 
 /** Convert a cwd path to a filesystem-safe slug (last directory segment) */
-export function cwdToSlug(cwd: string): string {
-  const normalized = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+function cwdToSlug(cwd: string): string {
+  const normalized = cwd.replaceAll("\\", "/").replace(/\/+$/, "");
   return normalized.split("/").pop() || "unknown";
 }
 

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/codex/install.ts

@@ -0,0 +1,95 @@
+/**
+ * PAL — Codex target installer
+ * Merges PAL hooks into ~/.codex/hooks.json (never overwrites user hooks).
+ * Symlinks skills. Ensures AGENTS.md symlink via regenerateIfNeeded().
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
+import { assets, palPkg, platform } from "../../hooks/lib/paths";
+import {
+  copySkills,
+  countSkills,
+  generateSkillIndex,
+  loadCodexHooksTemplate,
+  log,
+  mergeCodexHooks,
+  readJson,
+  scaffoldPalSettings,
+  writeJson,
+} from "../lib";
+
+/**
+ * Ensure `features.hooks = true` in config.toml without touching other content.
+ * Appends the setting if missing; skips if already present.
+ */
+function enableCodexHooks(configPath: string): void {
+  let content = "";
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, "utf-8");
+    // Already enabled — nothing to do
+    if (/^\s*hooks\s*=\s*true/m.test(content)) {
+      log.info("Codex hooks already enabled in config.toml");
+      return;
+    }
+    // [features] section exists but no hooks line — insert after the header
+    if (/^\[features\]/m.test(content)) {
+      content = content.replace(/(\[features\][^\n]*\n)/, "$1hooks = true\n");
+      writeFileSync(configPath, content, "utf-8");
+      log.success("Added hooks = true to existing [features] section in config.toml");
+      return;
+    }
+  }
+  // No config.toml, or no [features] section — append the block
+  const block = `${content.endsWith("\n") || content === "" ? "" : "\n"}\n[features]\nhooks = true\n`;
+  writeFileSync(configPath, content + block, "utf-8");
+  log.success("Enabled hooks = true in ~/.codex/config.toml");
+}
+
+const PKG_ROOT = palPkg().replaceAll("\\", "/");
+const CODEX_DIR = platform.codexDir();
+const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+
+// --- Ensure ~/.codex/ exists ---
+mkdirSync(CODEX_DIR, { recursive: true });
+
+// --- Merge hooks ---
+if (existsSync(HOOKS_FILE)) {
+  copyFileSync(HOOKS_FILE, `${HOOKS_FILE}.bak.${Date.now()}`);
+  log.info("Backed up hooks.json");
+}
+
+const template = loadCodexHooksTemplate(assets.codexHooksTemplate(), PKG_ROOT);
+const existing = readJson<Record<string, unknown>>(HOOKS_FILE, {});
+const merged = mergeCodexHooks(existing, template);
+
+writeJson(HOOKS_FILE, merged);
+log.success("Merged PAL hooks into ~/.codex/hooks.json");
+
+// --- Symlink skills to ~/.codex/skills/ ---
+const codexSkillsDir = resolve(CODEX_DIR, "skills");
+copySkills(codexSkillsDir);
+generateSkillIndex();
+
+// --- Scaffold PAL settings ---
+scaffoldPalSettings();
+
+// --- Generate / verify AGENTS.md symlink ---
+regenerateIfNeeded();
+log.success("Ensured AGENTS.md symlink at ~/.codex/AGENTS.md");
+
+// --- Enable hooks in config.toml ---
+const CONFIG_FILE = resolve(CODEX_DIR, "config.toml");
+enableCodexHooks(CONFIG_FILE);
+
+log.success("Codex installation complete");
+console.log("");
+log.info(`Skills: ${countSkills()}`);
+log.info(`Hooks: ${HOOKS_FILE}`);