add(openrouter): responses factory and reasoning-replay test coverage

Author: Tom-Ryder

Sources/AgentRunKit/Documentation.docc/Articles/LLMProviders.md

@@ -67,6 +67,8 @@ let client = OpenAIClient.openRouter(
 
 `OpenAIClient.openRouter(...)` pins ``OpenAIChatProfile/openRouter`` and defaults ``OpenAIChatAssistantReplayProfile`` to `.openRouterReasoningDetails`.
 
+Reasoning replay is best-effort. Some models return no `reasoning_details` on a given turn (for example GPT-class models routed through Chat Completions, which expose replayable reasoning only through the Responses API). When that happens the assistant turn carries no replayable reasoning and `reasoning_details` is absent from the next request. A workflow that requires replayable reasoning continuity can detect this by inspecting the reasoning details on the returned assistant message, such as the last assistant entry in ``AgentResult/history``.
+
 Together's preserved-thinking replay depends on a provider-specific mode (`clear_thinking`) not yet modeled by the client, so it remains conservative in this release. For first-party OpenAI reasoning continuity, and for Responses-native OpenRouter models such as xAI Grok, use ``ResponsesAPIClient`` instead. See `Targeting OpenRouter with ResponsesAPIClient` below.
 
 ## ResponsesAPIClient vs OpenAIClient
@@ -75,16 +77,14 @@ Together's preserved-thinking replay depends on a provider-specific mode (`clear
 
 ### Targeting OpenRouter with ResponsesAPIClient
 
-``ResponsesAPIClient`` is not locked to OpenAI. It accepts any base URL and works with OpenRouter's `/v1/responses` endpoint for models that OpenRouter routes through the Responses protocol. Point it at `OpenAIClient.openRouterBaseURL`:
+``ResponsesAPIClient`` is not locked to OpenAI. It accepts any base URL and works with OpenRouter's `/v1/responses` endpoint for models that OpenRouter routes through the Responses protocol. The `ResponsesAPIClient.openRouter(...)` factory pins ``ResponsesAPIClient/openRouterBaseURL`` and `store: false`:
 
 ```swift
-let client = ResponsesAPIClient(
+let client = ResponsesAPIClient.openRouter(
     apiKey: "sk-or-...",
     model: "x-ai/grok-4",
     maxOutputTokens: 4096,
-    baseURL: OpenAIClient.openRouterBaseURL,
-    reasoningConfig: .high,
-    store: false
+    reasoningConfig: .high
 )
 ```
 
@@ -93,7 +93,7 @@ Prefer ``ResponsesAPIClient`` over ``OpenAIClient`` on OpenRouter when:
 - The target model is Responses-API-native rather than Chat-Completions-native.
 - Provider-native reasoning continuity depends on preserving full Responses output items across turns.
 
-xAI Grok models are the canonical case. Grok returns encrypted reasoning artifacts as Responses output items, and ``ResponsesAPIClient`` preserves those items in ``AssistantContinuity`` for lossless replay on the next turn. ``OpenAIClient`` with `.openRouterReasoningDetails` flattens reasoning back to Chat Completions `reasoning_details`, which is the right contract for Chat-Completions-native OpenRouter models but not for Responses-native Grok. Set `store: false` on ``ResponsesAPIClient`` when targeting OpenRouter: this makes the client request `reasoning.encrypted_content` and send full history on every call, and it disables `previous_response_id` continuation, which matches OpenRouter's stateless Responses routing.
+xAI Grok models are the canonical case. Grok returns encrypted reasoning artifacts as Responses output items, and ``ResponsesAPIClient`` preserves those items in ``AssistantContinuity`` for lossless replay on the next turn. ``OpenAIClient`` with `.openRouterReasoningDetails` flattens reasoning back to Chat Completions `reasoning_details`, which is the right contract for Chat-Completions-native OpenRouter models but not for Responses-native Grok. The `openRouter(...)` factory sets `store: false`: this makes the client request `reasoning.encrypted_content` and send full history on every call, and it disables `previous_response_id` continuation, which matches OpenRouter's stateless Responses routing.
 
 ``OpenAIClient`` remains the correct Chat Completions transport for OpenRouter models that are not Responses-native. The two clients are independent paths, not substitutes: pick the one the target model speaks.
 

Sources/AgentRunKit/LLM/Providers/Responses/ResponsesAPIClient.swift

@@ -355,4 +355,24 @@ public extension ResponsesAPIClient {
         URL(validStaticString: "https://api.openai.com/v1")
     nonisolated static let chatGPTBaseURL =
         URL(validStaticString: "https://chatgpt.com/backend-api/codex")
+    nonisolated static let openRouterBaseURL =
+        URL(validStaticString: "https://openrouter.ai/api/v1")
+
+    static func openRouter(
+        apiKey: String,
+        model: String? = nil,
+        maxOutputTokens: Int? = nil,
+        contextWindowSize: Int? = nil,
+        reasoningConfig: ReasoningConfig? = nil
+    ) -> ResponsesAPIClient {
+        ResponsesAPIClient(
+            apiKey: apiKey,
+            model: model,
+            maxOutputTokens: maxOutputTokens,
+            contextWindowSize: contextWindowSize,
+            baseURL: openRouterBaseURL,
+            reasoningConfig: reasoningConfig,
+            store: false
+        )
+    }
 }

Tests/AgentRunKitTests/LLM/OpenAIChat/OpenAIClientStreamingTests.swift

@@ -0,0 +1,111 @@
+@testable import AgentRunKit
+import Foundation
+import Testing
+
+struct OpenAIChatStreamingReasoningTests {
+    private func makeClient(baseURL: URL, session: URLSession) -> OpenAIClient {
+        OpenAIClient(
+            apiKey: "test-key",
+            model: "anthropic/claude-opus-4.8",
+            baseURL: baseURL,
+            session: session,
+            assistantReplayProfile: .openRouterReasoningDetails
+        )
+    }
+
+    private func sseLine(_ json: String) -> String {
+        "data: \(json)"
+    }
+
+    private func reasoningEvent(_ detail: String) -> String {
+        sseLine(#"{"choices":[{"index":0,"delta":{"reasoning_details":[\#(detail)]}}]}"#)
+    }
+
+    private func reasoningDetailsStreamBody() -> Data {
+        let hello = #"{"type":"reasoning.text","format":"anthropic-claude-v1","index":0,"text":"Hello"}"#
+        let world = #"{"type":"reasoning.text","format":"anthropic-claude-v1","index":0,"text":" world"}"#
+        let signature = #"{"type":"reasoning.text","format":"anthropic-claude-v1","index":0,"signature":"sig-abc"}"#
+        let events = [
+            reasoningEvent(hello),
+            reasoningEvent(world),
+            reasoningEvent(signature),
+            sseLine(#"{"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}"#),
+        ]
+        return Data((events.joined(separator: "\n\n") + "\n\ndata: [DONE]\n\n").utf8)
+    }
+
+    @Test
+    func streamingReasoningDetailDeltasDecodedFromBytes() async throws {
+        let session = URLSession(configuration: StreamingTestURLProtocol.configuration())
+        defer { session.invalidateAndCancel() }
+        let client = try makeClient(
+            baseURL: #require(URL(string: "https://openrouter-reasoning-deltas.test/v1")),
+            session: session
+        )
+        let request = try client.buildRequest(messages: [.user("Hi")], tools: [], stream: true)
+        let requestURL = try #require(client.buildURLRequest(request).url)
+        StreamingTestURLProtocol.register(url: requestURL, body: reasoningDetailsStreamBody())
+        defer { StreamingTestURLProtocol.unregister(url: requestURL) }
+
+        let (deltas, error) = await collectStreamResult(
+            client.stream(messages: [.user("Hi")], tools: [], requestContext: nil)
+        )
+        #expect(error == nil)
+
+        let reasoningDeltas = deltas.compactMap { delta -> [JSONValue]? in
+            guard case let .reasoningDetails(details) = delta else { return nil }
+            return details
+        }
+        #expect(reasoningDeltas.count == 3)
+        #expect(reasoningDeltas.first == [.object([
+            "type": .string("reasoning.text"),
+            "format": .string("anthropic-claude-v1"),
+            "index": .int(0),
+            "text": .string("Hello"),
+        ])])
+        #expect(reasoningDeltas.last == [.object([
+            "type": .string("reasoning.text"),
+            "format": .string("anthropic-claude-v1"),
+            "index": .int(0),
+            "signature": .string("sig-abc"),
+        ])])
+    }
+
+    @Test
+    func streamingReasoningDetailsConsolidateIntoSingleBlock() async throws {
+        let session = URLSession(configuration: StreamingTestURLProtocol.configuration())
+        defer { session.invalidateAndCancel() }
+        let client = try makeClient(
+            baseURL: #require(URL(string: "https://openrouter-reasoning-merge.test/v1")),
+            session: session
+        )
+        let request = try client.buildRequest(messages: [.user("Hi")], tools: [], stream: true)
+        let requestURL = try #require(client.buildURLRequest(request).url)
+        StreamingTestURLProtocol.register(url: requestURL, body: reasoningDetailsStreamBody())
+        defer { StreamingTestURLProtocol.unregister(url: requestURL) }
+
+        let processor = StreamProcessor(
+            client: client,
+            toolDefinitions: [],
+            policy: .chat,
+            eventFactory: StreamEventFactory(sessionID: nil, runID: nil, origin: .live)
+        )
+        let (_, continuation) = AsyncThrowingStream<StreamEvent, Error>.makeStream()
+        var totalUsage = TokenUsage()
+        let iteration = try await processor.process(
+            messages: [.user("Hi")],
+            totalUsage: &totalUsage,
+            continuation: continuation
+        )
+
+        let details = try #require(iteration.toAssistantMessage().reasoningDetails)
+        #expect(details.count == 1)
+        #expect(details[0] == .object([
+            "type": .string("reasoning.text"),
+            "format": .string("anthropic-claude-v1"),
+            "index": .int(0),
+            "text": .string("Hello world"),
+            "signature": .string("sig-abc"),
+        ]))
+    }
+}

