agentflow-core 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -31,11 +31,16 @@ __export(index_exports, {
   getNode: () => getNode,
   getParent: () => getParent,
   getStats: () => getStats,
-  getSubtree: () => getSubtree
+  getSubtree: () => getSubtree,
+  getTraceTree: () => getTraceTree,
+  groupByTraceId: () => groupByTraceId,
+  runTraced: () => runTraced,
+  stitchTrace: () => stitchTrace
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/graph-builder.ts
+var import_crypto = require("crypto");
 function deepFreeze(obj) {
   if (obj === null || typeof obj !== "object") return obj;
   if (obj instanceof Map) {
@@ -66,6 +71,9 @@ function createGraphBuilder(config) {
   const generateId = config?.idGenerator ?? createCounterIdGenerator();
   const agentId = config?.agentId ?? "unknown";
   const trigger = config?.trigger ?? "manual";
+  const spanId = (0, import_crypto.randomUUID)();
+  const traceId = config?.traceId ?? (typeof process !== "undefined" ? process.env?.AGENTFLOW_TRACE_ID : void 0) ?? (0, import_crypto.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();
@@ -136,7 +144,10 @@ function createGraphBuilder(config) {
       status: graphStatus,
       trigger,
       agentId,
-      events: [...events]
+      events: [...events],
+      traceId,
+      spanId,
+      parentSpanId
     };
     return deepFreeze(graph);
   }
@@ -144,6 +155,9 @@ function createGraphBuilder(config) {
     get graphId() {
       return graphId;
     },
+    get traceContext() {
+      return { traceId, spanId };
+    },
     startNode(opts) {
       assertNotBuilt();
       const id = generateId();
@@ -251,6 +265,242 @@ 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();
+  for (const g of graphs) {
+    if (!g.traceId) continue;
+    const arr = groups.get(g.traceId) ?? [];
+    arr.push(g);
+    groups.set(g.traceId, arr);
+  }
+  return groups;
+}
+function stitchTrace(graphs) {
+  if (graphs.length === 0) throw new Error("No graphs to stitch");
+  const traceId = graphs[0].traceId ?? "";
+  const graphsBySpan = /* @__PURE__ */ new Map();
+  const childMap = /* @__PURE__ */ new Map();
+  let rootGraph = null;
+  for (const g of graphs) {
+    if (g.spanId) graphsBySpan.set(g.spanId, g);
+    if (!g.parentSpanId) {
+      if (!rootGraph || g.startTime < rootGraph.startTime) rootGraph = g;
+    }
+    if (g.parentSpanId) {
+      const siblings = childMap.get(g.parentSpanId) ?? [];
+      if (g.spanId) siblings.push(g.spanId);
+      childMap.set(g.parentSpanId, siblings);
+    }
+  }
+  if (!rootGraph) rootGraph = graphs[0];
+  let status = "completed";
+  let endTime = 0;
+  let startTime = Infinity;
+  for (const g of graphs) {
+    startTime = Math.min(startTime, g.startTime);
+    if (g.status === "failed") status = "failed";
+    else if (g.status === "running" && status !== "failed") status = "running";
+    if (g.endTime === null) endTime = null;
+    else if (endTime !== null) endTime = Math.max(endTime, g.endTime);
+  }
+  const frozenChildMap = /* @__PURE__ */ new Map();
+  for (const [k, v] of childMap) frozenChildMap.set(k, Object.freeze([...v]));
+  return Object.freeze({
+    traceId,
+    graphs: graphsBySpan,
+    rootGraph,
+    childMap: frozenChildMap,
+    startTime,
+    endTime,
+    status
+  });
+}
+function getTraceTree(trace) {
+  const result = [];
+  function walk(spanId) {
+    const graph = trace.graphs.get(spanId);
+    if (graph) result.push(graph);
+    const children = trace.childMap.get(spanId) ?? [];
+    for (const childSpan of children) walk(childSpan);
+  }
+  if (trace.rootGraph.spanId) walk(trace.rootGraph.spanId);
+  else result.push(trace.rootGraph);
+  return result;
+}
+
 // src/graph-query.ts
 function getNode(graph, nodeId) {
   return graph.nodes.get(nodeId);
@@ -402,5 +652,9 @@ function getStats(graph) {
   getNode,
   getParent,
   getStats,
-  getSubtree
+  getSubtree,
+  getTraceTree,
+  groupByTraceId,
+  runTraced,
+  stitchTrace
 });

package/dist/index.d.cts

@@ -65,6 +65,12 @@ interface ExecutionGraph {
     readonly agentId: string;
     /** Full ordered event log for auditability. */
     readonly events: readonly TraceEvent[];
+    /** Distributed trace ID linking graphs across services. */
+    readonly traceId?: string;
+    /** Unique span ID for this graph within the trace. */
+    readonly spanId?: string;
+    /** Parent span ID, or null if this is the root span. */
+    readonly parentSpanId?: string | null;
 }
 /**
  * Configuration for AgentFlow.
@@ -100,6 +106,10 @@ interface AgentFlowConfig {
     readonly logger?: (message: string) => void;
     /** Error callback for internal failures. */
     readonly onError?: (error: unknown) => void;
+    /** Distributed trace ID to join an existing trace. */
+    readonly traceId?: string;
+    /** Parent span ID for linking to an upstream graph. */
+    readonly parentSpanId?: string;
 }
 /**
  * Output adapter interface. Writers receive the completed execution graph
@@ -161,6 +171,11 @@ interface StartNodeOptions {
 interface GraphBuilder {
     /** The graph's ID, available before `build()`. */
     readonly graphId: string;
+    /** Trace context for propagating distributed trace information. */
+    readonly traceContext: {
+        traceId: string;
+        spanId: string;
+    };
     /** Start a new execution node. Returns the generated node ID. */
     startNode(opts: StartNodeOptions): string;
     /** End a node. Status defaults to `'completed'`. */
@@ -204,6 +219,16 @@ interface GraphStats {
     readonly failureCount: number;
     readonly hungCount: number;
 }
+/** A stitched distributed trace spanning multiple execution graphs. */
+interface DistributedTrace {
+    readonly traceId: string;
+    readonly graphs: ReadonlyMap<string, ExecutionGraph>;
+    readonly rootGraph: ExecutionGraph;
+    readonly childMap: ReadonlyMap<string, readonly string[]>;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly status: GraphStatus;
+}
 /** @internal Mutable version of ExecutionNode used during graph construction. */
 interface MutableExecutionNode {
     id: string;
@@ -251,6 +276,59 @@ 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[];
+
 /**
  * Pure query functions for interrogating a built `ExecutionGraph`.
  * Every function takes a frozen graph and returns derived data without mutation.
@@ -367,4 +445,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-export { type Adapter, type AgentFlowConfig, 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 };
+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

@@ -65,6 +65,12 @@ interface ExecutionGraph {
     readonly agentId: string;
     /** Full ordered event log for auditability. */
     readonly events: readonly TraceEvent[];
+    /** Distributed trace ID linking graphs across services. */
+    readonly traceId?: string;
+    /** Unique span ID for this graph within the trace. */
+    readonly spanId?: string;
+    /** Parent span ID, or null if this is the root span. */
+    readonly parentSpanId?: string | null;
 }
 /**
  * Configuration for AgentFlow.
@@ -100,6 +106,10 @@ interface AgentFlowConfig {
     readonly logger?: (message: string) => void;
     /** Error callback for internal failures. */
     readonly onError?: (error: unknown) => void;
+    /** Distributed trace ID to join an existing trace. */
+    readonly traceId?: string;
+    /** Parent span ID for linking to an upstream graph. */
+    readonly parentSpanId?: string;
 }
 /**
  * Output adapter interface. Writers receive the completed execution graph
@@ -161,6 +171,11 @@ interface StartNodeOptions {
 interface GraphBuilder {
     /** The graph's ID, available before `build()`. */
     readonly graphId: string;
+    /** Trace context for propagating distributed trace information. */
+    readonly traceContext: {
+        traceId: string;
+        spanId: string;
+    };
     /** Start a new execution node. Returns the generated node ID. */
     startNode(opts: StartNodeOptions): string;
     /** End a node. Status defaults to `'completed'`. */
@@ -204,6 +219,16 @@ interface GraphStats {
     readonly failureCount: number;
     readonly hungCount: number;
 }
+/** A stitched distributed trace spanning multiple execution graphs. */
+interface DistributedTrace {
+    readonly traceId: string;
+    readonly graphs: ReadonlyMap<string, ExecutionGraph>;
+    readonly rootGraph: ExecutionGraph;
+    readonly childMap: ReadonlyMap<string, readonly string[]>;
+    readonly startTime: number;
+    readonly endTime: number | null;
+    readonly status: GraphStatus;
+}
 /** @internal Mutable version of ExecutionNode used during graph construction. */
 interface MutableExecutionNode {
     id: string;
@@ -251,6 +276,59 @@ 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[];
+
 /**
  * Pure query functions for interrogating a built `ExecutionGraph`.
  * Every function takes a frozen graph and returns derived data without mutation.
@@ -367,4 +445,4 @@ declare function getDepth(graph: ExecutionGraph): number;
  */
 declare function getStats(graph: ExecutionGraph): GraphStats;
 
-export { type Adapter, type AgentFlowConfig, 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 };
+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 };