Skip to main content

infinity_agent_core/system/
defer.rs

1//! The [`DeferQueue`] trait: holding back synthetic events while a tool call
2//! is in flight.
3//!
4//! When a thread has dispatched a tool call and is waiting for its result,
5//! processing an unrelated synthetic event (a subscription event, a child
6//! thread's report, a message from the parent) would *interrupt* the pending
7//! call: the runtime injects a synthetic "interrupted" result so the history
8//! stays well-formed, and the real result is later dropped as stale. To avoid
9//! cancelling work that is still running, such events should be deferred
10//! until the pending call is answered.
11//!
12//! Whether deferral is possible depends on the platform. A resident runtime
13//! (the local driver, the Infinity Code daemon) can hold events in memory. A
14//! serverless embedding has no process to hold them in — it can either
15//! implement this trait against its transport (e.g. re-enqueueing the message
16//! with a delay on SQS) or use [`NoDeferral`] to process events immediately,
17//! accepting the interruption semantics.
18
19use async_trait::async_trait;
20
21use crate::message::InputMessage;
22
23type BoxError = Box<dyn std::error::Error + Send + Sync>;
24
25/// Where deferrable inputs wait while the thread cannot process them.
26#[async_trait(?Send)]
27pub trait DeferQueue {
28    /// Hold back an input for later redelivery. Returns `Ok(false)` if this
29    /// queue cannot defer, in which case the step processes the input
30    /// immediately (interrupting any pending tool call).
31    async fn push(&mut self, input: InputMessage, message_id: String) -> Result<bool, BoxError>;
32
33    /// Take back all deferred inputs. Called when the thread can process them
34    /// (the pending tool call was answered or deliberately interrupted).
35    async fn drain(&mut self) -> Result<Vec<(InputMessage, String)>, BoxError>;
36}
37
38/// In-memory deferral for resident runtimes. Deferred events are lost if the
39/// process dies; on a durable transport prefer a transport-level
40/// implementation.
41#[derive(Default)]
42pub struct InMemoryDeferQueue {
43    items: Vec<(InputMessage, String)>,
44}
45
46impl InMemoryDeferQueue {
47    pub fn new() -> Self {
48        Self::default()
49    }
50
51    pub fn is_empty(&self) -> bool {
52        self.items.is_empty()
53    }
54}
55
56#[async_trait(?Send)]
57impl DeferQueue for InMemoryDeferQueue {
58    async fn push(&mut self, input: InputMessage, message_id: String) -> Result<bool, BoxError> {
59        self.items.push((input, message_id));
60        Ok(true)
61    }
62
63    async fn drain(&mut self) -> Result<Vec<(InputMessage, String)>, BoxError> {
64        Ok(std::mem::take(&mut self.items))
65    }
66}
67
68/// No deferral: every input is processed in the slice it arrives in, even if
69/// that interrupts a pending tool call. This matches platforms without a
70/// place to hold messages (e.g. a plain SQS-driven Lambda).
71pub struct NoDeferral;
72
73#[async_trait(?Send)]
74impl DeferQueue for NoDeferral {
75    async fn push(&mut self, _input: InputMessage, _message_id: String) -> Result<bool, BoxError> {
76        Ok(false)
77    }
78
79    async fn drain(&mut self) -> Result<Vec<(InputMessage, String)>, BoxError> {
80        Ok(Vec::new())
81    }
82}