@isaacwasserman/remora 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# 🦈 Remora
+
+Workflows by agents, for agents.
+
+Remora is a DSL for agents to write workflows for themselves. An agent receives a task, defines a workflow using Remora's JSON-based syntax, and gets it compiled and validated — producing an executable plan that is well-defined, repeatable, and auditable.
+
+> Unlike unstructured instructions, a Remora workflow is a concrete artifact that can be inspected, versioned, and re-run deterministically.
+
+The workflow definition is a JSON object, which means agents can produce it via a single tool call. The compiler returns structured diagnostics — errors and warnings with specific codes and locations — so the agent gets immediate feedback on whether its logic is sound and can fix issues before anything runs.
+
+> An agent can author a workflow, compile it, read the diagnostics, and iterate — all within a single conversation turn.
+
+The name comes from the remora fish, which attaches to sharks and other large animals. Remora workflows work alongside agents in a similar way: rather than constraining behavior through guardrails, the agent authors its own concrete, inspectable plan using familiar primitives — tool calls, loops, switch statements, and data extraction steps — connected by JMESPath expressions for data flow.
+
+## 🔒 Constrained Tool Schemas
+
+When the compiler analyzes a workflow, it determines exactly which tool parameters are static (known at compile time) versus dynamic (resolved at runtime). This produces a narrowed input schema for each tool.
+
+This matters for safety: a human supervisor can review the constrained schemas and approve a limited set of behaviors ahead of time. The compiler makes this distinction explicit, enabling workflows to run without human-in-the-loop supervision where appropriate.
+
+> A workflow that only ever calls `sendEmail` with a specific template and a dynamic recipient is meaningfully different from one with unconstrained access to the email API.
+
+## 🏗️ Architecture
+
+Remora has three main components:
+
+### Compiler
+
+A multi-pass compiler that takes a raw workflow definition and produces a validated execution graph. Passes include:
+
+- **Graph construction** — builds the DAG, detects cycles and duplicate step IDs
+- **Reference validation** — verifies all step references resolve
+- **Control flow validation** — checks branching and looping logic
+- **JMESPath validation** — parses and validates all expressions
+- **Tool validation** — ensures tool call parameters match available tool schemas
+- **Constrained schema generation** — produces narrowed tool input schemas
+- **Best practices** — applies non-destructive transformations (e.g., adding missing end steps)
+
+Diagnostics are emitted as structured errors and warnings with specific codes, step locations, and field paths.
+
+### Executor
+
+A runtime engine that walks the compiled execution graph step by step. It handles:
+
+- **Tool calls** with literal or expression-based arguments
+- **LLM prompts** with template string interpolation from step outputs
+- **Data extraction** via JMESPath or LLM-based extraction
+- **Switch-case** branching on step output values
+- **For-each** loops over arrays with scoped iteration variables
+
+Each step's output is stored in a scope that subsequent steps can reference via JMESPath expressions, providing structured data flow without arbitrary code.
+
+The executor is compatible with the [Vercel AI SDK](https://ai-sdk.dev/) and will eventually support any agent implementing the AI SDK's agent interface.
+
+### Viewer
+
+A React-based workflow visualizer built on [React Flow](https://reactflow.dev/) that renders compiled workflows as interactive DAGs. Currently serves as a developer tool and demo. The plan is to ship this as a set of embeddable UI components that other developers can use to display Remora workflows within their own apps.
+
+## The DSL
+
+Workflows are defined as a list of steps with an initial step ID. Each step has a type (`tool-call`, `llm-prompt`, `extract-data`, `switch-case`, `for-each`, or `end`), a `nextStepId` for sequencing, and type-specific parameters. Data flows between steps through JMESPath expressions that reference previous step outputs.
+
+See [`src/example-tasks.ts`](src/example-tasks.ts) for complete workflow examples including support ticket triage, order fulfillment, content moderation, and student course assignment.
+
+See [`src/types.ts`](src/types.ts) for the full type definitions.
+
+## Getting Started
+
+```bash
+bun install
+```
+
+Run the workflow viewer:
+
+```bash
+bun run viewer
+```
+
+Run tests:
+
+```bash
+bun test
+```
+
+Lint:
+
+```bash
+bun run lint
+```
+
+Type check:
+
+```bash
+bun run typecheck
+```
+
+## ⚠️ Status
+
+Early prototype. The core compiler, executor, and viewer are functional, but the API is unstable and breaking changes should be expected.

package/dist/compiler/index.d.ts

@@ -0,0 +1,8 @@
+import type { ToolSet } from "ai";
+import type { WorkflowDefinition } from "../types";
+import type { CompilerResult } from "./types";
+export declare function compileWorkflow(workflow: WorkflowDefinition, options?: {
+    tools?: ToolSet;
+}): Promise<CompilerResult>;
+export type { CompilerResult, ConstrainedToolSchema, ConstrainedToolSchemaMap, Diagnostic, DiagnosticCode, DiagnosticLocation, DiagnosticSeverity, ExecutionGraph, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/compiler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAElC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AASnD,OAAO,KAAK,EACX,cAAc,EAId,MAAM,SAAS,CAAC;AAEjB,wBAAsB,eAAe,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE;IACT,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB,GACC,OAAO,CAAC,cAAc,CAAC,CA4DzB;AAiBD,YAAY,EACX,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,GACd,MAAM,SAAS,CAAC"}

package/dist/compiler/passes/apply-best-practices.d.ts

@@ -0,0 +1,19 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ExecutionGraph } from "../types";
+interface BestPracticeRuleResult {
+    workflow: WorkflowDefinition;
+    diagnostics: Diagnostic[];
+}
+/**
+ * A best-practice rule that can non-destructively modify a workflow.
+ * Each rule receives a deep-cloned workflow and the execution graph,
+ * and returns the (possibly modified) workflow along with any diagnostics.
+ */
+export type BestPracticeRule = (workflow: WorkflowDefinition, graph: ExecutionGraph) => BestPracticeRuleResult;
+/**
+ * Applies all registered best-practice rules to a deep copy of the workflow.
+ * The original workflow is never mutated.
+ */
+export declare function applyBestPractices(workflow: WorkflowDefinition, graph: ExecutionGraph): BestPracticeRuleResult;
+export {};
+//# sourceMappingURL=apply-best-practices.d.ts.map

package/dist/compiler/passes/apply-best-practices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-best-practices.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/apply-best-practices.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE3D,UAAU,sBAAsB;IAC/B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC9B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,KACjB,sBAAsB,CAAC;AAQ5B;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,GACnB,sBAAsB,CAWxB"}

package/dist/compiler/passes/build-graph.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ExecutionGraph } from "../types";
+export declare function buildGraph(workflow: WorkflowDefinition): {
+    graph: ExecutionGraph | null;
+    diagnostics: Diagnostic[];
+};
+//# sourceMappingURL=build-graph.d.ts.map

package/dist/compiler/passes/build-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-graph.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/build-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAW3D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG;IACzD,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC1B,CAuIA"}

package/dist/compiler/passes/generate-constrained-tool-schemas.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { ConstrainedToolSchemaMap, ToolDefinitionMap } from "../types";
+export declare function generateConstrainedToolSchemas(workflow: WorkflowDefinition, tools: ToolDefinitionMap): ConstrainedToolSchemaMap;
+//# sourceMappingURL=generate-constrained-tool-schemas.d.ts.map

package/dist/compiler/passes/generate-constrained-tool-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-constrained-tool-schemas.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/generate-constrained-tool-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAEX,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,UAAU,CAAC;AA4GlB,wBAAgB,8BAA8B,CAC7C,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,iBAAiB,GACtB,wBAAwB,CA4D1B"}

package/dist/compiler/passes/validate-control-flow.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ExecutionGraph } from "../types";
+export declare function validateControlFlow(workflow: WorkflowDefinition, graph: ExecutionGraph): Diagnostic[];
+//# sourceMappingURL=validate-control-flow.d.ts.map

