agentflow-core 0.2.3 → 0.3.1

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   loadGraph: () => loadGraph,
   runTraced: () => runTraced,
   startLive: () => startLive,
+  startWatch: () => startWatch,
   stitchTrace: () => stitchTrace
 });
 module.exports = __toCommonJS(index_exports);
@@ -1214,6 +1215,522 @@ function startLive(argv) {
     process.exit(0);
   });
 }
+
+// src/watch.ts
+var import_node_fs4 = require("fs");
+var import_node_path3 = require("path");
+var import_node_os = require("os");
+
+// src/watch-state.ts
+var import_node_fs3 = require("fs");
+function parseDuration(input) {
+  const match = input.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i);
+  if (!match) {
+    const n = parseInt(input, 10);
+    return isNaN(n) ? 0 : n * 1e3;
+  }
+  const value = parseFloat(match[1]);
+  switch (match[2].toLowerCase()) {
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 6e4;
+    case "h":
+      return value * 36e5;
+    case "d":
+      return value * 864e5;
+    default:
+      return value * 1e3;
+  }
+}
+function emptyState() {
+  return { version: 1, agents: {}, lastPollTime: 0 };
+}
+function loadWatchState(filePath) {
+  if (!(0, import_node_fs3.existsSync)(filePath)) return emptyState();
+  try {
+    const raw = JSON.parse((0, import_node_fs3.readFileSync)(filePath, "utf8"));
+    if (raw.version !== 1 || typeof raw.agents !== "object") return emptyState();
+    return raw;
+  } catch {
+    return emptyState();
+  }
+}
+function saveWatchState(filePath, state) {
+  const tmp = filePath + ".tmp";
+  try {
+    (0, import_node_fs3.writeFileSync)(tmp, JSON.stringify(state, null, 2), "utf8");
+    (0, import_node_fs3.renameSync)(tmp, filePath);
+  } catch {
+    try {
+      (0, import_node_fs3.writeFileSync)(filePath, JSON.stringify(state, null, 2), "utf8");
+    } catch {
+    }
+  }
+}
+function estimateInterval(history) {
+  if (history.length < 3) return 0;
+  const sorted = [...history].sort((a, b) => a - b);
+  const deltas = [];
+  for (let i = 1; i < sorted.length; i++) {
+    const d = sorted[i] - sorted[i - 1];
+    if (d > 0) deltas.push(d);
+  }
+  if (deltas.length === 0) return 0;
+  deltas.sort((a, b) => a - b);
+  return deltas[Math.floor(deltas.length / 2)];
+}
+function detectTransitions(previous, currentRecords, config, now) {
+  const alerts = [];
+  const hasError = config.alertConditions.some((c) => c.type === "error");
+  const hasRecovery = config.alertConditions.some((c) => c.type === "recovery");
+  const staleConditions = config.alertConditions.filter((c) => c.type === "stale");
+  const consecutiveConditions = config.alertConditions.filter((c) => c.type === "consecutive-errors");
+  const byAgent = /* @__PURE__ */ new Map();
+  for (const r of currentRecords) {
+    const existing = byAgent.get(r.id);
+    if (!existing || r.lastActive > existing.lastActive) {
+      byAgent.set(r.id, r);
+    }
+  }
+  for (const [agentId, record] of byAgent) {
+    const prev = previous.agents[agentId];
+    const prevStatus = prev?.lastStatus ?? "unknown";
+    const currStatus = record.status;
+    if (hasError && currStatus === "error" && prevStatus !== "error") {
+      if (canAlert(prev, "error", config.cooldownMs, now)) {
+        alerts.push(makePayload(agentId, "error", prevStatus, currStatus, record, config.dirs));
+      }
+    }
+    if (hasRecovery && currStatus === "ok" && prevStatus === "error") {
+      alerts.push(makePayload(agentId, "recovery", prevStatus, currStatus, record, config.dirs));
+    }
+    const newConsec = currStatus === "error" ? (prev?.consecutiveErrors ?? 0) + 1 : 0;
+    for (const cond of consecutiveConditions) {
+      if (newConsec === cond.threshold) {
+        if (canAlert(prev, `consecutive-errors:${cond.threshold}`, config.cooldownMs, now)) {
+          alerts.push(makePayload(
+            agentId,
+            `consecutive-errors (${cond.threshold})`,
+            prevStatus,
+            currStatus,
+            { ...record, detail: `${newConsec} consecutive errors. ${record.detail}` },
+            config.dirs
+          ));
+        }
+      }
+    }
+    for (const cond of staleConditions) {
+      const sinceActive = now - record.lastActive;
+      if (sinceActive > cond.durationMs && record.lastActive > 0) {
+        if (canAlert(prev, "stale", config.cooldownMs, now)) {
+          const mins = Math.floor(sinceActive / 6e4);
+          alerts.push(makePayload(
+            agentId,
+            "stale",
+            prevStatus,
+            currStatus,
+            { ...record, detail: `No update for ${mins}m. ${record.detail}` },
+            config.dirs
+          ));
+        }
+      }
+    }
+    if (staleConditions.length === 0) {
+      const history = prev?.mtimeHistory ?? [];
+      const expectedInterval = estimateInterval(history);
+      if (expectedInterval > 0) {
+        const sinceActive = now - record.lastActive;
+        if (sinceActive > expectedInterval * 3) {
+          if (canAlert(prev, "stale-auto", config.cooldownMs, now)) {
+            const mins = Math.floor(sinceActive / 6e4);
+            const expectedMins = Math.floor(expectedInterval / 6e4);
+            alerts.push(makePayload(
+              agentId,
+              "stale (auto)",
+              prevStatus,
+              currStatus,
+              { ...record, detail: `No update for ${mins}m (expected every ~${expectedMins}m). ${record.detail}` },
+              config.dirs
+            ));
+          }
+        }
+      }
+    }
+  }
+  return alerts;
+}
+function updateWatchState(state, records, alerts, now) {
+  const agents = { ...state.agents };
+  const alertsByAgent = /* @__PURE__ */ new Map();
+  for (const a of alerts) alertsByAgent.set(a.agentId, a);
+  const byAgent = /* @__PURE__ */ new Map();
+  for (const r of records) {
+    const existing = byAgent.get(r.id);
+    if (!existing || r.lastActive > existing.lastActive) {
+      byAgent.set(r.id, r);
+    }
+  }
+  for (const [agentId, record] of byAgent) {
+    const prev = agents[agentId];
+    const history = prev?.mtimeHistory ?? [];
+    const newHistory = [...history];
+    if (newHistory.length === 0 || newHistory[newHistory.length - 1] !== record.lastActive) {
+      newHistory.push(record.lastActive);
+    }
+    while (newHistory.length > 10) newHistory.shift();
+    const alert = alertsByAgent.get(agentId);
+    const consecutiveErrors = record.status === "error" ? (prev?.consecutiveErrors ?? 0) + 1 : 0;
+    agents[agentId] = {
+      id: agentId,
+      lastStatus: record.status,
+      lastActive: record.lastActive,
+      lastAlertTime: alert ? now : prev?.lastAlertTime ?? 0,
+      lastAlertReason: alert ? alert.condition : prev?.lastAlertReason ?? "",
+      consecutiveErrors,
+      mtimeHistory: newHistory
+    };
+  }
+  return { version: 1, agents, lastPollTime: now };
+}
+function canAlert(prev, reason, cooldownMs, now) {
+  if (!prev) return true;
+  if (prev.lastAlertReason !== reason) return true;
+  return now - prev.lastAlertTime > cooldownMs;
+}
+function makePayload(agentId, condition, previousStatus, currentStatus, record, dirs) {
+  return {
+    agentId,
+    condition,
+    previousStatus,
+    currentStatus,
+    detail: record.detail,
+    file: record.file,
+    timestamp: Date.now(),
+    dirs
+  };
+}
+
+// src/watch-alerts.ts
+var import_node_https = require("https");
+var import_node_http = require("http");
+var import_node_child_process2 = require("child_process");
+function formatAlertMessage(payload) {
+  const time = new Date(payload.timestamp).toISOString();
+  const arrow = `${payload.previousStatus} \u2192 ${payload.currentStatus}`;
+  return [
+    `[ALERT] ${payload.condition}: "${payload.agentId}"`,
+    `  Status:  ${arrow}`,
+    payload.detail ? `  Detail:  ${payload.detail}` : null,
+    `  File:    ${payload.file}`,
+    `  Time:    ${time}`
+  ].filter(Boolean).join("\n");
+}
+function formatTelegram(payload) {
+  const icon = payload.condition === "recovery" ? "\u2705" : "\u26A0\uFE0F";
+  const time = new Date(payload.timestamp).toLocaleTimeString();
+  return [
+    `${icon} *AgentFlow Alert*`,
+    `*${payload.condition}*: \`${payload.agentId}\``,
+    `Status: ${payload.previousStatus} \u2192 ${payload.currentStatus}`,
+    payload.detail ? `Detail: ${payload.detail.slice(0, 200)}` : null,
+    `Time: ${time}`
+  ].filter(Boolean).join("\n");
+}
+async function sendAlert(payload, channel) {
+  try {
+    switch (channel.type) {
+      case "stdout":
+        sendStdout(payload);
+        break;
+      case "telegram":
+        await sendTelegram(payload, channel.botToken, channel.chatId);
+        break;
+      case "webhook":
+        await sendWebhook(payload, channel.url);
+        break;
+      case "command":
+        await sendCommand(payload, channel.cmd);
+        break;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[agentflow] Failed to send ${channel.type} alert: ${msg}`);
+  }
+}
+function sendStdout(payload) {
+  console.log(formatAlertMessage(payload));
+}
+function sendTelegram(payload, botToken, chatId) {
+  const body = JSON.stringify({
+    chat_id: chatId,
+    text: formatTelegram(payload),
+    parse_mode: "Markdown"
+  });
+  return new Promise((resolve4, reject) => {
+    const req = (0, import_node_https.request)(
+      `https://api.telegram.org/bot${botToken}/sendMessage`,
+      { method: "POST", headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) } },
+      (res) => {
+        res.resume();
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve4();
+        else reject(new Error(`Telegram API returned ${res.statusCode}`));
+      }
+    );
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+function sendWebhook(payload, url) {
+  const body = JSON.stringify(payload);
+  const isHttps = url.startsWith("https");
+  const doRequest = isHttps ? import_node_https.request : import_node_http.request;
+  return new Promise((resolve4, reject) => {
+    const req = doRequest(
+      url,
+      { method: "POST", headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) } },
+      (res) => {
+        res.resume();
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve4();
+        else reject(new Error(`Webhook returned ${res.statusCode}`));
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(1e4, () => {
+      req.destroy(new Error("Webhook timeout"));
+    });
+    req.write(body);
+    req.end();
+  });
+}
+function sendCommand(payload, cmd) {
+  return new Promise((resolve4, reject) => {
+    const env = {
+      ...process.env,
+      AGENTFLOW_ALERT_AGENT: payload.agentId,
+      AGENTFLOW_ALERT_CONDITION: payload.condition,
+      AGENTFLOW_ALERT_STATUS: payload.currentStatus,
+      AGENTFLOW_ALERT_PREVIOUS_STATUS: payload.previousStatus,
+      AGENTFLOW_ALERT_DETAIL: payload.detail,
+      AGENTFLOW_ALERT_FILE: payload.file,
+      AGENTFLOW_ALERT_TIMESTAMP: String(payload.timestamp)
+    };
+    (0, import_node_child_process2.exec)(cmd, { env, timeout: 3e4 }, (err) => {
+      if (err) reject(err);
+      else resolve4();
+    });
+  });
+}
+
+// src/watch.ts
+function parseWatchArgs(argv) {
+  const dirs = [];
+  const alertConditions = [];
+  const notifyChannels = [];
+  let recursive = false;
+  let pollIntervalMs = 3e4;
+  let cooldownMs = 30 * 6e4;
+  let stateFilePath = "";
+  const args = argv.slice(0);
+  if (args[0] === "watch") args.shift();
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      printWatchUsage();
+      process.exit(0);
+    } else if (arg === "--alert-on") {
+      i++;
+      const val = args[i] ?? "";
+      if (val === "error") {
+        alertConditions.push({ type: "error" });
+      } else if (val === "recovery") {
+        alertConditions.push({ type: "recovery" });
+      } else if (val.startsWith("stale:")) {
+        const dur = parseDuration(val.slice(6));
+        if (dur > 0) alertConditions.push({ type: "stale", durationMs: dur });
+      } else if (val.startsWith("consecutive-errors:")) {
+        const n = parseInt(val.slice(19), 10);
+        if (n > 0) alertConditions.push({ type: "consecutive-errors", threshold: n });
+      }
+      i++;
+    } else if (arg === "--notify") {
+      i++;
+      const val = args[i] ?? "";
+      if (val === "telegram") {
+        const botToken = process.env["AGENTFLOW_TELEGRAM_BOT_TOKEN"] ?? "";
+        const chatId = process.env["AGENTFLOW_TELEGRAM_CHAT_ID"] ?? "";
+        if (botToken && chatId) {
+          notifyChannels.push({ type: "telegram", botToken, chatId });
+        } else {
+          console.error("Warning: --notify telegram requires AGENTFLOW_TELEGRAM_BOT_TOKEN and AGENTFLOW_TELEGRAM_CHAT_ID env vars");
+        }
+      } else if (val.startsWith("webhook:")) {
+        notifyChannels.push({ type: "webhook", url: val.slice(8) });
+      } else if (val.startsWith("command:")) {
+        notifyChannels.push({ type: "command", cmd: val.slice(8) });
+      }
+      i++;
+    } else if (arg === "--poll") {
+      i++;
+      const v = parseInt(args[i] ?? "", 10);
+      if (!isNaN(v) && v > 0) pollIntervalMs = v * 1e3;
+      i++;
+    } else if (arg === "--cooldown") {
+      i++;
+      const dur = parseDuration(args[i] ?? "30m");
+      if (dur > 0) cooldownMs = dur;
+      i++;
+    } else if (arg === "--state-file") {
+      i++;
+      stateFilePath = args[i] ?? "";
+      i++;
+    } else if (arg === "--recursive" || arg === "-R") {
+      recursive = true;
+      i++;
+    } else if (!arg.startsWith("-")) {
+      dirs.push((0, import_node_path3.resolve)(arg));
+      i++;
+    } else {
+      i++;
+    }
+  }
+  if (dirs.length === 0) dirs.push((0, import_node_path3.resolve)("."));
+  if (alertConditions.length === 0) {
+    alertConditions.push({ type: "error" });
+    alertConditions.push({ type: "recovery" });
+  }
+  notifyChannels.unshift({ type: "stdout" });
+  if (!stateFilePath) {
+    stateFilePath = (0, import_node_path3.join)(dirs[0], ".agentflow-watch-state.json");
+  }
+  return {
+    dirs,
+    recursive,
+    pollIntervalMs,
+    alertConditions,
+    notifyChannels,
+    stateFilePath: (0, import_node_path3.resolve)(stateFilePath),
+    cooldownMs
+  };
+}
+function printWatchUsage() {
+  console.log(`
+AgentFlow Watch \u2014 headless alert system for agent infrastructure.
+
+Polls directories for JSON/JSONL files, detects failures and stale
+agents, sends alerts. Same auto-detection as \`agentflow live\`.
+
+Usage:
+  agentflow watch [dir...] [options]
+
+Arguments:
+  dir                          One or more directories to watch (default: .)
+
+Alert conditions (--alert-on, repeatable):
+  error                        Agent transitions to error status
+  recovery                     Agent recovers from error to ok
+  stale:DURATION               No file update within duration (e.g. 15m, 1h)
+  consecutive-errors:N         N consecutive error observations
+
+  Default (if none specified): error + recovery
+
+Notification channels (--notify, repeatable):
+  telegram                     Telegram Bot API (needs env vars)
+  webhook:URL                  POST JSON to any URL
+  command:CMD                  Run shell command with alert env vars
+
+  Stdout alerts are always printed regardless of --notify flags.
+
+Options:
+  --poll <secs>                Poll interval in seconds (default: 30)
+  --cooldown <duration>        Alert dedup cooldown (default: 30m)
+  --state-file <path>          Persistence file (default: <dir>/.agentflow-watch-state.json)
+  -R, --recursive              Scan subdirectories (1 level deep)
+  -h, --help                   Show this help message
+
+Environment variables:
+  AGENTFLOW_TELEGRAM_BOT_TOKEN   Telegram bot token (for --notify telegram)
+  AGENTFLOW_TELEGRAM_CHAT_ID     Telegram chat ID (for --notify telegram)
+
+Examples:
+  agentflow watch ./data --alert-on error --alert-on stale:15m
+  agentflow watch ./data ./cron --notify telegram --poll 60
+  agentflow watch ./traces --notify webhook:https://hooks.slack.com/... --alert-on consecutive-errors:3
+  agentflow watch ./data --notify "command:curl -X POST https://my-pagerduty/alert"
+`.trim());
+}
+function startWatch(argv) {
+  const config = parseWatchArgs(argv);
+  const valid = config.dirs.filter((d) => (0, import_node_fs4.existsSync)(d));
+  if (valid.length === 0) {
+    console.error(`No valid directories found: ${config.dirs.join(", ")}`);
+    process.exit(1);
+  }
+  const invalid = config.dirs.filter((d) => !(0, import_node_fs4.existsSync)(d));
+  if (invalid.length > 0) {
+    console.warn(`Skipping non-existent: ${invalid.join(", ")}`);
+  }
+  let state = loadWatchState(config.stateFilePath);
+  const condLabels = config.alertConditions.map((c) => {
+    if (c.type === "stale") return `stale:${Math.floor(c.durationMs / 6e4)}m`;
+    if (c.type === "consecutive-errors") return `consecutive-errors:${c.threshold}`;
+    return c.type;
+  });
+  const channelLabels = config.notifyChannels.filter((c) => c.type !== "stdout").map((c) => {
+    if (c.type === "webhook") return `webhook:${c.url.slice(0, 40)}...`;
+    if (c.type === "command") return `command:${c.cmd.slice(0, 40)}`;
+    return c.type;
+  });
+  console.log(`
+agentflow watch started`);
+  console.log(`  Directories:  ${valid.join(", ")}`);
+  console.log(`  Poll:         ${config.pollIntervalMs / 1e3}s`);
+  console.log(`  Alert on:     ${condLabels.join(", ")}`);
+  console.log(`  Notify:       stdout${channelLabels.length > 0 ? ", " + channelLabels.join(", ") : ""}`);
+  console.log(`  Cooldown:     ${Math.floor(config.cooldownMs / 6e4)}m`);
+  console.log(`  State:        ${config.stateFilePath}`);
+  console.log(`  Hostname:     ${(0, import_node_os.hostname)()}`);
+  console.log("");
+  let pollCount = 0;
+  async function poll() {
+    const now = Date.now();
+    pollCount++;
+    const files = scanFiles(valid, config.recursive);
+    const records = [];
+    for (const f of files.slice(0, 500)) {
+      const recs = f.ext === ".jsonl" ? processJsonlFile(f) : processJsonFile(f);
+      records.push(...recs);
+    }
+    const alerts = detectTransitions(state, records, config, now);
+    for (const alert of alerts) {
+      for (const channel of config.notifyChannels) {
+        await sendAlert(alert, channel);
+      }
+    }
+    state = updateWatchState(state, records, alerts, now);
+    saveWatchState(config.stateFilePath, state);
+    if (pollCount % 10 === 0) {
+      const agentCount = Object.keys(state.agents).length;
+      const errorCount = Object.values(state.agents).filter((a) => a.lastStatus === "error").length;
+      const runningCount = Object.values(state.agents).filter((a) => a.lastStatus === "running").length;
+      const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+      console.log(`[${time}] heartbeat: ${agentCount} agents, ${runningCount} running, ${errorCount} errors, ${files.length} files`);
+    }
+  }
+  poll();
+  setInterval(() => {
+    poll();
+  }, config.pollIntervalMs);
+  function shutdown() {
+    console.log("\nagentflow watch stopped.");
+    saveWatchState(config.stateFilePath, state);
+    process.exit(0);
+  }
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createGraphBuilder,
@@ -1234,5 +1751,6 @@ function startLive(argv) {
   loadGraph,
   runTraced,
   startLive,
+  startWatch,
   stitchTrace
 });

