From 8de2bab04a5776964e70ce6a29cc325489048bf9 Mon Sep 17 00:00:00 2001 From: Simo Lin Date: Wed, 22 Apr 2026 16:12:33 -0700 Subject: [PATCH 1/2] feat(protocols): implement T9 namespace tool grouping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Responses API spec §tools L475 defines a `Namespace` tool that groups related `Function` / `Custom` tools under a shared name + description. Inner elements share the top-level shape but are restricted to those two variants — nested namespaces and hosted/built-in tools are not permitted as elements. Protocol changes (`crates/protocols/src/responses.rs`): - Add `ResponseTool::Namespace { description, name, tools: Vec }` tagged `#[serde(rename = "namespace")]`. - Add a dedicated `NamespaceTool = Function(FunctionTool) | Custom(CustomTool)` enum rather than reusing `ResponseTool`. Using `ResponseTool` would structurally allow recursive `Namespace` nesting and hosted tools as namespace elements — both explicitly forbidden by spec. Forced-cascade router arms (no scope bleed): - `response_tool_to_value` (openai/responses/utils.rs) — route `Namespace` through `serde_json::to_value` so the full payload round-trips back to the client, mirroring how `Custom` / hosted tools are handled. - Harmony `tool_types` mapping (grpc/harmony/builder.rs) — emit `"namespace"` to match the spec discriminator. Integration tests (`crates/protocols/tests/responses.rs`, 4 new): - `test_namespace_tool_with_function_round_trip` — namespace carrying a single `Function` element. - `test_namespace_tool_with_custom_text_format_round_trip` — namespace carrying a `Custom` tool with `Text` format. - `test_namespace_tool_with_custom_grammar_format_round_trip` — namespace carrying a `Custom` tool with `Grammar` format, exercised for both `lark` and `regex` syntaxes. - `test_namespace_tool_mixed_elements_round_trip` — single namespace mixing `Function` and `Custom` elements. Refs: T9 (.claude/_audit/responses-api-gap-audit.md §T9, L568-578) Spec: .claude/_audit/openai-responses-api-spec.md L475 Signed-off-by: Simo Lin --- crates/protocols/src/responses.rs | 40 ++++ crates/protocols/tests/responses.rs | 192 ++++++++++++++++++ .../src/routers/grpc/harmony/builder.rs | 1 + .../src/routers/openai/responses/utils.rs | 4 + 4 files changed, 237 insertions(+) diff --git a/crates/protocols/src/responses.rs b/crates/protocols/src/responses.rs index 2de5723edf..7a114c51df 100644 --- a/crates/protocols/src/responses.rs +++ b/crates/protocols/src/responses.rs @@ -403,6 +403,46 @@ 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 { + /// Human-readable description surfaced to the model alongside the group. + description: String, + /// Stable identifier the model uses to address the namespace in + /// `function_call` / `custom_tool_call` items (via the `namespace` field). + 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. + tools: Vec, + }, +} + +/// Element type accepted inside a [`ResponseTool::Namespace`]'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), + + /// Custom tool — same shape as [`ResponseTool::Custom`]. + #[serde(rename = "custom")] + Custom(CustomTool), } #[serde_with::skip_serializing_none] diff --git a/crates/protocols/tests/responses.rs b/crates/protocols/tests/responses.rs index a30d53c70e..1490ba581a 100644 --- a/crates/protocols/tests/responses.rs +++ b/crates/protocols/tests/responses.rs @@ -1454,6 +1454,198 @@ 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 { + description, + name, + tools, + } => { + assert_eq!(name, "sql"); + assert_eq!(description, "Tools for interacting with the warehouse"); + assert_eq!(tools.len(), 1); + match &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 { tools, .. } => { + assert_eq!(tools.len(), 1); + match &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 { tools, .. } => match &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 { tools, .. } => { + assert_eq!(tools.len(), 2); + assert!( + matches!(&tools[0], NamespaceTool::Function(ft) if ft.function.name == "read_file") + ); + assert!(matches!(&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); +} + #[test] fn computer_call_input_item_round_trips_spec_shape() { let payload = json!({ diff --git a/model_gateway/src/routers/grpc/harmony/builder.rs b/model_gateway/src/routers/grpc/harmony/builder.rs index b6d29c6b1b..2d0d302879 100644 --- a/model_gateway/src/routers/grpc/harmony/builder.rs +++ b/model_gateway/src/routers/grpc/harmony/builder.rs @@ -441,6 +441,7 @@ impl HarmonyBuilder { ResponseTool::Computer => "computer", ResponseTool::ComputerUsePreview(_) => "computer_use_preview", ResponseTool::Custom(_) => "custom", + ResponseTool::Namespace { .. } => "namespace", }) .collect() }) diff --git a/model_gateway/src/routers/openai/responses/utils.rs b/model_gateway/src/routers/openai/responses/utils.rs index 0b0739e9e8..ffe1cab63a 100644 --- a/model_gateway/src/routers/openai/responses/utils.rs +++ b/model_gateway/src/routers/openai/responses/utils.rs @@ -252,6 +252,10 @@ pub(super) fn response_tool_to_value(tool: &ResponseTool) -> Option { 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, } } From 3743ccedda2eb76418b0d5347fe222429151fd72 Mon Sep 17 00:00:00 2001 From: Simo Lin Date: Wed, 22 Apr 2026 16:36:06 -0700 Subject: [PATCH 2/2] refactor(protocols): address T9 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two follow-ups from PR #1337 review (Claude nit + CodeRabbit nitpick). 1. Extract `NamespaceToolDef` struct (`crates/protocols/src/responses.rs`) Claude flagged that the inline struct-variant form of `ResponseTool::Namespace { description, name, tools }` cannot carry `#[serde(deny_unknown_fields)]`, unlike sibling tuple variants such as `Custom(CustomTool)` / `Function(FunctionTool)` whose wrapper structs reject unknown keys. A payload with a bogus top-level key (e.g. `{"type": "namespace", "name": "x", "bogus": 1, ...}`) was silently accepted — inconsistent with how the rest of the enum behaves. Switched to `ResponseTool::Namespace(NamespaceToolDef)` with `#[serde(deny_unknown_fields)]` on the dedicated struct. Updates propagate to the two forced-cascade router arms plus the matching test destructurings. 2. Add fail-fast tests for disallowed namespace child types (`crates/protocols/tests/responses.rs`) CodeRabbit requested negative tests locking in the spec invariant that namespace.tools may contain only Function or Custom. Added two deserialization-failure tests: - `test_namespace_tool_rejects_nested_namespace_element` — nested `{"type": "namespace", ...}` must fail. - `test_namespace_tool_rejects_hosted_tool_element` — hosted tools like `file_search` must fail. Tests: `cargo test -p openai-protocol --test responses` → 65 passed (2 new negative, 4 round-trip from the prior commit). Gates: clippy clean, fmt clean. Refs: review comments on #1337 (claude[bot], coderabbitai[bot]). Signed-off-by: Simo Lin --- crates/protocols/src/responses.rs | 36 +++++---- crates/protocols/tests/responses.rs | 77 +++++++++++++++---- .../src/routers/grpc/harmony/builder.rs | 2 +- .../src/routers/openai/responses/utils.rs | 2 +- 4 files changed, 85 insertions(+), 32 deletions(-) diff --git a/crates/protocols/src/responses.rs b/crates/protocols/src/responses.rs index 7a114c51df..707b21b8fc 100644 --- a/crates/protocols/src/responses.rs +++ b/crates/protocols/src/responses.rs @@ -412,21 +412,31 @@ pub enum ResponseTool { /// are restricted to `Function` or `Custom`. Nested namespaces and /// hosted/built-in tools are explicitly not permitted as elements. #[serde(rename = "namespace")] - Namespace { - /// Human-readable description surfaced to the model alongside the group. - description: String, - /// Stable identifier the model uses to address the namespace in - /// `function_call` / `custom_tool_call` items (via the `namespace` field). - 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. - tools: Vec, - }, + 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, } -/// Element type accepted inside a [`ResponseTool::Namespace`]'s `tools` array. +/// 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 diff --git a/crates/protocols/tests/responses.rs b/crates/protocols/tests/responses.rs index 1490ba581a..c97f101292 100644 --- a/crates/protocols/tests/responses.rs +++ b/crates/protocols/tests/responses.rs @@ -1484,15 +1484,11 @@ fn test_namespace_tool_with_function_round_trip() { let tool: ResponseTool = serde_json::from_value(payload.clone()) .expect("namespace tool with function element should deserialize"); match &tool { - ResponseTool::Namespace { - description, - name, - tools, - } => { - assert_eq!(name, "sql"); - assert_eq!(description, "Tools for interacting with the warehouse"); - assert_eq!(tools.len(), 1); - match &tools[0] { + 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)); @@ -1531,9 +1527,9 @@ fn test_namespace_tool_with_custom_text_format_round_trip() { let tool: ResponseTool = serde_json::from_value(payload.clone()) .expect("namespace tool with custom/text element should deserialize"); match &tool { - ResponseTool::Namespace { tools, .. } => { - assert_eq!(tools.len(), 1); - match &tools[0] { + 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))); @@ -1576,7 +1572,7 @@ fn test_namespace_tool_with_custom_grammar_format_round_trip() { let tool: ResponseTool = serde_json::from_value(payload.clone()) .expect("namespace tool with custom/grammar element should deserialize"); match &tool { - ResponseTool::Namespace { tools, .. } => match &tools[0] { + ResponseTool::Namespace(def) => match &def.tools[0] { NamespaceTool::Custom(c) => match &c.format { Some(CustomToolInputFormat::Grammar(g)) => { assert_eq!(g.definition, "start: NUMBER"); @@ -1632,12 +1628,12 @@ fn test_namespace_tool_mixed_elements_round_trip() { let tool: ResponseTool = serde_json::from_value(payload.clone()) .expect("namespace tool with mixed elements should deserialize"); match &tool { - ResponseTool::Namespace { tools, .. } => { - assert_eq!(tools.len(), 2); + ResponseTool::Namespace(def) => { + assert_eq!(def.tools.len(), 2); assert!( - matches!(&tools[0], NamespaceTool::Function(ft) if ft.function.name == "read_file") + matches!(&def.tools[0], NamespaceTool::Function(ft) if ft.function.name == "read_file") ); - assert!(matches!(&tools[1], NamespaceTool::Custom(c) if c.name == "write_file")); + assert!(matches!(&def.tools[1], NamespaceTool::Custom(c) if c.name == "write_file")); } other => panic!("expected ResponseTool::Namespace, got {other:?}"), } @@ -1646,6 +1642,53 @@ fn test_namespace_tool_mixed_elements_round_trip() { assert_eq!(serialized, payload); } +#[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::(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::(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!({ diff --git a/model_gateway/src/routers/grpc/harmony/builder.rs b/model_gateway/src/routers/grpc/harmony/builder.rs index 2d0d302879..05ad68ce48 100644 --- a/model_gateway/src/routers/grpc/harmony/builder.rs +++ b/model_gateway/src/routers/grpc/harmony/builder.rs @@ -441,7 +441,7 @@ impl HarmonyBuilder { ResponseTool::Computer => "computer", ResponseTool::ComputerUsePreview(_) => "computer_use_preview", ResponseTool::Custom(_) => "custom", - ResponseTool::Namespace { .. } => "namespace", + ResponseTool::Namespace(_) => "namespace", }) .collect() }) diff --git a/model_gateway/src/routers/openai/responses/utils.rs b/model_gateway/src/routers/openai/responses/utils.rs index ffe1cab63a..78c9a3b2fd 100644 --- a/model_gateway/src/routers/openai/responses/utils.rs +++ b/model_gateway/src/routers/openai/responses/utils.rs @@ -255,7 +255,7 @@ pub(super) fn response_tool_to_value(tool: &ResponseTool) -> Option { // 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::Namespace(_) => serde_json::to_value(tool).ok(), ResponseTool::Function(_) => None, } }