modeldispatcher-browser-agent 0.6.0

package/README.md

@@ -0,0 +1,203 @@
+# modeldispatcher-browser-agent
+
+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, or a local Ollama from
+the browser, using whatever key(s) the end user supplies. No vendor SDK, no
+server, nothing sent anywhere but the provider itself.
+
+`AgentConfig` is a **fallback list**, not a single selection: configure more
+than one provider (and more than one pooled key per provider), and
+`complete`/`streamComplete`/`streamChat` try each candidate in order,
+falling through to the next key or provider on failure instead of failing
+the whole request — the same idea as the Python core's fallback chain,
+running client-side.
+
+Extracted from four apps (StepByLearn, JobFlowTracker, KanDOne, HighFive)
+that had each independently built the same thing — one canonical provider
+registry, request/response handling, and streaming parser instead of four
+near-duplicate copies.
+
+## Install
+
+```bash
+npm install modeldispatcher-browser-agent
+```
+
+(Published to the public npm registry — no `.npmrc` or token needed.)
+
+## Usage
+
+```ts
+import { loadConfig, complete, streamChat, PROVIDERS, MODEL_OPTIONS } from "modeldispatcher-browser-agent";
+
+// Reads the whole fallback list from localStorage by default (one JSON
+// blob under "aiConfig"); pass a ConfigStorage + ConfigKeys to use your
+// app's own key name.
+const cfg = loadConfig();
+// cfg.providers: [{ provider: "gemini", model: "gemini-2.0-flash", apiKeys: ["AIza-..."] }, ...]
+// cfg.ollamaUrl: "http://localhost:11434"
+
+// One-shot, full text back — tries cfg.providers in order, and each
+// provider's own pooled keys in order, until one succeeds:
+const answer = await complete(cfg, "Summarise this in one sentence: ...");
+
+// One-shot, incremental text back:
+await streamComplete(cfg, "Write a haiku", { onChunk: (text) => render(text) });
+
+// Multi-turn chat — normalises a raw UI message list (role validation,
+// user-first ordering, merging) before dispatching:
+await streamChat(cfg, uiMessages, {
+  systemInstruction: "You are a helpful assistant.",
+  onChunk: (text) => render(text),
+});
+```
+
+`PROVIDERS` is the canonical registry (name, default model, key placeholder,
+where to get a key) and `MODEL_OPTIONS`/`modelOptionsFor(id)` a curated
+shortlist of current models per vendor — together enough to render a
+provider `<select>` and a model `<select>`, the same shape every app's
+`APIKeySettings`/`Settings` screen already builds by hand.
+
+### Fallback errors
+
+```ts
+import { NoProviderConfiguredError, AllProvidersExhaustedError } from "modeldispatcher-browser-agent";
+
+try {
+  await complete(cfg, prompt);
+} catch (err) {
+  if (err instanceof NoProviderConfiguredError) {
+    // cfg.providers has nothing usable — send the visitor to AI settings.
+  } else if (err instanceof AllProvidersExhaustedError) {
+    // Every configured provider/key was tried. err.attempts is
+    // [{ provider, error }, ...] for a detailed failure message.
+  } else {
+    throw err;
+  }
+}
+```
+
+A streaming call (`streamComplete`/`streamChat`) only falls back **before**
+the first chunk of a given candidate reaches `onChunk`. Once any text has
+streamed, a later failure on that same candidate is thrown immediately
+instead of silently retried on the next provider — the caller has already
+rendered a partial answer, and switching providers mid-stream would
+duplicate or contradict it rather than complete it.
+
+## No-API-key escape hatch: `openExternalChat`
+
+For a user with no API key configured (or who just doesn't want to set one
+up), `openExternalChat` hands their question off to a free, public AI chat
+product instead — ChatGPT, Claude, Gemini (via Google Search's AI Mode), or
+Groq — opening it in a new tab with the question pre-filled where the
+product supports that, and always copying the question to the clipboard too
+as a fallback:
+
+```ts
+import { openExternalChat, EXTERNAL_CHAT_PROVIDERS } from "modeldispatcher-browser-agent";
+
+const result = await openExternalChat("claude", "Summarise this in one sentence: ...");
+// result.prefilled        — true if the question actually made it into the URL
+// result.copiedToClipboard — true if it's also on the clipboard, for pasting
+```
+
+`EXTERNAL_CHAT_PROVIDERS` lists the four supported products for rendering a
+picker, the same way `PROVIDERS` does for the BYOK providers above.
+
+**Why this needs a clipboard fallback at all:** the URL query parameters that
+pre-fill a provider's chat box (`claude.ai/new?q=...`, `chatgpt.com/?q=...`,
+Google Search's `udm=50` AI Mode) are undocumented, reverse-engineered
+conventions — not a stable API any vendor promises to keep working. Groq has
+no known one at all, so it just opens the plain homepage. `openExternalChat`
+always copies the question to the clipboard regardless, so a broken or
+removed parameter never means the user's question is lost, just that they
+paste instead of finding it already typed in.
+
+## Saving a favorite for the escape hatch: `loadExternalChatFavorite`
+
+`openExternalChat` is an *action* — it navigates the instant it's called, so
+it belongs on a button next to wherever the user is actually about to ask
+something, never inside a settings screen (clicking a settings option should
+never itself open a new tab). What *does* belong in settings is letting the
+visitor pick and save **which** free product they'd reach for, ahead of
+time — that's what this is for:
+
+```ts
+import {
+  loadExternalChatFavorite,
+  saveExternalChatFavorite,
+} from "modeldispatcher-browser-agent";
+
+// Settings screen: save the pick. No network call, no navigation.
+saveExternalChatFavorite("claude");
+
+// Wherever the user composes a question: read it back to decide what
+// the "ask externally" button should say/do.
+const favorite = loadExternalChatFavorite(); // "claude" | null
+if (favorite) {
+  await openExternalChat(favorite, currentQuestion);
+}
+```
+
+Deliberately separate storage from `loadConfig`/`saveConfig` (BYOK
+provider/key/model) — picking a favorite here has nothing to do with which
+BYOK provider is configured, and a settings screen commonly offers both as
+independent, unrelated choices.
+
+## Making it optional per app: `resolveDispatcherFeatures`
+
+Adopting this doesn't have to be all-or-nothing on day one. Two independent,
+developer-set flags — never a switch an end user sees — decide what an app
+actually turns on:
+
+```ts
+// modeldispatcher.config.ts — your app's own config module, not exported to users
+import { resolveDispatcherFeatures } from "modeldispatcher-browser-agent";
+
+export const dispatcherFeatures = resolveDispatcherFeatures({
+  ui: import.meta.env.VITE_MODEL_DISPATCHER_UI !== "false",
+  dispatch: import.meta.env.VITE_MODEL_DISPATCHER_DISPATCH !== "false",
+});
+```
+
+```tsx
+function AiSettingsScreen() {
+  // .ui: render <ModelPicker>/<AskExternallyButton>, or this app's own settings screen.
+  return dispatcherFeatures.ui ? <ModelPicker {...props} /> : <LegacyAiSettings />;
+}
+
+async function askAi(question: string) {
+  // .dispatch: route through complete()'s fallback dispatch, or this app's own call path.
+  return dispatcherFeatures.dispatch ? complete(loadConfig(), question) : legacyAskAi(question);
+}
+```
+
+Both default to `true` — resolving with no overrides at all turns everything
+on — so an app opts *out* per feature during a gradual rollout rather than
+opting in from a cold start. This package never reads environment variables
+itself (every bundler exposes them differently); your app's config module
+resolves its own env var and passes the boolean in. Full pattern, including
+the non-Vite env var forms: [`docs/USAGE.md`](../../docs/USAGE.md).
+
+## What's in scope, what isn't
+
+This package owns the generic "talk to a provider" plumbing: provider
+configs, request/response translation, SSE/NDJSON stream parsing, retry on
+429/5xx, cross-provider/cross-key fallback dispatch, timeout/abort handling,
+Ollama URL validation, and chat-history normalisation. It deliberately does
+**not** know about any app's actual
+prompts or business logic (job-search coaching, trip parsing, whatever) —
+that stays in each app, calling through this the same way
+`services/llm_model_dispatcher.py` in AppMyTrip calls through the Python
+gateway without the gateway knowing what a "trip" is.
+
+## Testing
+
+```bash
+npm run typecheck
+npm test
+```
+
+All 81 tests run against mocked `fetch`/`ReadableStream`/`window.open`/
+clipboard — no real network, no real API key needed.

package/dist/agent.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The public entry points — now multi-provider: `cfg.providers` is an
+ * ordered fallback list (each vendor with one or more pooled keys) instead
+ * of a single vendor+key, so a rate limit, bad key, or outage on the first
+ * configured provider falls through to the next instead of failing the
+ * whole request. Mirrors the Python core's fallback chain, simplified for a
+ * browser client with no shared quota/routing state to manage.
+ *
+ *   - complete()       — one-shot prompt in, full text back (HighFive, StepByLearn)
+ *   - streamComplete()  — one-shot prompt in, incremental text via onChunk (JobFlowTracker's runStream)
+ *   - streamChat()      — a UI chat history in (auto-normalised via buildMessages), incremental text back (JobFlowTracker's/KanDOne's streamChat)
+ *
+ * All three dispatch on each candidate's `provider` to the matching
+ * provider module; callers never need their own provider switch statement.
+ */
+import { type BuildMessagesOptions } from "./messages.js";
+import type { AgentConfig, ChatMessage, RequestOptions, StreamOptions } from "./types.js";
+/** One candidate that failed, kept only to compose
+ * {@link AllProvidersExhaustedError}'s message. */
+interface FailedAttempt {
+    readonly provider: string;
+    readonly error: string;
+}
+/** `cfg.providers` has nothing usable at all — no vendor has a pooled key,
+ * and Ollama isn't configured either. Raised before any network call, the
+ * same way the Python core's `NoProviderAvailableError` is. */
+export declare class NoProviderConfiguredError extends Error {
+    constructor();
+}
+/** Every configured provider/key was tried and every one failed. */
+export declare class AllProvidersExhaustedError extends Error {
+    readonly attempts: readonly FailedAttempt[];
+    constructor(attempts: readonly FailedAttempt[]);
+}
+/** Non-streaming completion, tried across every configured provider/key in
+ * order until one succeeds. `prompt` is wrapped as a single user turn; pass
+ * `messages` instead for an already-built multi-turn history.
+ *
+ * Raises:
+ *   NoProviderConfiguredError: `cfg.providers` has no usable credential at all.
+ *   AllProvidersExhaustedError: every candidate was tried and failed;
+ *     `.attempts` lists each provider and its error.
+ */
+export declare function complete(cfg: AgentConfig, promptOrMessages: string | readonly ChatMessage[], options?: RequestOptions): Promise<string>;
+/**
+ * Streaming completion, tried across every configured provider/key in
+ * order — but only up to the first chunk actually streamed. Once any text
+ * has reached `onChunk` for a candidate, a later failure on that same
+ * candidate is surfaced immediately rather than silently retried on the
+ * next provider: the caller has already rendered a partial answer, and
+ * switching providers mid-stream would duplicate or contradict it rather
+ * than complete it.
+ *
+ * Raises the same errors as {@link complete}.
+ */
+export declare function streamComplete(cfg: AgentConfig, promptOrMessages: string | readonly ChatMessage[], options: StreamOptions): Promise<string>;
+/**
+ * Streaming multi-turn chat: normalises a raw UI message list via
+ * {@link buildMessages} (role validation, alternation, sentinel-dropping)
+ * before dispatching — the one thing `streamComplete()` deliberately
+ * doesn't do, since its `messages` input is assumed already well-formed.
+ */
+export declare function streamChat(cfg: AgentConfig, uiMessages: readonly ChatMessage[], options: StreamOptions & BuildMessagesOptions): Promise<string>;
+export {};

package/dist/agent.js

@@ -0,0 +1,160 @@
+/**
+ * The public entry points — now multi-provider: `cfg.providers` is an
+ * ordered fallback list (each vendor with one or more pooled keys) instead
+ * of a single vendor+key, so a rate limit, bad key, or outage on the first
+ * configured provider falls through to the next instead of failing the
+ * whole request. Mirrors the Python core's fallback chain, simplified for a
+ * browser client with no shared quota/routing state to manage.
+ *
+ *   - complete()       — one-shot prompt in, full text back (HighFive, StepByLearn)
+ *   - streamComplete()  — one-shot prompt in, incremental text via onChunk (JobFlowTracker's runStream)
+ *   - streamChat()      — a UI chat history in (auto-normalised via buildMessages), incremental text back (JobFlowTracker's/KanDOne's streamChat)
+ *
+ * All three dispatch on each candidate's `provider` to the matching
+ * provider module; callers never need their own provider switch statement.
+ */
+import { buildMessages } from "./messages.js";
+import { completeAnthropic, streamAnthropic } from "./providers/anthropic.js";
+import { completeGemini, streamGemini } from "./providers/gemini.js";
+import { completeOllama, streamOllama } from "./providers/ollama.js";
+import { completeOpenAICompatible, streamOpenAICompatible } from "./providers/openaiCompatible.js";
+/** `cfg.providers` has nothing usable at all — no vendor has a pooled key,
+ * and Ollama isn't configured either. Raised before any network call, the
+ * same way the Python core's `NoProviderAvailableError` is. */
+export class NoProviderConfiguredError extends Error {
+    constructor() {
+        super("No AI provider is configured — add a provider and key (or Ollama) in AI settings.");
+        this.name = "NoProviderConfiguredError";
+    }
+}
+/** Every configured provider/key was tried and every one failed. */
+export class AllProvidersExhaustedError extends Error {
+    attempts;
+    constructor(attempts) {
+        super(`All configured AI providers failed: ${attempts.map((a) => `${a.provider} (${a.error})`).join("; ")}`);
+        this.name = "AllProvidersExhaustedError";
+        this.attempts = attempts;
+    }
+}
+/**
+ * Flatten the configured provider list into concrete, single-key attempts,
+ * in fallback order: each provider's own pooled keys are tried in the order
+ * they were added before moving to the next configured provider. Ollama
+ * contributes at most one candidate (it authenticates via `cfg.ollamaUrl`,
+ * not a key) and only when its own entry is present in the list — a
+ * provider with no usable credential is never offered as a candidate at
+ * all, the same rule the Python core's registry-building applies.
+ */
+function candidatesOf(cfg) {
+    const candidates = [];
+    for (const cred of cfg.providers) {
+        if (cred.provider === "ollama") {
+            candidates.push({ provider: "ollama", model: cred.model, apiKey: "", ollamaUrl: cfg.ollamaUrl });
+            continue;
+        }
+        for (const apiKey of cred.apiKeys) {
+            if (apiKey)
+                candidates.push({ provider: cred.provider, model: cred.model, apiKey, ollamaUrl: cfg.ollamaUrl });
+        }
+    }
+    return candidates;
+}
+function messagesOf(promptOrMessages) {
+    return typeof promptOrMessages === "string" ? [{ role: "user", content: promptOrMessages }] : promptOrMessages;
+}
+function completeOne(candidate, messages, options) {
+    switch (candidate.provider) {
+        case "gemini":
+            return completeGemini(candidate, messages, options);
+        case "anthropic":
+            return completeAnthropic(candidate, messages, options);
+        case "ollama":
+            return completeOllama(candidate, messages, options);
+        case "openai":
+        case "groq":
+            return completeOpenAICompatible(candidate.provider, candidate, messages, options);
+    }
+}
+/** Non-streaming completion, tried across every configured provider/key in
+ * order until one succeeds. `prompt` is wrapped as a single user turn; pass
+ * `messages` instead for an already-built multi-turn history.
+ *
+ * Raises:
+ *   NoProviderConfiguredError: `cfg.providers` has no usable credential at all.
+ *   AllProvidersExhaustedError: every candidate was tried and failed;
+ *     `.attempts` lists each provider and its error.
+ */
+export async function complete(cfg, promptOrMessages, options = {}) {
+    const candidates = candidatesOf(cfg);
+    if (candidates.length === 0)
+        throw new NoProviderConfiguredError();
+    const messages = messagesOf(promptOrMessages);
+    const attempts = [];
+    for (const candidate of candidates) {
+        try {
+            return await completeOne(candidate, messages, options);
+        }
+        catch (err) {
+            attempts.push({ provider: candidate.provider, error: err.message });
+        }
+    }
+    throw new AllProvidersExhaustedError(attempts);
+}
+function streamOne(candidate, messages, onChunk, options) {
+    switch (candidate.provider) {
+        case "gemini":
+            return streamGemini(candidate, messages, onChunk, options);
+        case "anthropic":
+            return streamAnthropic(candidate, messages, onChunk, options);
+        case "ollama":
+            return streamOllama(candidate, messages, onChunk, options);
+        case "openai":
+        case "groq":
+            return streamOpenAICompatible(candidate.provider, candidate, messages, onChunk, options);
+    }
+}
+/**
+ * Streaming completion, tried across every configured provider/key in
+ * order — but only up to the first chunk actually streamed. Once any text
+ * has reached `onChunk` for a candidate, a later failure on that same
+ * candidate is surfaced immediately rather than silently retried on the
+ * next provider: the caller has already rendered a partial answer, and
+ * switching providers mid-stream would duplicate or contradict it rather
+ * than complete it.
+ *
+ * Raises the same errors as {@link complete}.
+ */
+export async function streamComplete(cfg, promptOrMessages, options) {
+    const candidates = candidatesOf(cfg);
+    if (candidates.length === 0)
+        throw new NoProviderConfiguredError();
+    const messages = messagesOf(promptOrMessages);
+    const { onChunk, ...rest } = options;
+    const attempts = [];
+    for (const candidate of candidates) {
+        let startedStreaming = false;
+        try {
+            return await streamOne(candidate, messages, (text) => {
+                startedStreaming = true;
+                onChunk(text);
+            }, rest);
+        }
+        catch (err) {
+            if (startedStreaming)
+                throw err;
+            attempts.push({ provider: candidate.provider, error: err.message });
+        }
+    }
+    throw new AllProvidersExhaustedError(attempts);
+}
+/**
+ * Streaming multi-turn chat: normalises a raw UI message list via
+ * {@link buildMessages} (role validation, alternation, sentinel-dropping)
+ * before dispatching — the one thing `streamComplete()` deliberately
+ * doesn't do, since its `messages` input is assumed already well-formed.
+ */
+export async function streamChat(cfg, uiMessages, options) {
+    const normalised = buildMessages(uiMessages, options);
+    return streamComplete(cfg, normalised, options);
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { AgentConfig, 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 declare const DEFAULT_CONFIG_KEYS: ConfigKeys;
+/** 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 declare function resolveStorage(storage?: ConfigStorage): ConfigStorage;
+/** 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 declare function loadConfig(storage?: ConfigStorage, keys?: ConfigKeys): AgentConfig;
+/** 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 declare function saveConfig(config: AgentConfig, storage?: ConfigStorage, keys?: ConfigKeys): void;
+export declare function clearConfig(storage?: ConfigStorage, keys?: ConfigKeys): void;
+/** 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 declare function isConfigReady(cfg: AgentConfig): boolean;
+/** True when `provider` isn't already in `cfg.providers` — for an "Add
+ * provider" control to only offer vendors not yet configured. */
+export declare function isProviderConfigured(cfg: AgentConfig, provider: ProviderId): boolean;

package/dist/config.js

@@ -0,0 +1,91 @@
+/**
+ * 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";
+export const DEFAULT_CONFIG_KEYS = {
+    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) {
+    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) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const { provider, model, apiKeys } = raw;
+    if (typeof provider !== "string" || !isKnownProvider(provider))
+        return null;
+    const keys = Array.isArray(apiKeys)
+        ? apiKeys.filter((k) => 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, keys = DEFAULT_CONFIG_KEYS) {
+    const store = resolveStorage(storage);
+    const raw = store.getItem(keys.config);
+    if (!raw)
+        return { providers: [], ollamaUrl: DEFAULT_OLLAMA_URL };
+    let parsed;
+    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;
+    const sanitized = Array.isArray(providers)
+        ? providers.map(sanitizeCredential).filter((c) => 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, storage, keys = DEFAULT_CONFIG_KEYS) {
+    const store = resolveStorage(storage);
+    const cleaned = {
+        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, keys = DEFAULT_CONFIG_KEYS) {
+    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) {
+    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, provider) {
+    return cfg.providers.some((cred) => cred.provider === provider);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/externalChat.d.ts

@@ -0,0 +1,46 @@
+/**
+ * "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 declare const EXTERNAL_CHAT_PROVIDERS: Record<ExternalChatProviderId, ExternalChatProviderInfo>;
+/** 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;
+}
+/**
+ * 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 declare function openExternalChat(provider: ExternalChatProviderId, question: string, deps?: OpenExternalChatDeps): Promise<OpenExternalChatResult>;