agentflow-core 0.1.2 → 0.1.3

package/dist/cli.cjs

@@ -0,0 +1,542 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli.ts
+var import_path = require("path");
+
+// src/runner.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/graph-builder.ts
+var import_crypto = require("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 = (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();
+  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 getNode(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 = getNode(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 = getNode(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();
+      getNode(from);
+      getNode(to);
+      edges.push({ from, to, type });
+      recordEvent(from, "custom", { to, type, action: "edge_add" });
+    },
+    pushEvent(event) {
+      assertNotBuilt();
+      getNode(event.nodeId);
+      events.push({
+        ...event,
+        timestamp: Date.now()
+      });
+    },
+    updateState(nodeId, state) {
+      assertNotBuilt();
+      const node = getNode(nodeId);
+      Object.assign(node.state, state);
+      recordEvent(nodeId, "custom", { action: "state_update", ...state });
+    },
+    withParent(parentId, fn) {
+      assertNotBuilt();
+      getNode(parentId);
+      parentStack.push(parentId);
+      try {
+        return fn();
+      } finally {
+        parentStack.pop();
+      }
+    },
+    getSnapshot() {
+      return buildGraph();
+    },
+    build() {
+      assertNotBuilt();
+      const graph = buildGraph();
+      built = true;
+      return graph;
+    }
+  };
+  return builder;
+}
+
+// src/runner.ts
+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/cli.ts
+function parseArgs(argv) {
+  const result = {
+    tracesDir: "./traces",
+    watchDirs: [],
+    watchPatterns: ["*.json"],
+    trigger: "cli",
+    command: []
+  };
+  const dashDashIdx = argv.indexOf("--");
+  const flagArgs = dashDashIdx === -1 ? argv : argv.slice(0, dashDashIdx);
+  const commandArgs = dashDashIdx === -1 ? [] : argv.slice(dashDashIdx + 1);
+  let i = 0;
+  while (i < flagArgs.length) {
+    const arg = flagArgs[i];
+    switch (arg) {
+      case "run":
+        i++;
+        break;
+      case "--traces-dir":
+        i++;
+        result.tracesDir = flagArgs[i] ?? result.tracesDir;
+        i++;
+        break;
+      case "--watch-dir":
+        i++;
+        if (flagArgs[i]) {
+          result.watchDirs.push(flagArgs[i]);
+        }
+        i++;
+        break;
+      case "--watch-pattern":
+        i++;
+        if (flagArgs[i]) {
+          if (result.watchPatterns.length === 1 && result.watchPatterns[0] === "*.json") {
+            result.watchPatterns = [];
+          }
+          result.watchPatterns.push(flagArgs[i]);
+        }
+        i++;
+        break;
+      case "--agent-id":
+        i++;
+        result.agentId = flagArgs[i];
+        i++;
+        break;
+      case "--trigger":
+        i++;
+        result.trigger = flagArgs[i] ?? result.trigger;
+        i++;
+        break;
+      default:
+        i++;
+        break;
+    }
+  }
+  result.command = commandArgs;
+  return result;
+}
+function printUsage() {
+  console.log(`
+AgentFlow CLI \u2014 Wrap any command with automatic execution tracing.
+
+Usage:
+  agentflow run [options] -- <command>
+
+Options:
+  --traces-dir <path>     Directory to save trace files (default: ./traces)
+  --watch-dir <path>      Directory to watch for state changes (repeatable)
+  --watch-pattern <glob>  File pattern to watch (default: *.json)
+  --agent-id <name>       Agent ID for the orchestrator trace
+  --trigger <name>        Trigger label (default: cli)
+  --help                  Show this help message
+
+Examples:
+  agentflow run -- python -m alfred process
+  agentflow run --watch-dir /home/trader/.alfred/data -- python -m alfred process
+  agentflow run --traces-dir ./my-traces --agent-id alfred -- node worker.js
+`.trim());
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+  const parsed = parseArgs(argv);
+  if (parsed.command.length === 0) {
+    console.error("Error: No command specified. Use -- to separate agentflow flags from the command.");
+    console.error("Example: agentflow run -- python -m alfred process");
+    process.exit(1);
+  }
+  const commandStr = parsed.command.join(" ");
+  const watchSummary = parsed.watchDirs.length > 0 ? parsed.watchDirs.map((d) => `${d} (${parsed.watchPatterns.join(", ")})`).join(", ") : "(none)";
+  console.log(`
+\u{1F50D} AgentFlow: Tracing command: ${commandStr}`);
+  console.log(`\u{1F4C1} Traces: ${parsed.tracesDir}`);
+  console.log(`\u{1F441}\uFE0F  Watching: ${watchSummary}`);
+  console.log("");
+  const config = {
+    command: parsed.command,
+    tracesDir: parsed.tracesDir,
+    watchDirs: parsed.watchDirs,
+    watchPatterns: parsed.watchPatterns,
+    trigger: parsed.trigger
+  };
+  if (parsed.agentId) {
+    config.agentId = parsed.agentId;
+  }
+  try {
+    const result = await runTraced(config);
+    console.log("");
+    console.log(`\u2705 Command completed (exit code ${result.exitCode}, ${result.duration.toFixed(1)}s)`);
+    if (result.tracePaths.length > 0) {
+      console.log("\u{1F4DD} Traces saved:");
+      const orchPath = result.tracePaths[0];
+      const orchName = (0, import_path.basename)(orchPath, ".json").split("-")[0] ?? "orchestrator";
+      console.log(`   ${orchName.padEnd(14)} \u2192 ${orchPath}`);
+      for (let i = 1; i < result.tracePaths.length; i++) {
+        const tPath = result.tracePaths[i];
+        const name = (0, import_path.basename)(tPath, ".json").replace(/-\d{4}-.*$/, "");
+        const isLast = i === result.tracePaths.length - 1;
+        const prefix = isLast ? "\u2514\u2500" : "\u251C\u2500";
+        console.log(`   ${prefix} ${name.padEnd(12)} \u2192 ${tPath} (state changed)`);
+      }
+    }
+    console.log(`\u{1F517} Trace ID: ${result.traceId}`);
+    console.log("");
+    process.exit(result.exitCode);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`\u274C AgentFlow error: ${message}`);
+    process.exit(1);
+  }
+}
+main();

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import {
+  runTraced
+} from "./chunk-DGLK6IBP.js";
+
+// src/cli.ts
+import { basename } from "path";
+function parseArgs(argv) {
+  const result = {
+    tracesDir: "./traces",
+    watchDirs: [],
+    watchPatterns: ["*.json"],
+    trigger: "cli",
+    command: []
+  };
+  const dashDashIdx = argv.indexOf("--");
+  const flagArgs = dashDashIdx === -1 ? argv : argv.slice(0, dashDashIdx);
+  const commandArgs = dashDashIdx === -1 ? [] : argv.slice(dashDashIdx + 1);
+  let i = 0;
+  while (i < flagArgs.length) {
+    const arg = flagArgs[i];
+    switch (arg) {
+      case "run":
+        i++;
+        break;
+      case "--traces-dir":
+        i++;
+        result.tracesDir = flagArgs[i] ?? result.tracesDir;
+        i++;
+        break;
+      case "--watch-dir":
+        i++;
+        if (flagArgs[i]) {
+          result.watchDirs.push(flagArgs[i]);
+        }
+        i++;
+        break;
+      case "--watch-pattern":
+        i++;
+        if (flagArgs[i]) {
+          if (result.watchPatterns.length === 1 && result.watchPatterns[0] === "*.json") {
+            result.watchPatterns = [];
+          }
+          result.watchPatterns.push(flagArgs[i]);
+        }
+        i++;
+        break;
+      case "--agent-id":
+        i++;
+        result.agentId = flagArgs[i];
+        i++;
+        break;
+      case "--trigger":
+        i++;
+        result.trigger = flagArgs[i] ?? result.trigger;
+        i++;
+        break;
+      default:
+        i++;
+        break;
+    }
+  }
+  result.command = commandArgs;
+  return result;
+}
+function printUsage() {
+  console.log(`
+AgentFlow CLI \u2014 Wrap any command with automatic execution tracing.
+
+Usage:
+  agentflow run [options] -- <command>
+
+Options:
+  --traces-dir <path>     Directory to save trace files (default: ./traces)
+  --watch-dir <path>      Directory to watch for state changes (repeatable)
+  --watch-pattern <glob>  File pattern to watch (default: *.json)
+  --agent-id <name>       Agent ID for the orchestrator trace
+  --trigger <name>        Trigger label (default: cli)
+  --help                  Show this help message
+
+Examples:
+  agentflow run -- python -m alfred process
+  agentflow run --watch-dir /home/trader/.alfred/data -- python -m alfred process
+  agentflow run --traces-dir ./my-traces --agent-id alfred -- node worker.js
+`.trim());
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+  const parsed = parseArgs(argv);
+  if (parsed.command.length === 0) {
+    console.error("Error: No command specified. Use -- to separate agentflow flags from the command.");
+    console.error("Example: agentflow run -- python -m alfred process");
+    process.exit(1);
+  }
+  const commandStr = parsed.command.join(" ");
+  const watchSummary = parsed.watchDirs.length > 0 ? parsed.watchDirs.map((d) => `${d} (${parsed.watchPatterns.join(", ")})`).join(", ") : "(none)";
+  console.log(`
+\u{1F50D} AgentFlow: Tracing command: ${commandStr}`);
+  console.log(`\u{1F4C1} Traces: ${parsed.tracesDir}`);
+  console.log(`\u{1F441}\uFE0F  Watching: ${watchSummary}`);
+  console.log("");
+  const config = {
+    command: parsed.command,
+    tracesDir: parsed.tracesDir,
+    watchDirs: parsed.watchDirs,
+    watchPatterns: parsed.watchPatterns,
+    trigger: parsed.trigger
+  };
+  if (parsed.agentId) {
+    config.agentId = parsed.agentId;
+  }
+  try {
+    const result = await runTraced(config);
+    console.log("");
+    console.log(`\u2705 Command completed (exit code ${result.exitCode}, ${result.duration.toFixed(1)}s)`);
+    if (result.tracePaths.length > 0) {
+      console.log("\u{1F4DD} Traces saved:");
+      const orchPath = result.tracePaths[0];
+      const orchName = basename(orchPath, ".json").split("-")[0] ?? "orchestrator";
+      console.log(`   ${orchName.padEnd(14)} \u2192 ${orchPath}`);
+      for (let i = 1; i < result.tracePaths.length; i++) {
+        const tPath = result.tracePaths[i];
+        const name = basename(tPath, ".json").replace(/-\d{4}-.*$/, "");
+        const isLast = i === result.tracePaths.length - 1;
+        const prefix = isLast ? "\u2514\u2500" : "\u251C\u2500";
+        console.log(`   ${prefix} ${name.padEnd(12)} \u2192 ${tPath} (state changed)`);
+      }
+    }
+    console.log(`\u{1F517} Trace ID: ${result.traceId}`);
+    console.log("");
+    process.exit(result.exitCode);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`\u274C AgentFlow error: ${message}`);
+    process.exit(1);
+  }
+}
+main();