portable-agent-layer 0.72.0 → 0.73.0

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

@@ -0,0 +1,96 @@
+/**
+ * The knobs behind the grid and the bell.
+ *
+ * These were constants in the source, which meant "gone quiet after 14 days"
+ * was PAL's opinion rather than the user's. They live in pal-settings.json now,
+ * with the old constants as the defaults so nothing changes until someone says
+ * otherwise.
+ */
+
+import { PROJECT_STALE_DAYS_DEFAULT } from "../../hooks/lib/projects";
+import {
+  raw as rawSettings,
+  reload,
+  write as writeSettings,
+} from "../../hooks/lib/settings";
+
+const ATTENTION_SOURCES = ["refusals", "waiting", "unranked"] as const;
+export type AttentionSource = (typeof ATTENTION_SOURCES)[number];
+
+export interface ControlRoomPrefs {
+  quietAfterDays: number;
+  urgentWithinDays: number;
+  rankGoals: boolean;
+  attention: Record<AttentionSource, boolean>;
+}
+
+const PREF_DEFAULTS: ControlRoomPrefs = {
+  quietAfterDays: PROJECT_STALE_DAYS_DEFAULT,
+  urgentWithinDays: 14,
+  rankGoals: true,
+  attention: { refusals: true, waiting: true, unranked: true },
+};
+
+const DAY_LIMIT = 365;
+
+function storedPrefs(): Partial<ControlRoomPrefs> {
+  const stored = rawSettings().controlRoom;
+  return (stored ?? {}) as Partial<ControlRoomPrefs>;
+}
+
+function positiveDays(value: unknown, fallback: number): number {
+  return typeof value === "number" &&
+    Number.isInteger(value) &&
+    value > 0 &&
+    value <= DAY_LIMIT
+    ? value
+    : fallback;
+}
+
+export function readPrefs(): ControlRoomPrefs {
+  const stored = storedPrefs();
+  return {
+    quietAfterDays: positiveDays(stored.quietAfterDays, PREF_DEFAULTS.quietAfterDays),
+    urgentWithinDays: positiveDays(
+      stored.urgentWithinDays,
+      PREF_DEFAULTS.urgentWithinDays
+    ),
+    rankGoals: stored.rankGoals ?? PREF_DEFAULTS.rankGoals,
+    attention: { ...PREF_DEFAULTS.attention, ...(stored.attention ?? {}) },
+  };
+}
+
+export type PrefUpdate = Partial<ControlRoomPrefs>;
+
+export function validatePrefs(update: PrefUpdate): string | null {
+  for (const key of ["quietAfterDays", "urgentWithinDays"] as const) {
+    const value = update[key];
+    if (value === undefined) continue;
+    if (positiveDays(value, -1) === -1) {
+      return `${key} must be a whole number of days, 1..${DAY_LIMIT}`;
+    }
+  }
+  if (update.rankGoals !== undefined && typeof update.rankGoals !== "boolean") {
+    return "rankGoals must be true or false";
+  }
+  for (const [key, value] of Object.entries(update.attention ?? {})) {
+    if (!(ATTENTION_SOURCES as readonly string[]).includes(key)) {
+      return `unknown attention source: ${key}`;
+    }
+    if (typeof value !== "boolean") return `attention.${key} must be true or false`;
+  }
+  return null;
+}
+
+export function writePrefs(update: PrefUpdate): ControlRoomPrefs {
+  const data = rawSettings();
+  const current = readPrefs();
+  const next: ControlRoomPrefs = {
+    ...current,
+    ...update,
+    attention: { ...current.attention, ...(update.attention ?? {}) },
+  };
+  writeSettings({ ...data, controlRoom: { ...next } });
+  reload();
+  return next;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Where the control room listens. Split from server.ts so the build can read it
+ * without importing the server itself — server.ts imports the page bundle, and
+ * a bundler asked to load that would be chasing its own output.
+ */
+
+export const DEFAULT_PORT = 7250;
+export const LOOPBACK = "127.0.0.1";

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