agents-pod 0.1.0 → 0.2.0

package/src/inbox.ts

@@ -1,18 +1,58 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 /**
- * An Inbox Item (ADR 0013): one positional id, the four values a Pod Template
+ * An Inbox Item (ADR 0013): one positional id, the values a Pod Template
  * binds, and the facts the two-pass stability guard compares. `{{path}}` is the
  * item file's absolute path (directory inbox) or the JSONL path plus line.
+ *
+ * The optional routing fields are the platform's passengers (ADR 0026): they
+ * never join the id or the body, they only feed the Delivery Address.
  */
 export interface InboxItem {
-  /** Directory: the filename. File: the line number. Never content (ADR 0013). */
+  /** Directory: filename. File: line number. Source: the platform's id (ADRs 0013, 0024). */
   id: string;
   title: string;
   body: string;
+  /** Empty for a Source item, which has no filesystem attachment (ADR 0024). */
   path: string;
+  /** Inbox stability facts only; placeholders are zero for a Source item. */
   mtimeMs: number;
   size: number;
+  /** The chat a reply has to land in; without it there is no address. */
+  chatId?: string;
+  /** The root message: the Conversation's key, propagated by the platform. */
+  rootId?: string;
+  /** The topic thread, when the platform gave the message one. */
+  threadId?: string;
+}
+
+/**
+ * The Delivery Address (ADR 0026): the Conversation's key, the chat, and the
+ * optional thread as one opaque token — the string an outbox entry's `to`
+ * takes verbatim and a deliverer parses. Core never reads it back. An item with
+ * no chat has nowhere to be answered, so it renders the empty string rather
+ * than a token with a `chat=` hole; root and thread are passengers, never a
+ * substitute for the chat.
+ *
+ * The affinity is `root_id ?? item id`, exactly as ADR 0026 states it. For a
+ * directory or JSONL inbox the id is the item's position, not a platform
+ * message id; a Source (ADR 0024) is what makes the id the platform's, and
+ * therefore the fallback usable by a deliverer.
+ */
+export function deliveryAddress(
+  item: Pick<InboxItem, "id" | "chatId" | "rootId" | "threadId">,
+): string {
+  if (item.chatId === undefined) return "";
+  const affinity = item.rootId ?? item.id;
+  const thread = item.threadId === undefined ? "" : `;thread=${item.threadId}`;
+  return `chat=${item.chatId};affinity=${affinity}${thread}`;
+}
+
+/** A routing field is a non-empty, trimmed string; anything else is as ignored as an unknown key. */
+function routingField(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
 }
 
 /** A malformed JSONL line: skipped, unclaimed, warned on every pass (ADR 0013). */
