1pub mod output;
15pub mod patch;
16pub mod prepare;
17pub mod spec;
18pub use spec::UnhandledInvalidToolCall;
19pub mod transcript;
20
21pub use output::OutputMode;
22pub use patch::RequestPatch;
23pub use prepare::{PrepareError, PreparedRequest, prepare_request};
24pub use spec::RunSpec;
25
26use std::collections::{BTreeMap, BTreeSet};
27
28use serde::{Deserialize, Serialize};
29
30use rig_core::completion::{CompletionResponse, FinishReason, ToolDefinition};
31use rig_core::error::ProviderError;
32
33use rig_core::message::{
34 AssistantContent, ToolCall, ToolChoice, ToolName, ToolResult, ToolResultContent, UserContent,
35};
36
37use rig_core::completion::{Message, ResponseIdentity, Usage};
38pub mod policy;
39pub mod response;
40pub mod streamed;
41
42pub use policy::{
43 InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest,
44};
45pub use response::{CompletionCall, MemoryAppend, PromptError, PromptResponse};
46use rig_core::completion::message::turn_delivered_no_answer;
47use rig_core::json_utils;
48use transcript::{
49 TOOL_NOT_EXECUTED_DUE_TO_INVALID_PEER, TranscriptError, assistant_message,
50 assistant_text_from_choice, assistant_turn, build_full_history, build_history_for_request,
51 invalid_tool_retry_user_message, is_empty_assistant_turn, tool_result_message,
52 validate_canonical,
53};
54
55pub use streamed::{
56 PartialStreamedTurn, StreamedInvalidToolCall, StreamedResolution, StreamedTurn,
57 StreamedTurnAssembler, StreamedTurnEvent,
58};
59
60fn unknown_tool_call_error(
62 tool_name: String,
63 available_tools: Vec<String>,
64 allowed_tools: Vec<String>,
65 chat_history: Vec<Message>,
66) -> PromptError {
67 PromptError::UnknownToolCall {
68 tool_name,
69 available_tools,
70 allowed_tools,
71 chat_history,
72 }
73}
74
75#[derive(Clone, Copy)]
76struct InvalidToolCallDiagnostic<'a> {
77 tool_call: &'a ToolCall,
78 executable_tool_names: &'a BTreeSet<String>,
79 allowed_tool_names: &'a BTreeSet<String>,
80 history: &'a [Message],
81 reason: &'a InvalidToolCallReason,
82}
83
84impl InvalidToolCallDiagnostic<'_> {
85 fn unknown(&self, tool_name: String) -> PromptError {
86 unknown_tool_call_error(
87 tool_name,
88 self.executable_tool_names.iter().cloned().collect(),
89 self.allowed_tool_names.iter().cloned().collect(),
90 self.history.to_vec(),
91 )
92 }
93
94 fn unknown_current(&self) -> PromptError {
96 match self.reason {
97 InvalidToolCallReason::UnknownTool => {
98 self.unknown(self.tool_call.function.name.to_string())
99 }
100 InvalidToolCallReason::MalformedArguments { error } => {
101 PromptError::Report(malformed_tool_input_report(self.tool_call, error))
102 }
103 }
104 }
105
106 fn cancelled(&self, reason: String) -> PromptError {
107 PromptError::prompt_cancelled(self.history.to_vec(), reason)
108 }
109}
110
111fn malformed_tool_input_report(tool_call: &ToolCall, error: &str) -> rig_core::error::ErrorReport {
113 rig_core::error::ErrorReport::new(
114 rig_core::error::ErrorKind::Response,
115 format!(
116 "tool call `{}` arrived with malformed JSON input: {error}",
117 tool_call.function.name
118 ),
119 )
120}
121
122enum ValidatedInvalidToolCallAction {
123 Retry { feedback: String },
124 Repair { tool_name: String },
125 Skip { reason: String },
126}
127
128#[derive(Debug, Clone, Serialize, Deserialize)]
130pub enum AgentRunStep {
131 CallModel {
134 prompt: Message,
136 history: Vec<Message>,
139 turn: usize,
141 },
142 CallTools {
145 calls: Vec<PendingToolCall>,
147 },
148 Done(PromptResponse),
150}
151
152#[derive(Debug, Clone, Serialize, Deserialize)]
154pub struct PendingToolCall {
155 pub tool_call: ToolCall,
157 pub preresolved_result: Option<UserContent>,
161}
162
163#[derive(Debug, Clone, Serialize, Deserialize)]
165pub struct ModelTurn {
166 pub message_id: Option<String>,
168 pub response_id: Option<String>,
170 pub provider_request_id: Option<String>,
172 pub choice: Vec<AssistantContent>,
174 pub usage: Usage,
176 pub executable_tool_names: BTreeSet<String>,
178 pub allowed_tool_names: BTreeSet<String>,
180 pub finish_reason: Option<FinishReason>,
182 pub raw: serde_json::Value,
184}
185
186impl ModelTurn {
187 pub fn from_response(resp: &CompletionResponse, prepared: &prepare::PreparedRequest) -> Self {
190 Self::from_response_parts(
191 resp,
192 prepared.executable_tool_names.clone(),
193 prepared.allowed_tool_names.clone(),
194 )
195 }
196
197 pub fn from_response_parts(
202 resp: &CompletionResponse,
203 executable_tool_names: BTreeSet<String>,
204 allowed_tool_names: BTreeSet<String>,
205 ) -> Self {
206 Self::new(
207 resp.message_id.clone(),
208 resp.choice.clone(),
209 resp.usage,
210 executable_tool_names,
211 allowed_tool_names,
212 resp.raw.clone(),
213 )
214 .with_identity(resp.response_id.clone(), resp.provider_request_id.clone())
215 .with_finish_reason(resp.finish_reason())
216 }
217
218 pub fn new(
222 message_id: Option<String>,
223 choice: Vec<AssistantContent>,
224 usage: Usage,
225 executable_tool_names: BTreeSet<String>,
226 allowed_tool_names: BTreeSet<String>,
227 raw: serde_json::Value,
228 ) -> Self {
229 Self {
230 message_id,
231 response_id: None,
232 provider_request_id: None,
233 choice,
234 usage,
235 executable_tool_names,
236 allowed_tool_names,
237 finish_reason: None,
238 raw,
239 }
240 }
241
242 pub fn with_identity(
244 mut self,
245 response_id: Option<String>,
246 provider_request_id: Option<String>,
247 ) -> Self {
248 self.response_id = response_id;
249 self.provider_request_id = provider_request_id;
250 self
251 }
252
253 pub fn with_finish_reason(mut self, finish_reason: Option<FinishReason>) -> Self {
255 self.finish_reason = finish_reason;
256 self
257 }
258}
259
260#[derive(Debug, Clone, Serialize, Deserialize)]
262pub enum ModelTurnOutcome {
263 Continue {
272 response_hook_suppressed: bool,
274 },
275 NeedsResolution(InvalidToolCallContext),
280 TurnRetried,
284}
285
286#[derive(Debug, Clone, Serialize, Deserialize)]
287struct ResolvingState {
288 message_id: Option<String>,
289 original_choice: Vec<AssistantContent>,
292 items: Vec<AssistantContent>,
294 next_index: usize,
296 executable_tool_names: BTreeSet<String>,
297 allowed_tool_names: BTreeSet<String>,
298 skipped: BTreeMap<usize, UserContent>,
301 recovered: bool,
302 any_skipped: bool,
303 has_tool_calls: bool,
304}
305
306fn pending_invalid_call(resolving: &ResolvingState) -> Option<&ToolCall> {
309 match resolving.items.get(resolving.next_index) {
310 Some(AssistantContent::ToolCall(tool_call))
311 if !resolving
312 .allowed_tool_names
313 .contains(tool_call.function.name.as_str()) =>
314 {
315 Some(tool_call)
316 }
317 _ => None,
318 }
319}
320
321fn has_tool_calls(items: &[AssistantContent]) -> bool {
322 items
323 .iter()
324 .any(|item| matches!(item, AssistantContent::ToolCall(_)))
325}
326
327#[derive(Debug, Clone, Serialize, Deserialize)]
328struct TurnState {
329 message_id: Option<String>,
330 items: Vec<AssistantContent>,
331 has_tool_calls: bool,
332 skipped: BTreeMap<usize, UserContent>,
334}
335
336#[derive(Debug, Clone, Serialize, Deserialize)]
337enum RunState {
338 PreparingRequest,
340 AwaitingModel,
342 ResolvingToolCalls(ResolvingState),
345 AwaitingAdvance(TurnState),
348 ExecutingTools(Vec<PendingToolCall>),
352 Done(PromptResponse),
354 Failed,
356}
357
358#[derive(Debug, Clone, Serialize, Deserialize)]
365#[serde(deny_unknown_fields)]
366pub struct AgentRun {
367 #[serde(deserialize_with = "run_format")]
369 format: u32,
370 max_turns: usize,
371 max_invalid_tool_call_retries: usize,
372 unhandled_invalid_tool_call: UnhandledInvalidToolCall,
374 tool_choice: Option<ToolChoice>,
375 output_tool_name: Option<String>,
378 output_schema: Option<serde_json::Value>,
380 max_output_retries: usize,
384 output_retries: usize,
385 chat_history: Option<Vec<Message>>,
386 new_messages: Vec<Message>,
387 current_turn: usize,
388 usage: Usage,
389 completion_calls: Vec<CompletionCall>,
390 completion_call_index: usize,
391 invalid_tool_call_retries: usize,
392 rollback_pending: bool,
395 streamed_completion_call_recorded: bool,
399 previous_model: Option<rig_core::completion::ModelRef>,
406 turn_tools: Option<TurnTools>,
410 entries: Vec<RunEntry>,
412 state: RunState,
413}
414
415pub const RUN_FORMAT: u32 = 1;
417
418fn run_format<'de, D: serde::Deserializer<'de>>(deserializer: D) -> Result<u32, D::Error> {
422 let format = u32::deserialize(deserializer)?;
423 if format == RUN_FORMAT {
424 Ok(format)
425 } else {
426 Err(serde::de::Error::custom(format!(
427 "resume refused: the run is format {format}, this rig reads format {RUN_FORMAT}"
428 )))
429 }
430}
431
432#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
435pub struct RunEntry {
436 pub kind: String,
440 pub turn: usize,
443 pub value: serde_json::Value,
446}
447
448#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
451pub struct TurnTools {
452 pub turn: usize,
455 pub definitions: Vec<ToolDefinition>,
457}
458
459impl TurnTools {
460 pub fn contains(&self, tool_name: &str) -> bool {
462 self.definitions.iter().any(|d| d.name == tool_name)
463 }
464}
465
466impl AgentRun {
467 pub fn new(prompt: impl Into<Message>) -> Self {
470 Self {
471 format: RUN_FORMAT,
472 max_turns: 1,
473 max_invalid_tool_call_retries: 0,
474 unhandled_invalid_tool_call: UnhandledInvalidToolCall::Fail,
475 tool_choice: None,
476 output_tool_name: None,
477 output_schema: None,
478 max_output_retries: 0,
479 output_retries: 0,
480 chat_history: None,
481 new_messages: vec![prompt.into()],
482 current_turn: 0,
483 usage: Usage::default(),
484 completion_calls: Vec::new(),
485 completion_call_index: 0,
486 invalid_tool_call_retries: 0,
487 rollback_pending: false,
488 streamed_completion_call_recorded: false,
489 previous_model: None,
490 turn_tools: None,
491 entries: Vec::new(),
492 state: RunState::PreparingRequest,
493 }
494 }
495
496 pub fn initial_prompt(&self) -> Option<&Message> {
501 (self.current_turn == 0 && matches!(self.state, RunState::PreparingRequest))
502 .then(|| self.new_messages.last())
503 .flatten()
504 }
505
506 pub(crate) fn rewrite_initial_prompt(
514 &mut self,
515 prompt: impl Into<Message>,
516 ) -> Result<(), PromptError> {
517 let started = self.current_turn != 0 || !matches!(self.state, RunState::PreparingRequest);
518 match self.new_messages.last_mut() {
519 Some(slot) if !started => {
520 *slot = prompt.into();
521 Ok(())
522 }
523 _ => Err(PromptError::prompt_cancelled(
524 self.full_history(),
525 "the initial prompt can only be rewritten before the run starts",
526 )),
527 }
528 }
529
530 pub fn append_entry(&mut self, entry: RunEntry) {
532 self.entries.push(entry);
533 }
534
535 pub fn entries(&self) -> &[RunEntry] {
537 &self.entries
538 }
539
540 pub fn entries_of<'a>(&'a self, kind: &'a str) -> impl Iterator<Item = &'a RunEntry> {
542 self.entries.iter().filter(move |entry| entry.kind == kind)
543 }
544
545 pub fn last_entry_of(&self, kind: &str) -> Option<&RunEntry> {
547 self.entries.iter().rev().find(|entry| entry.kind == kind)
548 }
549
550 pub fn advertise_tools(&mut self, turn: usize, definitions: Vec<ToolDefinition>) {
554 self.turn_tools = Some(TurnTools { turn, definitions });
555 }
556
557 pub fn advertised_tools(&self) -> Option<&TurnTools> {
563 self.turn_tools.as_ref()
564 }
565
566 pub fn with_history(mut self, history: Vec<Message>) -> Self {
568 self.chat_history = Some(history);
569 self
570 }
571
572 pub fn max_turns(mut self, max_turns: usize) -> Self {
577 self.max_turns = max_turns;
578 self
579 }
580
581 pub fn with_output_validation(
585 mut self,
586 output_schema: Option<serde_json::Value>,
587 max_output_retries: usize,
588 ) -> Self {
589 self.output_schema = output_schema;
590 self.max_output_retries = max_output_retries;
591 self
592 }
593
594 fn missing_required_output_fields(&self, args: &serde_json::Value) -> Vec<String> {
600 let Some(required) = self
601 .output_schema
602 .as_ref()
603 .and_then(|schema| schema.get("required"))
604 .and_then(|required| required.as_array())
605 else {
606 return Vec::new();
607 };
608 let object = args.as_object();
609 required
610 .iter()
611 .filter_map(|field| field.as_str())
612 .filter(|field| object.is_none_or(|object| !object.contains_key(*field)))
613 .map(str::to_owned)
614 .collect()
615 }
616
617 fn text_satisfies_output_schema(&self, text: &str) -> bool {
620 serde_json::from_str::<serde_json::Value>(text.trim())
621 .ok()
622 .is_some_and(|value| self.missing_required_output_fields(&value).is_empty())
623 }
624
625 pub fn input_chat_history(&self) -> &[Message] {
629 self.chat_history.as_deref().unwrap_or_default()
630 }
631
632 fn can_reprompt_for_output(&self) -> bool {
636 self.output_retries < self.max_output_retries && self.current_turn < self.max_turns
637 }
638
639 fn reprompt_for_output(&mut self) -> Result<AgentRunStep, PromptError> {
644 self.output_retries += 1;
645 self.state = RunState::PreparingRequest;
646 self.next_step()
647 }
648
649 pub fn max_invalid_tool_call_retries(mut self, retries: usize) -> Self {
653 self.max_invalid_tool_call_retries = retries;
654 self
655 }
656
657 pub fn with_unhandled_invalid_tool_call(mut self, policy: UnhandledInvalidToolCall) -> Self {
660 self.unhandled_invalid_tool_call = policy;
661 self
662 }
663
664 pub fn with_tool_choice(mut self, tool_choice: ToolChoice) -> Self {
668 self.tool_choice = Some(tool_choice);
669 self
670 }
671
672 pub fn with_output_tool_name(mut self, name: impl Into<String>) -> Self {
676 self.output_tool_name = Some(name.into());
677 self
678 }
679
680 #[must_use = "a refused commit means the run already pinned a name"]
688 pub fn commit_output_tool_name(&mut self, name: impl Into<String>) -> bool {
689 if self.output_tool_name.is_some() {
690 return false;
691 }
692 self.output_tool_name = Some(name.into());
693 true
694 }
695
696 pub fn output_tool_name(&self) -> Option<&str> {
700 self.output_tool_name.as_deref()
701 }
702
703 pub fn usage(&self) -> Usage {
705 self.usage
706 }
707
708 pub fn turn(&self) -> usize {
710 self.current_turn
711 }
712
713 pub fn previous_model(&self) -> Option<&rig_core::completion::ModelRef> {
715 self.previous_model.as_ref()
716 }
717
718 pub fn set_previous_model(&mut self, model: rig_core::completion::ModelRef) {
721 self.previous_model = Some(model);
722 }
723
724 pub fn completion_calls(&self) -> &[CompletionCall] {
726 &self.completion_calls
727 }
728
729 pub fn messages(&self) -> &[Message] {
732 &self.new_messages
733 }
734
735 pub fn accepted_turn_choice(&self) -> Option<Vec<AssistantContent>> {
737 let RunState::AwaitingAdvance(turn) = &self.state else {
738 return None;
739 };
740
741 if turn.items.is_empty() {
742 return None;
743 }
744 Some(turn.items.clone())
745 }
746
747 pub fn replace_accepted_turn_choice(
750 &mut self,
751 choice: Vec<AssistantContent>,
752 ) -> Result<(), PromptError> {
753 let replacement_has_tool_calls = choice
754 .iter()
755 .any(|item| matches!(item, AssistantContent::ToolCall(_)));
756 let parked_has_tool_calls = match &self.state {
757 RunState::AwaitingAdvance(turn) => turn.has_tool_calls,
758 _ => {
759 return Err(self.protocol_violation(
760 "replace_accepted_turn_choice called without an accepted turn awaiting advancement",
761 ));
762 }
763 };
764 if parked_has_tool_calls || replacement_has_tool_calls {
765 return Err(PromptError::prompt_cancelled(
766 self.full_history(),
767 "a completion outcome replacement does not support tool-bearing model turns; patch or deny the tool dispatches instead",
768 ));
769 }
770 if let RunState::AwaitingAdvance(turn) = &mut self.state {
771 turn.items = choice;
772 }
773 Ok(())
774 }
775
776 pub fn retry_model_turn(&mut self, request: RetryRequest) -> Result<(), PromptError> {
790 let turn = match std::mem::replace(&mut self.state, RunState::Failed) {
791 RunState::AwaitingAdvance(turn) => turn,
792 other => {
793 self.state = other;
794 return Err(self.protocol_violation(
795 "retry_model_turn called without an accepted turn awaiting advancement",
796 ));
797 }
798 };
799
800 if turn.has_tool_calls {
801 return Err(PromptError::prompt_cancelled(
802 self.full_history(),
803 "model-turn retry does not support tool-bearing model turns; use tool-call hooks instead",
804 ));
805 }
806
807 match request {
808 RetryRequest::Repeat => {}
809 RetryRequest::Feedback(feedback) => {
810 self.new_messages
813 .extend(assistant_turn(turn.message_id, turn.items));
814 self.new_messages.push(Message::user(feedback));
815 }
816 }
817
818 self.state = RunState::PreparingRequest;
819 Ok(())
820 }
821
822 pub fn full_history(&self) -> Vec<Message> {
824 build_full_history(self.chat_history.as_deref(), self.new_messages.clone())
825 }
826
827 pub fn is_done(&self) -> bool {
829 matches!(self.state, RunState::Done(_))
830 }
831
832 pub fn response(&self) -> Option<&PromptResponse> {
837 match &self.state {
838 RunState::Done(response) => Some(response),
839 _ => None,
840 }
841 }
842
843 pub fn cancel_error(&self, reason: impl Into<String>) -> PromptError {
846 PromptError::prompt_cancelled(self.full_history(), reason)
847 }
848
849 pub fn pending_invalid_tool_call(&self) -> Option<InvalidToolCallContext> {
853 let RunState::ResolvingToolCalls(resolving) = &self.state else {
854 return None;
855 };
856 let tool_call = pending_invalid_call(resolving)?;
857
858 Some(InvalidToolCallContext {
859 tool_name: tool_call.function.name.to_string(),
860 tool_call_id: Some(tool_call.id.clone()),
861 args: Some(json_utils::serialize_json_value(
862 &tool_call.function.arguments,
863 )),
864 available_tools: resolving.executable_tool_names.iter().cloned().collect(),
865 allowed_tools: resolving.allowed_tool_names.iter().cloned().collect(),
866 tool_choice: self.tool_choice.clone(),
867 chat_history: self.diagnostic_history(resolving),
868 is_streaming: false,
869 reason: InvalidToolCallReason::UnknownTool,
870 })
871 }
872
873 pub fn next_step(&mut self) -> Result<AgentRunStep, PromptError> {
881 match std::mem::replace(&mut self.state, RunState::Failed) {
882 RunState::PreparingRequest => {
883 let Some((prompt_ref, history_for_turn)) = self.new_messages.split_last() else {
884 return Err(PromptError::prompt_cancelled(
885 self.full_history(),
886 "prompt loop lost its pending prompt",
887 ));
888 };
889 let prompt = prompt_ref.clone();
890
891 if self.current_turn >= self.max_turns {
892 return Err(PromptError::MaxTurnsError {
893 max_turns: self.max_turns,
894 chat_history: self.full_history(),
895 prompt,
896 });
897 }
898
899 let history =
900 build_history_for_request(self.chat_history.as_deref(), history_for_turn);
901 self.current_turn += 1;
902 self.rollback_pending = false;
903 self.streamed_completion_call_recorded = false;
904 self.state = RunState::AwaitingModel;
905 Ok(AgentRunStep::CallModel {
906 prompt,
907 history,
908 turn: self.current_turn,
909 })
910 }
911 RunState::AwaitingAdvance(turn_state) => {
912 let TurnState {
913 message_id,
914 items,
915 has_tool_calls,
916 skipped,
917 } = turn_state;
918 if has_tool_calls
921 && let Some(output_tool_name) = self.output_tool_name.clone()
922 && let Some(tool_call) = items.iter().find_map(|item| match item {
923 AssistantContent::ToolCall(tc) if tc.function.name == output_tool_name => {
924 Some(tc)
925 }
926 _ => None,
927 })
928 {
929 let output_tool_calls = items
930 .iter()
931 .filter(|item| {
932 matches!(
933 item,
934 AssistantContent::ToolCall(tc)
935 if tc.function.name == output_tool_name
936 )
937 })
938 .count();
939 let args = tool_call.function.arguments.clone();
940 let tool_call_id = tool_call.id.clone();
941 let output = json_utils::serialize_json_value(&args);
942
943 let missing = self.missing_required_output_fields(&args);
944 if !missing.is_empty() && self.can_reprompt_for_output() {
945 self.new_messages
946 .extend(assistant_message(message_id, items.clone()));
947 let feedback = format!(
948 "The `{output_tool_name}` arguments were missing required field(s): \
949 {}. Call `{output_tool_name}` again with every required field.",
950 missing.join(", ")
951 );
952 if let Some(user_message) =
953 invalid_tool_retry_user_message(&items, &tool_call_id, &feedback)
954 {
955 self.new_messages.push(user_message);
956 }
957 return self.reprompt_for_output();
958 }
959
960 let mut final_items: Vec<AssistantContent> = items
963 .iter()
964 .filter(|item| !matches!(item, AssistantContent::ToolCall(_)))
965 .cloned()
966 .collect();
967 final_items.push(AssistantContent::text(output.clone()));
968 self.new_messages
969 .extend(assistant_message(message_id, final_items.clone()));
970
971 return Ok(self.finish(output, final_items, output_tool_calls));
972 }
973
974 if turn_delivered_no_answer(&items)
977 && let Some(reason) = self.truncating_finish_reason()
978 {
979 return Err(ProviderError::Response(reason.no_answer_message()).into());
980 }
981
982 self.new_messages
984 .extend(assistant_turn(message_id, items.clone()));
985
986 if has_tool_calls {
987 self.output_retries = 0;
989 let calls: Vec<PendingToolCall> = items
990 .iter()
991 .enumerate()
992 .filter_map(|(index, item)| match item {
993 AssistantContent::ToolCall(tool_call) => Some(PendingToolCall {
994 tool_call: tool_call.clone(),
995 preresolved_result: skipped.get(&index).cloned(),
996 }),
997 _ => None,
998 })
999 .collect();
1000 self.state = RunState::ExecutingTools(calls.clone());
1001 Ok(AgentRunStep::CallTools { calls })
1002 } else {
1003 if let Some(output_tool_name) = self.output_tool_name.clone()
1006 && !is_empty_assistant_turn(&items)
1007 && self.can_reprompt_for_output()
1008 && !self.text_satisfies_output_schema(&assistant_text_from_choice(&items))
1009 {
1010 let feedback = format!(
1011 "Provide your final answer by calling the `{output_tool_name}` tool \
1012 with the structured result as its arguments, not as plain text."
1013 );
1014 self.new_messages.push(Message::user(feedback));
1015 return self.reprompt_for_output();
1016 }
1017
1018 Ok(self.finish(assistant_text_from_choice(&items), items, 0))
1019 }
1020 }
1021 RunState::ExecutingTools(calls) => {
1022 let step = AgentRunStep::CallTools {
1025 calls: calls.clone(),
1026 };
1027 self.state = RunState::ExecutingTools(calls);
1028 Ok(step)
1029 }
1030 RunState::Done(response) => {
1031 let step = AgentRunStep::Done(response.clone());
1032 self.state = RunState::Done(response);
1033 Ok(step)
1034 }
1035 state @ (RunState::AwaitingModel | RunState::ResolvingToolCalls(_)) => {
1036 let reason = match &state {
1037 RunState::AwaitingModel => {
1038 "next_step called while a model response is pending; feed it via model_response first"
1039 }
1040 _ => {
1041 "next_step called while an invalid tool-call resolution is pending; answer it via resolve_invalid_tool_call first"
1042 }
1043 };
1044 self.state = state;
1045 Err(self.protocol_violation(reason))
1046 }
1047 RunState::Failed => Err(self.protocol_violation(
1048 "next_step called after the run already failed or was misdriven",
1049 )),
1050 }
1051 }
1052
1053 pub fn model_response(&mut self, turn: ModelTurn) -> Result<ModelTurnOutcome, PromptError> {
1059 if !matches!(self.state, RunState::AwaitingModel) {
1060 return Err(
1061 self.protocol_violation("model_response called without a pending CallModel step")
1062 );
1063 }
1064 if self.streamed_completion_call_recorded {
1065 return Err(self.protocol_violation(
1066 "model_response called after record_streamed_completion_call for the same turn; feed streamed turns via streamed_turn",
1067 ));
1068 }
1069
1070 self.record_completion_call(
1071 turn.usage,
1072 ResponseIdentity {
1073 message_id: turn.message_id.clone(),
1075 response_id: turn.response_id,
1076 provider_request_id: turn.provider_request_id,
1077 },
1078 turn.finish_reason,
1079 turn.raw,
1080 );
1081
1082 let items: Vec<AssistantContent> = turn.choice.clone();
1083 let has_tool_calls = has_tool_calls(&items);
1084
1085 self.state = RunState::ResolvingToolCalls(ResolvingState {
1086 message_id: turn.message_id,
1087 original_choice: turn.choice,
1088 items,
1089 next_index: 0,
1090 executable_tool_names: turn.executable_tool_names,
1091 allowed_tool_names: turn.allowed_tool_names,
1092 skipped: BTreeMap::new(),
1093 recovered: false,
1094 any_skipped: false,
1095 has_tool_calls,
1096 });
1097
1098 self.advance_resolution()
1099 }
1100
1101 fn truncating_finish_reason(&self) -> Option<&FinishReason> {
1104 self.completion_calls
1105 .last()?
1106 .finish_reason
1107 .as_ref()
1108 .filter(|reason| reason.truncated_output())
1109 }
1110
1111 fn record_completion_call(
1112 &mut self,
1113 usage: Usage,
1114 identity: ResponseIdentity,
1115 finish_reason: Option<FinishReason>,
1116 raw: serde_json::Value,
1117 ) -> CompletionCall {
1118 let call = CompletionCall::new(self.completion_call_index, usage, raw)
1119 .with_identity(identity)
1120 .with_finish_reason(finish_reason);
1121 self.completion_call_index += 1;
1122 self.completion_calls.push(call.clone());
1123 self.usage += usage;
1124 call
1125 }
1126
1127 fn finish(
1131 &mut self,
1132 output: String,
1133 content: Vec<AssistantContent>,
1134 output_tool_calls: usize,
1135 ) -> AgentRunStep {
1136 let response = PromptResponse::new(output, self.usage)
1137 .with_messages(self.new_messages.clone())
1138 .with_completion_calls(self.completion_calls.clone())
1139 .with_output_tool_calls(output_tool_calls)
1140 .with_content(content);
1141 self.state = RunState::Done(response.clone());
1142 AgentRunStep::Done(response)
1143 }
1144
1145 fn finalize_turn(
1149 &mut self,
1150 message_id: Option<String>,
1151 items: Vec<AssistantContent>,
1152 has_tool_calls: bool,
1153 skipped: BTreeMap<usize, UserContent>,
1154 ) {
1155 self.state = RunState::AwaitingAdvance(TurnState {
1156 message_id,
1157 items,
1158 has_tool_calls,
1159 skipped,
1160 });
1161 }
1162
1163 fn validate_invalid_tool_call_action(
1168 &mut self,
1169 action: InvalidToolCallAction,
1170 diagnostic: InvalidToolCallDiagnostic<'_>,
1171 ) -> Result<ValidatedInvalidToolCallAction, PromptError> {
1172 let result = match action {
1173 InvalidToolCallAction::Fail => Err(diagnostic.unknown_current()),
1174 InvalidToolCallAction::Retry { feedback } => {
1175 if self.invalid_tool_call_retries >= self.max_invalid_tool_call_retries {
1176 Err(diagnostic.unknown_current())
1177 } else {
1178 self.invalid_tool_call_retries += 1;
1179 Ok(ValidatedInvalidToolCallAction::Retry { feedback })
1180 }
1181 }
1182 InvalidToolCallAction::Repair { tool_name } => match diagnostic.reason {
1183 InvalidToolCallReason::MalformedArguments { .. } => {
1188 Err(diagnostic.unknown_current())
1189 }
1190 InvalidToolCallReason::UnknownTool => {
1191 if diagnostic.allowed_tool_names.contains(&tool_name) {
1192 Ok(ValidatedInvalidToolCallAction::Repair { tool_name })
1193 } else {
1194 Err(diagnostic.unknown(tool_name))
1195 }
1196 }
1197 },
1198 InvalidToolCallAction::Stop { reason } => Err(diagnostic.cancelled(reason)),
1199 InvalidToolCallAction::Skip { reason } => {
1200 if matches!(self.tool_choice, Some(ToolChoice::None)) {
1201 Err(diagnostic.unknown_current())
1202 } else {
1203 Ok(ValidatedInvalidToolCallAction::Skip { reason })
1204 }
1205 }
1206 };
1207
1208 if result.is_err() {
1209 self.state = RunState::Failed;
1210 }
1211 result
1212 }
1213
1214 pub fn resolve_invalid_tool_call(
1230 &mut self,
1231 action: InvalidToolCallAction,
1232 ) -> Result<ModelTurnOutcome, PromptError> {
1233 let mut resolving = self.take_resolving(
1234 "resolve_invalid_tool_call called without a pending invalid tool call",
1235 )?;
1236 let Some(tool_call) = pending_invalid_call(&resolving).cloned() else {
1237 self.state = RunState::ResolvingToolCalls(resolving);
1238 return Err(self.protocol_violation(
1239 "resolve_invalid_tool_call called without a pending invalid tool call",
1240 ));
1241 };
1242
1243 let diagnostic_history = self.diagnostic_history(&resolving);
1244 let action = self.validate_invalid_tool_call_action(
1245 action,
1246 InvalidToolCallDiagnostic {
1247 tool_call: &tool_call,
1248 executable_tool_names: &resolving.executable_tool_names,
1249 allowed_tool_names: &resolving.allowed_tool_names,
1250 reason: &InvalidToolCallReason::UnknownTool,
1251 history: &diagnostic_history,
1252 },
1253 )?;
1254
1255 match action {
1256 ValidatedInvalidToolCallAction::Retry { feedback } => {
1257 self.new_messages.extend(assistant_message(
1258 resolving.message_id.clone(),
1259 resolving.original_choice.clone(),
1260 ));
1261 let Some(user_message) = invalid_tool_retry_user_message(
1262 &resolving.original_choice,
1263 &tool_call.id,
1264 &feedback,
1265 ) else {
1266 return Err(PromptError::prompt_cancelled(
1267 diagnostic_history,
1268 "invalid tool call retry produced no retry messages",
1269 ));
1270 };
1271 self.new_messages.push(user_message);
1272 self.state = RunState::PreparingRequest;
1273 Ok(ModelTurnOutcome::TurnRetried)
1274 }
1275 ValidatedInvalidToolCallAction::Repair { tool_name } => {
1276 if let Some(AssistantContent::ToolCall(tool_call)) =
1277 resolving.items.get_mut(resolving.next_index)
1278 && let Ok(tool_name) = ToolName::new(tool_name)
1279 {
1280 tool_call.function.name = tool_name;
1281 }
1282 resolving.recovered = true;
1283 self.state = RunState::ResolvingToolCalls(resolving);
1284 self.advance_resolution()
1285 }
1286 ValidatedInvalidToolCallAction::Skip { reason } => {
1287 let user_content = UserContent::tool_result(
1288 tool_call.id.clone(),
1289 tool_call.function.name.clone(),
1290 vec![ToolResultContent::from(reason)],
1291 );
1292 resolving.skipped.insert(resolving.next_index, user_content);
1296 resolving.recovered = true;
1297 resolving.any_skipped = true;
1298 resolving.next_index += 1;
1299 self.state = RunState::ResolvingToolCalls(resolving);
1300 self.advance_resolution()
1301 }
1302 }
1303 }
1304
1305 pub fn resolve_unhandled_invalid_tool_call(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1309 match self.unhandled_invalid_tool_call {
1310 UnhandledInvalidToolCall::Fail => {
1311 self.resolve_invalid_tool_call(InvalidToolCallAction::fail())
1312 }
1313 UnhandledInvalidToolCall::Ignore => self.ignore_invalid_tool_call(),
1314 }
1315 }
1316
1317 pub fn ignore_invalid_tool_call(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1320 let mut resolving = self.take_resolving(
1321 "ignore_invalid_tool_call called without a pending invalid tool call",
1322 )?;
1323
1324 if pending_invalid_call(&resolving).is_none() {
1325 self.state = RunState::ResolvingToolCalls(resolving);
1326 return Err(self.protocol_violation(
1327 "ignore_invalid_tool_call called without a pending invalid tool call",
1328 ));
1329 }
1330
1331 resolving.items.remove(resolving.next_index);
1332 resolving.has_tool_calls = has_tool_calls(&resolving.items);
1333 self.state = RunState::ResolvingToolCalls(resolving);
1334 self.advance_resolution()
1335 }
1336
1337 pub fn tool_results(&mut self, results: Vec<UserContent>) -> Result<(), PromptError> {
1343 let RunState::ExecutingTools(pending) = &self.state else {
1344 return Err(
1345 self.protocol_violation("tool_results called without a pending CallTools step")
1346 );
1347 };
1348 let mut unanswered: Vec<rig_core::message::CallId> = pending
1351 .iter()
1352 .map(|call| call.tool_call.id.clone())
1353 .collect();
1354
1355 if results.is_empty() {
1356 self.state = RunState::Failed;
1357 return Err(PromptError::prompt_cancelled(
1358 self.full_history(),
1359 "tool execution produced no tool results",
1360 ));
1361 }
1362 for result in &results {
1363 let UserContent::ToolResult(tool_result) = result else {
1364 return Err(self.protocol_violation(
1365 "tool_results received content that is not a tool result",
1366 ));
1367 };
1368 let Some(index) = unanswered.iter().position(|id| tool_result.call == *id) else {
1369 return Err(self.protocol_violation(&format!(
1370 "tool_results received a result for unknown or already-answered tool call id `{}`",
1371 tool_result.call
1372 )));
1373 };
1374 unanswered.swap_remove(index);
1375 }
1376 if !unanswered.is_empty() {
1377 return Err(self.protocol_violation(&format!(
1378 "tool_results left pending tool call id(s) unanswered: {unanswered:?}"
1379 )));
1380 }
1381
1382 self.new_messages.push(Message::User { content: results });
1384 self.state = RunState::PreparingRequest;
1385 Ok(())
1386 }
1387
1388 fn take_resolving(&mut self, violation: &str) -> Result<ResolvingState, PromptError> {
1392 match std::mem::replace(&mut self.state, RunState::Failed) {
1393 RunState::ResolvingToolCalls(resolving) => Ok(resolving),
1394 other => {
1395 self.state = other;
1396 Err(self.protocol_violation(violation))
1397 }
1398 }
1399 }
1400
1401 fn advance_resolution(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1404 let mut resolving =
1405 self.take_resolving("internal: advance_resolution outside of tool-call resolution")?;
1406 while let Some(item) = resolving.items.get(resolving.next_index) {
1407 match item {
1408 AssistantContent::ToolCall(tool_call)
1409 if !resolving
1410 .allowed_tool_names
1411 .contains(tool_call.function.name.as_str()) =>
1412 {
1413 break;
1414 }
1415 _ => resolving.next_index += 1,
1416 }
1417 }
1418
1419 if resolving.next_index < resolving.items.len() {
1420 self.state = RunState::ResolvingToolCalls(resolving);
1421 return match self.pending_invalid_tool_call() {
1422 Some(context) => Ok(ModelTurnOutcome::NeedsResolution(context)),
1423 None => Err(self.protocol_violation(
1424 "internal: pending invalid tool call could not be derived",
1425 )),
1426 };
1427 }
1428
1429 let ResolvingState {
1430 message_id,
1431 items,
1432 mut skipped,
1433 recovered,
1434 any_skipped,
1435 has_tool_calls,
1436 ..
1437 } = resolving;
1438
1439 if any_skipped {
1442 for (index, item) in items.iter().enumerate() {
1443 if let AssistantContent::ToolCall(tool_call) = item {
1444 skipped.entry(index).or_insert_with(|| {
1445 tool_result_message(
1446 tool_call.id.clone(),
1447 tool_call.function.name.clone(),
1448 TOOL_NOT_EXECUTED_DUE_TO_INVALID_PEER.to_string(),
1449 )
1450 });
1451 }
1452 }
1453 }
1454
1455 self.finalize_turn(message_id, items, has_tool_calls, skipped);
1456 Ok(ModelTurnOutcome::Continue {
1457 response_hook_suppressed: recovered,
1458 })
1459 }
1460
1461 pub fn record_streamed_completion_call(
1469 &mut self,
1470 usage: Usage,
1471 identity: ResponseIdentity,
1472 finish_reason: Option<FinishReason>,
1473 raw: serde_json::Value,
1474 ) -> Result<CompletionCall, PromptError> {
1475 let recordable = matches!(self.state, RunState::AwaitingModel)
1476 || (matches!(self.state, RunState::PreparingRequest) && self.rollback_pending);
1477 if !recordable {
1478 return Err(self.protocol_violation(
1479 "record_streamed_completion_call called without a pending or rolled-back CallModel step",
1480 ));
1481 }
1482 if self.streamed_completion_call_recorded {
1483 return Err(self.protocol_violation(
1484 "record_streamed_completion_call called twice for the same model turn",
1485 ));
1486 }
1487 self.streamed_completion_call_recorded = true;
1488
1489 Ok(self.record_completion_call(usage, identity, finish_reason, raw))
1490 }
1491
1492 pub fn streamed_invalid_tool_call_context(
1495 &self,
1496 partial: &PartialStreamedTurn,
1497 invalid: &StreamedInvalidToolCall,
1498 ) -> InvalidToolCallContext {
1499 InvalidToolCallContext {
1500 tool_name: invalid.tool_call.function.name.to_string(),
1501 tool_call_id: Some(invalid.tool_call.id.clone()),
1502 args: invalid.args.clone(),
1503 available_tools: invalid.executable_tool_names.iter().cloned().collect(),
1504 allowed_tools: invalid.allowed_tool_names.iter().cloned().collect(),
1505 tool_choice: self.tool_choice.clone(),
1506 chat_history: self
1507 .streamed_diagnostic_history(partial, Some(invalid.tool_call.clone())),
1508 is_streaming: true,
1509 reason: invalid.reason.clone(),
1510 }
1511 }
1512
1513 pub fn resolve_streamed_invalid_tool_call(
1519 &mut self,
1520 partial: &PartialStreamedTurn,
1521 invalid: &StreamedInvalidToolCall,
1522 action: InvalidToolCallAction,
1523 ) -> Result<StreamedResolution, PromptError> {
1524 if !matches!(self.state, RunState::AwaitingModel) {
1525 return Err(self.protocol_violation(
1526 "resolve_streamed_invalid_tool_call called without a pending CallModel step",
1527 ));
1528 }
1529
1530 let diagnostic_history =
1531 self.streamed_diagnostic_history(partial, Some(invalid.tool_call.clone()));
1532 let action = self.validate_invalid_tool_call_action(
1533 action,
1534 InvalidToolCallDiagnostic {
1535 tool_call: &invalid.tool_call,
1536 executable_tool_names: &invalid.executable_tool_names,
1537 allowed_tool_names: &invalid.allowed_tool_names,
1538 reason: &invalid.reason,
1539 history: &diagnostic_history,
1540 },
1541 )?;
1542
1543 match action {
1544 ValidatedInvalidToolCallAction::Retry { feedback } => self.abandon_streamed_turn(
1545 partial,
1546 invalid,
1547 feedback,
1548 diagnostic_history,
1549 "invalid tool call retry produced no retry messages",
1550 None,
1551 ),
1552 ValidatedInvalidToolCallAction::Repair { tool_name } => {
1553 Ok(StreamedResolution::Repaired { tool_name })
1554 }
1555 ValidatedInvalidToolCallAction::Skip { reason } => {
1556 let skipped_tool_result = invalid
1560 .tool_call
1561 .result(vec![ToolResultContent::text(reason.as_str())]);
1562 self.abandon_streamed_turn(
1563 partial,
1564 invalid,
1565 reason,
1566 diagnostic_history,
1567 "invalid tool call skip produced no recovery messages",
1568 Some(skipped_tool_result),
1569 )
1570 }
1571 }
1572 }
1573
1574 pub fn ignore_streamed_invalid_tool_call(&mut self) -> Result<StreamedResolution, PromptError> {
1578 if !matches!(self.state, RunState::AwaitingModel) {
1579 return Err(self.protocol_violation(
1580 "ignore_streamed_invalid_tool_call called without a pending CallModel step",
1581 ));
1582 }
1583 Ok(StreamedResolution::Ignored)
1584 }
1585
1586 fn abandon_streamed_turn(
1590 &mut self,
1591 partial: &PartialStreamedTurn,
1592 invalid: &StreamedInvalidToolCall,
1593 feedback: String,
1594 diagnostic_history: Vec<Message>,
1595 no_messages_reason: &str,
1596 skipped_tool_result: Option<ToolResult>,
1597 ) -> Result<StreamedResolution, PromptError> {
1598 let Some((assistant_message, user_message)) =
1599 partial.rollback_messages(invalid.tool_call.clone(), feedback)
1600 else {
1601 self.state = RunState::Failed;
1602 return Err(PromptError::prompt_cancelled(
1603 diagnostic_history,
1604 no_messages_reason,
1605 ));
1606 };
1607 self.new_messages.push(assistant_message);
1608 self.new_messages.push(user_message);
1609 self.rollback_pending = true;
1610 self.state = RunState::PreparingRequest;
1611 Ok(StreamedResolution::TurnAbandoned {
1612 skipped_tool_result,
1613 })
1614 }
1615
1616 pub fn streamed_turn(&mut self, turn: StreamedTurn) -> Result<(), PromptError> {
1624 if !matches!(self.state, RunState::AwaitingModel) {
1625 return Err(
1626 self.protocol_violation("streamed_turn called without a pending CallModel step")
1627 );
1628 }
1629 if !self.streamed_completion_call_recorded {
1630 return Err(self.protocol_violation(
1631 "streamed_turn called before record_streamed_completion_call recorded the turn's completion call",
1632 ));
1633 }
1634
1635 let has_tool_calls = has_tool_calls(&turn.choice);
1636
1637 for item in &turn.choice {
1638 let AssistantContent::ToolCall(tool_call) = item else {
1639 continue;
1640 };
1641 if !turn
1642 .allowed_tool_names
1643 .contains(tool_call.function.name.as_str())
1644 {
1645 let mut diagnostic_messages = self.new_messages.clone();
1646 diagnostic_messages
1647 .extend(assistant_turn(turn.message_id.clone(), turn.choice.clone()));
1648 let diagnostic_history =
1649 build_full_history(self.chat_history.as_deref(), diagnostic_messages);
1650 self.state = RunState::Failed;
1651 return Err(unknown_tool_call_error(
1652 tool_call.function.name.to_string(),
1653 turn.executable_tool_names.iter().cloned().collect(),
1654 turn.allowed_tool_names.iter().cloned().collect(),
1655 diagnostic_history,
1656 ));
1657 }
1658 }
1659
1660 self.finalize_turn(
1661 turn.message_id,
1662 turn.choice,
1663 has_tool_calls,
1664 BTreeMap::new(),
1665 );
1666 Ok(())
1667 }
1668
1669 fn streamed_diagnostic_history(
1672 &self,
1673 partial: &PartialStreamedTurn,
1674 current_tool_call: Option<ToolCall>,
1675 ) -> Vec<Message> {
1676 let mut messages = self.new_messages.clone();
1677 if let Some(assistant) = partial.assistant_message(current_tool_call) {
1678 messages.push(assistant);
1679 }
1680 build_full_history(self.chat_history.as_deref(), messages)
1681 }
1682
1683 fn diagnostic_history(&self, resolving: &ResolvingState) -> Vec<Message> {
1686 let mut diagnostic_messages = self.new_messages.clone();
1687 diagnostic_messages.extend(assistant_message(
1688 resolving.message_id.clone(),
1689 resolving.original_choice.clone(),
1690 ));
1691 build_full_history(self.chat_history.as_deref(), diagnostic_messages)
1692 }
1693
1694 fn protocol_violation(&self, reason: &str) -> PromptError {
1695 PromptError::prompt_cancelled(
1696 self.full_history(),
1697 format!("agent run driver protocol violation: {reason}"),
1698 )
1699 }
1700}
1701
1702impl AgentRun {
1703 pub fn from_spec(
1709 spec: &RunSpec,
1710 prompt: impl Into<Message>,
1711 history: Option<Vec<Message>>,
1712 ) -> Self {
1713 let mut run = AgentRun::new(prompt)
1714 .max_turns(spec.effective_max_turns())
1715 .max_invalid_tool_call_retries(spec.max_invalid_tool_call_retries)
1716 .with_unhandled_invalid_tool_call(spec.unhandled_invalid_tool_call)
1717 .with_output_validation(spec.output_schema.clone(), RunSpec::DEFAULT_OUTPUT_RETRIES);
1718 if let Some(history) = history {
1719 run = run.with_history(history);
1720 }
1721 if let Some(tool_choice) = spec.tool_choice.clone() {
1722 run = run.with_tool_choice(tool_choice);
1723 }
1724 if let Some(name) = spec.output_tool_name.clone() {
1725 run = run.with_output_tool_name(name);
1726 }
1727 run
1728 }
1729}
1730
1731impl AgentRun {
1732 pub fn with_validated_history(self, history: Vec<Message>) -> Result<Self, TranscriptError> {
1738 validate_canonical(&history)?;
1739 Ok(self.with_history(history))
1740 }
1741}
1742
1743#[cfg(not(target_family = "wasm"))]
1746const _: fn() = || {
1747 fn assert_send_sync_static<T: Send + Sync + 'static>() {}
1748 assert_send_sync_static::<AgentRun>();
1749 assert_send_sync_static::<AgentRunStep>();
1750 assert_send_sync_static::<PendingToolCall>();
1751 assert_send_sync_static::<ModelTurn>();
1752 assert_send_sync_static::<StreamedTurn>();
1753 assert_send_sync_static::<StreamedTurnAssembler>();
1754 assert_send_sync_static::<PromptResponse>();
1755 assert_send_sync_static::<CompletionCall>();
1756 assert_send_sync_static::<PromptError>();
1757 assert_send_sync_static::<TurnTools>();
1758 assert_send_sync_static::<RunEntry>();
1759};
1760
1761#[cfg(test)]
1762mod tests;