1use rap_protocol::ThreadId;
4use std::rc::Rc;
5
6use async_trait::async_trait;
7use tokio::sync::{mpsc, oneshot};
8
9use crate::message::InputMessage;
10use crate::tools::Tool;
11use crate::traits::{ConversationStore, InputSender, StateStore};
12use rap_client::http::HttpClient;
13use rap_client::notifier::RapNotifier;
14
15use super::config::{StaticThreadConfig, ThreadConfigSource};
16use super::defer::DeferQueue;
17use super::local::ChannelSender;
18use super::local::{
19 LaunchRegistry, LaunchingSystem, RunningSystem, UnionConfigSource, UnionModelSource,
20};
21use super::model::ModelSource;
22use super::observer::ThreadObserver;
23use super::thread::{StepOutcome, Thread};
24
25type BoxError = Box<dyn std::error::Error + Send + Sync>;
26
27type BuildParts<C, S, M, H> = (
28 Rc<SystemInner<C, S, M, H>>,
29 Option<mpsc::UnboundedReceiver<(InputMessage, String)>>,
30);
31
32#[derive(Clone)]
35pub struct NoRapHttp;
36
37#[derive(Debug)]
38pub struct NoRapHttpError;
39
40impl std::fmt::Display for NoRapHttpError {
41 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
42 write!(f, "no HTTP client configured")
43 }
44}
45
46impl std::error::Error for NoRapHttpError {}
47
48#[async_trait]
49impl HttpClient for NoRapHttp {
50 type Error = NoRapHttpError;
51
52 async fn post(&self, _url: &str, _body: &str) -> Result<u16, NoRapHttpError> {
53 Err(NoRapHttpError)
54 }
55
56 async fn get(&self, _url: &str) -> Result<(u16, Vec<u8>), NoRapHttpError> {
57 Err(NoRapHttpError)
58 }
59}
60
61pub(crate) struct SystemInner<C, S, M, H>
63where
64 C: ConversationStore,
65 S: StateStore,
66 M: InputSender,
67 H: HttpClient,
68{
69 pub conversation_store: C,
70 pub state_store: S,
71 pub model: Box<dyn ModelSource>,
72 pub config: Box<dyn ThreadConfigSource<M, H>>,
73 pub sender: M,
74 pub callback_url: String,
75 pub builtin_tools: bool,
76 pub tokio_sleep_tools: bool,
77}
78
79pub struct AgentSystemBuilder<C, S, M, H = NoRapHttp>
103where
104 C: ConversationStore,
105 S: StateStore,
106 M: InputSender,
107 H: HttpClient,
108{
109 conversation_store: C,
110 state_store: S,
111 model: Box<dyn ModelSource>,
112 tools: Vec<Box<dyn Tool<M>>>,
113 config: Option<Box<dyn ThreadConfigSource<M, H>>>,
114 sender: M,
115 local_rx: Option<mpsc::UnboundedReceiver<(InputMessage, String)>>,
116 extra_system_prompt: Option<String>,
117 callback_url: String,
118 rap_notifier: Option<RapNotifier<H>>,
119 builtin_tools: bool,
120 tokio_sleep_tools: bool,
121 launch_registry: Option<LaunchRegistry<M>>,
122}
123
124impl<C, S, M, H> AgentSystemBuilder<C, S, M, H>
125where
126 C: ConversationStore + 'static,
127 S: StateStore + 'static,
128 M: InputSender + 'static,
129 H: HttpClient + 'static,
130{
131 fn with_sender(
136 conversation_store: C,
137 state_store: S,
138 model: impl ModelSource + 'static,
139 sender: M,
140 local_rx: Option<mpsc::UnboundedReceiver<(InputMessage, String)>>,
141 ) -> Self {
142 AgentSystemBuilder {
143 conversation_store,
144 state_store,
145 model: Box::new(model),
146 tools: Vec::new(),
147 config: None,
148 sender,
149 local_rx,
150 extra_system_prompt: None,
151 callback_url: String::new(),
152 rap_notifier: None,
153 builtin_tools: true,
154 tokio_sleep_tools: false,
155 launch_registry: None,
156 }
157 }
158
159 pub fn tool(mut self, tool: Box<dyn Tool<M>>) -> Self {
161 self.tools.push(tool);
162 self
163 }
164
165 pub fn tools(mut self, tools: impl IntoIterator<Item = Box<dyn Tool<M>>>) -> Self {
167 self.tools.extend(tools);
168 self
169 }
170
171 pub fn extra_system_prompt(mut self, prompt: impl Into<String>) -> Self {
173 self.extra_system_prompt = Some(prompt.into());
174 self
175 }
176
177 pub fn thread_config<H2: HttpClient + 'static>(
183 self,
184 source: impl ThreadConfigSource<M, H2> + 'static,
185 ) -> AgentSystemBuilder<C, S, M, H2> {
186 assert!(
187 self.tools.is_empty()
188 && self.extra_system_prompt.is_none()
189 && self.rap_notifier.is_none(),
190 "thread_config replaces the static tools/extra_system_prompt/rap_notifier configuration; do not combine them"
191 );
192 AgentSystemBuilder {
193 conversation_store: self.conversation_store,
194 state_store: self.state_store,
195 model: self.model,
196 tools: Vec::new(),
197 config: Some(Box::new(source)),
198 sender: self.sender,
199 local_rx: self.local_rx,
200 extra_system_prompt: None,
201 callback_url: self.callback_url,
202 rap_notifier: None,
203 builtin_tools: self.builtin_tools,
204 tokio_sleep_tools: self.tokio_sleep_tools,
205 launch_registry: self.launch_registry,
206 }
207 }
208
209 pub fn callback_url(mut self, url: impl Into<String>) -> Self {
211 self.callback_url = url.into();
212 self
213 }
214
215 pub fn without_builtin_tools(mut self) -> Self {
218 self.builtin_tools = false;
219 self
220 }
221
222 pub fn with_tokio_sleep_tools(mut self) -> Self {
226 self.tokio_sleep_tools = true;
227 self
228 }
229
230 pub fn rap_notifier<H2: HttpClient + 'static>(
235 self,
236 notifier: RapNotifier<H2>,
237 ) -> AgentSystemBuilder<C, S, M, H2> {
238 assert!(
239 self.config.is_none(),
240 "rap_notifier cannot be combined with thread_config; put the notifier in the ThreadConfig instead"
241 );
242 AgentSystemBuilder {
243 conversation_store: self.conversation_store,
244 state_store: self.state_store,
245 model: self.model,
246 tools: self.tools,
247 config: None,
248 sender: self.sender,
249 local_rx: self.local_rx,
250 extra_system_prompt: self.extra_system_prompt,
251 callback_url: self.callback_url,
252 rap_notifier: Some(notifier),
253 builtin_tools: self.builtin_tools,
254 tokio_sleep_tools: self.tokio_sleep_tools,
255 launch_registry: self.launch_registry,
256 }
257 }
258
259 fn build_inner(self) -> BuildParts<C, S, M, H> {
260 let mut config: Box<dyn ThreadConfigSource<M, H>> = match self.config {
261 Some(source) => source,
262 None => Box::new(StaticThreadConfig {
263 tools: self.tools.into_iter().map(Rc::from).collect(),
264 extra_system_prompt: self.extra_system_prompt,
265 rap_notifier: self.rap_notifier,
266 }),
267 };
268 let mut model = self.model;
269 if let Some(registry) = self.launch_registry {
270 config = Box::new(UnionConfigSource {
271 inner: config,
272 registry: registry.clone(),
273 conversation_store: self.conversation_store.clone(),
274 });
275 model = Box::new(UnionModelSource {
276 inner: model,
277 registry,
278 conversation_store: self.conversation_store.clone(),
279 });
280 }
281 (
282 Rc::new(SystemInner {
283 conversation_store: self.conversation_store,
284 state_store: self.state_store,
285 model,
286 config,
287 sender: self.sender,
288 callback_url: self.callback_url,
289 builtin_tools: self.builtin_tools,
290 tokio_sleep_tools: self.tokio_sleep_tools,
291 }),
292 self.local_rx,
293 )
294 }
295
296 pub fn build(self) -> AgentSystem<C, S, M, H> {
298 let (inner, _local_rx) = self.build_inner();
299 AgentSystem { inner }
300 }
301}
302
303impl<C, S, M> AgentSystemBuilder<C, S, M, NoRapHttp>
304where
305 C: ConversationStore + 'static,
306 S: StateStore + 'static,
307 M: InputSender + 'static,
308{
309 pub fn new(
314 conversation_store: C,
315 state_store: S,
316 model: impl ModelSource + 'static,
317 sender: M,
318 ) -> Self {
319 Self::with_sender(conversation_store, state_store, model, sender, None)
320 }
321}
322
323impl<C, S> AgentSystemBuilder<C, S, ChannelSender, NoRapHttp>
324where
325 C: ConversationStore + 'static,
326 S: StateStore + 'static,
327{
328 pub fn new_local(
332 conversation_store: C,
333 state_store: S,
334 model: impl ModelSource + 'static,
335 ) -> Self {
336 let (sender, rx) = ChannelSender::new_pair();
337 Self::with_sender(conversation_store, state_store, model, sender, Some(rx))
338 }
339}
340
341impl<C, S, H> AgentSystemBuilder<C, S, ChannelSender, H>
342where
343 C: ConversationStore + 'static,
344 S: StateStore + 'static,
345 H: HttpClient + 'static,
346{
347 pub fn build_local(mut self) -> LocalAgentSystem<C, S, H> {
354 let registry = LaunchRegistry::default();
355 self.launch_registry = Some(registry.clone());
356 let (inner, local_rx) = self.build_inner();
357 let input_rx = local_rx.expect(
358 "bug: build_local requires a builder created with AgentSystemBuilder::new_local",
359 );
360 LocalAgentSystem {
361 system: AgentSystem { inner },
362 input_rx,
363 registry,
364 }
365 }
366
367 pub fn start(self) -> LaunchingSystem<C, S, H> {
375 self.build_local().start()
376 }
377
378 pub fn start_with_observer<O, F>(self, make_observer: F) -> RunningSystem<O::SubscribeRequest>
385 where
386 O: ThreadObserver + 'static,
387 F: Fn(&ThreadId<str>) -> O + 'static,
388 {
389 self.build_local().start_with_observer(make_observer)
390 }
391}
392
393pub struct AgentSystem<C, S, M, H>
402where
403 C: ConversationStore,
404 S: StateStore,
405 M: InputSender,
406 H: HttpClient,
407{
408 pub(crate) inner: Rc<SystemInner<C, S, M, H>>,
409}
410
411impl<C, S, M, H> AgentSystem<C, S, M, H>
412where
413 C: ConversationStore + 'static,
414 S: StateStore + 'static,
415 M: InputSender + 'static,
416 H: HttpClient + 'static,
417{
418 pub fn sender(&self) -> &M {
420 &self.inner.sender
421 }
422
423 pub async fn step<O: ThreadObserver, D: DeferQueue>(
453 &mut self,
454 inputs: Vec<(InputMessage, String)>,
455 observer: &O,
456 defer: &mut D,
457 ) -> Result<Vec<(ThreadId, StepOutcome)>, BoxError> {
458 let mut groups: Vec<(ThreadId, Vec<(InputMessage, String)>)> = Vec::new();
460 for (msg, id) in inputs {
461 match groups.iter_mut().find(|(g, _)| *g == msg.group_id) {
462 Some((_, batch)) => batch.push((msg, id)),
463 None => groups.push((msg.group_id.clone(), vec![(msg, id)])),
464 }
465 }
466
467 let mut ready = Vec::new();
470 for (thread_id, batch) in groups {
471 let thread = Thread::load(self.inner.clone(), thread_id.clone()).await?;
472 let batch = thread.filter_deferrable(batch, defer).await?;
473 ready.push((thread_id, thread, batch));
474 }
475
476 let results = futures_util::future::join_all(ready.into_iter().map(
477 |(thread_id, thread, batch)| async move {
478 let (_cancel_tx, cancel_rx) = oneshot::channel();
481 let outcome = thread.step_no_defer(batch, observer, cancel_rx).await;
482 (thread_id, outcome)
483 },
484 ))
485 .await;
486
487 let mut outcomes = Vec::with_capacity(results.len());
488 for (thread_id, outcome) in results {
489 outcomes.push((thread_id, outcome?));
490 }
491 Ok(outcomes)
492 }
493}
494
495pub struct LocalAgentSystem<C, S, H>
503where
504 C: ConversationStore,
505 S: StateStore,
506 H: HttpClient,
507{
508 pub(crate) system: AgentSystem<C, S, ChannelSender, H>,
509 pub(crate) input_rx: mpsc::UnboundedReceiver<(InputMessage, String)>,
510 pub(crate) registry: LaunchRegistry<ChannelSender>,
511}
512
513impl<C, S, H> LocalAgentSystem<C, S, H>
514where
515 C: ConversationStore + 'static,
516 S: StateStore + 'static,
517 H: HttpClient + 'static,
518{
519 pub fn sender(&self) -> ChannelSender {
522 self.system.inner.sender.clone()
523 }
524}
525#[cfg(test)]
526mod tests {
527 use super::*;
528 use crate::message::{InputMessage, InputMessageContent, OAuthRequired};
529 use crate::stores::{InMemoryConversationStore, InMemoryStateStore};
530 use crate::system::defer::NoDeferral;
531 use crate::system::events::AgentEvent;
532 use crate::system::local::ChannelSender;
533 use crate::system::observer::EventCollector;
534 use crate::system::test_support::*;
535 use crate::system::thread::StepOutcome;
536
537 #[tokio::test(flavor = "current_thread")]
538 async fn step_mode_runs_single_slice() {
539 let local = tokio::task::LocalSet::new();
540 local
541 .run_until(async {
542 let (model, mut ctrl) = model_source(None);
543 let (sender, mut loopback_rx) = ChannelSender::new_pair();
544 let system = AgentSystemBuilder::new(
545 InMemoryConversationStore::new(),
546 InMemoryStateStore::new(),
547 model,
548 sender,
549 )
550 .build();
551
552 let step = tokio::task::spawn_local(async move {
553 let mut system = system;
554 let collector = EventCollector::new();
555 let outcomes = system
556 .step(
557 vec![user_text_input("t1", "hello")],
558 &collector,
559 &mut NoDeferral,
560 )
561 .await
562 .expect("step");
563 (outcomes, collector.take())
564 });
565
566 let _req = ctrl.next_request().await;
567 ctrl.send_text("hi there");
568 ctrl.finish();
569
570 let (outcomes, events) = step.await.expect("join");
571 assert_eq!(outcomes.len(), 1);
572 assert_eq!(outcomes[0].0.as_str(), "t1");
573 assert!(matches!(outcomes[0].1, StepOutcome::Completed { .. }));
574 assert!(events.iter().any(|(t, e)| t.as_str() == "t1"
575 && matches!(e, AgentEvent::UserInput { text } if text == "hello")));
576 assert!(events.iter().any(|(t, e)| t.as_str() == "t1"
577 && matches!(e, AgentEvent::TextChunk { text } if text == "hi there")));
578 assert!(
579 events
580 .iter()
581 .any(|(_, e)| matches!(e, AgentEvent::CompletionFinished { .. }))
582 );
583 assert!(loopback_rx.try_recv().is_err());
585 })
586 .await;
587 }
588
589 #[tokio::test(flavor = "current_thread")]
590 async fn step_mode_runs_multiple_threads_from_one_batch() {
591 let local = tokio::task::LocalSet::new();
592 local
593 .run_until(async {
594 let (model, mut ctrl) = model_source(None);
595 let (sender, _loopback_rx) = ChannelSender::new_pair();
596 let system = AgentSystemBuilder::new(
597 InMemoryConversationStore::new(),
598 InMemoryStateStore::new(),
599 model,
600 sender,
601 )
602 .build();
603
604 let step = tokio::task::spawn_local(async move {
606 let mut system = system;
607 let collector = EventCollector::new();
608 let outcomes = system
609 .step(
610 vec![
611 user_text_input("t1", "hello from one"),
612 user_text_input("t2", "hello from two"),
613 ],
614 &collector,
615 &mut NoDeferral,
616 )
617 .await
618 .expect("step");
619 (outcomes, collector.take())
620 });
621
622 let _req1 = ctrl.next_request().await;
626 ctrl.send_text("one");
627 ctrl.finish();
628 let _req2 = ctrl.next_request().await;
629 ctrl.send_text("two");
630 ctrl.finish();
631
632 let (outcomes, events) = step.await.expect("join");
633 let mut ids: Vec<&str> = outcomes.iter().map(|(t, _)| t.as_str()).collect();
634 ids.sort_unstable();
635 assert_eq!(ids, ["t1", "t2"]);
636 assert!(
637 outcomes
638 .iter()
639 .all(|(_, o)| matches!(o, StepOutcome::Completed { .. }))
640 );
641 assert!(events.iter().any(|(t, e)| t.as_str() == "t1"
642 && matches!(e, AgentEvent::TextChunk { text } if text == "one")));
643 assert!(events.iter().any(|(t, e)| t.as_str() == "t2"
644 && matches!(e, AgentEvent::TextChunk { text } if text == "two")));
645 })
646 .await;
647 }
648
649 #[tokio::test(flavor = "current_thread")]
653 async fn step_mode_surfaces_oauth_and_completes_actionable_input() {
654 let local = tokio::task::LocalSet::new();
655 local
656 .run_until(async {
657 let (model, mut ctrl) = model_source(None);
658 let (sender, _loopback_rx) = ChannelSender::new_pair();
659 let system = AgentSystemBuilder::new(
660 InMemoryConversationStore::new(),
661 InMemoryStateStore::new(),
662 model,
663 sender,
664 )
665 .build();
666
667 let oauth = (
668 InputMessage {
669 content: InputMessageContent::OAuth(OAuthRequired {
670 content_type: "oauth_required".into(),
671 id: "o1".into(),
672 call_id: None,
673 auth_url: "https://example.com/auth".into(),
674 }),
675 group_id: "t1".into(),
676 metadata: None,
677 synthetic: None,
678 display_as: None,
679 subscription: false,
680 },
681 uuid::Uuid::new_v4().to_string(),
682 );
683
684 let step = tokio::task::spawn_local(async move {
685 let mut system = system;
686 let collector = EventCollector::new();
687 let outcomes = system
688 .step(
689 vec![oauth, user_text_input("t1", "hello")],
690 &collector,
691 &mut NoDeferral,
692 )
693 .await
694 .expect("step");
695 (outcomes, collector.take())
696 });
697
698 let _req = ctrl.next_request().await;
699 ctrl.send_text("hi there");
700 ctrl.finish();
701
702 let (outcomes, events) = step.await.expect("join");
703 assert_eq!(outcomes.len(), 1);
704 assert!(matches!(outcomes[0].1, StepOutcome::Completed { .. }));
705 assert!(events.iter().any(|(t, e)| t.as_str() == "t1"
706 && matches!(e, AgentEvent::OAuthRequired { auth_url } if auth_url == "https://example.com/auth")));
707 assert!(events.iter().any(|(t, e)| t.as_str() == "t1"
708 && matches!(e, AgentEvent::UserInput { text } if text == "hello")));
709 })
710 .await;
711 }
712}