agents-pod 0.1.0 → 0.3.0

package/src/workspace.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { InboxItem } from "./inbox.ts";
+import { deliveryAddress, type InboxItem } from "./inbox.ts";
 import { podDir } from "./paths.ts";
 import type { PodRecord } from "./registry.ts";
 
@@ -48,7 +48,7 @@ const TEMPLATES: Record<string, string> = {
     "One line per decision, with its reason. Append-only.",
     "",
   ].join("\n"),
-  "TASKS.md": ["# Tasks", "", "## Plan", "", "## Inbox", ""].join("\n"),
+  "TASKS.md": ["# Tasks", "", "## Plan", "", "## Waiting", "", "## Inbox", ""].join("\n"),
 };
 
 /** The one section reconcile may write (ADR 0008, 0014). */
@@ -58,6 +58,9 @@ export async function createPodWorkspace(pod: PodRecord): Promise<string> {
   const dir = podDir(pod.project, pod.id);
   const docs = join(dir, "docs");
   await mkdir(docs, { recursive: true });
+  // The outbox is beside the three-slot Document Store, never a fourth slot
+  // (ADRs 0008, 0025).
+  await mkdir(join(dir, "outbox"), { recursive: true });
   for (const [name, body] of Object.entries(TEMPLATES)) {
     await writeFile(join(docs, name), body);
   }
@@ -70,9 +73,13 @@ export async function createPodWorkspace(pod: PodRecord): Promise<string> {
  * audit have an anchor; the body is copied because the source file belongs to
  * its writer and may be deleted once the item is claimed.
  */
-export function inboxBlock(item: Pick<InboxItem, "id" | "title" | "body">): string {
+export function inboxBlock(
+  item: Pick<InboxItem, "id" | "title" | "body" | "chatId" | "rootId" | "threadId">,
+): string {
   const title = item.title.split("\n", 1)[0]!.trim();
-  const lines = [`- [ ] ${item.id} — ${title}`];
+  const address = deliveryAddress(item);
+  const suffix = address === "" ? "" : ` — to: ${address}`;
+  const lines = [`- [ ] ${item.id} — ${title}${suffix}`];
   const body = item.body.replace(/\r\n/g, "\n").replace(/\n+$/, "");
   if (body.length > 0) {
     for (const line of body.split("\n")) {

package/src/wrapper.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
+  appendFile,
   copyFile,
   mkdir,
   open,
@@ -20,7 +21,15 @@ import {
   type WrapperRecord,
 } from "./liveness.ts";
 import { podDir } from "./paths.ts";
-import { readPods, writePods, type WakeUpOutcome } from "./registry.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). */
@@ -213,17 +222,52 @@ 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, n: number, what: string): Promise<void> {
-  const pods = await readPods();
-  const record = pods.find((candidate) => candidate.id === podId);
-  if (!record) return;
-  record.wakeUps.push({ n, outcome: "failed", detail: what });
-  record.state = "idle";
-  await writePods(pods);
+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> {
@@ -255,8 +299,7 @@ export async function runWrapper(argv: string[]): Promise<number> {
   const agentId = agentWord ?? pod.policy?.agent ?? "default";
   const agent = resolveAgentDefinition(await readAgents(), agentId);
   if (!agent) {
-    await recordUnresolved(podId, n, "agent resolution failed");
-    return 0;
+    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
@@ -266,8 +309,14 @@ export async function runWrapper(argv: string[]): Promise<number> {
   // from there; it never silently runs pi in claude's name.
   const refusal = agentTypeRefusal(agent.type);
   if (refusal !== undefined) {
-    await recordUnresolved(podId, n, `agent ${agent.id} has type ${agent.type}: ${refusal}`);
-    return 0;
+    return (await recordUnresolved(
+      podId,
+      podRoot,
+      n,
+      `agent ${agent.id} has type ${agent.type}: ${refusal}`,
+    ))
+      ? 0
+      : 1;
   }
 
   const wakeupDir = join(podRoot, "wakeups", String(n));
@@ -437,9 +486,7 @@ export async function runWrapper(argv: string[]): Promise<number> {
   // 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 pods = await readPods();
-    const record = pods.find((p) => p.id === podId);
-    if (record) {
+    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
@@ -452,9 +499,9 @@ export async function runWrapper(argv: string[]): Promise<number> {
             : { n, outcome: "cancelled" },
         );
         record.state = "cancelled";
-        await writePods(pods);
       }
-    }
+    });
+    if (!recorded) return 1;
     // The identity outlives its purpose only until the outcome is recorded.
     await rm(wrapperRecordFile, { force: true });
     return 0;
@@ -466,13 +513,15 @@ export async function runWrapper(argv: string[]): Promise<number> {
     () => undefined,
   );
   const { outcome, detail } = await adjudicate(docsDir, wakeStart, eventsFile, code);
-  const pods = await readPods();
-  const record = pods.find((p) => p.id === podId);
-  if (record) {
+  // 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";
-    await writePods(pods);
-  }
+  });
+  if (!recorded) return 1;
   // The identity outlives its purpose only until the outcome is recorded.
   await rm(wrapperRecordFile, { force: true });
   return 0;