Skip to main content

infinity_agent_core/system/local/
driver.rs

1//! The per-thread driver loop used by local (resident) agent systems.
2//!
3//! One driver owns one thread: it batches inputs from the thread's
4//! channel, runs [`Thread::step`]s, interrupts an in-flight completion when
5//! user text arrives, defers synthetic events while a tool call is pending,
6//! triggers auto-compaction, and idles out when there is nothing left to
7//! wait for. The [router](super::router) respawns a driver when new input
8//! arrives for an idle thread.
9
10use rap_protocol::ThreadId;
11use std::collections::HashSet;
12use std::future::Future;
13use std::pin::Pin;
14use std::rc::Rc;
15use std::sync::{Arc, Mutex};
16
17use tokio::sync::{mpsc, oneshot};
18
19use crate::message::{InputMessage, InputMessageContent, SyntheticKind, TaggedSyntheticKind};
20use crate::traits::{ConversationStore, StateStore};
21use infinity_provider_protocol::message::UserContent;
22use rap_client::http::HttpClient;
23
24use super::sender::ChannelSender;
25use crate::system::builder::SystemInner;
26use crate::system::defer::InMemoryDeferQueue;
27use crate::system::events::AgentEvent;
28use crate::system::observer::ThreadObserver;
29use crate::system::thread::{StepOutcome, Thread, is_user_text_input};
30
31type BoxError = Box<dyn std::error::Error + Send + Sync>;
32
33type StepFuture<'a> = Pin<Box<dyn Future<Output = Result<StepOutcome, BoxError>> + 'a>>;
34
35/// An in-flight step paired with its cancellation handle. Keeping the two in
36/// one value makes it impossible for them to desynchronize: interrupting the
37/// step consumes both, and dropping the pair (e.g. on driver teardown) drops
38/// the sender, which the step observes as a cancellation.
39struct InFlightStep<'a> {
40    fut: StepFuture<'a>,
41    cancel_tx: oneshot::Sender<()>,
42}
43
44impl InFlightStep<'_> {
45    /// Interrupt the step and wait for it to wind down. The cancellation
46    /// path flushes whatever streamed so far to the store before returning,
47    /// so no partial turn is lost.
48    async fn cancel(self) -> Result<StepOutcome, BoxError> {
49        let _ = self.cancel_tx.send(());
50        self.fut.await
51    }
52}
53
54/// Set of thread IDs with a live driver.
55pub type ActiveThreads = Arc<Mutex<HashSet<ThreadId>>>;
56
57/// A transition in one thread driver's liveness.
58///
59/// For one driver, [`ThreadLifecycleState::Live`] is always reported before
60/// its matching [`ThreadLifecycleState::Idle`]. Because drivers respawn on
61/// demand, one thread can report many live/idle pairs over its lifetime.
62#[derive(Debug, Clone, PartialEq, Eq)]
63pub struct ThreadLifecycleEvent {
64    /// The thread whose driver changed state.
65    pub thread_id: ThreadId,
66    /// The driver's new lifecycle state.
67    pub state: ThreadLifecycleState,
68}
69
70/// One thread driver's current liveness.
71#[derive(Debug, Clone, Copy, PartialEq, Eq)]
72pub enum ThreadLifecycleState {
73    /// The driver spawned and is processing input or waiting on in-flight work.
74    Live,
75    /// The driver exited because no work is queued or expected. Active
76    /// subscriptions may still respawn it when an event arrives.
77    Idle,
78}
79
80fn is_compaction_complete(msg: &InputMessage) -> bool {
81    msg.synthetic
82        .as_ref()
83        .is_some_and(SyntheticKind::is_compaction_complete)
84}
85
86pub(crate) async fn drive_thread<C, S, H, O>(
87    inner: Rc<SystemInner<C, S, ChannelSender, H>>,
88    thread_id: ThreadId,
89    mut rx: mpsc::UnboundedReceiver<(InputMessage, String)>,
90    mut subscribe_rx: mpsc::UnboundedReceiver<(O::SubscribeRequest, oneshot::Sender<()>)>,
91    observer: O,
92    active_threads: ActiveThreads,
93    lifecycle_tx: mpsc::UnboundedSender<ThreadLifecycleEvent>,
94) where
95    C: ConversationStore + 'static,
96    S: StateStore + 'static,
97    H: HttpClient + 'static,
98    O: ThreadObserver + 'static,
99{
100    active_threads
101        .lock()
102        .expect("bug: mutex poisoned")
103        .insert(thread_id.to_owned());
104    // Report liveness transitions at the same two points where
105    // `active_threads` changes, so the channel and the set can never
106    // disagree about a driver's state.
107    let _ = lifecycle_tx.send(ThreadLifecycleEvent {
108        thread_id: thread_id.clone(),
109        state: ThreadLifecycleState::Live,
110    });
111    let _guard = DriverGuard {
112        thread_id: thread_id.clone(),
113        active_threads,
114        lifecycle_tx,
115    };
116
117    let thread = match Thread::load(inner, thread_id.clone()).await {
118        Ok(t) => t,
119        Err(e) => {
120            observer.on_event(
121                &thread_id,
122                &AgentEvent::Info {
123                    text: format!("Error: {e}"),
124                },
125            );
126            return;
127        }
128    };
129
130    let mut defer = InMemoryDeferQueue::new();
131    // Inputs that queued up while a step was in flight (or were generated
132    // internally, like the auto-compaction trigger).
133    let mut pending_batch: Vec<(InputMessage, String)> = Vec::new();
134    let mut compaction_triggered = false;
135    let mut total_tokens: u64 = 0;
136    // Set when subscribe_rx is closed, so selects stop polling it (a closed
137    // channel is always ready and would otherwise spin).
138    let mut subscribe_closed = false;
139
140    let mut in_flight: Option<InFlightStep<'_>> = None;
141
142    loop {
143        let new_inputs: Vec<(InputMessage, String)> = if let Some(flight) = in_flight.as_mut() {
144            tokio::select! {
145                biased;
146
147                res = &mut flight.fut => {
148                    in_flight = None;
149                    handle_step_result(
150                        res,
151                        &observer,
152                        &thread_id,
153                        &mut total_tokens,
154                        &mut compaction_triggered,
155                        &mut pending_batch,
156                    );
157                    continue;
158                },
159                first = rx.recv() => {
160                    let Some(first) = first else {
161                        // Input channel closed — the system is shutting down.
162                        // Interrupt the in-flight step and wait for it to wind
163                        // down so pending history items are synced to the
164                        // store.
165                        let _ = in_flight
166                            .take()
167                            .expect("bug: in-flight step missing during shutdown")
168                            .cancel()
169                            .await;
170                        return;
171                    };
172                    let mut batch = vec![first];
173                    while let Ok(item) = rx.try_recv() {
174                        batch.push(item);
175                    }
176
177                    if batch.iter().any(|(msg, _)| is_user_text_input(msg)) {
178                        // User text interrupts the in-flight completion.
179                        let res = in_flight
180                            .take()
181                            .expect("bug: in-flight step missing during interrupt")
182                            .cancel()
183                            .await;
184                        handle_step_result(
185                            res,
186                            &observer,
187                            &thread_id,
188                            &mut total_tokens,
189                            &mut compaction_triggered,
190                            &mut pending_batch,
191                        );
192
193                        let (mut user_inputs, non_user_inputs): (Vec<_>, Vec<_>) = batch
194                            .into_iter()
195                            .partition(|(msg, _)| is_user_text_input(msg));
196
197                        if let InputMessageContent::User(UserContent::Text(text)) =
198                            &mut user_inputs[0].0.content
199                        {
200                            text.text = format!("<interrupt>{}", text.text);
201                        } else {
202                            panic!("bug: user_inputs should only contain user text");
203                        }
204
205                        pending_batch.extend(non_user_inputs);
206                        user_inputs
207                    } else {
208                        pending_batch.extend(batch);
209                        continue;
210                    }
211                },
212                req = subscribe_rx.recv(), if !subscribe_closed => {
213                    match req {
214                        Some((req, ack)) => {
215                            observer.on_subscribe(&thread_id, req, thread.replay_snapshot());
216                            let _ = ack.send(());
217                        }
218                        None => subscribe_closed = true,
219                    }
220                    continue;
221                }
222            }
223        } else {
224            let mut batch: Vec<(InputMessage, String)> = std::mem::take(&mut pending_batch);
225            while let Ok(item) = rx.try_recv() {
226                batch.push(item);
227            }
228
229            // Deferred events whose blocking tool call has been resolved must
230            // be processed even if nothing else arrives.
231            let defer_ready = !defer.is_empty() && thread.pending_active_tool_call().is_none();
232
233            if batch.is_empty() && !defer_ready {
234                match check_before_idle(
235                    &mut batch,
236                    &mut rx,
237                    &mut subscribe_rx,
238                    &observer,
239                    &thread,
240                    &thread_id,
241                ) {
242                    IdleDecision::Continue => {
243                        // Input arrived after the initial drain but before the
244                        // synchronous idle check. Keep this driver alive and
245                        // process it instead of publishing a transient idle.
246                    }
247                    IdleDecision::Exit => {
248                        tracing::info!("Thread {} going idle", thread_id);
249                        return;
250                    }
251                    IdleDecision::AwaitInput => {
252                        // Park until something arrives.
253                        loop {
254                            tokio::select! {
255                                biased;
256                                msg = rx.recv() => {
257                                    match msg {
258                                        Some(m) => {
259                                            batch.push(m);
260                                            break;
261                                        }
262                                        None => return,
263                                    }
264                                }
265                                req = subscribe_rx.recv(), if !subscribe_closed => {
266                                    match req {
267                                        Some((req, ack)) => {
268                                            observer.on_subscribe(&thread_id, req, thread.replay_snapshot());
269                                            let _ = ack.send(());
270                                        }
271                                        None => subscribe_closed = true,
272                                    }
273                                }
274                            }
275                        }
276                        while let Ok(item) = rx.try_recv() {
277                            batch.push(item);
278                        }
279                    }
280                }
281            }
282
283            batch
284        };
285
286        // Reset the compaction trigger (and the stale token count) once a
287        // compaction round-trips: the next completion reports fresh usage.
288        for (msg, _) in &new_inputs {
289            if is_compaction_complete(msg) {
290                compaction_triggered = false;
291                total_tokens = 0;
292            }
293        }
294
295        let batch = match thread.filter_deferrable(new_inputs, &mut defer).await {
296            Ok(batch) => batch,
297            Err(e) => {
298                observer.on_event(
299                    &thread_id,
300                    &AgentEvent::Info {
301                        text: format!("Error: {e}"),
302                    },
303                );
304                continue;
305            }
306        };
307        if batch.is_empty() {
308            // Everything was deferred (or nothing arrived); wait for more input.
309            continue;
310        }
311
312        let (cancel_tx, cancel_rx) = oneshot::channel::<()>();
313        in_flight = Some(InFlightStep {
314            fut: Box::pin(thread.step_no_defer(batch, &observer, cancel_rx)),
315            cancel_tx,
316        });
317    }
318}
319
320enum IdleDecision {
321    Continue,
322    Exit,
323    AwaitInput,
324}
325
326/// Perform the final idle check without yielding to the router task. Since the
327/// router shares this `LocalSet`, an input either appears in `rx` here or is
328/// sent after the receivers are dropped, causing the router to spawn a new
329/// driver.
330fn check_before_idle<C, S, H, O>(
331    batch: &mut Vec<(InputMessage, String)>,
332    rx: &mut mpsc::UnboundedReceiver<(InputMessage, String)>,
333    subscribe_rx: &mut mpsc::UnboundedReceiver<(O::SubscribeRequest, oneshot::Sender<()>)>,
334    observer: &O,
335    thread: &Thread<C, S, ChannelSender, H>,
336    thread_id: &ThreadId<str>,
337) -> IdleDecision
338where
339    C: ConversationStore + 'static,
340    S: StateStore + 'static,
341    H: HttpClient + 'static,
342    O: ThreadObserver,
343{
344    while let Ok((request, ack)) = subscribe_rx.try_recv() {
345        observer.on_subscribe(thread_id, request, thread.replay_snapshot());
346        let _ = ack.send(());
347    }
348
349    if let Ok(item) = rx.try_recv() {
350        batch.push(item);
351        while let Ok(item) = rx.try_recv() {
352            batch.push(item);
353        }
354        IdleDecision::Continue
355    } else if thread.awaiting_tool_result() {
356        IdleDecision::AwaitInput
357    } else {
358        // Active subscriptions do not keep the driver resident. Their events
359        // respawn it; embeddings can keep associated resources alive based on
360        // subscription state when they observe this idle transition.
361        IdleDecision::Exit
362    }
363}
364
365fn handle_step_result(
366    res: Result<StepOutcome, BoxError>,
367    observer: &impl ThreadObserver,
368    thread_id: &ThreadId<str>,
369    total_tokens: &mut u64,
370    compaction_triggered: &mut bool,
371    pending_batch: &mut Vec<(InputMessage, String)>,
372) {
373    match res {
374        Ok(StepOutcome::Completed {
375            usage,
376            context_window,
377        }) => {
378            if let Some(u) = usage {
379                // Use total_tokens which includes cached input. When prompt
380                // caching is active, `input_tokens` alone undercounts usage.
381                *total_tokens = u.total_tokens;
382            }
383            // Background compaction: trigger when the context is > 75% full.
384            if !*compaction_triggered
385                && context_window > 0
386                && *total_tokens as usize > context_window * 3 / 4
387            {
388                *compaction_triggered = true;
389                tracing::info!(
390                    "Auto-compaction for thread {}: {} total tokens > 75% of {} context window",
391                    thread_id,
392                    total_tokens,
393                    context_window
394                );
395                observer.on_event(
396                    thread_id,
397                    &AgentEvent::Info {
398                        text: "✦ Auto-compaction triggered (context > 75%)".to_owned(),
399                    },
400                );
401                pending_batch.push((
402                    InputMessage {
403                        content: InputMessageContent::User(UserContent::text("")),
404                        group_id: thread_id.to_owned(),
405                        metadata: None,
406                        synthetic: Some(SyntheticKind::Tagged(TaggedSyntheticKind::Compaction)),
407                        display_as: None,
408                        subscription: false,
409                    },
410                    uuid::Uuid::new_v4().to_string(),
411                ));
412            }
413        }
414        Ok(StepOutcome::Skipped) => {}
415        Err(e) => {
416            observer.on_event(
417                thread_id,
418                &AgentEvent::Info {
419                    text: format!("Error: {e}"),
420                },
421            );
422        }
423    }
424}
425
426struct DriverGuard {
427    thread_id: ThreadId,
428    active_threads: ActiveThreads,
429    lifecycle_tx: mpsc::UnboundedSender<ThreadLifecycleEvent>,
430}
431
432impl Drop for DriverGuard {
433    fn drop(&mut self) {
434        self.active_threads
435            .lock()
436            .expect("bug: mutex poisoned")
437            .remove(&self.thread_id);
438        // Notify the embedding that this thread's driver exited, so it can
439        // release per-conversation resources once nothing else is live.
440        let _ = self.lifecycle_tx.send(ThreadLifecycleEvent {
441            thread_id: self.thread_id.clone(),
442            state: ThreadLifecycleState::Idle,
443        });
444    }
445}
446#[cfg(test)]
447mod tests {
448    use crate::system::events::AgentEvent;
449    use crate::system::test_support::*;
450
451    /// An active subscription does not keep a driver resident: once the
452    /// subscription tool's result settles the call, the driver idles out, and a
453    /// later subscription event respawns it.
454    #[tokio::test(flavor = "current_thread")]
455    async fn subscribed_thread_idles_and_event_respawns_it() {
456        let local = tokio::task::LocalSet::new();
457        local
458            .run_until(async {
459                let (mut running, mut rx, mut ctrl, _conv) =
460                    start_system(vec![Box::new(SubscribeTool)], None);
461                running
462                    .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "subscribe")
463                    .await;
464                let _req = ctrl.next_request().await;
465                ctrl.send_tool_call("tc-sub", "subscribe_tool", serde_json::json!({}));
466                ctrl.finish();
467                collect_until_finished(&mut rx).await;
468
469                // The subscription result triggers one more round; after it the
470                // thread holds an active subscription and nothing else.
471                let _req2 = ctrl.next_request().await;
472                ctrl.send_text("subscribed");
473                ctrl.finish();
474                collect_until_finished(&mut rx).await;
475
476                wait_idle(&mut running).await;
477                assert!(
478                    running.is_idle(),
479                    "an active subscription must not keep the driver resident"
480                );
481
482                // A subscription event arrives later: the router respawns a
483                // driver and the event is processed in a child thread, which
484                // reports a request to the model.
485                running
486                    .send(
487                        subscription_event_input("t1", "tc-sub", "late event").0,
488                        "ev-late",
489                    )
490                    .await;
491                let child_req = ctrl.next_request().await;
492                assert!(
493                    tool_result_texts(&child_req)
494                        .iter()
495                        .any(|t| t.contains("late event")),
496                    "the event must reach a respawned driver"
497                );
498                ctrl.send_text("handled");
499                ctrl.finish();
500            })
501            .await;
502    }
503
504    #[tokio::test(flavor = "current_thread")]
505    async fn auto_compaction_triggers_and_applies() {
506        let local = tokio::task::LocalSet::new();
507        local
508            .run_until(async {
509                // Tiny context window so the usage report crosses the threshold.
510                let (mut running, mut rx, mut ctrl, _conv) =
511                    start_system(vec![], Some(small_context_entry()));
512                running
513                    .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "hello")
514                    .await;
515                let _req = ctrl.next_request().await;
516                ctrl.send_text("hi there");
517                ctrl.finish_with_usage(high_usage());
518                collect_until_finished(&mut rx).await;
519
520                // The driver spawns a compaction child; close it with a summary.
521                let creq = ctrl.next_request().await;
522                assert!(is_compaction_req(&creq));
523                handle_compaction_child(&mut ctrl, &creq, "summary of everything");
524
525                // The parent eventually applies the compaction.
526                loop {
527                    if let Evt::E(AgentEvent::CompactionApplied) = next_evt(&mut rx).await {
528                        break;
529                    }
530                }
531                wait_idle(&mut running).await;
532            })
533            .await;
534    }
535}