portable-agent-layer 0.6.1 → 0.7.0

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

@@ -0,0 +1,265 @@
+/**
+ * Learning Store — single collection layer for reading failures and session learnings.
+ *
+ * Both context.ts (session injection) and graduation.ts (pattern detection) read from
+ * the same directories. This module provides a shared, deduplicated API for both.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parse } from "./frontmatter";
+
+// ── Types ──
+
+export interface FailureEntry {
+  slug: string;
+  rating: number;
+  context: string;
+  principle: string;
+  date: string;
+  ts: string;
+}
+
+export interface LearningEntry {
+  filename: string;
+  title: string;
+  category: string;
+  principle: string;
+  date: string;
+  insights: string;
+}
+
+// ── Shared Directory Walker ──
+
+/**
+ * Walk year/month directory structure in reverse chronological order.
+ * Yields entries from the innermost directory (month level).
+ */
+function* walkMonthDirs(baseDir: string): Generator<{ monthDir: string }> {
+  if (!existsSync(baseDir)) return;
+  try {
+    for (const year of readdirSync(baseDir).sort().reverse()) {
+      const yearDir = resolve(baseDir, year);
+      try {
+        for (const month of readdirSync(yearDir).sort().reverse()) {
+          yield { monthDir: resolve(yearDir, month) };
+        }
+      } catch {
+        /* skip invalid year dirs */
+      }
+    }
+  } catch {
+    /* non-critical */
+  }
+}
+
+// ── Failures ──
+
+export function readFailures(baseDir: string, limit?: number): FailureEntry[] {
+  const entries: FailureEntry[] = [];
+
+  for (const { monthDir } of walkMonthDirs(baseDir)) {
+    try {
+      for (const slug of readdirSync(monthDir).sort().reverse()) {
+        const capturePath = resolve(monthDir, slug, "capture.md");
+        if (!existsSync(capturePath)) continue;
+
+        try {
+          const content = readFileSync(capturePath, "utf-8");
+          const { meta } = parse<{
+            rating?: number;
+            context?: string;
+            principle?: string;
+            date?: string;
+            ts?: string;
+            slug?: string;
+          }>(content);
+
+          if (!meta.context) continue;
+
+          entries.push({
+            slug: meta.slug || slug,
+            rating: meta.rating ?? 0,
+            context: meta.context,
+            principle: meta.principle || "",
+            date: meta.date || (meta.ts ? String(meta.ts).slice(0, 10) : ""),
+            ts: meta.ts ? String(meta.ts) : "",
+          });
+
+          if (limit && entries.length >= limit) return entries;
+        } catch {
+          /* skip malformed */
+        }
+      }
+    } catch {
+      /* skip invalid month dirs */
+    }
+  }
+
+  return entries;
+}
+
+// ── Learnings ──
+
+export function readLearnings(baseDir: string, limit?: number): LearningEntry[] {
+  const entries: LearningEntry[] = [];
+
+  for (const { monthDir } of walkMonthDirs(baseDir)) {
+    try {
+      const files = readdirSync(monthDir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .reverse();
+
+      for (const file of files) {
+        try {
+          const content = readFileSync(resolve(monthDir, file), "utf-8");
+          const { meta, body } = parse<{
+            title?: string;
+            category?: string;
+            principle?: string;
+            date?: string;
+          }>(content);
+
+          if (!meta.title) continue;
+
+          const insightsMatch = body.match(/## Insights\n([\s\S]*?)(?=\n##|$)/);
+
+          entries.push({
+            filename: file,
+            title: meta.title,
+            category: meta.category || "algorithm",
+            principle: meta.principle || "",
+            date: meta.date || "",
+            insights: insightsMatch?.[1]?.trim() || "",
+          });
+
+          if (limit && entries.length >= limit) return entries;
+        } catch {
+          /* skip malformed */
+        }
+      }
+    } catch {
+      /* skip invalid month dirs */
+    }
+  }
+
+  return entries;
+}
+
+// ── Text Similarity (Jaccard on keywords) ──
+
+const STOP_WORDS = new Set([
+  "the",
+  "a",
+  "an",
+  "is",
+  "was",
+  "are",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "shall",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "and",
+  "but",
+  "or",
+  "nor",
+  "not",
+  "no",
+  "so",
+  "if",
+  "then",
+  "than",
+  "that",
+  "this",
+  "it",
+  "its",
+  "i",
+  "you",
+  "he",
+  "she",
+  "we",
+  "they",
+  "my",
+  "your",
+  "his",
+  "her",
+  "our",
+  "their",
+  "what",
+  "which",
+  "who",
+  "when",
+  "where",
+  "how",
+  "all",
+  "each",
+  "both",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "up",
+  "out",
+  "about",
+  "just",
+  "also",
+  "very",
+  "too",
+  "only",
+  "own",
+]);
+
+export function extractKeywords(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 2 && !STOP_WORDS.has(w))
+  );
+}
+
+export function similarity(a: string, b: string): number {
+  const ka = extractKeywords(a);
+  const kb = extractKeywords(b);
+  if (ka.size === 0 || kb.size === 0) return 0;
+
+  let intersection = 0;
+  for (const w of ka) {
+    if (kb.has(w)) intersection++;
+  }
+  const union = new Set([...ka, ...kb]).size;
+  return union > 0 ? intersection / union : 0;
+}

