1mod calls;
15mod committed;
16pub mod output;
17pub mod patch;
18pub mod prepare;
19pub mod spec;
20pub use spec::UnhandledInvalidToolCall;
21pub(crate) mod transcript;
22
23mod batch;
24use batch::{ToolBatch, ToolSlot};
25
26pub use calls::{ExecCall, MalformedCall, PendingToolCall, ToolAnswer};
27pub use committed::{CommittedItem, project};
28pub use output::OutputMode;
29pub use patch::RequestPatch;
30pub use prepare::{PrepareError, PreparedRequest, prepare_request};
31pub use spec::RunSpec;
32
33use std::collections::BTreeMap;
34use std::sync::Arc;
35
36use serde::{Deserialize, Serialize};
37
38use rig_core::completion::{CompletionResponse, FinishReason, ToolDefinition};
39use rig_core::error::ProviderError;
40
41use rig_core::conversation::Aside;
42use rig_core::conversation::pairing::{PairingError, validate};
43use rig_core::message::{AssistantContent, AssistantMessage, ToolCall, ToolName, UserContent};
44use rig_core::tool::feedback::{
45 invalid_arguments_feedback, not_executed, tool_result_message, tool_result_output,
46};
47
48use calls::AnswerKind;
49
50use rig_core::completion::{Message, ResponseIdentity, Usage};
51pub mod policy;
52pub mod response;
53pub mod streamed;
54
55pub use policy::{
56 InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest, TurnPolicy,
57};
58pub use response::{CompletionCall, PromptError, PromptResponse};
59use rig_core::completion::message::turn_failure;
60use rig_core::structured_output;
61use transcript::{assistant_message, assistant_turn, choice_text, invalid_tool_retry_user_message};
62
63pub use streamed::{
64 PartialStreamedTurn, StreamedInvalidToolCall, StreamedResolution, StreamedTurn,
65 StreamedTurnAssembler, StreamedTurnEvent,
66};
67
68enum ValidatedInvalidToolCallAction {
69 Retry { feedback: String },
70 Repair { tool_name: String },
71 Skip { reason: String },
72}
73
74#[derive(Debug, Clone, Serialize, Deserialize)]
76pub enum AgentRunStep {
77 CallModel {
82 prompt: Arc<Message>,
84 history: Vec<Arc<Message>>,
88 turn: usize,
90 },
91 CallTools {
94 calls: Vec<PendingToolCall>,
96 },
97 Done(PromptResponse),
99}
100
101#[derive(Debug, Clone, Serialize, Deserialize)]
103pub struct ModelTurn {
104 pub head: AssistantMessage,
106 pub response_id: Option<String>,
108 pub provider_request_id: Option<String>,
110 pub choice: Vec<AssistantContent>,
112 pub usage: Usage,
114 pub policy: TurnPolicy,
116 pub finish_reason: Option<FinishReason>,
118 pub raw: serde_json::Value,
120}
121
122impl ModelTurn {
123 pub fn from_response(resp: &CompletionResponse, prepared: &prepare::PreparedRequest) -> Self {
126 Self::from_policy(resp, prepared.policy.clone())
127 }
128
129 pub fn from_policy(resp: &CompletionResponse, policy: TurnPolicy) -> Self {
135 Self::new(
136 resp.head(),
137 resp.choice.clone(),
138 resp.usage,
139 policy,
140 resp.raw.clone(),
141 )
142 .with_identity(
143 resp.response_id().map(str::to_owned),
144 resp.provider_request_id.clone(),
145 )
146 .with_finish_reason(resp.finish_reason())
147 }
148
149 pub fn new(
153 head: AssistantMessage,
154 choice: Vec<AssistantContent>,
155 usage: Usage,
156 policy: TurnPolicy,
157 raw: serde_json::Value,
158 ) -> Self {
159 Self {
160 head,
161 response_id: None,
162 provider_request_id: None,
163 choice,
164 usage,
165 policy,
166 finish_reason: None,
167 raw,
168 }
169 }
170
171 pub fn with_identity(
173 mut self,
174 response_id: Option<String>,
175 provider_request_id: Option<String>,
176 ) -> Self {
177 self.response_id = response_id;
178 self.provider_request_id = provider_request_id;
179 self
180 }
181
182 pub fn with_finish_reason(mut self, finish_reason: Option<FinishReason>) -> Self {
184 self.finish_reason = finish_reason;
185 self
186 }
187}
188
189#[derive(Debug, Clone, Serialize, Deserialize)]
191pub enum ModelTurnOutcome {
192 Continue {
201 response_hook_suppressed: bool,
203 },
204 NeedsResolution(InvalidToolCallContext),
209 TurnRetried,
213}
214
215#[derive(Debug, Clone, Serialize, Deserialize)]
216struct ResolvingState {
217 head: AssistantMessage,
218 original_choice: Vec<AssistantContent>,
221 items: Vec<AssistantContent>,
223 next_index: usize,
225 policy: TurnPolicy,
226 skipped: BTreeMap<usize, UserContent>,
229 recovered: bool,
230 any_skipped: bool,
231 has_tool_calls: bool,
232}
233
234fn pending_invalid_call(resolving: &ResolvingState) -> Option<&ToolCall> {
237 match resolving.items.get(resolving.next_index) {
238 Some(AssistantContent::ToolCall(tool_call))
239 if !resolving.policy.allows(tool_call.function.name.as_str()) =>
240 {
241 Some(tool_call)
242 }
243 _ => None,
244 }
245}
246
247fn has_tool_calls(items: &[AssistantContent]) -> bool {
248 items
249 .iter()
250 .any(|item| matches!(item, AssistantContent::ToolCall(_)))
251}
252
253#[derive(Debug, Clone, Serialize, Deserialize)]
254struct TurnState {
255 head: AssistantMessage,
256 items: Vec<AssistantContent>,
257 has_tool_calls: bool,
258 skipped: BTreeMap<usize, UserContent>,
260 policy: TurnPolicy,
263}
264
265#[derive(Debug, Clone, Serialize, Deserialize)]
266enum RunState {
267 PreparingRequest { rollback_owed: bool },
271 AwaitingModel { recorded: bool },
274 ResolvingToolCalls(ResolvingState),
277 AwaitingAdvance(TurnState),
280 ExecutingTools(ToolBatch, TurnPolicy),
284 Done(PromptResponse),
286 Failed,
288}
289
290impl RunState {
291 const READY: Self = Self::PreparingRequest {
292 rollback_owed: false,
293 };
294}
295
296#[derive(Debug, Clone, Serialize, Deserialize)]
303#[serde(deny_unknown_fields)]
304pub struct AgentRun {
305 #[serde(deserialize_with = "run_format")]
307 format: u32,
308 max_turns: usize,
309 max_invalid_tool_call_retries: usize,
310 max_consecutive_malformed_tool_calls: Option<usize>,
312 unhandled_invalid_tool_call: UnhandledInvalidToolCall,
314 output_tool_name: Option<String>,
318 output_schema: Option<serde_json::Value>,
320 max_output_retries: usize,
324 output_retries: usize,
325 chat_history: Option<Vec<Arc<Message>>>,
326 #[serde(rename = "new_messages")]
328 history: committed::CommittedLog,
329 current_turn: usize,
330 usage: Usage,
331 completion_calls: Vec<CompletionCall>,
332 completion_call_index: usize,
333 invalid_tool_call_retries: usize,
334 malformed_tool_call_retries: usize,
337 previous_model: Option<rig_core::completion::ModelRef>,
344 turn_tools: Option<TurnTools>,
348 entries: Vec<Aside>,
352 state: RunState,
353}
354
355pub const RUN_FORMAT: u32 = 5;
357
358fn run_format<'de, D: serde::Deserializer<'de>>(deserializer: D) -> Result<u32, D::Error> {
362 let format = u32::deserialize(deserializer)?;
363 if format == RUN_FORMAT {
364 Ok(format)
365 } else {
366 Err(serde::de::Error::custom(format!(
367 "resume refused: the run is format {format}, this rig reads format {RUN_FORMAT}"
368 )))
369 }
370}
371
372#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
375pub struct TurnTools {
376 pub turn: usize,
379 pub definitions: Vec<Arc<ToolDefinition>>,
381}
382
383impl TurnTools {
384 pub fn contains(&self, tool_name: &str) -> bool {
386 self.definitions.iter().any(|d| d.name == tool_name)
387 }
388}
389
390impl AgentRun {
391 pub fn new(prompt: impl Into<Message>) -> Self {
394 Self {
395 format: RUN_FORMAT,
396 max_turns: 1,
397 max_invalid_tool_call_retries: 0,
398 max_consecutive_malformed_tool_calls: None,
399 unhandled_invalid_tool_call: UnhandledInvalidToolCall::Fail,
400 output_tool_name: None,
401 output_schema: None,
402 max_output_retries: 0,
403 output_retries: 0,
404 chat_history: None,
405 history: committed::CommittedLog::new(prompt.into()),
406 current_turn: 0,
407 usage: Usage::default(),
408 completion_calls: Vec::new(),
409 completion_call_index: 0,
410 invalid_tool_call_retries: 0,
411 malformed_tool_call_retries: 0,
412 previous_model: None,
413 turn_tools: None,
414 entries: Vec::new(),
415 state: RunState::READY,
416 }
417 }
418
419 pub fn initial_prompt(&self) -> Option<&Message> {
424 (self.current_turn == 0 && matches!(self.state, RunState::PreparingRequest { .. }))
425 .then(|| self.history.last().map(|prompt| &**prompt))
426 .flatten()
427 }
428
429 pub(crate) fn rewrite_initial_prompt(
437 &mut self,
438 prompt: impl Into<Message>,
439 ) -> Result<(), PromptError> {
440 let started =
441 self.current_turn != 0 || !matches!(self.state, RunState::PreparingRequest { .. });
442 if let (false, Some(slot)) = (started, self.history.unstarted_prompt()) {
443 *slot = Arc::new(prompt.into());
444 return Ok(());
445 }
446 Err(self.cancel_error("the initial prompt can only be rewritten before the run starts"))
447 }
448
449 pub fn append_entry(&mut self, entry: Aside) {
451 self.entries.push(entry);
452 }
453
454 pub fn entries(&self) -> &[Aside] {
456 &self.entries
457 }
458
459 pub fn entries_of<'a>(&'a self, kind: &'a str) -> impl Iterator<Item = &'a Aside> {
461 self.entries.iter().filter(move |entry| entry.kind == kind)
462 }
463
464 pub fn last_entry_of(&self, kind: &str) -> Option<&Aside> {
466 self.entries.iter().rev().find(|entry| entry.kind == kind)
467 }
468
469 pub fn advertise_tools(&mut self, turn: usize, definitions: Vec<Arc<ToolDefinition>>) {
473 self.turn_tools = Some(TurnTools { turn, definitions });
474 }
475
476 pub fn advertised_tools(&self) -> Option<&TurnTools> {
482 self.turn_tools.as_ref()
483 }
484
485 pub fn with_history(
487 mut self,
488 history: impl IntoIterator<Item = impl Into<Arc<Message>>>,
489 ) -> Self {
490 self.chat_history = Some(history.into_iter().map(Into::into).collect());
491 self
492 }
493
494 pub fn max_turns(mut self, max_turns: usize) -> Self {
499 self.max_turns = max_turns;
500 self
501 }
502
503 pub fn with_output_validation(
509 mut self,
510 output_schema: Option<serde_json::Value>,
511 max_output_retries: usize,
512 ) -> Self {
513 self.output_schema = output_schema;
514 self.max_output_retries = max_output_retries;
515 self
516 }
517
518 pub fn input_chat_history(&self) -> &[Arc<Message>] {
522 self.chat_history.as_deref().unwrap_or_default()
523 }
524
525 fn can_reprompt_for_output(&self) -> bool {
529 self.output_retries < self.max_output_retries && self.current_turn < self.max_turns
530 }
531
532 fn reprompt_for_output(&mut self) -> Result<AgentRunStep, PromptError> {
537 self.output_retries += 1;
538 self.state = RunState::READY;
539 self.next_step()
540 }
541
542 pub fn max_invalid_tool_call_retries(mut self, retries: usize) -> Self {
546 self.max_invalid_tool_call_retries = retries;
547 self
548 }
549
550 pub fn max_consecutive_malformed_tool_calls(mut self, limit: impl Into<Option<usize>>) -> Self {
554 self.max_consecutive_malformed_tool_calls = limit.into();
555 self
556 }
557
558 pub fn with_unhandled_invalid_tool_call(mut self, policy: UnhandledInvalidToolCall) -> Self {
561 self.unhandled_invalid_tool_call = policy;
562 self
563 }
564
565 pub fn with_output_tool_name(mut self, name: impl Into<String>) -> Self {
576 self.output_tool_name = Some(name.into());
577 self
578 }
579
580 pub fn output_tool_name(&self) -> Option<&str> {
585 self.output_tool_name.as_deref()
586 }
587
588 fn pin_output_tool(&mut self, policy: &TurnPolicy) {
592 if self.output_tool_name.is_none() {
593 self.output_tool_name = policy.output_tool().map(str::to_owned);
594 }
595 }
596
597 pub(crate) fn unhandled_invalid_tool_call(&self) -> UnhandledInvalidToolCall {
599 self.unhandled_invalid_tool_call
600 }
601
602 pub fn usage(&self) -> Usage {
604 self.usage
605 }
606
607 pub fn turn(&self) -> usize {
609 self.current_turn
610 }
611
612 pub fn previous_model(&self) -> Option<&rig_core::completion::ModelRef> {
614 self.previous_model.as_ref()
615 }
616
617 pub fn set_previous_model(&mut self, model: rig_core::completion::ModelRef) {
620 self.previous_model = Some(model);
621 }
622
623 pub fn completion_calls(&self) -> &[CompletionCall] {
625 &self.completion_calls
626 }
627
628 pub fn messages(&self) -> &[Arc<Message>] {
633 &self.history
634 }
635
636 pub fn projection_start(&self) -> usize {
640 let pending = matches!(self.state, RunState::ExecutingTools(..));
641 let holder = |message: &Arc<Message>| pending && matches!(**message, Message::Assistant(_));
642 (self.history.iter().rposition(holder)).unwrap_or(self.history.len())
643 }
644
645 pub fn accepted_turn_choice(&self) -> Option<Vec<AssistantContent>> {
647 let RunState::AwaitingAdvance(turn) = &self.state else {
648 return None;
649 };
650
651 if turn.items.is_empty() {
652 return None;
653 }
654 Some(turn.items.clone())
655 }
656
657 pub fn replace_accepted_turn_choice(
660 &mut self,
661 choice: Vec<AssistantContent>,
662 ) -> Result<(), PromptError> {
663 let replacement_has_tool_calls = choice
664 .iter()
665 .any(|item| matches!(item, AssistantContent::ToolCall(_)));
666 let parked_has_tool_calls = match &self.state {
667 RunState::AwaitingAdvance(turn) => turn.has_tool_calls,
668 _ => {
669 return Err(self.protocol_violation(
670 "replace_accepted_turn_choice called without an accepted turn awaiting advancement",
671 ));
672 }
673 };
674 if parked_has_tool_calls || replacement_has_tool_calls {
675 return Err(self.cancel_error(
676 "a completion outcome replacement does not support tool-bearing model turns; patch or deny the tool dispatches instead",
677 ));
678 }
679 if let RunState::AwaitingAdvance(turn) = &mut self.state {
680 turn.items = choice;
681 }
682 Ok(())
683 }
684
685 pub fn retry_model_turn(&mut self, request: RetryRequest) -> Result<(), PromptError> {
699 let turn = match std::mem::replace(&mut self.state, RunState::Failed) {
700 RunState::AwaitingAdvance(turn) => turn,
701 other => {
702 self.state = other;
703 return Err(self.protocol_violation(
704 "retry_model_turn called without an accepted turn awaiting advancement",
705 ));
706 }
707 };
708
709 if turn.has_tool_calls {
710 return Err(self.fail(
711 "model-turn retry does not support tool-bearing model turns; use tool-call hooks instead",
712 ));
713 }
714
715 match request {
716 RetryRequest::Repeat => {}
717 RetryRequest::Feedback(feedback) => {
718 self.history.commit(assistant_turn(turn.head, turn.items));
721 self.history.commit([Message::user(feedback)]);
722 }
723 }
724
725 self.state = RunState::READY;
726 Ok(())
727 }
728
729 pub fn full_history(&self) -> Vec<Message> {
735 self.owned_history(self.closure())
736 }
737
738 fn owned_history(&self, extra: impl IntoIterator<Item = Message>) -> Vec<Message> {
741 let shared = self.input_chat_history().iter().chain(self.history.iter());
742 shared
743 .map(|message| Message::clone(message))
744 .chain(extra)
745 .collect()
746 }
747
748 fn closure(&self) -> Option<Message> {
752 let RunState::ExecutingTools(batch, _) = &self.state else {
753 return None;
754 };
755 Some(batch.interrupt())
756 }
757
758 pub fn is_done(&self) -> bool {
760 matches!(self.state, RunState::Done(_))
761 }
762
763 pub fn response(&self) -> Option<&PromptResponse> {
768 match &self.state {
769 RunState::Done(response) => Some(response),
770 _ => None,
771 }
772 }
773
774 pub fn canonical_history(&self) -> Vec<Message> {
779 rig_core::conversation::pairing::repair(self.full_history()).messages
780 }
781
782 pub fn cancel_error(&self, reason: impl Into<String>) -> PromptError {
785 PromptError::cancelled(self.canonical_history(), reason)
786 }
787
788 fn fail(&mut self, reason: impl Into<String>) -> PromptError {
791 let error = self.cancel_error(reason);
792 let closure = self.closure();
793 self.history.commit(closure);
794 self.state = RunState::Failed;
795 error
796 }
797
798 fn call_model_step(&self) -> Result<AgentRunStep, PromptError> {
800 let Some((prompt, history)) = self.history.split_last() else {
801 return Err(self.cancel_error("prompt loop lost its pending prompt"));
802 };
803 let input = self.input_chat_history().iter();
804 Ok(AgentRunStep::CallModel {
805 prompt: Arc::clone(prompt),
806 history: input.chain(history).cloned().collect(),
807 turn: self.current_turn,
808 })
809 }
810
811 pub fn pending_invalid_tool_call(&self) -> Option<InvalidToolCallContext> {
815 let RunState::ResolvingToolCalls(resolving) = &self.state else {
816 return None;
817 };
818 let tool_call = pending_invalid_call(resolving)?;
819
820 Some(resolving.policy.invalid_call_context(
821 tool_call,
822 Some(tool_call.function.arguments_json()),
823 self.diagnostic_history(resolving),
824 false,
825 resolving.policy.name_reason(tool_call),
826 ))
827 }
828
829 pub fn next_step(&mut self) -> Result<AgentRunStep, PromptError> {
853 match std::mem::replace(&mut self.state, RunState::Failed) {
854 state @ (RunState::PreparingRequest { .. } | RunState::AwaitingModel { .. }) => {
857 if let RunState::PreparingRequest { .. } = state {
858 if self.current_turn >= self.max_turns
859 && let Some(prompt) = self.history.last()
860 {
861 return Err(PromptError::MaxTurns {
862 max_turns: self.max_turns,
863 chat_history: self.full_history(),
864 prompt: Message::clone(prompt),
865 });
866 }
867 self.current_turn += 1;
868 }
869 let step = self.call_model_step()?;
870 self.state = RunState::AwaitingModel { recorded: false };
871 Ok(step)
872 }
873 RunState::AwaitingAdvance(turn_state) => {
874 let TurnState {
875 head,
876 items,
877 has_tool_calls,
878 mut skipped,
879 policy,
880 } = turn_state;
881 let finish = self
886 .completion_calls
887 .last()
888 .and_then(|call| call.finish_reason.as_ref());
889 if let Some(message) = turn_failure(&items, head.stop.as_ref(), finish) {
890 if has_tool_calls {
891 self.history.commit(assistant_turn(head, items));
892 }
893 return Err(ProviderError::Response(message).into());
894 }
895
896 if has_tool_calls
899 && let Some(output_tool_name) = policy.output_tool().map(str::to_owned)
900 && let Some(tool_call) = items.iter().find_map(|item| match item {
901 AssistantContent::ToolCall(tc) if tc.function.name == output_tool_name => {
902 Some(tc)
903 }
904 _ => None,
905 })
906 {
907 let output_tool_calls = items
908 .iter()
909 .filter(|item| {
910 matches!(
911 item,
912 AssistantContent::ToolCall(tc)
913 if tc.function.name == output_tool_name
914 )
915 })
916 .count();
917 let args = tool_call.function.arguments_value();
918 let tool_call_id = tool_call.id.clone();
919 let output = args.to_string();
920
921 if let Some(raw) = &tool_call.function.invalid_arguments {
924 if self.can_reprompt_for_output() {
925 self.history.commit(assistant_message(head, items.clone()));
926 let feedback = invalid_arguments_feedback(&output_tool_name, raw);
927 if let Some(user_message) =
928 invalid_tool_retry_user_message(&items, &tool_call_id, &feedback)
929 {
930 self.history.commit([user_message]);
931 }
932 return self.reprompt_for_output();
933 }
934 return Err(ProviderError::Response(format!(
935 "the output tool `{output_tool_name}` was called with arguments \
936 that are not a JSON object: {raw}"
937 ))
938 .into());
939 }
940
941 let missing = self
942 .output_schema
943 .as_ref()
944 .map(|schema| structured_output::missing_required_fields(schema, &args))
945 .unwrap_or_default();
946 if !missing.is_empty() && self.can_reprompt_for_output() {
947 self.history.commit(assistant_message(head, items.clone()));
948 let feedback =
949 structured_output::reprompt_missing_fields(&output_tool_name, &missing);
950 if let Some(user_message) =
951 invalid_tool_retry_user_message(&items, &tool_call_id, &feedback)
952 {
953 self.history.commit([user_message]);
954 }
955 return self.reprompt_for_output();
956 }
957
958 let mut final_items: Vec<AssistantContent> = items
961 .iter()
962 .filter(|item| !matches!(item, AssistantContent::ToolCall(_)))
963 .cloned()
964 .collect();
965 final_items.push(AssistantContent::text(output.clone()));
966 self.history
967 .commit(assistant_message(head, final_items.clone()));
968
969 let content = response::finalize_output_tool_choice(&items, &output)
970 .unwrap_or_else(|| vec![AssistantContent::text(output)]);
971 return Ok(self.finish(content, output_tool_calls));
972 }
973
974 let slots: Option<Vec<ToolSlot>> = has_tool_calls.then(|| {
975 items
976 .iter()
977 .enumerate()
978 .filter_map(|(index, item)| match item {
979 AssistantContent::ToolCall(tool_call) => Some(ToolSlot::classify(
980 tool_call.clone(),
981 skipped.remove(&index),
982 )),
983 _ => None,
984 })
985 .collect()
986 });
987 if let Some(slots) = &slots {
989 self.count_malformed_tool_calls(slots)?;
990 }
991 self.history.commit(assistant_turn(head, items.clone()));
993
994 if let Some(slots) = slots {
995 self.output_retries = 0;
997 self.state = RunState::ExecutingTools(ToolBatch { slots }, policy);
998 self.answer_all([])?;
1001 self.next_step()
1002 } else {
1003 if let Some(output_tool_name) = policy.output_tool()
1006 && !items.iter().all(AssistantContent::is_blank)
1007 && self.can_reprompt_for_output()
1008 && !structured_output::text_satisfies_schema(
1009 self.output_schema.as_ref(),
1010 &choice_text(&items),
1011 )
1012 {
1013 self.history.commit([Message::user(
1014 structured_output::reprompt_text_answer(output_tool_name),
1015 )]);
1016 return self.reprompt_for_output();
1017 }
1018
1019 Ok(self.finish(items, 0))
1020 }
1021 }
1022 RunState::ExecutingTools(batch, policy) => {
1023 let calls = batch.pending(self.current_turn);
1024 self.state = RunState::ExecutingTools(batch, policy);
1025 Ok(AgentRunStep::CallTools { calls })
1026 }
1027 RunState::Done(response) => {
1028 let step = AgentRunStep::Done(response.clone());
1029 self.state = RunState::Done(response);
1030 Ok(step)
1031 }
1032 state @ RunState::ResolvingToolCalls(_) => {
1033 self.state = state;
1034 Err(self.protocol_violation(
1035 "next_step called while an invalid tool-call resolution is pending; answer it via resolve_invalid_tool_call first",
1036 ))
1037 }
1038 RunState::Failed => Err(self.protocol_violation(
1039 "next_step called after the run already failed or was misdriven",
1040 )),
1041 }
1042 }
1043
1044 pub fn model_response(&mut self, turn: ModelTurn) -> Result<ModelTurnOutcome, PromptError> {
1050 if self.pending_attempt("model_response")? {
1051 return Err(self.protocol_violation(
1052 "model_response called after record_streamed_completion_call for the same turn; feed streamed turns via streamed_turn",
1053 ));
1054 }
1055
1056 let identity = ResponseIdentity {
1057 response_id: turn.response_id,
1058 provider_request_id: turn.provider_request_id,
1059 };
1060 let call = self.completion_call(turn.usage, identity, turn.finish_reason, turn.raw);
1061 self.push_completion_call(call);
1062 self.pin_output_tool(&turn.policy);
1063
1064 let items: Vec<AssistantContent> = turn.choice.clone();
1065 let has_tool_calls = has_tool_calls(&items);
1066
1067 self.state = RunState::ResolvingToolCalls(ResolvingState {
1068 head: turn.head,
1069 original_choice: turn.choice,
1070 items,
1071 next_index: 0,
1072 policy: turn.policy,
1073 skipped: BTreeMap::new(),
1074 recovered: false,
1075 any_skipped: false,
1076 has_tool_calls,
1077 });
1078
1079 self.advance_resolution()
1080 }
1081
1082 fn completion_call(
1084 &self,
1085 usage: Usage,
1086 identity: ResponseIdentity,
1087 finish_reason: Option<FinishReason>,
1088 raw: serde_json::Value,
1089 ) -> CompletionCall {
1090 CompletionCall::new(self.completion_call_index, usage, raw)
1091 .with_identity(identity)
1092 .with_finish_reason(finish_reason)
1093 }
1094
1095 fn push_completion_call(&mut self, call: CompletionCall) {
1097 self.completion_call_index += 1;
1098 self.usage += call.usage;
1099 self.completion_calls.push(call);
1100 }
1101
1102 fn finish(&mut self, content: Vec<AssistantContent>, output_tool_calls: usize) -> AgentRunStep {
1106 let response = PromptResponse::from_content(content, self.usage)
1107 .with_messages(
1108 self.history
1109 .iter()
1110 .map(|message| Message::clone(message))
1111 .collect(),
1112 )
1113 .with_completion_calls(self.completion_calls.clone())
1114 .with_output_tool_calls(output_tool_calls);
1115 self.state = RunState::Done(response.clone());
1116 AgentRunStep::Done(response)
1117 }
1118
1119 fn finalize_turn(
1123 &mut self,
1124 head: AssistantMessage,
1125 items: Vec<AssistantContent>,
1126 has_tool_calls: bool,
1127 skipped: BTreeMap<usize, UserContent>,
1128 policy: TurnPolicy,
1129 ) {
1130 self.state = RunState::AwaitingAdvance(TurnState {
1131 head,
1132 items,
1133 has_tool_calls,
1134 skipped,
1135 policy,
1136 });
1137 }
1138
1139 fn count_malformed_tool_calls(&mut self, slots: &[ToolSlot]) -> Result<(), PromptError> {
1144 let malformed = slots.iter().find_map(|slot| match slot {
1145 ToolSlot::Malformed(tool_call) => tool_call
1146 .function
1147 .invalid_arguments
1148 .as_deref()
1149 .map(|raw| (tool_call, raw)),
1150 _ => None,
1151 });
1152 let Some((tool_call, raw)) = malformed else {
1153 self.malformed_tool_call_retries = 0;
1154 return Ok(());
1155 };
1156 self.malformed_tool_call_retries = self.malformed_tool_call_retries.saturating_add(1);
1157 let Some(limit) = self
1158 .max_consecutive_malformed_tool_calls
1159 .filter(|limit| self.malformed_tool_call_retries > *limit)
1160 else {
1161 return Ok(());
1162 };
1163 let error = policy::arguments_parse_error(raw);
1164 Err(ProviderError::Response(format!(
1165 "tool `{}` was called with arguments that are not a JSON object on {} consecutive \
1166 turns, more than the {} retries allowed: {error}",
1167 tool_call.function.name, self.malformed_tool_call_retries, limit,
1168 ))
1169 .into())
1170 }
1171
1172 pub fn malformed_context(
1176 &self,
1177 call: &MalformedCall,
1178 is_streaming: bool,
1179 ) -> InvalidToolCallContext {
1180 let policy = match &self.state {
1181 RunState::ExecutingTools(_, policy) => std::borrow::Cow::Borrowed(policy),
1182 _ => std::borrow::Cow::Owned(TurnPolicy::default()),
1183 };
1184 let raw = call.raw_arguments();
1185 policy.invalid_call_context(
1186 call.tool_call(),
1187 Some(raw.to_owned()),
1188 self.owned_history(None),
1191 is_streaming,
1192 InvalidToolCallReason::malformed_arguments(raw),
1193 )
1194 }
1195
1196 fn validate_invalid_tool_call_action(
1201 &mut self,
1202 action: InvalidToolCallAction,
1203 tool_call: &ToolCall,
1204 policy: &TurnPolicy,
1205 history: &[Message],
1206 ) -> Result<ValidatedInvalidToolCallAction, PromptError> {
1207 let unknown = |name: String| policy.unknown_call(name, history.to_vec());
1208 let rejected = || unknown(tool_call.function.name.to_string());
1209 let result = match action {
1210 InvalidToolCallAction::Fail => Err(rejected()),
1211 InvalidToolCallAction::Retry { feedback } => {
1212 if self.invalid_tool_call_retries >= self.max_invalid_tool_call_retries {
1213 Err(rejected())
1214 } else {
1215 self.invalid_tool_call_retries += 1;
1216 Ok(ValidatedInvalidToolCallAction::Retry { feedback })
1217 }
1218 }
1219 InvalidToolCallAction::Repair { tool_name } => {
1220 if policy.allows(&tool_name) {
1221 Ok(ValidatedInvalidToolCallAction::Repair { tool_name })
1222 } else {
1223 Err(unknown(tool_name))
1224 }
1225 }
1226 InvalidToolCallAction::Stop { reason } => Err(self.cancel_error(reason)),
1227 InvalidToolCallAction::Skip { reason } => {
1228 if policy.forbids_calls() {
1229 Err(rejected())
1230 } else {
1231 Ok(ValidatedInvalidToolCallAction::Skip { reason })
1232 }
1233 }
1234 };
1235
1236 if result.is_err() {
1237 self.state = RunState::Failed;
1238 }
1239 result
1240 }
1241
1242 pub fn resolve_invalid_tool_call(
1258 &mut self,
1259 action: InvalidToolCallAction,
1260 ) -> Result<ModelTurnOutcome, PromptError> {
1261 let mut resolving = self.take_resolving(
1262 "resolve_invalid_tool_call called without a pending invalid tool call",
1263 )?;
1264 let Some(tool_call) = pending_invalid_call(&resolving).cloned() else {
1265 self.state = RunState::ResolvingToolCalls(resolving);
1266 return Err(self.protocol_violation(
1267 "resolve_invalid_tool_call called without a pending invalid tool call",
1268 ));
1269 };
1270
1271 let diagnostic_history = self.diagnostic_history(&resolving);
1272 let action = self.validate_invalid_tool_call_action(
1273 action,
1274 &tool_call,
1275 &resolving.policy,
1276 &diagnostic_history,
1277 )?;
1278
1279 match action {
1280 ValidatedInvalidToolCallAction::Retry { feedback } => {
1281 self.history.commit(assistant_message(
1282 resolving.head.clone(),
1283 resolving.original_choice.clone(),
1284 ));
1285 let Some(user_message) = invalid_tool_retry_user_message(
1286 &resolving.original_choice,
1287 &tool_call.id,
1288 &feedback,
1289 ) else {
1290 return Err(self.fail("invalid tool call retry produced no retry messages"));
1291 };
1292 self.history.commit([user_message]);
1293 self.state = RunState::READY;
1294 Ok(ModelTurnOutcome::TurnRetried)
1295 }
1296 ValidatedInvalidToolCallAction::Repair { tool_name } => {
1297 if let Some(AssistantContent::ToolCall(tool_call)) =
1298 resolving.items.get_mut(resolving.next_index)
1299 && let Ok(tool_name) = ToolName::new(tool_name)
1300 {
1301 tool_call.function.name = tool_name;
1302 }
1303 resolving.recovered = true;
1304 self.state = RunState::ResolvingToolCalls(resolving);
1305 self.advance_resolution()
1306 }
1307 ValidatedInvalidToolCallAction::Skip { reason } => {
1308 let user_content = tool_result_message(
1309 tool_call.id.clone(),
1310 tool_call.function.name.clone(),
1311 reason,
1312 );
1313 resolving.skipped.insert(resolving.next_index, user_content);
1317 resolving.recovered = true;
1318 resolving.any_skipped = true;
1319 resolving.next_index += 1;
1320 self.state = RunState::ResolvingToolCalls(resolving);
1321 self.advance_resolution()
1322 }
1323 }
1324 }
1325
1326 pub fn resolve_unhandled_invalid_tool_call(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1330 match self.unhandled_invalid_tool_call {
1331 UnhandledInvalidToolCall::Fail => {
1332 self.resolve_invalid_tool_call(InvalidToolCallAction::fail())
1333 }
1334 UnhandledInvalidToolCall::Ignore => self.ignore_invalid_tool_call(),
1335 }
1336 }
1337
1338 pub fn ignore_invalid_tool_call(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1341 let mut resolving = self.take_resolving(
1342 "ignore_invalid_tool_call called without a pending invalid tool call",
1343 )?;
1344
1345 if pending_invalid_call(&resolving).is_none() {
1346 self.state = RunState::ResolvingToolCalls(resolving);
1347 return Err(self.protocol_violation(
1348 "ignore_invalid_tool_call called without a pending invalid tool call",
1349 ));
1350 }
1351
1352 resolving.items.remove(resolving.next_index);
1353 resolving.has_tool_calls = has_tool_calls(&resolving.items);
1354 self.state = RunState::ResolvingToolCalls(resolving);
1355 self.advance_resolution()
1356 }
1357
1358 pub fn answer(&mut self, answer: ToolAnswer) -> Result<(), PromptError> {
1361 self.answer_all([answer])
1362 }
1363
1364 pub fn answer_all(
1374 &mut self,
1375 answers: impl IntoIterator<Item = ToolAnswer>,
1376 ) -> Result<(), PromptError> {
1377 let RunState::ExecutingTools(batch, policy) = &self.state else {
1378 return Err(self.protocol_violation("answer called without a pending CallTools step"));
1379 };
1380 let (mut batch, policy, turn) = (batch.clone(), policy.clone(), self.current_turn);
1382 let mut answers: Vec<ToolAnswer> = answers.into_iter().collect();
1383 answers.sort_by_key(ToolAnswer::ends_run);
1384 for ToolAnswer {
1385 turn: issued,
1386 index,
1387 call,
1388 kind,
1389 } in answers
1390 {
1391 let content = match (batch.slots.get(index), kind) {
1392 _ if issued != turn => {
1393 return Err(self.protocol_violation(&format!(
1394 "answer for tool call id `{call}` of model turn {issued}, but the pending calls are from turn {turn}"
1395 )));
1396 }
1397 (Some(ToolSlot::Execute(tool_call)), AnswerKind::Executed(result))
1398 if tool_call.id == call =>
1399 {
1400 tool_result_output(call, tool_call.function.name.clone(), &result)
1401 }
1402 (Some(ToolSlot::Malformed(tool_call)), AnswerKind::Malformed(action))
1403 if tool_call.id == call =>
1404 {
1405 match malformed_answer(tool_call, action) {
1406 Ok(content) => content,
1407 Err(end) => {
1408 self.state = RunState::ExecutingTools(batch, policy);
1411 return Err(match end {
1412 Ok(reason) => self.fail(reason),
1413 Err(error) => {
1414 let closure = self.closure();
1415 self.history.commit(closure);
1416 self.state = RunState::Failed;
1417 error
1418 }
1419 });
1420 }
1421 }
1422 }
1423 (Some(ToolSlot::Answered(_)), _) => {
1424 return Err(self.protocol_violation(&format!(
1425 "answer for tool call id `{call}` that is already answered"
1426 )));
1427 }
1428 _ => {
1429 return Err(self.protocol_violation(&format!(
1430 "answer for tool call id `{call}` does not match the pending call at position {index}"
1431 )));
1432 }
1433 };
1434 if let Some(slot) = batch.slots.get_mut(index) {
1435 *slot = ToolSlot::Answered(content);
1436 }
1437 }
1438 self.state = match batch.complete() {
1439 Ok(results) => {
1440 self.history.commit([results]);
1441 RunState::READY
1442 }
1443 Err(batch) => RunState::ExecutingTools(batch, policy),
1444 };
1445 Ok(())
1446 }
1447
1448 fn take_resolving(&mut self, violation: &str) -> Result<ResolvingState, PromptError> {
1452 match std::mem::replace(&mut self.state, RunState::Failed) {
1453 RunState::ResolvingToolCalls(resolving) => Ok(resolving),
1454 other => {
1455 self.state = other;
1456 Err(self.protocol_violation(violation))
1457 }
1458 }
1459 }
1460
1461 fn advance_resolution(&mut self) -> Result<ModelTurnOutcome, PromptError> {
1464 let mut resolving =
1465 self.take_resolving("internal: advance_resolution outside of tool-call resolution")?;
1466 while let Some(item) = resolving.items.get(resolving.next_index) {
1467 match item {
1468 AssistantContent::ToolCall(tool_call)
1469 if !resolving.policy.allows(tool_call.function.name.as_str()) =>
1470 {
1471 break;
1472 }
1473 _ => resolving.next_index += 1,
1474 }
1475 }
1476
1477 if resolving.next_index < resolving.items.len() {
1478 self.state = RunState::ResolvingToolCalls(resolving);
1479 return match self.pending_invalid_tool_call() {
1480 Some(context) => Ok(ModelTurnOutcome::NeedsResolution(context)),
1481 None => Err(self.protocol_violation(
1482 "internal: pending invalid tool call could not be derived",
1483 )),
1484 };
1485 }
1486
1487 let ResolvingState {
1488 head,
1489 items,
1490 mut skipped,
1491 recovered,
1492 any_skipped,
1493 has_tool_calls,
1494 policy,
1495 ..
1496 } = resolving;
1497
1498 if any_skipped {
1501 for (index, item) in items.iter().enumerate() {
1502 if let AssistantContent::ToolCall(tool_call) = item {
1503 skipped
1504 .entry(index)
1505 .or_insert_with(|| not_executed(tool_call));
1506 }
1507 }
1508 }
1509
1510 self.finalize_turn(head, items, has_tool_calls, skipped, policy);
1511 Ok(ModelTurnOutcome::Continue {
1512 response_hook_suppressed: recovered,
1513 })
1514 }
1515
1516 pub fn record_streamed_completion_call(
1525 &mut self,
1526 usage: Usage,
1527 identity: ResponseIdentity,
1528 finish_reason: Option<FinishReason>,
1529 raw: serde_json::Value,
1530 ) -> Result<CompletionCall, PromptError> {
1531 let recordable = match &mut self.state {
1532 RunState::AwaitingModel { recorded } => !std::mem::replace(recorded, true),
1533 RunState::PreparingRequest { rollback_owed } => std::mem::take(rollback_owed),
1534 _ => false,
1535 };
1536 if !recordable {
1537 return Err(self.protocol_violation(
1538 "record_streamed_completion_call called without a pending or rolled-back model attempt, or twice for one",
1539 ));
1540 }
1541
1542 let call = self.completion_call(usage, identity, finish_reason, raw);
1543 self.push_completion_call(call.clone());
1544 Ok(call)
1545 }
1546
1547 pub fn streamed_invalid_tool_call_context(
1550 &self,
1551 partial: &PartialStreamedTurn,
1552 invalid: &StreamedInvalidToolCall,
1553 ) -> InvalidToolCallContext {
1554 invalid.policy.invalid_call_context(
1555 &invalid.tool_call,
1556 invalid.args.clone(),
1557 self.streamed_diagnostic_history(partial, Some(invalid.tool_call.clone())),
1558 true,
1559 invalid.policy.name_reason(&invalid.tool_call),
1560 )
1561 }
1562
1563 pub fn resolve_streamed_invalid_tool_call(
1569 &mut self,
1570 partial: &PartialStreamedTurn,
1571 invalid: &StreamedInvalidToolCall,
1572 action: InvalidToolCallAction,
1573 ) -> Result<StreamedResolution, PromptError> {
1574 let recorded = self.pending_attempt("resolve_streamed_invalid_tool_call")?;
1575
1576 self.pin_output_tool(&invalid.policy);
1579 let diagnostic_history =
1580 self.streamed_diagnostic_history(partial, Some(invalid.tool_call.clone()));
1581 let action = self.validate_invalid_tool_call_action(
1582 action,
1583 &invalid.tool_call,
1584 &invalid.policy,
1585 &diagnostic_history,
1586 )?;
1587
1588 match action {
1589 ValidatedInvalidToolCallAction::Retry { feedback } => self.abandon_streamed_turn(
1590 partial,
1591 invalid,
1592 feedback,
1593 !recorded,
1594 "invalid tool call retry produced no retry messages",
1595 ),
1596 ValidatedInvalidToolCallAction::Repair { tool_name } => {
1597 Ok(StreamedResolution::Repaired { tool_name })
1598 }
1599 ValidatedInvalidToolCallAction::Skip { reason } => self.abandon_streamed_turn(
1600 partial,
1601 invalid,
1602 reason,
1603 !recorded,
1604 "invalid tool call skip produced no recovery messages",
1605 ),
1606 }
1607 }
1608
1609 pub fn ignore_streamed_invalid_tool_call(&mut self) -> Result<StreamedResolution, PromptError> {
1613 self.pending_attempt("ignore_streamed_invalid_tool_call")?;
1614 Ok(StreamedResolution::Ignored)
1615 }
1616
1617 fn abandon_streamed_turn(
1622 &mut self,
1623 partial: &PartialStreamedTurn,
1624 invalid: &StreamedInvalidToolCall,
1625 feedback: String,
1626 rollback_owed: bool,
1627 no_messages_reason: &str,
1628 ) -> Result<StreamedResolution, PromptError> {
1629 let Some((assistant_message, user_message)) =
1630 partial.rollback_messages(invalid.tool_call.clone(), feedback)
1631 else {
1632 return Err(self.fail(no_messages_reason));
1633 };
1634 self.history.commit([assistant_message, user_message]);
1635 self.state = RunState::PreparingRequest { rollback_owed };
1636 Ok(StreamedResolution::TurnAbandoned)
1637 }
1638
1639 pub fn streamed_turn(&mut self, turn: StreamedTurn) -> Result<(), PromptError> {
1647 if !self.pending_attempt("streamed_turn")? {
1648 return Err(self.protocol_violation(
1649 "streamed_turn called before record_streamed_completion_call recorded the turn's completion call",
1650 ));
1651 }
1652
1653 let has_tool_calls = has_tool_calls(&turn.choice);
1654
1655 for item in &turn.choice {
1656 let AssistantContent::ToolCall(tool_call) = item else {
1657 continue;
1658 };
1659 if !turn.policy.allows(tool_call.function.name.as_str()) {
1660 let diagnostic_history =
1661 self.owned_history(assistant_turn(turn.head.clone(), turn.choice.clone()));
1662 self.state = RunState::Failed;
1663 return Err(turn
1664 .policy
1665 .unknown_call(tool_call.function.name.to_string(), diagnostic_history));
1666 }
1667 }
1668
1669 self.pin_output_tool(&turn.policy);
1670 self.finalize_turn(
1671 turn.head,
1672 turn.choice,
1673 has_tool_calls,
1674 BTreeMap::new(),
1675 turn.policy,
1676 );
1677 Ok(())
1678 }
1679
1680 fn streamed_diagnostic_history(
1683 &self,
1684 partial: &PartialStreamedTurn,
1685 current_tool_call: Option<ToolCall>,
1686 ) -> Vec<Message> {
1687 self.owned_history(partial.assistant_message(current_tool_call))
1688 }
1689
1690 fn diagnostic_history(&self, resolving: &ResolvingState) -> Vec<Message> {
1693 self.owned_history(assistant_message(
1694 resolving.head.clone(),
1695 resolving.original_choice.clone(),
1696 ))
1697 }
1698
1699 fn pending_attempt(&self, op: &str) -> Result<bool, PromptError> {
1702 match self.state {
1703 RunState::AwaitingModel { recorded } => Ok(recorded),
1704 _ => {
1705 Err(self
1706 .protocol_violation(&format!("{op} called without a pending CallModel step")))
1707 }
1708 }
1709 }
1710
1711 fn protocol_violation(&self, reason: &str) -> PromptError {
1712 self.cancel_error(format!("agent run driver protocol violation: {reason}"))
1713 }
1714}
1715
1716impl AgentRun {
1717 pub fn from_spec(
1726 spec: &RunSpec,
1727 prompt: impl Into<Message>,
1728 history: Option<Vec<Arc<Message>>>,
1729 ) -> Self {
1730 let mut run = AgentRun::new(prompt)
1731 .max_turns(spec.effective_max_turns())
1732 .max_invalid_tool_call_retries(spec.max_invalid_tool_call_retries)
1733 .with_unhandled_invalid_tool_call(spec.unhandled_invalid_tool_call)
1734 .with_output_validation(
1735 spec.output_schema
1736 .as_ref()
1737 .map(|schema| schema.as_value().clone()),
1738 RunSpec::DEFAULT_OUTPUT_RETRIES,
1739 );
1740 run.max_consecutive_malformed_tool_calls = spec.max_consecutive_malformed_tool_calls;
1741 if let Some(history) = history {
1742 run = run.with_history(history);
1743 }
1744 if let Some(name) = spec.output_tool_name.clone() {
1745 run = run.with_output_tool_name(name);
1746 }
1747 run
1748 }
1749}
1750
1751impl AgentRun {
1752 pub fn with_validated_history(self, history: Vec<Message>) -> Result<Self, PairingError> {
1758 validate(&history)?;
1759 Ok(self.with_history(history))
1760 }
1761}
1762
1763#[cfg(not(target_family = "wasm"))]
1766const _: fn() = || {
1767 fn assert_send_sync_static<T: Send + Sync + 'static>() {}
1768 assert_send_sync_static::<AgentRun>();
1769 assert_send_sync_static::<AgentRunStep>();
1770 assert_send_sync_static::<PendingToolCall>();
1771 assert_send_sync_static::<ModelTurn>();
1772 assert_send_sync_static::<StreamedTurn>();
1773 assert_send_sync_static::<StreamedTurnAssembler>();
1774 assert_send_sync_static::<PromptResponse>();
1775 assert_send_sync_static::<CompletionCall>();
1776 assert_send_sync_static::<PromptError>();
1777 assert_send_sync_static::<TurnTools>();
1778};
1779
1780fn malformed_answer(
1783 tool_call: &ToolCall,
1784 action: Option<InvalidToolCallAction>,
1785) -> Result<UserContent, Result<String, PromptError>> {
1786 let (id, name) = (tool_call.id.clone(), tool_call.function.name.clone());
1787 let raw = tool_call
1788 .function
1789 .invalid_arguments
1790 .as_deref()
1791 .unwrap_or_default();
1792 let feedback = match action {
1793 None => invalid_arguments_feedback(name.as_str(), raw),
1794 Some(InvalidToolCallAction::Retry { feedback }) => feedback,
1795 Some(InvalidToolCallAction::Skip { reason }) => {
1796 let skipped = rig_core::tool::ToolResult::skipped(reason);
1797 return Ok(tool_result_output(id, name, &skipped));
1798 }
1799 Some(InvalidToolCallAction::Stop { reason }) => return Err(Ok(reason)),
1800 Some(InvalidToolCallAction::Fail | InvalidToolCallAction::Repair { .. }) => {
1801 return Err(Err(ProviderError::Response(format!(
1802 "tool `{name}` was called with arguments that are not a JSON object: {}",
1803 policy::arguments_parse_error(raw)
1804 ))
1805 .into()));
1806 }
1807 };
1808 Ok(tool_result_message(id, name, feedback))
1809}
1810
1811#[cfg(test)]
1812mod tests;