modeldispatcher-browser-agent 0.6.0 → 0.6.7

package/src/externalChat.ts

@@ -1,115 +1,124 @@
-/**
- * "Free agent" escape hatch: hand a question off to a free, public AI chat
- * web product instead of calling any API. For a BYOK app, this is what a
- * user with no API key configured (or who just doesn't want to set one up)
- * falls back to — open one of the well-known consumer chat products in a new
- * tab, with the question pre-filled where the product supports it.
- *
- * The query-prefill URL parameters below are undocumented, reverse-engineered
- * conventions (the kind of thing browser address-bar integrations and
- * "Ask X" share links rely on) — not a stable public API any vendor promises
- * to keep working, and they can change or disappear without notice. Treat
- * them as best-effort: `openExternalChat` always copies the question to the
- * clipboard too, regardless of whether a prefill parameter exists, so a
- * broken/removed parameter still leaves the user able to paste it in by hand
- * instead of silently losing their question.
- */
-
-import type { ExternalChatProviderId, ExternalChatProviderInfo } from "./types.js";
-
-export const EXTERNAL_CHAT_PROVIDERS: Record<ExternalChatProviderId, ExternalChatProviderInfo> = {
-  chatgpt: {
-    id: "chatgpt",
-    name: "ChatGPT",
-    homeUrl: "https://chatgpt.com/",
-    buildUrl: (question) => `https://chatgpt.com/?${new URLSearchParams({ q: question, hints: "search" })}`,
-  },
-  claude: {
-    id: "claude",
-    name: "Claude",
-    homeUrl: "https://claude.ai/new",
-    buildUrl: (question) => `https://claude.ai/new?${new URLSearchParams({ q: question })}`,
-  },
-  gemini: {
-    id: "gemini",
-    name: "Gemini (Google AI Mode)",
-    homeUrl: "https://www.google.com/",
-    // gemini.google.com itself has no known prefill parameter. Google
-    // Search's AI Mode does (`udm=50`), and is the more reliable target for
-    // "ask Google's AI this" — that's what this actually opens.
-    buildUrl: (question) => `https://www.google.com/search?${new URLSearchParams({ q: question, udm: "50" })}`,
-  },
-  groq: {
-    id: "groq",
-    name: "Groq",
-    homeUrl: "https://groq.com/",
-    // No known query-prefill parameter for Groq's consumer chat product —
-    // opens the plain homepage; the question still goes to the clipboard.
-    buildUrl: null,
-  },
-};
-
-/** Minimal shape of the two browser APIs this needs — injectable so this is
- * testable outside a real browser and swappable for a non-browser host. */
-export interface OpenExternalChatDeps {
-  open?: (url: string) => unknown;
-  clipboard?: { writeText(text: string): Promise<void> };
-}
-
-export interface OpenExternalChatResult {
-  readonly provider: ExternalChatProviderId;
-  readonly url: string;
-  /** True if this provider has a known prefill parameter and the question
-   * was actually embedded in `url`. False means `url` is just `homeUrl`. */
-  readonly prefilled: boolean;
-  /** True if the question was successfully copied to the clipboard — the
-   * fallback path a user needs whenever `prefilled` is false, and a useful
-   * safety net even when it's true. */
-  readonly copiedToClipboard: boolean;
-}
-
-function defaultOpen(url: string): void {
-  if (typeof window === "undefined") return;
-  window.open(url, "_blank", "noopener,noreferrer");
-}
-
-function resolveClipboard(
-  clipboard?: OpenExternalChatDeps["clipboard"],
-): OpenExternalChatDeps["clipboard"] | undefined {
-  if (clipboard) return clipboard;
-  if (typeof navigator !== "undefined" && navigator.clipboard) return navigator.clipboard;
-  return undefined;
-}
-
-/**
- * Open `provider`'s chat with `question`, pre-filled where a prefill
- * parameter is known, and always copy `question` to the clipboard as well.
- *
- * Never throws: a clipboard failure (permissions, a non-secure context, a
- * non-browser host) is reported via `copiedToClipboard: false` rather than
- * rejecting, since the tab still opens either way.
- */
-export async function openExternalChat(
-  provider: ExternalChatProviderId,
-  question: string,
-  deps: OpenExternalChatDeps = {},
-): Promise<OpenExternalChatResult> {
-  const info = EXTERNAL_CHAT_PROVIDERS[provider];
-  const prefilled = info.buildUrl !== null;
-  const url = info.buildUrl ? info.buildUrl(question) : info.homeUrl;
-
-  const clipboard = resolveClipboard(deps.clipboard);
-  let copiedToClipboard = false;
-  if (clipboard) {
-    try {
-      await clipboard.writeText(question);
-      copiedToClipboard = true;
-    } catch {
-      copiedToClipboard = false;
-    }
-  }
-
-  (deps.open ?? defaultOpen)(url);
-
-  return { provider, url, prefilled, copiedToClipboard };
-}
+/**
+ * "Free agent" escape hatch: hand a question off to a free, public AI chat
+ * web product instead of calling any API. For a BYOK app, this is what a
+ * user with no API key configured (or who just doesn't want to set one up)
+ * falls back to — open one of the well-known consumer chat products in a new
+ * tab, with the question pre-filled where the product supports it.
+ *
+ * The query-prefill URL parameters below are undocumented, reverse-engineered
+ * conventions (the kind of thing browser address-bar integrations and
+ * "Ask X" share links rely on) — not a stable public API any vendor promises
+ * to keep working, and they can change or disappear without notice. Treat
+ * them as best-effort: `openExternalChat` always copies the question to the
+ * clipboard too, regardless of whether a prefill parameter exists, so a
+ * broken/removed parameter still leaves the user able to paste it in by hand
+ * instead of silently losing their question.
+ */
+
+import type { ExternalChatProviderId, ExternalChatProviderInfo } from "./types.js";
+
+export const EXTERNAL_CHAT_PROVIDERS: Record<ExternalChatProviderId, ExternalChatProviderInfo> = {
+  chatgpt: {
+    id: "chatgpt",
+    name: "ChatGPT",
+    homeUrl: "https://chatgpt.com/",
+    buildUrl: (question) => `https://chatgpt.com/?${new URLSearchParams({ q: question, hints: "search" })}`,
+  },
+  claude: {
+    id: "claude",
+    name: "Claude",
+    homeUrl: "https://claude.ai/new",
+    buildUrl: (question) => `https://claude.ai/new?${new URLSearchParams({ q: question })}`,
+  },
+  gemini: {
+    id: "gemini",
+    name: "Gemini (Google AI Mode)",
+    homeUrl: "https://www.google.com/",
+    // gemini.google.com itself has no known prefill parameter. Google
+    // Search's AI Mode does (`udm=50`), and is the more reliable target for
+    // "ask Google's AI this" — that's what this actually opens.
+    buildUrl: (question) => `https://www.google.com/search?${new URLSearchParams({ q: question, udm: "50" })}`,
+  },
+  geminiApp: {
+    id: "geminiApp",
+    name: "Gemini",
+    homeUrl: "https://gemini.google.com/app",
+    // The real Gemini app, distinct from the AI-Mode entry above. It has no
+    // known query-prefill parameter — opens the plain app; the question
+    // still goes to the clipboard.
+    buildUrl: null,
+  },
+  groq: {
+    id: "groq",
+    name: "Groq",
+    homeUrl: "https://groq.com/",
+    // No known query-prefill parameter for Groq's consumer chat product —
+    // opens the plain homepage; the question still goes to the clipboard.
+    buildUrl: null,
+  },
+};
+
+/** Minimal shape of the two browser APIs this needs — injectable so this is
+ * testable outside a real browser and swappable for a non-browser host. */
+export interface OpenExternalChatDeps {
+  open?: (url: string) => unknown;
+  clipboard?: { writeText(text: string): Promise<void> };
+}
+
+export interface OpenExternalChatResult {
+  readonly provider: ExternalChatProviderId;
+  readonly url: string;
+  /** True if this provider has a known prefill parameter and the question
+   * was actually embedded in `url`. False means `url` is just `homeUrl`. */
+  readonly prefilled: boolean;
+  /** True if the question was successfully copied to the clipboard — the
+   * fallback path a user needs whenever `prefilled` is false, and a useful
+   * safety net even when it's true. */
+  readonly copiedToClipboard: boolean;
+}
+
+function defaultOpen(url: string): void {
+  if (typeof window === "undefined") return;
+  window.open(url, "_blank", "noopener,noreferrer");
+}
+
+function resolveClipboard(
+  clipboard?: OpenExternalChatDeps["clipboard"],
+): OpenExternalChatDeps["clipboard"] | undefined {
+  if (clipboard) return clipboard;
+  if (typeof navigator !== "undefined" && navigator.clipboard) return navigator.clipboard;
+  return undefined;
+}
+
+/**
+ * Open `provider`'s chat with `question`, pre-filled where a prefill
+ * parameter is known, and always copy `question` to the clipboard as well.
+ *
+ * Never throws: a clipboard failure (permissions, a non-secure context, a
+ * non-browser host) is reported via `copiedToClipboard: false` rather than
+ * rejecting, since the tab still opens either way.
+ */
+export async function openExternalChat(
+  provider: ExternalChatProviderId,
+  question: string,
+  deps: OpenExternalChatDeps = {},
+): Promise<OpenExternalChatResult> {
+  const info = EXTERNAL_CHAT_PROVIDERS[provider];
+  const prefilled = info.buildUrl !== null;
+  const url = info.buildUrl ? info.buildUrl(question) : info.homeUrl;
+
+  const clipboard = resolveClipboard(deps.clipboard);
+  let copiedToClipboard = false;
+  if (clipboard) {
+    try {
+      await clipboard.writeText(question);
+      copiedToClipboard = true;
+    } catch {
+      copiedToClipboard = false;
+    }
+  }
+
+  (deps.open ?? defaultOpen)(url);
+
+  return { provider, url, prefilled, copiedToClipboard };
+}

