portable-agent-layer 0.88.0 → 0.89.0

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

@@ -6,85 +6,93 @@
  * Records algorithm performance data after each LEARN phase.
  * Creates a queryable dataset for improving the algorithm over time.
  *
- * Usage:
- *   bun run tool:algorithm-reflect --task "description" --criteria 5 --passed 4 --failed 1 --sentiment 7 \
- *     --q1 "Should have read the file before planning" \
- *     --q2 "Could have parallelized the explore agents" \
- *     --q3 "Missed the implicit constraint about cross-platform"
+ * Usage: pal cli algorithm-reflect --task "…" --q1 "…" --q2 "…" --q3 "…" [options]
  */
 
 import { appendFileSync } from "node:fs";
-import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
 import { buildReflection, intOr, reflectionLine } from "../lib/algorithm-reflect";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { emit } from "../lib/emit";
 import { scriptArgs } from "../lib/script-args";
 
-const HELP = `
-AlgorithmReflect — Log algorithm performance after LEARN phase
+const DETAILS = `Required: --task, --q1, --q2, --q3.
 
-Usage:
-  bun run tool:algorithm-reflect --task "description" --criteria N --passed N --failed N --sentiment 1-10 \\
+Example:
+  pal cli 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/`;
 
-Output: algorithm-reflections.jsonl in memory/learning/reflections/
-`;
+const REQUIRED = ["task", "q1", "q2", "q3"] as const;
 
-function reflectionsPath(): string {
-  paths.reflections();
-  return paths.reflectionsFile();
-}
-
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      task: { type: "string" },
-      criteria: { type: "string" },
-      passed: { type: "string" },
-      failed: { type: "string" },
-      sentiment: { type: "string" },
-      q1: { type: "string" },
-      q2: { type: "string" },
-      q3: { type: "string" },
-      scope: { type: "string" },
-      help: { type: "boolean", short: "h" },
+export const command = leaf({
+  summary: "Log algorithm performance after the LEARN phase",
+  options: {
+    task: { type: "string", value: "<text>", description: "Brief task description" },
+    criteria: { type: "string", value: "<n>", description: "Total criteria count" },
+    passed: { type: "string", value: "<n>", description: "Criteria passed" },
+    failed: { type: "string", value: "<n>", description: "Criteria failed" },
+    sentiment: {
+      type: "string",
+      value: "<1-10>",
+      description: "Implied satisfaction 1-10",
     },
-  });
+    q1: {
+      type: "string",
+      value: "<text>",
+      description: "Q1 — Self: what I'd do differently",
+    },
+    q2: {
+      type: "string",
+      value: "<text>",
+      description: "Q2 — Algorithm: structural improvement",
+    },
+    q3: { type: "string", value: "<text>", description: "Q3 — AI: reasoning blind spot" },
+    scope: {
+      type: "string",
+      value: "<scope>",
+      description:
+        "general (default) | task-specific — is the algorithm idea reusable or task-bound?",
+    },
+  },
+  details: DETAILS,
+  run: ({ values }) => {
+    const { task, q1, q2, q3 } = values;
+    if (!task || !q1 || !q2 || !q3) throw new UsageError(missingRequired(values));
+    return appendReflection(
+      buildReflection({
+        task,
+        q1,
+        q2,
+        q3,
+        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,
+      })
+    );
+  },
+});
 
-  if (values.help) {
-    console.log(HELP);
-    process.exit(0);
-  }
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "algorithm-reflect"]);
+}
 
-  if (!values.task || !values.q1 || !values.q2 || !values.q3) {
-    console.error("Required: --task, --q1, --q2, --q3");
-    process.exit(1);
-  }
+function missingRequired(
+  values: Partial<Record<(typeof REQUIRED)[number], string>>
+): string {
+  const missing = REQUIRED.filter((name) => !values[name]).map((name) => `--${name}`);
+  return `missing ${missing.join(", ")}`;
+}
 
-  const reflection = buildReflection({
-    task: values.task,
-    q1: values.q1,
-    q2: values.q2,
-    q3: values.q3,
-    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,
-  });
+function reflectionsPath(): string {
+  paths.reflections();
+  return paths.reflectionsFile();
+}
 
