@remoraflow/core 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# 🦈 Remora
+
+Workflows by agents, for agents.
+
+**[Documentation](https://isaacwasserman.github.io/remora/)** · **[GitHub](https://github.com/isaacwasserman/remora)**
+
+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. Available as an npm import (`remora/viewer`) or via the [shadcn component registry](https://isaacwasserman.github.io/remora/guide/component-registry) for full customization:
+
+```bash
+npx shadcn@latest add https://isaacwasserman.github.io/remora/r/workflow-viewer.json
+npx shadcn@latest add https://isaacwasserman.github.io/remora/r/workflow-step-detail-panel.json
+```
+
+### Component Registry
+
+The viewer components are available via a [shadcn-compatible component registry](https://isaacwasserman.github.io/remora/guide/component-registry), giving you full control over the source code and styling. See the [component registry docs](https://isaacwasserman.github.io/remora/guide/component-registry) for details.
+
+## 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,25 @@
+import type { ToolSet } from "ai";
+import type { WorkflowDefinition } from "../types";
+import type { CompilerLimits, CompilerResult } from "./types";
+/**
+ * Compiles a workflow definition through a multi-pass validation pipeline,
+ * producing an execution graph and structured diagnostics.
+ *
+ * Passes: graph construction, reference validation, control flow validation,
+ * JMESPath validation, tool validation, for-each target validation, and
+ * best-practice transformations.
+ *
+ * @param workflow - The workflow definition to compile.
+ * @param options - Optional configuration.
+ * @param options.tools - Tool definitions to validate tool-call steps against.
+ *   When provided, enables tool input validation and constrained schema generation.
+ * @returns A {@link CompilerResult} containing diagnostics, the execution graph
+ *   (if structurally valid), an optimized workflow (if error-free), and
+ *   constrained tool schemas (if tools were provided).
+ */
+export declare function compileWorkflow(workflow: WorkflowDefinition, options?: {
+    tools?: ToolSet;
+    limits?: CompilerLimits;
+}): Promise<CompilerResult>;
+export type { CompilerLimits, 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;AAUnD,OAAO,KAAK,EACX,cAAc,EACd,cAAc,EAId,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE;IACT,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,cAAc,CAAC;CACxB,GACC,OAAO,CAAC,cAAc,CAAC,CAkEzB;AAiBD,YAAY,EACX,cAAc,EACd,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,CA0F1B"}

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

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ExecutionGraph, ToolDefinitionMap } from "../types";
+export declare function validateControlFlow(workflow: WorkflowDefinition, graph: ExecutionGraph, tools?: ToolDefinitionMap | null): 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,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG9E,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,EACrB,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,GAC9B,UAAU,EAAE,CA8Jd"}

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

@@ -0,0 +1,4 @@
+import type { WorkflowDefinition } from "../../types";
+import type { Diagnostic, ExecutionGraph, ToolDefinitionMap } from "../types";
+export declare function validateForeachTarget(workflow: WorkflowDefinition, 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,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAS9E,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,iBAAiB,GACtB,UAAU,EAAE,CA6Dd"}

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-limits.d.ts

@@ -0,0 +1,9 @@
+import type { WorkflowDefinition } from "../../types";
+import type { CompilerLimits, Diagnostic } from "../types";
+/**
+ * Validates literal values in sleep/wait-for-condition steps against
+ * configured upper/lower bounds. Only checks expressions with
+ * type === 'literal' — JMESPath expressions are unknown at compile time.
+ */
+export declare function validateLimits(workflow: WorkflowDefinition, limits?: CompilerLimits): Diagnostic[];
+//# sourceMappingURL=validate-limits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate-limits.d.ts","sourceRoot":"","sources":["../../../src/compiler/passes/validate-limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAU3D;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,CAAC,EAAE,cAAc,GACrB,UAAU,EAAE,CAqFd"}

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,CA0E7E"}

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,CAuEd"}

package/dist/compiler/types.d.ts

@@ -0,0 +1,100 @@
+import type { WorkflowDefinition, WorkflowStep } from "../types";
+/** Severity level of a compiler diagnostic. */
+export type DiagnosticSeverity = "error" | "warning";
+/** Identifies the source location of a diagnostic within the workflow. */
+export interface DiagnosticLocation {
+    /** The step that triggered the diagnostic, or `null` for workflow-level issues. */
+    stepId: string | null;
+    /** The field path within the step (e.g. `"params.toolInput.email"`). */
+    field: string;
+}
+/**
+ * Machine-readable code identifying the specific diagnostic.
+ * Useful for programmatic handling of compiler feedback.
+ */
+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" | "PATH_MISSING_END_STEP" | "LITERAL_OUTPUT_SHAPE_MISMATCH" | "FOREACH_TARGET_NOT_ARRAY" | "MISSING_CONDITION_BODY_STEP" | "CONDITION_BODY_ESCAPES" | "SLEEP_DURATION_EXCEEDS_LIMIT" | "WAIT_ATTEMPTS_EXCEEDS_LIMIT" | "WAIT_INTERVAL_EXCEEDS_LIMIT" | "BACKOFF_MULTIPLIER_OUT_OF_RANGE" | "WAIT_TIMEOUT_EXCEEDS_LIMIT";
+/**
+ * A structured compiler diagnostic with a severity, location, human-readable message,
+ * and machine-readable code. Emitted during compilation to report errors and warnings.
+ */
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    location: DiagnosticLocation;
+    /** A human-readable description of the issue. */
+    message: string;
+    code: DiagnosticCode;
+}
+/** JSON Schema representation of a tool's input and output. */
+export interface ToolSchemaDefinition {
+    inputSchema: {
+        required?: string[];
+        properties?: Record<string, unknown>;
+    };
+    outputSchema?: Record<string, unknown>;
+}
+/** Maps tool names to their schema definitions. */
+export type ToolDefinitionMap = Record<string, ToolSchemaDefinition>;
+/**
+ * DAG representation of a compiled workflow. Produced by the compiler's graph
+ * construction pass when the workflow is structurally valid.
+ */
+export interface ExecutionGraph {
+    /** Lookup from step ID to step definition. */
+    stepIndex: Map<string, WorkflowStep>;
+    /** Maps each step ID to the set of step IDs it transitions to. */
+    successors: Map<string, Set<string>>;
+    /** Maps each step ID to the set of step IDs that transition to it. */
+    predecessors: Map<string, Set<string>>;
+    /** Step IDs in topological order (respects data dependencies). */
+    topologicalOrder: string[];
+    /** Set of step IDs reachable from `initialStepId`. */
+    reachableSteps: Set<string>;
+    /** Maps each step ID to the set of loop variable names in scope at that step. */
+    loopVariablesInScope: Map<string, Set<string>>;
+    /** Maps body step IDs to the ID of the for-each or switch-case that owns them. */
+    bodyOwnership: Map<string, string>;
+}
+/**
+ * A narrowed tool schema produced by the compiler showing which inputs are
+ * static (known at compile time) vs. dynamic (resolved at runtime). This
+ * enables safety reviews: a human can approve a limited set of behaviors
+ * before execution begins.
+ */
+export interface ConstrainedToolSchema {
+    /** The narrowed input schema, intersecting constraints from all call sites. */
+    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[];
+}
+/** Maps tool names to their constrained schemas. */
+export type ConstrainedToolSchemaMap = Record<string, ConstrainedToolSchema>;
+export interface CompilerLimits {
+    /** Upper bound for wait-for-condition maxAttempts. Default: Infinity (unbounded). */
+    maxAttempts?: number;
+    /** Upper bound for sleep durationMs and wait intervalMs in ms. Default: 300_000 (5 min). */
+    maxSleepMs?: number;
+    /** Upper bound for backoffMultiplier. Default: 2. */
+    maxBackoffMultiplier?: number;
+    /** Lower bound for backoffMultiplier. Default: 1. */
+    minBackoffMultiplier?: number;
+    /** Upper bound for wait-for-condition timeoutMs in ms. Default: 600_000 (10 min). */
+    maxTimeoutMs?: number;
+}
+/** The result of compiling a workflow definition. */
+export interface CompilerResult {
+    /** Errors and warnings produced during compilation. */
+    diagnostics: Diagnostic[];
+    /** The execution graph, or `null` if the workflow has structural errors. */
+    graph: ExecutionGraph | null;
+    /** The optimized workflow with best-practice transformations applied, or `null` if there are errors. */
+    workflow: WorkflowDefinition | null;
+    /** Constrained tool schemas, or `null` if no tools were provided. */
+    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":"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"}

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,CA4B1B;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,CAqDA"}

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/compiler/utils/schema.d.ts

@@ -0,0 +1,33 @@
+import type { WorkflowDefinition, WorkflowStep } from "../../types";
+import type { ExecutionGraph, ToolDefinitionMap } from "../types";
+/**
+ * Parse a simple dotted JMESPath expression (e.g. "step_id.field.nested")
+ * into path segments. Returns null for complex expressions (filters,
+ * projections, functions, etc.).
+ */
+export declare function parseSimplePath(expression: string): string[] | null;
+/**
+ * Walk a JSON Schema along a dotted path, resolving through `properties`
+ * at each segment. Returns null if the path can't be resolved.
+ */
+export declare function resolvePath(schema: Record<string, unknown>, path: string[]): Record<string, unknown> | null;
+/**
+ * Extract the `type` string from a JSON Schema object.
+ */
+export declare function getSchemaType(schema: Record<string, unknown>): string | null;
+/**
+ * Find property names in a schema that are arrays.
+ */
+export declare function findArrayProperties(schema: Record<string, unknown>): string[];
+/**
+ * Resolve the output schema of a workflow step. Returns null if the
+ * output schema is unknown or can't be determined statically.
+ */
+export declare function getStepOutputSchema(step: WorkflowStep, tools: ToolDefinitionMap | null, workflow: WorkflowDefinition, graph: ExecutionGraph): Record<string, unknown> | null;
+/**
+ * Resolve a JMESPath output expression to a JSON Schema by tracing
+ * through step output schemas. Only handles simple dotted paths.
+ * Returns null for complex expressions or when schemas are unavailable.
+ */
+export declare function resolveExpressionSchema(expression: string, _endStepId: string, tools: ToolDefinitionMap | null, workflow: WorkflowDefinition, graph: ExecutionGraph): Record<string, unknown> | null;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/compiler/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAKnE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUhC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAG5E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAQ7E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,iBAAiB,GAAG,IAAI,EAC/B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiChC;AAgCD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,iBAAiB,GAAG,IAAI,EAC/B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,cAAc,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAoBhC"}