portable-agent-layer 0.71.0 → 0.73.0

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

@@ -9,14 +9,35 @@
 import { loadMachine } from "../../hooks/lib/machine";
 import { readAllProjects } from "../../hooks/lib/projects";
 import { isServesKind, setServes } from "../../hooks/lib/serves";
+import { PAGE_OUTCOMES } from "../ledger/outcomes";
 import { type LedgerFilter, ledgerFiles, parseSince } from "../ledger/query";
 import { ledgerView } from "../ledger/view";
-import { agenda, agentsAtWork, board, handoffs, signal } from "./data";
+import { attention, markRead } from "./attention";
+import { agenda, agentsAtWork, board, handoffs, signal, summary } from "./data";
+import { projectDetail } from "./detail";
 import { matrix } from "./matrix";
-import index from "./ui/index.html";
+import { type PrefUpdate, readPrefs, validatePrefs, writePrefs } from "./prefs";
+import { DEFAULT_PORT, LOOPBACK } from "./server-config";
+import { MAX_SNOOZE_DAYS, setSnooze } from "./snooze";
+import { indexHtml, staticAsset } from "./static";
+import {
+  type InstallSettings,
+  isQuadrant,
+  QUADRANTS,
+  readInstallSettings,
+  setIscStatus,
+  setPlacement,
+  type WriteOutcome,
+  writeInstallSettings,
+} from "./writes";
 
