portable-agent-layer 0.70.0 → 0.72.0

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

@@ -0,0 +1,332 @@
+/**
+ * The numbers behind the control room. Every panel reads through the same
+ * functions the session-start reminder uses, so the page and the agent can
+ * never disagree about a project's state.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { loadReflectNudge } from "../../hooks/handlers/reflect-trigger";
+import { type AgendaMove, readAgenda } from "../../hooks/lib/agenda-store";
+import {
+  isMaintainerEnv,
+  loadAlgorithmReviewNudge,
+} 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 { readProjectHistory } from "../../hooks/lib/work-tracking";
+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;
+const SESSION_WINDOW_DAYS = 30;
+const SERIES_LENGTH = 60;
+
+export interface ProjectCard {
+  slug: string;
+  path: string | null;
+  status: string;
+  updated: string;
+  ageDays: number;
+  stale: boolean;
+  openIscs: number;
+  next: string[];
+  blockers: string[];
+  lastSession: { date: string; title: string } | null;
+  sessions30d: number;
+  asking: string[];
+}
+
+export interface HandoffCard {
+  slug: string | null;
+  label: string;
+  cwd: string;
+  title: string;
+  sentence: string;
+  handoff: string;
+  at: string;
+  ageDays: number;
+  source: HandoffEntry["source"];
+}
+
+export interface AgendaView {
+  generatedAt: string | null;
+  ageHours: number | null;
+  stale: boolean;
+  moves: AgendaMove[];
+}
+
+export interface DueBadge {
+  state: "due" | "clear" | "n/a";
+  detail: string;
+}
+
+export interface RatingPoint {
+  ts: string;
+  rating: number;
+}
+
+export interface SignalView {
+  synthesizedAt: string | null;
+  ratings: {
+    count: number;
+    avg: number;
+    recentAvg: number;
+    lowCount: number;
+    trend: string;
+  } | null;
+  algorithm: {
+    reflectionCount: number;
+    passRate: number;
+    avgSentiment: number;
+  } | null;
+  series: RatingPoint[];
+  due: {
+    analysis: DueBadge;
+    algorithmReview: DueBadge;
+    relationshipReflect: DueBadge;
+  };
+}
+
+export interface AgentsRow {
+  slug: string;
+  actions: number;
+  runtimes: Record<string, number>;
+  machines: number;
+  actors: number;
+  sessions: number;
+}
+
+export interface AgentsView {
+  since: string;
+  projects: AgentsRow[];
+}
+
+function daysBetween(from: string, now: Date): number {
+  const age = now.getTime() - new Date(from).getTime();
+  return Number.isFinite(age) && age > 0 ? Math.floor(age / DAY_MS) : 0;
+}
+
+function isoDay(at: Date): string {
+  return at.toISOString().slice(0, 10);
+}
+
+function sessionsSince(path: string | null, since: Date): number {
+  if (!path) return 0;
+  const floor = isoDay(since);
+  return readProjectHistory(path, 200).filter((h) => h.date >= floor).length;
+}
+
+export function freshHandoffs(now: Date): [string, HandoffEntry][] {
+  return Object.entries(readHandoffs()).filter(
+    ([, h]) =>
+      h.status === "in-progress" &&
+      h.handoff &&
+      daysBetween(h.timestamp, now) < HANDOFF_FRESH_DAYS
+  );
+}
+
+export function askingReasons(
+  p: ProjectProgress,
+  handoff: HandoffEntry | undefined,
+  stale: boolean
+): string[] {
+  const reasons: string[] = [];
+  if (handoff) reasons.push("handoff in progress");
+  const blockers = p.blockers?.length ?? 0;
+  if (blockers > 0) reasons.push(blockers === 1 ? "1 blocker" : `${blockers} blockers`);
+  if (stale && p.status === "active") reasons.push("gone quiet");
+  return reasons;
+}
+
+function toCard(
+  p: ProjectProgress,
+  handoff: HandoffEntry | undefined,
+  now: Date
+): ProjectCard {
+  const path = p.path ?? null;
+  const stale = isStale(p);
+  const history = path ? readProjectHistory(path, 1) : [];
+  const last = history.at(-1);
+  return {
+    slug: p.name,
+    path,
+    status: p.status,
+    updated: p.updated,
+    ageDays: daysBetween(p.updated, now),
+    stale,
+    openIscs: parseIscs(p.criteria ?? "").filter((i) => i.status === "open").length,
+    next: p.next ?? [],
+    blockers: p.blockers ?? [],
+    lastSession: last ? { date: last.date, title: last.title } : null,
+    sessions30d: sessionsSince(
+      path,
+      new Date(now.getTime() - SESSION_WINDOW_DAYS * DAY_MS)
+    ),
+    asking: askingReasons(p, handoff, stale),
+  };
+}
+
+export function sortBoard(cards: ProjectCard[]): ProjectCard[] {
+  return [...cards].sort(
+    (a, b) => b.asking.length - a.asking.length || b.updated.localeCompare(a.updated)
+  );
+}
+
+export function board(now: Date = new Date()): ProjectCard[] {
+  const handoffs = new Map(freshHandoffs(now));
+  return sortBoard(
+    readAllProjects().map((p) =>
+      toCard(p, p.path ? handoffs.get(p.path) : undefined, now)
+    )
+  );
+}
+
+export function firstSentence(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const match = new RegExp(/^.*?[.!?](?=\s|$)/).exec(flat);
+  return match ? match[0] : flat;
+}
+
+/** An automatic handoff is a transcript excerpt; the user's own words are the part worth a sentence. */
+export function handoffSentence(text: string): string {
+  const [, userTurn] = text.split(/Last user message:\s*/, 2);
+  const spoken = userTurn ? userTurn.split(/\s*Last assistant response:/, 1)[0] : text;
+  return firstSentence(spoken);
+}
+
+export function handoffs(now: Date = new Date()): HandoffCard[] {
+  const slugByPath = new Map(
+    readAllProjects()
+      .filter((p) => p.path)
+      .map((p) => [p.path as string, p.name])
+  );
+  return freshHandoffs(now)
+    .map(([cwd, h]) => ({
+      slug: slugByPath.get(cwd) ?? null,
+      label: slugByPath.get(cwd) ?? basename(cwd),
+      cwd,
+      title: h.title,
+      sentence: handoffSentence(h.handoff),
+      handoff: h.handoff,
+      at: h.timestamp,
+      ageDays: daysBetween(h.timestamp, now),
+      source: h.source,
+    }))
+    .sort((a, b) => b.at.localeCompare(a.at));
+}
+
+/**
+ * The page never writes the agenda — it says how old the one on disk is, so a
+ * morning reading yesterday's three moves knows that is what it is looking at.
+ */
+export function agenda(now: Date = new Date()): AgendaView {
+  const stored = readAgenda();
+  if (!stored) return { generatedAt: null, ageHours: null, stale: true, moves: [] };
+  const ageHours = (now.getTime() - new Date(stored.generatedAt).getTime()) / 3_600_000;
+  return {
+    generatedAt: stored.generatedAt,
+    ageHours: Math.max(0, Math.round(ageHours)),
+    stale: !(ageHours < 24),
+    moves: stored.moves,
+  };
+}
+
+/** The nudge text is the verdict; the badge only strips its heading and emoji. */
+export function badgeFromNudge(nudge: string): DueBadge {
+  if (!nudge) return { state: "clear", detail: "" };
+  const detail = nudge.split("\n").slice(1).join(" ").replace(/^\W+/, "").trim();
+  return { state: "due", detail };
+}
+
+export function dueBadges(now: Date = new Date(), maintainer = isMaintainerEnv()) {
+  return {
+    analysis: badgeFromNudge(loadAnalyzeNudge(now)),
+    algorithmReview: maintainer
+      ? badgeFromNudge(loadAlgorithmReviewNudge(now))
+      : { state: "n/a" as const, detail: "only in a maintainer checkout" },
+    relationshipReflect: badgeFromNudge(loadReflectNudge()),
+  };
+}
+
+export function ratingSeries(limit = SERIES_LENGTH): RatingPoint[] {
+  const file = resolve(paths.signals(), "ratings.jsonl");
+  if (!existsSync(file)) return [];
+  const points: RatingPoint[] = [];
+  for (const line of readFileSync(file, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line) as { ts?: string; rating?: number };
+      if (typeof row.rating === "number" && row.ts)
+        points.push({ ts: row.ts, rating: row.rating });
+    } catch {}
+  }
+  return points.slice(-limit);
+}
+
+function readSynthesis(): Record<string, unknown> | null {
+  const file = resolve(paths.state(), "synthesis.json");
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function signal(now: Date = new Date()): SignalView {
+  const s = readSynthesis();
+  const ratings = s?.ratings as SignalView["ratings"] | undefined;
+  const algorithm = s?.algorithm as SignalView["algorithm"] | undefined;
+  return {
+    synthesizedAt: typeof s?.timestamp === "string" ? s.timestamp : null,
+    ratings: ratings ?? null,
+    algorithm: algorithm
+      ? {
+          reflectionCount: algorithm.reflectionCount,
+          passRate: algorithm.passRate,
+          avgSentiment: algorithm.avgSentiment,
+        }
+      : null,
+    series: ratingSeries(),
+    due: dueBadges(now),
+  };
+}
+
+function count<T>(items: T[], key: (item: T) => string): number {
+  return new Set(items.map(key)).size;
+}
+
+export function agentsAtWork(filter: LedgerFilter, now: Date = new Date()): AgentsView {
+  const since = filter.since ?? new Date(now.getTime() - SESSION_WINDOW_DAYS * DAY_MS);
+  const pathBySlug = new Map(
+    readAllProjects()
+      .filter((p) => p.path)
+      .map((p) => [p.name, p.path as string])
+  );
+  const bySlug = Map.groupBy(
+    queryLedger({ ...filter, since }),
+    (e) => anchorSlugOf(e.target) ?? "unanchored"
+  );
+  const projects = [...bySlug.entries()].map(([slug, entries]) => ({
+    slug,
+    actions: entries.length,
+    runtimes: Object.fromEntries(
+      Map.groupBy(entries, (e) => e.runtime)
+        .entries()
+        .map(([runtime, group]) => [runtime, group.length])
+    ),
+    machines: count(entries, (e) => e.machine),
+    actors: count(entries, (e) => e.actor),
+    sessions: sessionsSince(pathBySlug.get(slug) ?? null, since),
+  }));
+  return {
+    since: since.toISOString(),
+    projects: projects.sort(
+      (a, b) => b.actions - a.actions || a.slug.localeCompare(b.slug)
+    ),
+  };
+}

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

@@ -0,0 +1,182 @@
+/**
+ * The urgent/important grid, over projects and stated goals together.
+ *
+ * Two rules, both readable off disk, because a screen you open before a terminal
+ * cannot wait for a model. Importance comes from what a project serves, which
+ * PAL guesses once and the user can overrule. Urgency comes from what the files
+ * already say: a blocker, an unfinished handoff, a date coming up, or an
+ * important thing that has gone quiet.
+ *
+ * Every placement carries the reason it landed there, so a wrong guess argues
+ * with the user instead of hiding from them.
+ */
+
+import {
+  PROJECT_STALE_DAYS_DEFAULT,
+  type ProjectProgress,
+  readAllProjects,
+  type ServesAuthority,
+  type ServesKind,
+} 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 "../lib/handoff-note";
+import { freshHandoffs } from "./data";
+
+const URGENT_WITHIN_DAYS = 14;
+const RANKED_STATUSES = new Set(["active", "paused"]);
+
+export interface MatrixItem {
+  kind: "project" | "goal";
+  id: string;
+  label: string;
+  detail: string;
+  urgent: boolean;
+  important: boolean;
+  urgentBecause: string[];
+  importantBecause: string;
+  serves: ServesKind | null;
+  servesBy: ServesAuthority | null;
+  due: string | null;
+  waitingOn: string | null;
+}
+
+export interface Matrix {
+  now: MatrixItem[];
+  plan: MatrixItem[];
+  noise: MatrixItem[];
+  later: MatrixItem[];
+  /** Projects PAL has not guessed a purpose for yet — they rank as unimportant until it does. */
+  unranked: number;
+}
+
+function dueSoon(due: string | null, now: Date): 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;
+}
+
+function earliestDue(lines: string[]): string | null {
+  const dates = lines.map(dueFrom).filter((d): d is string => d !== null);
+  return dates.length > 0 ? dates.sort()[0] : null;
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** Measured against the grid's own clock, so a placement can be pinned in a test. */
+function quietSince(updated: string | undefined, now: Date): 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;
+}
+
+/**
+ * A fun project going quiet is just quiet. An important one going quiet is
+ * rotting, which is the only reading of staleness worth interrupting a morning for.
+ */
+function projectUrgency(
+  p: ProjectProgress,
+  important: boolean,
+  waiting: string | null,
+  due: string | null,
+  hasHandoff: boolean,
+  now: Date
+): 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)) {
+    reasons.push("gone quiet");
+  }
+  return reasons;
+}
+
+function projectItem(
+  p: ProjectProgress,
+  handoffs: Map<string, HandoffEntry>,
+  now: Date
+): MatrixItem {
+  const entry = p.path ? handoffs.get(p.path) : undefined;
+  const waiting = entry?.waitingOn ?? null;
+  const important = isImportant(p.serves);
+  const due = earliestDue(p.next ?? []);
+  const urgentBecause = projectUrgency(
+    p,
+    important,
+    waiting,
+    due,
+    entry !== undefined,
+    now
+  );
+
+  return {
+    kind: "project",
+    id: p.name,
+    label: p.name,
+    detail: p.serves_note ?? p.next?.[0] ?? "",
+    urgent: urgentBecause.length > 0,
+    important,
+    urgentBecause,
+    importantBecause: p.serves
+      ? SERVES_MEANING[p.serves]
+      : "no purpose on record yet — set one to rank it",
+    serves: p.serves ?? null,
+    servesBy: p.serves_by ?? null,
+    due,
+    waitingOn: waiting,
+  };
+}
+
+function goalItem(goal: TelosGoal, now: Date): MatrixItem {
+  const urgent = dueSoon(goal.due, now);
+  return {
+    kind: "goal",
+    id: goal.id,
+    label: goal.title,
+    detail: goal.horizon ?? goal.text,
+    urgent,
+    important: true,
+    urgentBecause: urgent ? [`dated ${goal.due}`] : [],
+    importantBecause: "a goal you stated",
+    serves: null,
+    servesBy: null,
+    due: goal.due,
+    waitingOn: null,
+  };
+}
+
+function quadrant(items: MatrixItem[], urgent: boolean, important: boolean) {
+  return items
+    .filter((i) => i.urgent === urgent && i.important === important)
+    .sort(
+      (a, b) =>
+        b.urgentBecause.length - a.urgentBecause.length || a.label.localeCompare(b.label)
+    );
+}
+
+/** @lintignore exercised directly by test/control-room-matrix.test.ts */
+export function buildMatrix(items: MatrixItem[], unranked: number): Matrix {
+  return {
+    now: quadrant(items, true, true),
+    plan: quadrant(items, false, true),
+    noise: quadrant(items, true, false),
+    later: quadrant(items, false, false),
+    unranked,
+  };
+}
+
+export function matrix(now: Date = new Date()): Matrix {
+  const handoffs = new Map(freshHandoffs(now));
+  const ranked = readAllProjects().filter((p) => RANKED_STATUSES.has(p.status));
+  const items = [
+    ...ranked.map((p) => projectItem(p, handoffs, now)),
+    ...readTelosGoals().map((g) => goalItem(g, now)),
+  ];
+  return buildMatrix(items, ranked.filter((p) => !p.serves).length);
+}

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

