@moxxy/plugin-provider-openai-codex 0.21.1

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@moxxy/plugin-provider-openai-codex",
+  "version": "0.21.1",
+  "description": "OpenAI Codex (ChatGPT Pro/Plus OAuth) LLMProvider plugin for moxxy. Streams against https://chatgpt.com/backend-api/codex/responses using PKCE-based OAuth tokens.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "provider",
+    "openai",
+    "codex",
+    "chatgpt",
+    "oauth",
+    "llm"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-provider-openai-codex"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "provider"
+    }
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.21.1",
+    "@moxxy/plugin-oauth": "0.0.33"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/codex/headers.ts

@@ -0,0 +1,41 @@
+import { createRequire } from 'node:module';
+import { ORIGINATOR } from '../oauth.js';
+import type { CodexTokens } from '../types.js';
+
+/**
+ * Resolve this plugin's real version from its package.json once at module load
+ * rather than freezing a stale literal in two places (the UA and the plugin
+ * def). The User-Agent is sent on every request to the ChatGPT backend; a
+ * permanently-`0.0.0` UA defeats server-side version gating and diverges from
+ * the real release. Resolves correctly when the package runs from its own dist
+ * (dev, tests, third-party `~/.moxxy/plugins` installs); falls back to `0.0.0`
+ * defensively — never throws on a header build. (NOTE: when inlined into the
+ * single-file CLI bundle the relative resolve fails and we keep the `0.0.0`
+ * fallback; a build-time constant would close that gap — see TECH_DEBT.)
+ */
+function resolvePluginVersion(): string {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../../package.json') as { version?: unknown };
+    return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export const PLUGIN_VERSION = resolvePluginVersion();
+
+export const CODEX_USER_AGENT = `moxxy/${PLUGIN_VERSION} (codex)`;
+
+export function buildCodexHeaders(tokens: CodexTokens, sessionId: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Accept: 'text/event-stream',
+    Authorization: `Bearer ${tokens.access}`,
+    originator: ORIGINATOR,
+    'User-Agent': CODEX_USER_AGENT,
+    session_id: sessionId,
+  };
+  if (tokens.accountId) headers['ChatGPT-Account-Id'] = tokens.accountId;
+  return headers;
+}

package/src/codex/sse-event-handler.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { handleSseEvent } from './sse-event-handler.js';
+import type { PendingFunctionCall, ResponsesSseEvent } from './stream-types.js';
+
+const run = (ev: ResponsesSseEvent, emitReasoning: boolean) =>
+  handleSseEvent(ev, new Map<string, PendingFunctionCall>(), emitReasoning);
+
+describe('handleSseEvent — reasoning summary', () => {
+  it('maps reasoning_summary_text.delta to a reasoning_delta when enabled', () => {
+    const out = run({ type: 'response.reasoning_summary_text.delta', delta: 'planning…' }, true);
+    expect(out.events).toEqual([{ type: 'reasoning_delta', delta: 'planning…' }]);
+  });
+
+  it('drops the reasoning summary entirely when the toggle is off', () => {
+    const out = run({ type: 'response.reasoning_summary_text.delta', delta: 'planning…' }, false);
+    expect(out.events ?? []).toEqual([]);
+  });
+
+  it('captures a reasoning item encrypted_content as a reasoning_signature', () => {
+    const out = run(
+      { type: 'response.output_item.added', item: { type: 'reasoning', encrypted_content: 'blob' } },
+      true,
+    );
+    expect(out.events).toEqual([{ type: 'reasoning_signature', encrypted: 'blob' }]);
+  });
+
+  it('still maps text + function-call events regardless of the reasoning toggle', () => {
+    expect(run({ type: 'response.output_text.delta', delta: 'hi' }, false).events).toEqual([
+      { type: 'text_delta', delta: 'hi' },
+    ]);
+  });
+});
+
+describe('handleSseEvent — hostile-stream bounds', () => {
+  it('caps a single tool call argument accumulation across many delta frames', () => {
+    const pending = new Map<string, PendingFunctionCall>();
+    // Seed a function call.
+    handleSseEvent(
+      {
+        type: 'response.output_item.added',
+        item: { type: 'function_call', id: 'fc1', call_id: 'call_1', name: 'echo' },
+      },
+      pending,
+      false,
+    );
+    // A hostile stream sends 2 MiB per delta frame; each frame is individually
+    // small enough to pass the consumer's frame buffer but accumulates across
+    // frames. The handler must surface a terminal error before unbounded growth.
+    const bigDelta = 'a'.repeat(2 * 1024 * 1024);
+    let result;
+    for (let i = 0; i < 20; i++) {
+      result = handleSseEvent(
+        { type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: bigDelta },
+        pending,
+        false,
+      );
+      if (result.terminal) break;
+    }
+    expect(result?.terminal).toBe(true);
+    expect(result?.events?.[0]).toMatchObject({ type: 'error', retryable: false });
+    // It bailed well before 20 * 2 MiB = 40 MiB accumulated (cap is 16 MiB).
+    expect(pending.get('fc1')!.args.length).toBeLessThanOrEqual(16 * 1024 * 1024);
+  });
+
+  it('caps the number of concurrently-pending tool calls', () => {
+    const pending = new Map<string, PendingFunctionCall>();
+    let result;
+    // A hostile stream seeds unbounded distinct function-call ids, never .done-ing
+    // any. The Map must not grow without limit.
+    for (let i = 0; i < 2000; i++) {
+      result = handleSseEvent(
+        {
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: `fc_${i}`, call_id: `call_${i}`, name: 'echo' },
+        },
+        pending,
+        false,
+      );
+      if (result.terminal) break;
+    }
+    expect(result?.terminal).toBe(true);
+    expect(result?.events?.[0]).toMatchObject({ type: 'error', retryable: false });
+    expect(pending.size).toBeLessThanOrEqual(1024);
+  });
+});