package/dist/compiler/passes/validate-control-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-control-flow.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/validate-control-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE3D,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,GACnB,UAAU,EAAE,CA4Fd"}

package/dist/compiler/passes/validate-foreach-target.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowStep } from "../../types";
+import type { Diagnostic, ExecutionGraph, ToolDefinitionMap } from "../types";
+export declare function validateForeachTarget(workflow: {
+    steps: WorkflowStep[];
+}, graph: ExecutionGraph, tools: ToolDefinitionMap): Diagnostic[];
+//# sourceMappingURL=validate-foreach-target.d.ts.map

package/dist/compiler/passes/validate-foreach-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-foreach-target.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/validate-foreach-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9E,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE;IAAE,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,EACnC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,iBAAiB,GACtB,UAAU,EAAE,CAoDd"}

package/dist/compiler/passes/validate-jmespath.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ExecutionGraph } from "../types";
+export declare function validateJmespath(workflow: WorkflowDefinition, graph: ExecutionGraph): Diagnostic[];
+//# sourceMappingURL=validate-jmespath.d.ts.map

package/dist/compiler/passes/validate-jmespath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-jmespath.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/validate-jmespath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAa3D,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,GACnB,UAAU,EAAE,CAyBd"}

package/dist/compiler/passes/validate-references.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic } from "../types";
+export declare function validateReferences(workflow: WorkflowDefinition): Diagnostic[];
+//# sourceMappingURL=validate-references.d.ts.map

