portable-agent-layer 0.69.0 → 0.71.0

package/src/hooks/lib/wall-clock.ts

@@ -0,0 +1,58 @@
+/**
+ * The one fact that goes stale inside a session: the time.
+ *
+ * The session-start reminder stamps the clock once, so a conversation picked up
+ * the next morning still believes it is yesterday. This line rides along with
+ * every prompt instead, in the principal's own timezone, because "is it morning"
+ * is the question the agent keeps getting wrong.
+ */
+
+import { identity, isEnabled } from "./settings";
+
+const FIELDS = {
+  weekday: "short",
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+} as const;
+
+function fieldsIn(now: Date, timeZone: string): Record<string, string> {
+  const parts = new Intl.DateTimeFormat("en-US", { ...FIELDS, timeZone }).formatToParts(
+    now
+  );
+  return Object.fromEntries(parts.map((p) => [p.type, p.value]));
+}
+
+/** The IANA name Intl settles on, or null when it does not recognise the input. */
+export function canonicalTimeZone(timeZone: string): string | null {
+  try {
+    return new Intl.DateTimeFormat("en-US", { timeZone }).resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+}
+
+export function isValidTimeZone(timeZone: string): boolean {
+  return canonicalTimeZone(timeZone) !== null;
+}
+
+/** A configured timezone is user input, and Intl throws on a bad one. UTC is always true. */
+function zoneOrUtc(timeZone: string): string {
+  return timeZone && isValidTimeZone(timeZone) ? timeZone : "UTC";
+}
+
+/** @lintignore exercised directly by test/wall-clock.test.ts */
+export function wallClockLine(now: Date, configuredZone: string): string {
+  const zone = zoneOrUtc(configuredZone);
+  const f = fieldsIn(now, zone);
+  return `Now: ${f.weekday} ${f.year}-${f.month}-${f.day} ${f.hour}:${f.minute} ${zone}`;
+}
+
+export function getWallClockReminder(now: Date = new Date()): string | null {
+  if (!isEnabled("wallClock")) return null;
+  const line = wallClockLine(now, identity().principal.timezone);
+  return `<system-reminder>${line}</system-reminder>`;
+}

package/src/tools/agent/handoff-note.ts

@@ -16,20 +16,22 @@ import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
 
-interface HandoffEntry {
+export interface HandoffEntry {
   timestamp: string;
   title: string;
   status: "in-progress" | "completed";
   handoff: string;
   artifacts: string[];
   source: "deliberate" | "auto";
+  /** What the work needs from the human before it can move — the one thing an agent cannot unblock. */
+  waitingOn?: string;
 }
 
 function handoffPath(): string {
   return resolve(ensureDir(paths.state()), "last-handoff.json");
 }
 
-function readHandoffs(): Record<string, HandoffEntry> {
+export function readHandoffs(): Record<string, HandoffEntry> {
   const p = handoffPath();
   if (!existsSync(p)) return {};
   try {
@@ -47,23 +49,31 @@ function writeHandoffs(handoffs: Record<string, HandoffEntry>): number {
   return Object.keys(trimmed).length;
 }
 
-function writeHandoffNote(
-  cwd: string,
-  title: string,
-  text: string,
-  done: boolean
-): { file: string; status: HandoffEntry["status"]; kept: number } {
+interface NoteInput {
+  cwd: string;
+  title: string;
+  text: string;
+  done: boolean;
+  waitingOn?: string;
+}
+
+function writeHandoffNote(note: NoteInput): {
+  file: string;
+  status: HandoffEntry["status"];
+  kept: number;
+} {
   const handoffs = readHandoffs();
-  handoffs[cwd] = {
+  handoffs[note.cwd] = {
     timestamp: new Date().toISOString(),
-    title,
-    status: done ? "completed" : "in-progress",
-    handoff: text,
+    title: note.title,
+    status: note.done ? "completed" : "in-progress",
+    handoff: note.text,
     artifacts: [],
     source: "deliberate",
+    ...(note.waitingOn ? { waitingOn: note.waitingOn } : {}),
   };
   const kept = writeHandoffs(handoffs);
-  return { file: handoffPath(), status: handoffs[cwd].status, kept };
+  return { file: handoffPath(), status: handoffs[note.cwd].status, kept };
 }
 
 function run() {
@@ -72,6 +82,7 @@ function run() {
     options: {
       title: { type: "string" },
       text: { type: "string" },
+      waiting: { type: "string" },
       done: { type: "boolean" },
       help: { type: "boolean", short: "h" },
     },
@@ -88,6 +99,7 @@ Usage:
 Arguments:
   --title   Brief title of what was being worked on (5-10 words)
   --text    What remains unfinished — decisions made, next steps, blockers
+  --waiting What this needs from you before it can move (a decision, an answer, access)
   --done    Mark as completed; suppresses "pick up where you left off" injection
 
 Output: writes to memory/state/last-handoff.json keyed by cwd
@@ -96,12 +108,12 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
   }
 
   if (values.done) {
-    const result = writeHandoffNote(
-      process.cwd(),
-      values.title || "session",
-      values.text || "",
-      true
-    );
+    const result = writeHandoffNote({
+      cwd: process.cwd(),
+      title: values.title || "session",
+      text: values.text || "",
+      done: true,
+    });
     emit.receipt(result.file, { status: result.status, entries: result.kept });
     process.exit(0);
   }
@@ -111,7 +123,13 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
     process.exit(1);
   }
 
-  const result = writeHandoffNote(process.cwd(), values.title, values.text, false);
+  const result = writeHandoffNote({
+    cwd: process.cwd(),
+    title: values.title,
+    text: values.text,
+    done: false,
+    waitingOn: values.waiting,
+  });
   emit.receipt(result.file, { status: result.status, entries: result.kept });
 }
 

package/src/tools/agent/project.ts

@@ -7,7 +7,8 @@
  *
  * Usage:
  *   bun ~/.pal/tools/project.ts list
- *   bun ~/.pal/tools/project.ts create [name] [--path PATH] [--objectives "..."]
+ *   bun ~/.pal/tools/project.ts create [name] [--path PATH] [--objectives "..."] [--serves goal|revenue|fun]
+ *   bun ~/.pal/tools/project.ts serves <name> <goal|revenue|fun> [note]
  *   bun ~/.pal/tools/project.ts resume <name>
  *   bun ~/.pal/tools/project.ts complete | archive | pause | unpause <name>
  *   bun ~/.pal/tools/project.ts add-next <name> "text"
@@ -38,6 +39,7 @@ import {
   readProject,
   writeProject,
 } from "../../hooks/lib/projects";
+import { isServesKind, SERVES_KINDS, setServes } from "../../hooks/lib/serves";
 
 function now(): string {
   return new Date().toISOString();
@@ -83,6 +85,8 @@ function cmdCreate(args: string[]): void {
       path: { type: "string" },
       name: { type: "string" },
       objectives: { type: "string" },
+      serves: { type: "string" },
+      "serves-note": { type: "string" },
     },
     allowPositionals: true,
   });
@@ -111,6 +115,10 @@ function cmdCreate(args: string[]): void {
         .join("\n")
     : undefined;
 
+  if (values.serves !== undefined && !isServesKind(values.serves)) {
+    fail(`--serves must be one of: ${SERVES_KINDS.join(", ")}`);
+  }
+
   const project: ProjectProgress = {
     name,
     path,
@@ -118,11 +126,31 @@ function cmdCreate(args: string[]): void {
     created: now(),
     updated: now(),
     ...(goalLines ? { goal: goalLines } : {}),
+    ...(isServesKind(values.serves)
+      ? { serves: values.serves, serves_by: "user" as const }
+      : {}),
+    ...(values["serves-note"] ? { serves_note: values["serves-note"] } : {}),
   };
   writeProject(project);
   ok({ created: true, project });
 }
 
+/** The answer the scaffolder asks for, and the one place importance can be corrected. */
+function cmdServes(args: string[]): void {
+  const [name, kind, ...note] = args;
+  if (!name || !kind) fail("Usage: serves <name> <goal|revenue|fun> [note]");
+  if (!isServesKind(kind)) fail(`serves must be one of: ${SERVES_KINDS.join(", ")}`);
+
+  const outcome = setServes({
+    name,
+    kind,
+    note: note.join(" ").trim() || undefined,
+    by: "user",
+  });
+  if (outcome === "missing") fail(`No project named "${name}".`);
+  ok({ project: name, serves: kind, by: "user" });
+}
+
 // ── resume ────────────────────────────────────────────────────────
 
 // resume returns a lean orientation view: all narrative sections, but the
@@ -386,7 +414,7 @@ function statusFromBox(box: string): IscStatus {
   return "open";
 }
 
-interface Isc {
+export interface Isc {
   id: number;
   text: string;
   status: IscStatus;
@@ -412,7 +440,7 @@ function decodeIscText(stored: string): string {
   return stored.replaceAll(/\\(.)/g, (whole, ch) => ISC_UNESCAPE[ch] ?? whole);
 }
 
-function parseIscs(criteria: string): Isc[] {
+export function parseIscs(criteria: string): Isc[] {
   const out: Isc[] = [];
   for (const line of criteria.split("\n")) {
     const m = new RegExp(/^-\s+\[( |x|~)\]\s+ISC-(\d+):\s+(.+)$/i).exec(line);
@@ -753,7 +781,8 @@ function help(): void {
 
 Commands:
   list                                          show all registered projects
-  create [name] [--path PATH] [--objectives X]  register a project
+  create [name] [--path PATH] [--objectives X] [--serves KIND]  register a project
+  serves <name> <goal|revenue|fun> [note]       say what it is for — outranks PAL's guess
   resume <name>                                 print lean project view (open-ISC titles; full text via show-isc)
   complete <name>                               mark complete
   archive <name>                                mark archived
@@ -796,6 +825,9 @@ function run(): void {
     case "create":
       cmdCreate(rest);
       return;
+    case "serves":
+      cmdServes(rest);
+      return;
     case "resume":
       cmdResume(rest);
       return;

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 { type HandoffEntry, readHandoffs } from "../agent/handoff-note";
+import { parseIscs } from "../agent/project";
+import { anchorSlugOf, type LedgerFilter, queryLedger } from "../ledger/query";
+
+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)
+    ),
+  };
+}