@startsimpli/llm 0.4.18 → 0.4.20

package/README.md

@@ -60,6 +60,7 @@ The factories read from `process.env` and return `null` when nothing is configur
 | `OPENAI_API_KEY` | `createOpenAIProvider()` | unset → provider disabled |
 | `OPENAI_BASE_URL` | `createOpenAIProvider()` | `https://api.openai.com/v1` |
 | `OPENAI_MODEL` | `createOpenAIProvider()` | `gpt-4o-mini` (`LLM_DEFAULTS.openaiModel`) |
+| `OPENAI_REASONING_EFFORT` | `createOpenAIProvider()` | unset (API default). gpt-5 family only: `none`, `low`, `medium`, `high` (gpt-5.5 rejects `minimal`). `maxTokens` stays the answer budget; reasoning headroom is added on top. |
 | `ANTHROPIC_API_KEY` | `createAnthropicProvider()` | unset → provider disabled |
 | `ANTHROPIC_BASE_URL` | `createAnthropicProvider()` | `https://api.anthropic.com/v1` |
 | `ANTHROPIC_MODEL` | `createAnthropicProvider()` | `claude-sonnet-4-20250514` (`LLM_DEFAULTS.anthropicModel`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/openai-provider.test.ts

@@ -32,6 +32,7 @@ interface Sent {
   temperature?: number;
   max_tokens?: number;
   max_completion_tokens?: number;
+  reasoning_effort?: string;
 }
 
 const OK_BODY = {
@@ -63,64 +64,136 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
-describe('the token-limit parameter', () => {
-  it.each(['gpt-5', 'gpt-5.1', 'gpt-5.2'])(
-    '%s gets max_completion_tokens and never max_tokens',
+/** Make the next fetch answer 400 with an OpenAI error body (formats captured from the API 2026-10-02). */
+function reject(error: { message: string; code?: string | null; param?: string | null }) {
+  fetchMock.mockImplementationOnce(async (_url: unknown, init: RequestInit) => {
+    sent.push(JSON.parse(String(init.body)) as Sent);
+    return { ok: false, status: 400, json: async () => ({ error: { type: 'invalid_request_error', ...error } }) } as unknown as Response;
+  });
+}
+
+describe('any model the account can call works: no model-name rules', () => {
+  it.each(['gpt-4o', 'gpt-4o-mini', 'ft:gpt-4.1-mini-2025-04-14:org:x:1', 'gpt-5.5', 'gpt-6.1-sol', 'some-model-nobody-has-heard-of'])(
+    '%s gets max_completion_tokens (accepted by every chat model) and never max_tokens',
     async (model) => {
       await provider(model).generate('u', 's');
-
       expect(sent[0]!.max_completion_tokens).toBeGreaterThan(0);
       expect(sent[0]!.max_tokens).toBeUndefined();
     },
   );
 
-  it('an UNRELEASED gpt-5 model is handled by family, not by a hardcoded list', async () => {
-    // bd startsim-768w.38.26. The day this id ships, a literal deny-list sends
-    // it max_tokens and every call 400s — silently, from the caller's view.
-    await provider('gpt-5.3').generate('u', 's');
-
-    expect(sent[0]!.max_completion_tokens).toBeGreaterThan(0);
-    expect(sent[0]!.max_tokens).toBeUndefined();
+  it('sends the configured temperature to every model until one refuses it', async () => {
+    await provider('gpt-6-sol').generate('u', 's');
+    await provider('gpt-4o').generate('u', 's');
+    expect(sent.map((b) => b.temperature)).toEqual([0.2, 0.2]);
   });
+});
 
-  it('gpt-4o keeps max_tokens, which it accepts', async () => {
-    // The fix must not break the models that were working.
-    await provider('gpt-4o').generate('u', 's');
+describe('adapting to what a model refuses', () => {
+  it('drops temperature when the model only takes its default, and remembers', async () => {
+    const p = provider('gpt-6-sol');
+    reject({ code: 'unsupported_value', param: 'temperature', message: "Unsupported value: 'temperature' does not support 0.2 with this model. Only the default (1) value is supported." });
+    const res = await p.generate('u', 's');
+    expect(res.content).toBe('{"ok":true}');
+    expect(sent).toHaveLength(2);
+    expect(sent[0]!.temperature).toBe(0.2);
+    expect(sent[1]!.temperature).toBeUndefined();
+    // second call: no retry, temperature already known to be refused
+    await p.generate('u', 's');
+    expect(sent).toHaveLength(3);
+    expect(sent[2]!.temperature).toBeUndefined();
+  });
 
-    expect(sent[0]!.max_tokens).toBeGreaterThan(0);
-    expect(sent[0]!.max_completion_tokens).toBeUndefined();
+  it('moves to the nearest supported reasoning effort the API lists', async () => {
+    const p = provider('gpt-6.1-sol');
+    reject({ code: 'unsupported_value', param: 'reasoning_effort', message: "Unsupported value: 'reasoning_effort' does not support 'none' with this model. Supported values are: 'low', 'medium', 'high', and 'xhigh'." });
+    await p.generate('u', 's', { reasoningEffort: 'none', maxTokens: 256 });
+    expect(sent[0]!.reasoning_effort).toBe('none');
+    expect(sent[1]!.reasoning_effort).toBe('low');
+    expect(sent[1]!.max_completion_tokens).toBeGreaterThan(256); // headroom for the effort actually sent
+    await p.generate('u', 's', { reasoningEffort: 'none' });
+    expect(sent[2]!.reasoning_effort).toBe('low');
   });
 
-  it('honours an explicit maxTokens on whichever parameter the model takes', async () => {
-    await provider('gpt-5.2').generate('u', 's', { maxTokens: 123 });
-    await provider('gpt-4o').generate('u', 's', { maxTokens: 123 });
+  it('drops reasoning_effort for a model that does not reason', async () => {
+    const p = provider('gpt-4o');
+    reject({ code: null, param: null, message: 'Unrecognized request argument supplied: reasoning_effort' });
+    await p.generate('u', 's', { reasoningEffort: 'low', maxTokens: 300 });
+    expect(sent[1]!.reasoning_effort).toBeUndefined();
+    expect(sent[1]!.max_completion_tokens).toBe(300); // no reasoning, no headroom
+  });
 
-    expect(sent[0]!.max_completion_tokens).toBe(123);
-    expect(sent[1]!.max_tokens).toBe(123);
+  it('clamps the token cap to what the model says it supports', async () => {
+    const p = provider('gpt-4o');
+    reject({ code: 'invalid_value', param: 'max_tokens', message: 'max_tokens is too large: 20288. This model supports at most 16384 completion tokens, whereas you provided 20288.' });
+    await p.generate('u', 's', { maxTokens: 8000 });
+    expect(sent[1]!.max_completion_tokens).toBe(16384);
   });
-});
 
-describe('temperature', () => {
-  it.each(['gpt-5', 'gpt-5.1', 'gpt-5.2', 'gpt-5.3'])(
-    '%s is sent temperature 1.0, whatever the deployment configured',
-    async (model) => {
-      // Base gpt-5 models reject any other value.
-      await provider(model).generate('u', 's', { temperature: 0.2 });
+  it('does not loop: an error it cannot act on, or the same lesson twice, throws', async () => {
+    const p = provider('gpt-6-sol');
+    reject({ code: 'invalid_value', param: 'messages', message: 'Invalid messages.' });
+    await expect(p.generate('u', 's')).rejects.toThrow();
+    expect(sent).toHaveLength(1);
+
+    const q = provider('gpt-6-sol');
+    const tempErr = { code: 'unsupported_value', param: 'temperature', message: "Unsupported value: 'temperature' does not support 0.2 with this model." };
+    reject(tempErr);
+    reject(tempErr);
+    await expect(q.generate('u', 's')).rejects.toThrow();
+    expect(sent).toHaveLength(3);
+  });
 
-      expect(sent[0]!.temperature).toBe(1.0);
-    },
-  );
+  it('adapts on the tool-calling path too', async () => {
+    const p = provider('gpt-6-sol');
+    reject({ code: 'unsupported_value', param: 'temperature', message: "Unsupported value: 'temperature' does not support 0.2 with this model. Only the default (1) value is supported." });
+    fetchMock.mockImplementationOnce(async (_url: unknown, init: RequestInit) => {
+      sent.push(JSON.parse(String(init.body)) as Sent);
+      return { ok: true, status: 200, json: async () => ({ ...OK_BODY, choices: [{ index: 0, message: { role: 'assistant', content: 'done' }, finish_reason: 'stop' }] }) } as unknown as Response;
+    });
+    const res = await p.generateWithTools([{ role: 'user', content: 'hi' }], 's', []);
+    expect(res.content).toBe('done');
+    expect(sent[1]!.temperature).toBeUndefined();
+  });
+});
 
-  it('a FINE-TUNED gpt-5 keeps the configured temperature', async () => {
-    // The existing carve-out, preserved: ft: models do accept it.
-    await provider('ft:gpt-5.2:acme::abc123').generate('u', 's', { temperature: 0.2 });
+/*
+ * MEASURED 2026-10-02 against gpt-5.5-2026-04-23, a 256-token structured call:
+ *   effort unset (API default) -> empty content: reasoning ate the whole cap
+ *   none   -> 2.3s, 35 completion tokens, 0 reasoning
+ *   low    -> 2.8s, 130 completion tokens, 91 reasoning
+ *   medium -> 42.8s, 412 completion tokens, 377 reasoning
+ * Hidden reasoning is billed against max_completion_tokens, so a caller's
+ * answer budget gets headroom.
+ */
+describe('reasoning effort and headroom', () => {
+  it('sends reasoning_effort when one is given, and omits it otherwise', async () => {
+    await provider('gpt-5.5').generate('u', 's', { reasoningEffort: 'low' });
+    await provider('gpt-5.5').generate('u', 's');
+    expect(sent[0]!.reasoning_effort).toBe('low');
+    expect(sent[1]!.reasoning_effort).toBeUndefined();
+  });
 
-    expect(sent[0]!.temperature).toBe(0.2);
+  it('takes the default effort from the provider config', async () => {
+    await new OpenAIProvider({ apiKey: 'k', defaultModel: 'gpt-5.5', defaultReasoningEffort: 'low' }).generate('u', 's');
+    expect(sent[0]!.reasoning_effort).toBe('low');
   });
 
-  it('gpt-4o keeps the configured temperature', async () => {
-    await provider('gpt-4o').generate('u', 's', { temperature: 0.2 });
+  it('adds reasoning headroom on top of the answer budget, scaled to the effort', async () => {
+    await provider('gpt-5.5').generate('u', 's', { maxTokens: 256, reasoningEffort: 'none' });
+    await provider('gpt-5.5').generate('u', 's', { maxTokens: 256, reasoningEffort: 'low' });
+    await provider('gpt-5.5').generate('u', 's', { maxTokens: 256 });
+    const [none, low, unset] = sent.map((b) => b.max_completion_tokens!);
+    expect(none).toBe(256);
+    expect(low).toBeGreaterThanOrEqual(256 + 1000);
+    expect(unset).toBeGreaterThan(low); // unset = the API default (medium)
+  });
+});
 
-    expect(sent[0]!.temperature).toBe(0.2);
+describe('response provenance', () => {
+  it('reports the provider and the model the API says answered', async () => {
+    const res = await provider('gpt-5.5').generate('u', 's');
+    expect(res.provider).toBe('openai');
+    expect(res.model).toBe('server-reported-model');
   });
 });

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   TokenUsage,
   LLMResponse,
   GenerateOptions,
+  ReasoningEffort,
   ProviderConfig,
   JsonExtractionResult,
   ValidationResult,

package/src/providers/anthropic.ts

@@ -151,7 +151,7 @@ export class AnthropicProvider implements ILLMProvider {
   readonly availableModels = ANTHROPIC_MODELS;
   readonly defaultModel: string;
 
-  private readonly config: Required<ProviderConfig>;
+  private readonly config: Required<Omit<ProviderConfig, 'defaultReasoningEffort'>>;
   private readonly apiVersion: string;
 
   constructor(config: ProviderConfig, apiVersion?: string) {
@@ -246,6 +246,7 @@ Please respond with a valid JSON object only. Do not include any text before or
           totalTokens: data.usage.input_tokens + data.usage.output_tokens,
         },
         model: data.model,
+        provider: this.name,
         responseId: data.id,
         finishReason: data.stop_reason ?? undefined,
       };

package/src/providers/mock.ts

@@ -88,6 +88,7 @@ export class MockLLMProvider implements ILLMProvider {
         content: mockBehavior.customResponse,
         usage: { promptTokens: 100, completionTokens: 500, totalTokens: 600 },
         model: this.defaultModel,
+        provider: this.name,
         responseId: `mock-${this.callCount}`,
         finishReason: 'stop',
       };
@@ -98,6 +99,7 @@ export class MockLLMProvider implements ILLMProvider {
         content: getInvalidResponse(),
         usage: { promptTokens: 100, completionTokens: 200, totalTokens: 300 },
         model: this.defaultModel,
+        provider: this.name,
         responseId: `mock-${this.callCount}`,
         finishReason: 'stop',
       };
@@ -107,6 +109,7 @@ export class MockLLMProvider implements ILLMProvider {
       content: getDefaultResponse(),
       usage: { promptTokens: 150, completionTokens: 800, totalTokens: 950 },
       model: this.defaultModel,
+      provider: this.name,
       responseId: `mock-${this.callCount}`,
       finishReason: 'stop',
     };

package/src/providers/openai.ts

@@ -17,6 +17,7 @@ import type {
   NativeToolSpec,
   NativeChatMessage,
   NativeToolResponse,
+  ReasoningEffort,
 } from '../types';
 import { LLM_DEFAULTS } from '../types';
 import { LLMProviderError } from '../errors';
@@ -31,35 +32,129 @@ interface OpenAIRequest {
   model: string;
   messages: OpenAIMessage[];
   temperature?: number;
-  /** Pre-gpt-5 models. Rejected outright by the gpt-5 family. */
-  max_tokens?: number;
-  /** The gpt-5 family's replacement for `max_tokens`. */
+  /** Accepted by every current chat model; `max_tokens` is rejected by reasoning models. */
   max_completion_tokens?: number;
+  /** Reasoning models only; dropped automatically for models that reject it. */
+  reasoning_effort?: ReasoningEffort;
   response_format?: { type: 'json_object' | 'text' };
 }
 
 /**
- * Is this the gpt-5 FAMILY? Matched by prefix, deliberately, not by a list of
- * ids (bd startsim-768w.38.26 filed the literal-id deny-list as a bug: it is
- * "correct only until OpenAI ships gpt-5.3", and the failure is a silent 400).
- * `ft:gpt-5…` fine-tunes are still gpt-5 models on the wire.
+ * WHAT A MODEL ACCEPTS IS LEARNED FROM THE API, NOT GUESSED FROM ITS NAME.
+ *
+ * The provider used to pick parameters by matching the model id (`gpt-5…` got
+ * max_completion_tokens and temperature 1.0). Every new family broke that:
+ * gpt-6* were treated as legacy and 400'd on every call. Any model the account
+ * can call must work, so requests are built in the modern shape and adapted
+ * when the API says why it refused (measured 2026-10-02):
+ *
+ *   max_completion_tokens  accepted by every chat model tried (gpt-4o,
+ *                          gpt-4o-mini, a gpt-4.1 fine-tune, gpt-5.x, gpt-6.x);
+ *                          `max_tokens` is rejected by all reasoning models.
+ *   temperature            400 unsupported_value param=temperature on reasoning
+ *                          models ("Only the default (1) value is supported")
+ *                          -> drop it.
+ *   reasoning_effort       non-reasoning models: "Unrecognized request argument
+ *                          supplied: reasoning_effort" -> drop it. Unsupported
+ *                          level: "Supported values are: 'low', 'medium', ..."
+ *                          -> nearest supported at or above the one asked for.
+ *   token cap              400 invalid_value "This model supports at most N
+ *                          completion tokens" -> clamp to N.
+ *
+ * Each lesson is remembered per model for the life of the provider, so only the
+ * first call to a model pays for the retry.
  */
-function isGpt5Family(model: string): boolean {
-  return /^gpt-5/.test(model.startsWith('ft:') ? model.slice(3) : model);
+interface ModelQuirks {
+  noTemperature?: boolean;
+  noReasoningEffort?: boolean;
+  /** Reasoning efforts this model accepts, when the API has told us. */
+  efforts?: ReasoningEffort[];
+  /** Largest completion-token cap this model accepts. */
+  maxOutput?: number;
+}
+
+const EFFORT_ORDER: ReasoningEffort[] = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'];
+
+/** The supported effort closest to the one asked for, preferring more reasoning over less. */
+function nearestEffort(want: ReasoningEffort, supported: ReasoningEffort[]): ReasoningEffort | undefined {
+  const rank = EFFORT_ORDER.indexOf(want);
+  const sorted = [...supported].sort((a, b) => EFFORT_ORDER.indexOf(a) - EFFORT_ORDER.indexOf(b));
+  return sorted.find((e) => EFFORT_ORDER.indexOf(e) >= rank) ?? sorted[sorted.length - 1];
 }
 
 /**
- * The token-limit parameter this model accepts. MEASURED against api.openai.com
- * on 2026-08-19: gpt-5.2 rejects `max_tokens` with "Unsupported parameter ...
- * Use 'max_completion_tokens' instead", while gpt-4o accepts `max_tokens`.
- * Sending the wrong one is a total outage of that model, not a degraded call.
+ * Update `q` from a 400. Returns true when the request can be retried with
+ * different parameters, false when the error is not about parameters.
  */
-function tokenLimitParam(model: string, maxTokens: number): Partial<OpenAIRequest> {
-  return isGpt5Family(model)
-    ? { max_completion_tokens: maxTokens }
-    : { max_tokens: maxTokens };
+function learnFromError(q: ModelQuirks, err: OpenAIErrorResponse['error'] | undefined, sent: { effort?: ReasoningEffort; maxTokens: number }): boolean {
+  if (!err?.message) return false;
+  const msg = err.message;
+  if (err.param === 'temperature' || /'temperature'/.test(msg)) {
+    if (q.noTemperature) return false;
+    q.noTemperature = true;
+    return true;
+  }
+  if (err.param === 'reasoning_effort' || /reasoning_effort/.test(msg)) {
+    const listed = [...msg.matchAll(/'([a-z]+)'/g)].map((m) => m[1]).filter((v): v is ReasoningEffort => (EFFORT_ORDER as string[]).includes(v));
+    const supported = listed.filter((v) => v !== sent.effort);
+    if (/Supported values/i.test(msg) && supported.length) {
+      if (q.efforts && q.efforts.join() === supported.join()) return false;
+      q.efforts = supported;
+      return true;
+    }
+    if (q.noReasoningEffort) return false;
+    q.noReasoningEffort = true;
+    return true;
+  }
+  const most = /at most (\d+) completion tokens/i.exec(msg);
+  if (most) {
+    const max = Number(most[1]);
+    if (!(max > 0) || (q.maxOutput !== undefined && q.maxOutput <= max)) return false;
+    q.maxOutput = max;
+    return true;
+  }
+  return false;
 }
 
+/**
+ * Tokens to allow for hidden reasoning, which reasoning models bill against
+ * max_completion_tokens: a caller's maxTokens is the size of the ANSWER. Unset
+ * means the API's default effort (medium on gpt-5.5). Measured on gpt-5.5: low
+ * reasoned ~90 tokens and medium ~380 on a small structured call; large outputs
+ * reason far more, so these are generous ceilings, not estimates. A cap is not
+ * a charge, and a model that rejects a cap this large gets it clamped.
+ */
+function reasoningHeadroom(effort?: ReasoningEffort): number {
+  switch (effort) {
+    case 'none': return 0;
+    case 'minimal': return 1024;
+    case 'low': return 4096;
+    case 'high': return 24576;
+    case 'xhigh': return 32768;
+    case 'medium':
+    default: return 12288;
+  }
+}
+
+/** The sampling half of a request, shaped by what this model has told us it accepts. */
+function samplingParams(
+  q: ModelQuirks,
+  temperature: number,
+  maxTokens: number,
+  effort?: ReasoningEffort,
+): Pick<OpenAIRequest, 'temperature' | 'max_completion_tokens' | 'reasoning_effort'> {
+  const sentEffort = q.noReasoningEffort || !effort ? undefined : (q.efforts ? nearestEffort(effort, q.efforts) : effort);
+  const headroom = q.noReasoningEffort ? 0 : reasoningHeadroom(sentEffort);
+  const cap = maxTokens + headroom;
+  return {
+    ...(q.noTemperature ? {} : { temperature }),
+    max_completion_tokens: q.maxOutput !== undefined ? Math.min(cap, q.maxOutput) : cap,
+    ...(sentEffort ? { reasoning_effort: sentEffort } : {}),
+  };
+}
+
+const MAX_ADAPTIVE_RETRIES = 3;
+
 interface OpenAIResponse {
   id: string;
   object: string;
@@ -139,7 +234,15 @@ export class OpenAIProvider implements ILLMProvider {
   readonly availableModels = OPENAI_MODELS;
   readonly defaultModel: string;
 
-  private readonly config: Required<ProviderConfig>;
+  private readonly config: Required<Omit<ProviderConfig, 'defaultReasoningEffort'>> & Pick<ProviderConfig, 'defaultReasoningEffort'>;
+  /** What each model has told us it accepts (see learnFromError). */
+  private readonly quirks = new Map<string, ModelQuirks>();
+
+  private quirksFor(model: string): ModelQuirks {
+    let q = this.quirks.get(model);
+    if (!q) { q = {}; this.quirks.set(model, q); }
+    return q;
+  }
 
   constructor(config: ProviderConfig) {
     this.config = {
@@ -149,10 +252,42 @@ export class OpenAIProvider implements ILLMProvider {
       defaultTemperature: config.defaultTemperature ?? DEFAULTS.temperature,
       defaultMaxTokens: config.defaultMaxTokens ?? DEFAULTS.maxTokens,
       timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
+      defaultReasoningEffort: config.defaultReasoningEffort,
     };
     this.defaultModel = this.config.defaultModel;
   }
 
+  /**
+   * POST a chat completion, adapting the request when the API rejects a
+   * parameter this model doesn't take (see learnFromError). Non-parameter
+   * errors, and a parameter error we can't act on, throw as before.
+   */
+  private async postAdaptively<T>(
+    model: string,
+    build: (q: ModelQuirks) => object,
+    sent: { effort?: ReasoningEffort; maxTokens: number },
+    signal: AbortSignal,
+  ): Promise<T> {
+    const q = this.quirksFor(model);
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(build(q)),
+        signal,
+      });
+      if (response.ok) return (await response.json()) as T;
+      const errorData = (await response.json().catch(() => ({
+        error: { message: 'Unknown error' },
+      }))) as OpenAIErrorResponse;
+      if (response.status === 400 && attempt < MAX_ADAPTIVE_RETRIES && learnFromError(q, errorData.error, sent)) continue;
+      throw this.handleApiError(response.status, errorData);
+    }
+  }
+
   isAvailable(): boolean {
     return Boolean(this.config.apiKey);
   }
@@ -173,51 +308,31 @@ export class OpenAIProvider implements ILLMProvider {
     }
 
     const model = options?.model ?? this.config.defaultModel;
-    // Base gpt-5 models require temperature=1.0, but fine-tuned models use configured temperature
-    const isFineTuned = model.startsWith('ft:');
-    const isBaseGpt5 = isGpt5Family(model) && !isFineTuned;
-    const temperature = isBaseGpt5
-      ? 1.0
-      : (options?.temperature ?? this.config.defaultTemperature);
+    const temperature = options?.temperature ?? this.config.defaultTemperature;
     const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
+    const effort = options?.reasoningEffort ?? this.config.defaultReasoningEffort;
     const timeout = options?.timeout ?? this.config.timeoutMs;
 
-    const requestBody: OpenAIRequest = {
+    const base = {
       model,
       messages: [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: userPrompt },
+        { role: 'system' as const, content: systemPrompt },
+        { role: 'user' as const, content: userPrompt },
       ],
-      temperature,
-      ...tokenLimitParam(model, maxTokens),
-      response_format: { type: 'json_object' },
+      response_format: { type: 'json_object' as const },
     };
 
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
 
     try {
-      const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${this.config.apiKey}`,
-        },
-        body: JSON.stringify(requestBody),
-        signal: controller.signal,
-      });
+      const data = await this.postAdaptively<OpenAIResponse>(model, (q) => ({
+        ...base,
+        ...samplingParams(q, temperature, maxTokens, effort),
+      }), { effort, maxTokens }, controller.signal);
 
       clearTimeout(timeoutId);
 
-      if (!response.ok) {
-        const errorData = (await response.json().catch(() => ({
-          error: { message: 'Unknown error' },
-        }))) as OpenAIErrorResponse;
-        throw this.handleApiError(response.status, errorData);
-      }
-
-      const data = (await response.json()) as OpenAIResponse;
-
       if (!data.choices?.[0]?.message?.content) {
         throw new LLMProviderError(
           'Empty response from OpenAI',
@@ -236,6 +351,7 @@ export class OpenAIProvider implements ILLMProvider {
           totalTokens: data.usage.total_tokens,
         },
         model: data.model,
+        provider: this.name,
         responseId: data.id,
         finishReason: data.choices[0].finish_reason,
       };
@@ -289,12 +405,9 @@ export class OpenAIProvider implements ILLMProvider {
     }
 
     const model = options?.model ?? this.config.defaultModel;
-    const isFineTuned = model.startsWith('ft:');
-    const isBaseGpt5 = isGpt5Family(model) && !isFineTuned;
-    const temperature = isBaseGpt5
-      ? 1.0
-      : (options?.temperature ?? this.config.defaultTemperature);
+    const temperature = options?.temperature ?? this.config.defaultTemperature;
     const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
+    const effort = options?.reasoningEffort ?? this.config.defaultReasoningEffort;
     const timeout = options?.timeout ?? this.config.timeoutMs;
 
     const oaiMessages: OpenAIToolMessage[] = [
@@ -318,11 +431,9 @@ export class OpenAIProvider implements ILLMProvider {
       }),
     ];
 
-    const requestBody = {
+    const base = {
       model,
       messages: oaiMessages,
-      temperature,
-      ...tokenLimitParam(model, maxTokens),
       tools: tools.map((t) => ({
         type: 'function' as const,
         function: { name: t.name, description: t.description, parameters: t.parameters },
@@ -333,25 +444,11 @@ export class OpenAIProvider implements ILLMProvider {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     try {
-      const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${this.config.apiKey}`,
-        },
-        body: JSON.stringify(requestBody),
-        signal: controller.signal,
-      });
+      const data = await this.postAdaptively<OpenAIToolsResponse>(model, (q) => ({
+        ...base,
+        ...samplingParams(q, temperature, maxTokens, effort),
+      }), { effort, maxTokens }, controller.signal);
       clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        const errorData = (await response.json().catch(() => ({
-          error: { message: 'Unknown error' },
-        }))) as OpenAIErrorResponse;
-        throw this.handleApiError(response.status, errorData);
-      }
-
-      const data = (await response.json()) as OpenAIToolsResponse;
       const choice = data.choices?.[0];
       const msg = choice?.message;
       const toolCalls = (msg?.tool_calls ?? []).map((tc) => {
@@ -459,5 +556,8 @@ export function createOpenAIProvider(): OpenAIProvider | null {
     // deployment's timeout and the other ignoring it is the kind of asymmetry
     // that only shows up as a provider-dependent bug at 3am.
     timeoutMs: Number(process.env.LLM_TIMEOUT_MS) || undefined,
+    // gpt-5 family only; unset leaves the API's default (medium, the slowest
+    // that answers small structured calls: see reasoningHeadroom).
+    defaultReasoningEffort: (process.env.OPENAI_REASONING_EFFORT || undefined) as ReasoningEffort | undefined,
   });
 }

package/src/types.ts

@@ -17,8 +17,10 @@ export interface LLMResponse {
   content: string;
   /** Token usage statistics */
   usage: TokenUsage;
-  /** Model identifier used for generation */
+  /** Model identifier used for generation, as the API reports it (e.g. the dated snapshot `gpt-5.5-2026-04-23`). */
   model: string;
+  /** Which provider answered (`openai`, `anthropic`, `mock`). */
+  provider?: string;
   /** Response ID for debugging/logging */
   responseId?: string;
   /** Finish reason (e.g., 'stop', 'length', 'content_filter') */
@@ -37,6 +39,12 @@ export interface GenerateOptions {
   maxTokens?: number;
   /** Request timeout in milliseconds */
   timeout?: number;
+  /**
+   * How much a reasoning model (OpenAI gpt-5 family) thinks before answering.
+   * Unset = the API's default. `maxTokens` stays the answer budget; the
+   * provider adds headroom for the reasoning on top.
+   */
+  reasoningEffort?: ReasoningEffort;
   /** Arbitrary extra data the caller wants to thread through (e.g. domain preferences) */
   extra?: Record<string, unknown>;
 }
@@ -82,8 +90,13 @@ export interface NativeToolResponse {
 /**
  * Provider configuration — everything needed to construct a provider instance.
  */
+/** OpenAI reasoning effort. Not every model takes every value (gpt-5.5 rejects 'minimal'). */
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
 export interface ProviderConfig {
   apiKey: string;
+  /** Default reasoning effort for reasoning models (see GenerateOptions.reasoningEffort). */
+  defaultReasoningEffort?: ReasoningEffort;
   baseUrl?: string;
   defaultModel?: string;
   defaultTemperature?: number;