feat(responses): unify tool dispatch under a single agentic-loop owner (#1046)

[leseb]

Summary

Makes openai_agentic_loop the single owner and sole parser of the Responses agentic loop, demoting openai_web_search, openai_mcp_dispatch, and openai_file_search_callout to execution-only dispatchers with no response phase, so one filter normalizes/accumulates/classifies every output item, publishes the single loop signal, and runs the one fallible terminal-buffered finalizer. File-search calls are carried by index (FileSearchAssignment) into a shared accumulated_output rather than copied, DispatchFailure is converted by the owner into a buffered JSON rejection or streaming SSE error frame, and a new mcp_classify module is the single source of truth for MCP disposition/approval while approval.rs keeps only the durable round-trip. MCP tool calls are exempted from max_tool_calls (built-ins only) while retaining their own per-round/concurrency caps, and mixed server/client function-call ownership fails closed with 502 before any external side effect.

Related issue

Refs #1046

Validation

• Unit tests — cargo test -p praxis-ai-apis (3362 passed, 0 failed)
• Integration or functional tests — updated openai_agentic_loop.rs, file_search_callout.rs, test_openai_responses_vllm.py
• make lint — clippy -D warnings + nightly fmt --check clean; make build clean

Checklist

• I reviewed every changed line and can explain the change.
• New capabilities include an example config and functional example test.
• User-facing behavior and generated documentation are updated.
• Performance-sensitive changes include appropriate benchmark or load-test evidence.
• Commits are signed and include a Signed-off-by trailer.

Breaking changes

Example config for the agentic loop is restructured (agentic-loop.yaml and the file-search example configs) to reflect the single-owner pipeline ordering; deployments that copied the prior per-tool response-phase wiring must adopt the owner-driven layout.

[franciscojavierarceo]

streamed local completions can return an empty 200 SSE body.

on every streaming IRR re-entry, openai_stream_events::arm clears ResponsesState.response_object at apis/src/openai/responses/stream_events/mod.rs:164-174. when a max_tool_calls rejection or approval-only round then completes before another upstream response, finish_deferred_local_response calls encode_local_completion at apis/src/openai/responses/agentic_loop/mod.rs:407-426. encode_local_completion returns None whenever that response object is no longer an object at apis/src/openai/responses/stream_events/mod.rs:1333-1343.

the client receives a 200 text/event-stream response without response.completed (and, when applicable, [DONE]), so a valid streamed approval or tool-limit response cannot complete reliably. we need to preserve a terminal response template or build one from the stable response id and accumulated output, and add a regression that exercises approval-only and tool-limit termination after a streaming IRR re-entry.

[leseb]

streamed local completions can return an empty 200 SSE body.

on every streaming IRR re-entry, openai_stream_events::arm clears ResponsesState.response_object at apis/src/openai/responses/stream_events/mod.rs:164-174. when a max_tool_calls rejection or approval-only round then completes before another upstream response, finish_deferred_local_response calls encode_local_completion at apis/src/openai/responses/agentic_loop/mod.rs:407-426. encode_local_completion returns None whenever that response object is no longer an object at apis/src/openai/responses/stream_events/mod.rs:1333-1343.

the client receives a 200 text/event-stream response without response.completed (and, when applicable, [DONE]), so a valid streamed approval or tool-limit response cannot complete reliably. we need to preserve a terminal response template or build one from the stable response id and accumulated output, and add a regression that exercises approval-only and tool-limit termination after a streaming IRR re-entry.

Fixed in 6395539. Thanks!

[franciscojavierarceo]

reviewed the current head, the preserved local streaming completions, agentic-loop ownership, targeted tests, and existing comments. no blocking issues found.