salvor/
lib.rs

1//! Salvor is a durable execution runtime for AI agents, written in Rust.
2//!
3//! A salvor is the party that recovers a wrecked ship and its cargo. This runtime does the same for
4//! a crashed agent run: every run is an append-only event log, so a process killed mid-step resumes
5//! exactly where it stopped, with no repeated side effects.
6//!
7//! This crate is a facade. It holds no logic of its own; it re-exports the `salvor-*` family so one
8//! dependency covers the library. Everything here is equally reachable by depending on the
9//! individual crates, which is the better choice when you want a narrow build.
10//!
11//! # What the default features give you
12//!
13//! The agent loop ([`runtime`]), the tool contract ([`tools`]), the SQLite event store ([`store`]),
14//! and the event model and replay engine ([`core`]). That is the set needed to define an agent, run
15//! it, kill it, and resume it.
16//!
17//! # What is optional
18//!
19//! Each of these is off by default, because each pulls a dependency tree worth opting into
20//! deliberately:
21//!
22//! - `graph`: the declarative graph document format and its validator.
23//! - `engine`: the walker that executes a graph document. Implies `graph`.
24//! - `server`: the HTTP and server-sent-events control plane.
25//! - `llm`: the Messages API client, for talking to a model directly.
26//! - `wasm`: sandboxed WebAssembly component tools. Heavy, since it builds wasmtime.
27//! - `mcp`: Model Context Protocol tools, forwarded to `salvor-tools`.
28//!
29//! # Versioning
30//!
31//! Every re-exported crate is pinned to this crate's exact version, so upgrading `salvor` moves the
32//! whole family together and cannot mix versions that were never tested against each other.
33
34#![forbid(unsafe_code)]
35#![warn(missing_docs)]
36
37/// The event model, replay cursor, and state fold: the durability engine's core.
38///
39/// Re-export of `salvor-core`. Pure and IO-free, which is also why it compiles to wasm for a
40/// browser that wants to fold a log itself.
41pub mod core {
42    pub use salvor_core::*;
43}
44
45/// The agent loop, budgets, and the deterministic run context.
46///
47/// Re-export of `salvor-runtime`. This is the IO edge: the part that calls a model, records what it
48/// did, and enforces the ceilings. Requires the `runtime` feature, on by default.
49#[cfg(feature = "runtime")]
50pub mod runtime {
51    pub use salvor_runtime::*;
52}
53
54/// The tool contract: effect classification, typed handlers, and the `#[derive(Tool)]` macro.
55///
56/// Re-export of `salvor-tools`. Requires the `tools` feature, on by default.
57#[cfg(feature = "tools")]
58pub mod tools {
59    pub use salvor_tools::*;
60}
61
62/// The event store trait and its SQLite implementation.
63///
64/// Re-export of `salvor-store`. Requires the `store` feature, on by default.
65#[cfg(feature = "store")]
66pub mod store {
67    pub use salvor_store::*;
68}
69
70/// The declarative graph document format and its validator.
71///
72/// Re-export of `salvor-graph`. Requires the `graph` feature.
73#[cfg(feature = "graph")]
74pub mod graph {
75    pub use salvor_graph::*;
76}
77
78/// The walker that executes a graph document: linear chains, gates, branches, maps, and forks.
79///
80/// Re-export of `salvor-engine`. Requires the `engine` feature.
81#[cfg(feature = "engine")]
82pub mod engine {
83    pub use salvor_engine::*;
84}
85
86/// The HTTP and server-sent-events control plane over the durable runtime.
87///
88/// Re-export of `salvor-server`. Requires the `server` feature.
89#[cfg(feature = "server")]
90pub mod server {
91    pub use salvor_server::*;
92}
93
94/// The Messages API client, for hosted and local model endpoints.
95///
96/// Re-export of `salvor-llm`. Requires the `llm` feature.
97#[cfg(feature = "llm")]
98pub mod llm {
99    pub use salvor_llm::*;
100}
101
102/// Sandboxed WebAssembly component tools, run under wasmtime with WASI capabilities denied.
103///
104/// Re-export of `salvor-wasm`. Requires the `wasm` feature.
105#[cfg(feature = "wasm")]
106pub mod wasm {
107    pub use salvor_wasm::*;
108}
109
110/// The handful of names most programs want, in one import.
111///
112/// Deliberately small: enough to define an agent, give it tools, run it against a store, and read
113/// the outcome. Anything more specific is one module path away.
114pub mod prelude {
115    // Each group follows its own feature: a narrow build gets a smaller prelude rather than a
116    // compile error, so `default-features = false` stays usable instead of merely legal.
117    pub use crate::core::{Event, EventEnvelope, RunId, RunState, RunStatus, derive_state};
118    #[cfg(feature = "runtime")]
119    pub use crate::runtime::{Agent, ParkReason, RunOutcome, Runtime, RuntimeError};
120    #[cfg(feature = "store")]
121    pub use crate::store::{EventStore, SqliteStore, StoreError};
122    #[cfg(feature = "tools")]
123    pub use crate::tools::{Effect, Tool, ToolCtx, ToolHandler, ToolOutcome};
124}
salvor/lib.rs

salvor/
lib.rs
