agents-pod 0.0.0-stage → 0.1.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/paths.ts

@@ -0,0 +1,57 @@
+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");
+}
+
+/** 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());
+  }
+}

package/src/workspace.ts

@@ -0,0 +1,124 @@
+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 { 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", "", "## 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 });
+  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">): string {
+  const title = item.title.split("\n", 1)[0]!.trim();
+  const lines = [`- [ ] ${item.id} — ${title}`];
+  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);
+}