package/dist/compiler/passes/validate-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,UAAU,EAAE,CA2D7E"}

package/dist/compiler/passes/validate-tools.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ToolDefinitionMap } from "../types";
+export declare function validateTools(workflow: WorkflowDefinition, tools: ToolDefinitionMap): Diagnostic[];
+//# sourceMappingURL=validate-tools.d.ts.map

package/dist/compiler/passes/validate-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-tools.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/validate-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9D,wBAAgB,aAAa,CAC5B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,iBAAiB,GACtB,UAAU,EAAE,CAsDd"}

package/dist/compiler/types.d.ts

@@ -0,0 +1,49 @@
+import type { WorkflowDefinition, WorkflowStep } from "../types";
+export type DiagnosticSeverity = "error" | "warning";
+export interface DiagnosticLocation {
+    stepId: string | null;
+    field: string;
+}
+export type DiagnosticCode = "INVALID_STEP_ID" | "INVALID_ITEM_NAME" | "ITEM_NAME_SHADOWS_STEP_ID" | "DUPLICATE_STEP_ID" | "MISSING_INITIAL_STEP" | "MISSING_NEXT_STEP" | "MISSING_BRANCH_BODY_STEP" | "MISSING_LOOP_BODY_STEP" | "UNREACHABLE_STEP" | "CYCLE_DETECTED" | "UNCLOSED_TEMPLATE_EXPRESSION" | "JMESPATH_SYNTAX_ERROR" | "JMESPATH_INVALID_ROOT_REFERENCE" | "JMESPATH_FORWARD_REFERENCE" | "END_STEP_HAS_NEXT" | "BRANCH_BODY_ESCAPES" | "LOOP_BODY_ESCAPES" | "MULTIPLE_DEFAULT_CASES" | "UNKNOWN_TOOL" | "MISSING_TOOL_INPUT_KEY" | "EXTRA_TOOL_INPUT_KEY" | "MISSING_START_STEP" | "END_STEP_MISSING_OUTPUT" | "END_STEP_UNEXPECTED_OUTPUT" | "FOREACH_TARGET_NOT_ARRAY";
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    location: DiagnosticLocation;
+    message: string;
+    code: DiagnosticCode;
+}
+export interface ToolSchemaDefinition {
+    inputSchema: {
+        required?: string[];
+        properties?: Record<string, unknown>;
+    };
+    outputSchema?: Record<string, unknown>;
+}
+export type ToolDefinitionMap = Record<string, ToolSchemaDefinition>;
+export interface ExecutionGraph {
+    stepIndex: Map<string, WorkflowStep>;
+    successors: Map<string, Set<string>>;
+    predecessors: Map<string, Set<string>>;
+    topologicalOrder: string[];
+    reachableSteps: Set<string>;
+    loopVariablesInScope: Map<string, Set<string>>;
+    bodyOwnership: Map<string, string>;
+}
+export interface ConstrainedToolSchema {
+    inputSchema: {
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    outputSchema?: Record<string, unknown>;
+    /** True when ALL inputs across ALL call sites are literals — safe for unsupervised execution. */
+    fullyStatic: boolean;
+    /** Step IDs that call this tool. */
+    callSites: string[];
+}
+export type ConstrainedToolSchemaMap = Record<string, ConstrainedToolSchema>;
+export interface CompilerResult {
+    diagnostics: Diagnostic[];
+    graph: ExecutionGraph | null;
+    workflow: WorkflowDefinition | null;
+    constrainedToolSchemas: ConstrainedToolSchemaMap | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/compiler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/compiler/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEjE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,2BAA2B,GAC3B,mBAAmB,GACnB,sBAAsB,GACtB,mBAAmB,GACnB,0BAA0B,GAC1B,wBAAwB,GACxB,kBAAkB,GAClB,gBAAgB,GAChB,8BAA8B,GAC9B,uBAAuB,GACvB,iCAAiC,GACjC,4BAA4B,GAC5B,mBAAmB,GACnB,qBAAqB,GACrB,mBAAmB,GACnB,wBAAwB,GACxB,cAAc,GACd,wBAAwB,GACxB,sBAAsB,GACtB,oBAAoB,GACpB,yBAAyB,GACzB,4BAA4B,GAC5B,0BAA0B,CAAC;AAE9B,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACpC,WAAW,EAAE;QACZ,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAErE,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACrC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACrC,WAAW,EAAE;QACZ,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,iGAAiG;IACjG,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,sBAAsB,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACxD"}

package/dist/compiler/utils/graph.d.ts

@@ -0,0 +1,35 @@
+import type { WorkflowStep } from "../../types";
+export declare function buildStepIndex(steps: WorkflowStep[]): {
+    index: Map<string, WorkflowStep>;
+    duplicates: string[];
+};
+export declare function computeSuccessors(stepIndex: Map<string, WorkflowStep>): Map<string, Set<string>>;
+export declare function computeReachability(initialStepId: string, successors: Map<string, Set<string>>): Set<string>;
+/**
+ * Detect cycles using DFS with white/gray/black coloring.
+ * Returns arrays of step IDs forming each detected cycle.
+ */
+export declare function detectCycles(stepIndex: Map<string, WorkflowStep>, successors: Map<string, Set<string>>): string[][];
+/**
+ * Compute the set of predecessor step IDs for each step.
+ * A predecessor of step X is any step that must have executed before X
+ * in the execution order.
+ *
+ * This uses topological order: for each step, its predecessors are the
+ * union of all steps that can reach it via successor edges.
+ */
+export declare function computePredecessors(topologicalOrder: string[], successors: Map<string, Set<string>>): Map<string, Set<string>>;
+/**
+ * Compute topological order using Kahn's algorithm.
+ * Returns null if cycles exist.
+ */
+export declare function topologicalSort(stepIds: string[], successors: Map<string, Set<string>>): string[] | null;
+/**
+ * Walk the execution graph to determine which loop variables (itemName)
+ * are in scope at each step, and which steps belong to a body (loop or branch).
+ */
+export declare function computeLoopScopesAndOwnership(initialStepId: string, stepIndex: Map<string, WorkflowStep>): {
+    loopVariablesInScope: Map<string, Set<string>>;
+    bodyOwnership: Map<string, string>;
+};
+//# sourceMappingURL=graph.d.ts.map

package/dist/compiler/utils/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/compiler/utils/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG;IACtD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,EAAE,CAAC;CACrB,CAaA;AAED,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAClC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAwB1B;AAED,wBAAgB,mBAAmB,CAClC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAClC,GAAG,CAAC,MAAM,CAAC,CAqBb;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EACpC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAClC,MAAM,EAAE,EAAE,CA+CZ;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,gBAAgB,EAAE,MAAM,EAAE,EAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAClC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA2B1B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAClC,MAAM,EAAE,GAAG,IAAI,CA4CjB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC5C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAClC;IACF,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC,CAiDA"}

package/dist/compiler/utils/jmespath-helpers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Validate that a JMESPath expression is syntactically valid.
+ */
+export declare function validateJmespathSyntax(expression: string): {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Extract root identifiers from a JMESPath AST.
+ * A "root identifier" is a Field node that represents a top-level
+ * reference (e.g., `stepId` in `stepId.field`, `foo` in `length(foo.bar)`).
+ *
+ * We walk the AST and collect Field nodes that appear in "root position" —
+ * meaning they are the leftmost leaf in a chain of Subexpressions,
+ * or standalone fields, or the first field in a function argument.
+ */
+export declare function extractRootIdentifiers(expression: string): string[];
+export interface TemplateExpression {
+    expression: string;
+    start: number;
+    end: number;
+}
+export interface TemplateExtractionResult {
+    expressions: TemplateExpression[];
+    unclosed: number[];
+}
+/**
+ * Extract all ${...} template expressions from an llm-prompt template string.
+ * Also reports positions of unclosed ${ sequences.
+ */
+export declare function extractTemplateExpressions(template: string): TemplateExtractionResult;
+//# sourceMappingURL=jmespath-helpers.d.ts.map

package/dist/compiler/utils/jmespath-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jmespath-helpers.d.ts","sourceRoot":"","sources":["../../../src/compiler/utils/jmespath-helpers.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOnD;AAYD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAWnE;AAmID,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,wBAAwB;IACxC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GACd,wBAAwB,CA+B1B"}

package/dist/executor/errors.d.ts

@@ -0,0 +1,32 @@
+export type RecoveryStrategy = "none" | "retry" | "llm-transform" | "llm-reprompt";
+export type ErrorCategory = "configuration" | "validation" | "external-service" | "expression" | "output-quality";
+export type ErrorCode = "TOOL_NOT_FOUND" | "TOOL_MISSING_EXECUTE" | "AGENT_NOT_PROVIDED" | "TOOL_INPUT_VALIDATION_FAILED" | "FOREACH_TARGET_NOT_ARRAY" | "WORKFLOW_OUTPUT_VALIDATION_FAILED" | "TOOL_EXECUTION_FAILED" | "LLM_API_ERROR" | "LLM_RATE_LIMITED" | "LLM_NETWORK_ERROR" | "LLM_NO_CONTENT" | "JMESPATH_EVALUATION_ERROR" | "TEMPLATE_INTERPOLATION_ERROR" | "LLM_OUTPUT_PARSE_ERROR";
+export declare class StepExecutionError extends Error {
+    readonly stepId: string;
+    readonly code: ErrorCode;
+    readonly category: ErrorCategory;
+    readonly cause?: unknown | undefined;
+    readonly name = "StepExecutionError";
+    constructor(stepId: string, code: ErrorCode, category: ErrorCategory, message: string, cause?: unknown | undefined);
+}
+export declare class ConfigurationError extends StepExecutionError {
+    constructor(stepId: string, code: ErrorCode, message: string);
+}
+export declare class ValidationError extends StepExecutionError {
+    readonly input: unknown;
+    constructor(stepId: string, code: ErrorCode, message: string, input: unknown, cause?: unknown);
+}
+export declare class ExternalServiceError extends StepExecutionError {
+    readonly statusCode?: number | undefined;
+    readonly isRetryable: boolean;
+    constructor(stepId: string, code: ErrorCode, message: string, cause?: unknown, statusCode?: number | undefined, isRetryable?: boolean);
+}
+export declare class ExpressionError extends StepExecutionError {
+    readonly expression: string;
+    constructor(stepId: string, code: ErrorCode, message: string, expression: string, cause?: unknown);
+}
+export declare class OutputQualityError extends StepExecutionError {
+    readonly rawOutput: unknown;
+    constructor(stepId: string, code: ErrorCode, message: string, rawOutput: unknown, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/executor/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/executor/errors.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GACzB,MAAM,GACN,OAAO,GACP,eAAe,GACf,cAAc,CAAC;AAElB,MAAM,MAAM,aAAa,GACtB,eAAe,GACf,YAAY,GACZ,kBAAkB,GAClB,YAAY,GACZ,gBAAgB,CAAC;AAEpB,MAAM,MAAM,SAAS,GAElB,gBAAgB,GAChB,sBAAsB,GACtB,oBAAoB,GAEpB,8BAA8B,GAC9B,0BAA0B,GAC1B,mCAAmC,GAEnC,uBAAuB,GACvB,eAAe,GACf,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB,GAEhB,2BAA2B,GAC3B,8BAA8B,GAE9B,wBAAwB,CAAC;AAI5B,qBAAa,kBAAmB,SAAQ,KAAK;aAI3B,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,SAAS;aACf,QAAQ,EAAE,aAAa;aAEd,KAAK,CAAC,EAAE,OAAO;IAPzC,SAAkB,IAAI,wBAAwB;gBAG7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,aAAa,EACvC,OAAO,EAAE,MAAM,EACU,KAAK,CAAC,EAAE,OAAO,YAAA;CAIzC;AAID,qBAAa,kBAAmB,SAAQ,kBAAkB;gBAC7C,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAG5D;AAED,qBAAa,eAAgB,SAAQ,kBAAkB;aAKrC,KAAK,EAAE,OAAO;gBAH9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,OAAO,EAC9B,KAAK,CAAC,EAAE,OAAO;CAIhB;AAED,qBAAa,oBAAqB,SAAQ,kBAAkB;aAM1C,UAAU,CAAC,EAAE,MAAM;aACnB,WAAW,EAAE,OAAO;gBALpC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,WAAW,GAAE,OAAc;CAI5C;AAED,qBAAa,eAAgB,SAAQ,kBAAkB;aAKrC,UAAU,EAAE,MAAM;gBAHlC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClC,KAAK,CAAC,EAAE,OAAO;CAIhB;AAED,qBAAa,kBAAmB,SAAQ,kBAAkB;aAKxC,SAAS,EAAE,OAAO;gBAHlC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,OAAO,EAClC,KAAK,CAAC,EAAE,OAAO;CAIhB"}

package/dist/executor/index.d.ts

@@ -0,0 +1,20 @@
+import type { Agent, LanguageModel, ToolSet } from "ai";
+import type { WorkflowDefinition, WorkflowStep } from "../types";
+import { StepExecutionError } from "./errors";
+export interface ExecutionResult {
+    success: boolean;
+    stepOutputs: Record<string, unknown>;
+    output?: unknown;
+    error?: StepExecutionError;
+}
+export interface ExecuteWorkflowOptions {
+    tools: ToolSet;
+    agent?: Agent | LanguageModel;
+    inputs?: Record<string, unknown>;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    onStepStart?: (stepId: string, step: WorkflowStep) => void;
+    onStepComplete?: (stepId: string, output: unknown) => void;
+}
+export declare function executeWorkflow(workflow: WorkflowDefinition, options: ExecuteWorkflowOptions): Promise<ExecutionResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/executor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAWxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEjE,OAAO,EAKN,kBAAkB,EAElB,MAAM,UAAU,CAAC;AAWlB,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,GAAG,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3D,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAkvBD,wBAAsB,eAAe,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,sBAAsB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA8D1B"}

package/dist/generator/index.d.ts

@@ -0,0 +1,24 @@
+import type { LanguageModel, ToolSet } from "ai";
+import type { Diagnostic } from "../compiler/types";
+import type { WorkflowDefinition } from "../types";
+export interface GenerateWorkflowOptions {
+    model: LanguageModel;
+    tools: ToolSet;
+    task: string;
+    maxRetries?: number;
+}
+export interface GenerateWorkflowResult {
+    workflow: WorkflowDefinition | null;
+    diagnostics: Diagnostic[];
+    attempts: number;
+}
+export interface WorkflowGeneratorToolOptions {
+    model: LanguageModel;
+    tools?: ToolSet;
+    maxRetries?: number;
+}
+export declare function generateWorkflow(options: GenerateWorkflowOptions): Promise<GenerateWorkflowResult>;
+export declare function createWorkflowGeneratorTool(options: WorkflowGeneratorToolOptions): import("ai").Tool<{
+    task: string;
+}, GenerateWorkflowResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/generator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generator/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAIjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAUnD,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC5C,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,sBAAsB,CAAC,CAsDjC;AAID,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,4BAA4B;;2BAiBrC"}

package/dist/generator/prompt.d.ts

@@ -0,0 +1,6 @@
+import { type ToolSet } from "ai";
+import type { Diagnostic } from "../compiler/types";
+export declare function serializeToolsForPrompt(tools: ToolSet): Promise<string>;
+export declare function buildWorkflowGenerationPrompt(serializedTools: string): string;
+export declare function formatDiagnostics(diagnostics: Diagnostic[]): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/generator/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/generator/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAa7E;AAED,wBAAgB,6BAA6B,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CA8K7E;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAWnE"}

package/dist/lib.d.ts

@@ -0,0 +1,11 @@
+export type { CompilerResult, ConstrainedToolSchema, ConstrainedToolSchemaMap, Diagnostic, DiagnosticCode, DiagnosticLocation, DiagnosticSeverity, ExecutionGraph, } from "./compiler";
+export { compileWorkflow } from "./compiler";
+export type { ExecuteWorkflowOptions, ExecutionResult } from "./executor";
+export { executeWorkflow } from "./executor";
+export type { ErrorCategory, ErrorCode, RecoveryStrategy, } from "./executor/errors";
+export { ConfigurationError, ExpressionError, ExternalServiceError, OutputQualityError, StepExecutionError, ValidationError, } from "./executor/errors";
+export type { GenerateWorkflowOptions, GenerateWorkflowResult, WorkflowGeneratorToolOptions, } from "./generator";
+export { createWorkflowGeneratorTool, generateWorkflow } from "./generator";
+export { buildWorkflowGenerationPrompt, serializeToolsForPrompt, } from "./generator/prompt";
+export { type WorkflowDefinition, type WorkflowStep, workflowDefinitionSchema, } from "./types";
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACX,aAAa,EACb,SAAS,EACT,gBAAgB,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACX,uBAAuB,EACvB,sBAAsB,EACtB,4BAA4B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EACN,6BAA6B,EAC7B,uBAAuB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,wBAAwB,GACxB,MAAM,SAAS,CAAC"}