portable-agent-layer 0.72.0 → 0.73.0

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

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

@@ -14,11 +14,19 @@ import {
 } from "../../hooks/lib/algorithm-review";
 import { loadAnalyzeNudge } from "../../hooks/lib/analyze-nudge";
 import { paths } from "../../hooks/lib/paths";
-import { isStale, type ProjectProgress, readAllProjects } from "../../hooks/lib/projects";
+import {
+  isStale,
+  type ProjectProgress,
+  readAllProjects,
+  type ServesAuthority,
+  type ServesKind,
+} from "../../hooks/lib/projects";
 import { readProjectHistory } from "../../hooks/lib/work-tracking";
 import { anchorSlugOf, type LedgerFilter, queryLedger } from "../ledger/query";
+import { viewStats } from "../ledger/view";
 import { type HandoffEntry, readHandoffs } from "../lib/handoff-note";
 import { parseIscs } from "../lib/project-isc";
+import { readSnoozes, snoozedUntil } from "./snooze";
 
 const DAY_MS = 86_400_000;
 const HANDOFF_FRESH_DAYS = 7;
@@ -38,6 +46,19 @@ export interface ProjectCard {
   lastSession: { date: string; title: string } | null;
   sessions30d: number;
   asking: string[];
+  /** What the project is for, and who decided — the fact importance is ranked from. */
+  serves: ServesKind | null;
+  servesBy: ServesAuthority | null;
+  /** Which agents touched it, and how often, over the same 30 days. */
+  runtimes: Record<string, number>;
+}
+
+export interface SummaryView {
+  since: string;
+  days: number;
+  actions: number;
+  refusals: number;
+  rating: number | null;
 }
 
 export interface HandoffCard {
@@ -91,7 +112,7 @@ export interface SignalView {
   };
 }
 
