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