portable-agent-layer 0.88.0 → 0.89.0

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

@@ -18,56 +18,60 @@
  * Which flags make which notes is in lib/note-flags.ts.
  */
 
-import { parseArgs } from "node:util";
 import { appendNotes } from "../../hooks/lib/relationship";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { emit } from "../lib/emit";
-import { notesFromFlags } from "../lib/note-flags";
+import { type NoteFlags, notesFromFlags } from "../lib/note-flags";
 import { scriptArgs } from "../lib/script-args";
 
-const HELP = `
-RelationshipNote — Append W/O/Session entries to today's relationship log
+const DETAILS = `Multiple flags may be combined in one call. At least one of --o, --w, --b is required.
 
-Usage:
+Examples:
   pal cli relationship-note --o "User prefers X" --confidence 0.80
   pal cli relationship-note --w "User is building X in TypeScript"
   pal cli relationship-note --b "Debugged the cache split logic"
 
-Flags:
-  --o TEXT          Opinion/behavioral observation about the user
-  --confidence N    Confidence for --o (0.0–1.0, default 0.75)
-  --w TEXT          World fact about the user's situation
-  --b TEXT          Session diary — what the assistant did (first-person)
+Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md`;
 
-Multiple flags may be combined in one call. At least one of --o, --w, --b is required.
-
-Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
-`;
-
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      o: { type: "string", multiple: true },
-      w: { type: "string", multiple: true },
-      b: { type: "string" },
-      confidence: { type: "string" },
-      help: { type: "boolean", short: "h" },
+export const command = leaf({
+  summary: "Append W/O/Session entries to today's relationship log",
+  options: {
+    o: {
+      type: "string",
+      multiple: true,
+      value: "<text>",
+      description: "Opinion/behavioral observation about the user (repeatable)",
     },
-  });
-
-  if (values.help) {
-    console.log(HELP);
-    process.exit(0);
-  }
+    confidence: {
+      type: "string",
+      value: "<n>",
+      description: "Confidence for --o (0.0–1.0, default 0.75)",
+    },
+    w: {
+      type: "string",
+      multiple: true,
+      value: "<text>",
+      description: "World fact about the user's situation (repeatable)",
+    },
+    b: {
+      type: "string",
+      value: "<text>",
+      description: "Session diary — what the assistant did (first-person)",
+    },
+  },
+  details: DETAILS,
+  run: ({ values }) => appendFromFlags(values),
+});
 
-  const result = notesFromFlags(values);
-  if ("error" in result) {
-    console.error(result.error);
-    process.exit(1);
-  }
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "relationship-note"]);
+}
 
+function appendFromFlags(flags: NoteFlags): undefined {
+  const result = notesFromFlags(flags);
+  if ("error" in result) throw new UsageError(result.error);
   const { file, written } = appendNotes(result.notes);
   emit.receipt(file, { written, deduped: result.notes.length - written });
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

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

@@ -15,9 +15,9 @@
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { readOpinions, saveOpinion, setLastReflectDate } from "../../hooks/lib/opinions";
 import { palHome } from "../../hooks/lib/paths";
+import { leaf, runCommand } from "../lib/command";
 import { emit } from "../lib/emit";
 import {
   consoleLines,
@@ -30,21 +30,27 @@ import {
 } from "../lib/relationship-reflect";
 import { scriptArgs } from "../lib/script-args";
 
-const HELP = `
-RelationshipReflect — Periodic reflection + opinion promotion
-
-Reads recent relationship notes and ratings. Promotes recurring
+const DETAILS = `Reads recent relationship notes and ratings. Promotes recurring
 observations (O type) into tracked opinions with confidence scoring.
-
-Usage:
-  pal cli relationship-reflect             Reflect on last 7 days (default)
-  pal cli relationship-reflect --month     Reflect on last 30 days
-  pal cli relationship-reflect --dry-run   Preview without writing
+With no flags, reflects on the last 7 days.
 
 Output:
   - Updates memory/relationship/opinions.json (confidence tracking)
-  - Creates reflection report in memory/relationship/reflections/
-`;
+  - Creates reflection report in memory/relationship/reflections/`;
+
+export const command = leaf({
+  summary: "Periodic reflection + opinion promotion",
+  options: {
+    month: { type: "boolean", description: "Reflect on last 30 days" },
+    "dry-run": { type: "boolean", description: "Preview without writing" },
+  },
+  details: DETAILS,
+  run: ({ values }) => reflect(values.month ?? false, values["dry-run"] ?? false),
+});
+
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "relationship-reflect"]);
+}
 
 const relationshipDir = () => resolve(palHome(), "memory", "relationship");
 const ratingsFile = () => resolve(palHome(), "memory", "signals", "ratings.jsonl");
