modeldispatcher-browser-agent 0.6.6 → 0.7.0

package/dist/providers/openaiCompatible.js

@@ -61,4 +61,86 @@ export async function streamOpenAICompatible(provider, cfg, messages, onChunk, o
     });
     return full;
 }
+function toToolApiMessages(messages, systemInstruction) {
+    const hasSystemTurn = messages.some((m) => m.role === "system");
+    const system = !hasSystemTurn && systemInstruction ? [{ role: "system", content: systemInstruction }] : [];
+    return [
+        ...system,
+        ...messages.flatMap((m) => {
+            if (m.role === "tool") {
+                return m.results.map((r) => ({ role: "tool", tool_call_id: r.callId, content: r.content }));
+            }
+            if ("toolCalls" in m) {
+                return [
+                    {
+                        role: "assistant",
+                        content: m.content || null,
+                        tool_calls: m.toolCalls.map((c) => ({
+                            id: c.id,
+                            type: "function",
+                            function: { name: c.name, arguments: JSON.stringify(c.arguments) },
+                        })),
+                    },
+                ];
+            }
+            return [{ role: m.role, content: m.content }];
+        }),
+    ];
+}
+/** Parse the model's tool-call arguments: a JSON string that may be empty. */
+export function parseArguments(raw, toolName) {
+    if (!raw || !raw.trim())
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Tool call ${toolName} sent arguments that are not valid JSON`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Tool call ${toolName} sent arguments that are not a JSON object`);
+    }
+    return parsed;
+}
+/** One non-streaming turn with tools available (OpenAI or Groq). */
+export async function completeWithToolsOpenAICompatible(provider, cfg, messages, tools, options = {}) {
+    const res = await fetchWithRetry(BASE_URLS[provider], {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
+        body: JSON.stringify({
+            model: cfg.model,
+            max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+            messages: toToolApiMessages(messages, options.systemInstruction),
+            ...(tools.length
+                ? {
+                    tools: tools.map((t) => ({
+                        type: "function",
+                        function: { name: t.name, description: t.description, parameters: t.parameters },
+                    })),
+                }
+                : {}),
+        }),
+    }, options.signal);
+    if (!res.ok)
+        throw new Error(await describeHttpError(res));
+    const data = await res.json();
+    const choice = data.choices?.[0];
+    if (!choice?.message)
+        throw new Error(`${provider} returned no answer`);
+    if (choice.finish_reason === "content_filter")
+        throw new Error(`${provider} filtered the answer`);
+    const message = choice.message;
+    const calls = message.tool_calls ?? [];
+    if (choice.finish_reason === "length" && calls.length) {
+        throw new Error(`${provider} ran out of tokens in the middle of a tool call`);
+    }
+    return {
+        text: message.content ?? "",
+        toolCalls: calls.map((c) => {
+            const name = c.function?.name ?? "";
+            return { id: c.id ?? "", name, arguments: parseArguments(c.function?.arguments, name) };
+        }),
+    };
+}
 //# sourceMappingURL=openaiCompatible.js.map

package/dist/providers/openaiCompatible.js.map

