agents-pod 0.0.0-stage → 0.2.0

package/src/notify/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Pod notifications: the second adapter family, copied from agents-cron
+ * (ADR 0021). Notifiers own "how a pod moment is announced"; reconcile owns
+ * "when". The inventory is two events only — park and done.
+ */
+
+/** Identifies one configured channel — the `id` of a `channels[]` entry. */
+export type ChannelId = string;
+
+/** Posts the moment to an HTTP endpoint (Slack, Lark, Discord, n8n, …). */
+export type WebhookChannel = {
+  id: string;
+  type: "webhook";
+  url: string;
+  /** Extra request headers, e.g. `{"Authorization": "Bearer …"}`. */
+  headers?: Record<string, string>;
+  /** json (default) posts the raw notification; text posts plain text; feishu posts the Feishu bot body. */
+  format?: "json" | "text" | "feishu";
+};
+
+/** Sends the moment as an email over SMTP. */
+export type EmailChannel = {
+  id: string;
+  type: "email";
+  host: string;
+  /** Defaults to 465. */
+  port?: number;
+  /** Defaults to true when the port is 465, false otherwise. */
+  secure?: boolean;
+  /** SMTP user; omit for an unauthenticated relay. */
+  user?: string;
+  /** Env var holding the SMTP password; defaults to AGENTS_POD_SMTP_PASSWORD. */
+  passwordEnv?: string;
+  from: string;
+  /** Comma-separated recipient list. */
+  to: string;
+  subjectPrefix?: string;
+};
+
+/** Shows the moment as a desktop notification (macOS Notification Center, Linux notify-send). */
+export type SystemChannel = {
+  id: string;
+  type: "system";
+  /** macOS sound name (Glass, Ping, …); ignored on Linux. */
+  sound?: string;
+};
+
+export type NotificationChannel = WebhookChannel | EmailChannel | SystemChannel;
+
+/**
+ * Which pod moments produce a notification (ADR 0021): `error` means park
+ * only, `always` means park + done, `never` means nothing. Default `always` —
+ * for work measured in days, completion is the product.
+ */
+export type NotifyLevel = "always" | "error" | "never";
+
+/** The full inventory: two events, no more. */
+export type NotificationEvent = "park" | "done";
+
+export type NotificationsConfig = {
+  on: NotifyLevel;
+  channels: NotificationChannel[];
+};
+
+/** One failure in the consecutive run that provoked a park (ADR 0009 detail). */
+export type FailureLine = {
+  n: number;
+  outcome: string;
+  detail?: string;
+};
+
+/**
+ * A pod moment shaped for delivery. Park carries the verdict (pod id, goal
+ * first line, the consecutive failures with their details); done carries the
+ * handoff's status line (ADR 0021).
+ */
+export type PodNotification = {
+  event: NotificationEvent;
+  podId: string;
+  /** The goal's first line — the one-line handle (ADR 0011). */
+  goal: string;
+  /** park: consecutive failures at the verdict. */
+  consecutiveFailures?: number;
+  /** park: each failure with its ADR 0009 detail. */
+  failures?: FailureLine[];
+  /** park: a non-streak cause, e.g. agent resolution failure (ADR 0012). */
+  reason?: string;
+  /** done: the handoff's status line. */
+  handoffStatus?: string;
+};
+
+/** One delivery channel, resolved and ready to send. */
+export type Notifier = {
+  readonly id: string;
+  send(notification: PodNotification): Promise<void>;
+};

package/src/notify/webhook.ts

