portable-agent-layer 0.70.0 → 0.72.0

package/src/tools/agent/algorithm-reflect.ts

@@ -15,87 +15,36 @@
 
 import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
-import { encodeAnchor } from "../../hooks/lib/anchor";
 import { paths } from "../../hooks/lib/paths";
+import { buildReflection, intOr, reflectionLine } from "../lib/algorithm-reflect";
 import { emit } from "../lib/emit";
 
-// ── Types ──
+const HELP = `
+AlgorithmReflect — Log algorithm performance after LEARN phase
 
-interface AlgorithmReflection extends RecordAttribution {
-  timestamp: string;
-  cwd: string;
-  task: string;
-  criteria_count: number;
-  criteria_passed: number;
-  criteria_failed: number;
-  sentiment: number;
-  q1: string;
-  q2: string;
-  q3: string;
-  /** general = the improvement ideas generalize to the algorithm; task-specific = bound to this task. */
-  scope: "general" | "task-specific";
-}
+Usage:
+  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
+    --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+
+Arguments:
+  --task        Brief task description
+  --criteria    Total criteria count
+  --passed      Criteria passed
+  --failed      Criteria failed
+  --sentiment   Implied satisfaction 1-10
+  --q1          Q1 — Self: what I'd do differently
+  --q2          Q2 — Algorithm: structural improvement
+  --q3          Q3 — AI: reasoning blind spot
+  --scope       general (default) | task-specific — is the algorithm idea reusable or task-bound?
 
-// ── Core ──
+Output: algorithm-reflections.jsonl in memory/learning/reflections/
+`;
 
 function reflectionsPath(): string {
-  paths.reflections(); // ensures the directory exists
+  paths.reflections();
   return paths.reflectionsFile();
 }
 
-/**
- * Assemble a reflection record from CLI-style input, stamping the current
- * cwd (anchored) and this machine's id. Exported so the stamping logic is
- * directly testable without going through argv parsing.
- */
-export function buildReflection(input: {
-  task: string;
-  q1: string;
-  q2: string;
-  q3: string;
-  criteria_count?: number;
-  criteria_passed?: number;
-  criteria_failed?: number;
-  sentiment?: number;
-  scope?: string;
-}): AlgorithmReflection {
-  return {
-    timestamp: new Date().toISOString(),
-    cwd: encodeAnchor(process.cwd()),
-    ...currentAttribution(),
-    task: input.task,
-    criteria_count: input.criteria_count ?? 0,
-    criteria_passed: input.criteria_passed ?? 0,
-    criteria_failed: input.criteria_failed ?? 0,
-    sentiment: Math.max(1, Math.min(10, input.sentiment ?? 5)),
-    q1: input.q1,
-    q2: input.q2,
-    q3: input.q3,
-    // Default to general (the ~94% case); only "task-specific" suppresses it
-    // from algorithm-update clustering.
-    scope: input.scope === "task-specific" ? "task-specific" : "general",
-  };
-}
-
-function appendReflection(reflection: AlgorithmReflection): {
-  success: boolean;
-  message: string;
-  path: string;
-} {
-  const p = reflectionsPath();
-  const line = `${JSON.stringify(reflection)}\n`;
-  appendFileSync(p, line, "utf-8");
-
-  return {
-    success: true,
-    message: `Reflection logged: ${reflection.criteria_passed}/${reflection.criteria_count} passed, sentiment ${reflection.sentiment}/10`,
-    path: p,
-  };
-}
-
-// ── CLI ──
-
 function run() {
   const { values } = parseArgs({
     args: Bun.argv.slice(2),
@@ -114,26 +63,7 @@ function run() {
   });
 
   if (values.help) {
-    console.log(`
-AlgorithmReflect — Log algorithm performance after LEARN phase
-
-Usage:
-  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
-    --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
-
-Arguments:
-  --task        Brief task description
-  --criteria    Total criteria count
-  --passed      Criteria passed
-  --failed      Criteria failed
-  --sentiment   Implied satisfaction 1-10
-  --q1          Q1 — Self: what I'd do differently
-  --q2          Q2 — Algorithm: structural improvement
-  --q3          Q3 — AI: reasoning blind spot
-  --scope       general (default) | task-specific — is the algorithm idea reusable or task-bound?
-
-Output: algorithm-reflections.jsonl in memory/learning/reflections/
-`);
+    console.log(HELP);
     process.exit(0);
   }
 
@@ -147,15 +77,16 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
     q1: values.q1,
     q2: values.q2,
     q3: values.q3,
-    criteria_count: parseInt(values.criteria || "0", 10),
-    criteria_passed: parseInt(values.passed || "0", 10),
-    criteria_failed: parseInt(values.failed || "0", 10),
-    sentiment: parseInt(values.sentiment || "5", 10),
+    criteria_count: intOr(values.criteria, 0),
+    criteria_passed: intOr(values.passed, 0),
+    criteria_failed: intOr(values.failed, 0),
+    sentiment: intOr(values.sentiment, 5),
     scope: values.scope,
   });
 
