Skip to main content

infinity_agent_core/
traits.rs

1use async_trait::async_trait;
2use infinity_provider_protocol::message::AssistantContent;
3
4use rap_protocol::{ChoiceId, ThreadId, ToolCallId};
5
6use crate::message::{InfinityMessage, InputMessage};
7use crate::system::UserChoice;
8
9/// How much of the parent's conversation history a newly spawned child
10/// thread inherits.
11#[derive(Clone, Copy, Debug, PartialEq, Eq)]
12pub enum SpawnContext {
13    /// Inherit the parent's history up to the given message order
14    /// (exclusive). Callers pass the safe spawn point — the cutoff right
15    /// before the spawn tool call itself and any trailing unanswered tool
16    /// calls — and seed the child's own store with whatever the child needs
17    /// past the cutoff (e.g. a copy of the spawn call).
18    InheritUpTo(usize),
19    /// Start with an empty history: the child sees none of the parent's (or
20    /// any ancestor's) messages. Instructions sent to the child must be
21    /// fully self-contained.
22    Fresh,
23}
24
25/// Persistent conversation history storage (DSQL in Lambda, in-memory for CLI).
26#[async_trait]
27pub trait ConversationStore: Send + Sync + Clone {
28    type Error: std::error::Error + Send + Sync + 'static;
29
30    async fn ensure_root_thread(&self, thread_id: &ThreadId<str>) -> Result<(), Self::Error>;
31
32    /// Return whether an exact root or child thread record exists without
33    /// creating it.
34    async fn thread_exists(&self, thread_id: &ThreadId<str>) -> Result<bool, Self::Error>;
35
36    /// Load history for a session. Both bounds are counted in messages from
37    /// the start of the thread: `start_from` skips that many leading
38    /// messages, `up_to` truncates to that many leading messages (so
39    /// `start_from: Some(a), up_to: Some(b)` yields the a-th through b-1-th
40    /// messages, zero-based). `None` means unbounded.
41    ///
42    /// Implementations may number rows internally however they like (the
43    /// in-memory store uses zero-based indexes with an inclusive-start/
44    /// exclusive-end slice; the DSQL store uses one-based orders with an
45    /// exclusive-start/inclusive-end predicate) as long as the parameters
46    /// are interpreted as leading-row counts. All persisted "order" values
47    /// (spawn cutoffs, compaction `up_to_order`s) follow this same
48    /// count-based convention.
49    async fn load_history_up_to(
50        &self,
51        session_id: &ThreadId<str>,
52        start_from: Option<i64>,
53        up_to: Option<i64>,
54    ) -> Result<Vec<InfinityMessage>, Self::Error>;
55
56    /// Load full history for a thread including ancestor context and compaction.
57    /// Walks backwards through ancestors to find the most recent compaction
58    /// summary, skipping all earlier ancestors (their content is in the summary).
59    /// Returns `(history, leaf_compacted_up_to, ancestor_prefix_len)` where the
60    /// second element is the absolute store index the leaf thread's compaction
61    /// covers (if any), and the third is how many messages at the front of the
62    /// history come from ancestors (not this thread's own store).
63    async fn load_history_with_ancestors(
64        &self,
65        thread_id: &ThreadId<str>,
66    ) -> Result<(Vec<InfinityMessage>, Option<i64>, usize), Self::Error> {
67        // Check the thread itself first
68        if let Ok(Some((summary, compacted_up_to))) = self
69            .load_latest_compaction_summary_up_to(thread_id, None)
70            .await
71        {
72            let mut combined = vec![InfinityMessage::Assistant {
73                content: AssistantContent::text(format!(
74                    "[Compacted conversation summary]\n{}",
75                    summary
76                )),
77            }];
78            combined.extend(
79                self.load_history_up_to(thread_id, Some(compacted_up_to), None)
80                    .await?,
81            );
82            return Ok((combined, Some(compacted_up_to), 0));
83        }
84
85        let mut ancestors = self.get_ancestor_chain(thread_id).await?;
86
87        // Fresh-context threads sever history inheritance: nothing from
88        // before the fresh spawn is visible. Find the deepest fresh boundary
89        // in the chain (the leaf itself, or an ancestor) and drop every
90        // ancestor slice above it. Entry `i` holds ancestor `i`'s own slice,
91        // so when ancestor `i` is the fresh thread its slice is kept.
92        if self.is_fresh_context_thread(thread_id).await? {
93            ancestors.clear();
94        } else {
95            for i in (0..ancestors.len()).rev() {
96                if self.is_fresh_context_thread(&ancestors[i].0).await? {
97                    ancestors.drain(..i);
98                    break;
99                }
100            }
101        }
102
103        // Walk backwards to find the first ancestor with a compaction summary
104        let mut compaction_idx = None;
105        let mut compaction_summary = None;
106        for i in (0..ancestors.len()).rev() {
107            let (ref tid, cutoff) = ancestors[i];
108            if let Ok(Some((summary, compacted_up_to))) = self
109                .load_latest_compaction_summary_up_to(tid, Some(cutoff))
110                .await
111            {
112                compaction_idx = Some(i);
113                compaction_summary = Some((summary, compacted_up_to));
114                break;
115            }
116        }
117
118        let mut combined = Vec::new();
119
120        if let (Some(idx), Some((summary, compacted_up_to))) = (compaction_idx, compaction_summary)
121        {
122            // Prepend the compaction summary (covers all ancestors before idx + ancestor idx's messages up to compacted_up_to)
123            combined.push(InfinityMessage::Assistant {
124                content: AssistantContent::text(format!(
125                    "[Compacted conversation summary]\n{}",
126                    summary
127                )),
128            });
129            // Load remaining messages from the compacted ancestor (after summary, up to cutoff)
130            let (_, cutoff) = &ancestors[idx];
131            combined.extend(
132                self.load_history_up_to(&ancestors[idx].0, Some(compacted_up_to), Some(*cutoff))
133                    .await?,
134            );
135            // Load subsequent ancestors normally
136            for (tid, cutoff) in &ancestors[idx + 1..] {
137                combined.extend(self.load_history_up_to(tid, None, Some(*cutoff)).await?);
138            }
139        } else {
140            // No compaction anywhere — load all ancestors
141            for (tid, cutoff) in &ancestors {
142                combined.extend(self.load_history_up_to(tid, None, Some(*cutoff)).await?);
143            }
144        }
145
146        let ancestor_prefix_len = combined.len();
147        combined.extend(self.load_history_up_to(thread_id, None, None).await?);
148        Ok((combined, None, ancestor_prefix_len))
149    }
150
151    async fn append_messages(
152        &self,
153        session_id: &ThreadId<str>,
154        messages: Vec<(InfinityMessage, String)>,
155    ) -> Result<(), Self::Error>;
156
157    async fn spawn_thread(
158        &self,
159        parent_thread_id: &ThreadId<str>,
160        spawn_tool_call_id: &ToolCallId<str>,
161        is_for_subscription_event: bool,
162        context: SpawnContext,
163    ) -> Result<ThreadId, Self::Error>;
164
165    async fn is_thread_closed(&self, thread_id: &ThreadId<str>) -> Result<bool, Self::Error>;
166
167    async fn close_thread(&self, thread_id: &ThreadId<str>) -> Result<(), Self::Error>;
168
169    async fn is_subscription_event_thread(
170        &self,
171        thread_id: &ThreadId<str>,
172    ) -> Result<bool, Self::Error>;
173
174    /// Whether `thread_id` was spawned with [`SpawnContext::Fresh`] (no
175    /// inherited history). Fresh threads act as a boundary in
176    /// [`load_history_with_ancestors`](Self::load_history_with_ancestors):
177    /// neither they nor their descendants see any context from before the
178    /// fresh spawn.
179    async fn is_fresh_context_thread(&self, thread_id: &ThreadId<str>)
180    -> Result<bool, Self::Error>;
181
182    async fn get_thread_parent_info(
183        &self,
184        thread_id: &ThreadId<str>,
185    ) -> Result<Option<(ThreadId, ToolCallId)>, Self::Error>;
186
187    async fn get_ancestor_chain(
188        &self,
189        thread_id: &ThreadId<str>,
190    ) -> Result<Vec<(ThreadId, i64)>, Self::Error>;
191
192    // ── Compaction support ──
193
194    async fn mark_thread_as_compaction(&self, thread_id: &ThreadId<str>)
195    -> Result<(), Self::Error>;
196
197    async fn is_compaction_thread(&self, thread_id: &ThreadId<str>) -> Result<bool, Self::Error>;
198
199    async fn get_thread_spawn_order(
200        &self,
201        thread_id: &ThreadId<str>,
202    ) -> Result<Option<i64>, Self::Error>;
203
204    async fn save_compaction_summary(
205        &self,
206        thread_id: &ThreadId<str>,
207        summary: &str,
208        up_to_order: i64,
209    ) -> Result<(), Self::Error>;
210
211    /// Load the latest compaction summary. When `up_to_order` is `Some(n)`,
212    /// only return summaries whose `up_to_order` is <= n.
213    async fn load_latest_compaction_summary_up_to(
214        &self,
215        thread_id: &ThreadId<str>,
216        up_to_order: Option<i64>,
217    ) -> Result<Option<(String, i64)>, Self::Error>;
218}
219
220/// Key-value state store for processed message IDs, metadata, toolset caches
221/// (DynamoDB in Lambda, in-memory HashMap for CLI).
222#[async_trait]
223pub trait StateStore: Send + Sync + Clone {
224    type Error: std::error::Error + Send + Sync + 'static;
225
226    /// Durably deduplicated message IDs for this thread. Only inputs that are
227    /// not naturally idempotent are tracked (user text and subscription
228    /// events); tool results are deduplicated against history itself.
229    async fn get_processed_ids(
230        &self,
231        thread_id: &ThreadId<str>,
232    ) -> Result<std::collections::HashSet<String>, Self::Error>;
233
234    async fn add_processed_message_ids(
235        &self,
236        thread_id: &ThreadId<str>,
237        message_ids: Vec<String>,
238    ) -> Result<(), Self::Error>;
239
240    async fn get_metadata(
241        &self,
242        root_thread_id: &ThreadId<str>,
243    ) -> Result<Option<serde_json::Value>, Self::Error>;
244
245    async fn set_metadata(
246        &self,
247        root_thread_id: &ThreadId<str>,
248        metadata: serde_json::Value,
249    ) -> Result<(), Self::Error>;
250
251    /// Return the list of active subscription tool_call_ids for a specific thread.
252    async fn get_active_subscriptions(
253        &self,
254        thread_id: &ThreadId<str>,
255    ) -> Result<Vec<ToolCallId>, Self::Error>;
256
257    /// Record a new active subscription (tool_call_id) for a specific thread.
258    async fn add_active_subscription(
259        &self,
260        thread_id: &ThreadId<str>,
261        tool_call_id: &ToolCallId<str>,
262    ) -> Result<(), Self::Error>;
263
264    /// Remove an active subscription (tool_call_id) from a specific thread.
265    async fn remove_active_subscription(
266        &self,
267        thread_id: &ThreadId<str>,
268        tool_call_id: &ToolCallId<str>,
269    ) -> Result<(), Self::Error>;
270
271    /// Add or replace a pending user choice for one thread.
272    async fn add_pending_user_choice(
273        &self,
274        thread_id: &ThreadId<str>,
275        choice: UserChoice,
276    ) -> Result<(), Self::Error>;
277
278    /// Remove a pending user choice after it is answered or interrupted.
279    async fn remove_pending_user_choice(
280        &self,
281        thread_id: &ThreadId<str>,
282        choice_id: &ChoiceId<str>,
283    ) -> Result<(), Self::Error>;
284
285    /// List choices awaiting a response for one thread.
286    async fn get_pending_user_choices(
287        &self,
288        thread_id: &ThreadId<str>,
289    ) -> Result<Vec<UserChoice>, Self::Error>;
290
291    /// Whether an existing thread has been explicitly stopped.
292    ///
293    /// The local router consults this before spawning a driver for input that
294    /// cannot legitimately resume a stopped thread: synthetic subscription
295    /// events and thread reports, tool results, OAuth completions, and user
296    /// choices. Returning `true` drops such input before a driver is spawned.
297    /// Plain user text is never gated by this method because sending new text
298    /// is how a user resumes a stopped thread.
299    ///
300    /// `thread_id` is the target thread itself, not necessarily its root.
301    /// Implementations that track stopped state per conversation may resolve
302    /// the root themselves. Stores without stopped-thread policy inherit the
303    /// default `false` response.
304    async fn is_thread_stopped(&self, _thread_id: &ThreadId<str>) -> Result<bool, Self::Error> {
305        Ok(false)
306    }
307}
308
309/// Abstraction over input message delivery (SQS in Lambda, channel/direct in CLI).
310#[async_trait]
311pub trait InputSender: Send + Sync + Clone {
312    type Error: std::error::Error + Send + Sync + 'static;
313
314    /// Send a message to the input queue for processing.
315    async fn send_to_input_queue(
316        &self,
317        message: InputMessage,
318        dedup_id: &str,
319    ) -> Result<(), Self::Error>;
320}