@moxxy/plugin-provider-openai 0.1.0

package/src/provider.test.ts

@@ -0,0 +1,350 @@
+import { describe, expect, it } from 'vitest';
+import { OpenAIProvider } from './provider.js';
+
+function fakeOpenAI(chunks: ReadonlyArray<unknown>): { chat: { completions: { create: () => Promise<AsyncIterable<unknown>> } } } {
+  return {
+    chat: {
+      completions: {
+        create: async () =>
+          (async function* () {
+            for (const c of chunks) yield c;
+          })(),
+      },
+    },
+  };
+}
+
+describe('OpenAIProvider.stream', () => {
+  it('emits message_start, text_delta(s), message_end for a plain text completion', async () => {
+    const fake = fakeOpenAI([
+      { choices: [{ index: 0, delta: { content: 'Hello, ' } }] },
+      { choices: [{ index: 0, delta: { content: 'world!' } }] },
+      { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+    ]);
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-4o-mini', messages: [] })) events.push(e);
+    expect(events[0]).toMatchObject({ type: 'message_start' });
+    const text = events.filter((e) => e.type === 'text_delta').map((e) => (e as { delta: string }).delta).join('');
+    expect(text).toBe('Hello, world!');
+    expect(events[events.length - 1]).toMatchObject({ type: 'message_end', stopReason: 'end_turn' });
+  });
+
+  it('translates streamed tool_calls into tool_use_start / _delta / _end', async () => {
+    const fake = fakeOpenAI([
+      {
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                { index: 0, id: 'call_1', function: { name: 'Read', arguments: '' } },
+              ],
+            },
+          },
+        ],
+      },
+      {
+        choices: [
+          {
+            index: 0,
+            delta: { tool_calls: [{ index: 0, function: { arguments: '{"path":' } }] },
+          },
+        ],
+      },
+      {
+        choices: [
+          {
+            index: 0,
+            delta: { tool_calls: [{ index: 0, function: { arguments: '"/etc/hosts"}' } }] },
+          },
+        ],
+      },
+      { choices: [{ index: 0, delta: {}, finish_reason: 'tool_calls' }] },
+    ]);
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-4o-mini', messages: [] })) events.push(e);
+    const start = events.find((e) => e.type === 'tool_use_start');
+    expect(start).toMatchObject({ id: 'call_1', name: 'Read' });
+    const end = events.find((e) => e.type === 'tool_use_end');
+    expect(end).toMatchObject({ id: 'call_1', input: { path: '/etc/hosts' } });
+    const last = events[events.length - 1];
+    expect(last).toMatchObject({ type: 'message_end', stopReason: 'tool_use' });
+  });
+
+  it('maps OpenAI finish_reason values to moxxy stop reasons', async () => {
+    const cases: Array<[string, string]> = [
+      ['stop', 'end_turn'],
+      ['length', 'max_tokens'],
+      ['tool_calls', 'tool_use'],
+      ['content_filter', 'error'],
+    ];
+    for (const [reason, expected] of cases) {
+      const fake = fakeOpenAI([{ choices: [{ delta: {}, finish_reason: reason }] }]);
+      const p = new OpenAIProvider({ client: fake as never });
+      const events = [];
+      for await (const e of p.stream({ model: 'gpt-4o', messages: [] })) events.push(e);
+      expect(events[events.length - 1]).toMatchObject({ type: 'message_end', stopReason: expected });
+    }
+  });
+
+  it('requests usage via stream_options and surfaces token + cache-read counts from the final empty-choices chunk', async () => {
+    let captured: Record<string, unknown> | undefined;
+    const fake = {
+      chat: {
+        completions: {
+          create: async (body: Record<string, unknown>) => {
+            captured = body;
+            return (async function* () {
+              yield { choices: [{ index: 0, delta: { content: 'hi' } }] };
+              yield { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] };
+              // OpenAI sends usage in a trailing chunk with NO choices, only
+              // when include_usage was requested.
+              yield {
+                choices: [],
+                usage: {
+                  prompt_tokens: 100,
+                  completion_tokens: 20,
+                  prompt_tokens_details: { cached_tokens: 80 },
+                },
+              };
+            })();
+          },
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-4o-mini', messages: [] })) events.push(e);
+    expect(captured?.stream_options).toEqual({ include_usage: true });
+    expect(events[events.length - 1]).toMatchObject({
+      type: 'message_end',
+      usage: { inputTokens: 100, outputTokens: 20, cacheReadTokens: 80 },
+    });
+  });
+
+  it('emits error event when create() throws', async () => {
+    const fake = {
+      chat: {
+        completions: {
+          create: async () => {
+            throw new Error('rate_limit');
+          },
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-4o', messages: [] })) events.push(e);
+    const err = events.find((e) => e.type === 'error');
+    expect(err).toMatchObject({ retryable: true });
+  });
+
+  it('emits reasoning_delta from delta.reasoning_content when req.reasoning is set', async () => {
+    const fake = fakeOpenAI([
+      { choices: [{ index: 0, delta: { reasoning_content: 'thinking… ' } }] },
+      { choices: [{ index: 0, delta: { reasoning_content: 'done' } }] },
+      { choices: [{ index: 0, delta: { content: 'answer' } }] },
+      { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+    ]);
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({
+      model: 'gpt-5.4-mini',
+      messages: [],
+      reasoning: { effort: 'low' },
+    })) {
+      events.push(e);
+    }
+    const reasoning = events
+      .filter((e) => e.type === 'reasoning_delta')
+      .map((e) => (e as { delta: string }).delta)
+      .join('');
+    expect(reasoning).toBe('thinking… done');
+  });
+
+  it('handles the alternate delta.reasoning field name', async () => {
+    const fake = fakeOpenAI([
+      { choices: [{ index: 0, delta: { reasoning: 'alt-field' } }] },
+      { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+    ]);
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-5.4-mini', messages: [], reasoning: true })) {
+      events.push(e);
+    }
+    const reasoning = events.find((e) => e.type === 'reasoning_delta');
+    expect(reasoning).toMatchObject({ delta: 'alt-field' });
+  });
+
+  it('ignores reasoning deltas when req.reasoning is absent or false', async () => {
+    for (const reasoning of [undefined, false]) {
+      const fake = fakeOpenAI([
+        { choices: [{ index: 0, delta: { reasoning_content: 'should be dropped' } }] },
+        { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] },
+      ]);
+      const p = new OpenAIProvider({ client: fake as never });
+      const events = [];
+      for await (const e of p.stream({ model: 'gpt-5.4-mini', messages: [], reasoning })) {
+        events.push(e);
+      }
+      expect(events.some((e) => e.type === 'reasoning_delta')).toBe(false);
+    }
+  });
+
+  it('requests reasoning_effort for reasoning models when reasoning is enabled', async () => {
+    let captured: Record<string, unknown> | undefined;
+    const fake = {
+      chat: {
+        completions: {
+          create: async (body: Record<string, unknown>) => {
+            captured = body;
+            return (async function* () {
+              yield { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] };
+            })();
+          },
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({
+      model: 'gpt-5.4-mini',
+      messages: [],
+      reasoning: { effort: 'high' },
+    })) {
+      events.push(e);
+    }
+    expect(captured?.reasoning_effort).toBe('high');
+  });
+
+  it('requests reasoning_effort for OpenAI-compatible reasoning backends (non-gpt-5 ids)', async () => {
+    // z.ai GLM / DeepSeek-R1 / vLLM / Ollama reasoning model ids never match
+    // the gpt-5/o1/o3 token-field heuristic, but they honor reasoning_effort —
+    // effort must be sent independently of that heuristic.
+    let captured: Record<string, unknown> | undefined;
+    const fake = {
+      chat: {
+        completions: {
+          create: async (body: Record<string, unknown>) => {
+            captured = body;
+            return (async function* () {
+              yield { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] };
+            })();
+          },
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    for await (const _ of p.stream({
+      model: 'glm-4.6',
+      messages: [],
+      reasoning: { effort: 'high' },
+    })) {
+      // drain
+    }
+    expect(captured?.reasoning_effort).toBe('high');
+    // The token-field heuristic is unchanged: a non-gpt-5 id keeps `max_tokens`.
+    expect(captured && 'max_completion_tokens' in captured).toBe(false);
+  });
+
+  it('emits a clean aborted error (not a classified error) when the signal fires mid-stream', async () => {
+    const controller = new AbortController();
+    const fake = {
+      chat: {
+        completions: {
+          create: async () =>
+            (async function* () {
+              yield { choices: [{ index: 0, delta: { content: 'partial' } }] };
+              // The host cancels; the SDK rejects the iterator with an AbortError.
+              controller.abort();
+              throw Object.assign(new Error('Request was aborted'), { name: 'AbortError' });
+            })(),
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-4o', messages: [], signal: controller.signal })) {
+      events.push(e);
+    }
+    const err = events.find((e) => e.type === 'error');
+    expect(err).toMatchObject({ message: 'aborted', retryable: false });
+  });
+
+  it('emits a clean aborted error when create() rejects after the signal fired', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const fake = {
+      chat: {
+        completions: {
+          create: async () => {
+            throw Object.assign(new Error('Request was aborted'), { name: 'AbortError' });
+          },
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({ model: 'gpt-4o', messages: [], signal: controller.signal })) {
+      events.push(e);
+    }
+    const err = events.find((e) => e.type === 'error');
+    expect(err).toMatchObject({ message: 'aborted', retryable: false });
+  });
+
+  it('countTokens returns a positive estimate', async () => {
+    const p = new OpenAIProvider({ client: fakeOpenAI([]) as never });
+    const n = await p.countTokens({
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: [{ type: 'text', text: 'hello world' }] }],
+    });
+    expect(n).toBeGreaterThan(0);
+  });
+
+  it('delivers hook-injected req.system as a system message after the leading system prompt', async () => {
+    let captured: { messages?: Array<{ role: string; content?: unknown }> } | undefined;
+    const fake = {
+      chat: {
+        completions: {
+          create: async (body: never) => {
+            captured = body;
+            return (async function* () {
+              yield { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] };
+            })();
+          },
+        },
+      },
+    };
+    const p = new OpenAIProvider({ client: fake as never });
+    const events = [];
+    for await (const e of p.stream({
+      model: 'gpt-4o',
+      system: '[memory note] consider consolidating',
+      messages: [
+        { role: 'system', content: [{ type: 'text', text: 'BASE PROMPT' }] },
+        { role: 'user', content: [{ type: 'text', text: 'hi' }] },
+      ],
+    })) {
+      events.push(e);
+    }
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    expect(captured?.messages?.map((m) => m.role)).toEqual(['system', 'system', 'user']);
+    expect(captured?.messages?.[0]).toMatchObject({ content: 'BASE PROMPT' });
+    expect(captured?.messages?.[1]).toMatchObject({ content: '[memory note] consider consolidating' });
+  });
+
+  it('reports an overridden name + model catalog for runtime-registered vendors', () => {
+    const models = [
+      { id: 'glm-4.6', contextWindow: 200_000, supportsTools: true, supportsStreaming: true, supportsDocuments: true },
+    ];
+    const p = new OpenAIProvider({ client: fakeOpenAI([]) as never, name: 'zai', models });
+    expect(p.name).toBe('zai');
+    expect(p.models).toEqual(models);
+    // Defaults stay 'openai' + the OpenAI catalog.
+    const plain = new OpenAIProvider({ client: fakeOpenAI([]) as never });
+    expect(plain.name).toBe('openai');
+    expect(plain.models.length).toBeGreaterThan(0);
+  });
+});

package/src/provider.ts

@@ -0,0 +1,339 @@
+import OpenAI from 'openai';
+import type {
+  LLMProvider,
+  ModelDescriptor,
+  ProviderEvent,
+  ProviderRequest,
+  StopReason,
+} from '@moxxy/sdk';
+import { estimateTextTokens, toFriendlyError } from '@moxxy/sdk';
+import { toOpenAIMessages, toOpenAITools } from './translate.js';
+
+export interface OpenAIProviderConfig {
+  readonly apiKey?: string;
+  readonly baseURL?: string;
+  readonly defaultModel?: string;
+  readonly client?: OpenAI;
+  /**
+   * Override the reported provider name (events, usage stats, error
+   * context). Defaults to `'openai'`. Runtime-registered OpenAI-compatible
+   * vendors (provider_add → z.ai, deepseek, groq, …) reuse this class and
+   * MUST pass their own slug here, otherwise their traffic and errors are
+   * all misattributed to OpenAI.
+   */
+  readonly name?: string;
+  /**
+   * Override the advertised model catalog. Defaults to the OpenAI catalog.
+   * Runtime-registered vendors pass their own descriptors so context-window
+   * lookups (compaction/elision budgets) and capability gating
+   * (supportsImages/supportsDocuments) work against the vendor's models
+   * instead of missing on the OpenAI list.
+   */
+  readonly models?: ReadonlyArray<ModelDescriptor>;
+}
+
+/**
+ * Model catalog as of OpenAI's 2026 API surface. The 5.x family supersedes
+ * the 4o family but the older ones stay listed so existing configs keep
+ * working without a forced migration.
+ *
+ * Output/context numbers are the public documented limits as of April-May
+ * 2026; verify against https://developers.openai.com/api/docs/models when
+ * picking a model for a long-context workload.
+ */
+// The gpt-5.x family are reasoning models (`supportsReasoning`): they accept
+// `reasoning_effort` and, on backends that stream a summary, surface reasoning
+// deltas. Official OpenAI Chat Completions doesn't stream a reasoning summary
+// (Responses-API only), so the flag mainly gates the config UI + effort there;
+// OpenAI-compatible reasoning backends (DeepSeek/z.ai/local) do stream it.
+export const openAIModels: ReadonlyArray<ModelDescriptor> = [
+  // GPT-5.5 family (released April 23, 2026): newest frontier class.
+  { id: 'gpt-5.5', contextWindow: 1_050_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.5-pro', contextWindow: 1_050_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+
+  // GPT-5.4 family: cheaper general-purpose tier; -mini and -nano are the
+  // new sweet-spot defaults for high-volume agentic workloads.
+  { id: 'gpt-5.4', contextWindow: 1_000_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.4-pro', contextWindow: 1_000_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.4-mini', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5.4-nano', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+
+  // GPT-5.3-Codex: agentic coding specialist. Vision-capable.
+  { id: 'gpt-5.3-codex', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+
+  // GPT-5.2 and GPT-5: prior reasoning models, configurable effort.
+  { id: 'gpt-5.2', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+  { id: 'gpt-5', contextWindow: 400_000, maxOutputTokens: 128_000, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true, supportsReasoning: true },
+
+  // GPT-4 family: kept for explicit-pin use cases.
+  // 4.1 is text-only; 4o/4o-mini are vision + document capable; 4-turbo predates file inputs.
+  { id: 'gpt-4.1', contextWindow: 1_000_000, maxOutputTokens: 32_768, supportsTools: true, supportsStreaming: true },
+  { id: 'gpt-4o', contextWindow: 128_000, maxOutputTokens: 16_384, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true },
+  { id: 'gpt-4o-mini', contextWindow: 128_000, maxOutputTokens: 16_384, supportsTools: true, supportsStreaming: true, supportsImages: true, supportsDocuments: true },
+  { id: 'gpt-4-turbo', contextWindow: 128_000, maxOutputTokens: 4_096, supportsTools: true, supportsStreaming: true, supportsImages: true },
+];
+
+interface PendingToolCall {
+  id: string;
+  name: string;
+  argsBuffer: string;
+  emittedStart: boolean;
+}
+
+export class OpenAIProvider implements LLMProvider {
+  readonly name: string;
+  readonly models: ReadonlyArray<ModelDescriptor>;
+  private readonly client: OpenAI;
+  private readonly defaultModel: string;
+
+  constructor(config: OpenAIProviderConfig = {}) {
+    this.name = config.name ?? 'openai';
+    this.models = config.models ?? openAIModels;
+    this.client =
+      config.client ??
+      new OpenAI({
+        apiKey: config.apiKey ?? process.env.OPENAI_API_KEY,
+        ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+      });
+    this.defaultModel = config.defaultModel ?? 'gpt-5.4-mini';
+  }
+
+  async *stream(req: ProviderRequest): AsyncIterable<ProviderEvent> {
+    const messages = toOpenAIMessages(req.messages);
+    // `req.system` is the hook-injection side channel (e.g. the memory
+    // consolidation nudge): extra system text delivered IN ADDITION to any
+    // system-role messages already in `req.messages`. Insert it right after
+    // the leading system message(s) so it reads as system guidance without
+    // reordering the conversation.
+    if (req.system) {
+      let insertAt = 0;
+      while (insertAt < messages.length && messages[insertAt]!.role === 'system') insertAt += 1;
+      messages.splice(insertAt, 0, { role: 'system', content: req.system });
+    }
+    const tools = req.tools && req.tools.length > 0 ? toOpenAITools(req.tools) : undefined;
+    const model = req.model || this.defaultModel;
+
+    yield { type: 'message_start', model };
+
+    // GPT-5.x (and OpenAI's reasoning models) renamed the token cap field
+    // from `max_tokens` to `max_completion_tokens` and ALSO reject the
+    // legacy name with a 400. Use the new name for any model whose id
+    // starts with gpt-5 / o1 / o3; keep the legacy name for the gpt-4
+    // family so existing callers don't regress.
+    const usesCompletionTokens = /^(?:gpt-5|o1|o3)/.test(model);
+    const tokenLimitKey = usesCompletionTokens ? 'max_completion_tokens' : 'max_tokens';
+
+    // Reasoning preview is gated by the per-provider toggle (`req.reasoning`).
+    // When on, request `reasoning_effort` for OpenAI reasoning models (improves
+    // depth + makes a summary available where the backend streams one) and
+    // surface the streamed reasoning/reasoning_content deltas.
+    const emitReasoning = req.reasoning != null && req.reasoning !== false;
+    const reasoningEffort = typeof req.reasoning === 'object' ? req.reasoning.effort : undefined;
+
+    // Type the request body as the SDK's streaming-create params so field
+    // names/value types are checked. The local `OpenAIChatMessage` /
+    // `OpenAIToolDef` shapes genuinely diverge from the SDK's wide message/tool
+    // unions (we build a narrower, hand-rolled shape), so cast ONLY those two
+    // fields — not the whole body — keeping the rest type-checked.
+    const params: OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming = {
+      model,
+      messages: messages as unknown as OpenAI.Chat.Completions.ChatCompletionMessageParam[],
+      ...(tools
+        ? { tools: tools as unknown as OpenAI.Chat.Completions.ChatCompletionTool[] }
+        : {}),
+      ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
+      ...(req.maxTokens ? { [tokenLimitKey]: req.maxTokens } : {}),
+      // Send `reasoning_effort` independently of the token-field heuristic.
+      // The two are unrelated concerns: `usesCompletionTokens` picks the cap
+      // FIELD NAME for the OpenAI-hosted reasoning models, while effort applies
+      // to any reasoning backend. OpenAI-compatible vendors (z.ai GLM,
+      // DeepSeek-R1, vLLM, Ollama) honor reasoning_effort but their model ids
+      // never match the gpt-5/o1/o3 regex, so gating effort on it silently
+      // dropped a user-requested effort for exactly those backends. The
+      // descriptor's `supportsReasoning` already gates this upstream via
+      // req.reasoning.
+      ...(emitReasoning && reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
+      stream: true,
+      // OpenAI only emits the final `usage` chunk when this is set;
+      // without it `raw.usage` is null on every chunk and token usage
+      // (and cache-read counts) are silently lost for every streamed turn.
+      stream_options: { include_usage: true },
+    };
+
+    let stream: AsyncIterable<unknown>;
+    try {
+      stream = (await this.client.chat.completions.create(
+        params,
+        // Pass the AbortSignal into the SDK request options so cancelling
+        // mid-stream tears down the underlying HTTP request instead of just
+        // stopping our consumption loop. Without this, Esc / Ctrl+C felt
+        // like nothing happened — the model kept generating and the user
+        // got charged for tokens after the cancel.
+        req.signal ? { signal: req.signal } : undefined,
+      )) as unknown as AsyncIterable<unknown>;
+    } catch (err) {
+      // A cancel can surface as a thrown AbortError from the create() await —
+      // report the clean terminal 'aborted' event (parity with the Anthropic
+      // provider) so callers that suppress error UI on user cancel don't get a
+      // noisy classified provider error.
+      if (req.signal?.aborted) {
+        yield { type: 'error', message: 'aborted', retryable: false };
+        return;
+      }
+      yield { type: 'error', ...toFriendlyError(err, { provider: this.name }) };
+      return;
+    }
+
+    const pending = new Map<number, PendingToolCall>();
+    let stopReason: StopReason = 'end_turn';
+    let usageIn = 0;
+    let usageOut = 0;
+    let usageCacheRead = 0;
+
+    try {
+      for await (const raw of stream as AsyncIterable<OpenAIStreamChunk>) {
+        if (req.signal?.aborted) {
+          yield { type: 'error', message: 'aborted', retryable: false };
+          return;
+        }
+        // Usage arrives in a FINAL chunk that has an empty `choices` array
+        // (only when stream_options.include_usage is set), so it must be read
+        // before the `!choice` guard below — otherwise it's `continue`d past.
+        if (raw.usage) {
+          usageIn = raw.usage.prompt_tokens ?? usageIn;
+          usageOut = raw.usage.completion_tokens ?? usageOut;
+          // `prompt_tokens` already includes the cached portion; surface the
+          // cached count so cache hit-rate accounting works (parity with the
+          // Anthropic provider's cache_read_input_tokens).
+          usageCacheRead = raw.usage.prompt_tokens_details?.cached_tokens ?? usageCacheRead;
+        }
+        const choice = raw.choices?.[0];
+        if (!choice) continue;
+        const delta = choice.delta ?? {};
+
+        if (typeof delta.content === 'string' && delta.content) {
+          yield { type: 'text_delta', delta: delta.content };
+        }
+
+        if (emitReasoning) {
+          const reasoning = delta.reasoning_content ?? delta.reasoning;
+          if (typeof reasoning === 'string' && reasoning) {
+            yield { type: 'reasoning_delta', delta: reasoning };
+          }
+        }
+
+        if (delta.tool_calls) {
+          for (const tcDelta of delta.tool_calls) {
+            const idx = tcDelta.index ?? 0;
+            let entry = pending.get(idx);
+            if (!entry) {
+              entry = {
+                id: tcDelta.id ?? `call_${idx}`,
+                name: tcDelta.function?.name ?? '',
+                argsBuffer: '',
+                emittedStart: false,
+              };
+              pending.set(idx, entry);
+            } else if (tcDelta.id) {
+              entry.id = tcDelta.id;
+            }
+            if (tcDelta.function?.name && !entry.name) entry.name = tcDelta.function.name;
+            if (tcDelta.function?.name && !entry.emittedStart && entry.name) {
+              entry.emittedStart = true;
+              yield { type: 'tool_use_start', id: entry.id, name: entry.name };
+            }
+            if (typeof tcDelta.function?.arguments === 'string') {
+              entry.argsBuffer += tcDelta.function.arguments;
+              yield { type: 'tool_use_delta', id: entry.id, partialInput: tcDelta.function.arguments };
+            }
+          }
+        }
+
+        if (choice.finish_reason) {
+          stopReason = mapStopReason(choice.finish_reason);
+        }
+      }
+    } catch (err) {
+      // The SDK rejects the iterator with an AbortError once req.signal fires;
+      // emit the clean 'aborted' event instead of a classified provider error
+      // (parity with the Anthropic provider and the in-loop abort check above).
+      if (req.signal?.aborted) {
+        yield { type: 'error', message: 'aborted', retryable: false };
+        return;
+      }
+      yield { type: 'error', ...toFriendlyError(err, { provider: this.name }) };
+      return;
+    }
+
+    // Flush tool_use_end events with parsed arguments.
+    for (const entry of pending.values()) {
+      let parsed: unknown = {};
+      if (entry.argsBuffer) {
+        try {
+          parsed = JSON.parse(entry.argsBuffer);
+        } catch {
+          parsed = { _rawPartial: entry.argsBuffer };
+        }
+      }
+      if (entry.emittedStart) {
+        yield { type: 'tool_use_end', id: entry.id, input: parsed };
+      }
+    }
+
+    yield {
+      type: 'message_end',
+      stopReason,
+      usage:
+        usageIn > 0 || usageOut > 0
+          ? {
+              inputTokens: usageIn,
+              outputTokens: usageOut,
+              ...(usageCacheRead > 0 ? { cacheReadTokens: usageCacheRead } : {}),
+            }
+          : undefined,
+    };
+  }
+
+  async countTokens(req: Pick<ProviderRequest, 'model' | 'messages' | 'system' | 'tools'>): Promise<number> {
+    // OpenAI doesn't expose a free token counter; fall back to a coarse estimate.
+    const blob =
+      (req.system ?? '') +
+      req.messages.map((m) => m.content.map((c) => ('text' in c ? c.text : JSON.stringify(c))).join('')).join('') +
+      (req.tools ?? []).map((t) => t.name + t.description).join('');
+    return estimateTextTokens(blob);
+  }
+}
+
+interface OpenAIStreamChunk {
+  choices?: Array<{
+    index?: number;
+    delta?: {
+      content?: string | null;
+      // Reasoning summary streamed by OpenAI-compatible reasoning backends
+      // (DeepSeek-R1, z.ai/GLM, vLLM, Ollama, …). The field name varies by
+      // vendor — handle both. Official OpenAI Chat Completions doesn't stream
+      // it (Responses-API only), so it's simply absent there.
+      reasoning_content?: string | null;
+      reasoning?: string | null;
+      tool_calls?: Array<{
+        index?: number;
+        id?: string;
+        function?: { name?: string; arguments?: string };
+      }>;
+    };
+    finish_reason?: string | null;
+  }>;
+  usage?: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    prompt_tokens_details?: { cached_tokens?: number };
+  };
+}
+
+function mapStopReason(s: string): StopReason {
+  if (s === 'tool_calls') return 'tool_use';
+  if (s === 'length') return 'max_tokens';
+  if (s === 'stop') return 'end_turn';
+  if (s === 'content_filter') return 'error';
+  return 'end_turn';
+}