agentflow-core 0.1.2 → 0.1.3

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   getSubtree: () => getSubtree,
   getTraceTree: () => getTraceTree,
   groupByTraceId: () => groupByTraceId,
+  runTraced: () => runTraced,
   stitchTrace: () => stitchTrace
 });
 module.exports = __toCommonJS(index_exports);
@@ -264,6 +265,178 @@ function createGraphBuilder(config) {
   return builder;
 }
 
+// src/runner.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`);
+}
+function snapshotDir(dir, patterns) {
+  const result = /* @__PURE__ */ new Map();
+  if (!(0, import_node_fs.existsSync)(dir)) return result;
+  for (const entry of (0, import_node_fs.readdirSync)(dir)) {
+    if (!patterns.some((re) => re.test(entry))) continue;
+    const full = (0, import_node_path.join)(dir, entry);
+    try {
+      const stat = (0, import_node_fs.statSync)(full);
+      if (stat.isFile()) {
+        result.set(full, stat.mtimeMs);
+      }
+    } catch {
+    }
+  }
+  return result;
+}
+function agentIdFromFilename(filePath) {
+  const base = (0, import_node_path.basename)(filePath, ".json");
+  const cleaned = base.replace(/-state$/, "");
+  return `alfred-${cleaned}`;
+}
+function deriveAgentId(command) {
+  return "orchestrator";
+}
+function fileTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-").replace(/\.\d+Z$/, "");
+}
+function graphToJson(graph) {
+  const nodesObj = {};
+  for (const [id, node] of graph.nodes) {
+    nodesObj[id] = node;
+  }
+  return {
+    id: graph.id,
+    rootNodeId: graph.rootNodeId,
+    nodes: nodesObj,
+    edges: graph.edges,
+    startTime: graph.startTime,
+    endTime: graph.endTime,
+    status: graph.status,
+    trigger: graph.trigger,
+    agentId: graph.agentId,
+    events: graph.events,
+    traceId: graph.traceId,
+    spanId: graph.spanId,
+    parentSpanId: graph.parentSpanId
+  };
+}
+async function runTraced(config) {
+  const {
+    command,
+    agentId = deriveAgentId(command),
+    trigger = "cli",
+    tracesDir = "./traces",
+    watchDirs = [],
+    watchPatterns = ["*.json"]
+  } = config;
+  if (command.length === 0) {
+    throw new Error("runTraced: command must not be empty");
+  }
+  const resolvedTracesDir = (0, import_node_path.resolve)(tracesDir);
+  const patterns = watchPatterns.map(globToRegex);
+  const orchestrator = createGraphBuilder({ agentId, trigger });
+  const { traceId, spanId } = orchestrator.traceContext;
+  const beforeSnapshots = /* @__PURE__ */ new Map();
+  for (const dir of watchDirs) {
+    beforeSnapshots.set(dir, snapshotDir(dir, patterns));
+  }
+  const rootId = orchestrator.startNode({ type: "agent", name: agentId });
+  const dispatchId = orchestrator.startNode({
+    type: "tool",
+    name: "dispatch-command",
+    parentId: rootId
+  });
+  orchestrator.updateState(dispatchId, { command: command.join(" ") });
+  const monitorId = orchestrator.startNode({
+    type: "tool",
+    name: "state-monitor",
+    parentId: rootId
+  });
+  orchestrator.updateState(monitorId, {
+    watchDirs,
+    watchPatterns
+  });
+  const startMs = Date.now();
+  const execCmd = command[0] ?? "";
+  const execArgs = command.slice(1);
+  process.env.AGENTFLOW_TRACE_ID = traceId;
+  process.env.AGENTFLOW_PARENT_SPAN_ID = spanId;
+  const result = (0, import_node_child_process.spawnSync)(execCmd, execArgs, { stdio: "inherit" });
+  delete process.env.AGENTFLOW_TRACE_ID;
+  delete process.env.AGENTFLOW_PARENT_SPAN_ID;
+  const exitCode = result.status ?? 1;
+  const duration = (Date.now() - startMs) / 1e3;
+  const stateChanges = [];
+  for (const dir of watchDirs) {
+    const before = beforeSnapshots.get(dir) ?? /* @__PURE__ */ new Map();
+    const after = snapshotDir(dir, patterns);
+    for (const [filePath, mtime] of after) {
+      const prevMtime = before.get(filePath);
+      if (prevMtime === void 0 || mtime > prevMtime) {
+        stateChanges.push(filePath);
+      }
+    }
+  }
+  orchestrator.updateState(monitorId, { stateChanges });
+  orchestrator.endNode(monitorId);
+  if (exitCode === 0) {
+    orchestrator.endNode(dispatchId);
+  } else {
+    orchestrator.failNode(dispatchId, `Command exited with code ${exitCode}`);
+  }
+  orchestrator.updateState(rootId, {
+    exitCode,
+    duration,
+    stateChanges
+  });
+  if (exitCode === 0) {
+    orchestrator.endNode(rootId);
+  } else {
+    orchestrator.failNode(rootId, `Command exited with code ${exitCode}`);
+  }
+  const orchestratorGraph = orchestrator.build();
+  const allGraphs = [orchestratorGraph];
+  for (const filePath of stateChanges) {
+    const childAgentId = agentIdFromFilename(filePath);
+    const childBuilder = createGraphBuilder({
+      agentId: childAgentId,
+      trigger: "state-change",
+      traceId,
+      parentSpanId: spanId
+    });
+    const childRootId = childBuilder.startNode({
+      type: "agent",
+      name: childAgentId
+    });
+    childBuilder.updateState(childRootId, {
+      stateFile: filePath,
+      detectedBy: "runner-state-monitor"
+    });
+    childBuilder.endNode(childRootId);
+    allGraphs.push(childBuilder.build());
+  }
+  if (!(0, import_node_fs.existsSync)(resolvedTracesDir)) {
+    (0, import_node_fs.mkdirSync)(resolvedTracesDir, { recursive: true });
+  }
+  const ts = fileTimestamp();
+  const tracePaths = [];
+  for (const graph of allGraphs) {
+    const filename = `${graph.agentId}-${ts}.json`;
+    const outPath = (0, import_node_path.join)(resolvedTracesDir, filename);
+    (0, import_node_fs.writeFileSync)(outPath, JSON.stringify(graphToJson(graph), null, 2), "utf-8");
+    tracePaths.push(outPath);
+  }
+  return {
+    exitCode,
+    traceId,
+    spanId,
+    tracePaths,
+    stateChanges,
+    duration
+  };
+}
+
 // src/graph-stitch.ts
 function groupByTraceId(graphs) {
   const groups = /* @__PURE__ */ new Map();
@@ -482,5 +655,6 @@ function getStats(graph) {
   getSubtree,
   getTraceTree,
   groupByTraceId,
+  runTraced,
   stitchTrace
 });

