smoltalk 0.4.1 → 0.5.0

package/dist/smolError.d.ts

@@ -1,15 +1,88 @@
+export interface SmolErrorOptions {
+    /** HTTP status code from the provider response, when the error came from an HTTP call. */
+    status?: number;
+    /**
+     * Curated, safe-to-log subset of the provider response headers (see
+     * `extractHttpErrorFields` for the allowlist). The full, unredacted headers
+     * live on the raw provider error at `cause`.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Suggested wait before retrying, in milliseconds, parsed from the
+     * `retry-after-ms` / `retry-after` response headers (when available).
+     */
+    retryAfterMs?: number;
+    /** Provider request id (`x-request-id` / `request-id`), useful for support tickets. */
+    requestId?: string;
+    /** The underlying provider error this was derived from, if any. */
+    cause?: unknown;
+}
+/**
+ * Base error type for all smoltalk failures. Carries a curated, safe-to-log
+ * snapshot of the HTTP response on `status` / `headers` / `retryAfterMs` /
+ * `requestId`.
+ *
+ * **Security note on `cause`:** the raw provider error is attached at `cause`
+ * as a non-enumerable property (using the ES2022 `Error` `{ cause }` option),
+ * so `JSON.stringify(err)` and most error serializers (Sentry, pino, Bunyan)
+ * will NOT walk it. The custom `toJSON()` below similarly omits both `cause`
+ * and `stack`. The provider error can still contain `authorization` headers,
+ * cookies, and echoed prompt bodies — direct access (`err.cause`) and Node's
+ * native `console.error` chain still work, so handle deliberately.
+ */
 export declare class SmolError extends Error {
-    constructor(message: string);
+    /** HTTP status code from the provider response, when available. */
+    readonly status?: number;
+    /**
+     * Curated, safe-to-log subset of the provider response headers. For the full,
+     * unredacted set (including any session cookies the provider sent), reach for
+     * the raw provider error on `cause` — but note that `cause` is non-enumerable
+     * specifically to keep it out of casual logging.
+     */
+    readonly headers?: Record<string, string>;
+    /**
+     * Suggested wait before retrying, in milliseconds, parsed from the
+     * `retry-after-ms` / `retry-after` response headers (when available).
+     * Always non-negative and capped at a sane ceiling (see `httpError.ts`).
+     */
+    readonly retryAfterMs?: number;
+    /** Provider request id (`x-request-id` / `request-id`), useful for support tickets. */
+    readonly requestId?: string;
+    constructor(message: string, options?: SmolErrorOptions);
+    /**
+     * Custom JSON serializer. Returns only the curated/safe fields — never
+     * `cause` or `stack`, both of which can leak secrets (auth headers in
+     * `cause`, file system paths and source snippets in `stack`).
+     */
+    toJSON(): Record<string, unknown>;
 }
 export declare class SmolStructuredOutputError extends SmolError {
-    constructor(message: string);
+    constructor(message: string, options?: SmolErrorOptions);
 }
 export declare class SmolTimeoutError extends SmolError {
-    constructor(message: string);
+    constructor(message: string, options?: SmolErrorOptions);
 }
 export declare class SmolContentPolicyError extends SmolError {
-    constructor(message: string);
+    constructor(message: string, options?: SmolErrorOptions);
 }
 export declare class SmolContextWindowExceededError extends SmolError {
-    constructor(message: string);
+    constructor(message: string, options?: SmolErrorOptions);
+}
+/** Rate limited (HTTP 429). Inspect `retryAfterMs` to back off. */
+export declare class SmolRateLimitError extends SmolError {
+    constructor(message: string, options?: SmolErrorOptions);
+}
+/** Provider temporarily overloaded/unavailable (HTTP 503, or Anthropic's 529). */
+export declare class SmolOverloadedError extends SmolError {
+    constructor(message: string, options?: SmolErrorOptions);
+}
+/** Authentication or permission failure (HTTP 401/403). */
+export declare class SmolAuthError extends SmolError {
+    constructor(message: string, options?: SmolErrorOptions);
 }
