agentflow-core 0.5.2 → 0.6.1

package/dist/index.d.cts

@@ -494,6 +494,114 @@ declare function withGuards(builder: GraphBuilder, config?: GuardConfig): GraphB
 
 declare function startLive(argv: string[]): void;
 
+/**
+ * AgentFlow Process Audit — OS-level process health checks for agent systems.
+ *
+ * Detects stale PID files, orphan processes, systemd unit issues,
+ * and mismatches between declared state (PID files, workers.json)
+ * and actual OS process state.
+ *
+ * Linux-only (reads /proc). Returns structured results for programmatic
+ * use or terminal display.
+ *
+ * @module
+ */
+interface PidFileResult {
+    path: string;
+    pid: number | null;
+    alive: boolean;
+    /** Whether /proc/<pid>/cmdline contains the expected process name. */
+    matchesProcess: boolean;
+    stale: boolean;
+    reason: string;
+}
+interface SystemdUnitResult {
+    unit: string;
+    activeState: string;
+    subState: string;
+    mainPid: number;
+    restarts: number;
+    result: string;
+    crashLooping: boolean;
+    failed: boolean;
+}
+interface WorkerEntry {
+    name: string;
+    pid: number | null;
+    declaredStatus: string;
+    alive: boolean;
+    stale: boolean;
+}
+interface WorkersResult {
+    orchestratorPid: number | null;
+    orchestratorAlive: boolean;
+    startedAt: string;
+    workers: WorkerEntry[];
+}
+interface OsProcess {
+    pid: number;
+    cpu: string;
+    mem: string;
+    command: string;
+}
+interface ProcessAuditResult {
+    pidFile: PidFileResult | null;
+    systemd: SystemdUnitResult | null;
+    workers: WorkersResult | null;
+    osProcesses: OsProcess[];
+    orphans: OsProcess[];
+    problems: string[];
+}
+interface ProcessAuditConfig {
+    /** Path to the PID file (e.g. /home/user/.myapp/data/app.pid). */
+    pidFile?: string;
+    /** Path to workers.json or equivalent process registry. */
+    workersFile?: string;
+    /** Systemd unit name (e.g. "myapp.service"). Use `null` to skip. */
+    systemdUnit?: string | null;
+    /** Process name to match in `pgrep -a` and /proc/cmdline (e.g. "alfred", "myagent"). */
+    processName: string;
+}
+/**
+ * Scan directories for PID files (`*.pid`), worker registries (`workers.json`,
+ * `*-workers.json`), and infer a process name from the PID file name.
+ *
+ * Returns a config suitable for `auditProcesses()`, or null if nothing found.
+ *
+ * @example
+ * ```ts
+ * const config = discoverProcessConfig(['./data', '/var/run/myagent']);
+ * if (config) console.log(formatAuditReport(auditProcesses(config)));
+ * ```
+ */
+declare function discoverProcessConfig(dirs: string[]): ProcessAuditConfig | null;
+/**
+ * Run a full process health audit.
+ *
+ * Checks PID files, systemd units, worker registries, and OS process tables
+ * to detect stale processes, orphans, and state mismatches.
+ *
+ * @example
+ * ```ts
+ * import { auditProcesses, formatAuditReport } from 'agentflow-core';
+ *
+ * const result = auditProcesses({
+ *   processName: 'alfred',
+ *   pidFile: '/home/user/.alfred/data/alfred.pid',
+ *   workersFile: '/home/user/.alfred/data/workers.json',
+ *   systemdUnit: 'alfred.service',
+ * });
+ *
+ * console.log(formatAuditReport(result));
+ * ```
+ */
+declare function auditProcesses(config: ProcessAuditConfig): ProcessAuditResult;
+/**
+ * Format an audit result as a human-readable terminal report.
+ * Uses Unicode box-drawing characters and status icons.
+ */
+declare function formatAuditReport(result: ProcessAuditResult): string;
+
 /**
  * Load and deserialize execution graphs from JSON.
  *
@@ -743,4 +851,4 @@ interface AlertPayload {
     readonly dirs: readonly string[];
 }
 
-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 GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type Writer, checkGuards, createGraphBuilder, createTraceStore, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };
+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 GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type OsProcess, type PidFileResult, type ProcessAuditConfig, type ProcessAuditResult, type RunConfig, type RunResult, type StartNodeOptions, type SystemdUnitResult, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type WorkerEntry, type WorkersResult, type Writer, auditProcesses, checkGuards, createGraphBuilder, createTraceStore, discoverProcessConfig, findWaitingOn, formatAuditReport, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };

package/dist/index.d.ts

@@ -494,6 +494,114 @@ declare function withGuards(builder: GraphBuilder, config?: GuardConfig): GraphB
 
 declare function startLive(argv: string[]): void;
 
+/**
+ * AgentFlow Process Audit — OS-level process health checks for agent systems.
+ *
+ * Detects stale PID files, orphan processes, systemd unit issues,
+ * and mismatches between declared state (PID files, workers.json)
+ * and actual OS process state.
+ *
+ * Linux-only (reads /proc). Returns structured results for programmatic
+ * use or terminal display.
+ *
+ * @module
+ */
+interface PidFileResult {
+    path: string;
+    pid: number | null;
+    alive: boolean;
+    /** Whether /proc/<pid>/cmdline contains the expected process name. */
+    matchesProcess: boolean;
+    stale: boolean;
+    reason: string;
+}
+interface SystemdUnitResult {
+    unit: string;
+    activeState: string;
+    subState: string;
+    mainPid: number;
+    restarts: number;
+    result: string;
+    crashLooping: boolean;
+    failed: boolean;
+}
+interface WorkerEntry {
+    name: string;
+    pid: number | null;
+    declaredStatus: string;
+    alive: boolean;
+    stale: boolean;
+}
+interface WorkersResult {
+    orchestratorPid: number | null;
+    orchestratorAlive: boolean;
+    startedAt: string;
+    workers: WorkerEntry[];
+}
+interface OsProcess {
+    pid: number;
+    cpu: string;
+    mem: string;
+    command: string;
+}
+interface ProcessAuditResult {
+    pidFile: PidFileResult | null;
+    systemd: SystemdUnitResult | null;
+    workers: WorkersResult | null;
+    osProcesses: OsProcess[];
+    orphans: OsProcess[];
+    problems: string[];
+}
+interface ProcessAuditConfig {
+    /** Path to the PID file (e.g. /home/user/.myapp/data/app.pid). */
+    pidFile?: string;
+    /** Path to workers.json or equivalent process registry. */
+    workersFile?: string;
+    /** Systemd unit name (e.g. "myapp.service"). Use `null` to skip. */
+    systemdUnit?: string | null;
+    /** Process name to match in `pgrep -a` and /proc/cmdline (e.g. "alfred", "myagent"). */
+    processName: string;
+}
+/**
+ * Scan directories for PID files (`*.pid`), worker registries (`workers.json`,
+ * `*-workers.json`), and infer a process name from the PID file name.
+ *
+ * Returns a config suitable for `auditProcesses()`, or null if nothing found.
+ *
+ * @example
+ * ```ts
+ * const config = discoverProcessConfig(['./data', '/var/run/myagent']);
+ * if (config) console.log(formatAuditReport(auditProcesses(config)));
+ * ```
+ */
+declare function discoverProcessConfig(dirs: string[]): ProcessAuditConfig | null;
+/**
+ * Run a full process health audit.
+ *
+ * Checks PID files, systemd units, worker registries, and OS process tables
+ * to detect stale processes, orphans, and state mismatches.
+ *
+ * @example
+ * ```ts
+ * import { auditProcesses, formatAuditReport } from 'agentflow-core';
+ *
+ * const result = auditProcesses({
+ *   processName: 'alfred',
+ *   pidFile: '/home/user/.alfred/data/alfred.pid',
+ *   workersFile: '/home/user/.alfred/data/workers.json',
+ *   systemdUnit: 'alfred.service',
+ * });
+ *
+ * console.log(formatAuditReport(result));
+ * ```
+ */
+declare function auditProcesses(config: ProcessAuditConfig): ProcessAuditResult;
+/**
+ * Format an audit result as a human-readable terminal report.
+ * Uses Unicode box-drawing characters and status icons.
+ */
+declare function formatAuditReport(result: ProcessAuditResult): string;
+
 /**
  * Load and deserialize execution graphs from JSON.
  *
@@ -743,4 +851,4 @@ interface AlertPayload {
     readonly dirs: readonly string[];
 }
 
-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 GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type Writer, checkGuards, createGraphBuilder, createTraceStore, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };
+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 GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type OsProcess, type PidFileResult, type ProcessAuditConfig, type ProcessAuditResult, type RunConfig, type RunResult, type StartNodeOptions, type SystemdUnitResult, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type WorkerEntry, type WorkersResult, type Writer, auditProcesses, checkGuards, createGraphBuilder, createTraceStore, discoverProcessConfig, findWaitingOn, formatAuditReport, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };

package/dist/index.js

@@ -1,7 +1,10 @@
 import {
+  auditProcesses,
   createGraphBuilder,
   createTraceStore,
+  discoverProcessConfig,
   findWaitingOn,
+  formatAuditReport,
   getChildren,
   getCriticalPath,
   getDepth,
@@ -20,7 +23,7 @@ import {
   stitchTrace,
   toAsciiTree,
   toTimeline
-} from "./chunk-YTMQBL3T.js";
+} from "./chunk-BOSYI5YM.js";
 import {
   graphToJson,
   loadGraph
@@ -184,10 +187,13 @@ function withGuards(builder, config) {
   };
 }
 export {
+  auditProcesses,
   checkGuards,
   createGraphBuilder,
   createTraceStore,
+  discoverProcessConfig,
   findWaitingOn,
+  formatAuditReport,
   getChildren,
   getCriticalPath,
   getDepth,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflow-core",
-  "version": "0.5.2",
-  "description": "Monitor any AI agent system. Auto-detects failures, sends alerts. Zero config, zero dependencies.",
+  "version": "0.6.1",
+  "description": "Monitor any AI agent system. Auto-detects failures, sends alerts, audits OS processes. Zero config, zero dependencies.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -37,7 +37,11 @@
     "autogen",
     "cron",
     "watchdog",
-    "health-check"
+    "health-check",
+    "process-audit",
+    "pid",
+    "orphan-detection",
+    "systemd"
   ],
   "license": "MIT",
   "repository": {