feat: tool types + registry + ToolHandler trait (PR A)

[ashwing]

Summary

Implements PR A from the tool framework design:

• ResponsesTool — replaces pub type ResponsesTool = FunctionTool alias with a #[serde(tag = "type")] tagged enum covering all five Responses API tool types (function, mcp, web_search_preview, file_search, code_interpreter). Wire-compatible: existing {"type":"function",...} requests deserialize unchanged. Marked #[non_exhaustive] for future API additions.
• ToolRegistry — request-scoped HashMap<name → ToolEntry> built from RequestPayload.tools + any server-discovered tools. Provides gateway_owned / client_owned split for post-inference dispatch routing (PR B).
• ToolHandler trait — validate / discover / normalize / execute lifecycle. Send + Sync for Arc<dyn ToolHandler>. Default discover() is a no-op; execute() must be implemented per handler type.
• FunctionHandler — trivial ToolHandler impl for type: "function" tools. Normalizes to FunctionTool, never gateway-executes (client-owned).
• normalize pipeline — ResponsesTool::to_function_tool() wired into RequestPayload::to_upstream_request(). vLLM always receives Vec<FunctionTool>, never raw ResponsesTool variants. Function tools pass through unchanged; gateway-managed types (mcp, web_search_preview, file_search, code_interpreter) are dropped with a tracing::debug! until their handlers land in PR B/C.
• From<ToolOutput> for FunctionToolResultMessage — zero-friction conversion for PR B's dispatch loop.
• McpToolParam includes headers: Option<HashMap<String,String>> for per-server auth forwarding.

What vLLM sees after this PR

Client sends	vLLM receives
{"type":"function","name":"foo",...}	{"type":"function","name":"foo",...} ✅ unchanged
{"type":"mcp","server_label":"db",...}	nothing — dropped until PR C
{"type":"web_search_preview"}	nothing — dropped until PR C

Gateway-type tools are parsed, validated, and stored in ResponseMetadata.effective_tools for rehydration across turns — they just don't reach vLLM until real normalize() implementations land.

No execution logic in this PR: no dispatch_tools, no LoopDecision, no changes to engine.rs / rehydrate.rs / persist.rs.

Depends on: #64 (io types refactor — merged). Unblocks: PR B (dispatch), PR C (MCP handler), CustomCodexTool (#68).

Test Plan

cargo build --workspace     # 0 errors
cargo clippy --workspace --all-targets -- -D warnings  # 0 warnings
cargo test --workspace      # 246 tests pass

Key new tests in types::tools::tests:

• All 5 ResponsesTool variants round-trip through serde
• ToolRegistry lookup, gateway_owned / client_owned split, allowed_tools filtering, duplicate-name warning, empty-name skip
• FunctionHandler::validate() rejects empty names
• to_upstream_request() with mixed tools — only function tool reaches vLLM
• All-gateway tools → tools: null (empty array never sent to vLLM)

[maralbahari]

@ashwing thank you. overall tools/ module looks well-structured. I have added some inline comments and it would be great to make sure the serde shapes and normalization logic are validated against real wire payloads before we merge.

We already have multi-turn tool call cassettes at crates/agentic-core/tests/cassettes/tool_calls/multi_turn/ responses_tool_calls_3turn.yaml, responses_tool_calls_5turn.yaml, and responses_tool_calls_parallel.yaml. Each turn's request.body.tools is the exact JSON the gateway receives, so parsing it into Vec<ResponsesTool> is the same validation as a real request without needing any running server.

The existing accumulator_cassette_test.rs already has the load_turn_cassette_from helper and Turn struct that deserializes request bodies as serde_json::Value. you can reuse that infrastructure directly in a new tool_normalization_test.rs.

Specifically the tests that cover:

serde_json::from_value::<Vec<ResponsesTool>>(request.body["tools"]) parses without error for every turn across all three cassettes
Each parsed tool normalizes correctly via to_function_tool(). The Function variants produce a FunctionTool with the right name/type, non-function variants return None
ToolRegistry::build on the cassette tools produces the expected entries and lookup by name works
Full round-trip: deserialize request.body into RequestPayload, call to_upstream_request(), assert the upstream tools field only contains FunctionTool entries and none of the gateway-only types leak through

Regarding MCP related code like DiscoveredTool, the discover() method, and the MCP branch in ToolRegistry::build, please don't add stub functions we can't test. discover() always returns Ok(vec![]) and DiscoveredTool is never populated, so this is dead code we can't validate.

