Skip to main content

odori_engine/
lib.rs

1//! The durable-execution substrate: worker bootstrap over an embedded
2//! tokeira engine (or any Temporal-contract endpoint).
3//!
4//! This crate owns everything between "the user calls run" and "a workflow
5//! task executes": connecting the Temporal Rust SDK 0.7 client, building
6//! the worker with `odori-agents`' run-loop workflow and turn activities
7//! registered, and running it to shutdown.
8//!
9//! ## The embedded transport
10//!
11//! The embedded tokeira engine (`tokeira-engine` in the engine repo)
12//! exposes an in-process RPC endpoint consumed through
13//! `ConnectionOptions::service_override` — an in-memory duplex with no TCP
14//! listener and no port. `service_override` accepts the **SDK's own**
15//! callback-service type, so this crate depends only on SDK types: the
16//! [`Engine`] owns that engine and hands its service override to
17//! [`ConnectTarget::ServiceOverride`]. The same bootstrap drives an
18//! external tokeirad or Temporal server via [`ConnectTarget::Url`], which
19//! is also how the integration harness proves both paths.
20//!
21//! ```rust,ignore
22//! let engine = Engine::start_with_embedded_config(EmbeddedEngineConfig::default()).await?;
23//! let odori = OdoriRuntime::builder("my-app")
24//!     .connect(ConnectTarget::service_override(engine.service_override()))
25//!     .agents(registry)
26//!     .providers(providers)
27//!     .start()
28//!     .await?;
29//! let result: String = odori.runner().run("assistant", "hello", "run-1").await?;
30//! ```
31
32use std::{
33    fmt,
34    sync::Arc,
35    time::{Duration, Instant},
36};
37
38use anyhow::Context as _;
39use odori_agents::{
40    AgentRegistry, Providers, Runner, TurnActivities, register_odori, run::ToolActivities,
41};
42use temporalio_client::{
43    Client, ClientOptions, Connection, ConnectionOptions, Url,
44    callback_based::CallbackBasedGrpcService,
45};
46use temporalio_sdk::{Runtime, Worker, WorkerOptions};
47
48pub use tokeira_config::{
49    DsqlMigrationPolicy, EmbeddedConfigError, EmbeddedDsqlLimits, EmbeddedEngineConfig,
50    EmbeddedStorageConfig, EmbeddedValidationError, ExistingEmbeddedDsqlConfig,
51    ManagedClusterIntent, ManagedEmbeddedDsqlConfig, SnapshotPolicyConfig, TokeiraConfig,
52};
53pub use tokeira_engine::{
54    ClusterStartupReport, EmbeddedEngineShutdownError, EmbeddedEngineStartError,
55    EmbeddedShutdownFailure, EmbeddedStartupPhase, EmbeddedStorageMode, EngineStartupReport,
56    OwnershipStartupReport, SchemaStartupOutcome, SchemaStartupReport,
57};
58
59/// Odori's owner for an embedded Tokeira engine.
60///
61/// The wrapper deliberately accepts E1's configuration types and returns E1's
62/// typed startup and shutdown failures unchanged. In particular, a rejected
63/// DSQL configuration cannot turn into an in-memory engine here.
64#[derive(Debug)]
65pub struct Engine {
66    inner: tokeira_engine::Engine,
67    startup_elapsed: Duration,
68}
69
70impl Engine {
71    /// Start an embedded engine in the explicitly selected storage mode.
72    ///
73    /// [`EmbeddedStorageConfig::InMemory`] also honors the snapshot policy in
74    /// [`TokeiraConfig`]. Managed and existing DSQL modes preserve the engine's
75    /// validation, lifecycle, migration, and never-fallback semantics.
76    pub async fn start_with_embedded_config(
77        config: EmbeddedEngineConfig,
78    ) -> Result<Self, EmbeddedEngineStartError> {
79        let started_at = Instant::now();
80        let inner = tokeira_engine::Engine::start_with_embedded_config(config).await?;
81        Ok(Self {
82            inner,
83            startup_elapsed: started_at.elapsed(),
84        })
85    }
86
87    /// The engine's complete redacted cluster, schema, and ownership report.
88    pub fn startup_report(&self) -> &EngineStartupReport {
89        self.inner.startup_report()
90    }
91
92    /// Wall-clock time measured across the complete embedded startup call.
93    pub fn startup_elapsed(&self) -> Duration {
94        self.startup_elapsed
95    }
96
97    /// Adapt this engine to the Temporal SDK's in-process transport.
98    pub fn service_override(&self) -> CallbackBasedGrpcService {
99        self.inner.service_override()
100    }
101
102    /// Gracefully stop the engine, forwarding E1's typed cleanup result.
103    pub async fn shutdown(self) -> Result<(), EmbeddedEngineShutdownError> {
104        self.inner.shutdown().await
105    }
106}
107
108/// Where the worker and client connect.
109#[derive(Clone)]
110pub enum ConnectTarget {
111    /// In-process duplex to an embedded engine: the callback service from
112    /// [`Engine::service_override`] (or any implementation
113    /// of the SDK's callback service).
114    ServiceOverride(CallbackBasedGrpcService),
115    /// A network endpoint speaking the Temporal contract (tokeirad, or a
116    /// Temporal server).
117    Url(Url),
118}
119
120impl ConnectTarget {
121    /// Wrap an engine's service override.
122    pub fn service_override(service: CallbackBasedGrpcService) -> Self {
123        ConnectTarget::ServiceOverride(service)
124    }
125}
126
127impl fmt::Debug for ConnectTarget {
128    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
129        match self {
130            ConnectTarget::ServiceOverride(_) => f.write_str("ConnectTarget::ServiceOverride"),
131            ConnectTarget::Url(url) => f.debug_tuple("ConnectTarget::Url").field(url).finish(),
132        }
133    }
134}
135
136/// Builder for [`OdoriRuntime`].
137#[derive(Debug)]
138pub struct OdoriRuntimeBuilder {
139    task_queue: String,
140    namespace: String,
141    target: Option<ConnectTarget>,
142    registry: AgentRegistry,
143    providers: Option<Providers>,
144    #[cfg(feature = "preview")]
145    bridge: Option<odori_mcp_bridge::BridgeConfig>,
146}
147
148impl OdoriRuntimeBuilder {
149    /// The registered agents, replacing any prior set.
150    pub fn agents(mut self, registry: AgentRegistry) -> Self {
151        self.registry = registry;
152        self
153    }
154
155    /// The provider set turns execute through.
156    pub fn providers(mut self, providers: Providers) -> Self {
157        self.providers = Some(providers);
158        self
159    }
160
161    /// Where to connect (required).
162    pub fn connect(mut self, target: ConnectTarget) -> Self {
163        self.target = Some(target);
164        self
165    }
166
167    /// Override the namespace (default: `"default"`).
168    pub fn namespace(mut self, namespace: impl Into<String>) -> Self {
169        self.namespace = namespace.into();
170        self
171    }
172
173    /// Enable the mcp-bridge for this runtime: framework tools execute as
174    /// durable activities reachable mid-turn.
175    #[cfg(feature = "preview")]
176    pub fn bridge(mut self, config: odori_mcp_bridge::BridgeConfig) -> Self {
177        self.bridge = Some(config);
178        self
179    }
180
181    /// Connect, assemble the worker, and start it on the current tokio
182    /// runtime.
183    pub async fn start(self) -> anyhow::Result<OdoriRuntime> {
184        let target = self.target.context("ConnectTarget is required")?;
185        let providers = self.providers.context("a provider set is required")?;
186
187        // The URL is only an SDK configuration value when service_override
188        // is present; no DNS lookup or listener is involved (engine-repo
189        // tokeira-engine README).
190        let connection_options = match target {
191            ConnectTarget::ServiceOverride(service) => ConnectionOptions::new(
192                Url::parse("http://odori-embedded.invalid:7233")
193                    .context("static embedded URL must parse")?,
194            )
195            .service_override(service)
196            .dns_load_balancing(None)
197            .build(),
198            ConnectTarget::Url(url) => ConnectionOptions::new(url).build(),
199        };
200        let connection = Connection::connect(connection_options)
201            .await
202            .context("connect the Temporal Rust SDK client")?;
203        let client = Client::new(connection, ClientOptions::new(self.namespace).build())
204            .context("construct the SDK client")?;
205
206        let registry = Arc::new(self.registry);
207        #[allow(unused_mut)]
208        let mut activities = TurnActivities::new(registry.clone(), providers);
209        #[allow(unused_mut)]
210        let mut tool_activities = ToolActivities::new(registry.clone());
211        #[cfg(feature = "preview")]
212        let bridge = match self.bridge {
213            Some(config) => {
214                tool_activities = tool_activities.with_max_result_bytes(config.max_result_bytes);
215                let bridge = odori_mcp_bridge::Bridge::start(
216                    registry.clone(),
217                    Arc::new(odori_mcp_bridge::WorkflowUpdateClient::new(client.clone())),
218                    config,
219                )
220                .await
221                .context("start the mcp-bridge server")?;
222                activities = activities.with_attachments(Arc::new(bridge.clone()));
223                Some(bridge)
224            }
225            None => None,
226        };
227        let _ = &registry;
228
229        // Workflow futures are deliberately !Send, so the worker cannot run
230        // on a multi-threaded tokio executor. It gets its own OS thread with
231        // a current-thread runtime; the client (Send) is shared with it, and
232        // the shutdown handle comes back over a oneshot.
233        let (ready_sender, ready_receiver) = tokio::sync::oneshot::channel();
234        let worker_client = client.clone();
235        let worker_queue = self.task_queue.clone();
236        let worker_thread = std::thread::Builder::new()
237            .name("odori-worker".to_owned())
238            .spawn(move || -> anyhow::Result<()> {
239                let local = tokio::runtime::Builder::new_current_thread()
240                    .enable_all()
241                    .build()
242                    .context("build the worker thread's runtime")?;
243                local.block_on(async move {
244                    let runtime = Runtime::from_current_tokio(Default::default())
245                        .context("assemble the SDK runtime")?;
246                    let worker_options = register_odori(
247                        WorkerOptions::new(worker_queue),
248                        activities,
249                        tool_activities,
250                    )
251                    .context("register the Odori workflow and activities")?
252                    .build();
253                    let mut worker = Worker::new(&runtime, worker_client, worker_options)
254                        .context("construct the SDK worker")?;
255                    let shutdown: Box<dyn Fn() + Send + Sync> = Box::new(worker.shutdown_handle());
256                    if ready_sender.send(shutdown).is_err() {
257                        // The starter gave up; nothing to serve.
258                        return Ok(());
259                    }
260                    worker.run().await.context("run the SDK worker")
261                })
262            })
263            .context("spawn the worker thread")?;
264        let shutdown = ready_receiver
265            .await
266            .context("worker thread ended before signalling readiness")?;
267
268        Ok(OdoriRuntime {
269            client,
270            task_queue: self.task_queue,
271            shutdown: Some(shutdown),
272            worker_thread: Some(worker_thread),
273            #[cfg(feature = "preview")]
274            bridge,
275        })
276    }
277}
278
279/// A running Odori worker plus the client surface against it.
280pub struct OdoriRuntime {
281    client: Client,
282    task_queue: String,
283    shutdown: Option<Box<dyn Fn() + Send + Sync>>,
284    worker_thread: Option<std::thread::JoinHandle<anyhow::Result<()>>>,
285    #[cfg(feature = "preview")]
286    bridge: Option<odori_mcp_bridge::Bridge>,
287}
288
289impl fmt::Debug for OdoriRuntime {
290    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
291        f.debug_struct("OdoriRuntime")
292            .field("task_queue", &self.task_queue)
293            .finish_non_exhaustive()
294    }
295}
296
297impl OdoriRuntime {
298    /// Start assembling a runtime submitting to `task_queue`.
299    pub fn builder(task_queue: impl Into<String>) -> OdoriRuntimeBuilder {
300        OdoriRuntimeBuilder {
301            task_queue: task_queue.into(),
302            namespace: "default".to_owned(),
303            target: None,
304            registry: AgentRegistry::new(),
305            providers: None,
306            #[cfg(feature = "preview")]
307            bridge: None,
308        }
309    }
310
311    /// A runner bound to this runtime's task queue.
312    pub fn runner(&self) -> Runner {
313        Runner::new(self.client.clone(), self.task_queue.clone())
314    }
315
316    /// The underlying SDK client, for surfaces the runner does not wrap.
317    pub fn client(&self) -> Client {
318        self.client.clone()
319    }
320
321    /// The bridge endpoint URL, when the bridge is enabled.
322    #[cfg(feature = "preview")]
323    pub fn bridge_url(&self) -> Option<&str> {
324        self.bridge.as_ref().map(|bridge| bridge.url())
325    }
326
327    /// Stop the worker and await its drain.
328    pub async fn shutdown(mut self) -> anyhow::Result<()> {
329        if let Some(shutdown) = self.shutdown.take() {
330            shutdown();
331        }
332        if let Some(thread) = self.worker_thread.take() {
333            tokio::task::spawn_blocking(move || {
334                thread
335                    .join()
336                    .map_err(|_| anyhow::anyhow!("worker thread panicked"))?
337            })
338            .await
339            .context("join the worker thread")??;
340        }
341        Ok(())
342    }
343}