smoltalk 0.4.1 → 0.4.2

package/dist/classes/ToolCall.js

@@ -47,9 +47,10 @@ export class ToolCall {
     static fromJSON(json) {
         const result = ToolCallJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse ToolCall");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse ToolCall:", z.prettifyError(result.error));
+            // Raw payload can contain tool-call arguments (often secrets) — only at debug level.
+            logger.debug("ToolCall payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse ToolCall");
         }
         return new ToolCall(result.data.id, result.data.name, result.data.arguments);

package/dist/classes/message/AssistantMessage.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
 import { CostEstimateSchema, TextPartSchema, ThinkingBlockSchema, TokenUsageSchema, } from "../../types.js";
 import { ToolCall, ToolCallJSONSchema } from "../ToolCall.js";
+import { getLogger } from "../../util/logger.js";
 export const AssistantMessageJSONSchema = z.object({
     role: z.literal("assistant"),
     content: z.union([z.string(), z.array(TextPartSchema), z.null()]),
@@ -86,9 +87,10 @@ export class AssistantMessage extends BaseMessage {
     static fromJSON(json) {
         const result = AssistantMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse AssistantMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse AssistantMessage:", z.prettifyError(result.error));
+            // Raw payload can contain assistant content / tool args — only at debug level.
+            logger.debug("AssistantMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse AssistantMessage");
         }
         return new AssistantMessage(result.data.content, {

package/dist/classes/message/DeveloperMessage.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
 import { TextPartSchema } from "../../types.js";
+import { getLogger } from "../../util/logger.js";
 export const DeveloperMessageJSONSchema = z.object({
     role: z.literal("developer"),
     content: z.union([z.string(), z.array(TextPartSchema)]),
@@ -43,9 +44,10 @@ export class DeveloperMessage extends BaseMessage {
     static fromJSON(json) {
         const result = DeveloperMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse DeveloperMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse DeveloperMessage:", z.prettifyError(result.error));
+            // Raw payload can contain developer-message content — only at debug level.
+            logger.debug("DeveloperMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse DeveloperMessage");
         }
         return new DeveloperMessage(result.data.content, {

package/dist/classes/message/SystemMessage.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
 import { TextPartSchema } from "../../types.js";
+import { getLogger } from "../../util/logger.js";
 export const SystemMessageJSONSchema = z.object({
     role: z.literal("system"),
     content: z.union([z.string(), z.array(TextPartSchema)]),
@@ -43,9 +44,10 @@ export class SystemMessage extends BaseMessage {
     static fromJSON(json) {
         const result = SystemMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse SystemMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse SystemMessage:", z.prettifyError(result.error));
+            // Raw payload can contain system prompt content — only at debug level.
+            logger.debug("SystemMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse SystemMessage");
         }
         return new SystemMessage(result.data.content, {

package/dist/classes/message/ToolMessage.js

@@ -52,9 +52,10 @@ export class ToolMessage extends BaseMessage {
     static fromJSON(json) {
         const result = ToolMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse ToolMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse ToolMessage:", z.prettifyError(result.error));
+            // Raw payload can contain tool results (file paths, secrets) — only at debug level.
+            logger.debug("ToolMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse ToolMessage");
         }
         const TextPartArraySchema = z.array(TextPartSchema);

package/dist/classes/message/UserMessage.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
+import { getLogger } from "../../util/logger.js";
 export const UserMessageJSONSchema = z.object({
     role: z.literal("user"),
     content: z.string(),
@@ -42,9 +43,10 @@ export class UserMessage extends BaseMessage {
     static fromJSON(json) {
         const result = UserMessageJSONSchema.safeParse(json);
         if (!result.success) {
-            console.error("Failed to parse UserMessage");
-            console.error(JSON.stringify(json, null, 2));
-            console.error(z.prettifyError(result.error));
+            const logger = getLogger();
+            logger.error("Failed to parse UserMessage:", z.prettifyError(result.error));
+            // Raw payload can contain user prompts / PII — only at debug level.
+            logger.debug("UserMessage payload that failed to parse:", JSON.stringify(json, null, 2));
             throw new Error("Failed to parse UserMessage");
         }
         return new UserMessage(result.data.content, {

package/dist/clients/anthropic.js

@@ -4,7 +4,8 @@ import { SystemMessage, DeveloperMessage } from "../classes/message/index.js";
 import { getLogger } from "../util/logger.js";
 import { success, } from "../types.js";
 import { zodToAnthropicTool } from "../util/tool.js";
-import { SmolContentPolicyError, SmolContextWindowExceededError, } from "../smolError.js";
+import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { extractHttpErrorFields } from "../util/httpError.js";
 import { BaseClient } from "./baseClient.js";
 import { getModel, isTextModel } from "../models.js";
 import { Model } from "../model.js";
@@ -212,19 +213,21 @@ export class SmolAnthropic extends BaseClient {
     }
     rethrowAsSmolError(error) {
         if (error instanceof Anthropic.APIError) {
+            const http = { ...extractHttpErrorFields(error), cause: error };
             const msg = error.message.toLowerCase();
             if (msg.includes("prompt is too long") ||
                 msg.includes("context length") ||
                 msg.includes("context window") ||
                 msg.includes("too many tokens")) {
-                throw new SmolContextWindowExceededError(error.message);
+                throw new SmolContextWindowExceededError(error.message, http);
             }
             if (msg.includes("content policy") ||
                 msg.includes("usage policies") ||
                 msg.includes("content filtering") ||
                 msg.includes("violates our")) {
-                throw new SmolContentPolicyError(error.message);
+                throw new SmolContentPolicyError(error.message, http);
             }
+            throw smolErrorForStatus(error.message, http);
         }
         throw error;
     }

package/dist/clients/google.d.ts

@@ -17,6 +17,7 @@ export declare class SmolGoogle extends BaseClient implements SmolClient {
     getModel(): ModelName;
     private calculateUsageAndCost;
     private buildRequest;
+    private rethrowAsSmolError;
     _textSync(config: SmolConfig): Promise<Result<PromptResult>>;
     __textSync(request: GeneratedRequest): Promise<Result<PromptResult>>;
     _textStream(config: SmolConfig): AsyncGenerator<StreamChunk>;

package/dist/clients/google.js

@@ -3,7 +3,8 @@ import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../util/logger.js";
 import { addCosts, addTokenUsage, success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
-import { SmolContentPolicyError, SmolContextWindowExceededError, } from "../smolError.js";
+import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { extractHttpErrorFields } from "../util/httpError.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { BaseClient } from "./baseClient.js";
 import { Model } from "../model.js";
@@ -88,6 +89,18 @@ export class SmolGoogle extends BaseClient {
             ...sanitizeAttributes(config.rawAttributes),
         };
     }
+    rethrowAsSmolError(error) {
+        const http = { ...extractHttpErrorFields(error), cause: error };
+        const msg = (error.message || "").toLowerCase();
+        if (msg.includes("token") &&
+            (msg.includes("exceed") || msg.includes("too long") || msg.includes("limit"))) {
+            throw new SmolContextWindowExceededError(error.message, http);
+        }
+        if (http.status !== undefined) {
+            throw smolErrorForStatus(error.message, http);
+        }
+        throw error;
+    }
     async _textSync(config) {
         const signal = this.getAbortSignal(config);
         const request = {
@@ -180,14 +193,7 @@ export class SmolGoogle extends BaseClient {
             result = await this.client.models.generateContent(request);
         }
         catch (error) {
-            const msg = (error.message || "").toLowerCase();
-            if (msg.includes("token") &&
-                (msg.includes("exceed") ||
-                    msg.includes("too long") ||
-                    msg.includes("limit"))) {
-                throw new SmolContextWindowExceededError(error.message);
-            }
-            throw error;
+            this.rethrowAsSmolError(error);
         }
         this.logger.debug("Response from Google Gemini:", JSON.stringify(result, null, 2));
         this.statelogClient?.promptResponse(result);
@@ -257,14 +263,7 @@ export class SmolGoogle extends BaseClient {
             stream = await this.client.models.generateContentStream(request);
         }
         catch (error) {
-            const msg = (error.message || "").toLowerCase();
-            if (msg.includes("token") &&
-                (msg.includes("exceed") ||
-                    msg.includes("too long") ||
-                    msg.includes("limit"))) {
-                throw new SmolContextWindowExceededError(error.message);
-            }
-            throw error;
+            this.rethrowAsSmolError(error);
         }
         let content = "";
         const toolCallsMap = new Map();

package/dist/clients/ollama.d.ts

@@ -12,6 +12,7 @@ export declare class SmolOllama extends BaseClient implements SmolClient {
     getClient(): Ollama;
     getModel(): ModelName;
     private calculateUsageAndCost;
+    private rethrowAsSmolError;
     _textSync(config: SmolConfig): Promise<Result<PromptResult>>;
     _textStream(config: SmolConfig): AsyncGenerator<StreamChunk>;
 }

package/dist/clients/ollama.js

@@ -5,7 +5,8 @@ import { success, } from "../types.js";
 import { zodToGoogleTool } from "../util/tool.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { BaseClient } from "./baseClient.js";
-import { SmolContextWindowExceededError } from "../smolError.js";
+import { SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { extractHttpErrorFields } from "../util/httpError.js";
 import { Model } from "../model.js";
 export const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
 export class SmolOllama extends BaseClient {
@@ -51,6 +52,17 @@ export class SmolOllama extends BaseClient {
         }
         return { usage, cost };
     }
+    rethrowAsSmolError(error) {
+        const http = { ...extractHttpErrorFields(error), cause: error };
+        const msg = (error.message || "").toLowerCase();
+        if (msg.includes("context length") || msg.includes("context window")) {
+            throw new SmolContextWindowExceededError(error.message, http);
+        }
+        if (http.status !== undefined) {
+            throw smolErrorForStatus(error.message, http);
+        }
+        throw error;
+    }
     async _textSync(config) {
         const messages = config.messages.map((msg) => msg.toOpenAIMessage());
         const tools = (config.tools || []).map((tool) => {
@@ -82,11 +94,7 @@ export class SmolOllama extends BaseClient {
             result = await this.client.chat(request);
         }
         catch (error) {
-            const msg = (error.message || "").toLowerCase();
-            if (msg.includes("context length") || msg.includes("context window")) {
-                throw new SmolContextWindowExceededError(error.message);
-            }
-            throw error;
+            this.rethrowAsSmolError(error);
         }
         finally {
             if (signal && abortHandler) {
@@ -201,6 +209,9 @@ export class SmolOllama extends BaseClient {
                 },
             };
         }
+        catch (error) {
+            this.rethrowAsSmolError(error);
+        }
         finally {
             if (signal && abortHandler) {
                 signal.removeEventListener("abort", abortHandler);

package/dist/clients/openai.js

@@ -4,7 +4,8 @@ import { ToolCall } from "../classes/ToolCall.js";
 import { isFunctionToolCall, sanitizeAttributes } from "../util/util.js";
 import { getLogger } from "../util/logger.js";
 import { BaseClient } from "./baseClient.js";
-import { SmolContentPolicyError, SmolContextWindowExceededError, } from "../smolError.js";
+import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { extractHttpErrorFields } from "../util/httpError.js";
 import { zodToOpenAITool } from "../util/tool.js";
 import { Model } from "../model.js";
 export class SmolOpenAi extends BaseClient {
@@ -74,12 +75,14 @@ export class SmolOpenAi extends BaseClient {
     }
     rethrowAsSmolError(error) {
         if (error instanceof OpenAI.APIError) {
+            const http = { ...extractHttpErrorFields(error), cause: error };
             if (error.code === "context_length_exceeded") {
-                throw new SmolContextWindowExceededError(error.message);
+                throw new SmolContextWindowExceededError(error.message, http);
             }
             if (error.code === "content_policy_violation") {
-                throw new SmolContentPolicyError(error.message);
+                throw new SmolContentPolicyError(error.message, http);
             }
+            throw smolErrorForStatus(error.message, http);
         }
         throw error;
     }

package/dist/clients/openaiResponses.js

@@ -6,7 +6,8 @@ import { BaseClient } from "./baseClient.js";
 import { zodToOpenAIResponsesTool } from "../util/tool.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { Model } from "../model.js";
-import { SmolContentPolicyError, SmolContextWindowExceededError, } from "../smolError.js";
+import { SmolContentPolicyError, SmolContextWindowExceededError, smolErrorForStatus, } from "../smolError.js";
+import { extractHttpErrorFields } from "../util/httpError.js";
 export class SmolOpenAiResponses extends BaseClient {
     client;
     logger;
@@ -107,12 +108,14 @@ export class SmolOpenAiResponses extends BaseClient {
     }
     rethrowAsSmolError(error) {
         if (error instanceof OpenAI.APIError) {
+            const http = { ...extractHttpErrorFields(error), cause: error };
             if (error.code === "context_length_exceeded") {
-                throw new SmolContextWindowExceededError(error.message);
+                throw new SmolContextWindowExceededError(error.message, http);
             }
             if (error.code === "content_policy_violation") {
-                throw new SmolContentPolicyError(error.message);
+                throw new SmolContentPolicyError(error.message, http);
             }
+            throw smolErrorForStatus(error.message, http);
         }
         throw error;
     }

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/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;

package/dist/util/httpError.js

@@ -0,0 +1,237 @@
+/**
+ * Explicit allowlist (not denylist, not prefix-wildcard). smoltalk can be
+ * pointed at proxies (LiteLLM, OpenRouter) that re-emit upstream headers
+ * verbatim, and some APIs echo credentials back on errors — a denylist would
+ * pass `authorization`, `x-api-key`, forwarded `llm_provider-*` headers, etc.
+ * (cf. Traefik GHSA-p6hg-qh38-555r). A prefix wildcard like `x-ratelimit-*`
+ * is safer than a denylist but still risks absorbing a future
+ * `x-ratelimit-organization` style header that carries an identifier or
+ * secret. Capture only known-safe headers with diagnostic value; the raw
+ * provider error is reachable on `SmolError.cause` (non-enumerable) as the
+ * escape hatch for callers that explicitly opt in.
+ */
+const ALLOWED_HEADERS = new Set([
+    // Retry hints
+    "retry-after",
+    "retry-after-ms",
+    // Request correlation
+    "request-id",
+    "x-request-id",
+    // Diagnostic
+    "content-type",
+    // OpenAI rate-limit family (exhaustive as of writing — new headers added
+    // by providers must be added explicitly here).
+    "x-ratelimit-limit-requests",
+    "x-ratelimit-limit-tokens",
+    "x-ratelimit-remaining-requests",
+    "x-ratelimit-remaining-tokens",
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    // Anthropic rate-limit family
+    "anthropic-ratelimit-requests-limit",
+    "anthropic-ratelimit-requests-remaining",
+    "anthropic-ratelimit-requests-reset",
+    "anthropic-ratelimit-tokens-limit",
+    "anthropic-ratelimit-tokens-remaining",
+    "anthropic-ratelimit-tokens-reset",
+    "anthropic-ratelimit-input-tokens-limit",
+    "anthropic-ratelimit-input-tokens-remaining",
+    "anthropic-ratelimit-input-tokens-reset",
+    "anthropic-ratelimit-output-tokens-limit",
+    "anthropic-ratelimit-output-tokens-remaining",
+    "anthropic-ratelimit-output-tokens-reset",
+]);
+function isAllowedHeader(name) {
+    return ALLOWED_HEADERS.has(name.toLowerCase());
+}
+/**
+ * Upper bound on `retryAfterMs`. Anything longer is almost certainly a
+ * misparsed HTTP-date or a hostile/buggy proxy injecting a far-future value
+ * (e.g. `Sat, 01 Jan 9999 …`). 5 minutes is well beyond any sane provider
+ * rate-limit window — callers that wanted to wait longer would have given
+ * up by then anyway.
+ */
+const MAX_RETRY_AFTER_MS = 5 * 60 * 1000;
+function clampRetryAfter(ms) {
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, Math.round(ms)));
+}
+/**
+ * Read a property without letting a throwing accessor break the whole
+ * extraction. Some error shapes (especially JSON-parsed bodies that bubble
+ * up as errors) can carry getters that throw or have side effects.
+ */
+function safeGet(obj, key) {
+    try {
+        return obj[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractHttpErrorFields(error) {
+    const fields = {};
+    if (!error || typeof error !== "object") {
+        return fields;
+    }
+    const err = error;
+    const status = safeGet(err, "status") ??
+        safeGet(err, "statusCode") ??
+        safeGet(err, "status_code");
+    if (typeof status === "number") {
+        fields.status = status;
+    }
+    const headers = normalizeHeaders(safeGet(err, "headers"));
+    if (headers) {
+        fields.headers = headers;
+        const retryAfterMs = parseRetryAfterMs(headers);
+        if (retryAfterMs !== undefined) {
+            fields.retryAfterMs = retryAfterMs;
+        }
+    }
+    const requestId = extractRequestId(err, headers);
+    if (requestId !== undefined) {
+        fields.requestId = requestId;
+    }
+    return fields;
+}
+function extractRequestId(err, headers) {
+    // The OpenAI/Anthropic SDK errors carry a parsed request id directly.
+    // NOTE: providers may embed account/org identifiers in request ids (e.g.
+    // OpenAI's `req_<orghash>_<reqhash>`). These are loggable but not entirely
+    // opaque — keep that in mind when forwarding to third-party telemetry.
+    const requestID = safeGet(err, "requestID");
+    if (typeof requestID === "string") {
+        return requestID;
+    }
+    const request_id = safeGet(err, "request_id");
+    if (typeof request_id === "string") {
+        return request_id;
+    }
+    if (headers) {
+        return (headerValue(headers, "x-request-id") ?? headerValue(headers, "request-id"));
+    }
+    return undefined;
+}
+function normalizeHeaders(raw) {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const out = {};
+    // Web `Headers` (used by the OpenAI/Anthropic SDKs) is iterable via forEach.
+    // We always lowercase the stored key so downstream `headers["x-request-id"]`
+    // lookups work regardless of the provider's original casing.
+    try {
+        if (typeof raw.forEach === "function") {
+            raw.forEach((value, key) => {
+                if (isAllowedHeader(key)) {
+                    out[key.toLowerCase()] = value;
+                }
+            });
+        }
+        else {
+            // Fall back to a plain object of header key/value pairs.
+            for (const [key, value] of Object.entries(raw)) {
+                if (typeof value === "string" && isAllowedHeader(key)) {
+                    out[key.toLowerCase()] = value;
+                }
+            }
+        }
+    }
+    catch {
+        // A malformed Headers-shaped object with a throwing iterator — give up
+        // on header capture rather than poisoning the entire extraction.
+        return undefined;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Parse a retry delay (in milliseconds) from the response headers, mirroring
+ * the logic the OpenAI and Anthropic SDKs use:
+ * 1. `retry-after-ms` (non-standard, ms precision) takes precedence.
+ * 2. Otherwise `retry-after` (RFC 9110): either delta-seconds or an HTTP-date.
+ *
+ * Always returns a non-negative value capped at `MAX_RETRY_AFTER_MS`.
+ */
+function parseRetryAfterMs(headers) {
+    // `retry-after-ms` (non-standard, OpenAI-specific) is always purely numeric;
+    // try whole-value first, then first-of-list, then give up.
+    const msRaw = headerValue(headers, "retry-after-ms");
+    const ms = numericHeader(msRaw) ?? numericHeader(firstNumericToken(msRaw));
+    if (ms !== undefined) {
+        return clampRetryAfter(ms);
+    }
+    const retryAfter = headerValue(headers, "retry-after");
+    if (retryAfter !== undefined) {
+        // 1. Try the whole value as a delta-seconds number ("30", "-3600").
+        const seconds = numericHeader(retryAfter);
+        if (seconds !== undefined) {
+            return clampRetryAfter(seconds * 1000);
+        }
+        // 2. Comma-separated numeric list? Take the first token if numeric.
+        //    NOTE: HTTP-dates contain commas ("Sat, 01 Jan ..."), so we only
+        //    take the first token when it parses as a pure number — otherwise
+        //    we'd mangle a perfectly good HTTP-date into "Sat".
+        const firstNumeric = numericHeader(firstNumericToken(retryAfter));
+        if (firstNumeric !== undefined) {
+            return clampRetryAfter(firstNumeric * 1000);
+        }
+        // 3. Otherwise treat as RFC 9110 HTTP-date.
+        const dateMs = Date.parse(retryAfter) - Date.now();
+        if (!Number.isNaN(dateMs)) {
+            return clampRetryAfter(dateMs);
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the first comma-separated token of `value` only if it parses as a
+ * number. Returns undefined for non-numeric first tokens (notably HTTP-dates
+ * like `"Sat, 01 Jan 2026 ..."`) so the caller can fall back to date parsing.
+ */
+function firstNumericToken(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const first = value.split(",")[0];
+    if (first === undefined) {
+        return undefined;
+    }
+    const trimmed = first.trim();
+    if (trimmed === "" || Number.isNaN(Number(trimmed))) {
+        return undefined;
+    }
+    return trimmed;
+}
+/**
+ * Strict numeric parse — unlike `parseFloat`, this rejects values with trailing
+ * junk (`"5xyz"`, `"30abc"`) instead of silently accepting a prefix.
+ */
+function numericHeader(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    const parsed = Number(trimmed);
+    if (Number.isNaN(parsed)) {
+        return undefined;
+    }
+    return parsed;
+}
+function headerValue(headers, name) {
+    // Keys are stored lowercased by `normalizeHeaders`, so a direct lookup is
+    // sufficient. Keep a case-insensitive fallback for defense in depth in case
+    // a caller hands us a non-normalized object.
+    const lower = name.toLowerCase();
+    if (lower in headers) {
+        return headers[lower];
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower) {
+            return value;
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [