foxmind 0.0.0-stage → 0.1.0

package/dist/browser/trialml.js

@@ -0,0 +1,196 @@
+// Firefox's own on-device inference engine, browser.trial.ml. It needs the
+// optional "trialML" permission, takes models only from the Mozilla hub and the
+// Mozilla and Xenova orgs on Hugging Face, and allows one engine per extension.
+import { FoxmindError } from "../errors.js";
+import { failure } from "../http.js";
+import { checkReply } from "../reply.js";
+import { bounded } from "./runtime.js";
+const GB = 1e9;
+/** The size of one file in a Hugging Face repo, from the hub API. */
+async function fileSize(model, file) {
+    const response = await fetch(`https://huggingface.co/api/models/${model}?blobs=true`).catch(() => undefined);
+    if (!response?.ok)
+        return undefined;
+    const info = (await response.json());
+    return info.siblings?.find((sibling) => sibling.rfilename === file)?.size;
+}
+const api = () => globalThis.browser;
+/** Ask the user for the optional trialML permission. Call it from a click handler. */
+export function requestTrialML() {
+    const permissions = api()?.permissions;
+    if (!permissions)
+        return Promise.resolve(false);
+    return permissions.request({ permissions: ["trialML"] });
+}
+/** Firefox allows one engine per extension, so the first provider to start one keeps it. */
+let engine;
+/** The status that engine progress goes to. One listener per page, however often the engine restarts. */
+let progressTo;
+let listening = false;
+/** One vector per text from whatever shape the engine returns. */
+export function toVectors(result, count) {
+    let rows = result;
+    const tensor = result;
+    if (tensor && !Array.isArray(result) && tensor.data && tensor.dims) {
+        const width = tensor.dims.at(-1);
+        const flat = Array.from(tensor.data);
+        rows = Array.from({ length: flat.length / width }, (_, i) => flat.slice(i * width, (i + 1) * width));
+    }
+    while (Array.isArray(rows) && rows.length === 1 && Array.isArray(rows[0]) && Array.isArray(rows[0][0]) && count === rows[0].length)
+        rows = rows[0];
+    const ok = Array.isArray(rows) && rows.length === count && rows.every((row) => Array.isArray(row) && row.every((x) => typeof x === "number"));
+    return ok ? rows : undefined;
+}
+/** Why trial.ml cannot run, or undefined when it can. The namespace exists only after the grant. */
+async function unavailable() {
+    const permissions = api()?.permissions;
+    if (permissions && !(await permissions.contains({ permissions: ["trialML"] }).catch(() => false))) {
+        return { code: "permission", reason: 'The optional "trialML" permission is not granted. Call requestTrialML() from a click.' };
+    }
+    if (!api()?.trial?.ml)
+        return { code: "unsupported", reason: "browser.trial.ml is missing: this is not Firefox, or trial ML is turned off." };
+    return undefined;
+}
+/** The text in a text-generation result, in any of the shapes the backends return. */
+function generatedText(output) {
+    if (typeof output === "string")
+        return output;
+    const record = output;
+    if (typeof record?.finalOutput === "string")
+        return record.finalOutput;
+    if (typeof record?.output === "string")
+        return record.output;
+    const text = output?.[0]?.generated_text;
+    return Array.isArray(text) ? text.at(-1)?.content : text;
+}
+export function trialML(options) {
+    const chat = options.task === "chat";
+    const model = options.model ?? (chat ? "Xenova/Qwen1.5-0.5B-Chat" : "Xenova/all-MiniLM-L6-v2");
+    const name = options.name ?? `trialml-${options.task}`;
+    const device = options.device ?? "wasm";
+    const origin = { provider: name, tier: "browser", secrets: [] };
+    const llama = options.backend === "llama.cpp";
+    const key = `${options.task}:${model}:${options.modelFile ?? ""}:${device}`;
+    /** Checks that need no engine: the file size, and the orgs trial ML takes models from. */
+    async function refused() {
+        if (llama && options.modelFile) {
+            const size = await fileSize(model, options.modelFile);
+            const max = options.maxBytes ?? 4 * GB;
+            if (size !== undefined && size > max) {
+                return { code: "out_of_memory", reason: `${options.modelFile} is ${(size / GB).toFixed(2)} GB, more than the ${(max / GB).toFixed(2)} GB limit (maxBytes) for a model in the browser. Run it on a local server instead.` };
+            }
+        }
+        if (!/^(Mozilla|Xenova)\//.test(model))
+            return { code: "unsupported", reason: `trial.ml takes models only from the Mozilla and Xenova orgs on Hugging Face (or the Mozilla hub), not ${model}.` };
+        return undefined;
+    }
+    const state = { state: "idle" };
+    async function ready() {
+        const blocked = (await unavailable()) ?? (await refused());
+        if (blocked)
+            throw failure(origin, blocked.code, blocked.reason);
+        const ml = api().trial.ml;
+        if (engine && engine.key !== key)
+            throw failure(origin, "unsupported", `Firefox allows one trial.ml engine per extension, and ${engine.owner} holds it (${engine.key}).`);
+        if (!engine) {
+            state.state = "loading";
+            progressTo = state;
+            if (!listening) {
+                listening = true;
+                ml.onProgress.addListener((data) => {
+                    const progress = Number(data.progress ?? data.totalProgress);
+                    if (progressTo && Number.isFinite(progress))
+                        progressTo.progress = progress > 1 ? progress / 100 : progress;
+                });
+            }
+            const request = { taskName: chat ? "text-generation" : "feature-extraction", modelHub: "huggingface", modelId: model, ...(llama ? { backend: "llama.cpp", modelFile: options.modelFile } : { device }) };
+            const started = { owner: name, key, ready: ml.createEngine(request) };
+            engine = started;
+            started.ready.catch(() => { if (engine === started)
+                engine = undefined; });
+        }
+        try {
+            await engine.ready;
+        }
+        catch (error) {
+            throw mapped(error);
+        }
+        Object.assign(state, { state: "ready", progress: 1 });
+        return ml;
+    }
+    function mapped(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        state.state = "error";
+        state.reason = message;
+        if (/disabled/i.test(message))
+            return failure(origin, "unsupported", `Trial ML is turned off in this Firefox: ${message}`);
+        if (/memory/i.test(message))
+            return failure(origin, "out_of_memory", `Firefox stopped the engine for lack of memory: ${message}`);
+        return failure(origin, "bad_response", `trial.ml failed: ${message}`);
+    }
+    /**
+     * One engine call. It stops waiting at the caller's abort or after
+     * timeoutMs (default 120 s): an engine that never answers must not hang the
+     * caller. Firefox has no call to stop the engine itself.
+     */
+    async function run(args, runOptions, callOptions = {}) {
+        const ml = await bounded(origin, ready(), { signal: callOptions.signal });
+        try {
+            return await bounded(origin, ml.runEngine({ args, options: runOptions, ...(llama ? runOptions : {}) }), { signal: callOptions.signal, timeoutMs: callOptions.timeoutMs ?? 120_000 });
+        }
+        catch (error) {
+            if (error instanceof FoxmindError)
+                throw error;
+            throw mapped(error);
+        }
+    }
+    return {
+        name,
+        tier: "browser",
+        model,
+        capabilities: chat ? ["chat"] : ["embed"],
+        async probe() {
+            const blocked = (await unavailable()) ?? (await refused());
+            if (blocked)
+                return { ok: false, ...blocked };
+            if (engine && engine.key !== key)
+                return { ok: false, code: "unsupported", reason: `${engine.owner} holds the one trial.ml engine.` };
+            return { ok: true, where: `trial.ml (${device})` };
+        },
+        status: () => ({ name, tier: "browser", model, capabilities: chat ? ["chat"] : ["embed"], where: `trial.ml (${device})`, ...state }),
+        async load() {
+            await ready();
+        },
+        ...(chat
+            ? {
+                async chat(messages, chatOptions) {
+                    if (chatOptions.tools?.length)
+                        throw failure(origin, "unsupported", "trial.ml has no tool calls. Use transformers() or a server for tools.");
+                    const plain = messages.map(({ role, content }) => ({ role, content }));
+                    const maxTokens = chatOptions.maxTokens ?? 256;
+                    // The ONNX backend takes { args, options }; the llama.cpp backend takes { prompt, nPredict }.
+                    const output = await run([plain], llama ? { prompt: plain, nPredict: maxTokens } : { max_new_tokens: maxTokens }, chatOptions);
+                    const content = generatedText(output);
+                    if (typeof content !== "string")
+                        throw failure(origin, "bad_response", "trial.ml returned no generated text.");
+                    return checkReply(origin, { message: { role: "assistant", content }, finishReason: "stop" }, chatOptions.json);
+                },
+            }
+            : {
+                async embed(texts, embedOptions) {
+                    const vectors = toVectors(await run([texts], { pooling: "mean", normalize: true }, embedOptions), texts.length);
+                    if (!vectors)
+                        throw failure(origin, "bad_response", "trial.ml returned a shape that is not one vector per text.");
+                    return vectors;
+                },
+            }),
+    };
+}
+/**
+ * Experimental: a GGUF model on Firefox's llama.cpp backend, through trial ML.
+ * Small models only: trial ML takes models from the Mozilla and Xenova orgs,
+ * and foxmind refuses files over `maxBytes` (default 4 GB) before the download.
+ */
+export function wllama(options) {
+    return trialML({ task: "chat", backend: "llama.cpp", name: options.name ?? "wllama", ...options });
+}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+export declare const USAGE = "Usage: foxmind doctor [--json] [--ollama URL] [--llama-server URL] [--lm-studio URL] [--timeout MS]\n\nChecks which local model servers run on this machine and lists their models.\nExit code 0 when at least one server works, 1 when none does, 2 for bad input.\n";
+export interface Output {
+    out(text: string): void;
+    err(text: string): void;
+}
+export declare function main(argv: string[], output: Output): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,46 @@
+// The foxmind command. Today it has one subcommand: doctor.
+import { doctor, format } from "./doctor.js";
+export const USAGE = `Usage: foxmind doctor [--json] [--ollama URL] [--llama-server URL] [--lm-studio URL] [--timeout MS]
+
+Checks which local model servers run on this machine and lists their models.
+Exit code 0 when at least one server works, 1 when none does, 2 for bad input.
+`;
+const URL_FLAGS = { "--ollama": "ollama", "--llama-server": "llamaServer", "--lm-studio": "lmStudio" };
+export async function main(argv, output) {
+    const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h") {
+        output.out(USAGE);
+        return 0;
+    }
+    const bad = (why) => {
+        output.err(`${why}\n\n${USAGE}`);
+        return 2;
+    };
+    if (command !== "doctor")
+        return bad(command ? `Unknown command "${command}".` : "Give a command.");
+    const options = {};
+    let asJson = false;
+    for (let i = 0; i < rest.length; i++) {
+        const flag = rest[i];
+        const value = rest[i + 1];
+        if (flag === "--json")
+            asJson = true;
+        else if (flag in URL_FLAGS) {
+            if (!value || !/^https?:\/\//.test(value))
+                return bad(`${flag} needs an http:// or https:// URL.`);
+            options[URL_FLAGS[flag]] = value;
+            i++;
+        }
+        else if (flag === "--timeout") {
+            if (!value || !/^\d+$/.test(value))
+                return bad("--timeout needs a number of milliseconds.");
+            options.timeoutMs = Number(value);
+            i++;
+        }
+        else
+            return bad(`Unknown flag "${flag}".`);
+    }
+    const report = await doctor(options);
+    output.out(asJson ? `${JSON.stringify(report, null, 2)}\n` : format(report));
+    return report.checks.some((check) => check.ok) ? 0 : 1;
+}

package/dist/doctor.d.ts

@@ -0,0 +1,23 @@
+export interface DoctorOptions {
+    ollama?: string;
+    llamaServer?: string;
+    lmStudio?: string;
+    timeoutMs?: number;
+}
+export interface Check {
+    tier: "local";
+    name: string;
+    ok: boolean;
+    where: string;
+    models?: string[];
+    reason?: string;
+}
+export interface Report {
+    node: string;
+    platform: string;
+    checks: Check[];
+    browser: string;
+    cloud: string;
+}
+export declare function doctor(options?: DoctorOptions): Promise<Report>;
+export declare function format(report: Report): string;

package/dist/doctor.js

@@ -0,0 +1,58 @@
+// What works on this machine: probes each local server and lists its models.
+// It never reads API keys, so it cannot print one.
+import { call } from "./http.js";
+import { SALUKI } from "./providers/presets.js";
+const START = {
+    ollama: 'Start it with "ollama serve".',
+    "llama-server": 'Start it with "llama-server -m <model.gguf> --jinja".',
+    "lm-studio": 'Start it with "lms server start".',
+};
+function api(url) {
+    const trimmed = url.replace(/\/+$/, "");
+    return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+}
+async function models(name, where, timeoutMs) {
+    const origin = { provider: name, tier: "local", secrets: [] };
+    try {
+        const fetched = await call(origin, `${where}/models`, { timeoutMs }, timeoutMs);
+        const ids = ((await fetched.json()).data ?? []).map((model) => model.id);
+        return { tier: "local", name, ok: true, where, models: ids };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message.replace(/^[^:]+\(local\): /, "") : String(error);
+        return { tier: "local", name, ok: false, where, reason: `${message.replace(/\.?$/, ".")} ${START[name]}` };
+    }
+}
+export async function doctor(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 2000;
+    const llama = api(options.llamaServer ?? "http://127.0.0.1:8080");
+    const [ollama, llamaServer, lmStudio] = await Promise.all([
+        models("ollama", api(options.ollama ?? "http://127.0.0.1:11434"), timeoutMs),
+        models("llama-server", llama, timeoutMs),
+        models("lm-studio", api(options.lmStudio ?? "http://127.0.0.1:1234"), timeoutMs),
+    ]);
+    const serving = llamaServer.models?.find((id) => /saluki/i.test(id));
+    const saluki = serving
+        ? { tier: "local", name: "saluki", ok: true, where: llama, models: [serving] }
+        : {
+            tier: "local",
+            name: "saluki",
+            ok: false,
+            where: llama,
+            reason: `${llamaServer.ok ? `llama-server serves ${llamaServer.models?.join(", ") || "no model"}, not Saluki.` : "llama-server is not running."} Download it with "${SALUKI.download}", then start it with "${SALUKI.serve}".`,
+        };
+    return {
+        node: process.version,
+        platform: `${process.platform} ${process.arch}`,
+        checks: [ollama, llamaServer, saluki, lmStudio],
+        browser: "WebGPU, trial.ml and in-browser models: doctor runs in Node and cannot check them. Load the demo extension in Firefox.",
+        cloud: "anthropic and cloud openaiCompatible: these need your own key. doctor does not read keys.",
+    };
+}
+export function format(report) {
+    const rows = report.checks.map((check) => {
+        const detail = check.ok ? `models: ${check.models?.join(", ") || "none"}` : check.reason;
+        return `${check.tier.padEnd(8)} ${check.name.padEnd(13)} ${(check.ok ? "yes" : "no").padEnd(4)} ${check.where.padEnd(28)} ${detail}`;
+    });
+    return [`foxmind doctor · Node ${report.node} · ${report.platform}`, "", ...rows, `browser  ${report.browser}`, `cloud    ${report.cloud}`, ""].join("\n");
+}

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+import type { Tier } from "./types.js";
+export type ErrorCode = "no_provider" | "unreachable" | "timeout" | "aborted" | "rate_limited" | "auth" | "model_not_found" | "http" | "stream_interrupted" | "bad_tool_call" | "bad_json" | "bad_response" | "unsupported" | "download_failed" | "cache_corrupt" | "out_of_memory" | "webgpu_missing" | "permission";
+/** A provider the router did not use, and why. */
+export interface Skip {
+    provider: string;
+    tier: Tier;
+    code: string;
+    reason: string;
+}
+export interface ErrorDetails {
+    provider?: string;
+    tier?: Tier;
+    status?: number;
+    retryAfterMs?: number;
+    /** The text that failed to parse (tool arguments or JSON), cut to 200 characters. */
+    raw?: string;
+    /** Text streamed before the failure. */
+    partial?: string;
+    skipped?: Skip[];
+    cause?: unknown;
+}
+export declare class FoxmindError extends Error {
+    readonly code: ErrorCode;
+    provider?: string;
+    tier?: Tier;
+    status?: number;
+    retryAfterMs?: number;
+    raw?: string;
+    partial?: string;
+    skipped?: Skip[];
+    constructor(code: ErrorCode, message: string, details?: ErrorDetails);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: ErrorCode;
+        provider: string | undefined;
+        tier: Tier | undefined;
+        status: number | undefined;
+        retryAfterMs: number | undefined;
+        raw: string | undefined;
+        partial: string | undefined;
+        skipped: Skip[] | undefined;
+    };
+}
+/** Replace every secret and every key-shaped string in text with "[redacted]". */
+export declare function redact(text: string, secrets?: (string | undefined)[]): string;
+/** Cut text for an error message. */
+export declare function clip(text: string, max?: number): string;

