portable-agent-layer 0.72.0 → 0.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -13,6 +13,9 @@
     "README.md",
     "LICENSE"
   ],
+  "workspaces": [
+    "src/tools/control-room/ui"
+  ],
   "engines": {
     "bun": ">=1.4.0"
   },
@@ -53,7 +56,9 @@
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
     "build:skill-tools": "bun run scripts/build-skill-tools.ts",
-    "prepack": "bun run build:skill-tools",
+    "build:ui": "bun run --filter @pal/control-room-ui build",
+    "dev:ui": "bun run --filter @pal/control-room-ui dev",
+    "prepack": "bun run build:skill-tools && bun run build:ui",
     "install:all": "bun run src/cli/index.ts cli install",
     "uninstall": "bun run src/cli/index.ts cli uninstall",
     "tool:synthesize": "bun run src/tools/agent/synthesize.ts",
@@ -61,7 +66,9 @@
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
     "eval:sentiment": "bun eval/run.ts sentiment",
-    "eval:failure-principle": "bun eval/run.ts failure-principle"
+    "eval:failure-principle": "bun eval/run.ts failure-principle",
+    "eval:goal-links": "bun eval/run.ts goal-links",
+    "eval:waiting-on": "bun eval/run.ts waiting-on"
   },
   "lint-staged": {
     "*.ts": [
@@ -83,8 +90,6 @@
     "@types/adm-zip": "^0.5.8",
     "@types/bun": "latest",
     "@types/node": "latest",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
     "husky": "^9.1.7",
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
@@ -102,8 +107,6 @@
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
     "playwright": "^1.60.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
     "unpdf": "^0.12.0"
   }
 }

package/src/cli/server.ts

@@ -12,6 +12,7 @@ import { parseArgs } from "node:util";
 import { spawnDetachedInference } from "../hooks/lib/detached-inference";
 import { paths } from "../hooks/lib/paths";
 import { DEFAULT_PORT, LOOPBACK, type ServerStatus } from "../tools/control-room/server";
+import { BUILD_COMMAND, buildPage, isBuilt } from "../tools/control-room/static";
 
 interface ServerState {
   pid: number;
@@ -137,6 +138,12 @@ async function cmdStart(args: string[]): Promise<number> {
     return 0;
   }
 
+  if (!isBuilt() && !buildPage()) {
+    return fail(
+      `The control room's page is not built and could not be. Run: ${BUILD_COMMAND}`
+    );
+  }
+
   spawnDetachedInference(SERVER_SCRIPT, [`--port=${port}`], "control-room");
   const status = await waitUntilAnswering(port);
   if (!status)

package/src/hooks/handlers/agenda.ts

@@ -10,10 +10,14 @@
  *    answer to "what now" is rarely "open a repository".
  */
 
+import { writeFile } from "node:fs/promises";
 import { matrix } from "../../tools/control-room/matrix";
+import { handoffFile, readHandoffs, withWaitingOn } from "../../tools/lib/handoff-note";
 import { type AgendaMove, readAgenda, writeAgenda } from "../lib/agenda-store";
+import { linkInputs, readGoalLinks, writeGoalLinks } from "../lib/goal-links";
 import { canInfer, inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
+import { SONNET_MODEL } from "../lib/models";
 import { readAllProjects } from "../lib/projects";
 import { isServesKind, SERVES_KINDS, setServes } from "../lib/serves";
 import { readTelosGoals } from "../lib/telos-goals";
@@ -21,6 +25,7 @@ import { logTokenUsage } from "../lib/token-usage";
 
 const FRESH_HOURS = 6;
 const MAX_PROJECTS_PER_GUESS = 40;
+const MAX_WAITING_PER_RUN = 3;
 
 function hoursSince(iso: string, now: Date): number {
   const at = new Date(iso).getTime();
@@ -53,6 +58,45 @@ const SERVES_SCHEMA = {
   required: ["projects"] as const,
 };
 
+const LINKS_SCHEMA = {
+  type: "object" as const,
+  additionalProperties: false,
+  properties: {
+    links: {
+      type: "array" as const,
+      description: "One entry per goal you were given, no others",
+      items: {
+        type: "object" as const,
+        additionalProperties: false,
+        properties: {
+          goalId: { type: "string" as const },
+          projects: {
+            type: "array" as const,
+            description:
+              "Slugs of the projects that move this goal forward, copied exactly. Empty when none does.",
+            items: { type: "string" as const },
+          },
+        },
+        required: ["goalId", "projects"] as const,
+      },
+    },
+  },
+  required: ["links"] as const,
+};
+
+const WAITING_SCHEMA = {
+  type: "object" as const,
+  additionalProperties: false,
+  properties: {
+    question: {
+      type: "string" as const,
+      description:
+        "The one thing the work needs from the person before it can move, in their own terms. Empty string when the handoff asks nothing of them.",
+    },
+  },
+  required: ["question"] as const,
+};
+
 const MOVES_SCHEMA = {
   type: "object" as const,
   additionalProperties: false,
@@ -72,8 +116,13 @@ const MOVES_SCHEMA = {
             type: "string" as const,
             description: "One short clause naming the evidence it came from",
           },
+          project: {
+            type: "string" as const,
+            description:
+              "The slug of the project this move belongs to, exactly as given, or an empty string when it belongs to none",
+          },
         },
-        required: ["move", "because"] as const,
+        required: ["move", "because", "project"] as const,
       },
     },
   },
