portable-agent-layer 0.110.0 → 0.112.0

package/src/hooks/lib/work-tree-render.ts

@@ -0,0 +1,157 @@
+/**
+ * How the work tree reads as text: the CLI's views, the block a new or
+ * compacted session starts with, and the one line every prompt carries.
+ */
+
+import { activePath, nodesWithStatus, type ScopeTree, type WorkNode } from "./work-tree";
+
+const SESSION_BUDGET = 2_000;
+const RECENT_DECISIONS = 3;
+const LISTED_PARKED = 5;
+const PROMPT_LINE_MAX = 300;
+
+const RECORD_HINT =
+  "Record as you go: pal cli work stopped|decide|attach|follow-up|open|done (pal cli work --help)";
+
+export function suffix(
+  lead: string,
+  value: string | null | undefined,
+  tail = ""
+): string {
+  return value ? `${lead}${value}${tail}` : "";
+}
+
+function clip(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function label(node: WorkNode): string {
+  return `${node.title} [${node.id}]`;
+}
+
+function stoppedClause(node: WorkNode): string {
+  return node.stoppedAt
+    ? ` — stopped at: ${node.stoppedAt}`
+    : " — no stopped-at recorded";
+}
+
+function due(followUp: { due?: string }): string {
+  return followUp.due ? ` (due ${followUp.due.slice(0, 10)})` : "";
+}
+
+export function renderNodeDetail(tree: ScopeTree, node: WorkNode): string {
+  const path = activePath({ ...tree, active: node.id })
+    .map((n) => n.title)
+    .join(" › ");
+  const lines = [
+    `${label(node)} — ${node.status}`,
+    `Path: ${path}`,
+    `Stopped at: ${node.stoppedAt ?? "(not recorded)"}`,
+  ];
+  if (node.waitingOn) lines.push(`Waiting on: ${node.waitingOn}`);
+  if (node.summary) lines.push(`Summary: ${node.summary}`);
+  if (node.links.isc !== undefined) lines.push(`ISC: ${node.links.isc}`);
+  if (node.links.commitment) lines.push(`Commitment: ${node.links.commitment}`);
+  const section = (title: string, rows: string[]) => {
+    if (rows.length) lines.push(`${title}:`, ...rows.map((r) => `  - ${r}`));
+  };
+  section(
+    "Decisions",
+    node.decisions.map(
+      (d) => `${d.ts.slice(0, 10)} ${d.text}${suffix(" (why: ", d.why, ")")}`
+    )
+  );
+  section(
+    "Artifacts",
+    node.artifacts.map((a) => `${a.kind} ${a.ref}${suffix(" — ", a.label)}`)
+  );
+  section(
+    "Follow-ups",
+    node.followUps.map((f) => `${f.text}${due(f)}`)
+  );
+  return lines.join("\n");
+}
+
+function childrenOf(tree: ScopeTree, parent: string | null): WorkNode[] {
+  return [...tree.nodes.values()]
+    .filter(
+      (n) => n.parent === parent || (parent === null && !tree.nodes.has(n.parent ?? ""))
+    )
+    .sort((a, b) => a.opened.localeCompare(b.opened));
+}
+
+const MARK: Record<WorkNode["status"], string> = {
+  active: "▶",
+  parked: "‖",
+  waiting: "?",
+  done: "✓",
+};
+
+export function renderTreeList(tree: ScopeTree, includeDone: boolean): string {
+  const lines: string[] = [];
+  const walk = (node: WorkNode, depth: number) => {
+    if (node.status === "done" && !includeDone) return;
+    const stop = node.status === "done" ? "" : stoppedClause(node);
+    lines.push(`${"  ".repeat(depth)}${MARK[node.status]} ${label(node)}${stop}`);
+    for (const child of childrenOf(tree, node.id)) walk(child, depth + 1);
+  };
+  for (const root of childrenOf(tree, null)) walk(root, 0);
+  return lines.length ? lines.join("\n") : `No work recorded for ${tree.scope} yet.`;
+}
+
+function activeSection(tree: ScopeTree): string[] {
+  const path = activePath(tree);
+  const active = path.at(-1);
+  if (!active) return ["Active: none — enter a parked node or open one."];
+  const lines = [`Active: ${label(active)}${stoppedClause(active)}`];
+  if (path.length > 1) lines.push(`  Inside: ${path.map((n) => n.title).join(" › ")}`);
+  for (const d of active.decisions.slice(-RECENT_DECISIONS))
+    lines.push(`  Decided ${d.ts.slice(0, 10)}: ${d.text}`);
+  return lines;
+}
+
+function listSection(title: string, rows: string[]): string[] {
+  return rows.length ? [title, ...rows.map((r) => `- ${r}`)] : [];
+}
+
+/** What a new or compacted session needs to pick the work back up without digging. */
+export function renderSessionContext(tree: ScopeTree): string {
+  if (tree.nodes.size === 0) return "";
+  const nodes = [...tree.nodes.values()];
+  const open = nodes.filter((n) => n.status !== "done");
+  const lines = [
+    `## Work tree — ${tree.scope}`,
+    ...activeSection(tree),
+    ...listSection(
+      "Waiting on the user:",
+      nodesWithStatus(tree, "waiting").map((n) => `${label(n)}: ${n.waitingOn}`)
+    ),
+    ...listSection(
+      "Parked:",
+      nodesWithStatus(tree, "parked")
+        .slice(0, LISTED_PARKED)
+        .map((n) => `${label(n)}${stoppedClause(n)}`)
+    ),
+    ...listSection(
+      "Follow-ups:",
+      open.flatMap((n) => n.followUps.map((f) => `${f.text}${due(f)} — on ${n.title}`))
+    ),
+    RECORD_HINT,
+  ];
+  return clip(lines.join("\n"), SESSION_BUDGET);
+}
+
+const NEW_TOPIC_HINT =
+  'New topic: if this is separate work, park the active node with its stopped-at (pal cli work park --stopped "…") and open one for this (pal cli work open "…").';
+
+/** The line every prompt carries, so the active node survives anything that drops context. */
+export function renderPromptLine(tree: ScopeTree, newTopic: boolean): string | null {
+  if (tree.nodes.size === 0) return null;
+  const active = tree.active ? tree.nodes.get(tree.active) : undefined;
+  const parked = nodesWithStatus(tree, "parked").length;
+  const head = active
+    ? `Work: ${label(active)}${stoppedClause(active)}`
+    : "Work: no active node";
+  const line = clip(`${head} · ${parked} parked`, PROMPT_LINE_MAX);
+  return newTopic ? `${line}\n${NEW_TOPIC_HINT}` : line;
+}

package/src/hooks/lib/work-tree.ts

@@ -0,0 +1,307 @@
+/**
+ * The work tree: what the user is working on, what is parked and where each
+ * piece of work stopped, kept as an append-only event log so a compaction, a
+ * new session or a detour never loses it. The tree is derived on every read;
+ * nothing but the events is stored.
+ */
+
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+import { readAllProjects, resolveProjectFromCwd } from "./projects";
+
+export type NodeStatus = "active" | "parked" | "waiting" | "done";
+
+export type ArtifactKind =
+  | "commit"
+  | "branch"
+  | "pr"
+  | "artifact"
+  | "file"
+  | "run"
+  | "link";
+
+export const ARTIFACT_KINDS: readonly ArtifactKind[] = [
+  "commit",
+  "branch",
+  "pr",
+  "artifact",
+  "file",
+  "run",
+  "link",
+];
+
+interface NodeLinks {
+  isc?: number;
+  commitment?: string;
+}
+
+interface EventBase {
+  id: string;
+  ts: string;
+  scope: string;
+  node: string;
+}
+
+export type WorkEvent = EventBase &
+  (
+    | { type: "open"; title: string; parent: string | null; links?: NodeLinks }
+    | { type: "enter" }
+    | { type: "park"; stoppedAt?: string }
+    | { type: "wait"; on: string }
+    | { type: "done"; summary?: string }
+    | { type: "stopped"; text: string }
+    | { type: "decide"; text: string; why?: string }
+    | { type: "attach"; kind: ArtifactKind; ref: string; label?: string }
+    | { type: "follow-up"; text: string; due?: string }
+    | { type: "git-cursor"; branch: string; head: string }
+  );
+
+type Payload<T extends WorkEvent["type"]> = Omit<
+  Extract<WorkEvent, { type: T }>,
+  keyof EventBase | "type"
+>;
+
+interface Decision {
+  ts: string;
+  text: string;
+  why?: string;
+}
+
+interface Artifact {
+  ts: string;
+  kind: ArtifactKind;
+  ref: string;
+  label?: string;
+}
+
+interface FollowUp {
+  ts: string;
+  text: string;
+  due?: string;
+}
+
+export interface WorkNode {
+  id: string;
+  title: string;
+  parent: string | null;
+  status: NodeStatus;
+  stoppedAt: string | null;
+  waitingOn: string | null;
+  summary: string | null;
+  decisions: Decision[];
+  artifacts: Artifact[];
+  followUps: FollowUp[];
+  links: NodeLinks;
+  opened: string;
+  updated: string;
+}
+
+interface GitCursor {
+  branch: string;
+  head: string;
+}
+
+export interface ScopeTree {
+  scope: string;
+  active: string | null;
+  nodes: Map<string, WorkNode>;
+  gitCursor: GitCursor | null;
+}
+
+function workTreeFile(): string {
+  return resolve(ensureDir(resolve(paths.memory(), "work-tree")), "events.jsonl");
+}
+
+/** A registered project is its own scope wherever in it the agent stands; anything else is its folder. */
+export function scopeOf(cwd: string): string {
+  return resolveProjectFromCwd(cwd, readAllProjects())?.name ?? resolve(cwd);
+}
+
+export function newNodeId(
+  now: number = Date.now(),
+  random: () => number = Math.random
+): string {
+  return now.toString(36).slice(-5) + random().toString(36).slice(2, 5);
+}
+
+function parseLine(line: string): WorkEvent[] {
+  try {
+    return [JSON.parse(line) as WorkEvent];
+  } catch {
+    return [];
+  }
+}
+
+/** Ordered by time, so the union an import merges in replays the same as one machine's log. */
+export function readEvents(file: string = workTreeFile()): WorkEvent[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .flatMap(parseLine)
+    .sort((a, b) => a.ts.localeCompare(b.ts));
+}
+
+export function appendEvent<T extends WorkEvent["type"]>(
+  scope: string,
+  node: string,
+  type: T,
+  payload: Payload<T>,
+  file: string = workTreeFile(),
+  now: Date = new Date()
+): WorkEvent {
+  const event = {
+    id: newNodeId(now.getTime()),
+    ts: now.toISOString(),
+    scope,
+    node,
+    type,
+    ...payload,
+  } as WorkEvent;
+  appendFileSync(file, `${JSON.stringify(event)}\n`, "utf-8");
+  return event;
+}
+
+function emptyNode(
+  id: string,
+  title: string,
+  parent: string | null,
+  ts: string
+): WorkNode {
+  return {
+    id,
+    title,
+    parent,
+    status: "active",
+    stoppedAt: null,
+    waitingOn: null,
+    summary: null,
+    decisions: [],
+    artifacts: [],
+    followUps: [],
+    links: {},
+    opened: ts,
+    updated: ts,
+  };
+}
+
+function parkActive(tree: ScopeTree): void {
+  const current = tree.active ? tree.nodes.get(tree.active) : undefined;
+  if (current?.status === "active") current.status = "parked";
+  tree.active = null;
+}
+
+function activate(tree: ScopeTree, node: WorkNode): void {
+  if (tree.active !== node.id) parkActive(tree);
+  node.status = "active";
+  node.waitingOn = null;
+  tree.active = node.id;
+}
+
+/** Finishing a detour hands the work back to the nearest unfinished ancestor. */
+function returnToParent(tree: ScopeTree, node: WorkNode): void {
+  let parent = node.parent ? tree.nodes.get(node.parent) : undefined;
+  while (parent && parent.status === "done")
+    parent = parent.parent ? tree.nodes.get(parent.parent) : undefined;
+  if (parent) activate(tree, parent);
+}
+
+function applyToNode(tree: ScopeTree, node: WorkNode, event: WorkEvent): void {
+  switch (event.type) {
+    case "enter":
+      activate(tree, node);
+      break;
+    case "park":
+      if (event.stoppedAt) node.stoppedAt = event.stoppedAt;
+      node.status = "parked";
+      if (tree.active === node.id) tree.active = null;
+      break;
+    case "wait":
+      node.status = "waiting";
+      node.waitingOn = event.on;
+      if (tree.active === node.id) tree.active = null;
+      break;
+    case "done": {
+      const wasActive = tree.active === node.id;
+      node.status = "done";
+      node.summary = event.summary ?? node.summary;
+      if (wasActive) {
+        tree.active = null;
+        returnToParent(tree, node);
+      }
+      break;
+    }
+    case "stopped":
+      node.stoppedAt = event.text;
+      break;
+    case "decide":
+      node.decisions.push({ ts: event.ts, text: event.text, why: event.why });
+      break;
+    case "attach":
+      node.artifacts.push({
+        ts: event.ts,
+        kind: event.kind,
+        ref: event.ref,
+        label: event.label,
+      });
+      break;
+    case "follow-up":
+      node.followUps.push({ ts: event.ts, text: event.text, due: event.due });
+      break;
+  }
+  node.updated = event.ts;
+}
+
+function apply(tree: ScopeTree, event: WorkEvent): void {
+  if (event.type === "git-cursor") {
+    tree.gitCursor = { branch: event.branch, head: event.head };
+    return;
+  }
+  if (event.type === "open") {
+    const node = emptyNode(event.node, event.title, event.parent, event.ts);
+    node.links = event.links ?? {};
+    tree.nodes.set(node.id, node);
+    activate(tree, node);
+    return;
+  }
+  const node = tree.nodes.get(event.node);
+  if (node) applyToNode(tree, node, event);
+}
+
+export function buildTree(scope: string, events: WorkEvent[]): ScopeTree {
+  const tree: ScopeTree = { scope, active: null, nodes: new Map(), gitCursor: null };
+  for (const event of events) if (event.scope === scope) apply(tree, event);
+  return tree;
+}
+
+export function readTree(scope: string, file: string = workTreeFile()): ScopeTree {
+  return buildTree(scope, readEvents(file));
+}
+
+/** From the root down to the active node: the detours the user is inside of. */
+export function activePath(tree: ScopeTree): WorkNode[] {
+  const path: WorkNode[] = [];
+  let node = tree.active ? tree.nodes.get(tree.active) : undefined;
+  while (node) {
+    path.unshift(node);
+    node = node.parent ? tree.nodes.get(node.parent) : undefined;
+  }
+  return path;
+}
+
+function byRecent(a: WorkNode, b: WorkNode): number {
+  return b.updated.localeCompare(a.updated);
+}
+
+export function nodesWithStatus(tree: ScopeTree, status: NodeStatus): WorkNode[] {
+  return [...tree.nodes.values()].filter((n) => n.status === status).sort(byRecent);
+}
+
+/** An id, or any unambiguous prefix of one. */
+export function findNode(tree: ScopeTree, idOrPrefix: string): WorkNode | null {
+  const exact = tree.nodes.get(idOrPrefix);
+  if (exact) return exact;
+  const matches = [...tree.nodes.values()].filter((n) => n.id.startsWith(idOrPrefix));
+  return matches.length === 1 ? matches[0] : null;
+}

package/src/tools/lib/command.ts

@@ -78,7 +78,15 @@ export async function runCommand(
     : runLeaf(command, args, path);
 }
 
+function startsWithFallbackOption(command: Group, args: string[]): boolean {
+  const first = args[0];
+  if (!command.fallback || first === undefined || !first.startsWith("-")) return false;
+  return !HELP_FLAGS.has(first) && !command.aliases?.[first];
+}
+
 async function runGroup(command: Group, args: string[], path: string[]): Promise<number> {
+  if (command.fallback && startsWithFallbackOption(command, args))
+    return runGroup(command, [command.fallback, ...args], path);
   const [first, ...rest] = args;
   const name = first === undefined ? command.fallback : first;
   if (name === undefined || name === "help" || HELP_FLAGS.has(name)) {