package/dist/errors.js

@@ -0,0 +1,36 @@
+export class FoxmindError extends Error {
+    code;
+    provider;
+    tier;
+    status;
+    retryAfterMs;
+    raw;
+    partial;
+    skipped;
+    constructor(code, message, details = {}) {
+        const where = details.provider ? `${details.provider}${details.tier ? ` (${details.tier})` : ""}: ` : "";
+        super(`${where}${message}`, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = "FoxmindError";
+        this.code = code;
+        const { cause: _cause, ...rest } = details;
+        Object.assign(this, rest);
+    }
+    toJSON() {
+        const { code, provider, tier, status, retryAfterMs, raw, partial, skipped } = this;
+        return { name: this.name, message: this.message, code, provider, tier, status, retryAfterMs, raw, partial, skipped };
+    }
+}
+/** Matches common API key shapes, so a key the caller did not give us is still hidden. */
+const KEY_SHAPES = /\b(sk-[A-Za-z0-9_-]{8,}|sk-ant-[A-Za-z0-9_-]{8,}|hf_[A-Za-z0-9]{8,}|AIza[A-Za-z0-9_-]{20,})/g;
+/** Replace every secret and every key-shaped string in text with "[redacted]". */
+export function redact(text, secrets = []) {
+    let out = text;
+    for (const secret of secrets)
+        if (secret && secret.length >= 4)
+            out = out.split(secret).join("[redacted]");
+    return out.replace(KEY_SHAPES, "[redacted]");
+}
+/** Cut text for an error message. */
+export function clip(text, max = 200) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}