-  const result = appendReflection(reflection);
-  emit.receipt(result.path, {
+  const path = reflectionsPath();
+  appendFileSync(path, reflectionLine(reflection), "utf-8");
+  emit.receipt(path, {
     passed: reflection.criteria_passed,
     of: reflection.criteria_count,
     scope: reflection.scope,

package/src/tools/agent/analyze.ts

@@ -5,130 +5,17 @@
  * Reads failures and session learnings, finds recurring patterns,
  * summarizes ratings, and generates recommendations.
  *
+ * What the report says is in lib/analyze-report.ts.
+ *
  * Usage: bun run tool:analyze
  */
 
 import { parseArgs } from "node:util";
 import { writeLastAnalyzeDate } from "../../hooks/lib/analyze-nudge";
-import { type AnalysisResult, analyze } from "../../hooks/lib/graduation";
-
-// ── ANSI Colors ──
-
-const c = {
-  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
-  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
-  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
-  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
-  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
-  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
-  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
-};
-
-function printReport(result: AnalysisResult): void {
-  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");
-    return;
-  }
-
-  if (result.ratings) {
-    const r = result.ratings;
-    const lowOrMid = r.average <= 4 ? c.red : c.yellow;
-    const avgColor = r.average >= 7 ? c.green : lowOrMid;
-    const ratingStr = `${r.average.toFixed(1)}/10`;
-    const lowStr = `Low (≤4): ${r.low.count}`;
-    const highStr = `High (≥7): ${r.high.count}`;
-    console.log(
-      `\n  ${c.bold("Ratings:")} ${avgColor(ratingStr)} avg (${r.total} total)`
-    );
-    console.log(`  ${c.red(lowStr)} | ${c.green(highStr)}`);
-  }
-
-  if (result.candidates.length > 0) {
-    const graduationHeader = `Graduation Report — ${result.candidates.length} pattern(s) detected`;
-    console.log(`\n  ${c.bold(c.green(graduationHeader))}\n`);
-    console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
-
-    for (const candidate of result.candidates) {
-      const domain = `[${candidate.domain}]`;
-      const count = `${candidate.entries.length}x`;
-      console.log(`  ${c.cyan(domain)} ${c.bold(count)} occurrences`);
-      console.log("");
-
-      for (const entry of candidate.entries) {
-        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
-        const tag =
-          sourceType === "failure"
-            ? c.red(`[${sourceType}]`)
-            : c.yellow(`[${sourceType}]`);
-        console.log(
-          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 100)}`
-        );
-      }
-
-      console.log(`\n  ${c.dim("Files:")}`);
-      for (const entry of candidate.entries) {
-        console.log(`    ${c.dim(entry.path)}`);
-      }
-
-      console.log("");
-      const framePath = `memory/wisdom/frames/${candidate.domain}.md`;
-      console.log(`  Target frame: ${c.magenta(framePath)}`);
-      console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
-    }
-  }
-
-  if (result.emerging.length > 0) {
-    console.log(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
-    for (const group of result.emerging) {
-      const domain = `[${group.domain}]`;
-      const count = `${group.entries.length}x`;
-      console.log(`  ${c.cyan(domain)} ${c.bold(count)}`);
-      for (const entry of group.entries) {
-        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
-        const tag =
-          sourceType === "failure"
-            ? c.red(`[${sourceType}]`)
-            : c.yellow(`[${sourceType}]`);
-        console.log(
-          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 80)}`
-        );
-      }
-      console.log("  Files:");
-      for (const entry of group.entries) {
-        console.log(`    ${c.dim(entry.path)}`);
-      }
-      console.log("");
-    }
-  }
-
-  if (result.recommendations.length > 0) {
-    console.log(`  ${c.bold("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: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`);
-  }
-}
+import { analyze } from "../../hooks/lib/graduation";
+import { reportLines } from "../lib/analyze-report";
 
-export async function run(argv: string[] = Bun.argv.slice(2)) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      help: { type: "boolean", short: "h" },
-      actionable: { type: "boolean", short: "a" },
-    },
-  });
-
-  if (values.help) {
-    console.log(`
+const HELP = `
   PAL Learning Analysis — unified graduation + ratings report
 
   Reads all captured failures (rating ≤3) and session learnings,
@@ -147,12 +34,24 @@ export async function run(argv: string[] = Bun.argv.slice(2)) {
     - Your principle here [CRYSTAL: 85%]
 
   Usage: pal cli analyze [--actionable]
-`);
+`;
+
+export async function run(argv: string[] = Bun.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      help: { type: "boolean", short: "h" },
+      actionable: { type: "boolean", short: "a" },
+    },
+  });
+
+  if (values.help) {
+    console.log(HELP);
     process.exit(0);
   }
 
   const result = await analyze({ actionable: values.actionable });
-  printReport(result);
+  for (const line of reportLines(result)) console.log(line);
   writeLastAnalyzeDate(new Date().toISOString());
 }
 

