add(replay): gate openai assistant reasoning replay by explicit profile

Tom-Ryder · Tom-Ryder · commit 055e80f0b4b0 · 2026-04-03T21:54:39.000-07:00
diff --git a/Sources/AgentRunKit/Documentation.docc/AgentRunKit.md b/Sources/AgentRunKit/Documentation.docc/AgentRunKit.md
@@ -76,6 +76,7 @@ For a complete walkthrough, see <doc:GettingStarted>.
 - <doc:LLMProviders>
 - ``LLMClient``
 - ``OpenAIClient``
+- ``OpenAIChatAssistantReplayProfile``
 - ``AnthropicClient``
 - ``AnthropicReasoningOptions``
 - ``GeminiClient``
diff --git a/Sources/AgentRunKit/Documentation.docc/Articles/LLMProviders.md b/Sources/AgentRunKit/Documentation.docc/Articles/LLMProviders.md
@@ -39,6 +39,28 @@ Three clients preserve same-substrate continuity state, restoring provider-nativ
 
 Other clients (``OpenAIClient``, ``GeminiClient``) use semantic-only replay. History is reconstructed from the semantic fields, which is sufficient for the agent loop but does not preserve provider-specific turn metadata.
 
+### Assistant Reasoning Replay on Chat Completions
+
+``OpenAIClient`` parses reasoning fields (`reasoning`, `reasoning_content`, `reasoning_details`) from all provider responses. However, replaying those fields back onto later assistant turns is not universally safe across the diverse Chat Completions ecosystem.
+
+Outbound replay is controlled by ``OpenAIChatAssistantReplayProfile``, which defaults to `.conservative` (omit all assistant-local reasoning fields from requests). This is the correct default because first-party OpenAI routes reasoning continuity through the Responses API, and other providers have heterogeneous replay contracts.
+
+One opt-in profile is available:
+
+- `.openRouterReasoningDetails`: emits `reasoning_details` on assistant turns, matching OpenRouter's documented contract for preserving encrypted reasoning blocks across turns. Does not emit `reasoning_content`.
+
+```swift
+let client = OpenAIClient(
+    apiKey: "sk-or-...",
+    model: "anthropic/claude-sonnet-4",
+    baseURL: OpenAIClient.openRouterBaseURL,
+    reasoningConfig: .high,
+    assistantReplayProfile: .openRouterReasoningDetails
+)
+```
+
+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, use ``ResponsesAPIClient``.
+
 ## ResponsesAPIClient vs OpenAIClient
 
 Both connect to OpenAI. ``OpenAIClient`` uses the Chat Completions API, a stateless request/response protocol shared by many compatible providers (OpenRouter, Groq, Together, Ollama). ``ResponsesAPIClient`` uses the Responses API, which maintains server-side conversation state and supports delta requests that send only new messages since the last response.
