modeldispatcher-browser-agent 0.6.0

package/src/config.ts

@@ -0,0 +1,117 @@
+/**
+ * BYOK config persistence: the whole `AgentConfig` (an ordered fallback list
+ * of providers, each with its own pooled keys, plus the shared Ollama URL)
+ * as one JSON blob under one storage key — simpler than one key per field
+ * now that the config is a list rather than a single flat selection, and
+ * the key name/storage itself stay overridable so an app can keep its own
+ * naming without forking the loader logic.
+ */
+
+import { PROVIDERS, isKnownProvider } from "./registry.js";
+import type { AgentConfig, ProviderCredential, ProviderId } from "./types.js";
+
+/** Minimal Web Storage shape — matches `localStorage`, injectable for tests
+ * or for a non-browser host (e.g. a React Native AsyncStorage shim). */
+export interface ConfigStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface ConfigKeys {
+  /** Single key holding the whole config as JSON. */
+  config: string;
+}
+
+export const DEFAULT_CONFIG_KEYS: ConfigKeys = {
+  config: "aiConfig",
+};
+
+const DEFAULT_OLLAMA_URL = "http://localhost:11434";
+
+/** Resolve an explicit storage, or fall back to `localStorage` in a browser.
+ * Shared with {@link ./externalChatFavorite.js} so both persistence modules
+ * agree on where "no storage available" should throw. */
+export function resolveStorage(storage?: ConfigStorage): ConfigStorage {
+  if (storage) return storage;
+  if (typeof localStorage !== "undefined") return localStorage;
+  throw new Error(
+    "No storage available: pass a ConfigStorage explicitly outside a browser.",
+  );
+}
+
+function sanitizeCredential(raw: unknown): ProviderCredential | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const { provider, model, apiKeys } = raw as Record<string, unknown>;
+  if (typeof provider !== "string" || !isKnownProvider(provider)) return null;
+
+  const keys = Array.isArray(apiKeys)
+    ? apiKeys.filter((k): k is string => typeof k === "string" && k.trim().length > 0).map((k) => k.trim())
+    : [];
+  const resolvedModel = typeof model === "string" && model.trim() ? model.trim() : PROVIDERS[provider].defaultModel;
+
+  return { provider, model: resolvedModel, apiKeys: keys };
+}
+
+/** Read the configured provider fallback list + Ollama URL from storage.
+ * A missing, empty, or corrupt blob resolves to an empty provider list
+ * (nothing configured yet) rather than throwing — the same "still runs,
+ * just answers no-credential" posture the rest of this package uses. */
+export function loadConfig(
+  storage?: ConfigStorage,
+  keys: ConfigKeys = DEFAULT_CONFIG_KEYS,
+): AgentConfig {
+  const store = resolveStorage(storage);
+  const raw = store.getItem(keys.config);
+  if (!raw) return { providers: [], ollamaUrl: DEFAULT_OLLAMA_URL };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { providers: [], ollamaUrl: DEFAULT_OLLAMA_URL };
+  }
+  if (typeof parsed !== "object" || parsed === null) return { providers: [], ollamaUrl: DEFAULT_OLLAMA_URL };
+
+  const { providers, ollamaUrl } = parsed as Record<string, unknown>;
+  const sanitized = Array.isArray(providers)
+    ? providers.map(sanitizeCredential).filter((c): c is ProviderCredential => c !== null)
+    : [];
+  const resolvedOllamaUrl = typeof ollamaUrl === "string" && ollamaUrl.trim() ? ollamaUrl.trim() : DEFAULT_OLLAMA_URL;
+
+  return { providers: sanitized, ollamaUrl: resolvedOllamaUrl };
+}
+
+/** Persist the full config, replacing whatever was stored before — callers
+ * (e.g. `ModelPicker`) hold the authoritative in-memory list and pass the
+ * whole thing on every change, the same controlled-component pattern the
+ * React layer uses. */
+export function saveConfig(config: AgentConfig, storage?: ConfigStorage, keys: ConfigKeys = DEFAULT_CONFIG_KEYS): void {
+  const store = resolveStorage(storage);
+  const cleaned: AgentConfig = {
+    providers: config.providers.map((cred) => ({
+      provider: cred.provider,
+      model: cred.model.trim(),
+      apiKeys: cred.apiKeys.map((k) => k.trim()).filter((k) => k.length > 0),
+    })),
+    ollamaUrl: config.ollamaUrl.trim() || DEFAULT_OLLAMA_URL,
+  };
+  store.setItem(keys.config, JSON.stringify(cleaned));
+}
+
+export function clearConfig(storage?: ConfigStorage, keys: ConfigKeys = DEFAULT_CONFIG_KEYS): void {
+  resolveStorage(storage).removeItem(keys.config);
+}
+
+/** Whether `cfg` has at least one usable candidate to dispatch to — Ollama
+ * (no key needed) or any vendor with at least one pooled key. Mirrors
+ * `candidatesOf` in `agent.ts` without needing to import its internals. */
+export function isConfigReady(cfg: AgentConfig): boolean {
+  return cfg.providers.some((cred) => cred.provider === "ollama" || cred.apiKeys.length > 0);
+}
+
+/** True when `provider` isn't already in `cfg.providers` — for an "Add
+ * provider" control to only offer vendors not yet configured. */
+export function isProviderConfigured(cfg: AgentConfig, provider: ProviderId): boolean {
+  return cfg.providers.some((cred) => cred.provider === provider);
+}