+/**
+ * Pick the most specific SmolError subclass for an HTTP status code, so retry
+ * code can `instanceof`-dispatch instead of sniffing magic status numbers.
+ * Falls back to the base `SmolError` for unclassified statuses.
+ */
+export declare function smolErrorForStatus(message: string, options?: SmolErrorOptions): SmolError;

package/dist/smolError.js

@@ -1,30 +1,155 @@
+/**
+ * Base error type for all smoltalk failures. Carries a curated, safe-to-log
+ * snapshot of the HTTP response on `status` / `headers` / `retryAfterMs` /
+ * `requestId`.
+ *
+ * **Security note on `cause`:** the raw provider error is attached at `cause`
+ * as a non-enumerable property (using the ES2022 `Error` `{ cause }` option),
+ * so `JSON.stringify(err)` and most error serializers (Sentry, pino, Bunyan)
+ * will NOT walk it. The custom `toJSON()` below similarly omits both `cause`
+ * and `stack`. The provider error can still contain `authorization` headers,
+ * cookies, and echoed prompt bodies — direct access (`err.cause`) and Node's
+ * native `console.error` chain still work, so handle deliberately.
+ */
 export class SmolError extends Error {
-    constructor(message) {
+    /** HTTP status code from the provider response, when available. */
+    status;
+    /**
+     * Curated, safe-to-log subset of the provider response headers. For the full,
+     * unredacted set (including any session cookies the provider sent), reach for
+     * the raw provider error on `cause` — but note that `cause` is non-enumerable
+     * specifically to keep it out of casual logging.
+     */
+    headers;
+    /**
+     * Suggested wait before retrying, in milliseconds, parsed from the
+     * `retry-after-ms` / `retry-after` response headers (when available).
+     * Always non-negative and capped at a sane ceiling (see `httpError.ts`).
+     */
+    retryAfterMs;
+    /** Provider request id (`x-request-id` / `request-id`), useful for support tickets. */
+    requestId;
+    constructor(message, options = {}) {
         super(message);
         this.name = "SmolTalkError";
+        this.status = options.status;
+        this.headers = options.headers;
+        this.retryAfterMs = options.retryAfterMs;
+        this.requestId = options.requestId;
+        if (options.cause !== undefined) {
+            // Explicit non-enumerable install. A plain `this.cause = options.cause`
+            // would create an *enumerable* own property — `JSON.stringify(err)` and
+            // structured loggers (`logger.error({ err })`) would then walk `cause`
+            // and re-leak the raw provider error (including the unredacted
+            // `set-cookie` / `authorization` headers the allowlist stripped from
+            // `headers`). This restores the behavior the spec intends for
+            // `new Error(msg, { cause })`: `cause` is the escape hatch, not the
+            // default-serialized field.
+            Object.defineProperty(this, "cause", {
+                value: options.cause,
+                enumerable: false,
+                writable: true,
+                configurable: true,
+            });
+        }
+    }
+    /**
+     * Custom JSON serializer. Returns only the curated/safe fields — never
+     * `cause` or `stack`, both of which can leak secrets (auth headers in
+     * `cause`, file system paths and source snippets in `stack`).
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            status: this.status,
+            headers: this.headers,
+            retryAfterMs: this.retryAfterMs,
+            requestId: this.requestId,
+        };
+    }
+    /**
+     * Custom Node.js inspect. Node's default error formatter walks `cause` and
+     * prints it even when the property is non-enumerable, which would re-leak
+     * the raw provider error through `console.error(err)` / `util.inspect(err)`.
+     * Override that path to show a placeholder; callers who want the full chain
+     * can still reach for `err.cause` explicitly.
+     */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        const fields = [`${this.name}: ${this.message}`];
+        if (this.status !== undefined)
+            fields.push(`status: ${this.status}`);
+        if (this.requestId !== undefined)
+            fields.push(`requestId: ${JSON.stringify(this.requestId)}`);
+        if (this.retryAfterMs !== undefined)
+            fields.push(`retryAfterMs: ${this.retryAfterMs}`);
+        if (this.headers !== undefined)
+            fields.push(`headers: ${JSON.stringify(this.headers)}`);
+        if (this.cause !== undefined)
+            fields.push("cause: [hidden — access err.cause directly]");
+        return fields.join("\n  ");
     }
 }
 export class SmolStructuredOutputError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolStructuredOutputError";
     }
 }
 export class SmolTimeoutError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolTimeoutError";
     }
 }
 export class SmolContentPolicyError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolContentPolicyError";
     }
 }
 export class SmolContextWindowExceededError extends SmolError {
-    constructor(message) {
-        super(message);
+    constructor(message, options = {}) {
+        super(message, options);
         this.name = "SmolContextWindowExceededError";
     }
 }
+/** Rate limited (HTTP 429). Inspect `retryAfterMs` to back off. */
+export class SmolRateLimitError extends SmolError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SmolRateLimitError";
+    }
+}
+/** Provider temporarily overloaded/unavailable (HTTP 503, or Anthropic's 529). */
+export class SmolOverloadedError extends SmolError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SmolOverloadedError";
+    }
+}
+/** Authentication or permission failure (HTTP 401/403). */
+export class SmolAuthError extends SmolError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "SmolAuthError";
+    }
+}
+/**
+ * Pick the most specific SmolError subclass for an HTTP status code, so retry
+ * code can `instanceof`-dispatch instead of sniffing magic status numbers.
+ * Falls back to the base `SmolError` for unclassified statuses.
+ */
+export function smolErrorForStatus(message, options = {}) {
+    const status = options.status;
+    if (status === 429) {
+        return new SmolRateLimitError(message, options);
+    }
+    if (status === 503 || status === 529) {
+        return new SmolOverloadedError(message, options);
+    }
+    if (status === 401 || status === 403) {
+        return new SmolAuthError(message, options);
+    }
+    return new SmolError(message, options);
+}

