yaml-flow 2.1.0 → 2.3.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 export { StepMachine as FlowEngine, StepMachine, applyStepResult, checkCircuitBreaker, computeStepInput, createStepMachine as createEngine, createInitialState, createStepMachine, extractReturnData, loadStepFlow, validateStepFlowConfig } from './step-machine/index.cjs';
 export { C as CircuitBreakerConfig, R as RetryConfig, S as StepConfig, a as StepContext, b as StepEvent, c as StepEventListener, d as StepEventType, e as StepFlowConfig, f as StepFlowSettings, g as StepHandler, h as StepInput, i as StepMachineOptions, j as StepMachineResult, k as StepMachineState, l as StepMachineStore, m as StepReducerResult, n as StepResult, T as TerminalStateConfig } from './types-FZ_eyErS.cjs';
-export { A as AgentActionEvent, C as COMPLETION_STRATEGIES, a as CONFLICT_STRATEGIES, b as CompletionResult, c as CompletionStrategy, d as ConflictStrategy, D as DEFAULTS, E as EXECUTION_MODES, e as EXECUTION_STATUS, f as ExecutionConfig, g as ExecutionMode, h as ExecutionState, i as ExecutionStatus, G as GraphConfig, j as GraphEvent, k as GraphSettings, T as GraphTaskConfig, I as InjectTokensEvent, S as SchedulerResult, l as StuckDetection, m as TASK_STATUS, n as TaskCompletedEvent, o as TaskCreationEvent, p as TaskFailedEvent, q as TaskStartedEvent, r as TaskState, s as TaskStatus, t as addDynamicTask, u as apply, v as applyAll, w as computeAvailableOutputs, x as createDefaultTaskState, y as createInitialExecutionState, z as detectStuckState, B as getAllTasks, F as getCandidateTasks, H as getProvides, J as getRequires, K as getTask, L as hasTask, M as isExecutionComplete, N as isNonActiveTask, O as isRepeatableTask, P as isTaskCompleted, Q as isTaskRunning, R as next } from './constants-D1fTEbbM.cjs';
+export { A as AgentActionEvent, C as COMPLETION_STRATEGIES, a as CONFLICT_STRATEGIES, b as CompletionResult, c as CompletionStrategy, d as ConflictStrategy, D as DEFAULTS, E as EXECUTION_MODES, e as EXECUTION_STATUS, f as ExecutionConfig, g as ExecutionMode, h as ExecutionPlan, i as ExecutionState, j as ExecutionStatus, k as ExportOptions, G as GraphConfig, l as GraphEvent, m as GraphIssue, n as GraphSettings, T as GraphTaskConfig, o as GraphValidationResult, I as InjectTokensEvent, p as IssueSeverity, M as MermaidOptions, S as SchedulerResult, q as StuckDetection, r as TASK_STATUS, s as TaskCompletedEvent, t as TaskCreationEvent, u as TaskFailedEvent, v as TaskStartedEvent, w as TaskState, x as TaskStatus, y as addDynamicTask, z as apply, B as applyAll, F as computeAvailableOutputs, H as createDefaultTaskState, J as createInitialExecutionState, K as detectStuckState, L as exportGraphConfig, N as exportGraphConfigToFile, O as flowToMermaid, P as getAllTasks, Q as getCandidateTasks, R as getProvides, U as getRequires, V as getTask, W as graphToMermaid, X as hasTask, Y as isExecutionComplete, Z as isNonActiveTask, _ as isRepeatableTask, $ as isTaskCompleted, a0 as isTaskRunning, a1 as loadGraphConfig, a2 as next, a3 as planExecution, a4 as validateGraph, a5 as validateGraphConfig } from './constants-BftTHiuV.cjs';
 export { MemoryStore } from './stores/memory.cjs';
 export { LocalStorageStore } from './stores/localStorage.cjs';
 export { FileStore } from './stores/file.cjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { StepMachine as FlowEngine, StepMachine, applyStepResult, checkCircuitBreaker, computeStepInput, createStepMachine as createEngine, createInitialState, createStepMachine, extractReturnData, loadStepFlow, validateStepFlowConfig } from './step-machine/index.js';
 export { C as CircuitBreakerConfig, R as RetryConfig, S as StepConfig, a as StepContext, b as StepEvent, c as StepEventListener, d as StepEventType, e as StepFlowConfig, f as StepFlowSettings, g as StepHandler, h as StepInput, i as StepMachineOptions, j as StepMachineResult, k as StepMachineState, l as StepMachineStore, m as StepReducerResult, n as StepResult, T as TerminalStateConfig } from './types-FZ_eyErS.js';