package/src/tools/agent/handoff-note.ts

@@ -10,60 +10,38 @@
  *   bun ~/.pal/tools/handoff-note.ts --done   # mark completed, suppress next-session injection
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { ensureDir, paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
+import {
+  handoffFile,
+  type NoteInput,
+  readHandoffs,
+  recordNote,
+  statusOf,
+} from "../lib/handoff-note";
 
-interface HandoffEntry {
-  timestamp: string;
-  title: string;
-  status: "in-progress" | "completed";
-  handoff: string;
-  artifacts: string[];
-  source: "deliberate" | "auto";
-}
+const HELP = `
+HandoffNote — Write a handoff note for the current project
 
-function handoffPath(): string {
-  return resolve(ensureDir(paths.state()), "last-handoff.json");
-}
+Usage:
+  bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains"
+  bun ~/.pal/tools/handoff-note.ts --done    # mark session completed
 
-function readHandoffs(): Record<string, HandoffEntry> {
-  const p = handoffPath();
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
+Arguments:
+  --title   Brief title of what was being worked on (5-10 words)
+  --text    What remains unfinished — decisions made, next steps, blockers
+  --waiting What this needs from you before it can move (a decision, an answer, access)
+  --done    Mark as completed; suppresses "pick up where you left off" injection
 
-/** Returns how many entries survived the trim, which is what the receipt reports. */
-function writeHandoffs(handoffs: Record<string, HandoffEntry>): number {
-  const entries = Object.entries(handoffs);
-  const trimmed = entries.length > 20 ? Object.fromEntries(entries.slice(-20)) : handoffs;
-  writeFileSync(handoffPath(), JSON.stringify(trimmed, null, 2), "utf-8");
-  return Object.keys(trimmed).length;
-}
+Output: writes to memory/state/last-handoff.json keyed by cwd
+`;
 
-function writeHandoffNote(
-  cwd: string,
-  title: string,
-  text: string,
-  done: boolean
-): { file: string; status: HandoffEntry["status"]; kept: number } {
-  const handoffs = readHandoffs();
-  handoffs[cwd] = {
-    timestamp: new Date().toISOString(),
-    title,
-    status: done ? "completed" : "in-progress",
-    handoff: text,
-    artifacts: [],
-    source: "deliberate",
-  };
-  const kept = writeHandoffs(handoffs);
-  return { file: handoffPath(), status: handoffs[cwd].status, kept };
+function saveNote(note: NoteInput): void {
+  const file = handoffFile();
+  const store = recordNote(readHandoffs(file), note, new Date());
+  writeFileSync(file, JSON.stringify(store, null, 2), "utf-8");
+  emit.receipt(file, { status: statusOf(note), entries: Object.keys(store).length });
 }
 
 function run() {
@@ -72,37 +50,24 @@ function run() {
     options: {
       title: { type: "string" },
       text: { type: "string" },
+      waiting: { type: "string" },
       done: { type: "boolean" },
       help: { type: "boolean", short: "h" },
     },
   });
 
   if (values.help) {
-    console.log(`
-HandoffNote — Write a handoff note for the current project
-
-Usage:
-  bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains"
-  bun ~/.pal/tools/handoff-note.ts --done    # mark session completed
-
-Arguments:
-  --title   Brief title of what was being worked on (5-10 words)
-  --text    What remains unfinished — decisions made, next steps, blockers
-  --done    Mark as completed; suppresses "pick up where you left off" injection
-
-Output: writes to memory/state/last-handoff.json keyed by cwd
-`);
+    console.log(HELP);
     process.exit(0);
   }
 
   if (values.done) {
-    const result = writeHandoffNote(
-      process.cwd(),
-      values.title || "session",
-      values.text || "",
-      true
-    );
-    emit.receipt(result.file, { status: result.status, entries: result.kept });
+    saveNote({
+      cwd: process.cwd(),
+      title: values.title || "session",
+      text: values.text || "",
+      done: true,
+    });
     process.exit(0);
   }
 
@@ -111,8 +76,13 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
     process.exit(1);
   }
 
-  const result = writeHandoffNote(process.cwd(), values.title, values.text, false);
-  emit.receipt(result.file, { status: result.status, entries: result.kept });
+  saveNote({
+    cwd: process.cwd(),
+    title: values.title,
+    text: values.text,
+    done: false,
+    waitingOn: values.waiting,
+  });
 }
 
 if (import.meta.main) run();