Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions crates/protocols/src/responses.rs
Original file line number Diff line number Diff line change
Expand Up @@ -403,6 +403,56 @@ pub enum ResponseTool {
/// raw `input` string back to the client; the client owns execution.
#[serde(rename = "custom")]
Custom(CustomTool),

/// Grouping of `Function` / `Custom` tools under a shared namespace.
///
/// Spec (openai-responses-api-spec.md §tools L475):
/// `Namespace { description, name, tools: array of Function | Custom,
/// type: "namespace" }` — inner elements share the top-level shape but
/// are restricted to `Function` or `Custom`. Nested namespaces and
/// hosted/built-in tools are explicitly not permitted as elements.
#[serde(rename = "namespace")]
Namespace(NamespaceToolDef),
}

/// Payload carried by [`ResponseTool::Namespace`].
///
/// Using a dedicated struct (rather than inline struct-variant fields) lets
/// us apply `#[serde(deny_unknown_fields)]`, matching sibling variants like
/// [`CustomTool`] and [`FunctionTool`] so unrecognized namespace-level keys
/// are rejected instead of silently swallowed.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct NamespaceToolDef {
/// Human-readable description surfaced to the model alongside the group.
pub description: String,
/// Stable identifier the model uses to address the namespace in
/// `function_call` / `custom_tool_call` items (via the `namespace` field).
pub name: String,
/// Tools in this namespace. Spec restricts elements to `Function` or
/// `Custom`; the dedicated [`NamespaceTool`] enum prevents nested
/// namespaces and hosted-tool leakage that the parent `ResponseTool`
/// enum would otherwise allow.
pub tools: Vec<NamespaceTool>,
}

/// Element type accepted inside a [`NamespaceToolDef`]'s `tools` array.
///
/// Spec (openai-responses-api-spec.md §tools L475): namespace elements must be
/// either a `Function` or a `Custom` tool. Using a dedicated enum rather than
/// `ResponseTool` prevents recursive nesting (`Namespace` inside `Namespace`)
/// and hosted/built-in tool leakage that the spec forbids.
#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
#[serde(tag = "type")]
#[serde(rename_all = "snake_case")]
pub enum NamespaceTool {
/// Function tool — same shape as [`ResponseTool::Function`].
#[serde(rename = "function")]
Function(FunctionTool),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve namespace function defer-loading and optional schema

Do not reuse FunctionTool for namespace members: this path flattens into common::Function (which requires parameters and has no defer_loading field), so namespace tools like {"type":"namespace",...,"tools":[{"type":"function","name":"lookup","defer_loading":true}]} cannot be represented faithfully. As a result, valid namespace function definitions either fail deserialization (missing required schema fields) or silently lose namespace-specific function metadata, which breaks deferred namespace/tool-search workflows.

Useful? React with 👍 / 👎.


/// Custom tool — same shape as [`ResponseTool::Custom`].
#[serde(rename = "custom")]
Custom(CustomTool),
}

#[serde_with::skip_serializing_none]
Expand Down
235 changes: 235 additions & 0 deletions crates/protocols/tests/responses.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1454,6 +1454,241 @@ fn test_custom_tool_grammar_format_round_trip() {
}
}

#[test]
fn test_namespace_tool_with_function_round_trip() {
// Spec (openai-responses-api-spec.md §tools L475):
// `Namespace { description, name, tools: array of Function | Custom,
// type: "namespace" }`. Inner elements reuse the top-level Function
// shape but are restricted by the spec to Function or Custom.
let payload = json!({
"type": "namespace",
"name": "sql",
"description": "Tools for interacting with the warehouse",
"tools": [
{
"type": "function",
"name": "select",
"description": "Run a read-only SELECT",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"}
},
"required": ["query"]
},
"strict": true
}
]
});

let tool: ResponseTool = serde_json::from_value(payload.clone())
.expect("namespace tool with function element should deserialize");
match &tool {
ResponseTool::Namespace(def) => {
assert_eq!(def.name, "sql");
assert_eq!(def.description, "Tools for interacting with the warehouse");
assert_eq!(def.tools.len(), 1);
match &def.tools[0] {
NamespaceTool::Function(ft) => {
assert_eq!(ft.function.name, "select");
assert_eq!(ft.function.strict, Some(true));
}
other @ NamespaceTool::Custom(_) => {
panic!("expected NamespaceTool::Function, got {other:?}")
}
}
}
other => panic!("expected ResponseTool::Namespace, got {other:?}"),
}

let serialized = serde_json::to_value(&tool).expect("namespace tool should serialize");
assert_eq!(serialized, payload);
}

#[test]
fn test_namespace_tool_with_custom_text_format_round_trip() {
// Spec (openai-responses-api-spec.md §tools L471-475): namespace elements
// may be Custom tools. `Custom { name, type: "custom", defer_loading?,
// description?, format? }` with `format: Text { type: "text" }`.
let payload = json!({
"type": "namespace",
"name": "shell",
"description": "User-owned shell helpers",
"tools": [
{
"type": "custom",
"name": "raw_cmd",
"description": "Emit a free-form shell command",
"format": {"type": "text"}
}
]
});

let tool: ResponseTool = serde_json::from_value(payload.clone())
.expect("namespace tool with custom/text element should deserialize");
match &tool {
ResponseTool::Namespace(def) => {
assert_eq!(def.tools.len(), 1);
match &def.tools[0] {
NamespaceTool::Custom(c) => {
assert_eq!(c.name, "raw_cmd");
assert!(matches!(c.format, Some(CustomToolInputFormat::Text)));
}
other @ NamespaceTool::Function(_) => {
panic!("expected NamespaceTool::Custom, got {other:?}")
}
}
}
other => panic!("expected ResponseTool::Namespace, got {other:?}"),
}

let serialized = serde_json::to_value(&tool).expect("namespace tool should serialize");
assert_eq!(serialized, payload);
}

