everruns_runtime/
lib.rs

1//! Public in-process runtime for embedding Everruns.
2//!
3//! The runtime crate exposes an in-memory execution surface that runs the same
4//! core atoms (`input`, `reason`, `act`) used elsewhere in the system, but
5//! without the durable engine, gRPC worker boundary, or control-plane server.
6//! It is part of the [Everruns](https://everruns.com) ecosystem.
7//!
8//! This is the intended public entrypoint for embedders who want to:
9//!
10//! - run sessions in their own process
11//! - provide their own platform definition (capabilities, drivers, harnesses)
12//! - seed harnesses, agents, sessions, and workspace files directly in code
13//! - replace the default in-memory stores with custom runtime backends
14//! - inspect the assembled turn context before or after executing a turn
15//! - reuse runtime-owned host phase execution from durable or server-backed hosts
16//! - map `plan_next_host_turn(...)` onto their own queue, retry, or in-memory host
17//!
18//! For a runnable example, see:
19//!
20//! ```text
21//! cargo run -p everruns-runtime --example in_process_runtime
22//! cargo run -p everruns-runtime --example inspect_context
23//! ```
24//!
25//! # Example
26//!
27//! ```ignore
28//! use everruns_core::{
29//!     CapabilityRegistry, DriverRegistry, InputMessage, LlmProviderType, ModelWithProvider,
30//!     PlatformDefinition,
31//! };
32//! use everruns_core::capabilities::TestMathCapability;
33//! use everruns_runtime::InProcessRuntimeBuilder;
34//!
35//! let mut capabilities = CapabilityRegistry::new();
36//! capabilities.register(TestMathCapability);
37//!
38//! let platform = PlatformDefinition::new(capabilities, DriverRegistry::new());
39//!
40//! let runtime = InProcessRuntimeBuilder::new()
41//!     .platform_definition(platform)
42//!     .single_session(|s| {
43//!         s.harness("math", "You are a calculator.")
44//!             .harness_display_name("Math")
45//!             .with_capability("test_math")
46//!             .agent("math-agent", "Use tools when needed.")
47//!             .agent_display_name("Math Agent")
48//!             .agent_max_iterations(8)
49//!             .session_title("Math Session")
50//!     })
51//!     .llm_sim(everruns_core::llmsim_driver::LlmSimConfig::fixed("4"))
52//!     .default_model(ModelWithProvider {
53//!         model: "llmsim-model".into(),
54//!         provider_type: LlmProviderType::LlmSim,
55//!         api_key: Some("fake-key".into()),
56//!         base_url: None,
57//!     })
58//!     .build()
59//!     .await?;
60//!
61//! let session_id = runtime.default_session_id().expect("single_session id");
62//! let result = runtime
63//!     .run_turn(
64//!         session_id,
65//!         InputMessage::user("What is 2 + 2?"),
66//!     )
67//!     .await?;
68//! assert!(result.success);
69//! # Ok::<(), everruns_core::AgentLoopError>(())
70//! ```
71//!
72//! # Real-disk workspace
73//!
74//! Embedders who want built-in capabilities (`file_system`,
75//! `agent_instructions`, `skills`, ...) to read and write a real directory
76//! on disk can configure [`RealDiskSessionFileSystemFactory`] on their
77//! [`PlatformDefinition`](everruns_core::PlatformDefinition). Every capability that goes through
78//! `ToolContext.file_store` or `SystemPromptContext.file_store` picks it up
79//! automatically.
80//!
81//! See the runnable examples for the full wiring:
82//!
83//! ```text
84//! cargo run -p everruns-runtime --example real_disk_agent_instructions
85//! cargo run -p everruns-runtime --example real_disk_file_system_tools
86//! ```
87//!
88//! And `specs/file-store.md` for the trait contract.
89
90mod backends;
91mod builders;
92mod file_store_decorators;
93mod host;
94mod in_memory;
95mod real_disk;
96mod runtime;
97mod turn_strategy;
98
99pub use backends::{
100    EventBus, RuntimeAgentStore, RuntimeBackends, RuntimeHarnessStore, RuntimeMessageStore,
101    RuntimeProviderStore, RuntimeSessionStore,
102};
103pub use builders::{AgentBuilder, HarnessBuilder, SessionBuilder, SingleSessionBuilder};
104pub use everruns_core::AssembledTurnContext;
105pub use file_store_decorators::{
106    ApprovalGatingFileStore, DEFAULT_WRITE_BLOCKLIST, FileApprovalGate, WriteBlocklistFileStore,
107};
108pub use host::{
109    RuntimeHostAdapter, RuntimeHostTurnContext, RuntimeSessionLifecycle, detect_dependency_blocker,
110    execute_act_activity, execute_input_activity, execute_reason_activity,
111};
112pub use in_memory::{
113    InMemorySessionFileStore, InMemorySessionFileSystemFactory, InMemorySessionStorageStore,
114    InMemorySessionStore,
115};
116pub use real_disk::{RealDiskFileStore, RealDiskSessionFileSystemFactory};
117pub use runtime::{InProcessRuntime, InProcessRuntimeBuilder, TurnResult};
118pub use turn_strategy::{RuntimeActPlan, RuntimeTurnPlan, RuntimeTurnState, plan_next_host_turn};
everruns_runtime/lib.rs

everruns_runtime/
lib.rs
