portable-agent-layer 0.71.0 → 0.72.0

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

@@ -10,70 +10,38 @@
  *   bun ~/.pal/tools/handoff-note.ts --done   # mark completed, suppress next-session injection
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { ensureDir, paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
+import {
+  handoffFile,
+  type NoteInput,
+  readHandoffs,
+  recordNote,
+  statusOf,
+} from "../lib/handoff-note";
+
+const HELP = `
+HandoffNote — Write a handoff note for the current project
 
-export interface HandoffEntry {
-  timestamp: string;
-  title: string;
-  status: "in-progress" | "completed";
-  handoff: string;
-  artifacts: string[];
-  source: "deliberate" | "auto";
-  /** What the work needs from the human before it can move — the one thing an agent cannot unblock. */
-  waitingOn?: string;
-}
-
-function handoffPath(): string {
-  return resolve(ensureDir(paths.state()), "last-handoff.json");
-}
-
-export function readHandoffs(): Record<string, HandoffEntry> {
-  const p = handoffPath();
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
+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
 
-/** Returns how many entries survived the trim, which is what the receipt reports. */
-function writeHandoffs(handoffs: Record<string, HandoffEntry>): number {
-  const entries = Object.entries(handoffs);
-  const trimmed = entries.length > 20 ? Object.fromEntries(entries.slice(-20)) : handoffs;
-  writeFileSync(handoffPath(), JSON.stringify(trimmed, null, 2), "utf-8");
-  return Object.keys(trimmed).length;
-}
+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
 
-interface NoteInput {
-  cwd: string;
-  title: string;
-  text: string;
-  done: boolean;
-  waitingOn?: string;
-}
+Output: writes to memory/state/last-handoff.json keyed by cwd
+`;
 
-function writeHandoffNote(note: NoteInput): {
-  file: string;
-  status: HandoffEntry["status"];
-  kept: number;
-} {
-  const handoffs = readHandoffs();
-  handoffs[note.cwd] = {
-    timestamp: new Date().toISOString(),
-    title: note.title,
-    status: note.done ? "completed" : "in-progress",
-    handoff: note.text,
-    artifacts: [],
-    source: "deliberate",
-    ...(note.waitingOn ? { waitingOn: note.waitingOn } : {}),
-  };
-  const kept = writeHandoffs(handoffs);
-  return { file: handoffPath(), status: handoffs[note.cwd].status, kept };
+function saveNote(note: NoteInput): void {
+  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 });
 }
 
 function run() {
@@ -89,32 +57,17 @@ function run() {
   });
 
   if (values.help) {
-    console.log(`
-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
-
-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
-`);
+    console.log(HELP);
     process.exit(0);
   }
 
   if (values.done) {
-    const result = writeHandoffNote({
+    saveNote({
       cwd: process.cwd(),
       title: values.title || "session",
       text: values.text || "",
       done: true,
     });
-    emit.receipt(result.file, { status: result.status, entries: result.kept });
     process.exit(0);
   }
 
@@ -123,14 +76,13 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
     process.exit(1);
   }
 
-  const result = writeHandoffNote({
+  saveNote({
     cwd: process.cwd(),
     title: values.title,
     text: values.text,
     done: false,
     waitingOn: values.waiting,
   });
-  emit.receipt(result.file, { status: result.status, entries: result.kept });
 }
 
 if (import.meta.main) run();

package/src/tools/agent/project.ts

@@ -40,6 +40,18 @@ import {
   writeProject,
 } from "../../hooks/lib/projects";
 import { isServesKind, SERVES_KINDS, setServes } from "../../hooks/lib/serves";
+import {
+  archiveLine,
+  dropEmptyArchiveHeadings,
+  encodeIscText,
+  ISC_BOX,
+  iscTitle,
+  nextIscId,
+  parseIscs,
+  removeIscLine,
+  selectIscs,
+  taskSlug,
+} from "../lib/project-isc";
 
 function now(): string {
   return new Date().toISOString();
@@ -400,130 +412,13 @@ function cmdRm(args: string[]): void {
 // Three states, not two: a retired ISC is one that stopped being valid, which the
 // record must not report as completed work. The box character is the storage form
 // and the id stays in it, so a retired line keeps reserving its id in nextIscId.
-type IscStatus = "open" | "done" | "retired";
-
-const ISC_BOX: Record<IscStatus, string> = {
-  open: "[ ]",
-  done: "[x]",
-  retired: "[~]",
-};
-
-function statusFromBox(box: string): IscStatus {
-  if (box.toLowerCase() === "x") return "done";
-  if (box === "~") return "retired";
-  return "open";
-}
-
-export interface Isc {
-  id: number;
-  text: string;
-  status: IscStatus;
-}
-
-/**
- * An ISC is one markdown line, so a newline in its text would end the record
- * and strand every paragraph after it as unparseable debris. Backslashes are
- * escaped first so that decoding a literal "\n" in a regex cannot be mistaken
- * for the separator.
- */
-function encodeIscText(text: string): string {
-  return text
-    .replaceAll("\\", "\\\\")
-    .replaceAll("\r\n", "\n")
-    .replaceAll("\r", "\n")
-    .replaceAll("\n", "\\n");
-}
-
-const ISC_UNESCAPE: Record<string, string> = { n: "\n", "\\": "\\" };
-
-function decodeIscText(stored: string): string {
-  return stored.replaceAll(/\\(.)/g, (whole, ch) => ISC_UNESCAPE[ch] ?? whole);
-}
-
-export function parseIscs(criteria: string): Isc[] {
-  const out: Isc[] = [];
-  for (const line of criteria.split("\n")) {
-    const m = new RegExp(/^-\s+\[( |x|~)\]\s+ISC-(\d+):\s+(.+)$/i).exec(line);
-    if (m)
-      out.push({
-        id: Number(m[2]),
-        text: decodeIscText(m[3].trim()),
-        status: statusFromBox(m[1]),
-      });
-  }
-  return out;
-}
-
-// Collapse a full ISC line to a glanceable title for resume: cut at the first
-// clause boundary, then hard-cap length. Full text stays reachable via show-isc.
-function iscTitle(text: string): string {
-  const boundary = text.search(/; | — | \(|\. /);
-  const clause = (boundary > 0 ? text.slice(0, boundary) : text).trim();
-  return clause.length > 80 ? `${clause.slice(0, 79).trimEnd()}…` : clause;
-}
-
-// Scans Criteria AND Changelog so an archived id can never be handed out again.
-function nextIscId(p: ProjectProgress): number {
-  const ids = [...parseIscs(p.criteria ?? ""), ...parseIscs(p.changelog ?? "")].map(
-    (i) => i.id
-  );
-  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
-}
-
-function removeIscLine(
-  section: string,
-  id: number
-): { line: string | null; rest: string } {
-  const lines = section.split("\n");
-  const idx = lines.findIndex((l) =>
-    new RegExp(String.raw`^-\s+\[[ x~]\]\s+ISC-${id}:`).test(l)
-  );
-  if (idx === -1) return { line: null, rest: section };
-  const [line] = lines.splice(idx, 1);
-  return {
-    line,
-    rest: lines
-      .join("\n")
-      .replace(/\n{3,}/g, "\n\n")
-      .trim(),
-  };
-}
-
-// Drops any "### Archived <date>" heading whose block has no content left —
-// e.g. after every ISC filed under that date has been reopened.
-function dropEmptyArchiveHeadings(changelog: string): string {
-  const lines = changelog.split("\n");
-  const blockHasContent = (headingIdx: number): boolean => {
-    for (let j = headingIdx + 1; j < lines.length && !lines[j].startsWith("### "); j++) {
-      if (lines[j].trim() !== "") return true;
-    }
-    return false;
-  };
-  return lines
-    .filter((l, i) => !(/^### Archived /.test(l) && !blockHasContent(i)))
-    .join("\n")
-    .replace(/\n{3,}/g, "\n\n")
-    .trim();
-}
-
-function archiveLine(
-  changelog: string | undefined,
-  doneLine: string,
-  kind: "Archived" | "Retired" = "Archived"
-): string {
-  const heading = `### ${kind} ${new Date().toISOString().slice(0, 10)}`;
-  const base = (changelog ?? "").trim();
-  if (base.includes(heading)) return `${base}\n${doneLine}`;
-  return base ? `${base}\n\n${heading}\n${doneLine}` : `${heading}\n${doneLine}`;
-}
-
 function cmdAddIsc(args: string[]): void {
   const name = args[0] ?? fail("Usage: add-isc <name> <title>");
   const title = args.slice(1).join(" ").trim();
   if (!title) fail("Usage: add-isc <name> <title>");
   const p = requireProject(name);
   const current = p.criteria ?? "";
-  const id = nextIscId(p);
+  const id = nextIscId(current, p.changelog ?? "");
   const newLine = `- [ ] ISC-${id}: ${encodeIscText(title)}`;
   p.criteria = current ? `${current.trimEnd()}\n${newLine}` : newLine;
   p.updated = now();
@@ -584,13 +479,6 @@ function cmdReopenIsc(args: string[]): void {
   ok({ checked: false, id });
 }
 
-function selectIscs(open: Isc[], done: Isc[], retired: Isc[], flags: Set<string>): Isc[] {
-  if (flags.has("--all")) return [...open, ...done, ...retired];
-  if (flags.has("--closed")) return done;
-  if (flags.has("--retired")) return retired;
-  return open;
-}
-
 function cmdListIsc(args: string[]): void {
   const flags = new Set(args.filter((a) => a.startsWith("--")));
   const name =
@@ -721,15 +609,6 @@ function cmdPruneIsc(args: string[]): void {
 
 // ── Task ISA (work/) ──────────────────────────────────────────────
 
-function taskSlug(title: string): string {
-  const sanitized = title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 40);
-  return `${sanitized}-${Date.now().toString(36)}`;
-}
-
 function taskIsaPath(slug: string): string {
   const dir = resolve(paths.work(), slug);
   mkdirSync(dir, { recursive: true });

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

@@ -13,27 +13,17 @@
  * Note types:
  *   --o   Opinion/behavioral observation about the user (requires --confidence)
  *   --w   World fact about the user's situation (objective, observable)
- *   --b   Session diary — what Jarvis did this session (first-person, specific)
+ *   --b   Session diary — what the assistant did this session (first-person)
+ *
+ * Which flags make which notes is in lib/note-flags.ts.
  */
 
 import { parseArgs } from "node:util";
 import { appendNotes } from "../../hooks/lib/relationship";
 import { emit } from "../lib/emit";
+import { notesFromFlags } from "../lib/note-flags";
 
-function run() {
-  const { values } = parseArgs({
-    args: Bun.argv.slice(2),
-    options: {
-      o: { type: "string", multiple: true },
-      w: { type: "string", multiple: true },
-      b: { type: "string" },
-      confidence: { type: "string" },
-      help: { type: "boolean", short: "h" },
-    },
-  });
-
-  if (values.help) {
-    console.log(`
+const HELP = `
 RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
@@ -45,45 +35,36 @@ 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 Jarvis did (first-person, specific)
+  --b TEXT          Session diary — what the assistant did (first-person)
 
 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
-`);
-    process.exit(0);
-  }
-
-  if (!values.o && !values.w && !values.b) {
-    console.error("Required: at least one of --o, --w, --b");
-    process.exit(1);
-  }
-
-  const notes = [];
+`;
 
-  if (values.o && values.o.length > 0) {
-    const confidence = values.confidence ? Number.parseFloat(values.confidence) : 0.75;
-    if (Number.isNaN(confidence) || confidence < 0 || confidence > 1) {
-      console.error("--confidence must be a number between 0.0 and 1.0");
-      process.exit(1);
-    }
-    for (const text of values.o) {
-      notes.push({ type: "O" as const, text, confidence });
-    }
-  }
+if (import.meta.main) {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      o: { type: "string", multiple: true },
+      w: { type: "string", multiple: true },
+      b: { type: "string" },
+      confidence: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
 
-  if (values.w && values.w.length > 0) {
-    for (const text of values.w) {
-      notes.push({ type: "W" as const, text });
-    }
+  if (values.help) {
+    console.log(HELP);
+    process.exit(0);
   }
 
-  if (values.b) {
-    notes.push({ type: "Session" as const, text: values.b });
+  const result = notesFromFlags(values);
+  if ("error" in result) {
+    console.error(result.error);
+    process.exit(1);
   }
 
-  const { file, written } = appendNotes(notes);
-  emit.receipt(file, { written, deduped: notes.length - written });
+  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

@@ -17,7 +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 { readJsonl } from "../self-model";
+import { readJsonl } from "../lib/self-model";
 
 // ── Config ──
 

package/src/tools/agent/thread.ts

@@ -11,99 +11,54 @@
  *   bun ~/.pal/tools/thread.ts --list [--all]
  */
 
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
-import { encodeAnchor } from "../../hooks/lib/anchor";
-import { ensureDir, paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
+import {
+  addThread,
+  readThreads,
+  resolveThreadIn,
+  threadsFile,
+  visibleThreads,
+  writeThreads,
+} from "../lib/thread";
+
+const HELP = `
+Thread — Manage open threads across sessions
 
-// ── Types ──
-
-export interface Thread extends RecordAttribution {
-  id: string;
-  cwd: string;
-  title: string;
-  context: string;
-  status: "open" | "resolved";
-  created: string;
-  resolved: string | null;
-}
-
-// ── Storage ──
-
-function threadsPath(): string {
-  return resolve(ensureDir(paths.state()), "threads.jsonl");
-}
-
-function generateId(): string {
-  return Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
-}
+Usage:
+  thread.ts --add --title "..." [--context "..."]
+  thread.ts --resolve --id <id>
+  thread.ts --list [--all]
+`;
 
-export function readThreads(): Thread[] {
-  const p = threadsPath();
-  if (!existsSync(p)) return [];
-  try {
-    return readFileSync(p, "utf-8")
-      .split("\n")
-      .filter((l) => l.trim())
-      .map((l) => JSON.parse(l) as Thread);
-  } catch {
-    return [];
+function add(title: string | undefined, context: string | undefined) {
+  if (!title) {
+    console.error("--title required");
+    process.exit(1);
   }
+  const thread = addThread(title, context ?? "");
+  emit.receipt(threadsFile(), {
+    id: thread.id,
+    title: thread.title,
+    status: thread.status,
+  });
 }
 
-export function writeThreads(threads: Thread[]): void {
-  writeFileSync(
-    threadsPath(),
-    `${threads.map((t) => JSON.stringify(t)).join("\n")}\n`,
-    "utf-8"
-  );
-}
-
-// ── Operations ──
-
-/** Exported so the cwd-anchor and origin-stamp wiring is directly testable. */
-export function addThread(title: string, context: string): Thread {
-  const thread: Thread = {
-    id: generateId(),
-    cwd: encodeAnchor(process.cwd()),
-    ...currentAttribution(),
-    title,
-    context,
-    status: "open",
-    created: new Date().toISOString(),
-    resolved: null,
-  };
-  appendFileSync(threadsPath(), `${JSON.stringify(thread)}\n`, "utf-8");
-  return thread;
-}
-
-function resolveThread(id: string): {
-  success: boolean;
-  thread?: Thread;
-  message: string;
-} {
-  const threads = readThreads();
-  const idx = threads.findIndex((t) => t.id === id);
-  if (idx === -1) return { success: false, message: `Thread not found: ${id}` };
-  threads[idx].status = "resolved";
-  threads[idx].resolved = new Date().toISOString();
-  writeThreads(threads);
-  return {
-    success: true,
-    thread: threads[idx],
-    message: `Resolved: ${threads[idx].title}`,
-  };
-}
-
-function listThreads(all: boolean): Thread[] {
-  return all ? readThreads() : readThreads().filter((t) => t.status === "open");
+function markResolved(id: string | undefined) {
+  if (!id) {
+    console.error("--id required");
+    process.exit(1);
+  }
+  const file = threadsFile();
+  const resolution = resolveThreadIn(readThreads(file), id, new Date());
+  if (!resolution) {
+    console.error(`Thread not found: ${id}`);
+    process.exit(1);
+  }
+  writeThreads(resolution.threads, file);
+  emit.receipt(file, { id, status: "resolved", title: resolution.thread.title });
 }
 
-// ── CLI ──
-
 function run() {
   const { values } = parseArgs({
     args: Bun.argv.slice(2),
@@ -125,49 +80,14 @@ function run() {
   else if (values.list) cmd = "list";
 
   if (values.help || !cmd) {
-    console.log(`
-Thread — Manage open threads across sessions
-
-Usage:
-  thread.ts --add --title "..." [--context "..."]
-  thread.ts --resolve --id <id>
-  thread.ts --list [--all]
-`);
+    console.log(HELP);
     process.exit(cmd ? 0 : 1);
   }
 
-  if (cmd === "add") {
-    if (!values.title) {
-      console.error("--title required");
-      process.exit(1);
-    }
-    const thread = addThread(values.title, values.context ?? "");
-    emit.receipt(threadsPath(), {
-      id: thread.id,
-      title: thread.title,
-      status: thread.status,
-    });
-  }
-
-  if (cmd === "resolve") {
-    if (!values.id) {
-      console.error("--id required");
-      process.exit(1);
-    }
-    const resolved = resolveThread(values.id);
-    if (!resolved.success) {
-      console.error(resolved.message);
-      process.exit(1);
-    }
-    emit.receipt(threadsPath(), {
-      id: values.id,
-      status: "resolved",
-      title: resolved.thread?.title,
-    });
-  }
-
+  if (cmd === "add") add(values.title, values.context);
+  if (cmd === "resolve") markResolved(values.id);
   if (cmd === "list") {
-    const threads = listThreads(values.all ?? false);
+    const threads = visibleThreads(readThreads(), values.all ?? false);
     emit.data(JSON.stringify({ count: threads.length, threads }, null, 2));
   }
 }

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

@@ -16,9 +16,9 @@ import { loadAnalyzeNudge } from "../../hooks/lib/analyze-nudge";
 import { paths } from "../../hooks/lib/paths";
 import { isStale, type ProjectProgress, readAllProjects } from "../../hooks/lib/projects";
 import { readProjectHistory } from "../../hooks/lib/work-tracking";
-import { type HandoffEntry, readHandoffs } from "../agent/handoff-note";
-import { parseIscs } from "../agent/project";
 import { anchorSlugOf, type LedgerFilter, queryLedger } from "../ledger/query";
+import { type HandoffEntry, readHandoffs } from "../lib/handoff-note";
+import { parseIscs } from "../lib/project-isc";
 
 const DAY_MS = 86_400_000;
 const HANDOFF_FRESH_DAYS = 7;

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

@@ -20,7 +20,7 @@ import {
 } from "../../hooks/lib/projects";
 import { isImportant, SERVES_MEANING } from "../../hooks/lib/serves";
 import { dueFrom, readTelosGoals, type TelosGoal } from "../../hooks/lib/telos-goals";
-import type { HandoffEntry } from "../agent/handoff-note";
+import type { HandoffEntry } from "../lib/handoff-note";
 import { freshHandoffs } from "./data";
 
 const URGENT_WITHIN_DAYS = 14;

package/src/tools/control-room/ui/ledger.tsx

@@ -28,8 +28,9 @@ function Row({ r }: { r: LedgerViewRow }) {
         </span>
       </td>
       <td>{r.tool}</td>
-      <td className="target" title={r.target}>
+      <td className="target" title={r.command ?? r.target}>
         <b>{slug}</b> {rest.join(" ")}
+        {r.command && <span className="reason">{r.command}</span>}
       </td>
       <td>{r.change}</td>
       <td>

package/src/tools/ledger/view.ts

@@ -40,6 +40,8 @@ export interface LedgerViewRow {
   change: string;
   outcome: string;
   reason?: string;
+  /** Present only on a blocked shell action, where the target is a directory. */
+  command?: string;
 }
 
 export interface LedgerView {
@@ -100,6 +102,7 @@ function toRow(entry: LedgerEntry, registry: ActorRegistryEntry[]): LedgerViewRo
     outcome: entry.outcome,
   };
   if (entry.reason) row.reason = entry.reason;
+  if (entry.command) row.command = entry.command;
   return row;
 }