Skip to main content

stasis/
lib.rs

1//! Stasis is a durable AI orchestration framework with runtime jobs, control-plane
2//! primitives, and memory integration adapters.
3//! Use the [prelude] module for a batteries-included public API surface.
4
5// `async_trait` marks the generated method `#[must_use]` and the boxed future
6// is already `#[must_use]`. Clippy reports that pair on every async trait method.
7#![allow(clippy::double_must_use)]
8
9#[cfg(all(target_arch = "wasm32", feature = "native"))]
10compile_error!(
11    "the `native` feature (default) is not supported on wasm32; build with `--no-default-features`"
12);
13
14#[cfg(all(target_arch = "wasm32", feature = "surreal-native"))]
15compile_error!(
16    "`surreal-native` is not supported on wasm32; use `--features surreal-ws` for remote `wss://`"
17);
18
19pub mod application;
20#[cfg(feature = "dashboard")]
21pub mod dashboard;
22pub mod domain;
23pub mod infrastructure;
24pub mod ports;
25pub mod sdk;
26
27pub use stasis_macros::stasis_tool;
28
29#[doc(hidden)]
30pub mod macro_support {
31    pub use async_trait;
32    pub use schemars;
33    pub use serde;
34    pub use serde_json;
35}
36
37/// Minimal runtime imports for consumers integrating job handlers and runtime wiring.
38///
39/// `JobConsumer::on_lifecycle` receives [`JobLifecycleEvent`] after each persisted
40/// transition so app-level pending/finishing status can roll back on defer, retry,
41/// cancel, or dead-letter.
42pub mod runtime_prelude {
43    pub use crate::application::runtime::in_memory_runtime::{
44        InMemoryRuntime, JobExecutionOutcome, JobHandler,
45    };
46    pub use crate::application::runtime::inbound_trigger::decode_inbound_json;
47    pub use crate::application::runtime::job_context::{JobConsumeError, JobContext, JobResult};
48    pub use crate::application::runtime::job_continuation::{
49        ContinuationBuilder, ContinuationReceipt,
50    };
51    pub use crate::application::runtime::job_lifecycle::{JobLifecycleEvent, StaleRecoverReport};
52    pub use crate::application::runtime::runtime_factory::{
53        RuntimeBackend, RuntimeComposition, RuntimeFactory, SurrealAuth,
54    };
55    pub use crate::application::runtime::stasis_runtime_builder::StasisRuntimeBuilder;
56    pub use crate::application::runtime::store_runtime::StoreRuntime;
57    pub use crate::application::runtime::typed_job::{
58        JobConsumer, TypedEnqueueBuilder, TypedJobHandler,
59    };
60    pub use crate::domain::errors::{Result, StasisError};
61    pub use crate::domain::runtime::inbound_trigger::{
62        InboundAccept, InboundDisposition, InboundProtocol,
63    };
64    pub use crate::domain::runtime::job::{BackoffPolicy, JobState, NewJob};
65    pub use crate::domain::runtime::job_continuation::ContinuationTrigger;
66    pub use crate::domain::runtime::placement::{PlacementConstraints, WorkerCapabilities};
67    pub use crate::domain::runtime::provenance::{
68        ProvenanceRef, ProvenanceScheme, SttpProvenanceAdapter,
69    };
70    pub use crate::domain::runtime::recurring::RecurringDefinition;
71    pub use crate::domain::runtime::resource_lease::{
72        FencingToken, OwnerId, ResourceKey, ResourceLease,
73    };
74    pub use crate::domain::runtime::typed_contract::{
75        JobDeclaration, RetryPolicy, StasisEvent, StasisJob,
76    };
77}
78
79/// Extended runtime imports including orchestration payloads, endpoint routing, and store adapters.
80pub mod runtime_prelude_ext {
81    pub use crate::application::dto::{
82        HeartbeatClusterNodeRequest, RegisterClusterNodeRequest, RegisterDeliveryEndpointRequest,
83    };
84    pub use crate::application::orchestration::runtime_job_payloads::{
85        AgentSessionJobPayload, AgentTurnJobPayload, ConcurrentPatternJobPayload,
86        HandoffPatternJobPayload, OrchestratorPatternJobPayload, PromptJobPayload,
87        SequentialPatternJobPayload, ToolLoopJobPayload,
88    };
89    pub use crate::application::orchestration::runtime_workflow_job_builder::RuntimeWorkflowJobBuilder;
90    pub use crate::application::runtime::in_memory_runtime::{
91        InMemoryRuntime, JobExecutionOutcome, JobHandler,
92    };
93    pub use crate::application::runtime::stasis_runtime_builder::StasisRuntimeBuilder;
94    pub use crate::domain::runtime::blob_descriptor::BlobDescriptor;
95    pub use crate::domain::runtime::cluster_node::ClusterNodeRole;
96    pub use crate::domain::runtime::delivery_endpoint::{
97        DeliveryEndpoint, DeliveryProtocol, NewDeliveryEndpoint,
98    };
99    pub use crate::domain::runtime::federation::{
100        FederatedSignalEnvelope, FederatedTerminalResult, sign_federated_signal,
101        sign_federated_terminal_result, verify_federated_signal, verify_federated_terminal_result,
102    };
103    pub use crate::domain::runtime::outbox::OutboxEvent;
104    pub use crate::domain::runtime::placement::{PlacementConstraints, WorkerCapabilities};
105    pub use crate::domain::runtime::provenance::{ProvenanceRef, SttpProvenanceAdapter};
106    pub use crate::domain::runtime::remote_job_envelope::{
107        OriginAuthority, RemoteJobEnvelope, TerminalDeliveryEndpoint, sign_remote_job_envelope,
108        verify_remote_job_envelope,
109    };
110    pub use crate::infrastructure::runtime::composite_control_plane_store::CompositeControlPlaneStore;
111    pub use crate::infrastructure::runtime::endpoint_routing_event_publisher::EndpointRoutingEventPublisher;
112    #[cfg(any(not(target_arch = "wasm32"), feature = "http-wasm"))]
113    pub use crate::infrastructure::runtime::http_cluster_command_forwarder::HttpClusterCommandForwarder;
114    #[cfg(any(not(target_arch = "wasm32"), feature = "http-wasm"))]
115    pub use crate::infrastructure::runtime::http_webhook_event_publisher::{
116        HttpWebhookEventPublisher, HttpWebhookTransportPublisher,
117    };
118    pub use crate::infrastructure::runtime::in_memory_blob_transfer::InMemoryBlobTransfer;
119    pub use crate::infrastructure::runtime::in_memory_cluster_node_store::InMemoryClusterNodeStore;
120    pub use crate::infrastructure::runtime::in_memory_delivery_endpoint_store::InMemoryDeliveryEndpointStore;
121    pub use crate::infrastructure::runtime::in_memory_endpoint_delivery_status_store::InMemoryEndpointDeliveryStatusStore;
122    pub use crate::infrastructure::runtime::in_memory_federated_bus::InMemoryFederatedBus;
123    pub use crate::infrastructure::runtime::in_memory_ownership_handoff_store::InMemoryOwnershipHandoffStore;
124    #[cfg(feature = "surreal")]
125    pub use crate::infrastructure::runtime::surreal_cluster_node_store::SurrealClusterNodeStore;
126    #[cfg(feature = "surreal")]
127    pub use crate::infrastructure::runtime::surreal_delivery_endpoint_store::SurrealDeliveryEndpointStore;
128    #[cfg(feature = "surreal")]
129    pub use crate::infrastructure::runtime::surreal_endpoint_delivery_status_store::SurrealEndpointDeliveryStatusStore;
130    pub use crate::ports::outbound::runtime::blob_transfer::BlobTransferPort;
131    pub use crate::ports::outbound::runtime::delivery_endpoint_store::DeliveryEndpointStore;
132    pub use crate::ports::outbound::runtime::endpoint_delivery_status_store::EndpointDeliveryStatusStore;
133    pub use crate::ports::outbound::runtime::endpoint_transport_publisher::EndpointTransportPublisher;
134    pub use crate::ports::outbound::runtime::federated_delivery::{
135        FederatedDeliveryPort, FederatedIngressPort,
136    };
137    pub use crate::ports::outbound::runtime::ownership_handoff_store::{
138        OwnershipHandoffStore, ReserveOwnershipHandoff,
139    };
140}
141
142/// Minimal memory imports for consumers using context store/recall/transform APIs.
143pub mod memory_prelude {
144    pub use crate::ports::outbound::memory::memory_models::{
145        MemoryAggregateRequest, MemoryRecallRequest, MemoryReflexRequest, MemoryReflexResponse,
146        MemoryRollupRequest, MemoryScope, MemoryStoreRequest, MemoryTransformRequest,
147    };
148    pub use crate::ports::outbound::memory::memory_operations::MemoryOperations;
149}
150
151/// Extended memory imports including concrete Locus adapters and context reader/writer traits.
152pub mod memory_prelude_ext {
153    pub use crate::infrastructure::memory::locus_context_reader::LocusContextReader;
154    pub use crate::infrastructure::memory::locus_context_writer::LocusContextWriter;
155    pub use crate::infrastructure::memory::locus_memory_operations::LocusMemoryOperations;
156    pub use crate::infrastructure::memory::locus_node_store_factory::{
157        LocusMemoryStore, LocusNodeStoreFactory,
158    };
159    pub use crate::ports::outbound::memory::memory_context_reader::MemoryContextReader;
160    pub use crate::ports::outbound::memory::memory_context_writer::MemoryContextWriter;
161    pub use crate::ports::outbound::memory::memory_models::{
162        MemoryAggregateRequest, MemoryRecallRequest, MemoryReflexRequest, MemoryReflexResponse,
163        MemoryRollupRequest, MemoryScope, MemoryStoreRequest, MemoryTransformRequest,
164    };
165    pub use crate::ports::outbound::memory::memory_operations::MemoryOperations;
166}
167
168/// Minimal SDK imports for common external consumers.
169pub mod sdk_prelude {
170    pub use crate::application::dto::{InvokeAgentRequest, RegisterAgentRequest};
171    pub use crate::application::runtime::runtime_factory::{
172        RuntimeBackend, RuntimeFactory, SurrealAuth,
173    };
174    pub use crate::domain::errors::{Result, StasisError};
175    pub use crate::domain::runtime::job::{BackoffPolicy, NewJob};
176    #[cfg(feature = "llm-chat")]
177    pub use crate::infrastructure::llm::mock_chat_client::MockAiChatClient;
178    pub use crate::infrastructure::llm::mock_gateway::MockLlmGateway;
179    pub use crate::infrastructure::persistence::in_memory_agent_repository::InMemoryAgentRepository;
180    pub use crate::sdk::runtime_sdk::{RuntimeSdk, StasisRuntime};
181    pub use crate::sdk::stasis_sdk::StasisSdk;
182}
183
184/// Extended SDK imports including control-plane and provider-specific integration types.
185pub mod sdk_prelude_ext {
186    pub use crate::application::dto::InvokeAgentResponse;
187    pub use crate::application::runtime::runtime_factory::RuntimeComposition;
188    pub use crate::domain::runtime::job::JobState;
189    pub use crate::domain::runtime::recurring::RecurringDefinition;
190    #[cfg(feature = "llm-genai")]
191    pub use crate::infrastructure::llm::genai_gateway::GenaiLlmGateway;
192    #[cfg(feature = "llm-chat")]
193    pub use crate::infrastructure::llm::mock_chat_client::MockAiChatClient;
194    #[cfg(all(feature = "llm-openai-http", not(feature = "llm-genai")))]
195    pub use crate::infrastructure::llm::openai_http_chat_client::OpenAiHttpChatClient;
196    #[cfg(feature = "llm-openai-http")]
197    pub use crate::infrastructure::llm::openai_http_gateway::OpenAiHttpGateway;
198    pub use crate::sdk::control_plane_sdk::ControlPlaneSdk;
199    pub use crate::sdk::runtime_sdk::RuntimeStatsSnapshot;
200}
201
202/// Re-exported minimal public API surface for common Stasis consumers.
203pub mod prelude {
204    pub use crate::memory_prelude::*;
205    pub use crate::runtime_prelude::*;
206    pub use crate::sdk_prelude::*;
207}
208
209/// Environment and secrets configuration helpers.
210pub mod config_prelude {
211    #[cfg(feature = "env-fs")]
212    pub use crate::application::config::env::load_dotenv_from;
213    pub use crate::application::config::env::{
214        EnvBootstrapOptions, EnvBootstrapReport, EnvError, bootstrap, bootstrap_with,
215        first_non_empty, non_empty, required, truthy, with_default,
216    };
217    pub use crate::application::config::secrets::{
218        ChainedSecretsSource, FileSecretsSource, OsEnvSource, SecretsSource, default_secrets_dir,
219    };
220}
221
222/// OpenTelemetry contract keys, span names, and runtime telemetry ports.
223pub mod telemetry_prelude {
224    pub use crate::application::telemetry::keys;
225    pub use crate::application::telemetry::operation::OperationTelemetry;
226    pub use crate::application::telemetry::propagation::{
227        TracePropagationMode, generate_w3c_trace_id, is_w3c_trace_id, job_execute_span_attributes,
228        parent_trace_context, parse_traceparent, trace_propagation_mode,
229    };
230    pub use crate::application::telemetry::request_context::{
231        inbound_trace_context, inbound_trace_context_for_propagation, scope_inbound_trace,
232        trace_id_for_enqueue,
233    };
234    pub use crate::application::telemetry::spans;
235    pub use crate::infrastructure::telemetry::{NoopRuntimeTelemetry, NoopRuntimeTracing};
236    pub use crate::ports::outbound::runtime::runtime_metrics::RuntimeMetrics;
237    pub use crate::ports::outbound::runtime::runtime_telemetry::RuntimeTelemetry;
238    pub use crate::ports::outbound::runtime::runtime_tracing::{
239        OtelAttribute, OtelAttributeValue, RuntimeTracing, SpanGuard, TraceContext, in_span,
240    };
241
242    #[cfg(feature = "otel")]
243    pub use crate::infrastructure::telemetry::OpenTelemetryTelemetry;
244}
245
246/// Re-exported extended API surface for advanced integrations.
247pub mod prelude_ext {
248    pub use crate::config_prelude::*;
249    pub use crate::memory_prelude_ext::*;
250    pub use crate::runtime_prelude_ext::*;
251    pub use crate::sdk_prelude_ext::*;
252}
253
254#[cfg(test)]
255mod tests {
256    use crate::application::dto::{InvokeAgentRequest, RegisterAgentRequest};
257    use crate::infrastructure::llm::mock_gateway::MockLlmGateway;
258    use crate::infrastructure::persistence::in_memory_agent_repository::InMemoryAgentRepository;
259    use crate::sdk::stasis_sdk::StasisSdk;
260
261    #[tokio::test]
262    async fn end_to_end_agent_registration_and_invocation_works() {
263        let repository = InMemoryAgentRepository::default();
264        let llm = MockLlmGateway::new("mock completion");
265        let sdk = StasisSdk::new(repository, llm);
266
267        let registration = RegisterAgentRequest {
268            id: "planner".to_string(),
269            name: "Task Planner".to_string(),
270            system_prompt: "Break work down into ordered steps".to_string(),
271        };
272
273        sdk.register_agent(registration)
274            .await
275            .expect("agent should register");
276
277        let response = sdk
278            .invoke_agent(InvokeAgentRequest {
279                agent_id: "planner".to_string(),
280                user_prompt: "Plan a release checklist".to_string(),
281            })
282            .await
283            .expect("agent should invoke");
284
285        assert_eq!(response.completion, "mock completion");
286    }
287}