-export { A as AgentActionEvent, C as COMPLETION_STRATEGIES, a as CONFLICT_STRATEGIES, b as CompletionResult, c as CompletionStrategy, d as ConflictStrategy, D as DEFAULTS, E as EXECUTION_MODES, e as EXECUTION_STATUS, f as ExecutionConfig, g as ExecutionMode, h as ExecutionState, i as ExecutionStatus, G as GraphConfig, j as GraphEvent, k as GraphSettings, T as GraphTaskConfig, I as InjectTokensEvent, S as SchedulerResult, l as StuckDetection, m as TASK_STATUS, n as TaskCompletedEvent, o as TaskCreationEvent, p as TaskFailedEvent, q as TaskStartedEvent, r as TaskState, s as TaskStatus, t as addDynamicTask, u as apply, v as applyAll, w as computeAvailableOutputs, x as createDefaultTaskState, y as createInitialExecutionState, z as detectStuckState, B as getAllTasks, F as getCandidateTasks, H as getProvides, J as getRequires, K as getTask, L as hasTask, M as isExecutionComplete, N as isNonActiveTask, O as isRepeatableTask, P as isTaskCompleted, Q as isTaskRunning, R as next } from './constants-D1fTEbbM.js';
+export { A as AgentActionEvent, C as COMPLETION_STRATEGIES, a as CONFLICT_STRATEGIES, b as CompletionResult, c as CompletionStrategy, d as ConflictStrategy, D as DEFAULTS, E as EXECUTION_MODES, e as EXECUTION_STATUS, f as ExecutionConfig, g as ExecutionMode, h as ExecutionPlan, i as ExecutionState, j as ExecutionStatus, k as ExportOptions, G as GraphConfig, l as GraphEvent, m as GraphIssue, n as GraphSettings, T as GraphTaskConfig, o as GraphValidationResult, I as InjectTokensEvent, p as IssueSeverity, M as MermaidOptions, S as SchedulerResult, q as StuckDetection, r as TASK_STATUS, s as TaskCompletedEvent, t as TaskCreationEvent, u as TaskFailedEvent, v as TaskStartedEvent, w as TaskState, x as TaskStatus, y as addDynamicTask, z as apply, B as applyAll, F as computeAvailableOutputs, H as createDefaultTaskState, J as createInitialExecutionState, K as detectStuckState, L as exportGraphConfig, N as exportGraphConfigToFile, O as flowToMermaid, P as getAllTasks, Q as getCandidateTasks, R as getProvides, U as getRequires, V as getTask, W as graphToMermaid, X as hasTask, Y as isExecutionComplete, Z as isNonActiveTask, _ as isRepeatableTask, $ as isTaskCompleted, a0 as isTaskRunning, a1 as loadGraphConfig, a2 as next, a3 as planExecution, a4 as validateGraph, a5 as validateGraphConfig } from './constants-DMbnp--H.js';
 export { MemoryStore } from './stores/memory.js';
 export { LocalStorageStore } from './stores/localStorage.js';
 export { FileStore } from './stores/file.js';

package/dist/index.js

@@ -1331,6 +1331,615 @@ function applyTaskCreation(state, taskName, taskConfig) {
   };
 }
 