package/src/hooks/lib/security.ts

@@ -30,6 +30,7 @@ export const HOOK_MANAGED_FILES = [
   "pending-failure.json",
   "token-usage.jsonl",
   "graduated.json",
+  "update-available.json",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */

package/src/hooks/lib/stop.ts

@@ -8,7 +8,6 @@ import { resolve } from "node:path";
 import { autoBackup } from "../handlers/backup";
 import { captureFailure } from "../handlers/failure";
 import { captureRelationship } from "../handlers/relationship";
-import { checkSynthesisTrigger } from "../handlers/synthesis";
 import { resetTab } from "../handlers/tab";
 import { updateCounts } from "../handlers/update-counts";
 import { captureWorkLearning } from "../handlers/work-learning";
@@ -44,7 +43,6 @@ export async function runStopHandlers(
     checkPendingFailure(transcript),
     updateCounts(),
     autoBackup(),
-    checkSynthesisTrigger(),
   ]);
 
   const handlerNames = [
@@ -55,7 +53,6 @@ export async function runStopHandlers(
     "pending-failure",
     "update-counts",
     "backup",
-    "synthesis",
   ];
   for (let i = 0; i < results.length; i++) {
     const r = results[i];
@@ -145,9 +142,7 @@ async function checkPendingFailure(transcript: string): Promise<void> {
       pending.rating,
       pending.context,
       transcript,
-      pending.detailedContext,
-      pending.responsePreview,
-      pending.userPreview
+      pending.detailedContext
     );
   } catch {
     // Non-critical

package/src/tools/analyze.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+/**
+ * Unified Learning Analysis — graduation patterns + ratings summary.
+ *
+ * Reads failures and session learnings, finds recurring patterns,
+ * summarizes ratings, and generates recommendations.
+ *
+ * Usage: bun run tool:analyze
+ */
+
+import { parseArgs } from "node:util";
+import { analyze } from "../hooks/lib/graduation";
+
+const { values } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    help: { type: "boolean", short: "h" },
+    actionable: { type: "boolean", short: "a" },
+  },
+});
+
+if (values.help) {
+  console.log(`
+  PAL Learning Analysis — unified graduation + ratings report
+
+  Reads all captured failures (rating ≤3) and session learnings,
+  groups recurring patterns via Jaccard similarity on context text,
+  and summarizes rating trends.
+
+  Sections:
+    Ratings       Overall average, low/high counts
+    Graduation    Patterns with 3+ occurrences → ready to crystallize
+    Emerging      Patterns with 2 occurrences → one more to graduate
+
+  Flags:
+    --actionable, -a  Generate actionable recommendations via Haiku inference
+
+  To crystallize a graduated pattern, add it to the target wisdom frame:
+    - Your principle here [CRYSTAL: 85%]
+
+  Usage: bun run tool:analyze [--actionable] [--help]
+`);
+  process.exit(0);
+}
+
+const result = await analyze({ actionable: values.actionable });
+
+const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
+const hasRatings = result.ratings !== null;
+
+if (!hasPatterns && !hasRatings) {
+  console.log("\n  No patterns or ratings data found.\n");
+  process.exit(0);
+}
+
+// ── Ratings Summary ──
+
+if (result.ratings) {
+  const r = result.ratings;
+  console.log(`\n  Ratings: ${r.average.toFixed(1)}/10 avg (${r.total} total)`);
+  console.log(`  Low (≤4): ${r.low.count} | High (≥7): ${r.high.count}`);
+}
+
+// ── Graduation Candidates ──
+
+if (result.candidates.length > 0) {
+  console.log(
+    `\n  Graduation Report — ${result.candidates.length} pattern(s) detected\n`
+  );
+  console.log("  ─────────────────────────────────────────────────\n");
+
+  for (const candidate of result.candidates) {
+    console.log(`  [${candidate.domain}] ${candidate.entries.length}x occurrences`);
+    console.log("");
+
+    for (const entry of candidate.entries) {
+      const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+      console.log(
+        `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 100)}`
+      );
+    }
+
+    console.log("");
+    console.log("  Target frame:", `memory/wisdom/frames/${candidate.domain}.md`);
+    console.log("  ─────────────────────────────────────────────────\n");
+  }
+}
+
+// ── Emerging Patterns ──
+
+if (result.emerging.length > 0) {
+  console.log(`  Emerging (2x — one more to graduate)\n`);
+  for (const group of result.emerging) {
+    console.log(`  [${group.domain}] ${group.entries.length}x`);
+    for (const entry of group.entries) {
+      const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+      console.log(
+        `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 80)}`
+      );
+    }
+    console.log("");
+  }
+}
+
+// ── Recommendations ──
+
+if (result.recommendations.length > 0) {
+  console.log("  Recommendations:\n");
+  for (const rec of result.recommendations) {
+    console.log(`    ${rec}`);
+  }
+  console.log("");
+}
+
+if (result.candidates.length > 0) {
+  console.log("  To crystallize: add a line to the wisdom frame file.");
+  console.log("  Format: - Your principle here [CRYSTAL: 85%]\n");
+}