@@ -0,0 +1,39 @@
+import { bodyOf, subjectOf } from "./format.ts";
+import type { Notifier, PodNotification, WebhookChannel } from "./types.ts";
+
+/** Delivery budget per channel; a hung endpoint must not stall a pass (ADR 0021). */
+const TIMEOUT_MS = 10_000;
+
+export function webhookNotifier(channel: WebhookChannel): Notifier {
+  return {
+    id: channel.id,
+    async send(n: PodNotification): Promise<void> {
+      const body =
+        channel.format === "feishu"
+          ? JSON.stringify({ msg_type: "text", content: { text: `${subjectOf(n)}\n\n${bodyOf(n)}` } })
+          : channel.format === "text"
+            ? `${subjectOf(n)}\n\n${bodyOf(n)}`
+            : JSON.stringify({ source: "agents-pod", ...n }, null, 2);
+      const res = await fetch(channel.url, {
+        method: "POST",
+        headers: {
+          "content-type": channel.format === "text" ? "text/plain; charset=utf-8" : "application/json",
+          ...(channel.headers ?? {}),
+        },
+        body,
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+      if (!res.ok) throw new Error(`webhook answered HTTP ${res.status}`);
+      if (channel.format === "feishu") {
+        // Feishu answers HTTP 200 even for business errors (bad keyword,
+        // wrong format); a non-zero code means the bot never delivered.
+        const answer = (await res.json().catch(() => undefined)) as { code?: number; msg?: string } | undefined;
+        // Only an explicit non-zero code is a rejection; endpoints that answer
+        // nothing (or Feishu-compatible servers without a body) stay OK.
+        if (typeof answer?.code === "number" && answer.code !== 0) {
+          throw new Error(`feishu webhook rejected the message: ${answer.code} ${answer.msg ?? ""}`.trim());
+        }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,67 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * The machine-global store root: `$AGENTS_POD_HOME ?? $HOME` + `.agents/pods/`.
+ * The env override exists for the same reason agents-cron's does: tests and
+ * secondary installs need a throwaway root without touching the real store
+ * (ADR 0004: own store, never shared with agents-cron).
+ */
+export function storeRoot(): string {
+  const home = process.env.AGENTS_POD_HOME ?? homedir();
+  return join(home, ".agents", "pods");
+}
+
+export function podsFile(): string {
+  return join(storeRoot(), "pods.json");
+}
+
+/** Per-project wake-up capacity (ADR 0022), machine-global like the Pod registry. */
+export function projectsFile(): string {
+  return join(storeRoot(), "projects.json");
+}
+
+/** The one definition source in P0 (ADR 0012): machine-global, no project layer. */
+export function agentsFile(): string {
+  return join(storeRoot(), "agents.json");
+}
+
+/** Listeners and their claim records: intake is data, never a process (ADR 0007). */
+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");
+}
+
+/** Where a stolen lock is audited: one line per steal, read by cron (ADR 0018). */
+export function cronLogPath(): string {
+  return join(storeRoot(), "cron.log");
+}
+
+/** The one notification config, in the store root (ADR 0021): no per-pod routing. */
+export function notifyConfigFile(): string {
+  return join(storeRoot(), "config.json");
+}
+
+/** The short-lived registry mutex that makes state transitions CAS (ADR 0017, 0018). */
+export function registryLockPath(): string {
+  return join(storeRoot(), "registry.lock");
+}
+
+/** The pod's working tree lives under the project (ADR 0004): docs, log, wake-ups. */
+export function podDir(project: string, podId: string): string {
+  return join(project, ".agents", "pods", podId);
+}

package/src/projects.ts

@@ -0,0 +1,49 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { projectsFile } from "./paths.ts";
+import type { PodRecord } from "./registry.ts";
+
+/** One project's wake-up capacity; absent records mean unlimited (ADR 0022). */
+export interface ProjectRecord {
+  project: string;
+  maxActive: number;
+}
+
+export async function readProjects(): Promise<ProjectRecord[]> {
+  try {
+    return JSON.parse(await readFile(projectsFile(), "utf8")) as ProjectRecord[];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export async function writeProjects(projects: ProjectRecord[]): Promise<void> {
+  const file = projectsFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(projects, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+export function projectMaxActive(project: string, projects: ProjectRecord[]): number | undefined {
+  const root = resolve(project);
+  return projects.find((candidate) => resolve(candidate.project) === root)?.maxActive;
+}
+
+/** Spawning and active are the two states with a live Wake-up being admitted. */
+export function projectHasCapacity(
+  project: string,
+  pods: PodRecord[],
+  projects: ProjectRecord[],
+): boolean {
+  const maxActive = projectMaxActive(project, projects);
+  if (maxActive === undefined) return true;
+  const root = resolve(project);
+  const active = pods.filter(
+    (pod) =>
+      resolve(pod.project) === root && (pod.state === "spawning" || pod.state === "active"),
+  ).length;
+  return active < maxActive;
+}

package/src/registry.ts

@@ -0,0 +1,103 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { acquireWithRetry, releaseLock } from "./locks.ts";
+import { podsFile, registryLockPath } from "./paths.ts";
+
+/**
+ * Pod states (ADR 0006): spawning / active / idle / done / cancelled. `lost`
+ * and `cancelled` are wake-up outcomes, never pod states.
+ */
+export type PodState = "spawning" | "active" | "idle" | "done" | "cancelled";
+
+export type WakeUpOutcome = "more" | "done" | "failed" | "lost" | "cancelled";
+
+export interface WakeUpEntry {
+  n: number;
+  outcome: WakeUpOutcome;
+  detail?: string;
+}
+
+export interface PodRecord {
+  id: string;
+  goal: string;
+  state: PodState;
+  /** The project root the pod's workspace lives under. */
+  project: string;
+  /** The upstream Pod whose done state admits this Pod's first wake-up (ADR 0022). */
+  after?: string;
+  wakeUps: WakeUpEntry[];
+  policy?: WakePolicy;
+  /** When a pass first observed a wedged wrapper (ADR 0017's two-pass rule). */
+  wedgedAt?: number;
+  /**
+   * Reconcile's progress-kill intent (ADR 0019): written under the registry
+   * lock before the signal, so the verdict is on disk before it is acted on.
+   */
+  /** A reconcile kill's intent, written before the signal (ADRs 0017, 0019): the
+ * wrapper defers to the verdict and records no second outcome. */
+  killIntent?: { n: number; at: number; cause: "progressless" | "wedged" };
+  /**
+   * When this episode's notification was sent (ADR 0021). A human wake that
+   * clears a park also clears it, opening the next episode.
+   */
+  notifiedAt?: number;
+}
+
+/** The policy block reconcile derives from outcome facts (ADR 0011). */
+export interface WakePolicy {
+  failureStreak: number;
+  nextWakeAt?: number;
+  parked?: boolean;
+  /** How many wake-up outcomes the policy has already taken into account. */
+  appliedOutcomes: number;
+  /** The agent every wake-up resolves to unless one wake names another (ADR 0012). */
+  agent?: string;
+  /** The pod's model pin: it beats the definition's model (ADR 0012). */
+  model?: string;
+}
+
+export async function readPods(): Promise<PodRecord[]> {
+  try {
+    return JSON.parse(await readFile(podsFile(), "utf8")) as PodRecord[];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/**
+ * Atomic write: a crash mid-write never leaves a half-written registry. The
+ * temp name is unique per writer — the CLI and a detached wrapper both write
+ * this file, and a shared temp name let one rename steal the other's file.
+ */
+export async function writePods(pods: PodRecord[]): Promise<void> {
+  const file = podsFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(pods, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+/**
+ * The registry mutex (ADR 0017's lock budget, ADR 0018's division of labour):
+ * a state transition re-reads pods.json inside it, verifies its condition
+ * still holds, then writes — the pass lock only keeps one pass around, this is
+ * what makes two racers (two passes, or a human and a pass) unable to both
+ * win. `undefined` means the lock could not be had: callers skip, never write
+ * blind.
+ */
+export async function withRegistryLock<T>(
+  work: () => Promise<T>,
+): Promise<T | undefined> {
+  const held = await acquireWithRetry(registryLockPath(), {
+    pid: process.pid,
+    startedAt: Date.now(),
+  });
+  if (!held) return undefined;
+  try {
+    return await work();
+  } finally {
+    await releaseLock(registryLockPath());
+  }
+}