portable-agent-layer 0.3.0 → 0.5.0

package/src/tools/eval-principles.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env bun
+/**
+ * Principle Evaluation — generate, regenerate, or compare candidate principles.
+ *
+ * Reads failures (capture.md) and learnings (frontmatter .md) and uses Haiku
+ * to generate candidate principles. Useful for tuning prompt quality.
+ *
+ * Modes:
+ *   --dry-run     Preview which files would be updated
+ *   --evaluate    Show current vs new principle for comparison (does not write)
+ *   --force       Regenerate principles even if one already exists
+ *   (default)     Generate missing principles only
+ *
+ * Usage:
+ *   bun run tool:eval                    # generate missing
+ *   bun run tool:eval -- --dry-run       # preview
+ *   bun run tool:eval -- --evaluate      # compare current vs new
+ *   bun run tool:eval -- --force         # regenerate all
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { hasFrontmatter, parse, stringify } from "../hooks/lib/frontmatter";
+import { inference } from "../hooks/lib/inference";
+import { palHome } from "../hooks/lib/paths";
+import {
+  FAILURE_PRINCIPLE_PROMPT,
+  LEARNING_PRINCIPLE_PROMPT,
+} from "../hooks/lib/prompts";
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const evaluate = args.includes("--evaluate");
+const force = args.includes("--force");
+
+const home = palHome();
+let processed = 0;
+let skipped = 0;
+let failed = 0;
+
+async function generatePrinciple(systemPrompt: string, context: string): Promise<string> {
+  const result = await inference({
+    system: systemPrompt,
+    user: context,
+    maxTokens: 100,
+    timeout: 10000,
+    jsonSchema: {
+      type: "object" as const,
+      additionalProperties: false,
+      properties: {
+        principle: { type: "string" as const },
+      },
+      required: ["principle"],
+    },
+  });
+
+  if (result.success && result.output) {
+    const parsed = JSON.parse(result.output) as { principle?: string };
+    const principle = parsed.principle?.trim() || "";
+    if (principle.length > 10) return principle;
+  }
+  return "";
+}
+
+// ── Failures ──
+
+async function processFailures() {
+  const failuresDir = resolve(home, "memory", "learning", "failures");
+  if (!existsSync(failuresDir)) return;
+
+  for (const year of readdirSync(failuresDir)) {
+    const yearDir = resolve(failuresDir, year);
+    for (const month of readdirSync(yearDir)) {
+      const monthDir = resolve(yearDir, month);
+      for (const slug of readdirSync(monthDir)) {
+        const capturePath = resolve(monthDir, slug, "capture.md");
+        if (!existsSync(capturePath)) continue;
+
+        const content = readFileSync(capturePath, "utf-8");
+        if (!hasFrontmatter(content)) continue;
+
+        const { meta, body } = parse<{
+          principle?: string;
+          context?: string;
+          rating?: number;
+        }>(content);
+
+        const hasPrinciple = !!meta.principle;
+        if (hasPrinciple && !force && !evaluate) {
+          skipped++;
+          continue;
+        }
+
+        const context = meta.context || "";
+        if (!context) {
+          skipped++;
+          continue;
+        }
+
+        const inputContext = `Rating: ${meta.rating}/10\nContext: ${context}\n\n${body.slice(0, 400)}`;
+
+        if (dryRun) {
+          console.log(`  [failure] ${slug.slice(0, 60)}`);
+          processed++;
+          continue;
+        }
+
+        try {
+          const newPrinciple = await generatePrinciple(
+            FAILURE_PRINCIPLE_PROMPT,
+            inputContext
+          );
+          if (!newPrinciple) {
+            skipped++;
+            continue;
+          }
+
+          if (evaluate) {
+            console.log(`  [failure] ${slug.slice(0, 50)}`);
+            if (hasPrinciple) {
+              console.log(`    OLD: ${meta.principle}`);
+            }
+            console.log(`    NEW: ${newPrinciple}`);
+            console.log("");
+            processed++;
+            continue;
+          }
+
+          const newMeta = { ...meta, principle: newPrinciple } as Record<string, unknown>;
+          writeFileSync(capturePath, stringify(newMeta, body), "utf-8");
+          console.log(`  [failure] ${slug.slice(0, 60)}`);
+          processed++;
+        } catch {
+          failed++;
+        }
+      }
+    }
+  }
+}
+
+// ── Learnings ──
+
+async function processLearnings() {
+  const learningDir = resolve(home, "memory", "learning", "session");
+  if (!existsSync(learningDir)) return;
+
+  for (const year of readdirSync(learningDir)) {
+    const yearDir = resolve(learningDir, year);
+    for (const month of readdirSync(yearDir)) {
+      const monthDir = resolve(yearDir, month);
+      for (const file of readdirSync(monthDir).filter((f) => f.endsWith(".md"))) {
+        const filepath = resolve(monthDir, file);
+        const content = readFileSync(filepath, "utf-8");
+
+        if (!hasFrontmatter(content)) {
+          skipped++;
+          continue;
+        }
+
+        const { meta, body } = parse<{
+          principle?: string;
+          title?: string;
+        }>(content);
+
+        const hasPrinciple = !!meta.principle;
+        if (hasPrinciple && !force && !evaluate) {
+          skipped++;
+          continue;
+        }
+
+        const title = meta.title || "";
+        if (!title) {
+          skipped++;
+          continue;
+        }
+
+        const inputContext = `Title: ${title}\n\n${body.slice(0, 400)}`;
+
+        if (dryRun) {
+          console.log(`  [learning] ${file.slice(0, 60)}`);
+          processed++;
+          continue;
+        }
+
+        try {
+          const newPrinciple = await generatePrinciple(
+            LEARNING_PRINCIPLE_PROMPT,
+            inputContext
+          );
+          if (!newPrinciple) {
+            skipped++;
+            continue;
+          }
+
+          if (evaluate) {
+            console.log(`  [learning] ${file.slice(0, 50)}`);
+            if (hasPrinciple) {
+              console.log(`    OLD: ${meta.principle}`);
+            }
+            console.log(`    NEW: ${newPrinciple}`);
+            console.log("");
+            processed++;
+            continue;
+          }
+
+          const newMeta = { ...meta, principle: newPrinciple } as Record<string, unknown>;
+          writeFileSync(filepath, stringify(newMeta, body), "utf-8");
+          console.log(`  [learning] ${file.slice(0, 60)}`);
+          processed++;
+        } catch {
+          failed++;
+        }
+      }
+    }
+  }
+}
+
+// ── Main ──
+
+const mode = evaluate
+  ? "evaluate"
+  : force
+    ? "force regenerate"
+    : dryRun
+      ? "dry run"
+      : "backfill";
+console.log(`\n  Principle ${mode}...\n`);
+
+await processFailures();
+await processLearnings();
+
+console.log(
+  `\n  Done: ${processed} ${evaluate ? "compared" : "processed"}, ${skipped} skipped, ${failed} failed\n`
+);

package/src/tools/graduate.ts

@@ -0,0 +1,55 @@
+#!/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) {
+  console.log("\n  No recurring patterns found (need 3+ similar entries).\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");
+}
+
+console.log("  To crystallize: add a line to the wisdom frame file.");
+console.log("  Format: - Your principle here [CRYSTAL: 85%]\n");

package/src/tools/pattern-synthesis.ts

@@ -15,6 +15,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { stringify } from "../hooks/lib/frontmatter";
 import { HAIKU_MODEL } from "../hooks/lib/models";
 import { palHome } from "../hooks/lib/paths";
 
@@ -260,19 +261,15 @@ async function analyzeRatings(
 
 function formatReport(result: SynthesisResult): string {
   const date = new Date().toISOString().slice(0, 10);
-  const lines: string[] = [
-    "# Learning Pattern Synthesis",
-    "",
-    `**Period:** ${result.period}`,
-    `**Generated:** ${date}`,
-    `**Total Ratings:** ${result.totalRatings}`,
-    `**Average Rating:** ${result.avgRating.toFixed(1)}/10`,
-    "",
-    "---",
-    "",
-    "## Top Issues",
-    "",
-  ];
+
+  const meta: Record<string, unknown> = {
+    period: result.period,
+    date,
+    total_ratings: result.totalRatings,
+    average_rating: result.avgRating.toFixed(1),
+  };
+
+  const lines: string[] = ["## Top Issues", ""];
 
   if (result.topIssues.length > 0) {
     for (let i = 0; i < result.topIssues.length; i++) {
@@ -324,7 +321,7 @@ function formatReport(result: SynthesisResult): string {
     ""
   );
 
-  return lines.join("\n");
+  return stringify(meta, lines.join("\n"));
 }
 
 function writeReport(result: SynthesisResult, period: string): string {

package/src/tools/token-cost.ts

@@ -47,6 +47,16 @@ function emptyBucket(): Bucket {
   return { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, cost: 0, calls: 0 };
 }
 
+function findPricing(model: string): (typeof MODEL_PRICING)[string] | null {
+  // Exact match first
+  if (MODEL_PRICING[model]) return MODEL_PRICING[model];
+  // Prefix match (e.g. "claude-sonnet-4-5-20250929" matches "claude-sonnet-4-5")
+  for (const key of Object.keys(MODEL_PRICING)) {
+    if (model.startsWith(key)) return MODEL_PRICING[key];
+  }
+  return null;
+}
+
 function costForUsage(
   model: string,
   input: number,
@@ -54,7 +64,7 @@ function costForUsage(
   cacheWrite: number,
   cacheRead: number
 ): number {
-  const p = MODEL_PRICING[model];
+  const p = findPricing(model);
   if (!p) return 0;
   return (
     (input * p.input +
@@ -159,14 +169,34 @@ function readClaudeCode(): {
 
   for (const projDir of projectDirs) {
     const projPath = resolve(claudeDir, projDir);
-    const projName = projDir.split("-").pop() ?? projDir;
+    // Project dir is like "-Users-rico-Development-git-myproject" — extract last meaningful segment
+    const segments = projDir.replace(/^-/, "").split("-");
+    const projName = segments.length > 1 ? segments.slice(-1)[0] : projDir;
 
     if (typeof args.project === "string" && !projName.includes(args.project)) continue;
 
-    const jsonlFiles = readdirSync(projPath).filter((f) => f.endsWith(".jsonl"));
+    // Collect all JSONL files: top-level + subagent directories
+    const jsonlFiles: string[] = [];
+
+    for (const entry of readdirSync(projPath, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        jsonlFiles.push(resolve(projPath, entry.name));
+      } else if (entry.isDirectory()) {
+        // Check for subagent transcripts inside session directories
+        const subagentsDir = resolve(projPath, entry.name, "subagents");
+        try {
+          for (const sub of readdirSync(subagentsDir)) {
+            if (sub.endsWith(".jsonl")) {
+              jsonlFiles.push(resolve(subagentsDir, sub));
+            }
+          }
+        } catch {
+          /* no subagents dir */
+        }
+      }
+    }
 
-    for (const file of jsonlFiles) {
-      const filepath = resolve(projPath, file);
+    for (const filepath of jsonlFiles) {
       let content: string;
       try {
         content = readFileSync(filepath, "utf-8");