+function appendReflection(reflection: ReturnType<typeof buildReflection>): undefined {
   const path = reflectionsPath();
   appendFileSync(path, reflectionLine(reflection), "utf-8");
   emit.receipt(path, {
@@ -94,4 +102,4 @@ export function run(argv: string[] = scriptArgs()) {
   });
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

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

@@ -14,12 +14,12 @@
  * invisible even when (especially when) the keyword sort misses or mis-sorts it.
  *
  * Library:  import { synthesizeAlgorithm, formatAlgorithmReport } from ".../algorithm-synthesize"
- * Script:   bun src/tools/agent/algorithm-synthesize.ts [--since <ISO>] [--json]
+ * Script:   pal cli algorithm-synthesize [--since <ISO>] [--json]
  */
 
-import { parseArgs } from "node:util";
 import { readReflections } from "../../hooks/lib/learning-store";
 import { paths } from "../../hooks/lib/paths";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { scriptArgs } from "../lib/script-args";
 
 /** Algorithm areas a Q2 idea can target, mapped to ALGORITHM.md structure. */
@@ -203,19 +203,44 @@ export function formatAlgorithmReport(s: AlgorithmSynthesis): string {
   return lines.join("\n");
 }
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      since: { type: "string" },
-      json: { type: "boolean", default: false },
+const DETAILS = `Reads the Q2 field ("what a smarter algorithm would have done") of every
+algorithm reflection and pre-sorts it into candidate areas of ALGORITHM.md. The
+buckets are a keyword hint only: every Q2 they miss is listed in full under
+"Unbucketed", and task-specific Q2s are listed separately.`;
+
+export const command = leaf({
+  summary: "Cluster algorithm reflections into candidate ALGORITHM.md changes",
+  options: {
+    since: {
+      type: "string",
+      value: "<iso-date>",
+      description: "Only reflections from this date on (default: all time)",
     },
-  });
-  const since = values.since ? new Date(values.since) : undefined;
+    json: {
+      type: "boolean",
+      default: false,
+      description: "Print the full synthesis as JSON instead of the report",
+    },
+  },
+  details: DETAILS,
+  run: ({ values }) => printSynthesis(sinceDate(values.since), values.json),
+});
+
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "algorithm-synthesize"]);
+}
+
+function sinceDate(raw: string | undefined): Date | undefined {
+  if (raw === undefined) return undefined;
+  const since = new Date(raw);
+  if (Number.isNaN(since.getTime()))
+    throw new UsageError(`--since is not a date: ${raw}`);
+  return since;
+}
+
+function printSynthesis(since: Date | undefined, asJson: boolean): undefined {
   const result = synthesizeAlgorithm(since);
-  console.log(
-    values.json ? JSON.stringify(result, null, 2) : formatAlgorithmReport(result)
-  );
+  console.log(asJson ? JSON.stringify(result, null, 2) : formatAlgorithmReport(result));
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

package/src/tools/agent/analyze.ts

@@ -7,53 +7,48 @@
  *
  * What the report says is in lib/analyze-report.ts.
  *
- * Usage: bun run tool:analyze
+ * Usage: pal cli analyze [--actionable]
  */
 
-import { parseArgs } from "node:util";
 import { writeLastAnalyzeDate } from "../../hooks/lib/analyze-nudge";
 import { analyze } from "../../hooks/lib/graduation";
 import { reportLines } from "../lib/analyze-report";
+import { leaf, runCommand } from "../lib/command";
 import { scriptArgs } from "../lib/script-args";
 
-const HELP = `
-  PAL Learning Analysis — unified graduation + ratings report
-
-  Reads all captured failures (rating ≤3) and session learnings,
-  groups recurring patterns via Dice 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: pal cli analyze [--actionable]
-`;
-
-export async function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      help: { type: "boolean", short: "h" },
-      actionable: { type: "boolean", short: "a" },
+const DETAILS = `Reads all captured failures (rating ≤3) and session learnings,
+groups recurring patterns via Dice 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
+
+To crystallize a graduated pattern, add it to the target wisdom frame:
+  - Your principle here [CRYSTAL: 85%]`;
+
+export const command = leaf({
+  summary: "PAL Learning Analysis — unified graduation + ratings report",
+  options: {
+    actionable: {
+      type: "boolean",
+      short: "a",
+      description: "Generate actionable recommendations via Haiku inference",
     },
-  });
+  },
+  details: DETAILS,
+  run: ({ values }) => printAnalysis(values.actionable),
+});
 
-  if (values.help) {
-    console.log(HELP);
-    process.exit(0);
-  }
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "analyze"]);
+}
 
-  const result = await analyze({ actionable: values.actionable });
+async function printAnalysis(actionable: boolean | undefined): Promise<undefined> {
+  const result = await analyze({ actionable });
   for (const line of reportLines(result)) console.log(line);
   writeLastAnalyzeDate(new Date().toISOString());
 }
 
-if (import.meta.main) await run();
+if (import.meta.main) process.exit(await run());

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

@@ -11,7 +11,7 @@
  */
 
 import { writeFileSync } from "node:fs";
