1use std::future::poll_fn;
2use std::sync::Mutex;
3use std::task::Poll;
4
5use ai::http::BoxFuture;
6use ai::transcript::{current_tools, normalize_context};
7use ai::{
8 AbortSignal, AssistantContent, AssistantMessage, AssistantMessageEvent, Context, Message, SimpleStreamOptions,
9 StopReason, StreamOptions, SystemContent, SystemMessage, Tool, ToolCall, ToolReference, ToolResultMessage,
10};
11use serde_json::Value;
12
13use std::sync::Arc;
14
15use jsonschema::validate_tool_arguments;
16
17use crate::types::{
18 AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, AgentToolResult, BeforeToolCallContext,
19 StreamFn,
20};
21
22pub(crate) struct Emit<'a>(Mutex<&'a mut (dyn FnMut(AgentEvent) + Send)>);
23
24impl Emit<'_> {
25 fn emit(&self, event: AgentEvent) {
26 let mut sink = self.0.lock().unwrap_or_else(|poisoned| poisoned.into_inner());
27 (*sink)(event)
28 }
29}
30
31pub async fn agent_loop(
34 prompts: Vec<AgentMessage>,
35 context: AgentContext,
36 config: AgentLoopConfig,
37 emit: &mut (dyn FnMut(AgentEvent) + Send),
38 signal: &AbortSignal,
39 stream_fn: &dyn StreamFn,
40) -> Vec<AgentMessage> {
41 let emit = Emit(Mutex::new(emit));
42 let initial = declare_tool_changes(&context, prompts);
43 let mut new_messages = initial.clone();
44 let mut current = context;
45 current.messages.extend(initial.iter().cloned());
46 emit.emit(AgentEvent::AgentStart);
47 emit.emit(AgentEvent::TurnStart);
48 for message in initial {
49 emit.emit(AgentEvent::MessageStart {
50 message: message.clone(),
51 });
52 emit.emit(AgentEvent::MessageEnd { message });
53 }
54 run_loop(current, &mut new_messages, config, signal, &emit, stream_fn).await;
55 new_messages
56}
57
58fn poll_messages(source: &mut Option<crate::types::MessageSource>) -> Vec<AgentMessage> {
59 source.as_mut().map(|get| get()).unwrap_or_default()
60}
61
62async fn run_loop(
63 mut context: AgentContext,
64 new_messages: &mut Vec<AgentMessage>,
65 mut config: AgentLoopConfig,
66 signal: &AbortSignal,
67 emit: &Emit<'_>,
68 stream_fn: &dyn StreamFn,
69) {
70 let mut first_turn = true;
71 let mut pending = poll_messages(&mut config.get_steering_messages);
72 let mut has_more_tool_calls = true;
73 while has_more_tool_calls || !pending.is_empty() {
74 if !first_turn {
75 emit.emit(AgentEvent::TurnStart);
76 }
77 first_turn = false;
78 for message in declare_tool_changes(&context, std::mem::take(&mut pending)) {
79 emit.emit(AgentEvent::MessageStart {
80 message: message.clone(),
81 });
82 emit.emit(AgentEvent::MessageEnd {
83 message: message.clone(),
84 });
85 context.messages.push(message.clone());
86 new_messages.push(message);
87 }
88
89 let message = stream_assistant_response(&mut context, &config, signal, emit, stream_fn).await;
90 new_messages.push(Message::Assistant(message.clone()));
91 if matches!(message.stop_reason, StopReason::Error | StopReason::Aborted) {
92 emit.emit(AgentEvent::TurnEnd {
93 message: Message::Assistant(message),
94 tool_results: Vec::new(),
95 });
96 emit.emit(AgentEvent::AgentEnd {
97 messages: new_messages.clone(),
98 });
99 return;
100 }
101
102 let tool_calls: Vec<ToolCall> = message
103 .content
104 .iter()
105 .filter_map(|c| match c {
106 AssistantContent::ToolCall(call) => Some(call.clone()),
107 _ => None,
108 })
109 .collect();
110 has_more_tool_calls = false;
111 let mut tool_results = Vec::new();
112 if !tool_calls.is_empty() {
113 let batch = if message.stop_reason == StopReason::Length {
114 fail_truncated_tool_calls(&tool_calls, emit)
115 } else {
116 execute_tool_calls(&context, &message, &tool_calls, &config, signal, emit).await
117 };
118 has_more_tool_calls = !batch.terminate;
119 for result in &batch.messages {
120 context.messages.push(Message::ToolResult(result.clone()));
121 new_messages.push(Message::ToolResult(result.clone()));
122 }
123 tool_results = batch.messages;
124 }
125 emit.emit(AgentEvent::TurnEnd {
126 message: Message::Assistant(message),
127 tool_results,
128 });
129 pending = poll_messages(&mut config.get_steering_messages);
130 }
131 emit.emit(AgentEvent::AgentEnd {
132 messages: new_messages.clone(),
133 });
134}
135
136pub(crate) fn declare_tool_changes(context: &AgentContext, pending: Vec<AgentMessage>) -> Vec<AgentMessage> {
139 let system_index = pending.iter().rposition(|m| matches!(m, Message::System(_)));
140 let baseline: Vec<AgentMessage> = pending
141 .iter()
142 .enumerate()
143 .map(|(i, m)| match m {
144 Message::System(s) if Some(i) == system_index => {
145 Message::System(with_tool_changes(s, Vec::new(), Vec::new()))
146 }
147 other => other.clone(),
148 })
149 .collect();
150 let mut transcript = context.messages.clone();
151 transcript.extend(baseline.iter().cloned());
152 let executable: Vec<Tool> = context.tools.iter().map(|t| t.tool().clone()).collect();
153 let (added, removed) = tool_state_changes(¤t_tools(&transcript), &executable);
154 let unchanged = added.is_empty() && removed.is_empty();
155
156 if let Some(index) = system_index {
157 let Message::System(system) = &pending[index] else {
158 unreachable!()
159 };
160 let declares = system.tools_added.as_ref().is_some_and(|t| !t.is_empty())
161 || system.tools_removed.as_ref().is_some_and(|t| !t.is_empty());
162 if unchanged && !declares {
163 return pending;
164 }
165 let update = with_tool_changes(system, added, removed);
166 let mut out = baseline;
167 out[index] = Message::System(update);
168 return out;
169 }
170 if unchanged {
171 return pending;
172 }
173 let empty = SystemMessage {
174 content: SystemContent::Text(String::new()),
175 sections: None,
176 tools_added: None,
177 tools_removed: None,
178 timestamp: jsrt::date::now_ms(),
179 };
180 let update = Message::System(with_tool_changes(&empty, added, removed));
181 let index = pending
182 .iter()
183 .position(|m| !matches!(m, Message::System(_)))
184 .unwrap_or(pending.len());
185 let mut out = pending;
186 out.insert(index, update);
187 out
188}
189
190fn with_tool_changes(message: &SystemMessage, added: Vec<Tool>, removed: Vec<ToolReference>) -> SystemMessage {
191 SystemMessage {
192 tools_added: (!added.is_empty()).then_some(added),
193 tools_removed: (!removed.is_empty()).then_some(removed),
194 ..message.clone()
195 }
196}
197
198fn tool_state_changes(previous: &[Tool], current: &[Tool]) -> (Vec<Tool>, Vec<ToolReference>) {
201 let json = |tool: &Tool| serde_json::to_string(tool).unwrap_or_default();
202 let same = |a: &Tool, b: &Tool| json(a) == json(b);
203 let added = current
204 .iter()
205 .filter(|tool| !previous.iter().any(|p| p.name == tool.name && same(p, tool)))
206 .cloned()
207 .collect();
208 let removed = previous
209 .iter()
210 .filter(|tool| !current.iter().any(|c| c.name == tool.name && same(tool, c)))
211 .map(|tool| ToolReference {
212 name: tool.name.clone(),
213 })
214 .collect();
215 (added, removed)
216}
217
218async fn stream_assistant_response(
220 context: &mut AgentContext,
221 config: &AgentLoopConfig,
222 signal: &AbortSignal,
223 emit: &Emit<'_>,
224 stream_fn: &dyn StreamFn,
225) -> AssistantMessage {
226 let llm_context = normalize_context(&Context {
227 system_prompt: None,
228 messages: context.messages.clone(),
229 tools: None,
230 });
231 let options = SimpleStreamOptions {
232 base: StreamOptions {
233 api_key: config.api_key.clone(),
234 session_id: config.session_id.clone(),
235 signal: Some(signal.clone()),
236 ..Default::default()
237 },
238 reasoning: config.reasoning.clone(),
239 ..Default::default()
240 };
241 let messages = &mut context.messages;
242 let mut added_partial = false;
243 let mut sink = |event: &AssistantMessageEvent| match event {
244 AssistantMessageEvent::Start { partial } => {
245 messages.push(Message::Assistant(partial.clone()));
246 added_partial = true;
247 emit.emit(AgentEvent::MessageStart {
248 message: Message::Assistant(partial.clone()),
249 });
250 }
251 AssistantMessageEvent::Done { .. } | AssistantMessageEvent::Error { .. } => {}
252 AssistantMessageEvent::TextStart { partial, .. }
253 | AssistantMessageEvent::TextDelta { partial, .. }
254 | AssistantMessageEvent::TextEnd { partial, .. }
255 | AssistantMessageEvent::ThinkingStart { partial, .. }
256 | AssistantMessageEvent::ThinkingDelta { partial, .. }
257 | AssistantMessageEvent::ThinkingEnd { partial, .. }
258 | AssistantMessageEvent::ToolCallStart { partial, .. }
259 | AssistantMessageEvent::ToolCallDelta { partial, .. }
260 | AssistantMessageEvent::ToolCallEnd { partial, .. } => {
261 if added_partial {
262 let message = Message::Assistant(partial.clone());
263 if let Some(last) = messages.last_mut() {
264 *last = message.clone();
265 }
266 emit.emit(AgentEvent::MessageUpdate {
267 message,
268 assistant_message_event: event.clone(),
269 });
270 }
271 }
272 };
273 let final_message = stream_fn.stream(&config.model, &llm_context, &options, &mut sink).await;
274 let message = Message::Assistant(final_message.clone());
275 if added_partial {
276 if let Some(last) = context.messages.last_mut() {
277 *last = message.clone();
278 }
279 } else {
280 context.messages.push(message.clone());
281 emit.emit(AgentEvent::MessageStart {
282 message: message.clone(),
283 });
284 }
285 emit.emit(AgentEvent::MessageEnd { message });
286 final_message
287}
288
289struct Batch {
290 messages: Vec<ToolResultMessage>,
291 terminate: bool,
292}
293
294struct Finalized {
295 call: ToolCall,
296 result: AgentToolResult,
297 is_error: bool,
298}
299
300fn fail_truncated_tool_calls(calls: &[ToolCall], emit: &Emit<'_>) -> Batch {
302 let mut messages = Vec::new();
303 for call in calls {
304 emit_start(call, emit);
305 let finalized = Finalized {
306 call: call.clone(),
307 result: AgentToolResult::error(format!(
308 "Tool call \"{}\" was not executed: the response hit the output token limit, so its arguments may be truncated. Re-issue the tool call with complete arguments.",
309 call.name
310 )),
311 is_error: true,
312 };
313 emit_end(&finalized, emit);
314 let message = tool_result_message(&finalized);
315 emit_result_message(&message, emit);
316 messages.push(message);
317 }
318 Batch {
319 messages,
320 terminate: false,
321 }
322}
323
324fn emit_start(call: &ToolCall, emit: &Emit<'_>) {
325 emit.emit(AgentEvent::ToolExecutionStart {
326 tool_call_id: call.id.clone(),
327 tool_name: call.name.clone(),
328 args: call.arguments.clone(),
329 });
330}
331
332fn emit_end(finalized: &Finalized, emit: &Emit<'_>) {
333 emit.emit(AgentEvent::ToolExecutionEnd {
334 tool_call_id: finalized.call.id.clone(),
335 tool_name: finalized.call.name.clone(),
336 result: finalized.result.clone(),
337 is_error: finalized.is_error,
338 });
339}
340
341fn emit_result_message(message: &ToolResultMessage, emit: &Emit<'_>) {
342 emit.emit(AgentEvent::MessageStart {
343 message: Message::ToolResult(message.clone()),
344 });
345 emit.emit(AgentEvent::MessageEnd {
346 message: Message::ToolResult(message.clone()),
347 });
348}
349
350fn tool_result_message(finalized: &Finalized) -> ToolResultMessage {
351 ToolResultMessage {
352 tool_call_id: finalized.call.id.clone(),
353 tool_name: finalized.call.name.clone(),
354 content: finalized.result.content.clone(),
355 details: Some(finalized.result.details.clone()).filter(|d| !d.is_null()),
356 usage: finalized.result.usage.clone(),
357 is_error: finalized.is_error,
358 timestamp: jsrt::date::now_ms(),
359 }
360}
361
362fn should_terminate(finalized: &[Finalized]) -> bool {
363 !finalized.is_empty() && finalized.iter().all(|f| f.result.terminate == Some(true))
364}
365
366async fn execute_tool_calls(
367 context: &AgentContext,
368 assistant: &AssistantMessage,
369 calls: &[ToolCall],
370 config: &AgentLoopConfig,
371 signal: &AbortSignal,
372 emit: &Emit<'_>,
373) -> Batch {
374 let mut slots: Vec<Option<Finalized>> = Vec::new();
375 let mut running: Vec<BoxFuture<'_, (usize, Finalized)>> = Vec::new();
376 for call in calls {
377 emit_start(call, emit);
378 match prepare_tool_call(context, assistant, call, config, signal).await {
379 Prepared::Immediate(done) => {
380 emit_end(&done, emit);
381 slots.push(Some(*done));
382 }
383 Prepared::Ready { tool, args } => {
384 let index = slots.len();
385 running.push(Box::pin(async move {
386 let done = if signal.aborted() {
387 immediate(call, "Operation aborted")
388 } else {
389 let executed = execute_prepared(call, tool, &args, signal, emit).await;
390 finalize(call, executed)
391 };
392 emit_end(&done, emit);
393 (index, done)
394 }));
395 slots.push(None);
396 }
397 }
398 if signal.aborted() {
399 break;
400 }
401 }
402 for (index, done) in join_all(running).await {
403 slots[index] = Some(done);
404 }
405 let finalized: Vec<Finalized> = slots.into_iter().flatten().collect();
406 let mut messages = Vec::new();
407 for done in &finalized {
408 let message = tool_result_message(done);
409 emit_result_message(&message, emit);
410 messages.push(message);
411 }
412 Batch {
413 terminate: should_terminate(&finalized),
414 messages,
415 }
416}
417
418async fn join_all<T>(mut futures: Vec<BoxFuture<'_, T>>) -> Vec<T> {
420 let mut out = Vec::new();
421 poll_fn(|cx| {
422 let mut i = 0;
423 while i < futures.len() {
424 if let Poll::Ready(value) = futures[i].as_mut().poll(cx) {
425 drop(futures.remove(i));
426 out.push(value);
427 } else {
428 i += 1;
429 }
430 }
431 if futures.is_empty() {
432 Poll::Ready(())
433 } else {
434 Poll::Pending
435 }
436 })
437 .await;
438 out
439}
440
441enum Prepared<'c> {
442 Immediate(Box<Finalized>),
443 Ready { tool: &'c Arc<dyn AgentTool>, args: Value },
444}
445
446fn immediate(call: &ToolCall, message: impl Into<String>) -> Finalized {
447 Finalized {
448 call: call.clone(),
449 result: AgentToolResult::error(message),
450 is_error: true,
451 }
452}
453
454async fn prepare_tool_call<'c>(
458 context: &'c AgentContext,
459 assistant: &AssistantMessage,
460 call: &ToolCall,
461 config: &AgentLoopConfig,
462 signal: &AbortSignal,
463) -> Prepared<'c> {
464 let Some(tool) = context.tools.iter().find(|t| t.tool().name == call.name) else {
465 return Prepared::Immediate(Box::new(immediate(call, format!("Tool {} not found", call.name))));
466 };
467 let args = match validate_tool_arguments(&call.name, &tool.tool().parameters, &call.arguments) {
468 Ok(args) => args,
469 Err(message) => return Prepared::Immediate(Box::new(immediate(call, message))),
470 };
471 if let Some(before) = &config.before_tool_call {
472 let decision = before(
473 BeforeToolCallContext {
474 assistant_message: assistant,
475 tool_call: call,
476 args: &args,
477 context,
478 },
479 signal,
480 )
481 .await;
482 let decision = match decision {
483 Ok(decision) => decision,
484 Err(message) => return Prepared::Immediate(Box::new(immediate(call, message))),
485 };
486 if signal.aborted() {
487 return Prepared::Immediate(Box::new(immediate(call, "Operation aborted")));
488 }
489 if let Some(decision) = decision.filter(|d| d.block) {
490 let mut done = immediate(
491 call,
492 decision
493 .reason
494 .filter(|r| !r.is_empty())
495 .unwrap_or_else(|| "Tool execution was blocked".into()),
496 );
497 if decision.terminate == Some(true) {
498 done.result.terminate = Some(true);
499 }
500 return Prepared::Immediate(Box::new(done));
501 }
502 }
503 if signal.aborted() {
504 return Prepared::Immediate(Box::new(immediate(call, "Operation aborted")));
505 }
506 Prepared::Ready { tool, args }
507}
508
509async fn execute_prepared(
511 call: &ToolCall,
512 tool: &Arc<dyn AgentTool>,
513 args: &Value,
514 signal: &AbortSignal,
515 emit: &Emit<'_>,
516) -> (AgentToolResult, bool) {
517 let on_update = |partial: AgentToolResult| {
518 emit.emit(AgentEvent::ToolExecutionUpdate {
519 tool_call_id: call.id.clone(),
520 tool_name: call.name.clone(),
521 args: call.arguments.clone(),
522 partial_result: partial,
523 })
524 };
525 match tool.execute(&call.id, args.clone(), signal, &on_update).await {
526 Ok(result) => (result, false),
527 Err(message) => (AgentToolResult::error(message), true),
528 }
529}
530
531fn finalize(call: &ToolCall, (result, is_error): (AgentToolResult, bool)) -> Finalized {
533 Finalized {
534 call: call.clone(),
535 result,
536 is_error,
537 }
538}