@milkdown/crepe 7.19.2 → 7.21.0

package/src/llm-providers/providers.spec.ts

@@ -0,0 +1,472 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+type FetchSig = (...args: Parameters<typeof fetch>) => Promise<Response>
+
+import type { AIPromptContext } from '../feature/ai/types'
+
+import { createAnthropicProvider } from './anthropic'
+import { createOpenAIProvider } from './openai'
+import {
+  DEFAULT_SYSTEM_PROMPT,
+  buildDefaultUserMessage,
+  parseSSE,
+  resolveSystemPrompt,
+} from './shared'
+
+const sampleContext: AIPromptContext = {
+  document: '# Title\n\nHello.',
+  selection: 'Hello.',
+  instruction: 'Make it longer.',
+}
+
+function sseResponse(events: string[]): Response {
+  const text = events.map((e) => `data: ${e}\n\n`).join('')
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(text))
+      controller.close()
+    },
+  })
+  return new Response(stream, {
+    status: 200,
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+function chunkedSseResponse(rawChunks: string[]): Response {
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const encoder = new TextEncoder()
+      for (const chunk of rawChunks) {
+        controller.enqueue(encoder.encode(chunk))
+      }
+      controller.close()
+    },
+  })
+  return new Response(stream, {
+    status: 200,
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+async function collect<T>(iter: AsyncIterable<T>): Promise<T[]> {
+  const out: T[] = []
+  for await (const v of iter) out.push(v)
+  return out
+}
+
+describe('shared helpers', () => {
+  test('buildDefaultUserMessage includes selection when non-empty', () => {
+    const msg = buildDefaultUserMessage(sampleContext)
+    expect(msg).toContain('<document>\n# Title\n\nHello.\n</document>')
+    expect(msg).toContain('<selection>\nHello.\n</selection>')
+    expect(msg).toContain('<instruction>\nMake it longer.\n</instruction>')
+  })
+
+  test('buildDefaultUserMessage omits selection when empty', () => {
+    const msg = buildDefaultUserMessage({ ...sampleContext, selection: '' })
+    expect(msg).not.toContain('<selection>')
+    expect(msg).toContain('<instruction>')
+  })
+
+  test('resolveSystemPrompt: undefined → default, null → null, string → as-is', () => {
+    expect(resolveSystemPrompt(undefined)).toBe(DEFAULT_SYSTEM_PROMPT)
+    expect(resolveSystemPrompt(null)).toBeNull()
+    expect(resolveSystemPrompt('custom')).toBe('custom')
+  })
+
+  test('parseSSE strips `data: ` and ignores other lines', async () => {
+    const response = chunkedSseResponse([
+      'event: ping\n',
+      'data: hello\n',
+      '\n',
+      ': comment\n',
+      'data:nospace\n',
+      '\n',
+    ])
+    const ac = new AbortController()
+    const out = await collect(parseSSE(response, ac.signal))
+    expect(out).toEqual(['hello', 'nospace'])
+  })
+
+  test('parseSSE handles a payload split across reads', async () => {
+    const response = chunkedSseResponse(['data: hel', 'lo\n\ndata: world\n\n'])
+    const ac = new AbortController()
+    const out = await collect(parseSSE(response, ac.signal))
+    expect(out).toEqual(['hello', 'world'])
+  })
+
+  test('parseSSE preserves significant whitespace in the trailing payload', async () => {
+    // No trailing newline — the buffer reaches the tail flush. The
+    // payload here intentionally contains leading and trailing spaces
+    // (a streamed token boundary the model emitted on purpose); the
+    // tail flush must not strip them.
+    const response = chunkedSseResponse(['data:  hello world  '])
+    const ac = new AbortController()
+    const out = await collect(parseSSE(response, ac.signal))
+    expect(out).toEqual([' hello world  '])
+  })
+
+  test('parseSSE stops yielding after abort', async () => {
+    const ac = new AbortController()
+    const stream = new ReadableStream<Uint8Array>({
+      async start(controller) {
+        const encoder = new TextEncoder()
+        controller.enqueue(encoder.encode('data: a\n\n'))
+        await new Promise((r) => setTimeout(r, 0))
+        ac.abort()
+        controller.enqueue(encoder.encode('data: b\n\n'))
+        controller.close()
+      },
+    })
+    const response = new Response(stream, { status: 200 })
+    const out = await collect(parseSSE(response, ac.signal))
+    expect(out).toEqual(['a'])
+  })
+})
+
+describe('createOpenAIProvider', () => {
+  let originalFetch: typeof fetch
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+  })
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  test('refuses apiKey in browser without dangerouslyAllowBrowser', () => {
+    expect(() =>
+      createOpenAIProvider({ apiKey: 'sk-test', model: 'gpt-4o-mini' })
+    ).toThrow(/Refusing to send your API key/)
+  })
+
+  test('allows browser apiKey with dangerouslyAllowBrowser', () => {
+    expect(() =>
+      createOpenAIProvider({
+        apiKey: 'sk-test',
+        model: 'gpt-4o-mini',
+        dangerouslyAllowBrowser: true,
+      })
+    ).not.toThrow()
+  })
+
+  test('does not require dangerouslyAllowBrowser when apiKey is absent', () => {
+    expect(() =>
+      createOpenAIProvider({
+        baseURL: 'https://my-proxy.example.com',
+        headers: { Authorization: 'Bearer session-token' },
+        model: 'gpt-4o-mini',
+      })
+    ).not.toThrow()
+  })
+
+  test('refuses apiKey in worker context (no DOM, WorkerGlobalScope present)', () => {
+    // Simulate Service/Web/Shared Worker: no `document`, but
+    // `WorkerGlobalScope` is the global type.
+    vi.stubGlobal('document', undefined)
+    vi.stubGlobal('WorkerGlobalScope', class {})
+    try {
+      expect(() =>
+        createOpenAIProvider({ apiKey: 'sk-test', model: 'gpt-4o-mini' })
+      ).toThrow(/Refusing to send your API key/)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  test('does not flag Node/SSR (no DOM, no WorkerGlobalScope)', () => {
+    vi.stubGlobal('document', undefined)
+    vi.stubGlobal('WorkerGlobalScope', undefined)
+    try {
+      expect(() =>
+        createOpenAIProvider({ apiKey: 'sk-test', model: 'gpt-4o-mini' })
+      ).not.toThrow()
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  test('streams text from delta.content and stops at [DONE]', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () =>
+      sseResponse([
+        JSON.stringify({ choices: [{ delta: { content: 'Hello' } }] }),
+        JSON.stringify({ choices: [{ delta: { content: ', world' } }] }),
+        JSON.stringify({ choices: [{ delta: {} }] }),
+        '[DONE]',
+        JSON.stringify({ choices: [{ delta: { content: 'never' } }] }),
+      ])
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      apiKey: 'sk-test',
+      model: 'gpt-4o-mini',
+      dangerouslyAllowBrowser: true,
+    })
+    const out = await collect(
+      provider(sampleContext, new AbortController().signal)
+    )
+    expect(out.join('')).toBe('Hello, world')
+  })
+
+  test('sends Authorization, model, stream:true, and default messages', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () => sseResponse(['[DONE]']))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      apiKey: 'sk-test',
+      model: 'gpt-4o-mini',
+      dangerouslyAllowBrowser: true,
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+
+    expect(fetchMock).toHaveBeenCalledOnce()
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://api.openai.com/v1/chat/completions')
+    const headers = (init as RequestInit).headers as Record<string, string>
+    expect(headers.Authorization).toBe('Bearer sk-test')
+    expect(headers['Content-Type']).toBe('application/json')
+    const body = JSON.parse(String((init as RequestInit).body))
+    expect(body.model).toBe('gpt-4o-mini')
+    expect(body.stream).toBe(true)
+    expect(body.messages[0].role).toBe('system')
+    expect(body.messages[0].content).toBe(DEFAULT_SYSTEM_PROMPT)
+    expect(body.messages[1].role).toBe('user')
+    expect(body.messages[1].content).toContain('<instruction>')
+  })
+
+  test('honors baseURL, custom headers, and extra body fields', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () => sseResponse(['[DONE]']))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      baseURL: 'https://my-proxy.example.com/',
+      headers: { Authorization: 'Bearer session-token' },
+      model: 'gpt-4o-mini',
+      body: { temperature: 0.2 },
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://my-proxy.example.com/v1/chat/completions')
+    const headers = (init as RequestInit).headers as Record<string, string>
+    expect(headers.Authorization).toBe('Bearer session-token')
+    const body = JSON.parse(String((init as RequestInit).body))
+    expect(body.temperature).toBe(0.2)
+  })
+
+  test('omits system message when systemPrompt is null', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () => sseResponse(['[DONE]']))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      apiKey: 'sk-test',
+      model: 'gpt-4o-mini',
+      systemPrompt: null,
+      dangerouslyAllowBrowser: true,
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+    const body = JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))
+    expect(body.messages).toHaveLength(1)
+    expect(body.messages[0].role).toBe('user')
+  })
+
+  test('keeps an empty-string systemPrompt instead of omitting it', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () => sseResponse(['[DONE]']))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      apiKey: 'sk-test',
+      model: 'gpt-4o-mini',
+      systemPrompt: '',
+      dangerouslyAllowBrowser: true,
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+    const body = JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))
+    expect(body.messages).toHaveLength(2)
+    expect(body.messages[0]).toEqual({ role: 'system', content: '' })
+    expect(body.messages[1].role).toBe('user')
+  })
+
+  test('throws on non-2xx with body included', async () => {
+    globalThis.fetch = vi.fn(
+      async () =>
+        new Response('rate limited', {
+          status: 429,
+          headers: { 'Content-Type': 'text/plain' },
+        })
+    ) as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      apiKey: 'sk-test',
+      model: 'gpt-4o-mini',
+      dangerouslyAllowBrowser: true,
+    })
+    await expect(
+      collect(provider(sampleContext, new AbortController().signal))
+    ).rejects.toThrow(/429.*rate limited/)
+  })
+
+  test('passes the abort signal through to fetch', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () => sseResponse(['[DONE]']))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createOpenAIProvider({
+      apiKey: 'sk-test',
+      model: 'gpt-4o-mini',
+      dangerouslyAllowBrowser: true,
+    })
+    const ac = new AbortController()
+    await collect(provider(sampleContext, ac.signal))
+    const init = fetchMock.mock.calls[0]![1] as RequestInit
+    expect(init.signal).toBe(ac.signal)
+  })
+})
+
+describe('createAnthropicProvider', () => {
+  let originalFetch: typeof fetch
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+  })
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  test('streams text from text_delta and stops at message_stop', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () =>
+      sseResponse([
+        JSON.stringify({ type: 'message_start' }),
+        JSON.stringify({ type: 'content_block_start' }),
+        JSON.stringify({
+          type: 'content_block_delta',
+          delta: { type: 'text_delta', text: 'Hello' },
+        }),
+        JSON.stringify({
+          type: 'content_block_delta',
+          delta: { type: 'text_delta', text: ', world' },
+        }),
+        JSON.stringify({ type: 'content_block_stop' }),
+        JSON.stringify({ type: 'message_stop' }),
+        // Anything after message_stop must be ignored.
+        JSON.stringify({
+          type: 'content_block_delta',
+          delta: { type: 'text_delta', text: 'never' },
+        }),
+      ])
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createAnthropicProvider({
+      apiKey: 'sk-ant-test',
+      model: 'claude-sonnet-4-5',
+      dangerouslyAllowBrowser: true,
+    })
+    const out = await collect(
+      provider(sampleContext, new AbortController().signal)
+    )
+    expect(out.join('')).toBe('Hello, world')
+  })
+
+  test('sends x-api-key, anthropic-version, max_tokens, and system field', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () =>
+      sseResponse([JSON.stringify({ type: 'message_stop' })])
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createAnthropicProvider({
+      apiKey: 'sk-ant-test',
+      model: 'claude-sonnet-4-5',
+      maxTokens: 2048,
+      dangerouslyAllowBrowser: true,
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://api.anthropic.com/v1/messages')
+    const headers = (init as RequestInit).headers as Record<string, string>
+    expect(headers['x-api-key']).toBe('sk-ant-test')
+    expect(headers['anthropic-version']).toBe('2023-06-01')
+    expect(headers['anthropic-dangerous-direct-browser-access']).toBe('true')
+    const body = JSON.parse(String((init as RequestInit).body))
+    expect(body.model).toBe('claude-sonnet-4-5')
+    expect(body.max_tokens).toBe(2048)
+    expect(body.stream).toBe(true)
+    expect(body.system).toBe(DEFAULT_SYSTEM_PROMPT)
+    expect(body.messages).toHaveLength(1)
+    expect(body.messages[0].role).toBe('user')
+  })
+
+  test('omits system field when systemPrompt is null', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () =>
+      sseResponse([JSON.stringify({ type: 'message_stop' })])
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createAnthropicProvider({
+      apiKey: 'sk-ant-test',
+      model: 'claude-sonnet-4-5',
+      systemPrompt: null,
+      dangerouslyAllowBrowser: true,
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+    const body = JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))
+    expect(body.system).toBeUndefined()
+  })
+
+  test('keeps an empty-string systemPrompt instead of omitting it', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () =>
+      sseResponse([JSON.stringify({ type: 'message_stop' })])
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createAnthropicProvider({
+      apiKey: 'sk-ant-test',
+      model: 'claude-sonnet-4-5',
+      systemPrompt: '',
+      dangerouslyAllowBrowser: true,
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+    const body = JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))
+    expect(body.system).toBe('')
+  })
+
+  test('proxy mode: omits x-api-key and direct-browser-access header', async () => {
+    const fetchMock = vi.fn<FetchSig>(async () =>
+      sseResponse([JSON.stringify({ type: 'message_stop' })])
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const provider = createAnthropicProvider({
+      baseURL: 'https://my-proxy.example.com',
+      headers: { Authorization: 'Bearer session-token' },
+      model: 'claude-sonnet-4-5',
+    })
+    await collect(provider(sampleContext, new AbortController().signal))
+
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://my-proxy.example.com/v1/messages')
+    const headers = (init as RequestInit).headers as Record<string, string>
+    expect(headers['x-api-key']).toBeUndefined()
+    expect(headers['anthropic-dangerous-direct-browser-access']).toBeUndefined()
+    expect(headers.Authorization).toBe('Bearer session-token')
+  })
+
+  test('throws on non-2xx with body included', async () => {
+    globalThis.fetch = vi.fn(
+      async () =>
+        new Response('overloaded', {
+          status: 529,
+          headers: { 'Content-Type': 'text/plain' },
+        })
+    ) as unknown as typeof fetch
+
+    const provider = createAnthropicProvider({
+      apiKey: 'sk-ant-test',
+      model: 'claude-sonnet-4-5',
+      dangerouslyAllowBrowser: true,
+    })
+    await expect(
+      collect(provider(sampleContext, new AbortController().signal))
+    ).rejects.toThrow(/529.*overloaded/)
+  })
+})

