foxmind 0.0.0-stage → 0.1.0

package/dist/mind.d.ts

@@ -0,0 +1,60 @@
+import { type Skip } from "./errors.js";
+import type { CallOptions, Capability, ChatOptions, ChatReply, Entity, ExtractOptions, Labels, Message, Probe, Provider, ProviderStatus, Tier } from "./types.js";
+export interface MindOptions {
+    providers: Provider[];
+    /** Provider names or tiers ("browser", "local", "cloud"), best first. Providers not named come after, in `providers` order. */
+    prefer?: string[];
+    /**
+     * The only tiers the router may use. Providers of other tiers are dropped:
+     * never probed, never called. Private mode is `only: ["browser", "local"]`.
+     */
+    only?: Tier[];
+    /** When a call fails, try the next provider and list the failure in `skipped`. Default false. */
+    fallbackOnError?: boolean;
+    /** How long a probe result stays good. Default 30000. */
+    probeTtlMs?: number;
+}
+export interface Answered {
+    provider: string;
+    tier: Tier;
+    model: string;
+    ms: number;
+    /** Providers tried before this one, and why each did not answer. */
+    skipped: Skip[];
+}
+export type ChatResult = ChatReply & Answered;
+export interface EmbedResult extends Answered {
+    vectors: number[][];
+}
+export interface ExtractResult extends Answered {
+    entities: Record<string, Entity[]>;
+}
+export interface ClassifyResult extends Answered {
+    scores: Record<string, number>[];
+}
+export interface MindStatus {
+    providers: ProviderStatus[];
+    last?: {
+        capability: Capability;
+        provider: string;
+        tier: Tier;
+        model: string;
+        at: string;
+    };
+}
+export interface Mind {
+    readonly providers: readonly Provider[];
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResult>;
+    embed(texts: string[], options?: CallOptions): Promise<EmbedResult>;
+    extract(text: string, labels: Labels, options?: ExtractOptions): Promise<ExtractResult>;
+    classify(texts: string[], prompt: string, labels: Labels, options?: CallOptions): Promise<ClassifyResult>;
+    /** Probe every provider now, past the cache. */
+    probe(options?: CallOptions): Promise<(Probe & {
+        provider: string;
+        tier: Tier;
+    })[]>;
+    /** Download and start one provider's model now. */
+    load(name: string, options?: CallOptions): Promise<void>;
+    status(): MindStatus;
+}
+export declare function createMind(options: MindOptions): Mind;

package/dist/mind.js