#[test]
fn test_namespace_tool_with_custom_grammar_format_round_trip() {
// Spec (openai-responses-api-spec.md §tools L472-475): namespace elements
// may be Custom tools whose `format: Grammar { definition, syntax: "lark"
// | "regex", type: "grammar" }` constrains free-form input at decode time.
for syntax in ["lark", "regex"] {
let payload = json!({
"type": "namespace",
"name": "parse",
"description": "Grammar-constrained parsers",
"tools": [
{
"type": "custom",
"name": "expr_parser",
"format": {
"type": "grammar",
"definition": "start: NUMBER",
"syntax": syntax
}
}
]
});

let tool: ResponseTool = serde_json::from_value(payload.clone())
.expect("namespace tool with custom/grammar element should deserialize");
match &tool {
ResponseTool::Namespace(def) => match &def.tools[0] {
NamespaceTool::Custom(c) => match &c.format {
Some(CustomToolInputFormat::Grammar(g)) => {
assert_eq!(g.definition, "start: NUMBER");
let expected = if syntax == "lark" {
CustomToolGrammarSyntax::Lark
} else {
CustomToolGrammarSyntax::Regex
};
assert_eq!(g.syntax, expected);
}
other => panic!("expected Grammar format, got {other:?}"),
},
other @ NamespaceTool::Function(_) => {
panic!("expected NamespaceTool::Custom, got {other:?}")
}
},
other => panic!("expected ResponseTool::Namespace, got {other:?}"),
}

let serialized = serde_json::to_value(&tool).expect("namespace tool should serialize");
assert_eq!(serialized, payload);
}
}

#[test]
fn test_namespace_tool_mixed_elements_round_trip() {
// Spec (openai-responses-api-spec.md §tools L475): a single namespace may
// mix Function and Custom elements in any order.
let payload = json!({
"type": "namespace",
"name": "fs",
"description": "Filesystem helpers",
"tools": [
{
"type": "function",
"name": "read_file",
"description": "Read a file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
},
"strict": true
},
{
"type": "custom",
"name": "write_file",
"description": "Write a file by free-form payload"
}
]
});

let tool: ResponseTool = serde_json::from_value(payload.clone())
.expect("namespace tool with mixed elements should deserialize");
match &tool {
ResponseTool::Namespace(def) => {
assert_eq!(def.tools.len(), 2);
assert!(
matches!(&def.tools[0], NamespaceTool::Function(ft) if ft.function.name == "read_file")
);
assert!(matches!(&def.tools[1], NamespaceTool::Custom(c) if c.name == "write_file"));
}
other => panic!("expected ResponseTool::Namespace, got {other:?}"),
}

let serialized = serde_json::to_value(&tool).expect("namespace tool should serialize");
assert_eq!(serialized, payload);
}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

#[test]
fn test_namespace_tool_rejects_nested_namespace_element() {
// Spec (openai-responses-api-spec.md §tools L475): a Namespace's `tools`
// may contain only Function or Custom — nested Namespace elements are
// forbidden. The dedicated NamespaceTool enum (without a Namespace arm)
// is what enforces this at the protocol layer.
let payload = json!({
"type": "namespace",
"name": "outer",
"description": "outer namespace",
"tools": [
{
"type": "namespace",
"name": "inner",
"description": "inner namespace",
"tools": []
}
]
});

assert!(
serde_json::from_value::<ResponseTool>(payload).is_err(),
"nested namespace elements must be rejected"
);
}

#[test]
fn test_namespace_tool_rejects_hosted_tool_element() {
// Spec (openai-responses-api-spec.md §tools L475): hosted / built-in tool
// types (e.g. `file_search`, `web_search_preview`, `code_interpreter`)
// may appear as top-level ResponseTool entries but MUST NOT appear as
// namespace elements.
let payload = json!({
"type": "namespace",
"name": "ns",
"description": "namespace",
"tools": [
{ "type": "file_search", "vector_store_ids": ["vs_123"] }
]
});

assert!(
serde_json::from_value::<ResponseTool>(payload).is_err(),
"hosted/built-in tools must be rejected inside namespace.tools"
);
}

#[test]
fn computer_call_input_item_round_trips_spec_shape() {
let payload = json!({
Expand Down
1 change: 1 addition & 0 deletions model_gateway/src/routers/grpc/harmony/builder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -441,6 +441,7 @@ impl HarmonyBuilder {
ResponseTool::Computer => "computer",
ResponseTool::ComputerUsePreview(_) => "computer_use_preview",
ResponseTool::Custom(_) => "custom",
ResponseTool::Namespace(_) => "namespace",
})
.collect()
})
Expand Down
4 changes: 4 additions & 0 deletions model_gateway/src/routers/openai/responses/utils.rs
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,10 @@ pub(super) fn response_tool_to_value(tool: &ResponseTool) -> Option<Value> {
serde_json::to_value(tool).ok()
}
ResponseTool::Custom(_) => serde_json::to_value(tool).ok(),
// Namespace groups Function/Custom elements; serialize through serde so
// the full {type, name, description, tools} payload round-trips back
// to the client unchanged (T9).
ResponseTool::Namespace(_) => serde_json::to_value(tool).ok(),
ResponseTool::Function(_) => None,
}
}
Expand Down
Loading