package/src/externalChatFavorite.ts

@@ -1,43 +1,43 @@
-/**
- * Persistence for a visitor's saved "ask externally" favorite.
- *
- * Deliberately separate from {@link ./config.js}'s `AgentConfig`
- * (provider/key/model for BYOK dispatch): picking a favorite here means the
- * visitor wants the app to offer opening this free chat product instead of
- * calling any API, so it has nothing to do with which provider/key is
- * configured for BYOK and must never be conflated with it. A settings screen
- * showing both is choosing between two independent, saveable preferences —
- * selecting a favorite here never itself opens anything (see
- * {@link ./externalChat.js}'s `openExternalChat` for the action that does).
- */
-
-import { EXTERNAL_CHAT_PROVIDERS } from "./externalChat.js";
-import { resolveStorage, type ConfigStorage } from "./config.js";
-import type { ExternalChatProviderId } from "./types.js";
-
-export const DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY = "aiExternalChatFavorite";
-
-function isKnownExternalChatProvider(id: string): id is ExternalChatProviderId {
-  return Object.hasOwn(EXTERNAL_CHAT_PROVIDERS, id);
-}
-
-/** Read the saved favorite, or `null` if none is set (or the stored value is
- * no longer a recognised provider). */
-export function loadExternalChatFavorite(
-  storage?: ConfigStorage,
-  key: string = DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY,
-): ExternalChatProviderId | null {
-  const raw = resolveStorage(storage).getItem(key);
-  return raw !== null && isKnownExternalChatProvider(raw) ? raw : null;
-}
-
-/** Persist the favorite; pass `null` to clear it. */
-export function saveExternalChatFavorite(
-  favorite: ExternalChatProviderId | null,
-  storage?: ConfigStorage,
-  key: string = DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY,
-): void {
-  const store = resolveStorage(storage);
-  if (favorite === null) store.removeItem(key);
-  else store.setItem(key, favorite);
-}
+/**
+ * Persistence for a visitor's saved "ask externally" favorite.
+ *
+ * Deliberately separate from {@link ./config.js}'s `AgentConfig`
+ * (provider/key/model for BYOK dispatch): picking a favorite here means the
+ * visitor wants the app to offer opening this free chat product instead of
+ * calling any API, so it has nothing to do with which provider/key is
+ * configured for BYOK and must never be conflated with it. A settings screen
+ * showing both is choosing between two independent, saveable preferences —
+ * selecting a favorite here never itself opens anything (see
+ * {@link ./externalChat.js}'s `openExternalChat` for the action that does).
+ */
+
+import { EXTERNAL_CHAT_PROVIDERS } from "./externalChat.js";
+import { resolveStorage, type ConfigStorage } from "./config.js";
+import type { ExternalChatProviderId } from "./types.js";
+
+export const DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY = "aiExternalChatFavorite";
+
+function isKnownExternalChatProvider(id: string): id is ExternalChatProviderId {
+  return Object.hasOwn(EXTERNAL_CHAT_PROVIDERS, id);
+}
+
+/** Read the saved favorite, or `null` if none is set (or the stored value is
+ * no longer a recognised provider). */
+export function loadExternalChatFavorite(
+  storage?: ConfigStorage,
+  key: string = DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY,
+): ExternalChatProviderId | null {
+  const raw = resolveStorage(storage).getItem(key);
+  return raw !== null && isKnownExternalChatProvider(raw) ? raw : null;
+}
+
+/** Persist the favorite; pass `null` to clear it. */
+export function saveExternalChatFavorite(
+  favorite: ExternalChatProviderId | null,
+  storage?: ConfigStorage,
+  key: string = DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY,
+): void {
+  const store = resolveStorage(storage);
+  if (favorite === null) store.removeItem(key);
+  else store.setItem(key, favorite);
+}