@@ -0,0 +1,150 @@
+/**
+ * The control room — one local page over ~/.pal, meant to be opened before a
+ * terminal. Loopback only, read only, no state of its own: every request goes
+ * back to the files.
+ *
+ * `pal cli server start|stop|status` owns the process; this file only serves.
+ */
+
+import { loadMachine } from "../../hooks/lib/machine";
+import { readAllProjects } from "../../hooks/lib/projects";
+import { isServesKind, setServes } from "../../hooks/lib/serves";
+import { type LedgerFilter, ledgerFiles, parseSince } from "../ledger/query";
+import { ledgerView } from "../ledger/view";
+import { agenda, agentsAtWork, board, handoffs, signal } from "./data";
+import { matrix } from "./matrix";
+import index from "./ui/index.html";
+
+export const DEFAULT_PORT = 7250;
+export const LOOPBACK = "127.0.0.1";
+
+export interface ServerStatus {
+  pid: number;
+  port: number;
+  startedAt: string;
+  ledgerFiles: number;
+  machine: string;
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, { status });
+}
+
+/** A window the page cannot parse is an error, not the whole ledger. */
+function filterFromQuery(params: URLSearchParams): LedgerFilter | string {
+  const filter: LedgerFilter = {};
+  const project = params.get("project");
+  if (project) filter.project = project;
+  for (const key of ["since", "until"] as const) {
+    const spec = params.get(key);
+    if (!spec) continue;
+    const at = parseSince(spec);
+    if (!at) return `Unrecognised ${key}: ${spec}`;
+    filter[key] = at;
+  }
+  return filter;
+}
+
+function projects(): Response {
+  const slugs = readAllProjects()
+    .map((p) => p.name)
+    .sort((a, b) => a.localeCompare(b));
+  return json(slugs.map((slug) => ({ slug })));
+}
+
+function withFilter(url: URL, view: (filter: LedgerFilter) => unknown): Response {
+  const filter = filterFromQuery(url.searchParams);
+  if (typeof filter === "string") return json({ error: filter }, 400);
+  return json(view(filter));
+}
+
+function status(port: number, startedAt: string): Response {
+  const body: ServerStatus = {
+    pid: process.pid,
+    port,
+    startedAt,
+    ledgerFiles: ledgerFiles().length,
+    machine: loadMachine().label,
+  };
+  return json(body);
+}
+
+/**
+ * The one thing the page may change. Importance is a guess until the user
+ * corrects it, and a correction is worth one click — but this stays a single
+ * named field on a single record, not a write surface over ~/.pal.
+ */
+async function overrideServes(request: Request): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ error: "expected a JSON body" }, 400);
+  }
+  const { project, serves, note } = (body ?? {}) as Record<string, unknown>;
+  if (typeof project !== "string" || !project) {
+    return json({ error: "project is required" }, 400);
+  }
+  if (!isServesKind(serves)) {
+    return json({ error: "serves must be goal, revenue or fun" }, 400);
+  }
+
+  const outcome = setServes({
+    name: project,
+    kind: serves,
+    note: typeof note === "string" && note ? note : undefined,
+    by: "user",
+  });
+  if (outcome === "missing") return json({ error: `no such project: ${project}` }, 404);
+  return json({ project, serves, by: "user" });
+}
+
+export function startControlRoom(port: number = DEFAULT_PORT) {
+  const startedAt = new Date().toISOString();
+  return Bun.serve({
+    hostname: LOOPBACK,
+    port,
+    development: false,
+    routes: { "/": index },
+    fetch(request, server) {
+      const url = new URL(request.url);
+      if (request.method === "POST" && url.pathname === "/api/serves") {
+        return overrideServes(request);
+      }
+      if (request.method !== "GET") return json({ error: "read only" }, 405);
+      switch (url.pathname) {
+        case "/api/agenda":
+          return json(agenda());
+        case "/api/matrix":
+          return json(matrix());
+        case "/api/board":
+          return json(board());
+        case "/api/handoffs":
+          return json(handoffs());
+        case "/api/signal":
+          return json(signal());
+        case "/api/agents":
+          return withFilter(url, agentsAtWork);
+        case "/api/ledger":
+          return withFilter(url, ledgerView);
+        case "/api/projects":
+          return projects();
+        case "/api/status":
+          return status(server.port ?? port, startedAt);
+        default:
+          return json({ error: "not found" }, 404);
+      }
+    },
+  });
+}
+
+function portFromArgv(argv: string[]): number {
+  const flag = argv.find((arg) => arg.startsWith("--port="));
+  const port = flag ? Number(flag.slice("--port=".length)) : DEFAULT_PORT;
+  return Number.isInteger(port) && port >= 0 ? port : DEFAULT_PORT;
+}
+
+if (import.meta.main) {
+  const server = startControlRoom(portFromArgv(process.argv.slice(2)));
+  console.log(`http://${LOOPBACK}:${server.port}/`);
+}

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

