Skip to main content

infinity_agent_core/system/
thread.rs

1//! [`Thread`]: a handle to one conversation thread, with a step-oriented
2//! execution API.
3
4use rap_protocol::ThreadId;
5use std::cell::{Cell, RefCell};
6use std::collections::{HashMap, HashSet};
7use std::rc::Rc;
8
9use futures_util::StreamExt;
10use infinity_provider_protocol::message::{ToolResultContent, UserContent};
11use infinity_provider_protocol::{ToolDefinition, Usage};
12use tokio::sync::oneshot;
13
14use crate::event_processor::{self, CompletionAction, CompletionEvent, HistoryManager};
15use crate::message::{InputMessage, InputMessageContent, SyntheticKind, TaggedSyntheticKind};
16use crate::tools::{Tool, ToolContext};
17use crate::traits::{ConversationStore, InputSender, StateStore};
18use rap_client::http::HttpClient;
19
20use super::builder::SystemInner;
21use super::defer::DeferQueue;
22use super::events::{AgentEvent, ReplaySnapshot, UserChoice};
23use super::observer::ThreadObserver;
24
25type BoxError = Box<dyn std::error::Error + Send + Sync>;
26
27/// The name of the built-in thread-closing tool. An unanswered call to it
28/// never receives a result (the thread is closed), so it does not count as
29/// "waiting for a tool result".
30const CLOSE_THREAD_TOOL: &str = "close_thread";
31
32/// The result of one step (see [`AgentSystem::step`](super::AgentSystem::step)).
33#[derive(Debug)]
34pub enum StepOutcome {
35    /// No input was actionable — no completion ran. (Deferred, duplicate, or
36    /// out-of-band inputs such as OAuth challenges land here.)
37    Skipped,
38    /// A completion round ran (it may have dispatched a tool call, which will
39    /// deliver its result as a later input).
40    Completed {
41        /// Token usage reported by the provider, if any.
42        usage: Option<Usage>,
43        /// The context window of the model that ran the round (`0` when
44        /// unknown). Useful for compaction thresholds.
45        context_window: usize,
46    },
47}
48
49/// Whether this input is a plain user text message (as opposed to a tool
50/// result or synthetic event). User text deliberately interrupts pending
51/// work.
52pub fn is_user_text_input(msg: &InputMessage) -> bool {
53    msg.synthetic.is_none()
54        && matches!(
55            &msg.content,
56            InputMessageContent::User(UserContent::Text(_))
57        )
58}
59
60/// Whether this input is a synthetic event that can be deferred while the
61/// thread waits on a pending tool call (subscription events, thread reports,
62/// parent messages).
63pub fn is_deferrable_synthetic_event(msg: &InputMessage) -> bool {
64    msg.synthetic.as_ref().is_some_and(|s| {
65        matches!(
66            s,
67            SyntheticKind::Tagged(
68                TaggedSyntheticKind::SubscriptionEvent { .. }
69                    | TaggedSyntheticKind::ThreadReport { .. }
70                    | TaggedSyntheticKind::ParentMessage { .. }
71            ) | SyntheticKind::SubscriptionEvent(_)
72        )
73    })
74}
75
76/// A thread's resolved configuration: [`ThreadConfig`] tools plus the
77/// built-in thread/subscription tools.
78struct ResolvedConfig<M: InputSender, H: HttpClient> {
79    tools: Vec<Rc<dyn Tool<M>>>,
80    extra_system_prompt: Option<String>,
81    rap_notifier: Option<rap_client::notifier::RapNotifier<H>>,
82}
83
84/// A handle to one conversation thread of an [`AgentSystem`](super::AgentSystem).
85///
86/// A `Thread` owns the thread's in-memory [`HistoryManager`] and executes
87/// **steps**: one step prepares a batch of input messages, runs at most one
88/// completion round, commits the results durably, and dispatches at most one
89/// asynchronous tool call. Between steps the thread holds no in-flight work,
90/// which is what lets serverless embeddings drop it entirely (a later slice
91/// reloads it from the stores) and resident embeddings park it on a channel.
92///
93/// The thread's configuration (tools, prompt, notifier) is resolved lazily
94/// on the first step rather than at load, so loading a thread for replay or
95/// subscription does not touch (or boot) its tool servers.
96pub struct Thread<C: ConversationStore, S: StateStore, M: InputSender, H: HttpClient> {
97    inner: Rc<SystemInner<C, S, M, H>>,
98    history: HistoryManager<C, S>,
99    /// Lazily resolved per-thread configuration (see
100    /// [`resolved_config`](Self::resolved_config)).
101    config: RefCell<Option<Rc<ResolvedConfig<M, H>>>>,
102    /// In-progress (uncommitted) reasoning text, for replay snapshots.
103    current_thinking: RefCell<Option<String>>,
104    /// Whether a completion round is currently streaming.
105    in_flight: Cell<bool>,
106    /// Pending choices loaded from and kept in sync with this thread's state entry.
107    pending_choices: RefCell<Vec<UserChoice>>,
108}
109
110impl<C, S, M, H> Thread<C, S, M, H>
111where
112    C: ConversationStore + 'static,
113    S: StateStore + 'static,
114    M: InputSender + 'static,
115    H: HttpClient + 'static,
116{
117    pub(crate) async fn load(
118        inner: Rc<SystemInner<C, S, M, H>>,
119        thread_id: ThreadId,
120    ) -> Result<Self, BoxError> {
121        let history = HistoryManager::new_with_history(
122            inner.conversation_store.clone(),
123            inner.state_store.clone(),
124            thread_id,
125        )
126        .await?;
127        let pending_choices = inner
128            .state_store
129            .get_pending_user_choices(&history.thread_id)
130            .await?;
131        Ok(Self {
132            inner,
133            history,
134            config: RefCell::new(None),
135            current_thinking: RefCell::new(None),
136            in_flight: Cell::new(false),
137            pending_choices: RefCell::new(pending_choices),
138        })
139    }
140
141    /// Resolve (once) this thread's configuration and append the built-in
142    /// tools to it.
143    async fn resolved_config(&self) -> Result<Rc<ResolvedConfig<M, H>>, BoxError> {
144        if let Some(config) = self.config.borrow().clone() {
145            return Ok(config);
146        }
147        let config = self.inner.config.resolve(&self.history.thread_id).await?;
148        let mut tools = config.tools;
149        if self.inner.builtin_tools {
150            tools.push(Rc::new(crate::tools::thread::SpawnThreadTool {
151                conversation_store: self.inner.conversation_store.clone(),
152            }));
153            tools.push(Rc::new(crate::tools::thread::ReportToParentTool {
154                conversation_store: self.inner.conversation_store.clone(),
155            }));
156            tools.push(Rc::new(crate::tools::thread::CloseThreadTool {
157                conversation_store: self.inner.conversation_store.clone(),
158                rap_notifier: config.rap_notifier.clone(),
159            }));
160            tools.push(Rc::new(crate::tools::thread::SendMessageToChildTool {
161                conversation_store: self.inner.conversation_store.clone(),
162            }));
163            tools.push(Rc::new(
164                crate::tools::cancel_subscription::CancelSubscriptionTool {
165                    state_store: self.inner.state_store.clone(),
166                    rap_notifier: config.rap_notifier.clone(),
167                },
168            ));
169            tools.push(Rc::new(crate::tools::sleep::SleepUntilEventOrInputTool));
170        }
171        if self.inner.tokio_sleep_tools {
172            tools.push(Rc::new(crate::tools::sleep::TokioSleepTool));
173            tools.push(Rc::new(crate::tools::sleep::TokioSleepUntilTool));
174        }
175        let resolved = Rc::new(ResolvedConfig {
176            tools,
177            extra_system_prompt: config.extra_system_prompt,
178            rap_notifier: config.rap_notifier,
179        });
180        *self.config.borrow_mut() = Some(resolved.clone());
181        Ok(resolved)
182    }
183
184    /// A live view of the thread for bringing a new subscriber up to date:
185    /// committed history plus the in-flight turn, the in-progress reasoning
186    /// text, and whether a completion is currently streaming.
187    pub fn replay_snapshot(&self) -> ReplaySnapshot {
188        ReplaySnapshot {
189            history: self.history.current_turn_view(),
190            current_thinking: self.current_thinking.borrow().clone(),
191            in_progress: self.in_flight.get(),
192            pending_choices: self.pending_choices.borrow().clone(),
193        }
194    }
195
196    /// If the last history entry is an unanswered tool call, its
197    /// `(tool_call_id, tool_name)`.
198    pub fn pending_tool_call(&self) -> Option<(String, String)> {
199        self.history.history.borrow().last().and_then(|msg| {
200            if let crate::message::InfinityMessage::ToolCall { call, .. } = msg {
201                Some((call.id.clone(), call.function.name.clone()))
202            } else {
203                None
204            }
205        })
206    }
207
208    /// The thread is waiting for the result of a dispatched tool call whose
209    /// tool represents in-flight work (i.e. it is not a passive tool like the
210    /// sleep family). While this is `Some`, deferrable synthetic events must
211    /// not be processed — doing so would inject an "interrupted" result for
212    /// a call that is actually still running.
213    ///
214    /// If the thread's configuration has not been resolved yet (no step has
215    /// run), the call is conservatively treated as active.
216    pub fn pending_active_tool_call(&self) -> Option<String> {
217        let (id, name) = self.pending_tool_call()?;
218        let passive = self.config.borrow().as_ref().is_some_and(|config| {
219            config
220                .tools
221                .iter()
222                .find(|t| t.name() == name)
223                .is_some_and(|t| t.is_passive())
224        });
225        if passive { None } else { Some(id) }
226    }
227
228    /// Whether the thread must stay resident: the result of an unanswered
229    /// tool call (other than `close_thread`, whose result never arrives) is
230    /// still on its way. Active subscriptions do not keep a thread resident;
231    /// their events wake it through the router when they arrive.
232    ///
233    /// Synchronous so a driver can make its exit decision atomically with
234    /// respect to the router on the shared `LocalSet`.
235    pub fn awaiting_tool_result(&self) -> bool {
236        self.pending_tool_call()
237            .is_some_and(|(_, name)| name != CLOSE_THREAD_TOOL)
238    }
239
240    /// Apply the deferral policy to a batch of inputs.
241    ///
242    /// While the thread waits on a pending active tool call, deferrable
243    /// synthetic events are pushed into `defer` (unless the batch itself
244    /// settles the pending call — via its actual result or an interrupting
245    /// user message). When the thread can process deferred events, they are
246    /// drained and appended after the incoming batch. Returns the batch that
247    /// should be passed to [`step`](Self::step).
248    pub async fn filter_deferrable<D: DeferQueue>(
249        &self,
250        inputs: Vec<(InputMessage, String)>,
251        defer: &mut D,
252    ) -> Result<Vec<(InputMessage, String)>, BoxError> {
253        // Deferral decisions depend on tool passivity, so resolve the
254        // thread's configuration if it hasn't been yet.
255        self.resolved_config().await?;
256        let Some(pending_call_id) = self.pending_active_tool_call() else {
257            let mut batch = inputs;
258            batch.extend(defer.drain().await?);
259            return Ok(batch);
260        };
261
262        // Flushing is safe when the batch itself settles the pending call
263        // first: either it contains the call's actual tool result, or a user
264        // text input (which deliberately interrupts the pending call). Batch
265        // items are processed before drained deferred items, so ordering is
266        // preserved.
267        let settles_pending = inputs.iter().any(|(msg, _)| {
268            is_user_text_input(msg)
269                || (msg.synthetic.is_none()
270                    && matches!(
271                        &msg.content,
272                        InputMessageContent::User(UserContent::ToolResult(r))
273                            if r.id == pending_call_id
274                    ))
275        });
276
277        if settles_pending {
278            let mut batch = inputs;
279            batch.extend(defer.drain().await?);
280            return Ok(batch);
281        }
282
283        let mut batch = Vec::new();
284        for (msg, id) in inputs {
285            if is_deferrable_synthetic_event(&msg) && defer.push(msg.clone(), id.clone()).await? {
286                continue;
287            }
288            batch.push((msg, id));
289        }
290        Ok(batch)
291    }
292
293    /// Prepare a single input message into history, emitting the
294    /// corresponding events. Returns `true` when the input is actionable
295    /// (a completion should run). Errors from the observer's durability
296    /// hooks fail the step; errors from input preparation itself are
297    /// surfaced as [`AgentEvent::Info`].
298    async fn prepare_one<O: ThreadObserver>(
299        &self,
300        input_msg: InputMessage,
301        message_id: String,
302        observer: &O,
303    ) -> Result<bool, BoxError> {
304        let thread_id = self.history.thread_id.clone();
305        let prepare_result = event_processor::prepare_input(
306            input_msg.clone(),
307            message_id,
308            &self.history,
309            &self.inner.conversation_store,
310            &self.inner.sender,
311        )
312        .await;
313
314        match prepare_result {
315            Ok(event_processor::PrepareResult::Handled) => Ok(false),
316            Ok(event_processor::PrepareResult::CompactionApplied) => {
317                observer.on_event(&thread_id, &AgentEvent::CompactionApplied);
318                Ok(false)
319            }
320            Ok(event_processor::PrepareResult::OAuthRequired { auth_url }) => {
321                observer.on_event(&thread_id, &AgentEvent::OAuthRequired { auth_url });
322                Ok(false)
323            }
324            Ok(event_processor::PrepareResult::UserChoiceRequired {
325                id,
326                prompt,
327                choices,
328                default,
329                response_url,
330            }) => {
331                let choice = UserChoice {
332                    id,
333                    prompt,
334                    choices,
335                    default,
336                    response_url,
337                };
338                self.inner
339                    .state_store
340                    .add_pending_user_choice(&thread_id, choice.clone())
341                    .await?;
342                {
343                    let mut pending = self.pending_choices.borrow_mut();
344                    if let Some(existing) = pending.iter_mut().find(|c| c.id == choice.id) {
345                        *existing = choice.clone();
346                    } else {
347                        pending.push(choice.clone());
348                    }
349                }
350                observer.on_event(&thread_id, &AgentEvent::UserChoiceRequired { choice });
351                Ok(false)
352            }
353            Err(e) => {
354                observer.on_event(
355                    &thread_id,
356                    &AgentEvent::Info {
357                        text: format!("Error: {}", e),
358                    },
359                );
360                Ok(false)
361            }
362            Ok(event_processor::PrepareResult::Ready) => {
363                self.emit_input_echo(&input_msg, observer, &thread_id);
364                if let InputMessageContent::User(UserContent::ToolResult(result)) =
365                    &input_msg.content
366                    && self
367                        .pending_choices
368                        .borrow()
369                        .iter()
370                        .any(|choice| choice.id.as_str() == result.id)
371                {
372                    self.inner
373                        .state_store
374                        .remove_pending_user_choice(
375                            &thread_id,
376                            rap_protocol::ChoiceId::from_ref(&result.id),
377                        )
378                        .await?;
379                    self.pending_choices
380                        .borrow_mut()
381                        .retain(|choice| choice.id.as_str() != result.id);
382                    observer.on_event(
383                        &thread_id,
384                        &AgentEvent::UserChoiceDismissed {
385                            choice_id: rap_protocol::ChoiceId::from(result.id.clone()),
386                        },
387                    );
388                }
389                Ok(true)
390            }
391        }
392    }
393
394    /// Emit the event describing an accepted input: a subscription event or
395    /// thread report, an incoming tool result, or user text. The event itself
396    /// is computed by the shared [`event_processor::input_event`].
397    fn emit_input_echo<O: ThreadObserver>(
398        &self,
399        input_msg: &InputMessage,
400        observer: &O,
401        thread_id: &ThreadId<str>,
402    ) {
403        if let Some(event) = event_processor::input_event(&self.history, input_msg) {
404            observer.on_event(thread_id, &event);
405        }
406    }
407
408    /// Execute one step over a batch that has **not** been run through the
409    /// deferral policy: prepare `inputs` into history, run at most one
410    /// completion round, commit durably, and dispatch at most one
411    /// asynchronous tool call. Callers are expected to apply
412    /// [`filter_deferrable`](Self::filter_deferrable) first.
413    ///
414    /// Events are delivered to `observer` synchronously as they occur; the
415    /// turn is synced to the conversation store before the tool call (if
416    /// any) is dispatched.
417    ///
418    /// `cancel` aborts the completion stream early (user interruption). The
419    /// cancelled step still flushes and commits whatever streamed before the
420    /// cancellation. **Note:** dropping the paired sender counts as
421    /// cancellation, so callers that don't intend to cancel must keep the
422    /// sender alive for the duration of the step.
423    pub async fn step_no_defer<O: ThreadObserver>(
424        &self,
425        inputs: Vec<(InputMessage, String)>,
426        observer: &O,
427        cancel: oneshot::Receiver<()>,
428    ) -> Result<StepOutcome, BoxError> {
429        let thread_id = self.history.thread_id.clone();
430        // Resolve the thread's configuration before anything observable
431        // happens (interruption notifications below already need the
432        // notifier; a completion needs the tools).
433        let config = self.resolved_config().await?;
434
435        // ── Prepare phase: fold each input into history ──
436        let mut any_ready = false;
437        let mut last_message_id = String::new();
438        for (input_msg, message_id) in inputs {
439            if self
440                .prepare_one(input_msg, message_id.clone(), observer)
441                .await?
442            {
443                any_ready = true;
444                last_message_id = message_id;
445            }
446        }
447
448        // Best-effort: notify RAP tool servers about interrupted tool calls.
449        // Dismissing the associated pending user choices is a durable state
450        // transition: it is awaited before the step continues, so the agent
451        // cannot proceed past an interruption whose dismissal has not been
452        // persisted.
453        let interrupted = self.history.take_interrupted_tool_calls();
454        if !interrupted.is_empty() {
455            if let Some(notifier) = config.rap_notifier.as_ref() {
456                for call_id in &interrupted {
457                    notifier.notify_tool_cancelled(&thread_id, call_id).await;
458                }
459            }
460            for call_id in interrupted {
461                self.inner
462                    .state_store
463                    .remove_pending_user_choice(&thread_id, &call_id)
464                    .await?;
465                self.pending_choices
466                    .borrow_mut()
467                    .retain(|choice| choice.id != call_id);
468                observer.on_event(
469                    &thread_id,
470                    &AgentEvent::UserChoiceDismissed { choice_id: call_id },
471                );
472            }
473        }
474
475        if !any_ready {
476            // Commit anything already known-safe (e.g. processed IDs from
477            // deduped inputs). Interruption results and other fresh inputs
478            // stay unvalidated — and unpersisted — until a completion
479            // produces model output for them.
480            self.history.sync().await?;
481            return Ok(StepOutcome::Skipped);
482        }
483
484        // ── Completion phase ──
485        let model = self.inner.model.resolve(&thread_id).await?;
486
487        let tool_names: HashSet<String> =
488            config.tools.iter().map(|t| t.name().to_owned()).collect();
489        let tool_defs: Vec<ToolDefinition> = config
490            .tools
491            .iter()
492            .map(|t| ToolDefinition {
493                name: t.name().to_owned(),
494                description: t.description().to_owned(),
495                parameters: t.parameters(),
496            })
497            .collect();
498        let tool_registry: HashMap<String, &dyn Tool<M>> = config
499            .tools
500            .iter()
501            .map(|t| (t.name().to_owned(), t.as_ref()))
502            .collect();
503
504        let user_id = self
505            .history
506            .get_metadata()
507            .and_then(|m| m.get("user_id").and_then(|v| v.as_str()).map(String::from));
508        let tool_context = ToolContext {
509            message_sender: self.inner.sender.clone(),
510            group_id: thread_id.clone(),
511            callback_url: self.inner.callback_url.clone(),
512            user_id,
513            thread_stack: self.history.get_thread_stack(),
514            // Stamped per-call during synchronous tool execution (see
515            // `run_completion`); meaningless at step scope.
516            safe_spawn_point: None,
517        };
518
519        observer.on_event(&thread_id, &AgentEvent::CompletionStarted);
520        self.in_flight.set(true);
521
522        let mut action = None;
523        let mut usage: Option<Usage> = None;
524        {
525            let mut stream = std::pin::pin!(event_processor::run_completion(
526                model.provider.as_ref(),
527                &model.model_id,
528                model.supports_image_input,
529                &self.history,
530                &tool_names,
531                &tool_defs,
532                &tool_registry,
533                &tool_context,
534                &thread_id,
535                &last_message_id,
536                config.extra_system_prompt.as_deref(),
537                cancel,
538            ));
539
540            while let Some(ev) = stream.next().await {
541                match ev {
542                    Ok(event) => self.handle_completion_event(
543                        event,
544                        observer,
545                        &thread_id,
546                        &mut action,
547                        &mut usage,
548                    ),
549                    Err(e) => {
550                        observer.on_event(
551                            &thread_id,
552                            &AgentEvent::Info {
553                                text: format!("Error: {}", e),
554                            },
555                        );
556                        break;
557                    }
558                }
559            }
560        }
561        self.in_flight.set(false);
562        *self.current_thinking.borrow_mut() = None;
563
564        // ── Commit phase: the turn becomes durable before anything external
565        // can react to it. ──
566        self.history.sync().await?;
567        observer.on_event(&thread_id, &AgentEvent::CompletionFinished { usage });
568
569        // ── Dispatch phase: fire the tool call (if any) after the commit
570        // barrier, so the call is durable in history before its result can
571        // possibly arrive. A failed dispatch enqueues an error tool result
572        // so the agent recovers instead of waiting forever. ──
573        if let Some(action) = action
574            && let Err(e) = event_processor::execute_action_with_error_result(
575                action,
576                &tool_registry,
577                &tool_context,
578            )
579            .await
580        {
581            observer.on_event(
582                &thread_id,
583                &AgentEvent::Info {
584                    text: format!("Error: {}", e),
585                },
586            );
587        }
588
589        Ok(StepOutcome::Completed {
590            usage,
591            context_window: model.context_window,
592        })
593    }
594
595    fn handle_completion_event(
596        &self,
597        event: CompletionEvent,
598        observer: &impl ThreadObserver,
599        thread_id: &ThreadId<str>,
600        action: &mut Option<CompletionAction>,
601        usage: &mut Option<Usage>,
602    ) {
603        match event {
604            CompletionEvent::Info(text) => {
605                observer.on_event(thread_id, &AgentEvent::Info { text });
606            }
607            CompletionEvent::TextChunk(text) => {
608                *self.current_thinking.borrow_mut() = None;
609                observer.on_event(thread_id, &AgentEvent::TextChunk { text });
610            }
611            CompletionEvent::ThinkingStart => {
612                *self.current_thinking.borrow_mut() = None;
613                observer.on_event(thread_id, &AgentEvent::ThinkingStarted);
614            }
615            CompletionEvent::ThinkingEnd => {
616                *self.current_thinking.borrow_mut() = None;
617                observer.on_event(thread_id, &AgentEvent::ThinkingEnded);
618            }
619            CompletionEvent::ThinkingChunk(text) => {
620                self.current_thinking
621                    .borrow_mut()
622                    .get_or_insert_default()
623                    .push_str(&text);
624                observer.on_event(thread_id, &AgentEvent::ThinkingChunk { text });
625            }
626            CompletionEvent::SyncToolCall {
627                tool_name,
628                tool_args,
629                display_as,
630            } => {
631                *self.current_thinking.borrow_mut() = None;
632                observer.on_event(
633                    thread_id,
634                    &AgentEvent::ToolCall {
635                        name: tool_name,
636                        args: tool_args,
637                        display_as,
638                    },
639                );
640            }
641            CompletionEvent::SyncToolResult(res) => {
642                *self.current_thinking.borrow_mut() = None;
643                if let Some(ToolResultContent::Text(text)) = res.content.first() {
644                    observer.on_event(
645                        thread_id,
646                        &AgentEvent::ToolResult {
647                            segments: vec![rap_protocol::DisplaySegment::Text(text.text.clone())],
648                        },
649                    );
650                }
651            }
652            CompletionEvent::Action(CompletionAction::Done(r)) => {
653                // There may be multiple `Done` if the agent synchronously
654                // loops back; the last one carries the round's final usage.
655                *self.current_thinking.borrow_mut() = None;
656                if let Some(u) = r.usage {
657                    *usage = Some(u);
658                }
659            }
660            CompletionEvent::Action(a) => {
661                if let CompletionAction::ExecuteToolCall {
662                    ref tool_name,
663                    ref tool_args,
664                    ref display_as,
665                    ..
666                } = a
667                {
668                    *self.current_thinking.borrow_mut() = None;
669                    observer.on_event(
670                        thread_id,
671                        &AgentEvent::ToolCall {
672                            name: tool_name.clone(),
673                            args: tool_args.clone(),
674                            display_as: display_as.clone(),
675                        },
676                    );
677                }
678                assert!(action.is_none(), "bug: multiple terminal actions");
679                *action = Some(a);
680            }
681        }
682    }
683}
684#[cfg(test)]
685mod tests {
686    use crate::system::test_support::*;
687
688    /// A tool call whose dispatch fails must feed an error result back to the
689    /// agent (as a new input through the loopback queue) instead of leaving the
690    /// thread waiting forever on a result that will never come.
691    #[tokio::test(flavor = "current_thread")]
692    async fn failed_tool_dispatch_returns_error_result_to_agent() {
693        let local = tokio::task::LocalSet::new();
694        local
695            .run_until(async {
696                let (mut running, mut rx, mut ctrl, _conv) =
697                    start_system(vec![Box::new(FailingTool)], None);
698                running
699                    .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "use tool")
700                    .await;
701                let _req = ctrl.next_request().await;
702                ctrl.send_tool_call("call-1", "failing_tool", serde_json::json!({}));
703                ctrl.finish();
704
705                // The dispatch failure enqueues a fallback error result, which
706                // wakes the thread for a second completion round.
707                let req2 = ctrl.next_request().await;
708                assert!(
709                    tool_result_texts(&req2)
710                        .iter()
711                        .any(|t| t.contains("Error: Tool call failed")),
712                    "second round should see the fallback error tool result"
713                );
714                ctrl.send_text("recovered");
715                ctrl.finish();
716
717                collect_until_finished(&mut rx).await; // round 1
718                let texts = collect_until_finished(&mut rx).await; // round 2
719                assert_eq!(texts, vec!["recovered"]);
720                wait_idle(&mut running).await;
721            })
722            .await;
723    }
724}