fix(openai): use max_completion_tokens for gpt-5 + o-series models

Production paracosm broke after the per-call maxTokens caps shipped:
OpenAI's gpt-5.x and o-series (reasoning) models reject max_tokens with
HTTP 400 "Unsupported parameter: 'max_tokens' is not supported with
this model. Use 'max_completion_tokens' instead."

OpenAIProvider.buildPayload always sent max_tokens. Now sniffs the
model id via modelRequiresMaxCompletionTokens() and routes to either
max_tokens (legacy: gpt-4o, gpt-4-turbo, gpt-4.1, gpt-3.5) or
max_completion_tokens (new: gpt-5.x, o1, o3, o4). Same value,
different param name — the two are semantically equivalent within
each generation.

Errs conservative: unknown model ids (Anthropic, Llama, etc — not
that they reach this code path, but defensively) fall through to
max_tokens. Older deployments don't silently break when the param
flag changes.

6 vitest cases pin the routing decision across known model families
(gpt-5.x, o1/o3/o4, gpt-4o, gpt-4.1, gpt-3.5) and the case-insensitive
match logic. Streaming + non-streaming completions both flow through
the shared buildPayload path so the fix covers both.

Author: jddunn

src/core/llm/providers/implementations/OpenAIProvider.ts

@@ -166,6 +166,29 @@ type _OpenAIAPIErrorResponse = {
  * Provides an interface to OpenAI's suite of models (GPT, Embeddings).
  * It handles API requests, streaming, error management, and model information.
  */
+/**
+ * Whether the given model id belongs to the family that requires
+ * `max_completion_tokens` instead of the legacy `max_tokens` parameter.
+ *
+ * OpenAI's reasoning models (o1, o3, o4) and the GPT-5 family reject
+ * `max_tokens` outright with HTTP 400 "Unsupported parameter:
+ * 'max_tokens' is not supported with this model. Use
+ * 'max_completion_tokens' instead." Legacy chat completions
+ * (gpt-4o, gpt-4-turbo, gpt-4.1, gpt-3.5, etc.) still accept the
+ * old field.
+ *
+ * Errs on the conservative side — any model id that is not a clear
+ * member of one of the new families uses `max_tokens` so older
+ * deployments do not silently break when the param-name flag changes.
+ *
+ * @param modelId Provider-side model identifier (e.g. `'gpt-5.4-mini'`).
+ * @returns `true` when the model needs `max_completion_tokens`.
+ */
+export function modelRequiresMaxCompletionTokens(modelId: string): boolean {
+  // o1 / o3 / o4 reasoning models, plus GPT-5 family.
+  return /^(o\d|gpt-5)/i.test(modelId);
+}
+
 export class OpenAIProvider implements IProvider {
   /** @inheritdoc */
   public readonly providerId: string = 'openai';
@@ -614,7 +637,18 @@ export class OpenAIProvider implements IProvider {
 
     if (options.temperature !== undefined) payload.temperature = options.temperature;
     if (options.topP !== undefined) payload.top_p = options.topP;
-    if (options.maxTokens !== undefined) payload.max_tokens = options.maxTokens;
+    if (options.maxTokens !== undefined) {
+      // OpenAI's reasoning + GPT-5 model families reject `max_tokens`
+      // and require `max_completion_tokens` instead. Legacy chat
+      // completions (gpt-4o, gpt-4-turbo, gpt-3.5, etc.) keep
+      // `max_tokens`. The two fields are otherwise equivalent — same
+      // semantic meaning, just renamed in the newer API surface.
+      if (modelRequiresMaxCompletionTokens(modelId)) {
+        payload.max_completion_tokens = options.maxTokens;
+      } else {
+        payload.max_tokens = options.maxTokens;
+      }
+    }
     if (options.presencePenalty !== undefined) payload.presence_penalty = options.presencePenalty;
     if (options.frequencyPenalty !== undefined) payload.frequency_penalty = options.frequencyPenalty;
     if (options.stopSequences !== undefined) payload.stop = options.stopSequences;

src/core/llm/providers/tests/openai-max-completion-tokens.spec.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Tests for the model-id sniff that decides whether to
+ * send `max_tokens` (legacy) or `max_completion_tokens` (newer
+ * reasoning + GPT-5 families) to the OpenAI API.
+ */
+import { describe, it, expect } from 'vitest';
+import { modelRequiresMaxCompletionTokens } from '../implementations/OpenAIProvider.js';
+
+describe('modelRequiresMaxCompletionTokens', () => {
+  it('returns true for the GPT-5 family', () => {
+    expect(modelRequiresMaxCompletionTokens('gpt-5')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('gpt-5.4')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('gpt-5.4-mini')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('gpt-5.4-nano')).toBe(true);
+  });
+
+  it('returns true for o-series reasoning models', () => {
+    expect(modelRequiresMaxCompletionTokens('o1')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('o1-mini')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('o3')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('o3-mini')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('o4-mini')).toBe(true);
+  });
+
+  it('returns false for legacy gpt-4 family models that still accept max_tokens', () => {
+    expect(modelRequiresMaxCompletionTokens('gpt-4o')).toBe(false);
+    expect(modelRequiresMaxCompletionTokens('gpt-4o-mini')).toBe(false);
+    expect(modelRequiresMaxCompletionTokens('gpt-4-turbo')).toBe(false);
+    expect(modelRequiresMaxCompletionTokens('gpt-4.1')).toBe(false);
+    expect(modelRequiresMaxCompletionTokens('gpt-4.1-mini')).toBe(false);
+  });
+
+  it('returns false for gpt-3.5 + chat completions models', () => {
+    expect(modelRequiresMaxCompletionTokens('gpt-3.5-turbo')).toBe(false);
+  });
+
+  it('is case-insensitive', () => {
+    expect(modelRequiresMaxCompletionTokens('GPT-5')).toBe(true);
+    expect(modelRequiresMaxCompletionTokens('O1-Mini')).toBe(true);
+  });
+
+  it('errs conservative for unknown model ids — uses legacy max_tokens', () => {
+    expect(modelRequiresMaxCompletionTokens('claude-sonnet-4-6')).toBe(false);
+    expect(modelRequiresMaxCompletionTokens('llama3:8b')).toBe(false);
+    expect(modelRequiresMaxCompletionTokens('mystery-model')).toBe(false);
+  });
+});