portable-agent-layer 0.88.0 → 0.89.0

package/src/tools/control-room/ui/dist/index.html

@@ -10,7 +10,7 @@
       rel="stylesheet"
       href="https://fonts.googleapis.com/css2?family=Barlow:wght@400;500;600&family=Barlow+Condensed:wght@400;500;600&display=swap"
     />
-    <script type="module" crossorigin src="/assets/index-BZMDzWFa.js"></script>
+    <script type="module" crossorigin src="/assets/index-mFpXpiBj.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DeglMbfS.css">
   </head>
   <body>

package/src/tools/control-room/ui/screens/log.tsx

@@ -1,4 +1,5 @@
 import { useId, useState } from "react";
+import type { AgentName } from "../../../../hooks/lib/agent-registry";
 import { PAGE_OUTCOMES, type PageOutcome } from "../../../ledger/outcomes";
 import type { LedgerView, LedgerViewRow } from "../../../ledger/view";
 import { Badge } from "../components/badge";
@@ -42,7 +43,15 @@ export const LOG_KEYS = [
 export type LogFilter = Record<(typeof LOG_KEYS)[number], string>;
 
 const AUTHORITIES = ["user", "agent"] as const;
-const RUNTIMES = ["claude", "cursor", "codex", "copilot", "opencode", "unknown"] as const;
+const RUNTIMES = Object.keys({
+  claude: true,
+  cursor: true,
+  codex: true,
+  copilot: true,
+  opencode: true,
+  antigravity: true,
+  unknown: true,
+} satisfies Record<AgentName | "unknown", true>);
 
 const EMPTY_FILTER: LogFilter = {
   project: "",

package/src/tools/lib/command.ts

@@ -0,0 +1,275 @@
+/**
+ * The `pal cli` command tree. A command declares its arguments and flags once;
+ * that declaration drives the parser, the `--help` page and the error a wrong
+ * call gets, so the three cannot drift apart.
+ */
+
+import { type ParseArgsOptionDescriptor, parseArgs } from "node:util";
+
+export interface OptionSpec extends ParseArgsOptionDescriptor {
+  description: string;
+  value?: string;
+}
+
+export type OptionSpecs = Record<string, OptionSpec>;
+
+type ParsedValues<O extends OptionSpecs> = ReturnType<
+  typeof parseArgs<{ options: O; allowPositionals: true; strict: true }>
+>["values"];
+
+export interface CommandInput<O extends OptionSpecs = OptionSpecs> {
+  values: ParsedValues<O>;
+  positionals: string[];
+  passedThrough: string[];
+  argv: string[];
+}
+
+export interface LeafSpec<O extends OptionSpecs> {
+  summary: string;
+  args?: string;
+  options?: O;
+  details?: string;
+  passThrough?: boolean;
+  run(input: CommandInput<O>): unknown;
+}
+
+export interface Leaf extends Omit<LeafSpec<OptionSpecs>, "run"> {
+  kind: "leaf";
+  run(input: CommandInput): unknown;
+}
+
+export interface Group {
+  kind: "group";
+  summary: string;
+  commands: Record<string, Command>;
+  aliases?: Record<string, string>;
+  fallback?: string;
+  details?: string;
+}
+
+export type Command = Leaf | Group;
+
+export class UsageError extends Error {}
+
+export function leaf<const O extends OptionSpecs = Record<never, OptionSpec>>(
+  spec: LeafSpec<O>
+): Leaf {
+  return { kind: "leaf", ...spec } as unknown as Leaf;
+}
+
+export function group(spec: Omit<Group, "kind">): Group {
+  return { kind: "group", ...spec };
+}
+
+const HELP_FLAGS = new Set(["-h", "--help"]);
+const HELP_OPTION: OptionSpec = {
+  type: "boolean",
+  short: "h",
+  description: "Show this help",
+};
+
+export async function runCommand(
+  command: Command,
+  args: string[],
+  path: string[]
+): Promise<number> {
+  return command.kind === "group"
+    ? runGroup(command, args, path)
+    : runLeaf(command, args, path);
+}
+
+async function runGroup(command: Group, args: string[], path: string[]): Promise<number> {
+  const [first, ...rest] = args;
+  const name = first === undefined ? command.fallback : first;
+  if (name === undefined || name === "help" || HELP_FLAGS.has(name)) {
+    console.log(helpText(command, path));
+    return 0;
+  }
+  const resolved = command.aliases?.[name] ?? name;
+  const sub = command.commands[resolved];
+  if (!sub) return usageFailure(`unknown command '${name}'`, command, path);
+  return runCommand(sub, rest, [...path, resolved]);
+}
+
+async function runLeaf(command: Leaf, args: string[], path: string[]): Promise<number> {
+  const { head, passedThrough } = splitPassThrough(command, args);
+  if (head.some((arg) => HELP_FLAGS.has(arg))) {
+    console.log(helpText(command, path));
+    return 0;
+  }
+  try {
+    const { values, positionals } = parseWithTextShielded(head, command.options ?? {});
+    checkPositionals(command.args, positionals);
+    return exitCode(
+      await command.run({ values, positionals, passedThrough, argv: head })
+    );
+  } catch (error) {
+    if (!isUsageError(error)) throw error;
+    const message =
+      error instanceof UsageError ? error.message : firstSentence(error.message);
+    return usageFailure(message, command, path);
+  }
+}
+
+const SHIELD = "\u0000text:";
+
+function isFreeText(arg: string): boolean {
+  return /\s/.test(arg);
+}
+
+function parseWithTextShielded(args: string[], options: OptionSpecs) {
+  const unshield = (value: string) =>
+    value.startsWith(SHIELD)
+      ? (args[Number(value.slice(SHIELD.length))] ?? value)
+      : value;
+  const unshieldValue = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(unshieldValue);
+    return typeof value === "string" ? unshield(value) : value;
+  };
+  const parsed = parseArgs({
+    args: args.map((arg, index) => (isFreeText(arg) ? `${SHIELD}${index}` : arg)),
+    options,
+    allowPositionals: true,
+    strict: true,
+  });
+  const values = Object.fromEntries(
+    Object.entries(parsed.values).map(([key, value]) => [key, unshieldValue(value)])
+  ) as typeof parsed.values;
+  return { values, positionals: parsed.positionals.map(unshield) };
+}
+
+function exitCode(result: unknown): number {
+  return typeof result === "number" ? result : 0;
+}
+
+function firstSentence(message: string): string {
+  return message.split(/\.\s/)[0] ?? message;
+}
+
+function splitPassThrough(
+  command: Leaf,
+  args: string[]
+): { head: string[]; passedThrough: string[] } {
+  const at = command.passThrough
+    ? passThroughStart(args, argSlots(command.args))
+    : args.length;
+  const tail = args.slice(at);
+  return {
+    head: args.slice(0, at),
+    passedThrough: tail[0] === "--" ? tail.slice(1) : tail,
+  };
+}
+
+function passThroughStart(args: string[], slots: ArgSlot[]): number {
+  let filled = 0;
+  for (const [index, arg] of args.entries()) {
+    if (arg === "--") return index;
+    if (!arg.startsWith("-")) filled += 1;
+    if (filled === slots.length) return index + 1;
+  }
+  return args.length;
+}
+
+function isUsageError(error: unknown): error is Error {
+  if (error instanceof UsageError) return true;
+  const code = (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" && code.startsWith("ERR_PARSE_ARGS_");
+}
+
+function usageFailure(message: string, command: Command, path: string[]): number {
+  console.error(`error: ${message}\n\n${helpText(command, path)}`);
+  return 1;
+}
+
+interface ArgSlot {
+  name: string;
+  required: boolean;
+  variadic: boolean;
+}
+
+function argSlots(synopsis: string | undefined): ArgSlot[] {
+  return (synopsis ?? "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((token) => ({
+      name: token,
+      required: token.startsWith("<"),
+      variadic: token.includes("..."),
+    }));
+}
+
+function checkPositionals(synopsis: string | undefined, positionals: string[]): void {
+  const slots = argSlots(synopsis);
+  const missing = slots.filter((slot) => slot.required)[positionals.length];
+  if (missing) throw new UsageError(`missing ${missing.name}`);
+  if (slots.some((slot) => slot.variadic)) return;
+  const extra = positionals[slots.length];
+  if (extra !== undefined) throw new UsageError(`unexpected argument '${extra}'`);
+}
+
+export function helpText(command: Command, path: string[]): string {
+  return command.kind === "group" ? groupHelp(command, path) : leafHelp(command, path);
+}
+
+function leafHelp(command: Leaf, path: string[]): string {
+  const options = { ...command.options, help: HELP_OPTION };
+  const synopsis = [
+    ...path,
+    ...(command.args ? [command.args] : []),
+    ...(command.options && Object.keys(command.options).length ? ["[options]"] : []),
+    ...(command.passThrough ? ["[<passed-on>...]"] : []),
+  ].join(" ");
+  const rows = Object.entries(options).map(
+    ([name, spec]) => [optionLabel(name, spec), spec.description] as const
+  );
+  return [
+    `Usage: ${synopsis}`,
+    "",
+    `  ${command.summary}`,
+    "",
+    "Options:",
+    ...table(rows),
+    ...(command.details ? ["", command.details.trimEnd()] : []),
+  ].join("\n");
+}
+
+function optionLabel(name: string, spec: OptionSpec): string {
+  const short = spec.short ? `-${spec.short}, ` : "";
+  const value = spec.type === "string" ? ` ${spec.value ?? "<value>"}` : "";
+  return `${short}--${name}${value}`;
+}
+
+function groupHelp(command: Group, path: string[]): string {
+  const placeholder = command.fallback ? "[<command>]" : "<command>";
+  const rows = Object.entries(command.commands).map(
+    ([name, sub]) => [commandLabel(name, sub, command), sub.summary] as const
+  );
+  const fallbackNote = command.fallback
+    ? [`With no command, runs '${command.fallback}'.`]
+    : [];
+  return [
+    `Usage: ${[...path, placeholder].join(" ")}`,
+    "",
+    `  ${command.summary}`,
+    "",
+    "Commands:",
+    ...table(rows),
+    "",
+    ...fallbackNote,
+    `Run '${path.join(" ")} <command> --help' for its arguments and options.`,
+    ...(command.details ? ["", command.details.trimEnd()] : []),
+  ].join("\n");
+}
+
+function commandLabel(name: string, sub: Command, parent: Group): string {
+  const aliases = Object.entries(parent.aliases ?? {})
+    .filter(([, target]) => target === name)
+    .map(([alias]) => alias);
+  const names = [name, ...aliases].join(" | ");
+  return sub.kind === "leaf" && sub.args ? `${names} ${sub.args}` : names;
+}
+
+function table(rows: readonly (readonly [string, string])[]): string[] {
+  const width = Math.max(...rows.map(([label]) => label.length));
+  return rows.map(([label, text]) => `  ${label.padEnd(width)}  ${text}`);
+}

