diff --git a/packages/core/src/model-resolver.ts b/packages/core/src/model-resolver.ts index 3755ff94152..9a134a5296a 100644 --- a/packages/core/src/model-resolver.ts +++ b/packages/core/src/model-resolver.ts @@ -323,7 +323,7 @@ export const layer = Layer.effect( cost: selected.cost, limit: selected.limit, compaction: selected.compaction, - websocket: selected.websocket ?? true, + websocket: selected.websocket ?? false, } }) return Service.of({ diff --git a/packages/core/src/plugin/provider/azure.ts b/packages/core/src/plugin/provider/azure.ts index 0c8d0e8c379..06d3eb383b9 100644 --- a/packages/core/src/plugin/provider/azure.ts +++ b/packages/core/src/plugin/provider/azure.ts @@ -162,7 +162,10 @@ export const AzurePlugin = define({ draft.settings.baseURL, resolveResourceName(draft.settings, resourceName) ?? resourceName, ) - if (responsesWebSocketCapable(item.provider, draft)) draft.capabilities.responsesWebsockets = true + if (responsesWebSocketCapable(item.provider, draft)) { + draft.capabilities.responsesWebsockets = true + draft.websocket = true + } }) } } diff --git a/packages/core/src/plugin/provider/openai.ts b/packages/core/src/plugin/provider/openai.ts index 6227f5ec278..9ed574ff468 100644 --- a/packages/core/src/plugin/provider/openai.ts +++ b/packages/core/src/plugin/provider/openai.ts @@ -257,6 +257,7 @@ export const OpenAIPlugin = define({ for (const model of item.models.values()) { evt.model.update(item.provider.id, model.id, (draft) => { draft.capabilities.responsesWebsockets = true + draft.websocket = true }) } if (!chatgpt) return diff --git a/packages/core/src/session/runner/model.ts b/packages/core/src/session/runner/model.ts index 66fce538675..c8414150793 100644 --- a/packages/core/src/session/runner/model.ts +++ b/packages/core/src/session/runner/model.ts @@ -73,7 +73,7 @@ export const resolved = ( cost: options.cost, limit: options.limit, compaction: options.compaction, - websocket: options.websocket ?? true, + websocket: options.websocket ?? false, }) const layer = Layer.effect( diff --git a/packages/core/test/generate.test.ts b/packages/core/test/generate.test.ts index 1bc31eb48c6..65624e21773 100644 --- a/packages/core/test/generate.test.ts +++ b/packages/core/test/generate.test.ts @@ -94,7 +94,7 @@ resolverIt.effect("resolves dynamic models with their catalog metadata", () => capabilities: selected.capabilities, cost: selected.cost, limit: selected.limit, - websocket: true, + websocket: false, }) }), ) diff --git a/packages/core/test/plugin/provider-azure.test.ts b/packages/core/test/plugin/provider-azure.test.ts index 8aacb8dc37c..e0e2f5cbc17 100644 --- a/packages/core/test/plugin/provider-azure.test.ts +++ b/packages/core/test/plugin/provider-azure.test.ts @@ -488,13 +488,14 @@ describe("AzurePlugin", () => { yield* addPlugin() - expect( - required(yield* catalog.model.get(Provider.ID.azure, models.responses)).capabilities.responsesWebsockets, - ).toBe(true) - for (const modelID of [models.chat, models.preview, models.deploymentURL, models.gateway, models.nonAzure]) - expect( - required(yield* catalog.model.get(Provider.ID.azure, modelID)).capabilities.responsesWebsockets, - ).toBeUndefined() + const responses = required(yield* catalog.model.get(Provider.ID.azure, models.responses)) + expect(responses.capabilities.responsesWebsockets).toBe(true) + expect(responses.websocket).toBe(true) + for (const modelID of [models.chat, models.preview, models.deploymentURL, models.gateway, models.nonAzure]) { + const model = required(yield* catalog.model.get(Provider.ID.azure, modelID)) + expect(model.capabilities.responsesWebsockets).toBeUndefined() + expect(model.websocket).toBeUndefined() + } }), ), ) diff --git a/packages/core/test/plugin/provider-openai.test.ts b/packages/core/test/plugin/provider-openai.test.ts index 35b04435e9b..dc81004df95 100644 --- a/packages/core/test/plugin/provider-openai.test.ts +++ b/packages/core/test/plugin/provider-openai.test.ts @@ -207,6 +207,7 @@ describe("OpenAIPlugin", () => { expect(model.enabled).toBe(true) expect(model.limit).toEqual({ context: 1_050_000, input: 922_000, output: 128_000 }) expect(model.capabilities.responsesWebsockets).toBe(true) + expect(model.websocket).toBe(true) expect(direct.headers).not.toHaveProperty("originator") expect(direct.baseURL).toBe("https://api.openai.com/v1") expect(provider.headers).not.toHaveProperty("x-codex-beta-features") @@ -216,7 +217,7 @@ describe("OpenAIPlugin", () => { }), ) - it.effect("selects Azure WebSocket from capability unless the policy disables it", () => + it.effect("selects WebSocket only from explicit policy", () => Effect.gen(function* () { const credentials = yield* Credential.Service yield* credentials.create({ @@ -267,11 +268,13 @@ describe("OpenAIPlugin", () => { Effect.provideService(SessionModelTransport.Service, transport), ) - const prepared = yield* prepare() + const prepared = yield* prepare(true) + const defaulted = yield* prepare() const disabled = yield* prepare(false) expect(prepared.options.webSocket).toBe(executor) expect(prepared.options.http).toBeUndefined() + expect(defaulted.options.webSocket).toBeUndefined() expect(disabled.options.webSocket).toBeUndefined() }), ) diff --git a/packages/core/test/plugin/provider-xai.test.ts b/packages/core/test/plugin/provider-xai.test.ts index 9dbbacf2f40..e420771b2a5 100644 --- a/packages/core/test/plugin/provider-xai.test.ts +++ b/packages/core/test/plugin/provider-xai.test.ts @@ -69,7 +69,7 @@ describe("XAIPlugin", () => { }), ) - it.effect("marks xAI deployments as Responses WebSocket capable", () => + it.effect("keeps xAI Responses WebSockets opt-in", () => Effect.gen(function* () { const catalog = yield* Catalog.Service const providerID = Provider.ID.make("xai") @@ -82,9 +82,9 @@ describe("XAIPlugin", () => { yield* addPlugin() - expect((yield* catalog.model.get(providerID, Model.ID.make("grok-4.6")))?.capabilities.responsesWebsockets).toBe( - true, - ) + const model = yield* catalog.model.get(providerID, Model.ID.make("grok-4.6")) + expect(model?.capabilities.responsesWebsockets).toBe(true) + expect(model?.websocket).toBeUndefined() }), ) }) diff --git a/packages/schema/src/config/provider.ts b/packages/schema/src/config/provider.ts index b1a669b1d52..3f0bdea37b5 100644 --- a/packages/schema/src/config/provider.ts +++ b/packages/schema/src/config/provider.ts @@ -64,7 +64,7 @@ class Model extends Schema.Class("Config.Model")({ export class Info extends Schema.Class("Config.Provider")({ compaction: Provider.Compaction.pipe(optional), websocket: Schema.Boolean.pipe(optional).annotate({ - description: "Use the provider's WebSocket transport when the route supports it. Defaults to true.", + description: "Use the provider's WebSocket transport when the route supports it. Defaults to the built-in policy.", }), canonical: Provider.ID.pipe(optional), name: Schema.String.pipe(optional), diff --git a/packages/schema/src/model.ts b/packages/schema/src/model.ts index d1fe3abf95b..c42bde5f0e6 100644 --- a/packages/schema/src/model.ts +++ b/packages/schema/src/model.ts @@ -107,7 +107,7 @@ export const Info = Schema.Struct({ compatibility: Compatibility.pipe(optional), package: Provider.Package.pipe(optional), compaction: Provider.Compaction.pipe(optional), - /** Session WebSocket policy; omitted inherits the provider policy, which defaults to enabled. */ + /** Session WebSocket policy; omitted inherits the provider policy, then defaults to disabled. */ websocket: Schema.Boolean.pipe(optional), ...Provider.Overlays, capabilities: Capabilities, diff --git a/packages/schema/src/provider.ts b/packages/schema/src/provider.ts index 47a74c9bc7d..c83f8153544 100644 --- a/packages/schema/src/provider.ts +++ b/packages/schema/src/provider.ts @@ -59,7 +59,7 @@ export const Info = Schema.Struct({ activation: Activation, package: Package, compaction: Compaction.pipe(optional), - /** Session WebSocket policy for routes that support it; omitted means enabled. */ + /** Session WebSocket policy for routes that support it; omitted means disabled. */ websocket: Schema.Boolean.pipe(optional), ...Overlays, }) diff --git a/services/www/src/docs/content/config.mdx b/services/www/src/docs/content/config.mdx index 286ce603120..f63791089d4 100644 --- a/services/www/src/docs/content/config.mdx +++ b/services/www/src/docs/content/config.mdx @@ -538,7 +538,7 @@ headers, and model variants. } ``` -`websocket: false` on a provider or model keeps it on HTTP instead of the -session WebSocket; a model policy overrides the provider policy. +`websocket: true` on a provider or model opts into its supported session +WebSocket; a model policy overrides the provider policy. See the [providers guide](/providers) for credentials, custom endpoints, provider packages, the WebSocket transport, and model configuration. diff --git a/services/www/src/docs/content/providers.mdx b/services/www/src/docs/content/providers.mdx index 75c83cae648..0dcdf714eec 100644 --- a/services/www/src/docs/content/providers.mdx +++ b/services/www/src/docs/content/providers.mdx @@ -110,7 +110,7 @@ role for other Foundry models. If a request fails because the token belongs to a ## WebSocket transport -OpenAI, Azure, and xAI Responses models keep one WebSocket connection open per session and send each step over it +OpenAI and supported Azure Responses models keep one WebSocket connection open per session and send each step over it instead of opening a new HTTP request. While the request prefix is unchanged, consecutive steps only transmit what was added since the previous response, which cuts upload volume on long sessions. Provider compaction runs over the same connection. @@ -119,7 +119,8 @@ The connection is transparent. When the provider closes the socket, the next ste be opened at all, the session continues over HTTP. Plugins that register `http.request` or `http.response` hooks for a provider keep it on HTTP so the hooks observe every request. -Set `websocket: false` on a provider or model to keep it on HTTP; a model policy overrides the provider policy: +WebSockets are opt-in per built-in provider. Set `websocket: true` to enable a supported provider or model, or `false` +to disable a built-in opt-in; a model policy overrides the provider policy: ```jsonc title="opencode.jsonc" {