Skip to main content

infinity_agent_core/system/local/
launch.rs

1//! Launching threads with their own tools and prompt.
2//!
3//! Build a local system, start it, and launch configured threads through
4//! [`LaunchingSystem::thread_builder`]. Each launched thread gets a generated
5//! ID and runs with the union of the system-wide configuration and the tools
6//! and prompt registered at launch.
7
8use rap_protocol::ThreadId;
9use std::cell::RefCell;
10use std::collections::HashMap;
11use std::rc::Rc;
12
13use async_trait::async_trait;
14
15use crate::tools::Tool;
16use crate::traits::{ConversationStore, InputSender, StateStore};
17use rap_client::http::HttpClient;
18
19use super::driver::ThreadLifecycleEvent;
20use super::handle::{HandleSubscribeRequest, ThreadHandle, attach, handle_observer_factory};
21use super::router::RunningSystem;
22use super::sender::ChannelSender;
23use crate::system::builder::{AgentSystem, LocalAgentSystem};
24use crate::system::config::{ThreadConfig, ThreadConfigSource};
25use crate::system::model::{ModelSource, ResolvedModel};
26
27type BoxError = Box<dyn std::error::Error + Send + Sync>;
28
29/// The tools, prompt, and model a thread was launched with.
30struct LaunchConfig<M: InputSender> {
31    tools: Vec<Rc<dyn Tool<M>>>,
32    extra_system_prompt: Option<String>,
33    model: Option<Rc<dyn ModelSource>>,
34}
35
36/// Per-thread launch configurations, shared between the running system's
37/// [`UnionConfigSource`] and the [`LaunchingSystem`] that registers entries.
38/// Lives (and dies) with the process: launch configurations are not
39/// persisted, so a thread resumed after a restart runs with the system-wide
40/// configuration only.
41#[derive(Clone)]
42pub(crate) struct LaunchRegistry<M: InputSender> {
43    threads: Rc<RefCell<HashMap<ThreadId, LaunchConfig<M>>>>,
44}
45
46impl<M: InputSender> Default for LaunchRegistry<M> {
47    fn default() -> Self {
48        Self {
49            threads: Rc::new(RefCell::new(HashMap::new())),
50        }
51    }
52}
53
54/// Resolve the root thread of `thread_id`. Launch configurations attach to
55/// the launched thread, which is always a root; subagent threads resolve to
56/// their root so they inherit its entry.
57async fn root_thread_id<C: ConversationStore>(
58    store: &C,
59    thread_id: &ThreadId<str>,
60) -> Result<ThreadId, BoxError> {
61    Ok(store
62        .get_ancestor_chain(thread_id)
63        .await
64        .map_err(|e| Box::new(e) as BoxError)?
65        .first()
66        .map(|(id, _)| id.clone())
67        .unwrap_or_else(|| thread_id.to_owned()))
68}
69
70/// Wraps the system-wide [`ModelSource`]: threads launched with their own
71/// model (and the subagent threads they spawn, via root resolution) resolve
72/// through it; all other threads fall through to the inner source.
73pub(crate) struct UnionModelSource<C: ConversationStore, M: InputSender> {
74    pub(crate) inner: Box<dyn ModelSource>,
75    pub(crate) registry: LaunchRegistry<M>,
76    pub(crate) conversation_store: C,
77}
78
79#[async_trait(?Send)]
80impl<C, M> ModelSource for UnionModelSource<C, M>
81where
82    C: ConversationStore + 'static,
83    M: InputSender + 'static,
84{
85    async fn resolve(&self, thread_id: &ThreadId<str>) -> Result<ResolvedModel, BoxError> {
86        let root_id = root_thread_id(&self.conversation_store, thread_id).await?;
87        let launched = self
88            .registry
89            .threads
90            .borrow()
91            .get(&root_id)
92            .and_then(|config| config.model.clone());
93        match launched {
94            Some(model) => model.resolve(thread_id).await,
95            None => self.inner.resolve(thread_id).await,
96        }
97    }
98}
99
100/// Wraps the system-wide [`ThreadConfigSource`], unioning each launched
101/// thread's registered tools and prompt on top of whatever the inner source
102/// resolves. Launch configurations attach to the launched (root) thread, so
103/// threads a launched thread spawns resolve their root's entry and inherit
104/// its tools and prompt. Threads whose root has no registry entry see the
105/// inner configuration unchanged.
106pub(crate) struct UnionConfigSource<C: ConversationStore, M: InputSender, H: HttpClient> {
107    pub(crate) inner: Box<dyn ThreadConfigSource<M, H>>,
108    pub(crate) registry: LaunchRegistry<M>,
109    pub(crate) conversation_store: C,
110}
111
112#[async_trait(?Send)]
113impl<C, M, H> ThreadConfigSource<M, H> for UnionConfigSource<C, M, H>
114where
115    C: ConversationStore + 'static,
116    M: InputSender + 'static,
117    H: HttpClient + 'static,
118{
119    async fn resolve(&self, thread_id: &ThreadId<str>) -> Result<ThreadConfig<M, H>, BoxError> {
120        let mut config = self.inner.resolve(thread_id).await?;
121        let root_id = root_thread_id(&self.conversation_store, thread_id).await?;
122        if let Some(local) = self.registry.threads.borrow().get(&root_id) {
123            config.tools.extend(local.tools.iter().cloned());
124            config.extra_system_prompt = match (
125                config.extra_system_prompt.take(),
126                local.extra_system_prompt.clone(),
127            ) {
128                (Some(system_wide), Some(local)) => Some(format!("{system_wide}\n\n{local}")),
129                (system_wide, local) => system_wide.or(local),
130            };
131        }
132        Ok(config)
133    }
134}
135
136impl<C, S, H> LocalAgentSystem<C, S, H>
137where
138    C: ConversationStore + 'static,
139    S: StateStore + 'static,
140    H: HttpClient + 'static,
141{
142    /// Run the system with the built-in thread-builder API: create threads
143    /// through [`LaunchingSystem::thread_builder`], and reattach to existing
144    /// threads with [`LaunchingSystem::thread_handle`].
145    pub fn start(self) -> LaunchingSystem<C, S, H> {
146        let registry = self.registry.clone();
147        let system = AgentSystem {
148            inner: self.system.inner.clone(),
149        };
150        let running = self.start_inner(handle_observer_factory());
151        LaunchingSystem {
152            system,
153            running,
154            registry,
155        }
156    }
157}
158
159/// A running local system whose threads are created through
160/// [`thread_builder`](Self::thread_builder), each with its own tools and
161/// prompt unioned onto the system-wide configuration. New threads cannot be
162/// created by attaching a handle: [`thread_handle`](Self::thread_handle) only
163/// reattaches to a thread that was launched or already exists in the store.
164pub struct LaunchingSystem<C, S, H>
165where
166    C: ConversationStore,
167    S: StateStore,
168    H: HttpClient,
169{
170    pub(crate) system: AgentSystem<C, S, ChannelSender, H>,
171    pub(crate) running: RunningSystem<HandleSubscribeRequest>,
172    pub(crate) registry: LaunchRegistry<ChannelSender>,
173}
174
175impl<C, S, H> LaunchingSystem<C, S, H>
176where
177    C: ConversationStore + 'static,
178    S: StateStore + 'static,
179    H: HttpClient + 'static,
180{
181    /// Start configuring a new thread. Finish with
182    /// [`ThreadBuilder::launch`].
183    pub fn thread_builder(&self) -> ThreadBuilder<'_, C, S, H> {
184        ThreadBuilder {
185            system: self,
186            tools: Vec::new(),
187            extra_system_prompt: None,
188            model: None,
189        }
190    }
191
192    /// Attach to an existing thread. Returns `Ok(None)` if the thread was not
193    /// launched in this process and does not exist in the conversation store.
194    /// New threads are created with [`thread_builder`](Self::thread_builder).
195    pub async fn thread_handle(
196        &self,
197        thread_id: &ThreadId<str>,
198    ) -> Result<Option<ThreadHandle>, C::Error> {
199        if !self.thread_exists(thread_id).await? {
200            return Ok(None);
201        }
202        Ok(Some(attach(&self.running, thread_id).await))
203    }
204
205    async fn thread_exists(&self, thread_id: &ThreadId<str>) -> Result<bool, C::Error> {
206        if self.registry.threads.borrow().contains_key(thread_id) {
207            return Ok(true);
208        }
209        self.system
210            .inner
211            .conversation_store
212            .thread_exists(thread_id)
213            .await
214    }
215
216    /// The system's [`InputSender`](crate::traits::InputSender), for callback
217    /// servers and any other external message injectors.
218    pub fn sender(&self) -> ChannelSender {
219        self.running.sender()
220    }
221
222    /// Wait for the next thread-driver lifecycle transition. See
223    /// [`RunningSystem::next_lifecycle_event`].
224    pub async fn next_lifecycle_event(&mut self) -> Option<ThreadLifecycleEvent> {
225        self.running.next_lifecycle_event().await
226    }
227
228    /// Whether no thread driver is currently live. Threads with active
229    /// subscriptions but no pending work do not count as live; their events
230    /// respawn a driver when they arrive.
231    pub fn is_idle(&self) -> bool {
232        self.running.is_idle()
233    }
234
235    /// Wind the whole system down (process exit): every driver flushes its
236    /// in-flight turn and exits; resolves when the wind-down is complete.
237    pub async fn shutdown(self) {
238        self.running.shutdown().await;
239    }
240}
241
242/// Configures and launches one new thread on a [`LaunchingSystem`]. The
243/// thread's ID is generated at [`launch`](Self::launch); the registered tools
244/// and prompt are unioned onto the system-wide configuration for every
245/// completion the thread runs.
246pub struct ThreadBuilder<'a, C, S, H>
247where
248    C: ConversationStore,
249    S: StateStore,
250    H: HttpClient,
251{
252    system: &'a LaunchingSystem<C, S, H>,
253    tools: Vec<Box<dyn Tool<ChannelSender>>>,
254    extra_system_prompt: Option<String>,
255    model: Option<Rc<dyn ModelSource>>,
256}
257
258impl<C, S, H> ThreadBuilder<'_, C, S, H>
259where
260    C: ConversationStore + 'static,
261    S: StateStore + 'static,
262    H: HttpClient + 'static,
263{
264    /// Give the thread an additional tool (on top of the system-wide tools).
265    pub fn tool(mut self, tool: Box<dyn Tool<ChannelSender>>) -> Self {
266        self.tools.push(tool);
267        self
268    }
269
270    /// Give the thread additional tools (on top of the system-wide tools).
271    pub fn tools(mut self, tools: impl IntoIterator<Item = Box<dyn Tool<ChannelSender>>>) -> Self {
272        self.tools.extend(tools);
273        self
274    }
275
276    /// Append thread-specific text to the system prompt (after any
277    /// system-wide extra prompt).
278    pub fn extra_system_prompt(mut self, prompt: impl Into<String>) -> Self {
279        self.extra_system_prompt = Some(prompt.into());
280        self
281    }
282
283    /// Give the thread its own [`ModelSource`] in place of the system-wide
284    /// one. Like the system-wide source, it resolves at the start of every
285    /// completion round, and threads this thread spawns inherit it.
286    pub fn model(mut self, model: impl ModelSource + 'static) -> Self {
287        self.model = Some(Rc::new(model));
288        self
289    }
290
291    /// Create the thread: generate its ID, register the launch
292    /// configuration, and attach. Returns the thread's [`ThreadHandle`]
293    /// (its ID is [`ThreadHandle::thread_id`]).
294    ///
295    /// The launch configuration lives for the lifetime of the process; a
296    /// thread resumed after a restart runs with the system-wide
297    /// configuration only.
298    pub async fn launch(self) -> ThreadHandle {
299        let thread_id = ThreadId::from(uuid::Uuid::new_v4().to_string());
300        self.system.registry.threads.borrow_mut().insert(
301            thread_id.clone(),
302            LaunchConfig {
303                tools: self.tools.into_iter().map(Rc::from).collect(),
304                extra_system_prompt: self.extra_system_prompt,
305                model: self.model,
306            },
307        );
308        attach(&self.system.running, &thread_id).await
309    }
310}
311#[cfg(test)]
312mod tests {
313    use crate::system::test_support::*;
314
315    #[tokio::test(flavor = "current_thread")]
316    async fn launched_threads_union_their_own_tools_and_prompt() {
317        let local = tokio::task::LocalSet::new();
318        local
319            .run_until(async {
320                let (system, mut ctrl) = start_launcher_system(
321                    vec![Box::new(NamedTool("global_tool"))],
322                    "Global prompt.",
323                );
324
325                let mut alpha = system
326                    .thread_builder()
327                    .tool(Box::new(NamedTool("alpha_tool")))
328                    .extra_system_prompt("You are alpha.")
329                    .launch()
330                    .await;
331                let mut beta = system
332                    .thread_builder()
333                    .tool(Box::new(NamedTool("beta_tool")))
334                    .launch()
335                    .await;
336                assert_ne!(alpha.thread_id(), beta.thread_id());
337
338                alpha.send_user_text("hi").await.expect("send input");
339                let req = ctrl.next_request().await;
340                let names = tool_names(&req);
341                assert!(names.contains(&"global_tool".to_owned()));
342                assert!(names.contains(&"alpha_tool".to_owned()));
343                assert!(!names.contains(&"beta_tool".to_owned()));
344                let preamble = req.preamble.clone().expect("system prompt present");
345                assert!(preamble.contains("Global prompt."));
346                assert!(preamble.contains("You are alpha."));
347                ctrl.send_text("hello alpha");
348                ctrl.finish();
349                assert_eq!(
350                    handle_texts_until_finished(&mut alpha).await,
351                    ["hello alpha"]
352                );
353
354                beta.send_user_text("hi").await.expect("send input");
355                let req = ctrl.next_request().await;
356                let names = tool_names(&req);
357                assert!(names.contains(&"global_tool".to_owned()));
358                assert!(names.contains(&"beta_tool".to_owned()));
359                assert!(!names.contains(&"alpha_tool".to_owned()));
360                let preamble = req.preamble.clone().expect("system prompt present");
361                assert!(preamble.contains("Global prompt."));
362                assert!(!preamble.contains("You are alpha."));
363                ctrl.send_text("hello beta");
364                ctrl.finish();
365                assert_eq!(handle_texts_until_finished(&mut beta).await, ["hello beta"]);
366            })
367            .await;
368    }
369
370    #[tokio::test(flavor = "current_thread")]
371    async fn launcher_thread_handle_attaches_to_existing_threads_only() {
372        let local = tokio::task::LocalSet::new();
373        local
374            .run_until(async {
375                let (mut system, mut ctrl) = start_launcher_system(vec![], "");
376
377                // Unknown threads cannot be attached to.
378                assert!(
379                    system
380                        .thread_handle(rap_protocol::ThreadId::from_ref("no-such-thread"))
381                        .await
382                        .expect("check unknown thread")
383                        .is_none()
384                );
385
386                // Launched threads can, even before their first message.
387                let launched = system.thread_builder().launch().await;
388                let launched_id = launched.thread_id().to_owned();
389                assert!(
390                    system
391                        .thread_handle(&launched_id)
392                        .await
393                        .expect("check launched thread")
394                        .is_some()
395                );
396
397                let history_thread = system.thread_builder().launch().await;
398                let history_thread_id = history_thread.thread_id().to_owned();
399                history_thread
400                    .send_user_text("hello")
401                    .await
402                    .expect("send input");
403                let _req = ctrl.next_request().await;
404                ctrl.send_text("hi");
405                ctrl.finish();
406                // Wait for the round to settle (drivers idle out).
407                while !system.is_idle() {
408                    tokio::time::timeout(
409                        std::time::Duration::from_secs(5),
410                        system.next_lifecycle_event(),
411                    )
412                    .await
413                    .expect("timed out waiting for a driver exit")
414                    .expect("thread lifecycle channel closed");
415                }
416                drop(history_thread);
417                let mut attached = system
418                    .thread_handle(&history_thread_id)
419                    .await
420                    .expect("load existing thread")
421                    .expect("thread has history");
422                assert!(
423                    !attached.replay().history.is_empty(),
424                    "replay includes the thread's history"
425                );
426                attached.send_user_text("again").await.expect("send input");
427                let _req = ctrl.next_request().await;
428                ctrl.send_text("still here");
429                ctrl.finish();
430                assert_eq!(
431                    handle_texts_until_finished(&mut attached).await,
432                    ["still here"]
433                );
434            })
435            .await;
436    }
437
438    #[tokio::test(flavor = "current_thread")]
439    async fn launched_thread_children_inherit_launch_config() {
440        let local = tokio::task::LocalSet::new();
441        local
442            .run_until(async {
443                let (system, mut ctrl) = start_launcher_system(
444                    vec![Box::new(NamedTool("global_tool"))],
445                    "Global prompt.",
446                );
447
448                let alpha = system
449                    .thread_builder()
450                    .tool(Box::new(NamedTool("alpha_tool")))
451                    .extra_system_prompt("You are alpha.")
452                    .launch()
453                    .await;
454                let alpha_id = alpha.thread_id().to_owned();
455
456                alpha
457                    .send_user_text("spawn a child")
458                    .await
459                    .expect("send input");
460                let _req = ctrl.next_request().await;
461                ctrl.send_tool_call(
462                    "tc-spawn",
463                    "spawn_thread",
464                    serde_json::json!({
465                        "instructions": "do child work",
466                        "child_of": [alpha_id],
467                    }),
468                );
469                ctrl.finish();
470
471                // The spawn is synchronous: the parent loops back with the
472                // spawn result first.
473                let parent_followup = ctrl.next_request().await;
474                assert!(tool_names(&parent_followup).contains(&"alpha_tool".to_owned()));
475                ctrl.send_text("spawned");
476                ctrl.finish();
477
478                // The child's seed message produces its first completion. Launch
479                // configurations attach to the launched (root) thread, so the
480                // child runs with alpha's tools and prompt.
481                let child_req = ctrl.next_request().await;
482                let names = tool_names(&child_req);
483                assert!(names.contains(&"global_tool".to_owned()));
484                assert!(
485                    names.contains(&"alpha_tool".to_owned()),
486                    "child threads inherit the launched root's tools"
487                );
488                let preamble = child_req.preamble.expect("system prompt present");
489                assert!(
490                    preamble.contains("You are alpha."),
491                    "child threads inherit the launched root's prompt"
492                );
493                ctrl.send_text("child done");
494                ctrl.finish();
495            })
496            .await;
497    }
498
499    #[tokio::test(flavor = "current_thread")]
500    async fn launched_threads_use_their_own_model_and_children_inherit_it() {
501        let local = tokio::task::LocalSet::new();
502        local
503            .run_until(async {
504                let (system, mut system_ctrl) = start_launcher_system(vec![], "");
505                let (alpha_model, mut alpha_ctrl) = model_source(None);
506
507                let alpha = system.thread_builder().model(alpha_model).launch().await;
508                let alpha_id = alpha.thread_id().to_owned();
509                let other = system.thread_builder().launch().await;
510
511                // The launched model serves alpha's rounds; the system-wide
512                // model serves everyone else.
513                alpha.send_user_text("hi").await.expect("send input");
514                let _req = alpha_ctrl.next_request().await;
515                alpha_ctrl.send_text("from alpha model");
516                alpha_ctrl.finish();
517
518                other.send_user_text("hi").await.expect("send input");
519                let _req = system_ctrl.next_request().await;
520                system_ctrl.send_text("from system model");
521                system_ctrl.finish();
522
523                // A child spawned by alpha inherits alpha's model.
524                alpha
525                    .send_user_text("spawn a child")
526                    .await
527                    .expect("send input");
528                let _req = alpha_ctrl.next_request().await;
529                alpha_ctrl.send_tool_call(
530                    "tc-spawn",
531                    "spawn_thread",
532                    serde_json::json!({
533                        "instructions": "do child work",
534                        "child_of": [alpha_id],
535                    }),
536                );
537                alpha_ctrl.finish();
538
539                // Parent follow-up (spawn is synchronous), then the child's
540                // seed completion: both on alpha's model.
541                let _parent_followup = alpha_ctrl.next_request().await;
542                alpha_ctrl.send_text("spawned");
543                alpha_ctrl.finish();
544                let child_req = alpha_ctrl.next_request().await;
545                assert!(
546                    tool_result_texts(&child_req)
547                        .iter()
548                        .any(|t| t.contains("do child work")),
549                    "the request on alpha's model is the child's seed"
550                );
551                alpha_ctrl.send_text("child done");
552                alpha_ctrl.finish();
553            })
554            .await;
555    }
556}