since MCP is not in scope for this PR, please remove DiscoveredTool, the discover() method from ToolHandler, and the discovered parameter from normalize(). We can add MCP support once we have a way to test it.

[ashwing]

Rebased on main after #79 and #81 merged. Squashed into a single clean commit — conflicts resolved, all 264 tests pass.

[ashwing]

Done across all commits on this rebase. Specifically:

1. Section dividers — stripped from all files.

2. From<&FunctionToolParam> for normalization — replaced the manual Value::get() extraction path with impl From<&FunctionToolParam> for FunctionTool. FunctionHandler::normalize now deserializes the stored &Value back into FunctionToolParam and calls FunctionTool::from(&p) — single conversion path, no divergence risk.

3. types/ vs tool/ — agreed on the distinction. Wire shapes (ResponsesTool, param structs, NonEmptyToolName) stay in types/tools/. The behavioral layer (ToolRegistry, ToolHandler, FunctionHandler, normalize pipeline) moved to src/tool/. types/tools/mod.rs doc comment now explicitly states it contains only serde shapes.

4. Cassette tests + MCP stubs removed — added tool_normalization_test.rs with 12 tests against the openai 3turn/5turn/parallel cassettes covering: Vec<ResponsesTool> parse, to_function_tool() normalization, ToolRegistry::build lookup, and full RequestPayload round-trip. DiscoveredTool, discover(), and the discovered param from normalize() all removed — no dead MCP code.

Also fixed two issues caught during review: ToolOutput missing #[derive(Debug)], and an MCP registry key mismatch (server_label was used as registry key but gateway_owned/client_owned look up by tool name — MCP entries now skip with a debug log until PR C adds real discovery).

Rebased on main after #79 and #81 — single clean commit, 264 tests pass.

[maralbahari]

@ashwing thank you for addressing the issue.
after giving more thoughts on the ToolHandler design there some issues worth fixing now.

Trait shape: execute() on FunctionHandler seems meaningless.

ToolHandler has three methods: validate, normalize, and execute. The first two make sense for every tool type. But execute does not: the whole point of a function tool is that the gateway does not execute it. So FunctionHandler::execute() can never do anything valid, and the implementation reflects this by always returning an error.

The problem is that the trait forces every future tool handler to implement execute(), even ones that are also client-owned. The trait's shape implies "all tools can be executed by the gateway," which is false.

A cleaner split would be two traits:

pub trait ToolHandler {
    fn tool_type(&self) -> ToolType;
    fn validate(&self, param: &Value) -> Result<(), ToolError>;
    fn normalize(&self, param: &Value) -> Vec<FunctionTool>;
}

pub trait GatewayExecutor: ToolHandler {
    fn execute(
        &self,
        tool_name: &str,
        arguments: &str,
        config: &Value,
    ) -> Pin<Box<dyn Future<Output = Result<ToolOutput, ToolError>> + Send + '_>>;
}

FunctionHandler implements only ToolHandler. Future handlers for WebSearch, CodeInterpreter, etc. implement both. The type system then makes it impossible to accidentally call execute() on a client-owned tool, rather than relying on a runtime error to catch it.

ToolRegistry::gateway_owned() and client_owned() already do this split correctly at the routing layer. The trait should reflect the same boundary so the compiler enforces it, not a panic at runtime.

[ashwing]

@maralbahari The original design had execute() on ToolHandler as a forward-looking decision — PR B's HandlerRegistry was going to dispatch to Arc<dyn ToolHandler> uniformly, treating every tool through the same interface. The intent was to keep the dispatch loop simple: iterate calls, call execute() on whatever handler the registry returns, let the handler decide what to do. FunctionHandler::execute() returning an error was a guard for the case where routing went wrong, not the expected path.

That said, your point stands — gateway_owned/client_owned already do the routing split at the registry level, so the executor in PR B will never call execute() on a function tool. The split is the right call: ToolHandler for all tools, GatewayExecutor for the ones the gateway actually runs.

Done. Split into:

• ToolHandler: tool_type, validate, normalize — every tool type implements this
• GatewayExecutor: ToolHandler + 'static: execute() — gateway-owned tools only

FunctionHandler now implements only ToolHandler. Added a compile-time assertion _assert_gateway_executor_dyn_compatible to lock in Arc<dyn GatewayExecutor> object safety for PR B.

Also applied NonEmptyToolName to FunctionToolParam.name — serde now rejects empty names at deserialization, eliminating the three divergent empty-name checks across registry::build, to_function_tool, and FunctionHandler::validate.

[maralbahari]

@ashwing Thanks. LGTM