Module blueprint

Expand description

Blueprint runner — glue that executes a flow.ir AST (mlua_flow_ir::Node) through the engine. Each Step.ref is run as a single task via start_task + dispatch_attempt_with_run_ctx, and the resulting Pass Value is written back to Step.out.

Fully-async chain. Uses mlua_flow_ir::eval_async and AsyncDispatcher; block_on and spawn_blocking are never mixed in, so the whole stack stays consistent with the engine’s tokio async world.

§Usage

let dispatcher = EngineDispatcher::with_spawner(engine.clone(), op_token, spawner);
let bp: mlua_flow_ir::Node = serde_json::from_str(BP_JSON)?;
let final_ctx = mlua_flow_ir::eval_async(&bp, init_ctx, &dispatcher).await?;

§Schema types (the IF crate)

Blueprint / AgentDef / AgentKind and friends live in the mlua_swarm_schema crate and are re-exported from here. The struct/enum set that used to live directly in src/blueprint.rs has been moved into the IF crate to support extension discipline, versioning, and external consumers.

Modules§

compiler: Blueprint Compiler, CompiledAgentTable, and the three default SpawnerFactory implementations.
loader: Compat shim — the Blueprint loader (expand_file_refs / load_blueprint_from_path / pre_read_default_agent_kind / LoadError) moved to the sibling mlua-swarm-compile crate’s linker module so that the CLI (mse bp lint / mse bp build) and the server register path share one linker binary instead of two hand-copied bodies. This module re-exports the moved surface for pre-migration call sites; new code should reach into mlua_swarm_compile::linker directly (issue 4c4e3eb8 Phase 2).
store: BlueprintStore — the Blueprint VCS abstraction.

Structs§

