yaml-flow 2.8.0 → 3.1.0

package/dist/index.js

@@ -1,5 +1,7 @@
-import { execFile } from 'child_process';
 import addFormats from 'ajv-formats';
+import { existsSync, writeFileSync, appendFileSync, readFileSync } from 'fs';
+import { createHash } from 'crypto';
+import { exec, execFile } from 'child_process';
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -3911,7 +3913,7 @@ var require_core = __commonJS({
         uriResolver
       };
     }
-    var Ajv2 = class {
+    var Ajv4 = class {
       constructor(opts = {}) {
         this.schemas = {};
         this.refs = {};
@@ -4281,9 +4283,9 @@ var require_core = __commonJS({
         }
       }
     };
-    Ajv2.ValidationError = validation_error_1.default;
-    Ajv2.MissingRefError = ref_error_1.default;
-    exports$1.default = Ajv2;
+    Ajv4.ValidationError = validation_error_1.default;
+    Ajv4.MissingRefError = ref_error_1.default;
+    exports$1.default = Ajv4;
     function checkOptions(checkOpts, options, msg, log = "error") {
       for (const key in checkOpts) {
         const opt = key;
@@ -6354,7 +6356,7 @@ var require_ajv = __commonJS({
     var draft7MetaSchema = require_json_schema_draft_07();
     var META_SUPPORT_DATA = ["/properties"];
     var META_SCHEMA_ID = "http://json-schema.org/draft-07/schema";
-    var Ajv2 = class extends core_1.default {
+    var Ajv4 = class extends core_1.default {
       _addVocabularies() {
         super._addVocabularies();
         draft7_1.default.forEach((v) => this.addVocabulary(v));
@@ -6373,11 +6375,11 @@ var require_ajv = __commonJS({
         return this.opts.defaultMeta = super.defaultMeta() || (this.getSchema(META_SCHEMA_ID) ? META_SCHEMA_ID : void 0);
       }
     };
-    exports$1.Ajv = Ajv2;
-    module.exports = exports$1 = Ajv2;
-    module.exports.Ajv = Ajv2;
+    exports$1.Ajv = Ajv4;
+    module.exports = exports$1 = Ajv4;
+    module.exports.Ajv = Ajv4;
     Object.defineProperty(exports$1, "__esModule", { value: true });
-    exports$1.default = Ajv2;
+    exports$1.default = Ajv4;
     var validate_1 = require_validate();
     Object.defineProperty(exports$1, "KeywordCxt", { enumerable: true, get: function() {
       return validate_1.KeywordCxt;
@@ -6911,6 +6913,188 @@ async function loadStepFlow(source) {
   return flow;
 }
 
+// schema/flow.schema.json
+var flow_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://github.com/yaml-flow/schema/flow.json",
+  title: "YamlFlow Configuration",
+  description: "Schema for yaml-flow workflow definitions",
+  type: "object",
+  required: ["settings", "steps", "terminal_states"],
+  properties: {
+    id: {
+      type: "string",
+      description: "Optional flow identifier"
+    },
+    settings: {
+      type: "object",
+      description: "Flow-level settings",
+      required: ["start_step"],
+      properties: {
+        start_step: {
+          type: "string",
+          description: "Step to start execution from"
+        },
+        max_total_steps: {
+          type: "integer",
+          minimum: 1,
+          default: 100,
+          description: "Maximum steps before forced termination"
+        },
+        timeout_ms: {
+          type: "integer",
+          minimum: 0,
+          description: "Flow timeout in milliseconds"
+        }
+      },
+      additionalProperties: false
+    },
+    steps: {
+      type: "object",
+      description: "Step definitions",
+      minProperties: 1,
+      additionalProperties: {
+        $ref: "#/definitions/step"
+      }
+    },
+    terminal_states: {
+      type: "object",
+      description: "Terminal state definitions",
+      minProperties: 1,
+      additionalProperties: {
+        $ref: "#/definitions/terminal_state"
+      }
+    }
+  },
+  additionalProperties: false,
+  definitions: {
+    step: {
+      type: "object",
+      description: "Individual step configuration",
+      required: ["transitions"],
+      properties: {
+        description: {
+          type: "string",
+          description: "Human-readable description"
+        },
+        expects_data: {
+          type: "array",
+          items: { type: "string" },
+          description: "Data keys this step expects as input"
+        },
+        produces_data: {
+          type: "array",
+          items: { type: "string" },
+          description: "Data keys this step produces as output"
+        },
+        transitions: {
+          type: "object",
+          description: "Mapping of result -> next step name",
+          additionalProperties: { type: "string" },
+          minProperties: 1
+        },
+        retry: {
+          $ref: "#/definitions/retry_config"
+        },
+        circuit_breaker: {
+          $ref: "#/definitions/circuit_breaker_config"
+        }
+      },
+      additionalProperties: false
+    },
+    terminal_state: {
+      type: "object",
+      description: "Terminal state configuration",
+      required: ["return_intent"],
+      properties: {
+        description: {
+          type: "string",
+          description: "Human-readable description"
+        },
+        return_intent: {
+          type: "string",
+          description: "Intent/status to return (e.g., 'success', 'error')"
+        },
+        return_artifacts: {
+          oneOf: [
+            { type: "string" },
+            { type: "array", items: { type: "string" } },
+            { type: "boolean", const: false }
+          ],
+          description: "Data key(s) to include in result, or false to exclude"
+        },
+        expects_data: {
+          type: "array",
+          items: { type: "string" },
+          description: "Data keys this terminal state expects"
+        }
+      },
+      additionalProperties: false
+    },
+    retry_config: {
+      type: "object",
+      description: "Retry configuration for step failures",
+      required: ["max_attempts"],
+      properties: {
+        max_attempts: {
+          type: "integer",
+          minimum: 1,
+          description: "Maximum retry attempts"
+        },
+        delay_ms: {
+          type: "integer",
+          minimum: 0,
+          description: "Delay between retries in ms"
+        },
+        backoff_multiplier: {
+          type: "number",
+          minimum: 1,
+          description: "Backoff multiplier (e.g., 2 for exponential)"
+        }
+      },
+      additionalProperties: false
+    },
+    circuit_breaker_config: {
+      type: "object",
+      description: "Circuit breaker configuration for loops",
+      required: ["max_iterations", "on_open"],
+      properties: {
+        max_iterations: {
+          type: "integer",
+          minimum: 1,
+          description: "Maximum iterations before circuit opens"
+        },
+        on_open: {
+          type: "string",
+          description: "Step to transition to when circuit opens"
+        }
+      },
+      additionalProperties: false
+    }
+  }
+};
+
+// src/step-machine/schema-validator.ts
+var import_ajv = __toESM(require_ajv());
+var _compiled = null;
+function getValidator() {
+  if (_compiled) return _compiled;
+  const ajv = new import_ajv.default({ allErrors: true });
+  addFormats(ajv);
+  _compiled = ajv.compile(flow_schema_default);
+  return _compiled;
+}
+function validateFlowSchema(config) {
+  const validate = getValidator();
+  const valid = validate(config);
+  if (valid) return { ok: true, errors: [] };
+  const errors = (validate.errors ?? []).map((e) => {
+    const path = e.instancePath || "/";
+    return `${path}: ${e.message ?? "unknown error"}`;
+  });
+  return { ok: false, errors };
+}
+
 // src/event-graph/constants.ts
 var TASK_STATUS = {
   NOT_STARTED: "not-started",
@@ -6987,15 +7171,14 @@ function isTaskCompleted(taskState) {
 function isTaskRunning(taskState) {
   return taskState?.status === TASK_STATUS.RUNNING;
 }
-function isRepeatableTask(taskConfig) {
-  return taskConfig.repeatable === true || typeof taskConfig.repeatable === "object" && taskConfig.repeatable !== null;
+function getRefreshStrategy(taskConfig, graphSettings) {
+  return taskConfig.refreshStrategy ?? graphSettings?.refreshStrategy ?? "data-changed";
 }
-function getRepeatableMax(taskConfig) {
-  if (taskConfig.repeatable === true) return void 0;
-  if (typeof taskConfig.repeatable === "object" && taskConfig.repeatable !== null) {
-    return taskConfig.repeatable.max;
-  }
-  return void 0;
+function isRerunnable(taskConfig, graphSettings) {
+  return getRefreshStrategy(taskConfig, graphSettings) !== "once";
+}
+function getMaxExecutions(taskConfig) {
+  return taskConfig.maxExecutions;
 }
 function computeAvailableOutputs(graph, taskStates) {
   const outputs = /* @__PURE__ */ new Set();
@@ -7043,7 +7226,7 @@ function addDynamicTask(graph, taskName, taskConfig) {
     }
   };
 }
-function createDefaultTaskState() {
+function createDefaultGraphEngineStore() {
   return {
     status: "not-started",
     executionCount: 0,
@@ -7056,7 +7239,7 @@ function createDefaultTaskState() {
 function createInitialExecutionState(graph, executionId) {
   const tasks = {};
   for (const taskName of Object.keys(graph.tasks)) {
-    tasks[taskName] = createDefaultTaskState();
+    tasks[taskName] = createDefaultGraphEngineStore();
   }
   return {
     status: "running",
@@ -7427,48 +7610,88 @@ function getCandidateTasks(graph, state) {
   const candidates = [];
   for (const [taskName, taskConfig] of Object.entries(graphTasks)) {
     const taskState = state.tasks[taskName];
-    if (!isRepeatableTask(taskConfig)) {
-      if (taskState?.status === TASK_STATUS.COMPLETED || taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
-        continue;
-      }
-    } else {
-      if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
-        continue;
-      }
-      const maxExec = getRepeatableMax(taskConfig);
-      if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
+    const strategy = getRefreshStrategy(taskConfig, graph.settings);
+    const rerunnable = strategy !== "once";
+    if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
+      continue;
+    }
+    const maxExec = getMaxExecutions(taskConfig);
+    if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
+      continue;
+    }
+    if (taskConfig.circuit_breaker && taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
+      continue;
+    }
+    if (!rerunnable) {
+      if (taskState?.status === TASK_STATUS.COMPLETED) {
         continue;
       }
-      if (taskConfig.circuit_breaker) {
-        if (taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
-          continue;
+    }
+    if (rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      const requires2 = getRequires(taskConfig);
+      switch (strategy) {
+        case "data-changed": {
+          if (requires2.length > 0) {
+            const hasChangedData = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (!otherState) continue;
+                  const consumed = taskState.lastConsumedHashes?.[req];
+                  if (otherState.lastDataHash == null) {
+                    return otherState.executionCount > taskState.lastEpoch;
+                  }
+                  return otherState.lastDataHash !== consumed;
+                }
+              }
+              return false;
+            });
+            if (!hasChangedData) continue;
+          } else {
+            continue;
+          }
+          break;
         }
-      }
-      if (taskState?.status === TASK_STATUS.COMPLETED) {
-        const requires2 = getRequires(taskConfig);
-        if (requires2.length > 0) {
-          const hasRefreshedInputs = requires2.some((req) => {
-            for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
-              if (getProvides(otherConfig).includes(req)) {
-                const otherState = state.tasks[otherName];
-                if (otherState && otherState.executionCount > taskState.lastEpoch) {
-                  return true;
+        case "epoch-changed": {
+          if (requires2.length > 0) {
+            const hasRefreshedInputs = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (otherState && otherState.executionCount > taskState.lastEpoch) {
+                    return true;
+                  }
                 }
               }
-            }
-            return false;
-          });
-          if (!hasRefreshedInputs) continue;
-        } else {
+              return false;
+            });
+            if (!hasRefreshedInputs) continue;
+          } else {
+            continue;
+          }
+          break;
+        }
+        case "time-based": {
+          const interval = taskConfig.refreshInterval ?? 0;
+          if (interval <= 0) continue;
+          const completedAt = taskState.completedAt;
+          if (!completedAt) continue;
+          const elapsedSec = (Date.now() - Date.parse(completedAt)) / 1e3;
+          if (elapsedSec < interval) continue;
+          break;
+        }
+        case "manual": {
           continue;
         }
+        default:
+          continue;
       }
     }
     const requires = getRequires(taskConfig);
     if (!requires.every((req) => availableOutputs.includes(req))) {
       continue;
     }
-    if (!isRepeatableTask(taskConfig)) {
+    if (!rerunnable) {
       const provides = getProvides(taskConfig);
       const allAlreadyAvailable = provides.length > 0 && provides.every((output) => availableOutputs.includes(output));
       if (allAlreadyAvailable) continue;
@@ -7537,7 +7760,7 @@ function selectOptimalTasks(candidates, graph, state, conflictStrategy) {
 
 // src/event-graph/task-transitions.ts
 function applyTaskStart(state, taskName) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState2();
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore2();
   const updatedTask = {
     ...existingTask,
     status: "running",
@@ -7552,8 +7775,8 @@ function applyTaskStart(state, taskName) {
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function applyTaskCompletion(state, graph, taskName, result) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState2();
+function applyTaskCompletion(state, graph, taskName, result, dataHash, data) {
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore2();
   const taskConfig = graph.tasks[taskName];
   if (!taskConfig) {
     throw new Error(`Task "${taskName}" not found in graph`);
@@ -7564,6 +7787,19 @@ function applyTaskCompletion(state, graph, taskName, result) {
   } else {
     outputTokens = getProvides(taskConfig);
   }
+  const lastConsumedHashes = { ...existingTask.lastConsumedHashes };
+  const requires = taskConfig.requires ?? [];
+  for (const token of requires) {
+    for (const [otherName, otherConfig] of Object.entries(graph.tasks)) {
+      if (getProvides(otherConfig).includes(token)) {
+        const otherState = state.tasks[otherName];
+        if (otherState?.lastDataHash) {
+          lastConsumedHashes[token] = otherState.lastDataHash;
+        }
+        break;
+      }
+    }
+  }
   const updatedTask = {
     ...existingTask,
     status: "completed",
@@ -7571,11 +7807,11 @@ function applyTaskCompletion(state, graph, taskName, result) {
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
     executionCount: existingTask.executionCount + 1,
     lastEpoch: existingTask.executionCount + 1,
+    lastDataHash: dataHash,
+    data,
+    lastConsumedHashes,
     error: void 0
   };
-  if (isRepeatableTask(taskConfig)) {
-    updatedTask.status = "not-started";
-  }
   const newOutputs = [.../* @__PURE__ */ new Set([...state.availableOutputs, ...outputTokens])];
   return {
     ...state,
@@ -7585,7 +7821,7 @@ function applyTaskCompletion(state, graph, taskName, result) {
   };
 }
 function applyTaskFailure(state, graph, taskName, error) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState2();
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore2();
   const taskConfig = graph.tasks[taskName];
   if (taskConfig?.retry) {
     const retryCount = existingTask.retryCount + 1;
@@ -7628,7 +7864,7 @@ function applyTaskFailure(state, graph, taskName, error) {
   };
 }
 function applyTaskProgress(state, taskName, message, progress) {
-  const existingTask = state.tasks[taskName] ?? createDefaultTaskState2();
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore2();
   const updatedTask = {
     ...existingTask,
     progress: typeof progress === "number" ? progress : existingTask.progress,
@@ -7644,7 +7880,27 @@ function applyTaskProgress(state, taskName, message, progress) {
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function createDefaultTaskState2() {
+function applyTaskRestart(state, taskName) {
+  const existingTask = state.tasks[taskName];
+  if (!existingTask) return state;
+  const updatedTask = {
+    ...existingTask,
+    status: "not-started",
+    startedAt: void 0,
+    completedAt: void 0,
+    failedAt: void 0,
+    error: void 0,
+    data: void 0,
+    progress: null,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createDefaultGraphEngineStore2() {
   return {
     status: "not-started",
     executionCount: 0,
@@ -7664,11 +7920,13 @@ function apply(state, event, graph) {
     case "task-started":
       return applyTaskStart(state, event.taskName);
     case "task-completed":
-      return applyTaskCompletion(state, graph, event.taskName, event.result);
+      return applyTaskCompletion(state, graph, event.taskName, event.result, event.dataHash, event.data);
     case "task-failed":
       return applyTaskFailure(state, graph, event.taskName, event.error);
     case "task-progress":
       return applyTaskProgress(state, event.taskName, event.message, event.progress);
+    case "task-restart":
+      return applyTaskRestart(state, event.taskName);
     case "inject-tokens":
       return applyInjectTokens(state, event.tokens);
     case "agent-action":
@@ -7739,7 +7997,7 @@ function applyTaskCreation(state, taskName, taskConfig) {
     ...state,
     tasks: {
       ...state.tasks,
-      [taskName]: createDefaultTaskState()
+      [taskName]: createDefaultGraphEngineStore()
     },
     lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
   };
@@ -8354,107 +8612,377 @@ function buildResult(issues) {
   };
 }
 
-// src/stores/localStorage.ts
-var LocalStorageStore = class {
-  prefix;
-  constructor(options = {}) {
-    this.prefix = options.prefix ?? "yamlflow";
-    if (typeof localStorage === "undefined") {
-      throw new Error("LocalStorageStore requires localStorage (browser environment)");
-    }
-  }
-  runKey(runId) {
-    return `${this.prefix}:run:${runId}`;
-  }
-  dataKey(runId) {
-    return `${this.prefix}:data:${runId}`;
-  }
-  indexKey() {
-    return `${this.prefix}:runs`;
-  }
-  async saveRunState(runId, state) {
-    localStorage.setItem(this.runKey(runId), JSON.stringify(state));
-    const runs = await this.listRuns();
-    if (!runs.includes(runId)) {
-      runs.push(runId);
-      localStorage.setItem(this.indexKey(), JSON.stringify(runs));
-    }
-  }
-  async loadRunState(runId) {
-    const raw = localStorage.getItem(this.runKey(runId));
-    return raw ? JSON.parse(raw) : null;
-  }
-  async deleteRunState(runId) {
-    localStorage.removeItem(this.runKey(runId));
-    localStorage.removeItem(this.dataKey(runId));
-    const runs = await this.listRuns();
-    const filtered = runs.filter((id) => id !== runId);
-    localStorage.setItem(this.indexKey(), JSON.stringify(filtered));
-  }
-  async setData(runId, key, value) {
-    const allData = await this.getAllData(runId);
-    allData[key] = value;
-    localStorage.setItem(this.dataKey(runId), JSON.stringify(allData));
-  }
-  async getData(runId, key) {
-    const allData = await this.getAllData(runId);
-    return allData[key];
-  }
-  async getAllData(runId) {
-    const raw = localStorage.getItem(this.dataKey(runId));
-    return raw ? JSON.parse(raw) : {};
-  }
-  async clearData(runId) {
-    localStorage.removeItem(this.dataKey(runId));
-  }
-  async listRuns() {
-    const raw = localStorage.getItem(this.indexKey());
-    return raw ? JSON.parse(raw) : [];
-  }
-  /**
-   * Clear all flow data from localStorage
-   */
-  clearAll() {
-    const keysToRemove = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const key = localStorage.key(i);
-      if (key?.startsWith(this.prefix + ":")) {
-        keysToRemove.push(key);
+// schema/event-graph.schema.json
+var event_graph_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://github.com/yaml-flow/schema/event-graph.json",
+  title: "Event Graph Configuration",
+  description: "Schema for stateless event-graph (DAG) workflow definitions in yaml-flow",
+  type: "object",
+  required: ["settings", "tasks"],
+  additionalProperties: false,
+  properties: {
+    id: {
+      type: "string",
+      description: "Optional graph identifier"
+    },
+    settings: {
+      $ref: "#/definitions/settings"
+    },
+    tasks: {
+      type: "object",
+      description: "Task definitions keyed by name",
+      minProperties: 1,
+      additionalProperties: {
+        $ref: "#/definitions/task"
       }
     }
-    keysToRemove.forEach((key) => localStorage.removeItem(key));
-  }
-};
-
-// src/stores/file.ts
-var FileStore = class {
-  directory;
-  fs = null;
-  path = null;
-  constructor(options) {
-    this.directory = options.directory;
-  }
-  async ensureModules() {
-    if (!this.fs || !this.path) {
-      this.fs = await import('fs/promises');
-      this.path = await import('path');
-      await this.fs.mkdir(this.directory, { recursive: true });
-    }
-  }
-  runPath(runId) {
-    return this.path.join(this.directory, `${runId}.run.json`);
-  }
-  dataPath(runId) {
-    return this.path.join(this.directory, `${runId}.data.json`);
-  }
-  async saveRunState(runId, state) {
-    await this.ensureModules();
-    await this.fs.writeFile(
-      this.runPath(runId),
-      JSON.stringify(state, null, 2),
-      "utf-8"
-    );
-  }
+  },
+  definitions: {
+    settings: {
+      type: "object",
+      required: ["completion"],
+      properties: {
+        completion: {
+          type: "string",
+          enum: [
+            "all-tasks-done",
+            "all-outputs-done",
+            "only-resolved",
+            "goal-reached",
+            "manual"
+          ],
+          description: "Completion strategy"
+        },
+        conflict_strategy: {
+          type: "string",
+          enum: [
+            "alphabetical",
+            "priority-first",
+            "duration-first",
+            "cost-optimized",
+            "resource-aware",
+            "random-select",
+            "user-choice",
+            "parallel-all",
+            "skip-conflicts",
+            "round-robin"
+          ],
+          description: "Conflict resolution strategy"
+        },
+        execution_mode: {
+          type: "string",
+          enum: ["dependency-mode", "eligibility-mode"],
+          description: "Execution mode"
+        },
+        goal: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "Goal outputs \u2014 required when completion is 'goal-reached'"
+        },
+        max_iterations: {
+          type: "integer",
+          minimum: 1,
+          description: "Max scheduler iterations (safety limit, default: 1000)"
+        },
+        timeout_ms: {
+          type: "integer",
+          minimum: 0,
+          description: "Timeout in ms (declared for drivers, not enforced by pure engine)"
+        },
+        refreshStrategy: {
+          $ref: "#/definitions/refresh_strategy",
+          description: "Default refresh strategy for all tasks (default: 'data-changed')"
+        }
+      },
+      additionalProperties: false,
+      if: {
+        properties: { completion: { const: "goal-reached" } }
+      },
+      then: {
+        required: ["completion", "goal"]
+      }
+    },
+    task: {
+      type: "object",
+      required: ["provides"],
+      properties: {
+        requires: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tokens this task needs to become eligible"
+        },
+        provides: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tokens this task produces on successful completion"
+        },
+        on: {
+          type: "object",
+          description: "Conditional provides based on handler result key",
+          additionalProperties: {
+            type: "array",
+            items: { type: "string" }
+          }
+        },
+        on_failure: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tokens to inject when this task fails"
+        },
+        method: {
+          type: "string",
+          description: "Task execution method (informational \u2014 driver concern)"
+        },
+        config: {
+          type: "object",
+          description: "Arbitrary task configuration (driver concern)"
+        },
+        priority: {
+          type: "number",
+          description: "Higher = preferred in conflict resolution"
+        },
+        estimatedDuration: {
+          type: "number",
+          minimum: 0,
+          description: "Estimated duration in ms (used by duration-first strategy)"
+        },
+        estimatedCost: {
+          type: "number",
+          minimum: 0,
+          description: "Estimated cost (used by cost-optimized strategy)"
+        },
+        estimatedResources: {
+          type: "object",
+          additionalProperties: { type: "number" },
+          description: "Resource requirements (used by resource-aware strategy)"
+        },
+        retry: {
+          $ref: "#/definitions/task_retry"
+        },
+        refreshStrategy: {
+          $ref: "#/definitions/refresh_strategy",
+          description: "Task-level refresh strategy (overrides settings default)"
+        },
+        refreshInterval: {
+          type: "number",
+          minimum: 0,
+          description: "Interval in seconds for time-based refresh strategy"
+        },
+        maxExecutions: {
+          type: "integer",
+          minimum: 1,
+          description: "Maximum number of times this task can execute"
+        },
+        circuit_breaker: {
+          $ref: "#/definitions/task_circuit_breaker"
+        },
+        description: {
+          type: "string",
+          description: "Human-readable description"
+        },
+        inference: {
+          $ref: "#/definitions/inference_hints"
+        }
+      },
+      additionalProperties: false
+    },
+    task_retry: {
+      type: "object",
+      required: ["max_attempts"],
+      properties: {
+        max_attempts: {
+          type: "integer",
+          minimum: 1,
+          description: "Maximum retry attempts"
+        },
+        delay_ms: {
+          type: "integer",
+          minimum: 0,
+          description: "Delay between retries in ms"
+        },
+        backoff_multiplier: {
+          type: "number",
+          minimum: 1,
+          description: "Backoff multiplier (e.g., 2 for exponential)"
+        }
+      },
+      additionalProperties: false
+    },
+    refresh_strategy: {
+      type: "string",
+      enum: ["data-changed", "epoch-changed", "time-based", "manual", "once"],
+      description: "Strategy for determining when a completed task should re-run"
+    },
+    task_circuit_breaker: {
+      type: "object",
+      required: ["max_executions", "on_break"],
+      properties: {
+        max_executions: {
+          type: "integer",
+          minimum: 1,
+          description: "Max executions before breaker trips"
+        },
+        on_break: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "Tokens to inject when breaker trips"
+        }
+      },
+      additionalProperties: false
+    },
+    inference_hints: {
+      type: "object",
+      description: "LLM inference hints \u2014 opt-in metadata for AI-assisted completion detection",
+      properties: {
+        criteria: {
+          type: "string",
+          description: "Human-readable completion criteria"
+        },
+        keywords: {
+          type: "array",
+          items: { type: "string" },
+          description: "Keywords to help the LLM understand the domain"
+        },
+        suggestedChecks: {
+          type: "array",
+          items: { type: "string" },
+          description: "Suggested checks for verification"
+        },
+        autoDetectable: {
+          type: "boolean",
+          description: "Whether the LLM should attempt to auto-detect completion (default: false)"
+        }
+      },
+      additionalProperties: false
+    }
+  }
+};
+
+// src/event-graph/schema-validator.ts
+var import_ajv2 = __toESM(require_ajv());
+var _compiled2 = null;
+function getValidator2() {
+  if (_compiled2) return _compiled2;
+  const ajv = new import_ajv2.default({ allErrors: true });
+  addFormats(ajv);
+  _compiled2 = ajv.compile(event_graph_schema_default);
+  return _compiled2;
+}
+function validateGraphSchema(config) {
+  const validate = getValidator2();
+  const valid = validate(config);
+  if (valid) return { ok: true, errors: [] };
+  const errors = (validate.errors ?? []).map((e) => {
+    const path = e.instancePath || "/";
+    return `${path}: ${e.message ?? "unknown error"}`;
+  });
+  return { ok: false, errors };
+}
+
+// src/stores/localStorage.ts
+var LocalStorageStore = class {
+  prefix;
+  constructor(options = {}) {
+    this.prefix = options.prefix ?? "yamlflow";
+    if (typeof localStorage === "undefined") {
+      throw new Error("LocalStorageStore requires localStorage (browser environment)");
+    }
+  }
+  runKey(runId) {
+    return `${this.prefix}:run:${runId}`;
+  }
+  dataKey(runId) {
+    return `${this.prefix}:data:${runId}`;
+  }
+  indexKey() {
+    return `${this.prefix}:runs`;
+  }
+  async saveRunState(runId, state) {
+    localStorage.setItem(this.runKey(runId), JSON.stringify(state));
+    const runs = await this.listRuns();
+    if (!runs.includes(runId)) {
+      runs.push(runId);
+      localStorage.setItem(this.indexKey(), JSON.stringify(runs));
+    }
+  }
+  async loadRunState(runId) {
+    const raw = localStorage.getItem(this.runKey(runId));
+    return raw ? JSON.parse(raw) : null;
+  }
+  async deleteRunState(runId) {
+    localStorage.removeItem(this.runKey(runId));
+    localStorage.removeItem(this.dataKey(runId));
+    const runs = await this.listRuns();
+    const filtered = runs.filter((id) => id !== runId);
+    localStorage.setItem(this.indexKey(), JSON.stringify(filtered));
+  }
+  async setData(runId, key, value) {
+    const allData = await this.getAllData(runId);
+    allData[key] = value;
+    localStorage.setItem(this.dataKey(runId), JSON.stringify(allData));
+  }
+  async getData(runId, key) {
+    const allData = await this.getAllData(runId);
+    return allData[key];
+  }
+  async getAllData(runId) {
+    const raw = localStorage.getItem(this.dataKey(runId));
+    return raw ? JSON.parse(raw) : {};
+  }
+  async clearData(runId) {
+    localStorage.removeItem(this.dataKey(runId));
+  }
+  async listRuns() {
+    const raw = localStorage.getItem(this.indexKey());
+    return raw ? JSON.parse(raw) : [];
+  }
+  /**
+   * Clear all flow data from localStorage
+   */
+  clearAll() {
+    const keysToRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(this.prefix + ":")) {
+        keysToRemove.push(key);
+      }
+    }
+    keysToRemove.forEach((key) => localStorage.removeItem(key));
+  }
+};
+
+// src/stores/file.ts
+var FileStore = class {
+  directory;
+  fs = null;
+  path = null;
+  constructor(options) {
+    this.directory = options.directory;
+  }
+  async ensureModules() {
+    if (!this.fs || !this.path) {
+      this.fs = await import('fs/promises');
+      this.path = await import('path');
+      await this.fs.mkdir(this.directory, { recursive: true });
+    }
+  }
+  runPath(runId) {
+    return this.path.join(this.directory, `${runId}.run.json`);
+  }
+  dataPath(runId) {
+    return this.path.join(this.directory, `${runId}.data.json`);
+  }
+  async saveRunState(runId, state) {
+    await this.ensureModules();
+    await this.fs.writeFile(
+      this.runPath(runId),
+      JSON.stringify(state, null, 2),
+      "utf-8"
+    );
+  }
   async loadRunState(runId) {
     await this.ensureModules();
     try {
@@ -8719,7 +9247,7 @@ function createLiveGraph(config, executionId) {
   const id = executionId ?? `live-${Date.now()}`;
   const tasks = {};
   for (const taskName of Object.keys(config.tasks)) {
-    tasks[taskName] = createDefaultTaskState3();
+    tasks[taskName] = createDefaultGraphEngineStore3();
   }
   const state = {
     status: "running",
@@ -8747,7 +9275,7 @@ function applyEvent(live, event) {
       newState = applyTaskStart(state, event.taskName);
       break;
     case "task-completed":
-      newState = applyTaskCompletion(state, config, event.taskName, event.result);
+      newState = applyTaskCompletion(state, config, event.taskName, event.result, event.dataHash, event.data);
       break;
     case "task-failed":
       newState = applyTaskFailure(state, config, event.taskName, event.error);
@@ -8755,6 +9283,9 @@ function applyEvent(live, event) {
     case "task-progress":
       newState = applyTaskProgress(state, event.taskName, event.message, event.progress);
       break;
+    case "task-restart":
+      newState = applyTaskRestart(state, event.taskName);
+      break;
     case "inject-tokens":
       newState = {
         ...state,
@@ -8770,6 +9301,9 @@ function applyEvent(live, event) {
   }
   return { config, state: newState };
 }
+function applyEvents(live, events) {
+  return events.reduce((current, event) => applyEvent(current, event), live);
+}
 function addNode(live, name, taskConfig) {
   if (live.config.tasks[name]) return live;
   return {
@@ -8779,7 +9313,7 @@ function addNode(live, name, taskConfig) {
     },
     state: {
       ...live.state,
-      tasks: { ...live.state.tasks, [name]: createDefaultTaskState3() },
+      tasks: { ...live.state.tasks, [name]: createDefaultGraphEngineStore3() },
       lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
     }
   };
@@ -8896,7 +9430,7 @@ function resetNode(live, name) {
       ...live.state,
       tasks: {
         ...live.state.tasks,
-        [name]: createDefaultTaskState3()
+        [name]: createDefaultGraphEngineStore3()
       },
       lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
     }
@@ -8935,7 +9469,7 @@ function enableNode(live, name) {
 function getNode(live, name) {
   const config = live.config.tasks[name];
   if (!config) return void 0;
-  const state = live.state.tasks[name] ?? createDefaultTaskState3();
+  const state = live.state.tasks[name] ?? createDefaultGraphEngineStore3();
   return { name, config, state };
 }
 function snapshot(live) {
@@ -8973,7 +9507,7 @@ function restore(data) {
   }
   return { config, state };
 }
-function createDefaultTaskState3() {
+function createDefaultGraphEngineStore3() {
   return {
     status: "not-started",
     executionCount: 0,
@@ -9014,55 +9548,101 @@ function schedule(live) {
   const blocked = [];
   for (const [taskName, taskConfig] of Object.entries(graphTasks)) {
     const taskState = state.tasks[taskName];
-    if (!isRepeatableTask(taskConfig)) {
-      if (taskState?.status === TASK_STATUS.COMPLETED || taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
-        continue;
-      }
-    } else {
-      if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
-        continue;
-      }
-      const maxExec = getRepeatableMax(taskConfig);
-      if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
-        continue;
-      }
-      if (taskConfig.circuit_breaker && taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
-        continue;
-      }
-      if (taskState?.status === TASK_STATUS.COMPLETED) {
-        const requires2 = getRequires(taskConfig);
-        if (requires2.length > 0) {
-          const hasRefreshed = requires2.some((req) => {
-            for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
-              if (getProvides(otherConfig).includes(req)) {
-                const otherState = state.tasks[otherName];
-                if (otherState && otherState.executionCount > taskState.lastEpoch) return true;
-              }
-            }
-            return false;
-          });
-          if (!hasRefreshed) continue;
-        } else {
-          continue;
-        }
-      }
+    const strategy = getRefreshStrategy(taskConfig, config.settings);
+    const rerunnable = strategy !== "once";
+    if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
+      continue;
     }
-    const requires = getRequires(taskConfig);
-    if (requires.length === 0) {
-      eligible.push(taskName);
+    const maxExec = getMaxExecutions(taskConfig);
+    if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
       continue;
     }
-    const missingTokens = [];
-    const pendingTokens = [];
-    const failedTokenInfo = [];
-    for (const token of requires) {
-      if (availableOutputs.has(token)) continue;
-      const producers = producerMap[token] || [];
-      if (producers.length === 0) {
-        missingTokens.push(token);
-      } else {
-        const allFailed = producers.every((p) => isNonActiveTask(state.tasks[p]));
-        if (allFailed) {
+    if (taskConfig.circuit_breaker && taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
+      continue;
+    }
+    if (!rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      continue;
+    }
+    if (rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      const requires2 = getRequires(taskConfig);
+      let shouldSkip = false;
+      switch (strategy) {
+        case "data-changed": {
+          if (requires2.length > 0) {
+            const hasChangedData = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (!otherState) continue;
+                  const consumed = taskState.lastConsumedHashes?.[req];
+                  if (otherState.lastDataHash == null) {
+                    return otherState.executionCount > taskState.lastEpoch;
+                  }
+                  return otherState.lastDataHash !== consumed;
+                }
+              }
+              return false;
+            });
+            if (!hasChangedData) shouldSkip = true;
+          } else {
+            shouldSkip = true;
+          }
+          break;
+        }
+        case "epoch-changed": {
+          if (requires2.length > 0) {
+            const hasRefreshed = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (otherState && otherState.executionCount > taskState.lastEpoch) return true;
+                }
+              }
+              return false;
+            });
+            if (!hasRefreshed) shouldSkip = true;
+          } else {
+            shouldSkip = true;
+          }
+          break;
+        }
+        case "time-based": {
+          const interval = taskConfig.refreshInterval ?? 0;
+          if (interval <= 0) {
+            shouldSkip = true;
+            break;
+          }
+          const completedAt = taskState.completedAt;
+          if (!completedAt) {
+            shouldSkip = true;
+            break;
+          }
+          const elapsedSec = (Date.now() - Date.parse(completedAt)) / 1e3;
+          if (elapsedSec < interval) shouldSkip = true;
+          break;
+        }
+        case "manual":
+          shouldSkip = true;
+          break;
+      }
+      if (shouldSkip) continue;
+    }
+    const requires = getRequires(taskConfig);
+    if (requires.length === 0) {
+      eligible.push(taskName);
+      continue;
+    }
+    const missingTokens = [];
+    const pendingTokens = [];
+    const failedTokenInfo = [];
+    for (const token of requires) {
+      if (availableOutputs.has(token)) continue;
+      const producers = producerMap[token] || [];
+      if (producers.length === 0) {
+        missingTokens.push(token);
+      } else {
+        const allFailed = producers.every((p) => isNonActiveTask(state.tasks[p]));
+        if (allFailed) {
           failedTokenInfo.push({ token, failedProducer: producers[0] });
         } else {
           pendingTokens.push(token);
@@ -9440,255 +10020,644 @@ function getDownstream(live, nodeName) {
   }));
   return { nodeName, nodes, tokens: [...tokenSet] };
 }
-
-// src/inference/core.ts
-var DEFAULT_THRESHOLD = 0.5;
-var DEFAULT_SYSTEM_PROMPT = `You are a workflow completion analyzer. Given a graph of tasks with their current states, evidence, and inference hints, determine which tasks appear to be completed based on the available evidence.
-
-For each task you analyze, provide a JSON response. Be conservative \u2014 only mark tasks as completed when the evidence strongly supports it.`;
-function buildInferencePrompt(live, options = {}) {
-  const { scope, context, systemPrompt } = options;
-  const graphTasks = getAllTasks(live.config);
-  const { state } = live;
-  const candidates = getAnalyzableCandidates(live, scope);
-  if (candidates.length === 0) {
-    return "";
+var MemoryJournal = class {
+  buffer = [];
+  append(event) {
+    this.buffer.push(event);
   }
-  const lines = [];
-  lines.push(systemPrompt || DEFAULT_SYSTEM_PROMPT);
-  lines.push("");
-  lines.push("## Graph State");
-  lines.push("");
-  lines.push(`Available tokens: ${state.availableOutputs.length > 0 ? state.availableOutputs.join(", ") : "(none)"}`);
-  lines.push("");
-  const completedTasks = Object.entries(state.tasks).filter(([_, ts]) => ts.status === "completed").map(([name]) => name);
-  if (completedTasks.length > 0) {
-    lines.push(`Completed tasks: ${completedTasks.join(", ")}`);
-    lines.push("");
+  drain() {
+    const events = this.buffer;
+    this.buffer = [];
+    return events;
   }
-  lines.push("## Tasks to Analyze");
-  lines.push("");
-  for (const taskName of candidates) {
-    const taskConfig = graphTasks[taskName];
-    const taskState = state.tasks[taskName];
-    lines.push(`### ${taskName}`);
-    if (taskConfig.description) {
-      lines.push(`Description: ${taskConfig.description}`);
-    }
-    const requires = getRequires(taskConfig);
-    const provides = getProvides(taskConfig);
-    if (requires.length > 0) lines.push(`Requires: ${requires.join(", ")}`);
-    if (provides.length > 0) lines.push(`Provides: ${provides.join(", ")}`);
-    lines.push(`Current status: ${taskState?.status || "not-started"}`);
-    const hints = taskConfig.inference;
-    if (hints) {
-      if (hints.criteria) lines.push(`Completion criteria: ${hints.criteria}`);
-      if (hints.keywords?.length) lines.push(`Keywords: ${hints.keywords.join(", ")}`);
-      if (hints.suggestedChecks?.length) lines.push(`Suggested checks: ${hints.suggestedChecks.join("; ")}`);
+  get size() {
+    return this.buffer.length;
+  }
+};
+var FileJournal = class {
+  constructor(path) {
+    this.path = path;
+    if (!existsSync(path)) {
+      writeFileSync(path, "", "utf-8");
+    }
+  }
+  path;
+  pending = 0;
+  append(event) {
+    appendFileSync(this.path, JSON.stringify(event) + "\n", "utf-8");
+    this.pending++;
+  }
+  drain() {
+    const content = readFileSync(this.path, "utf-8").trim();
+    writeFileSync(this.path, "", "utf-8");
+    this.pending = 0;
+    if (!content) return [];
+    return content.split("\n").map((line) => JSON.parse(line));
+  }
+  get size() {
+    try {
+      const content = readFileSync(this.path, "utf-8").trim();
+      if (!content) return 0;
+      return content.split("\n").length;
+    } catch {
+      return this.pending;
     }
-    lines.push("");
   }
-  if (context) {
-    lines.push("## Additional Context / Evidence");
-    lines.push("");
-    lines.push(context);
-    lines.push("");
+};
+function computeDataHash(data) {
+  const json = stableStringify(data);
+  return createHash("sha256").update(json).digest("hex").slice(0, 16);
+}
+function stableStringify(value) {
+  if (value === null || value === void 0 || typeof value !== "object") {
+    return JSON.stringify(value);
   }
-  lines.push("## Response Format");
-  lines.push("");
-  lines.push("Respond with a JSON array of objects, one per task you have evidence for:");
-  lines.push("```json");
-  lines.push("[");
-  lines.push("  {");
-  lines.push('    "taskName": "task-name",');
-  lines.push('    "confidence": 0.0 to 1.0,');
-  lines.push('    "reasoning": "explanation of why you believe this task is complete or not"');
-  lines.push("  }");
-  lines.push("]");
-  lines.push("```");
-  lines.push("");
-  lines.push("Rules:");
-  lines.push('- Only include tasks from the "Tasks to Analyze" section');
-  lines.push("- confidence 0.0 = no evidence of completion, 1.0 = certain it is complete");
-  lines.push("- If you have no evidence for a task, omit it from the array");
-  lines.push("- Be conservative \u2014 require clear evidence before high confidence");
-  lines.push("- Respond ONLY with the JSON array, no additional text");
-  return lines.join("\n");
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
 }
-async function inferCompletions(live, adapter, options = {}) {
-  options.threshold ?? DEFAULT_THRESHOLD;
-  const analyzedNodes = getAnalyzableCandidates(live, options.scope);
-  if (analyzedNodes.length === 0) {
-    return { suggestions: [], promptUsed: "", rawResponse: "", analyzedNodes: [] };
+function encodeCallbackToken(taskName) {
+  const payload = JSON.stringify({ t: taskName, n: Date.now().toString(36) + Math.random().toString(36).slice(2, 6) });
+  return Buffer.from(payload).toString("base64url");
+}
+function decodeCallbackToken(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token, "base64url").toString());
+    if (typeof payload?.t === "string") return { taskName: payload.t };
+    return null;
+  } catch {
+    return null;
   }
-  const prompt = buildInferencePrompt(live, options);
-  const rawResponse = await adapter.analyze(prompt);
-  const suggestions = parseInferenceResponse(rawResponse, analyzedNodes);
-  return {
-    suggestions,
-    promptUsed: prompt,
-    rawResponse,
-    analyzedNodes
-  };
 }
-function applyInferences(live, result, threshold = DEFAULT_THRESHOLD) {
-  let current = live;
-  for (const suggestion of result.suggestions) {
-    if (suggestion.confidence < threshold) continue;
-    const taskState = current.state.tasks[suggestion.taskName];
-    if (!taskState) continue;
-    if (taskState.status === "completed" || taskState.status === "running") continue;
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    current = applyEvent(current, {
+function createReactiveGraph(config, options, executionId) {
+  const {
+    handlers: initialHandlers,
+    journal = new MemoryJournal(),
+    onDrain
+  } = options;
+  let live = createLiveGraph(config, executionId);
+  let disposed = false;
+  const handlers = new Map(Object.entries(initialHandlers));
+  let draining = false;
+  let drainQueued = false;
+  function drain() {
+    if (disposed) return;
+    if (draining) {
+      drainQueued = true;
+      return;
+    }
+    draining = true;
+    try {
+      do {
+        drainQueued = false;
+        drainOnce();
+      } while (drainQueued);
+    } finally {
+      draining = false;
+    }
+  }
+  function drainOnce() {
+    const events = journal.drain();
+    if (events.length > 0) {
+      live = applyEvents(live, events);
+    }
+    const result = schedule(live);
+    if (events.length > 0) {
+      onDrain?.(events, live, result);
+    }
+    for (const taskName of result.eligible) {
+      dispatchTask(taskName);
+    }
+  }
+  function resolveUpstreamState(taskName) {
+    const taskConfig = live.config.tasks[taskName];
+    const requires = taskConfig.requires ?? [];
+    const tokenToTask = /* @__PURE__ */ new Map();
+    for (const [name, cfg] of Object.entries(live.config.tasks)) {
+      for (const token of cfg.provides ?? []) {
+        tokenToTask.set(token, name);
+      }
+    }
+    const state = {};
+    for (const token of requires) {
+      const producerTask = tokenToTask.get(token);
+      if (producerTask) {
+        state[token] = live.state.tasks[producerTask]?.data;
+      } else {
+        state[token] = void 0;
+      }
+    }
+    return state;
+  }
+  async function runPipeline(taskName, callbackToken) {
+    const taskConfig = live.config.tasks[taskName];
+    const handlerNames = taskConfig.taskHandlers ?? [];
+    const upstreamState = resolveUpstreamState(taskName);
+    for (const handlerName of handlerNames) {
+      const handler = handlers.get(handlerName);
+      if (!handler) {
+        throw new Error(`Handler '${handlerName}' not found in registry (task '${taskName}')`);
+      }
+      const input = {
+        nodeId: taskName,
+        state: upstreamState,
+        taskState: live.state.tasks[taskName],
+        config: taskConfig,
+        callbackToken
+      };
+      const status = await handler(input);
+      if (status === "task-initiate-failure") {
+        throw new Error(`Handler '${handlerName}' returned task-initiate-failure (task '${taskName}')`);
+      }
+    }
+  }
+  function dispatchTask(taskName) {
+    const taskConfig = live.config.tasks[taskName];
+    const handlerNames = taskConfig?.taskHandlers;
+    if (!handlerNames || handlerNames.length === 0) {
+      return;
+    }
+    journal.append({
       type: "task-started",
-      taskName: suggestion.taskName,
-      timestamp: now
+      taskName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
     });
-    current = applyEvent(current, {
-      type: "task-completed",
-      taskName: suggestion.taskName,
-      timestamp: now,
-      result: "llm-inferred"
+    const callbackToken = encodeCallbackToken(taskName);
+    runPipeline(taskName, callbackToken).catch((error) => {
+      if (disposed) return;
+      journal.append({
+        type: "task-failed",
+        taskName,
+        error: error.message ?? String(error),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      drain();
     });
   }
-  return current;
-}
-async function inferAndApply(live, adapter, options = {}) {
-  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
-  const inference = await inferCompletions(live, adapter, options);
-  const updated = applyInferences(live, inference, threshold);
-  const applied = inference.suggestions.filter((s) => s.confidence >= threshold);
-  const skipped = inference.suggestions.filter((s) => s.confidence < threshold);
   return {
-    live: updated,
-    inference,
-    applied,
-    skipped
+    push(event) {
+      if (disposed) return;
+      if (event.type === "task-completed" && event.data && !event.dataHash) {
+        event = { ...event, dataHash: computeDataHash(event.data) };
+      }
+      journal.append(event);
+      drain();
+    },
+    pushAll(events) {
+      if (disposed) return;
+      for (const event of events) {
+        if (event.type === "task-completed" && event.data && !event.dataHash) {
+          journal.append({ ...event, dataHash: computeDataHash(event.data) });
+        } else {
+          journal.append(event);
+        }
+      }
+      drain();
+    },
+    resolveCallback(callbackToken, data, errors) {
+      if (disposed) return;
+      const decoded = decodeCallbackToken(callbackToken);
+      if (!decoded) return;
+      const { taskName } = decoded;
+      if (!live.config.tasks[taskName]) return;
+      if (errors && errors.length > 0) {
+        journal.append({
+          type: "task-failed",
+          taskName,
+          error: errors.join("; "),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      } else {
+        const dataHash = data && Object.keys(data).length > 0 ? computeDataHash(data) : void 0;
+        journal.append({
+          type: "task-completed",
+          taskName,
+          data,
+          dataHash,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      drain();
+    },
+    addNode(name, taskConfig) {
+      if (disposed) return;
+      live = addNode(live, name, taskConfig);
+      drain();
+    },
+    removeNode(name) {
+      if (disposed) return;
+      live = removeNode(live, name);
+    },
+    addRequires(nodeName, tokens) {
+      if (disposed) return;
+      live = addRequires(live, nodeName, tokens);
+      drain();
+    },
+    removeRequires(nodeName, tokens) {
+      if (disposed) return;
+      live = removeRequires(live, nodeName, tokens);
+      drain();
+    },
+    addProvides(nodeName, tokens) {
+      if (disposed) return;
+      live = addProvides(live, nodeName, tokens);
+      drain();
+    },
+    removeProvides(nodeName, tokens) {
+      if (disposed) return;
+      live = removeProvides(live, nodeName, tokens);
+    },
+    registerHandler(name, fn) {
+      handlers.set(name, fn);
+    },
+    unregisterHandler(name) {
+      handlers.delete(name);
+    },
+    retrigger(taskName) {
+      if (disposed) return;
+      if (!live.config.tasks[taskName]) return;
+      journal.append({
+        type: "task-restart",
+        taskName,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      drain();
+    },
+    retriggerAll(taskNames) {
+      if (disposed) return;
+      for (const name of taskNames) {
+        if (!live.config.tasks[name]) continue;
+        journal.append({
+          type: "task-restart",
+          taskName: name,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      drain();
+    },
+    getState() {
+      return live;
+    },
+    getSchedule() {
+      return schedule(live);
+    },
+    dispose() {
+      disposed = true;
+    }
   };
 }
-function getAnalyzableCandidates(live, scope) {
-  const graphTasks = getAllTasks(live.config);
-  const { state } = live;
-  const candidates = [];
-  for (const [name, config] of Object.entries(graphTasks)) {
-    const taskState = state.tasks[name];
-    if (taskState?.status === "completed" || taskState?.status === "running") continue;
-    if (scope) {
-      if (scope.includes(name)) candidates.push(name);
-    } else {
-      if (config.inference?.autoDetectable) candidates.push(name);
+
+// src/continuous-event-graph/validate.ts
+function validateLiveGraph(live) {
+  const issues = [];
+  const { config, state } = live;
+  const tasks = getAllTasks(config);
+  const taskNames = Object.keys(tasks);
+  for (const name of taskNames) {
+    if (!state.tasks[name]) {
+      issues.push({
+        severity: "error",
+        code: "MISSING_STATE",
+        message: `Task "${name}" exists in config but has no state entry`,
+        tasks: [name]
+      });
     }
   }
-  return candidates;
-}
-function parseInferenceResponse(rawResponse, validNodes, _threshold) {
-  const validSet = new Set(validNodes);
-  try {
-    const jsonStr = extractJson(rawResponse);
-    if (!jsonStr) return [];
-    const parsed = JSON.parse(jsonStr);
-    if (!Array.isArray(parsed)) return [];
-    const suggestions = [];
-    for (const item of parsed) {
-      if (!item || typeof item !== "object") continue;
-      if (typeof item.taskName !== "string") continue;
-      if (typeof item.confidence !== "number") continue;
-      if (!validSet.has(item.taskName)) continue;
-      const confidence = Math.max(0, Math.min(1, item.confidence));
-      suggestions.push({
-        taskName: item.taskName,
-        confidence,
-        reasoning: typeof item.reasoning === "string" ? item.reasoning : "",
-        detectionMethod: "llm-inferred"
+  for (const name of Object.keys(state.tasks)) {
+    if (!tasks[name]) {
+      issues.push({
+        severity: "warning",
+        code: "ORPHAN_STATE",
+        message: `State entry "${name}" has no corresponding task config`,
+        tasks: [name]
       });
     }
-    return suggestions;
-  } catch {
-    return [];
   }
-}
-function extractJson(text) {
-  if (!text || typeof text !== "string") return null;
-  const trimmed = text.trim();
-  const fenceMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
-  if (fenceMatch) return fenceMatch[1].trim();
-  const firstBracket = trimmed.indexOf("[");
-  const lastBracket = trimmed.lastIndexOf("]");
-  if (firstBracket !== -1 && lastBracket > firstBracket) {
-    return trimmed.slice(firstBracket, lastBracket + 1);
+  for (const name of taskNames) {
+    const ts = state.tasks[name];
+    if (!ts) continue;
+    if (ts.status === TASK_STATUS.RUNNING && !ts.startedAt) {
+      issues.push({
+        severity: "warning",
+        code: "RUNNING_WITHOUT_START",
+        message: `Task "${name}" is running but has no startedAt timestamp`,
+        tasks: [name]
+      });
+    }
+    if (ts.status === TASK_STATUS.COMPLETED && !ts.completedAt) {
+      issues.push({
+        severity: "warning",
+        code: "COMPLETED_WITHOUT_TIMESTAMP",
+        message: `Task "${name}" is completed but has no completedAt timestamp`,
+        tasks: [name]
+      });
+    }
+    if (ts.status === TASK_STATUS.FAILED) {
+      if (!ts.failedAt) {
+        issues.push({
+          severity: "warning",
+          code: "FAILED_WITHOUT_INFO",
+          message: `Task "${name}" is failed but has no failedAt timestamp`,
+          tasks: [name]
+        });
+      }
+      if (!ts.error) {
+        issues.push({
+          severity: "info",
+          code: "FAILED_WITHOUT_INFO",
+          message: `Task "${name}" is failed but has no error message`,
+          tasks: [name]
+        });
+      }
+    }
   }
-  if (trimmed.startsWith("[")) return trimmed;
-  return null;
+  const expectedOutputs = /* @__PURE__ */ new Set();
+  for (const name of taskNames) {
+    const ts = state.tasks[name];
+    if (ts?.status === TASK_STATUS.COMPLETED) {
+      for (const token of getProvides(tasks[name])) {
+        expectedOutputs.add(token);
+      }
+    }
+  }
+  const actualOutputs = new Set(state.availableOutputs);
+  const allProducible = /* @__PURE__ */ new Set();
+  for (const taskConfig of Object.values(tasks)) {
+    for (const t of getProvides(taskConfig)) allProducible.add(t);
+    if (taskConfig.on) {
+      for (const tokens of Object.values(taskConfig.on)) {
+        for (const t of tokens) allProducible.add(t);
+      }
+    }
+    if (taskConfig.on_failure) {
+      for (const t of taskConfig.on_failure) allProducible.add(t);
+    }
+  }
+  for (const token of actualOutputs) {
+    if (!expectedOutputs.has(token) && !allProducible.has(token)) {
+      issues.push({
+        severity: "info",
+        code: "INJECTED_TOKEN",
+        message: `Token "${token}" is available but no task in the graph can produce it (likely injected)`,
+        tokens: [token]
+      });
+    }
+  }
+  for (const token of expectedOutputs) {
+    if (!actualOutputs.has(token)) {
+      issues.push({
+        severity: "warning",
+        code: "MISSING_OUTPUT",
+        message: `Token "${token}" should be available (its producer completed) but is not in availableOutputs`,
+        tokens: [token]
+      });
+    }
+  }
+  for (const name of taskNames) {
+    const ts = state.tasks[name];
+    if (!ts) continue;
+    if (ts.executionCount < 0) {
+      issues.push({
+        severity: "error",
+        code: "INVALID_EXECUTION_COUNT",
+        message: `Task "${name}" has negative execution count: ${ts.executionCount}`,
+        tasks: [name]
+      });
+    }
+    const maxExec = tasks[name].maxExecutions;
+    if (maxExec !== void 0 && ts.executionCount > maxExec) {
+      issues.push({
+        severity: "error",
+        code: "EXCEEDED_MAX_EXECUTIONS",
+        message: `Task "${name}" executed ${ts.executionCount} times, exceeding maxExecutions of ${maxExec}`,
+        tasks: [name]
+      });
+    }
+  }
+  return buildResult2(issues);
 }
-function createCliAdapter(opts) {
-  const timeout = opts.timeout ?? 6e4;
-  return {
-    analyze: (prompt) => {
-      return new Promise((resolve2, reject) => {
-        const args = opts.args(prompt);
-        const child = execFile(
-          opts.command,
-          opts.stdin ? opts.args("") : args,
-          {
-            timeout,
-            cwd: opts.cwd,
-            env: opts.env ? { ...process.env, ...opts.env } : void 0,
-            maxBuffer: 10 * 1024 * 1024
-            // 10MB
-          },
-          (error, stdout, stderr) => {
-            if (error) {
-              reject(new Error(
-                `CLI adapter failed: ${opts.command} exited with ${error.code ?? "error"}` + (stderr ? `
-stderr: ${stderr.slice(0, 500)}` : "") + `
-${error.message}`
-              ));
-            } else {
-              resolve2(stdout);
-            }
-          }
-        );
-        if (opts.stdin && child.stdin) {
-          child.stdin.write(prompt);
-          child.stdin.end();
-        }
+function validateReactiveGraph(input) {
+  const { graph, handlers } = input;
+  const live = graph.getState();
+  const issues = [];
+  const tasks = getAllTasks(live.config);
+  const taskNames = Object.keys(tasks);
+  const handlerNames = new Set(Object.keys(handlers));
+  const referencedHandlers = /* @__PURE__ */ new Set();
+  for (const name of taskNames) {
+    const taskHandlers = tasks[name].taskHandlers;
+    if (taskHandlers) {
+      for (const h of taskHandlers) {
+        referencedHandlers.add(h);
+      }
+    }
+  }
+  for (const name of taskNames) {
+    const taskHandlers = tasks[name].taskHandlers;
+    if (!taskHandlers) continue;
+    for (const h of taskHandlers) {
+      if (!handlers[h]) {
+        issues.push({
+          severity: "error",
+          code: "MISSING_HANDLER",
+          message: `Task "${name}" references handler "${h}" but it is not in the registry`,
+          tasks: [name]
+        });
+      }
+    }
+  }
+  for (const name of handlerNames) {
+    if (!referencedHandlers.has(name)) {
+      issues.push({
+        severity: "warning",
+        code: "ORPHAN_HANDLER",
+        message: `Handler "${name}" is registered but not referenced by any task's taskHandlers`,
+        tasks: [name]
       });
     }
-  };
+  }
+  const liveResult = validateLiveGraph(live);
+  issues.push(...liveResult.issues);
+  return buildResult2(issues);
 }
-function createHttpAdapter(opts) {
-  const timeout = opts.timeout ?? 6e4;
+function buildResult2(issues) {
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
   return {
-    analyze: async (prompt) => {
-      const body = opts.buildBody ? opts.buildBody(prompt) : { prompt };
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeout);
-      try {
-        const response = await fetch(opts.url, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            ...opts.headers ?? {}
-          },
-          body: JSON.stringify(body),
-          signal: controller.signal
-        });
-        if (!response.ok) {
-          const text = await response.text().catch(() => "");
-          throw new Error(`HTTP ${response.status}: ${text.slice(0, 500)}`);
+    valid: errors.length === 0,
+    issues,
+    errors,
+    warnings
+  };
+}
+
+// src/continuous-event-graph/mutate.ts
+function mutateGraph(live, mutations) {
+  let current = live;
+  for (const mutation of mutations) {
+    current = applySingleMutation(current, mutation);
+  }
+  return current;
+}
+function applySingleMutation(live, mutation) {
+  switch (mutation.type) {
+    case "add-node":
+      return addNode(live, mutation.name, mutation.config);
+    case "remove-node":
+      return removeNode(live, mutation.name);
+    case "add-requires":
+      return addRequires(live, mutation.taskName, mutation.tokens);
+    case "remove-requires":
+      return removeRequires(live, mutation.taskName, mutation.tokens);
+    case "add-provides":
+      return addProvides(live, mutation.taskName, mutation.tokens);
+    case "remove-provides":
+      return removeProvides(live, mutation.taskName, mutation.tokens);
+    case "inject-tokens":
+      return injectTokens(live, mutation.tokens);
+    case "drain-tokens":
+      return drainTokens(live, mutation.tokens);
+    case "reset-node":
+      return resetNode(live, mutation.name);
+    case "disable-node":
+      return disableNode(live, mutation.name);
+    case "enable-node":
+      return enableNode(live, mutation.name);
+    case "apply-events":
+      return applyEvents(live, mutation.events);
+    default:
+      throw new Error(`Unknown mutation type: ${mutation.type}`);
+  }
+}
+function createCallbackHandler(fn, getResolve) {
+  return async (input) => {
+    const { callbackToken } = input;
+    Promise.resolve(fn(input)).then((data) => getResolve()(callbackToken, data)).catch((err) => getResolve()(callbackToken, {}, [err instanceof Error ? err.message : String(err)]));
+    return "task-initiated";
+  };
+}
+function createFireAndForgetHandler(fn, getResolve) {
+  return async (input) => {
+    const { callbackToken } = input;
+    Promise.resolve(fn(input)).then(() => getResolve()(callbackToken, {})).catch(() => getResolve()(callbackToken, {}));
+    return "task-initiated";
+  };
+}
+function createShellHandler(options) {
+  const {
+    command: commandTemplate,
+    cwd,
+    env,
+    timeoutMs = 3e4,
+    exitCodeMap,
+    captureOutput = false,
+    getResolve
+  } = options;
+  return async (input) => {
+    const { callbackToken, nodeId } = input;
+    const command = commandTemplate.replace(/\$\{taskName\}/g, nodeId);
+    exec(
+      command,
+      {
+        cwd,
+        env: env ? { ...process.env, ...env } : void 0,
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024
+        // 10MB
+      },
+      (error, stdout, stderr) => {
+        const exitCode = error?.code ?? (error ? 1 : 0);
+        if (exitCode !== 0 && !exitCodeMap?.[exitCode]) {
+          getResolve()(callbackToken, {}, [`Command exited with code ${exitCode}: ${stderr || error?.message}`]);
+          return;
         }
-        const json = await response.json();
-        if (opts.extractResponse) {
-          return opts.extractResponse(json);
+        const data = {};
+        if (captureOutput) {
+          data.stdout = stdout;
+          data.stderr = stderr;
+          data.exitCode = exitCode;
         }
-        if (typeof json.response === "string") return json.response;
-        if (typeof json.text === "string") return json.text;
-        if (typeof json.content === "string") return json.content;
-        return JSON.stringify(json);
-      } finally {
-        clearTimeout(timer);
+        getResolve()(callbackToken, data);
       }
-    }
+    );
+    return "task-initiated";
+  };
+}
+function detectRuntime(scriptPath) {
+  if (scriptPath.endsWith(".js") || scriptPath.endsWith(".mjs") || scriptPath.endsWith(".ts")) return "node";
+  if (scriptPath.endsWith(".py")) return "python3";
+  if (scriptPath.endsWith(".sh")) return "bash";
+  return "bash";
+}
+function createScriptHandler(options) {
+  const {
+    scriptPath,
+    runtime,
+    args = [],
+    cwd,
+    timeoutMs = 6e4,
+    captureOutput = false,
+    getResolve
+  } = options;
+  const resolvedRuntime = runtime ?? detectRuntime(scriptPath);
+  const shellArgs = [ctx_taskName_placeholder, ...args].join(" ");
+  const command = `${resolvedRuntime} ${scriptPath} ${shellArgs}`;
+  return createShellHandler({
+    command: command.replace(ctx_taskName_placeholder, "${taskName}"),
+    cwd,
+    timeoutMs,
+    captureOutput,
+    getResolve
+  });
+}
+var ctx_taskName_placeholder = "__TASK_NAME__";
+function createWebhookHandler(options) {
+  const {
+    url: urlTemplate,
+    method = "POST",
+    headers = {},
+    timeoutMs = 3e4,
+    failOnNon2xx = true,
+    getResolve
+  } = options;
+  return async (input) => {
+    const { callbackToken, nodeId, config } = input;
+    const url = urlTemplate.replace(/\$\{taskName\}/g, nodeId);
+    const body = JSON.stringify({
+      taskName: nodeId,
+      callbackToken,
+      config
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    fetch(url, {
+      method,
+      headers: { "Content-Type": "application/json", ...headers },
+      body,
+      signal: controller.signal
+    }).then(async (response) => {
+      clearTimeout(timer);
+      if (failOnNon2xx && !response.ok) {
+        const text = await response.text().catch(() => "");
+        getResolve()(callbackToken, {}, [`HTTP ${response.status}: ${text}`]);
+        return;
+      }
+      const data = await response.json().catch(() => ({}));
+      getResolve()(callbackToken, data);
+    }).catch((err) => {
+      clearTimeout(timer);
+      getResolve()(callbackToken, {}, [err instanceof Error ? err.message : String(err)]);
+    });
+    return "task-initiated";
+  };
+}
+function createNoopHandler(getResolve, staticData) {
+  return async (input) => {
+    getResolve()(input.callbackToken, staticData ?? {});
+    return "task-initiated";
   };
 }
 
@@ -10005,17 +10974,17 @@ var live_cards_schema_default = {
 };
 
 // src/card-compute/schema-validator.ts
-var import_ajv = __toESM(require_ajv());
-var _compiled = null;
-function getValidator() {
-  if (_compiled) return _compiled;
-  const ajv = new import_ajv.default({ allErrors: true });
+var import_ajv3 = __toESM(require_ajv());
+var _compiled3 = null;
+function getValidator3() {
+  if (_compiled3) return _compiled3;
+  const ajv = new import_ajv3.default({ allErrors: true });
   addFormats(ajv);
-  _compiled = ajv.compile(live_cards_schema_default);
-  return _compiled;
+  _compiled3 = ajv.compile(live_cards_schema_default);
+  return _compiled3;
 }
 function validateLiveCardSchema(node) {
-  const validate = getValidator();
+  const validate = getValidator3();
   const valid = validate(node);
   if (valid) return { ok: true, errors: [] };
   const errors = (validate.errors ?? []).map((e) => {
@@ -10472,6 +11441,405 @@ var CardCompute = {
   }
 };
 
-export { COMPLETION_STRATEGIES, CONFLICT_STRATEGIES, CardCompute, DEFAULTS, EXECUTION_MODES, EXECUTION_STATUS, FileStore, StepMachine as FlowEngine, LocalStorageStore, MemoryStore, StepMachine, TASK_STATUS, addDynamicTask, addNode, addProvides, addRequires, apply, applyAll, applyEvent, applyInferences, applyStepResult, batch, buildInferencePrompt, checkCircuitBreaker, computeAvailableOutputs, computeStepInput, createCliAdapter, createDefaultTaskState, createStepMachine as createEngine, createHttpAdapter, createInitialExecutionState, createInitialState, createLiveGraph, createStepMachine, detectStuckState, disableNode, drainTokens, enableNode, exportGraphConfig, exportGraphConfigToFile, extractReturnData, flowToMermaid, getAllTasks, getCandidateTasks, getDownstream, getNode, getProvides, getRequires, getTask, getUnreachableNodes, getUnreachableTokens, getUpstream, graphToMermaid, hasTask, inferAndApply, inferCompletions, injectTokens, inspect, isExecutionComplete, isNonActiveTask, isRepeatableTask, isTaskCompleted, isTaskRunning, loadGraphConfig, loadStepFlow, next, planExecution, removeNode, removeProvides, removeRequires, resetNode, resolveConfigTemplates, resolveVariables, restore, schedule, snapshot, validateGraph, validateGraphConfig, validateLiveCardSchema, validateStepFlowConfig };
+// src/continuous-event-graph/live-cards-bridge.ts
+function liveCardsToReactiveGraph(input, options = {}) {
+  let cards;
+  let boardSettings = {};
+  let boardId;
+  if (!Array.isArray(input) && "nodes" in input) {
+    const board = input;
+    cards = board.nodes;
+    boardId = board.id;
+    boardSettings = board.settings ?? {};
+  } else {
+    cards = input;
+  }
+  const {
+    sourceHandlers = {},
+    defaultSourceHandler,
+    cardHandlers = {},
+    reactiveOptions = {},
+    graphSettings = {},
+    executionId
+  } = options;
+  const cardMap = /* @__PURE__ */ new Map();
+  for (const card of cards) {
+    if (cardMap.has(card.id)) {
+      throw new Error(`Duplicate card ID: "${card.id}"`);
+    }
+    cardMap.set(card.id, card);
+  }
+  const sharedState = options.sharedState ?? /* @__PURE__ */ new Map();
+  const tasks = {};
+  for (const card of cards) {
+    const requires = card.data?.requires ?? [];
+    for (const req of requires) {
+      if (!cardMap.has(req)) {
+        throw new Error(`Card "${card.id}" requires "${req}" but no card with that ID exists`);
+      }
+    }
+    tasks[card.id] = {
+      requires: requires.length > 0 ? requires : void 0,
+      provides: [card.id],
+      taskHandlers: [card.id],
+      // each card has a named handler matching its ID
+      description: card.meta?.title ?? `${card.type}: ${card.id}`
+    };
+  }
+  const config = {
+    id: boardId ?? `live-cards-${Date.now()}`,
+    settings: {
+      completion: "manual",
+      execution_mode: "eligibility-mode",
+      ...boardSettings,
+      ...graphSettings
+    },
+    tasks
+  };
+  const handlers = {};
+  let graphRef = null;
+  const getResolve = () => (token, data, errors) => {
+    graphRef.resolveCallback(token, data, errors);
+  };
+  for (const card of cards) {
+    if (card.type === "source") {
+      handlers[card.id] = buildSourceHandler(card, sourceHandlers, defaultSourceHandler, sharedState, getResolve);
+    } else {
+      handlers[card.id] = buildCardHandler(card, cardHandlers, sharedState, cardMap, getResolve);
+    }
+  }
+  const graph = createReactiveGraph(
+    config,
+    {
+      ...reactiveOptions,
+      handlers
+    },
+    executionId
+  );
+  graphRef = graph;
+  return { graph, config, handlers, cards: cardMap, sharedState };
+}
+function buildSourceHandler(card, sourceHandlers, defaultSourceHandler, sharedState, getResolve) {
+  if (sourceHandlers[card.id]) {
+    const userHandler = sourceHandlers[card.id];
+    return async (input) => {
+      return userHandler(input);
+    };
+  }
+  if (defaultSourceHandler) {
+    const factoryHandler = defaultSourceHandler(card);
+    return async (input) => {
+      return factoryHandler(input);
+    };
+  }
+  return async (input) => {
+    const state = { ...card.state };
+    sharedState.set(card.id, state);
+    getResolve()(input.callbackToken, state);
+    return "task-initiated";
+  };
+}
+function buildCardHandler(card, cardHandlers, sharedState, cardMap, getResolve) {
+  if (cardHandlers[card.id]) {
+    const userHandler = cardHandlers[card.id];
+    return async (input) => {
+      return userHandler(input);
+    };
+  }
+  return async (input) => {
+    const computeNode = {
+      id: card.id,
+      state: { ...card.state },
+      compute: card.compute
+    };
+    const requires = card.data?.requires ?? [];
+    for (const upstreamId of requires) {
+      const upstreamState = sharedState.get(upstreamId);
+      if (upstreamState) {
+        computeNode.state[upstreamId] = upstreamState;
+      }
+      const upstreamCard = cardMap.get(upstreamId);
+      if (upstreamCard?.data?.provides && upstreamState) {
+        for (const [key, bindRef] of Object.entries(upstreamCard.data.provides)) {
+          if (typeof bindRef === "string" && bindRef.startsWith("state.")) {
+            const path = bindRef.slice(6);
+            const value = deepGet2(upstreamState, path);
+            if (value !== void 0) {
+              computeNode.state[key] = value;
+            }
+          }
+        }
+      }
+    }
+    CardCompute.run(computeNode);
+    const resultState = { ...computeNode.state };
+    sharedState.set(card.id, resultState);
+    getResolve()(input.callbackToken, resultState);
+    return "task-initiated";
+  };
+}
+function deepGet2(obj, path) {
+  if (!path || !obj) return void 0;
+  const parts = path.split(".");
+  let cur = obj;
+  for (const part of parts) {
+    if (cur == null) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+// src/inference/core.ts
+var DEFAULT_THRESHOLD = 0.5;
+var DEFAULT_SYSTEM_PROMPT = `You are a workflow completion analyzer. Given a graph of tasks with their current states, evidence, and inference hints, determine which tasks appear to be completed based on the available evidence.
+
+For each task you analyze, provide a JSON response. Be conservative \u2014 only mark tasks as completed when the evidence strongly supports it.`;
+function buildInferencePrompt(live, options = {}) {
+  const { scope, context, systemPrompt } = options;
+  const graphTasks = getAllTasks(live.config);
+  const { state } = live;
+  const candidates = getAnalyzableCandidates(live, scope);
+  if (candidates.length === 0) {
+    return "";
+  }
+  const lines = [];
+  lines.push(systemPrompt || DEFAULT_SYSTEM_PROMPT);
+  lines.push("");
+  lines.push("## Graph State");
+  lines.push("");
+  lines.push(`Available tokens: ${state.availableOutputs.length > 0 ? state.availableOutputs.join(", ") : "(none)"}`);
+  lines.push("");
+  const completedTasks = Object.entries(state.tasks).filter(([_, ts]) => ts.status === "completed").map(([name]) => name);
+  if (completedTasks.length > 0) {
+    lines.push(`Completed tasks: ${completedTasks.join(", ")}`);
+    lines.push("");
+  }
+  lines.push("## Tasks to Analyze");
+  lines.push("");
+  for (const taskName of candidates) {
+    const taskConfig = graphTasks[taskName];
+    const taskState = state.tasks[taskName];
+    lines.push(`### ${taskName}`);
+    if (taskConfig.description) {
+      lines.push(`Description: ${taskConfig.description}`);
+    }
+    const requires = getRequires(taskConfig);
+    const provides = getProvides(taskConfig);
+    if (requires.length > 0) lines.push(`Requires: ${requires.join(", ")}`);
+    if (provides.length > 0) lines.push(`Provides: ${provides.join(", ")}`);
+    lines.push(`Current status: ${taskState?.status || "not-started"}`);
+    const hints = taskConfig.inference;
+    if (hints) {
+      if (hints.criteria) lines.push(`Completion criteria: ${hints.criteria}`);
+      if (hints.keywords?.length) lines.push(`Keywords: ${hints.keywords.join(", ")}`);
+      if (hints.suggestedChecks?.length) lines.push(`Suggested checks: ${hints.suggestedChecks.join("; ")}`);
+    }
+    lines.push("");
+  }
+  if (context) {
+    lines.push("## Additional Context / Evidence");
+    lines.push("");
+    lines.push(context);
+    lines.push("");
+  }
+  lines.push("## Response Format");
+  lines.push("");
+  lines.push("Respond with a JSON array of objects, one per task you have evidence for:");
+  lines.push("```json");
+  lines.push("[");
+  lines.push("  {");
+  lines.push('    "taskName": "task-name",');
+  lines.push('    "confidence": 0.0 to 1.0,');
+  lines.push('    "reasoning": "explanation of why you believe this task is complete or not"');
+  lines.push("  }");
+  lines.push("]");
+  lines.push("```");
+  lines.push("");
+  lines.push("Rules:");
+  lines.push('- Only include tasks from the "Tasks to Analyze" section');
+  lines.push("- confidence 0.0 = no evidence of completion, 1.0 = certain it is complete");
+  lines.push("- If you have no evidence for a task, omit it from the array");
+  lines.push("- Be conservative \u2014 require clear evidence before high confidence");
+  lines.push("- Respond ONLY with the JSON array, no additional text");
+  return lines.join("\n");
+}
+async function inferCompletions(live, adapter, options = {}) {
+  options.threshold ?? DEFAULT_THRESHOLD;
+  const analyzedNodes = getAnalyzableCandidates(live, options.scope);
+  if (analyzedNodes.length === 0) {
+    return { suggestions: [], promptUsed: "", rawResponse: "", analyzedNodes: [] };
+  }
+  const prompt = buildInferencePrompt(live, options);
+  const rawResponse = await adapter.analyze(prompt);
+  const suggestions = parseInferenceResponse(rawResponse, analyzedNodes);
+  return {
+    suggestions,
+    promptUsed: prompt,
+    rawResponse,
+    analyzedNodes
+  };
+}
+function applyInferences(live, result, threshold = DEFAULT_THRESHOLD) {
+  let current = live;
+  for (const suggestion of result.suggestions) {
+    if (suggestion.confidence < threshold) continue;
+    const taskState = current.state.tasks[suggestion.taskName];
+    if (!taskState) continue;
+    if (taskState.status === "completed" || taskState.status === "running") continue;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    current = applyEvent(current, {
+      type: "task-started",
+      taskName: suggestion.taskName,
+      timestamp: now
+    });
+    current = applyEvent(current, {
+      type: "task-completed",
+      taskName: suggestion.taskName,
+      timestamp: now,
+      result: "llm-inferred"
+    });
+  }
+  return current;
+}
+async function inferAndApply(live, adapter, options = {}) {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  const inference = await inferCompletions(live, adapter, options);
+  const updated = applyInferences(live, inference, threshold);
+  const applied = inference.suggestions.filter((s) => s.confidence >= threshold);
+  const skipped = inference.suggestions.filter((s) => s.confidence < threshold);
+  return {
+    live: updated,
+    inference,
+    applied,
+    skipped
+  };
+}
+function getAnalyzableCandidates(live, scope) {
+  const graphTasks = getAllTasks(live.config);
+  const { state } = live;
+  const candidates = [];
+  for (const [name, config] of Object.entries(graphTasks)) {
+    const taskState = state.tasks[name];
+    if (taskState?.status === "completed" || taskState?.status === "running") continue;
+    if (scope) {
+      if (scope.includes(name)) candidates.push(name);
+    } else {
+      if (config.inference?.autoDetectable) candidates.push(name);
+    }
+  }
+  return candidates;
+}
+function parseInferenceResponse(rawResponse, validNodes, _threshold) {
+  const validSet = new Set(validNodes);
+  try {
+    const jsonStr = extractJson(rawResponse);
+    if (!jsonStr) return [];
+    const parsed = JSON.parse(jsonStr);
+    if (!Array.isArray(parsed)) return [];
+    const suggestions = [];
+    for (const item of parsed) {
+      if (!item || typeof item !== "object") continue;
+      if (typeof item.taskName !== "string") continue;
+      if (typeof item.confidence !== "number") continue;
+      if (!validSet.has(item.taskName)) continue;
+      const confidence = Math.max(0, Math.min(1, item.confidence));
+      suggestions.push({
+        taskName: item.taskName,
+        confidence,
+        reasoning: typeof item.reasoning === "string" ? item.reasoning : "",
+        detectionMethod: "llm-inferred"
+      });
+    }
+    return suggestions;
+  } catch {
+    return [];
+  }
+}
+function extractJson(text) {
+  if (!text || typeof text !== "string") return null;
+  const trimmed = text.trim();
+  const fenceMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+  if (fenceMatch) return fenceMatch[1].trim();
+  const firstBracket = trimmed.indexOf("[");
+  const lastBracket = trimmed.lastIndexOf("]");
+  if (firstBracket !== -1 && lastBracket > firstBracket) {
+    return trimmed.slice(firstBracket, lastBracket + 1);
+  }
+  if (trimmed.startsWith("[")) return trimmed;
+  return null;
+}
+function createCliAdapter(opts) {
+  const timeout = opts.timeout ?? 6e4;
+  return {
+    analyze: (prompt) => {
+      return new Promise((resolve2, reject) => {
+        const args = opts.args(prompt);
+        const child = execFile(
+          opts.command,
+          opts.stdin ? opts.args("") : args,
+          {
+            timeout,
+            cwd: opts.cwd,
+            env: opts.env ? { ...process.env, ...opts.env } : void 0,
+            maxBuffer: 10 * 1024 * 1024
+            // 10MB
+          },
+          (error, stdout, stderr) => {
+            if (error) {
+              reject(new Error(
+                `CLI adapter failed: ${opts.command} exited with ${error.code ?? "error"}` + (stderr ? `
+stderr: ${stderr.slice(0, 500)}` : "") + `
+${error.message}`
+              ));
+            } else {
+              resolve2(stdout);
+            }
+          }
+        );
+        if (opts.stdin && child.stdin) {
+          child.stdin.write(prompt);
+          child.stdin.end();
+        }
+      });
+    }
+  };
+}
+function createHttpAdapter(opts) {
+  const timeout = opts.timeout ?? 6e4;
+  return {
+    analyze: async (prompt) => {
+      const body = opts.buildBody ? opts.buildBody(prompt) : { prompt };
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      try {
+        const response = await fetch(opts.url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...opts.headers ?? {}
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          const text = await response.text().catch(() => "");
+          throw new Error(`HTTP ${response.status}: ${text.slice(0, 500)}`);
+        }
+        const json = await response.json();
+        if (opts.extractResponse) {
+          return opts.extractResponse(json);
+        }
+        if (typeof json.response === "string") return json.response;
+        if (typeof json.text === "string") return json.text;
+        if (typeof json.content === "string") return json.content;
+        return JSON.stringify(json);
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+
+export { COMPLETION_STRATEGIES, CONFLICT_STRATEGIES, CardCompute, DEFAULTS, EXECUTION_MODES, EXECUTION_STATUS, FileJournal, FileStore, StepMachine as FlowEngine, LocalStorageStore, MemoryJournal, MemoryStore, StepMachine, TASK_STATUS, addDynamicTask, addNode, addProvides, addRequires, apply, applyAll, applyEvent, applyEvents, applyInferences, applyStepResult, batch, buildInferencePrompt, checkCircuitBreaker, computeAvailableOutputs, computeStepInput, createCallbackHandler, createCliAdapter, createDefaultGraphEngineStore, createStepMachine as createEngine, createFireAndForgetHandler, createHttpAdapter, createInitialExecutionState, createInitialState, createLiveGraph, createNoopHandler, createReactiveGraph, createScriptHandler, createShellHandler, createStepMachine, createWebhookHandler, detectStuckState, disableNode, drainTokens, enableNode, exportGraphConfig, exportGraphConfigToFile, extractReturnData, flowToMermaid, getAllTasks, getCandidateTasks, getDownstream, getMaxExecutions, getNode, getProvides, getRefreshStrategy, getRequires, getTask, getUnreachableNodes, getUnreachableTokens, getUpstream, graphToMermaid, hasTask, inferAndApply, inferCompletions, injectTokens, inspect, isExecutionComplete, isNonActiveTask, isRerunnable, isTaskCompleted, isTaskRunning, liveCardsToReactiveGraph, loadGraphConfig, loadStepFlow, mutateGraph, next, planExecution, removeNode, removeProvides, removeRequires, resetNode, resolveConfigTemplates, resolveVariables, restore, schedule, snapshot, validateFlowSchema, validateGraph, validateGraphConfig, validateGraphSchema, validateLiveCardSchema, validateLiveGraph, validateReactiveGraph, validateStepFlowConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map