package/dist/index.d.cts

@@ -276,6 +276,55 @@ interface MutableExecutionNode {
  */
 declare function createGraphBuilder(config?: AgentFlowConfig): GraphBuilder;
 
+/**
+ * CLI runner that wraps any command with automatic AgentFlow tracing.
+ *
+ * No code changes needed in the target application — the runner sets
+ * AGENTFLOW_TRACE_ID and AGENTFLOW_PARENT_SPAN_ID env vars so any child
+ * process using AgentFlow auto-joins the distributed trace.
+ *
+ * @example
+ * ```ts
+ * const result = await runTraced({
+ *   command: ['python', '-m', 'alfred', 'process'],
+ *   watchDirs: ['/home/trader/.alfred/data'],
+ * });
+ * ```
+ * @module
+ */
+interface RunConfig {
+    /** Command to execute (e.g. ['python', '-m', 'alfred', 'process']). */
+    command: string[];
+    /** Agent ID for the orchestrator trace (default: derived from command). */
+    agentId?: string;
+    /** Trigger label (default: "cli"). */
+    trigger?: string;
+    /** Directory to save trace files (default: ./traces). */
+    tracesDir?: string;
+    /** Directories to watch for state file changes during execution. */
+    watchDirs?: string[];
+    /** File patterns to watch (default: ["*.json"]). */
+    watchPatterns?: string[];
+}
+interface RunResult {
+    exitCode: number;
+    traceId: string;
+    spanId: string;
+    tracePaths: string[];
+    stateChanges: string[];
+    duration: number;
+}
+/**
+ * Run a command with automatic AgentFlow tracing.
+ *
+ * 1. Creates an orchestrator (parent) trace.
+ * 2. Snapshots watched directories.
+ * 3. Spawns the command with trace env vars.
+ * 4. After exit, detects state file changes and creates child traces.
+ * 5. Saves all trace JSON files.
+ */
+declare function runTraced(config: RunConfig): Promise<RunResult>;
+
 declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
 declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
 declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
@@ -396,4 +445,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 StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, groupByTraceId, stitchTrace };
+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, groupByTraceId, runTraced, stitchTrace };

package/dist/index.d.ts

