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
use serde::{Deserialize, Serialize};
use std::fmt;
use uuid::Uuid;
/// Maximum number of follow-up intents held by a runtime before they are
/// consumed. Rejecting overflow preserves every accepted instruction and
/// makes back-pressure visible to the caller.
pub const MAX_QUEUED_FOLLOW_UP_INTENTS: usize = 16;
/// Maximum number of applied follow-up IDs retained for restart recovery.
pub const MAX_APPLIED_FOLLOW_UP_INTENT_IDS: usize = 64;
/// A follow-up instruction with a stable identity for recovery and
/// de-duplication.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct QueuedFollowUpIntent {
id: String,
text: String,
}
impl QueuedFollowUpIntent {
/// Create a new intent with a UUIDv4 identity.
#[must_use]
pub fn new(text: String) -> Self {
Self { id: Uuid::new_v4().to_string(), text }
}
/// Reconstruct an intent recovered from durable state.
pub fn from_parts(id: impl Into<String>, text: impl Into<String>) -> Self {
Self { id: id.into(), text: text.into() }
}
#[must_use]
pub fn id(&self) -> &str {
&self.id
}
#[must_use]
pub fn text(&self) -> &str {
&self.text
}
/// Consume the intent and return its user-visible text.
#[must_use]
pub fn into_parts(self) -> (String, String) {
(self.id, self.text)
}
}
/// Error returned when a runtime cannot accept another follow-up intent.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FollowUpQueueFull {
pub capacity: usize,
}
impl fmt::Display for FollowUpQueueFull {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "follow-up intent queue is full (capacity {})", self.capacity)
}
}
impl std::error::Error for FollowUpQueueFull {}
/// Messages used to steer the agent's execution loop from an external source.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum SteeringMessage {
/// Stop the agent's execution loop immediately (Steering).
SteerStop,
/// Pause the agent's execution loop.
Pause,
/// Resume the agent's execution loop.
Resume,
/// Inject input as a follow-up message after the current turn ends (FollowUp).
FollowUpInput(String),
}