Skip to main content

rig_agent/run/
policy.rs

1//! Invalid tool-call diagnostics and recovery decisions exchanged with drivers.
2//!
3//! ```
4//! use rig_agent::run::policy::InvalidToolCallAction;
5//! let action = InvalidToolCallAction::retry("Use an advertised tool name.");
6//! assert!(matches!(action, InvalidToolCallAction::Retry { .. }));
7//! ```
8
9use std::collections::BTreeSet;
10
11use rig_core::message::{Message, ToolCall, ToolChoice, ToolName};
12use serde::{Deserialize, Serialize};
13
14use super::response::PromptError;
15use rig_core::error::ProviderError;
16
17/// Why a model-emitted tool call cannot be dispatched as written.
18///
19/// Not every [`InvalidToolCallAction`] fits every reason: a name can be
20/// repaired, argument text cannot.
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(tag = "reason", rename_all = "snake_case")]
23#[non_exhaustive]
24pub enum InvalidToolCallReason {
25    /// The name is not an executable tool for this turn.
26    UnknownTool,
27    /// The tool exists, but the active tool choice does not allow it.
28    DisallowedByToolChoice,
29    /// The arguments are not a JSON object. The raw text is in
30    /// [`InvalidToolCallContext::args`].
31    MalformedArguments {
32        /// What the JSON parser rejected.
33        error: String,
34    },
35}
36
37impl InvalidToolCallReason {
38    /// The reason for arguments `raw` that are not a JSON object, with the
39    /// parser's description of what it rejected.
40    pub fn malformed_arguments(raw: &str) -> Self {
41        Self::MalformedArguments {
42            error: arguments_parse_error(raw),
43        }
44    }
45}
46
47/// What the JSON parser rejects in arguments `raw` that are not an object.
48pub(crate) fn arguments_parse_error(raw: &str) -> String {
49    match serde_json::from_str::<serde_json::Value>(raw) {
50        Err(error) => error.to_string(),
51        Ok(value) => format!("expected a JSON object, found {}", json_kind(&value)),
52    }
53}
54
55fn json_kind(value: &serde_json::Value) -> &'static str {
56    match value {
57        serde_json::Value::Null => "null",
58        serde_json::Value::Bool(_) => "a boolean",
59        serde_json::Value::Number(_) => "a number",
60        serde_json::Value::String(_) => "a string",
61        serde_json::Value::Array(_) => "an array",
62        serde_json::Value::Object(_) => "an object",
63    }
64}
65
66/// Diagnostics for an invalid model-emitted tool call.
67#[derive(Debug, Clone, Serialize, Deserialize)]
68#[non_exhaustive]
69pub struct InvalidToolCallContext {
70    /// Name emitted by the model.
71    pub tool_name: String,
72    /// Durable tool-call id: the provider's when it issued one, else rig's
73    /// minted handle. Absent only when no call object exists at all.
74    pub tool_call_id: Option<rig_core::message::CallId>,
75    /// Emitted JSON arguments, when present. For
76    /// [`InvalidToolCallReason::MalformedArguments`] this is the raw text the
77    /// model sent.
78    pub args: Option<String>,
79    /// Executable tools advertised for the turn.
80    pub available_tools: Vec<String>,
81    /// Tools permitted by the active tool choice.
82    pub allowed_tools: Vec<String>,
83    /// Active tool choice.
84    pub tool_choice: Option<ToolChoice>,
85    /// Diagnostic history including the rejected output.
86    pub chat_history: Vec<Message>,
87    /// Whether the call came from the streaming path.
88    pub is_streaming: bool,
89    /// Why the call cannot be dispatched as written.
90    pub reason: InvalidToolCallReason,
91}
92
93/// The tool policy of one model turn, built once by
94/// [`prepare_request`](super::prepare::prepare_request) and read by every
95/// invalid-call check of that turn. The allowed set is derived from the
96/// executable tools, the choice and the output tool, and never persisted, so
97/// it cannot disagree with the choice.
98#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
99#[serde(try_from = "TurnPolicyRepr")]
100pub struct TurnPolicy {
101    executable: BTreeSet<String>,
102    tool_choice: Option<ToolChoice>,
103    output_tool: Option<String>,
104    /// Whether provider-hosted tools are advertised too.
105    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
106    hosted: bool,
107    #[serde(skip_serializing)]
108    allowed: BTreeSet<String>,
109}
110
111#[derive(Deserialize)]
112struct TurnPolicyRepr {
113    executable: BTreeSet<String>,
114    tool_choice: Option<ToolChoice>,
115    output_tool: Option<String>,
116    #[serde(default)]
117    hosted: bool,
118}
119
120impl TryFrom<TurnPolicyRepr> for TurnPolicy {
121    type Error = ProviderError;
122
123    fn try_from(repr: TurnPolicyRepr) -> Result<Self, Self::Error> {
124        Self::resolve(
125            repr.executable,
126            repr.tool_choice,
127            repr.output_tool,
128            None,
129            repr.hosted,
130        )
131    }
132}
133
134impl TurnPolicy {
135    /// The policy for a turn advertising `executable` tools and, in Tool
136    /// output mode, the synthetic `output_tool`, under `tool_choice`.
137    ///
138    /// # Errors
139    /// [`ProviderError::Request`] when the choice cannot be honored: `Required`
140    /// with no advertised tool, an empty `Specific`, or a `Specific` naming a
141    /// tool that is not advertised.
142    pub fn new(
143        executable: BTreeSet<String>,
144        tool_choice: Option<ToolChoice>,
145        output_tool: Option<String>,
146    ) -> Result<Self, ProviderError> {
147        Self::resolve(executable, tool_choice, output_tool, None, false)
148    }
149
150    /// [`new`](Self::new) with the names advertised before a per-turn
151    /// `active_tools` allow-list, which only sharpens the error message, and
152    /// whether provider-hosted tools are advertised too, which satisfy
153    /// `Required` without becoming executable.
154    pub(crate) fn resolve(
155        executable: BTreeSet<String>,
156        tool_choice: Option<ToolChoice>,
157        output_tool: Option<String>,
158        pre_filter: Option<&BTreeSet<String>>,
159        hosted: bool,
160    ) -> Result<Self, ProviderError> {
161        let output = output_tool.as_deref();
162        let hint = |active_tools_caused: bool| {
163            if active_tools_caused {
164                " A per-turn `active_tools` allow-list narrowed the advertised tools this turn; \
165                 set a compatible `tool_choice` in the same `RequestPatch`, or widen `active_tools`."
166            } else {
167                ""
168            }
169        };
170
171        let mut allowed = match &tool_choice {
172            Some(ToolChoice::Required) if executable.is_empty() && output.is_none() && !hosted => {
173                return Err(ProviderError::request(format!(
174                    "ToolChoice::Required forces the model to call a tool, but no tools are \
175                     advertised this turn.{}",
176                    hint(pre_filter.is_some_and(|pf| !pf.is_empty()))
177                )));
178            }
179            None | Some(ToolChoice::Auto | ToolChoice::Required) => executable.clone(),
180            Some(ToolChoice::None) => BTreeSet::new(),
181            Some(ToolChoice::Specific { function_names }) => {
182                if function_names.is_empty() {
183                    return Err(ProviderError::request(
184                        "ToolChoice::Specific requires at least one function name".to_string(),
185                    ));
186                }
187                let missing = function_names
188                    .iter()
189                    .map(ToolName::as_str)
190                    .filter(|name| !executable.contains(*name) && Some(*name) != output)
191                    .collect::<Vec<_>>();
192                if !missing.is_empty() {
193                    let advertised: Vec<_> = executable
194                        .iter()
195                        .map(String::as_str)
196                        .chain(output)
197                        .collect();
198                    // Attribute missing names to filtering only if they existed before it.
199                    return Err(ProviderError::request(format!(
200                        "ToolChoice::Specific requested tool names not advertised this turn: \
201                         {missing:?}. Advertised: {advertised:?}.{}",
202                        hint(pre_filter.is_some_and(|pf| missing.iter().any(|n| pf.contains(*n))))
203                    )));
204                }
205                function_names.iter().map(ToString::to_string).collect()
206            }
207        };
208        // The output tool is allowed, so its call is not invalid, though it
209        // never executes.
210        if let Some(name) = &output_tool {
211            allowed.insert(name.clone());
212        }
213
214        Ok(Self {
215            executable,
216            tool_choice,
217            output_tool,
218            hosted,
219            allowed,
220        })
221    }
222
223    /// Names of the real, dispatchable tools advertised this turn.
224    pub fn executable(&self) -> &BTreeSet<String> {
225        &self.executable
226    }
227
228    /// The turn's effective tool choice (patch over spec).
229    pub fn tool_choice(&self) -> Option<&ToolChoice> {
230        self.tool_choice.as_ref()
231    }
232
233    /// In Tool output mode, the synthetic output tool's name (allowed but
234    /// never executable).
235    pub fn output_tool(&self) -> Option<&str> {
236        self.output_tool.as_deref()
237    }
238
239    /// Whether the turn's choice is [`ToolChoice::None`], under which no
240    /// call may be skipped into the history.
241    pub fn forbids_calls(&self) -> bool {
242        matches!(self.tool_choice, Some(ToolChoice::None))
243    }
244
245    /// Whether a call to `name` is allowed this turn.
246    pub fn allows(&self, name: &str) -> bool {
247        self.allowed.contains(name)
248    }
249
250    /// The run's error for a call to `tool_name` this turn does not allow.
251    pub(crate) fn unknown_call(
252        &self,
253        tool_name: String,
254        chat_history: Vec<Message>,
255    ) -> PromptError {
256        PromptError::UnknownToolCall {
257            tool_name,
258            available_tools: self.executable.iter().cloned().collect(),
259            allowed_tools: self.allowed.iter().cloned().collect(),
260            chat_history,
261        }
262    }
263
264    /// Why `call` is not allowed: its tool is not executable at all, or is
265    /// executable but excluded by the tool choice.
266    pub(crate) fn name_reason(&self, call: &ToolCall) -> InvalidToolCallReason {
267        if self.executable.contains(call.function.name.as_str()) {
268            InvalidToolCallReason::DisallowedByToolChoice
269        } else {
270            InvalidToolCallReason::UnknownTool
271        }
272    }
273
274    /// The invalid-call context for `call` under this turn's policy, which
275    /// supplies the advertised tools, the allowed tools and the tool choice.
276    pub fn invalid_call_context(
277        &self,
278        call: &ToolCall,
279        args: Option<String>,
280        chat_history: Vec<Message>,
281        is_streaming: bool,
282        reason: InvalidToolCallReason,
283    ) -> InvalidToolCallContext {
284        InvalidToolCallContext {
285            tool_name: call.function.name.to_string(),
286            tool_call_id: Some(call.id.clone()),
287            args,
288            available_tools: self.executable.iter().cloned().collect(),
289            allowed_tools: self.allowed.iter().cloned().collect(),
290            tool_choice: self.tool_choice.clone(),
291            chat_history,
292            is_streaming,
293            reason,
294        }
295    }
296}
297
298/// How an accepted, tool-free model turn should be retried.
299#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
300pub enum RetryRequest {
301    /// Discard the rejected response and reuse the same prompt and preceding
302    /// history with fresh request preparation.
303    ///
304    /// Completion-call hooks, retrieval, and dynamic tool resolution run again,
305    /// so the resulting provider request may differ from the rejected attempt.
306    Repeat,
307    /// Preserve the rejected assistant response and append corrective feedback.
308    Feedback(String),
309}
310
311/// Action for invalid-tool-call hooks and manual invalid-call resolution.
312#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
313#[non_exhaustive]
314pub enum InvalidToolCallAction {
315    /// Preserve fail-fast behavior.
316    Fail,
317    /// Retry the model with corrective feedback.
318    Retry {
319        /// Feedback appended for the retry.
320        feedback: String,
321    },
322    /// Repair the emitted tool name.
323    Repair {
324        /// Replacement registered tool name.
325        tool_name: String,
326    },
327    /// Treat the invalid call as skipped.
328    Skip {
329        /// Synthetic model feedback.
330        reason: String,
331    },
332    /// Stop the run.
333    Stop {
334        /// Stop reason.
335        reason: String,
336    },
337}
338
339impl InvalidToolCallAction {
340    /// Creates an action that preserves fail-fast invalid-call handling.
341    pub fn fail() -> Self {
342        Self::Fail
343    }
344
345    /// Creates an action that retries the model with corrective feedback.
346    pub fn retry(feedback: impl Into<String>) -> Self {
347        Self::Retry {
348            feedback: feedback.into(),
349        }
350    }
351
352    /// Creates an action that replaces the invalid tool name.
353    pub fn repair(tool_name: impl Into<String>) -> Self {
354        Self::Repair {
355            tool_name: tool_name.into(),
356        }
357    }
358
359    /// Creates an action that treats the invalid call as skipped.
360    pub fn skip(reason: impl Into<String>) -> Self {
361        Self::Skip {
362            reason: reason.into(),
363        }
364    }
365
366    /// Creates an action that stops the run with the supplied reason.
367    pub fn stop(reason: impl Into<String>) -> Self {
368        Self::Stop {
369            reason: reason.into(),
370        }
371    }
372}
373
374#[cfg(test)]
375mod tests;