@@ -1 +1 @@
-{"version":3,"file":"openaiCompatible.js","sourceRoot":"","sources":["../../src/providers/openaiCompatible.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG7E,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,MAAM,SAAS,GAAsC;IACnD,MAAM,EAAE,4CAA4C;IACpD,IAAI,EAAE,iDAAiD;CACxD,CAAC;AAEF,SAAS,aAAa,CAAC,QAAgC,EAAE,iBAA0B;IACjF,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,CAAC,aAAa,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3G,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,SAAS,SAAS,CAAC,GAAuB,EAAE,QAAgC,EAAE,OAAuB,EAAE,MAAe;IACpH,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,OAAO,CAAC,SAAS,IAAI,kBAAkB;QACnD,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,OAAO,CACpB,QAA2B,EAC3B,GAAuB,EACvB,QAAgC,EAChC,OAAuB,EACvB,MAAe;IAEf,MAAM,GAAG,GAAG,MAAM,cAAc,CAC9B,SAAS,CAAC,QAAQ,CAAC,EACnB;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,EAAE;QACtF,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;KAChE,EACD,OAAO,CAAC,MAAM,CACf,CAAC;IACF,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,QAA2B,EAC3B,GAAuB,EACvB,QAAgC,EAChC,UAA0B,EAAE;IAE5B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAA2B,EAC3B,GAAuB,EACvB,QAAgC,EAChC,OAAwC,EACxC,UAA0B,EAAE;IAE5B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClE,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,MAAM,YAAY,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE;QAC/B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,GAAG,KAAK,QAAQ;YAAE,OAAO;QAC7B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC;YAC3D,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,IAAI,KAAK,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sCAAsC;QACxC,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"openaiCompatible.js","sourceRoot":"","sources":["../../src/providers/openaiCompatible.ts"],"names":[],"mappings":"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"}

package/dist/toolMessages.d.ts

@@ -0,0 +1,4 @@
+/** Helpers for the neutral tool-conversation history ({@link ToolChatMessage}). */
+import type { ToolChatMessage } from "./types.js";
+/** The content of the history's system turn, if it has one. */
+export declare function systemTurnOf(messages: readonly ToolChatMessage[]): string | undefined;

package/dist/toolMessages.js

@@ -0,0 +1,10 @@
+/** Helpers for the neutral tool-conversation history ({@link ToolChatMessage}). */
+/** The content of the history's system turn, if it has one. */
+export function systemTurnOf(messages) {
+    for (const m of messages) {
+        if (m.role === "system")
+            return m.content;
+    }
+    return undefined;
+}
+//# sourceMappingURL=toolMessages.js.map

package/dist/toolMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolMessages.js","sourceRoot":"","sources":["../src/toolMessages.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAInF,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,QAAoC;IAC/D,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool calling in the browser: the model asks for tools, the app runs them
+ * on the device, and the results go back until the model answers. The same
+ * bounded loop as the Python core's `AgentLoop`, client-side.
+ *
+ *   - runWithTools() — a chat history and a set of tools in, the final answer
+ *     and the tools used out
+ *
+ * Each turn is dispatched through the same fallback list as `complete()`, so
+ * a failing provider hands the run to the next one mid-conversation: the
+ * history is kept in a neutral form ({@link ToolChatMessage}) and translated
+ * per provider on every turn. Non-streaming: a turn may end in tool calls,
+ * so there is no single text stream to show.
+ */
+import type { AgentConfig, ProviderId, RequestOptions, ToolCall, ToolChatMessage, ToolResult, ToolSpec } from "./types.js";
+/** A tool the app runs itself: its declaration and its implementation. */
+export interface Tool {
+    readonly spec: ToolSpec;
+    /** Runs on the device with the model's decoded arguments; its return value
+     * (or the message of what it throws) is what the model reads. */
+    readonly run: (args: Readonly<Record<string, unknown>>) => string | Promise<string>;
+}
+export interface RunWithToolsOptions extends Omit<RequestOptions, "jsonMode"> {
+    readonly tools: readonly Tool[];
+    /** Model turns allowed before giving up (each may request several tools).
+     * Defaults to {@link DEFAULT_MAX_STEPS}. */
+    readonly maxSteps?: number;
+    /** Called after each tool runs, e.g. to show "looked up AAPL" while waiting. */
+    readonly onToolResult?: (call: ToolCall, result: ToolResult) => void;
+}
+export type ToolRunStopReason = "completed" | "max_steps";
+export interface ToolRunResult {
+    /** The model's final answer; may be empty when `stopReason` is "max_steps". */
+    readonly text: string;
+    readonly stopReason: ToolRunStopReason;
+    /** Names of the tools run, in order, repeats included. */
+    readonly toolsUsed: readonly string[];
+    /** The provider and model that produced the final turn. */
+    readonly provider: ProviderId;
+    readonly model: string;
+    /** The whole conversation including tool turns, to continue it later. */
+    readonly messages: readonly ToolChatMessage[];
+}
+export declare const DEFAULT_MAX_STEPS = 6;
+/**
+ * Run a conversation in which the model may call `options.tools`, until it
+ * answers without asking for one or `maxSteps` turns pass. Tools run one at
+ * a time, in the order asked, so a write lands before a later read.
+ *
+ * Raises:
+ *   NoProviderConfiguredError: `cfg.providers` has no usable credential.
+ *   AllProvidersExhaustedError: every candidate failed on some turn.
+ */
+export declare function runWithTools(cfg: AgentConfig, messages: readonly ToolChatMessage[], options: RunWithToolsOptions): Promise<ToolRunResult>;

package/dist/tools.js

@@ -0,0 +1,140 @@
+/**
+ * Tool calling in the browser: the model asks for tools, the app runs them
+ * on the device, and the results go back until the model answers. The same
+ * bounded loop as the Python core's `AgentLoop`, client-side.
+ *
+ *   - runWithTools() — a chat history and a set of tools in, the final answer
+ *     and the tools used out
+ *
+ * Each turn is dispatched through the same fallback list as `complete()`, so
+ * a failing provider hands the run to the next one mid-conversation: the
+ * history is kept in a neutral form ({@link ToolChatMessage}) and translated
+ * per provider on every turn. Non-streaming: a turn may end in tool calls,
+ * so there is no single text stream to show.
+ */
+import { AllProvidersExhaustedError, candidatesOf, NoProviderConfiguredError, } from "./agent.js";
+import { completeWithToolsAnthropic } from "./providers/anthropic.js";
+import { completeWithToolsGemini } from "./providers/gemini.js";
+import { completeWithToolsOllama } from "./providers/ollama.js";
+import { completeWithToolsOpenAICompatible } from "./providers/openaiCompatible.js";
+export const DEFAULT_MAX_STEPS = 6;
+function completeTurn(candidate, messages, tools, options) {
+    switch (candidate.provider) {
+        case "gemini":
+            return completeWithToolsGemini(candidate, messages, tools, options);
+        case "anthropic":
+            return completeWithToolsAnthropic(candidate, messages, tools, options);
+        case "ollama":
+            return completeWithToolsOllama(candidate, messages, tools, options);
+        case "openai":
+        case "groq":
+            return completeWithToolsOpenAICompatible(candidate.provider, candidate, messages, tools, options);
+    }
+}
+async function dispatchTurn(candidates, messages, tools, options) {
+    const attempts = [];
+    for (const candidate of candidates) {
+        try {
+            return { turn: await completeTurn(candidate, messages, tools, options), candidate };
+        }
+        catch (err) {
+            if (options.signal?.aborted)
+                throw err;
+            attempts.push({ provider: candidate.provider, error: messageOf(err) });
+        }
+    }
+    throw new AllProvidersExhaustedError(attempts);
+}
+/**
+ * Give calls without a provider id (Gemini, Ollama) one unique in the whole
+ * conversation, counting the calls already in it: a continued conversation
+ * must not repeat an id (Anthropic rejects duplicates).
+ */
+function numberCalls(calls, history) {
+    let next = history.reduce((n, m) => n + ("toolCalls" in m ? m.toolCalls.length : 0), 0);
+    return calls.map((call) => (call.id ? call : { ...call, id: `call_${next++}` }));
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The system prompt for every turn, decided once so a fallback doesn't change
+ * it: the explicit option, else every system turn in the history, joined.
+ */
+function systemOf(messages, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const turns = messages.flatMap((m) => (m.role === "system" ? [m.content] : []));
+    return turns.length ? turns.join("\n\n") : undefined;
+}
+/** What goes to the provider: no system turns (sent as the instruction) and no
+ * empty plain turns, which Anthropic and Gemini reject. */
+function sendable(history) {
+    return history.filter((m) => m.role !== "system" && (m.role === "tool" || "toolCalls" in m || m.content !== ""));
+}
+async function runTool(tools, call) {
+    const tool = tools.get(call.name);
+    if (!tool)
+        return { callId: call.id, name: call.name, content: `unknown tool: ${call.name}`, isError: true };
+    try {
+        return { callId: call.id, name: call.name, content: await tool.run(call.arguments), isError: false };
+    }
+    catch (err) {
+        // Handed back to the model, which can retry or explain, as the Python core does.
+        return { callId: call.id, name: call.name, content: `tool error: ${messageOf(err)}`, isError: true };
+    }
+}
+/**
+ * Run a conversation in which the model may call `options.tools`, until it
+ * answers without asking for one or `maxSteps` turns pass. Tools run one at
+ * a time, in the order asked, so a write lands before a later read.
+ *
+ * Raises:
+ *   NoProviderConfiguredError: `cfg.providers` has no usable credential.
+ *   AllProvidersExhaustedError: every candidate failed on some turn.
+ */
+export async function runWithTools(cfg, messages, options) {
+    const candidates = candidatesOf(cfg);
+    if (candidates.length === 0)
+        throw new NoProviderConfiguredError();
+    const { tools, maxSteps = DEFAULT_MAX_STEPS, onToolResult, systemInstruction, ...rest } = options;
+    const system = systemOf(messages, systemInstruction);
+    const requestOptions = system === undefined ? rest : { ...rest, systemInstruction: system };
+    const specs = tools.map((t) => t.spec);
+    const byName = new Map(tools.map((t) => [t.spec.name, t]));
+    const history = [...messages];
+    const toolsUsed = [];
+    let last;
+    for (let step = 0; step < maxSteps; step++) {
+        last = await dispatchTurn(candidates, sendable(history), specs, requestOptions);
+        const calls = numberCalls(last.turn.toolCalls, history);
+        if (calls.length === 0) {
+            if (last.turn.text)
+                history.push({ role: "assistant", content: last.turn.text });
+            return result(last, "completed", toolsUsed, history);
+        }
+        history.push({ role: "assistant", content: last.turn.text, toolCalls: calls });
+        const results = [];
+        for (const call of calls) {
+            const outcome = await runTool(byName, call);
+            toolsUsed.push(call.name);
+            results.push(outcome);
+            onToolResult?.(call, outcome);
+        }
+        history.push({ role: "tool", results });
+    }
+    if (!last)
+        throw new RangeError(`maxSteps must be at least 1, got ${maxSteps}`);
+    return result(last, "max_steps", toolsUsed, history);
+}
+function result(last, stopReason, toolsUsed, history) {
+    return {
+        text: last.turn.text,
+        stopReason,
+        toolsUsed,
+        provider: last.candidate.provider,
+        model: last.candidate.model,
+        messages: history,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/types.d.ts

@@ -59,6 +59,57 @@ export interface ChatMessage {
     readonly role: ChatRole;
     readonly content: string;
 }
+/**
+ * A tool the model may call, declared by name, purpose, and a JSON Schema for
+ * its arguments — the same shape as the Python core's `ToolSpec`. Keep
+ * `parameters` to the schema subset every provider accepts (`type`,
+ * `properties`, `required`, `description`, `enum`, `items`); Gemini rejects
+ * the rest, so `additionalProperties` and `$schema` are dropped for it.
+ */
+export interface ToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+/** A model's request to run one tool, decoded from a provider response. */
+export interface ToolCall {
+    /** The provider's call id, or one generated for providers that send none
+     * (Gemini, Ollama). Pairs the call with its {@link ToolResult}. */
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    /** Gemini's `thoughtSignature`, echoed back on the next turn as its
+     * thinking models require. Absent for every other provider. */
+    readonly signature?: string;
+}
+/** What running a {@link ToolCall} produced, fed back to the model. */
+export interface ToolResult {
+    readonly callId: string;
+    readonly name: string;
+    readonly content: string;
+    /** True when the tool threw or was unknown: the model sees the error text
+     * and can recover, instead of the whole run failing. */
+    readonly isError: boolean;
+}
+/**
+ * One turn of a tool-using conversation: a plain {@link ChatMessage}, the
+ * assistant asking for tools, or the results of every tool it asked for in
+ * that turn (kept together because Anthropic and Gemini want them in a
+ * single turn).
+ */
+export type ToolChatMessage = ChatMessage | {
+    readonly role: "assistant";
+    readonly content: string;
+    readonly toolCalls: readonly ToolCall[];
+} | {
+    readonly role: "tool";
+    readonly results: readonly ToolResult[];
+};
+/** One model turn in a tool loop: text, tool calls, or both. */
+export interface ToolTurn {
+    readonly text: string;
+    readonly toolCalls: readonly ToolCall[];
+}
 /** Options shared by both complete() and streamComplete()/streamChat(). */
 export interface RequestOptions {
     /** System prompt / instruction, applied via each provider's native mechanism. */
@@ -81,7 +132,7 @@ export interface StreamOptions extends RequestOptions {
 /** A free, public AI chat web product `openExternalChat` can hand a question
  * off to — the no-API-key escape hatch, distinct from the `ProviderId`s above
  * (which all require a BYOK credential). */
-export type ExternalChatProviderId = "chatgpt" | "claude" | "gemini" | "groq";
+export type ExternalChatProviderId = "chatgpt" | "claude" | "gemini" | "geminiApp" | "groq";
 /** Static metadata about one external chat provider. */
 export interface ExternalChatProviderInfo {
     readonly id: ExternalChatProviderId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modeldispatcher-browser-agent",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Browser-native, bring-your-own-key AI agent core with cross-provider/cross-key fallback dispatch: multi-provider (Gemini/OpenAI/Anthropic/Groq/Ollama), streaming and non-streaming, no backend and no vendor SDK required. The client-side sibling to model-dispatcher for apps with no server to run it on.",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,6 @@
   ],
   "devDependencies": {
     "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
+    "vitest": "^5.1.0"
   }
 }

package/src/agent.ts

@@ -29,7 +29,7 @@ import type {
 
 /** One candidate that failed, kept only to compose
  * {@link AllProvidersExhaustedError}'s message. */
-interface FailedAttempt {
+export interface FailedAttempt {
   readonly provider: string;
   readonly error: string;
 }
@@ -64,7 +64,7 @@ export class AllProvidersExhaustedError extends Error {
  * 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: AgentConfig): ProviderCallConfig[] {
+export function candidatesOf(cfg: AgentConfig): ProviderCallConfig[] {
   const candidates: ProviderCallConfig[] = [];
   for (const cred of cfg.providers) {
     if (cred.provider === "ollama") {

package/src/externalChat.ts

@@ -39,6 +39,15 @@ export const EXTERNAL_CHAT_PROVIDERS: Record<ExternalChatProviderId, ExternalCha
     // "ask Google's AI this" — that's what this actually opens.
     buildUrl: (question) => `https://www.google.com/search?${new URLSearchParams({ q: question, udm: "50" })}`,
   },
+  geminiApp: {
+    id: "geminiApp",
+    name: "Gemini",
+    homeUrl: "https://gemini.google.com/app",
+    // The real Gemini app, distinct from the AI-Mode entry above. It has no
+    // known query-prefill parameter — opens the plain app; the question
+    // still goes to the clipboard.
+    buildUrl: null,
+  },
   groq: {
     id: "groq",
     name: "Groq",

package/src/index.ts

@@ -38,6 +38,8 @@ export type { DispatcherFeatureFlags } from "./features.js";
 export { buildMessages } from "./messages.js";
 export type { BuildMessagesOptions } from "./messages.js";
 export { isKnownProvider, modelOptionsFor, MODEL_OPTIONS, PROVIDERS } from "./registry.js";
+export { DEFAULT_MAX_STEPS, runWithTools } from "./tools.js";
+export type { RunWithToolsOptions, Tool, ToolRunResult, ToolRunStopReason } from "./tools.js";
 export type {
   AgentConfig,
   ChatMessage,
@@ -49,4 +51,9 @@ export type {
   ProviderInfo,
   RequestOptions,
   StreamOptions,
+  ToolCall,
+  ToolChatMessage,
+  ToolResult,
+  ToolSpec,
+  ToolTurn,
 } from "./types.js";

package/src/providers/anthropic.ts

@@ -6,8 +6,16 @@
  * it behind in the first place.
  */
 
+import { systemTurnOf } from "../toolMessages.js";
 import { consumeLines, describeHttpError, fetchWithRetry } from "../http.js";
-import type { ChatMessage, ProviderCallConfig, RequestOptions } from "../types.js";
+import type {
+  ChatMessage,
+  ProviderCallConfig,
+  RequestOptions,
+  ToolChatMessage,
+  ToolSpec,
+  ToolTurn,
+} from "../types.js";
 
 const DEFAULT_MAX_TOKENS = 1024;
 const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
@@ -84,3 +92,84 @@ export async function streamAnthropic(
   });
   return full;
 }
+
+function toToolApiMessages(messages: readonly ToolChatMessage[]) {
+  return messages
+    .filter((m) => m.role !== "system")
+    .map((m) => {
+      if (m.role === "tool") {
+        return {
+          role: "user",
+          content: m.results.map((r) => ({
+            type: "tool_result",
+            tool_use_id: r.callId,
+            content: r.content,
+            ...(r.isError ? { is_error: true } : {}),
+          })),
+        };
+      }
+      if ("toolCalls" in m) {
+        return {
+          role: "assistant",
+          content: [
+            ...(m.content ? [{ type: "text", text: m.content }] : []),
+            ...m.toolCalls.map((c) => ({ type: "tool_use", id: c.id, name: c.name, input: c.arguments })),
+          ],
+        };
+      }
+      return { role: m.role, content: m.content };
+    });
+}
+
+interface AnthropicBlock {
+  type?: string;
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+/** One non-streaming turn with tools available. */
+export async function completeWithToolsAnthropic(
+  cfg: ProviderCallConfig,
+  messages: readonly ToolChatMessage[],
+  tools: readonly ToolSpec[],
+  options: RequestOptions = {},
+): Promise<ToolTurn> {
+  const system = options.systemInstruction ?? systemTurnOf(messages);
+  const res = await fetchWithRetry(
+    ANTHROPIC_URL,
+    {
+      method: "POST",
+      headers: headers(cfg),
+      body: JSON.stringify({
+        model: cfg.model,
+        max_tokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+        ...(system ? { system } : {}),
+        messages: toToolApiMessages(messages),
+        ...(tools.length
+          ? { tools: tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters })) }
+          : {}),
+      }),
+    },
+    options.signal,
+  );
+  if (!res.ok) throw new Error(await describeHttpError(res));
+  const data = await res.json();
+  const blocks: AnthropicBlock[] = data.content ?? [];
+  if (data.stop_reason === "refusal") throw new Error("Anthropic declined to answer");
+  if (data.stop_reason === "max_tokens" && blocks.some((b) => b.type === "tool_use")) {
+    // The tool input may be cut off: running it would act on partial arguments.
+    throw new Error("Anthropic ran out of tokens in the middle of a tool call");
+  }
+  if (blocks.length === 0) throw new Error(`Anthropic returned an empty turn (${data.stop_reason ?? "no reason"})`);
+  return {
+    text: blocks
+      .filter((b) => b.type === "text")
+      .map((b) => b.text ?? "")
+      .join(""),
+    toolCalls: blocks
+      .filter((b) => b.type === "tool_use")
+      .map((b) => ({ id: b.id ?? "", name: b.name ?? "", arguments: b.input ?? {} })),
+  };
+}