Skip to main content

infinity_agent_core/system/local/
handle.rs

1//! Thread handles: the channel-based interface returned by [`ThreadBuilder`].
2//!
3//! A [`ThreadHandle`] sends inputs to one launched thread and receives its
4//! [`AgentEvent`]s after an initial [`ReplaySnapshot`]. The observer and
5//! subscription machinery in this module are internal to [`LaunchingSystem`].
6//!
7//! [`ThreadBuilder`]: super::ThreadBuilder
8//! [`LaunchingSystem`]: super::LaunchingSystem
9
10use rap_protocol::ThreadId;
11use std::cell::RefCell;
12use std::collections::HashMap;
13use std::rc::Rc;
14
15use async_trait::async_trait;
16use tokio::sync::{mpsc, oneshot};
17
18use crate::message::InputMessage;
19use crate::traits::InputSender;
20
21use super::router::RunningSystem;
22use super::sender::{ChannelSendError, ChannelSender};
23use crate::system::events::{AgentEvent, ReplaySnapshot};
24use crate::system::observer::ThreadObserver;
25
26/// The subscribe request used by [`HandleObserver`]: where to send the
27/// thread's live events, and a one-shot for the initial replay.
28pub(crate) struct HandleSubscribeRequest {
29    events_tx: mpsc::UnboundedSender<AgentEvent>,
30    replay_tx: oneshot::Sender<ReplaySnapshot>,
31}
32
33/// The built-in observer behind [`ThreadHandle`]s. The subscriber registry is
34/// shared across driver instances so handles survive driver idle and respawn.
35#[derive(Clone)]
36pub(crate) struct HandleObserver {
37    subscribers: Rc<RefCell<HashMap<ThreadId, Vec<mpsc::UnboundedSender<AgentEvent>>>>>,
38}
39
40#[async_trait(?Send)]
41impl ThreadObserver for HandleObserver {
42    type SubscribeRequest = HandleSubscribeRequest;
43
44    fn on_event(&self, thread_id: &ThreadId<str>, event: &AgentEvent) {
45        let mut subs = self.subscribers.borrow_mut();
46        if let Some(list) = subs.get_mut(thread_id) {
47            // Prune handles that have been dropped.
48            list.retain(|tx| tx.send(event.clone()).is_ok());
49            if list.is_empty() {
50                subs.remove(thread_id);
51            }
52        }
53    }
54
55    fn on_subscribe(
56        &self,
57        thread_id: &ThreadId<str>,
58        request: HandleSubscribeRequest,
59        snapshot: ReplaySnapshot,
60    ) {
61        // A dropped receiver just means the handle no longer wants the replay.
62        let _ = request.replay_tx.send(snapshot);
63        self.subscribers
64            .borrow_mut()
65            .entry(thread_id.to_owned())
66            .or_default()
67            .push(request.events_tx);
68    }
69}
70
71/// A live connection to one thread of a running local system: send it
72/// inputs and receive its events. Created by [`super::ThreadBuilder::launch`]
73/// or by reattaching through [`super::LaunchingSystem::thread_handle`].
74///
75/// Dropping the handle detaches it; the thread itself is unaffected.
76pub struct ThreadHandle {
77    thread_id: ThreadId,
78    sender: ChannelSender,
79    /// The thread's events, in emission order, starting from the moment the
80    /// handle attached. Every event is either reflected in
81    /// [`replay`](Self::replay) or delivered here, exactly once.
82    pub events: mpsc::UnboundedReceiver<AgentEvent>,
83    replay: ReplaySnapshot,
84}
85
86impl ThreadHandle {
87    /// The thread this handle is attached to.
88    pub fn thread_id(&self) -> &ThreadId<str> {
89        &self.thread_id
90    }
91
92    /// The state of the thread at the moment the handle attached: committed
93    /// history plus any in-flight turn and in-progress reasoning.
94    pub fn replay(&self) -> &ReplaySnapshot {
95        &self.replay
96    }
97
98    /// Receive the thread's next event. Returns `None` only after the system
99    /// has shut down.
100    pub async fn recv(&mut self) -> Option<AgentEvent> {
101        self.events.recv().await
102    }
103
104    /// Send plain user text to the thread.
105    pub async fn send_user_text(&self, text: impl Into<String>) -> Result<(), ChannelSendError> {
106        let msg = InputMessage::user_text(self.thread_id.clone(), text);
107        self.send(msg, &uuid::Uuid::new_v4().to_string()).await
108    }
109
110    /// Send an input message to the thread. The message's `group_id` is
111    /// overwritten with this handle's thread ID; `dedup_id` should be stable
112    /// across redeliveries of the same message.
113    pub async fn send(
114        &self,
115        mut message: InputMessage,
116        dedup_id: &str,
117    ) -> Result<(), ChannelSendError> {
118        message.group_id = self.thread_id.clone();
119        self.sender.send_to_input_queue(message, dedup_id).await
120    }
121}
122
123/// Subscribe to `thread_id` and package the subscription into a
124/// [`ThreadHandle`]. Callers must first establish that the thread was launched
125/// or already exists in the conversation store. Infallible: shutting a system
126/// down requires owning it, so a borrowed system's router is alive.
127pub(crate) async fn attach(
128    running: &RunningSystem<HandleSubscribeRequest>,
129    thread_id: &ThreadId<str>,
130) -> ThreadHandle {
131    let (events_tx, events) = mpsc::unbounded_channel();
132    let (replay_tx, replay_rx) = oneshot::channel();
133    let request = HandleSubscribeRequest {
134        events_tx,
135        replay_tx,
136    };
137    running.subscribe(thread_id, request).await;
138    // The subscribe ack is sent after `on_subscribe` runs, so the replay
139    // is already available.
140    let replay = replay_rx
141        .await
142        .expect("bug: subscribe acked without a replay");
143    ThreadHandle {
144        thread_id: thread_id.to_owned(),
145        sender: running.sender(),
146        events,
147        replay,
148    }
149}
150
151/// A per-system factory for [`HandleObserver`]s sharing one subscriber
152/// registry (so subscriptions survive driver respawns).
153pub(crate) fn handle_observer_factory() -> impl Fn(&ThreadId<str>) -> HandleObserver + 'static {
154    let subscribers: Rc<RefCell<HashMap<ThreadId, Vec<mpsc::UnboundedSender<AgentEvent>>>>> =
155        Default::default();
156    move |_thread_id| HandleObserver {
157        subscribers: subscribers.clone(),
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use crate::system::events::AgentEvent;
164    use crate::system::test_support::*;
165
166    #[tokio::test(flavor = "current_thread")]
167    async fn thread_handle_sends_inputs_and_receives_events() {
168        let local = tokio::task::LocalSet::new();
169        local
170            .run_until(async {
171                let (mut system, mut ctrl) = start_launcher_system(vec![], "");
172
173                let mut handle = system.thread_builder().launch().await;
174                let thread_id = handle.thread_id().to_owned();
175                assert!(handle.replay().history.is_empty(), "fresh thread");
176                assert!(!handle.replay().in_progress);
177
178                handle.send_user_text("hello").await.expect("send input");
179                let _req = ctrl.next_request().await;
180                ctrl.send_text("hi there");
181                ctrl.finish();
182                assert_eq!(handle_texts_until_finished(&mut handle).await, ["hi there"]);
183
184                // A handle attached after the exchange replays the history.
185                wait_idle(&mut system.running).await;
186                let late = system
187                    .thread_handle(&thread_id)
188                    .await
189                    .expect("load existing thread")
190                    .expect("launched thread exists");
191                assert!(
192                    !late.replay().history.is_empty(),
193                    "late handle sees committed history"
194                );
195                assert!(!late.replay().in_progress);
196            })
197            .await;
198    }
199
200    #[tokio::test(flavor = "current_thread")]
201    async fn thread_handle_survives_driver_respawn() {
202        let local = tokio::task::LocalSet::new();
203        local
204            .run_until(async {
205                let (mut system, mut ctrl) = start_launcher_system(vec![], "");
206
207                let mut handle = system.thread_builder().launch().await;
208                assert!(handle.replay().history.is_empty());
209                wait_idle(&mut system.running).await;
210                assert!(system.is_idle(), "launching alone does not keep a driver");
211
212                // The first message respawns the driver; the handle still
213                // receives every event.
214                handle.send_user_text("hello").await.expect("send input");
215                let _req = ctrl.next_request().await;
216                ctrl.send_text("first");
217                ctrl.finish();
218                assert_eq!(handle_texts_until_finished(&mut handle).await, ["first"]);
219
220                // And again across another idle/respawn cycle.
221                wait_idle(&mut system.running).await;
222                handle.send_user_text("more").await.expect("send input");
223                let _req = ctrl.next_request().await;
224                ctrl.send_text("second");
225                ctrl.finish();
226                assert_eq!(handle_texts_until_finished(&mut handle).await, ["second"]);
227            })
228            .await;
229    }
230
231    #[tokio::test(flavor = "current_thread")]
232    async fn dropped_thread_handle_is_pruned_and_others_keep_receiving() {
233        let local = tokio::task::LocalSet::new();
234        local
235            .run_until(async {
236                let (system, mut ctrl) = start_launcher_system(vec![], "");
237
238                let dropped = system.thread_builder().launch().await;
239                let mut kept = system
240                    .thread_handle(dropped.thread_id())
241                    .await
242                    .expect("load launched thread")
243                    .expect("launched thread exists");
244                drop(dropped);
245
246                kept.send_user_text("hello").await.expect("send input");
247                let _req = ctrl.next_request().await;
248                ctrl.send_text("still here");
249                ctrl.finish();
250                assert_eq!(handle_texts_until_finished(&mut kept).await, ["still here"]);
251            })
252            .await;
253    }
254
255    /// The consumption contract of a [`ThreadHandle`] event stream:
256    /// `CompletionFinished` ends one *round*, not the conversation. A round that
257    /// finished with a tool call means more events are coming (the tool result
258    /// and the follow-up round), so a consumer keeps pulling until a round
259    /// finishes without a pending tool call.
260    #[tokio::test(flavor = "current_thread")]
261    async fn thread_handle_streams_across_tool_call_rounds() {
262        /// The significant events of this scenario, in stream order.
263        #[derive(Debug, PartialEq)]
264        enum Tag {
265            UserInput(String),
266            ToolCall(String),
267            ToolResult(String),
268            TextChunk(String),
269            CompletionFinished,
270        }
271        fn tag(event: AgentEvent) -> Option<Tag> {
272            match event {
273                AgentEvent::UserInput { text } => Some(Tag::UserInput(text)),
274                AgentEvent::ToolCall { name, .. } => Some(Tag::ToolCall(name)),
275                AgentEvent::ToolResult { segments } => segments.iter().find_map(|s| {
276                    if let rap_protocol::DisplaySegment::Text(t) = s {
277                        Some(Tag::ToolResult(t.clone()))
278                    } else {
279                        None
280                    }
281                }),
282                AgentEvent::TextChunk { text } => Some(Tag::TextChunk(text)),
283                AgentEvent::CompletionFinished { .. } => Some(Tag::CompletionFinished),
284                _ => None,
285            }
286        }
287        /// Pull tagged events until (and including) the next `CompletionFinished`.
288        async fn collect_round(handle: &mut super::ThreadHandle) -> Vec<Tag> {
289            let mut tags = Vec::new();
290            loop {
291                let event = tokio::time::timeout(std::time::Duration::from_secs(5), handle.recv())
292                    .await
293                    .expect("timed out waiting for a handle event")
294                    .expect("handle event channel closed");
295                if let Some(t) = tag(event) {
296                    let done = t == Tag::CompletionFinished;
297                    tags.push(t);
298                    if done {
299                        return tags;
300                    }
301                }
302            }
303        }
304
305        let local = tokio::task::LocalSet::new();
306        local
307            .run_until(async {
308                let (mut system, mut ctrl) = start_launcher_system(vec![Box::new(AsyncTool)], "");
309                let mut handle = system.thread_builder().launch().await;
310                let thread_id = handle.thread_id().to_owned();
311
312                // Round 1: the model answers the user with a tool call.
313                handle.send_user_text("use tool").await.expect("send input");
314                let _req = ctrl.next_request().await;
315                ctrl.send_tool_call("tc-1", "async_tool", serde_json::json!({}));
316                ctrl.finish();
317
318                let round1 = collect_round(&mut handle).await;
319                assert_eq!(
320                    round1,
321                    vec![
322                        Tag::UserInput("use tool".into()),
323                        Tag::ToolCall("async_tool".into()),
324                        Tag::CompletionFinished,
325                    ],
326                    "round 1 ends at a CompletionFinished whose round issued a tool call"
327                );
328                assert!(
329                    !system.is_idle(),
330                    "the thread is waiting on the tool result"
331                );
332
333                // The stream did not stop: the tool result arrives later and
334                // starts round 2.
335                handle
336                    .send(
337                        tool_result_input(thread_id.as_str(), "tc-1", "tool done").0,
338                        "res-1",
339                    )
340                    .await
341                    .expect("send tool result");
342                let _req = ctrl.next_request().await;
343                ctrl.send_text("all done");
344                ctrl.finish();
345
346                let round2 = collect_round(&mut handle).await;
347                assert_eq!(
348                    round2,
349                    vec![
350                        Tag::ToolResult("tool done".into()),
351                        Tag::TextChunk("all done".into()),
352                        Tag::CompletionFinished,
353                    ],
354                    "round 2 delivers the tool result echo and the follow-up text"
355                );
356
357                // A round that finished without a pending tool call: the thread
358                // idles out and the consumer is done.
359                wait_idle(&mut system.running).await;
360            })
361            .await;
362    }
363}