package/src/tools/subagent-doctor.ts

@@ -2,7 +2,7 @@
  * subagent-doctor — static evaluator for a personal subagent definition
  * (~/.pal/agents/<name>.md) with merged multi-platform frontmatter. Checks only
  * what is mechanically verifiable: name/description constraints, per-platform
- * blocks (claude/opencode/cursor/copilot/codex), model/tools/permission shape, body
+ * blocks (one per agent), model/tools/permission shape, body
  * length, and absolute-path portability.
  *
  * Library:  import { lintSubagent, formatSubagentReport } from ".../subagent-doctor"
@@ -13,11 +13,8 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import {
-  AGENT_PLATFORMS,
-  type AgentPlatform,
-  parseAgentDefinition,
-} from "../hooks/lib/agent-definition";
+import { parseAgentDefinition } from "../hooks/lib/agent-definition";
+import { AGENT_NAMES, type AgentName } from "../hooks/lib/agent-registry";
 import { assets, namesAPath, palHome, toPath } from "../hooks/lib/paths";
 
 type Level = "pass" | "warn" | "error";
@@ -42,7 +39,7 @@ interface ParsedSubagent {
   description: string | null;
   descriptionQuoted: boolean;
   global: string[];
-  platforms: Partial<Record<AgentPlatform, string[]>>;
+  platforms: Partial<Record<AgentName, string[]>>;
   body: string;
 }
 