package/src/externalChat.ts

@@ -0,0 +1,115 @@
+/**
+ * "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 };
+}

package/src/externalChatFavorite.ts

@@ -0,0 +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);
+}

package/src/features.ts

@@ -0,0 +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 };
+}

package/src/http.ts

@@ -0,0 +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}`;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * modeldispatcher-browser-agent — public API surface.
+ *
+ * A browser-native, bring-your-own-key AI agent core: the client-side
+ * sibling to `model-dispatcher` for apps with no backend to run the Python
+ * gateway on. Talks directly to Gemini/OpenAI/Anthropic/Groq/Ollama from the
+ * browser, using whatever key the end user supplies — no vendor SDK, no
+ * server, nothing sent anywhere but the provider itself.
+ */
+
+export {
+  AllProvidersExhaustedError,
+  complete,
+  NoProviderConfiguredError,
+  streamChat,
+  streamComplete,
+} from "./agent.js";
+export {
+  clearConfig,
+  DEFAULT_CONFIG_KEYS,
+  isConfigReady,
+  isProviderConfigured,
+  loadConfig,
+  resolveStorage,
+  saveConfig,
+} from "./config.js";
+export type { ConfigKeys, ConfigStorage } from "./config.js";
+export { DEFAULT_TIMEOUT_MS, describeHttpError, validateOllamaUrl } from "./http.js";
+export { EXTERNAL_CHAT_PROVIDERS, openExternalChat } from "./externalChat.js";
+export type { OpenExternalChatDeps, OpenExternalChatResult } from "./externalChat.js";
+export {
+  DEFAULT_EXTERNAL_CHAT_FAVORITE_KEY,
+  loadExternalChatFavorite,
+  saveExternalChatFavorite,
+} from "./externalChatFavorite.js";
+export { DEFAULT_DISPATCHER_FEATURES, resolveDispatcherFeatures } from "./features.js";
+export type { DispatcherFeatureFlags } from "./features.js";
+export { buildMessages } from "./messages.js";
+export type { BuildMessagesOptions } from "./messages.js";
+export { isKnownProvider, modelOptionsFor, MODEL_OPTIONS, PROVIDERS } from "./registry.js";
+export type {
+  AgentConfig,
+  ChatMessage,
+  ChatRole,
+  ExternalChatProviderId,
+  ExternalChatProviderInfo,
+  ProviderCredential,
+  ProviderId,
+  ProviderInfo,
+  RequestOptions,
+  StreamOptions,
+} from "./types.js";

package/src/messages.ts