package/dist/http.d.ts

@@ -0,0 +1,46 @@
+import { FoxmindError, type ErrorDetails } from "./errors.js";
+import type { CallOptions, Tier } from "./types.js";
+export interface Origin {
+    provider: string;
+    tier: Tier;
+    /** Secrets to hide from every error message. */
+    secrets: (string | undefined)[];
+}
+export interface Request extends CallOptions {
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * One signal for the caller's abort and a timeout that can restart. The
+ * timeout covers the wait for the response headers and then each gap between
+ * two body chunks, never the whole request, so a slow healthy stream lives.
+ */
+export declare function watchdog(options: CallOptions, fallbackMs: number): {
+    signal: AbortSignal;
+    arm: () => void;
+    stop: () => void;
+    ms: number;
+    timedOut: () => boolean;
+};
+export declare function failure(origin: Origin, code: ConstructorParameters<typeof FoxmindError>[0], message: string, details?: ErrorDetails): FoxmindError;
+/**
+ * Map an exception from fetch or a body read to a FoxmindError. When a stream
+ * was running, a dropped connection is `stream_interrupted` and the error
+ * keeps the text streamed so far.
+ */
+export declare function fetchFailure(origin: Origin, error: unknown, timedOut: boolean, url: string, timeoutMs: number, partial?: string): FoxmindError;
+/** "Retry-After" in seconds or as a date, or "retry-after-ms". */
+export declare function retryAfter(headers: Headers): number | undefined;
+/** Throw the FoxmindError for a non-2xx response. */
+export declare function httpFailure(origin: Origin, response: Response): Promise<FoxmindError>;
+export interface Fetched {
+    response: Response;
+    /** The body. Each chunk restarts the timeout; read this, not response.body. */
+    body: ReadableStream<Uint8Array> | null;
+    /** Map an error from reading the body (a timeout, a dropped connection) to a FoxmindError. */
+    fail(error: unknown, partial?: string): FoxmindError;
+    json<T>(): Promise<T>;
+}
+/** fetch() that returns an ok response or throws a FoxmindError. */
+export declare function call(origin: Origin, url: string, request: Request, fallbackMs: number): Promise<Fetched>;

package/dist/http.js

@@ -0,0 +1,164 @@
+// fetch with a timeout, a caller abort, and HTTP failures mapped to FoxmindError
+// codes. Every message goes through redact() before it leaves this file.
+import { clip, FoxmindError, redact } from "./errors.js";
+/**
+ * One signal for the caller's abort and a timeout that can restart. The
+ * timeout covers the wait for the response headers and then each gap between
+ * two body chunks, never the whole request, so a slow healthy stream lives.
+ */
+export function watchdog(options, fallbackMs) {
+    const ms = options.timeoutMs ?? fallbackMs;
+    const controller = new AbortController();
+    let fired = false;
+    let timer;
+    const stop = () => clearTimeout(timer);
+    const arm = () => {
+        stop();
+        timer = setTimeout(() => {
+            fired = true;
+            controller.abort();
+        }, ms);
+    };
+    arm();
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    return { signal, arm, stop, ms, timedOut: () => fired && !options.signal?.aborted };
+}
+export function failure(origin, code, message, details = {}) {
+    return new FoxmindError(code, redact(message, origin.secrets), {
+        ...details,
+        provider: origin.provider,
+        tier: origin.tier,
+        raw: details.raw === undefined ? undefined : clip(redact(details.raw, origin.secrets)),
+        partial: details.partial === undefined ? undefined : redact(details.partial, origin.secrets),
+    });
+}
+/**
+ * Map an exception from fetch or a body read to a FoxmindError. When a stream
+ * was running, a dropped connection is `stream_interrupted` and the error
+ * keeps the text streamed so far.
+ */
+export function fetchFailure(origin, error, timedOut, url, timeoutMs, partial) {
+    if (error instanceof FoxmindError)
+        return error;
+    const details = partial === undefined ? {} : { partial };
+    if (timedOut)
+        return failure(origin, "timeout", `${url} sent nothing for ${timeoutMs} ms.`, details);
+    if (error instanceof Error && error.name === "AbortError")
+        return failure(origin, "aborted", "The caller stopped the call.", details);
+    const cause = error instanceof Error && error.cause instanceof Error ? error.cause.message : String(error);
+    if (partial !== undefined)
+        return failure(origin, "stream_interrupted", `The stream from ${url} stopped after ${partial.length} characters: ${cause}`, details);
+    return failure(origin, "unreachable", `Cannot reach ${url}: ${cause}`);
+}
+/** "Retry-After" in seconds or as a date, or "retry-after-ms". */
+export function retryAfter(headers) {
+    const ms = Number(headers.get("retry-after-ms"));
+    if (ms > 0)
+        return ms;
+    const value = headers.get("retry-after");
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+/** The server's own words from an error body, in the OpenAI or Anthropic shape. */
+function serverMessage(text) {
+    try {
+        const body = JSON.parse(text);
+        if (typeof body.error === "string")
+            return body.error;
+        return body.error?.message ?? body.message ?? text;
+    }
+    catch {
+        return text;
+    }
+}
+/** Throw the FoxmindError for a non-2xx response. */
+export async function httpFailure(origin, response) {
+    const said = clip(serverMessage(await response.text().catch(() => "")).trim(), 300);
+    const status = response.status;
+    const text = `HTTP ${status}${said ? `: ${said}` : ""}`;
+    if (status === 429)
+        return failure(origin, "rate_limited", text, { status, retryAfterMs: retryAfter(response.headers) });
+    if (status === 401 || status === 403)
+        return failure(origin, "auth", text, { status });
+    if (status === 501)
+        return failure(origin, "unsupported", text, { status });
+    // OpenAI: "model ... does not exist"; Ollama: 'model "x" not found'; Anthropic: "model: x".
+    if ((status === 404 || status === 400) && /model/i.test(said) && /not.?found|does not exist|unknown|^model:/i.test(said)) {
+        return failure(origin, "model_not_found", text, { status });
+    }
+    return failure(origin, "http", text, { status });
+}
+/** fetch() that returns an ok response or throws a FoxmindError. */
+export async function call(origin, url, request, fallbackMs) {
+    const dog = watchdog(request, fallbackMs);
+    const fail = (error, partial) => fetchFailure(origin, error, dog.timedOut(), url, dog.ms, partial);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: request.method ?? (request.body === undefined ? "GET" : "POST"),
+            headers: { ...(request.body === undefined ? {} : { "content-type": "application/json" }), ...request.headers },
+            body: request.body === undefined ? undefined : JSON.stringify(request.body),
+            signal: dog.signal,
+            // Never follow a redirect: fetch would send the key headers to the new host.
+            redirect: "manual",
+        });
+    }
+    catch (error) {
+        dog.stop();
+        throw fail(error);
+    }
+    if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+        dog.stop();
+        const target = response.headers.get("location") ?? "a URL the browser does not show";
+        await response.body?.cancel().catch(() => { });
+        throw failure(origin, "http", `${url} answered ${response.status || "a redirect"} to ${target}. foxmind does not follow redirects, so no key goes to another URL. Use the final URL as baseURL.`, { status: response.status || undefined });
+    }
+    if (!response.ok) {
+        const failed = await httpFailure(origin, response);
+        dog.stop();
+        throw failed;
+    }
+    // The headers came: from now on the timeout is the longest gap between chunks.
+    dog.arm();
+    const reader = response.body?.getReader();
+    const body = reader
+        ? new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        dog.stop();
+                        controller.close();
+                    }
+                    else {
+                        dog.arm();
+                        controller.enqueue(value);
+                    }
+                }
+                catch (error) {
+                    dog.stop();
+                    controller.error(error);
+                }
+            },
+            cancel(reason) {
+                dog.stop();
+                return reader.cancel(reason);
+            },
+        })
+        : (dog.stop(), null);
+    const json = async () => {
+        const text = await new Response(body).text().catch((error) => { throw fail(error); });
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw failure(origin, "bad_response", `${url} sent a body that is not JSON: ${clip(text, 120)}`);
+        }
+    };
+    return { response, body, fail, json };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { FoxmindError, type ErrorCode, type Skip } from "./errors.js";
+export { openaiCompatible, type OpenAICompatibleOptions } from "./providers/openai.js";
+export type * from "./types.js";
+export { createMind, type Answered, type ChatResult, type ClassifyResult, type EmbedResult, type ExtractResult, type Mind, type MindOptions, type MindStatus } from "./mind.js";
+export { llamaServer, lmStudio, ollama, saluki, SALUKI } from "./providers/presets.js";
+export { anthropic, type AnthropicOptions } from "./providers/anthropic.js";
+export { doctor, format as formatDoctor, type Check, type DoctorOptions, type Report } from "./doctor.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// The public API of foxmind for Node and the browser.
+export { FoxmindError } from "./errors.js";
+export { openaiCompatible } from "./providers/openai.js";
+export { createMind } from "./mind.js";
+export { llamaServer, lmStudio, ollama, saluki, SALUKI } from "./providers/presets.js";
+export { anthropic } from "./providers/anthropic.js";
+export { doctor, format as formatDoctor } from "./doctor.js";