@@ -58,6 +55,29 @@ const OPENCODE_MODES = ["subagent", "primary", "all"];
 const CODEX_SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"];
 const CODEX_TABLE_KEYS = ["tools", "skills"];
 const SHARED_FIELDS = ["name", "description"];
+const ANTIGRAVITY_MODELS = ["inherit", "flash", "pro"];
+const ANTIGRAVITY_TOOLS = [
+  "view_file",
+  "write_to_file",
+  "replace_file_content",
+  "multi_replace_file_content",
+  "list_dir",
+  "find_by_name",
+  "grep_search",
+  "search_web",
+  "read_url_content",
+  "run_command",
+  "manage_task",
+  "schedule",
+  "list_permissions",
+  "ask_permission",
+  "invoke_subagent",
+  "define_subagent",
+  "send_message",
+  "manage_subagents",
+  "ask_question",
+  "generate_image",
+];
 
 /** Machine/user-specific absolute paths that will not survive an export. */
 const ABSOLUTE_PATH_RE =
@@ -200,6 +220,49 @@ function checkCodexBlock(lines: string[], add: AddFinding): void {
   }
 }
 
+function checkAntigravityBlock(lines: string[], add: AddFinding): void {
+  const model = fieldValue(lines, "model");
+  if (model !== null && !ANTIGRAVITY_MODELS.includes(model)) {
+    add(
+      "warn",
+      "antigravity.model",
+      `model "${model}" — expected one of ${ANTIGRAVITY_MODELS.join(", ")}`
+    );
+  }
+  checkAntigravityTools(antigravityTools(lines), add);
+}
+
+function antigravityTools(lines: string[]): unknown {
+  try {
+    return (Bun.YAML.parse(lines.join("\n")) as { tools?: unknown } | null)?.tools;
+  } catch {
+    return "unparseable";
+  }
+}
+
+function checkAntigravityTools(tools: unknown, add: AddFinding): void {
+  if (tools === undefined || tools === null || (Array.isArray(tools) && !tools.length)) {
+    add(
+      "warn",
+      "antigravity.tools",
+      "no `tools` — Antigravity gives the subagent no tools at all; list the ones it needs"
+    );
+    return;
+  }
+  if (!Array.isArray(tools) || !tools.every((t) => typeof t === "string")) {
+    add("error", "antigravity.tools", "`tools` must be a YAML list of tool names");
+    return;
+  }
+  const unknown = tools.filter((t) => !ANTIGRAVITY_TOOLS.includes(t));
+  unknown.length > 0
+    ? add(
+        "error",
+        "antigravity.tools",
+        `unknown tool(s) ${unknown.join(", ")} — an unmapped tool name can hang the subagent; use Antigravity names such as run_command, view_file, search_web`
+      )
+    : add("pass", "antigravity.tools", `${tools.length} known tool(s)`);
+}
+
 function validateModel(model: string, platform: string, add: AddFinding): void {
   const known = KNOWN_MODELS.includes(model) || /^(claude-|gpt-|o\d|gemini-)/.test(model);
   if (!known) {
@@ -321,13 +384,14 @@ export function lintSubagent(file: string): SubagentReport {
   }
 
   // ── platform blocks ──
-  const present = AGENT_PLATFORMS.filter((p) => (platforms[p]?.length ?? 0) > 0);
+  const present = AGENT_NAMES.filter((p) => (platforms[p]?.length ?? 0) > 0);
+  const blockKeys = AGENT_NAMES.map((p) => p.concat(":")).join("/");
   present.length > 0
     ? add("pass", "platforms", `defines block(s): ${present.join(", ")}`)
     : add(
         "warn",
         "platforms",
-        "no platform block — the subagent installs with only name/description; add a claude:/opencode:/cursor:/copilot:/codex: block to set model, tools, mode"
+        `no platform block — the subagent installs with only name/description; add a ${blockKeys} block to set model, tools, mode`
       );
 
   if (platforms.claude) checkClaudeBlock(platforms.claude, add);
@@ -335,6 +399,7 @@ export function lintSubagent(file: string): SubagentReport {
   if (platforms.cursor) checkCursorBlock(platforms.cursor, add);
   if (platforms.copilot) checkCopilotBlock(platforms.copilot, add);
   if (platforms.codex) checkCodexBlock(platforms.codex, add);
+  if (platforms.antigravity) checkAntigravityBlock(platforms.antigravity, add);
 
   // ── skills field: Claude preloads it; the others have no such field ──
   for (const p of ["opencode", "cursor", "copilot"] as const) {

package/src/tools/token-cost.ts

@@ -4,16 +4,15 @@
  * Reads from two sources:
  * 1. Claude Code session transcripts (~/.claude/projects/)
  * 2. PAL Haiku inference logs (memory/signals/token-usage.jsonl)
- *
- * Invoked via `pal cli usage [--today|--week|--month|--all] [--project <name>]`.
  */
 
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { parseArgs } from "node:util";
 import { palHome } from "../hooks/lib/paths";
 import { findBinaryOnPath } from "../hooks/lib/which";
+import { leaf, runCommand } from "./lib/command";
+import { scriptArgs } from "./lib/script-args";
 import { parseRtkSummary, type RtkGain, usageLines } from "./lib/token-report";
 import { readClaudeCode, readPalInference } from "./lib/usage-buckets";
 
@@ -30,24 +29,26 @@ function rtkGain(): RtkGain {
   };
 }
 
-export function usage() {
-  const { values } = parseArgs({
-    options: {
-      today: { type: "boolean", default: false },
-      week: { type: "boolean", default: false },
-      month: { type: "boolean", default: false },
-      all: { type: "boolean", default: false },
-      project: { type: "string" },
-    },
-    strict: false,
-  });
-
+function printUsage(project: string | undefined): undefined {
   const lines = usageLines(
-    readClaudeCode(resolve(homedir(), ".claude", "projects"), values.project as string),
+    readClaudeCode(resolve(homedir(), ".claude", "projects"), project),
     readPalInference(resolve(palHome(), "memory", "signals", "token-usage.jsonl")),
     rtkGain()
   );
   for (const line of lines) console.log(line);
 }
 
-if (import.meta.main) usage();
+export const usageCommand = leaf({
+  summary: "Summarize token usage and estimated cost for today, 7 and 30 days",
+  options: {
+    project: {
+      type: "string",
+      value: "<name>",
+      description: "Only Claude Code sessions of this project",
+    },
+  },
+  run: ({ values }) => printUsage(values.project),
+});
+
+if (import.meta.main)
+  process.exit(await runCommand(usageCommand, scriptArgs(), ["pal", "cli", "usage"]));