@@ -0,0 +1,43 @@
+import type { AgendaView } from "../data";
+import { Pending, useLoaded } from "./panel";
+
+function Age({ view }: { view: AgendaView }) {
+  if (!view.generatedAt) return <span className="agenda-age">never written</span>;
+  const hours = view.ageHours ?? 0;
+  const text = hours < 1 ? "written just now" : `written ${hours}h ago`;
+  return (
+    <span className={view.stale ? "agenda-age stale" : "agenda-age"}>
+      {view.stale ? `${text} — out of date` : text}
+    </span>
+  );
+}
+
+export function Agenda() {
+  const loaded = useLoaded<AgendaView>("/api/agenda");
+
+  return (
+    <section className="agenda">
+      <header>
+        <h2>Today</h2>
+        {loaded.state === "ready" && <Age view={loaded.data} />}
+      </header>
+      <Pending value={loaded} />
+      {loaded.state === "ready" &&
+        (loaded.data.moves.length === 0 ? (
+          <p className="agenda-empty">
+            No moves yet. They are written when a session ends — finish one and come back.
+          </p>
+        ) : (
+          <ol className="moves">
+            {loaded.data.moves.map((move, i) => (
+              <li key={move.move}>
+                <span className="rank">{i + 1}</span>
+                <span className="move">{move.move}</span>
+                <span className="because">{move.because}</span>
+              </li>
+            ))}
+          </ol>
+        ))}
+    </section>
+  );
+}