package/src/features.ts

@@ -1,40 +1,40 @@
-/**
- * Per-app opt-in/opt-out for the two things this package supplies. This is a
- * developer/deploy-time decision made once when an app is wired up — never a
- * switch an end user sees or controls. Both flags default to enabled, so
- * adopting the shared framework is opt-OUT per app, not opt-in-everywhere.
- *
- * This package never reads environment variables itself: every bundler
- * exposes them differently (`import.meta.env` for Vite, `process.env` for
- * Next.js/CRA), so resolving env vars is left to each app's own config
- * module, which passes the result in as `overrides`.
- */
-
-/** Which parts of the shared framework this app has enabled. */
-export interface DispatcherFeatureFlags {
-  /** Render `<ModelPicker>`/`<AskExternallyButton>`, or this app's own settings UI. */
-  readonly ui: boolean;
-  /** Route AI calls through `complete()`/`streamComplete()`'s fallback dispatch,
-   * or this app's own existing call path. */
-  readonly dispatch: boolean;
-}
-
-/** Both features enabled — the framework's out-of-the-box behavior. */
-export const DEFAULT_DISPATCHER_FEATURES: DispatcherFeatureFlags = Object.freeze({
-  ui: true,
-  dispatch: true,
-});
-
-/**
- * Resolves the effective feature flags for this app: enabled-by-default,
- * merged with whatever this app's own config module decided to override.
- *
- * Call this once at your app's own composition root and pass the result down
- * to wherever the UI/dispatch branching actually happens — see
- * `docs/USAGE.md` for the full pattern.
- */
-export function resolveDispatcherFeatures(
-  overrides?: Partial<DispatcherFeatureFlags>,
-): DispatcherFeatureFlags {
-  return { ...DEFAULT_DISPATCHER_FEATURES, ...overrides };
-}
+/**
+ * Per-app opt-in/opt-out for the two things this package supplies. This is a
+ * developer/deploy-time decision made once when an app is wired up — never a
+ * switch an end user sees or controls. Both flags default to enabled, so
+ * adopting the shared framework is opt-OUT per app, not opt-in-everywhere.
+ *
+ * This package never reads environment variables itself: every bundler
+ * exposes them differently (`import.meta.env` for Vite, `process.env` for
+ * Next.js/CRA), so resolving env vars is left to each app's own config
+ * module, which passes the result in as `overrides`.
+ */
+
+/** Which parts of the shared framework this app has enabled. */
+export interface DispatcherFeatureFlags {
+  /** Render `<ModelPicker>`/`<AskExternallyButton>`, or this app's own settings UI. */
+  readonly ui: boolean;
+  /** Route AI calls through `complete()`/`streamComplete()`'s fallback dispatch,
+   * or this app's own existing call path. */
+  readonly dispatch: boolean;
+}
+
+/** Both features enabled — the framework's out-of-the-box behavior. */
+export const DEFAULT_DISPATCHER_FEATURES: DispatcherFeatureFlags = Object.freeze({
+  ui: true,
+  dispatch: true,
+});
+
+/**
+ * Resolves the effective feature flags for this app: enabled-by-default,
+ * merged with whatever this app's own config module decided to override.
+ *
+ * Call this once at your app's own composition root and pass the result down
+ * to wherever the UI/dispatch branching actually happens — see
+ * `docs/USAGE.md` for the full pattern.
+ */
+export function resolveDispatcherFeatures(
+  overrides?: Partial<DispatcherFeatureFlags>,
+): DispatcherFeatureFlags {
+  return { ...DEFAULT_DISPATCHER_FEATURES, ...overrides };
+}

