agents-pod 0.0.0-stage → 0.2.0

package/src/sources.ts

@@ -0,0 +1,278 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { BadInboxLine, InboxItem } from "./inbox.ts";
+import type { ListenerRecord } from "./listeners.ts";
+import { sourcesFile } from "./paths.ts";
+
+/** A Source outlives its Listeners; its opaque cursor lives beside them (ADR 0024). */
+export interface SourceRecord {
+  name: string;
+  cmd: string;
+  timeoutMs: number;
+  cursor?: string;
+  /** The previous successful drain is the claim-retention horizon (ADR 0024). */
+  lastDrainAt?: number;
+}
+
+export interface SourceDrain {
+  name: string;
+  items: InboxItem[];
+  bad: BadInboxLine[];
+  cursor?: string;
+  /** Successful drains carry their generation and the preceding one's boundary. */
+  drainedAt?: number;
+  previousDrainAt?: number;
+  /** A failed drain contributes nothing and leaves the cursor untouched. */
+  error?: string;
+}
+
+/** One MiB is the whole successful stdout budget (ADR 0024). */
+export const DRAIN_STDOUT_CAP = 1024 * 1024;
+
+export async function readSources(): Promise<SourceRecord[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(sourcesFile(), "utf8"));
+    return Array.isArray(parsed) ? (parsed as SourceRecord[]) : [];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/** The cursor's own atomic write, separate from listeners.json (ADR 0024). */
+export async function writeSources(sources: SourceRecord[]): Promise<void> {
+  const file = sourcesFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(sources, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+function routingField(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** A stream item is complete when its line parses; no two-pass guard applies. */
+export function parseDrainOutput(name: string, text: string): SourceDrain {
+  const items: InboxItem[] = [];
+  const bad: BadInboxLine[] = [];
+  let cursor: string | undefined;
+  const lines = text.split("\n")
+    .map((raw, index) => ({ raw, line: index + 1 }))
+    .filter(({ raw }) => raw.trim() !== "");
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const { raw, line } = lines[index]!;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      bad.push({ line, reason: "invalid JSON" });
+      continue;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      bad.push({ line, reason: "invalid JSON (not an object)" });
+      continue;
+    }
+    const record = parsed as {
+      id?: unknown;
+      body?: unknown;
+      title?: unknown;
+      cursor?: unknown;
+      chat_id?: unknown;
+      root_id?: unknown;
+      thread_id?: unknown;
+    };
+    if (
+      index === lines.length - 1 &&
+      "cursor" in record &&
+      record.id === undefined &&
+      record.body === undefined
+    ) {
+      if (typeof record.cursor !== "string") {
+        bad.push({ line, reason: "invalid cursor" });
+      } else {
+        cursor = record.cursor;
+      }
+      continue;
+    }
+    if (typeof record.id !== "string" || record.id.trim() === "") {
+      bad.push({ line, reason: "no id" });
+      continue;
+    }
+    if (typeof record.body !== "string") {
+      bad.push({ line, reason: "no body" });
+      continue;
+    }
+    const title =
+      typeof record.title === "string" && record.title.trim() !== ""
+        ? record.title
+        : record.body.split("\n", 1)[0]!.trim();
+    const chatId = routingField(record.chat_id);
+    const rootId = routingField(record.root_id);
+    const threadId = routingField(record.thread_id);
+    items.push({
+      id: record.id,
+      title,
+      body: record.body,
+      path: "",
+      mtimeMs: 0,
+      size: 0,
+      ...(chatId === undefined ? {} : { chatId }),
+      ...(rootId === undefined ? {} : { rootId }),
+      ...(threadId === undefined ? {} : { threadId }),
+    });
+  }
+  return { name, items, bad, ...(cursor === undefined ? {} : { cursor }) };
+}
+
+async function drainOne(source: SourceRecord, project: string): Promise<SourceDrain> {
+  const empty = { name: source.name, items: [], bad: [] };
+  const result = await new Promise<{ stdout?: string; error?: string }>((resolve) => {
+    const child = spawn(source.cmd, [], {
+      cwd: project,
+      env: {
+        ...process.env,
+        AGENTS_POD_SOURCE_ID: source.name,
+        AGENTS_POD_CURSOR: source.cursor ?? "",
+      },
+      // A shell drain can leave a child holding stdout after the shell dies.
+      // Its own process group makes the timeout and output cap real bounds.
+      detached: true,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const kill = (): void => {
+      if (child.pid === undefined) {
+        child.kill("SIGKILL");
+        return;
+      }
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    };
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let oversized = false;
+    let timedOut = false;
+    let spawnError: string | undefined;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, source.timeoutMs);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (bytes > DRAIN_STDOUT_CAP) {
+        if (!oversized) {
+          oversized = true;
+          kill();
+        }
+        return;
+      }
+      chunks.push(chunk);
+    });
+    child.on("error", (error) => {
+      spawnError = error.message;
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (oversized) return resolve({ error: "stdout exceeded 1 MiB" });
+      if (timedOut) return resolve({ error: `timed out after ${source.timeoutMs / 1000}s` });
+      if (spawnError !== undefined) return resolve({ error: spawnError });
+      if (code !== 0) {
+        return resolve({
+          error: signal === null ? `exit ${code ?? "unknown"}` : `terminated by ${signal}`,
+        });
+      }
+      resolve({ stdout: Buffer.concat(chunks).toString("utf8") });
+    });
+  });
+  if (result.error !== undefined) return { ...empty, error: result.error };
+  // Distinct generations need distinct boundaries even when two local drains
+  // finish within one wall-clock millisecond.
+  const drainedAt = Math.max(Date.now(), (source.lastDrainAt ?? 0) + 1);
+  return {
+    ...parseDrainOutput(source.name, result.stdout ?? ""),
+    drainedAt,
+    ...(source.lastDrainAt === undefined ? {} : { previousDrainAt: source.lastDrainAt }),
+  };
+}
+
+/** Drain each distinct Source once, before the registry lock or any Pod work (ADR 0024). */
+export async function drainSources(
+  project: string,
+  listeners: ListenerRecord[],
+): Promise<SourceDrain[]> {
+  const sources = await readSources();
+  const names = [...new Set(listeners.flatMap((listener) => listener.source ?? []))];
+  const drained: SourceDrain[] = [];
+  for (const name of names) {
+    const source = sources.find((candidate) => candidate.name === name);
+    drained.push(
+      source === undefined
+        ? { name, items: [], bad: [], error: "source record is missing" }
+        : await drainOne(source, project),
+    );
+  }
+  return drained;
+}
+
+/**
+ * Two generations are enough: after this drain, anything older than the prior
+ * successful one is behind the committed cursor and cannot arrive again. The
+ * store is transformed without I/O; the caller writes it inside the registry
+ * lock before advancing the Source records (ADR 0024). Legacy claims without a
+ * timestamp are retained because their generation cannot be proven.
+ */
+export function pruneSourceClaims(
+  listeners: ListenerRecord[],
+  drained: SourceDrain[],
+): { listeners: ListenerRecord[]; changed: boolean } {
+  const horizons = new Map<string, number>();
+  for (const drain of drained) {
+    if (drain.error === undefined && drain.previousDrainAt !== undefined) {
+      horizons.set(`source:${drain.name}`, drain.previousDrainAt);
+    }
+  }
+  if (horizons.size === 0) return { listeners, changed: false };
+
+  let changed = false;
+  const pruned = listeners.map((listener) => {
+    const claimed = listener.claimed.filter((claim) => {
+      const horizon = horizons.get(claim.inbox);
+      return (
+        horizon === undefined || claim.claimedAt === undefined || claim.claimedAt >= horizon
+      );
+    });
+    if (claimed.length === listener.claimed.length) return listener;
+    changed = true;
+    return { ...listener, claimed };
+  });
+  return { listeners: pruned, changed };
+}
+
+/** Claims and pruning land before this cursor/retention-horizon write (ADR 0024). */
+export async function commitSourceCursors(drained: SourceDrain[]): Promise<void> {
+  const sources = await readSources();
+  let changed = false;
+  for (const drain of drained) {
+    if (drain.error !== undefined || drain.drainedAt === undefined) continue;
+    const source = sources.find((candidate) => candidate.name === drain.name);
+    if (source === undefined) continue;
+    if (drain.cursor !== undefined && source.cursor !== drain.cursor) {
+      source.cursor = drain.cursor;
+      changed = true;
+    }
+    if (source.lastDrainAt !== drain.drainedAt) {
+      source.lastDrainAt = drain.drainedAt;
+      changed = true;
+    }
+  }
+  if (changed) await writeSources(sources);
+}

