Skip to main content

pixie_pi/agent/
agent_loop.rs

1//! The agent loop (`packages/agent/agent-loop.ts`): stream an assistant response,
2//! execute any tool calls, feed results back, and repeat until the model stops.
3
4use std::sync::Arc;
5
6use futures::StreamExt;
7use serde_json::Value;
8use tokio::sync::mpsc;
9use tokio_stream::wrappers::ReceiverStream;
10use tokio_util::sync::CancellationToken;
11
12use crate::agent::context::{AgentContext, AgentEvent};
13use crate::agent::tool::{
14    validate_required, AgentTool, ExecutionMode, ToolCallContext, ToolGate, ToolResult,
15};
16use crate::ai::anthropic::{stream_simple, LlmContext, SimpleStreamOptions};
17use crate::ai::stream::AssistantMessageEvent;
18use crate::ai::types::{
19    AssistantMessage, ContentBlock, Message, Model, ToolResultMessage,
20};
21
22/// Configuration for the agent loop.
23pub struct AgentLoopConfig {
24    pub client: reqwest::Client,
25    pub model: Model,
26    pub options: SimpleStreamOptions,
27    pub tool_execution: ExecutionMode,
28    pub gate: Option<Arc<dyn ToolGate>>,
29}
30
31/// A boxed async stream of agent events.
32pub type AgentEventStream = ReceiverStream<AgentEvent>;
33
34/// Start an agent loop as a background task and return its event stream. The
35/// loop appends `prompts` to a copy of the context, runs to completion, and
36/// terminates with a single [`AgentEvent::AgentEnd`] carrying the final
37/// transcript. Each run is independent (the caller owns the live transcript).
38pub fn agent_loop(
39    ctx: AgentContext,
40    config: AgentLoopConfig,
41    prompts: Vec<Message>,
42    cancel: CancellationToken,
43) -> AgentEventStream {
44    let (tx, rx) = mpsc::channel(128);
45    let tx2 = tx.clone();
46    tokio::spawn(async move {
47        if let Err(e) = run_loop(ctx, config, prompts, cancel, tx).await {
48            let _ = tx2.send(AgentEvent::Error(e.to_string())).await;
49        }
50    });
51    ReceiverStream::new(rx)
52}
53
54async fn run_loop(
55    mut ctx: AgentContext,
56    config: AgentLoopConfig,
57    prompts: Vec<Message>,
58    cancel: CancellationToken,
59    tx: mpsc::Sender<AgentEvent>,
60) -> anyhow::Result<()> {
61    let _ = tx.send(AgentEvent::AgentStart).await;
62
63    // Inject the prompt messages.
64    for prompt in &prompts {
65        ctx.messages.push(prompt.clone());
66        let _ = tx.send(AgentEvent::MessageStart(prompt.clone())).await;
67        let _ = tx.send(AgentEvent::MessageEnd(prompt.clone())).await;
68    }
69
70    loop {
71        if cancel.is_cancelled() {
72            break;
73        }
74        let _ = tx.send(AgentEvent::TurnStart).await;
75
76        let assistant = match stream_assistant(&mut ctx, &config, cancel.clone(), &tx).await {
77            Ok(m) => m,
78            Err(e) => {
79                let _ = tx.send(AgentEvent::Error(e.to_string())).await;
80                break;
81            }
82        };
83
84        let _ = tx.send(AgentEvent::Usage(assistant.usage.clone())).await;
85
86        let tool_calls: Vec<(String, String, Value)> = assistant
87            .content
88            .iter()
89            .filter_map(|b| match b {
90                ContentBlock::ToolCall { id, name, arguments } => {
91                    Some((id.clone(), name.clone(), arguments.clone()))
92                }
93                _ => None,
94            })
95            .collect();
96
97        let tool_results: Vec<ToolResultMessage> = if tool_calls.is_empty() {
98            Vec::new()
99        } else {
100            execute_tool_calls(&ctx, &tool_calls, &config, cancel.clone(), &tx).await
101        };
102
103        for result in &tool_results {
104            let msg = Message::ToolResult(result.clone());
105            ctx.messages.push(msg.clone());
106            let _ = tx.send(AgentEvent::MessageStart(msg.clone())).await;
107            let _ = tx.send(AgentEvent::MessageEnd(msg)).await;
108        }
109
110        let _ = tx
111            .send(AgentEvent::TurnEnd {
112                message: assistant,
113                tool_results,
114            })
115            .await;
116
117        // Stop when the assistant produced no tool calls (it's done), or the
118        // run was aborted. Otherwise the tool results are now in context and
119        // we loop to let the model respond again.
120        if tool_calls.is_empty() || cancel.is_cancelled() {
121            break;
122        }
123    }
124
125    let _ = tx.send(AgentEvent::AgentEnd { messages: ctx.messages }).await;
126    Ok(())
127}
128
129/// Stream a single assistant response, mutating the context's transcript.
130async fn stream_assistant(
131    ctx: &mut AgentContext,
132    config: &AgentLoopConfig,
133    cancel: CancellationToken,
134    tx: &mpsc::Sender<AgentEvent>,
135) -> anyhow::Result<AssistantMessage> {
136    let tools_schema: Vec<_> = ctx.tools.iter().map(|t| t.schema()).collect();
137    let llm = LlmContext {
138        system_prompt: Some(&ctx.system_prompt),
139        messages: &ctx.messages,
140        tools: &tools_schema,
141    };
142    let stream = stream_simple(&config.client, &config.model, &llm, &config.options, cancel);
143
144    let mut partial = AssistantMessage::empty();
145    partial.model = config.model.id.clone();
146    partial.provider = config.model.provider.clone();
147    ctx.messages.push(Message::Assistant(partial.clone()));
148    let _ = tx
149        .send(AgentEvent::MessageStart(Message::Assistant(partial.clone())))
150        .await;
151
152    let mut final_msg: Option<AssistantMessage> = None;
153    let mut stream = stream;
154    while let Some(event) = stream.next().await {
155        match &event {
156            AssistantMessageEvent::Done { message, .. }
157            | AssistantMessageEvent::Error { message, .. } => {
158                final_msg = Some(message.clone());
159                apply_event(&mut partial, &event);
160                let _ = tx.send(AgentEvent::MessageUpdate { event }).await;
161            }
162            _ => {
163                apply_event(&mut partial, &event);
164                let _ = tx.send(AgentEvent::MessageUpdate { event }).await;
165            }
166        }
167    }
168
169    let final_msg = final_msg.unwrap_or(partial);
170    // Replace the placeholder assistant message with the authoritative one.
171    if let Some(Message::Assistant(slot)) = ctx.messages.last_mut() {
172        *slot = final_msg.clone();
173    }
174    let _ = tx
175        .send(AgentEvent::MessageEnd(Message::Assistant(final_msg.clone())))
176        .await;
177    Ok(final_msg)
178}
179
180/// Reconstruct a partial assistant message from fine-grained events (for live
181/// rendering). The authoritative message arrives via `Done`/`Error`.
182fn apply_event(msg: &mut AssistantMessage, event: &AssistantMessageEvent) {
183    match event {
184        AssistantMessageEvent::Start => {}
185        AssistantMessageEvent::TextStart { content_index } => {
186            ensure_block(msg, *content_index, || ContentBlock::Text { text: String::new() });
187        }
188        AssistantMessageEvent::TextDelta { content_index, delta } => {
189            if let Some(ContentBlock::Text { text }) = msg.content.get_mut(*content_index) {
190                text.push_str(delta);
191            }
192        }
193        AssistantMessageEvent::TextEnd { .. } => {}
194        AssistantMessageEvent::ThinkingStart { content_index } => {
195            ensure_block(msg, *content_index, || ContentBlock::Thinking {
196                thinking: String::new(),
197                thinking_signature: String::new(),
198                redacted: false,
199            });
200        }
201        AssistantMessageEvent::ThinkingDelta { content_index, delta } => {
202            if let Some(ContentBlock::Thinking { thinking, .. }) = msg.content.get_mut(*content_index)
203            {
204                thinking.push_str(delta);
205            }
206        }
207        AssistantMessageEvent::ThinkingEnd { .. } => {}
208        AssistantMessageEvent::ToolCallStart { content_index } => {
209            ensure_block(msg, *content_index, || ContentBlock::ToolCall {
210                id: String::new(),
211                name: String::new(),
212                arguments: Value::Object(Default::default()),
213            });
214        }
215        AssistantMessageEvent::ToolCallDelta { .. } => {
216            // Live tool-argument deltas are parsed by the provider; the final
217            // arguments arrive with the authoritative message.
218        }
219        AssistantMessageEvent::ToolCallEnd { .. } => {}
220        AssistantMessageEvent::Done { message, .. }
221        | AssistantMessageEvent::Error { message, .. } => {
222            *msg = message.clone();
223        }
224    }
225}
226
227fn ensure_block(msg: &mut AssistantMessage, index: usize, make: impl Fn() -> ContentBlock) {
228    while msg.content.len() <= index {
229        msg.content.push(make());
230    }
231}
232
233/// Execute all tool calls from one assistant message and return the result
234/// messages (in tool-call order). Respects per-tool / config execution mode.
235async fn execute_tool_calls(
236    ctx: &AgentContext,
237    tool_calls: &[(String, String, Value)],
238    config: &AgentLoopConfig,
239    cancel: CancellationToken,
240    tx: &mpsc::Sender<AgentEvent>,
241) -> Vec<ToolResultMessage> {
242    let force_sequential = config.tool_execution == ExecutionMode::Sequential
243        || tool_calls.iter().any(|(_id, name, _)| {
244            id_is_sequential(ctx, name)
245        });
246
247    if force_sequential {
248        sequential_execute(ctx, tool_calls, config, cancel, tx).await
249    } else {
250        parallel_execute(ctx, tool_calls, config, cancel, tx).await
251    }
252}
253
254fn id_is_sequential(ctx: &AgentContext, name: &str) -> bool {
255    ctx.find_tool(name)
256        .map(|t| t.execution_mode() == ExecutionMode::Sequential)
257        .unwrap_or(false)
258}
259
260struct Prepared {
261    tool: Arc<dyn AgentTool>,
262    args: Value,
263}
264
265enum PreparedOutcome {
266    Run(Prepared),
267    Immediate(ToolResult, bool /*is_error*/),
268}
269
270async fn prepare_one(
271    ctx: &AgentContext,
272    tool_call: &(String, String, Value),
273    config: &AgentLoopConfig,
274    tx: &mpsc::Sender<AgentEvent>,
275) -> PreparedOutcome {
276    let (id, name, args) = tool_call;
277    let _ = tx
278        .send(AgentEvent::ToolExecutionStart {
279            tool_call_id: id.clone(),
280            tool_name: name.clone(),
281            args: args.clone(),
282        })
283        .await;
284
285    let Some(tool) = ctx.find_tool(name).cloned() else {
286        return PreparedOutcome::Immediate(
287            ToolResult::error(format!("Tool {name} not found")),
288            true,
289        );
290    };
291
292    let prepared_args = tool.prepare_arguments(args.clone());
293    if let Err(e) = validate_required(&tool.input_schema(), &prepared_args) {
294        return PreparedOutcome::Immediate(ToolResult::error(e), true);
295    }
296
297    if let Some(gate) = &config.gate {
298        let res = gate
299            .before(ToolCallContext {
300                tool_call_id: id,
301                tool_name: name,
302                args: &prepared_args,
303            })
304            .await;
305        if res.block {
306            let reason = res
307                .reason
308                .unwrap_or_else(|| "Tool execution was blocked".to_string());
309            return PreparedOutcome::Immediate(ToolResult::error(reason), true);
310        }
311    }
312
313    PreparedOutcome::Run(Prepared {
314        tool,
315        args: prepared_args,
316    })
317}
318
319async fn run_prepared(
320    prepared: Prepared,
321    tool_call: &(String, String, Value),
322    cancel: CancellationToken,
323    tx: &mpsc::Sender<AgentEvent>,
324) -> (ToolResult, bool) {
325    let (id, name, _args) = tool_call;
326    let child = cancel.child_token();
327    let result = prepared.tool.execute(prepared.args, child).await;
328    let (result, is_error) = match result {
329        Ok(r) => (r, false),
330        Err(e) => (ToolResult::error(e.to_string()), true),
331    };
332    let _ = tx
333        .send(AgentEvent::ToolExecutionEnd {
334            tool_call_id: id.clone(),
335            tool_name: name.clone(),
336            is_error,
337        })
338        .await;
339    (result, is_error)
340}
341
342fn build_result_message(
343    tool_call: &(String, String, Value),
344    result: ToolResult,
345    is_error: bool,
346) -> ToolResultMessage {
347    let (id, name, _) = tool_call;
348    ToolResultMessage {
349        tool_call_id: id.clone(),
350        tool_name: name.clone(),
351        content: result.content,
352        is_error,
353        timestamp: crate::ai::now_ms(),
354    }
355}
356
357async fn sequential_execute(
358    ctx: &AgentContext,
359    tool_calls: &[(String, String, Value)],
360    config: &AgentLoopConfig,
361    cancel: CancellationToken,
362    tx: &mpsc::Sender<AgentEvent>,
363) -> Vec<ToolResultMessage> {
364    let mut messages = Vec::with_capacity(tool_calls.len());
365    for tc in tool_calls {
366        if cancel.is_cancelled() {
367            break;
368        }
369        let outcome = prepare_one(ctx, tc, config, tx).await;
370        let (result, is_error) = match outcome {
371            PreparedOutcome::Run(prepared) => run_prepared(prepared, tc, cancel.clone(), tx).await,
372            PreparedOutcome::Immediate(result, is_error) => {
373                let (id, name, _) = tc;
374                let _ = tx
375                    .send(AgentEvent::ToolExecutionEnd {
376                        tool_call_id: id.clone(),
377                        tool_name: name.clone(),
378                        is_error,
379                    })
380                    .await;
381                (result, is_error)
382            }
383        };
384        messages.push(build_result_message(tc, result, is_error));
385    }
386    messages
387}
388
389async fn parallel_execute(
390    ctx: &AgentContext,
391    tool_calls: &[(String, String, Value)],
392    config: &AgentLoopConfig,
393    cancel: CancellationToken,
394    tx: &mpsc::Sender<AgentEvent>,
395) -> Vec<ToolResultMessage> {
396    // Prepare sequentially (emits start events in order), then run concurrently.
397    let mut prepared: Vec<PreparedOutcome> = Vec::with_capacity(tool_calls.len());
398    for tc in tool_calls {
399        if cancel.is_cancelled() {
400            break;
401        }
402        prepared.push(prepare_one(ctx, tc, config, tx).await);
403    }
404
405    let futures: Vec<_> = prepared
406        .into_iter()
407        .enumerate()
408        .map(|(i, outcome)| {
409            let tx = tx.clone();
410            let cancel = cancel.clone();
411            let tc = &tool_calls[i];
412            async move {
413                match outcome {
414                    PreparedOutcome::Run(p) => run_prepared(p, tc, cancel, &tx).await,
415                    PreparedOutcome::Immediate(result, is_error) => {
416                        let (id, name, _) = tc;
417                        let _ = tx
418                            .send(AgentEvent::ToolExecutionEnd {
419                                tool_call_id: id.clone(),
420                                tool_name: name.clone(),
421                                is_error,
422                            })
423                            .await;
424                        (result, is_error)
425                    }
426                }
427            }
428        })
429        .collect();
430
431    let results = futures::future::join_all(futures).await;
432    results
433        .into_iter()
434        .enumerate()
435        .map(|(i, (result, is_error))| build_result_message(&tool_calls[i], result, is_error))
436        .collect()
437}
438
439#[cfg(test)]
440mod tests {
441    use super::*;
442    use crate::ai::types::ContentBlock;
443
444    #[test]
445    fn apply_event_assembles_text() {
446        let mut msg = AssistantMessage::empty();
447        apply_event(&mut msg, &AssistantMessageEvent::TextStart { content_index: 0 });
448        apply_event(
449            &mut msg,
450            &AssistantMessageEvent::TextDelta {
451                content_index: 0,
452                delta: "Hello ".into(),
453            },
454        );
455        apply_event(
456            &mut msg,
457            &AssistantMessageEvent::TextDelta {
458                content_index: 0,
459                delta: "world".into(),
460            },
461        );
462        assert_eq!(msg.content.len(), 1);
463        match &msg.content[0] {
464            ContentBlock::Text { text } => assert_eq!(text, "Hello world"),
465            _ => panic!("expected text block"),
466        }
467    }
468}