Refactor: Centralize multi-step tool loop into StepLoop; gateways become single-turn adapters

[vinitkadam03]

Summary

This PR extracts the multi-step tool loop from individual gateways into a central StepLoop class, making gateways thin single-turn adapters. The net result is ~3,600 lines of duplicated orchestration code replaced by ~850 lines of shared logic and leaner gateways.

• StepLoop (src/Gateway/StepLoop.php) — new central class that owns the multi-step tool loop (LLM call → tool execution → re-prompt) for both generate and stream flows. Named after the Step DTO it produces on each iteration.
• SingleTurnResponse (src/Gateway/SingleTurnResponse.php) — lean DTO representing one LLM turn, returned by all gateways. Lives under Laravel\Ai\Gateway (not Responses) because it's an internal gateway↔loop contract, never exposed to userland.
• All nine gateways (OpenAI, Anthropic, Groq, Gemini, Mistral, xAI, DeepSeek, Ollama, OpenRouter, plus the Prism adapter) simplified to single-turn adapters — each gateway's ParsesTextResponses and HandlesTextStreaming traits drop recursive multi-step logic entirely.
• previous_response_id threading for OpenAI / xAI — StepLoop passes an opaque provider response ID between turns so providers that support stateful continuation can use it instead of replaying the full conversation.
• providerExecuted flag on ToolCall — Anthropic's server_tool_use blocks (web_search, web_fetch, code_execution, advisor) are now tagged when parsed and re-emitted as server_tool_use on replay. The step loop skips local execution for them via the existing findTool() → null path.
• providerOptions correctly persisted in continuation requests (addresses the fix from Fix OpenAI strict tool parameters and persist providerOptions in tool loops #340).

A note on scope

This is a large architectural change and my first PR to this repo, so understandably there may not be trust built up yet. I'm completely fine with this serving as a reference implementation that maintainers can review, cherry-pick from, or rewrite as they see fit.

I raised the proposal in #347 after noticing the same orchestration logic being duplicated across new gateway PRs (#309, #311). @pushpak1300 mentioned wanting to get migrated off Prism first before making arch changes — this PR is compatible with that direction since it doesn't remove Prism, it just makes PrismGateway a thinner adapter with withMaxSteps(1). I've also been contributing to Prism and working on client-executed tools and tool approval there (prism-php/prism#932), which is what originally motivated this refactor — those features would only need to be implemented once in the step loop rather than in every gateway.

Happy to iterate on any feedback.

Note: I have not been able to run the full integration test suite as I don't have API keys for all providers. The unit tests and feature tests with HTTP fakes all pass. Would appreciate the maintainers running the integration suite against this branch.

Motivation

Before this change, every gateway independently implemented the same recursive multi-step tool orchestration — ParsesTextResponses had processResponse → continueWithToolResults → processResponse loops, and HandlesTextStreaming had parallel handleStreamingToolCalls → processTextStream recursion. This meant:

• Every new gateway (Anthropic Add direct Anthropic gateway for Messages API #309, Groq Add Groq gateway for Chat Completions API #311, DeepSeek Migrate DeepSeek provider to a native gateway #399, Ollama, OpenRouter) had to reimplement ~200–400 lines of identical orchestration logic.
• Cross-cutting concerns (telemetry, tool approval, rate limiting around tool calls) would need to be added in every gateway.
• Bug fixes to the tool loop required changes in every gateway.
• Provider-specific behaviors like Anthropic's server_tool_use replay, OpenAI's previous_response_id continuation, or Anthropic's reasoning-signature pass-through had to be thought through in each gateway's bespoke loop.

With orchestration centralized, a new gateway only needs to implement single-turn LLM communication — one generateText() and one streamText() method. The surface area becomes small enough that providers could realistically be maintained as community packages: anyone could add support for a new LLM by implementing the single-turn contract without understanding or replicating the orchestration logic.

Changes

Area	What changed
TextGateway contract	generateText() returns SingleTurnResponse, accepts ?string $previousResponseId; onToolInvocation() removed
StepLoop (new)	Owns multi-step tool loop, usage aggregation, structured output handling, previousResponseId threading, streaming path
SingleTurnResponse (new)	DTO returned by every gateway — text, toolCalls, finishReason, usage, meta, structured, responseId
ToolCall	New providerExecuted: bool flag for server-side tool invocations (Anthropic server_tool_use)
OpenAiGateway	Single-turn; ParsesTextResponses drops ~270 lines; BuildsTextRequests handles previous_response_id
AnthropicGateway	Single-turn; ParsesTextResponses drops ~260 lines; HandlesTextStreaming drops ~220 lines; providerExecuted re-emits server_tool_use blocks on replay
GroqGateway	Single-turn; ParsesTextResponses drops ~280 lines; HandlesTextStreaming drops ~190 lines
GeminiGateway	Single-turn; ParsesTextResponses drops ~210 lines; HandlesTextStreaming drops ~150 lines
MistralGateway	Single-turn; ParsesTextResponses drops ~250 lines; HandlesTextStreaming drops ~160 lines
XaiGateway	Single-turn; ParsesTextResponses drops ~250 lines; BuildsTextRequests handles previous_response_id
DeepSeekGateway	Ported to single-turn contract
OllamaGateway	Ported to single-turn. Behavioral quirk preserved: force FinishReason::ToolCalls when tool_calls are populated regardless of done_reason, since Ollama can return "stop" alongside tool calls
OpenRouterGateway	Ported to single-turn. Behavioral quirk preserved: finish_reason: "error" with inline error payload → emit stream Error event
PrismGateway	Single-turn; delegates to Prism with withMaxSteps(1)
FakeTextGateway	Updated to match new contract
GeneratesText / StreamsText	Instantiate StepLoop and delegate; tool-invocation events wired via callbacks
StreamEnd	Gains ?string $responseId for provider ID propagation through the streaming path

[vinitkadam03]

Anthropic's thinking blocks include a cryptographic signature that must be replayed verbatim in tool use continuations. The old gateway preserved this by replaying raw API content. The orchestrator round-trips through typed DTOs, so the signature needs to be explicitly modeled.

Added reasoningSignature to ToolCall, following the existing reasoningId/reasoningSummary pattern. The Anthropic gateway now extracts thinking text + signature and attaches them to tool calls. MapsMessages emits the full thinking block with signature on replay.

Also fixed a pre-existing gap in DatabaseConversationStore — reasoningId, reasoningSummary, and the new reasoningSignature were being written to the DB but never read back on load.

Longer term, reasoning could be modeled as standalone content parts on AssistantMessage with a provider metadata bag - keeping core types generic while letting each provider carry opaque data like signatures through the round-trip. Happy to take that on as a follow-up.

[vinitkadam03]

Just rebased over #409. Thought it was a nice example of what this refactor helps with: that fix needed changes in BuildsTextRequests, continueWithToolResults, and handleStreamingToolCalls within each affected gateway. With the centralized step loop, only BuildsTextRequests needs the fix per gateway since continuation just calls the same request builder again. Fewer places to patch within each gateway for future fixes like this one 🙂