@@ -0,0 +1,61 @@
+/**
+ * Normalise a UI's chat history into a provider-safe message list: strict
+ * role validation, length capping, and merging consecutive same-role
+ * messages — Anthropic and Gemini both require strict user/assistant
+ * alternation starting with "user", which raw UI state doesn't guarantee.
+ */
+
+import type { ChatMessage, ChatRole } from "./types.js";
+
+const VALID_TURN_ROLES = new Set<ChatRole>(["user", "assistant"]);
+const MAX_MESSAGE_LENGTH = 4000;
+
+export interface BuildMessagesOptions {
+  /** If true, always append a trailing filler user turn (e.g. to kick off a
+   * greeting flow) instead of only when the history would otherwise start
+   * with "assistant". */
+  forceTrailingFiller?: boolean;
+  /** The filler turn's content when one is needed to satisfy user-first
+   * ordering. Defaults to "begin". */
+  fillerContent?: string;
+  /** Marker content to drop entirely rather than treat as a real turn
+   * (e.g. a UI-internal "simulate opening" sentinel). */
+  dropContent?: string;
+}
+
+/**
+ * Build a provider-safe chat history from UI messages: validates/coerces
+ * roles, caps message length, drops sentinel content, ensures user-first
+ * ordering, and merges consecutive same-role turns (required by
+ * Anthropic/Gemini's strict alternation).
+ */
+export function buildMessages(
+  uiMessages: readonly ChatMessage[],
+  options: BuildMessagesOptions = {},
+): ChatMessage[] {
+  const { forceTrailingFiller = false, fillerContent = "begin", dropContent } = options;
+
+  let messages = uiMessages
+    .map(({ role, content }): ChatMessage => ({
+      role: VALID_TURN_ROLES.has(role) ? role : "user",
+      content: String(content ?? "").trim().slice(0, MAX_MESSAGE_LENGTH),
+    }))
+    .filter((m) => m.content.length > 0 && (dropContent === undefined || m.content !== dropContent));
+
+  if (forceTrailingFiller) {
+    messages = [...messages, { role: "user", content: fillerContent }];
+  } else if (messages.length > 0 && messages[0]?.role === "assistant") {
+    messages = [{ role: "user", content: fillerContent }, ...messages];
+  }
+
+  const merged: ChatMessage[] = [];
+  for (const message of messages) {
+    const last = merged.at(-1);
+    if (last && last.role === message.role) {
+      merged[merged.length - 1] = { role: last.role, content: `${last.content}\n\n${message.content}` };
+    } else {
+      merged.push(message);
+    }
+  }
+  return merged.length > 0 ? merged : [{ role: "user", content: fillerContent }];
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,86 @@
+/**
+ * Anthropic Claude — direct browser call via raw fetch, no SDK dependency.
+ * `anthropic-dangerous-direct-browser-access` is the header the official SDK
+ * sends under `dangerouslyAllowBrowser` — acceptable here because the user
+ * supplies their own key on their own machine; there is no backend to hide
+ * it behind in the first place.
+ */
+
+import { consumeLines, describeHttpError, fetchWithRetry } from "../http.js";
+import type { ChatMessage, ProviderCallConfig, RequestOptions } from "../types.js";
+
+const DEFAULT_MAX_TOKENS = 1024;
+const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+
+function toApiMessages(messages: readonly ChatMessage[]) {
+  return messages.filter((m) => m.role !== "system").map((m) => ({ role: m.role, content: m.content }));
+}
+
+function systemOf(messages: readonly ChatMessage[], explicit?: string): string | undefined {
+  return explicit ?? messages.find((m) => m.role === "system")?.content;
+}
+
+function buildBody(cfg: ProviderCallConfig, messages: readonly ChatMessage[], options: RequestOptions, stream: boolean) {
+  const system = systemOf(messages, options.systemInstruction);
+  return {
+    model: cfg.model,
+    max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+    ...(system ? { system } : {}),
+    messages: toApiMessages(messages),
+    ...(stream ? { stream: true } : {}),
+  };
+}
+
+function headers(cfg: ProviderCallConfig): HeadersInit {
+  return {
+    "Content-Type": "application/json",
+    "x-api-key": cfg.apiKey,
+    "anthropic-version": "2023-06-01",
+    "anthropic-dangerous-direct-browser-access": "true",
+  };
+}
+
+export async function completeAnthropic(
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  options: RequestOptions = {},
+): Promise<string> {
+  const res = await fetchWithRetry(
+    ANTHROPIC_URL,
+    { method: "POST", headers: headers(cfg), body: JSON.stringify(buildBody(cfg, messages, options, false)) },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(await describeHttpError(res));
+  const data = await res.json();
+  return data.content?.[0]?.text ?? "";
+}
+
+export async function streamAnthropic(
+  cfg: ProviderCallConfig,
+  messages: readonly ChatMessage[],
+  onChunk: (fullTextSoFar: string) => void,
+  options: RequestOptions = {},
+): Promise<string> {
+  const res = await fetchWithRetry(
+    ANTHROPIC_URL,
+    { method: "POST", headers: headers(cfg), body: JSON.stringify(buildBody(cfg, messages, options, true)) },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(await describeHttpError(res));
+
+  let full = "";
+  await consumeLines(res, (line) => {
+    if (!line.startsWith("data: ")) return;
+    const raw = line.slice(6).trim();
+    try {
+      const event = JSON.parse(raw);
+      if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+        full += event.delta.text;
+        onChunk(full);
+      }
+    } catch {
+      // Skip a malformed/partial SSE frame.
+    }
+  });
+  return full;
+}