everruns_runtime/
lib.rs

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

everruns_runtime/
lib.rs
