portable-agent-layer 0.75.0 → 0.76.0

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

@@ -6,8 +6,8 @@
  * Written by Claude in-session — no inference call needed.
  *
  * Usage:
- *   bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains + next steps"
- *   bun ~/.pal/tools/handoff-note.ts --done   # mark completed, suppress next-session injection
+ *   pal cli handoff-note --title "what we were doing" --text "what remains + next steps"
+ *   pal cli handoff-note --done   # mark completed, suppress next-session injection
  */
 
 import { writeFileSync } from "node:fs";
@@ -20,13 +20,14 @@ import {
   recordNote,
   statusOf,
 } from "../lib/handoff-note";
+import { scriptArgs } from "../lib/script-args";
 
 const HELP = `
 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
+  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)
@@ -44,9 +45,9 @@ function saveNote(note: NoteInput): void {
   emit.receipt(file, { status: statusOf(note), entries: Object.keys(store).length });
 }
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       title: { type: "string" },
       text: { type: "string" },

package/src/tools/agent/project.ts

@@ -6,27 +6,27 @@
  * Frontmatter holds operational state; body holds ISA spec sections.
  *
  * Usage:
- *   bun ~/.pal/tools/project.ts list
- *   bun ~/.pal/tools/project.ts create [name] [--path PATH] [--objectives "..."] [--serves goal|revenue|fun]
- *   bun ~/.pal/tools/project.ts serves <name> <goal|revenue|fun> [note]
- *   bun ~/.pal/tools/project.ts resume <name>
- *   bun ~/.pal/tools/project.ts complete | archive | pause | unpause <name>
- *   bun ~/.pal/tools/project.ts add-next <name> "text"
- *   bun ~/.pal/tools/project.ts add-blocker <name> "text"
- *   bun ~/.pal/tools/project.ts add-decision <name> "decision" "rationale"
- *   bun ~/.pal/tools/project.ts add-handoff <name> "text"
- *   bun ~/.pal/tools/project.ts rm-next | rm-blocker <name> <index>
- *   bun ~/.pal/tools/project.ts update-section <name> <section> "content"
- *   bun ~/.pal/tools/project.ts criteria <name>
- *   bun ~/.pal/tools/project.ts isa-init <name>
- *   bun ~/.pal/tools/project.ts migrate
+ *   pal cli project list
+ *   pal cli project create [name] [--path PATH] [--objectives "..."] [--serves goal|revenue|fun]
+ *   pal cli project serves <name> <goal|revenue|fun> [note]
+ *   pal cli project resume <name>
+ *   pal cli project complete | archive | pause | unpause <name>
+ *   pal cli project add-next <name> "text"
+ *   pal cli project add-blocker <name> "text"
+ *   pal cli project add-decision <name> "decision" "rationale"
+ *   pal cli project add-handoff <name> "text"
+ *   pal cli project rm-next | rm-blocker <name> <index>
+ *   pal cli project update-section <name> <section> "content"
+ *   pal cli project criteria <name>
+ *   pal cli project isa-init <name>
+ *   pal cli project migrate
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { writeBinding } from "../../hooks/lib/bindings";
-import { paths } from "../../hooks/lib/paths";
+import { paths, toPath } from "../../hooks/lib/paths";
 import {
   defaultSlug,
   deleteProject,
@@ -55,6 +55,7 @@ import {
   selectIscs,
   taskSlug,
 } from "../lib/project-isc";
+import { scriptArgs } from "../lib/script-args";
 
 function now(): string {
   return new Date().toISOString();
@@ -106,7 +107,7 @@ function cmdCreate(args: string[]): void {
     allowPositionals: true,
   });
 
-  const path = resolve(values.path ?? process.cwd());
+  const path = toPath(values.path ?? process.cwd());
   const name = (values.name ?? positionals[0] ?? defaultSlug(path)).trim();
 
   if (!/^[a-z0-9_-]+$/.test(name)) {
@@ -271,7 +272,7 @@ function addHandoff(name: string, text: string): void {
 function cmdSetPath(args: string[]): void {
   const [name, ...rest] = args;
   if (!name || rest.length === 0) fail("Usage: set-path <name> <new-path>");
-  const newPath = resolve(rest.join(" ").trim());
+  const newPath = toPath(rest.join(" ").trim());
   const p = requireProject(name);
   writeBinding(p.name, newPath);
   p.updated = now();
@@ -693,8 +694,8 @@ Commands:
 `);
 }
 
