Crate leviath_runtime 

Leviath Runtime

ECS-based agent execution engine using bevy_ecs.

The runtime manages agent lifecycle, context window management, task scheduling, and inference execution through a game-loop-inspired architecture where agents are entities and their behaviors are systems.

Embedding

AgentWorld is the front door for running agents inside your own application - no lev CLI, daemon, or config file. Build a world from plain values, spawn an agent, and drive the event stream:

use leviath_runtime::{AgentWorld, BlueprintSource, ProviderCreds, SpawnSpec, WorldEvent};

let world = AgentWorld::builder()
    .provider(ProviderCreds {
        name: "anthropic".to_string(),
        api_key: std::env::var("ANTHROPIC_API_KEY").ok(),
        ..ProviderCreds::simple("anthropic")
    })
    .build()?;

let mut events = world.events();
let run = world
    .spawn(SpawnSpec::new(
        BlueprintSource::Path("coder.leviath".into()),
        "Build a CSV parser",
        std::env::current_dir()?,
    ))
    .await?;

while let Some(event) = events.next().await {
    match event {
        WorldEvent::StageTransition { from, to, .. } => println!("{from} -> {to}"),
        WorldEvent::ToolCallStarted { tool, .. } => println!("running {tool}"),
        WorldEvent::Interaction { request, .. } => {
            // The agent asked a question: answer via world.answer(...).
        }
        WorldEvent::Completed { run_id, status, .. } if run_id == run.as_ref() => break,
        _ => {}
    }
}
world.shutdown().await;

Stability layers

• AgentWorld and the other embed types are the stable embedding surface.
• WorldHost and PipelineWorld are the semi-stable machinery both the daemon and AgentWorld are built on; use them when you need your own assembly (custom spawners, hooks, tick control).
• The raw ECS underneath (PipelineWorld::world_mut) is the unstable escape hatch: it tracks this crate’s bevy_ecs version (re-exported as ecs) and carries no compatibility promise.

Re-exports

pub use components::AgentState;

pub use components::AgentStatus;

pub use components::ContextWindow;

pub use components::ParentRef;

pub use components::SubAgentChildren;

pub use embed::AgentWorld;

pub use embed::AgentWorldBuilder;

pub use embed::BasicToolService;

pub use embed::BlueprintSource;

pub use embed::EmbedError;

pub use embed::EventStream;

pub use embed::RunId;

pub use embed::SpawnSpec;

pub use fanout::FanOutSpawner;

pub use fanout::FanOutSpawnerRes;

pub use host::ControlOp;

pub use host::SpawnArgs;

pub use host::WorldEvent;

pub use host::WorldHost;

pub use inference_pool::InferencePoolConfig;

pub use inference_pool::InferencePools;

pub use interaction_hub::InteractionHub;

pub use pipeline::ModelDefaults;

pub use pipeline::ResolvedStage;

pub use pipeline::ToolService;

pub use provider_creds::ProviderCreds;

pub use provider_creds::build_provider_registry;

pub use taint::TaintGate;

pub use tool_bridge::BoxedToolExec;

pub use world::PipelineWorld;

pub use world::TickOutcome;

pub use bevy_ecs as ecs;

Modules

cancel

A one-shot “stop what you’re doing” signal for work already in flight.

components

ECS components for agent state and execution.

context_setup

Context-window setup helpers shared by the ECS pipeline’s spawner and stage-entry.

custom_region

Runtime side of script-backed custom regions (RegionKind::Custom).

dynamic_interaction

Agent-initiated dynamic interaction tools: present_for_review, ask_user_text, ask_user_choice, ask_user_confirm, edit_document.

embed

Embedding the runtime as a library: the batteries-included assembly a Rust application uses to run agents in-process, without the lev CLI, the daemon, or a config file.

fanout

Fan-out stage handling as ECS systems.

host

The world host: the daemon-side wrapper that owns a single PipelineWorld, maps stable run ids to ECS entities, and interleaves external control operations with driving the world - all on one task, so there is never any locking around the world.

inference_pool

Per-model inference concurrency pools.

interaction_hub

In-memory interaction hub - the shared-world replacement for the imperative worker’s pending.json/response.json file polling.

interaction_points

Declarative stage-boundary interaction points (StageMode::InteractivePoints).

persistence

Agent-state persistence: turning a live ECS agent into the on-disk snapshot the dashboard/API read (meta.json + context.json under the run directory).

pipeline

The ECS pipeline (Phase 2): components + systems that drive every agent through check-input → infer → tools → apply → repeat, entirely as data.

provider_creds

Decoupled provider credentials + registry construction.

restore

Restart recovery: bring a freshly-spawned agent back to its persisted running state so the daemon resumes it where it stopped.

script_provider

Lazy, hot-reloading resolution of Rhai script providers.

taint

Taint gate checking for tool execution.

telemetry

Observability as an ECS system: watch the components every other system already writes and narrate them into the installed TelemetrySink.

title

One-shot run-title generation.

tool_bridge

The async worker side of the ECS tool stage - the sync-ECS ↔ async-I/O bridge for tool execution.

world

The pipeline driver: a single PipelineWorld that hosts every agent as ECS data and ticks the crate::pipeline systems over all of them - the traditional-game-loop core of the shared world.

Structs

ProviderRegistry

Registry of inference providers, keyed by provider name (e.g. "anthropic").

RetryPolicy

How a transient inference failure is retried before the agent is failed.

Type Aliases

AgentEvent

The name issue-facing docs use for the world’s event enum; the same type as WorldEvent.