@@ -0,0 +1,122 @@
+// The router. It picks a provider in `prefer` order, skips the ones that
+// cannot run now, and says in every result and error which provider and tier
+// answered and which ones it skipped and why.
+import { FoxmindError } from "./errors.js";
+const TIERS = new Set(["browser", "local", "cloud"]);
+function order(providers, prefer = []) {
+    const names = new Set();
+    for (const provider of providers) {
+        if (names.has(provider.name))
+            throw new TypeError(`createMind got two providers named "${provider.name}". Give each one its own name.`);
+        names.add(provider.name);
+    }
+    for (const entry of prefer) {
+        if (!names.has(entry) && !TIERS.has(entry))
+            throw new TypeError(`prefer names "${entry}", which is not a provider name or a tier. Providers: ${[...names].join(", ")}.`);
+    }
+    const ranked = prefer.flatMap((entry) => providers.filter((provider) => provider.name === entry || provider.tier === entry));
+    return [...new Set([...ranked, ...providers])];
+}
+const aborted = () => new FoxmindError("aborted", "The caller stopped the call.");
+export function createMind(options) {
+    const only = options.only;
+    for (const tier of only ?? [])
+        if (!TIERS.has(tier))
+            throw new TypeError(`only names "${tier}", which is not a tier. Tiers: browser, local, cloud.`);
+    const providers = order(options.providers, options.prefer).filter((provider) => !only || only.includes(provider.tier));
+    if (only && !providers.length)
+        throw new TypeError(`only: [${only.join(", ")}] leaves no provider. Add a provider of one of those tiers.`);
+    const excluded = only ? ` only: [${only.join(", ")}] excluded the other tiers.` : "";
+    const ttl = options.probeTtlMs ?? 30_000;
+    const probes = new Map();
+    let last;
+    /**
+     * A cached or fresh probe. The probe runs on its own timeout, never on the
+     * caller's signal, so an abort cannot turn into a cached "unreachable". An
+     * abort while the probe runs throws aborted and caches nothing.
+     */
+    async function probe(provider, callOptions) {
+        const cached = probes.get(provider.name);
+        if (cached && Date.now() - cached.at < ttl)
+            return cached.result;
+        const running = provider.probe().catch((error) => ({ ok: false, code: "unreachable", reason: String(error) }));
+        const signal = callOptions.signal;
+        const result = signal
+            ? await Promise.race([running, new Promise((_, reject) => signal.addEventListener("abort", () => reject(aborted()), { once: true }))])
+            : await running;
+        if (signal?.aborted)
+            throw aborted();
+        probes.set(provider.name, { at: Date.now(), result });
+        return result;
+    }
+    async function call(capability, callOptions, run) {
+        const able = providers.filter((provider) => provider.capabilities.includes(capability));
+        if (!able.length) {
+            throw new FoxmindError("no_provider", `No provider can ${capability}. Providers: ${providers.map((p) => `${p.name} (${p.capabilities.join(", ")})`).join("; ") || "none"}.${excluded}`, { skipped: [] });
+        }
+        const skipped = [];
+        for (const provider of able) {
+            // An abort ends the call here. It never moves the text on to the next provider.
+            if (callOptions.signal?.aborted)
+                throw aborted();
+            const probed = await probe(provider, callOptions);
+            if (!probed.ok) {
+                skipped.push({ provider: provider.name, tier: provider.tier, code: probed.code ?? "unavailable", reason: probed.reason ?? "The probe failed." });
+                continue;
+            }
+            // Once text reached the caller, a second provider would repeat it, so a stream never falls back.
+            let streamed = false;
+            const onDelta = callOptions.onDelta;
+            const attempt = onDelta ? { ...callOptions, onDelta: (text) => { streamed = true; onDelta(text); } } : callOptions;
+            const started = Date.now();
+            try {
+                const value = await run(provider, attempt);
+                last = { capability, provider: provider.name, tier: provider.tier, model: provider.model, at: new Date().toISOString() };
+                return { value, provider: provider.name, tier: provider.tier, model: provider.model, ms: Date.now() - started, skipped };
+            }
+            catch (error) {
+                const failed = error instanceof FoxmindError ? error : new FoxmindError("http", String(error), { provider: provider.name, tier: provider.tier, cause: error });
+                // Whatever went wrong, the cached probe no longer tells the truth.
+                probes.delete(provider.name);
+                if (options.fallbackOnError && !streamed && failed.code !== "aborted" && !callOptions.signal?.aborted) {
+                    skipped.push({ provider: provider.name, tier: provider.tier, code: failed.code, reason: failed.message });
+                    continue;
+                }
+                failed.skipped = skipped;
+                throw failed;
+            }
+        }
+        const list = skipped.map((skip) => `${skip.provider} (${skip.tier}): ${skip.reason}`).join("; ");
+        throw new FoxmindError("no_provider", `No provider could ${capability}. ${list}${excluded}`, { skipped });
+    }
+    return {
+        providers,
+        async chat(messages, chatOptions = {}) {
+            const { value, ...answered } = await call("chat", chatOptions, (provider, o) => provider.chat(messages, o));
+            return { ...value, ...answered };
+        },
+        async embed(texts, embedOptions = {}) {
+            const { value, ...answered } = await call("embed", embedOptions, (provider, o) => provider.embed(texts, o));
+            return { vectors: value, ...answered };
+        },
+        async extract(text, labels, extractOptions = {}) {
+            const { value, ...answered } = await call("extract", extractOptions, (provider, o) => provider.extract(text, labels, o));
+            return { entities: value, ...answered };
+        },
+        async classify(texts, prompt, labels, classifyOptions = {}) {
+            const { value, ...answered } = await call("classify", classifyOptions, (provider, o) => provider.classify(texts, prompt, labels, o));
+            return { scores: value, ...answered };
+        },
+        async probe(probeOptions = {}) {
+            probes.clear();
+            return Promise.all(providers.map(async (provider) => ({ ...(await probe(provider, probeOptions)), provider: provider.name, tier: provider.tier })));
+        },
+        async load(name, loadOptions = {}) {
+            const provider = providers.find((candidate) => candidate.name === name);
+            if (!provider)
+                throw new TypeError(`No provider named "${name}".`);
+            await provider.load?.(loadOptions);
+        },
+        status: () => ({ providers: providers.map((provider) => provider.status()), ...(last ? { last } : {}) }),
+    };
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,16 @@
+import type { Provider } from "../types.js";
+export interface AnthropicOptions {
+    apiKey: string;
+    /** Default "claude-opus-5-5". */
+    model?: string;
+    /** Default "https://api.anthropic.com". */
+    baseURL?: string;
+    /** Default 16000. The Messages API needs a value. */
+    maxTokens?: number;
+    /** Default "anthropic". */
+    name?: string;
+    /** Default 300000. */
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+}
+export declare function anthropic(options: AnthropicOptions): Provider;

package/dist/providers/anthropic.js

@@ -0,0 +1,200 @@
+// The Anthropic Messages API, mapped to the OpenAI shape both ways. The caller
+// passes the key; foxmind keeps it in memory only and never stores it.
+import { FoxmindError } from "../errors.js";
+import { call, failure } from "../http.js";
+import { checkReply } from "../reply.js";
+import { events } from "../sse.js";
+const JSON_RULE = "Reply with one JSON object and nothing else: no prose and no code fence.";
+function finishReason(stop) {
+    if (stop === "tool_use")
+        return "tool_calls";
+    if (stop === "max_tokens")
+        return "length";
+    if (stop === "refusal")
+        return "content_filter";
+    return "stop";
+}
+export function anthropic(options) {
+    const baseURL = (options.baseURL ?? "https://api.anthropic.com").replace(/\/+$/, "");
+    const model = options.model ?? "claude-opus-5-5";
+    const name = options.name ?? "anthropic";
+    const origin = { provider: name, tier: "cloud", secrets: [options.apiKey] };
+    const timeout = options.timeoutMs ?? 300_000;
+    let last;
+    const headers = () => ({
+        ...options.headers,
+        "x-api-key": options.apiKey,
+        "anthropic-version": "2023-06-01",
+        // Lets a browser extension page call the API with the user's own key.
+        "anthropic-dangerous-direct-browser-access": "true",
+    });
+    /** OpenAI messages to Anthropic: system messages to `system`, grouped tool results, tool_use blocks. */
+    function toWire(messages) {
+        const system = [];
+        const out = [];
+        for (const message of messages) {
+            if (message.role === "system") {
+                // Many models reject role "system" inside messages, so every system message joins the top-level system, in order.
+                system.push(message.content ?? "");
+            }
+            else if (message.role === "user") {
+                out.push({ role: "user", content: message.content ?? "" });
+            }
+            else if (message.role === "tool") {
+                const result = { type: "tool_result", tool_use_id: message.tool_call_id, content: message.content ?? "" };
+                const previous = out.at(-1);
+                if (previous?.role === "user" && Array.isArray(previous.content) && previous.content.every((block) => block.type === "tool_result"))
+                    previous.content.push(result);
+                else
+                    out.push({ role: "user", content: [result] });
+            }
+            else {
+                const saved = message.provider_data?.anthropic?.content;
+                if (saved) {
+                    out.push({ role: "assistant", content: saved });
+                    continue;
+                }
+                if (!message.tool_calls?.length) {
+                    out.push({ role: "assistant", content: message.content ?? "" });
+                    continue;
+                }
+                const blocks = message.content ? [{ type: "text", text: message.content }] : [];
+                for (const toolCall of message.tool_calls) {
+                    let input;
+                    try {
+                        input = JSON.parse(toolCall.function.arguments || "{}");
+                    }
+                    catch {
+                        throw failure(origin, "bad_tool_call", `Past tool call "${toolCall.function.name}" in the messages has arguments that are not JSON.`, { raw: toolCall.function.arguments });
+                    }
+                    blocks.push({ type: "tool_use", id: toolCall.id, name: toolCall.function.name, input });
+                }
+                out.push({ role: "assistant", content: blocks });
+            }
+        }
+        return { system, messages: out };
+    }
+    function toReply(data) {
+        if (!Array.isArray(data.content))
+            throw failure(origin, "bad_response", "The reply has no content array.");
+        const text = data.content.filter((block) => block.type === "text").map((block) => block.text ?? "");
+        const toolCalls = data.content
+            .filter((block) => block.type === "tool_use")
+            .map((block) => ({ id: block.id ?? "", type: "function", function: { name: block.name ?? "", arguments: JSON.stringify(block.input ?? {}) } }));
+        // Thinking blocks must go back unchanged with the next turn.
+        const keep = data.content.some((block) => block.type === "thinking" || block.type === "redacted_thinking");
+        return {
+            message: {
+                role: "assistant",
+                content: text.length ? text.join("") : null,
+                ...(toolCalls.length ? { tool_calls: toolCalls } : {}),
+                ...(keep ? { provider_data: { anthropic: { content: data.content } } } : {}),
+            },
+            finishReason: finishReason(data.stop_reason),
+            usage: { inputTokens: data.usage?.input_tokens ?? 0, outputTokens: data.usage?.output_tokens ?? 0 },
+        };
+    }
+    /** Join a stream of Messages API events into one reply. */
+    async function collect(fetched, onDelta) {
+        const blocks = [];
+        const json = [];
+        const reply = { usage: {} };
+        let text = "";
+        let done = false;
+        try {
+            for await (const event of events(fetched.body)) {
+                const data = JSON.parse(event.data);
+                const index = data.index ?? 0;
+                if (data.type === "message_start")
+                    reply.usage = { ...data.message?.usage };
+                else if (data.type === "content_block_start")
+                    blocks[index] = { ...data.content_block };
+                else if (data.type === "content_block_delta" && data.delta) {
+                    const block = blocks[index];
+                    const delta = data.delta;
+                    if (delta.type === "text_delta") {
+                        block.text = (block.text ?? "") + delta.text;
+                        text += delta.text;
+                        onDelta(delta.text);
+                    }
+                    else if (delta.type === "input_json_delta")
+                        json[index] = (json[index] ?? "") + delta.partial_json;
+                    else if (delta.type === "thinking_delta")
+                        block.thinking = (block.thinking ?? "") + delta.thinking;
+                    else if (delta.type === "signature_delta")
+                        block.signature = delta.signature;
+                }
+                else if (data.type === "content_block_stop" && blocks[index]?.type === "tool_use") {
+                    const raw = json[index] ?? "";
+                    try {
+                        blocks[index].input = raw.trim() ? JSON.parse(raw) : {};
+                    }
+                    catch {
+                        throw failure(origin, "bad_tool_call", `The arguments of tool call "${blocks[index].name}" are not valid JSON.`, { raw, partial: text });
+                    }
+                }
+                else if (data.type === "message_delta") {
+                    reply.stop_reason = data.delta?.stop_reason ?? reply.stop_reason;
+                    reply.usage = { ...reply.usage, ...data.usage };
+                }
+                else if (data.type === "message_stop")
+                    done = true;
+                else if (data.type === "error") {
+                    const kind = data.error?.type;
+                    const said = `The API sent an error in the stream: ${data.error?.message ?? kind}`;
+                    if (kind === "rate_limit_error")
+                        throw failure(origin, "rate_limited", said, { partial: text });
+                    if (kind === "authentication_error")
+                        throw failure(origin, "auth", said, { partial: text });
+                    throw failure(origin, "http", said, { partial: text, ...(kind === "overloaded_error" ? { status: 529 } : {}) });
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof FoxmindError)
+                throw error;
+            if (error instanceof SyntaxError)
+                throw failure(origin, "bad_response", "The stream sent data that is not JSON.", { partial: text });
+            throw fetched.fail(error, text);
+        }
+        if (!done)
+            throw failure(origin, "stream_interrupted", "The stream ended before message_stop.", { partial: text });
+        return { ...reply, content: blocks.filter(Boolean) };
+    }
+    return {
+        name,
+        tier: "cloud",
+        model,
+        capabilities: ["chat"],
+        async probe(probeOptions = {}) {
+            try {
+                await call(origin, `${baseURL}/v1/models/${encodeURIComponent(model)}`, { headers: headers(), ...probeOptions, timeoutMs: probeOptions.timeoutMs ?? 5000 }, 5000);
+                last = { ok: true, where: baseURL };
+            }
+            catch (error) {
+                const failed = error;
+                last = { ok: false, code: failed.code ?? "unreachable", reason: failed.message, where: baseURL };
+            }
+            return last;
+        },
+        status() {
+            return { name, tier: "cloud", model, capabilities: ["chat"], state: !last ? "idle" : last.ok ? "ready" : "unavailable", where: baseURL, ...(last?.reason ? { reason: last.reason } : {}) };
+        },
+        async chat(messages, chat) {
+            const wire = toWire(messages);
+            const system = [...wire.system, ...(chat.json ? [JSON_RULE] : [])].join("\n\n");
+            const body = {
+                model,
+                max_tokens: chat.maxTokens ?? options.maxTokens ?? 16_000,
+                ...(system ? { system } : {}),
+                ...(chat.tools?.length ? { tools: chat.tools.map((tool) => ({ name: tool.function.name, ...(tool.function.description ? { description: tool.function.description } : {}), input_schema: tool.function.parameters ?? { type: "object", properties: {} } })) } : {}),
+                ...(chat.temperature === undefined ? {} : { temperature: chat.temperature }),
+                messages: wire.messages,
+                ...(chat.onDelta ? { stream: true } : {}),
+            };
+            const fetched = await call(origin, `${baseURL}/v1/messages`, { ...chat, headers: headers(), body }, timeout);
+            const data = chat.onDelta ? await collect(fetched, chat.onDelta) : await fetched.json();
+            return checkReply(origin, toReply(data), chat.json);
+        },
+    };
+}

package/dist/providers/openai.d.ts

@@ -0,0 +1,39 @@
+import type { FinishReason, Message, Provider, Tier, ToolCall } from "../types.js";
+export interface OpenAICompatibleOptions {
+    /** The API root, with the version: "http://127.0.0.1:8080/v1", "https://api.openai.com/v1". */
+    baseURL: string;
+    model: string;
+    /** Sent as "Authorization: Bearer". foxmind keeps it in memory only and hides it from every error. */
+    apiKey?: string;
+    /** The model for embed(). Default: `model`. */
+    embedModel?: string;
+    /** Default "openai-compatible". */
+    name?: string;
+    /** Default "local" for localhost and 127.0.0.1, else "cloud". */
+    tier?: Tier;
+    headers?: Record<string, string>;
+    /** Extra fields for every chat request, for example llama.cpp's `chat_template_kwargs`. */
+    body?: Record<string, unknown>;
+    /**
+     * How probe() checks the server's model list: true = it must list `model`,
+     * a RegExp = one id must match, false = do not check. Default true.
+     */
+    checkModel?: boolean | RegExp;
+    /** Added to the reason of a failed probe, for example the command that starts the server. */
+    hint?: string;
+    /** Default 120000 for chat and embed. probe() always uses 3000. */
+    timeoutMs?: number;
+}
+export declare function finishReason(value: string | null | undefined): FinishReason;
+/** The wire message without the fields only foxmind uses. */
+export declare function toWire(message: Message): {
+    role: import("../types.js").Role;
+    content: string | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+};
+/** Ollama names models that run on ollama.com with a "-cloud" or ":cloud" ending. */
+export declare function isCloudModel(model: string): boolean;
+export declare function isLocalURL(url: string): boolean;
+export declare function openaiCompatible(options: OpenAICompatibleOptions): Provider;

package/dist/providers/openai.js

@@ -0,0 +1,177 @@
+// Any server that speaks the OpenAI chat completions API: llama.cpp
+// llama-server, Ollama, LM Studio, OpenAI, OpenRouter and many more.
+import { FoxmindError } from "../errors.js";
+import { call, failure } from "../http.js";
+import { checkReply } from "../reply.js";
+import { events } from "../sse.js";
+export function finishReason(value) {
+    if (value === "tool_calls" || value === "function_call")
+        return "tool_calls";
+    if (value === "length" || value === "content_filter")
+        return value;
+    return "stop";
+}
+/** The wire message without the fields only foxmind uses. */
+export function toWire(message) {
+    const { reasoning: _reasoning, provider_data: _data, ...wire } = message;
+    return wire;
+}
+/** Ollama names models that run on ollama.com with a "-cloud" or ":cloud" ending. */
+export function isCloudModel(model) {
+    return /[-:]cloud$/i.test(model);
+}
+export function isLocalURL(url) {
+    return /^https?:\/\/(localhost|127\.\d+\.\d+\.\d+|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+export function openaiCompatible(options) {
+    const baseURL = options.baseURL.replace(/\/+$/, "");
+    const name = options.name ?? "openai-compatible";
+    // A model named *-cloud (Ollama) runs on a remote host even when the server is on localhost.
+    const tier = options.tier ?? (isLocalURL(baseURL) && !isCloudModel(options.model) ? "local" : "cloud");
+    const origin = { provider: name, tier, secrets: [options.apiKey] };
+    const headers = { ...options.headers, ...(options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}) };
+    const timeout = options.timeoutMs ?? 120_000;
+    let last;
+    function request(messages, chat, stream) {
+        return {
+            ...options.body,
+            model: options.model,
+            messages: messages.map(toWire),
+            ...(chat.tools?.length ? { tools: chat.tools } : {}),
+            ...(chat.json ? { response_format: { type: "json_object" } } : {}),
+            ...(chat.temperature === undefined ? {} : { temperature: chat.temperature }),
+            ...(chat.maxTokens === undefined ? {} : { max_tokens: chat.maxTokens }),
+            ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
+        };
+    }
+    function reply(data) {
+        const choice = data.choices?.[0];
+        if (!choice?.message)
+            throw failure(origin, "bad_response", "The reply has no choices[0].message.");
+        const wire = choice.message;
+        const reasoning = wire.reasoning_content ?? wire.reasoning;
+        const message = {
+            role: "assistant",
+            content: wire.content ?? null,
+            ...(wire.tool_calls?.length ? { tool_calls: wire.tool_calls } : {}),
+            ...(reasoning ? { reasoning } : {}),
+        };
+        const usage = data.usage ? { inputTokens: data.usage.prompt_tokens ?? 0, outputTokens: data.usage.completion_tokens ?? 0 } : undefined;
+        return { message, finishReason: finishReason(choice.finish_reason), ...(usage ? { usage } : {}) };
+    }
+    /** Join streamed pieces into one completion, calling onDelta with each piece of text. */
+    async function collect(fetched, onDelta) {
+        const message = { content: "" };
+        const calls = [];
+        let finish;
+        let done = false;
+        let usage;
+        try {
+            for await (const event of events(fetched.body)) {
+                if (event.data === "[DONE]") {
+                    done = true;
+                    break;
+                }
+                let chunk;
+                try {
+                    chunk = JSON.parse(event.data);
+                }
+                catch {
+                    throw failure(origin, "bad_response", `The stream sent data that is not JSON: ${event.data.slice(0, 120)}`, { partial: message.content });
+                }
+                if (chunk.error) {
+                    const said = typeof chunk.error === "string" ? chunk.error : chunk.error.message;
+                    throw failure(origin, "http", `The server sent an error in the stream: ${said ?? event.data}`, { partial: message.content });
+                }
+                usage = chunk.usage ?? usage;
+                const choice = chunk.choices?.[0];
+                const delta = choice?.delta ?? {};
+                if (delta.content) {
+                    message.content += delta.content;
+                    onDelta(delta.content);
+                }
+                const thought = delta.reasoning_content ?? delta.reasoning;
+                if (thought)
+                    message.reasoning_content = (message.reasoning_content ?? "") + thought;
+                for (const piece of delta.tool_calls ?? []) {
+                    // With no index, a new id starts a new call; otherwise the piece belongs to the last call.
+                    const top = calls.length - 1;
+                    const index = piece.index ?? (top < 0 || (piece.id && piece.id !== calls[top].id) ? top + 1 : top);
+                    const slot = (calls[index] ??= { id: "", type: "function", function: { name: "", arguments: "" } });
+                    if (piece.id)
+                        slot.id = piece.id;
+                    // Some servers repeat the name in every piece: keep the first one.
+                    if (piece.function?.name && !slot.function.name)
+                        slot.function.name = piece.function.name;
+                    slot.function.arguments += piece.function?.arguments ?? "";
+                }
+                finish = choice?.finish_reason ?? finish;
+            }
+        }
+        catch (error) {
+            if (error instanceof FoxmindError)
+                throw error;
+            // A connection that drops after the server said it was done lost nothing.
+            if (!finish)
+                throw fetched.fail(error, message.content);
+        }
+        if (!done && !finish)
+            throw failure(origin, "stream_interrupted", "The stream ended before the server said it was done.", { partial: message.content });
+        const toolCalls = calls.filter(Boolean);
+        return {
+            choices: [{ message: { ...message, content: message.content || (toolCalls.length ? null : ""), ...(toolCalls.length ? { tool_calls: toolCalls } : {}) }, finish_reason: finish }],
+            ...(usage ? { usage } : {}),
+        };
+    }
+    return {
+        name,
+        tier,
+        model: options.model,
+        capabilities: ["chat", "embed"],
+        async probe(probeOptions = {}) {
+            try {
+                const fetched = await call(origin, `${baseURL}/models`, { headers, ...probeOptions, timeoutMs: probeOptions.timeoutMs ?? 3000 }, 3000);
+                const ids = ((await fetched.json()).data ?? []).map((model) => model.id);
+                const check = options.checkModel ?? true;
+                const found = check === false || (check instanceof RegExp ? ids.some((id) => check.test(id)) : ids.includes(options.model));
+                last = found
+                    ? { ok: true, where: baseURL }
+                    : { ok: false, code: "model_not_found", where: baseURL, reason: `The server does not list ${check instanceof RegExp ? String(check) : `"${options.model}"`}. It has: ${ids.join(", ") || "no models"}.` };
+            }
+            catch (error) {
+                const failed = error;
+                last = { ok: false, code: failed.code ?? "unreachable", where: baseURL, reason: failed.message ?? String(error) };
+            }
+            if (!last.ok && options.hint)
+                last.reason = `${last.reason} ${options.hint}`;
+            return last;
+        },
+        status() {
+            return {
+                name,
+                tier,
+                model: options.model,
+                capabilities: ["chat", "embed"],
+                state: !last ? "idle" : last.ok ? "ready" : "unavailable",
+                where: baseURL,
+                ...(last?.reason ? { reason: last.reason } : {}),
+            };
+        },
+        async chat(messages, chat) {
+            const url = `${baseURL}/chat/completions`;
+            const stream = chat.onDelta !== undefined;
+            const fetched = await call(origin, url, { ...chat, headers, body: request(messages, chat, stream) }, timeout);
+            const data = chat.onDelta ? await collect(fetched, chat.onDelta) : await fetched.json();
+            return checkReply(origin, reply(data), chat.json);
+        },
+        async embed(texts, embed) {
+            const url = `${baseURL}/embeddings`;
+            const fetched = await call(origin, url, { ...embed, headers, body: { model: options.embedModel ?? options.model, input: texts } }, timeout);
+            const data = (await fetched.json()).data;
+            if (!Array.isArray(data) || data.length !== texts.length) {
+                throw failure(origin, "bad_response", `Asked for ${texts.length} embeddings and got ${Array.isArray(data) ? data.length : "none"}.`);
+            }
+            return data.toSorted((a, b) => a.index - b.index).map((item) => item.embedding);
+        },
+    };
+}

package/dist/providers/presets.d.ts

@@ -0,0 +1,33 @@
+import { type OpenAICompatibleOptions } from "./openai.js";
+import type { Provider } from "../types.js";
+type PresetOptions = Partial<Omit<OpenAICompatibleOptions, "model">>;
+/** Underdog Saluki 27B 1.0, from its Hugging Face model card (checked 2026-10-08). */
+export declare const SALUKI: {
+    readonly repo: "ConwayResearch/Underdog-Saluki-27B-1.0";
+    readonly file: "Underdog-Saluki-27B-1.0-IQ2-mix.gguf";
+    readonly sizeGB: 7.89;
+    readonly license: "Apache-2.0";
+    readonly download: "huggingface-cli download ConwayResearch/Underdog-Saluki-27B-1.0 Underdog-Saluki-27B-1.0-IQ2-mix.gguf --local-dir .";
+    readonly serve: "llama-server -m Underdog-Saluki-27B-1.0-IQ2-mix.gguf --jinja -ngl 99 -fa on -c 32768";
+};
+/** Ollama's OpenAI-compatible API. "llama3.2" matches "llama3.2:latest". */
+export declare function ollama(options: PresetOptions & {
+    model: string;
+}): Provider;
+/** llama.cpp llama-server. It serves one model, so the name is not checked. */
+export declare function llamaServer(options?: PresetOptions & {
+    model?: string;
+}): Provider;
+/** LM Studio's local server. */
+export declare function lmStudio(options: PresetOptions & {
+    model: string;
+}): Provider;
+/**
+ * Underdog Saluki 27B on llama-server: the default planner for private mode.
+ * Thinking is off by default with temperature 0, the model card's settings
+ * for direct tool calls. `thinking: true` uses its settings for reasoning.
+ */
+export declare function saluki(options?: PresetOptions & {
+    thinking?: boolean;
+}): Provider;
+export {};