package/src/hooks/handlers/synthesis.ts

@@ -1,109 +0,0 @@
-/**
- * Auto-trigger pattern synthesis on Stop when conditions are met:
- * - 7+ days since last synthesis report
- * - 20+ new ratings since last synthesis
- */
-
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { logDebug } from "../lib/log";
-import { palPkg, paths } from "../lib/paths";
-
-const MIN_DAYS_BETWEEN = 7;
-const MIN_NEW_RATINGS = 20;
-
-function getLastSynthesisDate(): Date | null {
-  try {
-    const synthDir = paths.synthesis();
-    if (!existsSync(synthDir)) return null;
-
-    const months = readdirSync(synthDir).sort().reverse();
-    for (const month of months) {
-      const monthDir = resolve(synthDir, month);
-      const files = readdirSync(monthDir)
-        .filter((f) => f.endsWith(".md"))
-        .sort()
-        .reverse();
-      if (files.length > 0) {
-        // Filename: YYYY-MM-DD_period-patterns.md
-        const dateStr = files[0].slice(0, 10);
-        const date = new Date(dateStr);
-        if (!Number.isNaN(date.getTime())) return date;
-      }
-    }
-  } catch {
-    /* ignore */
-  }
-  return null;
-}
-
-function countRatingsSince(since: Date | null): number {
-  try {
-    const ratingsFile = resolve(paths.signals(), "ratings.jsonl");
-    if (!existsSync(ratingsFile)) return 0;
-
-    const lines = readFileSync(ratingsFile, "utf-8").trim().split("\n");
-    if (!since) return lines.length;
-
-    let count = 0;
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line) as { ts?: string };
-        if (entry.ts && new Date(entry.ts) > since) count++;
-      } catch {
-        /* skip bad lines */
-      }
-    }
-    return count;
-  } catch {
-    return 0;
-  }
-}
-
-export async function checkSynthesisTrigger(): Promise<void> {
-  const lastDate = getLastSynthesisDate();
-  const now = new Date();
-
-  // Check days since last synthesis
-  if (lastDate) {
-    const daysSince = (now.getTime() - lastDate.getTime()) / (1000 * 60 * 60 * 24);
-    if (daysSince < MIN_DAYS_BETWEEN) {
-      logDebug(
-        "synthesis",
-        `Skipping: only ${daysSince.toFixed(1)} days since last report`
-      );
-      return;
-    }
-  }
-
-  // Check new rating count
-  const newRatings = countRatingsSince(lastDate);
-  if (newRatings < MIN_NEW_RATINGS) {
-    logDebug(
-      "synthesis",
-      `Skipping: only ${newRatings} new ratings (need ${MIN_NEW_RATINGS})`
-    );
-    return;
-  }
-
-  logDebug(
-    "synthesis",
-    `Triggering: ${newRatings} new ratings, ${lastDate ? `last report: ${lastDate.toISOString().slice(0, 10)}` : "no previous report"}`
-  );
-
-  // Spawn synthesis as a detached process so it doesn't block the Stop handler
-  try {
-    const repoDir = palPkg();
-    const proc = Bun.spawn(["bun", "run", "tool:patterns"], {
-      cwd: repoDir,
-      stdout: "ignore",
-      stderr: "ignore",
-      stdin: "ignore",
-    });
-    // Don't await — let it run in background
-    proc.unref();
-    logDebug("synthesis", "Spawned pattern synthesis in background");
-  } catch (err) {
-    logDebug("synthesis", `Failed to spawn: ${err}`);
-  }
-}

