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 == result.id)
371                {
372                    self.inner
373                        .state_store
374                        .remove_pending_user_choice(&thread_id, &result.id)
375                        .await?;
376                    self.pending_choices
377                        .borrow_mut()
378                        .retain(|choice| choice.id != result.id);
379                    observer.on_event(
380                        &thread_id,
381                        &AgentEvent::UserChoiceDismissed {
382                            choice_id: result.id.clone(),
383                        },
384                    );
385                }
386                Ok(true)
387            }
388        }
389    }
390
391    /// Emit the event describing an accepted input: a subscription event or
392    /// thread report, an incoming tool result, or user text. The event itself
393    /// is computed by the shared [`event_processor::input_event`].
394    fn emit_input_echo<O: ThreadObserver>(
395        &self,
396        input_msg: &InputMessage,
397        observer: &O,
398        thread_id: &ThreadId<str>,
399    ) {
400        if let Some(event) = event_processor::input_event(&self.history, input_msg) {
401            observer.on_event(thread_id, &event);
402        }
403    }
404
405    /// Execute one step over a batch that has **not** been run through the
406    /// deferral policy: prepare `inputs` into history, run at most one
407    /// completion round, commit durably, and dispatch at most one
408    /// asynchronous tool call. Callers are expected to apply
409    /// [`filter_deferrable`](Self::filter_deferrable) first.
410    ///
411    /// Events are delivered to `observer` synchronously as they occur; the
412    /// turn is synced to the conversation store before the tool call (if
413    /// any) is dispatched.
414    ///
415    /// `cancel` aborts the completion stream early (user interruption). The
416    /// cancelled step still flushes and commits whatever streamed before the
417    /// cancellation. **Note:** dropping the paired sender counts as
418    /// cancellation, so callers that don't intend to cancel must keep the
419    /// sender alive for the duration of the step.
420    pub async fn step_no_defer<O: ThreadObserver>(
421        &self,
422        inputs: Vec<(InputMessage, String)>,
423        observer: &O,
424        cancel: oneshot::Receiver<()>,
425    ) -> Result<StepOutcome, BoxError> {
426        let thread_id = self.history.thread_id.clone();
427        // Resolve the thread's configuration before anything observable
428        // happens (interruption notifications below already need the
429        // notifier; a completion needs the tools).
430        let config = self.resolved_config().await?;
431
432        // ── Prepare phase: fold each input into history ──
433        let mut any_ready = false;
434        let mut last_message_id = String::new();
435        for (input_msg, message_id) in inputs {
436            if self
437                .prepare_one(input_msg, message_id.clone(), observer)
438                .await?
439            {
440                any_ready = true;
441                last_message_id = message_id;
442            }
443        }
444
445        // Best-effort: notify RAP tool servers about interrupted tool calls.
446        // Dismissing the associated pending user choices is a durable state
447        // transition: it is awaited before the step continues, so the agent
448        // cannot proceed past an interruption whose dismissal has not been
449        // persisted.
450        let interrupted = self.history.take_interrupted_tool_calls();
451        if !interrupted.is_empty() {
452            if let Some(notifier) = config.rap_notifier.as_ref() {
453                for call_id in &interrupted {
454                    notifier.notify_tool_cancelled(&thread_id, call_id).await;
455                }
456            }
457            for call_id in interrupted {
458                self.inner
459                    .state_store
460                    .remove_pending_user_choice(&thread_id, &call_id)
461                    .await?;
462                self.pending_choices
463                    .borrow_mut()
464                    .retain(|choice| choice.id != call_id);
465                observer.on_event(
466                    &thread_id,
467                    &AgentEvent::UserChoiceDismissed { choice_id: call_id },
468                );
469            }
470        }
471
472        if !any_ready {
473            // Commit anything prepare persisted (processed IDs, interruption
474            // results) even though no completion runs.
475            self.history.sync().await?;
476            return Ok(StepOutcome::Skipped);
477        }
478
479        // ── Completion phase ──
480        let model = self.inner.model.resolve(&thread_id).await?;
481
482        let tool_names: HashSet<String> =
483            config.tools.iter().map(|t| t.name().to_owned()).collect();
484        let tool_defs: Vec<ToolDefinition> = config
485            .tools
486            .iter()
487            .map(|t| ToolDefinition {
488                name: t.name().to_owned(),
489                description: t.description().to_owned(),
490                parameters: t.parameters(),
491            })
492            .collect();
493        let tool_registry: HashMap<String, &dyn Tool<M>> = config
494            .tools
495            .iter()
496            .map(|t| (t.name().to_owned(), t.as_ref()))
497            .collect();
498
499        let user_id = self
500            .history
501            .get_metadata()
502            .and_then(|m| m.get("user_id").and_then(|v| v.as_str()).map(String::from));
503        let tool_context = ToolContext {
504            message_sender: self.inner.sender.clone(),
505            group_id: thread_id.clone(),
506            callback_url: self.inner.callback_url.clone(),
507            user_id,
508            thread_stack: self.history.get_thread_stack(),
509        };
510
511        observer.on_event(&thread_id, &AgentEvent::CompletionStarted);
512        self.in_flight.set(true);
513
514        let mut action = None;
515        let mut usage: Option<Usage> = None;
516        {
517            let mut stream = std::pin::pin!(event_processor::run_completion(
518                model.provider.as_ref(),
519                &model.model_id,
520                model.supports_image_input,
521                &self.history,
522                &tool_names,
523                &tool_defs,
524                &tool_registry,
525                &tool_context,
526                &thread_id,
527                &last_message_id,
528                config.extra_system_prompt.as_deref(),
529                cancel,
530            ));
531
532            while let Some(ev) = stream.next().await {
533                match ev {
534                    Ok(event) => self.handle_completion_event(
535                        event,
536                        observer,
537                        &thread_id,
538                        &mut action,
539                        &mut usage,
540                    ),
541                    Err(e) => {
542                        observer.on_event(
543                            &thread_id,
544                            &AgentEvent::Info {
545                                text: format!("Error: {}", e),
546                            },
547                        );
548                        break;
549                    }
550                }
551            }
552        }
553        self.in_flight.set(false);
554        *self.current_thinking.borrow_mut() = None;
555
556        // ── Commit phase: the turn becomes durable before anything external
557        // can react to it. ──
558        self.history.sync().await?;
559        observer.on_event(&thread_id, &AgentEvent::CompletionFinished { usage });
560
561        // ── Dispatch phase: fire the tool call (if any) after the commit
562        // barrier, so the call is durable in history before its result can
563        // possibly arrive. A failed dispatch enqueues an error tool result
564        // so the agent recovers instead of waiting forever. ──
565        if let Some(action) = action
566            && let Err(e) = event_processor::execute_action_with_error_result(
567                action,
568                &tool_registry,
569                &tool_context,
570            )
571            .await
572        {
573            observer.on_event(
574                &thread_id,
575                &AgentEvent::Info {
576                    text: format!("Error: {}", e),
577                },
578            );
579        }
580
581        Ok(StepOutcome::Completed {
582            usage,
583            context_window: model.context_window,
584        })
585    }
586
587    fn handle_completion_event(
588        &self,
589        event: CompletionEvent,
590        observer: &impl ThreadObserver,
591        thread_id: &ThreadId<str>,
592        action: &mut Option<CompletionAction>,
593        usage: &mut Option<Usage>,
594    ) {
595        match event {
596            CompletionEvent::Info(text) => {
597                observer.on_event(thread_id, &AgentEvent::Info { text });
598            }
599            CompletionEvent::TextChunk(text) => {
600                *self.current_thinking.borrow_mut() = None;
601                observer.on_event(thread_id, &AgentEvent::TextChunk { text });
602            }
603            CompletionEvent::ThinkingStart => {
604                *self.current_thinking.borrow_mut() = None;
605                observer.on_event(thread_id, &AgentEvent::ThinkingStarted);
606            }
607            CompletionEvent::ThinkingEnd => {
608                *self.current_thinking.borrow_mut() = None;
609                observer.on_event(thread_id, &AgentEvent::ThinkingEnded);
610            }
611            CompletionEvent::ThinkingChunk(text) => {
612                self.current_thinking
613                    .borrow_mut()
614                    .get_or_insert_default()
615                    .push_str(&text);
616                observer.on_event(thread_id, &AgentEvent::ThinkingChunk { text });
617            }
618            CompletionEvent::SyncToolCall {
619                tool_name,
620                tool_args,
621                display_as,
622            } => {
623                *self.current_thinking.borrow_mut() = None;
624                observer.on_event(
625                    thread_id,
626                    &AgentEvent::ToolCall {
627                        name: tool_name,
628                        args: tool_args,
629                        display_as,
630                    },
631                );
632            }
633            CompletionEvent::SyncToolResult(res) => {
634                *self.current_thinking.borrow_mut() = None;
635                if let Some(ToolResultContent::Text(text)) = res.content.first() {
636                    observer.on_event(
637                        thread_id,
638                        &AgentEvent::ToolResult {
639                            segments: vec![rap_protocol::DisplaySegment::Text(text.text.clone())],
640                        },
641                    );
642                }
643            }
644            CompletionEvent::Action(CompletionAction::Done(r)) => {
645                // There may be multiple `Done` if the agent synchronously
646                // loops back; the last one carries the round's final usage.
647                *self.current_thinking.borrow_mut() = None;
648                if let Some(u) = r.usage {
649                    *usage = Some(u);
650                }
651            }
652            CompletionEvent::Action(a) => {
653                if let CompletionAction::ExecuteToolCall {
654                    ref tool_name,
655                    ref tool_args,
656                    ref display_as,
657                    ..
658                } = a
659                {
660                    *self.current_thinking.borrow_mut() = None;
661                    observer.on_event(
662                        thread_id,
663                        &AgentEvent::ToolCall {
664                            name: tool_name.clone(),
665                            args: tool_args.clone(),
666                            display_as: display_as.clone(),
667                        },
668                    );
669                }
670                assert!(action.is_none(), "bug: multiple terminal actions");
671                *action = Some(a);
672            }
673        }
674    }
675}
676#[cfg(test)]
677mod tests {
678    use crate::system::test_support::*;
679
680    /// A tool call whose dispatch fails must feed an error result back to the
681    /// agent (as a new input through the loopback queue) instead of leaving the
682    /// thread waiting forever on a result that will never come.
683    #[tokio::test(flavor = "current_thread")]
684    async fn failed_tool_dispatch_returns_error_result_to_agent() {
685        let local = tokio::task::LocalSet::new();
686        local
687            .run_until(async {
688                let (mut running, mut rx, mut ctrl, _conv) =
689                    start_system(vec![Box::new(FailingTool)], None);
690                running
691                    .send_user_text(rap_protocol::ThreadId::from_ref("t1"), "use tool")
692                    .await;
693                let _req = ctrl.next_request().await;
694                ctrl.send_tool_call("call-1", "failing_tool", serde_json::json!({}));
695                ctrl.finish();
696
697                // The dispatch failure enqueues a fallback error result, which
698                // wakes the thread for a second completion round.
699                let req2 = ctrl.next_request().await;
700                assert!(
701                    tool_result_texts(&req2)
702                        .iter()
703                        .any(|t| t.contains("Error: Tool call failed")),
704                    "second round should see the fallback error tool result"
705                );
706                ctrl.send_text("recovered");
707                ctrl.finish();
708
709                collect_until_finished(&mut rx).await; // round 1
710                let texts = collect_until_finished(&mut rx).await; // round 2
711                assert_eq!(texts, vec!["recovered"]);
712                wait_idle(&mut running).await;
713            })
714            .await;
715    }
716}