package/src/workspace.ts

@@ -0,0 +1,131 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { deliveryAddress, type InboxItem } from "./inbox.ts";
+import { podDir } from "./paths.ts";
+import type { PodRecord } from "./registry.ts";
+
+/** The document store's three slots: the only progress signal P1 trusts (ADR 0019). */
+export const DOC_FILES = ["HANDOFF.md", "DECISIONS.md", "TASKS.md"] as const;
+
+/** A document at a moment: progress is mtime or size moving (ADR 0019). */
+export interface DocFacts {
+  mtimeMs: number;
+  size: number;
+}
+
+/**
+ * The progress baseline (ADR 0019): the wake-up's start records what the
+ * documents looked like, so a later pass can prove they never moved. An absent
+ * file is simply not recorded — its appearing or vanishing is a change.
+ */
+export async function snapshotDocs(docsDir: string): Promise<Record<string, DocFacts>> {
+  const facts: Record<string, DocFacts> = {};
+  for (const name of DOC_FILES) {
+    const info = await stat(join(docsDir, name)).catch(() => undefined);
+    if (info !== undefined) facts[name] = { mtimeMs: info.mtimeMs, size: info.size };
+  }
+  return facts;
+}
+
+/**
+ * The document store's three slots, created from templates at spawn (ADR 0008).
+ * The wording is free markdown; the only machine surface P0 depends on is the
+ * HANDOFF first line and TASKS checkboxes, both grepped, never parsed.
+ *
+ * `## Inbox` is last so reconcile's append is an EOF append (ADR 0014).
+ */
+const TEMPLATES: Record<string, string> = {
+  "HANDOFF.md": [
+    "status: rotating",
+    "",
+    "No wake-up has written a handoff yet.",
+    "",
+  ].join("\n"),
+  "DECISIONS.md": [
+    "# Decisions",
+    "",
+    "One line per decision, with its reason. Append-only.",
+    "",
+  ].join("\n"),
+  "TASKS.md": ["# Tasks", "", "## Plan", "", "## Waiting", "", "## Inbox", ""].join("\n"),
+};
+
+/** The one section reconcile may write (ADR 0008, 0014). */
+const INBOX_HEADING = "## Inbox";
+
+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);
+  }
+  return dir;
+}
+
+/**
+ * One Inbox entry block (ADR 0014): `- [ ] <id> — <title>`, then the body
+ * copied in as an indented list continuation. The id leads so counting and
+ * 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" | "chatId" | "rootId" | "threadId">,
+): string {
+  const title = item.title.split("\n", 1)[0]!.trim();
+  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")) {
+      // A blank line stays blank: an indented empty line is trailing whitespace.
+      lines.push(line.trim().length === 0 ? "" : `  ${line}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The id's checkbox line, checked or not: the document is the truth (ADR 0014). */
+function alreadyInboxed(text: string, id: string): boolean {
+  return new RegExp(`^- \\[[ xX]\\] ${escapeRegExp(id)} —`, "m").test(text);
+}
+
+/**
+ * Append a batch to a pod's `## Inbox` (ADR 0014) — reconcile's only write into
+ * a pod's documents (ADR 0008), and only while no wake-up is live (the caller's
+ * gate). Idempotent by document, not by marker: an id that already has a
+ * checkbox line is skipped, so a crash between this write and the claim's
+ * `appended` marker repairs on the next pass instead of duplicating the block.
+ * An older pod without the section gets the heading at EOF on its first append.
+ */
+export async function appendInbox(docsDir: string, items: readonly InboxItem[]): Promise<void> {
+  const file = join(docsDir, "TASKS.md");
+  const existing = await readFile(file, "utf8").catch(() => "");
+  const fresh = items.filter((item) => !alreadyInboxed(existing, item.id));
+  if (fresh.length === 0) return; // a repair pass: the document already has it
+
+  let text = existing.length === 0 ? "# Tasks\n" : existing;
+  if (!/^##\s+Inbox\s*$/m.test(text)) {
+    if (!text.endsWith("\n")) text += "\n";
+    if (!text.endsWith("\n\n")) text += "\n";
+    text += `${INBOX_HEADING}\n`;
+  }
+  if (!text.endsWith("\n")) text += "\n";
+  if (!text.endsWith("\n\n")) text += "\n";
+  text += fresh.map(inboxBlock).join("\n");
+
+  // The registry's atomic write, applied to the one shared file: a crash never
+  // leaves a half-written TASKS.md for the next wake-up to read.
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, text);
+  await rename(tmp, file);
+}