@isaacwasserman/remora 0.1.0

package/dist/lib.js

@@ -0,0 +1,1973 @@
+// src/compiler/index.ts
+import { asSchema } from "ai";
+
+// src/compiler/passes/apply-best-practices.ts
+var rules = [addMissingStartStep, addMissingEndSteps];
+function applyBestPractices(workflow, graph) {
+  let result = structuredClone(workflow);
+  const allDiagnostics = [];
+  for (const rule of rules) {
+    const ruleResult = rule(result, graph);
+    result = ruleResult.workflow;
+    allDiagnostics.push(...ruleResult.diagnostics);
+  }
+  return { workflow: result, diagnostics: allDiagnostics };
+}
+function addMissingStartStep(workflow, _graph) {
+  const diagnostics = [];
+  const hasStartStep = workflow.steps.some((s) => s.type === "start");
+  if (hasStartStep) {
+    return { workflow, diagnostics };
+  }
+  const startStepId = "__start";
+  const oldInitialStepId = workflow.initialStepId;
+  const startStep = {
+    id: startStepId,
+    name: "Start",
+    description: "Auto-generated start step",
+    type: "start",
+    params: {
+      inputSchema: {}
+    },
+    nextStepId: oldInitialStepId
+  };
+  workflow.steps.unshift(startStep);
+  workflow.initialStepId = startStepId;
+  diagnostics.push({
+    severity: "warning",
+    location: { stepId: null, field: "initialStepId" },
+    message: "Workflow has no start step; one was automatically added with an empty input schema",
+    code: "MISSING_START_STEP"
+  });
+  return { workflow, diagnostics };
+}
+function addMissingEndSteps(workflow, _graph) {
+  const newEndSteps = [];
+  for (const step of workflow.steps) {
+    if (step.type === "end")
+      continue;
+    if (step.nextStepId)
+      continue;
+    const endStepId = `${step.id}_end`;
+    step.nextStepId = endStepId;
+    newEndSteps.push({
+      id: endStepId,
+      name: "End",
+      description: `End of chain after ${step.id}`,
+      type: "end"
+    });
+  }
+  workflow.steps.push(...newEndSteps);
+  return { workflow, diagnostics: [] };
+}
+
+// src/compiler/utils/graph.ts
+function buildStepIndex(steps) {
+  const index = new Map;
+  const duplicates = [];
+  for (const step of steps) {
+    if (index.has(step.id)) {
+      duplicates.push(step.id);
+    } else {
+      index.set(step.id, step);
+    }
+  }
+  return { index, duplicates };
+}
+function computeSuccessors(stepIndex) {
+  const successors = new Map;
+  for (const [id, step] of stepIndex) {
+    const succs = new Set;
+    if (step.nextStepId) {
+      succs.add(step.nextStepId);
+    }
+    if (step.type === "switch-case") {
+      for (const c of step.params.cases) {
+        succs.add(c.branchBodyStepId);
+      }
+    }
+    if (step.type === "for-each") {
+      succs.add(step.params.loopBodyStepId);
+    }
+    successors.set(id, succs);
+  }
+  return successors;
+}
+function computeReachability(initialStepId, successors) {
+  const reachable = new Set;
+  const queue = [initialStepId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined)
+      break;
+    if (reachable.has(current))
+      continue;
+    reachable.add(current);
+    const succs = successors.get(current);
+    if (succs) {
+      for (const s of succs) {
+        if (!reachable.has(s)) {
+          queue.push(s);
+        }
+      }
+    }
+  }
+  return reachable;
+}
+function detectCycles(stepIndex, successors) {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map;
+  for (const id of stepIndex.keys()) {
+    color.set(id, WHITE);
+  }
+  const cycles = [];
+  const path = [];
+  function dfs(node) {
+    if (!stepIndex.has(node))
+      return;
+    color.set(node, GRAY);
+    path.push(node);
+    const succs = successors.get(node);
+    if (succs) {
+      for (const next of succs) {
+        if (!stepIndex.has(next))
+          continue;
+        const c = color.get(next);
+        if (c === undefined)
+          continue;
+        if (c === GRAY) {
+          const cycleStart = path.indexOf(next);
+          cycles.push(path.slice(cycleStart));
+        } else if (c === WHITE) {
+          dfs(next);
+        }
+      }
+    }
+    path.pop();
+    color.set(node, BLACK);
+  }
+  for (const id of stepIndex.keys()) {
+    if (color.get(id) === WHITE) {
+      dfs(id);
+    }
+  }
+  return cycles;
+}
+function computePredecessors(topologicalOrder, successors) {
+  const predecessors = new Map;
+  for (const id of topologicalOrder) {
+    predecessors.set(id, new Set);
+  }
+  for (const id of topologicalOrder) {
+    const succs = successors.get(id);
+    if (!succs)
+      continue;
+    for (const succ of succs) {
+      const predSet = predecessors.get(succ);
+      if (!predSet)
+        continue;
+      predSet.add(id);
+      const idPreds = predecessors.get(id);
+      if (idPreds) {
+        for (const p of idPreds) {
+          predSet.add(p);
+        }
+      }
+    }
+  }
+  return predecessors;
+}
+function topologicalSort(stepIds, successors) {
+  const inDegree = new Map;
+  const stepIdSet = new Set(stepIds);
+  for (const id of stepIds) {
+    inDegree.set(id, 0);
+  }
+  for (const id of stepIds) {
+    const succs = successors.get(id);
+    if (!succs)
+      continue;
+    for (const s of succs) {
+      if (stepIdSet.has(s)) {
+        inDegree.set(s, (inDegree.get(s) ?? 0) + 1);
+      }
+    }
+  }
+  const queue = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0)
+      queue.push(id);
+  }
+  const order = [];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    if (node === undefined)
+      break;
+    order.push(node);
+    const succs = successors.get(node);
+    if (!succs)
+      continue;
+    for (const s of succs) {
+      if (!stepIdSet.has(s))
+        continue;
+      const currentDeg = inDegree.get(s);
+      if (currentDeg === undefined)
+        continue;
+      const newDeg = currentDeg - 1;
+      inDegree.set(s, newDeg);
+      if (newDeg === 0) {
+        queue.push(s);
+      }
+    }
+  }
+  return order.length === stepIds.length ? order : null;
+}
+function computeLoopScopesAndOwnership(initialStepId, stepIndex) {
+  const loopVariablesInScope = new Map;
+  const bodyOwnership = new Map;
+  function walkChain(startId, loopVars, ownerStepId) {
+    let currentId = startId;
+    const chainSteps = [];
+    while (currentId) {
+      if (loopVariablesInScope.has(currentId))
+        break;
+      const step = stepIndex.get(currentId);
+      if (!step)
+        break;
+      loopVariablesInScope.set(currentId, new Set(loopVars));
+      if (ownerStepId !== null) {
+        bodyOwnership.set(currentId, ownerStepId);
+      }
+      chainSteps.push(step);
+      currentId = step.nextStepId;
+    }
+    for (const step of chainSteps) {
+      if (step.type === "for-each") {
+        const innerVars = new Set(loopVars);
+        innerVars.add(step.params.itemName);
+        walkChain(step.params.loopBodyStepId, innerVars, step.id);
+      }
+      if (step.type === "switch-case") {
+        for (const c of step.params.cases) {
+          walkChain(c.branchBodyStepId, loopVars, step.id);
+        }
+      }
+    }
+  }
+  walkChain(initialStepId, new Set, null);
+  return { loopVariablesInScope, bodyOwnership };
+}
+
+// src/compiler/passes/build-graph.ts
+function buildGraph(workflow) {
+  const diagnostics = [];
+  const VALID_STEP_ID = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+  for (const step of workflow.steps) {
+    if (!VALID_STEP_ID.test(step.id)) {
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: step.id, field: "id" },
+        message: `Step ID '${step.id}' is invalid — must match [a-zA-Z_][a-zA-Z0-9_]* (use underscores, not hyphens)`,
+        code: "INVALID_STEP_ID"
+      });
+    }
+  }
+  const stepIdSet = new Set(workflow.steps.map((s) => s.id));
+  for (const step of workflow.steps) {
+    if (step.type === "for-each") {
+      const { itemName } = step.params;
+      if (!VALID_STEP_ID.test(itemName)) {
+        diagnostics.push({
+          severity: "error",
+          location: { stepId: step.id, field: "params.itemName" },
+          message: `Item name '${itemName}' is invalid — must match [a-zA-Z_][a-zA-Z0-9_]*`,
+          code: "INVALID_ITEM_NAME"
+        });
+      }
+      if (stepIdSet.has(itemName)) {
+        diagnostics.push({
+          severity: "warning",
+          location: { stepId: step.id, field: "params.itemName" },
+          message: `Item name '${itemName}' shadows step ID '${itemName}' — references to '${itemName}' inside the loop body will resolve to the loop variable, not the step output`,
+          code: "ITEM_NAME_SHADOWS_STEP_ID"
+        });
+      }
+    }
+  }
+  const { index: stepIndex, duplicates } = buildStepIndex(workflow.steps);
+  for (const dupId of duplicates) {
+    diagnostics.push({
+      severity: "error",
+      location: { stepId: dupId, field: "id" },
+      message: `Duplicate step ID '${dupId}'`,
+      code: "DUPLICATE_STEP_ID"
+    });
+  }
+  if (!stepIndex.has(workflow.initialStepId)) {
+    diagnostics.push({
+      severity: "error",
+      location: { stepId: null, field: "initialStepId" },
+      message: `Initial step '${workflow.initialStepId}' does not exist`,
+      code: "MISSING_INITIAL_STEP"
+    });
+    return { graph: null, diagnostics };
+  }
+  if (duplicates.length > 0) {
+    return { graph: null, diagnostics };
+  }
+  const successors = computeSuccessors(stepIndex);
+  const cycles = detectCycles(stepIndex, successors);
+  for (const cycle of cycles) {
+    const firstStep = cycle[0];
+    if (!firstStep)
+      continue;
+    diagnostics.push({
+      severity: "error",
+      location: { stepId: firstStep, field: "nextStepId" },
+      message: `Cycle detected: ${cycle.join(" → ")} → ${firstStep}`,
+      code: "CYCLE_DETECTED"
+    });
+  }
+  const reachableSteps = computeReachability(workflow.initialStepId, successors);
+  for (const [id] of stepIndex) {
+    if (!reachableSteps.has(id)) {
+      diagnostics.push({
+        severity: "warning",
+        location: { stepId: id, field: "id" },
+        message: `Step '${id}' is not reachable from initial step '${workflow.initialStepId}'`,
+        code: "UNREACHABLE_STEP"
+      });
+    }
+  }
+  if (cycles.length > 0) {
+    return { graph: null, diagnostics };
+  }
+  const reachableIds = [...reachableSteps];
+  const topologicalOrder = topologicalSort(reachableIds, successors);
+  if (!topologicalOrder) {
+    return { graph: null, diagnostics };
+  }
+  const predecessors = computePredecessors(topologicalOrder, successors);
+  const { loopVariablesInScope, bodyOwnership } = computeLoopScopesAndOwnership(workflow.initialStepId, stepIndex);
+  return {
+    graph: {
+      stepIndex,
+      successors,
+      predecessors,
+      topologicalOrder,
+      reachableSteps,
+      loopVariablesInScope,
+      bodyOwnership
+    },
+    diagnostics
+  };
+}
+
+// src/compiler/passes/generate-constrained-tool-schemas.ts
+function collectCallSites(workflow) {
+  const callSitesByTool = new Map;
+  for (const step of workflow.steps) {
+    if (step.type !== "tool-call")
+      continue;
+    const { toolName, toolInput } = step.params;
+    const keys = new Map;
+    for (const [key, expr] of Object.entries(toolInput)) {
+      const expression = expr;
+      if (expression.type === "literal") {
+        keys.set(key, { type: "literal", value: expression.value });
+      } else {
+        keys.set(key, { type: "jmespath" });
+      }
+    }
+    let sites = callSitesByTool.get(toolName);
+    if (!sites) {
+      sites = [];
+      callSitesByTool.set(toolName, sites);
+    }
+    sites.push({ stepId: step.id, keys });
+  }
+  return callSitesByTool;
+}
+function constrainProperty(callSites, key, originalPropertySchema) {
+  let providedCount = 0;
+  let allLiteral = true;
+  const literalValues = [];
+  const seen = new Set;
+  for (const site of callSites) {
+    const entry = site.keys.get(key);
+    if (!entry)
+      continue;
+    providedCount++;
+    if (entry.type === "jmespath") {
+      allLiteral = false;
+    } else {
+      const serialized = JSON.stringify(entry.value);
+      if (!seen.has(serialized)) {
+        seen.add(serialized);
+        literalValues.push(entry.value);
+      }
+    }
+  }
+  const providedInAll = providedCount === callSites.length;
+  if (!allLiteral) {
+    return { schema: originalPropertySchema, allLiteral: false, providedInAll };
+  }
+  const original = originalPropertySchema && typeof originalPropertySchema === "object" ? originalPropertySchema : {};
+  if (literalValues.length === 1) {
+    return {
+      schema: { ...original, const: literalValues[0] },
+      allLiteral: true,
+      providedInAll
+    };
+  }
+  return {
+    schema: { ...original, enum: literalValues },
+    allLiteral: true,
+    providedInAll
+  };
+}
+function generateConstrainedToolSchemas(workflow, tools) {
+  const callSitesByTool = collectCallSites(workflow);
+  const result = {};
+  for (const [toolName, callSites] of callSitesByTool) {
+    const toolDef = tools[toolName];
+    if (!toolDef)
+      continue;
+    const originalProperties = toolDef.inputSchema.properties ?? {};
+    const allUsedKeys = new Set;
+    for (const site of callSites) {
+      for (const key of site.keys.keys()) {
+        allUsedKeys.add(key);
+      }
+    }
+    const constrainedProperties = {};
+    const requiredKeys = [];
+    let fullyStatic = true;
+    for (const key of allUsedKeys) {
+      const originalProp = originalProperties[key];
+      if (originalProp === undefined)
+        continue;
+      const { schema, allLiteral, providedInAll } = constrainProperty(callSites, key, originalProp);
+      constrainedProperties[key] = schema;
+      if (providedInAll) {
+        requiredKeys.push(key);
+      }
+      if (!allLiteral) {
+        fullyStatic = false;
+      }
+    }
+    const constrained = {
+      inputSchema: {
+        required: requiredKeys.sort(),
+        properties: constrainedProperties
+      },
+      fullyStatic,
+      callSites: callSites.map((s) => s.stepId).sort()
+    };
+    if (toolDef.outputSchema) {
+      constrained.outputSchema = toolDef.outputSchema;
+    }
+    result[toolName] = constrained;
+  }
+  return result;
+}
+
+// src/compiler/passes/validate-control-flow.ts
+function validateControlFlow(workflow, graph) {
+  const diagnostics = [];
+  for (const step of workflow.steps) {
+    if (step.type === "end" && step.nextStepId) {
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: step.id, field: "nextStepId" },
+        message: `End step '${step.id}' should not have a nextStepId`,
+        code: "END_STEP_HAS_NEXT"
+      });
+    }
+    if (step.type === "switch-case") {
+      const defaultCount = step.params.cases.filter((c) => c.value.type === "default").length;
+      if (defaultCount > 1) {
+        diagnostics.push({
+          severity: "error",
+          location: { stepId: step.id, field: "params.cases" },
+          message: `Switch-case step '${step.id}' has ${defaultCount} default cases (expected at most 1)`,
+          code: "MULTIPLE_DEFAULT_CASES"
+        });
+      }
+      for (const [i, c] of step.params.cases.entries()) {
+        const escapes = checkBodyEscapes(c.branchBodyStepId, step.id, graph);
+        if (escapes) {
+          diagnostics.push({
+            severity: "warning",
+            location: {
+              stepId: step.id,
+              field: `params.cases[${i}].branchBodyStepId`
+            },
+            message: `Branch body starting at '${c.branchBodyStepId}' in step '${step.id}' has a step ('${escapes.escapingStep}') whose nextStepId points outside the branch body to '${escapes.target}'`,
+            code: "BRANCH_BODY_ESCAPES"
+          });
+        }
+      }
+    }
+    if (step.type === "for-each") {
+      const escapes = checkBodyEscapes(step.params.loopBodyStepId, step.id, graph);
+      if (escapes) {
+        diagnostics.push({
+          severity: "warning",
+          location: {
+            stepId: step.id,
+            field: "params.loopBodyStepId"
+          },
+          message: `Loop body starting at '${step.params.loopBodyStepId}' in step '${step.id}' has a step ('${escapes.escapingStep}') whose nextStepId points outside the loop body to '${escapes.target}'`,
+          code: "LOOP_BODY_ESCAPES"
+        });
+      }
+    }
+  }
+  if (workflow.outputSchema) {
+    for (const step of workflow.steps) {
+      if (step.type === "end" && !step.params?.output) {
+        diagnostics.push({
+          severity: "warning",
+          location: { stepId: step.id, field: "params" },
+          message: `End step '${step.id}' has no output expression, but the workflow declares an outputSchema`,
+          code: "END_STEP_MISSING_OUTPUT"
+        });
+      }
+    }
+  } else {
+    for (const step of workflow.steps) {
+      if (step.type === "end" && step.params?.output) {
+        diagnostics.push({
+          severity: "warning",
+          location: { stepId: step.id, field: "params.output" },
+          message: `End step '${step.id}' has an output expression, but the workflow does not declare an outputSchema`,
+          code: "END_STEP_UNEXPECTED_OUTPUT"
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+function checkBodyEscapes(startId, parentStepId, graph) {
+  let currentId = startId;
+  const visited = new Set;
+  while (currentId) {
+    if (visited.has(currentId))
+      break;
+    visited.add(currentId);
+    const step = graph.stepIndex.get(currentId);
+    if (!step)
+      break;
+    if (step.nextStepId) {
+      const nextOwner = graph.bodyOwnership.get(step.nextStepId);
+      const currentOwner = graph.bodyOwnership.get(currentId);
+      if ((currentOwner === parentStepId || currentId === startId) && nextOwner !== parentStepId) {
+        return { escapingStep: currentId, target: step.nextStepId };
+      }
+    }
+    currentId = step.nextStepId;
+  }
+  return null;
+}
+
+// src/compiler/passes/validate-foreach-target.ts
+function validateForeachTarget(workflow, graph, tools) {
+  const diagnostics = [];
+  for (const step of workflow.steps) {
+    if (step.type !== "for-each")
+      continue;
+    if (step.params.target.type !== "jmespath")
+      continue;
+    const expression = step.params.target.expression;
+    const segments = parseSimplePath(expression);
+    if (!segments)
+      continue;
+    const [rootId, ...fieldPath] = segments;
+    if (!rootId)
+      continue;
+    const referencedStep = graph.stepIndex.get(rootId);
+    if (!referencedStep)
+      continue;
+    const outputSchema = getStepOutputSchema(referencedStep, tools);
+    if (!outputSchema)
+      continue;
+    const resolvedSchema = resolvePath(outputSchema, fieldPath);
+    if (!resolvedSchema)
+      continue;
+    const resolvedType = getSchemaType(resolvedSchema);
+    if (resolvedType === "array")
+      continue;
+    if (resolvedType === "object") {
+      const suggestions = findArrayProperties(resolvedSchema);
+      const hint = suggestions.length > 0 ? ` Did you mean ${suggestions.map((s) => `'${rootId}.${s}'`).join(" or ")}?` : "";
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: step.id, field: "params.target" },
+        message: `for-each target '${expression}' resolves to an object, not an array.${hint}`,
+        code: "FOREACH_TARGET_NOT_ARRAY"
+      });
+    } else if (resolvedType !== null) {
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: step.id, field: "params.target" },
+        message: `for-each target '${expression}' resolves to type '${resolvedType}', not an array.`,
+        code: "FOREACH_TARGET_NOT_ARRAY"
+      });
+    }
+  }
+  return diagnostics;
+}
+function parseSimplePath(expression) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$/.test(expression)) {
+    return null;
+  }
+  return expression.split(".");
+}
+function getStepOutputSchema(step, tools) {
+  if (step.type === "tool-call") {
+    const toolDef = tools[step.params.toolName];
+    return toolDef?.outputSchema ?? null;
+  }
+  if (step.type === "start" && step.params.inputSchema) {
+    return step.params.inputSchema;
+  }
+  return null;
+}
+function resolvePath(schema, path) {
+  let current = schema;
+  for (const segment of path) {
+    const properties = current.properties;
+    if (!properties?.[segment])
+      return null;
+    current = properties[segment];
+  }
+  return current;
+}
+function getSchemaType(schema) {
+  if (typeof schema.type === "string")
+    return schema.type;
+  return null;
+}
+function findArrayProperties(schema) {
+  const properties = schema.properties;
+  if (!properties)
+    return [];
+  return Object.entries(properties).filter(([_, propSchema]) => propSchema.type === "array").map(([name]) => name);
+}
+
+// src/compiler/utils/jmespath-helpers.ts
+import { compile } from "@jmespath-community/jmespath";
+function validateJmespathSyntax(expression) {
+  try {
+    compile(expression);
+    return { valid: true };
+  } catch (e) {
+    return { valid: false, error: e.message };
+  }
+}
+function extractRootIdentifiers(expression) {
+  let ast;
+  try {
+    ast = compile(expression);
+  } catch {
+    return [];
+  }
+  const roots = new Set;
+  collectRoots(ast, roots);
+  return [...roots];
+}
+function collectRoots(node, roots) {
+  if (!node || typeof node !== "object")
+    return;
+  switch (node.type) {
+    case "Field":
+      if (node.name)
+        roots.add(node.name);
+      break;
+    case "Subexpression":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    case "FilterProjection":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    case "Projection":
+    case "Flatten":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    case "Function":
+      if (node.children) {
+        for (const child of node.children) {
+          collectRoots(child, roots);
+        }
+      }
+      break;
+    case "MultiSelectList":
+    case "MultiSelectHash":
+      if (node.children) {
+        for (const child of node.children) {
+          collectRoots(child, roots);
+        }
+      }
+      break;
+    case "Comparator":
+    case "And":
+    case "Or":
+    case "Arithmetic":
+      if (node.left)
+        collectRoots(node.left, roots);
+      if (node.right)
+        collectRoots(node.right, roots);
+      break;
+    case "Not":
+    case "Negate":
+      if (node.children?.[0])
+        collectRoots(node.children[0], roots);
+      break;
+    case "Pipe":
+      if (node.left)
+        collectRoots(node.left, roots);
+      break;
+    case "IndexExpression":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    case "ValueProjection":
+    case "Slice":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    case "Literal":
+    case "Current":
+    case "Identity":
+    case "Expref":
+      break;
+    case "KeyValuePair": {
+      const kvValue = node.value;
+      if (kvValue) {
+        collectRoots(kvValue, roots);
+      }
+      break;
+    }
+    default:
+      if (node.left)
+        collectRoots(node.left, roots);
+      if (node.right)
+        collectRoots(node.right, roots);
+      if (node.children) {
+        for (const child of node.children) {
+          collectRoots(child, roots);
+        }
+      }
+      break;
+  }
+}
+function collectLeftmostRoot(node, roots) {
+  if (!node)
+    return;
+  switch (node.type) {
+    case "Field":
+      if (node.name)
+        roots.add(node.name);
+      break;
+    case "Subexpression":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    case "FilterProjection":
+    case "Projection":
+    case "Flatten":
+    case "IndexExpression":
+    case "ValueProjection":
+    case "Slice":
+      if (node.left)
+        collectLeftmostRoot(node.left, roots);
+      break;
+    default:
+      collectRoots(node, roots);
+      break;
+  }
+}
+function extractTemplateExpressions(template) {
+  const expressions = [];
+  const unclosed = [];
+  let i = 0;
+  while (i < template.length) {
+    if (template[i] === "$" && template[i + 1] === "{") {
+      const start = i;
+      i += 2;
+      let depth = 1;
+      const exprStart = i;
+      while (i < template.length && depth > 0) {
+        if (template[i] === "{")
+          depth++;
+        else if (template[i] === "}")
+          depth--;
+        if (depth > 0)
+          i++;
+      }
+      if (depth === 0) {
+        const expression = template.slice(exprStart, i);
+        expressions.push({ expression, start, end: i + 1 });
+        i++;
+      } else {
+        unclosed.push(start);
+      }
+    } else {
+      i++;
+    }
+  }
+  return { expressions, unclosed };
+}
+
+// src/compiler/passes/validate-jmespath.ts
+function validateJmespath(workflow, graph) {
+  const diagnostics = [];
+  const { expressions, templateDiagnostics } = collectExpressions(workflow);
+  diagnostics.push(...templateDiagnostics);
+  for (const expr of expressions) {
+    const syntaxResult = validateJmespathSyntax(expr.expression);
+    if (!syntaxResult.valid) {
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: expr.stepId, field: expr.field },
+        message: `Invalid JMESPath syntax in '${expr.expression}': ${syntaxResult.error}`,
+        code: "JMESPATH_SYNTAX_ERROR"
+      });
+      continue;
+    }
+    validateExpressionScope(expr, graph, diagnostics);
+  }
+  return diagnostics;
+}
+function collectExpressions(workflow) {
+  const expressions = [];
+  const templateDiagnostics = [];
+  for (const step of workflow.steps) {
+    switch (step.type) {
+      case "tool-call":
+        for (const [key, val] of Object.entries(step.params.toolInput)) {
+          if (val.type === "jmespath") {
+            expressions.push({
+              expression: val.expression,
+              stepId: step.id,
+              field: `params.toolInput.${key}.expression`
+            });
+          }
+        }
+        break;
+      case "switch-case":
+        if (step.params.switchOn.type === "jmespath") {
+          expressions.push({
+            expression: step.params.switchOn.expression,
+            stepId: step.id,
+            field: "params.switchOn.expression"
+          });
+        }
+        for (const [i, c] of step.params.cases.entries()) {
+          if (c.value.type === "jmespath") {
+            expressions.push({
+              expression: c.value.expression,
+              stepId: step.id,
+              field: `params.cases[${i}].value.expression`
+            });
+          }
+        }
+        break;
+      case "for-each":
+        if (step.params.target.type === "jmespath") {
+          expressions.push({
+            expression: step.params.target.expression,
+            stepId: step.id,
+            field: "params.target.expression"
+          });
+        }
+        break;
+      case "extract-data":
+        if (step.params.sourceData.type === "jmespath") {
+          expressions.push({
+            expression: step.params.sourceData.expression,
+            stepId: step.id,
+            field: "params.sourceData.expression"
+          });
+        }
+        break;
+      case "start":
+        break;
+      case "end":
+        if (step.params?.output && step.params.output.type === "jmespath") {
+          expressions.push({
+            expression: step.params.output.expression,
+            stepId: step.id,
+            field: "params.output.expression"
+          });
+        }
+        break;
+      case "llm-prompt": {
+        const { expressions: templateExprs, unclosed } = extractTemplateExpressions(step.params.prompt);
+        for (const te of templateExprs) {
+          expressions.push({
+            expression: te.expression,
+            stepId: step.id,
+            field: `params.prompt[${te.start}:${te.end}]`
+          });
+        }
+        for (const pos of unclosed) {
+          templateDiagnostics.push({
+            severity: "error",
+            location: {
+              stepId: step.id,
+              field: `params.prompt[${pos}]`
+            },
+            message: `Unclosed template expression at position ${pos} in prompt`,
+            code: "UNCLOSED_TEMPLATE_EXPRESSION"
+          });
+        }
+        break;
+      }
+    }
+  }
+  return { expressions, templateDiagnostics };
+}
+function validateExpressionScope(expr, graph, diagnostics) {
+  const astRoots = extractRootIdentifiers(expr.expression);
+  const loopVars = graph.loopVariablesInScope.get(expr.stepId);
+  const predecessors = graph.predecessors.get(expr.stepId);
+  for (const root of astRoots) {
+    if (loopVars?.has(root))
+      continue;
+    if (graph.stepIndex.has(root)) {
+      if (predecessors && !predecessors.has(root)) {
+        diagnostics.push({
+          severity: "warning",
+          location: { stepId: expr.stepId, field: expr.field },
+          message: `Expression '${expr.expression}' references step '${root}' which may not have executed before step '${expr.stepId}'`,
+          code: "JMESPATH_FORWARD_REFERENCE"
+        });
+      }
+      continue;
+    }
+    diagnostics.push({
+      severity: "error",
+      location: { stepId: expr.stepId, field: expr.field },
+      message: `Expression '${expr.expression}' references '${root}' which is not a known step ID or loop variable in scope`,
+      code: "JMESPATH_INVALID_ROOT_REFERENCE"
+    });
+  }
+}
+
+// src/compiler/passes/validate-references.ts
+function validateReferences(workflow) {
+  const diagnostics = [];
+  const stepIds = new Set(workflow.steps.map((s) => s.id));
+  if (!stepIds.has(workflow.initialStepId)) {
+    diagnostics.push({
+      severity: "error",
+      location: { stepId: null, field: "initialStepId" },
+      message: `Initial step '${workflow.initialStepId}' does not exist`,
+      code: "MISSING_INITIAL_STEP"
+    });
+  }
+  for (const step of workflow.steps) {
+    if (step.nextStepId && !stepIds.has(step.nextStepId)) {
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: step.id, field: "nextStepId" },
+        message: `Step '${step.id}' references non-existent next step '${step.nextStepId}'`,
+        code: "MISSING_NEXT_STEP"
+      });
+    }
+    if (step.type === "switch-case") {
+      for (const [i, c] of step.params.cases.entries()) {
+        if (!stepIds.has(c.branchBodyStepId)) {
+          diagnostics.push({
+            severity: "error",
+            location: {
+              stepId: step.id,
+              field: `params.cases[${i}].branchBodyStepId`
+            },
+            message: `Step '${step.id}' case ${i} references non-existent branch body step '${c.branchBodyStepId}'`,
+            code: "MISSING_BRANCH_BODY_STEP"
+          });
+        }
+      }
+    }
+    if (step.type === "for-each") {
+      if (!stepIds.has(step.params.loopBodyStepId)) {
+        diagnostics.push({
+          severity: "error",
+          location: {
+            stepId: step.id,
+            field: "params.loopBodyStepId"
+          },
+          message: `Step '${step.id}' references non-existent loop body step '${step.params.loopBodyStepId}'`,
+          code: "MISSING_LOOP_BODY_STEP"
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+
+// src/compiler/passes/validate-tools.ts
+function validateTools(workflow, tools) {
+  const diagnostics = [];
+  for (const step of workflow.steps) {
+    if (step.type !== "tool-call")
+      continue;
+    const { toolName, toolInput } = step.params;
+    const toolDef = tools[toolName];
+    if (!toolDef) {
+      diagnostics.push({
+        severity: "error",
+        location: { stepId: step.id, field: "params.toolName" },
+        message: `Step '${step.id}' references unknown tool '${toolName}'`,
+        code: "UNKNOWN_TOOL"
+      });
+      continue;
+    }
+    const schemaProperties = toolDef.inputSchema.properties ?? {};
+    const requiredKeys = new Set(toolDef.inputSchema.required ?? []);
+    const definedKeys = new Set(Object.keys(schemaProperties));
+    const providedKeys = new Set(Object.keys(toolInput));
+    for (const key of providedKeys) {
+      if (!definedKeys.has(key)) {
+        diagnostics.push({
+          severity: "warning",
+          location: {
+            stepId: step.id,
+            field: `params.toolInput.${key}`
+          },
+          message: `Step '${step.id}' provides input key '${key}' which is not defined in tool '${toolName}' schema`,
+          code: "EXTRA_TOOL_INPUT_KEY"
+        });
+      }
+    }
+    for (const key of requiredKeys) {
+      if (!providedKeys.has(key)) {
+        diagnostics.push({
+          severity: "error",
+          location: { stepId: step.id, field: "params.toolInput" },
+          message: `Step '${step.id}' is missing required input key '${key}' for tool '${toolName}'`,
+          code: "MISSING_TOOL_INPUT_KEY"
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+
+// src/compiler/index.ts
+async function compileWorkflow(workflow, options) {
+  const diagnostics = [];
+  const graphResult = buildGraph(workflow);
+  diagnostics.push(...graphResult.diagnostics);
+  const refDiagnostics = validateReferences(workflow);
+  for (const d of refDiagnostics) {
+    if (d.code === "MISSING_INITIAL_STEP" && diagnostics.some((e) => e.code === "MISSING_INITIAL_STEP")) {
+      continue;
+    }
+    diagnostics.push(d);
+  }
+  if (graphResult.graph) {
+    diagnostics.push(...validateControlFlow(workflow, graphResult.graph));
+    diagnostics.push(...validateJmespath(workflow, graphResult.graph));
+  }
+  let constrainedToolSchemas = null;
+  if (options?.tools) {
+    const toolSchemas = await extractToolSchemas(options.tools);
+    diagnostics.push(...validateTools(workflow, toolSchemas));
+    constrainedToolSchemas = generateConstrainedToolSchemas(workflow, toolSchemas);
+    if (graphResult.graph) {
+      diagnostics.push(...validateForeachTarget(workflow, graphResult.graph, toolSchemas));
+    }
+  }
+  const hasErrors = diagnostics.some((d) => d.severity === "error");
+  let optimizedWorkflow = null;
+  if (graphResult.graph && !hasErrors) {
+    const bpResult = applyBestPractices(workflow, graphResult.graph);
+    optimizedWorkflow = bpResult.workflow;
+    diagnostics.push(...bpResult.diagnostics);
+  }
+  return {
+    diagnostics,
+    graph: graphResult.graph,
+    workflow: optimizedWorkflow,
+    constrainedToolSchemas
+  };
+}
+async function extractToolSchemas(tools) {
+  const schemas = {};
+  for (const [name, toolDef] of Object.entries(tools)) {
+    const jsonSchema = await asSchema(toolDef.inputSchema).jsonSchema;
+    schemas[name] = {
+      inputSchema: jsonSchema
+    };
+    if (toolDef.outputSchema) {
+      schemas[name].outputSchema = await asSchema(toolDef.outputSchema).jsonSchema;
+    }
+  }
+  return schemas;
+}
+// src/executor/index.ts
+import { safeValidateTypes } from "@ai-sdk/provider-utils";
+import { search } from "@jmespath-community/jmespath";
+import {
+  APICallError,
+  JSONParseError,
+  NoContentGeneratedError,
+  RetryError,
+  stepCountIs,
+  ToolLoopAgent,
+  TypeValidationError
+} from "ai";
+
+// src/executor/errors.ts
+class StepExecutionError extends Error {
+  stepId;
+  code;
+  category;
+  cause;
+  name = "StepExecutionError";
+  constructor(stepId, code, category, message, cause) {
+    super(message);
+    this.stepId = stepId;
+    this.code = code;
+    this.category = category;
+    this.cause = cause;
+  }
+}
+
+class ConfigurationError extends StepExecutionError {
+  constructor(stepId, code, message) {
+    super(stepId, code, "configuration", message);
+  }
+}
+
+class ValidationError extends StepExecutionError {
+  input;
+  constructor(stepId, code, message, input, cause) {
+    super(stepId, code, "validation", message, cause);
+    this.input = input;
+  }
+}
+
+class ExternalServiceError extends StepExecutionError {
+  statusCode;
+  isRetryable;
+  constructor(stepId, code, message, cause, statusCode, isRetryable = true) {
+    super(stepId, code, "external-service", message, cause);
+    this.statusCode = statusCode;
+    this.isRetryable = isRetryable;
+  }
+}
+
+class ExpressionError extends StepExecutionError {
+  expression;
+  constructor(stepId, code, message, expression, cause) {
+    super(stepId, code, "expression", message, cause);
+    this.expression = expression;
+  }
+}
+
+class OutputQualityError extends StepExecutionError {
+  rawOutput;
+  constructor(stepId, code, message, rawOutput, cause) {
+    super(stepId, code, "output-quality", message, cause);
+    this.rawOutput = rawOutput;
+  }
+}
+
+// src/executor/index.ts
+function stripCodeFence(text) {
+  const match = text.match(/^```(?:\w*)\s*\n?([\s\S]*?)\n?\s*```\s*$/);
+  return match?.[1] ?? text;
+}
+function isAgent(value) {
+  return typeof value === "object" && value !== null && "generate" in value;
+}
+function evaluateExpression(expr, scope, stepId) {
+  if (expr.type === "literal") {
+    return expr.value;
+  }
+  try {
+    return search(scope, expr.expression);
+  } catch (e) {
+    throw new ExpressionError(stepId, "JMESPATH_EVALUATION_ERROR", `JMESPath expression '${expr.expression}' failed: ${e instanceof Error ? e.message : String(e)}`, expr.expression, e);
+  }
+}
+function stringifyValue(value) {
+  if (value === null || value === undefined)
+    return "";
+  if (typeof value === "object")
+    return JSON.stringify(value);
+  return String(value);
+}
+function interpolateTemplate(template, scope, stepId) {
+  const { expressions } = extractTemplateExpressions(template);
+  if (expressions.length === 0)
+    return template;
+  let result = "";
+  let lastEnd = 0;
+  for (const expr of expressions) {
+    result += template.slice(lastEnd, expr.start);
+    try {
+      const value = search(scope, expr.expression);
+      result += stringifyValue(value);
+    } catch (e) {
+      throw new ExpressionError(stepId, "TEMPLATE_INTERPOLATION_ERROR", `Template expression '${expr.expression}' failed: ${e instanceof Error ? e.message : String(e)}`, expr.expression, e);
+    }
+    lastEnd = expr.end;
+  }
+  result += template.slice(lastEnd);
+  return result;
+}
+function classifyLlmError(stepId, e) {
+  if (APICallError.isInstance(e)) {
+    const code = e.statusCode === 429 ? "LLM_RATE_LIMITED" : "LLM_API_ERROR";
+    return new ExternalServiceError(stepId, code, e.message, e, e.statusCode, e.isRetryable ?? true);
+  }
+  if (RetryError.isInstance(e)) {
+    return new ExternalServiceError(stepId, "LLM_API_ERROR", e.message, e, undefined, false);
+  }
+  if (NoContentGeneratedError.isInstance(e)) {
+    return new ExternalServiceError(stepId, "LLM_NO_CONTENT", e.message, e, undefined, true);
+  }
+  if (TypeValidationError.isInstance(e)) {
+    return new OutputQualityError(stepId, "LLM_OUTPUT_PARSE_ERROR", `LLM output could not be parsed: ${e.message}`, e.value, e);
+  }
+  if (JSONParseError.isInstance(e)) {
+    return new OutputQualityError(stepId, "LLM_OUTPUT_PARSE_ERROR", `LLM output could not be parsed: ${e.message}`, e.text, e);
+  }
+  return new ExternalServiceError(stepId, "LLM_NETWORK_ERROR", e instanceof Error ? e.message : String(e), e, undefined, true);
+}
+function validateWorkflowInputs(step, inputs) {
+  const schema = step.params.inputSchema;
+  if (!schema || typeof schema !== "object")
+    return;
+  const required = schema.required;
+  if (Array.isArray(required)) {
+    const missing = required.filter((key) => typeof key === "string" && !(key in inputs));
+    if (missing.length > 0) {
+      throw new ValidationError(step.id, "TOOL_INPUT_VALIDATION_FAILED", `Workflow input validation failed: missing required input(s): ${missing.join(", ")}`, inputs);
+    }
+  }
+  const properties = schema.properties;
+  if (properties && typeof properties === "object") {
+    for (const [key, value] of Object.entries(inputs)) {
+      const propSchema = properties[key];
+      if (propSchema && typeof propSchema === "object" && "type" in propSchema) {
+        const expectedType = propSchema.type;
+        const actualType = typeof value;
+        if (expectedType === "integer" || expectedType === "number") {
+          if (actualType !== "number") {
+            throw new ValidationError(step.id, "TOOL_INPUT_VALIDATION_FAILED", `Workflow input validation failed: input '${key}' expected type '${expectedType}' but got '${actualType}'`, inputs);
+          }
+        } else if (expectedType === "array") {
+          if (!Array.isArray(value)) {
+            throw new ValidationError(step.id, "TOOL_INPUT_VALIDATION_FAILED", `Workflow input validation failed: input '${key}' expected type 'array' but got '${actualType}'`, inputs);
+          }
+        } else if (actualType !== expectedType) {
+          throw new ValidationError(step.id, "TOOL_INPUT_VALIDATION_FAILED", `Workflow input validation failed: input '${key}' expected type '${expectedType}' but got '${actualType}'`, inputs);
+        }
+      }
+    }
+  }
+}
+function validateWorkflowOutput(outputSchema, output, endStepId) {
+  const expectedType = outputSchema.type;
+  if (typeof expectedType === "string") {
+    if (expectedType === "object" && (typeof output !== "object" || output === null)) {
+      throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: expected type 'object' but got '${output === null ? "null" : typeof output}'`, output);
+    }
+    if (expectedType === "array" && !Array.isArray(output)) {
+      throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: expected type 'array' but got '${typeof output}'`, output);
+    }
+    if ((expectedType === "string" || expectedType === "boolean") && typeof output !== expectedType) {
+      throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: expected type '${expectedType}' but got '${typeof output}'`, output);
+    }
+    if ((expectedType === "number" || expectedType === "integer") && typeof output !== "number") {
+      throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: expected type '${expectedType}' but got '${typeof output}'`, output);
+    }
+  }
+  if (typeof output === "object" && output !== null && !Array.isArray(output)) {
+    const required = outputSchema.required;
+    if (Array.isArray(required)) {
+      const missing = required.filter((key) => typeof key === "string" && !(key in output));
+      if (missing.length > 0) {
+        throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: missing required field(s): ${missing.join(", ")}`, output);
+      }
+    }
+    const properties = outputSchema.properties;
+    if (properties && typeof properties === "object") {
+      for (const [key, value] of Object.entries(output)) {
+        const propSchema = properties[key];
+        if (propSchema && typeof propSchema === "object" && "type" in propSchema) {
+          const propExpectedType = propSchema.type;
+          const actualType = typeof value;
+          if (propExpectedType === "integer" || propExpectedType === "number") {
+            if (actualType !== "number") {
+              throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: field '${key}' expected type '${propExpectedType}' but got '${actualType}'`, output);
+            }
+          } else if (propExpectedType === "array") {
+            if (!Array.isArray(value)) {
+              throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: field '${key}' expected type 'array' but got '${actualType}'`, output);
+            }
+          } else if (actualType !== propExpectedType) {
+            throw new ValidationError(endStepId, "WORKFLOW_OUTPUT_VALIDATION_FAILED", `Workflow output validation failed: field '${key}' expected type '${propExpectedType}' but got '${actualType}'`, output);
+          }
+        }
+      }
+    }
+  }
+}
+async function executeToolCall(step, scope, tools) {
+  const toolDef = tools[step.params.toolName];
+  if (!toolDef?.execute) {
+    throw new ConfigurationError(step.id, "TOOL_NOT_FOUND", `Tool '${step.params.toolName}' not found or has no execute function`);
+  }
+  const resolvedInput = {};
+  for (const [key, expr] of Object.entries(step.params.toolInput)) {
+    resolvedInput[key] = evaluateExpression(expr, scope, step.id);
+  }
+  if (toolDef.inputSchema) {
+    const validation = await safeValidateTypes({
+      value: resolvedInput,
+      schema: toolDef.inputSchema
+    });
+    if (!validation.success) {
+      throw new ValidationError(step.id, "TOOL_INPUT_VALIDATION_FAILED", `Tool '${step.params.toolName}' input validation failed: ${validation.error.message}`, resolvedInput, validation.error);
+    }
+  }
+  try {
+    return await toolDef.execute(resolvedInput, {
+      toolCallId: step.id,
+      messages: []
+    });
+  } catch (e) {
+    throw new ExternalServiceError(step.id, "TOOL_EXECUTION_FAILED", e instanceof Error ? e.message : String(e), e);
+  }
+}
+async function executeLlmPrompt(step, scope, agent) {
+  const interpolatedPrompt = interpolateTemplate(step.params.prompt, scope, step.id);
+  const schemaStr = JSON.stringify(step.params.outputFormat, null, 2);
+  const prompt = `${interpolatedPrompt}
+
+You must respond with valid JSON matching this JSON Schema:
+${schemaStr}
+
+Respond ONLY with the JSON object, no other text.`;
+  try {
+    const result = await agent.generate({ prompt });
+    return JSON.parse(stripCodeFence(result.text));
+  } catch (e) {
+    if (e instanceof StepExecutionError)
+      throw e;
+    if (e instanceof SyntaxError) {
+      throw new OutputQualityError(step.id, "LLM_OUTPUT_PARSE_ERROR", `LLM output is not valid JSON: ${e.message}`, undefined, e);
+    }
+    throw classifyLlmError(step.id, e);
+  }
+}
+async function executeExtractData(step, scope, agent) {
+  const sourceData = evaluateExpression(step.params.sourceData, scope, step.id);
+  const sourceStr = typeof sourceData === "string" ? sourceData : JSON.stringify(sourceData, null, 2);
+  const schemaStr = JSON.stringify(step.params.outputFormat, null, 2);
+  const prompt = `Extract the following structured data from the provided source data.
+
+Source data:
+${sourceStr}
+
+You must respond with valid JSON matching this JSON Schema:
+${schemaStr}
+
+Respond ONLY with the JSON object, no other text.`;
+  try {
+    const result = await agent.generate({ prompt });
+    return JSON.parse(stripCodeFence(result.text));
+  } catch (e) {
+    if (e instanceof StepExecutionError)
+      throw e;
+    if (e instanceof SyntaxError) {
+      throw new OutputQualityError(step.id, "LLM_OUTPUT_PARSE_ERROR", `LLM output is not valid JSON: ${e.message}`, undefined, e);
+    }
+    throw classifyLlmError(step.id, e);
+  }
+}
+async function executeSwitchCase(step, scope, stepIndex, stepOutputs, loopVars, options) {
+  const switchValue = evaluateExpression(step.params.switchOn, scope, step.id);
+  let matchedBranchId;
+  let defaultBranchId;
+  for (const c of step.params.cases) {
+    if (c.value.type === "default") {
+      defaultBranchId = c.branchBodyStepId;
+    } else {
+      const caseValue = evaluateExpression(c.value, scope, step.id);
+      if (caseValue === switchValue) {
+        matchedBranchId = c.branchBodyStepId;
+        break;
+      }
+    }
+  }
+  const selectedBranchId = matchedBranchId ?? defaultBranchId;
+  if (!selectedBranchId) {
+    return;
+  }
+  return await executeChain(selectedBranchId, stepIndex, stepOutputs, loopVars, options);
+}
+async function executeForEach(step, scope, stepIndex, stepOutputs, loopVars, options) {
+  const target = evaluateExpression(step.params.target, scope, step.id);
+  if (!Array.isArray(target)) {
+    throw new ValidationError(step.id, "FOREACH_TARGET_NOT_ARRAY", `for-each target must be an array, got ${typeof target}`, target);
+  }
+  const results = [];
+  for (const item of target) {
+    const innerLoopVars = { ...loopVars, [step.params.itemName]: item };
+    const lastOutput = await executeChain(step.params.loopBodyStepId, stepIndex, stepOutputs, innerLoopVars, options);
+    results.push(lastOutput);
+  }
+  return results;
+}
+async function executeStep(step, scope, stepIndex, stepOutputs, loopVars, options) {
+  switch (step.type) {
+    case "tool-call":
+      return executeToolCall(step, scope, options.tools);
+    case "llm-prompt": {
+      if (!options.agent)
+        throw new ConfigurationError(step.id, "AGENT_NOT_PROVIDED", "No agent provided");
+      return executeLlmPrompt(step, scope, options.agent);
+    }
+    case "extract-data": {
+      if (!options.agent)
+        throw new ConfigurationError(step.id, "AGENT_NOT_PROVIDED", "No agent provided");
+      return executeExtractData(step, scope, options.agent);
+    }
+    case "switch-case":
+      return executeSwitchCase(step, scope, stepIndex, stepOutputs, loopVars, options);
+    case "for-each":
+      return executeForEach(step, scope, stepIndex, stepOutputs, loopVars, options);
+    case "start": {
+      const inputs = options.inputs ?? {};
+      const startStep = step;
+      validateWorkflowInputs(startStep, inputs);
+      return inputs;
+    }
+    case "end": {
+      const endStep = step;
+      if (endStep.params?.output) {
+        return evaluateExpression(endStep.params.output, scope, step.id);
+      }
+      return;
+    }
+  }
+}
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_BASE_DELAY_MS = 1000;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function retryStep(step, stepIndex, stepOutputs, loopVars, options, originalError) {
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const baseDelay = options.retryDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const scope = { ...stepOutputs, ...loopVars };
+  for (let attempt = 1;attempt <= maxRetries; attempt++) {
+    await sleep(baseDelay * 2 ** (attempt - 1));
+    try {
+      return await executeStep(step, scope, stepIndex, stepOutputs, loopVars, options);
+    } catch {
+      if (attempt === maxRetries)
+        throw originalError;
+    }
+  }
+  throw originalError;
+}
+async function recoverFromError(error, step, stepIndex, stepOutputs, loopVars, options) {
+  switch (error.code) {
+    case "LLM_RATE_LIMITED":
+    case "LLM_NETWORK_ERROR":
+    case "LLM_NO_CONTENT":
+    case "LLM_OUTPUT_PARSE_ERROR":
+      return retryStep(step, stepIndex, stepOutputs, loopVars, options, error);
+    case "LLM_API_ERROR":
+      if (error instanceof ExternalServiceError && error.isRetryable) {
+        return retryStep(step, stepIndex, stepOutputs, loopVars, options, error);
+      }
+      throw error;
+    default:
+      throw error;
+  }
+}
+async function executeChain(startStepId, stepIndex, stepOutputs, loopVars, options) {
+  let currentStepId = startStepId;
+  let lastOutput;
+  while (currentStepId) {
+    const step = stepIndex.get(currentStepId);
+    if (!step) {
+      throw new Error(`Step '${currentStepId}' not found`);
+    }
+    options.onStepStart?.(step.id, step);
+    const scope = { ...stepOutputs, ...loopVars };
+    let stepOutput;
+    try {
+      stepOutput = await executeStep(step, scope, stepIndex, stepOutputs, loopVars, options);
+    } catch (e) {
+      if (!(e instanceof StepExecutionError))
+        throw e;
+      stepOutput = await recoverFromError(e, step, stepIndex, stepOutputs, loopVars, options);
+    }
+    stepOutputs[step.id] = stepOutput;
+    lastOutput = stepOutput;
+    options.onStepComplete?.(step.id, stepOutput);
+    currentStepId = step.nextStepId;
+  }
+  return lastOutput;
+}
+function validateWorkflowConfig(workflow, options) {
+  const needsAgent = workflow.steps.some((s) => s.type === "llm-prompt" || s.type === "extract-data");
+  if (needsAgent && !options.agent) {
+    const llmStep = workflow.steps.find((s) => s.type === "llm-prompt" || s.type === "extract-data");
+    throw new ConfigurationError(llmStep?.id ?? "unknown", "AGENT_NOT_PROVIDED", "Workflow contains LLM steps but no agent was provided");
+  }
+  for (const step of workflow.steps) {
+    if (step.type !== "tool-call")
+      continue;
+    const toolDef = options.tools[step.params.toolName];
+    if (!toolDef) {
+      throw new ConfigurationError(step.id, "TOOL_NOT_FOUND", `Tool '${step.params.toolName}' not found`);
+    }
+    if (!toolDef.execute) {
+      throw new ConfigurationError(step.id, "TOOL_MISSING_EXECUTE", `Tool '${step.params.toolName}' has no execute function`);
+    }
+  }
+}
+async function executeWorkflow(workflow, options) {
+  const stepIndex = new Map;
+  for (const step of workflow.steps) {
+    stepIndex.set(step.id, step);
+  }
+  const stepOutputs = {};
+  const resolvedAgent = options.agent ? isAgent(options.agent) ? options.agent : new ToolLoopAgent({
+    model: options.agent,
+    stopWhen: stepCountIs(1)
+  }) : undefined;
+  const resolvedOptions = { ...options, agent: resolvedAgent };
+  try {
+    validateWorkflowConfig(workflow, resolvedOptions);
+    const chainOutput = await executeChain(workflow.initialStepId, stepIndex, stepOutputs, {}, resolvedOptions);
+    if (workflow.outputSchema) {
+      let endStepId = "unknown";
+      for (const step of workflow.steps) {
+        if (step.type === "end" && step.id in stepOutputs) {
+          endStepId = step.id;
+        }
+      }
+      validateWorkflowOutput(workflow.outputSchema, chainOutput, endStepId);
+    }
+    return { success: true, stepOutputs, output: chainOutput };
+  } catch (e) {
+    const error = e instanceof StepExecutionError ? e : new ExternalServiceError("unknown", "TOOL_EXECUTION_FAILED", e instanceof Error ? e.message : String(e), e, undefined, false);
+    return {
+      success: false,
+      stepOutputs,
+      error
+    };
+  }
+}
+// src/generator/index.ts
+import { generateText, stepCountIs as stepCountIs2, tool } from "ai";
+import { type as arktype } from "arktype";
+
+// src/types.ts
+import { type } from "arktype";
+var expressionSchema = type({
+  type: "'literal'",
+  value: "unknown"
+}).or({
+  type: "'jmespath'",
+  expression: "string"
+}).describe("a value that must always be wrapped as an expression object — use { type: 'literal', value: ... } for any static value (strings, numbers, booleans, etc.), or { type: 'jmespath', expression: '...' } for dynamic data extracted from previous steps' outputs (via their step ids, e.g. `stepId.someKey`) or loop variables (e.g. `itemName.someKey` within a for-each loop body)");
+var toolCallParamsSchema = type({
+  type: "'tool-call'",
+  params: {
+    toolName: "string",
+    toolInput: [
+      {
+        "[string]": expressionSchema
+      },
+      "@",
+      "a map of input parameter names to their values; ALL values must be wrapped as expression objects — even static strings like email addresses must use { type: 'literal', value: '...' }, never plain primitives"
+    ]
+  }
+}).describe("a step that calls a tool with specified input parameters (which can be static values or expressions)");
+var switchCaseParamsSchema = type({
+  type: "'switch-case'",
+  params: {
+    switchOn: expressionSchema,
+    cases: [
+      {
+        value: expressionSchema.or({ type: "'default'" }),
+        branchBodyStepId: [
+          "string",
+          "@",
+          "the id of the first step in the branch body chain to execute if this case matches"
+        ]
+      },
+      "[]"
+    ]
+  }
+}).describe("a step that branches to different step chains based on the value of an expression; each case's chain runs until a step with no nextStepId, at which point execution continues with this step's nextStepId; a case with type 'default' serves as the fallback if no other case matches");
+var forEachParamsSchema = type({
+  type: "'for-each'",
+  params: {
+    target: expressionSchema,
+    itemName: [
+      "string",
+      "@",
+      "the name to refer to the current item in the list within expressions in the loop body"
+    ],
+    loopBodyStepId: [
+      "string",
+      "@",
+      "the id of the first step in the loop body chain to execute for each item in the list"
+    ]
+  }
+}).describe("a step that iterates over a list and executes a chain of steps for each item; the loop body chain runs until a step with no nextStepId, at which point the next iteration begins; once all items are exhausted, execution continues with this step's nextStepId");
+var llmPromptSchema = type({
+  type: "'llm-prompt'",
+  params: {
+    prompt: [
+      "string",
+      "@",
+      "a template string where JMESPath expressions can be embedded using ${...} syntax (e.g. 'Hello ${user.name}, you have ${length(user.messages)} messages'). All data from previous steps is available via their step ids (e.g. ${stepId.someKey}), and loop variables are available within for-each loop bodies (e.g. ${itemName.someKey})"
+    ],
+    outputFormat: [
+      "object",
+      "@",
+      "JSON schema specifying the output format expected from the LLM"
+    ]
+  }
+}).describe("a step that prompts an LLM with a text prompt to produce an output in a specified format");
+var extractDataParamsSchema = type({
+  type: "'extract-data'",
+  params: {
+    sourceData: [expressionSchema, "@", "the data to extract information from"],
+    outputFormat: [
+      "object",
+      "@",
+      "JSON schema specifying the output format expected from the data extraction"
+    ]
+  }
+}).describe("a step that uses an LLM to extract structured data from a larger blob of source data (e.g. llm responses or tool outputs with unknown output formats) based on a specified output format");
+var startParamsSchema = type({
+  type: "'start'",
+  params: {
+    inputSchema: [
+      "object",
+      "@",
+      "a JSON Schema object defining the inputs required to run the workflow; the workflow executor will validate provided inputs against this schema, and the validated inputs become available in JMESPath scope via this step's id"
+    ]
+  }
+}).describe("a step that marks the entry point of a workflow and declares the input schema; its output is the validated input data, accessible by subsequent steps via its step id");
+var endSchema = type({
+  type: "'end'",
+  "params?": {
+    output: expressionSchema
+  }
+}).describe("a step that indicates the end of a branch; optionally specify an output expression whose evaluated value becomes the workflow's output");
+var workflowStepSchema = type({
+  id: /^[a-zA-Z_][a-zA-Z0-9_]+$/,
+  name: "string",
+  description: "string",
+  "nextStepId?": "string"
+}).and(toolCallParamsSchema.or(llmPromptSchema).or(extractDataParamsSchema).or(switchCaseParamsSchema).or(forEachParamsSchema).or(startParamsSchema).or(endSchema));
+var workflowDefinitionSchema = type({
+  initialStepId: "string",
+  "outputSchema?": [
+    "object",
+    "@",
+    "an optional JSON Schema object declaring the shape of the workflow's output; when present, the value produced by the end step's output expression will be validated against this schema"
+  ],
+  steps: [
+    [workflowStepSchema, "[]"],
+    "@",
+    "a list of steps to execute in the workflow; these should be in no particular order as execution flow is determined by the nextStepId fields and branching logic within the steps"
+  ]
+});
+
+// src/generator/prompt.ts
+import { asSchema as asSchema2 } from "ai";
+async function serializeToolsForPrompt(tools) {
+  return JSON.stringify(await Promise.all(Object.entries(tools).map(async ([toolName, toolDef]) => ({
+    name: toolName,
+    description: toolDef.description,
+    inputSchema: await asSchema2(toolDef.inputSchema).jsonSchema,
+    outputSchema: toolDef.outputSchema ? await asSchema2(toolDef.outputSchema).jsonSchema : undefined
+  }))));
+}
+function buildWorkflowGenerationPrompt(serializedTools) {
+  return `You are a workflow architect. Your job is to design a workflow definition in the remora DSL that accomplishes a given task using the provided tools. You MUST call the createWorkflow tool with a valid workflow definition.
+
+## Workflow Structure
+
+A workflow has:
+- \`initialStepId\`: the id of the first step to execute
+- \`steps\`: an array of step objects (order does not matter — execution flow is determined by nextStepId links)
+- \`outputSchema\` (optional): a JSON Schema object declaring the shape of the workflow's output. When present, every \`end\` step should have an \`output\` expression that evaluates to a value matching this schema.
+
+## Step Common Fields
+
+Every step has:
+- \`id\`: unique identifier matching /^[a-zA-Z_][a-zA-Z0-9_]+$/ (letters, digits, underscores; at least 2 characters)
+- \`name\`: human-readable name
+- \`description\`: what this step does
+- \`type\`: one of the step types below
+- \`nextStepId\` (optional): id of the next step to execute after this one
+
+## Step Types
+
+### start
+Entry point that declares and validates workflow inputs. Its output (the validated inputs) is accessible by subsequent steps via its step id.
+\`\`\`json
+{
+  "type": "start",
+  "params": {
+    "inputSchema": { "type": "object", "properties": { ... }, "required": [...] }
+  }
+}
+\`\`\`
+
+### tool-call
+Calls a tool with input parameters. All values in toolInput MUST be expression objects.
+\`\`\`json
+{
+  "type": "tool-call",
+  "params": {
+    "toolName": "name-of-tool",
+    "toolInput": {
+      "paramName": { "type": "literal", "value": "static value" },
+      "otherParam": { "type": "jmespath", "expression": "previous_step.someField" }
+    }
+  }
+}
+\`\`\`
+
+### llm-prompt
+Prompts an LLM with a template string to produce structured output. Use \${...} syntax to embed JMESPath expressions in the prompt.
+\`\`\`json
+{
+  "type": "llm-prompt",
+  "params": {
+    "prompt": "Classify this ticket: \${get_tickets.tickets[0].subject}",
+    "outputFormat": { "type": "object", "properties": { "category": { "type": "string" } }, "required": ["category"] }
+  }
+}
+\`\`\`
+
+### extract-data
+Uses an LLM to extract structured data from a source. Use when you need to parse unstructured or semi-structured data into a known shape.
+\`\`\`json
+{
+  "type": "extract-data",
+  "params": {
+    "sourceData": { "type": "jmespath", "expression": "previous_step.rawContent" },
+    "outputFormat": { "type": "object", "properties": { ... }, "required": [...] }
+  }
+}
+\`\`\`
+
+### switch-case
+Branches execution based on a value. Each case's branch chain runs until a step with no nextStepId, then execution continues with this step's nextStepId. Use \`{ "type": "default" }\` for a fallback case.
+\`\`\`json
+{
+  "type": "switch-case",
+  "params": {
+    "switchOn": { "type": "jmespath", "expression": "classify.category" },
+    "cases": [
+      {
+        "value": { "type": "literal", "value": "critical" },
+        "branchBodyStepId": "handle_critical"
+      },
+      {
+        "value": { "type": "default" },
+        "branchBodyStepId": "handle_other"
+      }
+    ]
+  }
+}
+\`\`\`
+
+### for-each
+Iterates over a list and executes a chain of steps for each item. The loop body chain runs until a step with no nextStepId, then the next iteration begins. After all items, execution continues with this step's nextStepId. The \`itemName\` becomes a scoped variable accessible only within the loop body.
+\`\`\`json
+{
+  "type": "for-each",
+  "params": {
+    "target": { "type": "jmespath", "expression": "get_items.items" },
+    "itemName": "item",
+    "loopBodyStepId": "process_item"
+  }
+}
+\`\`\`
+
+### end
+Marks the end of a branch or the workflow. Must NOT have a nextStepId. Optionally, specify an output expression whose value becomes the workflow's return value.
+\`\`\`json
+{
+  "type": "end"
+}
+\`\`\`
+
+With output (when the workflow declares an outputSchema):
+\`\`\`json
+{
+  "type": "end",
+  "params": {
+    "output": { "type": "jmespath", "expression": "summarize.result" }
+  }
+}
+\`\`\`
+
+## Expression System
+
+Every dynamic value must be an expression object:
+
+1. **Literal** — for static values known at design time:
+   \`{ "type": "literal", "value": <any value> }\`
+
+2. **JMESPath** — for referencing data from previous steps or loop variables:
+   \`{ "type": "jmespath", "expression": "<expression>" }\`
+   The root of a JMESPath expression must be either a step id (e.g. \`get_orders.orders\`) or a loop variable name (e.g. \`item.id\` within a for-each body).
+
+3. **Template strings** (llm-prompt only) — embed JMESPath in the prompt string using \${...}:
+   \`"Summarize: \${fetch_data.content}"\`
+   These are NOT expression objects — they appear directly in the prompt string.
+
+## Structural Rules
+
+1. Step IDs must be unique and match /^[a-zA-Z_][a-zA-Z0-9_]+$/.
+2. Steps link via nextStepId. Omitting nextStepId ends the chain.
+3. Branch body chains (switch-case) and loop body chains (for-each) must terminate — their last step must NOT have a nextStepId. Do NOT point them back to the parent or outside the body.
+4. Only reference step IDs of steps that will have executed before the current step (no forward references).
+5. Do not create cycles (for-each handles iteration — you do not need to loop manually).
+6. end steps must NOT have a nextStepId.
+
+## Available Tools
+
+Each tool below includes an \`outputSchema\` describing the shape of its return value. Use the output schema to construct correct JMESPath expressions. For example, if a tool returns \`{ "type": "object", "properties": { "orders": { "type": "array", ... } } }\`, reference the array as \`step_id.orders\`, not \`step_id\` alone.
+
+${serializedTools}
+
+## Common Mistakes
+
+1. NEVER use bare primitives in toolInput. ALL values must be expression objects.
+   WRONG: \`{ "email": "user@example.com" }\`
+   RIGHT: \`{ "email": { "type": "literal", "value": "user@example.com" } }\`
+
+2. Do NOT give end steps a nextStepId.
+
+3. Branch/loop body chains must terminate (last step has no nextStepId). Do NOT point them outside their scope.
+
+4. JMESPath expressions reference step outputs by step ID as the root identifier. Example: \`"get_orders.orders[0].id"\` means step "get_orders" → its output → .orders[0].id
+
+5. For-each itemName is a scoped variable accessible ONLY within the loop body steps.
+
+6. Step IDs must be at least 2 characters long.
+
+7. for-each target must resolve to an ARRAY. Check the tool's outputSchema to determine the correct path.
+   WRONG: \`"target": { "type": "jmespath", "expression": "get_orders" }\` (when get_orders returns an object with an \`orders\` array property)
+   RIGHT: \`"target": { "type": "jmespath", "expression": "get_orders.orders" }\`
+
+8. If the workflow needs to return structured data, declare an \`outputSchema\` on the workflow and give every \`end\` step an \`output\` expression that evaluates to a value matching it.`;
+}
+function formatDiagnostics(diagnostics) {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  if (errors.length === 0)
+    return "No errors.";
+  return errors.map((d) => {
+    const loc = d.location ? ` (at step ${d.location.stepId}${d.location.field ? `, field ${d.location.field}` : ""})` : "";
+    return `- [${d.code}] ${d.message}${loc}`;
+  }).join(`
+`);
+}
+
+// src/generator/index.ts
+async function generateWorkflow(options) {
+  const { model, tools, task, maxRetries = 3 } = options;
+  const missingOutputSchema = Object.entries(tools).filter(([_, t]) => !t.outputSchema).map(([name]) => name);
+  if (missingOutputSchema.length > 0) {
+    throw new Error(`All tools must have an outputSchema. Missing: ${missingOutputSchema.join(", ")}`);
+  }
+  const serializedTools = await serializeToolsForPrompt(tools);
+  const systemPrompt = buildWorkflowGenerationPrompt(serializedTools);
+  let successWorkflow = null;
+  let lastDiagnostics = [];
+  let attempts = 0;
+  const createWorkflowTool = tool({
+    description: "Create a workflow definition",
+    inputSchema: workflowDefinitionSchema,
+    execute: async (workflowDef) => {
+      attempts++;
+      const result = await compileWorkflow(workflowDef, { tools });
+      lastDiagnostics = result.diagnostics;
+      const errors = result.diagnostics.filter((d) => d.severity === "error");
+      if (errors.length > 0) {
+        return {
+          success: false,
+          errors: formatDiagnostics(result.diagnostics)
+        };
+      }
+      successWorkflow = result.workflow ?? workflowDef;
+      return { success: true };
+    }
+  });
+  await generateText({
+    model,
+    system: systemPrompt,
+    prompt: `Create a workflow to accomplish the following task:
+
+${task}`,
+    tools: { createWorkflow: createWorkflowTool },
+    toolChoice: { type: "tool", toolName: "createWorkflow" },
+    stopWhen: [stepCountIs2(maxRetries + 1), () => successWorkflow !== null]
+  });
+  return {
+    workflow: successWorkflow,
+    diagnostics: lastDiagnostics,
+    attempts
+  };
+}
+function createWorkflowGeneratorTool(options) {
+  const { model, tools: baseTools, maxRetries } = options;
+  return tool({
+    description: "Generate a validated workflow definition from a natural language task description",
+    inputSchema: arktype({ task: "string" }),
+    execute: async ({ task }) => {
+      return generateWorkflow({
+        model,
+        tools: baseTools ?? {},
+        task,
+        maxRetries
+      });
+    }
+  });
+}
+export {
+  workflowDefinitionSchema,
+  serializeToolsForPrompt,
+  generateWorkflow,
+  executeWorkflow,
+  createWorkflowGeneratorTool,
+  compileWorkflow,
+  buildWorkflowGenerationPrompt,
+  ValidationError,
+  StepExecutionError,
+  OutputQualityError,
+  ExternalServiceError,
+  ExpressionError,
+  ConfigurationError
+};
+
+//# debugId=DD448656596BC50E64756E2164756E21