diff --git a/docs/gateway/config-tools/custom-providers.md b/docs/gateway/config-tools/custom-providers.md index a4d34b01e1dc..cb8091c89efe 100644 --- a/docs/gateway/config-tools/custom-providers.md +++ b/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. | diff --git a/packages/ai/src/providers/openai-responses-shared.test.ts b/packages/ai/src/providers/openai-responses-shared.test.ts index fb8a2eb30ce9..ef90084ac7ea 100644 --- a/packages/ai/src/providers/openai-responses-shared.test.ts +++ b/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>) { @@ -123,8 +114,13 @@ async function* responseEvents(events: Array>) { 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; diff --git a/packages/ai/src/providers/openai-responses-tools.integration.test.ts b/packages/ai/src/providers/openai-responses-tools.integration.test.ts index 8a4b7932f8fe..f30473dac5b6 100644 --- a/packages/ai/src/providers/openai-responses-tools.integration.test.ts +++ b/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); diff --git a/packages/ai/src/providers/openai-responses-tools.ts b/packages/ai/src/providers/openai-responses-tools.ts index 969e26c8c708..f975a4b33aec 100644 --- a/packages/ai/src/providers/openai-responses-tools.ts +++ b/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; diff --git a/packages/ai/src/providers/openai-responses.live.test.ts b/packages/ai/src/providers/openai-responses.live.test.ts index 6339ca96408b..5358a24783b4 100644 --- a/packages/ai/src/providers/openai-responses.live.test.ts +++ b/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(); diff --git a/packages/ai/src/transports/openai-responses-params-internal.ts b/packages/ai/src/transports/openai-responses-params-internal.ts index fff5249d5556..30bb6853ec28 100644 --- a/packages/ai/src/transports/openai-responses-params-internal.ts +++ b/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 ( diff --git a/packages/llm-core/src/types.ts b/packages/llm-core/src/types.ts index 2ca5f885010c..e2078e66f288 100644 --- a/packages/llm-core/src/types.ts +++ b/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. */