package/src/tools/graduate.ts

@@ -1,79 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Graduation Report — surface recurring patterns for manual crystallization.
- *
- * Reads failures and session learnings, finds patterns that recur 3+ times,
- * and generates a readable report with context for each candidate.
- * You decide what to add to wisdom frames.
- *
- * Usage: bun run tool:graduate
- */
-
-import { graduate } from "../hooks/lib/graduation";
-
-const result = graduate();
-
-if (result.candidates.length === 0 && result.emerging.length === 0) {
-  console.log("\n  No recurring patterns found.\n");
-  process.exit(0);
-}
-
-console.log(`\n  Graduation Report — ${result.candidates.length} pattern(s) detected\n`);
-console.log("  ─────────────────────────────────────────────────\n");
-
-for (const candidate of result.candidates) {
-  // Collect unique candidate principles
-  const principles = [
-    ...new Set(candidate.entries.map((e) => e.principle).filter((p) => p.length > 0)),
-  ];
-
-  console.log(`  [${candidate.domain}] ${candidate.entries.length}x occurrences`);
-  console.log("");
-
-  // Show each entry with date and source
-  for (const entry of candidate.entries) {
-    const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
-    console.log(
-      `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 100)}`
-    );
-  }
-
-  // Show candidate principles from Haiku
-  if (principles.length > 0) {
-    console.log("\n  Suggested principles:");
-    for (const p of principles) {
-      console.log(`    → ${p}`);
-    }
-  }
-
-  console.log("");
-  console.log("  Target frame:", `memory/wisdom/frames/${candidate.domain}.md`);
-  console.log("  ─────────────────────────────────────────────────\n");
-}
-
-if (result.emerging.length > 0) {
-  console.log(`  Emerging (2x — one more to graduate)\n`);
-  for (const group of result.emerging) {
-    const principles = [
-      ...new Set(group.entries.map((e) => e.principle).filter((p) => p.length > 0)),
-    ];
-    console.log(`  [${group.domain}] ${group.entries.length}x`);
-    for (const entry of group.entries) {
-      const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
-      console.log(
-        `    ${entry.date || "unknown"} [${sourceType}] ${entry.text.slice(0, 80)}`
-      );
-    }
-    if (principles.length > 0) {
-      for (const p of principles) {
-        console.log(`    → ${p}`);
-      }
-    }
-    console.log("");
-  }
-}
-
-if (result.candidates.length > 0) {
-  console.log("  To crystallize: add a line to the wisdom frame file.");
-  console.log("  Format: - Your principle here [CRYSTAL: 85%]\n");
-}