1use rap_protocol::ThreadId;
8use std::collections::HashMap;
9use std::rc::Rc;
10
11use futures_util::StreamExt;
12use futures_util::stream::FuturesUnordered;
13use tokio::sync::{mpsc, oneshot};
14use tokio_util::sync::CancellationToken;
15
16use crate::message::InputMessage;
17use crate::traits::{ConversationStore, InputSender, StateStore};
18use rap_client::http::HttpClient;
19
20use super::driver::{ActiveThreads, ThreadLifecycleEvent, drive_thread};
21use super::sender::ChannelSender;
22use crate::system::builder::{LocalAgentSystem, SystemInner};
23use crate::system::observer::ThreadObserver;
24use crate::system::thread::is_user_text_input;
25
26pub(crate) type SubscribeMessage<Sub> = (ThreadId, Sub, oneshot::Sender<()>);
30
31pub struct SubscribeHandle<Sub: Send + 'static> {
33 tx: mpsc::UnboundedSender<SubscribeMessage<Sub>>,
34}
35
36impl<Sub: Send + 'static> Clone for SubscribeHandle<Sub> {
37 fn clone(&self) -> Self {
38 Self {
39 tx: self.tx.clone(),
40 }
41 }
42}
43
44impl<Sub: Send + 'static> SubscribeHandle<Sub> {
45 pub async fn subscribe(&self, thread_id: &ThreadId<str>, request: Sub) -> bool {
56 let (ack_tx, ack_rx) = oneshot::channel();
57 if self
58 .tx
59 .send((thread_id.to_owned(), request, ack_tx))
60 .is_err()
61 {
62 return false;
63 }
64 ack_rx.await.is_ok()
67 }
68}
69
70pub struct RunningSystem<Sub: Send + 'static> {
80 sender: ChannelSender,
81 subscribe_tx: mpsc::UnboundedSender<SubscribeMessage<Sub>>,
82 active_threads: ActiveThreads,
83 lifecycle_rx: mpsc::UnboundedReceiver<ThreadLifecycleEvent>,
84 shutdown: CancellationToken,
85 task: tokio::task::JoinHandle<()>,
86}
87
88impl<Sub: Send + 'static> RunningSystem<Sub> {
89 pub fn sender(&self) -> ChannelSender {
92 self.sender.clone()
93 }
94
95 pub async fn send(&self, message: InputMessage, dedup_id: &str) {
98 self.sender
99 .send_to_input_queue(message, dedup_id)
100 .await
101 .expect("bug: router exited while the system was alive");
102 }
103
104 pub async fn send_user_text(&self, thread_id: &ThreadId<str>, text: impl Into<String>) {
106 let msg = InputMessage::user_text(thread_id.to_owned(), text);
107 self.send(msg, &uuid::Uuid::new_v4().to_string()).await
108 }
109
110 pub async fn subscribe(&self, thread_id: &ThreadId<str>, request: Sub) {
113 assert!(
114 self.subscribe_handle().subscribe(thread_id, request).await,
115 "bug: router exited while the system was alive"
116 );
117 }
118
119 pub fn subscribe_handle(&self) -> SubscribeHandle<Sub> {
122 SubscribeHandle {
123 tx: self.subscribe_tx.clone(),
124 }
125 }
126
127 #[cfg(test)]
129 pub(crate) fn active_threads(&self) -> ActiveThreads {
130 self.active_threads.clone()
131 }
132
133 pub fn is_idle(&self) -> bool {
137 self.active_threads
138 .lock()
139 .expect("bug: mutex poisoned")
140 .is_empty()
141 }
142
143 pub async fn next_lifecycle_event(&mut self) -> Option<ThreadLifecycleEvent> {
146 self.lifecycle_rx.recv().await
147 }
148
149 pub fn try_next_lifecycle_event(
151 &mut self,
152 ) -> Result<ThreadLifecycleEvent, mpsc::error::TryRecvError> {
153 self.lifecycle_rx.try_recv()
154 }
155
156 pub async fn shutdown(self) {
160 self.shutdown.cancel();
161 if let Err(e) = self.task.await {
162 tracing::error!("router task failed during shutdown: {e}");
163 }
164 }
165}
166
167impl<C, S, H> LocalAgentSystem<C, S, H>
168where
169 C: ConversationStore + 'static,
170 S: StateStore + 'static,
171 H: HttpClient + 'static,
172{
173 pub fn start_with_observer<O, F>(self, make_observer: F) -> RunningSystem<O::SubscribeRequest>
181 where
182 O: ThreadObserver + 'static,
183 F: Fn(&ThreadId<str>) -> O + 'static,
184 {
185 self.start_inner(make_observer)
186 }
187}
188
189impl<C, S, H> LocalAgentSystem<C, S, H>
190where
191 C: ConversationStore + 'static,
192 S: StateStore + 'static,
193 H: HttpClient + 'static,
194{
195 pub(crate) fn start_inner<O, F>(self, make_observer: F) -> RunningSystem<O::SubscribeRequest>
198 where
199 O: ThreadObserver + 'static,
200 F: Fn(&ThreadId<str>) -> O + 'static,
201 {
202 let sender = self.system.inner.sender.clone();
203 let (subscribe_tx, subscribe_rx) = mpsc::unbounded_channel();
204 let (lifecycle_tx, thread_lifecycle) = mpsc::unbounded_channel();
205 let active_threads: ActiveThreads = Default::default();
206 let shutdown = CancellationToken::new();
207
208 let task = tokio::task::spawn_local(route_loop(
209 self.system.inner,
210 self.input_rx,
211 subscribe_rx,
212 make_observer,
213 active_threads.clone(),
214 lifecycle_tx,
215 shutdown.clone(),
216 ));
217
218 RunningSystem {
219 sender,
220 subscribe_tx,
221 active_threads,
222 lifecycle_rx: thread_lifecycle,
223 shutdown,
224 task,
225 }
226 }
227}
228
229struct WorkerChannels<Sub> {
230 input_tx: mpsc::UnboundedSender<(InputMessage, String)>,
231 subscribe_tx: mpsc::UnboundedSender<(Sub, oneshot::Sender<()>)>,
232}
233
234enum RoutedMessage<Sub> {
235 Input(Box<InputMessage>, String),
236 Subscribe(ThreadId, Sub, oneshot::Sender<()>),
237}
238
239async fn route_loop<C, S, H, O, F>(
240 inner: Rc<SystemInner<C, S, ChannelSender, H>>,
241 mut input_rx: mpsc::UnboundedReceiver<(InputMessage, String)>,
242 mut subscribe_rx: mpsc::UnboundedReceiver<SubscribeMessage<O::SubscribeRequest>>,
243 make_observer: F,
244 active_threads: ActiveThreads,
245 lifecycle_tx: mpsc::UnboundedSender<ThreadLifecycleEvent>,
246 shutdown: CancellationToken,
247) where
248 C: ConversationStore + 'static,
249 S: StateStore + 'static,
250 H: HttpClient + 'static,
251 O: ThreadObserver + 'static,
252 F: Fn(&ThreadId<str>) -> O + 'static,
253{
254 let mut workers: HashMap<ThreadId, WorkerChannels<O::SubscribeRequest>> = HashMap::new();
255 let mut subscribe_closed = false;
256 let mut drivers = FuturesUnordered::new();
262
263 loop {
264 let msg: Option<RoutedMessage<O::SubscribeRequest>> = tokio::select! {
265 biased;
266 _ = shutdown.cancelled() => None,
267 exited = drivers.next(), if !drivers.is_empty() => {
268 let exited: ThreadId = exited.expect("bug: drivers is empty");
269 if workers.get(&exited).is_some_and(|w| w.input_tx.is_closed()) {
272 workers.remove(&exited);
273 }
274 continue;
275 }
276 msg = input_rx.recv() => msg.map(|(m, id)| RoutedMessage::Input(Box::new(m), id)),
277 req = subscribe_rx.recv(), if !subscribe_closed => {
278 match req {
279 Some((thread_id, req, ack)) => Some(RoutedMessage::Subscribe(thread_id, req, ack)),
280 None => {
281 subscribe_closed = true;
282 continue;
283 }
284 }
285 }
286 };
287 let Some(msg) = msg else { break };
288
289 let thread_id = match &msg {
290 RoutedMessage::Input(input, _) => input.group_id.clone(),
291 RoutedMessage::Subscribe(thread_id, _, _) => thread_id.clone(),
292 };
293
294 if let Some(w) = workers.get(&thread_id) {
296 if !w.input_tx.is_closed() {
297 match msg {
298 RoutedMessage::Input(input, id) => {
299 let _ = w.input_tx.send((*input, id));
300 }
301 RoutedMessage::Subscribe(_, req, ack) => {
302 let _ = w.subscribe_tx.send((req, ack));
303 }
304 }
305 continue;
306 }
307 workers.remove(&thread_id);
308 }
309
310 if let RoutedMessage::Input(input, dedup_id) = &msg
315 && !is_user_text_input(input)
316 {
317 match inner.conversation_store.thread_exists(&thread_id).await {
318 Ok(true) => {}
319 Ok(false) => {
320 tracing::info!(
321 %thread_id,
322 %dedup_id,
323 "dropping event for unknown thread",
324 );
325 continue;
326 }
327 Err(e) => {
328 tracing::warn!(
332 %thread_id,
333 "thread existence check failed, processing event anyway: {e}",
334 );
335 }
336 }
337
338 match inner.state_store.is_thread_stopped(&thread_id).await {
339 Ok(false) => {}
340 Ok(true) => {
341 tracing::info!(
342 %thread_id,
343 %dedup_id,
344 "dropping event for stopped thread",
345 );
346 continue;
347 }
348 Err(e) => {
349 tracing::warn!(
351 %thread_id,
352 "stopped-thread check failed, processing event anyway: {e}",
353 );
354 }
355 }
356 }
357
358 let (input_tx, input_rx_worker) = mpsc::unbounded_channel();
360 let (worker_subscribe_tx, worker_subscribe_rx) = mpsc::unbounded_channel();
361 let observer = make_observer(&thread_id);
362
363 drivers.push({
364 let thread_id = thread_id.clone();
365 let driver = drive_thread(
366 inner.clone(),
367 thread_id.clone(),
368 input_rx_worker,
369 worker_subscribe_rx,
370 observer,
371 active_threads.clone(),
372 lifecycle_tx.clone(),
373 );
374 async move {
375 rap_protocol::log_panic("thread_driver", driver).await;
378 thread_id
379 }
380 });
381
382 match msg {
383 RoutedMessage::Input(input, id) => {
384 let _ = input_tx.send((*input, id));
385 }
386 RoutedMessage::Subscribe(_, req, ack) => {
387 let _ = worker_subscribe_tx.send((req, ack));
388 }
389 }
390 workers.insert(
391 thread_id,
392 WorkerChannels {
393 input_tx,
394 subscribe_tx: worker_subscribe_tx,
395 },
396 );
397 }
398
399 drop(workers);
404 while drivers.next().await.is_some() {}
405}
406#[cfg(test)]
407mod tests {
408 use super::ThreadLifecycleEvent;
409 use crate::system::events::AgentEvent;
410 use crate::system::local::ThreadLifecycleState;
411 use crate::system::test_support::*;
412
413 #[tokio::test(flavor = "current_thread")]
416 async fn stale_event_to_unknown_thread_wakes_nothing() {
417 let local = tokio::task::LocalSet::new();
418 local
419 .run_until(async {
420 let (mut running, mut rx, mut ctrl, conv) = start_system(vec![], None);
421
422 running
424 .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "hello")
425 .await;
426 let _req = ctrl.next_request().await;
427 ctrl.send_text("hi");
428 ctrl.finish();
429 collect_until_finished(&mut rx).await;
430 wait_idle(&mut running).await;
431
432 running
435 .send(
436 subscription_event_input("ghost", "tc-ghost", "stale event").0,
437 "ghost-sub",
438 )
439 .await;
440 running
441 .send(
442 tool_result_input("ghost", "tc-ghost", "stale result").0,
443 "ghost-res",
444 )
445 .await;
446 for _ in 0..8 {
447 tokio::task::yield_now().await;
448 }
449
450 assert!(
451 running.is_idle(),
452 "no driver may wake for an unknown thread"
453 );
454 while let Ok(event) = running.try_next_lifecycle_event() {
457 assert_ne!(
458 event.thread_id.as_str(),
459 "ghost",
460 "no lifecycle transition may be reported for a dropped event"
461 );
462 }
463 assert!(
464 conv.thread_info(rap_protocol::ThreadId::from_ref("ghost"))
465 .is_none(),
466 "a dropped event must not create thread records"
467 );
468 })
469 .await;
470 }
471
472 #[tokio::test(flavor = "current_thread")]
475 async fn user_text_still_creates_new_threads() {
476 let local = tokio::task::LocalSet::new();
477 local
478 .run_until(async {
479 let (running, mut rx, mut ctrl, conv) = start_system(vec![], None);
480 running
481 .send_user_text(rap_protocol::ThreadId::from_ref("brand-new"), "hello")
482 .await;
483 let _req = ctrl.next_request().await;
484 ctrl.send_text("created");
485 ctrl.finish();
486 collect_until_finished(&mut rx).await;
487 assert!(
488 conv.thread_info(rap_protocol::ThreadId::from_ref("brand-new"))
489 .is_some()
490 );
491 })
492 .await;
493 }
494
495 #[tokio::test(flavor = "current_thread")]
500 async fn event_respawns_idle_existing_thread() {
501 let local = tokio::task::LocalSet::new();
502 local
503 .run_until(async {
504 let (mut running, mut rx, mut ctrl, _conv) = start_system(vec![], None);
505
506 running
507 .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "hello")
508 .await;
509 let _req = ctrl.next_request().await;
510 ctrl.send_text("hi");
511 ctrl.finish();
512 collect_until_finished(&mut rx).await;
513 wait_idle(&mut running).await;
514 while running.try_next_lifecycle_event().is_ok() {}
517
518 running
519 .send(
520 tool_result_input("t1", "tc-old", "late result").0,
521 "res-late",
522 )
523 .await;
524 let live = tokio::time::timeout(
525 std::time::Duration::from_secs(5),
526 running.next_lifecycle_event(),
527 )
528 .await
529 .expect("timed out waiting for the driver to respawn")
530 .expect("thread lifecycle channel closed");
531 assert_eq!(
532 live,
533 ThreadLifecycleEvent {
534 thread_id: "t1".into(),
535 state: ThreadLifecycleState::Live,
536 },
537 "the existing thread's driver must wake"
538 );
539 let idle = tokio::time::timeout(
540 std::time::Duration::from_secs(5),
541 running.next_lifecycle_event(),
542 )
543 .await
544 .expect("timed out waiting for the respawned driver to exit")
545 .expect("thread lifecycle channel closed");
546 assert_eq!(
547 idle,
548 ThreadLifecycleEvent {
549 thread_id: "t1".into(),
550 state: ThreadLifecycleState::Idle,
551 },
552 "the respawned driver must idle back out"
553 );
554 })
555 .await;
556 }
557
558 #[tokio::test(flavor = "current_thread")]
559 async fn shutdown_flushes_in_flight_turn() {
560 let local = tokio::task::LocalSet::new();
561 local
562 .run_until(async {
563 let (running, mut rx, mut ctrl, conv) = start_system(vec![], None);
564 running
565 .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "hello")
566 .await;
567 let _req = ctrl.next_request().await;
568 ctrl.send_text("partial answer");
569 loop {
570 if let Evt::E(AgentEvent::TextChunk { .. }) = next_evt(&mut rx).await {
571 break;
572 }
573 }
574
575 running.shutdown().await;
577
578 use crate::traits::ConversationStore;
579 let history = conv
580 .load_history_up_to(rap_protocol::ThreadId::from_ref("t1"), None, None)
581 .await
582 .expect("load history");
583 assert!(
584 history
585 .iter()
586 .any(|m| matches!(m, crate::message::InfinityMessage::Assistant { .. })),
587 "partial assistant text must be persisted on shutdown, got {history:?}"
588 );
589 })
590 .await;
591 }
592}