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}