portable-agent-layer 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -48,6 +48,8 @@
     "ai:fyzz-api": "bun run src/tools/fyzz-api.ts",
     "ai:pdf-download": "bun run src/tools/pdf-download.ts",
     "ai:youtube-analyze": "bun run src/tools/youtube-analyze.ts",
+    "tool:eval": "bun run src/tools/eval-principles.ts",
+    "tool:graduate": "bun run src/tools/graduate.ts",
     "tool:patterns": "bun run src/tools/pattern-synthesis.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
     "tool:export": "bun run src/tools/export.ts",

package/src/cli/index.ts

@@ -252,6 +252,43 @@ function resolveTargets(
   return targets;
 }
 
+// ── Hook health ──
+
+interface HookHealth {
+  totalErrors: number;
+  lastError: string | null;
+}
+
+function checkHookHealth(home: string): HookHealth {
+  const logPath = resolve(home, "memory", "state", "debug.log");
+
+  try {
+    if (!existsSync(logPath)) return { totalErrors: 0, lastError: null };
+
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.split("\n").filter((l) => l.includes("] ERROR "));
+
+    // Filter to last 24h
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
+    const recentErrors = lines.filter((line) => {
+      const match = line.match(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/);
+      if (!match) return false;
+      return new Date(match[1]) > cutoff;
+    });
+
+    const lastError =
+      recentErrors.length > 0
+        ? recentErrors[recentErrors.length - 1]
+            .replace(/^\[.*?\] ERROR /, "")
+            .slice(0, 120)
+        : null;
+
+    return { totalErrors: recentErrors.length, lastError };
+  } catch {
+    return { totalErrors: 0, lastError: null };
+  }
+}
+
 // ── Doctor ──
 
 interface DoctorResult {
@@ -288,8 +325,9 @@ function doctor(silent = false): DoctorResult {
   })();
 
   if (!silent) {
-    const ok = (msg: string) => log.info(`  \u2713 ${msg}`);
-    const fail = (msg: string) => log.warn(`  \u2717 ${msg}`);
+    const ok = (msg: string) => console.log(`  \x1b[32m\u2713\x1b[0m ${msg}`);
+    const warn = (msg: string) => console.log(`  \x1b[33m\u26A0\x1b[0m ${msg}`);
+    const fail = (msg: string) => console.log(`  \x1b[31m\u2717\x1b[0m ${msg}`);
 
     console.log("");
     log.info("Doctor");
@@ -303,6 +341,25 @@ function doctor(silent = false): DoctorResult {
     ok(`PAL home: ${home} (${isRepo ? "repo" : "package"} mode)`);
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
+    // API key checks
+    process.env.ANTHROPIC_API_KEY
+      ? ok("ANTHROPIC_API_KEY is set")
+      : fail("ANTHROPIC_API_KEY — not set (hooks need it for inference)");
+    process.env.GEMINI_API_KEY
+      ? ok("GEMINI_API_KEY is set")
+      : warn("GEMINI_API_KEY — not set (optional, for YouTube analysis)");
+
+    // Hook health from debug.log
+    const hookHealth = checkHookHealth(home);
+    if (hookHealth.totalErrors === 0) {
+      ok("Hooks: no recent errors");
+    } else {
+      fail(`Hooks: ${hookHealth.totalErrors} error(s) in last 24h`);
+      if (hookHealth.lastError) {
+        log.warn(`    Last: ${hookHealth.lastError}`);
+      }
+    }
+
     if (!hasAgent) {
       console.log("");
       log.error("No supported agent found. Install Claude Code or opencode.");

package/src/hooks/handlers/failure.ts

@@ -2,14 +2,16 @@
  * Deep Failure Capture — full context dump for ratings 1–3.
  *
  * Writes to memory/learning/failures/YYYY-MM/{timestamp}_{slug}/
- *   CONTEXT.md    — full failure context with transcript excerpt
- *   sentiment.json — structured rating + metadata
+ *   capture.md     — frontmatter metadata + failure context body
+ *   sentiment.json — DEPRECATED legacy format (kept for backward compat)
  */
 
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { ensureDir, paths } from "../lib/paths";
+import { FAILURE_PRINCIPLE_PROMPT } from "../lib/prompts";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -53,32 +55,33 @@ export async function captureFailure(
     resolve(paths.failures(), monthPath(), `${fileTimestamp()}_${slug}`)
   );
 
-  // Attempt inference to fill root cause analysis
+  // Attempt inference to fill root cause analysis + candidate principle
   let whatWentWrong = "";
   let whatToDoDifferently = "";
+  let principle = "";
   try {
     const analysisResult = await inference({
-      system:
-        "You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable.",
+      system: `You are analyzing a failed AI assistant interaction. Based on the context, identify what went wrong and what should be done differently. Be specific and actionable. Also write a principle — ${FAILURE_PRINCIPLE_PROMPT}`,
       user: [
         `Rating: ${rating}/10`,
         `Context: ${context}`,
         detailedContext ? `Analysis: ${detailedContext}` : "",
-        `User said: ${lastUser}`,
-        `Assistant said: ${lastAssistant}`,
+        `Assistant response (what the user reacted to): ${lastAssistant}`,
+        `User reaction (the frustrated message): ${lastUser}`,
       ]
         .filter(Boolean)
         .join("\n"),
-      maxTokens: 300,
-      timeout: 8000,
+      maxTokens: 400,
+      timeout: 15000,
       jsonSchema: {
         type: "object" as const,
         additionalProperties: false,
         properties: {
           what_went_wrong: { type: "string" as const },
           what_to_do_differently: { type: "string" as const },
+          principle: { type: "string" as const },
         },
-        required: ["what_went_wrong", "what_to_do_differently"],
+        required: ["what_went_wrong", "what_to_do_differently", "principle"],
       },
     });
     if (analysisResult.usage) logTokenUsage("failure", analysisResult.usage);
@@ -86,51 +89,46 @@ export async function captureFailure(
       const parsed = JSON.parse(analysisResult.output) as {
         what_went_wrong?: string;
         what_to_do_differently?: string;
+        principle?: string;
       };
       whatWentWrong = parsed.what_went_wrong ?? "";
       whatToDoDifferently = parsed.what_to_do_differently ?? "";
+      principle = parsed.principle ?? "";
     }
   } catch {
     // Graceful fallback — empty sections are still useful with the other context
   }
 
-  const contextMdPath = resolve(dir, "CONTEXT.md");
-  writeFileSync(
-    contextMdPath,
-    [
-      `# Failure Capture — Rating ${rating}/10`,
-      `**Date:** ${new Date().toISOString().slice(0, 10)}`,
-      `**Context:** ${context}`,
-      "",
-      "## Last User Message",
-      lastUser || "*(unavailable)*",
-      "",
-      "## Last Assistant Response",
-      lastAssistant || "*(unavailable)*",
-      "",
-      ...(detailedContext ? ["## AI Response Context", detailedContext, ""] : []),
-      "## What Went Wrong?",
-      whatWentWrong || "",
-      "",
-      "## What Should Be Done Differently?",
-      whatToDoDifferently || "",
-      "",
-    ].join("\n"),
-    "utf-8"
-  );
+  const meta: Record<string, unknown> = {
+    rating,
+    context,
+    date: new Date().toISOString().slice(0, 10),
+    ts: new Date().toISOString(),
+    slug,
+  };
+  if (principle) meta.principle = principle;
 
+  const body = [
+    "## Last User Message",
+    lastUser || "*(unavailable)*",
+    "",
+    "## Last Assistant Response",
+    lastAssistant || "*(unavailable)*",
+    "",
+    ...(detailedContext ? ["## AI Response Context", detailedContext, ""] : []),
+    "## What Went Wrong?",
+    whatWentWrong || "",
+    "",
+    "## What Should Be Done Differently?",
+    whatToDoDifferently || "",
+  ].join("\n");
+
+  writeFileSync(resolve(dir, "capture.md"), stringify(meta, body), "utf-8");
+
+  // DEPRECATED: legacy sentiment.json — remove once all readers use capture.md frontmatter
   writeFileSync(
     resolve(dir, "sentiment.json"),
-    JSON.stringify(
-      {
-        rating,
-        context,
-        ts: new Date().toISOString(),
-        slug,
-      },
-      null,
-      2
-    ),
+    JSON.stringify({ rating, context, ts: new Date().toISOString(), slug }, null, 2),
     "utf-8"
   );
 }

package/src/hooks/handlers/rating.ts

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { ensureDir, paths } from "../lib/paths";
@@ -244,24 +245,24 @@ function writeLearningMarkdown(
   const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
   const filename = `${fileTimestamp()}_${source}-rating-${rating}_${category}.md`;
 
-  const content = [
-    `# ${source === "explicit" ? "Low Rating" : "Implicit Low Rating"}: ${rating}/10`,
-    `**Title:** ${context.slice(0, 100) || "(low rating)"}`,
-    `**Date:** ${new Date().toISOString().slice(0, 10)}`,
-    `**Rating:** ${rating}/10`,
-    `**Source:** ${source}`,
-    `**Category:** ${category.toUpperCase()}`,
-    "",
+  const meta: Record<string, unknown> = {
+    title: context.slice(0, 100) || "(low rating)",
+    category,
+    date: new Date().toISOString().slice(0, 10),
+    rating,
+    source,
+  };
+
+  const body = [
     "## Context",
     context || "*(unavailable)*",
     "",
     ...(detailedContext ? ["## Analysis", detailedContext, ""] : []),
     "## Last Response",
     responsePreview || "*(unavailable)*",
-    "",
   ].join("\n");
 
-  writeFileSync(resolve(dir, filename), content, "utf-8");
+  writeFileSync(resolve(dir, filename), stringify(meta, body), "utf-8");
 }
 
 function handleRating(
@@ -295,14 +296,7 @@ function handleRating(
       ),
       "utf-8"
     );
-    // Also write learning markdown
-    writeLearningMarkdown(
-      rating,
-      source,
-      context,
-      detailedContext ?? "",
-      responsePreview
-    );
+    // No learning markdown for ≤3 — failure capture covers it with richer analysis + tags
   } else if (rating < 5) {
     // Low but not critical — write learning markdown
     writeLearningMarkdown(

package/src/hooks/handlers/work-learning.ts

@@ -7,9 +7,11 @@
 
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stringify } from "../lib/frontmatter";
 import { inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { ensureDir, paths } from "../lib/paths";
+import { LEARNING_PRINCIPLE_PROMPT } from "../lib/prompts";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -106,6 +108,7 @@ export async function captureWorkLearning(
   let title = rawTitle;
   let summary = rawSummary;
   let insights = "";
+  let principle = "";
   try {
     const userMessages = messages
       .filter((m) => m.role === "user")
@@ -113,11 +116,10 @@ export async function captureWorkLearning(
       .slice(-8)
       .join("\n");
     const result = await inference({
-      system:
-        "You summarize AI coding sessions between a human user and an AI assistant. The 'Human messages' are what the user said. The 'AI response' is what the assistant said. Produce: 1) a short title (5-10 words) describing what was accomplished, 2) a summary of what the AI assistant did for the user (2-4 sentences, write from the AI's perspective using 'we'), 3) insights — what worked well, what was surprising, or what should be done differently next time (2-3 bullet points, no markdown).",
+      system: `You summarize AI coding sessions between a human user and an AI assistant. The 'Human messages' are what the user said. The 'AI response' is what the assistant said. Produce: 1) a short title (5-10 words) describing what was accomplished, 2) a summary of what the AI assistant did for the user (2-4 sentences, write from the AI's perspective using 'we'), 3) insights — what worked well, what was surprising, or what should be done differently next time (2-3 bullet points, no markdown), 4) principle — ${LEARNING_PRINCIPLE_PROMPT}`,
       user: `Human messages:\n${userMessages}\n\nAI response:\n${rawSummary.slice(0, 400)}`,
-      maxTokens: 250,
-      timeout: 8000,
+      maxTokens: 350,
+      timeout: 15000,
       jsonSchema: {
         type: "object" as const,
         additionalProperties: false,
@@ -125,8 +127,9 @@ export async function captureWorkLearning(
           title: { type: "string" as const },
           summary: { type: "string" as const },
           insights: { type: "string" as const },
+          principle: { type: "string" as const },
         },
-        required: ["title", "summary", "insights"],
+        required: ["title", "summary", "insights", "principle"],
       },
     });
     if (result.usage) logTokenUsage("work-learning", result.usage);
@@ -135,10 +138,12 @@ export async function captureWorkLearning(
         title?: string;
         summary?: string;
         insights?: string;
+        principle?: string;
       };
       if (parsed.title) title = parsed.title.slice(0, 100);
       if (parsed.summary) summary = parsed.summary;
       if (parsed.insights) insights = parsed.insights;
+      if (parsed.principle) principle = parsed.principle;
     }
   } catch {
     // Fallback to raw values
@@ -149,21 +154,24 @@ export async function captureWorkLearning(
   const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
   const filename = `${fileTimestamp()}_${category}_${slug}.md`;
 
-  const content = [
-    "# Work Completion Learning",
-    `**Title:** ${title}`,
-    `**Category:** ${category.toUpperCase()}`,
-    `**Date:** ${new Date().toISOString().slice(0, 10)}`,
-    ...(sessionId ? [`**Session:** ${sessionId}`] : []),
-    "",
+  const meta: Record<string, unknown> = {
+    title,
+    category,
+    date: new Date().toISOString().slice(0, 10),
+  };
+  if (principle) meta.principle = principle;
+  if (sessionId) meta.session = sessionId;
+
+  const body = [
     "## What Was Done",
     summary,
     "",
     "## Insights",
     insights || "*No insights captured.*",
-    "",
   ].join("\n");
 
+  const content = stringify(meta, body);
+
   // Remove previous capture for this session (overwrite on continued conversations)
   if (sessionId) {
     const prev = getPreviousCapture(sessionId);

package/src/hooks/lib/context.ts

@@ -5,6 +5,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { hasFrontmatter, parse } from "./frontmatter";
 import { paths } from "./paths";
 import { loadRecentNotes } from "./relationship";
 import { readSessionNames } from "./session-names";
@@ -247,28 +248,53 @@ export function loadLearningDigest(): string {
       if (files.length >= 6) break;
     }
 
-    function extractTitle(filePath: string): string {
+    function extractMeta(filePath: string): {
+      title: string;
+      category: string;
+    } {
       const content = readFileSync(filePath, "utf-8").trim();
+
+      // Frontmatter format (new)
+      if (hasFrontmatter(content)) {
+        const { meta } = parse<{ title?: string; category?: string }>(content);
+        return {
+          title: meta.title ? `**Title:** ${meta.title}` : content.slice(0, 80),
+          category: meta.category || "algorithm",
+        };
+      }
+
+      // DEPRECATED: legacy **Title:** inline format — remove once old learning files are migrated
       const titleLine = content.split("\n").find((l) => l.startsWith("**Title:**"));
-      if (titleLine) return titleLine;
-      // Fallback: first non-heading, non-empty line
       const fallback = content.split("\n").find((l) => l.trim() && !l.startsWith("#"));
-      return fallback?.slice(0, 100) ?? content.slice(0, 80);
+      return {
+        title: titleLine ?? fallback?.slice(0, 100) ?? content.slice(0, 80),
+        category: "algorithm", // legacy files use filename for category
+      };
     }
 
-    const algorithm = files.filter((f) => f.category === "algorithm").slice(0, 2);
-    const system = files.filter((f) => f.category === "system").slice(0, 2);
+    // Extract metadata, preferring frontmatter over filename for category
+    const enriched = files.map((f) => {
+      const meta = extractMeta(f.path);
+      return {
+        ...f,
+        title: meta.title,
+        category: meta.category !== "algorithm" ? meta.category : f.category,
+      };
+    });
+
+    const algorithm = enriched.filter((f) => f.category === "algorithm").slice(0, 2);
+    const system = enriched.filter((f) => f.category === "system").slice(0, 2);
 
     if (algorithm.length === 0 && system.length === 0) return "";
 
     const lines: string[] = ["## Recent Session Learnings"];
     if (algorithm.length > 0) {
       lines.push("### Approach");
-      for (const f of algorithm) lines.push(`- ${extractTitle(f.path)}`);
+      for (const f of algorithm) lines.push(`- ${f.title}`);
     }
     if (system.length > 0) {
       lines.push("### System");
-      for (const f of system) lines.push(`- ${extractTitle(f.path)}`);
+      for (const f of system) lines.push(`- ${f.title}`);
     }
     return lines.join("\n");
   } catch {
@@ -292,22 +318,38 @@ export function loadFailurePatterns(): string {
           const dirs = readdirSync(monthPath).sort().reverse();
           for (const dir of dirs) {
             if (!/^\d{8}-\d{6}_/.test(dir)) continue;
-            // Read context from sentiment.json for a meaningful description
+            // Try capture.md (new format), fall back to sentiment.json (legacy)
+            const capturePath = resolve(monthPath, dir, "capture.md");
             const sentimentPath = resolve(monthPath, dir, "sentiment.json");
-            if (existsSync(sentimentPath)) {
+
+            let rating: number | undefined;
+            let ctx: string | undefined;
+
+            if (existsSync(capturePath)) {
+              try {
+                const content = readFileSync(capturePath, "utf-8");
+                const { meta } = parse<{ rating?: number; context?: string }>(content);
+                rating = meta.rating;
+                ctx = meta.context;
+              } catch {
+                /* fallback below */
+              }
+            }
+
+            // DEPRECATED: legacy sentiment.json fallback — remove once old failures have capture.md
+            if (!ctx && existsSync(sentimentPath)) {
               try {
-                const data = JSON.parse(readFileSync(sentimentPath, "utf-8")) as {
-                  rating?: number;
-                  context?: string;
-                };
-                if (data.context) {
-                  const label = data.rating ? `[${data.rating}/10]` : "";
-                  failures.push(`${label} ${data.context}`.trim());
-                }
+                const data = JSON.parse(readFileSync(sentimentPath, "utf-8"));
+                rating = data.rating;
+                ctx = data.context;
               } catch {
-                // Fall back to slug from directory name
-                failures.push(dir.replace(/^\d{8}-\d{6}_/, ""));
+                /* skip */
               }
+            }
+
+            if (ctx) {
+              const label = rating ? `[${rating}/10]` : "";
+              failures.push(`${label} ${ctx}`.trim());
             } else {
               failures.push(dir.replace(/^\d{8}-\d{6}_/, ""));
             }
@@ -361,12 +403,28 @@ export function loadSynthesisRecommendations(): string {
 
         if (recs.length === 0) continue;
 
-        // Extract metadata
-        const periodMatch = content.match(/\*\*Period:\*\* (.+)/);
-        const avgMatch = content.match(/\*\*Average Rating:\*\* (.+)/);
+        // Extract metadata — frontmatter or legacy
+        let period = "";
+        let avgRating = "";
+
+        if (hasFrontmatter(content)) {
+          const { meta } = parse<{
+            period?: string;
+            average_rating?: string;
+          }>(content);
+          period = meta.period || "";
+          avgRating = meta.average_rating ? `${meta.average_rating}/10` : "";
+        } else {
+          // DEPRECATED: legacy **Key:** format
+          const periodMatch = content.match(/\*\*Period:\*\* (.+)/);
+          const avgMatch = content.match(/\*\*Average Rating:\*\* (.+)/);
+          period = periodMatch?.[1] || "";
+          avgRating = avgMatch?.[1] || "";
+        }
+
         const header = [
           "## Pattern Synthesis",
-          periodMatch ? `*${periodMatch[1]} — ${avgMatch?.[1] ?? ""}*` : "",
+          period ? `*${period} — ${avgRating}*` : "",
         ]
           .filter(Boolean)
           .join("\n");

package/src/hooks/lib/frontmatter.ts

@@ -0,0 +1,95 @@
+/**
+ * Lightweight YAML frontmatter parser/serializer.
+ *
+ * No external dependencies — parses simple key: value YAML between --- delimiters.
+ * Supports strings, numbers, booleans, and inline JSON arrays.
+ */
+
+export interface Parsed<T = Record<string, string>> {
+  meta: T;
+  body: string;
+}
+
+const DELIMITER = /^---\s*$/m;
+
+/**
+ * Parse frontmatter from a markdown string.
+ * Returns typed meta + body. If no frontmatter found, meta is empty and body is the full content.
+ */
+export function parse<T = Record<string, string>>(content: string): Parsed<T> {
+  const parts = content.split(DELIMITER);
+
+  // Need at least 3 parts: before --- | frontmatter | after ---
+  // parts[0] should be empty (content starts with ---)
+  if (parts.length < 3 || parts[0].trim() !== "") {
+    return { meta: {} as T, body: content };
+  }
+
+  const rawMeta = parts[1];
+  const body = parts.slice(2).join("---").trim();
+
+  const meta: Record<string, unknown> = {};
+  for (const line of rawMeta.split("\n")) {
+    const match = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+
+    // Inline JSON array
+    if (value.startsWith("[") && value.endsWith("]")) {
+      try {
+        meta[key] = JSON.parse(value);
+        continue;
+      } catch {
+        // Fall through to string handling
+      }
+    }
+
+    // Strip quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      meta[key] = value.slice(1, -1).replace(/\\"/g, '"');
+      continue;
+    }
+
+    // Type coercion
+    if (value === "true") meta[key] = true;
+    else if (value === "false") meta[key] = false;
+    else if (/^\d+$/.test(value)) meta[key] = Number.parseInt(value, 10);
+    else if (/^\d+\.\d+$/.test(value)) meta[key] = Number.parseFloat(value);
+    else meta[key] = value;
+  }
+
+  return { meta: meta as T, body };
+}
+
+/**
+ * Serialize metadata and body into a frontmatter string.
+ * Skips undefined/null values.
+ */
+export function stringify(meta: Record<string, unknown>, body: string): string {
+  const lines: string[] = ["---"];
+
+  for (const [key, value] of Object.entries(meta)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+    } else if (typeof value === "string") {
+      lines.push(`${key}: "${value.replace(/"/g, '\\"')}"`);
+    } else {
+      lines.push(`${key}: ${String(value)}`);
+    }
+  }
+
+  lines.push("---");
+  return `${lines.join("\n")}\n\n${body.trim()}\n`;
+}
+
+/**
+ * Check if content has frontmatter (starts with ---).
+ */
+export function hasFrontmatter(content: string): boolean {
+  return content.trimStart().startsWith("---");
+}