@specrun/cli 0.1.0-beta1

package/dist/index.js

@@ -0,0 +1,1281 @@
+#!/usr/bin/env node
+
+// src/cli/root.ts
+import { Command as Command4 } from "commander";
+
+// src/cli/run.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { Command as Command2 } from "commander";
+
+// src/spec/parser.ts
+function parseFlow(data) {
+  let raw;
+  try {
+    raw = JSON.parse(typeof data === "string" ? data : data.toString());
+  } catch (err) {
+    throw new Error(`spec: failed to parse component: ${err}`);
+  }
+  const base = raw;
+  if (base.component_type !== "Flow") {
+    throw new Error(
+      `spec: expected component_type 'Flow', got "${base.component_type}"`
+    );
+  }
+  const flow = raw;
+  const parsed = {
+    ...flow,
+    parsedNodes: []
+  };
+  if (!Array.isArray(flow.nodes)) {
+    throw new Error("spec: failed to parse flow: nodes must be an array");
+  }
+  for (let i = 0; i < flow.nodes.length; i++) {
+    try {
+      const node = parseNode(flow.nodes[i]);
+      parsed.parsedNodes.push(node);
+    } catch (err) {
+      throw new Error(`spec: failed to parse node ${i}: ${err}`);
+    }
+  }
+  return parsed;
+}
+function parseNode(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("spec: failed to parse node base: not an object");
+  }
+  const base = data;
+  switch (base.component_type) {
+    case "StartNode":
+      return data;
+    case "EndNode":
+      return data;
+    case "AgentNode":
+      return data;
+    case "ToolNode":
+      return data;
+    case "LlmNode":
+      return data;
+    case "BranchingNode":
+      return data;
+    default:
+      throw new Error(
+        `spec: unknown component_type "${base.component_type}"`
+      );
+  }
+}
+
+// src/spec/validate.ts
+function validateFlow(pf) {
+  const errs = [];
+  if (!pf.name) {
+    errs.push("flow name is required");
+  }
+  if (pf.component_type !== "Flow") {
+    errs.push(
+      `expected component_type 'Flow', got "${pf.component_type}"`
+    );
+  }
+  if (pf.parsedNodes.length === 0) {
+    errs.push("flow must have at least one node");
+  }
+  let hasStart = false;
+  let hasEnd = false;
+  const nodeNames = /* @__PURE__ */ new Map();
+  for (const n of pf.parsedNodes) {
+    const name = n.name;
+    const count = (nodeNames.get(name) ?? 0) + 1;
+    nodeNames.set(name, count);
+    if (count > 1) {
+      errs.push(`duplicate node name "${name}"`);
+    }
+    if (n.component_type === "StartNode") {
+      hasStart = true;
+    }
+    if (n.component_type === "EndNode") {
+      hasEnd = true;
+    }
+  }
+  if (!hasStart) {
+    errs.push("flow must have a StartNode");
+  }
+  if (!hasEnd) {
+    errs.push("flow must have an EndNode");
+  }
+  for (let i = 0; i < pf.control_flow_connections.length; i++) {
+    const edge = pf.control_flow_connections[i];
+    if (!nodeNames.has(edge.from_node)) {
+      errs.push(
+        `control_flow_connections[${i}]: from_node "${edge.from_node}" not found`
+      );
+    }
+    if (!nodeNames.has(edge.to_node)) {
+      errs.push(
+        `control_flow_connections[${i}]: to_node "${edge.to_node}" not found`
+      );
+    }
+  }
+  const dataEdges = pf.data_flow_connections ?? [];
+  for (let i = 0; i < dataEdges.length; i++) {
+    const edge = dataEdges[i];
+    if (!nodeNames.has(edge.source_node)) {
+      errs.push(
+        `data_flow_connections[${i}]: source_node "${edge.source_node}" not found`
+      );
+    }
+    if (!nodeNames.has(edge.destination_node)) {
+      errs.push(
+        `data_flow_connections[${i}]: destination_node "${edge.destination_node}" not found`
+      );
+    }
+  }
+  for (const n of pf.parsedNodes) {
+    if (n.component_type === "AgentNode") {
+      if (!n.agent) {
+        errs.push(`AgentNode "${n.name}" must have an agent`);
+      } else {
+        if (!n.agent.system_prompt) {
+          errs.push(
+            `AgentNode "${n.name}": agent must have a system_prompt`
+          );
+        }
+        if (!n.agent.llm_config) {
+          errs.push(
+            `AgentNode "${n.name}": agent must have llm_config`
+          );
+        }
+      }
+    }
+    if (n.component_type === "LlmNode") {
+      if (!n.prompt_template) {
+        errs.push(`LlmNode "${n.name}" must have a prompt_template`);
+      }
+      if (!n.llm_config) {
+        errs.push(`LlmNode "${n.name}" must have llm_config`);
+      }
+    }
+    if (n.component_type === "BranchingNode") {
+      if (!n.mapping || Object.keys(n.mapping).length === 0) {
+        errs.push(
+          `BranchingNode "${n.name}" must have a non-empty mapping`
+        );
+      }
+    }
+    if (n.component_type === "ToolNode") {
+      if (!n.tool) {
+        errs.push(`ToolNode "${n.name}" must have a tool`);
+      }
+    }
+  }
+  if (errs.length > 0) {
+    throw new Error(`validate: ${errs.join("; ")}`);
+  }
+}
+
+// src/node/branching.ts
+var DEFAULT_BRANCH = "DEFAULT_BRANCH";
+var BranchingExecutor = class {
+  node;
+  _branch = "";
+  constructor(node, _deps) {
+    this.node = node;
+  }
+  branch() {
+    return this._branch;
+  }
+  async execute(_signal, input) {
+    let [keyValue, ok] = input.getString("branching_mapping_key");
+    if (!ok) {
+      for (const key of input.keys()) {
+        const [v, found] = input.getString(key);
+        if (found) {
+          keyValue = v;
+          break;
+        }
+      }
+      if (!keyValue) {
+        throw new Error(
+          `run: BranchingNode "${this.node.name}": no branching_mapping_key in input`
+        );
+      }
+    }
+    if (keyValue in this.node.mapping) {
+      this._branch = this.node.mapping[keyValue];
+    } else if (DEFAULT_BRANCH in this.node.mapping) {
+      this._branch = this.node.mapping[DEFAULT_BRANCH];
+    } else {
+      this._branch = "default";
+    }
+    return input.clone();
+  }
+};
+var StartExecutor = class {
+  constructor(node) {
+    this.node = node;
+  }
+  branch() {
+    return "";
+  }
+  async execute(_signal, input) {
+    return input.clone();
+  }
+};
+var EndExecutor = class {
+  constructor(node) {
+    this.node = node;
+  }
+  branch() {
+    return "";
+  }
+  async execute(_signal, input) {
+    return input.clone();
+  }
+};
+
+// src/spec/types.ts
+function propertyTitle(p) {
+  const t = p.json_schema["title"];
+  return typeof t === "string" ? t : "";
+}
+
+// src/state/state.ts
+var State = class _State {
+  data;
+  constructor(data) {
+    this.data = data ? { ...data } : {};
+  }
+  /** Get retrieves a value by key. */
+  get(key) {
+    if (key in this.data) {
+      return [this.data[key], true];
+    }
+    return [void 0, false];
+  }
+  /** GetString retrieves a string value by key. */
+  getString(key) {
+    const [v, ok] = this.get(key);
+    if (!ok) return ["", false];
+    if (typeof v === "string") return [v, true];
+    return ["", false];
+  }
+  /** Set returns a new State with the given key-value pair added/replaced. */
+  set(key, value) {
+    const newData = { ...this.data };
+    newData[key] = value;
+    return new _State(newData);
+  }
+  /** Merge returns a new State with all key-value pairs from other merged in. */
+  merge(other) {
+    const newData = { ...this.data, ...other.data };
+    return new _State(newData);
+  }
+  /** Clone returns a deep copy of this State. */
+  clone() {
+    return new _State({ ...this.data });
+  }
+  /** Keys returns all keys in the state. */
+  keys() {
+    return Object.keys(this.data);
+  }
+  /** Data returns the underlying map (as a copy). */
+  toData() {
+    return { ...this.data };
+  }
+  /** toJSON serializes State to a plain object for JSON.stringify. */
+  toJSON() {
+    return { ...this.data };
+  }
+  /** String returns a JSON string representation. */
+  toString() {
+    try {
+      return JSON.stringify(this.data);
+    } catch (err) {
+      return `<error: ${err}>`;
+    }
+  }
+};
+
+// src/node/agent.ts
+var MAX_TOOL_ROUNDS = 10;
+var AgentExecutor = class {
+  node;
+  deps;
+  constructor(node, deps) {
+    this.node = node;
+    this.deps = deps;
+  }
+  branch() {
+    return "";
+  }
+  async execute(signal, input) {
+    const agent = this.node.agent;
+    if (!agent) {
+      throw new Error(`run: AgentNode "${this.node.name}" has no agent`);
+    }
+    if (!this.deps.llmProvider) {
+      throw new Error(
+        `run: AgentNode "${this.node.name}": no LLM provider configured`
+      );
+    }
+    const systemPrompt = substituteTemplate(
+      agent.system_prompt ?? "",
+      input
+    );
+    const toolDefs = [];
+    if (agent.tools) {
+      for (const t of agent.tools) {
+        toolDefs.push({
+          name: t.name,
+          description: t.description ?? "",
+          parameters: buildToolSchema(t)
+        });
+      }
+    }
+    const messages = [
+      { role: "system", content: systemPrompt }
+    ];
+    const inputJSON = JSON.stringify(input.toData());
+    messages.push({ role: "user", content: inputJSON });
+    let model = "gpt-4o";
+    if (agent.llm_config?.model_id) {
+      model = agent.llm_config.model_id;
+    }
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+      const resp = await this.deps.llmProvider.chatCompletion(signal, {
+        model,
+        messages,
+        tools: toolDefs.length > 0 ? toolDefs : void 0
+      });
+      if (!resp.tool_calls || resp.tool_calls.length === 0) {
+        let output = new State();
+        output = output.set("result", resp.content);
+        if (resp.content) {
+          try {
+            const parsed = JSON.parse(resp.content);
+            for (const [k, v] of Object.entries(parsed)) {
+              output = output.set(k, v);
+            }
+          } catch {
+          }
+        }
+        return output;
+      }
+      messages.push({
+        role: "assistant",
+        content: resp.content,
+        tool_calls: resp.tool_calls
+      });
+      for (const tc of resp.tool_calls) {
+        try {
+          const toolResult = await this.executeTool(signal, tc);
+          const resultJSON = JSON.stringify(toolResult);
+          if (this.deps.verbose) {
+            console.error(`  Tool "${tc.name}" result: ${resultJSON}`);
+          }
+          messages.push({
+            role: "tool",
+            tool_call_id: tc.id,
+            content: resultJSON
+          });
+        } catch (err) {
+          if (this.deps.verbose) {
+            console.error(`  Tool "${tc.name}" error: ${err}`);
+          }
+          messages.push({
+            role: "tool",
+            tool_call_id: tc.id,
+            content: `Error: ${err}`
+          });
+        }
+      }
+    }
+    throw new Error(
+      `run: AgentNode "${this.node.name}" exceeded max tool rounds (${MAX_TOOL_ROUNDS})`
+    );
+  }
+  async executeTool(signal, tc) {
+    let args;
+    try {
+      args = JSON.parse(tc.arguments);
+    } catch (err) {
+      throw new Error(`failed to parse tool arguments: ${err}`);
+    }
+    if (!this.deps.toolRegistry) {
+      throw new Error(`tool "${tc.name}" not found in registry`);
+    }
+    const [toolDef, ok] = this.deps.toolRegistry.lookup(tc.name);
+    if (!ok) {
+      throw new Error(`tool "${tc.name}" not found in registry`);
+    }
+    if (this.deps.verbose) {
+      console.error(
+        `  Executing tool "${tc.name}" with args: ${JSON.stringify(args)}`
+      );
+    }
+    if (!this.deps.toolExecutor) {
+      throw new Error(`no tool executor configured`);
+    }
+    const result = await this.deps.toolExecutor.execute(
+      signal,
+      toolDef.path,
+      args
+    );
+    return result.output;
+  }
+};
+function substituteTemplate(template, s) {
+  let result = template;
+  for (const key of s.keys()) {
+    const [v] = s.getString(key);
+    result = result.replaceAll(`{{${key}}}`, v);
+  }
+  return result;
+}
+function buildToolSchema(t) {
+  const properties = {};
+  const required = [];
+  if (t.inputs) {
+    for (const input of t.inputs) {
+      const name = propertyTitle(input);
+      if (!name) continue;
+      const prop = {};
+      for (const [k, v] of Object.entries(input.json_schema)) {
+        if (k !== "title") {
+          prop[k] = v;
+        }
+      }
+      properties[name] = prop;
+      required.push(name);
+    }
+  }
+  return {
+    type: "object",
+    properties,
+    required
+  };
+}
+
+// src/node/llm.ts
+var LLMExecutor = class {
+  node;
+  deps;
+  constructor(node, deps) {
+    this.node = node;
+    this.deps = deps;
+  }
+  branch() {
+    return "";
+  }
+  async execute(signal, input) {
+    if (!this.deps.llmProvider) {
+      throw new Error(
+        `run: LlmNode "${this.node.name}": no LLM provider configured`
+      );
+    }
+    const prompt = substituteTemplate(this.node.prompt_template, input);
+    let model = "gpt-4o";
+    if (this.node.llm_config?.model_id) {
+      model = this.node.llm_config.model_id;
+    }
+    const resp = await this.deps.llmProvider.chatCompletion(signal, {
+      model,
+      messages: [{ role: "user", content: prompt }]
+    });
+    let output = new State();
+    output = output.set("generated_text", resp.content);
+    return output;
+  }
+};
+
+// src/node/tool.ts
+var ToolNodeExecutor = class {
+  node;
+  deps;
+  constructor(node, deps) {
+    this.node = node;
+    this.deps = deps;
+  }
+  branch() {
+    return "";
+  }
+  async execute(signal, input) {
+    if (!this.node.tool) {
+      throw new Error(`run: ToolNode "${this.node.name}" has no tool`);
+    }
+    if (!this.deps.toolRegistry) {
+      throw new Error(
+        `run: ToolNode "${this.node.name}": no tool registry configured`
+      );
+    }
+    const [toolDef, ok] = this.deps.toolRegistry.lookup(this.node.tool.name);
+    if (!ok) {
+      throw new Error(
+        `run: ToolNode "${this.node.name}": tool "${this.node.tool.name}" not found`
+      );
+    }
+    if (!this.deps.toolExecutor) {
+      throw new Error(
+        `run: ToolNode "${this.node.name}": no tool executor configured`
+      );
+    }
+    const result = await this.deps.toolExecutor.execute(
+      signal,
+      toolDef.path,
+      input.toData()
+    );
+    return new State(result.output);
+  }
+};
+
+// src/graph/types.ts
+var CompiledGraph = class {
+  name;
+  nodes;
+  start;
+  dataFlowEdges;
+  constructor(name, nodes, start, dataFlowEdges) {
+    this.name = name;
+    this.nodes = nodes;
+    this.start = start;
+    this.dataFlowEdges = dataFlowEdges;
+  }
+  /** GetNode returns a compiled node by name. */
+  getNode(name) {
+    const n = this.nodes.get(name);
+    if (n) return [n, true];
+    return [void 0, false];
+  }
+  /** NextNode resolves the next node from the current node. */
+  nextNode(current, branch) {
+    for (const edge of current.edges) {
+      if (branch === "" && (edge.from_branch ?? "") === "") {
+        const next = this.nodes.get(edge.to_node);
+        if (next) return [next, true];
+      }
+      if (branch !== "" && edge.from_branch === branch) {
+        const next = this.nodes.get(edge.to_node);
+        if (next) return [next, true];
+      }
+    }
+    if (branch !== "") {
+      for (const edge of current.edges) {
+        if ((edge.from_branch ?? "") === "") {
+          const next = this.nodes.get(edge.to_node);
+          if (next) return [next, true];
+        }
+      }
+    }
+    return [void 0, false];
+  }
+};
+
+// src/graph/compile.ts
+function compile(pf, deps) {
+  const nodes = /* @__PURE__ */ new Map();
+  let start = "";
+  for (const n of pf.parsedNodes) {
+    const name = n.name;
+    const executor = buildExecutor(n, deps);
+    const cn = {
+      name,
+      type: n.component_type,
+      specNode: n,
+      executor,
+      edges: [],
+      inputMappings: /* @__PURE__ */ new Map()
+    };
+    if (n.component_type === "StartNode") {
+      start = name;
+    }
+    nodes.set(name, cn);
+  }
+  if (!start) {
+    throw new Error("compile: no StartNode found");
+  }
+  for (const edge of pf.control_flow_connections) {
+    const cn = nodes.get(edge.from_node);
+    if (!cn) {
+      throw new Error(
+        `compile: control flow edge from_node "${edge.from_node}" not found`
+      );
+    }
+    cn.edges.push(edge);
+  }
+  const dataEdges = pf.data_flow_connections ?? [];
+  for (const edge of dataEdges) {
+    const cn = nodes.get(edge.destination_node);
+    if (!cn) {
+      throw new Error(
+        `compile: data flow edge destination_node "${edge.destination_node}" not found`
+      );
+    }
+    cn.inputMappings.set(edge.destination_input, {
+      sourceNode: edge.source_node,
+      sourceOutput: edge.source_output
+    });
+  }
+  return new CompiledGraph(pf.name, nodes, start, dataEdges);
+}
+function buildExecutor(n, deps) {
+  switch (n.component_type) {
+    case "StartNode":
+      return new StartExecutor(n);
+    case "EndNode":
+      return new EndExecutor(n);
+    case "AgentNode":
+      return new AgentExecutor(n, deps);
+    case "LlmNode":
+      return new LLMExecutor(n, deps);
+    case "ToolNode":
+      return new ToolNodeExecutor(n, deps);
+    case "BranchingNode":
+      return new BranchingExecutor(n, deps);
+    default:
+      throw new Error(
+        `unknown node type: ${n.component_type}`
+      );
+  }
+}
+
+// src/graph/validate.ts
+function validate(g) {
+  const errs = [];
+  if (!g.start) {
+    errs.push("no start node");
+  }
+  const reachable = /* @__PURE__ */ new Set();
+  const walk = (name) => {
+    if (reachable.has(name)) return;
+    reachable.add(name);
+    const cn = g.nodes.get(name);
+    if (!cn) return;
+    for (const edge of cn.edges) {
+      walk(edge.to_node);
+    }
+  };
+  walk(g.start);
+  for (const name of g.nodes.keys()) {
+    if (!reachable.has(name)) {
+      errs.push(`node "${name}" is unreachable from start`);
+    }
+  }
+  let hasReachableEnd = false;
+  for (const [name, cn] of g.nodes) {
+    if (cn.type === "EndNode" && reachable.has(name)) {
+      hasReachableEnd = true;
+      break;
+    }
+  }
+  if (!hasReachableEnd) {
+    errs.push("no reachable EndNode from start");
+  }
+  for (const [name, cn] of g.nodes) {
+    if (cn.type === "EndNode") continue;
+    if (!reachable.has(name)) continue;
+    if (cn.edges.length === 0) {
+      errs.push(`node "${name}" has no outgoing edges`);
+    }
+  }
+  if (errs.length > 0) {
+    throw new Error(`validate: ${errs.join("; ")}`);
+  }
+}
+
+// src/tool/registry.ts
+import { readdirSync, statSync } from "fs";
+import { join, extname } from "path";
+var FileRegistry = class _FileRegistry {
+  tools;
+  constructor(tools) {
+    this.tools = tools;
+  }
+  /** Creates a registry by scanning the given directory for executables. */
+  static create(toolsDir) {
+    const tools = /* @__PURE__ */ new Map();
+    if (!toolsDir) {
+      return new _FileRegistry(tools);
+    }
+    let info;
+    try {
+      info = statSync(toolsDir);
+    } catch (err) {
+      throw new Error(`tool: tools directory "${toolsDir}": ${err}`);
+    }
+    if (!info.isDirectory()) {
+      throw new Error(`tool: "${toolsDir}" is not a directory`);
+    }
+    const entries = readdirSync(toolsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) continue;
+      const path = join(toolsDir, entry.name);
+      let entryInfo;
+      try {
+        entryInfo = statSync(path);
+      } catch {
+        continue;
+      }
+      if ((entryInfo.mode & 73) === 0) continue;
+      const ext = extname(entry.name);
+      const name = ext ? entry.name.slice(0, -ext.length) : entry.name;
+      tools.set(name, {
+        name,
+        description: "",
+        path
+      });
+    }
+    return new _FileRegistry(tools);
+  }
+  lookup(name) {
+    const t = this.tools.get(name);
+    if (t) return [t, true];
+    return [{ name: "", description: "", path: "" }, false];
+  }
+  all() {
+    return Array.from(this.tools.values());
+  }
+  /** Checks that all tool names in the spec have matching executables. */
+  validateTools(toolNames) {
+    const missing = [];
+    for (const name of toolNames) {
+      if (!this.tools.has(name)) {
+        missing.push(name);
+      }
+    }
+    if (missing.length > 0) {
+      throw new Error(
+        `tool: missing executables for tools: ${missing.join(", ")}`
+      );
+    }
+  }
+};
+
+// src/tool/executor.ts
+import { spawn } from "child_process";
+var DEFAULT_TIMEOUT = 3e4;
+var SubprocessExecutor = class {
+  timeout;
+  constructor(timeout) {
+    this.timeout = timeout ?? DEFAULT_TIMEOUT;
+  }
+  async execute(signal, toolPath, input) {
+    const inputJSON = JSON.stringify(input);
+    return new Promise((resolve, reject) => {
+      const ac = new AbortController();
+      const timer = setTimeout(() => {
+        ac.abort();
+        reject(
+          new Error(
+            `tool: execution timed out after ${this.timeout}ms`
+          )
+        );
+      }, this.timeout);
+      if (signal?.aborted) {
+        clearTimeout(timer);
+        reject(new Error("tool: execution aborted"));
+        return;
+      }
+      const onExternalAbort = () => {
+        ac.abort();
+        clearTimeout(timer);
+        reject(new Error("tool: execution aborted"));
+      };
+      signal?.addEventListener("abort", onExternalAbort, { once: true });
+      const proc = spawn(toolPath, [], {
+        stdio: ["pipe", "pipe", "pipe"],
+        signal: ac.signal
+      });
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+      proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+      proc.on("error", (err) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onExternalAbort);
+        if (ac.signal.aborted) return;
+        const stderrStr = Buffer.concat(stderrChunks).toString();
+        reject(
+          new Error(`tool: execution failed: ${err.message}: ${stderrStr}`)
+        );
+      });
+      proc.on("close", (code) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onExternalAbort);
+        const stderrStr = Buffer.concat(stderrChunks).toString();
+        if (code !== 0) {
+          reject(
+            new Error(
+              `tool: execution failed: exit code ${code}: ${stderrStr}`
+            )
+          );
+          return;
+        }
+        const stdoutStr = Buffer.concat(stdoutChunks).toString();
+        let output;
+        if (stdoutStr.length > 0) {
+          try {
+            output = JSON.parse(stdoutStr);
+          } catch (err) {
+            reject(
+              new Error(
+                `tool: failed to parse output JSON: ${err}: raw output: ${stdoutStr}`
+              )
+            );
+            return;
+          }
+        } else {
+          output = {};
+        }
+        resolve({ output, stderr: stderrStr });
+      });
+      proc.stdin.write(inputJSON);
+      proc.stdin.end();
+    });
+  }
+};
+
+// src/llm/openai.ts
+import OpenAI from "openai";
+var OpenAIProvider = class {
+  client;
+  constructor(opts) {
+    this.client = new OpenAI(opts);
+  }
+  async chatCompletion(signal, req) {
+    const messages = req.messages.map((msg) => {
+      switch (msg.role) {
+        case "system":
+          return {
+            role: "system",
+            content: msg.content
+          };
+        case "user":
+          return { role: "user", content: msg.content };
+        case "assistant": {
+          if (msg.tool_calls && msg.tool_calls.length > 0) {
+            return {
+              role: "assistant",
+              content: msg.content,
+              tool_calls: msg.tool_calls.map((tc) => ({
+                id: tc.id,
+                type: "function",
+                function: {
+                  name: tc.name,
+                  arguments: tc.arguments
+                }
+              }))
+            };
+          }
+          return {
+            role: "assistant",
+            content: msg.content
+          };
+        }
+        case "tool":
+          return {
+            role: "tool",
+            tool_call_id: msg.tool_call_id,
+            content: msg.content
+          };
+      }
+    });
+    const tools = req.tools && req.tools.length > 0 ? req.tools.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters
+      }
+    })) : void 0;
+    try {
+      const completion = await this.client.chat.completions.create(
+        {
+          model: req.model,
+          messages,
+          tools
+        },
+        { signal }
+      );
+      if (!completion.choices || completion.choices.length === 0) {
+        throw new Error("llm: no choices in response");
+      }
+      const choice = completion.choices[0];
+      const resp = {
+        content: choice.message.content ?? "",
+        finish_reason: choice.finish_reason ?? ""
+      };
+      if (choice.message.tool_calls && choice.message.tool_calls.length > 0) {
+        resp.tool_calls = choice.message.tool_calls.map(
+          (tc) => ({
+            id: tc.id,
+            name: tc.function.name,
+            arguments: tc.function.arguments
+          })
+        );
+      }
+      return resp;
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("llm:")) throw err;
+      throw new Error(`llm: OpenAI API error: ${err}`);
+    }
+  }
+};
+
+// src/runner/runner.ts
+var Runner = class {
+  graph;
+  opts;
+  constructor(graph, opts) {
+    this.graph = graph;
+    this.opts = opts;
+  }
+  /** Run executes the flow with the given initial inputs. */
+  async run(signal, inputs) {
+    const timeoutSignal = AbortSignal.timeout(this.opts.timeout);
+    const combinedAc = new AbortController();
+    const onTimeout = () => combinedAc.abort();
+    const onExternal = () => combinedAc.abort();
+    timeoutSignal.addEventListener("abort", onTimeout, { once: true });
+    signal?.addEventListener("abort", onExternal, { once: true });
+    const effectiveSignal = combinedAc.signal;
+    try {
+      return await this._run(effectiveSignal, inputs);
+    } finally {
+      timeoutSignal.removeEventListener("abort", onTimeout);
+      signal?.removeEventListener("abort", onExternal);
+    }
+  }
+  async _run(signal, inputs) {
+    this.emit({ type: "flow_start" });
+    const nodeOutputs = /* @__PURE__ */ new Map();
+    const [startNode, ok] = this.graph.getNode(this.graph.start);
+    if (!ok) {
+      throw new Error(`run: start node "${this.graph.start}" not found`);
+    }
+    let current = startNode;
+    let currentState = new State(inputs);
+    for (let iteration = 0; iteration < this.opts.maxIterations; iteration++) {
+      if (signal.aborted) {
+        throw new Error("run: context cancelled: operation was aborted");
+      }
+      if (this.opts.verbose) {
+        console.error(
+          `Executing node: ${current.name} (${current.type})`
+        );
+      }
+      this.emit({
+        type: "node_start",
+        nodeName: current.name,
+        nodeType: current.type,
+        state: currentState
+      });
+      const nodeInput = this.resolveInputs(
+        current,
+        nodeOutputs,
+        currentState
+      );
+      let output;
+      try {
+        output = await current.executor.execute(signal, nodeInput);
+      } catch (err) {
+        const execErr = err instanceof Error ? err : new Error(String(err));
+        this.emit({
+          type: "node_error",
+          nodeName: current.name,
+          nodeType: current.type,
+          error: execErr
+        });
+        throw execErr;
+      }
+      nodeOutputs.set(current.name, output);
+      this.emit({
+        type: "node_complete",
+        nodeName: current.name,
+        nodeType: current.type,
+        state: output
+      });
+      if (current.type === "EndNode") {
+        this.emit({ type: "flow_complete", state: output });
+        return output;
+      }
+      currentState = currentState.merge(output);
+      const branch = current.executor.branch();
+      const [next, found] = this.graph.nextNode(current, branch);
+      if (!found) {
+        throw new Error(
+          `run: no next node from "${current.name}" (branch="${branch}")`
+        );
+      }
+      current = next;
+    }
+    throw new Error(
+      `run: exceeded max iterations (${this.opts.maxIterations})`
+    );
+  }
+  resolveInputs(cn, nodeOutputs, currentState) {
+    if (cn.inputMappings.size === 0) {
+      return currentState;
+    }
+    let resolved = new State();
+    for (const [destInput, src] of cn.inputMappings) {
+      const srcOutput = nodeOutputs.get(src.sourceNode);
+      if (srcOutput) {
+        const [val, ok] = srcOutput.get(src.sourceOutput);
+        if (ok) {
+          resolved = resolved.set(destInput, val);
+        }
+      }
+    }
+    return currentState.merge(resolved);
+  }
+  emit(e) {
+    if (this.opts.eventHandler) {
+      this.opts.eventHandler(e);
+    }
+  }
+};
+
+// src/runner/options.ts
+var DEFAULT_MAX_ITERATIONS = 50;
+var DEFAULT_TIMEOUT2 = 3e5;
+function defaultOptions() {
+  return {
+    maxIterations: DEFAULT_MAX_ITERATIONS,
+    timeout: DEFAULT_TIMEOUT2,
+    verbose: false
+  };
+}
+
+// src/cli/validate.ts
+import { readFileSync } from "fs";
+import { Command } from "commander";
+var validateCommand = new Command("validate").description("Validate an Agent Spec flow definition").argument("<flow.json>", "Path to flow JSON file").option("--tools-dir <dir>", "Directory containing tool executables").action((flowPath, options) => {
+  const data = readFileSync(flowPath, "utf-8");
+  const pf = parseFlow(data);
+  console.log(`  Parsed flow: ${pf.name}`);
+  validateFlow(pf);
+  console.log("  Spec validation passed");
+  const deps = {};
+  const cg = compile(pf, deps);
+  console.log("  Graph compilation passed");
+  validate(cg);
+  console.log("  Graph validation passed");
+  if (options.toolsDir) {
+    const reg = FileRegistry.create(options.toolsDir);
+    const toolNames = collectToolNames(pf);
+    if (toolNames.length > 0) {
+      reg.validateTools(toolNames);
+      console.log(
+        `  Tool validation passed (${toolNames.length} tools found)`
+      );
+    } else {
+      console.log("  No tools to validate");
+    }
+  }
+  console.log(`Valid: ${flowPath}`);
+});
+function collectToolNames(pf) {
+  const names = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const n of pf.parsedNodes) {
+    if (n.component_type === "AgentNode") {
+      const an = n;
+      if (an.agent?.tools) {
+        for (const t of an.agent.tools) {
+          if (t.component_type === "ServerTool" && !seen.has(t.name)) {
+            names.push(t.name);
+            seen.add(t.name);
+          }
+        }
+      }
+    } else if (n.component_type === "ToolNode") {
+      const tn = n;
+      if (tn.tool && tn.tool.component_type === "ServerTool" && !seen.has(tn.tool.name)) {
+        names.push(tn.tool.name);
+        seen.add(tn.tool.name);
+      }
+    }
+  }
+  return names;
+}
+
+// src/cli/run.ts
+var runCommand = new Command2("run").description("Run an Agent Spec flow").argument("<flow.json>", "Path to flow JSON file").option("--tools-dir <dir>", "Directory containing tool executables").option("--input <json>", "Input JSON object").action(
+  async (flowPath, options, command) => {
+    const verbose = command.parent?.opts().verbose ?? false;
+    const data = readFileSync2(flowPath, "utf-8");
+    const pf = parseFlow(data);
+    validateFlow(pf);
+    const reg = FileRegistry.create(options.toolsDir ?? "");
+    const toolNames = collectToolNames(pf);
+    if (toolNames.length > 0) {
+      reg.validateTools(toolNames);
+    }
+    const provider = new OpenAIProvider();
+    const deps = {
+      llmProvider: provider,
+      toolExecutor: new SubprocessExecutor(),
+      toolRegistry: reg,
+      verbose
+    };
+    const cg = compile(pf, deps);
+    validate(cg);
+    let inputs;
+    if (options.input) {
+      try {
+        inputs = JSON.parse(options.input);
+      } catch (err) {
+        throw new Error(`failed to parse --input JSON: ${err}`);
+      }
+    } else {
+      inputs = {};
+    }
+    const opts = defaultOptions();
+    opts.verbose = verbose;
+    if (verbose) {
+      opts.eventHandler = (e) => {
+        switch (e.type) {
+          case "node_start":
+            console.error(
+              `[${e.nodeName}] Starting ${e.nodeType}`
+            );
+            break;
+          case "node_complete":
+            console.error(`[${e.nodeName}] Completed`);
+            break;
+          case "node_error":
+            console.error(
+              `[${e.nodeName}] Error: ${e.error}`
+            );
+            break;
+          case "flow_start":
+            console.error("Flow started");
+            break;
+          case "flow_complete":
+            console.error("Flow completed");
+            break;
+        }
+      };
+    }
+    const runner = new Runner(cg, opts);
+    const result = await runner.run(void 0, inputs);
+    const output = JSON.stringify(result.toData(), null, 2);
+    console.log(output);
+  }
+);
+
+// src/cli/init.ts
+import { Command as Command3 } from "commander";
+
+// src/scaffold/templates.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var flowTemplate = `{
+  "component_type": "Flow",
+  "agentspec_version": "26.1.0",
+  "name": "my-flow",
+  "start_node": {
+    "component_type": "StartNode",
+    "name": "start",
+    "inputs": [{"json_schema": {"title": "query", "type": "string"}}]
+  },
+  "nodes": [
+    {
+      "component_type": "StartNode",
+      "name": "start",
+      "inputs": [{"json_schema": {"title": "query", "type": "string"}}]
+    },
+    {
+      "component_type": "AgentNode",
+      "name": "assistant",
+      "agent": {
+        "component_type": "Agent",
+        "name": "assistant-agent",
+        "system_prompt": "You are a helpful assistant. Answer the user's question: {{query}}",
+        "llm_config": {
+          "component_type": "OpenAIConfig",
+          "model_id": "gpt-4o"
+        },
+        "tools": [
+          {
+            "component_type": "ServerTool",
+            "name": "example_tool",
+            "description": "An example tool that echoes input",
+            "inputs": [{"json_schema": {"title": "message", "type": "string"}}],
+            "outputs": [{"json_schema": {"title": "response", "type": "string"}}]
+          }
+        ]
+      }
+    },
+    {
+      "component_type": "EndNode",
+      "name": "end",
+      "inputs": [{"json_schema": {"title": "result", "type": "string"}}]
+    }
+  ],
+  "control_flow_connections": [
+    {"from_node": "start", "to_node": "assistant"},
+    {"from_node": "assistant", "to_node": "end"}
+  ],
+  "data_flow_connections": [
+    {"source_node": "start", "source_output": "query", "destination_node": "assistant", "destination_input": "query"},
+    {"source_node": "assistant", "source_output": "result", "destination_node": "end", "destination_input": "result"}
+  ]
+}
+`;
+var toolTemplate = `#!/usr/bin/env bash
+# Example tool: reads JSON from stdin, writes JSON to stdout
+set -euo pipefail
+
+# Parse input
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('message','no message'))" 2>/dev/null || echo "no message")
+
+# Return JSON output
+echo "{\\"response\\": \\"Echo: $MESSAGE\\"}"
+`;
+function generate(dir) {
+  const toolsDir = join2(dir, "tools");
+  try {
+    mkdirSync(toolsDir, { recursive: true });
+  } catch (err) {
+    throw new Error(`scaffold: failed to create directory: ${err}`);
+  }
+  const flowPath = join2(dir, "flow.json");
+  try {
+    writeFileSync(flowPath, flowTemplate, { mode: 420 });
+  } catch (err) {
+    throw new Error(`scaffold: failed to write flow.json: ${err}`);
+  }
+  const toolPath = join2(toolsDir, "example_tool.sh");
+  try {
+    writeFileSync(toolPath, toolTemplate, { mode: 493 });
+  } catch (err) {
+    throw new Error(`scaffold: failed to write example_tool.sh: ${err}`);
+  }
+}
+
+// src/cli/init.ts
+var initCommand = new Command3("init").description("Scaffold a new specrun project").argument("<project-name>", "Name of the project directory").action((dir) => {
+  generate(dir);
+  console.log(`Created project in ${dir}/`);
+  console.log("  flow.json              - Agent Spec flow definition");
+  console.log("  tools/example_tool.sh  - Example tool script");
+  console.log();
+  console.log("Next steps:");
+  console.log(`  1. Edit ${dir}/flow.json to define your workflow`);
+  console.log(`  2. Add tool scripts to ${dir}/tools/`);
+  console.log(
+    `  3. Run: specrun run ${dir}/flow.json --tools-dir ${dir}/tools --input '{"query": "hello"}'`
+  );
+});
+
+// src/cli/root.ts
+var program = new Command4("specrun").description("Lightweight CLI agentic workflow framework").option("--verbose", "Enable verbose output", false).option("--trace", "Enable trace-level output", false);
+program.addCommand(runCommand);
+program.addCommand(validateCommand);
+program.addCommand(initCommand);
+
+// src/index.ts
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err.message ?? err);
+  process.exit(1);
+});