Skip to main content

agent/
agent.rs

1use std::sync::{Arc, Mutex};
2
3use ai::transcript::create_initial_system_message;
4use ai::{
5    AbortSignal, AssistantContent, ImageContent, Message, Model, StopReason, TextContent, UserContent, UserMessage,
6    UserMessageContent,
7};
8
9use crate::agent_loop::agent_loop;
10use crate::types::{AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, BeforeToolCall, StreamFn};
11
12#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
13pub enum QueueMode {
14    All,
15    #[default]
16    OneAtATime,
17}
18
19struct Queue {
20    messages: Vec<AgentMessage>,
21    mode: QueueMode,
22}
23
24impl Queue {
25    fn peek(&self) -> Vec<AgentMessage> {
26        match self.mode {
27            QueueMode::All => self.messages.clone(),
28            QueueMode::OneAtATime => self.messages.first().cloned().into_iter().collect(),
29        }
30    }
31
32    fn drain(&mut self) -> Vec<AgentMessage> {
33        let drained = self.peek();
34        self.messages.drain(..drained.len());
35        drained
36    }
37}
38
39type Shared<T> = Arc<Mutex<T>>;
40
41/// Cloneable handle for listeners and other tasks: queue steering messages and abort the active run.
42#[derive(Clone)]
43pub struct AgentControl {
44    steering: Shared<Queue>,
45    active: Shared<Option<AbortSignal>>,
46}
47
48impl AgentControl {
49    /// Queue a message delivered after the current turn's tool calls.
50    pub fn steer(&self, message: AgentMessage) {
51        jsrt::sync::lock(&self.steering).messages.push(message);
52    }
53
54    pub fn abort(&self) {
55        if let Some(signal) = jsrt::sync::lock(&self.active).as_ref() {
56            signal.abort();
57        }
58    }
59}
60
61pub struct AgentOptions {
62    pub model: Model,
63    pub system_prompt: Option<String>,
64    pub tools: Vec<Arc<dyn AgentTool>>,
65    pub messages: Vec<AgentMessage>,
66    /// `"off"` or a reasoning level.
67    pub thinking_level: String,
68    pub steering_mode: QueueMode,
69    pub session_id: Option<String>,
70    pub before_tool_call: Option<BeforeToolCall>,
71}
72
73impl AgentOptions {
74    pub fn new(model: Model) -> Self {
75        AgentOptions {
76            model,
77            system_prompt: None,
78            tools: Vec::new(),
79            messages: Vec::new(),
80            thinking_level: "off".into(),
81            steering_mode: QueueMode::OneAtATime,
82            session_id: None,
83            before_tool_call: None,
84        }
85    }
86}
87
88type Listener = Box<dyn FnMut(&AgentEvent) + Send>;
89
90/// `Agent`: owns the transcript and tools, runs prompts through the loop, and keeps state from the events.
91pub struct Agent {
92    pub model: Model,
93    pub thinking_level: String,
94    pub tools: Vec<Arc<dyn AgentTool>>,
95    pub messages: Vec<AgentMessage>,
96    pub session_id: Option<String>,
97    pub error_message: Option<String>,
98    pub before_tool_call: Option<BeforeToolCall>,
99    stream_fn: Box<dyn StreamFn>,
100    listeners: Vec<Listener>,
101    control: AgentControl,
102}
103
104impl Agent {
105    pub fn new(options: AgentOptions, stream_fn: Box<dyn StreamFn>) -> Self {
106        let mut messages = options.messages;
107        let declarations: Vec<ai::Tool> = options.tools.iter().map(|t| t.tool().clone()).collect();
108        if !matches!(messages.first(), Some(Message::System(_)))
109            && let Some(initial) = create_initial_system_message(options.system_prompt.as_deref(), Some(&declarations))
110        {
111            messages.insert(0, Message::System(initial));
112        }
113        let queue = |mode| {
114            Arc::new(Mutex::new(Queue {
115                messages: Vec::new(),
116                mode,
117            }))
118        };
119        Agent {
120            model: options.model,
121            thinking_level: options.thinking_level,
122            tools: options.tools,
123            messages,
124            session_id: options.session_id,
125            error_message: None,
126            before_tool_call: options.before_tool_call,
127            stream_fn,
128            listeners: Vec::new(),
129            control: AgentControl {
130                steering: queue(options.steering_mode),
131                active: Arc::new(Mutex::new(None)),
132            },
133        }
134    }
135
136    pub fn control(&self) -> AgentControl {
137        self.control.clone()
138    }
139
140    pub fn subscribe(&mut self, listener: impl FnMut(&AgentEvent) + Send + 'static) {
141        self.listeners.push(Box::new(listener));
142    }
143
144    pub async fn prompt_text(&mut self, text: &str, images: Vec<ImageContent>) {
145        let mut content = vec![UserContent::Text(TextContent {
146            text: text.into(),
147            text_signature: None,
148        })];
149        content.extend(images.into_iter().map(UserContent::Image));
150        let message = Message::User(UserMessage {
151            content: UserMessageContent::Blocks(content),
152            timestamp: jsrt::date::now_ms(),
153        });
154        self.prompt(vec![message]).await;
155    }
156
157    /// The run's reply: the text of the transcript's last assistant message; `Err` when that message failed or was
158    /// aborted (its error), or there is none.
159    pub fn final_text(&self) -> Result<String, String> {
160        let last = self.messages.iter().rev().find_map(|m| match m {
161            Message::Assistant(message) => Some(message),
162            _ => None,
163        });
164        let Some(last) = last else {
165            return Err("Agent produced no assistant result at the completed tip".into());
166        };
167        if matches!(last.stop_reason, StopReason::Error | StopReason::Aborted) {
168            return Err(last.error_message.clone().unwrap_or_else(|| "Agent run failed".into()));
169        }
170        Ok(last
171            .content
172            .iter()
173            .filter_map(|part| match part {
174                AssistantContent::Text(text) => Some(text.text.as_str()),
175                _ => None,
176            })
177            .collect::<Vec<_>>()
178            .join("\n"))
179    }
180
181    /// Run the loop over `messages`; returns when the run ends (`agent_end`).
182    pub async fn prompt(&mut self, messages: Vec<AgentMessage>) {
183        let signal = AbortSignal::new();
184        *jsrt::sync::lock(&self.control.active) = Some(signal.clone());
185        self.error_message = None;
186
187        let steering = self.control.steering.clone();
188        let config = AgentLoopConfig {
189            model: self.model.clone(),
190            reasoning: (self.thinking_level != "off").then(|| self.thinking_level.clone()),
191            session_id: self.session_id.clone(),
192            api_key: None,
193            get_steering_messages: Some(Box::new(move || jsrt::sync::lock(&steering).drain())),
194            before_tool_call: self.before_tool_call.clone(),
195        };
196        let context = AgentContext {
197            messages: self.messages.clone(),
198            tools: self.tools.clone(),
199        };
200        let Agent {
201            messages: state,
202            error_message,
203            listeners,
204            stream_fn,
205            ..
206        } = self;
207        let mut process = |event: AgentEvent| {
208            match &event {
209                AgentEvent::MessageEnd { message } => state.push(message.clone()),
210                AgentEvent::TurnEnd {
211                    message: Message::Assistant(message),
212                    ..
213                } if message.error_message.is_some() => {
214                    error_message.clone_from(&message.error_message);
215                }
216                _ => {}
217            }
218            for listener in listeners.iter_mut() {
219                listener(&event);
220            }
221        };
222        agent_loop(messages, context, config, &mut process, &signal, stream_fn.as_ref()).await;
223
224        *jsrt::sync::lock(&self.control.active) = None;
225    }
226}