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//! `InProcessRuntimeBuilder::new()` starts from a runtime-safe built-in
19//! capability registry. Hosted Everruns product capabilities and capabilities
20//! that require optional host backends can still be enabled by supplying an
21//! explicit [`PlatformDefinition`](everruns_core::PlatformDefinition).
22//!
23//! For a runnable example, see:
24//!
25//! ```text
26//! cargo run -p everruns-runtime --example in_process_runtime
27//! cargo run -p everruns-runtime --example inspect_context
28//! ```
29//!
30//! # Example
31//!
32//! ```
33//! # #[tokio::main]
34//! # async fn main() -> Result<(), everruns_core::AgentLoopError> {
35//! use everruns_core::{
36//!     CapabilityRegistry, DriverRegistry, InputMessage, DriverId, ResolvedModel,
37//!     PlatformDefinition,
38//! };
39//! use everruns_core::capabilities::TestMathCapability;
40//! use everruns_runtime::InProcessRuntimeBuilder;
41//!
42//! let mut capabilities = CapabilityRegistry::new();
43//! capabilities.register(TestMathCapability);
44//!
45//! let platform = PlatformDefinition::new(capabilities, DriverRegistry::new());
46//!
47//! let runtime = InProcessRuntimeBuilder::new()
48//!     .platform_definition(platform)
49//!     .single_session(|s| {
50//!         s.harness("math", "You are a calculator.")
51//!             .harness_display_name("Math")
52//!             .with_capability("test_math")
53//!             .agent("math-agent", "Use tools when needed.")
54//!             .agent_display_name("Math Agent")
55//!             .agent_max_iterations(8)
56//!             .session_title("Math Session")
57//!     })
58//!     .llm_sim(everruns_core::llmsim_driver::LlmSimConfig::fixed("4"))
59//!     .default_model(ResolvedModel {
60//!         model: "llmsim-model".into(),
61//!         provider_type: DriverId::LlmSim,
62//!         api_key: Some("fake-key".into()),
63//!         base_url: None,
64//!         provider_metadata: None,
65//!     })
66//!     .build()
67//!     .await?;
68//!
69//! let session_id = runtime.default_session_id().expect("single_session id");
70//! let result = runtime
71//!     .run_turn(
72//!         session_id,
73//!         InputMessage::user("What is 2 + 2?"),
74//!     )
75//!     .await?;
76//! assert!(result.success);
77//! # Ok(())
78//! # }
79//! ```
80//!
81//! # Real-disk workspace
82//!
83//! Embedders who want built-in capabilities (`file_system`,
84//! `agent_instructions`, `skills`, ...) to read and write a real directory
85//! on disk can configure [`RealDiskSessionFileSystemFactory`] on their
86//! [`PlatformDefinition`](everruns_core::PlatformDefinition). Every capability that goes through
87//! `ToolContext.file_store` or `SystemPromptContext.file_store` picks it up
88//! automatically.
89//!
90//! See the runnable examples for the full wiring:
91//!
92//! ```text
93//! cargo run -p everruns-runtime --example real_disk_agent_instructions
94//! cargo run -p everruns-runtime --example real_disk_file_system_tools
95//! ```
96//!
97//! And `specs/file-store.md` for the trait contract.
98
99mod backends;
100mod builders;
101mod file_store_decorators;
102mod host;
103mod in_memory;
104mod mcp;
105mod mcp_cache;
106mod real_disk;
107mod runtime;
108mod turn_strategy;
109
110pub use backends::{
111    EventBus, PlatformStoreFactory, RuntimeAgentStore, RuntimeBackends, RuntimeHarnessStore,
112    RuntimeMessageStore, RuntimeProviderStore, RuntimeSessionStore, ScheduleStoreFactory,
113};
114pub use builders::{AgentBuilder, HarnessBuilder, SessionBuilder, SingleSessionBuilder};
115pub use everruns_core::AssembledTurnContext;
116// Embeddable in-process task-transition observation (EVE-729): embedders
117// implement `TaskTransitionObserver` to receive task lifecycle transitions
118// (terminal / awaiting_input / outbound message) in process, with the same
119// filter semantics as server webhook delivery but without HTTP.
120pub use everruns_core::task_observer::{TaskTransition, TaskTransitionObserver};
121pub use file_store_decorators::{
122    ApprovalGatingFileStore, DEFAULT_WRITE_BLOCKLIST, FileApprovalGate, WriteBlocklistFileStore,
123};
124pub use host::{
125    RuntimeHostAdapter, RuntimeHostTurnContext, RuntimeSessionLifecycle, detect_dependency_blocker,
126    execute_act_activity, execute_input_activity, execute_reason_activity,
127};
128pub use in_memory::{
129    InMemorySessionFileStore, InMemorySessionFileSystemFactory, InMemorySessionStorageStore,
130    InMemorySessionStore,
131};
132pub use real_disk::{RealDiskFileStore, RealDiskSessionFileSystemFactory, multi_root_file_system};
133pub use runtime::{
134    InProcessRuntime, InProcessRuntimeBuilder, TurnResult, in_process_internal_org_id,
135};
136pub use turn_strategy::{RuntimeActPlan, RuntimeTurnPlan, RuntimeTurnState, plan_next_host_turn};
everruns_runtime/lib.rs

everruns_runtime/
lib.rs