package/dist/index.d.cts

@@ -393,8 +393,72 @@ declare function runTraced(config: RunConfig): Promise<RunResult>;
  *
  * @module
  */
+
 declare function startLive(argv: string[]): void;
 
+/**
+ * AgentFlow Watch — headless alert system for agent infrastructure.
+ *
+ * Polls directories for JSON/JSONL state files, detects status transitions
+ * (ok→error, stale, recovery), and sends alerts via Telegram, webhooks,
+ * shell commands, or stdout.
+ *
+ * @module
+ */
+declare function startWatch(argv: string[]): void;
+
+/**
+ * Type definitions for the `agentflow watch` alert system.
+ * @module
+ */
+/** Alert condition parsed from --alert-on flags. */
+type AlertCondition = {
+    readonly type: 'error';
+} | {
+    readonly type: 'stale';
+    readonly durationMs: number;
+} | {
+    readonly type: 'recovery';
+} | {
+    readonly type: 'consecutive-errors';
+    readonly threshold: number;
+};
+/** Notification channel parsed from --notify flags. */
+type NotifyChannel = {
+    readonly type: 'stdout';
+} | {
+    readonly type: 'telegram';
+    readonly botToken: string;
+    readonly chatId: string;
+} | {
+    readonly type: 'webhook';
+    readonly url: string;
+} | {
+    readonly type: 'command';
+    readonly cmd: string;
+};
+/** Configuration for the watch command. */
+interface WatchConfig {
+    readonly dirs: string[];
+    readonly recursive: boolean;
+    readonly pollIntervalMs: number;
+    readonly alertConditions: AlertCondition[];
+    readonly notifyChannels: NotifyChannel[];
+    readonly stateFilePath: string;
+    readonly cooldownMs: number;
+}
+/** Alert payload passed to notification channels. */
+interface AlertPayload {
+    readonly agentId: string;
+    readonly condition: string;
+    readonly previousStatus: string;
+    readonly currentStatus: string;
+    readonly detail: string;
+    readonly file: string;
+    readonly timestamp: number;
+    readonly dirs: readonly string[];
+}
+
 declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
 declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
 declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
