Skip to main content

agent/
agent_loop.rs

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
31/// `runAgentLoop`: add `prompts` (after declaring tool changes) and run until the agent stops. Returns the new
32/// messages.
33pub 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
136/// `declareToolChanges`: make the transcript's declared tools equal `context.tools` by putting `toolsAdded` /
137/// `toolsRemoved` on the last pending system message, or on a new one before the first non-system pending message.
138pub(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(&current_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
198/// `getToolStateChanges`: a changed definition is a removal plus an addition. Declarations compare by their JSON
199/// text, as upstream's `declarationsEqual`.
200fn 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
218/// `streamAssistantResponse`: the in-progress message is the last context message while streaming.
219async 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
300/// A `length` stop may have truncated every tool call's arguments: none run.
301fn 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
418/// Polls every future until all finish, in completion order.
419async 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
454/// `prepareToolCall`: find the tool, validate and coerce the arguments against its
455/// schema (`validateToolArguments`, same error text), then ask `beforeToolCall`. Anything that fails or blocks is an
456/// immediate error result.
457async 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
509/// `executePreparedToolCall`: run the tool with the validated arguments; a thrown error is an error result.
510async 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
531/// `finalizeExecutedToolCall` without an `afterToolCall` hook: the executed result as it is.
532fn finalize(call: &ToolCall, (result, is_error): (AgentToolResult, bool)) -> Finalized {
533    Finalized {
534        call: call.clone(),
535        result,
536        is_error,
537    }
538}