package/dist/types/costEstimate.d.ts

@@ -4,6 +4,7 @@ export type CostEstimate = {
     outputCost: number;
     cachedInputCost?: number;
     cacheCreationInputCost?: number;
+    hostedToolsCost?: number;
     totalCost: number;
     currency: string;
 };
@@ -12,6 +13,7 @@ export declare const CostEstimateSchema: z.ZodObject<{
     outputCost: z.ZodNumber;
     cachedInputCost: z.ZodOptional<z.ZodNumber>;
     cacheCreationInputCost: z.ZodOptional<z.ZodNumber>;
+    hostedToolsCost: z.ZodOptional<z.ZodNumber>;
     totalCost: z.ZodNumber;
     currency: z.ZodString;
 }, z.core.$strip>;

package/dist/types/costEstimate.js

@@ -4,6 +4,7 @@ export const CostEstimateSchema = z.object({
     outputCost: z.number(),
     cachedInputCost: z.number().optional(),
     cacheCreationInputCost: z.number().optional(),
+    hostedToolsCost: z.number().optional(),
     totalCost: z.number(),
     currency: z.string(),
 });

package/dist/types.d.ts

@@ -5,6 +5,7 @@ import { Message } from "./classes/message/index.js";
 import { ToolCall } from "./classes/ToolCall.js";
 import { Model } from "./model.js";
 import { ModelName } from "./models.js";
+import type { ModelDataBlob } from "./modelData.js";
 import { Result } from "./types/result.js";
 import { TokenUsage } from "./types/tokenUsage.js";
 import { CostEstimate } from "./types/costEstimate.js";
@@ -44,6 +45,8 @@ export type SmolConfig = {
     }>;
     /** Arbitrary metadata passed to custom model providers. */
     metadata?: Record<string, any>;
+    /** Refreshed model/hosted-tool data (from refreshModels) to layer over the baked-in registry for this call. */
+    modelData?: ModelDataBlob;
     /** The conversation messages to send to the model. */
     messages: Message[];
     /** Tools (functions) the model can call. */
@@ -52,6 +55,10 @@ export type SmolConfig = {
         description?: string;
         schema: ZodType;
     }[];
+    /** Provider hosted tools (server-side) to enable for this call, by capability
+     *  name (catalog category), e.g. ["web_search"]. Distinct from `tools`
+     *  (client functions) — hosted tools run server-side and can't be intercepted. */
+    hostedTools?: string[];
     /** Maximum number of tokens the model can generate in its response. */
     maxTokens?: number;
     /** Sampling temperature (0-2). (OpenAI only) */
