portable-agent-layer 0.69.0 → 0.71.0

package/src/hooks/handlers/agenda.ts

@@ -0,0 +1,223 @@
+/**
+ * Stop handler: what to do tomorrow morning.
+ *
+ * Two jobs, both too slow and too expensive for a page load, so both happen
+ * here and land in files the morning screen only reads.
+ *
+ * 1. Guess what each project serves, once, so importance can be ranked at all.
+ *    A guess never overwrites the user's own answer.
+ * 2. Write three moves for the day — sentences, not project names, because the
+ *    answer to "what now" is rarely "open a repository".
+ */
+
+import { matrix } from "../../tools/control-room/matrix";
+import { type AgendaMove, readAgenda, writeAgenda } from "../lib/agenda-store";
+import { canInfer, inference } from "../lib/inference";
+import { logDebug, logError } from "../lib/log";
+import { readAllProjects } from "../lib/projects";
+import { isServesKind, SERVES_KINDS, setServes } from "../lib/serves";
+import { readTelosGoals } from "../lib/telos-goals";
+import { logTokenUsage } from "../lib/token-usage";
+
+const FRESH_HOURS = 6;
+const MAX_PROJECTS_PER_GUESS = 40;
+
+function hoursSince(iso: string, now: Date): number {
+  const at = new Date(iso).getTime();
+  if (!Number.isFinite(at)) return Number.POSITIVE_INFINITY;
+  return (now.getTime() - at) / 3_600_000;
+}
+
+const SERVES_SCHEMA = {
+  type: "object" as const,
+  additionalProperties: false,
+  properties: {
+    projects: {
+      type: "array" as const,
+      description: "One entry per project you were given, no others",
+      items: {
+        type: "object" as const,
+        additionalProperties: false,
+        properties: {
+          name: { type: "string" as const },
+          serves: { type: "string" as const, enum: SERVES_KINDS },
+          note: {
+            type: "string" as const,
+            description: "Six words at most on what it serves",
+          },
+        },
+        required: ["name", "serves", "note"] as const,
+      },
+    },
+  },
+  required: ["projects"] as const,
+};
+
+const MOVES_SCHEMA = {
+  type: "object" as const,
+  additionalProperties: false,
+  properties: {
+    moves: {
+      type: "array" as const,
+      description: "Exactly three, most consequential first",
+      items: {
+        type: "object" as const,
+        additionalProperties: false,
+        properties: {
+          move: {
+            type: "string" as const,
+            description: "One sentence, an action the user can start today",
+          },
+          because: {
+            type: "string" as const,
+            description: "One short clause naming the evidence it came from",
+          },
+        },
+        required: ["move", "because"] as const,
+      },
+    },
+  },
+  required: ["moves"] as const,
+};
+
+function goalsBrief(): string {
+  const goals = readTelosGoals();
+  if (goals.length === 0) return "The user has not written any goals down yet.";
+  return goals
+    .map((g) => {
+      const by = g.due ? ` [by ${g.due}]` : "";
+      return `- ${g.text}${by}`;
+    })
+    .join("\n");
+}
+
+/** A model's JSON is untrusted input like any other payload. */
+function parsePayload<T>(raw: string, caller: string): T | null {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    logError(caller, err);
+    return null;
+  }
+}
+
+/** Only projects with no purpose on record — a guess is made once, not nightly. */
+async function guessMissingServes(sessionId?: string): Promise<number> {
+  const missing = readAllProjects()
+    .filter((p) => !p.serves && (p.status === "active" || p.status === "paused"))
+    .slice(0, MAX_PROJECTS_PER_GUESS);
+  if (missing.length === 0) return 0;
+
+  const described = missing
+    .map((p) => {
+      const purpose = (p.goal ?? p.problem ?? "").replace(/\s+/g, " ").slice(0, 200);
+      return `- ${p.name}: ${purpose || "no description on record"}`;
+    })
+    .join("\n");
+
+  const result = await inference({
+    system: [
+      "You are told a person's goals and a list of their projects.",
+      "For each project, decide which of three things it serves:",
+      '"goal" — it moves one of the stated goals forward;',
+      '"revenue" — it is a way the work could pay, even speculatively;',
+      '"fun" — it is kept for its own sake.',
+      "Judge from the goals and the project description only. Never assume a project is unimportant because it is small or quiet.",
+      "Return one entry per project you were given.",
+    ].join("\n"),
+    user: `Their goals:\n${goalsBrief()}\n\nTheir projects:\n${described}`,
+    maxTokens: 700,
+    timeout: 90000,
+    jsonSchema: SERVES_SCHEMA,
+    caller: "agenda-serves",
+    sessionId,
+  });
+  if (result.usage) logTokenUsage("agenda-serves", result.usage);
+  if (!result.success || !result.output) return 0;
+
+  const parsed = parsePayload<{
+    projects: { name: string; serves: string; note: string }[];
+  }>(result.output, "agenda:serves");
+  if (!parsed?.projects) return 0;
+
+  const known = new Set(missing.map((p) => p.name));
+  let written = 0;
+  for (const guess of parsed.projects) {
+    if (!known.has(guess.name) || !isServesKind(guess.serves)) continue;
+    const outcome = setServes({
+      name: guess.name,
+      kind: guess.serves,
+      note: guess.note,
+      by: "inferred",
+    });
+    if (outcome === "written") written++;
+  }
+  return written;
+}
+
+function matrixBrief(): string {
+  const grid = matrix();
+  const lines = [...grid.now, ...grid.plan, ...grid.noise].map((item) => {
+    const why = item.urgentBecause.join(", ") || "nothing pressing";
+    const waiting = item.waitingOn ? ` — waiting on the user for: ${item.waitingOn}` : "";
+    return `- [${item.kind}] ${item.label}: ${item.importantBecause}; ${why}${waiting}`;
+  });
+  return lines.length > 0 ? lines.join("\n") : "Nothing is ranked yet.";
+}
+
+async function writeMoves(sessionId?: string): Promise<boolean> {
+  const result = await inference({
+    system: [
+      "You write the first three lines a person reads in the morning.",
+      "You are given their goals and a ranked list of their projects and goals with the reason each was ranked.",
+      "Write exactly three moves, most consequential first.",
+      "A move is a sentence naming an action, not a project name: 'Send ACE the mapping one-pager' beats 'work on ontology'.",
+      "Prefer what is blocked on the person themselves, then what serves a goal, then what is merely urgent.",
+      "Never invent a fact that is not in what you were given.",
+    ].join("\n"),
+    user: `Their goals:\n${goalsBrief()}\n\nWhat is ranked and why:\n${matrixBrief()}`,
+    maxTokens: 400,
+    timeout: 90000,
+    jsonSchema: MOVES_SCHEMA,
+    caller: "agenda-moves",
+    sessionId,
+  });
+  if (result.usage) logTokenUsage("agenda-moves", result.usage);
+  if (!result.success || !result.output) return false;
+
+  const parsed = parsePayload<{ moves: AgendaMove[] }>(result.output, "agenda:moves");
+  const moves = (parsed?.moves ?? []).filter((m) => m.move).slice(0, 3);
+  if (moves.length === 0) return false;
+
+  await writeAgenda({ generatedAt: new Date().toISOString(), moves });
+  return true;
+}
+
+/** Named so the caller — and a test — can tell a skip from a failure. */
+export type AgendaOutcome = "fresh" | "no-inference" | "written" | "failed";
+
+/** @lintignore exercised directly by test/agenda-handler.test.ts */
+export async function refreshAgenda(
+  now: Date = new Date(),
+  sessionId?: string
+): Promise<AgendaOutcome> {
+  const existing = readAgenda();
+  if (existing && hoursSince(existing.generatedAt, now) < FRESH_HOURS) return "fresh";
+  if (!canInfer()) return "no-inference";
+
+  const guessed = await guessMissingServes(sessionId);
+  const wrote = await writeMoves(sessionId);
+  logDebug("agenda", `serves guessed: ${guessed}, moves written: ${wrote}`);
+  return wrote ? "written" : "failed";
+}
+
+if (process.argv[2] === "--run") {
+  const sid = process.argv[3];
+  try {
+    const outcome = await refreshAgenda(new Date(), sid === "" ? undefined : sid);
+    logDebug("agenda", outcome);
+  } catch (err) {
+    logError("agenda:run", err);
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/inject-retrieval.ts

@@ -14,6 +14,7 @@ import { ensureIndex } from "../lib/retrieval-index";
 import { isEnabled } from "../lib/settings";
 import { getSkillReminder } from "../lib/skill-match";
 import { getSteeringReminder } from "../lib/steering";
+import { getWallClockReminder } from "../lib/wall-clock";
 
 const BUDGET_MS = 250;
 
@@ -79,11 +80,14 @@ function writeForAgent(reminder: string): void {
   }
 }
 
-/** Merge every prompt-time source — contextual steering, skill matches, prior-lesson
- *  retrieval — into one payload, or null when none of them produced anything.
+/** Merge every prompt-time source — the wall clock, contextual steering, skill
+ *  matches, prior-lesson retrieval — into one payload, or null when none of them
+ *  produced anything. The clock leads: it is the only part that is true of the
+ *  moment rather than of the prompt.
  *  @lintignore dynamically imported by opencode plugin */
 export async function getPromptContext(prompt: string): Promise<string | null> {
   const parts = [
+    getWallClockReminder(),
     getSteeringReminder(prompt),
     getSkillReminder(prompt),
     await getRetrievalReminder(prompt),

package/src/hooks/lib/agenda-store.ts

@@ -0,0 +1,41 @@
+/**
+ * Where the morning's three moves live between sessions.
+ *
+ * A file, not a computation: the page reads it, the stop handler writes it, and
+ * neither has to know how the other works.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+export interface AgendaMove {
+  move: string;
+  because: string;
+}
+
+export interface Agenda {
+  generatedAt: string;
+  moves: AgendaMove[];
+}
+
+/** @lintignore exercised directly by test/agenda-store.test.ts */
+export function agendaPath(): string {
+  return resolve(paths.state(), "agenda.json");
+}
+
+export function readAgenda(): Agenda | null {
+  const path = agendaPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Agenda;
+    return Array.isArray(parsed.moves) && parsed.generatedAt ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeAgenda(agenda: Agenda): Promise<void> {
+  await writeFile(agendaPath(), `${JSON.stringify(agenda, null, 2)}\n`, "utf-8");
+}

package/src/hooks/lib/paths.ts

@@ -62,6 +62,7 @@ export const paths = {
   work: () => ensureDir(home("memory", "work")),
   backups: () => ensureDir(home("backups")),
   debug: () => ensureDir(home("debug")),
+  serverState: () => home("server.json"),
 } as const;
 
 // Platform directories (env override or cross-platform defaults)

package/src/hooks/lib/projects.ts

@@ -24,6 +24,11 @@ import { detectRemote } from "./remote";
 
 export type ProjectStatus = "active" | "paused" | "complete" | "archived";
 
+/** What a project is for. The three answers importance can be ranked from. */
+export type ServesKind = "goal" | "revenue" | "fun";
+/** Who decided it. A user answer outranks a guess and survives re-inference. */
+export type ServesAuthority = "inferred" | "user";
+
 export interface ProjectProgress {
   name: string;
   /** Resolved for this machine at read time; absent when not checked out here. */
@@ -36,6 +41,10 @@ export interface ProjectProgress {
   next?: string[];
   blockers?: string[];
   handoff?: string;
+  /** What this project is for — the fact importance is ranked from. */
+  serves?: ServesKind;
+  serves_note?: string;
+  serves_by?: ServesAuthority;
   // ISA body sections
   problem?: string;
   goal?: string;
@@ -100,7 +109,7 @@ export function legacyJsonToProgress(raw: unknown): ProjectProgress | null {
   return p;
 }
 
-const PROJECT_STALE_DAYS_DEFAULT = 14;
+export const PROJECT_STALE_DAYS_DEFAULT = 14;
 
 const PROJECT_MARKERS = [
   ".git",
@@ -123,6 +132,9 @@ type IsaMeta = {
   next?: string[];
   blockers?: string[];
   handoff?: string;
+  serves?: ServesKind;
+  serves_note?: string;
+  serves_by?: ServesAuthority;
 };
 
 const BODY_SECTIONS: Array<[string, keyof ProjectProgress]> = [
@@ -269,6 +281,9 @@ export function writeProject(p: ProjectProgress): void {
   if (p.next?.length) meta.next = p.next;
   if (p.blockers?.length) meta.blockers = p.blockers;
   if (p.handoff) meta.handoff = p.handoff;
+  if (p.serves) meta.serves = p.serves;
+  if (p.serves_note) meta.serves_note = p.serves_note;
+  if (p.serves_by) meta.serves_by = p.serves_by;
   writeFileSync(ensureAndGetIsaFile(p.name), stringify(meta, buildBody(p)), "utf-8");
 }
 

package/src/hooks/lib/serves.ts

@@ -0,0 +1,60 @@
+/**
+ * What a project is for, and what that makes it worth.
+ *
+ * Importance cannot be read off a repository: two projects with identical
+ * activity can be a client's livelihood and a weekend toy. So the record carries
+ * one fact PAL guesses and the user can overrule — never a name or a rank
+ * written into source, because next month the same code serves something else.
+ */
+
+import {
+  readProject,
+  type ServesAuthority,
+  type ServesKind,
+  writeProject,
+} from "./projects";
+
+export const SERVES_KINDS: ServesKind[] = ["goal", "revenue", "fun"];
+
+export const SERVES_MEANING: Record<ServesKind, string> = {
+  goal: "serves a stated goal",
+  revenue: "a way this could pay",
+  fun: "kept for its own sake",
+};
+
+/** A goal and a revenue bet are worth protecting time for; fun is not. */
+export function isImportant(kind: ServesKind | undefined): boolean {
+  return kind === "goal" || kind === "revenue";
+}
+
+export function isServesKind(value: unknown): value is ServesKind {
+  return typeof value === "string" && SERVES_KINDS.includes(value as ServesKind);
+}
+
+export interface ServesUpdate {
+  name: string;
+  kind: ServesKind;
+  note?: string;
+  by: ServesAuthority;
+}
+
+/**
+ * A guess never overwrites an answer. This is the whole reason the record
+ * stores who decided: re-inference runs freely and the user is only asked once.
+ *
+ * Writing does bump `updated`, like every other write to the record — a hobby
+ * project that becomes the thing people depend on should rank as touched the
+ * moment that is written down, not fourteen days later.
+ */
+export function setServes(update: ServesUpdate): "written" | "kept" | "missing" {
+  const project = readProject(update.name);
+  if (!project) return "missing";
+  if (update.by === "inferred" && project.serves_by === "user") return "kept";
+
+  project.serves = update.kind;
+  project.serves_by = update.by;
+  if (update.note) project.serves_note = update.note;
+  project.updated = new Date().toISOString();
+  writeProject(project);
+  return "written";
+}

package/src/hooks/lib/stop.ts

@@ -50,6 +50,7 @@ export async function runStopHandlers(
   // inference and write results to disk; they don't block this hook.
   await detachSessionIntelligence(transcript, options.sessionId);
   await detachFailurePrinciple(transcript);
+  detachAgenda(options.sessionId);
   // Failure auto-graduation is intentionally NOT wired here: every pattern it
   // ever promoted was a frustration log, not a principle. Wisdom frames are
   // populated by Claude in-conversation (see wisdom.ts header). The handler
@@ -161,6 +162,19 @@ async function writeTranscriptTmp(transcript: string): Promise<string> {
   return file;
 }
 
+/**
+ * The agenda reads files, not the transcript, so it needs no tmp copy — but it
+ * calls a model, so it detaches like the others. It no-ops on a fresh agenda.
+ */
+function detachAgenda(sessionId?: string): void {
+  try {
+    const scriptPath = resolve(assets.hooks(), "handlers", "agenda.ts");
+    spawnDetachedInference(scriptPath, ["--run", sessionId ?? ""], "agenda");
+  } catch (err) {
+    logError("detachAgenda", err);
+  }
+}
+
 /** Spawn a detached child to run session-intelligence on a tmp copy of the transcript. */
 async function detachSessionIntelligence(
   transcript: string,

package/src/hooks/lib/telos-goals.ts

@@ -0,0 +1,144 @@
+/**
+ * The user's stated goals, read as ranked items rather than prose.
+ *
+ * A goal belongs on the morning screen next to the projects — "find clients"
+ * outranks every repository and is not one. Parsing is deliberately deterministic:
+ * the page must render without a model call, so a date is found by reading, not
+ * by asking.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+export interface TelosGoal {
+  id: string;
+  title: string;
+  text: string;
+  /** Horizon heading the entry sat under, when GOALS.md uses them. */
+  horizon: string | null;
+  /** First date the entry names, as an ISO day. */
+  due: string | null;
+}
+
+const MONTHS = [
+  "january",
+  "february",
+  "march",
+  "april",
+  "may",
+  "june",
+  "july",
+  "august",
+  "september",
+  "october",
+  "november",
+  "december",
+];
+
+const ISO_DAY = /\b(\d{4})-(\d{2})-(\d{2})\b/;
+const MONTH_YEAR = new RegExp(String.raw`\b(${MONTHS.join("|")})\s+(\d{4})\b`, "i");
+const QUARTER = /\bQ([1-4])\s*,?\s*(\d{4})\b/i;
+
+function endOfMonth(year: number, monthIndex: number): string {
+  return new Date(Date.UTC(year, monthIndex + 1, 0)).toISOString().slice(0, 10);
+}
+
+/** The last day the entry could still be met, which is what urgency measures against. */
+export function dueFrom(text: string): string | null {
+  const iso = ISO_DAY.exec(text);
+  if (iso) return iso[0];
+
+  const monthYear = MONTH_YEAR.exec(text);
+  if (monthYear) {
+    return endOfMonth(Number(monthYear[2]), MONTHS.indexOf(monthYear[1].toLowerCase()));
+  }
+
+  const quarter = QUARTER.exec(text);
+  if (quarter) return endOfMonth(Number(quarter[2]), Number(quarter[1]) * 3 - 1);
+
+  return null;
+}
+
+function firstSentenceOf(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const match = new RegExp(/^.*?[.!?](?=\s|$)/).exec(flat);
+  return match ? match[0] : flat;
+}
+
+function slug(title: string, index: number): string {
+  const base = title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, "")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 5)
+    .join("-");
+  return base || `goal-${index + 1}`;
+}
+
+function isScaffolding(line: string): boolean {
+  const l = line.trim();
+  return !l || l.startsWith("<!--") || l.startsWith("-->") || /^(-{3,}|_{3,})$/.test(l);
+}
+
+/**
+ * Bullets are entries when a block has them; otherwise the paragraph is the
+ * entry. Both shapes ship — the scaffold offers horizon headings with bullets,
+ * and people write prose anyway.
+ */
+function entriesIn(lines: string[]): string[] {
+  const bullets = lines
+    .filter((l) => /^\s*[-*+]\s+\S/.test(l))
+    .map((l) => l.replace(/^\s*[-*+]\s+/, "").trim());
+  if (bullets.length > 0) return bullets;
+  const paragraph = lines.join(" ").trim();
+  return paragraph ? [paragraph] : [];
+}
+
+function goalsFrom(content: string): TelosGoal[] {
+  const goals: TelosGoal[] = [];
+  let horizon: string | null = null;
+  let block: string[] = [];
+
+  const flush = () => {
+    for (const text of entriesIn(block)) {
+      const title = firstSentenceOf(text);
+      goals.push({
+        id: slug(title, goals.length),
+        title,
+        text: text.replace(/\s+/g, " ").trim(),
+        horizon,
+        due: dueFrom(text),
+      });
+    }
+    block = [];
+  };
+
+  for (const line of content.split("\n")) {
+    if (line.trim().startsWith("#")) {
+      flush();
+      const heading = line.replace(/^#+\s*/, "").trim();
+      horizon = /^goals$/i.test(heading) ? null : heading;
+      continue;
+    }
+    if (isScaffolding(line)) {
+      flush();
+      continue;
+    }
+    block.push(line);
+  }
+  flush();
+
+  return goals;
+}
+
+export function readTelosGoals(home: string = palHome()): TelosGoal[] {
+  const path = resolve(home, "telos", "GOALS.md");
+  if (!existsSync(path)) return [];
+  try {
+    return goalsFrom(readFileSync(path, "utf-8"));
+  } catch {
+    return [];
+  }
+}

package/src/hooks/lib/telos-topics.ts

@@ -0,0 +1,68 @@
+/**
+ * The TELOS topics, and the one rule for whether a topic has been answered.
+ *
+ * Install does not ask these questions any more — the onboarding skill does,
+ * whenever the user is ready to answer them. Both that skill and the doctor
+ * read the answer from here through `pal cli telos`, so the prose in the skill
+ * cannot drift away from the code that decides.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+interface TelosTopic {
+  key: string;
+  file: string;
+  /** Interviewed first, and the only ones the doctor reports on. */
+  priority: boolean;
+}
+
+const TELOS_TOPICS: TelosTopic[] = [
+  { key: "mission", file: "telos/MISSION.md", priority: true },
+  { key: "goals", file: "telos/GOALS.md", priority: true },
+  { key: "challenges", file: "telos/CHALLENGES.md", priority: true },
+  { key: "strategies", file: "telos/STRATEGIES.md", priority: true },
+  { key: "beliefs", file: "telos/BELIEFS.md", priority: true },
+  { key: "models", file: "telos/MODELS.md", priority: false },
+  { key: "narratives", file: "telos/NARRATIVES.md", priority: false },
+  { key: "learned", file: "telos/LEARNED.md", priority: false },
+  { key: "ideas", file: "telos/IDEAS.md", priority: false },
+];
+
+/** A shipped scaffold is headings, comments, rules and empty bullets — nothing said. */
+function isScaffolding(line: string): boolean {
+  const l = line.trim();
+  if (!l) return true;
+  if (l.startsWith("#")) return true;
+  if (l.startsWith("<!--") || l.startsWith("-->")) return true;
+  if (/^(-{3,}|\*{3,}|_{3,})$/.test(l)) return true;
+  return /^[-*+]$/.test(l);
+}
+
+/**
+ * Anything the scaffold did not put there counts, table rows included.
+ * @lintignore exercised directly by test/telos-topics.test.ts
+ */
+export function hasRealContent(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    return readFileSync(filePath, "utf-8")
+      .split("\n")
+      .some((line) => !isScaffolding(line));
+  } catch {
+    return false;
+  }
+}
+
+export interface TopicStatus extends TelosTopic {
+  path: string;
+  answered: boolean;
+}
+
+export function telosStatus(home: string = palHome()): TopicStatus[] {
+  return TELOS_TOPICS.map((topic) => {
+    const path = resolve(home, topic.file);
+    return { ...topic, path, answered: hasRealContent(path) };
+  });
+}

package/src/hooks/lib/token-usage.ts

@@ -14,7 +14,9 @@ type TokenCaller =
   | "session-name"
   | "session-intelligence"
   | "relationship"
-  | "self-model";
+  | "self-model"
+  | "agenda-serves"
+  | "agenda-moves";
 
 interface TokenUsageEntry {
   ts: string;