fix(api): SP-Ω recovery · land #72+#73+#74 (stack-merge orphan rescue)

[hizrianraz]

Recovery PR for the stacked-merge anti-pattern: SP-12 merge sequence ran gh pr merge --auto on stacked PRs faster than GitHub's auto-retarget could fire, so #72 (SP-2 streaming) + #73 (SP-4 capture) + #74 (SP-4 dial) all merged into their stacked bases (now orphan branches), NOT main.

This PR brings the orphan-branch content (feat/ain271-streaming-tooluse, which contains the #72+#73+#74 squash-merge commits) directly to main as a single squash commit.

After this lands, #75/#76/#77/#78 (still based on feat/ain271-streaming-tooluse) need their base retargeted to main, then merged individually.

---

Note

High Risk
Expands core inference surface with SSE streaming and tool-calling semantics, and changes routing policy resolution (even if gated), which can affect client behavior and backend dispatch paths. Also adds new invariants/tests around §16 capture that may fail if existing edge paths behave differently than expected.

Overview
Adds SP-2 streaming + tool-use across adapters and the Anthropic-compat /v1/messages surface: providers now accept tools/tool_choice, return structured content_blocks, and expose native SSE streaming via normalized StreamEvent parsing for Anthropic and OpenAI-compat backends.

Updates /v1/messages to support stream=true (returns text/event-stream with Anthropic-shaped frames and x-ainfera-stream-mode), and to pass through tool definitions while surfacing backend tool responses as polymorphic content[] blocks; unsupported backends raise ToolsNotSupportedError mapped to a structured 422.

Introduces SP-4 PR-A capture invariant guards (new capture_invariant module + integration/unit tests) to ensure every routed dispatch writes exactly one routing_outcomes row while vendor passthrough writes zero, and adds SP-4 PR-B routing_preference dial in resolve_policy (accepted on the wire, gated by AINFERA_ROUTING_PREFERENCE_LIVE, and non-overriding of explicit min_quality).

^{Reviewed by Cursor Bugbot for commit 0d33b78. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stream omits billing errors

Medium Severity

stream_messages only catches NoCandidateError and AllCandidatesFailedError around dispatch_with_brain. Cap, insufficient-funds, and other terminal errors from the non-streaming path propagate uncaught from the SSE generator, yielding 500s instead of the 402/409 responses clients get when stream=false.

 

^{Reviewed by Cursor Bugbot for commit 1fd4e23. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

^{Reviewed by Cursor Bugbot for commit 0d33b78. Configure here.}

[cursor]

Tool blocks dropped at inference

Medium Severity

The shim now returns inf_resp.content_blocks, but post_inference still builds blocks only from normalize_content(result.content). Adapter content_blocks (including tool_use) on DispatchResult are never copied onto InferenceResponse, so tool invocations never appear in the Anthropic JSON envelope.

 

^{Reviewed by Cursor Bugbot for commit 0d33b78. Configure here.}

[cursor]

Stream masks routing failures

Medium Severity

When stream=true, NoCandidateError and AllCandidatesFailedError yield HTTP 200 with an empty Anthropic SSE sequence and stop_reason end_turn. The non-stream path returns 422/503 with structured errors, so streaming clients can treat a failed route as a successful empty assistant message.

 

^{Reviewed by Cursor Bugbot for commit 0d33b78. Configure here.}