portable-agent-layer 0.70.0 → 0.72.0

package/src/tools/agent/project.ts

@@ -7,7 +7,8 @@
  *
  * Usage:
  *   bun ~/.pal/tools/project.ts list
- *   bun ~/.pal/tools/project.ts create [name] [--path PATH] [--objectives "..."]
+ *   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"
@@ -38,6 +39,19 @@ import {
   readProject,
   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();
@@ -83,6 +97,8 @@ function cmdCreate(args: string[]): void {
       path: { type: "string" },
       name: { type: "string" },
       objectives: { type: "string" },
+      serves: { type: "string" },
+      "serves-note": { type: "string" },
     },
     allowPositionals: true,
   });
@@ -111,6 +127,10 @@ function cmdCreate(args: string[]): void {
         .join("\n")
     : undefined;
 
+  if (values.serves !== undefined && !isServesKind(values.serves)) {
+    fail(`--serves must be one of: ${SERVES_KINDS.join(", ")}`);
+  }
+
   const project: ProjectProgress = {
     name,
     path,
@@ -118,11 +138,31 @@ function cmdCreate(args: string[]): void {
     created: now(),
     updated: now(),
     ...(goalLines ? { goal: goalLines } : {}),
+    ...(isServesKind(values.serves)
+      ? { serves: values.serves, serves_by: "user" as const }
+      : {}),
+    ...(values["serves-note"] ? { serves_note: values["serves-note"] } : {}),
   };
   writeProject(project);
   ok({ created: true, project });
 }
 
+/** The answer the scaffolder asks for, and the one place importance can be corrected. */
+function cmdServes(args: string[]): void {
+  const [name, kind, ...note] = args;
+  if (!name || !kind) fail("Usage: serves <name> <goal|revenue|fun> [note]");
+  if (!isServesKind(kind)) fail(`serves must be one of: ${SERVES_KINDS.join(", ")}`);
+
+  const outcome = setServes({
+    name,
+    kind,
+    note: note.join(" ").trim() || undefined,
+    by: "user",
+  });
+  if (outcome === "missing") fail(`No project named "${name}".`);
+  ok({ project: name, serves: kind, by: "user" });
+}
+
 // ── resume ────────────────────────────────────────────────────────
 
 // resume returns a lean orientation view: all narrative sections, but the
@@ -372,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";
-}
-
-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);
-}
-
-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();
@@ -556,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 =
@@ -693,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 });
@@ -753,7 +660,8 @@ function help(): void {
 
 Commands:
   list                                          show all registered projects
-  create [name] [--path PATH] [--objectives X]  register a project
+  create [name] [--path PATH] [--objectives X] [--serves KIND]  register a project
+  serves <name> <goal|revenue|fun> [note]       say what it is for — outranks PAL's guess
   resume <name>                                 print lean project view (open-ISC titles; full text via show-isc)
   complete <name>                               mark complete
   archive <name>                                mark archived
@@ -796,6 +704,9 @@ function run(): void {
     case "create":
       cmdCreate(rest);
       return;
+    case "serves":
+      cmdServes(rest);
+      return;
     case "resume":
       cmdResume(rest);
       return;

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));
   }
 }