portable-agent-layer 0.70.0 → 0.71.0

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 "../agent/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>
+  );
+}

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

@@ -0,0 +1,67 @@
+import type { AgentsRow, AgentsView } from "../data";
+import { Panel, Pending, useLoaded } from "./panel";
+
+function Row({ r, max }: { r: AgentsRow; max: number }) {
+  return (
+    <tr>
+      <td>
+        {r.slug}
+        <span className="bar">
+          <i style={{ width: `${(r.actions / max) * 100}%` }} />
+        </span>
+      </td>
+      <td className="num">{r.actions}</td>
+      <td>
+        <span className="runtimes">
+          {Object.entries(r.runtimes).map(([runtime, n]) => (
+            <span key={runtime} className="tag">
+              {runtime} {n}
+            </span>
+          ))}
+        </span>
+      </td>
+      <td className="num">{r.machines}</td>
+      <td className="num">{r.actors}</td>
+      <td className="num">{r.sessions}</td>
+    </tr>
+  );
+}
+
+export function Agents() {
+  const view = useLoaded<AgentsView>("/api/agents");
+  const max =
+    view.state === "ready" ? Math.max(1, ...view.data.projects.map((p) => p.actions)) : 1;
+  return (
+    <Panel
+      index="04 · activity"
+      title="Agents at work"
+      span={7}
+      order={3}
+      aside={view.state === "ready" ? `since ${view.data.since.slice(0, 10)}` : ""}
+    >
+      <Pending value={view} />
+      {view.state === "ready" && view.data.projects.length === 0 && (
+        <div className="empty">No recorded actions in the window.</div>
+      )}
+      {view.state === "ready" && view.data.projects.length > 0 && (
+        <table>
+          <thead>
+            <tr>
+              <th>project</th>
+              <th className="num">actions</th>
+              <th>runtimes</th>
+              <th className="num">machines</th>
+              <th className="num">actors</th>
+              <th className="num">sessions</th>
+            </tr>
+          </thead>
+          <tbody>
+            {view.data.projects.map((r) => (
+              <Row key={r.slug} r={r} max={max} />
+            ))}
+          </tbody>
+        </table>
+      )}
+    </Panel>
+  );
+}