package/src/llm-providers/shared.ts

@@ -0,0 +1,160 @@
+import type { AIPromptContext } from '../feature/ai/types'
+
+/// Default system prompt used by both `createOpenAIProvider` and
+/// `createAnthropicProvider`. Constrains the model to emit raw markdown
+/// suitable for the streaming + diff plugins to apply directly.
+export const DEFAULT_SYSTEM_PROMPT = `You are a writing assistant embedded in a markdown editor.
+
+Rules:
+- Output markdown only. Never wrap your output in code fences (e.g. \`\`\`markdown ... \`\`\`).
+- Never include preambles, explanations, or sign-offs — output only the edited or generated content itself.
+- Preserve the original markdown structure (headings, lists, links, code blocks) unless the instruction explicitly asks to change it.
+- If a <selection> is provided, return only the replacement for that selection — do not repeat surrounding document context.
+- If no <selection> is provided, return content to insert at the cursor that flows with the surrounding document.`
+
+/// Default user-message body. Wraps document, selection, and
+/// instruction in XML-ish tags so the model can tell them apart.
+export function buildDefaultUserMessage(context: AIPromptContext): string {
+  const parts: string[] = [`<document>\n${context.document}\n</document>`]
+  if (context.selection) {
+    parts.push(`<selection>\n${context.selection}\n</selection>`)
+  }
+  parts.push(`<instruction>\n${context.instruction}\n</instruction>`)
+  return parts.join('\n\n')
+}
+
+/// Common config shared by every built-in provider.
+export interface BaseProviderConfig {
+  /// API key used when calling the provider directly. Omit when routing
+  /// through your own backend (set `baseURL` + `headers` instead).
+  apiKey?: string
+
+  /// Override the API base URL. Defaults to the provider's official
+  /// endpoint. Point this at your own backend proxy in production
+  /// deployments so the API key never reaches the browser.
+  baseURL?: string
+
+  /// Extra headers merged into every request. Use this to inject your
+  /// app's session token when proxying through your backend.
+  headers?: Record<string, string>
+
+  /// Model identifier (e.g. `gpt-4o-mini`, `claude-sonnet-4-5`).
+  model: string
+
+  /// System prompt. Defaults to a markdown-output-only prompt that
+  /// works well with the streaming + diff plugins. Pass a custom string
+  /// to fully replace it; pass `null` to send no system prompt at all.
+  systemPrompt?: string | null
+
+  /// Required when calling the provider directly from a browser with an
+  /// `apiKey`. Setting this to `true` is an explicit acknowledgement
+  /// that your API key will be visible to anyone inspecting network
+  /// traffic. Recommended only for desktop apps, personal tools, or
+  /// BYOK setups where each user supplies their own key. Routing
+  /// through a backend (via `baseURL` + `headers`) does not need this.
+  dangerouslyAllowBrowser?: boolean
+}
+
+/// Detects any client-side execution context where the API key would
+/// be visible to user-controlled code: the main browser thread (DOM)
+/// and Web/Service/Shared/Worklet workers (`WorkerGlobalScope` is the
+/// global type in worker contexts). Node/SSR has neither.
+/// Computed on each call (rather than at module load) so tests can
+/// stub the relevant globals.
+function isBrowserLike(): boolean {
+  const g = globalThis as Record<string, unknown>
+  if (g.document !== undefined) return true
+  if (g.WorkerGlobalScope !== undefined) return true
+  return false
+}
+
+/// Throws when `apiKey` is set in a client-side context (main browser
+/// thread or Worker) without explicit `dangerouslyAllowBrowser` opt-in.
+/// Routing through a backend proxy (no `apiKey`, with `baseURL` +
+/// `headers`) bypasses this check because the key never reaches the
+/// client.
+export function assertBrowserSafe(
+  config: BaseProviderConfig,
+  providerName: string
+): void {
+  if (!config.apiKey) return
+  if (!isBrowserLike()) return
+  if (config.dangerouslyAllowBrowser) return
+  throw new Error(
+    `[${providerName}] Refusing to send your API key from a browser. ` +
+      `Direct browser → provider calls expose the key to every visitor. ` +
+      `Either route through your backend (set \`baseURL\` + \`headers\` ` +
+      `and omit \`apiKey\`), or set \`dangerouslyAllowBrowser: true\` to ` +
+      `acknowledge the risk (recommended only for desktop apps or BYOK setups).`
+  )
+}
+
+/// Resolve the system prompt. `undefined` → default, `null` → omitted,
+/// string → used as-is.
+export function resolveSystemPrompt(
+  systemPrompt: string | null | undefined
+): string | null {
+  if (systemPrompt === null) return null
+  return systemPrompt ?? DEFAULT_SYSTEM_PROMPT
+}
+
+/// Parse an SSE stream from `response.body`. Yields the payload after
+/// `data: ` for each event; ignores `event:`, `id:`, `retry:`, and
+/// comment lines. Stops cleanly when the signal aborts or the stream
+/// ends. Both OpenAI and Anthropic streaming endpoints use this format.
+export async function* parseSSE(
+  response: Response,
+  signal: AbortSignal
+): AsyncGenerator<string> {
+  if (!response.body) return
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder('utf-8')
+  let buffer = ''
+  try {
+    while (true) {
+      if (signal.aborted) return
+      const { done, value } = await reader.read()
+      if (signal.aborted) return
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      let nl: number
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        const raw = buffer.slice(0, nl)
+        buffer = buffer.slice(nl + 1)
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw
+        if (line.startsWith('data: ')) {
+          yield line.slice(6)
+        } else if (line.startsWith('data:')) {
+          yield line.slice(5)
+        }
+      }
+    }
+    // Flush any trailing data line that wasn't newline-terminated.
+    // Only strip a trailing `\r` (handle CRLF without an LF) — never
+    // `trim()` here, since the payload's leading/trailing whitespace
+    // is significant for streamed token content.
+    const tail = buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer
+    if (tail.startsWith('data: ')) yield tail.slice(6)
+    else if (tail.startsWith('data:')) yield tail.slice(5)
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+/// Throw a useful error when the API responds with a non-2xx status.
+/// Reads the body once for diagnostics.
+export async function readErrorBody(
+  response: Response,
+  providerName: string
+): Promise<Error> {
+  let body = ''
+  try {
+    body = await response.text()
+  } catch {
+    // ignore — we still want to throw a status-only error
+  }
+  return new Error(
+    `[${providerName}] Request failed with status ${response.status}` +
+      (body ? `: ${body.slice(0, 500)}` : '')
+  )
+}