diff --git a/Sources/AgentRunKit/LLM/OpenAIClient.swift b/Sources/AgentRunKit/LLM/OpenAIClient.swift
@@ -12,6 +12,7 @@ public struct OpenAIClient: LLMClient, Sendable {
     let session: URLSession
     let retryPolicy: RetryPolicy
     let reasoningConfig: ReasoningConfig?
+    let assistantReplayProfile: OpenAIChatAssistantReplayProfile
 
     public init(
         apiKey: String? = nil,
@@ -23,7 +24,8 @@ public struct OpenAIClient: LLMClient, Sendable {
         additionalHeaders: @Sendable @escaping () -> [String: String] = { [:] },
         session: URLSession = .shared,
         retryPolicy: RetryPolicy = .default,
-        reasoningConfig: ReasoningConfig? = nil
+        reasoningConfig: ReasoningConfig? = nil,
+        assistantReplayProfile: OpenAIChatAssistantReplayProfile = .conservative
     ) {
         self.apiKey = apiKey
         modelIdentifier = model
@@ -35,6 +37,7 @@ public struct OpenAIClient: LLMClient, Sendable {
         self.session = session
         self.retryPolicy = retryPolicy
         self.reasoningConfig = reasoningConfig
+        self.assistantReplayProfile = assistantReplayProfile
     }
 
     public func generate(
@@ -140,7 +143,7 @@ extension OpenAIClient {
         let tokenField = baseURL == OpenAIClient.openAIBaseURL ? "max_completion_tokens" : "max_tokens"
         return ChatCompletionRequest(
             model: modelIdentifier,
-            messages: messages.map(RequestMessage.init),
+            messages: messages.map { RequestMessage($0, replayProfile: assistantReplayProfile) },
             tools: tools.isEmpty ? nil : tools.map(RequestTool.init),
             toolChoice: tools.isEmpty ? nil : "auto",
             maxTokens: maxTokens,
@@ -328,7 +331,8 @@ public extension OpenAIClient {
         additionalHeaders: @Sendable @escaping () -> [String: String] = { [:] },
         session: URLSession = .shared,
         retryPolicy: RetryPolicy = .default,
-        reasoningConfig: ReasoningConfig? = nil
+        reasoningConfig: ReasoningConfig? = nil,
+        assistantReplayProfile: OpenAIChatAssistantReplayProfile = .conservative
     ) -> OpenAIClient {
         OpenAIClient(
             apiKey: nil,
@@ -340,7 +344,8 @@ public extension OpenAIClient {
             additionalHeaders: additionalHeaders,
             session: session,
             retryPolicy: retryPolicy,
-            reasoningConfig: reasoningConfig
+            reasoningConfig: reasoningConfig,
+            assistantReplayProfile: assistantReplayProfile
         )
     }
 }
diff --git a/Sources/AgentRunKit/LLM/OpenAIClientTypes.swift b/Sources/AgentRunKit/LLM/OpenAIClientTypes.swift
@@ -1,5 +1,20 @@
 import Foundation
 
+/// Controls which assistant-local reasoning fields are replayed onto outbound Chat Completions requests.
+public enum OpenAIChatAssistantReplayProfile: Sendable, Equatable {
+    case conservative
+    case openRouterReasoningDetails
+}
+
+extension OpenAIChatAssistantReplayProfile {
+    var emitsReasoningDetails: Bool {
+        switch self {
+        case .conservative: false
+        case .openRouterReasoningDetails: true
+        }
+    }
+}
+
 /// Per-request metadata and provider-specific parameters.
 public struct RequestContext: Sendable {
     public let extraFields: [String: JSONValue]
@@ -138,7 +153,7 @@ struct RequestMessage: Encodable {
         }
     }
 
-    init(_ message: ChatMessage) {
+    init(_ message: ChatMessage, replayProfile: OpenAIChatAssistantReplayProfile) {
         switch message {
         case let .system(text):
             role = "system"
@@ -170,8 +185,8 @@ struct RequestMessage: Encodable {
             toolCalls = msg.toolCalls.isEmpty ? nil : msg.toolCalls.map(RequestToolCall.init)
             toolCallId = nil
             name = nil
-            reasoningContent = msg.reasoning?.content
-            reasoningDetails = msg.reasoningDetails
+            reasoningContent = nil
+            reasoningDetails = replayProfile.emitsReasoningDetails ? msg.reasoningDetails : nil
         case let .tool(id, toolName, resultContent):
             role = "tool"
             content = .text(resultContent)
diff --git a/Tests/AgentRunKitTests/LLMClientTests.swift b/Tests/AgentRunKitTests/LLMClientTests.swift
@@ -662,162 +662,6 @@ struct ReasoningConfigTests {
     }
 }
 
-struct ReasoningMultiTurnTests {
-    @Test
-    func assistantMessageWithReasoningEncodes() throws {
-        let reasoning = ReasoningContent(content: "Let me think about this...")
-        let assistantMsg = AssistantMessage(content: "The answer is 42", reasoning: reasoning)
-        let client = OpenAIClient(
-            apiKey: "test-key",
-            model: "test/model",
-            baseURL: OpenAIClient.openRouterBaseURL
-        )
-        let messages: [ChatMessage] = [.assistant(assistantMsg)]
-        let request = client.buildRequest(messages: messages, tools: [])
-
-        let encoder = JSONEncoder()
-        let data = try encoder.encode(request)
-        let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
-
-        let jsonMessages = json?["messages"] as? [[String: Any]]
-        let msg = jsonMessages?[0]
-        #expect(msg?["role"] as? String == "assistant")
-        #expect(msg?["content"] as? String == "The answer is 42")
-        #expect(msg?["reasoning_content"] as? String == "Let me think about this...")
-    }
-
-    @Test
-    func assistantMessageWithReasoningDetailsEncodes() throws {
-        let details: [JSONValue] = [
-            .object([
-                "type": .string("reasoning.encrypted"),
-                "encrypted": .string("base64blob=="),
-                "id": .string("re_001")
-            ])
-        ]
-        let assistantMsg = AssistantMessage(content: "Result", reasoningDetails: details)
-        let client = OpenAIClient(
-            apiKey: "test-key",
-            model: "test/model",
-            baseURL: OpenAIClient.openRouterBaseURL
-        )
-        let messages: [ChatMessage] = [.assistant(assistantMsg)]
-        let request = client.buildRequest(messages: messages, tools: [])
-
-        let encoder = JSONEncoder()
-        let data = try encoder.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.encrypted")
-        #expect(encodedDetails?[0]["encrypted"] as? String == "base64blob==")
-        #expect(encodedDetails?[0]["id"] as? String == "re_001")
-    }
-
-    @Test
-    func assistantMessageWithoutReasoningDetailsOmitsField() throws {
-        let assistantMsg = AssistantMessage(content: "Simple")
-        let client = OpenAIClient(
-            apiKey: "test-key",
-            model: "test/model",
-            baseURL: OpenAIClient.openRouterBaseURL
-        )
-        let messages: [ChatMessage] = [.assistant(assistantMsg)]
-        let request = client.buildRequest(messages: messages, tools: [])
-
-        let encoder = JSONEncoder()
-        let data = try encoder.encode(request)
-        let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
-
-        let jsonMessages = json?["messages"] as? [[String: Any]]
-        let msg = jsonMessages?[0]
-        #expect(msg?["reasoning_details"] == nil)
-    }
-
-    @Test
-    func reasoningDetailsRoundTripPreservesSnakeCaseKeys() throws {
-        let details: [JSONValue] = [
-            .object([
-                "type": .string("reasoning.text"),
-                "reasoning_type": .string("chain_of_thought"),
-                "inner_data": .object(["nested_key": .string("value")])
-            ])
-        ]
-        let assistantMsg = AssistantMessage(content: "Result", reasoningDetails: details)
-        let client = OpenAIClient(
-            apiKey: "test-key",
-            model: "test/model",
-            baseURL: OpenAIClient.openRouterBaseURL
-        )
-        let messages: [ChatMessage] = [.assistant(assistantMsg)]
-        let request = client.buildRequest(messages: messages, tools: [])
-
-        let encoder = JSONEncoder()
-        let data = try encoder.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]]
-        let obj = encodedDetails?[0]
-        #expect(obj?["reasoning_type"] as? String == "chain_of_thought")
-        let inner = obj?["inner_data"] as? [String: Any]
-        #expect(inner?["nested_key"] as? String == "value")
-        #expect(obj?["reasoningType"] == nil, "snake_case keys must survive the round-trip unchanged")
-    }
-
-    @Test
-    func assistantMessageWithoutReasoningOmitsField() throws {
-        let assistantMsg = AssistantMessage(content: "The answer is 42")
-        let client = OpenAIClient(
-            apiKey: "test-key",
-            model: "test/model",
-            baseURL: OpenAIClient.openRouterBaseURL
-        )
-        let messages: [ChatMessage] = [.assistant(assistantMsg)]
-        let request = client.buildRequest(messages: messages, tools: [])
-
-        let encoder = JSONEncoder()
-        let data = try encoder.encode(request)
-        let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
-
-        let jsonMessages = json?["messages"] as? [[String: Any]]
-        let msg = jsonMessages?[0]
-        #expect(msg?["reasoning_content"] == nil)
-    }
-
-    @Test
-    func assistantMessageWithToolCallsAndReasoningEncodes() throws {
-        let reasoning = ReasoningContent(content: "I need to check the weather...")
-        let toolCall = ToolCall(id: "call_123", name: "get_weather", arguments: "{\"city\":\"NYC\"}")
-        let assistantMsg = AssistantMessage(
-            content: "Let me check",
-            toolCalls: [toolCall],
-            reasoning: reasoning
-        )
-        let client = OpenAIClient(
-            apiKey: "test-key",
-            model: "test/model",
-            baseURL: OpenAIClient.openRouterBaseURL
-        )
-        let messages: [ChatMessage] = [.assistant(assistantMsg)]
-        let request = client.buildRequest(messages: messages, tools: [])
-
-        let encoder = JSONEncoder()
-        let data = try encoder.encode(request)
-        let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
-
-        let jsonMessages = json?["messages"] as? [[String: Any]]
-        let msg = jsonMessages?[0]
-        #expect(msg?["reasoning_content"] as? String == "I need to check the weather...")
-        let jsonToolCalls = msg?["tool_calls"] as? [[String: Any]]
-        #expect(jsonToolCalls?.count == 1)
-    }
-}
-
 struct ProxyModeTests {
     @Test
     func proxyFactoryCreatesClientWithoutApiKeyOrModel() throws {
diff --git a/Tests/AgentRunKitTests/OpenAIReplayProfileTests.swift b/Tests/AgentRunKitTests/OpenAIReplayProfileTests.swift
diff --git a/Tests/AgentRunKitTests/Smoke/OpenRouterSmokeTests.swift b/Tests/AgentRunKitTests/Smoke/OpenRouterSmokeTests.swift