@@ -57,24 +63,9 @@ function saveReport(report: string, period: string): string {
   return filepath;
 }
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      month: { type: "boolean" },
-      "dry-run": { type: "boolean" },
-      help: { type: "boolean", short: "h" },
-    },
-  });
-
-  if (values.help) {
-    console.log(HELP);
-    process.exit(0);
-  }
-
-  const daysBack = values.month ? 30 : 7;
-  const period = values.month ? "Monthly" : "Weekly";
-  const dryRun = values["dry-run"] ?? false;
+function reflect(month: boolean, dryRun: boolean): undefined {
+  const daysBack = month ? 30 : 7;
+  const period = month ? "Monthly" : "Weekly";
 
   const notes = loadNotes(relationshipDir(), daysBack);
   const ratings = loadRatings(ratingsFile(), daysBack);
@@ -84,7 +75,7 @@ export function run(argv: string[] = scriptArgs()) {
 
   if (notes.length === 0 && ratings.length === 0) {
     emit.ok("No data to analyze");
-    process.exit(0);
+    return;
   }
 
   const plan = planPromotions(notes, readOpinions());
@@ -109,4 +100,4 @@ export function run(argv: string[] = scriptArgs()) {
   for (const line of highConfidenceLines(readOpinions())) emit.ok(line);
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

package/src/tools/agent/synthesize.ts

@@ -15,8 +15,8 @@
 
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { scriptArgs } from "../lib/script-args";
 import { readJsonl } from "../lib/self-model";
 
@@ -304,33 +304,33 @@ export function synthesize(days: number): SynthesisState {
 
 // ── CLI ──
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      days: { type: "string", default: "7" },
-      force: { type: "boolean" },
-      help: { type: "boolean", short: "h" },
+export const command = leaf({
+  summary: "Aggregate recent PAL activity into compact state",
+  options: {
+    days: {
+      type: "string",
+      default: "7",
+      value: "<n>",
+      description: "Lookback window (default: 7)",
     },
-  });
-
-  if (values.help) {
-    console.log(`
-Synthesize — Aggregate recent PAL activity into compact state
-
-Usage:
-  synthesize.ts [--days 7] [--force]
-
-Options:
-  --days   Lookback window (default: 7)
-  --force  Skip 24h guard
+    force: { type: "boolean", description: "Skip 24h guard" },
+  },
+  details: "Output: ~/.pal/memory/state/synthesis.json",
+  run: ({ values }) =>
+    synthesizeUnlessFresh(lookbackDays(values.days), values.force ?? false),
+});
+
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "synthesize"]);
+}
 
-Output: ~/.pal/memory/state/synthesis.json
-`);
-    process.exit(0);
-  }
+function lookbackDays(raw: string): number {
+  const days = parseInt(raw, 10);
+  if (Number.isNaN(days)) throw new UsageError(`--days must be a number of days: ${raw}`);
+  return days;
+}
 
-  const force = values.force ?? false;
+function synthesizeUnlessFresh(days: number, force: boolean): undefined {
   if (!shouldRun(force)) {
     console.log(
       JSON.stringify({
@@ -341,7 +341,6 @@ Output: ~/.pal/memory/state/synthesis.json
     return;
   }
 
-  const days = parseInt(values.days ?? "7", 10);
   const state = synthesize(days);
   const sp = synthesisPath();
 
@@ -363,4 +362,4 @@ Output: ~/.pal/memory/state/synthesis.json
   );
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

package/src/tools/agent/thread.ts

@@ -11,7 +11,7 @@
  *   pal cli thread --list [--all]
  */
 
-import { parseArgs } from "node:util";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { emit } from "../lib/emit";
 import { scriptArgs } from "../lib/script-args";
 import {
@@ -23,20 +23,41 @@ import {
   writeThreads,
 } from "../lib/thread";
 
-const HELP = `
-Thread — Manage open threads across sessions
+const DETAILS = `Modes (one of --add, --resolve, --list is required):
+  pal cli thread --add --title "..." [--context "..."]
+  pal cli thread --resolve --id <id>
+  pal cli thread --list [--all]`;
 
-Usage:
-  thread.ts --add --title "..." [--context "..."]
-  thread.ts --resolve --id <id>
-  thread.ts --list [--all]
-`;
+export const command = leaf({
+  summary: "Manage open threads across sessions",
+  options: {
+    add: { type: "boolean", description: "Open a new thread (needs --title)" },
+    resolve: { type: "boolean", description: "Mark a thread resolved (needs --id)" },
+    list: { type: "boolean", description: "Print open threads as JSON" },
+    title: { type: "string", value: "<text>", description: "Title of the thread to add" },
+    context: {
+      type: "string",
+      value: "<text>",
+      description: "Why it matters, what needs to happen (with --add)",
+    },
+    id: { type: "string", value: "<id>", description: "Id of the thread to resolve" },
+    all: { type: "boolean", description: "Include resolved threads (with --list)" },
+  },
+  details: DETAILS,
+  run: ({ values }) => {
+    if (values.add) return add(values.title, values.context);
+    if (values.resolve) return markResolved(values.id);
+    if (values.list) return list(values.all ?? false);
+    throw new UsageError("one of --add, --resolve, --list is required");
+  },
+});
 
-function add(title: string | undefined, context: string | undefined) {
-  if (!title) {
-    console.error("--title required");
-    process.exit(1);
-  }
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "thread"]);
+}
+
+function add(title: string | undefined, context: string | undefined): undefined {
+  if (!title) throw new UsageError("--add needs --title");
   const thread = addThread(title, context ?? "");
   emit.receipt(threadsFile(), {
     id: thread.id,
@@ -45,52 +66,22 @@ function add(title: string | undefined, context: string | undefined) {
   });
 }
 
-function markResolved(id: string | undefined) {
-  if (!id) {
-    console.error("--id required");
-    process.exit(1);
-  }
+function markResolved(id: string | undefined): number {
+  if (!id) throw new UsageError("--resolve needs --id");
   const file = threadsFile();
   const resolution = resolveThreadIn(readThreads(file), id, new Date());
   if (!resolution) {
     console.error(`Thread not found: ${id}`);
-    process.exit(1);
+    return 1;
   }
   writeThreads(resolution.threads, file);
   emit.receipt(file, { id, status: "resolved", title: resolution.thread.title });
+  return 0;
 }
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      add: { type: "boolean" },
-      resolve: { type: "boolean" },
-      list: { type: "boolean" },
-      title: { type: "string" },
-      context: { type: "string" },
-      id: { type: "string" },
-      all: { type: "boolean" },
-      help: { type: "boolean", short: "h" },
-    },
-  });
-
-  let cmd: string | null = null;
-  if (values.add) cmd = "add";
-  else if (values.resolve) cmd = "resolve";
-  else if (values.list) cmd = "list";
-
-  if (values.help || !cmd) {
-    console.log(HELP);
-    process.exit(cmd ? 0 : 1);
-  }
-
-  if (cmd === "add") add(values.title, values.context);
-  if (cmd === "resolve") markResolved(values.id);
-  if (cmd === "list") {
-    const threads = visibleThreads(readThreads(), values.all ?? false);
-    emit.data(JSON.stringify({ count: threads.length, threads }, null, 2));
-  }
+function list(includeResolved: boolean): undefined {
+  const threads = visibleThreads(readThreads(), includeResolved);
+  emit.data(JSON.stringify({ count: threads.length, threads }, null, 2));
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

package/src/tools/agent/wisdom-frame.ts

@@ -7,18 +7,13 @@
  * evolution log. Principles are marked [CRYSTAL: N%] manually when
  * confidence is high enough.
  *
- * Usage:
- *   bun run tool:wisdom-frame --domain communication --observation "prefers bullet points"
- *   bun run tool:wisdom-frame --domain development --observation "refactoring without tests caused regressions" --type anti-pattern
- *   bun run tool:wisdom-frame --domain workflow --observation "always run type-check after edits" --type principle
- *
- * Types: principle, contextual-rule, anti-pattern, evolution (default)
+ * Usage: pal cli wisdom-frame --domain <domain> --observation "…" [--type <type>]
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
+import { leaf, runCommand, UsageError } from "../lib/command";
 import { emit } from "../lib/emit";
 import { scriptArgs } from "../lib/script-args";
 
@@ -193,23 +188,7 @@ ${antiPatternEntry}
 
 // ── CLI ──
 
-export function run(argv: string[] = scriptArgs()) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      domain: { type: "string", short: "d" },
-      observation: { type: "string", short: "o" },
-      type: { type: "string", short: "t" },
-      help: { type: "boolean", short: "h" },
-    },
-  });
-
-  if (values.help) {
-    console.log(`
-WisdomFrameUpdater — Update wisdom frames with observations
-
-Usage:
-  bun run tool:wisdom-frame --domain <domain> --observation "text" [--type <type>]
+const DETAILS = `Required: --domain and --observation.
 
 Domains:
   development, workflow, communication, infrastructure, integration, or any custom domain
@@ -221,21 +200,49 @@ Types:
   evolution        General observation (default)
 
 Examples:
-  bun run tool:wisdom-frame -d workflow -o "always run type-check after edits"
-  bun run tool:wisdom-frame -d development -o "mocking DB hides migration bugs" -t anti-pattern
-  bun run tool:wisdom-frame -d communication -o "user prefers terse summaries" -t principle
-`);
-    process.exit(0);
-  }
-
-  if (!values.domain || !values.observation) {
-    console.error("Required: --domain and --observation");
-    process.exit(1);
-  }
+  pal cli wisdom-frame -d workflow -o "always run type-check after edits"
+  pal cli wisdom-frame -d development -o "mocking DB hides migration bugs" -t anti-pattern
+  pal cli wisdom-frame -d communication -o "user prefers terse summaries" -t principle`;
+
+export const command = leaf({
+  summary: "Update wisdom frames with observations",
+  options: {
+    domain: {
+      type: "string",
+      short: "d",
+      value: "<domain>",
+      description: "Frame to update; created if it does not exist",
+    },
+    observation: {
+      type: "string",
+      short: "o",
+      value: "<text>",
+      description: "The observation to record",
+    },
+    type: {
+      type: "string",
+      short: "t",
+      value: "<type>",
+      description: "Observation type (default: evolution)",
+    },
+  },
+  details: DETAILS,
+  run: ({ values }) => {
+    const { domain, observation } = values;
+    if (!domain || !observation) {
+      throw new UsageError("--domain and --observation are required");
+    }
+    return recordObservation(domain, observation, values.type || "evolution");
+  },
+});
+
+export function run(argv: string[] = scriptArgs()): Promise<number> {
+  return runCommand(command, argv, ["pal", "cli", "wisdom-frame"]);
+}
 
-  const cliType = (values.type || "evolution") as ObservationType;
-  const result = updateFrame(values.domain, values.observation, cliType);
+function recordObservation(domain: string, observation: string, type: string): undefined {
+  const result = updateFrame(domain, observation, type as ObservationType);
   emit.receipt(result.framePath, { domain: result.domain, type: result.type });
 }
 
-if (import.meta.main) run();
+if (import.meta.main) process.exit(await run());

package/src/tools/control-room/server.ts

@@ -34,8 +34,6 @@ import {
   writeInstallSettings,
 } from "./writes";
 
-export { DEFAULT_PORT, LOOPBACK };
-
 /**
  * Every path the single-page app owns. Listed rather than wildcarded, because a
  * blanket "/*" outranks the fetch handler and would swallow /api as well.