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
feat(protocol): represent MCP tools and backend history (#993)
David Gardnerab7d26443899
diff --git a/crates/protocol/README.md b/crates/protocol/README.mdindex a5b5b9f57..83a1eff17 100644--- a/crates/protocol/README.md+++ b/crates/protocol/README.md@@ -17,7 +17,7 @@ serde_json = "1"| Area | Types ||---|---|| Conversation | [`LlmRequest`], [`Message`], [`InstructionBlock`], [`ContentBlock`] |-| Tools | [`ToolDefinition`], [`ToolChoice`], [`ToolCall`], [`ToolResult`] |+| Tools | [`Tool`], [`ToolDefinition`], [`McpToolset`], [`McpToolConfig`], [`McpContent`], [`ToolChoice`], [`ToolCall`], [`ToolResult`] || Response | [`AggLlmResponse`], [`ResponseOutput`], [`Usage`], [`StopReason`] || Streaming | [`LlmResponse`], [`LlmResponseStream`], [`LlmResponseStreamEvent`], [`LlmResponseChunk`], [`ProviderStreamEvent`] || Envelope | [`Request`], [`Response`], [`Metadata`] |@@ -75,7 +75,7 @@ let request = Request {"required": ["name"]}),strict: Some(true),- }],+ }.into()],tool_choice: Some(ToolChoice::Auto),sampling: SamplingParams {temperature: Some(0.2),@@ -96,7 +96,7 @@ let request = Request {..Request::default()};-assert_eq!(request.llm_request.tools[0].name, "lookup_metric");+assert_eq!(request.llm_request.tools[0].function().map(|tool| tool.name.as_str()), Some("lookup_metric"));```## Response formsdiff --git a/crates/protocol/src/llm.rs b/crates/protocol/src/llm.rsindex cef8d5980..a284136b9 100644--- a/crates/protocol/src/llm.rs+++ b/crates/protocol/src/llm.rs@@ -2,8 +2,13 @@// 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};@@ -116,6 +121,8 @@ pub enum ContentBlock {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.@@ -226,6 +233,198 @@ pub struct ToolDefinition {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")]@@ -279,7 +478,7 @@ pub struct ReasoningParams {}/// Provider-specific fields that do not have first-class conversation fields.-#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]+#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]#[serde(default)]pub struct ProviderExtensions {/// Provider fields keyed by their original wire names.@@ -289,13 +488,22 @@ pub struct ProviderExtensions {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, Debug, Default, PartialEq, Serialize, Deserialize)]+#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]#[serde(default)]pub struct PreservationMetadata {/// Original request bodies keyed by source format.@@ -304,6 +512,16 @@ pub struct PreservationMetadata {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)]@@ -318,7 +536,7 @@ pub struct LlmRequest {/// Ordered conversation messages.pub messages: Vec<Message>,/// Tools available to the model.- pub tools: Vec<ToolDefinition>,+ pub tools: Vec<Tool>,/// Policy controlling model tool selection.pub tool_choice: Option<ToolChoice>,/// Common sampling controls.@@ -514,4 +732,123 @@ mod tests {);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(())+ }}diff --git a/crates/protocol/src/stream.rs b/crates/protocol/src/stream.rsindex c59a66f77..428d01a0f 100644--- a/crates/protocol/src/stream.rs+++ b/crates/protocol/src/stream.rs@@ -214,7 +214,7 @@ impl AggLlmResponse {////// This conversion is lossy: only text, reasoning, and tool-call content has/// a synthetic chunk representation. Refusals, tool results, media, files,- /// unknown blocks, response extensions, and preservation metadata are omitted.+ /// MCP activity, unknown blocks, response extensions, and preservation metadata are omitted.pub fn into_stream(self) -> LlmResponseStream {let mut chunks: Vec<LlmResponseChunk> = Vec::new();chunks.push(LlmResponseChunk::MessageStart {@@ -255,8 +255,7 @@ impl AggLlmResponse {});tool_call_index += 1;}- // Other variants (Image, ToolResult, Refusal, etc.) don't have- // a streaming chunk representation and don't appear in assistant outputs.+ // Other variants, including backend MCP activity, have no synthetic chunks._ => {}}}diff --git a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs b/crates/switchyard-translation/src/codecs/anthropic/buffered.rsindex de6d7c210..88aa8a324 100644--- a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs+++ b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs@@ -20,7 +20,7 @@ use crate::format::{FormatId, WireFormat};use crate::llm::{AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,- SamplingParams, StopReason, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,+ SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,};use crate::policy::{DeterministicIdPolicy, TranslationPolicy};use crate::util::{@@ -154,7 +154,10 @@ impl FormatCodec for AnthropicMessagesCodec {request.messages.push(Message { role, content });}}- request.tools = decode_anthropic_tools(body.get("tools"));+ request.tools = decode_anthropic_tools(body.get("tools"))+ .into_iter()+ .map(Tool::from)+ .collect();request.tool_choice = body.get("tool_choice").map(decode_anthropic_tool_choice);request.extensions.fields = provider_extensions(body,@@ -245,7 +248,7 @@ impl FormatCodec for AnthropicMessagesCodec {);if !tools.is_empty() {- body.insert("tools".to_string(), encode_anthropic_tools(tools));+ body.insert("tools".to_string(), encode_anthropic_tools(tools)?);}let parallel_tool_calls = request.extensions@@ -1118,6 +1121,11 @@ fn encode_one_anthropic_block(block: &ContentBlock) -> Result<Vec<Value>> {}),MediaSource::Raw(raw) => raw.clone(),}],+ ContentBlock::Mcp(_) => {+ return Err(TranslationError::LossyConversion(+ "MCP history encoding is not implemented".into(),+ ));+ }ContentBlock::Unknown { raw, .. } => vec![raw.clone()],})}@@ -1137,6 +1145,9 @@ fn encode_one_anthropic_tool_result_block(block: &ContentBlock) -> Result<Vec<VaContentBlock::Unknown { raw, .. } => {Ok(vec![json!({"type": "text", "text": json_string(raw)})])}+ ContentBlock::Mcp(_) => Err(TranslationError::LossyConversion(+ "MCP history encoding is not implemented".into(),+ )),ContentBlock::Reasoning { .. }| ContentBlock::Audio { .. }| ContentBlock::Video { .. }@@ -1198,11 +1209,16 @@ fn ensure_anthropic_tool_input_object(arguments: Value) -> Value {}// Encodes normalized tool definitions into Anthropic tool JSON.-fn encode_anthropic_tools(tools: &[ToolDefinition]) -> Value {- Value::Array(+fn encode_anthropic_tools(tools: &[Tool]) -> Result<Value> {+ Ok(Value::Array(tools.iter().map(|tool| {+ let tool = tool.function().ok_or_else(|| {+ TranslationError::LossyConversion(+ "MCP and provider tool encoding is not implemented".into(),+ )+ })?;let mut item = json!({"name": tool.name,"description": tool.description.clone().unwrap_or_default(),@@ -1211,10 +1227,10 @@ fn encode_anthropic_tools(tools: &[ToolDefinition]) -> Value {if let Some(strict) = tool.strict {item["strict"] = Value::Bool(strict);}- item+ Ok(item)})- .collect(),- )+ .collect::<Result<_>>()?,+ ))}// Encodes normalized tool choice into Anthropic tool-choice JSON.diff --git a/crates/switchyard-translation/src/codecs/common.rs b/crates/switchyard-translation/src/codecs/common.rsindex b8e0fc20c..ddd795f80 100644--- a/crates/switchyard-translation/src/codecs/common.rs+++ b/crates/switchyard-translation/src/codecs/common.rs@@ -6,7 +6,7 @@use serde_json::{Map, Value};use crate::error::{Result, TranslationError};-use crate::llm::{ContentBlock, LlmRequest, ToolChoice, ToolDefinition};+use crate::llm::{ContentBlock, LlmRequest, Tool, ToolChoice};// Internal provenance survives mutations that invalidate exact request replay.pub(crate) const ANTHROPIC_REQUEST_KEY: &str = "switchyard_anthropic_request";@@ -19,7 +19,7 @@ pub(crate) fn is_anthropic_request(request: &LlmRequest) -> bool {/// Converts an OpenAI allowed-tools policy to a restricted function list and mode.pub(crate) fn allowed_function_tools(request: &LlmRequest,-) -> Result<Option<(Vec<ToolDefinition>, ToolChoice)>> {+) -> Result<Option<(Vec<Tool>, ToolChoice)>> {let Some(ToolChoice::Raw(choice)) = &request.tool_choice else {return Ok(None);};@@ -63,7 +63,12 @@ pub(crate) fn allowed_function_tools(}_ => name.to_string(),};- if !request.tools.iter().any(|tool| tool.name == name) {+ if !request+ .tools+ .iter()+ .filter_map(Tool::function)+ .any(|tool| tool.name == name)+ {return Err(error());}names.push(name);@@ -73,7 +78,10 @@ pub(crate) fn allowed_function_tools(let tools = request.tools.iter()- .filter(|tool| names.contains(&tool.name))+ .filter(|tool| {+ tool.function()+ .is_some_and(|tool| names.contains(&tool.name))+ }).cloned().collect();Ok(Some((tools, mode)))diff --git a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rsindex afe99c539..5c36c6d55 100644--- a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs+++ b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs@@ -22,7 +22,7 @@ use crate::format::{FormatId, WireFormat};use crate::llm::{AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,- SamplingParams, StopReason, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,+ SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,};use crate::policy::{DeterministicIdPolicy, TranslationPolicy};use crate::util::{@@ -158,7 +158,10 @@ impl FormatCodec for OpenAiChatCodec {}}- request.tools = decode_openai_tools(body.get("tools"), &mut diagnostics, policy)?;+ request.tools = decode_openai_tools(body.get("tools"), &mut diagnostics, policy)?+ .into_iter()+ .map(Tool::from)+ .collect();request.tool_choice = body.get("tool_choice").map(decode_openai_tool_choice);request.extensions.fields = provider_extensions(body,@@ -233,7 +236,7 @@ impl FormatCodec for OpenAiChatCodec {body.insert("messages".to_string(), Value::Array(messages));if !tools.is_empty() {- body.insert("tools".to_string(), encode_openai_tools(tools));+ body.insert("tools".to_string(), encode_openai_tools(tools)?);if let Some(choice) = tool_choice {body.insert("tool_choice".to_string(), encode_openai_tool_choice(choice));}@@ -1036,6 +1039,14 @@ pub(crate) fn encode_openai_content(diagnostics: &mut Vec<TranslationDiagnostic>,policy: &TranslationPolicy,) -> Result<Value> {+ if content+ .iter()+ .any(|block| matches!(block, ContentBlock::Mcp(_)))+ {+ return Err(TranslationError::LossyConversion(+ "MCP history encoding is not implemented".into(),+ ));+ }let has_non_text = content.iter().any(|block| {matches!(block,@@ -1096,6 +1107,11 @@ pub(crate) fn encode_openai_content()?;blocks.push(openai_text_part(&media_source_text(source)));}+ ContentBlock::Mcp(_) => {+ return Err(TranslationError::LossyConversion(+ "MCP history encoding is not implemented".into(),+ ));+ }ContentBlock::Unknown { provider, raw } => {reject_responses_builtin_tool_item(provider, raw, WireFormat::OpenAiChat)?;push_lossy(@@ -1152,11 +1168,16 @@ fn media_source_text(source: &MediaSource) -> String {}/// Encodes normalized tool definitions into OpenAI tool JSON.-pub(crate) fn encode_openai_tools(tools: &[ToolDefinition]) -> Value {- Value::Array(+pub(crate) fn encode_openai_tools(tools: &[Tool]) -> Result<Value> {+ Ok(Value::Array(tools.iter().map(|tool| {+ let tool = tool.function().ok_or_else(|| {+ TranslationError::LossyConversion(+ "MCP and provider tool encoding is not implemented".into(),+ )+ })?;let mut function = json!({"name": tool.name,"description": tool.description.clone().unwrap_or_default(),@@ -1165,10 +1186,10 @@ pub(crate) fn encode_openai_tools(tools: &[ToolDefinition]) -> Value {if let Some(strict) = tool.strict {function["strict"] = Value::Bool(strict);}- json!({"type": "function", "function": function})+ Ok(json!({"type": "function", "function": function}))})- .collect(),- )+ .collect::<Result<_>>()?,+ ))}/// Encodes normalized tool choice into OpenAI Chat JSON.diff --git a/crates/switchyard-translation/src/codecs/responses/buffered.rs b/crates/switchyard-translation/src/codecs/responses/buffered.rsindex fb970f2d9..43fab2806 100644--- a/crates/switchyard-translation/src/codecs/responses/buffered.rs+++ b/crates/switchyard-translation/src/codecs/responses/buffered.rs@@ -26,7 +26,7 @@ use crate::format::{FormatId, WireFormat};use crate::llm::{AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,- SamplingParams, StopReason, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,+ SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,};use crate::policy::{DeterministicIdPolicy, TranslationPolicy};use crate::util::{@@ -114,7 +114,10 @@ impl FormatCodec for OpenAiResponsesCodec {let mut tool_namespaces = Map::new();let mut custom_tools = Map::new();request.tools =- decode_responses_tools(body.get("tools"), &mut tool_namespaces, &mut custom_tools);+ decode_responses_tools(body.get("tools"), &mut tool_namespaces, &mut custom_tools)+ .into_iter()+ .map(Tool::from)+ .collect();// Responses-lite clients (Codex with a GPT-5 model) carry the tool definitions inside// `input` as an `additional_tools` developer item instead of top-level `tools`. Those// definitions are the request's tools; the item itself is kept verbatim so the request@@ -126,11 +129,15 @@ impl FormatCodec for OpenAiResponsesCodec {&& item.get("type").and_then(Value::as_str) == Some("additional_tools")&& let Some(tools) = item.get("tools").and_then(Value::as_array){- request.tools.extend(decode_responses_tools(- Some(&Value::Array(tools.clone())),- &mut tool_namespaces,- &mut custom_tools,- ));+ request.tools.extend(+ decode_responses_tools(+ Some(&Value::Array(tools.clone())),+ &mut tool_namespaces,+ &mut custom_tools,+ )+ .into_iter()+ .map(Tool::from),+ );additional_tools.extend(tools.iter().cloned());}}@@ -240,7 +247,7 @@ impl FormatCodec for OpenAiResponsesCodec {&request.tools,crate::codex_namespaces::tool_namespaces(&request.extensions),crate::codex_custom_tools::custom_tools(&request.extensions),- ),+ )?,);}if let Some(choice) = &request.tool_choice@@ -1631,6 +1638,11 @@ fn encode_responses_content(blocks.push(json!({"type": "input_text", "text": file_source_text(source)}));}},+ ContentBlock::Mcp(_) => {+ return Err(TranslationError::LossyConversion(+ "MCP history encoding is not implemented".into(),+ ));+ }ContentBlock::Unknown { raw, .. } => {push_lossy(diagnostics,@@ -1694,13 +1706,18 @@ fn responses_file_part(source: &FileSource) -> Option<Value> {// A Responses client understands Codex containers, so a tool whose name this// request qualified is regrouped under the container it came from.fn encode_responses_tools(- tools: &[ToolDefinition],+ tools: &[Tool],namespaces: Option<&Map<String, Value>>,custom_tools: Option<&Map<String, Value>>,-) -> Value {+) -> Result<Value> {let mut out: Vec<Value> = Vec::new();let mut containers: Vec<(String, Vec<Value>)> = Vec::new();for tool in tools {+ let tool = tool.function().ok_or_else(|| {+ TranslationError::LossyConversion(+ "MCP and provider tool encoding is not implemented".into(),+ )+ })?;// A freeform tool goes back out exactly as the client defined it.if let Some(custom) = custom_tools.and_then(|custom| custom.get(&tool.name)) {out.push(custom.clone());@@ -1745,7 +1762,7 @@ fn encode_responses_tools("tools": children,}));}- Value::Array(out)+ Ok(Value::Array(out))}// Encodes normalized tool choice into Responses JSON.diff --git a/crates/switchyard-translation/tests/request_translation.rs b/crates/switchyard-translation/tests/request_translation.rsindex 6cd696397..10445bb1e 100644--- a/crates/switchyard-translation/tests/request_translation.rs+++ b/crates/switchyard-translation/tests/request_translation.rs@@ -16,6 +16,45 @@ use common::{REASONING_MODEL, normalized_policy, shell_tool_call};type TestResult<T = ()> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;+#[test]+fn openai_chat_rejects_mcp_history_before_text_only_returns() {+ use switchyard_translation::{LlmRequest, McpContent, Message, Role};++ let engine = TranslationEngine::default();+ for role in [Role::User, Role::Assistant] {+ let request = LlmRequest {+ messages: vec![Message {+ role,+ content: vec![+ ContentBlock::Text {+ text: "Keep this text".into(),+ },+ ContentBlock::Mcp(McpContent::Listing {+ server_name: "inventory".into(),+ id: None,+ tools: Vec::new(),+ error: None,+ }),+ ],+ }],+ ..LlmRequest::default()+ };+ for lossy_conversion_policy in [+ LossyConversionPolicy::AllowWithDiagnostics,+ LossyConversionPolicy::Reject,+ ] {+ let policy = TranslationPolicy {+ lossy_conversion_policy,+ ..TranslationPolicy::default()+ };+ assert!(matches!(+ engine.encode_request(WireFormat::OpenAiChat, &request, &policy),+ Err(TranslationError::LossyConversion(_))+ ));+ }+ }+}+#[test]fn responses_allowed_tools_is_translated_or_rejected() -> TestResult {let engine = TranslationEngine::default();@@ -4131,7 +4170,7 @@ fn responses_lite_additional_tools_item_is_the_tool_list() -> TestResult {.request.tools.iter()- .map(|tool| tool.name.as_str())+ .filter_map(|tool| tool.function().map(|tool| tool.name.as_str())).collect::<Vec<_>>();assert_eq!(names, vec!["exec", "update_plan"]);assert!(diff --git a/examples/dynamo-preproc/src/request.rs b/examples/dynamo-preproc/src/request.rsindex ae36f0bd9..f8b591617 100644--- a/examples/dynamo-preproc/src/request.rs+++ b/examples/dynamo-preproc/src/request.rs@@ -113,7 +113,10 @@ mod tests {assert_eq!(ir.sampling.temperature, Some(0.2));assert_eq!(ir.output.max_output_tokens, Some(64));assert_eq!(ir.tool_choice, Some(ToolChoice::Required));- assert_eq!(ir.tools[0].name, "Bash");+ assert_eq!(+ ir.tools[0].function().map(|tool| tool.name.as_str()),+ Some("Bash")+ );let ContentBlock::ToolCall(call) = &ir.messages[0].content[0] else {panic!("missing tool call")};