Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
//! Provider-neutral conversation types shared by routing, clients, and translation.
//!
//! Debug output redacts MCP URLs and authorization tokens and hides raw provider tool definitions,
//! extensions, and preserved bodies. Conversation content, including unknown provider
//! blocks, remains visible and may contain secrets. Serialization retains the stored values.
use std::collections::BTreeMap;
use std::fmt;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use crate::format::FormatId;
/// Maximum temperature on the shared IR's zero-based scale.
pub const MAX_IR_TEMPERATURE: f64 = 2.0;
/// Actor role normalized across provider APIs.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize, strum_macros::Display)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum Role {
/// System-level instructions.
System,
/// Developer-level instructions supported by some provider APIs.
Developer,
/// End-user input.
User,
/// Model-generated output.
Assistant,
/// Tool execution output.
Tool,
}
/// Instruction content separated from normal conversation messages.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct InstructionBlock {
/// Instruction authority, normally [`Role::System`] or [`Role::Developer`].
pub role: Role,
/// Ordered instruction content.
pub content: Vec<ContentBlock>,
}
/// One normalized conversation message.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Message {
/// Actor that produced the message.
pub role: Role,
/// Ordered message content.
pub content: Vec<ContentBlock>,
/// OpenAI Responses assistant message `phase`, such as `commentary` or `final_answer`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub phase: Option<String>,
}
impl Message {
/// Creates a message with no `phase`.
pub fn new(role: Role, content: Vec<ContentBlock>) -> Self {
Self {
role,
content,
phase: None,
}
}
/// Creates a text-only message for the given role.
pub fn text(role: Role, text: impl Into<String>) -> Self {
Self::new(role, vec![ContentBlock::Text { text: text.into() }])
}
/// Concatenates text-like content blocks when the message has any.
pub fn text_content(&self, separator: &str) -> Option<String> {
let parts = self
.content
.iter()
.filter_map(|block| match block {
ContentBlock::Text { text } => Some(text.as_str()),
ContentBlock::Refusal { text } => Some(text.as_str()),
_ => None,
})
.collect::<Vec<_>>();
if parts.is_empty() {
None
} else {
Some(parts.join(separator))
}
}
}
/// Normalized content block variants carried by messages and tool results.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentBlock {
/// Plain text content.
Text {
/// Text value.
text: String,
},
/// Model reasoning or thinking content.
Reasoning {
/// Reasoning text.
text: String,
/// Provider signature used to validate or continue the reasoning block.
signature: Option<String>,
/// Structured reasoning details, such as an encrypted `{ "type":
/// "reasoning.encrypted", "data": "..." }` object, replayed without modification.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
details: Vec<Value>,
},
/// Image content.
Image {
/// Image location or inline payload.
source: ImageSource,
},
/// Audio content.
Audio {
/// Audio location or inline payload.
source: MediaSource,
},
/// Video content.
Video {
/// Video location or inline payload.
source: MediaSource,
},
/// File content.
File {
/// File identifier or inline payload.
source: FileSource,
},
/// Tool invocation requested by the assistant.
ToolCall(ToolCall),
/// Result of an earlier tool invocation.
ToolResult(ToolResult),
/// MCP activity executed by the backend, rather than by the calling agent.
Mcp(McpContent),
/// Provider refusal content.
Refusal {
/// Human-readable refusal text.
text: String,
},
/// Provider block that has no normalized representation.
Unknown {
/// Wire format that supplied the block.
provider: FormatId,
/// Exact provider block.
raw: Value,
},
}
/// Image payload forms supported by the conversation model.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", content = "data", rename_all = "snake_case")]
pub enum ImageSource {
/// Image fetched from a URL.
Url {
/// Image URL.
url: String,
/// Optional provider-specific image detail level.
detail: Option<String>,
},
/// Base64-encoded image bytes.
Base64 {
/// MIME type, when supplied.
media_type: Option<String>,
/// Base64-encoded bytes.
data: String,
},
/// Provider image source with no normalized representation.
Raw(Value),
}
/// File payload forms supported by the conversation model.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", content = "data", rename_all = "snake_case")]
pub enum FileSource {
/// Provider-managed file identifier.
FileId(String),
/// Inline file payload.
FileData {
/// Encoded or textual file data as supplied by the provider format.
data: String,
/// Original filename, when supplied.
filename: Option<String>,
},
/// Provider file source with no normalized representation.
Raw(Value),
}
/// Audio and video payload forms supported by the conversation model.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", content = "data", rename_all = "snake_case")]
pub enum MediaSource {
/// Media fetched from a URL.
Url {
/// Media URL.
url: String,
/// MIME type, when supplied.
media_type: Option<String>,
},
/// Base64-encoded media bytes.
Base64 {
/// MIME type, when supplied.
media_type: Option<String>,
/// Base64-encoded bytes.
data: String,
},
/// Provider media source with no normalized representation.
Raw(Value),
}
/// Normalized assistant tool call.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ToolCall {
/// Provider tool-call identifier used to pair the result.
pub id: String,
/// Tool name.
pub name: String,
/// Parsed tool arguments.
pub arguments: Value,
}
/// Normalized tool result message content.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ToolResult {
/// Identifier of the [`ToolCall`] this result answers.
pub tool_call_id: String,
/// Ordered tool output content.
pub content: Vec<ContentBlock>,
/// Whether tool execution failed, when the provider reports it.
pub is_error: Option<bool>,
}
/// Normalized tool definition.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ToolDefinition {
/// Tool name exposed to the model.
pub name: String,
/// Human-readable tool description.
pub description: Option<String>,
/// JSON Schema describing accepted arguments.
pub parameters: Value,
/// Whether the provider should enforce the schema strictly.
pub strict: Option<bool>,
}
/// A tool available to the model, in catalog order.
#[derive(Clone, PartialEq, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Tool {
/// A remote MCP server and the tools it exposes.
Mcp(McpToolset),
/// A definition without a supported neutral representation.
Provider {
/// Source wire format; this definition is only replayed in that format.
provider: FormatId,
/// Complete provider definition.
raw: Value,
},
/// An agent-executed function. Its JSON retains the existing flat definition shape.
#[serde(untagged)]
Function(ToolDefinition),
}
impl<'de> Deserialize<'de> for Tool {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
// Keep these variants and the conversion below in sync with Tool.
#[derive(Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
enum TaggedTool {
Mcp(McpToolset),
Provider { provider: FormatId, raw: Value },
Function(ToolDefinition),
}
let value = Value::deserialize(deserializer)?;
// Only definitions without a type use the legacy function shape. A malformed
// tagged definition must fail instead of falling back to a function.
if value.get("type").is_none() {
return serde_json::from_value(value)
.map(Self::Function)
.map_err(serde::de::Error::custom);
}
let tool = serde_json::from_value(value).map_err(serde::de::Error::custom)?;
Ok(match tool {
TaggedTool::Mcp(mcp) => Self::Mcp(mcp),
TaggedTool::Provider { provider, raw } => Self::Provider { provider, raw },
TaggedTool::Function(function) => Self::Function(function),
})
}
}
impl fmt::Debug for Tool {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Function(definition) => f.debug_tuple("Function").field(definition).finish(),
Self::Mcp(mcp) => f.debug_tuple("Mcp").field(mcp).finish(),
// Raw provider definitions can contain credentials without normalized fields.
Self::Provider { provider, .. } => f
.debug_struct("Provider")
.field("provider", provider)
.finish_non_exhaustive(),
}
}
}
impl From<ToolDefinition> for Tool {
fn from(definition: ToolDefinition) -> Self {
Self::Function(definition)
}
}
impl Tool {
/// Returns the function definition, if this is an agent-executed function.
pub fn function(&self) -> Option<&ToolDefinition> {
match self {
Self::Function(definition) => Some(definition),
_ => None,
}
}
}
/// Configuration for a URL-based remote MCP toolset.
///
/// This type covers the supported neutral settings. Definitions with additional settings,
/// such as Responses headers, server descriptions, or conditional approval rules, belong
/// in [`Tool::Provider`] with the complete original definition.
#[derive(Clone, PartialEq, Serialize, Deserialize)]
pub struct McpToolset {
/// Server identity used by MCP calls.
pub name: String,
/// Remote MCP endpoint.
pub url: String,
/// Credential sent to the MCP server, when supplied.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub authorization_token: Option<String>,
/// Defaults for tools without a per-tool setting in `configs`.
#[serde(default, skip_serializing_if = "McpToolConfig::is_empty")]
pub default_config: McpToolConfig,
/// Per-tool settings, keyed by tool name. Each omitted setting inherits
/// from `default_config`, then falls back to the provider's default.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub configs: BTreeMap<String, McpToolConfig>,
/// Whether all calls require approval (`true`) or none do (`false`).
/// Absence retains provider defaults. Definitions with conditional approval rules
/// are stored in full as [`Tool::Provider`], rather than as this type.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub require_approval: Option<bool>,
}
impl fmt::Debug for McpToolset {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let Self {
name,
url: _,
authorization_token,
default_config,
configs,
require_approval,
} = self;
f.debug_struct("McpToolset")
.field("name", name)
// Credentials can appear in any part of the URL, including its path.
.field("url", &"[REDACTED]")
.field(
"authorization_token",
&authorization_token.as_ref().map(|_| "[REDACTED]"),
)
.field("default_config", default_config)
.field("configs", configs)
.field("require_approval", require_approval)
.finish()
}
}
/// Settings for an individual MCP tool or the defaults for a toolset.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct McpToolConfig {
/// Whether the tool is available for the model to call.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub enabled: Option<bool>,
/// Whether the tool definition is loaded through tool search instead of initially.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub defer_loading: Option<bool>,
}
impl McpToolConfig {
fn is_empty(&self) -> bool {
self.enabled.is_none() && self.defer_loading.is_none()
}
}
/// A tool discovered on an MCP server.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct McpListedTool {
/// Tool name as exposed by the server.
pub name: String,
/// Human-readable tool description, when supplied.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
/// JSON Schema describing accepted arguments.
pub input_schema: Value,
/// Additional tool metadata reported by the server.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub annotations: Option<Value>,
}
/// MCP discovery and execution history. Results reference the matching call's server identity.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum McpContent {
/// Tools discovered on a server at this point in the conversation.
Listing {
/// Identity of the MCP server.
server_name: String,
/// Listing identifier, when supplied by the provider.
#[serde(default, skip_serializing_if = "Option::is_none")]
id: Option<String>,
/// Discovered tools in the order reported by the server.
tools: Vec<McpListedTool>,
/// Discovery failure, when reported. An empty tool list alone is not a failure.
#[serde(default, skip_serializing_if = "Option::is_none")]
error: Option<String>,
},
/// A call executed by the backend's MCP client.
Call {
/// Identity of the MCP server.
server_name: String,
/// Ordinary call ID, name, and arguments.
call: ToolCall,
},
/// Output from a backend-executed MCP call.
Result(ToolResult),
}
/// Normalized tool choice policy.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", content = "data", rename_all = "snake_case")]
pub enum ToolChoice {
/// Let the model decide whether to call a tool.
Auto,
/// Require at least one tool call.
Required,
/// Disallow tool calls.
None,
/// Require a specific tool.
Tool {
/// Required tool name.
name: String,
},
/// Provider tool-choice value with no normalized representation.
Raw(Value),
}
/// Provider sampling parameters with common cross-provider names.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct SamplingParams {
/// Sampling temperature on the `0.0..=MAX_IR_TEMPERATURE` scale.
/// Directly constructed requests use this scale; omission retains provider defaults.
/// See [`MAX_IR_TEMPERATURE`].
pub temperature: Option<f64>,
/// Nucleus-sampling probability mass.
pub top_p: Option<f64>,
/// Maximum number of candidate tokens considered at each step.
pub top_k: Option<i64>,
}
/// Output budget and structured-output options.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OutputParams {
/// Maximum tokens the model may generate.
pub max_output_tokens: Option<u64>,
/// Provider-neutral or provider-specific structured-output configuration.
pub response_format: Option<Value>,
/// Whether the provider must enforce the response schema, overriding native
/// flags when set and retaining native behavior when `None`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub is_schema_enforced: Option<bool>,
}
/// Provider reasoning controls preserved by translation.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct ReasoningParams {
/// Requested reasoning effort or level.
pub effort: Option<String>,
/// Provider reasoning controls without a normalized field.
pub raw: Option<Value>,
}
/// Provider-specific fields that do not have first-class conversation fields.
#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct ProviderExtensions {
/// Provider fields keyed by their original wire names.
///
/// Codecs use these fields when translating to another format. Exact
/// same-format replay is controlled separately by [`PreservationMetadata`].
pub fields: Map<String, Value>,
}
// Extension values can include credentials or embedded original request bodies.
impl fmt::Debug for ProviderExtensions {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("ProviderExtensions")
.field("field_count", &self.fields.len())
.finish_non_exhaustive()
}
}
/// Exact source payloads retained for lossless same-format round trips.
///
/// Translation's default preservation policy prefers a stored same-format body
/// over reconstructing one from normalized fields. A caller that mutates the IR
/// must clear the corresponding entry or use a policy with preservation disabled
/// when those mutations must be encoded.
#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct PreservationMetadata {
/// Original request bodies keyed by source format.
pub requests: BTreeMap<FormatId, Value>,
/// Original response bodies keyed by source format.
pub responses: BTreeMap<FormatId, Value>,
}
// Original payloads can contain credentials even when normalized fields redact them.
impl fmt::Debug for PreservationMetadata {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("PreservationMetadata")
.field("request_formats", &self.requests.keys())
.field("response_formats", &self.responses.keys())
.finish_non_exhaustive()
}
}
/// Normalized request representation shared by Switchyard components.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct LlmRequest {
/// Model currently addressed by the request.
///
/// This initially contains the name supplied by the inbound client. A routing host may
/// replace it with the selected target before serving the request.
pub model: Option<String>,
/// System and developer instructions separated from conversation turns.
pub instructions: Vec<InstructionBlock>,
/// Ordered conversation messages.
pub messages: Vec<Message>,
/// This request-local count tracks temporary notes appended after the caller's conversation.
/// The HTTP client uses it to choose a cache breakpoint before the notes, subject to
/// provider support, caller policy, marker limits, and an eligible prefix.
/// Rust moves and clones retain the count.
/// Serialization omits the count, and deserialization resets it to zero.
/// Note text and preserved provider bodies remain serialized.
#[serde(skip)]
pub temporary_note_count: usize,
/// Whether this request performs compaction or resumes from a summary.
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub is_compaction: bool,
/// Whether the history contains a recognized compaction marker.
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub has_compaction: bool,
/// Tools available to the model.
pub tools: Vec<Tool>,
/// Policy controlling model tool selection.
pub tool_choice: Option<ToolChoice>,
/// Common sampling controls.
pub sampling: SamplingParams,
/// Output budget and shape controls.
pub output: OutputParams,
/// Reasoning controls.
pub reasoning: ReasoningParams,
/// Whether the caller requested a streamed response.
pub stream: bool,
/// Provider fields without first-class normalized equivalents.
pub extensions: ProviderExtensions,
/// Exact provider bodies used by codecs for lossless same-format round trips.
/// This is separate from a host's optional
/// [`Request::raw_request`](crate::Request::raw_request).
pub preservation: PreservationMetadata,
}
/// Normalized token usage counts.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Usage {
/// The upstream provider reports this monetary charge in USD.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub provider_cost: Option<f64>,
/// Non-cached input tokens. Provider codecs normalize aggregate OpenAI
/// input counts by subtracting the cache detail fields.
pub input_tokens: Option<u64>,
/// Cache-read and cache-creation token detail, when reported.
#[serde(flatten)]
pub cache: Option<Box<InputCacheUsage>>,
/// The output count includes reasoning tokens when the provider counts them.
pub output_tokens: Option<u64>,
/// Provider-reported or codec-computed total token count.
///
/// Codecs normalize OpenAI aggregate input counts before computing totals, so
/// this may equal non-cached input plus cache detail plus output.
pub total_tokens: Option<u64>,
/// Reasoning output tokens, when reported separately.
pub reasoning_tokens: Option<u64>,
}
/// Optional cache-token detail kept out of the common, cache-free usage allocation.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct InputCacheUsage {
/// The provider reports these cache-write tokens at the one-hour rate.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cache_creation_1h_input_tokens: Option<u64>,
/// Input tokens read from a provider cache.
pub cached_input_tokens: Option<u64>,
/// Input tokens written into a provider cache.
pub cache_creation_input_tokens: Option<u64>,
}
impl Usage {
/// Builds cache detail when at least one count is present.
pub fn cache_details(
cached_input_tokens: Option<u64>,
cache_creation_input_tokens: Option<u64>,
) -> Option<Box<InputCacheUsage>> {
if cached_input_tokens.is_none() && cache_creation_input_tokens.is_none() {
return None;
}
Some(Box::new(InputCacheUsage {
cache_creation_1h_input_tokens: None,
cached_input_tokens,
cache_creation_input_tokens,
}))
}
/// Returns the cache-read input-token count.
pub fn cached_input_tokens(&self) -> Option<u64> {
self.cache
.as_ref()
.and_then(|cache| cache.cached_input_tokens)
}
/// Returns the cache-creation input-token count.
pub fn cache_creation_input_tokens(&self) -> Option<u64> {
self.cache
.as_ref()
.and_then(|cache| cache.cache_creation_input_tokens)
}
/// Sets the cache-read count, allocating cache detail when needed.
pub fn set_cached_input_tokens(&mut self, value: u64) {
self.cache
.get_or_insert_with(|| Box::new(InputCacheUsage::default()))
.cached_input_tokens = Some(value);
}
/// Sets the cache-creation count, allocating cache detail when needed.
pub fn set_cache_creation_input_tokens(&mut self, value: u64) {
self.cache
.get_or_insert_with(|| Box::new(InputCacheUsage::default()))
.cache_creation_input_tokens = Some(value);
}
}
/// Normalized reason a model stopped producing output.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StopReason {
/// Model completed its turn normally.
EndTurn,
/// Model reached the configured output limit.
MaxTokens,
/// Model stopped to request a tool call.
ToolUse,
/// Provider safety or content filtering stopped generation.
ContentFilter,
/// Generation terminated because of an error.
Error,
/// Provider stop reason with no normalized equivalent.
Unknown,
}
/// A source URL cited by generated text.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct UrlCitation {
/// Start character offset in the concatenated text and refusal blocks.
pub start_index: usize,
/// Exclusive end character offset in the same text.
pub end_index: usize,
/// Source URL.
pub url: String,
/// Source title.
pub title: String,
}
/// One assistant output item in a normalized response.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct ResponseOutput {
/// Actor that produced the output, normally [`Role::Assistant`].
pub role: Role,
/// Ordered output content.
pub content: Vec<ContentBlock>,
/// URL citations in the concatenated text and refusal blocks.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub url_citations: Vec<UrlCitation>,
/// Why this output stopped, when known.
pub stop_reason: Option<StopReason>,
}
/// Normalized, fully-buffered response — the aggregate of a completed generation.
/// This is the terminal form of a streamed [`LlmResponse`](crate::LlmResponse).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct AggLlmResponse {
/// Provider response identifier.
pub id: Option<String>,
/// Model reported by the provider.
pub model: Option<String>,
/// Ordered response output items.
pub outputs: Vec<ResponseOutput>,
/// Normalized token usage.
pub usage: Usage,
/// Provider response fields without normalized equivalents.
pub extensions: ProviderExtensions,
/// Exact provider bodies retained for lossless round trips.
pub preservation: PreservationMetadata,
}
impl AggLlmResponse {
/// Returns the first output item when a response has any output.
pub fn first_output(&self) -> Option<&ResponseOutput> {
self.outputs.first()
}
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
#[test]
fn serde_uses_python_friendly_dictionary_shapes() -> Result<(), serde_json::Error> {
let request: LlmRequest = serde_json::from_value(json!({
"model": "auto",
"messages": [{
"role": "user",
"content": [{"type": "text", "text": "hello"}]
}]
}))?;
assert_eq!(request.messages[0], Message::text(Role::User, "hello"));
let tool_call = ContentBlock::ToolCall(ToolCall {
id: "call-1".to_string(),
name: "lookup".to_string(),
arguments: json!({"query": "rust"}),
});
assert_eq!(
serde_json::to_value(tool_call)?,
json!({
"type": "tool_call",
"id": "call-1",
"name": "lookup",
"arguments": {"query": "rust"}
})
);
Ok(())
}
#[test]
fn tool_deserialization_rejects_invalid_tagged_definitions() {
for definition in [
json!({"type": "mcp", "name": "inv", "parameters": {}}),
json!({"type": "provider", "provider": "x", "name": "n", "parameters": {}}),
json!({"type": "unknown", "name": "n", "parameters": {}}),
json!({"type": null, "name": "n", "parameters": {}}),
] {
assert!(serde_json::from_value::<Tool>(definition).is_err());
}
let error = serde_json::from_value::<Tool>(json!({
"type": "mcp", "name": "inv", "url": "https://example.invalid/mcp",
"authorization_token": 5, "parameters": {}
}))
.expect_err("an invalid credential must not become a function")
.to_string();
assert!(error.contains("string"), "field error was lost: {error}");
}
#[test]
fn tool_catalog_preserves_function_json_and_backend_history() -> Result<(), serde_json::Error> {
let function = json!({"name": "lookup", "description": null, "parameters": {"type": "object"}, "strict": null});
let definitions = json!([
function,
{"type": "mcp", "name": "inventory", "url": "https://example.invalid/mcp", "require_approval": false},
{"type": "provider", "provider": "openai_responses", "raw": {"type": "mcp", "connector_id": "connector_example", "server_label": "example"}},
{
"type": "mcp", "name": "configured", "url": "https://example.invalid/mcp",
"default_config": {"enabled": false, "defer_loading": true},
"configs": {"lookup": {"enabled": true}, "search": {"defer_loading": false}}
}
]);
let tools: Vec<Tool> = serde_json::from_value(definitions.clone())?;
assert!(matches!(&tools[0], Tool::Function(_)));
assert!(matches!(&tools[1], Tool::Mcp(_)));
assert!(matches!(&tools[2], Tool::Provider { .. }));
assert_eq!(serde_json::to_value(&tools)?, definitions);
let explicit_function: Tool = serde_json::from_value(json!({
"type": "function", "name": "lookup", "parameters": {"type": "object"}
}))?;
assert_eq!(explicit_function, tools[0]);
let history = json!([
{
"type": "mcp", "kind": "listing", "server_name": "inventory",
"id": "listing_1",
"tools": [{
"name": "lookup", "description": "Look up stock",
"input_schema": {"type": "object"},
"annotations": {"readOnlyHint": true}
}]
},
{"type": "mcp", "kind": "listing", "server_name": "empty", "tools": []},
{
"type": "mcp", "kind": "listing", "server_name": "unavailable",
"tools": [], "error": "Server unavailable"
},
{
"type": "mcp", "kind": "call", "server_name": "inventory",
"call": {"id": "call_1", "name": "lookup", "arguments": {}}
},
{
"type": "mcp", "kind": "result", "tool_call_id": "call_1",
"content": [{"type": "text", "text": "in stock"}], "is_error": false
}
]);
let content: Vec<ContentBlock> = serde_json::from_value(history.clone())?;
assert_eq!(serde_json::to_value(&content)?, history);
Ok(())
}
#[test]
fn mcp_credentials_are_omitted_from_debug() -> Result<(), serde_json::Error> {
let token = "synthetic-mcp-debug-secret";
let url_secret = "synthetic-mcp-url-secret";
let url = format!("https://example.invalid/mcp?api_key={url_secret}");
let mcp: McpToolset = serde_json::from_value(json!({
"name": "inventory", "url": url,
"authorization_token": token
}))?;
let raw = json!({"mcp_servers": [{"authorization_token": token}]});
let mut request = LlmRequest {
tools: vec![
Tool::Mcp(mcp.clone()),
Tool::Provider {
provider: "openai_responses".into(),
raw: json!({"type": "mcp", "authorization": token}),
},
],
..LlmRequest::default()
};
request
.preservation
.requests
.insert("anthropic_messages".into(), raw.clone());
request.extensions.fields.insert("metadata".into(), raw);
let serialized = serde_json::to_value(&request)?;
for debug in [
format!("{mcp:?}"),
format!("{mcp:#?}"),
format!("{:?}", request.tools),
format!("{:?}", request.extensions),
format!("{:?}", request.preservation),
format!("{request:?}"),
format!("{request:#?}"),
] {
assert!(!debug.contains(token), "Debug exposed an MCP credential");
assert!(
!debug.contains(url_secret),
"Debug exposed an MCP URL secret"
);
}
assert_eq!(serde_json::to_value(&request)?, serialized);
assert_eq!(serialized["tools"][0]["url"], url);
assert_eq!(serialized["tools"][0]["authorization_token"], token);
assert_eq!(serialized["tools"][1]["raw"]["authorization"], token);
Ok(())
}
}