-import { parseArgs } from "node:util";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { emit } from "../lib/emit";
 import {
   handoffFile,
@@ -22,68 +22,65 @@ import {
 } from "../lib/handoff-note";
 import { scriptArgs } from "../lib/script-args";
 
-const HELP = `
-HandoffNote — Write a handoff note for the current project
+const DETAILS = `Required: --title and --text, or --done to close.
 
-Usage:
+Examples:
   pal cli handoff-note --title "what we were doing" --text "what remains"
   pal cli handoff-note --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
-  --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
+Output: writes to memory/state/last-handoff.json keyed by cwd`;
 
-Output: writes to memory/state/last-handoff.json keyed by cwd
-`;
+export const command = leaf({
+  summary: "Write a handoff note for the current project",
+  options: {
+    title: {
+      type: "string",
+      value: "<text>",
+      description: "Brief title of what was being worked on (5-10 words)",
+    },
+    text: {
+      type: "string",
+      value: "<text>",
+      description: "What remains unfinished — decisions made, next steps, blockers",
+    },
+    waiting: {
+      type: "string",
+      value: "<text>",
+      description:
+        "What this needs from you before it can move (a decision, an answer, access)",
+    },
+    done: {
+      type: "boolean",
+      description: `Mark as completed; suppresses "pick up where you left off" injection`,
+    },
+  },
+  details: DETAILS,
+  run: ({ values }) => {
+    const { title, text, waiting, done } = values;
+    if (done) {
+      return saveNote({
+        cwd: process.cwd(),
+        title: title || "session",
+        text: text || "",
+        done: true,
+      });
+    }
+    if (!title || !text) {
+      throw new UsageError("--title and --text are required (or --done to close)");
+    }
+    return saveNote({ cwd: process.cwd(), title, text, done: false, waitingOn: waiting });
+  },
+});
 
-function saveNote(note: NoteInput): void {
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "handoff-note"]);
+}
+
+function saveNote(note: NoteInput): undefined {
   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 });
 }
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      title: { type: "string" },
-      text: { type: "string" },
-      waiting: { type: "string" },
-      done: { type: "boolean" },
-      help: { type: "boolean", short: "h" },
-    },
-  });
-
-  if (values.help) {
-    console.log(HELP);
-    process.exit(0);
-  }
-
-  if (values.done) {
-    saveNote({
-      cwd: process.cwd(),
-      title: values.title || "session",
-      text: values.text || "",
-      done: true,
-    });
-    process.exit(0);
-  }
-
-  if (!values.title || !values.text) {
-    console.error("Required: --title and --text (or --done to close)");
-    process.exit(1);
-  }
-
-  saveNote({
-    cwd: process.cwd(),
-    title: values.title,
-    text: values.text,
-    done: false,
-    waitingOn: values.waiting,
-  });
-}
-
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

package/src/tools/agent/interaction.ts

@@ -6,42 +6,46 @@
  * Usage: pal cli interaction report [--days N]
  */
 
-import { parseArgs } from "node:util";
 import { claimChecksSince } from "../../hooks/lib/claim-log";
 import { turnsSince } from "../../hooks/lib/interaction";
+import { group, leaf, runCommand, UsageError } from "../lib/command";
 import { claimCheckLines, reportLines, summarize } from "../lib/interaction-report";
 import { scriptArgs } from "../lib/script-args";
 
-const HELP = `
-  PAL Interaction report
+const DETAILS = `Reads the measured turns in memory/signals/interaction/ (features only, no
+text) and prints turns, channels, reactions, the hints sent, per agent the
+turns, replies filed and hints sent, and for each label (short, long, fast,
+skimming, friction) how the replies written while it was active compare with
+the replies written while none was. Last, the replies that claimed a result
+(memory/signals/claim-checks/), and which of them had no command behind the
+claim or were sent back.`;
 
-  Reads the measured turns in memory/signals/interaction/ (features only, no
-  text) and prints turns, channels, reactions, the hints sent, per agent the
-  turns, replies filed and hints sent, and for each
-  label (short, long, fast, skimming, friction) how the replies written while
-  it was active compare with the replies written while none was. Last, the
-  replies that claimed a result (memory/signals/claim-checks/), and which of
-  them had no command behind the claim or were sent back.
+const DAY_MS = 86_400_000;
 
-  Usage: pal cli interaction report [--days N]   (default 7)
-`;
+export const command = group({
+  summary: "How the user's turns went, and whether replies changed under each label",
+  commands: {
+    report: leaf({
+      summary: "Print the interaction report",
+      options: {
+        days: {
+          type: "string",
+          value: "<n>",
+          description: "Days to look back (default 7)",
+        },
+      },
+      details: DETAILS,
+      run: ({ values }) => printReport(Number(values.days ?? "7")),
+    }),
+  },
+});
 
-const DAY_MS = 86_400_000;
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "interaction"]);
+}
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    allowPositionals: true,
-    options: {
-      help: { type: "boolean", short: "h" },
-      days: { type: "string", default: "7" },
-    },
-  });
-  const days = Number(values.days);
-  if (values.help || positionals[0] !== "report" || !(days > 0)) {
-    console.log(HELP);
-    return;
-  }
+function printReport(days: number): undefined {
+  if (!(days > 0)) throw new UsageError("--days must be a positive number");
   const since = new Date(Date.now() - days * DAY_MS);
   const events = turnsSince(since);
   const claims = claimCheckLines(claimChecksSince(since));
@@ -49,4 +53,4 @@ export function run(argv: string[] = scriptArgs()) {
     console.log(line);
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());