@@ -276,6 +276,55 @@ interface MutableExecutionNode {
  */
 declare function createGraphBuilder(config?: AgentFlowConfig): GraphBuilder;
 
+/**
+ * CLI runner that wraps any command with automatic AgentFlow tracing.
+ *
+ * No code changes needed in the target application — the runner sets
+ * AGENTFLOW_TRACE_ID and AGENTFLOW_PARENT_SPAN_ID env vars so any child
+ * process using AgentFlow auto-joins the distributed trace.
+ *
+ * @example
+ * ```ts
+ * const result = await runTraced({
+ *   command: ['python', '-m', 'alfred', 'process'],
+ *   watchDirs: ['/home/trader/.alfred/data'],
+ * });
+ * ```
+ * @module
+ */
+interface RunConfig {
+    /** Command to execute (e.g. ['python', '-m', 'alfred', 'process']). */
+    command: string[];
+    /** Agent ID for the orchestrator trace (default: derived from command). */
+    agentId?: string;
+    /** Trigger label (default: "cli"). */
+    trigger?: string;
+    /** Directory to save trace files (default: ./traces). */
+    tracesDir?: string;
+    /** Directories to watch for state file changes during execution. */
+    watchDirs?: string[];
+    /** File patterns to watch (default: ["*.json"]). */
+    watchPatterns?: string[];
+}
+interface RunResult {
+    exitCode: number;
+    traceId: string;
+    spanId: string;
+    tracePaths: string[];
+    stateChanges: string[];
+    duration: number;
+}
+/**
+ * Run a command with automatic AgentFlow tracing.
+ *
+ * 1. Creates an orchestrator (parent) trace.
+ * 2. Snapshots watched directories.
+ * 3. Spawns the command with trace env vars.
+ * 4. After exit, detects state file changes and creates child traces.
+ * 5. Saves all trace JSON files.
+ */
+declare function runTraced(config: RunConfig): Promise<RunResult>;
+
 declare function groupByTraceId(graphs: ExecutionGraph[]): Map<string, ExecutionGraph[]>;
 declare function stitchTrace(graphs: ExecutionGraph[]): DistributedTrace;
 declare function getTraceTree(trace: DistributedTrace): ExecutionGraph[];
@@ -396,4 +445,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 StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, groupByTraceId, stitchTrace };
+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, groupByTraceId, runTraced, stitchTrace };

package/dist/index.js

