agents-pod 0.0.0-stage → 0.2.0

package/src/wrapper.ts

@@ -0,0 +1,533 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  appendFile,
+  copyFile,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+  type FileHandle,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentTypeRefusal, readAgents, resolveAgentDefinition } from "./agents-store.ts";
+import {
+  currentBootTime,
+  psStart,
+  type WrapperRecord,
+} from "./liveness.ts";
+import { podDir } from "./paths.ts";
+import { flushOutbox } from "./outbox.ts";
+import { sleep } from "./locks.ts";
+import {
+  readPods,
+  withRegistryLock,
+  writePods,
+  type PodRecord,
+  type WakeUpOutcome,
+} from "./registry.ts";
+import { snapshotDocs } from "./workspace.ts";
+
+/** The heartbeat interval: the mtime is the liveness signal (ADR 0017). */
+const HEARTBEAT_MS = 30_000;
+
+/**
+ * The cancel grace (ADR 0017): SIGTERM first (exit 143 is `cancelled`, ADR
+ * 0009), SIGKILL after ten seconds — enough to finish a line, not a thought.
+ */
+export const CANCEL_GRACE_MS = 10_000;
+
+/**
+ * Tail semantics, not a state machine (ADR 0009): at exit only the last lines
+ * of the event stream can change the verdict, and the settled marker and the
+ * final assistant turn are always among them.
+ */
+const EVENTS_TAIL_LINES = 8;
+
+function fail(message: string): never {
+  console.error(`wrapper: ${message}`);
+  process.exit(2);
+}
+
+export interface ComposedPrompt {
+  preamble: string;
+  goal: string;
+  full: string;
+}
+
+/**
+ * The wake-up prompt in the fixed order (ADR 0012): Pod Contract preamble,
+ * then Role Instructions (empty for the default agent), then the Goal with the
+ * pointer block (ADR 0008: pointers, not inlines).
+ */
+export function composePrompt(goal: string, docsDir: string, roleInstructions = ""): ComposedPrompt {
+  const preamble = [
+    "You are one wake-up inside an agents-pod. Work only from these documents:",
+    `1. ${join(docsDir, "HANDOFF.md")} — your predecessor's handoff; start where it ended.`,
+    `2. ${join(docsDir, "TASKS.md")} — the plan and its checkboxes.`,
+    `3. ${join(docsDir, "DECISIONS.md")} — the why behind the plan.`,
+    "When this window's work is done, end with pod_handoff (status: rotating or done) so your successor starts clean. Write-then-exit is the protocol: an exit without a fresh handoff counts as a failure.",
+  ].join("\n");
+  const goalBlock = `Goal: ${goal}`;
+  const sections = [preamble, roleInstructions.trim(), goalBlock].filter(
+    (section) => section.length > 0,
+  );
+  return { preamble, goal, full: sections.join("\n\n") };
+}
+
+/** An explicit binary override resolves before $PATH (ADR 0015). */
+export function resolveAgentBinary(env: NodeJS.ProcessEnv): string {
+  return env.AGENTS_POD_PI_BIN?.trim() || "pi";
+}
+
+async function nextWakeupNumber(podRoot: string): Promise<number> {
+  const dir = join(podRoot, "wakeups");
+  const entries = await readdir(dir).catch(() => []);
+  const numbers = entries
+    .map((name) => Number.parseInt(name, 10))
+    .filter((n) => Number.isInteger(n));
+  return numbers.length > 0 ? Math.max(...numbers) + 1 : 1;
+}
+
+/** The one shape the wrapper reads out of pi's JSONL stream (ADR 0009). */
+interface EventEnvelope {
+  type?: string;
+  aborted?: boolean;
+  message?: { role?: string; content?: unknown; stopReason?: string };
+}
+
+function parseEvent(line: string): EventEnvelope | undefined {
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (typeof parsed !== "object" || parsed === null) return undefined;
+    return parsed as EventEnvelope;
+  } catch {
+    return undefined; // a torn or foreign line never breaks the wake-up
+  }
+}
+
+/**
+ * The wrapper-extracted assistant text (ADR 0009's dual logs): only the
+ * assistant's `message_end` is human-facing; everything else stays machine
+ * data in events.jsonl. The user echo and the bulky agent_end are skipped.
+ */
+function assistantTextOf(event: EventEnvelope): string | undefined {
+  if (event.type !== "message_end" || event.message?.role !== "assistant") {
+    return undefined;
+  }
+  const content = event.message.content;
+  if (!Array.isArray(content)) return undefined;
+  const texts = content.flatMap((part: unknown) => {
+    if (typeof part !== "object" || part === null) return [];
+    const { type, text } = part as { type?: unknown; text?: unknown };
+    return type === "text" && typeof text === "string" ? [text] : [];
+  });
+  return texts.length > 0 ? texts.join("") : undefined;
+}
+
+/** What the event stream says about how the agent settled (ADR 0009 layer 2). */
+interface EventFacts {
+  /** Non-blank lines in the whole file: zero means the agent never spoke. */
+  lines: number;
+  /** Whether an `agent_settled` marker appeared in the tail. */
+  settled: boolean;
+  /** Its `aborted` flag, when the adapter reported one. */
+  aborted?: boolean;
+  /** The last assistant turn's `stopReason`, when one was reported. */
+  stopReason?: string;
+}
+
+async function observeEvents(eventsFile: string): Promise<EventFacts> {
+  const body = await readFile(eventsFile, "utf8").catch(() => "");
+  const all = body.split("\n").filter((line) => line.trim().length > 0);
+  const facts: EventFacts = { lines: all.length, settled: false };
+  for (const line of all.slice(-EVENTS_TAIL_LINES)) {
+    const event = parseEvent(line);
+    if (!event) continue;
+    if (event.type === "agent_settled") {
+      facts.settled = true;
+      if (typeof event.aborted === "boolean") facts.aborted = event.aborted;
+    } else if (event.type === "message_end" && event.message?.role === "assistant") {
+      if (typeof event.message.stopReason === "string") {
+        facts.stopReason = event.message.stopReason;
+      }
+    }
+  }
+  return facts;
+}
+
+export interface Adjudication {
+  outcome: WakeUpOutcome;
+  /** The raw signals behind the verdict, for the pod record (ADR 0009). */
+  detail?: string;
+}
+
+/** ADR 0009 layer 1: only a handoff written during this wake-up counts. */
+async function freshDeclaration(
+  docsDir: string,
+  wakeStart: number,
+): Promise<"more" | "done" | undefined> {
+  const handoff = join(docsDir, "HANDOFF.md");
+  const info = await stat(handoff).catch(() => undefined);
+  if (!info || info.mtimeMs <= wakeStart) return undefined;
+  const firstLine = (await readFile(handoff, "utf8")).split("\n", 1)[0]!.trim();
+  const declared = /^status:\s*(rotating|done)\s*$/.exec(firstLine);
+  if (!declared) return undefined;
+  return declared[1] === "done" ? "done" : "more";
+}
+
+/**
+ * Three-layer adjudication, higher overrides lower (ADR 0009): the fresh
+ * Handoff declaration first, the wrapper's event observation next, raw exit
+ * facts last. A clean exit without a fresh handoff is `failed` — write-then-
+ * exit has teeth. A declaration always wins; when the events disagree the
+ * outcome is unchanged and the discrepancy is recorded instead.
+ */
+async function adjudicate(
+  docsDir: string,
+  wakeStart: number,
+  eventsFile: string,
+  exitCode: number,
+): Promise<Adjudication> {
+  const events = await observeEvents(eventsFile);
+  const declared = await freshDeclaration(docsDir, wakeStart);
+
+  if (declared) {
+    const discrepancies: string[] = [];
+    if (events.aborted === true) discrepancies.push("agent settled aborted");
+    if (events.stopReason !== undefined && events.stopReason !== "stop") {
+      discrepancies.push(`last stop reason ${events.stopReason}`);
+    }
+    return discrepancies.length === 0
+      ? { outcome: declared }
+      : { outcome: declared, detail: `declared ${declared} but ${discrepancies.join("; ")}` };
+  }
+
+  if (events.lines === 0) {
+    return { outcome: "failed", detail: `no fresh handoff (no events, exit ${exitCode})` };
+  }
+  return {
+    outcome: "failed",
+    detail: `no fresh handoff (settled: ${events.settled}, exit ${exitCode})`,
+  };
+}
+
+
+/** Twelve hex chars of sha256: enough to attribute a wake-up's instructions (ADR 0012). */
+function instructionsHash(instructions: string): string {
+  return createHash("sha256").update(instructions).digest("hex").slice(0, 12);
+}
+
+/**
+ * One pod's read-modify-write belongs wholly inside the registry lock (ADR
+ * 0018). A wrapper that cannot record its result must fail loudly and keep its
+ * identity: reconcile may call that wake-up lost, but its outcome is never
+ * silently discarded.
+ */
+async function updatePodRecord(
+  podId: string,
+  podRoot: string,
+  n: number,
+  mutate: (record: PodRecord) => void,
+): Promise<boolean> {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const recorded = await withRegistryLock(async () => {
+      const pods = await readPods();
+      const record = pods.find((candidate) => candidate.id === podId);
+      if (record) {
+        mutate(record);
+        await writePods(pods);
+      }
+      return true;
+    });
+    if (recorded !== undefined) return true;
+    if (attempt < 2) await sleep(100 * 2 ** attempt);
+  }
+  await appendFile(
+    join(podRoot, "output.log"),
+    `wrapper: registry lock unavailable; wake-up ${n} outcome not recorded\n`,
+  );
+  return false;
+}
+
+/**
+ * Records a wake-up that never reached an agent. The outcome is a fact; the
+ * policy that follows from it — backoff, streak, park — stays reconcile's.
+ */
+async function recordUnresolved(
+  podId: string,
+  podRoot: string,
+  n: number,
+  what: string,
+): Promise<boolean> {
+  return updatePodRecord(podId, podRoot, n, (record) => {
+    record.wakeUps.push({ n, outcome: "failed", detail: what });
+    record.state = "idle";
+  });
+}
+
+export async function runWrapper(argv: string[]): Promise<number> {
+  // `--warm` is a wrapper flag, not a positional (ADR 0011): the agent id is
+  // the first word that is not a flag.
+  const warm = argv.includes("--warm");
+  const [podId, agentWord] = argv.filter((word) => !word.startsWith("--"));
+  if (!podId) fail("usage: wrapper <podId> [agentId] [--warm]");
+
+  const pod = (await readPods()).find((p) => p.id === podId);
+  if (!pod) fail(`unknown pod ${podId}`);
+
+  // The CLI refuses an illegal warm at the surface; the wrapper repeats the
+  // check so a hand-built argv cannot resume a session that never crashed
+  // (ADR 0011).
+  const lastWake = pod.wakeUps.at(-1);
+  if (warm && lastWake?.outcome !== "lost") {
+    fail(`--warm requires the last outcome to be lost (last: ${lastWake?.outcome ?? "none"})`);
+  }
+
+  const podRoot = podDir(pod.project, podId);
+  const n = await nextWakeupNumber(podRoot);
+  const docsDir = join(podRoot, "docs");
+
+  // The wake names its agent; the wrapper resolves it against the store, and
+  // always the latest definition — nothing is pinned between wake-ups
+  // (ADR 0012). An unresolvable id fails the wake-up, not the pod: the pod
+  // returns to idle and reconcile's streak machinery takes it from there.
+  const agentId = agentWord ?? pod.policy?.agent ?? "default";
+  const agent = resolveAgentDefinition(await readAgents(), agentId);
+  if (!agent) {
+    return (await recordUnresolved(podId, podRoot, n, "agent resolution failed")) ? 0 : 1;
+  }
+
+  // The second seat of the Pi-only guard (ADR 0023, agents-store.ts): the CLI refuses an
+  // unsupported --type at `agent add`, and this catches a definition that got
+  // in anyway — a store written by an older build, or a hand-edited file. A
+  // failed wake-up returns the pod to idle and the streak machinery takes it
+  // from there; it never silently runs pi in claude's name.
+  const refusal = agentTypeRefusal(agent.type);
+  if (refusal !== undefined) {
+    return (await recordUnresolved(
+      podId,
+      podRoot,
+      n,
+      `agent ${agent.id} has type ${agent.type}: ${refusal}`,
+    ))
+      ? 0
+      : 1;
+  }
+
+  const wakeupDir = join(podRoot, "wakeups", String(n));
+  await mkdir(wakeupDir, { recursive: true });
+
+  // The model chain: the pod's spawn pin beats the definition's model, which
+  // beats the adapter's default (ADR 0012).
+  const model = pod.policy?.model ?? agent.model;
+
+  // Every wake-up is attributable after the fact: the resolved definition is
+  // snapshotted beside its handoff (ADR 0012). A warm wake-up says so, so a
+  // resumed session is distinguishable from a fresh one after the fact.
+  const snapshot = {
+    id: agent.id,
+    type: agent.type,
+    model: model ?? null,
+    instructionsHash: instructionsHash(agent.instructions),
+    ...(warm ? { warm: true } : {}),
+  };
+  await writeFile(join(wakeupDir, "agent.json"), `${JSON.stringify(snapshot, null, 2)}\n`);
+
+  const prompt = composePrompt(pod.goal, docsDir, agent.instructions);
+  // Warm is session-level adoption (ADR 0011, 0020): the wake-up is still n+1
+  // with its own directory, wrapper, and outcome, but the agent opens the
+  // lost wake-up's session file — pi continues that conversation — instead of
+  // a fresh one. `n` itself is untouched, so the directories still count
+  // wake-ups honestly.
+  const sessionFile =
+    warm && lastWake
+      ? join(podRoot, "wakeups", String(lastWake.n), "session.jsonl")
+      : join(wakeupDir, "session.jsonl");
+  const heartbeatFile = join(podRoot, "heartbeat");
+  const outputLog = join(podRoot, "output.log");
+  const eventsFile = join(wakeupDir, "events.jsonl");
+  const wakeStart = Date.now();
+
+  // Cancel is a signal, not a queue (ADR 0003): trap SIGTERM, forward it to
+  // the agent, let ADR 0017's grace expire, then kill. `cancel` signals the
+  // whole group — the wrapper leads it — so the trap must be installed before
+  // the identity record tells anyone where to signal.
+  let cancelRequested = false;
+  let killedAfterGrace = false;
+  let agentProcess: ChildProcess | undefined;
+  let graceTimer: ReturnType<typeof setTimeout> | undefined;
+  const onSigterm = (): void => {
+    if (cancelRequested) return; // a repeated signal changes nothing
+    cancelRequested = true;
+    agentProcess?.kill("SIGTERM");
+    graceTimer = setTimeout(() => {
+      killedAfterGrace = true;
+      agentProcess?.kill("SIGKILL");
+    }, CANCEL_GRACE_MS);
+  };
+  process.on("SIGTERM", onSigterm);
+
+  // The wrapper's identity (ADR 0003): written before the agent is spawned, so
+  // a running wake-up can be probed by pid and process group, and removed only
+  // after the outcome is recorded — a missing record with state active is a
+  // ghost reconcile will mark lost.
+  //
+  // The spawn-time facts (ADR 0020) make the identity verifiable: `pidStart`
+  // is read once here (the raw `ps` rendering, compared as a string, never
+  // parsed) and `bootTime` is this wall-clock boot moment, so a later killer
+  // can prove the pid it holds is still this wrapper on the same machine.
+  const wrapperRecordFile = join(podRoot, "wrapper.json");
+  const pidStart = await psStart(process.pid);
+  // The progress baseline (ADR 0019): the documents as this wake-up found
+  // them. Reconcile compares it at verdict time; the pod log is never consulted.
+  const docs = await snapshotDocs(docsDir);
+  const identity: WrapperRecord = {
+    pid: process.pid,
+    pgid: process.pid,
+    wakeup: n,
+    startedAt: wakeStart,
+    bootTime: currentBootTime(),
+    ...(pidStart === undefined ? {} : { pidStart }),
+    docs,
+  };
+  await writeFile(wrapperRecordFile, `${JSON.stringify(identity, null, 2)}\n`);
+
+  const log = await open(outputLog, "a");
+  await log.write(`\n--- wake-up ${n} ${new Date().toISOString()} ---\n`);
+  // Created before the spawn: an empty stream is itself a fact ("the agent
+  // never emitted an event"), and adjudication reads it that way.
+  const eventsLog = await open(eventsFile, "a");
+
+  // Writes are serialized so the header, the extracted text, and stderr keep
+  // their arrival order inside each log (ADR 0009's dual logs).
+  let writes: Promise<unknown> = Promise.resolve();
+  const queue = (handle: FileHandle, text: string): void => {
+    writes = writes.then(() => handle.write(text));
+  };
+
+  // One JSON object per line is the adapter contract (ADR 0009); a torn last
+  // line is held back until close, and blank lines carry no event.
+  let pending = "";
+  const receiveLine = (line: string): void => {
+    if (line.trim().length === 0) return;
+    queue(eventsLog, `${line}\n`);
+    const event = parseEvent(line);
+    const text = event ? assistantTextOf(event) : undefined;
+    if (text !== undefined) {
+      queue(log, text.endsWith("\n") ? text : `${text}\n`);
+    }
+  };
+
+  const touch = () => writeFile(heartbeatFile, `${Date.now()}\n`);
+  await touch();
+  const beat = setInterval(touch, HEARTBEAT_MS);
+
+  const child = spawn(
+    resolveAgentBinary(process.env),
+    [
+      "--print",
+      "--mode",
+      "json",
+      "--session",
+      sessionFile,
+      ...(model === undefined ? [] : ["--model", model]),
+      prompt.full,
+    ],
+    {
+      cwd: pod.project,
+      env: {
+        ...process.env,
+        AGENTS_POD_POD_ID: podId,
+        AGENTS_POD_WAKEUP_N: String(n),
+        AGENTS_POD_DOCS_DIR: docsDir,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    },
+  );
+  agentProcess = child;
+  // The group signal can land between the identity write and this spawn; the
+  // child would have missed it, so the forward is repeated once it exists.
+  if (cancelRequested) child.kill("SIGTERM");
+
+  // Event mode by default (ADR 0009): stdout is JSONL, so the wrapper splits
+  // it per line instead of forwarding it — raw to events.jsonl, assistant
+  // text to output.log. stderr is human-facing noise and stays as-is.
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    pending += chunk;
+    const lines = pending.split("\n");
+    pending = lines.pop() ?? "";
+    for (const line of lines) receiveLine(line);
+  });
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => queue(log, chunk));
+
+  const code: number = await new Promise((resolve) => {
+    child.on("error", (error) => fail(`agent binary failed: ${error.message}`));
+    child.on("close", (exitCode) => {
+      if (pending.trim().length > 0) receiveLine(pending);
+      pending = "";
+      resolve(exitCode ?? -1);
+    });
+  });
+
+  clearInterval(beat);
+  await writes;
+  await log.close();
+  await eventsLog.close();
+  clearTimeout(graceTimer);
+
+  // A cancelled wake-up is not adjudicated (ADR 0009): `cancelled` has an
+  // owner, and its detail is the wind-down, not the agent's last words. The
+  // pod is terminal, so reconcile never walks it back to a wake (ADR 0011).
+  if (cancelRequested) {
+    const recorded = await updatePodRecord(podId, podRoot, n, (record) => {
+      // A reconcile kill already adjudicated this wake-up (ADRs 0017, 0019):
+      // its intent was written before the signal, so the wrapper adds no
+      // second, contradictory outcome — whether the cause was progressless or
+      // a wedged kill. A human cancel has no intent and records exactly as
+      // before.
+      if (record.killIntent?.n !== n) {
+        record.wakeUps.push(
+          killedAfterGrace
+            ? { n, outcome: "cancelled", detail: "killed after grace" }
+            : { n, outcome: "cancelled" },
+        );
+        record.state = "cancelled";
+      }
+    });
+    if (!recorded) return 1;
+    // The identity outlives its purpose only until the outcome is recorded.
+    await rm(wrapperRecordFile, { force: true });
+    return 0;
+  }
+
+  // The wrapper records facts (ADR 0011): snapshot the handoff, adjudicate the
+  // outcome, and move the pod on. Policy — backoff, park — is reconcile's.
+  await copyFile(join(docsDir, "HANDOFF.md"), join(wakeupDir, "handoff.md")).catch(
+    () => undefined,
+  );
+  const { outcome, detail } = await adjudicate(docsDir, wakeStart, eventsFile, code);
+  // Delivery holds the active state until its bounded flush is over; a
+  // concurrent pass must not wake a second wrapper over the same outbox
+  // (ADR 0025). Failures are logged inside the flush and never change outcome.
+  await flushOutbox(podId, pod.project, n);
+  const recorded = await updatePodRecord(podId, podRoot, n, (record) => {
+    record.wakeUps.push(detail === undefined ? { n, outcome } : { n, outcome, detail });
+    record.state = outcome === "done" ? "done" : "idle";
+  });
+  if (!recorded) return 1;
+  // The identity outlives its purpose only until the outcome is recorded.
+  await rm(wrapperRecordFile, { force: true });
+  return 0;
+}
+
+/** Located next to the CLI's own bin so installed and repo layouts both work. */
+export function wrapperScript(): string {
+  return fileURLToPath(new URL("../bin/wrapper.mjs", import.meta.url));
+}