portable-agent-layer 0.88.1 → 0.89.1

package/src/cli/ledger.ts

@@ -4,14 +4,8 @@
  * Thin presentation layer over src/tools/ledger/query.ts. Owns formatting and
  * argv parsing only; every question about the records themselves is answered
  * there.
- *
- * Subcommands:
- *   log [filters]     Matching actions, oldest first
- *   show <id>         One action in full, with its change and current standing
- *   stats [filters]   Counts by outcome, runtime, actor, tool and target
  */
 
-import { parseArgs } from "node:util";
 import type { LedgerEntry } from "../hooks/lib/ledger";
 import {
   type ChainVerdict,
@@ -28,75 +22,22 @@ import {
   standing,
   summarize,
 } from "../tools/ledger/query";
+import { UsageError } from "../tools/lib/command";
 
-const FILTER_OPTIONS = {
-  project: { type: "string" },
-  since: { type: "string" },
-  until: { type: "string" },
-  actor: { type: "string" },
-  machine: { type: "string" },
-  runtime: { type: "string" },
-  outcome: { type: "string" },
-  tool: { type: "string" },
-  target: { type: "string" },
-  limit: { type: "string" },
-  json: { type: "boolean" },
-} as const;
-
-export async function runLedger(args: string[]): Promise<number> {
-  const [sub, ...rest] = args;
-  switch (sub) {
-    case "log":
-      return cmdLog(rest);
-    case "show":
-      return cmdShow(rest);
-    case "stats":
-      return cmdStats(rest);
-    case undefined:
-    case "help":
-    case "--help":
-    case "-h":
-      showHelp();
-      return 0;
-    default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      showHelp();
-      return 1;
-  }
+export function ledgerLog(values: Record<string, unknown>): number {
+  return cmdLog(buildFilter(values), values.json === true);
 }
 
-function showHelp(): void {
-  console.log(`
-  Usage:
-    pal cli ledger <subcommand> [filters]
-
-  Subcommands:
-    log [filters]              Matching actions, oldest first
-    show <id>                  One action in full: change, target, standing
-    stats [filters]            Counts by outcome, runtime, actor, tool, target
-
-  Filters:
-    --project <slug>           Actions against a registered project
-    --since <7d|2026-09-01>    A duration back from now, or a date
-    --until <date>             Upper bound on the timestamp
-    --actor <id>               Who caused it
-    --machine <id>             Which install wrote it
-    --runtime <agent>          claude, cursor, codex, copilot, opencode
-    --outcome <applied|failed|denied>
-    --tool <Edit|Write>
-    --target <substring>       Match anywhere in the recorded path
-    --limit <n>                Keep the newest n matches
-    --json                     Machine-readable output
+export function ledgerShow(id: string, json: boolean): number {
+  return cmdShow(id, json);
+}
 
-  Examples:
-    pal cli ledger log --project portable-agent-layer --since 7d
-    pal cli ledger log --target memory/ --outcome applied
-    pal cli ledger stats --since 24h
-`);
+export function ledgerStats(values: Record<string, unknown>): number {
+  return cmdStats(buildFilter(values), values.json === true);
 }
 
 /** A filter that silently ignored an unparseable window would answer the wrong question. */
-function buildFilter(values: Record<string, unknown>): LedgerFilter | string {
+function buildFilter(values: Record<string, unknown>): LedgerFilter {
   const filter: LedgerFilter = {};
   for (const key of [
     "project",
@@ -115,43 +56,27 @@ function buildFilter(values: Record<string, unknown>): LedgerFilter | string {
     const spec = values[key];
     if (typeof spec !== "string") continue;
     const at = parseSince(spec);
-    if (!at) return `Unrecognised --${key}: ${spec} (use 7d, 24h, or a date)`;
+    if (!at)
+      throw new UsageError(`Unrecognised --${key}: ${spec} (use 7d, 24h, or a date)`);
     filter[key] = at;
   }
 
   if (typeof values.limit === "string") {
     const limit = Number(values.limit);
     if (!Number.isInteger(limit) || limit < 1)
-      return `--limit must be a positive integer`;
+      throw new UsageError("--limit must be a positive integer");
     filter.limit = limit;
   }
   return filter;
 }
 
-function parseFilters(args: string[]): { filter: LedgerFilter; json: boolean } | string {
-  try {
-    const { values } = parseArgs({
-      args,
-      options: FILTER_OPTIONS,
-      allowPositionals: true,
-    });
-    const filter = buildFilter(values);
-    return typeof filter === "string" ? filter : { filter, json: values.json === true };
-  } catch (error) {
-    return error instanceof Error ? error.message : String(error);
-  }
-}
-
 function shortId(id: string): string {
   return id.slice(0, 11).padEnd(11);
 }
 
-function cmdLog(args: string[]): number {
-  const parsed = parseFilters(args);
-  if (typeof parsed === "string") return fail(parsed);
-
-  const entries = queryLedger(parsed.filter);
-  if (parsed.json) {
+function cmdLog(filter: LedgerFilter, json: boolean): number {
+  const entries = queryLedger(filter);
+  if (json) {
     console.log(JSON.stringify(entries, null, 2));
     return 0;
   }
@@ -218,14 +143,11 @@ function printChange(entry: LedgerEntry): void {
   }
 }
 
-function cmdShow(args: string[]): number {
-  const [id, ...rest] = args;
-  if (!id) return fail("Usage: pal cli ledger show <id>");
-
+function cmdShow(id: string, json: boolean): number {
   const entry = findEntry(id);
   if (!entry) return fail(`No action with id ${id}`);
 
-  if (rest.includes("--json")) {
+  if (json) {
     console.log(
       JSON.stringify(
         {
@@ -280,12 +202,9 @@ function printTally(label: string, counts: Record<string, number>): void {
     console.log(`    ${String(count).padStart(6)}  ${key}`);
 }
 
-function cmdStats(args: string[]): number {
-  const parsed = parseFilters(args);
-  if (typeof parsed === "string") return fail(parsed);
-
-  const stats = summarize(queryLedger(parsed.filter));
-  if (parsed.json) {
+function cmdStats(filter: LedgerFilter, json: boolean): number {
+  const stats = summarize(queryLedger(filter));
+  if (json) {
     console.log(JSON.stringify(stats, null, 2));
     return 0;
   }

package/src/cli/personal-context.ts

@@ -1,10 +1,6 @@
 /**
  * pal cli telos / pal cli timezone — the personal context PAL carries about you.
  *
- *   pal cli telos             Which TELOS topics are answered, in interview order
- *   pal cli timezone          Show the configured timezone
- *   pal cli timezone <zone>   Set it, if Intl recognises the name
- *
  * Both exist for the onboarding skill. pal-settings.json is hook-protected, so
  * an agent cannot write the timezone itself, and a skill that restated the
  * answered/unanswered rule in prose would drift from the code that decides it.
@@ -18,14 +14,21 @@ import {
 import { telosStatus } from "../hooks/lib/telos-topics";
 import { canonicalTimeZone } from "../hooks/lib/wall-clock";
 import { log } from "../targets/lib";
+import { leaf } from "../tools/lib/command";
 
-export function runTelos(args: string[]): number {
-  if (args.length > 0) {
-    log.error(`Unknown telos argument: ${args[0]}`);
-    log.info("Usage: pal cli telos");
-    return 1;
-  }
+export const telosCommand = leaf({
+  summary: "Which TELOS topics are answered, in interview order",
+  run: printTelosStatus,
+});
+
+export const timezoneCommand = leaf({
+  summary: "Show the configured timezone, or set it to an IANA name",
+  args: "[zone...]",
+  details: "Example: pal cli timezone Europe/Budapest",
+  run: ({ positionals }) => timezone(positionals),
+});
 
+function printTelosStatus(): number {
   const topics = telosStatus();
   for (const topic of topics) {
     const mark = topic.answered ? "answered " : "unanswered";
@@ -39,8 +42,8 @@ export function runTelos(args: string[]): number {
   return 0;
 }
 
-export function runTimezone(args: string[]): number {
-  const requested = args.join(" ").trim();
+function timezone(words: string[]): number {
+  const requested = words.join(" ").trim();
 
   if (!requested) {
     const current = identity().principal.timezone;

package/src/cli/rule.ts

@@ -14,24 +14,39 @@ import {
   readRules,
   type TriggerProof,
 } from "../hooks/lib/adaptation-rules";
+import { group, leaf, runCommand } from "../tools/lib/command";
 
-const DECISIONS: Record<string, Exclude<RuleStatus, "draft">> = {
-  approve: "approved",
-  deny: "denied",
-};
+export const ruleCommand = group({
+  summary: "Review the rules PAL drafted from your corrections",
+  commands: {
+    list: leaf({
+      summary: "Drafts waiting for a decision",
+      options: {
+        all: { type: "boolean", description: "Every rule, not only the drafts" },
+        json: { type: "boolean", description: "Machine-readable output" },
+      },
+      run: ({ values }) => cmdList(values.all === true, values.json === true),
+    }),
+    approve: leaf({
+      summary: "Approve a draft so it steers",
+      args: "<id>",
+      run: ({ positionals }) => cmdDecide(positionals[0], "approved"),
+    }),
+    deny: leaf({
+      summary: "Deny a draft; it stays on record so it is not drafted again",
+      args: "<id>",
+      run: ({ positionals }) => cmdDecide(positionals[0], "denied"),
+    }),
+  },
+});
 
-export async function runRule(args: string[]): Promise<number> {
-  const [sub, ...rest] = args;
-  if (sub === "list") return cmdList(rest);
-  if (sub && sub in DECISIONS) return cmdDecide(rest[0], DECISIONS[sub]);
-  showHelp();
-  return sub === undefined || sub === "help" ? 0 : 1;
+export function runRule(args: string[]): Promise<number> {
+  return runCommand(ruleCommand, args, ["pal", "cli", "rule"]);
 }
 
-function cmdList(args: string[]): number {
-  const all = args.includes("--all");
+function cmdList(all: boolean, json: boolean): number {
   const rules = readRules().filter((r) => all || r.status === "draft");
-  if (args.includes("--json")) {
+  if (json) {
     console.log(JSON.stringify(rules, null, 2));
     return 0;
   }
@@ -64,14 +79,7 @@ function decisionLine(id: string, decision: string, rule: AdaptationRule): strin
   return `Rule ${rule.id} now triggers on: ${rule.trigger.pattern} (widened by ${id})`;
 }
 
-function cmdDecide(
-  id: string | undefined,
-  decision: Exclude<RuleStatus, "draft">
-): number {
-  if (!id) {
-    console.error("Give the rule id: pal cli rule approve|deny <id>");
-    return 1;
-  }
+function cmdDecide(id: string, decision: Exclude<RuleStatus, "draft">): number {
   const result = decideRule(id, decision);
   if (!result.ok) {
     console.error(result.reason);
@@ -80,11 +88,3 @@ function cmdDecide(
   console.log(decisionLine(id, decision, result.rule));
   return 0;
 }
-
-function showHelp(): void {
-  console.log(`pal cli rule — review adaptation rules drafted from your corrections
-
-  pal cli rule list [--all] [--json]   Drafts waiting for a decision
-  pal cli rule approve <id>            Approve a draft so it steers
-  pal cli rule deny <id>               Deny a draft; it is not drafted again`);
-}

package/src/cli/server.ts

@@ -8,11 +8,12 @@
 
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { spawnDetachedInference } from "../hooks/lib/detached-inference";
 import { paths } from "../hooks/lib/paths";
-import { DEFAULT_PORT, LOOPBACK, type ServerStatus } from "../tools/control-room/server";
+import type { ServerStatus } from "../tools/control-room/server";
+import { DEFAULT_PORT, LOOPBACK } from "../tools/control-room/server-config";
 import { BUILD_COMMAND, buildPage, isBuilt } from "../tools/control-room/static";
+import { group, leaf, UsageError } from "../tools/lib/command";
 
 interface ServerState {
   pid: number;
@@ -30,44 +31,29 @@ const SERVER_SCRIPT = resolve(
 const STARTUP_TIMEOUT_MS = 3000;
 const PROBE_TIMEOUT_MS = 500;
 
-export async function runServer(args: string[]): Promise<number> {
-  const [sub, ...rest] = args;
-  switch (sub) {
-    case "start":
-      return cmdStart(rest);
-    case "stop":
-      return cmdStop();
-    case "restart":
-      return cmdRestart();
-    case "status":
-      return cmdStatus();
-    case undefined:
-    case "help":
-    case "--help":
-    case "-h":
-      showHelp();
-      return 0;
-    default:
-      console.error(`Unknown subcommand: ${sub}\n`);
-      showHelp();
-      return 1;
-  }
-}
-
-function showHelp(): void {
-  console.log(`
-  Usage:
-    pal cli server <subcommand>
-
-  Subcommands:
-    start [--port <n>]         Start the control room in the background (default port ${DEFAULT_PORT})
-    stop                       Stop it
-    restart                    Replace a running one — the API only changes when the process does
-    status                     Show whether it is running, and where
-
-  The page listens on ${LOOPBACK} only.
-`);
-}
+export const serverCommand = group({
+  summary: "Start, stop and inspect the local control room",
+  details: `The page listens on ${LOOPBACK} only.`,
+  commands: {
+    start: leaf({
+      summary: "Start the control room in the background",
+      options: {
+        port: {
+          type: "string",
+          value: "<n>",
+          description: `Port to listen on (default ${DEFAULT_PORT})`,
+        },
+      },
+      run: ({ values }) => cmdStart(parsePort(values.port)),
+    }),
+    stop: leaf({ summary: "Stop it", run: cmdStop }),
+    restart: leaf({
+      summary: "Replace a running one — the API only changes when the process does",
+      run: cmdRestart,
+    }),
+    status: leaf({ summary: "Show whether it is running, and where", run: cmdStatus }),
+  },
+});
 
 function url(port: number): string {
   return `http://${LOOPBACK}:${port}/`;
@@ -122,19 +108,14 @@ async function waitUntilAnswering(port: number): Promise<ServerStatus | null> {
   return null;
 }
 
-function parsePort(args: string[]): number | string {
-  const { values } = parseArgs({ args, options: { port: { type: "string" } } });
-  if (values.port === undefined) return DEFAULT_PORT;
-  const port = Number(values.port);
-  return Number.isInteger(port) && port > 0 && port < 65536
-    ? port
-    : `--port must be a port number, got ${values.port}`;
+function parsePort(value: string | undefined): number {
+  if (value === undefined) return DEFAULT_PORT;
+  const port = Number(value);
+  if (Number.isInteger(port) && port > 0 && port < 65536) return port;
+  throw new UsageError(`--port must be a port number, got ${value}`);
 }
 
-async function cmdStart(args: string[]): Promise<number> {
-  const port = parsePort(args);
-  if (typeof port === "string") return fail(port);
-
+async function cmdStart(port: number): Promise<number> {
   const running = await runningServer();
   if (running) {
     console.log(`Already running at ${url(running.port)} (pid ${running.pid})`);
@@ -171,7 +152,7 @@ async function cmdRestart(): Promise<number> {
     return 0;
   }
   await cmdStop();
-  return cmdStart(["--port", String(running.port)]);
+  return cmdStart(running.port);
 }
 
 /**

package/src/cli/session-agent.ts

@@ -1,14 +1,12 @@
+import { AGENT_REGISTRY, LAUNCH_PRIORITY } from "../hooks/lib/agent-registry";
 import { findBinaryOnPath } from "../hooks/lib/which";
 
-const SESSION_AGENT_BINARIES = [
-  "claude",
-  "codex",
-  "cursor-agent",
-  "copilot",
-  "opencode",
-] as const;
+export type SessionAgent =
+  (typeof AGENT_REGISTRY)[(typeof LAUNCH_PRIORITY)[number]]["binary"];
 
-export type SessionAgent = (typeof SESSION_AGENT_BINARIES)[number];
+const SESSION_AGENT_BINARIES: readonly SessionAgent[] = LAUNCH_PRIORITY.map(
+  (agent) => AGENT_REGISTRY[agent].binary
+);
 
 export function findSessionAgent(): SessionAgent | null {
   return (
@@ -17,4 +15,4 @@ export function findSessionAgent(): SessionAgent | null {
 }
 
 export const NO_SESSION_AGENT_MESSAGE =
-  "No supported agent found. Install Claude Code, Codex, Cursor CLI, Copilot CLI or opencode.";
+  "No supported agent found. Install Claude Code, Codex, Cursor CLI, Copilot CLI, opencode or Antigravity CLI.";

package/src/cli/skill.ts

@@ -1,17 +1,7 @@
 /**
- * pal cli skill — manage personal skills under ~/.pal/skills/.
- *
- *   pal cli skill link <name>     Link an existing ~/.pal/skills/<name>/ into
- *                                 every installed agent so it is discoverable.
- *   pal cli skill doctor <name>   Evaluate ~/.pal/skills/<name>/ against the
- *                                 skill-authoring best practices.
- *   pal cli skill doctor --all    Evaluate every installed skill, one line each.
- *   pal cli skill author-model    Print the flagship model configured to author
- *                                 skills for the active agent (empty if none).
- *   pal cli skill run <skill> <tool> [-- args]
- *                                 Run ~/.pal/skills/<skill>/tools/<tool>, so a
- *                                 SKILL.md can name the tool instead of a path
- *                                 with a tilde no Windows shell expands.
+ * pal cli skill — manage personal skills under ~/.pal/skills/. `skill run`
+ * exists so a SKILL.md can name a tool instead of a path with a tilde no
+ * Windows shell expands.
  */
 
 import { spawnSync } from "node:child_process";
@@ -22,6 +12,7 @@ import { flagshipAuthorModel } from "../hooks/lib/models";
 import { withPalEnv } from "../hooks/lib/pal-env";
 import { isInside, palHome, palPkg } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
+import { group, leaf, UsageError } from "../tools/lib/command";
 import {
   formatReport,
   formatSummary,
@@ -105,60 +96,78 @@ function isShippedTool(path: string): boolean {
   return existsSync(shipped) && isInside(realpathSync(shipped), realpathSync(path));
 }
 
-export async function runSkill(args: string[]): Promise<number> {
-  const [sub, name] = args;
-
-  if (sub === "run") {
-    const [, skill, tool, ...rest] = args;
-    if (!skill || !tool) {
-      log.error("Usage: pal cli skill run <skill> <tool> [-- args]");
-      return 1;
-    }
-    return runSkillTool(skill, tool, rest[0] === "--" ? rest.slice(1) : rest);
-  }
-
-  if (sub === "author-model") {
-    const model = flagshipAuthorModel(getActiveAgent());
-    if (model) console.log(model);
-    return 0;
-  }
+function doctorOne(name: string): number {
+  const report = lintSkill(resolveSkillDir(name));
+  console.log(formatReport(report));
+  return report.errors > 0 ? 1 : 0;
+}
 
-  if (sub === "doctor") {
-    if (name === "--all") return doctorAll();
-    if (!name) {
-      log.error("Usage: pal cli skill doctor <skill-dir-or-name|--all>");
-      return 1;
-    }
-    const report = lintSkill(resolveSkillDir(name));
-    console.log(formatReport(report));
-    return report.errors > 0 ? 1 : 0;
-  }
+function doctor(name: string | undefined, all: boolean): number {
+  if (all && name) throw new UsageError("give a skill name or --all, not both");
+  if (all) return doctorAll();
+  if (!name) throw new UsageError("missing <name> (or --all)");
+  return doctorOne(name);
+}
 
-  if (sub === "link") {
-    if (!name) {
-      log.error("Usage: pal cli skill link <name>");
-      return 1;
-    }
-    try {
-      const linked = linkPersonalSkill(name);
-      if (linked.length === 0) {
-        log.warn(
-          `'${name}' linked to no per-skill agents (none installed). ` +
-            "It is still discoverable by opencode via ~/.pal/skills/."
-        );
-      } else {
-        log.success(
-          `Linked '${name}' into: ${linked.join(", ")} ` +
-            "(opencode: auto via ~/.pal/skills/)"
-        );
-      }
-      return 0;
-    } catch (e) {
-      log.error(e instanceof Error ? e.message : String(e));
-      return 1;
+function link(name: string): number {
+  try {
+    const linked = linkPersonalSkill(name);
+    if (linked.length === 0) {
+      log.warn(
+        `'${name}' linked to no per-skill agents (none installed). ` +
+          "It is still discoverable by opencode via ~/.pal/skills/."
+      );
+    } else {
+      log.success(
+        `Linked '${name}' into: ${linked.join(", ")} ` +
+          "(opencode: auto via ~/.pal/skills/)"
+      );
     }
+    return 0;
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : String(e));
+    return 1;
   }
+}
 
-  log.error("Usage: pal cli skill <run|link|doctor|author-model> [name|--all]");
-  return 1;
+export function printAuthorModel(): number {
+  const model = flagshipAuthorModel(getActiveAgent());
+  if (model) console.log(model);
+  return 0;
 }
+
+export const skillCommand = group({
+  summary: "Manage personal skills under ~/.pal/skills/",
+  commands: {
+    run: leaf({
+      summary:
+        "Run ~/.pal/skills/<skill>/tools/<tool>; every later argument goes to the tool",
+      args: "<skill> <tool>",
+      passThrough: true,
+      details:
+        "Arguments after <tool> reach the tool untouched; '--' before them is optional.",
+      run: ({ positionals, passedThrough }) =>
+        runSkillTool(positionals[0], positionals[1], passedThrough),
+    }),
+    link: leaf({
+      summary: "Link ~/.pal/skills/<name>/ into every installed agent",
+      args: "<name>",
+      run: ({ positionals }) => link(positionals[0]),
+    }),
+    doctor: leaf({
+      summary: "Check a skill against the skill-authoring best practices",
+      args: "[name]",
+      options: {
+        all: {
+          type: "boolean",
+          description: "Check every installed skill, one line each",
+        },
+      },
+      run: ({ positionals, values }) => doctor(positionals[0], values.all === true),
+    }),
+    "author-model": leaf({
+      summary: "Print the flagship model that authors skills for the active agent",
+      run: printAuthorModel,
+    }),
+  },
+});