@@ -1,228 +1,7 @@
-// src/graph-builder.ts
-import { randomUUID } from "crypto";
-function deepFreeze(obj) {
-  if (obj === null || typeof obj !== "object") return obj;
-  if (obj instanceof Map) {
-    Object.freeze(obj);
-    for (const value of obj.values()) {
-      deepFreeze(value);
-    }
-    return obj;
-  }
-  Object.freeze(obj);
-  const record = obj;
-  for (const key of Object.keys(record)) {
-    const value = record[key];
-    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
-      deepFreeze(value);
-    }
-  }
-  return obj;
-}
-function createCounterIdGenerator() {
-  let counter = 0;
-  return () => {
-    counter++;
-    return `node_${String(counter).padStart(3, "0")}`;
-  };
-}
-function createGraphBuilder(config) {
-  const generateId = config?.idGenerator ?? createCounterIdGenerator();
-  const agentId = config?.agentId ?? "unknown";
-  const trigger = config?.trigger ?? "manual";
-  const spanId = randomUUID();
-  const traceId = config?.traceId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_TRACE_ID : void 0) ?? randomUUID();
-  const parentSpanId = config?.parentSpanId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_PARENT_SPAN_ID : void 0) ?? null;
-  const graphId = generateId();
-  const startTime = Date.now();
-  const nodes = /* @__PURE__ */ new Map();
-  const edges = [];
-  const events = [];
-  const parentStack = [];
-  let rootNodeId = null;
-  let built = false;
-  function assertNotBuilt() {
-    if (built) {
-      throw new Error("GraphBuilder: cannot mutate after build() has been called");
-    }
-  }
-  function getNode2(nodeId) {
-    const node = nodes.get(nodeId);
-    if (!node) {
-      throw new Error(`GraphBuilder: node "${nodeId}" does not exist`);
-    }
-    return node;
-  }
-  function recordEvent(nodeId, eventType, data = {}) {
-    events.push({
-      timestamp: Date.now(),
-      eventType,
-      nodeId,
-      data
-    });
-  }
-  function buildGraph() {
-    if (rootNodeId === null) {
-      throw new Error("GraphBuilder: cannot build a graph with no nodes");
-    }
-    let graphStatus = "completed";
-    for (const node of nodes.values()) {
-      if (node.status === "failed" || node.status === "timeout" || node.status === "hung") {
-        graphStatus = "failed";
-        break;
-      }
-      if (node.status === "running") {
-        graphStatus = "running";
-      }
-    }
-    const endTime = graphStatus === "running" ? null : Date.now();
-    const frozenNodes = new Map(
-      [...nodes.entries()].map(([id, mNode]) => [
-        id,
-        {
-          id: mNode.id,
-          type: mNode.type,
-          name: mNode.name,
-          startTime: mNode.startTime,
-          endTime: mNode.endTime,
-          status: mNode.status,
-          parentId: mNode.parentId,
-          children: [...mNode.children],
-          metadata: { ...mNode.metadata },
-          state: { ...mNode.state }
-        }
-      ])
-    );
-    const graph = {
-      id: graphId,
-      rootNodeId,
-      nodes: frozenNodes,
-      edges: [...edges],
-      startTime,
-      endTime,
-      status: graphStatus,
-      trigger,
-      agentId,
-      events: [...events],
-      traceId,
-      spanId,
-      parentSpanId
-    };
-    return deepFreeze(graph);
-  }
-  const builder = {
-    get graphId() {
-      return graphId;
-    },
-    get traceContext() {
-      return { traceId, spanId };
-    },
-    startNode(opts) {
-      assertNotBuilt();
-      const id = generateId();
-      const parentId = opts.parentId ?? parentStack[parentStack.length - 1] ?? null;
-      if (parentId !== null && !nodes.has(parentId)) {
-        throw new Error(`GraphBuilder: parent node "${parentId}" does not exist`);
-      }
-      const node = {
-        id,
-        type: opts.type,
-        name: opts.name,
-        startTime: Date.now(),
-        endTime: null,
-        status: "running",
-        parentId,
-        children: [],
-        metadata: opts.metadata ? { ...opts.metadata } : {},
-        state: {}
-      };
-      nodes.set(id, node);
-      if (parentId !== null) {
-        const parent = nodes.get(parentId);
-        if (parent) {
-          parent.children.push(id);
-        }
-        edges.push({ from: parentId, to: id, type: "spawned" });
-      }
-      if (rootNodeId === null) {
-        rootNodeId = id;
-      }
-      recordEvent(id, "agent_start", { type: opts.type, name: opts.name });
-      return id;
-    },
-    endNode(nodeId, status = "completed") {
-      assertNotBuilt();
-      const node = getNode2(nodeId);
-      if (node.endTime !== null) {
-        throw new Error(
-          `GraphBuilder: node "${nodeId}" has already ended (status: ${node.status})`
-        );
-      }
-      node.endTime = Date.now();
-      node.status = status;
-      recordEvent(nodeId, "agent_end", { status });
-    },
-    failNode(nodeId, error) {
-      assertNotBuilt();
-      const node = getNode2(nodeId);
-      if (node.endTime !== null) {
-        throw new Error(
-          `GraphBuilder: node "${nodeId}" has already ended (status: ${node.status})`
-        );
-      }
-      const errorMessage = error instanceof Error ? error.message : error;
-      const errorStack = error instanceof Error ? error.stack : void 0;
-      node.endTime = Date.now();
-      node.status = "failed";
-      node.metadata.error = errorMessage;
-      if (errorStack) {
-        node.metadata.errorStack = errorStack;
-      }
-      recordEvent(nodeId, "tool_error", { error: errorMessage });
-    },
-    addEdge(from, to, type) {
-      assertNotBuilt();
-      getNode2(from);
-      getNode2(to);
-      edges.push({ from, to, type });
-      recordEvent(from, "custom", { to, type, action: "edge_add" });
-    },
-    pushEvent(event) {
-      assertNotBuilt();
-      getNode2(event.nodeId);
-      events.push({
-        ...event,
-        timestamp: Date.now()
-      });
-    },
-    updateState(nodeId, state) {
-      assertNotBuilt();
-      const node = getNode2(nodeId);
-      Object.assign(node.state, state);
-      recordEvent(nodeId, "custom", { action: "state_update", ...state });
-    },
-    withParent(parentId, fn) {
-      assertNotBuilt();
-      getNode2(parentId);
-      parentStack.push(parentId);
-      try {
-        return fn();
-      } finally {
-        parentStack.pop();
-      }
-    },
-    getSnapshot() {
-      return buildGraph();
-    },
-    build() {
-      assertNotBuilt();
-      const graph = buildGraph();
-      built = true;
-      return graph;
-    }
-  };
-  return builder;
-}
+import {
+  createGraphBuilder,
+  runTraced
+} from "./chunk-DGLK6IBP.js";
 
 // src/graph-stitch.ts
 function groupByTraceId(graphs) {
@@ -441,5 +220,6 @@ export {
   getSubtree,
   getTraceTree,
   groupByTraceId,
+  runTraced,
   stitchTrace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentflow-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Universal execution tracing for AI agent systems",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,7 +17,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean --tsconfig tsconfig.build.json"
+    "build": "tsup src/index.ts src/cli.ts --format esm,cjs --dts --clean --tsconfig tsconfig.build.json"
   },
   "dependencies": {},
   "keywords": [
@@ -27,5 +27,8 @@
     "execution-graph",
     "observability"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "bin": {
+    "agentflow": "./dist/cli.js"
+  }
 }