smoltalk 0.5.1 → 0.7.0

package/dist/clients/deepinfra.js

@@ -0,0 +1,27 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * DeepInfra client (https://deepinfra.com). OpenAI-compatible chat completions
+ * at the `/v1/openai` base URL.
+ *
+ * - Baked base URL `https://api.deepinfra.com/v1/openai` (override via config.baseUrl.deepInfra).
+ * - Key: config.apiKey.deepInfra or env DEEPINFRA_API_KEY.
+ * - Cost: reads `usage.estimated_cost` (USD).
+ */
+export class SmolDeepInfra extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("deepinfra", config);
+        // resolveBaseUrl bakes in the deepinfra default, so this is always defined.
+        const baseURL = resolveBaseUrl("deepinfra", config);
+        if (!apiKey) {
+            throw new Error("deepinfra: API key required (config.apiKey.deepInfra or DEEPINFRA_API_KEY).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(usage) {
+        // DeepInfra returns usage.estimated_cost (USD) on chat completions.
+        return typeof usage?.estimated_cost === "number"
+            ? usage.estimated_cost
+            : undefined;
+    }
+}

package/dist/clients/google.js

@@ -1,6 +1,7 @@
 import { GoogleGenAI } from "@google/genai";
 import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../util/logger.js";
+import { redactAttachments } from "../util/redact.js";
 import { addCosts, addTokenUsage, success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
 import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
@@ -68,10 +69,11 @@ export class SmolGoogle extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        if (!config.googleApiKey) {
+        const apiKey = config.apiKey?.google || process.env.GEMINI_API_KEY;
+        if (!apiKey) {
             throw new Error("Google API key is required for SmolGoogle client.");
         }
-        this.client = new GoogleGenAI({ apiKey: config.googleApiKey });
+        this.client = new GoogleGenAI({ apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }
@@ -247,7 +249,7 @@ export class SmolGoogle extends BaseClient {
         });
     }
     async __textSync(request) {
-        this.logger.debug("Sending request to Google Gemini:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending request to Google Gemini:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         let result;
         try {
@@ -325,7 +327,7 @@ export class SmolGoogle extends BaseClient {
             request.config.responseMimeType = undefined;
             request.config.responseJsonSchema = undefined;
         }
-        this.logger.debug("Sending streaming request to Google Gemini:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending streaming request to Google Gemini:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         let stream;
         try {

package/dist/clients/litellm.d.ts

@@ -0,0 +1,19 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import type { SmolConfig } from "../types.js";
+/**
+ * LiteLLM proxy client (https://docs.litellm.ai/docs/simple_proxy). OpenAI-
+ * compatible chat completions through a user-run LiteLLM proxy.
+ *
+ * - Base URL is REQUIRED from config.baseUrl.liteLlm or env LITELLM_BASE_URL.
+ * - Key: config.apiKey.liteLlm or env LITELLM_API_KEY.
+ * - Cost: reads the `x-litellm-response-cost` header (USD). Only available
+ *   for non-streaming responses; streaming requests fall back to the
+ *   smoltalk model registry.
+ */
+export declare class SmolLiteLlm extends SmolOpenAiCompat {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(_usage: any, rawResponse?: Response): number | undefined;
+}

package/dist/clients/litellm.js

@@ -0,0 +1,32 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * LiteLLM proxy client (https://docs.litellm.ai/docs/simple_proxy). OpenAI-
+ * compatible chat completions through a user-run LiteLLM proxy.
+ *
+ * - Base URL is REQUIRED from config.baseUrl.liteLlm or env LITELLM_BASE_URL.
+ * - Key: config.apiKey.liteLlm or env LITELLM_API_KEY.
+ * - Cost: reads the `x-litellm-response-cost` header (USD). Only available
+ *   for non-streaming responses; streaming requests fall back to the
+ *   smoltalk model registry.
+ */
+export class SmolLiteLlm extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("litellm", config);
+        const baseURL = resolveBaseUrl("litellm", config);
+        if (!apiKey) {
+            throw new Error("litellm: API key required (config.apiKey.liteLlm or LITELLM_API_KEY).");
+        }
+        if (!baseURL) {
+            throw new Error("litellm: base URL required (config.baseUrl.liteLlm or LITELLM_BASE_URL).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(_usage, rawResponse) {
+        const header = rawResponse?.headers?.get?.("x-litellm-response-cost");
+        if (!header)
+            return undefined;
+        const n = Number(header);
+        return Number.isFinite(n) ? n : undefined;
+    }
+}

package/dist/clients/ollama.js

@@ -1,9 +1,11 @@
 import { Ollama } from "ollama";
 import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../util/logger.js";
+import { redactAttachments } from "../util/redact.js";
 import { success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
 import { sanitizeAttributes } from "../util/util.js";
+import { resolveBaseUrl } from "../util/provider.js";
 import { BaseClient } from "./baseClient.js";
 import { SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
 import { extractHttpErrorFields } from "../util/httpError.js";
@@ -17,14 +19,15 @@ export class SmolOllama extends BaseClient {
         super(config);
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
-        if (config.ollamaApiKey) {
+        const apiKey = config.apiKey?.ollama;
+        if (apiKey) {
             this.client = new Ollama({
                 host: "https://cloud.ollama.com",
-                headers: { Authorization: "Bearer " + config.ollamaApiKey },
+                headers: { Authorization: "Bearer " + apiKey },
             });
         }
         else {
-            const host = config.ollamaHost || DEFAULT_OLLAMA_HOST;
+            const host = resolveBaseUrl("ollama", config) || DEFAULT_OLLAMA_HOST;
             this.client = new Ollama({ host });
         }
     }
@@ -64,14 +67,14 @@ export class SmolOllama extends BaseClient {
         throw error;
     }
     async _textSync(config) {
-        const messages = config.messages.map((msg) => msg.toOpenAIMessage());
+        const messages = config.messages.map((msg) => msg.toOllamaMessage());
         const tools = (config.tools || []).map((tool) => {
             return zodToGoogleTool(tool.name, tool.schema, {
                 description: tool.description,
             });
         });
         const request = {
-            messages: messages,
+            messages,
             model: this.getModel(),
         };
         if (tools.length > 0) {
@@ -81,7 +84,7 @@ export class SmolOllama extends BaseClient {
             request.format = config.responseFormat.toJSONSchema();
         }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
-        this.logger.debug("Sending request to Ollama:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending request to Ollama:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         const abortHandler = signal ? () => this.client.abort() : undefined;
@@ -117,14 +120,14 @@ export class SmolOllama extends BaseClient {
         return success({ output, toolCalls, usage, cost, model: this.getModel() });
     }
     async *_textStream(config) {
-        const messages = config.messages.map((msg) => msg.toOpenAIMessage());
+        const messages = config.messages.map((msg) => msg.toOllamaMessage());
         const tools = (config.tools || []).map((tool) => {
             return zodToGoogleTool(tool.name, tool.schema, {
                 description: tool.description,
             });
         });
         const request = {
-            messages: messages,
+            messages,
             model: this.getModel(),
             stream: true,
         };
@@ -135,7 +138,7 @@ export class SmolOllama extends BaseClient {
             request.format = config.responseFormat.toJSONSchema();
         }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
-        this.logger.debug("Sending streaming request to Ollama:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending streaming request to Ollama:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         const abortHandler = signal ? () => this.client.abort() : undefined;

package/dist/clients/openai.d.ts

@@ -1,16 +1,52 @@
 import OpenAI from "openai";
-import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk } from "../types.js";
+import { PromptResult, Result, SmolClient, SmolConfig, StreamChunk, HostedToolResult } from "../types.js";
+import { EgonLog } from "../util/logger.js";
 import { BaseClient } from "./baseClient.js";
 import { ModelName } from "../models.js";
+import { Model } from "../model.js";
+import { CostEstimate, TokenUsage } from "../types.js";
 export type SmolOpenAiConfig = SmolConfig;
 export declare class SmolOpenAi extends BaseClient implements SmolClient {
-    private client;
-    private logger;
-    private model;
+    protected client: OpenAI;
+    protected logger: EgonLog;
+    protected model: Model;
     constructor(config: SmolOpenAiConfig);
+    /**
+     * Build the `new OpenAI({...})` options. Subclasses override to inject a
+     * different baseURL or to pull the key from a different config field.
+     *
+     * Default behavior: read OPENAI_API_KEY (or config.apiKey.openAi). Throws
+     * if the key is missing — subclasses with required keys do their own check.
+     */
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    /**
+     * Inspect the provider-returned usage (and optionally the raw HTTP response)
+     * for a USD cost figure. Returns `undefined` if the provider didn't surface
+     * one, in which case `calculateUsageAndCost` falls back to the smoltalk
+     * model registry. Subclasses (OpenRouter, DeepInfra, LiteLLM) override this.
+     */
+    protected resolveCostUsd(_usage: any, _rawResponse?: Response): number | undefined;
+    /**
+     * Extra request body fields injected on every call. Subclasses override to
+     * add provider-specific request shapes (e.g. OpenRouter's `usage: { include: true }`
+     * or its `plugins: [{ id: "web" }]` for web search). Merged into the request
+     * after the standard params so it can override them.
+     */
+    protected buildRequestExtras(_config: SmolConfig): Record<string, unknown>;
+    /**
+     * Extract provider-specific hosted-tool results (e.g. OpenRouter web_search
+     * annotations) from a completion. Subclasses override; default returns none.
+     */
+    protected parseHostedToolResults(_completion: any, _config: SmolConfig): HostedToolResult[];
     getClient(): OpenAI;
     getModel(): ModelName;
-    private calculateUsageAndCost;
+    protected calculateUsageAndCost(usageData: any, rawResponse?: Response): {
+        usage?: TokenUsage;
+        cost?: CostEstimate;
+    };
     private buildRequest;
     private rethrowAsSmolError;
     _textSync(config: SmolConfig): Promise<Result<PromptResult>>;

package/dist/clients/openai.js

@@ -3,6 +3,7 @@ import { success, } from "../types.js";
 import { ToolCall } from "../classes/ToolCall.js";
 import { isFunctionToolCall, sanitizeAttributes } from "../util/util.js";
 import { getLogger } from "../util/logger.js";
+import { redactAttachments } from "../util/redact.js";
 import { BaseClient } from "./baseClient.js";
 import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
 import { extractHttpErrorFields } from "../util/httpError.js";
@@ -14,20 +15,57 @@ export class SmolOpenAi extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        if (!config.openAiApiKey) {
-            throw new Error("OpenAI API key is required for SmolOpenAi client.");
-        }
-        this.client = new OpenAI({ apiKey: config.openAiApiKey });
+        const options = this.resolveClientOptions(config);
+        this.client = new OpenAI(options);
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }
+    /**
+     * Build the `new OpenAI({...})` options. Subclasses override to inject a
+     * different baseURL or to pull the key from a different config field.
+     *
+     * Default behavior: read OPENAI_API_KEY (or config.apiKey.openAi). Throws
+     * if the key is missing — subclasses with required keys do their own check.
+     */
+    resolveClientOptions(config) {
+        const apiKey = config.apiKey?.openAi || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error("OpenAI API key is required for SmolOpenAi client.");
+        }
+        return { apiKey };
+    }
+    /**
+     * Inspect the provider-returned usage (and optionally the raw HTTP response)
+     * for a USD cost figure. Returns `undefined` if the provider didn't surface
+     * one, in which case `calculateUsageAndCost` falls back to the smoltalk
+     * model registry. Subclasses (OpenRouter, DeepInfra, LiteLLM) override this.
+     */
+    resolveCostUsd(_usage, _rawResponse) {
+        return undefined;
+    }
+    /**
+     * Extra request body fields injected on every call. Subclasses override to
+     * add provider-specific request shapes (e.g. OpenRouter's `usage: { include: true }`
+     * or its `plugins: [{ id: "web" }]` for web search). Merged into the request
+     * after the standard params so it can override them.
+     */
+    buildRequestExtras(_config) {
+        return {};
+    }
+    /**
+     * Extract provider-specific hosted-tool results (e.g. OpenRouter web_search
+     * annotations) from a completion. Subclasses override; default returns none.
+     */
+    parseHostedToolResults(_completion, _config) {
+        return [];
+    }
     getClient() {
         return this.client;
     }
     getModel() {
         return this.model.getModel();
     }
-    calculateUsageAndCost(usageData) {
+    calculateUsageAndCost(usageData, rawResponse) {
         let usage;
         let cost;
         if (usageData) {
@@ -40,9 +78,23 @@ export class SmolOpenAi extends BaseClient {
             if (cached > 0) {
                 usage.cachedInputTokens = cached;
             }
-            const calculatedCost = this.model.calculateCost(usage);
-            if (calculatedCost) {
-                cost = calculatedCost;
+            // Prefer provider-supplied cost when available (e.g. OpenRouter
+            // usage.cost, DeepInfra usage.estimated_cost, LiteLLM header).
+            // Fall back to the smoltalk model-registry calculation.
+            const providerCost = this.resolveCostUsd(usageData, rawResponse);
+            if (typeof providerCost === "number") {
+                cost = {
+                    inputCost: 0,
+                    outputCost: 0,
+                    totalCost: providerCost,
+                    currency: "USD",
+                };
+            }
+            else {
+                const calculatedCost = this.model.calculateCost(usage);
+                if (calculatedCost) {
+                    cost = calculatedCost;
+                }
             }
         }
         return { usage, cost };
@@ -61,6 +113,7 @@ export class SmolOpenAi extends BaseClient {
                 reasoning_effort: config.reasoningEffort,
             }),
             ...sanitizeAttributes(config.rawAttributes),
+            ...this.buildRequestExtras(config),
         };
         if (config.responseFormat) {
             request.response_format = {
@@ -88,15 +141,20 @@ export class SmolOpenAi extends BaseClient {
     }
     async _textSync(config) {
         const request = this.buildRequest(config);
-        this.logger.debug("Sending request to OpenAI:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending request to OpenAI:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         let completion;
+        let rawResponse;
         try {
-            completion = await this.client.chat.completions.create({
+            const result = await this.client.chat.completions
+                .create({
                 ...request,
                 stream: false,
-            }, { ...(signal && { signal }) });
+            }, { ...(signal && { signal }) })
+                .withResponse();
+            completion = result.data;
+            rawResponse = result.response;
         }
         catch (error) {
             this.rethrowAsSmolError(error);
@@ -123,19 +181,22 @@ export class SmolOpenAi extends BaseClient {
                 }
             }
         }
-        // Extract usage and calculate cost
-        const { usage, cost } = this.calculateUsageAndCost(completion.usage);
+        // Extract usage and calculate cost. rawResponse lets subclasses read
+        // response headers (e.g. LiteLLM's x-litellm-response-cost).
+        const { usage, cost } = this.calculateUsageAndCost(completion.usage, rawResponse);
+        const hostedToolResults = this.parseHostedToolResults(completion, config);
         return success({
             output,
             toolCalls,
             usage,
             cost,
             model: this.getModel(),
+            ...(hostedToolResults.length > 0 ? { hostedToolResults } : {}),
         });
     }
     async *_textStream(config) {
         const request = this.buildRequest(config);
-        this.logger.debug("Sending streaming request to OpenAI:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending streaming request to OpenAI:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         let completion;
@@ -156,6 +217,9 @@ export class SmolOpenAi extends BaseClient {
         for await (const chunk of completion) {
             // Extract usage from the final chunk
             if (chunk.usage) {
+                // Header-based cost (LiteLLM) is unsupported while streaming.
+                // Body-based cost (OpenRouter/DeepInfra) still works because it
+                // comes through chunk.usage.
                 const usageAndCost = this.calculateUsageAndCost(chunk.usage);
                 usage = usageAndCost.usage;
                 cost = usageAndCost.cost;

package/dist/clients/openaiCompat.d.ts

@@ -0,0 +1,22 @@
+import { SmolOpenAi } from "./openai.js";
+import type { SmolConfig } from "../types.js";
+/**
+ * Generic OpenAI-compatible client. Use when pointing smoltalk at any
+ * arbitrary OpenAI-shaped endpoint (vLLM, TGI, LM Studio, OpenLLM, etc.).
+ *
+ * Both `config.apiKey.openAiCompat` and `config.baseUrl.openAiCompat` are
+ * required (or their env-var fallbacks: `OPENAI_COMPAT_API_KEY`,
+ * `OPENAI_COMPAT_BASE_URL`).
+ *
+ * Cost: opportunistically reads `usage.cost`, `usage.estimated_cost`, or
+ * `usage.cost_usd` if the backend includes one of them. Otherwise falls back
+ * to the smoltalk model registry (which won't have these custom models, so
+ * cost stays undefined — that's expected for arbitrary backends).
+ */
+export declare class SmolOpenAiCompat extends SmolOpenAi {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(usage: any): number | undefined;
+}

package/dist/clients/openaiCompat.js

@@ -0,0 +1,33 @@
+import { SmolOpenAi } from "./openai.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * Generic OpenAI-compatible client. Use when pointing smoltalk at any
+ * arbitrary OpenAI-shaped endpoint (vLLM, TGI, LM Studio, OpenLLM, etc.).
+ *
+ * Both `config.apiKey.openAiCompat` and `config.baseUrl.openAiCompat` are
+ * required (or their env-var fallbacks: `OPENAI_COMPAT_API_KEY`,
+ * `OPENAI_COMPAT_BASE_URL`).
+ *
+ * Cost: opportunistically reads `usage.cost`, `usage.estimated_cost`, or
+ * `usage.cost_usd` if the backend includes one of them. Otherwise falls back
+ * to the smoltalk model registry (which won't have these custom models, so
+ * cost stays undefined — that's expected for arbitrary backends).
+ */
+export class SmolOpenAiCompat extends SmolOpenAi {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("openai-compat", config);
+        const baseURL = resolveBaseUrl("openai-compat", config);
+        if (!apiKey) {
+            throw new Error("openai-compat: API key required (config.apiKey.openAiCompat or OPENAI_COMPAT_API_KEY).");
+        }
+        if (!baseURL) {
+            throw new Error("openai-compat: base URL required (config.baseUrl.openAiCompat or OPENAI_COMPAT_BASE_URL).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(usage) {
+        // Try the three common conventions across OpenAI-compatible providers.
+        const c = usage?.cost ?? usage?.estimated_cost ?? usage?.cost_usd;
+        return typeof c === "number" ? c : undefined;
+    }
+}

package/dist/clients/openaiResponses.js

@@ -2,6 +2,7 @@ import OpenAI from "openai";
 import { success, } from "../types.js";
 import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../util/logger.js";
+import { redactAttachments } from "../util/redact.js";
 import { BaseClient } from "./baseClient.js";
 import { zodToOpenAIResponsesTool } from "../util/tool.js";
 import { sanitizeAttributes } from "../util/util.js";
@@ -53,10 +54,11 @@ export class SmolOpenAiResponses extends BaseClient {
     model;
     constructor(config) {
         super(config);
-        if (!config.openAiApiKey) {
+        const apiKey = config.apiKey?.openAi || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
             throw new Error("OpenAI API key is required for SmolOpenAiResponses client.");
         }
-        this.client = new OpenAI({ apiKey: config.openAiApiKey });
+        this.client = new OpenAI({ apiKey });
         this.logger = getLogger();
         this.model = new Model(config.model, undefined, config.modelData);
     }
@@ -165,7 +167,7 @@ export class SmolOpenAiResponses extends BaseClient {
     }
     async _textSync(config) {
         const request = this.buildRequest(config);
-        this.logger.debug("Sending request to OpenAI Responses API:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending request to OpenAI Responses API:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         let response;
@@ -204,7 +206,7 @@ export class SmolOpenAiResponses extends BaseClient {
     }
     async *_textStream(config) {
         const request = this.buildRequest(config);
-        this.logger.debug("Sending streaming request to OpenAI Responses API:", JSON.stringify(request, null, 2));
+        this.logger.debug("Sending streaming request to OpenAI Responses API:", JSON.stringify(redactAttachments(request), null, 2));
         this.statelogClient?.promptRequest(request);
         const signal = this.getAbortSignal(config);
         let stream;

package/dist/clients/openrouter.d.ts

@@ -0,0 +1,23 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import type { SmolConfig, HostedToolResult } from "../types.js";
+/**
+ * OpenRouter client (https://openrouter.ai). OpenAI-compatible chat completions.
+ *
+ * - Baked base URL `https://openrouter.ai/api/v1` (override via config.baseUrl.openRouter).
+ * - Key: config.apiKey.openRouter or env OPENROUTER_API_KEY.
+ * - Cost: reads `usage.cost` (USD). OpenRouter only returns this when
+ *   `usage: { include: true }` is set in the request body, which this client
+ *   injects automatically via buildRequestExtras.
+ * - Hosted web_search: when config.hostedTools includes "web_search",
+ *   injects `plugins: [{ id: "web", max_results: 5 }]` and parses
+ *   message.annotations into a HostedToolResult.
+ */
+export declare class SmolOpenRouter extends SmolOpenAiCompat {
+    protected resolveClientOptions(config: SmolConfig): {
+        apiKey: string;
+        baseURL: string;
+    };
+    protected resolveCostUsd(usage: any): number | undefined;
+    protected buildRequestExtras(config: SmolConfig): Record<string, unknown>;
+    protected parseHostedToolResults(completion: any, config: SmolConfig): HostedToolResult[];
+}

package/dist/clients/openrouter.js

@@ -0,0 +1,76 @@
+import { SmolOpenAiCompat } from "./openaiCompat.js";
+import { webSearchResult } from "../util/hostedTools.js";
+import { resolveApiKey, resolveBaseUrl } from "../util/provider.js";
+/**
+ * OpenRouter client (https://openrouter.ai). OpenAI-compatible chat completions.
+ *
+ * - Baked base URL `https://openrouter.ai/api/v1` (override via config.baseUrl.openRouter).
+ * - Key: config.apiKey.openRouter or env OPENROUTER_API_KEY.
+ * - Cost: reads `usage.cost` (USD). OpenRouter only returns this when
+ *   `usage: { include: true }` is set in the request body, which this client
+ *   injects automatically via buildRequestExtras.
+ * - Hosted web_search: when config.hostedTools includes "web_search",
+ *   injects `plugins: [{ id: "web", max_results: 5 }]` and parses
+ *   message.annotations into a HostedToolResult.
+ */
+export class SmolOpenRouter extends SmolOpenAiCompat {
+    resolveClientOptions(config) {
+        const apiKey = resolveApiKey("openrouter", config);
+        // resolveBaseUrl bakes in the openrouter default, so this is always defined.
+        const baseURL = resolveBaseUrl("openrouter", config);
+        if (!apiKey) {
+            throw new Error("openrouter: API key required (config.apiKey.openRouter or OPENROUTER_API_KEY).");
+        }
+        return { apiKey, baseURL };
+    }
+    resolveCostUsd(usage) {
+        return typeof usage?.cost === "number" ? usage.cost : undefined;
+    }
+    buildRequestExtras(config) {
+        // OpenRouter only returns usage.cost when this is set.
+        const extras = { usage: { include: true } };
+        if (config.hostedTools?.includes("web_search")) {
+            extras.plugins = [{ id: "web", max_results: 5 }];
+        }
+        return extras;
+    }
+    parseHostedToolResults(completion, config) {
+        if (!config.hostedTools?.includes("web_search"))
+            return [];
+        const annotations = completion?.choices?.[0]?.message?.annotations;
+        if (!Array.isArray(annotations) || annotations.length === 0)
+            return [];
+        const sources = [];
+        const citations = [];
+        for (const a of annotations) {
+            if (a?.type !== "url_citation" || !a.url_citation?.url)
+                continue;
+            const uc = a.url_citation;
+            const source = {
+                url: uc.url,
+            };
+            if (uc.title)
+                source.title = uc.title;
+            if (uc.content)
+                source.snippet = uc.content;
+            sources.push(source);
+            const citation = { url: uc.url };
+            if (uc.title)
+                citation.title = uc.title;
+            if (typeof uc.start_index === "number")
+                citation.startIndex = uc.start_index;
+            if (typeof uc.end_index === "number")
+                citation.endIndex = uc.end_index;
+            citations.push(citation);
+        }
+        if (sources.length === 0)
+            return [];
+        return [
+            webSearchResult("openrouter", {
+                sources,
+                citations,
+                callCount: 1,
+            }),
+        ];
+    }
+}

package/dist/clients/resolveAttachments.d.ts

@@ -0,0 +1,11 @@
+import { Message } from "../classes/message/index.js";
+import { Result } from "../types.js";
+export declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Whether any user message carries an image/file attachment part. */
+export declare function messagesHaveAttachments(messages: Message[]): boolean;
+/** Whether `provider` accepts a remote URL directly for this part type. */
+export declare function acceptsRemoteUrl(provider: string, partType: "image" | "file"): boolean;
+export declare function resolveMessageAttachments(messages: Message[], options: {
+    provider: string;
+    maxBytes: number;
+}): Promise<Result<Message[]>>;