@@ -74,8 +114,10 @@ async function scanDirectory(dir: string): Promise<InboxScan> {
 
 /**
  * A file inbox is JSONL only (ADR 0013): `body` is required, `title` optional,
- * extra keys ignored. A line that does not parse, or carries no string body, is
- * skipped and reported — never claimed, never fatal to the pass.
+ * `chat_id`/`root_id`/`thread_id` are read as the item's routing fields
+ * (ADR 0026), and every other key is ignored. A line that does not parse, or
+ * carries no string body, is skipped and reported — never claimed, never fatal
+ * to the pass.
  */
 async function scanJsonl(file: string): Promise<InboxScan> {
   const info = await stat(file).catch(() => undefined);
@@ -101,7 +143,13 @@ async function scanJsonl(file: string): Promise<InboxScan> {
       bad.push({ line, reason: "invalid JSON (not an object)" });
       continue;
     }
-    const record = parsed as { body?: unknown; title?: unknown };
+    const record = parsed as {
+      body?: unknown;
+      title?: unknown;
+      chat_id?: unknown;
+      root_id?: unknown;
+      thread_id?: unknown;
+    };
     if (typeof record.body !== "string") {
       bad.push({ line, reason: "no body" });
       continue;
@@ -110,6 +158,9 @@ async function scanJsonl(file: string): Promise<InboxScan> {
       typeof record.title === "string" && record.title.trim() !== ""
         ? record.title
         : firstLine(record.body);
+    const chatId = routingField(record.chat_id);
+    const rootId = routingField(record.root_id);
+    const threadId = routingField(record.thread_id);
     items.push({
       id: String(line),
       title,
@@ -117,6 +168,9 @@ async function scanJsonl(file: string): Promise<InboxScan> {
       path: `${file}#${line}`,
       mtimeMs: info.mtimeMs,
       size: info.size,
+      ...(chatId === undefined ? {} : { chatId }),
+      ...(rootId === undefined ? {} : { rootId }),
+      ...(threadId === undefined ? {} : { threadId }),
     });
   }
   return { items, bad };
@@ -129,8 +183,19 @@ export async function scanInbox(inbox: string): Promise<InboxScan> {
   return info.isDirectory() ? scanDirectory(inbox) : scanJsonl(inbox);
 }
 
-/** The exactly-four template placeholders (ADR 0013). */
-const PLACEHOLDERS = new Set(["id", "title", "body", "path"]);
+/**
+ * The five template placeholders (ADR 0013, amended by ADR 0026), each one a
+ * renderer: adding a sixth is one row, not a set plus two casts.
+ */
+const PLACEHOLDERS: Record<string, (item: InboxItem) => string> = {
+  id: (item) => item.id,
+  title: (item) => item.title,
+  body: (item) => item.body,
+  path: (item) => item.path,
+  // The address is derived, not a field: an item without routing fields
+  // renders empty, so a template stays valid for both kinds of item.
+  reply_to: deliveryAddress,
+};
 
 /**
  * Render a Pod Template against one item. An unknown `{{...}}` is a
@@ -144,11 +209,12 @@ export function renderTemplate(
   const unknown: string[] = [];
   const goal = template.replace(/\{\{([^{}]*)\}\}/g, (whole: string, raw: string) => {
     const name = raw.trim();
-    if (!PLACEHOLDERS.has(name)) {
+    const render = PLACEHOLDERS[name];
+    if (render === undefined) {
       unknown.push(name);
       return whole;
     }
-    return item[name as "id" | "title" | "body" | "path"];
+    return render(item);
   });
   if (unknown.length > 0) return { error: `unknown placeholder {{${unknown[0]}}}` };
   return { goal };

package/src/listeners.ts

@@ -11,9 +11,10 @@ import { listenersFile } from "./paths.ts";
 export type ListenerMode = "template" | "pod";
 
 /**
- * A consumed item, by position (ADR 0013): the claim namespace is the inbox, so
- * `inbox` + `item` is the key across listeners. `spawnedPodId` is what the
- * template materialized; `blocked` is a reason materialization will not happen
+ * A consumed item, by position for an inbox or platform id for a Source
+ * (ADRs 0013, 0024): the claim namespace is the origin, so `inbox` + `item` is
+ * the key across listeners. `spawnedPodId` is what the template materialized;
+ * `blocked` is a reason materialization will not happen
  * (a configuration error, or an item that vanished). `appended` is ADR 0014's
  * one boolean for a bound standing pod: the block is in the pod's `## Inbox`.
  * Beyond that the document is the truth — there is no per-item lifecycle.
@@ -21,6 +22,8 @@ export type ListenerMode = "template" | "pod";
 export interface ClaimRecord {
   inbox: string;
   item: string;
+  /** Source claims retain the current and previous successful drain (ADR 0024). */
+  claimedAt?: number;
   spawnedPodId?: string;
   blocked?: string;
   appended?: boolean;
@@ -35,13 +38,16 @@ export interface SeenFact {
 
 export interface ListenerRecord {
   id: string;
-  /** Absolute path: a directory inbox or one append-only JSONL file. */
-  inbox: string;
+  /** Exactly one origin: an absolute inbox path or a Source name (ADR 0024). */
+  inbox?: string;
+  source?: string;
   /** P0's rule: a plain substring; absent means every item matches. */
   match?: string;
   mode: ListenerMode;
   /** Template mode: the goal template file. */
   template?: string;
+  /** Template mode: materialize under this project instead of the tick's cwd (ADR 0007). */
+  project?: string;
   /** Pod mode: the standing pod whose `## Inbox` the items join (ADR 0014). */
   podId?: string;
   maxConcurrent: number;

package/src/outbox.ts

@@ -0,0 +1,294 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { cronLogPath, delivererFile, podDir } from "./paths.ts";
+
+/** The single operator delivery command (ADR 0025). */
+export interface DelivererRecord {
+  name: string;
+  cmd: string;
+  timeoutMs: number;
+}
+
+export const OUTBOX_FLUSH_MAX_ENTRIES = 10;
+export const OUTBOX_FLUSH_BUDGET_MS = 10_000;
+export const OUTBOX_DEAD_AFTER_MS = 3_600_000;
+
+export async function readDeliverer(): Promise<DelivererRecord | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(delivererFile(), "utf8"));
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as DelivererRecord)
+      : undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/** The single record has its own atomic write, beside sources.json (ADR 0025). */
+export async function writeDeliverer(deliverer: DelivererRecord): Promise<void> {
+  const file = delivererFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(deliverer, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+/**
+ * The filename is the uuid's third input, so a later pass can re-derive it
+ * without registry state (ADR 0025, amended by #14). Fifty hex chars fit the
+ * delivery platform's uuid limit.
+ */
+export function outboxUuid(podId: string, wakeup: number, filename: string): string {
+  return createHash("sha256")
+    .update(podId)
+    .update("\0")
+    .update(String(wakeup))
+    .update("\0")
+    .update(filename)
+    .digest("hex")
+    .slice(0, 50);
+}
+
+async function logOutbox(line: string): Promise<void> {
+  const file = cronLogPath();
+  await mkdir(dirname(file), { recursive: true });
+  await appendFile(file, `${line}\n`);
+}
+
+function validEntry(raw: string): boolean {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+    const entry = parsed as { to?: unknown; text?: unknown };
+    // The shape is fixed by ADR 0025: two strings, the address and the words.
+    return typeof entry.to === "string" && entry.to !== "" && typeof entry.text === "string";
+  } catch {
+    return false;
+  }
+}
+
+/** Exit 0 is the only acknowledgement; every other outcome leaves the file. */
+async function deliverOne(
+  deliverer: DelivererRecord,
+  podId: string,
+  project: string,
+  wakeup: number,
+  filename: string,
+  raw: string,
+  timeoutMs: number,
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    const child = spawn(deliverer.cmd, [], {
+      cwd: project,
+      env: {
+        ...process.env,
+        AGENTS_POD_POD_ID: podId,
+        AGENTS_POD_WAKEUP_N: String(wakeup),
+        AGENTS_POD_OUTBOX_ENTRY: filename,
+        AGENTS_POD_OUTBOX_UUID: outboxUuid(podId, wakeup, filename),
+      },
+      // A delivery command can leave a child behind; its own process group
+      // makes the invocation timeout a hard bound (ADR 0025).
+      detached: true,
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+    const kill = (): void => {
+      if (child.pid === undefined) {
+        child.kill("SIGKILL");
+        return;
+      }
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    };
+    let timedOut = false;
+    let spawnError: string | undefined;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, timeoutMs);
+    child.on("error", (error) => {
+      spawnError = error.message;
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (timedOut) return resolve(`timed out after ${timeoutMs / 1000}s`);
+      if (spawnError !== undefined) return resolve(spawnError);
+      if (code !== 0) {
+        return resolve(
+          signal === null ? `exit ${code ?? "unknown"}` : `terminated by ${signal}`,
+        );
+      }
+      resolve(undefined);
+    });
+    // A command may exit without reading stdin; that is its exit status, not a
+    // wrapper-level EPIPE failure.
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(raw);
+  });
+}
+
+/** The leading filename field is the entry's immutable wake-up attribution. */
+function entryWakeup(filename: string): number | undefined {
+  const match = /^([1-9]\d*)-/.exec(filename);
+  if (match === null) return undefined;
+  const wakeup = Number(match[1]);
+  return Number.isSafeInteger(wakeup) ? wakeup : undefined;
+}
+
+/** Dead-lettering changes the name, never the contents, and keeps the evidence. */
+async function deadLetter(podId: string, file: string, name: string, reason: string): Promise<void> {
+  try {
+    await rename(file, `${file}.dead`);
+    await logOutbox(`outbox ${podId}: ${name} dead-lettered (${reason}); kept as ${name}.dead`);
+  } catch (error) {
+    await logOutbox(
+      `outbox ${podId}: ${name} dead-letter rename failed (${(error as Error).message}); file kept`,
+    );
+  }
+}
+
+/**
+ * The wrapper and reconcile share one bounded flush (ADR 0025). A wrapper
+ * touches only its own wake-up's entries: older ones belong to pass retries.
+ * A pass derives every uuid from the filename, so retries keep their original
+ * wake-up number. Failures are audit lines, never outcome, policy, or
+ * notification changes.
+ */
+async function flushEntries(
+  podId: string,
+  project: string,
+  currentWakeup?: number,
+): Promise<void> {
+  const dir = join(podDir(project, podId), "outbox");
+  let names: string[];
+  try {
+    names = (await readdir(dir)).filter((name) => name.endsWith(".json")).sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    await logOutbox(`outbox ${podId}: unreadable (${(error as Error).message})`);
+    return;
+  }
+  if (names.length === 0) return;
+
+  let deliverer: DelivererRecord | undefined;
+  try {
+    deliverer = await readDeliverer();
+  } catch (error) {
+    await logOutbox(`outbox ${podId}: deliverer unreadable (${(error as Error).message})`);
+    return;
+  }
+  // The unconfigured wrapper flush stays a no-op; the pass owns waiting and
+  // aging so each pass can make the missing configuration audible once.
+  if (deliverer === undefined && currentWakeup !== undefined) return;
+
+  const startedAt = Date.now();
+  let invocations = 0;
+  let waiting = 0;
+  for (const name of names) {
+    const elapsed = Date.now() - startedAt;
+    if (
+      deliverer !== undefined &&
+      (invocations >= OUTBOX_FLUSH_MAX_ENTRIES || elapsed >= OUTBOX_FLUSH_BUDGET_MS)
+    ) {
+      return;
+    }
+    const file = join(dir, name);
+    const wakeup = entryWakeup(name);
+    if (wakeup === undefined) {
+      await deadLetter(podId, file, name, "unparseable wake-up");
+      continue;
+    }
+    if (currentWakeup !== undefined) {
+      // An earlier wake-up's failed entry must survive later wrapper flushes;
+      // the pass retries it with the same uuid until the one-hour boundary.
+      if (wakeup < currentWakeup) continue;
+      if (wakeup > currentWakeup) {
+        await deadLetter(podId, file, name, `wake-up ${wakeup} is after ${currentWakeup}`);
+        continue;
+      }
+    }
+
+    const info = await stat(file).catch(() => undefined);
+    if (info === undefined) {
+      await logOutbox(`outbox ${podId}: ${name} unreadable; skipped`);
+      continue;
+    }
+    if (Date.now() - info.mtimeMs > OUTBOX_DEAD_AFTER_MS) {
+      await deadLetter(podId, file, name, "older than one hour");
+      continue;
+    }
+
+    let raw: string;
+    try {
+      raw = await readFile(file, "utf8");
+    } catch (error) {
+      await logOutbox(`outbox ${podId}: ${name} unreadable (${(error as Error).message}); skipped`);
+      continue;
+    }
+    if (!validEntry(raw)) {
+      await deadLetter(podId, file, name, "invalid entry (expected JSON with to and text)");
+      continue;
+    }
+    if (deliverer === undefined) {
+      waiting += 1;
+      continue;
+    }
+
+    const remainingMs = OUTBOX_FLUSH_BUDGET_MS - (Date.now() - startedAt);
+    if (remainingMs <= 0) return;
+    invocations += 1;
+    const error = await deliverOne(
+      deliverer,
+      podId,
+      project,
+      wakeup,
+      name,
+      raw,
+      Math.min(deliverer.timeoutMs, remainingMs),
+    );
+    if (error === undefined) {
+      try {
+        // Deletion is the acknowledgement; no completion marker exists.
+        await rm(file, { force: true });
+      } catch (deleteError) {
+        await logOutbox(
+          `outbox ${podId}: ${name} delivered but delete failed (${(deleteError as Error).message})`,
+        );
+      }
+    } else {
+      await logOutbox(`outbox ${podId}: ${name} delivery failed (${error}); file kept`);
+    }
+  }
+  if (deliverer === undefined && waiting > 0) {
+    await logOutbox(`outbox ${podId}: no deliverer configured; ${waiting} entries waiting`);
+  }
+}
+
+/** Flush this wake-up's outbox after adjudication and before idle (ADR 0025). */
+export async function flushOutbox(
+  podId: string,
+  project: string,
+  wakeup: number,
+): Promise<void> {
+  await flushEntries(podId, project, wakeup);
+}
+
+/** Retry one non-active Pod's outbox during reconcile (ADR 0025). */
+export async function retryOutbox(podId: string, project: string): Promise<void> {
+  await flushEntries(podId, project);
+}

package/src/paths.ts

@@ -31,6 +31,16 @@ export function listenersFile(): string {
   return join(storeRoot(), "listeners.json");
 }
 
+/** Sources and their committed cursors, beside rather than inside the registry (ADR 0024). */
+export function sourcesFile(): string {
+  return join(storeRoot(), "sources.json");
+}
+
+/** The single outbound delivery command, beside the Source records (ADR 0025). */
+export function delivererFile(): string {
+  return join(storeRoot(), "deliverer.json");
+}
+
 /** The pass's single-flight advisory lock, one for the whole registry (ADR 0018). */
 export function reconcileLockPath(): string {
   return join(storeRoot(), "reconcile.lock");