package/src/codex/sse-event-handler.ts

@@ -0,0 +1,173 @@
+import type { ProviderEvent, StopReason } from '@moxxy/sdk';
+import {
+  parseToolArgs,
+  type PendingFunctionCall,
+  type ResponsesSseEvent,
+  type SseStepResult,
+} from './stream-types.js';
+
+/**
+ * Hard cap on a single tool call's accumulated argument text. `entry.args` grows
+ * by every `function_call_arguments.delta`; unlike the consumer's per-frame
+ * reassembly buffer (which shrinks once a frame is parsed), this accumulates
+ * ACROSS frames and is otherwise unbounded — a hostile stream of millions of
+ * small, individually-valid delta frames would grow it to OOM without ever
+ * tripping the frame-buffer cap. 16 MiB is far beyond any legitimate tool-call
+ * payload. Exceeding it is treated as a hostile stream (terminal error).
+ */
+const MAX_TOOL_ARGS_CHARS = 16 * 1024 * 1024;
+
+/**
+ * Hard cap on the number of concurrently-pending function calls. Each distinct
+ * `output_item.added` function_call seeds a `pending` entry that lives until its
+ * `.done` (or the post-stream flush); a hostile stream could emit unbounded
+ * distinct ids and never finish them, growing the Map without limit. No real
+ * turn fans out to anywhere near this many parallel tool calls.
+ */
+const MAX_PENDING_TOOL_CALLS = 1024;
+
+const TOOL_STREAM_LIMIT_ERROR = (what: string): SseStepResult => ({
+  events: [{ type: 'error', message: `Codex tool-call stream exceeded ${what} limit`, retryable: false }],
+  terminal: true,
+});
+
+/**
+ * Map a single Responses-API SSE event to zero or more moxxy ProviderEvents.
+ * Centralized here so the streaming loop stays a thin "read frame → call
+ * this → yield" structure and the event taxonomy is easy to test directly.
+ *
+ * Events we care about (subset of the full Responses API surface):
+ *   response.output_text.delta         → text_delta
+ *   response.output_item.added         → tool_use_start (if it's a function_call)
+ *   response.function_call_arguments.delta → tool_use_delta
+ *   response.function_call_arguments.done  → finalize tool_use_end
+ *   response.completed                 → message_end (sets stopReason)
+ *   response.failed / response.error   → error
+ */
+export function handleSseEvent(
+  ev: ResponsesSseEvent,
+  pending: Map<string, PendingFunctionCall>,
+  emitReasoning = false,
+): SseStepResult {
+  const type = ev.type ?? '';
+
+  if (type === 'response.output_text.delta' && typeof ev.delta === 'string' && ev.delta) {
+    return { events: [{ type: 'text_delta', delta: ev.delta }] };
+  }
+
+  // Reasoning summary text (Codex requests `summary: 'auto'`) → reasoning_delta.
+  // The streamed summary is the visible "thinking" between tool calls. Gated on
+  // the per-provider reasoning toggle; off → discard as before.
+  if (emitReasoning && type === 'response.reasoning_summary_text.delta' && typeof ev.delta === 'string' && ev.delta) {
+    return { events: [{ type: 'reasoning_delta', delta: ev.delta }] };
+  }
+
+  // A `reasoning` output item carries the encrypted_content we must replay
+  // verbatim on the next request (Codex requests `include: ['reasoning.encrypted_content']`).
+  if (emitReasoning && type === 'response.output_item.added' && ev.item?.type === 'reasoning') {
+    return ev.item.encrypted_content
+      ? { events: [{ type: 'reasoning_signature', encrypted: ev.item.encrypted_content }] }
+      : {};
+  }
+
+  if (type === 'response.output_item.added' && ev.item?.type === 'function_call') {
+    const id = ev.item.id ?? ev.item.call_id ?? `call_${pending.size}`;
+    // Bound the number of in-flight tool calls: a hostile stream could otherwise
+    // seed unbounded distinct ids and never `.done` them, growing the Map to OOM.
+    // (A new id that would overflow is rejected; re-using an existing id is fine.)
+    if (!pending.has(id) && pending.size >= MAX_PENDING_TOOL_CALLS) {
+      return TOOL_STREAM_LIMIT_ERROR('pending-call count');
+    }
+    const callId = ev.item.call_id ?? id;
+    const name = ev.item.name ?? '';
+    const entry: PendingFunctionCall = {
+      id,
+      callId,
+      name,
+      args: ev.item.arguments ?? '',
+      emittedStart: false,
+    };
+    pending.set(id, entry);
+    if (name) {
+      entry.emittedStart = true;
+      return { events: [{ type: 'tool_use_start', id: callId, name }] };
+    }
+    return {};
+  }
+
+  if (type === 'response.function_call_arguments.delta') {
+    const id = ev.item_id ?? ev.call_id ?? '';
+    const entry = pending.get(id);
+    const delta = ev.delta ?? '';
+    if (entry && typeof delta === 'string') {
+      // Bound the per-call argument accumulation: this grows across frames and
+      // is not covered by the consumer's per-frame reassembly cap.
+      if (entry.args.length + delta.length > MAX_TOOL_ARGS_CHARS) {
+        return TOOL_STREAM_LIMIT_ERROR('argument size');
+      }
+      entry.args += delta;
+      const outId = entry.callId || entry.id;
+      // If we hadn't emitted tool_use_start yet (server sent the args
+      // before the item.added with a name), do so now using whatever
+      // name landed later. Defensive — opencode's pattern.
+      const startEvents: ProviderEvent[] = [];
+      if (!entry.emittedStart && entry.name) {
+        entry.emittedStart = true;
+        startEvents.push({ type: 'tool_use_start', id: outId, name: entry.name });
+      }
+      return {
+        events: [...startEvents, { type: 'tool_use_delta', id: outId, partialInput: delta }],
+      };
+    }
+    return {};
+  }
+
+  if (type === 'response.function_call_arguments.done') {
+    const id = ev.item_id ?? ev.call_id ?? '';
+    const entry = pending.get(id);
+    if (!entry) return {};
+    pending.delete(id);
+    if (typeof ev.arguments === 'string' && ev.arguments) entry.args = ev.arguments;
+    const input = parseToolArgs(entry.args);
+    const outId = entry.callId || entry.id;
+    const events: ProviderEvent[] = [];
+    if (!entry.emittedStart && entry.name) {
+      events.push({ type: 'tool_use_start', id: outId, name: entry.name });
+    }
+    events.push({ type: 'tool_use_end', id: outId, input });
+    return { events };
+  }
+
+  if (type === 'response.completed') {
+    const usage = ev.response?.usage;
+    const input = usage?.input_tokens ?? 0;
+    const cacheRead = usage?.input_tokens_details?.cached_tokens ?? 0;
+    const incomplete = ev.response?.incomplete_details?.reason;
+    let stopReason: StopReason = 'end_turn';
+    if (incomplete === 'max_output_tokens') stopReason = 'max_tokens';
+    else if (incomplete === 'stop_sequence') stopReason = 'stop_sequence';
+    // The presence of unflushed function calls would already get mapped to
+    // tool_use by the post-loop logic; the explicit "completed" event
+    // doesn't carry a tool_use stop reason on its own.
+    return {
+      stopReason,
+      ...(usage
+        ? {
+            usage: {
+              input: Math.max(0, input - cacheRead),
+              output: usage.output_tokens ?? 0,
+              ...(usage.input_tokens_details?.cached_tokens !== undefined ? { cacheRead } : {}),
+            },
+          }
+        : {}),
+      terminal: true,
+    };
+  }
+
+  if (type === 'response.failed' || type === 'response.error' || type === 'error') {
+    const msg = ev.error?.message ?? `Codex stream failed: ${type}`;
+    return { events: [{ type: 'error', message: msg, retryable: false }], terminal: true };
+  }
+
+  return {};
+}