-function run(): void {
-  const [cmd, ...rest] = Bun.argv.slice(2);
+export function run(argv: string[] = scriptArgs()): void {
+  const [cmd, ...rest] = argv;
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     help();
     return;
@@ -810,7 +811,7 @@ function run(): void {
       cmdRm(rest);
       return;
     default:
-      fail(`Unknown command "${cmd}". Run 'project.ts help' for usage.`);
+      fail(`Unknown command "${cmd}". Run 'pal cli project help' for usage.`);
   }
 }
 

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

@@ -6,9 +6,9 @@
  * the user (O, W) and session diary entries (--b).
  *
  * Usage:
- *   bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
- *   bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
- *   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+ *   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"
  *
  * Note types:
  *   --o   Opinion/behavioral observation about the user (requires --confidence)
@@ -22,14 +22,15 @@ import { parseArgs } from "node:util";
 import { appendNotes } from "../../hooks/lib/relationship";
 import { emit } from "../lib/emit";
 import { notesFromFlags } from "../lib/note-flags";
+import { scriptArgs } from "../lib/script-args";
 
 const HELP = `
 RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
-  bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
-  bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
-  bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+  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
@@ -42,9 +43,9 @@ Multiple flags may be combined in one call. At least one of --o, --w, --b is req
 Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
 `;
 
-if (import.meta.main) {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       o: { type: "string", multiple: true },
       w: { type: "string", multiple: true },
@@ -68,3 +69,5 @@ if (import.meta.main) {
   const { file, written } = appendNotes(result.notes);
   emit.receipt(file, { written, deduped: result.notes.length - written });
 }
+
+if (import.meta.main) run();

package/src/tools/agent/synthesize.ts

@@ -7,7 +7,7 @@
  * reads and formats with behavioral guidance.
  *
  * Usage:
- *   bun ~/.pal/tools/synthesize.ts [--days 7] [--force]
+ *   pal cli synthesize [--days 7] [--force]
  *
  * Guards: skips if last synthesis was < 24h ago (unless --force).
  * Output: ~/.pal/memory/state/synthesis.json
@@ -17,6 +17,7 @@ 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 { scriptArgs } from "../lib/script-args";
 import { readJsonl } from "../lib/self-model";
 
 // ── Config ──
@@ -303,9 +304,9 @@ export function synthesize(days: number): SynthesisState {
 
 // ── CLI ──
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       days: { type: "string", default: "7" },
       force: { type: "boolean" },

package/src/tools/agent/thread.ts

@@ -6,13 +6,14 @@
  * Stored in memory/state/threads.jsonl as structured records.
  *
  * Usage:
- *   bun ~/.pal/tools/thread.ts --add --title "..." [--context "..."]
- *   bun ~/.pal/tools/thread.ts --resolve --id <id>
- *   bun ~/.pal/tools/thread.ts --list [--all]
+ *   pal cli thread --add --title "..." [--context "..."]
+ *   pal cli thread --resolve --id <id>
+ *   pal cli thread --list [--all]
  */
 
 import { parseArgs } from "node:util";
 import { emit } from "../lib/emit";
+import { scriptArgs } from "../lib/script-args";
 import {
   addThread,
   readThreads,
@@ -59,9 +60,9 @@ function markResolved(id: string | undefined) {
   emit.receipt(file, { id, status: "resolved", title: resolution.thread.title });
 }
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       add: { type: "boolean" },
       resolve: { type: "boolean" },

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

@@ -20,6 +20,7 @@ import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
+import { scriptArgs } from "../lib/script-args";
 
 // ── Types ──
 
@@ -192,9 +193,9 @@ ${antiPatternEntry}
 
 // ── CLI ──
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       domain: { type: "string", short: "d" },
       observation: { type: "string", short: "o" },

package/src/tools/lib/script-args.ts

@@ -0,0 +1,4 @@
+/** The arguments a spawned tool was given: argv leads with the runtime and the script path. */
+export function scriptArgs(argv: string[] = process.argv): string[] {
+  return argv.slice(2);
+}

package/src/tools/lib/skill-doctor.ts

@@ -12,7 +12,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, relative, resolve } from "node:path";
-import { palHome } from "../../hooks/lib/paths";
+import { palHome, toPath } from "../../hooks/lib/paths";
 import { declaredTriggers } from "../../hooks/lib/skill-triggers";
 
 type Level = "pass" | "warn" | "error";
@@ -449,7 +449,7 @@ export function formatReport(r: DoctorReport): string {
  * report names the directory the caller meant rather than a guess.
  */
 export function resolveSkillDir(arg: string): string {
-  const asPath = resolve(arg);
+  const asPath = toPath(arg);
   if (existsSync(resolve(asPath, "SKILL.md"))) return asPath;
   const byName = resolve(palHome(), "skills", arg);
   if (existsSync(resolve(byName, "SKILL.md"))) return byName;

package/src/tools/self-model.ts

@@ -9,7 +9,7 @@
  * ~/.pal/memory/self-model/current.md that is injected at session start.
  *
  * Usage:
- *   bun ~/.pal/tools/self-model.ts [--days 30] [--force] [--dry-run]
+ *   bun src/tools/self-model.ts [--days 30] [--force] [--dry-run]
  *
  * Every decision this makes lives in ./lib/self-model.ts, where the suite
  * reaches it directly; what stays here is paths, inference and the writes.

package/src/tools/skill-doctor.ts

@@ -15,7 +15,7 @@ import { formatReport, lintSkill, resolveSkillDir } from "./lib/skill-doctor";
 if (import.meta.main) {
   const arg = process.argv[2];
   if (!arg) {
-    console.error("Usage: bun src/tools/skill-doctor.ts <skill-dir-or-name>");
+    console.error("Usage: pal cli skill doctor <skill-dir-or-name>");
     process.exit(2);
   }
   const report = lintSkill(resolveSkillDir(arg));

package/src/tools/subagent-doctor.ts

@@ -13,7 +13,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import { assets, palHome } from "../hooks/lib/paths";
+import { assets, namesAPath, palHome, toPath } from "../hooks/lib/paths";
 
 type Level = "pass" | "warn" | "error";
 
@@ -396,16 +396,16 @@ export function formatSubagentReport(r: SubagentReport): string {
 
 /** Resolve a doctor argument to a subagent .md path (a path, or a name in the store). */
 export function resolveSubagentFile(arg: string): string {
-  if (arg.endsWith(".md") && existsSync(resolve(arg))) return resolve(arg);
-  const direct = resolve(arg);
+  const direct = toPath(arg);
   if (existsSync(direct) && direct.endsWith(".md")) return direct;
+  if (namesAPath(arg)) return direct.endsWith(".md") ? direct : `${direct}.md`;
   return resolve(palHome(), "agents", arg.endsWith(".md") ? arg : `${arg}.md`);
 }
 
 if (import.meta.main) {
   const arg = process.argv[2];
   if (!arg) {
-    console.error("Usage: bun src/tools/subagent-doctor.ts <file-or-name>");
+    console.error("Usage: pal cli subagent doctor <file-or-name>");
     process.exit(2);
   }
   const report = lintSubagent(resolveSubagentFile(arg));