@@ -129,10 +178,11 @@ async function guessMissingServes(sessionId?: string): Promise<number> {
     maxTokens: 700,
     timeout: 90000,
     jsonSchema: SERVES_SCHEMA,
+    model: SONNET_MODEL,
     caller: "agenda-serves",
     sessionId,
   });
-  if (result.usage) logTokenUsage("agenda-serves", result.usage);
+  if (result.usage) logTokenUsage("agenda-serves", result.usage, SONNET_MODEL);
   if (!result.success || !result.output) return 0;
 
   const parsed = parsePayload<{
@@ -157,7 +207,7 @@ async function guessMissingServes(sessionId?: string): Promise<number> {
 
 function matrixBrief(): string {
   const grid = matrix();
-  const lines = [...grid.now, ...grid.plan, ...grid.noise].map((item) => {
+  const lines = rankedItems(grid).map((item) => {
     const why = item.urgentBecause.join(", ") || "nothing pressing";
     const waiting = item.waitingOn ? ` — waiting on the user for: ${item.waitingOn}` : "";
     return `- [${item.kind}] ${item.label}: ${item.importantBecause}; ${why}${waiting}`;
@@ -165,7 +215,129 @@ function matrixBrief(): string {
   return lines.length > 0 ? lines.join("\n") : "Nothing is ranked yet.";
 }
 
+/**
+ * Only when the goals or the project set moved. A stop that changed neither
+ * costs nothing, which is what makes this affordable on every session.
+ */
+async function refreshGoalLinks(
+  sessionId?: string
+): Promise<"fresh" | "written" | "failed"> {
+  const goals = readTelosGoals();
+  const projects = readAllProjects().filter((p) => p.status === "active");
+  if (goals.length === 0 || projects.length === 0) return "fresh";
+
+  const inputs = linkInputs(
+    goals.map((g) => g.id),
+    projects.map((p) => p.name)
+  );
+  if (readGoalLinks()?.inputs === inputs) return "fresh";
+
+  const described = projects
+    .map(
+      (p) =>
+        `- ${p.name}: ${(p.goal ?? p.problem ?? "").replace(/\s+/g, " ").slice(0, 200) || "no description on record"}`
+    )
+    .join("\n");
+  const listed = goals.map((g) => `- ${g.id}: ${g.text}`).join("\n");
+
+  const result = await inference({
+    system: [
+      "You are told a person's stated goals and their active projects.",
+      "For each goal, name the projects that move it forward.",
+      "Judge from the goal and the project description only. A project that merely resembles a goal in subject does not serve it — it has to move it.",
+      "A goal that nothing serves gets an empty list, and that is a useful answer rather than a failure.",
+      "Copy project slugs exactly. Return one entry per goal you were given.",
+    ].join("\n"),
+    user: `Their goals:\n${listed}\n\nTheir active projects:\n${described}`,
+    maxTokens: 600,
+    timeout: 90000,
+    jsonSchema: LINKS_SCHEMA,
+    model: SONNET_MODEL,
+    caller: "agenda-goal-links",
+    sessionId,
+  });
+  if (result.usage) logTokenUsage("agenda-goal-links", result.usage, SONNET_MODEL);
+  if (!result.success || !result.output) return "failed";
+
+  const parsed = parsePayload<{ links: { goalId: string; projects: unknown }[] }>(
+    result.output,
+    "agenda:goal-links"
+  );
+  if (!parsed?.links) return "failed";
+
+  const goalIds = new Set(goals.map((g) => g.id));
+  const slugs = new Set(projects.map((p) => p.name));
+  const links = parsed.links
+    .filter((l) => goalIds.has(l.goalId))
+    .map((l) => ({
+      goalId: l.goalId,
+      projects: (Array.isArray(l.projects) ? l.projects : []).filter(
+        (slug): slug is string => typeof slug === "string" && slugs.has(slug)
+      ),
+    }));
+
+  await writeGoalLinks({ generatedAt: new Date().toISOString(), inputs, links });
+  return "written";
+}
+
+/**
+ * An auto handoff is a transcript excerpt nobody framed, so it never carries the
+ * question the work is stuck on — which is exactly the field three surfaces read.
+ * Most handoffs are stuck on nothing, so an empty answer is the common one.
+ */
+async function extractWaitingOn(sessionId?: string): Promise<number> {
+  const pending = Object.entries(readHandoffs()).filter(
+    ([, h]) =>
+      h.source === "auto" && h.status === "in-progress" && h.handoff && !h.waitingOn
+  );
+  if (pending.length === 0) return 0;
+
+  let written = 0;
+  for (const [cwd, entry] of pending.slice(0, MAX_WAITING_PER_RUN)) {
+    const result = await inference({
+      system: [
+        "You are given the last exchange of a coding session that stopped mid-work.",
+        "Decide whether the work is blocked on the person — a decision only they can make, a question they were asked and did not answer, an approval the work needs.",
+        "Most sessions are not blocked on anyone. Waiting for an agent to continue is not being blocked on the person.",
+        "When it is blocked, answer with the question in their own terms, under fifteen words.",
+        "When it is not, answer with an empty string. That is the ordinary answer.",
+      ].join("\n"),
+      user: entry.handoff,
+      maxTokens: 120,
+      timeout: 60000,
+      jsonSchema: WAITING_SCHEMA,
+      model: SONNET_MODEL,
+      caller: "agenda-waiting-on",
+      sessionId,
+    });
+    if (result.usage) logTokenUsage("agenda-waiting-on", result.usage, SONNET_MODEL);
+    if (!result.success || !result.output) continue;
+
+    const parsed = parsePayload<{ question: string }>(result.output, "agenda:waiting-on");
+    const question = parsed?.question?.trim();
+    if (!question) continue;
+    const store = withWaitingOn(readHandoffs(), cwd, question);
+    await writeFile(handoffFile(), JSON.stringify(store, null, 2), "utf-8");
+    written++;
+  }
+  return written;
+}
+
+function rankedItems(grid: ReturnType<typeof matrix>) {
+  return [...grid.now, ...grid.plan, ...grid.noise];
+}
+
+/** A model asked for a project name will invent one; only a slug it was shown counts. */
+function knownSlug(candidate: unknown, slugs: Set<string>): string | null {
+  return typeof candidate === "string" && slugs.has(candidate) ? candidate : null;
+}
+
 async function writeMoves(sessionId?: string): Promise<boolean> {
+  const slugs = new Set(
+    rankedItems(matrix())
+      .filter((i) => i.kind === "project")
+      .map((i) => i.id)
+  );
   const result = await inference({
     system: [
       "You write the first three lines a person reads in the morning.",
@@ -173,20 +345,31 @@ async function writeMoves(sessionId?: string): Promise<boolean> {
       "Write exactly three moves, most consequential first.",
       "A move is a sentence naming an action, not a project name: 'Send ACE the mapping one-pager' beats 'work on ontology'.",
       "Prefer what is blocked on the person themselves, then what serves a goal, then what is merely urgent.",
+      "Name the project each move belongs to, copying its slug exactly from the list you were given. A move that belongs to no project takes an empty string.",
       "Never invent a fact that is not in what you were given.",
     ].join("\n"),
     user: `Their goals:\n${goalsBrief()}\n\nWhat is ranked and why:\n${matrixBrief()}`,
     maxTokens: 400,
     timeout: 90000,
     jsonSchema: MOVES_SCHEMA,
+    model: SONNET_MODEL,
     caller: "agenda-moves",
     sessionId,
   });
-  if (result.usage) logTokenUsage("agenda-moves", result.usage);
+  if (result.usage) logTokenUsage("agenda-moves", result.usage, SONNET_MODEL);
   if (!result.success || !result.output) return false;
 
-  const parsed = parsePayload<{ moves: AgendaMove[] }>(result.output, "agenda:moves");
-  const moves = (parsed?.moves ?? []).filter((m) => m.move).slice(0, 3);
+  const parsed = parsePayload<{ moves: (AgendaMove & { project?: unknown })[] }>(
+    result.output,
+    "agenda:moves"
+  );
+  const moves: AgendaMove[] = (parsed?.moves ?? [])
+    .filter((m) => m.move)
+    .slice(0, 3)
+    .map(({ move, because, project }) => {
+      const slug = knownSlug(project, slugs);
+      return slug ? { move, because, project: slug } : { move, because };
+    });
   if (moves.length === 0) return false;
 
   await writeAgenda({ generatedAt: new Date().toISOString(), moves });
@@ -206,8 +389,13 @@ export async function refreshAgenda(
   if (!canInfer()) return "no-inference";
 
   const guessed = await guessMissingServes(sessionId);
+  const linked = await refreshGoalLinks(sessionId);
+  const waiting = await extractWaitingOn(sessionId);
   const wrote = await writeMoves(sessionId);
-  logDebug("agenda", `serves guessed: ${guessed}, moves written: ${wrote}`);
+  logDebug(
+    "agenda",
+    `serves guessed: ${guessed}, links: ${linked}, waitingOn: ${waiting}, moves written: ${wrote}`
+  );
   return wrote ? "written" : "failed";
 }
 

package/src/hooks/lib/agenda-store.ts

@@ -13,6 +13,8 @@ import { paths } from "./paths";
 export interface AgendaMove {
   move: string;
   because: string;
+  /** The project the move belongs to, when it belongs to one the page can open. */
+  project?: string;
 }
 
 export interface Agenda {

package/src/hooks/lib/goal-links.ts

@@ -0,0 +1,83 @@
+/**
+ * Which projects serve which stated goal, and how far along that makes it.
+ *
+ * The linkage needs judgement — "Catalyst is the starter that pays for the rest"
+ * serves "land two retained clients" only if you know what both mean — so a model
+ * draws it. The progress does not: it is criteria closed over criteria written,
+ * counted here, because a model returning "64%" says something unfalsifiable
+ * about a goal it cannot measure.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+interface GoalLink {
+  goalId: string;
+  projects: string[];
+}
+
+export interface GoalLinks {
+  generatedAt: string;
+  /** Hash of the goals and projects the linkage was drawn from. */
+  inputs: string;
+  links: GoalLink[];
+}
+
+export interface GoalProgress {
+  projects: string[];
+  closed: number;
+  written: number;
+}
+
+function goalLinksPath(): string {
+  return resolve(paths.state(), "goal-links.json");
+}
+
+export function readGoalLinks(): GoalLinks | null {
+  const path = goalLinksPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as GoalLinks;
+    return Array.isArray(parsed.links) && parsed.generatedAt ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeGoalLinks(links: GoalLinks): Promise<void> {
+  await writeFile(goalLinksPath(), `${JSON.stringify(links, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * A stable fingerprint of what the linkage was drawn from, so a stop where
+ * neither the goals nor the projects moved costs nothing.
+ */
+export function linkInputs(goalIds: string[], projectSlugs: string[]): string {
+  return Bun.hash(
+    JSON.stringify([[...goalIds].sort(), [...projectSlugs].sort()])
+  ).toString(36);
+}
+
+/**
+ * Counted, not estimated. A goal nothing serves has no progress rather than
+ * zero — "no project serves this yet" is the answer worth showing.
+ */
+export function progressFor(
+  goalId: string,
+  links: GoalLinks | null,
+  criteriaBySlug: Map<string, { closed: number; written: number }>
+): GoalProgress | null {
+  const projects = links?.links.find((l) => l.goalId === goalId)?.projects ?? [];
+  const known = projects.filter((slug) => criteriaBySlug.has(slug));
+  if (known.length === 0) return null;
+  let closed = 0;
+  let written = 0;
+  for (const slug of known) {
+    const counts = criteriaBySlug.get(slug) as { closed: number; written: number };
+    closed += counts.closed;
+    written += counts.written;
+  }
+  return { projects: known, closed, written };
+}

package/src/hooks/lib/models.ts

@@ -5,7 +5,7 @@
 import type { AgentType } from "./agent";
 
 export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
-export const SONNET_MODEL = "claude-sonnet-4-6";
+export const SONNET_MODEL = "claude-sonnet-5";
 export const FABLE_MODEL = "claude-fable-5";
 
 /**

package/src/hooks/lib/projects.ts

@@ -45,6 +45,9 @@ export interface ProjectProgress {
   serves?: ServesKind;
   serves_note?: string;
   serves_by?: ServesAuthority;
+  /** The user's own placement on the grid, which overrules both guesses. */
+  placed?: string;
+  placed_by?: ServesAuthority;
   // ISA body sections
   problem?: string;
   goal?: string;
@@ -284,6 +287,8 @@ export function writeProject(p: ProjectProgress): void {
   if (p.serves) meta.serves = p.serves;
   if (p.serves_note) meta.serves_note = p.serves_note;
   if (p.serves_by) meta.serves_by = p.serves_by;
+  if (p.placed) meta.placed = p.placed;
+  if (p.placed_by) meta.placed_by = p.placed_by;
   writeFileSync(ensureAndGetIsaFile(p.name), stringify(meta, buildBody(p)), "utf-8");
 }
 

package/src/hooks/lib/settings.ts

@@ -30,6 +30,8 @@ export interface PalSettingsData {
    * paths whose contents are never stored; it cannot shrink it.
    */
   ledger?: { redactPaths?: string[] };
+  /** Control-room ranking knobs and attention sources — see src/tools/control-room/prefs.ts. */
+  controlRoom?: Record<string, unknown>;
   /** Contextual-steering user extension: personal rules + shipped rules to suppress by tag. */
   steering?: {
     disable?: string[];

package/src/hooks/lib/telos-goals.ts

@@ -82,6 +82,11 @@ function isScaffolding(line: string): boolean {
   return !l || l.startsWith("<!--") || l.startsWith("-->") || /^(-{3,}|_{3,})$/.test(l);
 }
 
+/** A scaffold's empty bullet is punctuation, not a goal you stated. */
+function hasWords(text: string): boolean {
+  return /[a-z0-9]/i.test(text);
+}
+
 /**
  * Bullets are entries when a block has them; otherwise the paragraph is the
  * entry. Both shapes ship — the scaffold offers horizon headings with bullets,
@@ -90,10 +95,11 @@ function isScaffolding(line: string): boolean {
 function entriesIn(lines: string[]): string[] {
   const bullets = lines
     .filter((l) => /^\s*[-*+]\s+\S/.test(l))
-    .map((l) => l.replace(/^\s*[-*+]\s+/, "").trim());
+    .map((l) => l.replace(/^\s*[-*+]\s+/, "").trim())
+    .filter(hasWords);
   if (bullets.length > 0) return bullets;
   const paragraph = lines.join(" ").trim();
-  return paragraph ? [paragraph] : [];
+  return hasWords(paragraph) ? [paragraph] : [];
 }
 
 function goalsFrom(content: string): TelosGoal[] {

package/src/hooks/lib/token-usage.ts

@@ -16,6 +16,8 @@ type TokenCaller =
   | "relationship"
   | "self-model"
   | "agenda-serves"
+  | "agenda-goal-links"
+  | "agenda-waiting-on"
   | "agenda-moves";
 
 interface TokenUsageEntry {

package/src/tools/agent/project.ts

@@ -42,13 +42,16 @@ import {
 import { isServesKind, SERVES_KINDS, setServes } from "../../hooks/lib/serves";
 import {
   archiveLine,
-  dropEmptyArchiveHeadings,
+  completeIsc,
   encodeIscText,
   ISC_BOX,
+  type IscMove,
+  type IscSections,
   iscTitle,
   nextIscId,
   parseIscs,
   removeIscLine,
+  reopenIsc,
   selectIscs,
   taskSlug,
 } from "../lib/project-isc";
@@ -440,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
@@ -460,22 +471,13 @@ 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 });
 }