@@ -515,4 +579,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-export { type Adapter, type AgentFlowConfig, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, stitchTrace };
+export { type Adapter, type AgentFlowConfig, type AlertCondition, type AlertPayload, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type WatchConfig, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace };

package/dist/index.d.ts

@@ -393,8 +393,72 @@ declare function runTraced(config: RunConfig): Promise<RunResult>;
  *
  * @module
  */
+
 declare function startLive(argv: string[]): void;
 
+/**
+ * AgentFlow Watch — headless alert system for agent infrastructure.
+ *
+ * Polls directories for JSON/JSONL state files, detects status transitions
+ * (ok→error, stale, recovery), and sends alerts via Telegram, webhooks,
+ * shell commands, or stdout.
+ *
+ * @module
+ */
+declare function startWatch(argv: string[]): void;
+
+/**
+ * Type definitions for the `agentflow watch` alert system.
+ * @module
+ */
+/** Alert condition parsed from --alert-on flags. */
+type AlertCondition = {
+    readonly type: 'error';
+} | {
+    readonly type: 'stale';
+    readonly durationMs: number;
+} | {
+    readonly type: 'recovery';
+} | {
+    readonly type: 'consecutive-errors';
+    readonly threshold: number;
+};
+/** Notification channel parsed from --notify flags. */
+type NotifyChannel = {
+    readonly type: 'stdout';
+} | {
+    readonly type: 'telegram';
+    readonly botToken: string;
+    readonly chatId: string;
+} | {
+    readonly type: 'webhook';
+    readonly url: string;
+} | {
+    readonly type: 'command';
+    readonly cmd: string;
+};
+/** Configuration for the watch command. */
+interface WatchConfig {
+    readonly dirs: string[];
+    readonly recursive: boolean;
+    readonly pollIntervalMs: number;
+    readonly alertConditions: AlertCondition[];
+    readonly notifyChannels: NotifyChannel[];
+    readonly stateFilePath: string;
+    readonly cooldownMs: number;
+}
+/** Alert payload passed to notification channels. */
+interface AlertPayload {
+    readonly agentId: string;
+    readonly condition: string;
+    readonly previousStatus: string;
+    readonly currentStatus: string;
+    readonly detail: string;
+    readonly file: string;
+    readonly timestamp: number;
+    readonly dirs: readonly string[];
+}
+
 declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
 declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
 declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
@@ -515,4 +579,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-export { type Adapter, type AgentFlowConfig, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, stitchTrace };
+export { type Adapter, type AgentFlowConfig, type AlertCondition, type AlertPayload, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type WatchConfig, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace };