portable-agent-layer 0.71.0 → 0.73.0

package/src/tools/agent/project.ts

@@ -40,6 +40,21 @@ import {
   writeProject,
 } from "../../hooks/lib/projects";
 import { isServesKind, SERVES_KINDS, setServes } from "../../hooks/lib/serves";
+import {
+  archiveLine,
+  completeIsc,
+  encodeIscText,
+  ISC_BOX,
+  type IscMove,
+  type IscSections,
+  iscTitle,
+  nextIscId,
+  parseIscs,
+  removeIscLine,
+  reopenIsc,
+  selectIscs,
+  taskSlug,
+} from "../lib/project-isc";
 
 function now(): string {
   return new Date().toISOString();
@@ -400,130 +415,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();
@@ -545,17 +443,25 @@ function cmdCompleteIsc(args: string[]): void {
   const id = Number(args[1] ?? fail("Usage: complete-isc <name> <id>"));
   if (!Number.isInteger(id) || id < 1) fail("ISC id must be a positive integer");
   const p = requireProject(name);
-  if (parseIscs(p.changelog ?? "").some((i) => i.id === id)) {
+  const move = completeIsc(sectionsOf(p), id);
+  if (!move.ok) fail(`${move.reason} in project "${name}"`);
+  if (move.already) {
     ok({ checked: true, id, alreadyDone: true });
     return;
   }
-  const { line, rest } = removeIscLine(p.criteria ?? "", id);
-  if (!line) fail(`ISC-${id} not found in project "${name}"`);
-  p.criteria = rest;
-  p.changelog = archiveLine(p.changelog, line.replace("[ ]", "[x]"));
+  applyIscMove(p, move);
+  ok({ checked: true, id, archived: true });
+}
+
+function sectionsOf(p: ProjectProgress): IscSections {
+  return { criteria: p.criteria ?? "", changelog: p.changelog ?? "" };
+}
+
+function applyIscMove(p: ProjectProgress, move: IscMove & { ok: true }): void {
+  p.criteria = move.criteria;
+  p.changelog = move.changelog;
   p.updated = now();
   writeProject(p);
-  ok({ checked: true, id, archived: true });
 }
 
 // Reopening pulls the line back out of the Changelog (or legacy Criteria) into
@@ -565,32 +471,16 @@ function cmdReopenIsc(args: string[]): void {
   const id = Number(args[1] ?? fail("Usage: reopen-isc <name> <id>"));
   if (!Number.isInteger(id) || id < 1) fail("ISC id must be a positive integer");
   const p = requireProject(name);
-  if (parseIscs(p.criteria ?? "").some((i) => i.id === id && i.status === "open")) {
+  const move = reopenIsc(sectionsOf(p), id);
+  if (!move.ok) fail(`${move.reason} in project "${name}"`);
+  if (move.already) {
     ok({ checked: false, id, alreadyOpen: true });
     return;
   }
-  let removed = removeIscLine(p.changelog ?? "", id);
-  if (removed.line) {
-    p.changelog = dropEmptyArchiveHeadings(removed.rest);
-  } else {
-    removed = removeIscLine(p.criteria ?? "", id);
-    if (removed.line) p.criteria = removed.rest;
-  }
-  if (!removed.line) fail(`ISC-${id} not found in project "${name}"`);
-  const openLine = removed.line.replace(/\[[x~]\]/i, "[ ]");
-  p.criteria = p.criteria ? `${p.criteria.trimEnd()}\n${openLine}` : openLine;
-  p.updated = now();
-  writeProject(p);
+  applyIscMove(p, move);
   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 +611,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/attention.ts

@@ -0,0 +1,146 @@
+/**
+ * What is waiting on you, and what you have already seen.
+ *
+ * Every item here is a template over a fact PAL already holds — a refused tool
+ * call, an unanswered handoff, a project with no purpose on record. Nothing is
+ * inferred: the bell is the one surface that must be instant and always right,
+ * and a model in that path would fail silently exactly when it mattered.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "../../hooks/lib/paths";
+import { readAllProjects } from "../../hooks/lib/projects";
+import { queryLedger } from "../ledger/query";
+import { displayTarget } from "../ledger/view";
+import { freshHandoffs } from "./data";
+import { type AttentionSource, readPrefs } from "./prefs";
+
+const DAY_MS = 86_400_000;
+const REFUSAL_WINDOW_DAYS = 7;
+const MAX_ITEMS = 40;
+
+export interface AttentionItem {
+  id: string;
+  source: AttentionSource;
+  severity: "alarm" | "waiting" | "note";
+  title: string;
+  detail: string;
+  at: string;
+  project: string | null;
+  /** Where clicking it should land. */
+  href: string;
+  read: boolean;
+}
+
+export interface AttentionView {
+  unread: number;
+  items: AttentionItem[];
+}
+
+type ReadState = Record<string, string>;
+
+function readFile(): string {
+  return resolve(ensureDir(paths.state()), "attention-read.json");
+}
+
+function readMarks(): ReadState {
+  const file = readFile();
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as ReadState;
+  } catch {
+    return {};
+  }
+}
+
+function writeMarks(marks: ReadState): void {
+  writeFileSync(readFile(), `${JSON.stringify(marks, null, 2)}\n`, "utf-8");
+}
+
+export function markRead(ids: string[], now: Date = new Date()): number {
+  const marks = readMarks();
+  for (const id of ids) marks[id] = now.toISOString();
+  writeMarks(marks);
+  return ids.length;
+}
+
+function refusals(now: Date): AttentionItem[] {
+  const since = new Date(now.getTime() - REFUSAL_WINDOW_DAYS * DAY_MS);
+  return queryLedger({ since })
+    .filter((e) => e.outcome === "denied" || e.outcome === "blocked")
+    .map((e) => ({
+      id: `refusal:${e.id}`,
+      source: "refusals" as const,
+      severity: "alarm" as const,
+      title: `${e.outcome === "blocked" ? "Blocked" : "Denied"}: ${e.tool}`,
+      detail: e.reason ?? e.command ?? displayTarget(e.target),
+      at: e.ts,
+      project: anchorProject(e.target),
+      href: `/log?outcome=${e.outcome}`,
+      read: false,
+    }));
+}
+
+function anchorProject(target: string): string | null {
+  const match = /^\{proj:([^}]+)\}/.exec(target);
+  return match ? match[1] : null;
+}
+
+function waiting(now: Date): AttentionItem[] {
+  const slugByPath = new Map(
+    readAllProjects()
+      .filter((p) => p.path)
+      .map((p) => [p.path as string, p.name])
+  );
+  return freshHandoffs(now)
+    .filter(([, h]) => h.waitingOn)
+    .map(([cwd, h]) => {
+      const slug = slugByPath.get(cwd) ?? null;
+      return {
+        id: `waiting:${cwd}:${h.timestamp}`,
+        source: "waiting" as const,
+        severity: "waiting" as const,
+        title: `${slug ?? cwd} is waiting on you`,
+        detail: h.waitingOn as string,
+        at: h.timestamp,
+        project: slug,
+        href: slug ? `/projects/${slug}` : "/",
+        read: false,
+      };
+    });
+}
+
+function unranked(): AttentionItem[] {
+  return readAllProjects()
+    .filter((p) => p.status === "active" && !p.serves)
+    .map((p) => ({
+      id: `unranked:${p.name}`,
+      source: "unranked" as const,
+      severity: "note" as const,
+      title: `${p.name} has no purpose on record`,
+      detail: "It ranks as unimportant until you say what it serves.",
+      at: p.updated,
+      project: p.name,
+      href: `/projects/${p.name}`,
+      read: false,
+    }));
+}
+
+const SOURCES: Record<AttentionSource, (now: Date) => AttentionItem[]> = {
+  refusals,
+  waiting,
+  unranked: () => unranked(),
+};
+
+export function attention(now: Date = new Date()): AttentionView {
+  const prefs = readPrefs();
+  const marks = readMarks();
+  const items = (Object.keys(SOURCES) as AttentionSource[])
+    .filter((source) => prefs.attention[source])
+    .flatMap((source) => SOURCES[source](now))
+    .map((item) => ({ ...item, read: marks[item.id] !== undefined }))
+    .sort((a, b) => b.at.localeCompare(a.at))
+    .slice(0, MAX_ITEMS);
+  return { unread: items.filter((i) => !i.read).length, items };
+}