Tests/AgentRunKitTests/LLM/OpenAIChat/OpenAIReplayProfileTests.swift

@@ -214,6 +214,46 @@ struct ReasoningMultiTurnTests {
         let jsonToolCalls = msg?["tool_calls"] as? [[String: Any]]
         #expect(jsonToolCalls?.count == 1)
     }
+
+    @Test
+    func openRouterProfileEmitsReasoningDetailsAlongsideToolCalls() throws {
+        let details: [JSONValue] = [
+            .object([
+                "type": .string("reasoning.text"),
+                "format": .string("anthropic-claude-v1"),
+                "index": .int(0),
+                "text": .string("Let me check the weather"),
+                "signature": .string("sig-abc"),
+            ]),
+        ]
+        let toolCall = ToolCall(id: "call_123", name: "get_weather", arguments: "{\"city\":\"NYC\"}")
+        let assistantMsg = AssistantMessage(
+            content: "Checking",
+            toolCalls: [toolCall],
+            reasoningDetails: details
+        )
+        let client = OpenAIClient(
+            apiKey: "test-key",
+            model: "test/model",
+            baseURL: OpenAIClient.openRouterBaseURL,
+            assistantReplayProfile: .openRouterReasoningDetails
+        )
+        let messages: [ChatMessage] = [.assistant(assistantMsg)]
+        let request = try client.buildRequest(messages: messages, tools: [])
+
+        let data = try JSONEncoder().encode(request)
+        let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
+
+        let jsonMessages = json?["messages"] as? [[String: Any]]
+        let msg = jsonMessages?[0]
+        let encodedDetails = msg?["reasoning_details"] as? [[String: Any]]
+        #expect(encodedDetails?.count == 1)
+        #expect(encodedDetails?[0]["type"] as? String == "reasoning.text")
+        #expect(encodedDetails?[0]["signature"] as? String == "sig-abc")
+        let jsonToolCalls = msg?["tool_calls"] as? [[String: Any]]
+        #expect(jsonToolCalls?.count == 1)
+        #expect(jsonToolCalls?[0]["id"] as? String == "call_123")
+    }
 }
 
 struct ReplayProfileDefaultTests {

Tests/AgentRunKitTests/LLM/Responses/ResponsesAPIClientTests.swift

@@ -17,6 +17,7 @@ struct ResponsesRequestSerializationTests {
     func baseURLConstantsExposeOpenAIAndChatGPTEndpoints() {
         #expect(ResponsesAPIClient.openAIBaseURL.absoluteString == "https://api.openai.com/v1")
         #expect(ResponsesAPIClient.chatGPTBaseURL.absoluteString == "https://chatgpt.com/backend-api/codex")
+        #expect(ResponsesAPIClient.openRouterBaseURL.absoluteString == "https://openrouter.ai/api/v1")
     }
 
     @Test

Tests/AgentRunKitTests/LLM/Responses/ResponsesOpenRouterReplayTests.swift

@@ -0,0 +1,65 @@
+@testable import AgentRunKit
+import Foundation
+import Testing
+
+struct ResponsesOpenRouterReplayTests {
+    @Test
+    func openRouterFactoryTargetsStatelessEncryptedReasoning() async throws {
+        let client = ResponsesAPIClient.openRouter(apiKey: "sk-or-test", model: "x-ai/grok-4")
+        let request = try await client.buildRequest(messages: [.user("Hi")], tools: [])
+        let urlRequest = try await client.buildURLRequest(request)
+        #expect(urlRequest.url?.absoluteString == "https://openrouter.ai/api/v1/responses")
+
+        let json = try encodeRequest(request)
+        #expect(json["store"] as? Bool == false)
+        #expect(json["include"] as? [String] == ["reasoning.encrypted_content"])
+    }
+
+    @Test
+    func encryptedContentReasoningSurvivesContinuityReplay() async throws {
+        let blob = "gAAAAABencrypted-reasoning-payload-1234567890=="
+        let json = """
+        {
+            "id": "resp_enc",
+            "status": "completed",
+            "output": [
+                {
+                    "type": "reasoning",
+                    "id": "rs_enc_001",
+                    "summary": [],
+                    "encrypted_content": "\(blob)"
+                },
+                {
+                    "type": "message",
+                    "id": "msg_enc_001",
+                    "status": "completed",
+                    "role": "assistant",
+                    "content": [{"type": "output_text", "text": "The answer is 42."}]
+                }
+            ],
+            "usage": {"input_tokens": 10, "output_tokens": 5}
+        }
+        """
+        let client = ResponsesAPIClient.openRouter(apiKey: "sk-or-test", model: "x-ai/grok-4")
+        let response = try await client.decodeResponse(Data(json.utf8))
+        let message = await client.parseResponse(response)
+
+        guard case let .object(payload) = message.continuity?.payload,
+              case let .array(output) = payload["output"],
+              case let .object(reasoning) = output.first
+        else {
+            Issue.record("Expected Responses continuity with a reasoning output item")
+            return
+        }
+        #expect(reasoning["encrypted_content"] == .string(blob))
+
+        let request = try await client.buildRequest(messages: [.assistant(message)], tools: [])
+        let encoded = try encodeRequest(request)
+        let input = try #require(encoded["input"] as? [[String: Any]])
+        #expect(input[0]["type"] as? String == "reasoning")
+        #expect(input[0]["id"] as? String == "rs_enc_001")
+        #expect(input[0]["encrypted_content"] as? String == blob)
+        #expect(input[1]["type"] as? String == "message")
+        #expect(input[1]["id"] as? String == "msg_enc_001")
+    }
+}