package/src/codex/stream-consumer.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+import type { ProviderEvent } from '@moxxy/sdk';
+import { consumeResponsesSse } from './stream-consumer.js';
+
+/**
+ * Build a ReadableStream<Uint8Array> from a list of string chunks. Each chunk
+ * is delivered as its own `read()` so we can exercise frame reassembly across
+ * chunk boundaries.
+ */
+function streamOf(chunks: ReadonlyArray<string>): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  let i = 0;
+  return new ReadableStream<Uint8Array>({
+    pull(controller) {
+      if (i < chunks.length) {
+        controller.enqueue(enc.encode(chunks[i]!));
+        i += 1;
+      } else {
+        controller.close();
+      }
+    },
+  });
+}
+
+/** An SSE `data:` frame for a single event object, separator included. */
+const frame = (obj: unknown, sep = '\n\n'): string => `data: ${JSON.stringify(obj)}${sep}`;
+
+async function drain(
+  body: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+): Promise<ProviderEvent[]> {
+  const out: ProviderEvent[] = [];
+  for await (const ev of consumeResponsesSse(body, signal)) out.push(ev);
+  return out;
+}
+
+describe('consumeResponsesSse', () => {
+  it('assembles a tool call (added → arguments.delta → arguments.done) and upgrades stopReason to tool_use', async () => {
+    const events = await drain(
+      streamOf([
+        frame({
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: 'fc1', call_id: 'call_1', name: 'echo' },
+        }),
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: '{"msg":' }),
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: '"hi"}' }),
+        frame({
+          type: 'response.function_call_arguments.done',
+          item_id: 'fc1',
+          arguments: '{"msg":"hi"}',
+        }),
+        frame({ type: 'response.completed', response: {} }),
+      ]),
+    );
+
+    const start = events.find((e) => e.type === 'tool_use_start');
+    expect(start).toMatchObject({ type: 'tool_use_start', id: 'call_1', name: 'echo' });
+    const end = events.find((e) => e.type === 'tool_use_end');
+    expect(end).toMatchObject({ type: 'tool_use_end', id: 'call_1', input: { msg: 'hi' } });
+    const last = events.at(-1);
+    expect(last).toMatchObject({ type: 'message_end', stopReason: 'tool_use' });
+  });
+
+  it('flushes a tool call that never received a .done frame (truncated stream)', async () => {
+    const events = await drain(
+      streamOf([
+        frame({
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: 'fc1', call_id: 'call_1', name: 'echo' },
+        }),
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: '{"x":1}' }),
+        // stream ends with no .done and no response.completed
+      ]),
+    );
+    const end = events.find((e) => e.type === 'tool_use_end');
+    expect(end).toMatchObject({ type: 'tool_use_end', id: 'call_1', input: { x: 1 } });
+    const last = events.at(-1);
+    expect(last).toMatchObject({ type: 'message_end', stopReason: 'tool_use' });
+  });
+
+  it('does not emit a malformed tool_use for a truncated function_call that never carried a name', async () => {
+    // item.added with no `name`, some args, then the stream truncates before
+    // both the name and the .done arrive. The flush must NOT synthesize a
+    // nameless/invalid tool_use_start/end — it has no usable name.
+    const events = await drain(
+      streamOf([
+        frame({
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: 'fc1', call_id: 'call_1' }, // no name
+        }),
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: '{"x":1}' }),
+        // stream ends: no name ever arrived, no .done, no completed
+      ]),
+    );
+    expect(events.some((e) => e.type === 'tool_use_start')).toBe(false);
+    expect(events.some((e) => e.type === 'tool_use_end')).toBe(false);
+    // With no tool call emitted, the turn is not upgraded to tool_use.
+    const last = events.at(-1);
+    expect(last).toMatchObject({ type: 'message_end', stopReason: 'end_turn' });
+  });
+
+  it('flushes a tool_use_start+end when a name was buffered but its start frame never landed', async () => {
+    // Defensive flush path: emittedStart is false yet a name is present. We
+    // drive this by handing the consumer a pre-seeded pending entry via the
+    // documented event sequence the handler produces, then truncating. The
+    // flush must emit BOTH start and end so the call isn't dropped.
+    //
+    // The only handler path that leaves name set without emittedStart would be
+    // a future event type; until then this guards the flush's name-recovery
+    // branch against regressions by asserting a started call still flushes its
+    // end even with no .done (covered above) and that a named added+truncation
+    // yields a complete pair.
+    const events = await drain(
+      streamOf([
+        frame({
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: 'fc2', call_id: 'call_2', name: 'lookup' },
+        }),
+        // No args.delta, no .done — immediate truncation after the named start.
+      ]),
+    );
+    const start = events.find((e) => e.type === 'tool_use_start');
+    const end = events.find((e) => e.type === 'tool_use_end');
+    expect(start).toMatchObject({ id: 'call_2', name: 'lookup' });
+    expect(end).toMatchObject({ id: 'call_2' });
+  });
+
+  it('surfaces _rawPartial when the flushed args are not valid JSON', async () => {
+    const events = await drain(
+      streamOf([
+        frame({
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: 'fc1', call_id: 'call_1', name: 'echo' },
+        }),
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: '{"x":' }),
+      ]),
+    );
+    const end = events.find((e) => e.type === 'tool_use_end');
+    expect(end).toMatchObject({ type: 'tool_use_end', input: { _rawPartial: '{"x":' } });
+  });
+
+  it('reassembles a frame split across two chunk reads', async () => {
+    const f = frame({ type: 'response.output_text.delta', delta: 'hello' });
+    const cut = Math.floor(f.length / 2);
+    const events = await drain(
+      streamOf([f.slice(0, cut), f.slice(cut), frame({ type: 'response.completed', response: {} })]),
+    );
+    const text = events.find((e) => e.type === 'text_delta');
+    expect(text).toMatchObject({ type: 'text_delta', delta: 'hello' });
+  });
+
+  it('handles CRLF frame separators including a \\r split across reads', async () => {
+    // The \r and \n of a CRLF separator land in different read() calls.
+    const events = await drain(
+      streamOf([
+        `data: ${JSON.stringify({ type: 'response.output_text.delta', delta: 'crlf' })}\r`,
+        `\n\r\n`,
+        frame({ type: 'response.completed', response: {} }),
+      ]),
+    );
+    const text = events.find((e) => e.type === 'text_delta');
+    expect(text).toMatchObject({ type: 'text_delta', delta: 'crlf' });
+  });
+
+  it('emits a single error and no trailing message_end on response.failed', async () => {
+    const events = await drain(
+      streamOf([
+        frame({ type: 'response.failed', error: { message: 'boom' } }),
+        // a stray frame after the terminal one must be ignored
+        frame({ type: 'response.output_text.delta', delta: 'late' }),
+      ]),
+    );
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ type: 'error', message: 'boom' });
+    expect(events.some((e) => e.type === 'message_end')).toBe(false);
+  });
+
+  it('emits the abort error and stops when the signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const events = await drain(
+      streamOf([frame({ type: 'response.output_text.delta', delta: 'never' })]),
+      controller.signal,
+    );
+    expect(events).toEqual([{ type: 'error', message: 'aborted', retryable: false }]);
+  });
+
+  it('bounds the reassembly buffer: an endless body with no frame separator errors instead of OOMing', async () => {
+    // A misbehaving/MITM'd endpoint streams a continuous body that never emits a
+    // blank-line frame separator. Without the cap, `buffer` would grow until OOM.
+    const chunk = 'x'.repeat(1024 * 1024); // 1 MiB, no '\n\n' anywhere
+    let reads = 0;
+    const body = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        // Far more than the 8 MiB cap if left unbounded; the consumer must bail
+        // long before this many reads complete.
+        if (reads >= 100) {
+          controller.close();
+          return;
+        }
+        reads += 1;
+        controller.enqueue(new TextEncoder().encode(chunk));
+      },
+    });
+    const events = await drain(body);
+    expect(events).toEqual([
+      { type: 'error', message: 'Codex stream frame exceeded size limit', retryable: false },
+    ]);
+    // It stopped reading well before draining all 100 MiB.
+    expect(reads).toBeLessThan(20);
+  });
+
+  it('does not flush a phantom tool call after a mid-stream response.failed (error supersedes pending)', async () => {
+    // A function_call starts (tool_use_start emitted) but the stream fails before
+    // its .done arrives. The failed turn must surface ONE error and must NOT flush
+    // a trailing tool_use_end on top of it.
+    const events = await drain(
+      streamOf([
+        frame({
+          type: 'response.output_item.added',
+          item: { type: 'function_call', id: 'fc1', call_id: 'call_1', name: 'echo' },
+        }),
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: '{"x":1' }),
+        frame({ type: 'response.failed', error: { message: 'boom' } }),
+      ]),
+    );
+    const errs = events.filter((e) => e.type === 'error');
+    expect(errs).toHaveLength(1);
+    expect(events.some((e) => e.type === 'tool_use_end')).toBe(false);
+    expect(events.some((e) => e.type === 'message_end')).toBe(false);
+  });
+
+  it('bounds cross-frame tool-arg accumulation: many valid delta frames error instead of OOMing', async () => {
+    // Each frame here IS well-formed and individually under the frame-buffer cap,
+    // so the consumer's per-frame reassembly cap never trips. The unbounded vector
+    // is `entry.args += delta` accumulating across frames — the handler must cap it
+    // and surface a single terminal error.
+    const bigDelta = 'a'.repeat(1024 * 1024); // 1 MiB per frame
+    const frames = [
+      frame({
+        type: 'response.output_item.added',
+        item: { type: 'function_call', id: 'fc1', call_id: 'call_1', name: 'echo' },
+      }),
+      // 30 MiB of cumulative args — far over the 16 MiB cap — across 30 frames.
+      ...Array.from({ length: 30 }, () =>
+        frame({ type: 'response.function_call_arguments.delta', item_id: 'fc1', delta: bigDelta }),
+      ),
+    ];
+    const events = await drain(streamOf(frames));
+    const errs = events.filter((e) => e.type === 'error');
+    expect(errs).toHaveLength(1);
+    expect(errs[0]).toMatchObject({ retryable: false });
+    // The failed turn must not also emit a trailing message_end.
+    expect(events.some((e) => e.type === 'message_end')).toBe(false);
+  });
+
+  it('reports cached usage from response.completed as cache reads plus fresh input', async () => {
+    const events = await drain(
+      streamOf([
+        frame({ type: 'response.output_text.delta', delta: 'hi' }),
+        frame({
+          type: 'response.completed',
+          response: {
+            usage: {
+              input_tokens: 10,
+              output_tokens: 3,
+              input_tokens_details: { cached_tokens: 4 },
+            },
+          },
+        }),
+      ]),
+    );
+    const last = events.at(-1);
+    expect(last).toMatchObject({
+      type: 'message_end',
+      stopReason: 'end_turn',
+      usage: { inputTokens: 6, outputTokens: 3, cacheReadTokens: 4 },
+    });
+  });
+});