mlua_swarm/
lib.rs

1//! Swarm engine host for mlua — a long-running stateful runtime that
2//! compiles flow.ir Blueprints and dispatches their agent steps to workers.
3//!
4//! # Architecture
5//!
6//! `mlua-swarm` is the host layer of a four-layer stack:
7//!
8//! ```text
9//! flow.ir programs (Lua / JSON Blueprints authored by users or AIs)
10//!         │  parsed / compiled
11//! flow-ir-core        IR node & expr types + pure evaluation
12//!         │  bridged into Lua
13//! mlua-flow-ir        Lua <-> IR bridge (mlua-based)
14//!         │  hosted by
15//! mlua-swarm (this)   engine, workers, operators, middleware, stores
16//! ```
17//!
18//! A [`Blueprint`] declares a `flow` (step / seq / branch / loop / fanout /
19//! try / assign nodes) plus the `agents` it references. The [`Compiler`]
20//! resolves each agent to a [`SpawnerFactory`] (Lua in-process, Rust fn,
21//! subprocess, or WS operator), and the [`Engine`] drives the flow while
22//! recording task state as an [`Event`] stream.
23//!
24//! # Domain vs. Data separation
25//!
26//! Control-flow values (verdicts, counters, small routing fields) travel in
27//! the shared [`Ctx`]; large worker responses are offloaded to an
28//! [`OutputStore`] and referenced from `Ctx` by [`OutputRef`]. This keeps
29//! flow evaluation cheap and bounded regardless of payload size.
30//!
31//! # Middleware
32//!
33//! Worker dispatch passes through a [`SpawnerStack`] assembled from a
34//! [`LayerRegistry`]: a base layer set plus per-blueprint hints
35//! ([`CompilerHints`]) select layers such as audit, long-hold, main-AI
36//! bridging, senior escalation, and operator delegation.
37//!
38//! # Module map
39//!
40//! - [`types`] / [`errors`] — [`Role`](types::Role) × [`Verb`](types::Verb)
41//!   capability gate, [`CapToken`](types::CapToken) (HMAC-SHA256), ID
42//!   newtypes, and the [`EngineError`](errors::EngineError) surface.
43//! - [`core`] — engine config, task state machine, [`Ctx`], and the
44//!   [`Engine`] itself.
45//! - [`blueprint`] — schema shim, compiler, loader (`$agent_md` file-ref
46//!   expansion), and versioned stores (in-memory / git2-backed).
47//! - [`worker`] / [`operator`] — spawner adapters, process spawning, output
48//!   events, and WS operator sessions.
49//! - [`middleware`] — the layer registry and the individual layers.
50//! - [`lua`] / [`agent_block`] — Lua blueprint bridge, `agents/*.md` loader,
51//!   and the agent-block SDK spawner integration.
52//! - [`service`] / [`application`] / [`enhance`] — task-launch orchestration,
53//!   application façades, and the self-enhancement (patch / verify / commit)
54//!   flow.
55//! - [`store`] — persistence traits and default backends for outputs,
56//!   issues, and enhance settings/logs.
57
58#![warn(missing_docs)]
59
60pub mod application;
61pub mod blueprint;
62pub mod core;
63pub mod enhance;
64pub mod lua;
65pub mod middleware;
66pub mod operator;
67pub mod service;
68pub mod store;
69pub mod types;
70pub mod worker;
71
72// Symbol re-exports (preserve external API surface).
73pub use application::{
74    Application, BlueprintRef, EnhanceApplication, EnhanceApplicationConfig,
75    EnhanceApplicationError, EnhanceApplicationInput, TaskApplication, TaskApplicationError,
76    TaskApplicationInput, TaskApplicationOutput, TickOutcome, VersionSelector,
77};
78pub use blueprint::compiler::{
79    CompileError, CompiledAgentTable, CompiledBlueprint, Compiler, HostBridge,
80    LuaInProcessSpawnerFactory, LuaScriptSource, OperatorSpawnerFactory,
81    RustFnInProcessSpawnerFactory, SpawnerFactory, SpawnerFactoryKind, SpawnerRegistry,
82    SubprocessProcessSpawnerFactory,
83};
84pub use blueprint::loader::{expand_file_refs, load_blueprint_from_path, LoadError};
85pub use blueprint::{
86    current_schema_version, AgentDef, AgentKind, AgentMeta, Blueprint, BlueprintMetadata,
87    BlueprintOrigin, CompilerHints, CompilerStrategy, EngineDispatcher, SpawnerHints,
88    CURRENT_SCHEMA_VERSION,
89};
90pub use core::config::{EngineCfg, LongHoldConfig};
91pub use core::ctx::{
92    collapse_operator_kind, Ctx, CtxMeta, OperatorInfo, OperatorKind, SeniorBridge, SpawnHook,
93};
94pub use core::engine::Engine;
95pub use core::errors::EngineError;
96pub use core::projection_placement::{
97    ProjectionPlacement, ProjectionPlacementError, RootPreference,
98};
99pub use core::state::{
100    CapTokenConsumeError, CapTokenRecord, DispatchOutcome, Event, EventStream, OperatorSession,
101    ResumeKey, ResumePending, TaskSpec, TaskState, TaskStatus,
102};
103pub use core::step_naming::{StepNameEntry, StepNaming, StepNamingError, StepNamingWarning};
104pub use lua::bridge::{parse_lua_blueprint, parse_lua_blueprint_with_ctx};
105pub use middleware::lua_layer::LuaMiddleware;
106pub use middleware::project_name_alias::{ProjectNameAliasMiddleware, PROJECT_NAME_ALIAS_KEY};
107pub use middleware::resolver::{AgentResolver, FnResolver, ResolverMiddleware};
108pub use middleware::{
109    AuditMiddleware, LayerFactory, LayerRegistry, LongHoldMiddleware, MainAIMiddleware,
110    OperatorDelegateMiddleware, SeniorEscalationMiddleware, SpawnerLayer, SpawnerStack,
111};
112pub use operator::{Operator, OperatorSpawner, WorkerBinding};
113pub use service::{
114    TaskInputSpec, TaskLaunchError, TaskLaunchInput, TaskLaunchOutput, TaskLaunchService,
115};
116pub use store::output::{
117    InMemoryOutputStore, OutputRecord, OutputRef, OutputStore, OutputStoreError,
118};
119pub use types::{
120    default_role_verb_table, CapToken, CapTokenDecodeError, Role, RoleVerbGate, RunId, SessionId,
121    StepId, TaskId, Verb, WorkerId, WorkerPayload,
122};
123pub use worker::adapter::{
124    InProcSpawner, SpawnError, SpawnerAdapter, WorkerError, WorkerFn, WorkerInvocation,
125    WorkerResult,
126};
127pub use worker::agent_block::AgentBlockInProcessSpawnerFactory;
128pub use worker::output::{ContentRef, OutputEvent, OutputSink};
129pub use worker::process_spawner::{ProcessSpawner, StreamMode};
130pub use worker::{MiddlewareWorker, Worker, WorkerJoinHandler};
mlua_swarm/lib.rs

mlua_swarm/
lib.rs