-export interface AgentsRow {
+interface AgentsRow {
   slug: string;
   actions: number;
   runtimes: Record<string, number>;
@@ -142,10 +163,29 @@ export function askingReasons(
   return reasons;
 }
 
+function runtimesBySlug(since: Date): Map<string, Record<string, number>> {
+  const bySlug = Map.groupBy(
+    queryLedger({ since }),
+    (e) => anchorSlugOf(e.target) ?? "unanchored"
+  );
+  return new Map(
+    [...bySlug.entries()].map(([slug, entries]) => [
+      slug,
+      Object.fromEntries(
+        Map.groupBy(entries, (e) => e.runtime)
+          .entries()
+          .map(([runtime, group]) => [runtime, group.length])
+      ),
+    ])
+  );
+}
+
 function toCard(
   p: ProjectProgress,
   handoff: HandoffEntry | undefined,
-  now: Date
+  now: Date,
+  runtimes: Record<string, number>,
+  snoozes: Record<string, string>
 ): ProjectCard {
   const path = p.path ?? null;
   const stale = isStale(p);
@@ -158,7 +198,9 @@ function toCard(
     updated: p.updated,
     ageDays: daysBetween(p.updated, now),
     stale,
-    openIscs: parseIscs(p.criteria ?? "").filter((i) => i.status === "open").length,
+    openIscs: parseIscs(p.criteria ?? "").filter(
+      (i) => i.status === "open" && !snoozedUntil(p.name, i.id, snoozes)
+    ).length,
     next: p.next ?? [],
     blockers: p.blockers ?? [],
     lastSession: last ? { date: last.date, title: last.title } : null,
@@ -167,6 +209,9 @@ function toCard(
       new Date(now.getTime() - SESSION_WINDOW_DAYS * DAY_MS)
     ),
     asking: askingReasons(p, handoff, stale),
+    serves: p.serves ?? null,
+    servesBy: p.serves_by ?? null,
+    runtimes,
   };
 }
 
@@ -178,9 +223,17 @@ export function sortBoard(cards: ProjectCard[]): ProjectCard[] {
 
 export function board(now: Date = new Date()): ProjectCard[] {
   const handoffs = new Map(freshHandoffs(now));
+  const runtimes = runtimesBySlug(new Date(now.getTime() - SESSION_WINDOW_DAYS * DAY_MS));
+  const snoozes = readSnoozes(now);
   return sortBoard(
     readAllProjects().map((p) =>
-      toCard(p, p.path ? handoffs.get(p.path) : undefined, now)
+      toCard(
+        p,
+        p.path ? handoffs.get(p.path) : undefined,
+        now,
+        runtimes.get(p.name) ?? {},
+        snoozes
+      )
     )
   );
 }
@@ -296,6 +349,24 @@ export function signal(now: Date = new Date()): SignalView {
   };
 }
 
+/**
+ * The morning tile: how much happened, how much was refused, and how it was
+ * rated — three numbers over one window, so the page asks once instead of
+ * pulling the whole ledger down to count it in the browser.
+ */
+export function summary(days: number, now: Date = new Date()): SummaryView {
+  const since = new Date(now.getTime() - days * DAY_MS);
+  const stats = viewStats(queryLedger({ since }));
+  const ratings = readSynthesis()?.ratings as SignalView["ratings"] | undefined;
+  return {
+    since: since.toISOString(),
+    days,
+    actions: stats.total,
+    refusals: stats.refusals,
+    rating: ratings?.recentAvg ?? null,
+  };
+}
+
 function count<T>(items: T[], key: (item: T) => string): number {
   return new Set(items.map(key)).size;
 }

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

@@ -0,0 +1,158 @@
+/**
+ * One project, assembled. The board answers "which projects want you"; this
+ * answers "what is the state of this one" — the criteria it is judged against,
+ * the decisions behind it, and what the agents have been doing to it.
+ *
+ * Two of its sections live on the record as prose rather than fields, so they
+ * are parsed here: decisions are written by `add-decision` in a fixed shape, and
+ * context is whatever bullets the ISA carries.
+ */
+
+import {
+  readProject,
+  type ServesAuthority,
+  type ServesKind,
+} from "../../hooks/lib/projects";
+import { SERVES_MEANING } from "../../hooks/lib/serves";
+import { anchorSlugOf, queryLedger } from "../ledger/query";
+import { type LedgerViewRow, viewRows } from "../ledger/view";
+import type { HandoffEntry } from "../lib/handoff-note";
+import { type Isc, parseIscs } from "../lib/project-isc";
+import { freshHandoffs, handoffSentence } from "./data";
+import { readSnoozes, snoozedUntil } from "./snooze";
+
+const DAY_MS = 86_400_000;
+const RECENT_ACTIONS = 8;
+const ACTIVITY_WINDOW_DAYS = 14;
+
+export interface Decision {
+  date: string | null;
+  text: string;
+  why: string | null;
+}
+
+interface DetailHandoff {
+  sentence: string;
+  full: string;
+  at: string;
+  source: HandoffEntry["source"];
+  waitingOn: string | null;
+}
+
+export interface SnoozableIsc extends Isc {
+  snoozedUntil: string | null;
+}
+
+export interface ProjectDetailView {
+  slug: string;
+  status: string;
+  path: string | null;
+  remote: string | null;
+  goal: string;
+  purpose: string;
+  serves: ServesKind | null;
+  servesBy: ServesAuthority | null;
+  placed: string | null;
+  updated: string;
+  iscs: SnoozableIsc[];
+  next: string[];
+  blockers: string[];
+  decisions: Decision[];
+  context: string[];
+  handoff: DetailHandoff | null;
+  runtimes: Record<string, number>;
+  recent: LedgerViewRow[];
+}
+
+const DECISION_LINE = /^-\s*(\d{4}-\d{2}-\d{2}):\s*(.+?)(?:\s*\((.+)\))?\s*$/;
+
+/** `add-decision` writes "- YYYY-MM-DD: what (why)"; anything else is kept whole. */
+export function parseDecisions(section: string | undefined): Decision[] {
+  if (!section) return [];
+  const decisions: Decision[] = [];
+  for (const line of section.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = DECISION_LINE.exec(trimmed);
+    decisions.push(
+      match
+        ? { date: match[1], text: match[2].trim(), why: match[3]?.trim() ?? null }
+        : { date: null, text: trimmed.replace(/^-\s*/, ""), why: null }
+    );
+  }
+  return decisions.reverse();
+}
+
+/** Bullets when the section has them, otherwise each non-empty line stands alone. */
+export function parseBullets(section: string | undefined): string[] {
+  if (!section) return [];
+  const lines = section
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const bullets = lines.filter((l) => /^[-*+]\s+\S/.test(l));
+  const chosen = bullets.length > 0 ? bullets : lines;
+  return chosen.map((l) => l.replace(/^[-*+]\s+/, ""));
+}
+
+function detailHandoff(entry: HandoffEntry | undefined): DetailHandoff | null {
+  if (!entry) return null;
+  return {
+    sentence: handoffSentence(entry.handoff),
+    full: entry.handoff,
+    at: entry.timestamp,
+    source: entry.source,
+    waitingOn: entry.waitingOn ?? null,
+  };
+}
+
+function activity(slug: string, since: Date) {
+  const entries = queryLedger({ since }).filter((e) => anchorSlugOf(e.target) === slug);
+  const runtimes = Object.fromEntries(
+    Map.groupBy(entries, (e) => e.runtime)
+      .entries()
+      .map(([runtime, group]) => [runtime, group.length])
+  );
+  return { runtimes, recent: viewRows(entries).slice(0, RECENT_ACTIONS) };
+}
+
+export function projectDetail(
+  slug: string,
+  now: Date = new Date()
+): ProjectDetailView | null {
+  const project = readProject(slug);
+  if (!project) return null;
+
+  const handoffs = new Map(freshHandoffs(now));
+  const snoozes = readSnoozes(now);
+  const { runtimes, recent } = activity(
+    slug,
+    new Date(now.getTime() - ACTIVITY_WINDOW_DAYS * DAY_MS)
+  );
+
+  return {
+    slug: project.name,
+    status: project.status,
+    path: project.path ?? null,
+    remote: project.remote ?? null,
+    goal: project.goal ?? "",
+    purpose: project.serves
+      ? SERVES_MEANING[project.serves]
+      : "no purpose on record yet — set one to rank it",
+    serves: project.serves ?? null,
+    servesBy: project.serves_by ?? null,
+    placed: project.placed ?? null,
+    updated: project.updated,
+    iscs: [
+      ...parseIscs(project.criteria ?? ""),
+      ...parseIscs(project.changelog ?? ""),
+    ].map((isc) => ({ ...isc, snoozedUntil: snoozedUntil(slug, isc.id, snoozes) })),
+    next: project.next ?? [],
+    blockers: project.blockers ?? [],
+    decisions: parseDecisions(project.decisions),
+    context: parseBullets(project.context),
+    handoff: detailHandoff(project.path ? handoffs.get(project.path) : undefined),
+    runtimes,
+    recent,
+  };
+}

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

@@ -12,7 +12,11 @@
  */
 
 import {
-  PROJECT_STALE_DAYS_DEFAULT,
+  type GoalProgress,
+  progressFor,
+  readGoalLinks,
+} from "../../hooks/lib/goal-links";
+import {
   type ProjectProgress,
   readAllProjects,
   type ServesAuthority,
@@ -21,9 +25,11 @@ import {
 import { isImportant, SERVES_MEANING } from "../../hooks/lib/serves";
 import { dueFrom, readTelosGoals, type TelosGoal } from "../../hooks/lib/telos-goals";
 import type { HandoffEntry } from "../lib/handoff-note";
+import { parseIscs } from "../lib/project-isc";
 import { freshHandoffs } from "./data";
+import { type ControlRoomPrefs, readPrefs } from "./prefs";
+import { readSnoozes, snoozedUntil } from "./snooze";
 
-const URGENT_WITHIN_DAYS = 14;
 const RANKED_STATUSES = new Set(["active", "paused"]);
 
 export interface MatrixItem {
@@ -33,12 +39,16 @@ export interface MatrixItem {
   detail: string;
   urgent: boolean;
   important: boolean;
+  /** The quadrant the user pinned this to, which overrules both guesses. */
+  placed: string | null;
   urgentBecause: string[];
   importantBecause: string;
   serves: ServesKind | null;
   servesBy: ServesAuthority | null;
   due: string | null;
   waitingOn: string | null;
+  /** Counted from the criteria of the projects serving it, or null when none does. */
+  progress: { projects: string[]; closed: number; written: number } | null;
 }
 
 export interface Matrix {
@@ -50,11 +60,11 @@ export interface Matrix {
   unranked: number;
 }
 
-function dueSoon(due: string | null, now: Date): boolean {
+function dueSoon(due: string | null, now: Date, withinDays: number): boolean {
   if (!due) return false;
   const at = new Date(`${due}T23:59:59Z`).getTime();
   if (!Number.isFinite(at)) return false;
-  return at - now.getTime() <= URGENT_WITHIN_DAYS * 86_400_000;
+  return at - now.getTime() <= withinDays * 86_400_000;
 }
 
 function earliestDue(lines: string[]): string | null {
@@ -67,10 +77,10 @@ function plural(count: number, noun: string): string {
 }
 
 /** Measured against the grid's own clock, so a placement can be pinned in a test. */
-function quietSince(updated: string | undefined, now: Date): boolean {
+function quietSince(updated: string | undefined, now: Date, afterDays: number): boolean {
   if (!updated) return false;
   const age = now.getTime() - new Date(updated).getTime();
-  return Number.isFinite(age) && age > PROJECT_STALE_DAYS_DEFAULT * 86_400_000;
+  return Number.isFinite(age) && age > afterDays * 86_400_000;
 }
 
 /**
@@ -83,15 +93,20 @@ function projectUrgency(
   waiting: string | null,
   due: string | null,
   hasHandoff: boolean,
-  now: Date
+  now: Date,
+  prefs: ControlRoomPrefs
 ): string[] {
   const reasons: string[] = [];
   const blockers = p.blockers?.length ?? 0;
   if (blockers > 0) reasons.push(plural(blockers, "blocker"));
   if (waiting) reasons.push("waiting on you");
   else if (hasHandoff) reasons.push("handoff in progress");
-  if (dueSoon(due, now)) reasons.push(`next step dated ${due}`);
-  if (important && p.status === "active" && quietSince(p.updated, now)) {
+  if (dueSoon(due, now, prefs.urgentWithinDays)) reasons.push(`next step dated ${due}`);
+  if (
+    important &&
+    p.status === "active" &&
+    quietSince(p.updated, now, prefs.quietAfterDays)
+  ) {
     reasons.push("gone quiet");
   }
   return reasons;
@@ -100,7 +115,8 @@ function projectUrgency(
 function projectItem(
   p: ProjectProgress,
   handoffs: Map<string, HandoffEntry>,
-  now: Date
+  now: Date,
+  prefs: ControlRoomPrefs
 ): MatrixItem {
   const entry = p.path ? handoffs.get(p.path) : undefined;
   const waiting = entry?.waitingOn ?? null;
@@ -112,17 +128,20 @@ function projectItem(
     waiting,
     due,
     entry !== undefined,
-    now
+    now,
+    prefs
   );
 
+  const placed = placementOf(p.placed);
   return {
     kind: "project",
     id: p.name,
     label: p.name,
     detail: p.serves_note ?? p.next?.[0] ?? "",
-    urgent: urgentBecause.length > 0,
-    important,
-    urgentBecause,
+    urgent: placed ? placed.urgent : urgentBecause.length > 0,
+    important: placed ? placed.important : important,
+    placed: p.placed ?? null,
+    urgentBecause: placed ? ["placed by you", ...urgentBecause] : urgentBecause,
     importantBecause: p.serves
       ? SERVES_MEANING[p.serves]
       : "no purpose on record yet — set one to rank it",
@@ -130,11 +149,17 @@ function projectItem(
     servesBy: p.serves_by ?? null,
     due,
     waitingOn: waiting,
+    progress: null,
   };
 }
 
-function goalItem(goal: TelosGoal, now: Date): MatrixItem {
-  const urgent = dueSoon(goal.due, now);
+function goalItem(
+  goal: TelosGoal,
+  now: Date,
+  prefs: ControlRoomPrefs,
+  progress: GoalProgress | null
+): MatrixItem {
+  const urgent = dueSoon(goal.due, now, prefs.urgentWithinDays);
   return {
     kind: "goal",
     id: goal.id,
@@ -142,15 +167,54 @@ function goalItem(goal: TelosGoal, now: Date): MatrixItem {
     detail: goal.horizon ?? goal.text,
     urgent,
     important: true,
+    placed: null,
     urgentBecause: urgent ? [`dated ${goal.due}`] : [],
     importantBecause: "a goal you stated",
     serves: null,
     servesBy: null,
     due: goal.due,
     waitingOn: null,
+    progress,
   };
 }
 
+/** The user's placement, translated back into the two axes it stands for. */
+function placementOf(
+  placed: string | undefined
+): { urgent: boolean; important: boolean } | null {
+  switch (placed) {
+    case "now":
+      return { urgent: true, important: true };
+    case "plan":
+      return { urgent: false, important: true };
+    case "noise":
+      return { urgent: true, important: false };
+    case "later":
+      return { urgent: false, important: false };
+    default:
+      return null;
+  }
+}
+
+/** Criteria closed over criteria written, with snoozed and retired ones left out. */
+function criteriaBySlug(
+  projects: ProjectProgress[],
+  snoozes: Record<string, string>
+): Map<string, { closed: number; written: number }> {
+  return new Map(
+    projects.map((p) => {
+      const iscs = [
+        ...parseIscs(p.criteria ?? ""),
+        ...parseIscs(p.changelog ?? ""),
+      ].filter((i) => i.status !== "retired" && !snoozedUntil(p.name, i.id, snoozes));
+      return [
+        p.name,
+        { closed: iscs.filter((i) => i.status === "done").length, written: iscs.length },
+      ];
+    })
+  );
+}
+
 function quadrant(items: MatrixItem[], urgent: boolean, important: boolean) {
   return items
     .filter((i) => i.urgent === urgent && i.important === important)
@@ -172,11 +236,19 @@ export function buildMatrix(items: MatrixItem[], unranked: number): Matrix {
 }
 
 export function matrix(now: Date = new Date()): Matrix {
+  const prefs = readPrefs();
   const handoffs = new Map(freshHandoffs(now));
-  const ranked = readAllProjects().filter((p) => RANKED_STATUSES.has(p.status));
+  const all = readAllProjects();
+  const ranked = all.filter((p) => RANKED_STATUSES.has(p.status));
+  const links = readGoalLinks();
+  const criteria = criteriaBySlug(all, readSnoozes(now));
   const items = [
-    ...ranked.map((p) => projectItem(p, handoffs, now)),
-    ...readTelosGoals().map((g) => goalItem(g, now)),
+    ...ranked.map((p) => projectItem(p, handoffs, now, prefs)),
+    ...(prefs.rankGoals
+      ? readTelosGoals().map((g) =>
+          goalItem(g, now, prefs, progressFor(g.id, links, criteria))
+        )
+      : []),
   ];
   return buildMatrix(items, ranked.filter((p) => !p.serves).length);
 }