portable-agent-layer 0.111.0 → 0.113.0

package/src/hooks/lib/claim-log.ts

@@ -40,7 +40,7 @@ function monthFile(date: Date): string {
   return resolve(claimsDir(), `${date.toISOString().slice(0, 7)}.jsonl`);
 }
 
-function transcriptLines(payload: StopTurnPayload): string[] {
+export function transcriptLines(payload: StopTurnPayload): string[] {
   const path = payload.transcript_path ?? payload.transcriptPath;
   if (!path || !existsSync(path)) return [];
   return readFileSync(path, "utf-8").split("\n").filter(Boolean);

package/src/hooks/lib/claude-md.ts

@@ -110,7 +110,16 @@ export function needsRebuild(): boolean {
   return latestMtime(...sources) > outputMtime;
 }
 
-import { identity } from "./settings";
+import { identity, isOptedIn } from "./settings";
+
+const OPT_IN_LINE_RE = /^\{\{IF (\w+)\}\}(.*\n?)/gm;
+
+/** A `{{IF key}}` line stays, without its prefix, only when that setting is opted into. */
+function withOptedInLines(template: string): string {
+  return template.replace(OPT_IN_LINE_RE, (_, key: string, line: string) =>
+    isOptedIn(key) ? line : ""
+  );
+}
 
 /** Render AGENTS.md from the template using current state */
 export function buildClaudeMd(): string {
@@ -120,7 +129,7 @@ export function buildClaudeMd(): string {
 
   const id = identity();
 
-  return template
+  return withOptedInLines(template)
     .replaceAll("{{IDENTITY_NAME}}", id.ai.name)
     .replaceAll("{{IDENTITY_DISPLAY}}", id.ai.displayName)
     .replaceAll("{{IDENTITY_CATCHPHRASE}}", id.ai.catchphrase)

package/src/hooks/lib/context.ts

@@ -18,6 +18,7 @@ import { sessionDir } from "./session-dir";
 import * as settings from "./settings";
 import { readFramePrinciples } from "./wisdom";
 import { lastSessionTitle } from "./work-tracking";
+import { loadWorkTreeContext } from "./work-tree-context";
 
 /** Load and concatenate loadAtStartup files */
 function loadStartupFiles(): string {
@@ -223,10 +224,12 @@ export function buildSystemReminder(
     !opts.withoutHandoff && settings.isEnabled("handoff")
       ? loadHandoffContext(sessionDir())
       : "";
+  const workTree = loadWorkTreeContext(sessionDir());
   const dueNudges = opts.agent === "cursor" ? dueNudgeSections() : [];
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
+  if (workTree) parts.push(workTree);
   parts.push(...dueNudges);
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);

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

@@ -0,0 +1,25 @@
+/**
+ * Where the work tree enters an agent's context: the block every new or
+ * compacted session starts with, and the line every prompt carries.
+ */
+
+import { reactionTo } from "./interaction-reaction";
+import { sessionDir } from "./session-dir";
+import { isOptedIn } from "./settings";
+import { readTree, scopeOf } from "./work-tree";
+import { renderPromptLine, renderSessionContext } from "./work-tree-render";
+
+export function loadWorkTreeContext(cwd: string = sessionDir()): string {
+  if (!isOptedIn("workTree")) return "";
+  return renderSessionContext(readTree(scopeOf(cwd)));
+}
+
+export function workTreePromptLine(
+  userText: string,
+  cwd: string = sessionDir()
+): string | null {
+  if (!isOptedIn("workTree")) return null;
+  const newTopic = userText !== "" && reactionTo(userText, undefined) === "new-topic";
+  const line = renderPromptLine(readTree(scopeOf(cwd)), newTopic);
+  return line ? `<system-reminder>${line}</system-reminder>` : null;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * The end-of-turn check that keeps the work tree true: a turn that produced
+ * something (a commit, a branch, a PR, a published artifact) and recorded
+ * nothing in the tree is sent back once to record it.
+ */
+
+import { callsThisTurn, commandsThisTurn } from "./claim-check";
+import { alreadySentBack, transcriptLines } from "./claim-log";
+import { sessionDir } from "./session-dir";
+import { isOptedIn } from "./settings";
+import type { StopTurnPayload } from "./stop";
+import { readTree, scopeOf } from "./work-tree";
+import { attachGitProgress } from "./work-tree-git";
+import { renderPromptLine } from "./work-tree-render";
+
+const RECORDS_WORK_RE = /\bpal\s+cli\s+work\b/;
+
+const PRODUCERS: { what: string; re: RegExp }[] = [
+  { what: "committed", re: /\bgit\s+commit\b/ },
+  { what: "made a branch", re: /\bgit\s+(?:checkout\s+-b|switch\s+-c|branch\s+(?!-)\S)/ },
+  { what: "opened a PR", re: /\bgh\s+pr\s+create\b/ },
+];
+
+const ARTIFACT_TOOLS: ReadonlySet<string> = new Set(["Artifact"]);
+const NON_PUBLISH_ACTION_RE = /"action":"(?!publish")/;
+
+function producedThisTurn(commands: string[], lines: string[]): string[] {
+  const produced = PRODUCERS.filter((p) => commands.some((c) => p.re.test(c))).map(
+    (p) => p.what
+  );
+  const artifacts = callsThisTurn(lines, ARTIFACT_TOOLS) ?? [];
+  if (artifacts.some((call) => !NON_PUBLISH_ACTION_RE.test(call)))
+    produced.push("published an artifact");
+  return produced;
+}
+
+function sendBackReason(produced: string[], scope: string): string {
+  const where = renderPromptLine(readTree(scope), false) ?? "Work: nothing recorded yet";
+  return [
+    `This turn ${produced.join(", ")} but recorded nothing in the work tree (${where}).`,
+    'Record where the work stands with `pal cli work stopped "…"`, plus `decide` or `attach` where they fit;',
+    'if no node fits, open one first with `pal cli work open "…"` (`--root` for unrelated work).',
+  ].join(" ");
+}
+
+export function workTreeSendBack(
+  payload: StopTurnPayload,
+  lines: string[],
+  cwd: string
+): string | null {
+  if (!isOptedIn("workTree") || !isOptedIn("workTreeGate")) return null;
+  if (alreadySentBack(payload)) return null;
+  const commands = commandsThisTurn(lines);
+  if (commands === null || commands.some((c) => RECORDS_WORK_RE.test(c))) return null;
+  const produced = producedThisTurn(commands, lines);
+  return produced.length > 0 ? sendBackReason(produced, scopeOf(cwd)) : null;
+}
+
+/** The reason to send the turn back with, or null after attaching what git moved. */
+export function stopWorkTree(payload: StopTurnPayload | null): string | null {
+  if (!payload || !isOptedIn("workTree")) return null;
+  const cwd = sessionDir();
+  const sendBack = workTreeSendBack(payload, transcriptLines(payload), cwd);
+  if (sendBack) return sendBack;
+  attachGitProgress(cwd);
+  return null;
+}

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

@@ -0,0 +1,98 @@
+/**
+ * New commits and branch switches land on the active work-tree node at the end
+ * of a turn, so the tree knows what the work produced without being told.
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendEvent, readTree, scopeOf } from "./work-tree";
+
+const GIT_TIMEOUT_MS = 1000;
+const MAX_COMMITS = 20;
+
+interface GitSnapshot {
+  branch: string;
+  head: string;
+  email: string;
+}
+
+interface Commit {
+  sha: string;
+  subject: string;
+}
+
+function git(cwd: string, ...args: string[]): string | null {
+  const result = spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf-8",
+    timeout: GIT_TIMEOUT_MS,
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function snapshot(cwd: string): GitSnapshot | null {
+  const head = git(cwd, "rev-parse", "HEAD");
+  const branch = git(cwd, "rev-parse", "--abbrev-ref", "HEAD");
+  if (!head || !branch) return null;
+  return { head, branch, email: git(cwd, "config", "user.email") ?? "" };
+}
+
+/** Only the user's own commits: a pull brings other people's work, which this turn did not make. */
+function ownCommitsSince(cwd: string, from: string, to: string, email: string): Commit[] {
+  const log = git(
+    cwd,
+    "log",
+    `-${MAX_COMMITS}`,
+    "--format=%h%x09%ae%x09%s",
+    `${from}..${to}`
+  );
+  if (!log) return [];
+  return log
+    .split("\n")
+    .map((line) => line.split("\t"))
+    .filter(([, author]) => author === email)
+    .map(([sha, , subject]) => ({ sha, subject }))
+    .reverse();
+}
+
+/** A scope with no work yet is left alone, so visiting a repo writes nothing. */
+export function attachGitProgress(
+  cwd: string,
+  file?: string,
+  now: Date = new Date()
+): void {
+  const scope = scopeOf(cwd);
+  const tree = readTree(scope, file);
+  if (tree.nodes.size === 0) return;
+  const current = snapshot(cwd);
+  if (!current) return;
+  const cursor = tree.gitCursor;
+  if (cursor?.head === current.head && cursor.branch === current.branch) return;
+
+  if (cursor && tree.active) {
+    if (cursor.branch !== current.branch)
+      appendEvent(
+        scope,
+        tree.active,
+        "attach",
+        { kind: "branch", ref: current.branch },
+        file,
+        now
+      );
+    for (const commit of ownCommitsSince(cwd, cursor.head, current.head, current.email))
+      appendEvent(
+        scope,
+        tree.active,
+        "attach",
+        { kind: "commit", ref: commit.sha, label: commit.subject },
+        file,
+        now
+      );
+  }
+  appendEvent(
+    scope,
+    "",
+    "git-cursor",
+    { branch: current.branch, head: current.head },
+    file,
+    now
+  );
+}

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