-export const DEFAULT_PORT = 7250;
-export const LOOPBACK = "127.0.0.1";
+export { DEFAULT_PORT, LOOPBACK };
+
+/**
+ * Every path the single-page app owns. Listed rather than wildcarded, because a
+ * blanket "/*" outranks the fetch handler and would swallow /api as well.
+ */
+const PAGE_ROUTES = ["/", "/projects", "/projects/:slug", "/log", "/settings"];
 
 export interface ServerStatus {
   pid: number;
@@ -30,11 +51,25 @@ 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. */
+const AUTHORITIES: readonly string[] = ["user", "agent"];
+
+/**
+ * Free-form on the record, so the page may name any of them: a runtime or
+ * machine label PAL has never seen simply matches nothing.
+ */
+const PASSTHROUGH = ["project", "runtime", "machine", "actor", "tool"] as const;
+
+/**
+ * A window the page cannot parse is an error, not the whole ledger. The same
+ * goes for a closed set it spells wrong — silently answering with every row
+ * would read as "no such filter" rather than "no such value".
+ */
 function filterFromQuery(params: URLSearchParams): LedgerFilter | string {
   const filter: LedgerFilter = {};
-  const project = params.get("project");
-  if (project) filter.project = project;
+  for (const key of PASSTHROUGH) {
+    const value = params.get(key);
+    if (value) filter[key] = value;
+  }
   for (const key of ["since", "until"] as const) {
     const spec = params.get(key);
     if (!spec) continue;
@@ -42,6 +77,18 @@ function filterFromQuery(params: URLSearchParams): LedgerFilter | string {
     if (!at) return `Unrecognised ${key}: ${spec}`;
     filter[key] = at;
   }
+  const outcome = params.get("outcome");
+  if (outcome) {
+    if (!(PAGE_OUTCOMES as readonly string[]).includes(outcome)) {
+      return `Unrecognised outcome: ${outcome}`;
+    }
+    filter.outcome = outcome;
+  }
+  const authority = params.get("authority");
+  if (authority) {
+    if (!AUTHORITIES.includes(authority)) return `Unrecognised authority: ${authority}`;
+    filter.authority = authority;
+  }
   return filter;
 }
 
@@ -52,6 +99,23 @@ function projects(): Response {
   return json(slugs.map((slug) => ({ slug })));
 }
 
+function oneProject(slug: string | null): Response {
+  if (!slug) return json({ error: "slug is required" }, 400);
+  const detail = projectDetail(slug);
+  return detail ? json(detail) : json({ error: `no such project: ${slug}` }, 404);
+}
+
+const SUMMARY_DAYS_DEFAULT = 14;
+const SUMMARY_DAYS_MAX = 365;
+
+function summaryFor(spec: string | null): Response {
+  const days = spec ? Number(spec) : SUMMARY_DAYS_DEFAULT;
+  if (!Number.isInteger(days) || days < 1 || days > SUMMARY_DAYS_MAX) {
+    return json({ error: `days must be a whole number of 1..${SUMMARY_DAYS_MAX}` }, 400);
+  }
+  return json(summary(days));
+}
+
 function withFilter(url: URL, view: (filter: LedgerFilter) => unknown): Response {
   const filter = filterFromQuery(url.searchParams);
   if (typeof filter === "string") return json({ error: filter }, 400);
@@ -99,19 +163,130 @@ async function overrideServes(request: Request): Promise<Response> {
   return json({ project, serves, by: "user" });
 }
 
+async function readBody(request: Request): Promise<Record<string, unknown> | null> {
+  try {
+    return ((await request.json()) ?? {}) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function answer(outcome: WriteOutcome, body: Record<string, unknown>): Response {
+  return outcome.ok
+    ? json({ ...body, changed: outcome.changed })
+    : json({ error: outcome.error }, outcome.status);
+}
+
+/** Close or reopen one criterion — the same rule `complete-isc` reaches. */
+async function iscWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const { project, id, status } = body;
+  if (typeof project !== "string" || !project) {
+    return json({ error: "project is required" }, 400);
+  }
+  if (typeof id !== "number" || !Number.isInteger(id) || id < 1) {
+    return json({ error: "id must be a positive integer" }, 400);
+  }
+  if (status !== "open" && status !== "done") {
+    return json({ error: "status must be open or done" }, 400);
+  }
+  return answer(setIscStatus(project, id, status === "done"), { project, id, status });
+}
+
+async function placementWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const { project, quadrant } = body;
+  if (typeof project !== "string" || !project) {
+    return json({ error: "project is required" }, 400);
+  }
+  if (quadrant !== null && !isQuadrant(quadrant)) {
+    return json(
+      { error: `quadrant must be null or one of ${QUADRANTS.join(", ")}` },
+      400
+    );
+  }
+  return answer(setPlacement(project, quadrant), { project, quadrant });
+}
+
+async function settingsWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const update: Partial<InstallSettings> = {};
+  for (const key of ["actor", "timezone"] as const) {
+    const value = body[key];
+    if (value === undefined) continue;
+    if (typeof value !== "string") return json({ error: `${key} must be a string` }, 400);
+    update[key] = value;
+  }
+  const outcome = writeInstallSettings(update);
+  return outcome.ok ? json(readInstallSettings()) : answer(outcome, {});
+}
+
+async function snoozeWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const { project, id, days } = body;
+  if (typeof project !== "string" || !project) {
+    return json({ error: "project is required" }, 400);
+  }
+  if (typeof id !== "number" || !Number.isInteger(id) || id < 1) {
+    return json({ error: "id must be a positive integer" }, 400);
+  }
+  if (
+    typeof days !== "number" ||
+    !Number.isInteger(days) ||
+    days < 0 ||
+    days > MAX_SNOOZE_DAYS
+  ) {
+    return json({ error: `days must be a whole number of 0..${MAX_SNOOZE_DAYS}` }, 400);
+  }
+  return json({ project, id, until: setSnooze(project, id, days) });
+}
+
+async function readWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const ids = body.all === true ? attention().items.map((i) => i.id) : body.ids;
+  if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string")) {
+    return json({ error: "ids must be an array of strings, or all must be true" }, 400);
+  }
+  return json({ marked: markRead(ids as string[]) });
+}
+
+async function prefsWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const failure = validatePrefs(body as PrefUpdate);
+  return failure ? json({ error: failure }, 400) : json(writePrefs(body as PrefUpdate));
+}
+
+const WRITES: Record<string, (request: Request) => Promise<Response>> = {
+  "/api/serves": overrideServes,
+  "/api/isc": iscWrite,
+  "/api/placement": placementWrite,
+  "/api/settings": settingsWrite,
+  "/api/snooze": snoozeWrite,
+  "/api/attention/read": readWrite,
+  "/api/prefs": prefsWrite,
+};
+
 export function startControlRoom(port: number = DEFAULT_PORT) {
   const startedAt = new Date().toISOString();
   return Bun.serve({
     hostname: LOOPBACK,
     port,
     development: false,
-    routes: { "/": index },
+    routes: Object.fromEntries(PAGE_ROUTES.map((path) => [path, () => indexHtml()])),
     fetch(request, server) {
       const url = new URL(request.url);
-      if (request.method === "POST" && url.pathname === "/api/serves") {
-        return overrideServes(request);
-      }
+      const write = WRITES[url.pathname];
+      if (request.method === "POST" && write) return write(request);
       if (request.method !== "GET") return json({ error: "read only" }, 405);
+      if (!url.pathname.startsWith("/api/")) {
+        return staticAsset(url.pathname) ?? json({ error: "not found" }, 404);
+      }
       switch (url.pathname) {
         case "/api/agenda":
           return json(agenda());
@@ -127,8 +302,18 @@ export function startControlRoom(port: number = DEFAULT_PORT) {
           return withFilter(url, agentsAtWork);
         case "/api/ledger":
           return withFilter(url, ledgerView);
+        case "/api/project":
+          return oneProject(url.searchParams.get("slug"));
+        case "/api/summary":
+          return summaryFor(url.searchParams.get("days"));
         case "/api/projects":
           return projects();
+        case "/api/settings":
+          return json(readInstallSettings());
+        case "/api/prefs":
+          return json(readPrefs());
+        case "/api/attention":
+          return json(attention());
         case "/api/status":
           return status(server.port ?? port, startedAt);
         default:

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

@@ -0,0 +1,65 @@
+/**
+ * Snoozed criteria — an ISC you have seen and do not want ranked this week.
+ *
+ * Kept out of the ISA on purpose: the record says what the project is judged
+ * against, and "not this week" is a fact about your attention rather than about
+ * the project. It expires by date, so nothing has to unsnooze it.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "../../hooks/lib/paths";
+
+const DAY_MS = 86_400_000;
+export const MAX_SNOOZE_DAYS = 90;
+
+/** project#isc → the day it wakes up. */
+export type Snoozes = Record<string, string>;
+
+function snoozeKey(project: string, id: number): string {
+  return `${project}#${id}`;
+}
+
+function snoozeFile(): string {
+  return resolve(ensureDir(paths.state()), "snoozed.json");
+}
+
+export function readSnoozes(now: Date = new Date()): Snoozes {
+  const file = snoozeFile();
+  if (!existsSync(file)) return {};
+  let stored: Snoozes;
+  try {
+    stored = JSON.parse(readFileSync(file, "utf-8")) as Snoozes;
+  } catch {
+    return {};
+  }
+  const today = now.toISOString().slice(0, 10);
+  return Object.fromEntries(
+    Object.entries(stored).filter(
+      ([, until]) => typeof until === "string" && until > today
+    )
+  );
+}
+
+export function snoozedUntil(
+  project: string,
+  id: number,
+  snoozes: Snoozes
+): string | null {
+  return snoozes[snoozeKey(project, id)] ?? null;
+}
+
+/** Zero days wakes it now, which is how the page un-snoozes. */
+export function setSnooze(
+  project: string,
+  id: number,
+  days: number,
+  now: Date = new Date()
+): string | null {
+  const live = readSnoozes(now);
+  const key = snoozeKey(project, id);
+  if (days <= 0) delete live[key];
+  else live[key] = new Date(now.getTime() + days * DAY_MS).toISOString().slice(0, 10);
+  writeFileSync(snoozeFile(), `${JSON.stringify(live, null, 2)}\n`, "utf-8");
+  return live[key] ?? null;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * The built page, off disk. Vite compiles src/tools/control-room/ui into
+ * ui/dist; this serves it, and says so plainly when the build has not been run
+ * rather than answering a blank page.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+const UI_DIST = resolve(import.meta.dir, "ui", "dist");
+
+export const BUILD_COMMAND = "bun run build:ui";
+
+export function isBuilt(): boolean {
+  return existsSync(resolve(UI_DIST, "index.html"));
+}
+
+/**
+ * A clone has vite; a published install has the prepacked dist and never needs
+ * it. Either way the page is there by the time the server answers.
+ */
+export function buildPage(): boolean {
+  const repoRoot = resolve(import.meta.dir, "..", "..", "..");
+  // node_modules/.bin/vite is a shell shim that Windows cannot spawn directly;
+  // the package's own JS entry runs the same build under any runtime.
+  const vite = resolve(repoRoot, "node_modules", "vite", "bin", "vite.js");
+  if (!existsSync(vite)) return false;
+  const built = spawnSync(process.execPath, [vite, "build"], {
+    cwd: resolve(import.meta.dir, "ui"),
+    encoding: "utf-8",
+  });
+  return built.status === 0 && isBuilt();
+}
+
+function unbuiltPage(): Response {
+  return new Response(
+    `<!doctype html><meta charset="utf-8"><title>PAL control room</title>` +
+      `<body style="font:14px system-ui;padding:3rem;max-width:34rem">` +
+      `<h1>The page has not been built</h1>` +
+      `<p>The control room's assets are a build artifact rather than source. Run:</p>` +
+      `<pre style="background:#eee;padding:1rem">${BUILD_COMMAND}</pre></body>`,
+    { status: 503, headers: { "content-type": "text/html; charset=utf-8" } }
+  );
+}
+
+export function indexHtml(): Response {
+  if (!isBuilt()) return unbuiltPage();
+  return new Response(Bun.file(resolve(UI_DIST, "index.html")), {
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}
+
+/**
+ * Only what the build emitted, resolved inside dist — a request that climbs out
+ * of it with `..` is a miss, not a file read.
+ */
+export function staticAsset(pathname: string): Response | null {
+  const target = resolve(UI_DIST, `.${pathname}`);
+  if (!isInsideDist(target)) return null;
+  return existsSync(target) ? new Response(Bun.file(target)) : null;
+}
+
+/** Compared as paths, not strings — a separator differs by platform. */
+function isInsideDist(target: string): boolean {
+  const rel = relative(UI_DIST, target);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}

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

@@ -1,67 +1,213 @@
-import { StrictMode, useEffect, useState } from "react";
+import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+import {
+  BrowserRouter,
+  Navigate,
+  NavLink,
+  Route,
+  Routes,
+  useParams,
+  useSearchParams,
+} from "react-router";
 import type { ServerStatus } from "../server";
-import { Agenda } from "./agenda";
-import { Agents } from "./agents";
-import { Board } from "./board";
-import { Handoffs } from "./handoffs";
-import { Ledger } from "./ledger";
-import { MatrixGrid } from "./matrix";
-import { getJson } from "./panel";
-import { Signal } from "./signal";
+import { AttentionBell } from "./attention-bell";
+import { Screen, Scroller, Seg } from "./frame";
+import { useLoaded } from "./lib/api";
+import { cn } from "./lib/cn";
+import { LOG_KEYS, Log, type LogFilter } from "./screens/log";
+import { ProjectDetail } from "./screens/project-detail";
+import {
+  isStatusFilter,
+  Projects,
+  STATUS_FILTERS,
+  type StatusFilter,
+} from "./screens/projects";
+import { Settings } from "./screens/settings";
+import { isLayout, LAYOUTS, type Layout, Today } from "./screens/today";
 
-function Masthead({ status }: { status: ServerStatus | null }) {
+const LAYOUT_KEY = "pal.control-room.layout";
+
+/**
+ * A blueprint's registration marks are drawn 6px outside its border, so a scroll
+ * box whose children are blueprints would count them as overflow. The negative
+ * margin borrows that room back from the page gutter, leaving content aligned.
+ */
+const MARK_ROOM = "-m-2 p-2";
+
+function rememberedLayout(): Layout {
+  try {
+    const stored = localStorage.getItem(LAYOUT_KEY);
+    return isLayout(stored) ? stored : "matrix";
+  } catch {
+    return "matrix";
+  }
+}
+
+function remember(layout: Layout): void {
+  try {
+    localStorage.setItem(LAYOUT_KEY, layout);
+  } catch {}
+}
+
+function TodayRoute() {
+  const [params, setParams] = useSearchParams();
+  const asked = params.get("layout");
+  const layout = isLayout(asked) ? asked : rememberedLayout();
   return (
-    <div className="masthead">
-      <h1>
-        PAL <em>this morning</em>
-      </h1>
-      <div className="meta">
-        <span>
-          machine <b>{status?.machine ?? "…"}</b>
-        </span>
-        <span>
-          ledger <b>{status ? `${status.ledgerFiles} file(s)` : "…"}</b>
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="mb-4 flex justify-end">
+        <Seg
+          label="layout"
+          options={LAYOUTS}
+          value={layout}
+          onPick={(next) => {
+            remember(next);
+            setParams({ layout: next });
+          }}
+        />
+      </div>
+      <Scroller className={MARK_ROOM}>
+        <Today layout={layout} />
+      </Scroller>
+    </div>
+  );
+}
+
+function ProjectsRoute() {
+  const [params, setParams] = useSearchParams();
+  const asked = params.get("status");
+  const filter: StatusFilter = isStatusFilter(asked) ? asked : "ranked";
+  return (
+    <Screen
+      title="Projects"
+      aside={
+        <Seg
+          label="status"
+          options={STATUS_FILTERS}
+          value={filter}
+          onPick={(next) => setParams({ status: next })}
+        />
+      }
+    >
+      <Projects filter={filter} />
+    </Screen>
+  );
+}
+
+function ProjectDetailRoute() {
+  const { slug } = useParams();
+  return (
+    <Scroller className={MARK_ROOM}>
+      <ProjectDetail slug={slug ?? ""} />
+    </Scroller>
+  );
+}
+
+function LogRoute() {
+  const [params, setParams] = useSearchParams();
+  const filter = Object.fromEntries(
+    LOG_KEYS.map((key) => [key, params.get(key) ?? ""])
+  ) as LogFilter;
+  const update = (next: Partial<LogFilter>) => {
+    const merged = { ...filter, ...next };
+    setParams(Object.fromEntries(Object.entries(merged).filter(([, v]) => v)));
+  };
+  return (
+    <Screen
+      title="Action log"
+      aside={
+        <span className="text-[12px] text-neutral-700">
+          every tool call this install recorded
         </span>
+      }
+    >
+      <Log filter={filter} onFilter={update} />
+    </Screen>
+  );
+}
+
+function SettingsRoute() {
+  return (
+    <Screen title="Settings">
+      <Scroller className={MARK_ROOM}>
+        <Settings />
+      </Scroller>
+    </Screen>
+  );
+}
+
+const TABS = [
+  { to: "/", label: "Today", end: true },
+  { to: "/projects", label: "Projects", end: false },
+  { to: "/log", label: "Action log", end: false },
+  { to: "/settings", label: "Settings", end: false },
+] as const;
+
+function Header({ status }: { status: ServerStatus | null }) {
+  return (
+    <header className="flex flex-wrap items-center gap-5 border-b border-divider bg-bg px-7 py-2.5">
+      <div className="flex min-w-[120px] items-baseline gap-2">
+        <span className="font-heading text-[22px] font-semibold tracking-wide">PAL</span>
+        <span className="eyebrow">control</span>
+      </div>
+      <nav className="-mb-[11px] flex gap-0.5">
+        {TABS.map((tab) => (
+          <NavLink
+            key={tab.to}
+            to={tab.to}
+            end={tab.end}
+            className={({ isActive }) =>
+              cn(
+                "font-heading border-b-2 px-3 py-2 text-[15px] font-semibold whitespace-nowrap",
+                isActive
+                  ? "border-accent text-ink"
+                  : "border-transparent text-neutral-600 hover:text-accent"
+              )
+            }
+          >
+            {tab.label}
+          </NavLink>
+        ))}
+      </nav>
+      <div className="ml-auto flex items-center gap-3 text-[12px] text-neutral-700">
+        <span className="inline-block size-1.5 bg-accent" />
+        <b className="font-medium text-ink">{status?.machine ?? "…"}</b>
         <span>
-          port <b>{status?.port ?? "…"}</b>
+          · {status ? `${status.ledgerFiles} ledger file(s)` : "…"} · port{" "}
+          {status?.port ?? "…"}
         </span>
+        <AttentionBell />
       </div>
-    </div>
+    </header>
   );
 }
 
 function App() {
-  const [status, setStatus] = useState<ServerStatus | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  useEffect(() => {
-    getJson<ServerStatus>("/api/status")
-      .then(setStatus)
-      .catch((e: Error) => setError(e.message));
-  }, []);
+  const status = useLoaded<ServerStatus>("/api/status");
   return (
-    <div className="room">
-      <Masthead status={status} />
-      {error && <div className="error">{error}</div>}
-      <Agenda />
-      <MatrixGrid />
-      <div className="grid">
-        <Handoffs />
+    <BrowserRouter>
+      <div className="flex h-screen flex-col overflow-hidden">
+        <Header status={status.state === "ready" ? status.data : null} />
+        <main className="mx-auto flex w-full max-w-[1480px] min-h-0 flex-1 flex-col px-7 pt-6 pb-6">
+          <Routes>
+            <Route path="/" element={<TodayRoute />} />
+            <Route path="/projects" element={<ProjectsRoute />} />
+            <Route path="/projects/:slug" element={<ProjectDetailRoute />} />
+            <Route path="/log" element={<LogRoute />} />
+            <Route path="/settings" element={<SettingsRoute />} />
+            <Route path="*" element={<Navigate to="/" replace />} />
+          </Routes>
+        </main>
+        <footer className="flex flex-wrap justify-between gap-4 border-t border-divider px-7 py-3 text-[11px] text-neutral-600">
+          <span>
+            loopback only · every number from ~/.pal · no model runs on this page
+          </span>
+          <span>
+            {status.state === "ready" ? `up since ${status.data.startedAt}` : ""}
+          </span>
+        </footer>
       </div>
-      <details className="drawer">
-        <summary>When something breaks — projects, agents, signal, ledger</summary>
-        <div className="grid">
-          <Board />
-          <Signal />
-          <Agents />
-          <Ledger />
-        </div>
-      </details>
-      <div className="foot">
-        <span>loopback only · every number from ~/.pal · no model runs on this page</span>
-        <span>{status ? `up since ${status.startedAt}` : ""}</span>
-      </div>
-    </div>
+    </BrowserRouter>
   );
 }