diff --git a/docs/architecture/tla/OpenAICompatibleResponses.EarlyAttach.cfg b/docs/architecture/tla/OpenAICompatibleResponses.EarlyAttach.cfg new file mode 100644 index 0000000000..256cb7890e --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.EarlyAttach.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = FALSE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoCleanup.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoCleanup.cfg new file mode 100644 index 0000000000..bd5d667ee3 --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoCleanup.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = FALSE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoCompletion.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoCompletion.cfg new file mode 100644 index 0000000000..8c41f4c98b --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoCompletion.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = FALSE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoExtra.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoExtra.cfg new file mode 100644 index 0000000000..fbe979c48b --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoExtra.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = FALSE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoIsolation.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoIsolation.cfg new file mode 100644 index 0000000000..1efc2e1f3e --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoIsolation.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = FALSE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoReasoning.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoReasoning.cfg new file mode 100644 index 0000000000..e878fc35cd --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoReasoning.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = FALSE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoRoute.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoRoute.cfg new file mode 100644 index 0000000000..cee9028b46 --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoRoute.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = FALSE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoSanitize.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoSanitize.cfg new file mode 100644 index 0000000000..f731718e7b --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoSanitize.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = FALSE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoStreaming.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoStreaming.cfg new file mode 100644 index 0000000000..60fc2c5c08 --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoStreaming.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = FALSE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.NoTools.cfg b/docs/architecture/tla/OpenAICompatibleResponses.NoTools.cfg new file mode 100644 index 0000000000..08e3bed383 --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.NoTools.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = FALSE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.Unfixed.cfg b/docs/architecture/tla/OpenAICompatibleResponses.Unfixed.cfg new file mode 100644 index 0000000000..8ae44fe655 --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.Unfixed.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = FALSE + MergeExtra = FALSE + CleanText = FALSE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.cfg b/docs/architecture/tla/OpenAICompatibleResponses.cfg new file mode 100644 index 0000000000..92f7a417eb --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.cfg @@ -0,0 +1,17 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + RouteCompletions = TRUE + IsolateSubclasses = TRUE + InitialListenerBoundary <- InitialListenerOracle + AttachAfterBuild = TRUE + RequestBoundary <- RequestOracle + CleanupBoundary <- CleanupOracle + ForwardReasoning = TRUE + HonorStreaming = TRUE + MergeExtra = TRUE + CleanText = TRUE + RouteOptIn = TRUE + ForwardTools = TRUE + ReleaseListener = TRUE +INVARIANTS NoListenerDuringBuild Routing ReasoningAndTools ListenerReleased Streaming ExtraBody WellFormed diff --git a/docs/architecture/tla/OpenAICompatibleResponses.tla b/docs/architecture/tla/OpenAICompatibleResponses.tla new file mode 100644 index 0000000000..69e103735a --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponses.tla @@ -0,0 +1,97 @@ +---- MODULE OpenAICompatibleResponses ---- +\* Sources: OpenAICompatible.handleInputChange, OpenAiHandler.createMessage and completePrompt. +\* Sinks: buildResponsesRequest, client.responses.create, bridgeExternalAbortSignal.dispose. +\* Initial expectation: find routing, option loss, or listener leaks. Rules preceded the first review. +\* Failure: the saved flag selects the wrong API. Rule: Routing. +\* Failure: reasoning, tools, streaming, Extra Body, or valid text is lost. +\* Rules: ReasoningAndTools, Streaming, ExtraBody, WellFormed. The SDK is an oracle. +\* Failure: construction or request exit retains a listener. +\* Rules: NoListenerDuringBuild and ListenerReleased model attach, abort, and disposal order. +\* Only the Responses message route registers a bridge listener. +\* Parameters and protocol rules are in ResponsesRequestParameters.tla and ResponsesProtocol.tla. +\* Initial review ratchet: 0 covered, 3 added, 2 gap (translations and pixels). +\* Threads: discussion_r4616096233, discussion_r4616097051, discussion_r4616097077 on PR 2498. +\* PR: https://github.com/Zoo-Code-Org/Zoo-Code/pull/2498 +\* Self-review added the output-limit override rule after 456 requested tokens became 1000. +\* Refactor ratchet: 0 covered, 1 added, 0 gap. Derived listener state hid disposal order. +\* Review e7ed99742a: 0 covered, 9 added, 2 gap (helper duplication and code/model correspondence). +\* Finding 9's blanket rejection of max was false; supported effort values depend on the model. +\* Review 6385d18512: 1 covered (subclass isolation), 2 added (null defaults and replay scope), 5 gap. +\* Gaps 4-8 concern test evidence, malformed SDK output, comments, and UI wording. +\* The routing model already covered incompatible providers, but DeepSeek lacked the code guard. +\* Current gate: 6912 routing states pass; ten sabotage configs and the unfixed config fail. +\* Across three models: 29 sabotage configs fail with invariant error 12; three fixed configs pass. +\* Separate real-code mutations fail the focused tests. See ResponsesReviewReplays.md for each mapping. +\* These are manual gates. No script or CI step proves code/model correspondence. +\* Findings: completion routing, terminal failure, subclass flags, and replay were missing before fixes. +\* The latest model found no additional defect. No real-code replay false alarm remains. +\* Cost: about 85 agent minutes across the PR; the 33-config TLC gate takes about 30 seconds. +\* Run each config with OpenAICompatibleResponsesMC.tla. Metadata must be outside the repo. +\* Unit gate: openai.spec.ts, openai-compatible-responses.spec.ts, and responses-api-contract.spec.ts. +\* The model checks the request boundary. It does not prove the code correct. +CONSTANTS RequestBoundary, CleanupBoundary, InitialListenerBoundary +VARIABLES source, phase, listener, aborted +vars == <> +sink == RequestBoundary[source] +ExpectedResponses == source.responses /\ source.compatible + +InputDomain == + [responses : BOOLEAN, entrypoint : {"message", "completion"}, compatible : BOOLEAN, + streaming : {"unset", "on", "off"}, + reasoning : BOOLEAN, tools : BOOLEAN, extra : BOOLEAN, badText : BOOLEAN, + signal : {"none", "live", "aborted"}] + +Init == + /\ source \in InputDomain + /\ (source.entrypoint = "message" \/ ~source.tools) + /\ phase = "build" + /\ aborted = (source.signal = "aborted") + /\ listener = InitialListenerBoundary[source] + +\* buildResponsesRequest can return a body or throw before listener registration. +Build == + /\ phase = "build" + /\ phase' \in {"ready", "buildFailed"} + /\ UNCHANGED <> + +\* bridgeExternalAbortSignal skips registration for absent or pre-aborted signals. +Attach == + /\ phase = "ready" + /\ phase' = "request" + /\ listener' = (ExpectedResponses /\ source.entrypoint = "message" /\ source.signal = "live" /\ ~aborted) + /\ UNCHANGED <> + +\* The once-only abort listener removes itself when the external signal fires. +Abort == + /\ source.signal = "live" + /\ ~aborted + /\ aborted' = TRUE + /\ listener' = FALSE + /\ UNCHANGED <> + +\* Success, SDK failure, and generator close all enter the same finally block. +Finish == + /\ phase = "request" + /\ phase' = "cleanup" + /\ UNCHANGED <> + +\* The finally block calls the bridge's dispose function before the generator ends. +Dispose == + /\ phase = "cleanup" + /\ phase' = "done" + /\ listener' = CleanupBoundary[listener] + /\ UNCHANGED <> + +Next == Build \/ Attach \/ Abort \/ Finish \/ Dispose +Spec == Init /\ [][Next]_vars +RequestBuilt == phase \in {"ready", "request", "cleanup", "done"} +Routing == RequestBuilt => sink.responses = ExpectedResponses +ReasoningAndTools == RequestBuilt => + /\ sink.reasoning = source.reasoning + /\ sink.tools = source.tools +NoListenerDuringBuild == phase \in {"build", "ready", "buildFailed"} => ~listener +ListenerReleased == phase \in {"done", "buildFailed"} => ~listener +Streaming == RequestBuilt => sink.streaming = (source.entrypoint = "message" /\ source.streaming # "off") +ExtraBody == RequestBuilt => sink.extra = source.extra +WellFormed == RequestBuilt => ~sink.badText +==== diff --git a/docs/architecture/tla/OpenAICompatibleResponsesMC.tla b/docs/architecture/tla/OpenAICompatibleResponsesMC.tla new file mode 100644 index 0000000000..4eac00a188 --- /dev/null +++ b/docs/architecture/tla/OpenAICompatibleResponsesMC.tla @@ -0,0 +1,17 @@ +---- MODULE OpenAICompatibleResponsesMC ---- +\* Finite request boundaries stand for the SDK call. No parser is copied. +EXTENDS OpenAICompatibleResponses +CONSTANTS HonorStreaming, MergeExtra, CleanText, RouteOptIn, + ForwardTools, ForwardReasoning, ReleaseListener, AttachAfterBuild, RouteCompletions, IsolateSubclasses +EffectiveResponses(s) == s.responses /\ (s.compatible \/ ~IsolateSubclasses) + /\ (s.entrypoint = "message" \/ RouteCompletions) +RequestOracle == [s \in InputDomain |-> + [responses |-> IF RouteOptIn THEN EffectiveResponses(s) ELSE ~EffectiveResponses(s), + streaming |-> IF s.entrypoint = "completion" THEN FALSE ELSE IF HonorStreaming THEN s.streaming # "off" ELSE TRUE, + reasoning |-> IF ForwardReasoning THEN s.reasoning ELSE FALSE, + tools |-> IF ForwardTools THEN s.tools ELSE FALSE, + extra |-> IF MergeExtra THEN s.extra ELSE FALSE, + badText |-> s.badText /\ ~CleanText]] +InitialListenerOracle == [s \in InputDomain |-> ~AttachAfterBuild /\ s.responses /\ s.compatible /\ s.entrypoint = "message" /\ s.signal = "live"] +CleanupOracle == [attached \in BOOLEAN |-> IF ReleaseListener THEN FALSE ELSE attached] +==== diff --git a/docs/architecture/tla/ResponsesProtocol.NoCapture.cfg b/docs/architecture/tla/ResponsesProtocol.NoCapture.cfg new file mode 100644 index 0000000000..857b01de19 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoCapture.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = FALSE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoFailureGuard.cfg b/docs/architecture/tla/ResponsesProtocol.NoFailureGuard.cfg new file mode 100644 index 0000000000..a469d4ffad --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoFailureGuard.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = FALSE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoForeign.cfg b/docs/architecture/tla/ResponsesProtocol.NoForeign.cfg new file mode 100644 index 0000000000..4665e69fdc --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoForeign.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = FALSE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoInferenceGuard.cfg b/docs/architecture/tla/ResponsesProtocol.NoInferenceGuard.cfg new file mode 100644 index 0000000000..72ea212da5 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoInferenceGuard.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = FALSE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoOrder.cfg b/docs/architecture/tla/ResponsesProtocol.NoOrder.cfg new file mode 100644 index 0000000000..93fd582673 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoOrder.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = FALSE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoReplay.cfg b/docs/architecture/tla/ResponsesProtocol.NoReplay.cfg new file mode 100644 index 0000000000..b116137168 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoReplay.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = FALSE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoReset.cfg b/docs/architecture/tla/ResponsesProtocol.NoReset.cfg new file mode 100644 index 0000000000..574cb7def3 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoReset.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = FALSE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoRestriction.cfg b/docs/architecture/tla/ResponsesProtocol.NoRestriction.cfg new file mode 100644 index 0000000000..f989c0f284 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoRestriction.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = FALSE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.NoTerminal.cfg b/docs/architecture/tla/ResponsesProtocol.NoTerminal.cfg new file mode 100644 index 0000000000..056906f914 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.NoTerminal.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = FALSE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.OldAzureDefault.cfg b/docs/architecture/tla/ResponsesProtocol.OldAzureDefault.cfg new file mode 100644 index 0000000000..df7f9408d8 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.OldAzureDefault.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = FALSE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.PublishFailed.cfg b/docs/architecture/tla/ResponsesProtocol.PublishFailed.cfg new file mode 100644 index 0000000000..050a43e5d4 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.PublishFailed.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = TRUE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.cfg b/docs/architecture/tla/ResponsesProtocol.cfg new file mode 100644 index 0000000000..17b261e698 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.cfg @@ -0,0 +1,23 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + GuardReplayScope = TRUE + ReplayScopeBoundary <- ReplayScopeOracle + RequireTerminal = TRUE + ReasoningSamples <- Samples + AcceptBoundary <- AcceptOracle + SaveBoundary <- SaveOracle + ReplayBoundary <- ReplayOracle + ResetBoundary <- ResetOracle + PublishFailedBoundary = FALSE + ChoiceBoundary <- ChoiceOracle + ClientBoundary <- ClientOracle + RejectFailures = TRUE + PreserveOrder = TRUE + PreserveReasoning = TRUE + ReplayReasoning = TRUE + ResetReasoning = TRUE + PreserveRestriction = TRUE + UseAzureV1 = TRUE + GuardInference = TRUE +INVARIANTS NoForeignReasoning TerminalFailuresVisible SavedComplete ReplayComplete NoStaleReasoning NoFailedReasoning ToolRestrictionPreserved EndpointPolicy diff --git a/docs/architecture/tla/ResponsesProtocol.tla b/docs/architecture/tla/ResponsesProtocol.tla new file mode 100644 index 0000000000..3d14498ae1 --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocol.tla @@ -0,0 +1,95 @@ +---- MODULE ResponsesProtocol ---- +\* Source: OpenAiHandler.createMessage, completePrompt, and buildResponsesRequest. +\* Sinks: assertResponsesApiSuccess, getReasoningDetails, and convertToResponsesApiInput. +\* Expect to find silent terminal failure, missing replay, and stale reasoning state. +\* Failure: a bad terminal status is accepted. Rule: TerminalFailuresVisible. +\* Failure: reasoning is lost or reused from a previous request. Rules: ReplayComplete, NoStaleReasoning. +\* Failure: failed request reasoning is persisted. Rule: NoFailedReasoning. +\* Failure: a tool restriction is lost or malformed. Rule: ToolRestrictionPreserved. +\* Failure: an Azure endpoint selects the wrong client. Rule: EndpointPolicy. +\* Review PR 2498: added rules for findings 1, 2, 5, 7, 9, 10, 11. +\* Domain: compatible provider with Responses enabled. SDK events and storage are oracles. +\* The domain has two opaque reasoning items. Their contents are not parsed. +\* Final review added premature EOF: ended means SDK EOF without a completion event. +\* Current gate: 10368 states pass; eleven sabotage configs fail with invariant error 12. +\* Review 6385d18512: expect cross-endpoint replay. Added NoForeignReasoning for finding 3. +\* Sources: saved reasoning scope. Sinks: Responses input and Chat Completions conversion. +\* Failure: reasoning reaches a different endpoint or Chat Completions. +\* Each sabotage was replayed by removing its code guard and running the matching focused tests. +\* New inspection finding: use completed output order, not item arrival order, for saved reasoning. +\* Self-review ratchet: 0 covered, 3 added, 0 gap (saved order, replay domain, and premature EOF). +\* Model setup: the replay oracle domain was extended to include a reordered sample. +\* No real-code replay false alarm remains. The model does not prove the code correct. +\* Cost: about 15 agent minutes this round; each config runs in about 1 second. +\* Simplification expectation: no new defect; one completion callback must retain snapshot and item fallback behavior. +\* Existing SavedComplete, NoFailedReasoning, and TerminalFailuresVisible rules cover this change. +\* Zoomote threads 4631255963 and 4631288743: 2 covered, 0 added, 0 gap. +\* The same-profile toggle-off replay uses the existing NoForeignReasoning rule. +\* Local fingerprint calculation adds no stored state. EndpointPolicy covers the removed duplicate Azure guard. +\* Simplification gate: all 33 TLC configs retain their pass or invariant-failure result. +\* The focused tests retain snapshot order, missing-snapshot fallback, and explicit-empty clearing. +\* No new runtime defect or replay false alarm was found. Cost: about 8 more agent minutes. +\* Run with -config ResponsesProtocol.cfg ResponsesProtocolMC.tla, and repeat for each variant. +EXTENDS Naturals, Sequences +CONSTANTS ReasoningSamples, AcceptBoundary, SaveBoundary, ReplayBoundary, + ResetBoundary, PublishFailedBoundary, ChoiceBoundary, ClientBoundary, ReplayScopeBoundary +VARIABLES source, phase, received, saved, replayed, accepted +vars == <> +Domain == [status : {"completed", "failed", "incomplete", "cancelled", "error", "ended"}, + reasoning : ReasoningSamples, choice : {"none", "auto", "restricted", "malformed"}, + endpoint : {"generic", "azureLegacy", "azureV1", "inferenceLegacy", "inferenceV1"}, + explicitVersion : BOOLEAN, destination : {"same", "other", "chat"}] +ExpectedClient(s) == + IF s.endpoint = "inferenceLegacy" THEN "reject" + ELSE IF s.endpoint = "azureLegacy" /\ s.explicitVersion THEN "azure" + ELSE "plain" +Captured == SubSeq(source.reasoning, 1, received) +Init == + /\ source \in Domain + /\ phase = "start" + /\ received = 0 + /\ saved = <<"old">> + /\ replayed = <<>> + /\ accepted = FALSE +Reset == + /\ phase = "start" + /\ phase' = "build" + /\ saved' = ResetBoundary[saved] + /\ UNCHANGED <> +Build == + /\ phase = "build" + /\ phase' = IF ChoiceBoundary[source.choice] = "reject" \/ ClientBoundary[source] = "reject" + THEN "buildFailed" ELSE "request" + /\ UNCHANGED <> +Receive == + /\ phase = "request" + /\ received < Len(source.reasoning) + /\ received' = received + 1 + /\ UNCHANGED <> +Finish == + /\ phase = "request" + /\ source.status # "completed" \/ received = Len(source.reasoning) + /\ phase' = "finished" + /\ accepted' = AcceptBoundary[source.status] + /\ saved' = IF source.status = "completed" THEN SaveBoundary[source.reasoning] + ELSE IF PublishFailedBoundary THEN Captured ELSE <<>> + /\ UNCHANGED <> +Replay == + /\ phase = "finished" + /\ accepted + /\ phase' = "replayed" + /\ replayed' = IF ReplayScopeBoundary[source.destination] THEN ReplayBoundary[saved] ELSE <<>> + /\ UNCHANGED <> +Next == Reset \/ Build \/ Receive \/ Finish \/ Replay +Spec == Init /\ [][Next]_vars +TerminalFailuresVisible == phase \in {"finished", "replayed"} /\ source.status # "completed" => ~accepted +SavedComplete == phase \in {"finished", "replayed"} /\ source.status = "completed" => saved = source.reasoning +ReplayComplete == phase = "replayed" /\ source.status = "completed" /\ source.destination = "same" => replayed = source.reasoning +NoForeignReasoning == phase = "replayed" /\ source.destination # "same" => replayed = <<>> +NoStaleReasoning == phase \in {"build", "request", "buildFailed"} => saved = <<>> +NoFailedReasoning == phase \in {"finished", "replayed"} /\ source.status # "completed" => saved = <<>> +ToolRestrictionPreserved == + /\ source.choice = "restricted" => ChoiceBoundary[source.choice] = "restricted" + /\ source.choice = "malformed" => phase \notin {"request", "finished", "replayed"} +EndpointPolicy == ClientBoundary[source] = ExpectedClient(source) +==== diff --git a/docs/architecture/tla/ResponsesProtocolMC.tla b/docs/architecture/tla/ResponsesProtocolMC.tla new file mode 100644 index 0000000000..e2a00ea7fc --- /dev/null +++ b/docs/architecture/tla/ResponsesProtocolMC.tla @@ -0,0 +1,19 @@ +---- MODULE ResponsesProtocolMC ---- +\* Model switches remove one boundary guard at a time. +EXTENDS ResponsesProtocol +CONSTANTS RequireTerminal, RejectFailures, PreserveReasoning, PreserveOrder, ReplayReasoning, ResetReasoning, + PreserveRestriction, UseAzureV1, GuardInference, GuardReplayScope +Samples == {<<>>, <<"r1">>, <<"r1", "r2">>} +ReplayScopeOracle == [destination \in {"same", "other", "chat"} |-> GuardReplayScope => destination = "same"] +AcceptOracle == [status \in {"completed", "failed", "incomplete", "cancelled", "error", "ended"} |-> + status = "completed" \/ ~RejectFailures \/ (~RequireTerminal /\ status = "ended")] +SaveOracle == [items \in Samples |-> IF ~PreserveReasoning THEN <<>> ELSE IF PreserveOrder THEN items ELSE [i \in 1..Len(items) |-> items[Len(items) - i + 1]]] +ReplayOracle == [items \in Samples \cup {<<"r2", "r1">>} |-> IF ReplayReasoning THEN items ELSE <<>>] +ResetOracle == [items \in Samples \cup {<<"old">>} |-> IF ResetReasoning THEN <<>> ELSE items] +ChoiceOracle == [choice \in {"none", "auto", "restricted", "malformed"} |-> + IF ~PreserveRestriction THEN "auto" ELSE IF choice = "malformed" THEN "reject" ELSE choice] +ClientOracle == [s \in Domain |-> + IF s.endpoint = "inferenceLegacy" THEN IF GuardInference THEN "reject" ELSE "plain" + ELSE IF s.endpoint = "azureLegacy" THEN IF s.explicitVersion \/ ~UseAzureV1 THEN "azure" ELSE "plain" + ELSE "plain"] +==== diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoLimit.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoLimit.cfg new file mode 100644 index 0000000000..ab4c5625df --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoLimit.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = FALSE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoNullParameters.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoNullParameters.cfg new file mode 100644 index 0000000000..5e2a22e5b4 --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoNullParameters.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = FALSE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoNullStrict.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoNullStrict.cfg new file mode 100644 index 0000000000..79f7e3c06d --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoNullStrict.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = FALSE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoStrict.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoStrict.cfg new file mode 100644 index 0000000000..d563ff292a --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoStrict.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = FALSE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoTemperature.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoTemperature.cfg new file mode 100644 index 0000000000..181df75ad2 --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoTemperature.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = FALSE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoTimeout.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoTimeout.cfg new file mode 100644 index 0000000000..b78108e4a8 --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoTimeout.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = FALSE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoZeroLimit.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoZeroLimit.cfg new file mode 100644 index 0000000000..efd74dcefe --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoZeroLimit.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = FALSE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.NoZeroTemperature.cfg b/docs/architecture/tla/ResponsesRequestParameters.NoZeroTemperature.cfg new file mode 100644 index 0000000000..11b39b1778 --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.NoZeroTemperature.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = FALSE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.cfg b/docs/architecture/tla/ResponsesRequestParameters.cfg new file mode 100644 index 0000000000..379fbc48fa --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.cfg @@ -0,0 +1,13 @@ +SPECIFICATION Spec +CHECK_DEADLOCK FALSE +CONSTANTS + HonorNullStrict = TRUE + HonorNullParameters = TRUE + ParameterBoundary <- ParameterOracle + HonorLimit = TRUE + HonorZeroLimit = TRUE + HonorTemperature = TRUE + HonorZeroTemperature = TRUE + HonorStrict = TRUE + HonorTimeout = TRUE +INVARIANTS ToolParameters OutputLimit Temperature ToolStrictness TimeoutNormalization diff --git a/docs/architecture/tla/ResponsesRequestParameters.tla b/docs/architecture/tla/ResponsesRequestParameters.tla new file mode 100644 index 0000000000..4e58bba6a6 --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParameters.tla @@ -0,0 +1,42 @@ +---- MODULE ResponsesRequestParameters ---- +\* Source: OpenAiHandler options and resolved model info. Sink: buildResponsesRequest and SDK options. +\* Failure: zero, absent, or unsupported values change request defaults or omission. +\* Rules: OutputLimit, Temperature, ToolStrictness, TimeoutNormalization. +\* Review PR 2498, findings 4 and 5: added explicit zero, omission, and strict-schema domains. +\* The pure builder permits these value rules to be checked apart from async cleanup. +\* Runtime normalizers and schema conversion are oracles. No parser is copied. +\* Unit gate: openai-compatible-responses.spec.ts and openai.spec.ts. +\* Current gate: 19440 states pass; eight sabotage configs fail with invariant error 12. +\* Review 6385d18512: expect null-default mutants to pass old tests (finding 2). +\* Failure: absent function strictness or parameters become false or an empty schema. +\* Added null source values and ToolParameters. The SDK is an oracle. +\* Each sabotage was replayed on the real code. Tests cover accept and reject cases. +\* No new code bug was found here; the tests now make zero and omission rules explicit. +\* Cost: about 5 agent minutes this round; each config runs in about 1 second. +\* Run with -config ResponsesRequestParameters.cfg ResponsesRequestParametersMC.tla. +\* Repeat for each variant. The model does not prove the code correct. +CONSTANT ParameterBoundary +VARIABLE source +Domain == [includeLimit : {"unset", "on", "off"}, customLimit : {"unset", "zero", "custom"}, + modelLimit : {"unset", "default"}, temperature : {"unset", "zero", "custom"}, + supportsTemperature : {"unset", "on", "off"}, strict : {"unset", "on", "off", "mcp", "null"}, + parameters : {"null", "schema"}, tools : BOOLEAN, entrypoint : {"message", "completion"}, + timeout : {"unset", "disabled", "valid", "fractional"}] +ExpectedLimit(s) == IF s.includeLimit # "on" THEN "unset" + ELSE IF s.customLimit = "custom" THEN "custom" ELSE s.modelLimit +ExpectedTemperature(s) == IF s.supportsTemperature = "off" THEN "unset" ELSE s.temperature +ExpectedStrict(s) == IF ~s.tools THEN "omit" ELSE IF s.strict = "null" THEN "null" ELSE IF s.strict \in {"unset", "on"} THEN "on" ELSE "off" +ExpectedParameters(s) == IF s.tools THEN s.parameters ELSE "omit" +ExpectedTimeout(s) == IF s.entrypoint = "message" \/ s.timeout \in {"unset", "disabled"} THEN "unset" + ELSE IF s.timeout = "fractional" THEN "rounded" ELSE "valid" +Init == /\ source \in Domain + /\ (source.entrypoint = "message" \/ ~source.tools) +Next == UNCHANGED source +Spec == Init /\ [][Next]_source +sink == ParameterBoundary[source] +OutputLimit == sink.limit = ExpectedLimit(source) +Temperature == sink.temperature = ExpectedTemperature(source) +ToolStrictness == sink.strict = ExpectedStrict(source) +ToolParameters == sink.parameters = ExpectedParameters(source) +TimeoutNormalization == sink.timeout = ExpectedTimeout(source) +==== diff --git a/docs/architecture/tla/ResponsesRequestParametersMC.tla b/docs/architecture/tla/ResponsesRequestParametersMC.tla new file mode 100644 index 0000000000..de35f66896 --- /dev/null +++ b/docs/architecture/tla/ResponsesRequestParametersMC.tla @@ -0,0 +1,14 @@ +---- MODULE ResponsesRequestParametersMC ---- +\* Sabotage switches alter one value rule per run. +EXTENDS ResponsesRequestParameters +CONSTANTS HonorLimit, HonorZeroLimit, HonorTemperature, HonorZeroTemperature, HonorStrict, HonorTimeout, HonorNullStrict, HonorNullParameters +ParameterOracle == [s \in Domain |-> + [limit |-> IF ~HonorLimit /\ s.includeLimit = "on" /\ s.customLimit = "custom" THEN s.modelLimit + ELSE IF ~HonorZeroLimit /\ s.includeLimit = "on" /\ s.customLimit = "zero" THEN "zero" + ELSE ExpectedLimit(s), + temperature |-> IF ~HonorTemperature \/ (~HonorZeroTemperature /\ s.temperature = "zero") THEN "unset" + ELSE ExpectedTemperature(s), + strict |-> IF ~HonorStrict /\ s.tools THEN "on" ELSE IF ~HonorNullStrict /\ s.strict = "null" /\ s.tools THEN "off" ELSE ExpectedStrict(s), + parameters |-> IF ~HonorNullParameters /\ s.parameters = "null" /\ s.tools THEN "schema" ELSE ExpectedParameters(s), + timeout |-> IF ~HonorTimeout /\ s.entrypoint = "completion" THEN s.timeout ELSE ExpectedTimeout(s)]] +==== diff --git a/docs/architecture/tla/ResponsesReviewReplays.md b/docs/architecture/tla/ResponsesReviewReplays.md new file mode 100644 index 0000000000..3d686b32b8 --- /dev/null +++ b/docs/architecture/tla/ResponsesReviewReplays.md @@ -0,0 +1,43 @@ +# Responses review replay evidence + +These are separate manual TLC and real-code checks for PR #2498. Each fixed configuration passes; each sabotage configuration fails with invariant error 12. The matching code mutation makes the named focused Vitest cases fail. This table records the correspondence; CI does not verify it automatically. + +The unit files are `openai.spec.ts`, `openai-compatible-responses.spec.ts`, and `responses-api-stream.spec.ts`. Ownership value cases also live in `responses-api-contract.spec.ts`. + +| Model configuration | Focused test title or pattern | +| -------------------------------------------------- | -------------------------------------------------------- | +| `OpenAICompatibleResponses.EarlyAttach.cfg` | `does not attach a listener` | +| `OpenAICompatibleResponses.NoCleanup.cfg` | `releases the listener` | +| `OpenAICompatibleResponses.NoCompletion.cfg` | `routes single completions` | +| `OpenAICompatibleResponses.NoExtra.cfg` | `preserves streaming=` | +| `OpenAICompatibleResponses.NoIsolation.cfg` | `isolates the inherited` | +| `OpenAICompatibleResponses.NoReasoning.cfg` | `preserves routing, tools` | +| `OpenAICompatibleResponses.NoRoute.cfg` | `preserves routing, tools` | +| `OpenAICompatibleResponses.NoSanitize.cfg` | `sends well-formed prompt` | +| `OpenAICompatibleResponses.NoStreaming.cfg` | `preserves streaming=` | +| `OpenAICompatibleResponses.NoTools.cfg` | `preserves routing, tools` | +| `ResponsesRequestParameters.NoLimit.cfg` | `output limit defaults` | +| `ResponsesRequestParameters.NoNullParameters.cfg` | `API defaults for tools` | +| `ResponsesRequestParameters.NoNullStrict.cfg` | `API defaults for tools` | +| `ResponsesRequestParameters.NoStrict.cfg` | `strict-schema setting or preserves request invariants` | +| `ResponsesRequestParameters.NoTemperature.cfg` | `temperature capability` | +| `ResponsesRequestParameters.NoTimeout.cfg` | `normalizes completion timeout` | +| `ResponsesRequestParameters.NoZeroLimit.cfg` | `output limit defaults` | +| `ResponsesRequestParameters.NoZeroTemperature.cfg` | `temperature capability` | +| `ResponsesProtocol.NoCapture.cfg` | `round-trips all encrypted` | +| `ResponsesProtocol.NoFailureGuard.cfg` | `rejects terminal / Responses terminal failure contract` | +| `ResponsesProtocol.NoForeign.cfg` | `switching endpoint` | +| `ResponsesProtocol.NoInferenceGuard.cfg` | `rejects the legacy Azure` | +| `ResponsesProtocol.NoOrder.cfg` | `round-trips all encrypted` | +| `ResponsesProtocol.NoReplay.cfg` | `round-trips all encrypted` | +| `ResponsesProtocol.NoReset.cfg` | `clears prior reasoning` | +| `ResponsesProtocol.NoRestriction.cfg` | `allowed_tools mode or malformed function restrictions` | +| `ResponsesProtocol.NoTerminal.cfg` | `rejects EOF without` | +| `ResponsesProtocol.OldAzureDefault.cfg` | `uses Azure v1 for Responses` | +| `ResponsesProtocol.PublishFailed.cfg` | `clears prior reasoning` | + +`ResponsesProtocol.NoForeign.cfg` also corresponds to the `NoChatFilter` code mutation, rejected by `switching chat`. The ownership table exercises matching and mismatched endpoints, mismatched providers, missing ownership, and the other Responses consumers that supply no OpenAI ownership scope. + +`OpenAICompatibleResponses.Unfixed.cfg` remains a negative routing baseline. It fails independently of the 29 single-guard sabotage configurations. The initial unfixed implementation failed 24 focused regression cases at the previous review. + +The latest code mutation run rejected 30 mutations: one for each sabotage configuration and a second transport boundary for `NoForeign`. It includes DeepSeek in the inherited-flag mutation. Fixed models explored 6,912 routing states, 19,440 parameter states, and 10,368 protocol states. No additional runtime defect or replay false alarm was found by the expanded models. diff --git a/packages/types/src/providers/openai.ts b/packages/types/src/providers/openai.ts index fbe0f99522..b952d46fc4 100644 --- a/packages/types/src/providers/openai.ts +++ b/packages/types/src/providers/openai.ts @@ -1133,6 +1133,7 @@ export const openAiProviderDefinition = createProviderDefinition({ openAiUseAzure: z.boolean().optional(), azureApiVersion: z.string().optional(), openAiStreamingEnabled: z.boolean().optional(), + openAiUseResponsesApi: z.boolean().optional(), openAiHostHeader: z.string().optional(), // Keep temporarily for backward compatibility during migration. openAiHeaders: z.record(z.string(), z.string()).optional(), openAiExtraBody: openAiExtraBodySchema, diff --git a/src/api/providers/__tests__/openai.spec.ts b/src/api/providers/__tests__/openai.spec.ts index 1e8daccb5b..8006e5dab8 100644 --- a/src/api/providers/__tests__/openai.spec.ts +++ b/src/api/providers/__tests__/openai.spec.ts @@ -1,3 +1,9 @@ +import { DeepSeekHandler } from "../deepseek" +import { responsesReasoningScope } from "../../transform/responses-api-reasoning" +import { KimiCodeHandler } from "../kimi-code" +import { MoonshotHandler } from "../moonshot" +import { MimoHandler } from "../mimo" +import { prepareApiConversationMessage } from "../../../core/task/apiConversationHistory" // npx vitest run api/providers/__tests__/openai.spec.ts import { OpenAiHandler, getOpenAiModels } from "../openai" @@ -9,6 +15,7 @@ import { DEEP_SEEK_DEFAULT_TEMPERATURE, azureOpenAiDefaultApiVersion, type ModelInfo, + providerIdentifiers, } from "@roo-code/types" import { Package } from "../../../shared/package" import { makeApiHandlerOptions, makeCreateMessageMetadata } from "../../../test-utils/api" @@ -23,14 +30,16 @@ vitest.mock("../utils/timeout-config", () => ({ const MOCK_TIMEOUT_MS = 300_000 const mockCreate = vitest.fn() +const mockResponsesCreate = vitest.fn() vitest.mock("openai", () => { const mockConstructor = vitest.fn() const mockAzureConstructor = vitest.fn() return { __esModule: true, - default: mockConstructor.mockImplementation(function () { + default: mockConstructor.mockImplementation(function (options: { baseURL: string }) { return { + baseURL: options.baseURL, chat: { completions: { create: mockCreate.mockImplementation(async (options) => { @@ -79,6 +88,22 @@ vitest.mock("openai", () => { }), }, }, + responses: { + create: mockResponsesCreate.mockImplementation(async () => + asyncStreamFrom([ + { type: "response.output_text.delta", delta: "Test response" }, + { + type: "response.completed", + response: { + usage: { + input_tokens: 10, + output_tokens: 5, + }, + }, + }, + ]), + ), + }, } }), AzureOpenAI: mockAzureConstructor, @@ -2092,6 +2117,775 @@ describe("OpenAiHandler - strict tool schemas", () => { }) }) +describe("OpenAiHandler Responses API (openAiUseResponsesApi)", () => { + const systemPrompt = "You are a helpful assistant." + const messages: Anthropic.Messages.MessageParam[] = [{ role: "user", content: "Hello" }] + + const baseOptions: ApiHandlerOptions = { + openAiApiKey: "test-key", + openAiModelId: "my-terra-deployment", + openAiBaseUrl: "https://gateway.corp.example/v1", + openAiUseResponsesApi: true, + } + + const functionTool = { + type: "function" as const, + function: { + name: "read_file", + description: "Read a file", + parameters: { + type: "object", + properties: { path: { type: "string" } }, + required: ["path"], + }, + }, + } + + beforeEach(() => { + mockCreate.mockClear() + mockResponsesCreate.mockClear() + }) + + it.each([true, false, undefined])("preserves streaming=%s and Extra Body request precedence", async (streaming) => { + const handler = new OpenAiHandler({ + ...baseOptions, + openAiStreamingEnabled: streaming, + openAiExtraBody: JSON.stringify({ service_tier: "flex", model: "wrong", stream: !streaming }), + }) + if (streaming === false) { + mockResponsesCreate.mockResolvedValueOnce({ + output: [ + { type: "message", content: [{ type: "output_text", text: "Answer" }] }, + { type: "reasoning", summary: [{ type: "summary_text", text: "Thinking" }] }, + { type: "function_call", call_id: "call-1", name: "read_file", arguments: "{}" }, + ], + usage: { input_tokens: 10, output_tokens: 5 }, + }) + } + const chunks = await collectStream(handler.createMessage(systemPrompt, messages)) + expect(mockResponsesCreate.mock.calls[0][0]).toMatchObject({ + model: baseOptions.openAiModelId, + stream: streaming !== false, + service_tier: "flex", + }) + if (streaming === false) { + expect(chunks).toContainEqual({ type: "text", text: "Answer" }) + expect(chunks).toContainEqual({ type: "reasoning", text: "Thinking" }) + expect(chunks).toContainEqual({ type: "tool_call", id: "call-1", name: "read_file", arguments: "{}" }) + expect(chunks).toContainEqual(expect.objectContaining({ type: "usage", inputTokens: 10, outputTokens: 5 })) + } + }) + + it.each(["plain", "😀", "\ud800", "\udfff", "a\ud800b", "\ud800\ud801\udc00"])( + "sends well-formed prompt, history, and JSON tool arguments for %j", + async (text) => { + const history: Anthropic.Messages.MessageParam[] = [ + { role: "user", content: text }, + { + role: "assistant", + content: [{ type: "tool_use", id: "call-1", name: "read_file", input: { path: text } }], + }, + { role: "user", content: [{ type: "tool_result", tool_use_id: "call-1", content: text }] }, + ] + await collectStream(new OpenAiHandler(baseOptions).createMessage(text, history)) + const body = mockResponsesCreate.mock.calls[0][0] + expectNoLoneSurrogates(body) + for (const item of body.input) { + if (item.type === "function_call") expectNoLoneSurrogates(JSON.parse(item.arguments)) + } + expect(history[0].content).toBe(text) + if (text === "😀" || text === "plain") expect(body.instructions).toBe(text) + }, + ) + + const optionCases = [true, false, undefined].flatMap((responses) => + [true, false, undefined].flatMap((streaming) => + [true, false].map((reasoning) => ({ responses, streaming, reasoning })), + ), + ) + it.each(optionCases)( + "preserves routing, tools, and reasoning for %j", + async ({ responses, streaming, reasoning }) => { + const handler = new OpenAiHandler({ + ...baseOptions, + openAiUseResponsesApi: responses, + openAiStreamingEnabled: streaming, + enableReasoningEffort: reasoning, + openAiCustomModelInfo: { + contextWindow: 128_000, + supportsPromptCache: false, + supportsReasoningEffort: true, + reasoningEffort: "high", + }, + }) + if (responses && streaming === false) mockResponsesCreate.mockResolvedValueOnce({ output: [] }) + await collectStream( + handler.createMessage(systemPrompt, messages, makeCreateMessageMetadata({ tools: [functionTool] })), + ) + expect(mockResponsesCreate.mock.calls.length).toBe(responses ? 1 : 0) + expect(mockCreate.mock.calls.length).toBe(responses ? 0 : 1) + if (responses) { + const body = mockResponsesCreate.mock.calls[0][0] + expect(body.stream).toBe(streaming !== false) + expect(body.reasoning?.effort).toBe(reasoning ? "high" : undefined) + expect(body.tools[0].name).toBe("read_file") + } + }, + ) + + const units = [0x61, 0xd800, 0xdbff, 0xdc00, 0xdfff, 0xfffd] + const textCases = units.flatMap((first) => + units.flatMap((second) => units.map((third) => String.fromCharCode(first, second, third))), + ) + it.each(textCases)("sends well-formed text for generated UTF-16 input %j", async (text) => { + await collectStream(new OpenAiHandler(baseOptions).createMessage(text, [{ role: "user", content: text }])) + expectNoLoneSurrogates(mockResponsesCreate.mock.calls[0][0]) + }) + + it("keeps distinct tool IDs paired after sanitization", async () => { + const history: Anthropic.Messages.MessageParam[] = [ + { + role: "assistant", + content: [ + { type: "tool_use", id: "call\ud800", name: "read_file", input: { path: "a" } }, + { type: "tool_use", id: "call\ud801", name: "read_file", input: { path: "b" } }, + ], + }, + { + role: "user", + content: [ + { type: "tool_result", tool_use_id: "call\ud800", content: "a" }, + { type: "tool_result", tool_use_id: "call\ud801", content: "b" }, + ], + }, + ] + await collectStream(new OpenAiHandler(baseOptions).createMessage(systemPrompt, history)) + const input = mockResponsesCreate.mock.calls[0][0].input + expectNoLoneSurrogates(input) + expect(input[0].call_id).not.toBe(input[1].call_id) + expect(input[2].call_id).toBe(input[0].call_id) + expect(input[3].call_id).toBe(input[1].call_id) + }) + + it("resolves model parameters once on the Responses route", async () => { + const handler = new OpenAiHandler(baseOptions) + const getModel = vi.spyOn(handler, "getModel") + await collectStream(handler.createMessage(systemPrompt, messages)) + expect(getModel).toHaveBeenCalledOnce() + }) + + it.each([true, false])( + "does not attach a listener when construction fails with streaming=%s", + async (streaming) => { + const controller = new AbortController() + const add = vi.spyOn(controller.signal, "addEventListener") + const failure = new Error("history could not be read") + const history: Anthropic.Messages.MessageParam[] = [ + { + role: "user", + get content(): string { + throw failure + }, + }, + ] + await expect( + collectStream( + new OpenAiHandler({ ...baseOptions, openAiStreamingEnabled: streaming }).createMessage( + systemPrompt, + history, + makeCreateMessageMetadata({ abortSignal: controller.signal }), + ), + ), + ).rejects.toBe(failure) + expect(add).not.toHaveBeenCalled() + expect(mockResponsesCreate).not.toHaveBeenCalled() + }, + ) + + it.each(["before", "during"])("forwards an external abort %s the request", async (timing) => { + const controller = new AbortController() + const add = vi.spyOn(controller.signal, "addEventListener") + const remove = vi.spyOn(controller.signal, "removeEventListener") + if (timing === "before") controller.abort() + const stream = new OpenAiHandler(baseOptions).createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ abortSignal: controller.signal }), + ) + await stream.next() + const signal: AbortSignal = mockResponsesCreate.mock.calls[0][1].signal + expect(signal.aborted).toBe(timing === "before") + controller.abort() + expect(signal.aborted).toBe(true) + await stream.return(undefined) + if (timing === "before") expect(add).not.toHaveBeenCalled() + else expect(remove).toHaveBeenCalledWith("abort", add.mock.calls[0][1]) + }) + + it.each([true, false])("releases the listener on completion with streaming=%s", async (streaming) => { + const controller = new AbortController() + const add = vi.spyOn(controller.signal, "addEventListener") + const remove = vi.spyOn(controller.signal, "removeEventListener") + if (!streaming) mockResponsesCreate.mockResolvedValueOnce({ output: [], usage: null }) + await collectStream( + new OpenAiHandler({ ...baseOptions, openAiStreamingEnabled: streaming }).createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ abortSignal: controller.signal }), + ), + ) + expect(add).toHaveBeenCalledOnce() + expect(remove).toHaveBeenCalledWith("abort", add.mock.calls[0][1]) + }) + + it.each(["request", "iteration", "close"])("releases the listener on %s exit", async (exit) => { + const controller = new AbortController() + const add = vi.spyOn(controller.signal, "addEventListener") + const remove = vi.spyOn(controller.signal, "removeEventListener") + const failure = new Error("Request was aborted.") + if (exit === "request") mockResponsesCreate.mockRejectedValueOnce(failure) + if (exit === "iteration") + mockResponsesCreate.mockResolvedValueOnce( + (async function* () { + controller.abort() + yield { type: "response.output_text.delta", delta: "partial" } + throw failure + })(), + ) + const stream = new OpenAiHandler(baseOptions).createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ abortSignal: controller.signal }), + ) + if (exit === "close") { + await stream.next() + await stream.return(undefined) + } else { + await expect(collectStream(stream)).rejects.toMatchObject({ name: "AbortError" }) + } + expect(remove).toHaveBeenCalledWith("abort", add.mock.calls[0][1]) + }) + + it("preserves HTTP failures and releases the listener", async () => { + const controller = new AbortController() + const remove = vi.spyOn(controller.signal, "removeEventListener") + mockResponsesCreate.mockRejectedValueOnce(Object.assign(new Error("rate limited"), { status: 429 })) + await expect( + collectStream( + new OpenAiHandler(baseOptions).createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ abortSignal: controller.signal }), + ), + ), + ).rejects.toMatchObject({ status: 429 }) + expect(remove).toHaveBeenCalledOnce() + }) + + it.each([ + { type: "function" as const, function: { name: "read_file" } }, + { type: "custom" as const, custom: { name: "read_file" } }, + ])("maps named $type tool choices", async (choice) => { + await collectStream( + new OpenAiHandler(baseOptions).createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ tools: [functionTool], tool_choice: choice, parallelToolCalls: false }), + ), + ) + expect(mockResponsesCreate.mock.calls[0][0]).toMatchObject({ + tool_choice: { type: choice.type, name: "read_file" }, + parallel_tool_calls: false, + }) + }) + + it.each([true, false])("honors temperature and output limits with support=%s", async (supportsTemperature) => { + await collectStream( + new OpenAiHandler({ + ...baseOptions, + modelTemperature: 0.4, + includeMaxTokens: true, + modelMaxTokens: 456, + openAiCustomModelInfo: { + contextWindow: 128_000, + maxTokens: 1000, + supportsPromptCache: false, + supportsTemperature, + }, + }).createMessage(systemPrompt, messages), + ) + expect(mockResponsesCreate.mock.calls[0][0].temperature).toBe(supportsTemperature ? 0.4 : undefined) + expect(mockResponsesCreate.mock.calls[0][0].max_output_tokens).toBe(456) + }) + + it.each(["o1-mini", "o3-mini", "o4-mini"])( + "routes %s to Responses before model-family dispatch", + async (openAiModelId) => { + await collectStream( + new OpenAiHandler({ ...baseOptions, openAiModelId }).createMessage(systemPrompt, messages), + ) + expect(mockResponsesCreate).toHaveBeenCalledOnce() + expect(mockCreate).not.toHaveBeenCalled() + }, + ) + + it.each([true, false, undefined])( + "routes single completions with streaming setting %s", + async (openAiStreamingEnabled) => { + const handler = new OpenAiHandler({ + ...baseOptions, + openAiStreamingEnabled, + openAiExtraBody: '{"service_tier":"flex"}', + }) + mockResponsesCreate.mockResolvedValueOnce({ + status: "completed", + output: [ + { + type: "message", + content: [ + { type: "output_text", text: "first" }, + { type: "refusal", refusal: "ignored" }, + { type: "output_text", text: "second" }, + ], + }, + ], + }) + const controller = new AbortController() + expect( + await handler.completePrompt("prompt\ud800", { abortSignal: controller.signal, timeoutMs: 1234 }), + ).toBe("firstsecond") + expect(mockCreate).not.toHaveBeenCalled() + expect(mockResponsesCreate).toHaveBeenCalledWith( + expect.objectContaining({ + model: baseOptions.openAiModelId, + stream: false, + store: false, + service_tier: "flex", + }), + { signal: controller.signal, timeout: 1234 }, + ) + expectNoLoneSurrogates(mockResponsesCreate.mock.calls[0][0]) + }, + ) + + const terminalCases = ["message", "completion"].flatMap((entry) => + ["failed", "incomplete", "cancelled"].map((status) => ({ entry, status })), + ) + it.each(terminalCases)("rejects terminal $status from $entry", async ({ entry, status }) => { + const handler = new OpenAiHandler({ ...baseOptions, openAiStreamingEnabled: false }) + mockResponsesCreate.mockResolvedValueOnce({ + status, + output: [{ type: "message", content: [{ type: "output_text", text: "partial" }] }], + error: { message: "server rejected", code: "server_error" }, + }) + const request = + entry === "completion" + ? handler.completePrompt("prompt") + : collectStream(handler.createMessage(systemPrompt, messages)) + await expect(request).rejects.toMatchObject({ + code: "server_error", + message: expect.stringContaining("server rejected"), + }) + }) + + it.each(["message", "completion"])("preserves token-limit classification from $s", async (entry) => { + const handler = new OpenAiHandler({ ...baseOptions, openAiStreamingEnabled: false }) + mockResponsesCreate.mockResolvedValueOnce({ + status: "incomplete", + incomplete_details: { reason: "max_output_tokens" }, + output: [], + }) + await expect( + entry === "completion" + ? handler.completePrompt("prompt") + : collectStream(handler.createMessage(systemPrompt, messages)), + ).rejects.toMatchObject({ name: "OutputTokenLimitError" }) + }) + + it.each([KimiCodeHandler, MoonshotHandler, MimoHandler, DeepSeekHandler])( + "isolates the inherited Responses flag in %s", + async (Provider) => { + const handler = new Provider({ + ...baseOptions, + apiModelId: "custom-model", + kimiCodeAuthMethod: "api-key", + kimiCodeApiKey: "key", + }) + await collectStream(OpenAiHandler.prototype.createMessage.call(handler, systemPrompt, messages)) + await OpenAiHandler.prototype.completePrompt.call(handler, "prompt") + expect(mockCreate).toHaveBeenCalledTimes(2) + expect(mockResponsesCreate).not.toHaveBeenCalled() + }, + ) + + it.each([true, false])("round-trips all encrypted reasoning items with streaming=%s", async (streaming) => { + const handler = new OpenAiHandler({ ...baseOptions, openAiStreamingEnabled: streaming }) + const reasoningItems = ["rs1", "rs2"].map((id, index) => ({ + type: "reasoning", + id, + summary: index === 0 ? undefined : [], + encrypted_content: `opaque-${id}`, + })) + const expected = reasoningItems.map((item) => ({ ...item, summary: [] })) + const output = [ + ...reasoningItems, + { type: "function_call", call_id: "call1", name: "read_file", arguments: "{}" }, + ] + mockResponsesCreate.mockResolvedValueOnce( + streaming + ? asyncStreamFrom([ + ...[...reasoningItems].reverse().map((item) => ({ type: "response.output_item.done", item })), + { type: "response.completed", response: { status: "completed", output } }, + ]) + : { status: "completed", output }, + ) + await collectStream(handler.createMessage(systemPrompt, messages)) + expect(handler.getReasoningDetails()).toEqual( + expected.map((item) => ({ + ...item, + format: "openai-responses-v1", + provider: providerIdentifiers.openai, + endpoint: responsesReasoningScope(baseOptions.openAiBaseUrl!), + })), + ) + const saved = prepareApiConversationMessage({ + message: { role: "assistant", content: [{ type: "tool_use", id: "call1", name: "read_file", input: {} }] }, + api: handler, + apiConfiguration: { ...baseOptions, apiProvider: providerIdentifiers.openai }, + apiConversationHistory: [], + }) + const reloaded: typeof saved = JSON.parse(JSON.stringify(saved)) + mockResponsesCreate.mockResolvedValueOnce( + streaming + ? asyncStreamFrom([{ type: "response.completed", response: { status: "completed" } }]) + : { status: "completed", output: [] }, + ) + await collectStream( + handler.createMessage(systemPrompt, [ + reloaded, + { role: "user", content: [{ type: "tool_result", tool_use_id: "call1", content: "result" }] }, + ]), + ) + const input = mockResponsesCreate.mock.calls[1][0].input + expect(input.slice(0, 2)).toEqual(expected) + expect(input[2]).toMatchObject({ type: "function_call", call_id: "call1" }) + expect(input[3]).toMatchObject({ type: "function_call_output", call_id: "call1" }) + expect(handler.getReasoningDetails()).toBeUndefined() + }) + + it.each([undefined, null, []])( + "uses item fallback only when the completion snapshot is missing: %j", + async (output) => { + const handler = new OpenAiHandler(baseOptions) + const item = { type: "reasoning", id: "rs1", summary: [], encrypted_content: "opaque" } + mockResponsesCreate.mockResolvedValueOnce( + asyncStreamFrom([ + { type: "response.output_item.done", item }, + { type: "response.completed", response: { status: "completed", output } }, + ]), + ) + await collectStream(handler.createMessage(systemPrompt, messages)) + expect(handler.getReasoningDetails()).toEqual(output ? undefined : [expect.objectContaining(item)]) + }, + ) + + it.each(["endpoint", "chat"])("does not forward saved reasoning after switching %s", async (destination) => { + const handler = new OpenAiHandler(baseOptions) + const item = { type: "reasoning", id: "rs1", summary: [], encrypted_content: "private-opaque" } + mockResponsesCreate.mockResolvedValueOnce( + asyncStreamFrom([{ type: "response.completed", response: { status: "completed", output: [item] } }]), + ) + await collectStream(handler.createMessage(systemPrompt, messages)) + const saved = prepareApiConversationMessage({ + message: { role: "assistant", content: "answer" }, + api: handler, + apiConfiguration: { ...baseOptions, apiProvider: providerIdentifiers.openai }, + apiConversationHistory: [], + }) + const reloaded: typeof saved = JSON.parse(JSON.stringify(saved)) + const next = new OpenAiHandler({ + ...baseOptions, + openAiUseResponsesApi: destination !== "chat", + openAiBaseUrl: destination === "chat" ? baseOptions.openAiBaseUrl : "https://other.example/v1", + }) + mockCreate.mockClear() + mockResponsesCreate.mockClear() + await collectStream(next.createMessage(systemPrompt, [reloaded])) + const calls = destination === "chat" ? mockCreate.mock.calls : mockResponsesCreate.mock.calls + expect(calls).toHaveLength(1) + expect(JSON.stringify(calls[0][0])).not.toContain("private-opaque") + expect(JSON.stringify(calls[0][0])).not.toContain("reasoning_details") + }) + + it("returns a fresh copy of encrypted reasoning details", async () => { + const handler = new OpenAiHandler(baseOptions) + const item = { + type: "reasoning", + id: "rs1", + summary: [{ type: "summary_text", text: "summary" }], + encrypted_content: "opaque", + } + mockResponsesCreate.mockResolvedValueOnce( + asyncStreamFrom([{ type: "response.completed", response: { status: "completed", output: [item] } }]), + ) + await collectStream(handler.createMessage(systemPrompt, messages)) + const details = handler.getReasoningDetails()! + details[0].encrypted_content = "changed" + details[0].summary[0].text = "changed" + expect(handler.getReasoningDetails()?.[0]).toMatchObject(item) + }) + + it("normalizes an aborted Responses completion", async () => { + const handler = new OpenAiHandler(baseOptions) + const controller = new AbortController() + mockResponsesCreate.mockImplementationOnce(async (_body, options) => { + controller.abort() + options.signal.throwIfAborted() + }) + await expect(handler.completePrompt("prompt", { abortSignal: controller.signal })).rejects.toMatchObject({ + name: "AbortError", + }) + expect(mockResponsesCreate.mock.calls[0][1].signal).toBe(controller.signal) + }) + + it.each(["failure", "close", "construction"])("clears prior reasoning on $s", async (exit) => { + const handler = new OpenAiHandler(baseOptions) + const item = { type: "reasoning", id: "rs1", summary: [], encrypted_content: "opaque" } + mockResponsesCreate.mockResolvedValueOnce( + asyncStreamFrom([{ type: "response.completed", response: { status: "completed", output: [item] } }]), + ) + await collectStream(handler.createMessage(systemPrompt, messages)) + expect(handler.getReasoningDetails()).toEqual([expect.objectContaining(item)]) + if (exit === "construction") { + vi.spyOn(handler, "getModel").mockImplementationOnce(() => { + throw new Error("construction failed") + }) + await expect(collectStream(handler.createMessage(systemPrompt, messages))).rejects.toThrow() + } else { + mockResponsesCreate.mockResolvedValueOnce( + asyncStreamFrom([ + { type: "response.output_item.done", item }, + { type: "response.output_text.delta", delta: "partial" }, + { type: "response.failed", response: { error: { message: "failed" } } }, + ]), + ) + const stream = handler.createMessage(systemPrompt, messages) + if (exit === "close") { + await stream.next() + await stream.return(undefined) + } else await expect(collectStream(stream)).rejects.toThrow() + } + expect(handler.getReasoningDetails()).toBeUndefined() + }) + + it("passes the strict-schema setting through the Responses tool mapper", async () => { + await collectStream( + new OpenAiHandler({ ...baseOptions, openAiStrictToolSchemas: false }).createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ tools: [functionTool] }), + ), + ) + expect(mockResponsesCreate.mock.calls[0][0].tools[0]).toMatchObject({ + strict: false, + parameters: functionTool.function.parameters, + }) + }) + + it.each(["none", "max"] as const)("preserves model-specific reasoning effort %s", async (reasoningEffort) => { + const handler = new OpenAiHandler({ + ...baseOptions, + enableReasoningEffort: true, + openAiCustomModelInfo: { + contextWindow: 128000, + supportsPromptCache: false, + supportsReasoningEffort: true, + reasoningEffort, + }, + }) + await collectStream(handler.createMessage(systemPrompt, messages)) + expect(mockResponsesCreate.mock.calls[0][0].reasoning.effort).toBe(reasoningEffort) + if (reasoningEffort === "none") expect(mockResponsesCreate.mock.calls[0][0]).not.toHaveProperty("include") + }) + + it.each(["openai.azure.com", "services.ai.azure.com"])("preserves Azure v1 endpoint on %s", (host) => { + new OpenAiHandler({ + ...baseOptions, + openAiBaseUrl: `https://resource.${host}/openai/v1/`, + openAiUseAzure: true, + }) + expect(vi.mocked(OpenAI)).toHaveBeenLastCalledWith( + expect.objectContaining({ baseURL: `https://resource.${host}/openai/v1/` }), + ) + }) + + it("uses Azure v1 for Responses when no dated version was selected", () => { + new OpenAiHandler({ ...baseOptions, openAiBaseUrl: "https://resource.openai.azure.com/openai" }) + expect(vi.mocked(OpenAI)).toHaveBeenLastCalledWith( + expect.objectContaining({ baseURL: "https://resource.openai.azure.com/openai/v1" }), + ) + }) + + it("preserves an explicit Azure API version", () => { + new OpenAiHandler({ + ...baseOptions, + openAiBaseUrl: "https://resource.openai.azure.com", + azureApiVersion: "custom-version", + }) + expect(vi.mocked(AzureOpenAI)).toHaveBeenLastCalledWith( + expect.objectContaining({ + apiVersion: "custom-version", + baseURL: "https://resource.openai.azure.com/openai", + }), + ) + }) + + it("rejects the legacy Azure AI Inference Responses combination", () => { + expect( + () => new OpenAiHandler({ ...baseOptions, openAiBaseUrl: "https://resource.services.ai.azure.com" }), + ).toThrow("/openai/v1") + }) + + it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY, undefined, 1.2])( + "normalizes completion timeout %s", + async (timeoutMs) => { + const handler = new OpenAiHandler(baseOptions) + mockResponsesCreate.mockResolvedValueOnce({ status: "completed", output: [] }) + await handler.completePrompt("prompt", { timeoutMs }) + const options = mockResponsesCreate.mock.calls[0][1] + if (timeoutMs === 1.2) expect(options).toHaveProperty("timeout", 2) + else expect(options).not.toHaveProperty("timeout") + }, + ) + + it.each(["openai.azure.com", "services.ai.azure.com"])( + "uses the chat path under the explicit Azure v1 root on %s", + async (host) => { + const handler = new OpenAiHandler({ + ...baseOptions, + openAiUseResponsesApi: false, + openAiBaseUrl: `https://resource.${host}/openai/v1/`, + }) + await collectStream(handler.createMessage(systemPrompt, messages)) + expect(mockCreate).toHaveBeenCalledOnce() + expect(mockCreate.mock.calls[0][1]).not.toHaveProperty("path") + }, + ) + + it("rejects EOF without a terminal completion and does not publish partial reasoning", async () => { + const handler = new OpenAiHandler(baseOptions) + mockResponsesCreate.mockResolvedValueOnce( + asyncStreamFrom([ + { + type: "response.output_item.done", + item: { type: "reasoning", id: "rs1", encrypted_content: "opaque", summary: [] }, + }, + { type: "response.output_text.delta", delta: "partial" }, + ]), + ) + await expect(collectStream(handler.createMessage(systemPrompt, messages))).rejects.toThrow( + "before a completed response", + ) + expect(handler.getReasoningDetails()).toBeUndefined() + }) + + it("routes createMessage to the Responses API and not Chat Completions", async () => { + const handler = new OpenAiHandler(baseOptions) + const chunks = await collectStream(handler.createMessage(systemPrompt, messages)) + + expect(mockResponsesCreate).toHaveBeenCalledOnce() + expect(mockCreate).not.toHaveBeenCalled() + + const body = mockResponsesCreate.mock.calls[0][0] + expect(body.model).toBe("my-terra-deployment") + expect(body.instructions).toBe(systemPrompt) + expect(body.stream).toBe(true) + expect(body.store).toBe(false) + expect(body).not.toHaveProperty("reasoning_effort") + + // The shared Responses stream processor surfaces text and usage chunks. + expect(chunks).toContainEqual({ type: "text", text: "Test response" }) + expect(chunks.some((chunk) => chunk.type === "usage")).toBe(true) + }) + + it("translates reasoning_effort into reasoning: { effort } and keeps function tools", async () => { + const handler = new OpenAiHandler({ + ...baseOptions, + enableReasoningEffort: true, + openAiCustomModelInfo: { + contextWindow: 128_000, + supportsPromptCache: false, + supportsReasoningEffort: true, + reasoningEffort: "high", + }, + }) + + await collectStream( + handler.createMessage(systemPrompt, messages, makeCreateMessageMetadata({ tools: [functionTool] })), + ) + + expect(mockResponsesCreate).toHaveBeenCalledOnce() + const body = mockResponsesCreate.mock.calls[0][0] + expect(body.reasoning).toEqual({ effort: "high" }) + expect(body.include).toEqual(["reasoning.encrypted_content"]) + // Reasoning and tools are combined on the Responses API path — neither is dropped. + expect(body.tools).toEqual([ + { + type: "function", + name: "read_file", + description: "Read a file", + parameters: expect.objectContaining({ type: "object" }), + strict: true, + }, + ]) + expect(body.tool_choice).toBeUndefined() + expect(body.parallel_tool_calls).toBe(true) + }) + + it("omits reasoning when reasoning effort is disabled", async () => { + const handler = new OpenAiHandler({ + ...baseOptions, + enableReasoningEffort: false, + openAiCustomModelInfo: { contextWindow: 128_000, supportsPromptCache: false }, + }) + + await collectStream(handler.createMessage(systemPrompt, messages)) + + expect(mockResponsesCreate).toHaveBeenCalledOnce() + const body = mockResponsesCreate.mock.calls[0][0] + expect(body).not.toHaveProperty("reasoning") + expect(body).not.toHaveProperty("include") + }) + + it("passes string tool_choice through unchanged", async () => { + const handler = new OpenAiHandler(baseOptions) + + await collectStream( + handler.createMessage( + systemPrompt, + messages, + makeCreateMessageMetadata({ tools: [functionTool], tool_choice: "auto" }), + ), + ) + + const body = mockResponsesCreate.mock.calls[0][0] + expect(body.tool_choice).toBe("auto") + }) + + it("keeps Chat Completions as the default when the setting is off", async () => { + const handler = new OpenAiHandler({ + openAiApiKey: "test-key", + openAiModelId: "gpt-4", + openAiBaseUrl: "https://api.openai.com/v1", + }) + + await collectStream(handler.createMessage(systemPrompt, messages)) + + expect(mockCreate).toHaveBeenCalled() + expect(mockResponsesCreate).not.toHaveBeenCalled() + }) +}) + describe("getOpenAiModels", () => { beforeEach(() => { vi.mocked(axios.get).mockClear() diff --git a/src/api/providers/deepseek.ts b/src/api/providers/deepseek.ts index 25e660abec..07ac2fb5ed 100644 --- a/src/api/providers/deepseek.ts +++ b/src/api/providers/deepseek.ts @@ -94,6 +94,7 @@ export class DeepSeekHandler extends OpenAiHandler { constructor(options: ApiHandlerOptions) { super({ ...options, + openAiUseResponsesApi: false, openAiApiKey: options.deepSeekApiKey ?? NOT_PROVIDED, openAiModelId: options.apiModelId ?? deepSeekDefaultModelId, openAiBaseUrl: options.deepSeekBaseUrl || "https://api.deepseek.com", diff --git a/src/api/providers/kimi-code.ts b/src/api/providers/kimi-code.ts index 54e48b29c0..aa883eac5d 100644 --- a/src/api/providers/kimi-code.ts +++ b/src/api/providers/kimi-code.ts @@ -43,6 +43,7 @@ export class KimiCodeHandler extends OpenAiHandler { constructor(options: ApiHandlerOptions) { super({ ...options, + openAiUseResponsesApi: false, openAiBaseUrl: KIMI_CODE_BASE_URL, openAiApiKey: options.kimiCodeApiKey ?? NOT_PROVIDED, openAiModelId: options.apiModelId ?? kimiCodeDefaultModelId, diff --git a/src/api/providers/mimo.ts b/src/api/providers/mimo.ts index d2fba1cb48..891e0b4ed9 100644 --- a/src/api/providers/mimo.ts +++ b/src/api/providers/mimo.ts @@ -28,6 +28,7 @@ export class MimoHandler extends OpenAiHandler { constructor(options: ApiHandlerOptions) { super({ ...options, + openAiUseResponsesApi: false, openAiApiKey: options.mimoApiKey ?? NOT_PROVIDED, openAiModelId: options.apiModelId ?? mimoDefaultModelId, openAiBaseUrl: options.mimoBaseUrl || "https://token-plan-sgp.xiaomimimo.com/v1", diff --git a/src/api/providers/moonshot.ts b/src/api/providers/moonshot.ts index e43dac825a..c0143308f9 100644 --- a/src/api/providers/moonshot.ts +++ b/src/api/providers/moonshot.ts @@ -19,6 +19,7 @@ export class MoonshotHandler extends OpenAiHandler { // OpenAI Node SDK path as the generic "OpenAI Compatible" provider. super({ ...options, + openAiUseResponsesApi: false, openAiApiKey: options.moonshotApiKey ?? NOT_PROVIDED, openAiModelId: options.apiModelId ?? moonshotDefaultModelId, openAiBaseUrl: options.moonshotBaseUrl || "https://api.moonshot.ai/v1", diff --git a/src/api/providers/openai.ts b/src/api/providers/openai.ts index 98ea18df8a..cbd724c56a 100644 --- a/src/api/providers/openai.ts +++ b/src/api/providers/openai.ts @@ -4,6 +4,7 @@ import axios from "axios" import { type ModelInfo, + providerIdentifiers, azureOpenAiDefaultApiVersion, isAzureAiInferenceBaseUrl, isAzureOpenAiBaseUrl, @@ -21,7 +22,16 @@ import { TagMatcher } from "../../utils/tag-matcher" import { convertToOpenAiMessages } from "../transform/openai-format" import { sanitizeSurrogates } from "../transform/sanitize-surrogates" import { convertToR1Format } from "../transform/r1-format" +import { buildResponsesRequest } from "./utils/openai-compatible-responses" +import { processResponsesApiStream, createUsageNormalizer } from "../transform/responses-api-stream" import { ApiStream, ApiStreamUsageChunk } from "../transform/stream" +import { assertResponsesApiSuccess } from "../transform/responses-api-error" +import { + readResponsesReasoningItem, + responsesReasoningScope, + type ScopedResponsesReasoningItem, +} from "../transform/responses-api-reasoning" +import { OutputTokenLimitError } from "./utils/output-token-limit-error" import { getModelParams } from "../transform/model-params" import { DEFAULT_HEADERS, NOT_PROVIDED } from "./constants" @@ -29,6 +39,21 @@ import { BaseProvider } from "./base-provider" import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata, CompletePromptOptions } from "../index" import { handleOpenAIError } from "./utils/error-handler" import { extractReasoningFromDelta } from "./utils/extract-reasoning" +import { + bridgeExternalAbortSignal, + createAbortError, + isRequestAborted, + hasUsableTimeout, + toSdkTimeoutMs, +} from "./utils/abort-signal" + +function isAzureV1BaseUrl(baseUrl?: string): boolean { + try { + return /\/openai\/v1\/?$/.test(new URL(baseUrl ?? "").pathname) + } catch { + return false + } +} type OpenAiUsage = | { @@ -49,6 +74,7 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl protected client: OpenAI private readonly providerName = "OpenAI" private readonly extraBody: Record + private responsesReasoning: OpenAI.Responses.ResponseReasoningItem[] = [] constructor(options: ApiHandlerOptions) { super() @@ -65,7 +91,24 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl ...(this.options.openAiHeaders || {}), } - if (isAzureAiInference) { + const isAzureV1 = isAzureV1BaseUrl(baseURL) + if (isAzureAiInference && this.options.openAiUseResponsesApi) { + throw new Error( + "Responses API requires an /openai/v1 base URL for Azure AI Inference. Update the Base URL or disable Use Responses API.", + ) + } + if (isAzureV1 || (isAzureOpenAi && this.options.openAiUseResponsesApi && !this.options.azureApiVersion)) { + // Azure's v1 API supports Responses without a dated api-version parameter. + const responsesBaseURL = isAzureV1 + ? baseURL + : `${baseURL.replace(/\/openai\/?$/i, "").replace(/\/$/, "")}/openai/v1` + this.client = new OpenAI({ + baseURL: responsesBaseURL, + apiKey, + defaultHeaders: headers, + timeout: this.timeoutMs, + }) + } else if (isAzureAiInference) { // Azure AI Inference Service (e.g., for DeepSeek) uses a different path structure this.client = new OpenAI({ baseURL, @@ -100,9 +143,18 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl messages: Anthropic.Messages.MessageParam[], metadata?: ApiHandlerCreateMessageMetadata, ): ApiStream { + const modelId = this.options.openAiModelId ?? "" + // Opt-in Responses API path: some OpenAI-compatible endpoints (e.g. Azure + // OpenAI deployments of reasoning models behind corporate gateways) reject + // `reasoning_effort` combined with function tools on /chat/completions and + // require /responses instead. + if (this.options.openAiUseResponsesApi) { + yield* this.handleResponsesApiMessage(systemPrompt, messages, metadata) + return + } + const { info: modelInfo, reasoning } = this.getModel() const modelUrl = this.options.openAiBaseUrl ?? "" - const modelId = this.options.openAiModelId ?? "" // Stryker disable next-line LogicalOperator: equivalent. An unset option makes `&&` // yield undefined, which the parameter default in convertToolsForOpenAI turns back into // the same strict value as `??`. @@ -299,6 +351,98 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl } } + /** Sends the opt-in Responses request through the shared input and stream transforms. */ + private async *handleResponsesApiMessage( + systemPrompt: string, + messages: Anthropic.Messages.MessageParam[], + metadata?: ApiHandlerCreateMessageMetadata, + ): ApiStream { + this.responsesReasoning = [] + const { info: modelInfo, reasoning } = this.getModel() + // Stryker disable next-line LogicalOperator: equivalent. An unset option makes `&&` + // yield undefined, which the parameter default in convertToolsForOpenAI turns back into + // the same strict value as `??`. + const strictToolSchemas = this.options.openAiStrictToolSchemas ?? DEFAULT_OPEN_AI_STRICT_TOOL_SCHEMAS + + const reasoningItems = new Map() + const captureReasoning = (value: unknown) => { + const item = readResponsesReasoningItem(value) + if (item) reasoningItems.set(item.id, item) + } + const body = buildResponsesRequest({ + options: this.options, + modelInfo, + reasoning, + systemPrompt, + messages, + metadata, + tools: this.convertToolsForOpenAI(metadata?.tools, strictToolSchemas), + extraBody: this.extraBody, + reasoningScope: responsesReasoningScope(this.client.baseURL), + }) + + // Bridge the external abort signal only after every throw-prone part of + // request construction has run, so a construction failure cannot leak a + // listener on the caller's long-lived signal. + const { signal: abortSignal, dispose: removeExternalAbortListener } = bridgeExternalAbortSignal( + metadata?.abortSignal, + ) + + try { + const requestOptions = abortSignal ? { signal: abortSignal } : undefined + if (body.stream) { + const stream = await this.client.responses.create({ ...body, stream: true }, requestOptions) + let completed = false + yield* processResponsesApiStream(stream, createUsageNormalizer(), { + onOutputItem: captureReasoning, + onCompleted: (output) => { + completed = true + if (output) { + reasoningItems.clear() + output.forEach(captureReasoning) + } + }, + }) + if (!completed) throw new Error("Responses API stream ended before a completed response") + } else { + const response = await this.client.responses.create({ ...body, stream: false }, requestOptions) + assertResponsesApiSuccess(response) + for (const item of response.output) { + captureReasoning(item) + if (item.type === "message") { + for (const content of item.content) { + if (content.type === "output_text") yield { type: "text", text: content.text } + } + } else if (item.type === "function_call") { + yield { type: "tool_call", id: item.call_id, name: item.name, arguments: item.arguments } + } else if (item.type === "reasoning") { + for (const summary of item.summary ?? []) yield { type: "reasoning", text: summary.text } + } + } + const usage = createUsageNormalizer()(response.usage) + if (usage) yield usage + } + this.responsesReasoning = [...reasoningItems.values()] + } catch (error) { + if (error instanceof OutputTokenLimitError) throw error + if (isRequestAborted(error, abortSignal)) throw createAbortError(this.providerName) + throw handleOpenAIError(error, this.providerName) + } finally { + removeExternalAbortListener() + } + } + + getReasoningDetails(): ScopedResponsesReasoningItem[] | undefined { + if (!this.options.openAiUseResponsesApi || !this.responsesReasoning.length) return undefined + const endpoint = responsesReasoningScope(this.client.baseURL) + return structuredClone(this.responsesReasoning).map((item) => ({ + ...item, + format: "openai-responses-v1" as const, + provider: providerIdentifiers.openai, + endpoint, + })) + } + protected processUsageMetrics(usage: OpenAiUsage, _modelInfo?: ModelInfo): ApiStreamUsageChunk { const inputTokens = usage?.prompt_tokens || 0 const reportedCacheReadTokens = usage?.cache_read_input_tokens ?? usage?.prompt_tokens_details?.cached_tokens @@ -354,8 +498,38 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl } } - async completePrompt(prompt: string, _options?: CompletePromptOptions): Promise { + async completePrompt(prompt: string, options?: CompletePromptOptions): Promise { try { + if (this.options.openAiUseResponsesApi) { + const model = this.getModel() + const body = buildResponsesRequest({ + options: { ...this.options, openAiStreamingEnabled: false }, + modelInfo: model.info, + reasoning: model.reasoning, + systemPrompt: "", + messages: [{ role: "user", content: prompt }], + tools: undefined, + extraBody: this.extraBody, + reasoningScope: responsesReasoningScope(this.client.baseURL), + }) + const response = await this.client.responses.create( + { ...body, stream: false }, + { + ...(options?.abortSignal ? { signal: options.abortSignal } : {}), + ...(hasUsableTimeout(options?.timeoutMs) ? { timeout: toSdkTimeoutMs(options.timeoutMs) } : {}), + }, + ) + assertResponsesApiSuccess(response) + return response.output + .flatMap((item) => + item.type === "message" + ? item.content + .filter((content) => content.type === "output_text") + .map((content) => content.text) + : [], + ) + .join("") + } const isAzureAiInference = this._isAzureAiInference(this.options.openAiBaseUrl) const model = this.getModel() const modelInfo = model.info @@ -382,6 +556,8 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl return response.choices?.[0]?.message.content || "" } catch (error) { + if (error instanceof OutputTokenLimitError) throw error + if (isRequestAborted(error, options?.abortSignal)) throw createAbortError(this.providerName) if (error instanceof Error) { const wrapped = new Error(`${this.providerName} completion error: ${error.message}`, { cause: error }) const source = error as Error & { status?: number; errorDetails?: unknown; code?: unknown } @@ -582,7 +758,7 @@ export class OpenAiHandler extends BaseProvider implements SingleCompletionHandl } protected _isAzureAiInference(baseUrl?: string): boolean { - return isAzureAiInferenceBaseUrl(baseUrl) + return isAzureAiInferenceBaseUrl(baseUrl) && !isAzureV1BaseUrl(baseUrl) } /** diff --git a/src/api/providers/utils/__tests__/openai-compatible-responses.spec.ts b/src/api/providers/utils/__tests__/openai-compatible-responses.spec.ts new file mode 100644 index 0000000000..45ae5ba6dd --- /dev/null +++ b/src/api/providers/utils/__tests__/openai-compatible-responses.spec.ts @@ -0,0 +1,180 @@ +import { openAiModelInfoSaneDefaults, providerIdentifiers } from "@roo-code/types" +import { buildResponsesRequest } from "../openai-compatible-responses" +import { expectNoLoneSurrogates } from "../../../../test-utils/surrogates" + +type RequestInput = Parameters[0] + +const cases = [true, false, undefined].flatMap((streaming) => + [undefined, 456].flatMap((maxTokens) => [true, false].map((reasoning) => ({ streaming, maxTokens, reasoning }))), +) + +it.each(cases)( + "preserves request invariants without mutating explicit inputs: %j", + ({ streaming, maxTokens, reasoning }) => { + const input: RequestInput = { + options: { + openAiModelId: "deployment", + openAiStreamingEnabled: streaming, + includeMaxTokens: true, + modelMaxTokens: maxTokens, + }, + modelInfo: { ...openAiModelInfoSaneDefaults, maxTokens: 1000 }, + reasoning: reasoning ? { reasoning_effort: "high" } : undefined, + systemPrompt: "prompt\ud800😀", + messages: [{ role: "user", content: [{ type: "text", text: "history\udfff" }] }], + tools: [ + { type: "function", function: { name: "read_file", parameters: { type: "object" }, strict: false } }, + ], + reasoningScope: "test-endpoint", + extraBody: { model: "wrong", stream: !streaming, service_tier: "flex" }, + } + const before = structuredClone(input) + Object.freeze(input.options) + Object.freeze(input.modelInfo) + Object.freeze(input.messages) + Object.freeze(input.tools) + Object.freeze(input.extraBody) + const body = buildResponsesRequest(input) + expect(body).toMatchObject({ + model: "deployment", + stream: streaming !== false, + store: false, + service_tier: "flex", + max_output_tokens: maxTokens ?? 1000, + tools: [{ type: "function", name: "read_file", strict: false }], + }) + expect(body.reasoning?.effort).toBe(reasoning ? "high" : undefined) + expectNoLoneSurrogates(body) + expect(body.instructions).toContain("😀") + expect(input).toEqual(before) + expect(buildResponsesRequest(input)).toEqual(body) + }, +) + +function makeInput(overrides: Partial = {}): RequestInput { + return { + options: { openAiModelId: "custom" }, + modelInfo: { ...openAiModelInfoSaneDefaults, maxTokens: 1000 }, + reasoning: undefined, + systemPrompt: "system", + messages: [], + tools: undefined, + extraBody: {}, + reasoningScope: "test-endpoint", + ...overrides, + } +} + +it.each([ + { include: true, custom: 0, model: 1000, expected: 1000 }, + { include: true, custom: undefined, model: 1000, expected: 1000 }, + { include: true, custom: 456, model: 1000, expected: 456 }, + { include: false, custom: 456, model: 1000, expected: undefined }, + { include: undefined, custom: 456, model: 1000, expected: undefined }, + { include: true, custom: undefined, model: undefined, expected: undefined }, +])("honors output limit defaults and omission: %j", ({ include, custom, model, expected }) => { + const body = buildResponsesRequest( + makeInput({ + options: { includeMaxTokens: include, modelMaxTokens: custom }, + modelInfo: { ...openAiModelInfoSaneDefaults, maxTokens: model }, + }), + ) + if (expected === undefined) expect(body).not.toHaveProperty("max_output_tokens") + else expect(body).toHaveProperty("max_output_tokens", expected) +}) + +it.each([ + { supports: true, temperature: 0, expected: 0 }, + { supports: undefined, temperature: 0, expected: 0 }, + { supports: false, temperature: 0, expected: undefined }, + { supports: true, temperature: undefined, expected: undefined }, + { supports: undefined, temperature: undefined, expected: undefined }, + { supports: undefined, temperature: 0.4, expected: 0.4 }, + { supports: false, temperature: 0.4, expected: undefined }, +])("honors temperature capability, zero, and omission: %j", ({ supports, temperature, expected }) => { + const body = buildResponsesRequest( + makeInput({ + options: { modelTemperature: temperature }, + modelInfo: { ...openAiModelInfoSaneDefaults, supportsTemperature: supports }, + }), + ) + if (expected === undefined) expect(body).not.toHaveProperty("temperature") + else expect(body).toHaveProperty("temperature", expected) +}) + +it.each([undefined, [], [{ type: "custom" as const, custom: { name: "custom", format: { type: "text" as const } } }]])( + "omits tool controls when no function tools remain: %j", + (tools) => { + const body = buildResponsesRequest( + makeInput({ tools, metadata: { taskId: "task", tool_choice: "required", parallelToolCalls: false } }), + ) + expect(body).not.toHaveProperty("tools") + expect(body).not.toHaveProperty("tool_choice") + expect(body).not.toHaveProperty("parallel_tool_calls") + }, +) + +it.each(["auto", "required"] as const)("preserves allowed_tools mode %s and flattens function references", (mode) => { + const body = buildResponsesRequest( + makeInput({ + tools: [{ type: "function", function: { name: "read_file" } }], + metadata: { + taskId: "task", + tool_choice: { + type: "allowed_tools", + allowed_tools: { + mode, + tools: [ + { type: "function", function: { name: "read_file" } }, + { type: "custom", name: "other" }, + ], + }, + }, + }, + }), + ) + expect(body.tool_choice).toEqual({ + type: "allowed_tools", + mode, + tools: [ + { type: "function", name: "read_file" }, + { type: "custom", name: "other" }, + ], + }) +}) + +it.each([{}, { function: null }, { function: { name: 42 } }, { function: { name: "" } }])( + "rejects malformed function restrictions: %j", + (entry) => { + expect(() => + buildResponsesRequest( + makeInput({ + tools: [{ type: "function", function: { name: "read_file" } }], + metadata: { + taskId: "task", + tool_choice: { + type: "allowed_tools", + allowed_tools: { mode: "auto", tools: [{ type: "function", ...entry }] }, + }, + }, + }), + ), + ).toThrow("function name") + }, +) + +it.each([true, false])("replays standalone reasoning only with verified ownership: %s", (owned) => { + const item = { type: "reasoning" as const, id: "rs1", encrypted_content: "opaque", summary: [] } + const saved = owned + ? { ...item, format: "openai-responses-v1", provider: providerIdentifiers.openai, endpoint: "test-endpoint" } + : item + const body = buildResponsesRequest(makeInput({ messages: [saved] })) + expect(body.input).toEqual(owned ? [item] : []) +}) + +it("preserves API defaults for tools without strictness or parameters", () => { + const body = buildResponsesRequest(makeInput({ tools: [{ type: "function", function: { name: "no_args" } }] })) + expect(body.tools).toEqual([ + { type: "function", name: "no_args", description: undefined, strict: null, parameters: null }, + ]) +}) diff --git a/src/api/providers/utils/openai-compatible-responses.ts b/src/api/providers/utils/openai-compatible-responses.ts new file mode 100644 index 0000000000..2eb6f64065 --- /dev/null +++ b/src/api/providers/utils/openai-compatible-responses.ts @@ -0,0 +1,145 @@ +import type OpenAI from "openai" +import type { ModelInfo } from "@roo-code/types" +import type { ApiHandlerOptions } from "../../../shared/api" +import type { ApiHandlerCreateMessageMetadata } from "../../index" +import type { OpenAiReasoningParams } from "../../transform/reasoning" +import { convertToResponsesApiInput, type ResponsesApiMessage } from "../../transform/responses-api-input" +import { + sanitizeSurrogates, + sanitizeSurrogatesDeep, + sanitizeIdentifierSurrogates, +} from "../../transform/sanitize-surrogates" + +type ResponsesRequestInput = { + options: Readonly + modelInfo: ModelInfo + reasoning: OpenAiReasoningParams | undefined + systemPrompt: string + messages: ResponsesApiMessage[] + metadata?: ApiHandlerCreateMessageMetadata + tools: OpenAI.Chat.Completions.ChatCompletionTool[] | undefined + extraBody: Readonly> + reasoningScope: string +} + +/** Builds a request from explicit inputs without registering listeners or calling the SDK. */ +export function buildResponsesRequest({ + options, + modelInfo, + reasoning, + systemPrompt, + messages, + metadata, + tools, + extraBody, + reasoningScope, +}: ResponsesRequestInput): OpenAI.Responses.ResponseCreateParams { + // Sanitize before conversion, including strings inside JSON tool arguments. + // Encode IDs first so distinct tool calls remain distinct after sanitization. + const history = messages.map((message) => { + if (!("role" in message)) return message + return { + ...message, + content: + typeof message.content === "string" + ? message.content + : message.content.map((part) => { + if (part.type === "tool_use") return { ...part, id: sanitizeIdentifierSurrogates(part.id) } + if (part.type === "tool_result") + return { ...part, tool_use_id: sanitizeIdentifierSurrogates(part.tool_use_id) } + return part + }), + } + }) + // The deep sanitizer preserves the message structure and only replaces strings. + const sanitizedHistory = sanitizeSurrogatesDeep(history) as ResponsesApiMessage[] + const requestBody: OpenAI.Responses.ResponseCreateParams = { + model: options.openAiModelId ?? "", + instructions: sanitizeSurrogates(systemPrompt), + input: convertToResponsesApiInput(sanitizedHistory, reasoningScope), + stream: options.openAiStreamingEnabled ?? true, + // Stateless operation: don't store responses server-side. + store: false, + } + + // The Responses API takes reasoning as `reasoning: { effort }` instead of + // the Chat Completions `reasoning_effort` field; translate the resolved + // params (which honor the custom model info's reasoningEffort) so + // reasoning and function tools can be combined on this endpoint. + if (reasoning?.reasoning_effort) { + requestBody.reasoning = { + effort: reasoning.reasoning_effort, + } + // Only request encrypted reasoning content when reasoning is active. + if (String(reasoning.reasoning_effort) !== "none") requestBody.include = ["reasoning.encrypted_content"] + } + + // Omit temperature unless the + // model supports it and the user set a custom value, so the server's own + // default applies. + if (modelInfo.supportsTemperature !== false && options.modelTemperature != null) { + requestBody.temperature = options.modelTemperature + } + + // Mirror the Chat Completions max-tokens policy: only cap output when the + // user opted in via includeMaxTokens. + const maxTokens = options.modelMaxTokens || modelInfo.maxTokens + if (options.includeMaxTokens === true && maxTokens !== undefined) { + requestBody.max_output_tokens = maxTokens + } + + // convertToolsForOpenAI already applies the strict/non-strict schema + // policy (including the MCP strict exemption); the Responses API only + // needs the flattened function shape. + const responseTools = tools + ?.filter((tool) => tool?.type === "function") + .map((tool) => ({ + type: "function" as const, + name: tool.function.name, + description: tool.function.description, + parameters: tool.function.parameters ?? null, + strict: tool.function.strict ?? null, + })) + + if (responseTools?.length) { + requestBody.tools = responseTools + if (metadata?.tool_choice) { + requestBody.tool_choice = mapToolChoiceForResponsesApi(metadata.tool_choice) + } + requestBody.parallel_tool_calls = metadata?.parallelToolCalls ?? true + } + return { ...extraBody, ...requestBody } +} + +/** + * Maps a Chat Completions tool choice to the Responses API shape. String + * options (auto/required/none) are identical in both APIs; named-tool + * choices nest the name under `function`/`custom` in Chat Completions but + * keep it at the top level in the Responses API. Allowed function references are flattened while retaining their restriction mode. + */ +function mapToolChoiceForResponsesApi( + toolChoice: NonNullable, +): OpenAI.Responses.ResponseCreateParamsStreaming["tool_choice"] { + if (typeof toolChoice === "string") { + return toolChoice + } + switch (toolChoice.type) { + case "function": + return { type: "function", name: toolChoice.function.name } + case "custom": + return { type: "custom", name: toolChoice.custom.name } + case "allowed_tools": + return { + type: "allowed_tools", + mode: toolChoice.allowed_tools.mode, + tools: toolChoice.allowed_tools.tools.map((entry) => { + if (entry.type !== "function") return entry + const ref = entry.function + const name = ref && typeof ref === "object" && "name" in ref ? ref.name : undefined + if (typeof name !== "string" || !name) + throw new Error("Responses allowed_tools entry requires a function name") + return { type: "function", name } + }), + } + } +} diff --git a/src/api/transform/__tests__/responses-api-contract.spec.ts b/src/api/transform/__tests__/responses-api-contract.spec.ts new file mode 100644 index 0000000000..5755186723 --- /dev/null +++ b/src/api/transform/__tests__/responses-api-contract.spec.ts @@ -0,0 +1,112 @@ +import { providerIdentifiers } from "@roo-code/types" +import { convertToOpenAiMessages } from "../openai-format" +import { readResponsesReasoningItem, responsesReasoningScope } from "../responses-api-reasoning" +import { assertResponsesApiSuccess } from "../responses-api-error" +import { convertToResponsesApiInput } from "../responses-api-input" + +const reasoning = { + type: "reasoning", + id: "rs1", + encrypted_content: "opaque", + summary: [{ type: "summary_text", text: "summary" }], +} + +it.each([reasoning, { ...reasoning, summary: undefined }])("accepts valid reasoning items: %j", (item) => { + expect(readResponsesReasoningItem(item)).toEqual({ ...item, summary: item.summary ?? [] }) +}) + +it.each([ + null, + "reasoning", + {}, + { ...reasoning, id: "" }, + { ...reasoning, encrypted_content: 1 }, + { ...reasoning, type: "text" }, + { ...reasoning, summary: "summary" }, + { ...reasoning, summary: [null] }, + { ...reasoning, summary: [{ type: "summary_text", text: 1 }] }, +])("rejects invalid reasoning items: %j", (item) => { + expect(readResponsesReasoningItem(item)).toBeUndefined() + const message = { role: "assistant" as const, content: "answer", reasoning_details: [item] } + expect(convertToResponsesApiInput([message])).toEqual([ + { type: "message", role: "assistant", content: [{ type: "output_text", text: "answer" }] }, + ]) +}) + +it("replays all reasoning details before tool calls in their stored order", () => { + const second = { ...reasoning, id: "rs2", encrypted_content: "opaque2" } + const message = { + role: "assistant" as const, + content: [{ type: "tool_use" as const, id: "call1", name: "read_file", input: {} }], + reasoning_details: [reasoning, second], + } + expect(convertToResponsesApiInput([message]).slice(0, 2)).toEqual([reasoning, second]) + expect(convertToResponsesApiInput([message])[2]).toMatchObject({ type: "function_call", call_id: "call1" }) +}) + +it.each([undefined, null, {}, { status: "completed" }])("accepts successful or legacy responses: %j", (response) => { + expect(() => assertResponsesApiSuccess(response)).not.toThrow() +}) + +it.each(["failed", "incomplete", "cancelled"])("rejects terminal status %s", (status) => { + expect(() => assertResponsesApiSuccess({ status, error: { message: "failure", code: "backend_error" } })).toThrow( + "failure", + ) +}) + +it("preserves terminal failure details", () => { + try { + assertResponsesApiSuccess({ status: "failed", error: { message: "failure", code: "backend_error" } }) + } catch (error) { + expect(error).toMatchObject({ + code: "backend_error", + errorDetails: { message: "failure", code: "backend_error" }, + }) + return + } + throw new Error("Expected terminal failure") +}) + +it("accepts a standalone encrypted reasoning item from existing history", () => { + const item = { type: "reasoning" as const, id: "rs1", encrypted_content: "opaque", summary: [] } + expect(convertToResponsesApiInput([item])).toEqual([item]) +}) + +const scope = responsesReasoningScope("https://gateway.example/v1") +const scoped = { ...reasoning, format: "openai-responses-v1", provider: providerIdentifiers.openai, endpoint: scope } + +it.each([ + { detail: scoped, endpoint: scope, replay: true }, + { detail: scoped, endpoint: responsesReasoningScope("https://other.example/v1"), replay: false }, + { detail: scoped, endpoint: undefined, replay: false }, + { detail: { ...scoped, provider: providerIdentifiers.xai }, endpoint: scope, replay: false }, + { detail: { ...scoped, endpoint: undefined }, endpoint: scope, replay: false }, + { detail: reasoning, endpoint: scope, replay: false }, +])("limits replay to matching ownership: %j", ({ detail, endpoint, replay }) => { + const message = { role: "assistant" as const, content: "answer", reasoning_details: [detail] } + const expected = [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "answer" }] }] + expect(convertToResponsesApiInput([message], endpoint)).toEqual(replay ? [reasoning, ...expected] : expected) + const standalone = { + ...detail, + type: "reasoning" as const, + summary: [{ type: "summary_text" as const, text: "summary" }], + } + expect(convertToResponsesApiInput([standalone], endpoint)).toEqual(replay ? [reasoning] : []) +}) + +it.each([reasoning, scoped])("excludes Responses reasoning from Chat Completions: %j", (detail) => { + const message = { role: "assistant" as const, content: "answer", reasoning_details: [detail] } + expect(convertToOpenAiMessages([message])).toEqual([{ role: "assistant", content: "answer" }]) +}) + +it("normalizes trailing slashes without storing URL secrets in ownership metadata", () => { + const url = "https://user:secret@gateway.example/v1?token=private" + expect(responsesReasoningScope(url + "/")).toBe(responsesReasoningScope(url)) + expect(responsesReasoningScope(url)).toMatch(/^[a-f0-9]{64}$/) +}) + +it("uses the top-level response message when nested error details are missing", () => { + expect(() => assertResponsesApiSuccess({ status: "failed", message: "backend unavailable" })).toThrow( + "backend unavailable", + ) +}) diff --git a/src/api/transform/__tests__/responses-api-stream.spec.ts b/src/api/transform/__tests__/responses-api-stream.spec.ts index 5d3b3827c0..f72aae82eb 100644 --- a/src/api/transform/__tests__/responses-api-stream.spec.ts +++ b/src/api/transform/__tests__/responses-api-stream.spec.ts @@ -1,20 +1,6 @@ import { processResponsesApiStream, createUsageNormalizer } from "../responses-api-stream" -// Helper to create an async iterable from events -async function* mockStream(events: any[]) { - for (const event of events) { - yield event - } -} - -// Helper to collect all chunks from a stream -async function collectChunks(stream: AsyncGenerator) { - const chunks = [] - for await (const chunk of stream) { - chunks.push(chunk) - } - return chunks -} +import { asyncStreamFrom as mockStream, collectStream as collectChunks } from "../../../test-utils/stream" const noopUsage = () => undefined @@ -145,7 +131,7 @@ describe("processResponsesApiStream", () => { const chunks = await collectChunks(processResponsesApiStream(stream, noopUsage)) - expect(chunks[0].arguments).toBe('{"key":"value"}') + expect(chunks[0]).toMatchObject({ type: "tool_call", arguments: '{"key":"value"}' }) }) it("should skip tool_call with missing call_id or name", async () => { @@ -270,7 +256,7 @@ describe("processResponsesApiStream", () => { describe("completion and usage", () => { it("should yield usage from response.completed", async () => { - const mockNormalize = (usage: any) => ({ + const mockNormalize = (usage: { input_tokens: number; output_tokens: number }) => ({ type: "usage" as const, inputTokens: usage.input_tokens, outputTokens: usage.output_tokens, @@ -289,7 +275,7 @@ describe("processResponsesApiStream", () => { }) it("should yield usage from response.done", async () => { - const mockNormalize = (usage: any) => ({ + const mockNormalize = (usage: { input_tokens: number; output_tokens: number }) => ({ type: "usage" as const, inputTokens: usage.input_tokens, outputTokens: usage.output_tokens, @@ -338,7 +324,7 @@ describe("processResponsesApiStream", () => { describe("full conversation stream", () => { it("should handle a complete stream with reasoning, text, and usage", async () => { - const mockNormalize = (usage: any) => ({ + const mockNormalize = (usage: { input_tokens: number; output_tokens: number }) => ({ type: "usage" as const, inputTokens: usage.input_tokens, outputTokens: usage.output_tokens, @@ -468,3 +454,68 @@ describe("createUsageNormalizer", () => { ) }) }) + +describe("Responses terminal failure contract", () => { + it.each([ + { type: "response.failed", response: { error: { message: "backend failed", code: "server_error" } } }, + { type: "response.incomplete", response: { incomplete_details: { reason: "content_filter" } } }, + { type: "response.cancelled", response: {} }, + { type: "error", code: "rate_limit_exceeded", message: "wire failed" }, + { type: "response.error", error: { message: "wire failed" } }, + { type: "response.completed", response: { status: "failed", error: { message: "failed completion" } } }, + ])("rejects $type before reporting successful usage", async (event) => { + const normalize = vi.fn() + const result = collectChunks(processResponsesApiStream(mockStream([event]), normalize)) + await expect(result).rejects.toThrow() + if ("code" in event) await expect(result).rejects.toMatchObject({ code: event.code }) + expect(normalize).not.toHaveBeenCalled() + }) + + it("preserves output-token-limit classification", async () => { + await expect( + collectChunks( + processResponsesApiStream( + mockStream([ + { + type: "response.incomplete", + response: { incomplete_details: { reason: "max_output_tokens" } }, + }, + ]), + noopUsage, + ), + ), + ).rejects.toMatchObject({ name: "OutputTokenLimitError" }) + }) + + it("reports output items on item and completion events", async () => { + const item = { type: "reasoning", id: "r1", encrypted_content: "opaque", summary: [] } + const capture = vi.fn() + await collectChunks( + processResponsesApiStream( + mockStream([ + { type: "response.output_item.done", item }, + { type: "response.completed", response: { status: "completed", output: [item] } }, + ]), + noopUsage, + { onOutputItem: capture }, + ), + ) + expect(capture.mock.calls).toEqual([[item], [item]]) + }) + it.each([undefined, null, [], [{ type: "reasoning", id: "r1" }]])( + "reports completion and its optional output snapshot once: %j", + async (output) => { + const completed = vi.fn() + const capture = vi.fn() + await collectChunks( + processResponsesApiStream( + mockStream([{ type: "response.completed", response: { status: "completed", output } }]), + noopUsage, + { onCompleted: completed, onOutputItem: capture }, + ), + ) + expect(completed.mock.calls).toEqual([[output ?? undefined]]) + expect(capture).not.toHaveBeenCalled() + }, + ) +}) diff --git a/src/api/transform/openai-format.ts b/src/api/transform/openai-format.ts index 50a4a6d015..d91f6917d2 100644 --- a/src/api/transform/openai-format.ts +++ b/src/api/transform/openai-format.ts @@ -323,7 +323,10 @@ export function convertToOpenAiMessages( return undefined } - return details.map((detail: any) => { + // Raw Responses items are endpoint-scoped and cannot be sent through Chat Completions. + const filtered = details.filter((detail) => detail?.type !== "reasoning") + if (!filtered.length) return undefined + return filtered.map((detail) => { // Strip `id` from openai-responses-v1 blocks because OpenAI's Responses API // requires `store: true` to persist reasoning blocks. Since we manage // conversation state client-side, we don't use `store: true`, and sending diff --git a/src/api/transform/responses-api-error.ts b/src/api/transform/responses-api-error.ts new file mode 100644 index 0000000000..248e09142e --- /dev/null +++ b/src/api/transform/responses-api-error.ts @@ -0,0 +1,31 @@ +import { OutputTokenLimitError } from "../providers/utils/output-token-limit-error" + +function asRecord(value: unknown): Record { + return value && typeof value === "object" ? (value as Record) : {} +} + +/** Rejects terminal failures before output or usage can be reported as a successful response. */ +export function assertResponsesApiSuccess(value: unknown, eventStatus?: string): void { + const response = asRecord(value) + const status = eventStatus ?? response.status + if (status !== "failed" && status !== "incomplete" && status !== "cancelled") return + const details = asRecord(response.incomplete_details) + if (status === "incomplete" && details.reason === "max_output_tokens") throw new OutputTokenLimitError() + const error = asRecord(response.error) + const message = + typeof error.message === "string" + ? error.message + : typeof response.message === "string" + ? response.message + : typeof details.reason === "string" + ? details.reason + : "No further details were provided" + throw Object.assign(new Error(`Responses API response ${status}: ${message}`), { + ...(typeof error.code === "string" + ? { code: error.code } + : typeof response.code === "string" + ? { code: response.code } + : {}), + errorDetails: response.error ?? response.incomplete_details, + }) +} diff --git a/src/api/transform/responses-api-input.ts b/src/api/transform/responses-api-input.ts index 9ef31be280..95c612b106 100644 --- a/src/api/transform/responses-api-input.ts +++ b/src/api/transform/responses-api-input.ts @@ -1,5 +1,9 @@ +import type OpenAI from "openai" +import { readReplayableResponsesReasoning } from "./responses-api-reasoning" import { Anthropic } from "@anthropic-ai/sdk" +export type ResponsesApiMessage = Anthropic.Messages.MessageParam | OpenAI.Responses.ResponseReasoningItem + /** * Converts Anthropic-format messages to the OpenAI Responses API input format. * @@ -13,10 +17,26 @@ import { Anthropic } from "@anthropic-ai/sdk" * @param messages - Array of Anthropic MessageParam objects * @returns Array of Responses API input items */ -export function convertToResponsesApiInput(messages: Anthropic.Messages.MessageParam[]): any[] { +export function convertToResponsesApiInput(messages: ResponsesApiMessage[], reasoningScope?: string): any[] { const input: any[] = [] for (const message of messages) { + const reasoning = readReplayableResponsesReasoning(message, reasoningScope) + if (reasoning) { + input.push(reasoning) + continue + } + if (!("role" in message)) continue + if ( + message.role === "assistant" && + "reasoning_details" in message && + Array.isArray(message.reasoning_details) + ) { + for (const detail of message.reasoning_details) { + const item = readReplayableResponsesReasoning(detail, reasoningScope) + if (item) input.push(item) + } + } if (typeof message.content === "string") { if (message.role === "assistant") { // Assistant messages use output_text in the Responses API format diff --git a/src/api/transform/responses-api-reasoning.ts b/src/api/transform/responses-api-reasoning.ts new file mode 100644 index 0000000000..32f2229641 --- /dev/null +++ b/src/api/transform/responses-api-reasoning.ts @@ -0,0 +1,56 @@ +import { providerIdentifiers } from "@roo-code/types" +import { createHash } from "node:crypto" +import type OpenAI from "openai" + +/** Reads only the fields needed to replay an opaque Responses reasoning item. */ +export function readResponsesReasoningItem(value: unknown): OpenAI.Responses.ResponseReasoningItem | undefined { + if (!value || typeof value !== "object") return undefined + const item = value as Record + if ( + item.type !== "reasoning" || + typeof item.id !== "string" || + !item.id || + typeof item.encrypted_content !== "string" || + !item.encrypted_content + ) + return undefined + const summary = item.summary ?? [] + if (!Array.isArray(summary)) return undefined + const summaries: OpenAI.Responses.ResponseReasoningItem.Summary[] = [] + for (const part of summary) { + if (!part || typeof part !== "object" || part.type !== "summary_text" || typeof part.text !== "string") + return undefined + summaries.push({ type: "summary_text", text: part.text }) + } + return { type: "reasoning", id: item.id, encrypted_content: item.encrypted_content, summary: summaries } +} + +export type ScopedResponsesReasoningItem = OpenAI.Responses.ResponseReasoningItem & { + format: "openai-responses-v1" + provider: "openai" + endpoint: string +} + +/** Identifies the effective SDK endpoint without storing URL credentials or query secrets. */ +export function responsesReasoningScope(baseURL: string): string { + return createHash("sha256").update(baseURL.replace(/\/+$/, "")).digest("hex") +} + +/** Tagged history is private to its originating provider and effective endpoint. */ +export function readReplayableResponsesReasoning( + value: unknown, + endpoint?: string, +): OpenAI.Responses.ResponseReasoningItem | undefined { + if (!value || typeof value !== "object") return undefined + const item = value as Record + if (endpoint !== undefined || item.format === "openai-responses-v1") { + if ( + endpoint === undefined || + item.format !== "openai-responses-v1" || + item.provider !== providerIdentifiers.openai || + item.endpoint !== endpoint + ) + return undefined + } + return readResponsesReasoningItem(value) +} diff --git a/src/api/transform/responses-api-stream.ts b/src/api/transform/responses-api-stream.ts index 1008bf5a1b..3f8e35cdfd 100644 --- a/src/api/transform/responses-api-stream.ts +++ b/src/api/transform/responses-api-stream.ts @@ -1,3 +1,4 @@ +import { assertResponsesApiSuccess } from "./responses-api-error" import type { ApiStream, ApiStreamUsageChunk } from "./stream" /** @@ -20,12 +21,26 @@ import type { ApiStream, ApiStreamUsageChunk } from "./stream" export async function* processResponsesApiStream( stream: AsyncIterable, normalizeUsage: (usage: any) => ApiStreamUsageChunk | undefined, + observer?: { + onOutputItem?: (item: unknown) => void + onCompleted?: (output?: readonly unknown[]) => void + }, ): ApiStream { // Track call_ids that were streamed via delta events so we don't double-execute // when response.output_item.done arrives for the same function call. const streamedCallIds = new Set() for await (const event of stream) { + if ( + event?.type === "response.failed" || + event?.type === "response.incomplete" || + event?.type === "response.cancelled" + ) { + assertResponsesApiSuccess(event.response ?? event, event.type.slice("response.".length)) + } + if (event?.type === "error" || event?.type === "response.error") { + assertResponsesApiSuccess(event, "failed") + } // Text content deltas if (event?.type === "response.output_text.delta" || event?.type === "response.text.delta") { if (event?.delta) { @@ -50,6 +65,7 @@ export async function* processResponsesApiStream( // Output item events — handle completed function calls and fallback text if (event?.type === "response.output_item.done") { const item = event?.item + observer?.onOutputItem?.(item) if (item?.type === "function_call" || item?.type === "tool_call") { const callId = item.call_id || item.tool_call_id || item.id const name = item.name || item.function?.name @@ -98,6 +114,10 @@ export async function* processResponsesApiStream( // Completion events — extract usage if (event?.type === "response.completed" || event?.type === "response.done") { + assertResponsesApiSuccess(event.response) + const output = Array.isArray(event.response?.output) ? event.response.output : undefined + if (observer?.onCompleted) observer.onCompleted(output) + else if (output) for (const item of output) observer?.onOutputItem?.(item) const usage = event?.response?.usage || event?.usage const usageData = normalizeUsage(usage) if (usageData) { diff --git a/src/core/config/__tests__/ProviderSettingsManager.spec.ts b/src/core/config/__tests__/ProviderSettingsManager.spec.ts index c77464f9f2..bbd6e3b0e5 100644 --- a/src/core/config/__tests__/ProviderSettingsManager.spec.ts +++ b/src/core/config/__tests__/ProviderSettingsManager.spec.ts @@ -714,12 +714,13 @@ describe("ProviderSettingsManager", () => { ) it.each([true, false, undefined])( - "round-trips OpenAI-compatible reasoning settings through profile storage when enabled is %s", + "round-trips OpenAI-compatible reasoning and Responses settings through profile storage when enabled is %s", async (enableReasoningEffort) => { const configuration: ProviderSettings = { apiProvider: providerIdentifiers.openai, openAiModelId: "custom-model", enableReasoningEffort, + openAiUseResponsesApi: enableReasoningEffort, reasoningEffort: "low", openAiCustomModelInfo: { ...openAiModelInfoSaneDefaults, reasoningEffort: "max" }, } @@ -730,6 +731,7 @@ describe("ProviderSettingsManager", () => { const reloadedManager = new ProviderSettingsManager(mockContext) const profile = await reloadedManager.getProfile({ name: "compatible" }) + expect(profile.openAiUseResponsesApi).toBe(enableReasoningEffort) expect(profile.enableReasoningEffort).toBe(enableReasoningEffort) expect(profile.reasoningEffort).toBe("low") expect(profile.openAiCustomModelInfo).toEqual(configuration.openAiCustomModelInfo) diff --git a/src/core/webview/__tests__/ClineProvider.spec.ts b/src/core/webview/__tests__/ClineProvider.spec.ts index 67b1e00853..1229822f13 100644 --- a/src/core/webview/__tests__/ClineProvider.spec.ts +++ b/src/core/webview/__tests__/ClineProvider.spec.ts @@ -4062,13 +4062,14 @@ describe("ClineProvider", () => { }) test.each([true, false, undefined])( - "returns saved OpenAI-compatible reasoning settings to the webview when enabled is %s", + "returns saved OpenAI-compatible reasoning and Responses settings to the webview when enabled is %s", async (enableReasoningEffort) => { await provider.resolveWebviewView(mockWebviewView) const configuration: ProviderSettings = { apiProvider: providerIdentifiers.openai, openAiModelId: "custom-model", enableReasoningEffort, + openAiUseResponsesApi: enableReasoningEffort, reasoningEffort: "low", openAiCustomModelInfo: { ...openAiModelInfoSaneDefaults, reasoningEffort: "max" }, } diff --git a/src/eslint-suppressions.json b/src/eslint-suppressions.json index d5b845997a..aac05668ad 100644 --- a/src/eslint-suppressions.json +++ b/src/eslint-suppressions.json @@ -404,11 +404,6 @@ "count": 2 } }, - "api/transform/__tests__/responses-api-stream.spec.ts": { - "@typescript-eslint/no-explicit-any": { - "count": 5 - } - }, "api/transform/__tests__/zai-format.spec.ts": { "@typescript-eslint/no-explicit-any": { "count": 3 @@ -441,7 +436,7 @@ }, "api/transform/openai-format.ts": { "@typescript-eslint/no-explicit-any": { - "count": 8 + "count": 7 } }, "api/transform/r1-format.ts": { diff --git a/webview-ui/src/components/settings/__tests__/SettingsView.spec.tsx b/webview-ui/src/components/settings/__tests__/SettingsView.spec.tsx index e4f1b9864f..6d76a43d64 100644 --- a/webview-ui/src/components/settings/__tests__/SettingsView.spec.tsx +++ b/webview-ui/src/components/settings/__tests__/SettingsView.spec.tsx @@ -34,6 +34,16 @@ vi.mock("../ApiOptions", () => ({ data-testid="set-other-field" onClick={() => setApiConfigurationField("openAiBaseUrl", "https://example.test")} /> + {String(apiConfiguration?.openAiUseResponsesApi)} +