fix(ai): honor Responses strict-mode compatibility (#151416)

docs/gateway/config-tools/custom-providers.md

@@ -114,7 +114,7 @@ Configuring a custom/local provider `baseUrl` is also the narrow network trust d
     | `supportsUsageInStreaming` | Emits usage metadata in streaming responses. |
     | `supportsInstructions` | Responses API only: accepts the system prompt via top-level `instructions` instead of embedded in `input`. Defaults to `true` only for native OpenAI and xAI's main route — the two routes with confirmed contract evidence. Every other route, bundled or custom, defaults to `false`; set explicitly once verified against that endpoint. |
     | `supportsTools` | Supports structured tool/function calling. Set `false` to disable tools. |
-    | `supportsStrictMode` | Accepts strict tool schemas. |
+    | `supportsStrictMode` | Accepts the `strict` tool field. On compatible Completions and Responses routes, `true` permits explicit `strict: false` so optional tool arguments remain optional. |
     | `requiresStringContent` | Requires plain-string Chat Completions message content. |
     | `strictMessageKeys` | Requires outgoing messages to contain only accepted keys. |
     | `visibleReasoningDetailTypes` | Names reasoning detail block types safe to show in transcripts. |

packages/ai/src/providers/openai-responses-shared.test.ts

@@ -6,7 +6,7 @@ import type {
 } from "openai/resources/responses/responses.js";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { makeTextToolResult } from "../../../../test/helpers/text-tool-result.js";
-import { configureAiTransportHost } from "../host.js";
+import { configureAiTransportHost, getAiTransportHost } from "../host.js";
 import {
   buildOpenAIResponsesReasoningReplayMetadata,
   captureOpenAIResponsesCompaction,
@@ -102,16 +102,7 @@ const testAllowedToolCallProviders = new Set(["openai", "openai-codex", "opencod
 const reasoningReplayIdentity = { sessionId: "session-a", authProfileId: "profile-a" };
 
 function createAssistantOutput(): AssistantMessage {
-  return {
-    role: "assistant",
-    api: nativeOpenAIModel.api,
-    provider: nativeOpenAIModel.provider,
-    model: nativeOpenAIModel.id,
-    usage: createZeroUsage(),
-    stopReason: "stop",
-    timestamp: 0,
-    content: [],
-  };
+  return { ...createResponsesAssistantOutput(nativeOpenAIModel), timestamp: 0 };
 }
 
 async function* responseEvents(events: Array<Record<string, unknown>>) {
@@ -123,8 +114,13 @@ async function* responseEvents(events: Array<Record<string, unknown>>) {
 describe("convertResponsesToolPayload", () => {
   beforeEach(() => {
     // Mimic the OpenClaw host strict-tool policy: native OpenAI routes force
-    // strict=true, proxy-like routes leave the flag unset.
+    // strict=true; compatible routes opt in to sending strict=false.
+    const capabilities = getAiTransportHost().resolveProviderRequestCapabilities({});
     configureAiTransportHost({
+      resolveProviderRequestCapabilities: ({ baseUrl }) => ({
+        ...capabilities,
+        endpointClass: baseUrl === nativeOpenAIModel.baseUrl ? "openai-public" : "custom",
+      }),
       resolveOpenAIStrictToolSetting: (model, options) => {
         if (model.provider === "openai" && model.baseUrl === "https://api.openai.com/v1") {
           return true;

packages/ai/src/providers/openai-responses-tools.integration.test.ts

@@ -1,5 +1,5 @@
 import { expect, it } from "vitest";
-import { configureAiTransportHost } from "../host.js";
+import { configureAiTransportHost, getAiTransportHost } from "../host.js";
 import { createLlmRuntime } from "../stream.js";
 import { createOpenAIResponsesTransportStreamFn } from "../transports/openai-responses-client.js";
 import {
@@ -33,15 +33,35 @@ function completedResponseEvents() {
 
 it.each(
   (["provider", "transport"] as const).flatMap((entrypoint) =>
-    [true, false, undefined].map((strict) => ({ entrypoint, strict })),
+    [
+      { native: false, supportsStrictMode: true, strict: false },
+      { native: false, supportsStrictMode: false, strict: undefined },
+      { native: false, supportsStrictMode: undefined, strict: undefined },
+      { native: true, supportsStrictMode: undefined, strict: true },
+    ].map(({ native, supportsStrictMode, strict }) => ({
+      entrypoint,
+      native,
+      supportsStrictMode,
+      strict,
+    })),
   ),
-)("serializes $entrypoint Responses tools with strict=$strict", async ({ entrypoint, strict }) => {
+)("serializes $entrypoint Responses tools with strict=$strict", async (scenario) => {
+  const { entrypoint, native, supportsStrictMode, strict } = scenario;
   const server = await createResponsesLoopbackServer(completedResponseEvents);
-  configureAiTransportHost({ resolveOpenAIStrictToolSetting: () => strict });
+  const capabilities = getAiTransportHost().resolveProviderRequestCapabilities({});
+  configureAiTransportHost({
+    resolveProviderRequestCapabilities: () => ({
+      ...capabilities,
+      endpointClass: native ? "openai-public" : "custom",
+    }),
+    resolveOpenAIStrictToolSetting: (_model, options) =>
+      native ? true : options?.supportsStrictMode ? false : undefined,
+  });
+  const model = { ...responsesLoopbackModel, compat: { supportsStrictMode } };
   const parameters = Object.freeze({
     type: "object",
-    properties: Object.freeze({}),
-    required: Object.freeze([]),
+    properties: Object.freeze({ prompt: { type: "string" }, note: { type: "string" } }),
+    required: Object.freeze(native ? ["prompt", "note"] : ["prompt"]),
     additionalProperties: false,
   });
   let descriptionReads = 0;
@@ -88,12 +108,8 @@ it.each(
     for (let request = 0; request < 2; request++) {
       const stream =
         entrypoint === "provider"
-          ? runtime.stream(responsesLoopbackModel, context, options)
-          : await createOpenAIResponsesTransportStreamFn()(
-              responsesLoopbackModel,
-              context,
-              options,
-            );
+          ? runtime.stream(model, context, options)
+          : await createOpenAIResponsesTransportStreamFn()(model, context, options);
       for await (const event of stream) {
         if (event.type === "start" || event.type === "done" || event.type === "error") {
           lifecycle.push(event.type);

packages/ai/src/providers/openai-responses-tools.ts

@@ -1,6 +1,7 @@
 // OpenAI Responses tool helpers convert runtime tools to Responses API schemas.
 import type { FunctionTool } from "openai/resources/responses/responses.js";
 import { getAiTransportHost } from "../host.js";
+import { resolveOpenAICompletionsCompat } from "../transports/openai-completions-compat.js";
 import { resolveOpenAIStrictToolFlagWithDiagnostics } from "../transports/openai-transport-params.js";
 import type { Model, Tool } from "../types.js";
 import { sortPromptCacheToolsByName } from "../utils/prompt-cache-stability.js";
@@ -96,7 +97,9 @@ function resolveResponsesStrictToolSetting(
   if (options?.model) {
     return getAiTransportHost().resolveOpenAIStrictToolSetting(options.model, {
       transport: "stream",
-      supportsStrictMode: options.supportsStrictMode,
+      supportsStrictMode:
+        options.supportsStrictMode ??
+        resolveOpenAICompletionsCompat(options.model).supportsStrictMode,
     });
   }
   return false;

packages/ai/src/providers/openai-responses.live.test.ts

@@ -77,13 +77,13 @@ describeLive("OpenAI Responses live", () => {
   );
 
   it(
-    "keeps reasoning and tool-call items separable on a real interleaved stream",
+    "keeps reasoning and optional tool arguments on a compatible Responses route",
     async () => {
       const context: Context = {
         messages: [
           {
             role: "user",
-            content: "Call the live_probe tool with value set to exactly LIVE_OK.",
+            content: "Call the live_probe tool with value set to exactly LIVE_OK. Omit note.",
             timestamp: 0,
           },
         ],
@@ -91,15 +91,26 @@ describeLive("OpenAI Responses live", () => {
           {
             name: "live_probe",
             description: "Records a probe value.",
-            parameters: Type.Object({ value: Type.String() }),
+            parameters: Type.Object({ value: Type.String(), note: Type.Optional(Type.String()) }),
           },
         ],
       };
-      const result = await streamOpenAIResponses(liveModel(), context, {
-        apiKey: OPENAI_KEY,
-        maxTokens: 1024,
-        reasoningEffort: "low",
-      }).result();
+      let payload: unknown;
+      const result = await streamOpenAIResponses(
+        liveModel({
+          provider: "custom-openai",
+          compat: { supportsStrictMode: true },
+        }),
+        context,
+        {
+          apiKey: OPENAI_KEY,
+          maxTokens: 1024,
+          reasoningEffort: "low",
+          onPayload: (request) => {
+            payload = request;
+          },
+        },
+      ).result();
 
       expect(result.errorMessage).toBeUndefined();
       expect(result.stopReason).toBe("toolUse");
@@ -109,6 +120,9 @@ describeLive("OpenAI Responses live", () => {
       expect(probeCall?.name).toBe("live_probe");
       const probeArguments = (probeCall?.arguments ?? {}) as { value?: string };
       expect(probeArguments.value).toBe("LIVE_OK");
+      expect(probeArguments).not.toHaveProperty("note");
+      expect(payload).toHaveProperty("tools.0.strict", false);
+      expect(payload).toHaveProperty("tools.0.parameters.required", ["value"]);
       for (const block of result.content) {
         if (block.type === "thinking") {
           expect(block.thinkingSignature).toBeTruthy();

packages/ai/src/transports/openai-responses-params-internal.ts

@@ -279,6 +279,7 @@ export function buildOpenAIResponsesParams(
     const tools = context.tools;
     const strict = resolveOpenAIStrictToolSetting(model as OpenAIModeModel, {
       transport: "stream",
+      supportsStrictMode: compat.supportsStrictMode,
     });
     const { projection, tools: converted } = prepareResponsesTools(tools, strict, model);
     if (

packages/llm-core/src/types.ts

@@ -567,6 +567,8 @@ export interface OpenAICompletionsCompat {
 
 /** Compatibility settings for OpenAI Responses APIs. */
 export interface OpenAIResponsesCompat {
+  /** Whether a compatible provider accepts the `strict` tool field. Default: auto-detected from the endpoint. */
+  supportsStrictMode?: boolean;
   /** Whether the provider supports the `developer` role (vs `system`). Default: true. */
   supportsDeveloperRole?: boolean;
   /** Whether to send reasoning effort settings. Defaults to the model's known capabilities. */