+// src/event-graph/plan.ts
+function buildProducerMap(tasks) {
+  const map = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getProvides(config)) {
+      if (!map[token]) map[token] = [];
+      map[token].push(name);
+    }
+    if (config.on) {
+      for (const tokens of Object.values(config.on)) {
+        for (const token of tokens) {
+          if (!map[token]) map[token] = [];
+          if (!map[token].includes(name)) map[token].push(name);
+        }
+      }
+    }
+    if (config.on_failure) {
+      for (const token of config.on_failure) {
+        if (!map[token]) map[token] = [];
+        if (!map[token].includes(name)) map[token].push(name);
+      }
+    }
+  }
+  return map;
+}
+function buildDependencies(tasks, producerMap) {
+  const deps = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    const required = getRequires(config);
+    const taskDeps = /* @__PURE__ */ new Set();
+    for (const token of required) {
+      const producers = producerMap[token] || [];
+      for (const producer of producers) {
+        if (producer !== name) taskDeps.add(producer);
+      }
+    }
+    deps[name] = [...taskDeps];
+  }
+  return deps;
+}
+function computePhases(taskNames, dependencies) {
+  const taskSet = new Set(taskNames);
+  const inDegree = {};
+  const dependents = {};
+  for (const name of taskNames) {
+    inDegree[name] = 0;
+    dependents[name] = [];
+  }
+  for (const name of taskNames) {
+    for (const dep of dependencies[name] || []) {
+      if (taskSet.has(dep)) {
+        inDegree[name]++;
+        dependents[dep].push(name);
+      }
+    }
+  }
+  const phases = [];
+  const remaining = new Set(taskNames);
+  while (remaining.size > 0) {
+    const phase = [];
+    for (const name of remaining) {
+      if (inDegree[name] === 0) {
+        phase.push(name);
+      }
+    }
+    if (phase.length === 0) {
+      phases.push([...remaining]);
+      break;
+    }
+    phase.sort();
+    phases.push(phase);
+    for (const name of phase) {
+      remaining.delete(name);
+      for (const dependent of dependents[name] || []) {
+        if (remaining.has(dependent)) {
+          inDegree[dependent]--;
+        }
+      }
+    }
+  }
+  return phases;
+}
+function planExecution(graph) {
+  const tasks = getAllTasks(graph);
+  const taskNames = Object.keys(tasks);
+  if (taskNames.length === 0) {
+    return {
+      phases: [],
+      dependencies: {},
+      conflicts: {},
+      entryPoints: [],
+      leafTasks: [],
+      unreachableTokens: [],
+      blockedTasks: [],
+      depth: 0,
+      maxParallelism: 0
+    };
+  }
+  const producerMap = buildProducerMap(tasks);
+  const dependencies = buildDependencies(tasks, producerMap);
+  const conflicts = {};
+  for (const [token, producers] of Object.entries(producerMap)) {
+    if (producers.length > 1) {
+      conflicts[token] = producers;
+    }
+  }
+  const entryPoints = taskNames.filter((name) => getRequires(tasks[name]).length === 0);
+  const dependedOn = /* @__PURE__ */ new Set();
+  for (const deps of Object.values(dependencies)) {
+    for (const dep of deps) dependedOn.add(dep);
+  }
+  const leafTasks = taskNames.filter((name) => !dependedOn.has(name));
+  const allRequired = /* @__PURE__ */ new Set();
+  for (const config of Object.values(tasks)) {
+    for (const token of getRequires(config)) {
+      allRequired.add(token);
+    }
+  }
+  const unreachableTokens = [...allRequired].filter((token) => !producerMap[token]);
+  const unreachableSet = new Set(unreachableTokens);
+  const blockedTasks = taskNames.filter(
+    (name) => getRequires(tasks[name]).some((token) => unreachableSet.has(token))
+  );
+  const phases = computePhases(taskNames, dependencies);
+  return {
+    phases,
+    dependencies,
+    conflicts,
+    entryPoints,
+    leafTasks: leafTasks.sort(),
+    unreachableTokens: unreachableTokens.sort(),
+    blockedTasks: blockedTasks.sort(),
+    depth: phases.length,
+    maxParallelism: Math.max(0, ...phases.map((p) => p.length))
+  };
+}
+
+// src/event-graph/mermaid.ts
+function sanitizeId(name) {
+  return name.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function graphToMermaid(graph, options = {}) {
+  const { direction = "TD", showTokens = true, title } = options;
+  const tasks = getAllTasks(graph);
+  const taskNames = Object.keys(tasks);
+  if (taskNames.length === 0) {
+    return `graph ${direction}
+  empty[No tasks defined]`;
+  }
+  const producerMap = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getProvides(config)) {
+      if (!producerMap[token]) producerMap[token] = [];
+      producerMap[token].push(name);
+    }
+    if (config.on) {
+      for (const tokens of Object.values(config.on)) {
+        for (const token of tokens) {
+          if (!producerMap[token]) producerMap[token] = [];
+          if (!producerMap[token].includes(name)) producerMap[token].push(name);
+        }
+      }
+    }
+  }
+  const lines = [];
+  const diagramTitle = title || graph.id || "Event Graph";
+  lines.push(`%% ${diagramTitle}`);
+  lines.push(`graph ${direction}`);
+  const allRequired = /* @__PURE__ */ new Set();
+  for (const config of Object.values(tasks)) {
+    for (const token of getRequires(config)) {
+      allRequired.add(token);
+    }
+  }
+  const leafTaskSet = new Set(
+    taskNames.filter((name) => {
+      const prov = getProvides(tasks[name]);
+      return prov.length === 0 || prov.every((token) => !allRequired.has(token));
+    })
+  );
+  for (const name of taskNames) {
+    const id = sanitizeId(name);
+    const req = getRequires(tasks[name]);
+    if (req.length === 0) {
+      lines.push(`  ${id}([${name}])`);
+    } else if (leafTaskSet.has(name)) {
+      lines.push(`  ${id}[[${name}]]`);
+    } else {
+      lines.push(`  ${id}[${name}]`);
+    }
+  }
+  const edgeSet = /* @__PURE__ */ new Set();
+  for (const [name, config] of Object.entries(tasks)) {
+    const required = getRequires(config);
+    for (const token of required) {
+      const producers = producerMap[token] || [];
+      for (const producer of producers) {
+        if (producer === name) continue;
+        const edgeKey = `${producer}->${name}:${token}`;
+        if (edgeSet.has(edgeKey)) continue;
+        edgeSet.add(edgeKey);
+        const fromId = sanitizeId(producer);
+        const toId = sanitizeId(name);
+        if (showTokens) {
+          lines.push(`  ${fromId} -->|${token}| ${toId}`);
+        } else {
+          lines.push(`  ${fromId} --> ${toId}`);
+        }
+      }
+    }
+    for (const token of required) {
+      if (!producerMap[token]) {
+        const warnId = `warn_${sanitizeId(token)}`;
+        const toId = sanitizeId(name);
+        lines.push(`  ${warnId}{{\u26A0 ${token}}} -.->|missing| ${toId}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function flowToMermaid(flow, options = {}) {
+  const { direction = "TD", title } = options;
+  const steps = flow.steps;
+  const terminals = flow.terminal_states;
+  const startStep = flow.settings.start_step;
+  const lines = [];
+  const diagramTitle = title || flow.id || "Step Machine";
+  lines.push(`%% ${diagramTitle}`);
+  lines.push(`graph ${direction}`);
+  lines.push(`  START(( ))`);
+  lines.push(`  START --> ${sanitizeId(startStep)}`);
+  for (const name of Object.keys(steps)) {
+    const id = sanitizeId(name);
+    lines.push(`  ${id}[${name}]`);
+  }
+  for (const [name, config] of Object.entries(terminals)) {
+    const id = sanitizeId(name);
+    lines.push(`  ${id}([${name}: ${config.return_intent}])`);
+  }
+  for (const [stepName, stepConfig] of Object.entries(steps)) {
+    const fromId = sanitizeId(stepName);
+    for (const [result, target] of Object.entries(stepConfig.transitions)) {
+      const toId = sanitizeId(target);
+      lines.push(`  ${fromId} -->|${result}| ${toId}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/event-graph/loader.ts
+function validateGraphConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== "object") {
+    return ["Graph config must be an object"];
+  }
+  const c = config;
+  if (!c.settings || typeof c.settings !== "object") {
+    errors.push('Graph config must have a "settings" object');
+  } else {
+    const settings = c.settings;
+    if (!settings.completion || typeof settings.completion !== "string") {
+      errors.push("settings.completion must be a string");
+    }
+    if (settings.completion === "goal-reached") {
+      if (!Array.isArray(settings.goal) || settings.goal.length === 0) {
+        errors.push('settings.goal must be a non-empty array when completion is "goal-reached"');
+      }
+    }
+  }
+  if (!c.tasks || typeof c.tasks !== "object") {
+    errors.push('Graph config must have a "tasks" object');
+  } else {
+    const tasks = c.tasks;
+    if (Object.keys(tasks).length === 0) {
+      errors.push("Graph config must have at least one task");
+    }
+    for (const [name, task] of Object.entries(tasks)) {
+      if (!task || typeof task !== "object") {
+        errors.push(`Task "${name}" must be an object`);
+        continue;
+      }
+      const t = task;
+      if (!Array.isArray(t.provides)) {
+        errors.push(`Task "${name}" must have a "provides" array`);
+      }
+      if (t.requires !== void 0 && !Array.isArray(t.requires)) {
+        errors.push(`Task "${name}".requires must be an array if present`);
+      }
+      if (t.on !== void 0) {
+        if (typeof t.on !== "object" || Array.isArray(t.on)) {
+          errors.push(`Task "${name}".on must be an object mapping result keys to token arrays`);
+        } else {
+          for (const [key, tokens] of Object.entries(t.on)) {
+            if (!Array.isArray(tokens)) {
+              errors.push(`Task "${name}".on.${key} must be an array of tokens`);
+            }
+          }
+        }
+      }
+    }
+  }
+  return errors;
+}
+async function parseGraphYaml(yamlString) {
+  const yaml = await import('yaml');
+  return yaml.parse(yamlString);
+}
+async function loadGraphConfig(source) {
+  let config;
+  if (typeof source === "string") {
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+      const response = await fetch(source);
+      if (!response.ok) {
+        throw new Error(`Failed to load graph config from ${source}: ${response.statusText}`);
+      }
+      const text = await response.text();
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("json") || source.endsWith(".json")) {
+        config = JSON.parse(text);
+      } else {
+        config = await parseGraphYaml(text);
+      }
+    } else if (source.includes("{")) {
+      config = JSON.parse(source);
+    } else {
+      const fs = await import('fs/promises');
+      const text = await fs.readFile(source, "utf-8");
+      if (source.endsWith(".json")) {
+        config = JSON.parse(text);
+      } else {
+        config = await parseGraphYaml(text);
+      }
+    }
+  } else {
+    config = source;
+  }
+  const errors = validateGraphConfig(config);
+  if (errors.length > 0) {
+    throw new Error(`Invalid graph configuration:
+- ${errors.join("\n- ")}`);
+  }
+  return config;
+}
+function exportGraphConfig(config, options = {}) {
+  const { format = "json", indent = 2 } = options;
+  if (format === "yaml") {
+    return toYaml(config, indent);
+  }
+  return JSON.stringify(config, null, indent);
+}
+async function exportGraphConfigToFile(config, filePath, options = {}) {
+  const format = options.format ?? (filePath.endsWith(".yaml") || filePath.endsWith(".yml") ? "yaml" : "json");
+  const content = exportGraphConfig(config, { ...options, format });
+  const fs = await import('fs/promises');
+  await fs.writeFile(filePath, content, "utf-8");
+}
+function toYaml(obj, indent, depth = 0) {
+  const pad = " ".repeat(indent * depth);
+  if (obj === null || obj === void 0) return "null";
+  if (typeof obj === "boolean") return String(obj);
+  if (typeof obj === "number") return String(obj);
+  if (typeof obj === "string") {
+    if (obj.includes(":") || obj.includes("#") || obj.includes("\n") || obj.includes('"') || obj.includes("'") || obj.startsWith(" ") || obj.startsWith("{") || obj.startsWith("[") || obj === "") {
+      return JSON.stringify(obj);
+    }
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return "[]";
+    if (obj.every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean")) {
+      return `[${obj.map((v) => typeof v === "string" ? toYaml(v, indent, 0) : String(v)).join(", ")}]`;
+    }
+    return obj.map((item) => {
+      const val = toYaml(item, indent, depth + 1);
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        const lines = val.trimStart().split("\n");
+        return `${pad}- ${lines[0]}
+${lines.slice(1).map((l) => `${pad}  ${l.trimStart() ? l : ""}`).filter(Boolean).join("\n")}`;
+      }
+      return `${pad}- ${val}`;
+    }).join("\n");
+  }
+  if (typeof obj === "object") {
+    const entries = Object.entries(obj);
+    if (entries.length === 0) return "{}";
+    return entries.map(([key, value]) => {
+      if (value === void 0) return "";
+      const serialized = toYaml(value, indent, depth + 1);
+      if (typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length > 0) {
+        return `${pad}${key}:
+${serialized}`;
+      }
+      if (Array.isArray(value) && value.length > 0 && !value.every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean")) {
+        return `${pad}${key}:
+${serialized}`;
+      }
+      return `${pad}${key}: ${serialized}`;
+    }).filter(Boolean).join("\n");
+  }
+  return String(obj);
+}
+
+// src/event-graph/validate.ts
+function buildProducerMap2(tasks) {
+  const map = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getProvides(config)) {
+      if (!map[token]) map[token] = [];
+      map[token].push(name);
+    }
+    if (config.on) {
+      for (const tokens of Object.values(config.on)) {
+        for (const token of tokens) {
+          if (!map[token]) map[token] = [];
+          if (!map[token].includes(name)) map[token].push(name);
+        }
+      }
+    }
+    if (config.on_failure) {
+      for (const token of config.on_failure) {
+        if (!map[token]) map[token] = [];
+        if (!map[token].includes(name)) map[token].push(name);
+      }
+    }
+  }
+  return map;
+}
+function buildTaskDeps(tasks, producerMap) {
+  const deps = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    deps[name] = /* @__PURE__ */ new Set();
+    for (const token of getRequires(config)) {
+      for (const producer of producerMap[token] || []) {
+        if (producer !== name) deps[name].add(producer);
+      }
+    }
+  }
+  return deps;
+}
+function detectCycles(taskNames, deps) {
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = {};
+  const parent = {};
+  const cycles = [];
+  for (const name of taskNames) {
+    color[name] = WHITE;
+    parent[name] = null;
+  }
+  function dfs(node) {
+    color[node] = GRAY;
+    for (const dep of deps[node] || []) {
+      if (color[dep] === GRAY) {
+        const cycle = [dep];
+        let cur = node;
+        while (cur !== dep) {
+          cycle.push(cur);
+          cur = parent[cur];
+        }
+        cycle.push(dep);
+        cycle.reverse();
+        cycles.push(cycle);
+      } else if (color[dep] === WHITE) {
+        parent[dep] = node;
+        dfs(dep);
+      }
+    }
+    color[node] = BLACK;
+  }
+  for (const name of taskNames) {
+    if (color[name] === WHITE) {
+      dfs(name);
+    }
+  }
+  return cycles;
+}
+function validateGraph(graph) {
+  const issues = [];
+  const tasks = getAllTasks(graph);
+  const taskNames = Object.keys(tasks);
+  if (taskNames.length === 0) {
+    issues.push({
+      severity: "error",
+      code: "EMPTY_GRAPH",
+      message: "Graph has no tasks"
+    });
+    return buildResult(issues);
+  }
+  const producerMap = buildProducerMap2(tasks);
+  const deps = buildTaskDeps(tasks, producerMap);
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getRequires(config)) {
+      if (!producerMap[token]) {
+        issues.push({
+          severity: "error",
+          code: "DANGLING_REQUIRES",
+          message: `Task "${name}" requires token "${token}" but no task produces it`,
+          tasks: [name],
+          tokens: [token]
+        });
+      }
+    }
+  }
+  const cycles = detectCycles(taskNames, deps);
+  for (const cycle of cycles) {
+    issues.push({
+      severity: "error",
+      code: "CIRCULAR_DEPENDENCY",
+      message: `Circular dependency: ${cycle.join(" \u2192 ")}`,
+      tasks: cycle.filter((_t, i) => i < cycle.length - 1)
+      // dedupe last = first
+    });
+  }
+  for (const [name, config] of Object.entries(tasks)) {
+    const req = getRequires(config);
+    const prov = getProvides(config);
+    const self = req.filter((token) => prov.includes(token));
+    if (self.length > 0) {
+      issues.push({
+        severity: "error",
+        code: "SELF_DEPENDENCY",
+        message: `Task "${name}" requires tokens it provides itself: [${self.join(", ")}]`,
+        tasks: [name],
+        tokens: self
+      });
+    }
+  }
+  for (const [token, producers] of Object.entries(producerMap)) {
+    if (producers.length > 1) {
+      issues.push({
+        severity: "warning",
+        code: "PROVIDE_CONFLICT",
+        message: `Token "${token}" is produced by multiple tasks: [${producers.join(", ")}]. This requires a conflict strategy.`,
+        tasks: producers,
+        tokens: [token]
+      });
+    }
+  }
+  if (graph.settings.completion === "goal-reached" && graph.settings.goal) {
+    for (const goalToken of graph.settings.goal) {
+      if (!producerMap[goalToken]) {
+        issues.push({
+          severity: "error",
+          code: "UNREACHABLE_GOAL",
+          message: `Goal token "${goalToken}" cannot be produced by any task`,
+          tokens: [goalToken]
+        });
+      }
+    }
+  }
+  if (taskNames.length > 1) {
+    for (const [name, config] of Object.entries(tasks)) {
+      const prov = getProvides(config);
+      const onProv = config.on ? Object.values(config.on).flat() : [];
+      const failProv = config.on_failure || [];
+      if (prov.length === 0 && onProv.length === 0 && failProv.length === 0) {
+        issues.push({
+          severity: "warning",
+          code: "DEAD_END_TASK",
+          message: `Task "${name}" has no provides \u2014 it cannot unblock any downstream task`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  const allRequired = /* @__PURE__ */ new Set();
+  for (const config of Object.values(tasks)) {
+    for (const token of getRequires(config)) {
+      allRequired.add(token);
+    }
+  }
+  for (const [name, config] of Object.entries(tasks)) {
+    const req = getRequires(config);
+    const prov = getProvides(config);
+    const onProv = config.on ? Object.values(config.on).flat() : [];
+    const allProv = [...prov, ...onProv];
+    const isEntryPoint = req.length === 0;
+    const hasDownstream = allProv.some((token) => allRequired.has(token));
+    if (isEntryPoint && !hasDownstream && taskNames.length > 1) {
+      const isGoalRelevant = graph.settings.completion === "goal-reached" && graph.settings.goal?.some((g) => allProv.includes(g));
+      if (!isGoalRelevant) {
+        issues.push({
+          severity: "info",
+          code: "ISOLATED_TASK",
+          message: `Task "${name}" is disconnected \u2014 it has no requires and nothing depends on its provides`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  if (graph.settings.completion === "goal-reached" && !graph.settings.goal) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_GOAL",
+      message: 'Completion strategy is "goal-reached" but no goal tokens are defined'
+    });
+  }
+  return buildResult(issues);
+}
+function buildResult(issues) {
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  return {
+    valid: errors.length === 0,
+    issues,
+    errors,
+    warnings
+  };
+}
+
 // src/stores/localStorage.ts
 var LocalStorageStore = class {
   prefix;
@@ -1691,6 +2300,6 @@ function resolveConfigTemplates(config) {
   return result;
 }
 
-export { COMPLETION_STRATEGIES, CONFLICT_STRATEGIES, DEFAULTS, EXECUTION_MODES, EXECUTION_STATUS, FileStore, StepMachine as FlowEngine, LocalStorageStore, MemoryStore, StepMachine, TASK_STATUS, addDynamicTask, apply, applyAll, applyStepResult, batch, checkCircuitBreaker, computeAvailableOutputs, computeStepInput, createDefaultTaskState, createStepMachine as createEngine, createInitialExecutionState, createInitialState, createStepMachine, detectStuckState, extractReturnData, getAllTasks, getCandidateTasks, getProvides, getRequires, getTask, hasTask, isExecutionComplete, isNonActiveTask, isRepeatableTask, isTaskCompleted, isTaskRunning, loadStepFlow, next, resolveConfigTemplates, resolveVariables, validateStepFlowConfig };
+export { COMPLETION_STRATEGIES, CONFLICT_STRATEGIES, DEFAULTS, EXECUTION_MODES, EXECUTION_STATUS, FileStore, StepMachine as FlowEngine, LocalStorageStore, MemoryStore, StepMachine, TASK_STATUS, addDynamicTask, apply, applyAll, applyStepResult, batch, checkCircuitBreaker, computeAvailableOutputs, computeStepInput, createDefaultTaskState, createStepMachine as createEngine, createInitialExecutionState, createInitialState, createStepMachine, detectStuckState, exportGraphConfig, exportGraphConfigToFile, extractReturnData, flowToMermaid, getAllTasks, getCandidateTasks, getProvides, getRequires, getTask, graphToMermaid, hasTask, isExecutionComplete, isNonActiveTask, isRepeatableTask, isTaskCompleted, isTaskRunning, loadGraphConfig, loadStepFlow, next, planExecution, resolveConfigTemplates, resolveVariables, validateGraph, validateGraphConfig, validateStepFlowConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map