agents-pod 0.2.0 → 0.3.0

package/src/doctor.ts

@@ -0,0 +1,551 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readListeners, type ListenerRecord } from "./listeners.ts";
+import { readLock } from "./locks.ts";
+import { loadNotifyConfig } from "./notify/config.ts";
+import type { NotificationsConfig } from "./notify/types.ts";
+import { readDeliverer, type DelivererRecord } from "./outbox.ts";
+import {
+  lastPassFile,
+  notifyConfigFile,
+  reconcileLockPath,
+  storeRoot,
+} from "./paths.ts";
+import { readPods, type PodRecord } from "./registry.ts";
+import { readSources, type SourceRecord } from "./sources.ts";
+
+/**
+ * Doctor is a read-only Health Report over the store (ADR 0027): what is
+ * missing for a conversation to reach a Pod and a reply to leave one, and the
+ * one command that fixes each gap. It reads records only — never a platform,
+ * never a credential — because ADRs 0024/0025 keep both inside the operator's
+ * commands. It prints; it never writes.
+ */
+export type DoctorMark = "ok" | "bad" | "note";
+
+export interface DoctorLine {
+  mark: DoctorMark;
+  text: string;
+  /** The one command that fixes a `bad` line (ADR 0027). */
+  detail?: string[];
+}
+
+export interface DoctorSection {
+  title: string;
+  lines: DoctorLine[];
+}
+
+export interface DoctorReport {
+  store: string;
+  sections: DoctorSection[];
+  /** Present when nothing is configured: the ordered first run (ADR 0027). */
+  recipe: string[];
+  healthy: boolean;
+}
+
+export interface DoctorOptions {
+  /** `--probe`: run each operator command's `--check` (ADR 0027). Never default. */
+  probe?: boolean;
+  cwd?: string;
+  /** The environment password probes read; defaults to the process's own. */
+  env?: Record<string, string | undefined>;
+  now?: number;
+}
+
+/** A probe's own budget: the delivery and drain budget, unchanged (ADR 0021). */
+const PROBE_TIMEOUT_MS = 10_000;
+/** A command that does not implement `--check` says so with this code (ADR 0027). */
+const NO_SELF_CHECK = 3;
+const PROBE_OUTPUT_CAP = 8 * 1024;
+const PROBE_LINES = 6;
+/** A pass lock older than this is what the next pass steals (ADR 0018). */
+const LOCK_STALE_MS = 5 * 60_000;
+
+export async function doctor(options: DoctorOptions = {}): Promise<DoctorReport> {
+  const now = options.now ?? Date.now();
+  const env = options.env ?? process.env;
+  const root = storeRoot();
+
+  const registry = await readRegistry();
+  const sources = await readSources().catch(() => [] as SourceRecord[]);
+  const listeners = await readListeners();
+  const deliverer = await readDeliverer();
+  const warnings: string[] = [];
+  const notify = await loadNotifyConfig(undefined, (message) => warnings.push(message));
+  const lastPass = await readLastPass();
+
+  const firstRun =
+    sources.length === 0 && deliverer === undefined && notify.channels.length === 0;
+  if (firstRun) {
+    return { store: root, sections: [], recipe: recipeFor(sources, listeners, deliverer, notify, lastPass), healthy: false };
+  }
+
+  const sections: DoctorSection[] = [];
+  const storeLines: DoctorLine[] = [];
+  if (registry.error !== undefined) {
+    storeLines.push({ mark: "bad", text: `pods.json is unreadable: ${registry.error}` });
+  } else {
+    const active = registry.pods.filter((pod) => pod.state === "active").length;
+    storeLines.push({ mark: "ok", text: `${registry.pods.length} pods, ${active} active` });
+  }
+  const lock = await readLock(reconcileLockPath());
+  if (lock !== undefined) {
+    storeLines.push(
+      now - lock.startedAt > LOCK_STALE_MS
+        ? { mark: "note", text: `a pass lock has been held for ${age(now - lock.startedAt)} (the next pass steals it)` }
+        : { mark: "note", text: `a pass is running (pid ${lock.pid})` },
+    );
+  }
+  sections.push({ title: "store", lines: storeLines });
+
+  sections.push({ title: "pass", lines: await passLines(lastPass, now, sources, listeners, registry.pods) });
+  sections.push({ title: "intake", lines: await intakeLines(sources, listeners, now) });
+  sections.push({ title: "listeners", lines: await listenerLines(listeners, sources, registry.pods) });
+  sections.push({ title: "outbound", lines: await outboundLines(deliverer, registry.pods) });
+  sections.push({ title: "notify", lines: notifyLines(notify, warnings, env) });
+
+  if (options.probe) {
+    sections.push({
+      title: "checks",
+      lines: [
+        ...(await probeAll(sources, listeners, deliverer, options.cwd ?? process.cwd(), env)),
+      ],
+    });
+  }
+
+  const recipe = firstRun
+    ? []
+    : recipeFor(sources, listeners, deliverer, notify, lastPass);
+  const healthy = sections.every((section) => section.lines.every((line) => line.mark !== "bad"));
+  return { store: root, sections, recipe, healthy };
+}
+
+async function readRegistry(): Promise<{ pods: PodRecord[]; error?: string }> {
+  try {
+    return { pods: await readPods() };
+  } catch (error) {
+    return { pods: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * The pass marker (ADR 0027) exists because "cron is not installed" and "cron
+ * runs and finds nothing" are the same silence without it.
+ */
+async function readLastPass(): Promise<number | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(lastPassFile(), "utf8"));
+    const at = (parsed as { at?: unknown }).at;
+    return typeof at === "number" ? at : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function passLines(
+  lastPass: number | undefined,
+  now: number,
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  pods: PodRecord[],
+): Promise<DoctorLine[]> {
+  const expected = sources.length > 0 || listeners.length > 0 || pods.length > 0;
+  if (lastPass === undefined) {
+    return [
+      expected
+        ? {
+            mark: "bad",
+            text: "no pass has ever run — nothing is woken, no Source is drained",
+            detail: ["next: crontab -e", "      * * * * * cd <project> && agents-pod reconcile >> ~/.agents/pods/cron.log 2>&1"],
+          }
+        : { mark: "note", text: "no pass has run yet" },
+    ];
+  }
+  return [{ mark: "ok", text: `last pass ${age(now - lastPass)} ago` }];
+}
+
+async function intakeLines(
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  now: number,
+): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  const consumed = new Set(listeners.flatMap((listener) => listener.source ?? []));
+  for (const source of sources) {
+    const consumer = consumed.has(source.name);
+    const executable = await isExecutable(source.cmd);
+    if (!executable) {
+      lines.push({
+        mark: "bad",
+        text: `source ${source.name}: ${source.cmd} is not an executable file`,
+        detail: [
+          `next: agents-pod source rm ${source.name}`,
+          `      agents-pod source add ${source.name} --cmd <path> --timeout ${source.timeoutMs / 1000}`,
+        ],
+      });
+      continue;
+    }
+    const drained =
+      source.lastDrainAt === undefined
+        ? "never drained successfully"
+        : `last success ${age(now - source.lastDrainAt)} ago, ${
+            source.lastDrainItems === undefined
+              ? "yield not recorded"
+              : `${source.lastDrainItems} items`
+          }`;
+    const cursor = source.cursor === undefined ? "no cursor" : `cursor ${source.cursor}`;
+    // A Source that fails every pass is the loudest thing a report can say; the
+    // cursor never moving is otherwise indistinguishable from a quiet chat.
+    if (source.lastError !== undefined) {
+      const failed = source.lastFailureAt === undefined ? "the last drain" : `the last drain (${age(now - source.lastFailureAt)} ago)`;
+      lines.push({
+        mark: "bad",
+        text: `source ${source.name}: ${failed} failed — ${source.lastError}`,
+        detail: [
+          `      ${drained}; ${cursor} (neither moves until a drain succeeds)`,
+          "      run: agents-pod doctor --probe",
+        ],
+      });
+      continue;
+    }
+    if (!consumer) {
+      lines.push({
+        mark: "note",
+        text: `source ${source.name}: ${drained}, ${cursor} — no listener consumes it, so no pass runs it`,
+        detail: ["next: agents-pod listener add --source " + source.name + " --template <file> [--project <dir>]"],
+      });
+      continue;
+    }
+    // Zero items is a quiet chat, not a failure — but it is the exact shape of
+    // "the pull is pointed at nothing", so it never hides (ADR 0027).
+    if (source.lastDrainItems === 0) {
+      lines.push({
+        mark: "note",
+        text: `source ${source.name}: ${drained} — nothing arrives; the command runs, the conversation does not reach it`,
+        detail: [`      ${cursor}; run: agents-pod doctor --probe`],
+      });
+      continue;
+    }
+    lines.push({ mark: "ok", text: `source ${source.name}: ${source.cmd}` });
+    lines.push({ mark: "ok", text: `  ${drained}, ${cursor}` });
+  }
+  if (sources.length === 0) {
+    lines.push({
+      mark: "note",
+      text: "no Source: nothing from outside this machine becomes an Inbox Item",
+      detail: ['next: agents-pod source add <name> --cmd <path> (README "Writing a Source drain")'],
+    });
+  }
+  return lines;
+}
+
+async function listenerLines(
+  listeners: ListenerRecord[],
+  sources: SourceRecord[],
+  pods: PodRecord[],
+): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  for (const listener of listeners) {
+    const problems: string[] = [];
+    const origin =
+      listener.source !== undefined
+        ? `source ${listener.source}`
+        : `inbox ${listener.inbox ?? "(none)"}`;
+    if (listener.source !== undefined && !sources.some((source) => source.name === listener.source)) {
+      problems.push(`its Source ${listener.source} is not registered`);
+    }
+    if (listener.source === undefined && !(await exists(listener.inbox ?? ""))) {
+      problems.push(`its inbox ${listener.inbox ?? "(none)"} does not exist`);
+    }
+    if (listener.mode === "template") {
+      if (!(await exists(listener.template ?? ""))) {
+        problems.push(`its template ${listener.template ?? "(none)"} does not exist`);
+      }
+      if (listener.project !== undefined && !(await exists(listener.project))) {
+        problems.push(`its project ${listener.project} does not exist`);
+      }
+    } else if (!pods.some((pod) => pod.id === listener.podId)) {
+      problems.push(`its Pod ${listener.podId ?? "(none)"} is not in the registry`);
+    }
+    if (problems.length > 0) {
+      lines.push({
+        mark: "bad",
+        text: `${listener.id}: ${problems.join("; ")}`,
+        detail: [`next: agents-pod listener rm ${listener.id}`, "      then add it again with a path that exists"],
+      });
+      continue;
+    }
+    const target =
+      listener.mode === "template" ? `template ${listener.template ?? "(none)"}` : `pod ${listener.podId}`;
+    const project = listener.project !== undefined ? ` → ${listener.project}` : "";
+    lines.push({ mark: "ok", text: `${listener.id}: ${origin} → ${target}${project}` });
+  }
+  if (listeners.length === 0) {
+    lines.push({
+      mark: "note",
+      text: "no Listener: a Source is drained only for a Listener that consumes it",
+      detail: ["next: agents-pod listener add --source <name> --template <file> [--project <dir>]"],
+    });
+  }
+  return lines;
+}
+
+async function outboundLines(deliverer: DelivererRecord | undefined, pods: PodRecord[]): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  const { pending, dead } = await outboxFacts(pods);
+  if (deliverer === undefined) {
+    lines.push({
+      mark: "bad",
+      text:
+        pending > 0
+          ? `no deliverer: ${pending} entries in Pod outboxes are never sent`
+          : "no deliverer: a Pod's outbox is never sent",
+      detail: [
+        "next: agents-pod deliver add <name> --cmd <path> --timeout <s>",
+        "      the command owns the platform credentials (ADR 0025)",
+      ],
+    });
+  } else if (!(await isExecutable(deliverer.cmd))) {
+    lines.push({
+      mark: "bad",
+      text: `deliverer ${deliverer.name}: ${deliverer.cmd} is not an executable file`,
+      detail: [`next: agents-pod deliver rm ${deliverer.name}, then deliver add with a real path`],
+    });
+  } else {
+    lines.push({ mark: "ok", text: `deliverer ${deliverer.name}: ${deliverer.cmd}` });
+  }
+  if (pending > 0) lines.push({ mark: "note", text: `${pending} entries waiting in Pod outboxes` });
+  if (dead > 0) {
+    lines.push({
+      mark: "note",
+      text: `${dead} dead entries retained (older than an hour or malformed; kept, never retried)`,
+    });
+  }
+  return lines;
+}
+
+/** Outbox entries are facts of the Pod's workspace, not of the registry (ADR 0025). */
+async function outboxFacts(pods: PodRecord[]): Promise<{ pending: number; dead: number }> {
+  let pending = 0;
+  let dead = 0;
+  for (const pod of pods) {
+    const dir = join(pod.project, ".agents", "pods", pod.id, "outbox");
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (name.endsWith(".dead")) dead += 1;
+      else if (name.endsWith(".json")) pending += 1;
+    }
+  }
+  return { pending, dead };
+}
+
+function notifyLines(
+  notify: NotificationsConfig,
+  warnings: string[],
+  env: Record<string, string | undefined>,
+): DoctorLine[] {
+  const lines: DoctorLine[] = warnings.map((warning) => ({ mark: "bad" as const, text: warning }));
+  if (notify.channels.length === 0) {
+    lines.push({
+      mark: "note",
+      text: "no notification channels: parks and dones stay silent",
+      detail: [`next: add channels to ${notifyConfigFile()} (README "Notifications")`],
+    });
+    return lines;
+  }
+  lines.push({ mark: "ok", text: `${notify.channels.length} channels (on: ${notify.on})` });
+  if (notify.on === "never") {
+    lines.push({ mark: "note", text: "notifications.on is never: every channel is ignored" });
+  }
+  for (const channel of notify.channels) {
+    if (channel.type !== "email" || channel.user === undefined) continue;
+    const passwordEnv = channel.passwordEnv ?? "AGENTS_POD_SMTP_PASSWORD";
+    if (!env[passwordEnv]) {
+      lines.push({
+        mark: "bad",
+        text: `channel ${channel.id}: ${passwordEnv} is not set in this environment`,
+        detail: ["      an authenticated SMTP send will fail; core reads no credentials (ADR 0021)"],
+      });
+    }
+  }
+  return lines;
+}
+
+/**
+ * `--check` is the only way core can learn about a credential it must not hold
+ * (ADR 0027): exit 0 healthy, exit 3 no self-check, anything else unhealthy
+ * with the command's own words quoted.
+ */
+async function probeAll(
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  deliverer: DelivererRecord | undefined,
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<DoctorLine[]> {
+  const lines: DoctorLine[] = [];
+  const consumed = new Set(listeners.flatMap((listener) => listener.source ?? []));
+  for (const source of sources) {
+    lines.push(
+      ...(await trace(`source ${source.name}`, source.cmd, {
+        ...env,
+        AGENTS_POD_SOURCE_ID: source.name,
+        AGENTS_POD_CURSOR: source.cursor ?? "",
+      }, cwd)),
+    );
+    if (!consumed.has(source.name)) {
+      lines.push({ mark: "note", text: `source ${source.name}: no listener consumes it, so no pass runs it` });
+    }
+  }
+  if (deliverer !== undefined) {
+    lines.push(...(await trace(`deliverer ${deliverer.name}`, deliverer.cmd, env, cwd)));
+  }
+  if (lines.length === 0) {
+    lines.push({ mark: "note", text: "nothing to probe: no Source and no deliverer configured" });
+  }
+  return lines;
+}
+
+async function trace(
+  label: string,
+  cmd: string,
+  env: Record<string, string | undefined>,
+  cwd: string,
+): Promise<DoctorLine[]> {
+  if (!(await isExecutable(cmd))) {
+    return [{ mark: "bad", text: `${label}: ${cmd} is not an executable file` }];
+  }
+  const { code, signal, text } = await runCheck(cmd, env, cwd);
+  const quoted = text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .slice(0, PROBE_LINES)
+    .map((line) => `      ${line}`);
+  if (code === 0) {
+    return [{ mark: "ok", text: `${label}: self-check passed`, ...(quoted.length ? { detail: quoted } : {}) }];
+  }
+  if (code === NO_SELF_CHECK) {
+    return [
+      {
+        mark: "note",
+        text: `${label}: no self-check (exit ${NO_SELF_CHECK}) — core cannot verify anything it owns`,
+        detail: ["      add `--check` to the command (exit 0 healthy, 3 unsupported) to have it verified here"],
+      },
+    ];
+  }
+  const why = signal !== null ? `terminated by ${signal}` : `exit ${code ?? "unknown"}`;
+  return [
+    { mark: "bad", text: `${label}: self-check failed (${why})`, detail: quoted.length ? quoted : undefined },
+  ];
+}
+
+function runCheck(
+  cmd: string,
+  env: Record<string, string | undefined>,
+  cwd: string,
+): Promise<{ code: number | null; signal: NodeJS.Signals | null; text: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, ["--check"], { cwd, env: env as NodeJS.ProcessEnv, detached: true });
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    const collect = (chunk: Buffer): void => {
+      if (bytes >= PROBE_OUTPUT_CAP) return;
+      bytes += chunk.length;
+      chunks.push(chunk);
+    };
+    const timer = setTimeout(() => {
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    }, PROBE_TIMEOUT_MS);
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ code: null, signal: null, text: error.message });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, text: Buffer.concat(chunks).toString("utf8") });
+    });
+  });
+}
+
+/**
+ * The first run, in order (ADR 0027): each line is one command, and the last
+ * one is the report that says every line is `✓`.
+ */
+function recipeFor(
+  sources: SourceRecord[],
+  listeners: ListenerRecord[],
+  deliverer: DelivererRecord | undefined,
+  notify: NotificationsConfig,
+  lastPass: number | undefined,
+): string[] {
+  const steps: string[][] = [];
+  if (sources.length === 0) {
+    steps.push([
+      'write a Source command: one JSONL item per message, then {"cursor":"…"}',
+      '   README "Writing a Source drain"; a worked Feishu pair: examples/feishu/',
+      "   agents-pod source add <name> --cmd <path> --timeout <s>",
+    ]);
+  }
+  if (listeners.length === 0) {
+    steps.push(["agents-pod listener add --source <name> --template <file> [--project <dir>]"]);
+  }
+  if (deliverer === undefined) {
+    steps.push(["agents-pod deliver add <name> --cmd <path> --timeout <s>"]);
+  }
+  if (notify.channels.length === 0) {
+    steps.push([`add notification channels to ${notifyConfigFile()} (README "Notifications")`]);
+  }
+  if (lastPass === undefined) {
+    steps.push([
+      "crontab: * * * * * cd <project> && agents-pod reconcile >> ~/.agents/pods/cron.log 2>&1",
+    ]);
+  }
+  steps.push(["agents-pod doctor --probe — until every line is ✓"]);
+  return steps.flatMap((lines, index) =>
+    lines.map((line, position) => (position === 0 ? `${index + 1}. ${line}` : `   ${line}`)),
+  );
+}
+
+async function exists(path: string): Promise<boolean> {
+  if (!path) return false;
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isExecutable(path: string): Promise<boolean> {
+  if (!path) return false;
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return false;
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Ages are read at a glance: seconds, minutes, hours, days, never an epoch. */
+function age(ms: number): string {
+  if (ms < 60_000) return `${Math.max(0, Math.round(ms / 1000))}s`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m`;
+  if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)}h`;
+  return `${Math.round(ms / 86_400_000)}d`;
+}

package/src/paths.ts

@@ -56,6 +56,11 @@ export function notifyConfigFile(): string {
   return join(storeRoot(), "config.json");
 }
 
+/** When the last pass finished (ADR 0027): "no pass ever ran" is its own fact. */
+export function lastPassFile(): string {
+  return join(storeRoot(), "last-pass.json");
+}
+
 /** The short-lived registry mutex that makes state transitions CAS (ADR 0017, 0018). */
 export function registryLockPath(): string {
   return join(storeRoot(), "registry.lock");

package/src/sources.ts

@@ -14,6 +14,14 @@ export interface SourceRecord {
   cursor?: string;
   /** The previous successful drain is the claim-retention horizon (ADR 0024). */
   lastDrainAt?: number;
+  /**
+   * That drain's yield (ADR 0027): zero is a fact, not a gap — a pull that runs
+   * and delivers nothing is the shape of a conversation that never reaches it.
+   */
+  lastDrainItems?: number;
+  /** A failed drain's fact (ADR 0027): a report cannot say `ok` while every pass fails. */
+  lastFailureAt?: number;
+  lastError?: string;
 }
 
 export interface SourceDrain {
@@ -273,6 +281,32 @@ export async function commitSourceCursors(drained: SourceDrain[]): Promise<void>
       source.lastDrainAt = drain.drainedAt;
       changed = true;
     }
+    // The yield is recorded even when it is zero (ADR 0027): doctor reports a
+    // silent pull only because the count exists.
+    if (source.lastDrainItems !== drain.items.length) {
+      source.lastDrainItems = drain.items.length;
+      changed = true;
+    }
+    // A success clears the failure it disproved (ADR 0027).
+    if (source.lastError !== undefined) {
+      delete source.lastError;
+      delete source.lastFailureAt;
+      changed = true;
+    }
   }
   if (changed) await writeSources(sources);
 }
+
+/**
+ * A failed drain leaves the cursor and the yield alone, so its only trace is a
+ * `cron.log` line — invisible to anyone not tailing the log. The record keeps
+ * the fact for the report (ADR 0027), and a later success clears it.
+ */
+export async function recordSourceFailure(name: string, error: string): Promise<void> {
+  const sources = await readSources();
+  const source = sources.find((candidate) => candidate.name === name);
+  if (source === undefined) return;
+  source.lastFailureAt = Date.now();
+  source.lastError = error;
+  await writeSources(sources);
+}