AgentDef: Maps an agent name to a Worker IMPL kind and its configuration. Referenced from flow.ir Step.ref by name.
AgentMeta: Agent / Operator level metadata (description / version / tags).
AgentProfile: Agent persona information. Orthogonal to the backend kind (Shell / InProc / Operator).
AgentProviderCapability: One effective capability advertised by an execution-environment provider. Operator manifests normally publish one entry per wrapper variant.
AgentProviderManifest: Capability manifest supplied by an Operator/MainAI or an official execution-platform plugin when joining the Server.
AuditDef: GH #34 — one Blueprint-declared after-run audit hook. See Blueprint::audits for the persistence / invariant contract.
BindReceipt: Provider report describing the effective runtime binding for one agent. This value is untrusted until Swarm validates it against BindRequest.
BindRequest: Platform-neutral request sent to an AgentBindingProvider before a Run is dispatched.
BindingAttestation: Core-validated capability statement pinned into a BoundAgent.
BindingDigest: Strongly typed identity of one immutable BoundAgent snapshot. Transparent serde keeps the public JSON wire form a plain string.
Blueprint: Unified package of flow.ir + Swarm extension layers. The entry-point type of Swarm.
BlueprintMetadata: Blueprint-level metadata (description / origin / tags / ttl / version label / alias).
BoundAgent: Immutable, Run-scoped result of binding the Runner / Agent / Context layers for one logical agent.
CompilerHints: Per-agent overrides / hints. Interpreted by the Compiler / SpawnerFactory; not required.
CompilerStrategy: Compiler behavior rules. Controls strict / lenient handling and default fallback.
EngineDispatcher: Bridges mlua_flow_ir::AsyncDispatcher to the engine’s start_task + dispatch_attempt_with_run_ctx pair. Holds one Operator session token and one spawner, and spins up a fresh task per Step.ref, using it as the agent name.
MetaDef: Named, multi-step-shared declarative context payload (GH #21 Phase 2).
OperatorDef: Design-time definition of an Operator role (first-class).
ProjectionPlacementSpec: GH #27 (follow-up to #23) — Blueprint-declared override of the mlua-swarm core crate’s placement resolver (mlua_swarm::core::projection_placement::ProjectionPlacement), which decides where a Step’s materialized OUTPUT file (submit-time sink, server read-back, and spawn-time ctx_projection pointer — the “3 path” convergence point) is written on disk. Both fields are independently optional and validated (dir_template) at Compiler::compile time — see that resolver’s from_spec doc for the full rejection rules.
RunnerDef: One Blueprint::runners registry entry — a named Runner declaration referenced by AgentDef.runner_ref / Blueprint::default_runner. Same registry shape as MetaDef (GH #21 Phase 2).
SpawnerHints: Set of capability hint keys for the SpawnerLayer required by a Blueprint.
SubprocessDef: GH #83 — one declarative CLI invocation template: how a materialized worker payload (system prompt + task + model/tools/cwd) is rendered into a child-process invocation, and how its stdout is normalized back into the worker-result shape.
SubprocessOutput: GH #83 — declarative stdout → worker-result normalization for a SubprocessDef (plain mode only; streaming modes keep their event protocol untouched).
SubprocessOverrides: Per-agent overrides for Runner::Subprocess — values that take precedence over the agent’s profile.model / profile.tools and the spawn-time {work_dir} placeholder source when rendering the SubprocessDef template. Lives on the Runner variant (not on SubprocessDef) so the template itself stays flat (no per-agent state, no variant axis).
WorkerModel: Canonical GH #46 Worker unit: a resolved Runner paired with the AgentDef it backs. The Milestone 4 adapter is the consumer that turns this into a runtime spawn; this crate only declares the shape (no execution logic lives here — see the crate doc’s IN-immutability discipline).

Enums§

AgentKind: SoT of the Worker IMPL axis. A closed enum managed inside Swarm and extended by variant addition through explicit maintenance. String lookup / escape hatches are deliberately not adopted.
AuditMode: GH #34 — dispatch timing for an AuditDef’s audit agent. Neither variant ever changes the audited step’s outcome (see Blueprint::audits’s binding invariant).
BindOutcome: One provider outcome for a single BindRequest.
BindingBackend: Backend family a binding provider must resolve.
BindingDigestParseError: Rejection returned when an external binding digest is not in canonical sha256:<64 lowercase hex> form.
BlueprintOrigin: Provenance record of a Blueprint.
BoundAgentResolveError: Failure while constructing immutable BoundAgent snapshots.
Runner: The execution shell an agent’s Worker IMPL runs inside — holding tool grant, model selection, and runtime capabilities. Tier 1 of the GH #46 3-tier Worker model (Runner / Agent / Context).
RunnerResolutionSource: Which declaration tier supplied a BoundAgent’s resolved Runner. Kept in the immutable snapshot so explain surfaces can distinguish a first-class binding from the Claude Code compatibility fallback.
RunnerResolveError: Everything resolve_runner can fail with: an AgentDef.runner_ref / Blueprint.default_runner reference that names no entry in Blueprint.runners.
SchemaOperatorKind: The schema-side OperatorKind (see crate::core::ctx::OperatorKind for the runtime duplicate consumed by Engine). Re-exported under an explicit alias so callers reading Blueprint.operators[].kind / Blueprint.default_operator_kind do not have to reach into mlua_swarm_schema directly. Kind axis of an Operator role (= “in which mode does this Operator run”). Corresponds 1:1 with the engine’s runtime OperatorKind. Kept as a schema duplicate so that BPs can be authored while depending only on this crate.

Constants§

CURRENT_SCHEMA_VERSION: Current Blueprint schema version. Tied to this crate’s semver.

Functions§

current_schema_version: Blueprint construction helper: returns the semver of the current schema version. Callers can write schema_version: current_schema_version(),.
default_global_agent_kind: Global default AgentKind at the Schema impl Default layer. Bottom of the 4-layer cascade.
resolve_bound_agents: Resolve every Blueprint.agents entry into an immutable Run snapshot. Output order follows Blueprint.agents, making persistence and explain responses stable without a second sort.
resolve_bound_agents_strict: Strict counterpart to resolve_bound_agents: rejects the deprecated profile.worker_binding fallback. This is the migration gate for callers that require every binding to use the platform-neutral Runner contract.
resolve_runner: Resolve agent’s effective Runner against bp, in cascade order (highest priority first):