@@ -96,6 +103,27 @@ export type ToolLoopDetection = {
     intervention?: "remove-tool" | "remove-all-tools" | "throw-error" | "halt-execution";
     excludeTools?: string[];
 };
+export type WebSearchSource = {
+    url: string;
+    title?: string;
+    snippet?: string;
+};
+export type WebSearchCitation = {
+    url: string;
+    title?: string;
+    startIndex?: number;
+    endIndex?: number;
+};
+export type HostedToolResult = {
+    tool: string;
+    provider: string;
+    queries?: string[];
+    sources?: WebSearchSource[];
+    citations?: WebSearchCitation[];
+    callCount?: number;
+    estimatedCost?: number;
+    raw?: unknown;
+};
 export type PromptResult = {
     output: string | null;
     toolCalls: ToolCall[];
@@ -103,8 +131,9 @@ export type PromptResult = {
     usage?: TokenUsage;
     cost?: CostEstimate;
     model?: ModelName;
+    hostedToolResults?: HostedToolResult[];
 };
-export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, }: Partial<PromptResult>): PromptResult;
+export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, }: Partial<PromptResult>): PromptResult;
 export type StreamChunk = {
     type: "text";
     text: string;

package/dist/types.js

@@ -2,7 +2,7 @@ export * from "./types/result.js";
 import z from "zod";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
-export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, }) {
+export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, }) {
     return {
         output: output || null,
         toolCalls: toolCalls || [],
@@ -10,6 +10,7 @@ export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, m
         usage,
         cost,
         model,
+        hostedToolResults,
     };
 }
 export const TextPartSchema = z.object({

package/dist/util/hostedTools.d.ts

@@ -0,0 +1,19 @@
+import type { ModelDataBlob } from "../modelData.js";
+import type { CostEstimate } from "../types/costEstimate.js";
+import type { HostedToolResult, WebSearchSource, WebSearchCitation } from "../types.js";
+export declare const WEB_SEARCH = "web_search";
+export declare const IMPLEMENTED_HOSTED_TOOLS: Set<string>;
+export declare function validateHostedTools(requested: string[] | undefined, model: string, modelData?: ModelDataBlob): string | null;
+export declare function estimateHostedToolCost(result: HostedToolResult, model: string, modelData?: ModelDataBlob): number | undefined;
+export declare function foldHostedToolCost(cost: CostEstimate | undefined, results: HostedToolResult[]): CostEstimate | undefined;
+export declare function webSearchResult(provider: string, parts: {
+    queries?: string[];
+    sources?: WebSearchSource[];
+    citations?: WebSearchCitation[];
+    callCount?: number;
+    raw?: unknown;
+}): HostedToolResult;
+export declare function applyHostedToolCost(results: HostedToolResult[], cost: CostEstimate | undefined, model: string, modelData?: ModelDataBlob): {
+    results: HostedToolResult[];
+    cost: CostEstimate | undefined;
+};

package/dist/util/hostedTools.js

@@ -0,0 +1,104 @@
+import { getHostedTools, hostedToolPricingFor } from "../models.js";
+import { getModel } from "../models.js";
+import { round } from "./util.js";
+export const WEB_SEARCH = "web_search";
+// Capabilities whose runtime translation/parsing smoltalk actually implements.
+export const IMPLEMENTED_HOSTED_TOOLS = new Set([WEB_SEARCH]);
+// Returns an error message if any requested capability is unusable for this
+// model, else null. Capabilities are matched against the catalog `category`.
+export function validateHostedTools(requested, model, modelData) {
+    if (!requested || requested.length === 0) {
+        return null;
+    }
+    const allCategories = new Set(getHostedTools({ includeDisabled: true, modelData }).map((t) => t.category));
+    const availableCategories = new Set(getHostedTools({ model, modelData }).map((t) => t.category));
+    for (const name of requested) {
+        if (!IMPLEMENTED_HOSTED_TOOLS.has(name)) {
+            if (allCategories.has(name)) {
+                return `Hosted tool "${name}" is in the catalog but not yet supported by smoltalk at runtime.`;
+            }
+            return `Unknown hosted tool "${name}".`;
+        }
+        if (!availableCategories.has(name)) {
+            const provider = getModel(model, modelData)?.provider ?? "unknown";
+            return `${name} is a hosted capability; ${model} (${provider}) doesn't offer it — pass a search function as a tool instead.`;
+        }
+    }
+    return null;
+}
+// callCount x catalog price for the capability on this model. Only per_call
+// pricing yields a number (web search); undefined otherwise.
+export function estimateHostedToolCost(result, model, modelData) {
+    if (!result.callCount) {
+        return undefined;
+    }
+    const tools = getHostedTools({ model, includeDisabled: true, modelData });
+    const tool = tools.find((t) => t.category === result.tool && t.provider === result.provider);
+    if (!tool) {
+        return undefined;
+    }
+    const price = hostedToolPricingFor(tool, model);
+    if (!price || price.unit !== "per_call" || price.amount === undefined) {
+        return undefined;
+    }
+    return round(result.callCount * price.amount, 6);
+}
+// Fold per-result estimatedCost into a CostEstimate (hostedToolsCost + totalCost).
+export function foldHostedToolCost(cost, results) {
+    let hosted = 0;
+    for (const r of results) {
+        if (r.estimatedCost) {
+            hosted += r.estimatedCost;
+        }
+    }
+    if (hosted === 0) {
+        return cost;
+    }
+    const hostedRounded = round(hosted, 6);
+    if (!cost) {
+        return {
+            inputCost: 0,
+            outputCost: 0,
+            hostedToolsCost: hostedRounded,
+            totalCost: hostedRounded,
+            currency: "USD",
+        };
+    }
+    return {
+        ...cost,
+        hostedToolsCost: round((cost.hostedToolsCost || 0) + hosted, 6),
+        totalCost: round(cost.totalCost + hosted, 6),
+    };
+}
+// Build a normalized web-search result, omitting empty fields. One place for the
+// "assemble result" shape so each parser doesn't repeat it.
+export function webSearchResult(provider, parts) {
+    const result = { tool: WEB_SEARCH, provider };
+    if (parts.queries && parts.queries.length > 0) {
+        result.queries = parts.queries;
+    }
+    if (parts.sources && parts.sources.length > 0) {
+        result.sources = parts.sources;
+    }
+    if (parts.citations && parts.citations.length > 0) {
+        result.citations = parts.citations;
+    }
+    if (parts.callCount) {
+        result.callCount = parts.callCount;
+    }
+    if (parts.raw !== undefined) {
+        result.raw = parts.raw;
+    }
+    return result;
+}
+// Estimate per-result cost and fold the total into the CostEstimate. One call
+// for every client, so the estimate+fold sequence lives in exactly one place.
+export function applyHostedToolCost(results, cost, model, modelData) {
+    for (const r of results) {
+        const est = estimateHostedToolCost(r, model, modelData);
+        if (est !== undefined) {
+            r.estimatedCost = est;
+        }
+    }
+    return { results, cost: foldHostedToolCost(cost, results) };
+}

package/dist/util/httpError.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Best-effort extraction of HTTP status and headers from a provider SDK error.
+ *
+ * Each provider SDK shapes its errors slightly differently:
+ * - OpenAI / Anthropic: `status` (number) + `headers` (web `Headers`)
+ * - Google Gemini (`@google/genai`): `status` (number), no headers
+ * - Ollama: `status_code` (number), no headers
+ */
+export interface HttpErrorFields {
+    status?: number;
+    /** Allowlisted, safe-to-log subset of response headers (see `ALLOWED_HEADERS`). */
+    headers?: Record<string, string>;
+    /**
+     * Suggested wait before retrying, in milliseconds, parsed from the
+     * `retry-after-ms` / `retry-after` response headers. Only ever populated for
+     * OpenAI/Anthropic — Google and Ollama errors carry no headers to parse.
+     * Always non-negative and capped at `MAX_RETRY_AFTER_MS`.
+     */
+    retryAfterMs?: number;
+    /** Provider request id (`x-request-id` / `request-id`), useful for support tickets. */
+    requestId?: string;
+}
+export declare function extractHttpErrorFields(error: unknown): HttpErrorFields;