Module orchestration 

Programmable, deterministic multi-agent orchestration.

Today an agent fans work out only by model-driven delegation (the LLM decides to call the task / parallel_task tool). This module adds a programmable layer: a developer expresses fan-out / pipelines / verification panels as code, so the orchestration is reproducible, testable, budget-bounded, and (later) resumable — independent of what the model chooses to do.

The framework / host boundary

Everything here is written against one seam, AgentExecutor: “run this step, give me the result.” The framework owns the grammar (which steps, how they compose, the concurrency hint, the data contracts AgentStepSpec / StepOutcome) and ships a default executor that runs every step locally. The placement of those steps across a cluster — transport, scheduling, where a step actually executes — belongs to the host, which implements AgentExecutor. The combinators never observe where a step ran, so the same orchestration scales from one process to a cluster without change.

The in-box implementation is crate::tools::TaskExecutor.

Structs

AgentStepSpec

A single unit of orchestrated agent work — what to run, independent of where it runs.

BudgetSnapshot

An immutable view of a WorkflowBudget ledger.

StepOutcome

The result of running one AgentStepSpec to completion.

Workflow

A cheaply-clonable (all-Arc) typed orchestration facade.

WorkflowBudget

A shared, workflow-scoped token ledger that also acts as a BudgetGuard.

WorkflowBuilder

Builder for a Workflow. The executor is mandatory (it is the seam to the host’s placement / scheduling); everything else is optional.

WorkflowCheckpoint

Snapshot of a workflow’s completed steps at a step boundary.

WorkflowStepRecord

One completed step within a workflow.

Enums

LoopDecision

What an execute_loop predicate decides after seeing a round’s outcomes.

WorkflowEvent

Workflow-level milestone stream, distinct from the per-step AgentEvent stream the combinators already emit.

Constants

WORKFLOW_CHECKPOINT_SCHEMA_VERSION

Schema version. Bumped on incompatible format changes; loads from a future version are rejected (see WorkflowCheckpoint::ensure_loadable).

Traits

AgentExecutor

Runs agent steps — the seam between the framework’s orchestration grammar and the host’s placement / transport / scheduling.

Functions

execute_loop

Run rounds until the predicate says Stop, a round is asked to run no specs, or max_iterations is reached — whichever comes first. Each round is a barrier (execute_steps_parallel); next receives the just-completed round’s outcomes and decides whether (and with what) to continue. Returns the last round’s outcomes (empty if initial was empty).

execute_pipeline

Run each item through stages as an independent chain.

execute_steps_parallel

Fan specs out across the executor, bounded by its concurrency_hint, preserving input order. A panicked branch becomes a failed StepOutcome without dropping the others.

execute_steps_parallel_resumable

Like execute_steps_parallel, but resumable: progress is journaled to store under workflow_id, so an interrupted run picks up from the last completed step.

Type Aliases

PipelineStage

A pipeline stage: given the previous stage’s outcome (None before the first stage) and the original item, produce the next step to run — or None to stop this item’s chain early.