package/src/http.ts

@@ -1,100 +1,100 @@
-/**
- * Shared HTTP plumbing every provider call needs: a request timeout merged
- * with the caller's own AbortSignal, one retry on a transient (429/5xx)
- * failure, Ollama URL validation, and a line-buffered stream reader so each
- * provider's stream parser only has to know its own line format.
- */
-
-export const DEFAULT_TIMEOUT_MS = 60_000;
-const RETRY_DELAY_MS = 600;
-
-/** A hung provider (dropped connection, stalled proxy) would otherwise hang
- * forever — fetch() has no default timeout. Merges an optional caller signal
- * (e.g. "abort because the component unmounted") with a hard ceiling. */
-export function requestSignal(
-  signal?: AbortSignal,
-  timeoutMs: number = DEFAULT_TIMEOUT_MS,
-): AbortSignal {
-  const timeoutSignal = AbortSignal.timeout(timeoutMs);
-  return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-}
-
-function isRetryableStatus(status: number): boolean {
-  return status === 429 || (status >= 500 && status < 600);
-}
-
-/**
- * fetch() with one retry on a 429/5xx or a network failure. An
- * externally-aborted request (unmount, a newer request superseding this
- * one) is never retried — that's a deliberate cancellation, not a
- * transient failure, and retrying it would just start a request nobody
- * wants the result of anymore.
- */
-export async function fetchWithRetry(
-  url: string,
-  init: RequestInit,
-  externalSignal?: AbortSignal,
-  timeoutMs: number = DEFAULT_TIMEOUT_MS,
-): Promise<Response> {
-  for (let attempt = 0; ; attempt++) {
-    try {
-      const res = await fetch(url, { ...init, signal: requestSignal(externalSignal, timeoutMs) });
-      if (attempt === 0 && isRetryableStatus(res.status)) {
-        await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
-        continue;
-      }
-      return res;
-    } catch (err) {
-      if (externalSignal?.aborted || attempt > 0) throw err;
-      await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
-    }
-  }
-}
-
-/** Reject a remote Ollama URL that isn't HTTPS (localhost is exempt — that's
- * the whole point of running it locally). Returns the normalised origin. */
-export function validateOllamaUrl(url: string): string {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch (err) {
-    throw new Error(`Invalid Ollama URL: ${(err as Error).message}`, { cause: err });
-  }
-  const isLocalhost = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
-  if (!isLocalhost && parsed.protocol !== "https:") {
-    throw new Error("Remote Ollama must use HTTPS. For local testing, use http://localhost:11434");
-  }
-  return parsed.origin;
-}
-
-/** A 200 with no body (adblocker, misbehaving proxy) would otherwise throw a
- * raw TypeError on getReader() deep inside the parser. */
-function getBodyReader(res: Response): ReadableStreamDefaultReader<Uint8Array> {
-  if (!res.body) throw new Error("Empty response body from AI provider.");
-  return res.body.getReader();
-}
-
-/** Feeds each complete line of a streamed response body to `onLine`, so
- * every provider's stream parser only needs to know its own line format
- * (SSE "data: " frames vs. bare NDJSON). */
-export async function consumeLines(res: Response, onLine: (line: string) => void): Promise<void> {
-  const reader = getBodyReader(res);
-  const decoder = new TextDecoder();
-  let buffer = "";
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    const lines = buffer.split("\n");
-    buffer = lines.pop() ?? "";
-    for (const line of lines) onLine(line);
-  }
-}
-
-/** Extract a provider's error message from a JSON error body, falling back
- * to the raw HTTP status when the body isn't shaped as expected. */
-export async function describeHttpError(res: Response): Promise<string> {
-  const body: unknown = await res.json().catch(() => ({}));
-  const message = (body as { error?: { message?: string } })?.error?.message;
-  return message ?? `HTTP ${res.status}`;
-}
+/**
+ * Shared HTTP plumbing every provider call needs: a request timeout merged
+ * with the caller's own AbortSignal, one retry on a transient (429/5xx)
+ * failure, Ollama URL validation, and a line-buffered stream reader so each
+ * provider's stream parser only has to know its own line format.
+ */
+
+export const DEFAULT_TIMEOUT_MS = 60_000;
+const RETRY_DELAY_MS = 600;
+
+/** A hung provider (dropped connection, stalled proxy) would otherwise hang
+ * forever — fetch() has no default timeout. Merges an optional caller signal
+ * (e.g. "abort because the component unmounted") with a hard ceiling. */
+export function requestSignal(
+  signal?: AbortSignal,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): AbortSignal {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || (status >= 500 && status < 600);
+}
+
+/**
+ * fetch() with one retry on a 429/5xx or a network failure. An
+ * externally-aborted request (unmount, a newer request superseding this
+ * one) is never retried — that's a deliberate cancellation, not a
+ * transient failure, and retrying it would just start a request nobody
+ * wants the result of anymore.
+ */
+export async function fetchWithRetry(
+  url: string,
+  init: RequestInit,
+  externalSignal?: AbortSignal,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<Response> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const res = await fetch(url, { ...init, signal: requestSignal(externalSignal, timeoutMs) });
+      if (attempt === 0 && isRetryableStatus(res.status)) {
+        await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+        continue;
+      }
+      return res;
+    } catch (err) {
+      if (externalSignal?.aborted || attempt > 0) throw err;
+      await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+    }
+  }
+}
+
+/** Reject a remote Ollama URL that isn't HTTPS (localhost is exempt — that's
+ * the whole point of running it locally). Returns the normalised origin. */
+export function validateOllamaUrl(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch (err) {
+    throw new Error(`Invalid Ollama URL: ${(err as Error).message}`, { cause: err });
+  }
+  const isLocalhost = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
+  if (!isLocalhost && parsed.protocol !== "https:") {
+    throw new Error("Remote Ollama must use HTTPS. For local testing, use http://localhost:11434");
+  }
+  return parsed.origin;
+}
+
+/** A 200 with no body (adblocker, misbehaving proxy) would otherwise throw a
+ * raw TypeError on getReader() deep inside the parser. */
+function getBodyReader(res: Response): ReadableStreamDefaultReader<Uint8Array> {
+  if (!res.body) throw new Error("Empty response body from AI provider.");
+  return res.body.getReader();
+}
+
+/** Feeds each complete line of a streamed response body to `onLine`, so
+ * every provider's stream parser only needs to know its own line format
+ * (SSE "data: " frames vs. bare NDJSON). */
+export async function consumeLines(res: Response, onLine: (line: string) => void): Promise<void> {
+  const reader = getBodyReader(res);
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) onLine(line);
+  }
+}
+
+/** Extract a provider's error message from a JSON error body, falling back
+ * to the raw HTTP status when the body isn't shaped as expected. */
+export async function describeHttpError(res: Response): Promise<string> {
+  const body: unknown = await res.json().catch(() => ({}));
+  const message = (body as { error?: { message?: string } })?.error?.message;
+  return message ?? `HTTP ${res.status}`;
+}