genai-lite 0.10.0 → 0.11.0

package/README.md

@@ -13,7 +13,7 @@ A lightweight, portable Node.js/TypeScript library providing a unified interface
 - ⚡ **Lightweight** - Minimal dependencies, focused functionality
 - 🛡️ **Provider Normalization** - Consistent responses across different AI APIs
 - 🧠 **Local Reasoning Toggle** - Turn thinking on/off for detected GGUF models (Qwen 3.5-class, Gemma 4, and more) with vendor-tuned sampling defaults
-- 🔁 **Built-in Reliability** - Automatic retries with backoff/`Retry-After`, per-request timeouts, and abort signals; image generation supports cancellation too (including server-side cancel for local diffusion)
+- 🔁 **Built-in Reliability** - Automatic retries with backoff/`Retry-After`, per-request timeouts, and abort signals — for both LLM and image generation (local diffusion additionally gets server-side cancel and is never blind-retried)
 - 🎨 **Configurable Model Presets** - Built-in presets with full customization options
 - 🎭 **Template Engine** - Sophisticated templating with conditionals and variable substitution
 - 📊 **Configurable Logging** - Debug mode, custom loggers (pino, winston), and silent mode for tests

package/dist/adapters/image/GenaiElectronImageAdapter.d.ts

@@ -35,6 +35,7 @@ export declare class GenaiElectronImageAdapter implements ImageProviderAdapter {
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
         signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<ImageGenerationResponse>;
     /**
      * Builds the request payload for genai-electron

package/dist/adapters/image/GenaiElectronImageAdapter.js

@@ -43,7 +43,10 @@ class GenaiElectronImageAdapter {
      * Generates images using genai-electron's async API with progress polling
      */
     async generate(config) {
-        const { request, resolvedPrompt, settings, signal } = config;
+        const { request, resolvedPrompt, settings, signal, timeoutMs } = config;
+        // Per-request override of the construction-time timeout; applies to both
+        // the POST and the poll-loop budget
+        const effectiveTimeout = timeoutMs ?? this.timeout;
         let generationId;
         try {
             if (signal?.aborted) {
@@ -58,10 +61,10 @@ class GenaiElectronImageAdapter {
                 steps: payload.steps,
             });
             // Start generation (returns immediately with ID)
-            generationId = await this.startGeneration(payload, signal);
+            generationId = await this.startGeneration(payload, signal, effectiveTimeout);
             this.logger.info(`GenaiElectron Image API: Generation started with ID: ${generationId}`);
             // Poll for completion
-            const result = await this.pollForCompletion(generationId, settings.diffusion?.onProgress, signal);
+            const result = await this.pollForCompletion(generationId, settings.diffusion?.onProgress, signal, effectiveTimeout);
             this.logger.info(`GenaiElectron Image API: Generation complete (${result.timeTaken}ms)`);
             // Convert to ImageGenerationResponse
             return this.convertToResponse(result, request);
@@ -104,7 +107,7 @@ class GenaiElectronImageAdapter {
      * so both surface as AbortError — classification comes from adapter-side
      * state (timer-fired flag vs signal.aborted), with the caller's abort winning.
      */
-    async startGeneration(payload, signal) {
+    async startGeneration(payload, signal, effectiveTimeout) {
         const url = `${this.baseURL}/v1/images/generations`;
         const controller = new AbortController();
         let timedOut = false;
@@ -120,7 +123,7 @@ class GenaiElectronImageAdapter {
         const timeoutId = setTimeout(() => {
             timedOut = true;
             controller.abort();
-        }, this.timeout);
+        }, effectiveTimeout);
         try {
             const response = await fetch(url, {
                 method: 'POST',
@@ -141,7 +144,7 @@ class GenaiElectronImageAdapter {
                     throw this.createAbortError('Image generation request was aborted before it started');
                 }
                 if (timedOut) {
-                    throw this.createTimeoutError(`Request timeout after ${this.timeout}ms (connecting to ${this.baseURL})`);
+                    throw this.createTimeoutError(`Request timeout after ${effectiveTimeout}ms (connecting to ${this.baseURL})`);
                 }
             }
             throw error;
@@ -154,7 +157,7 @@ class GenaiElectronImageAdapter {
     /**
      * Polls for generation completion with progress updates
      */
-    async pollForCompletion(generationId, onProgress, signal) {
+    async pollForCompletion(generationId, onProgress, signal, effectiveTimeout) {
         const url = `${this.baseURL}/v1/images/generations/${generationId}`;
         const startTime = Date.now();
         while (true) {
@@ -163,8 +166,8 @@ class GenaiElectronImageAdapter {
                 throw this.createAbortError(`Image generation request was aborted (ID: ${generationId})`);
             }
             // Check overall timeout
-            if (Date.now() - startTime > this.timeout) {
-                throw this.createTimeoutError(`Generation timeout after ${this.timeout}ms (ID: ${generationId})`);
+            if (Date.now() - startTime > effectiveTimeout) {
+                throw this.createTimeoutError(`Generation timeout after ${effectiveTimeout}ms (ID: ${generationId})`);
             }
             // Fetch status
             let response;
@@ -343,6 +346,17 @@ class GenaiElectronImageAdapter {
             errorCode = types_1.ADAPTER_ERROR_CODES.RATE_LIMIT_EXCEEDED;
             errorType = 'rate_limit_error';
         }
+        else if (error.code === 'NOT_FOUND') {
+            // Server JSON code from a poll GET/DELETE whose generation is gone —
+            // typically expired from the registry (default TTL 300s). Without this
+            // branch the 404 status maps to MODEL_NOT_FOUND ("model not found"),
+            // which is misleading for an expired generation.
+            errorMessage =
+                'Generation not found on the server — it likely expired from the ' +
+                    `registry before polling completed. ${error.message}`;
+            errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+            errorType = 'server_error';
+        }
         else if (error.code === 'SERVER_NOT_RUNNING') {
             errorMessage = `Image generation server is not running (connecting to ${this.baseURL})`;
             errorCode = types_1.ADAPTER_ERROR_CODES.NETWORK_ERROR;
@@ -371,6 +385,9 @@ class GenaiElectronImageAdapter {
         enhancedError.code = errorCode;
         enhancedError.type = errorType;
         enhancedError.status = mapped.status;
+        if (mapped.retryAfterMs !== undefined) {
+            enhancedError.retryAfterMs = mapped.retryAfterMs;
+        }
         enhancedError.providerId = this.id;
         enhancedError.modelId = request.modelId;
         return enhancedError;

package/dist/adapters/image/MockImageAdapter.d.ts

@@ -20,5 +20,6 @@ export declare class MockImageAdapter implements ImageProviderAdapter {
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
         signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<ImageGenerationResponse>;
 }

package/dist/adapters/image/OpenAIImageAdapter.d.ts

@@ -36,6 +36,7 @@ export declare class OpenAIImageAdapter implements ImageProviderAdapter {
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
         signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<ImageGenerationResponse>;
     /**
      * Validates prompt length for the given model

package/dist/adapters/image/OpenAIImageAdapter.js

@@ -59,7 +59,7 @@ class OpenAIImageAdapter {
      * Generates images using OpenAI's API
      */
     async generate(config) {
-        const { request, resolvedPrompt, settings, apiKey, signal } = config;
+        const { request, resolvedPrompt, settings, apiKey, signal, timeoutMs } = config;
         if (!apiKey) {
             throw new Error('OpenAI API key is required but was not provided');
         }
@@ -102,14 +102,18 @@ class OpenAIImageAdapter {
                 n: params.n,
                 isGptImageModel,
             });
-            // Make API call (per-request abort signal when provided)
-            const response = await client.images.generate(params, signal ? { signal } : undefined);
+            // Make API call (per-request abort signal and timeout override when provided)
+            const requestOptions = {
+                ...(signal && { signal }),
+                ...(timeoutMs !== undefined && { timeout: timeoutMs }),
+            };
+            const response = await client.images.generate(params, Object.keys(requestOptions).length > 0 ? requestOptions : undefined);
             if (!response.data || response.data.length === 0) {
                 throw new Error('OpenAI API returned no images in response');
             }
             this.logger.info(`OpenAI Image API call successful, generated ${response.data.length} images`);
             // Process response
-            return await this.processResponse(response, request, isGptImageModel, signal);
+            return await this.processResponse(response, request, isGptImageModel, signal, timeoutMs);
         }
         catch (error) {
             this.logger.error('OpenAI Image API error:', error);
@@ -199,7 +203,7 @@ class OpenAIImageAdapter {
     /**
      * Processes the OpenAI API response and converts to ImageGenerationResponse
      */
-    async processResponse(response, request, isGptImageModel, signal) {
+    async processResponse(response, request, isGptImageModel, signal, timeoutMs) {
         const images = [];
         for (let i = 0; i < response.data.length; i++) {
             const item = response.data[i];
@@ -222,9 +226,17 @@ class OpenAIImageAdapter {
             else {
                 // dall-e-2/dall-e-3: can be url or b64_json
                 if (item.url) {
-                    // Fetch image from URL
+                    // Fetch image from URL. The SDK timeout only covers images.generate,
+                    // so bound this fetch with the same per-request budget when one was
+                    // given (AbortSignal.timeout carries a TimeoutError reason, mapping
+                    // to REQUEST_TIMEOUT; a caller abort still maps to REQUEST_ABORTED)
                     imageUrl = item.url;
-                    const imageResponse = await fetch(item.url, signal ? { signal } : undefined);
+                    const fetchSignal = timeoutMs !== undefined
+                        ? signal
+                            ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+                            : AbortSignal.timeout(timeoutMs)
+                        : signal;
+                    const imageResponse = await fetch(item.url, fetchSignal ? { signal: fetchSignal } : undefined);
                     if (!imageResponse.ok) {
                         throw new Error(`Failed to fetch image from URL: ${imageResponse.statusText}`);
                     }
@@ -297,6 +309,9 @@ class OpenAIImageAdapter {
         enhancedError.code = mapped.errorCode;
         enhancedError.type = mapped.errorType;
         enhancedError.status = mapped.status;
+        if (mapped.retryAfterMs !== undefined) {
+            enhancedError.retryAfterMs = mapped.retryAfterMs;
+        }
         enhancedError.providerId = this.id;
         enhancedError.modelId = request.modelId;
         return enhancedError;

package/dist/image/ImageService.d.ts

@@ -17,6 +17,7 @@ export declare class ImageService {
     private requestValidator;
     private settingsResolver;
     private modelResolver;
+    private retryOptions;
     constructor(getApiKey: ApiKeyProvider, options?: ImageServiceOptions);
     /**
      * Generates images based on the request
@@ -26,6 +27,16 @@ export declare class ImageService {
      * @returns Promise resolving to response or error
      */
     generateImage(request: ImageGenerationRequest | ImageGenerationRequestWithPreset, options?: GenerateImageOptions): Promise<ImageGenerationResponse | ImageFailureResponse>;
+    /**
+     * Builds a failure envelope from a thrown error.
+     *
+     * Adapters throw errors stamped with an ADAPTER_ERROR_CODES code plus
+     * type/status/retryAfterMs — that classification is propagated. Anything else
+     * (e.g. a failing ApiKeyProvider whose error carries a foreign `.code` like
+     * ENOENT) keeps the generic fallback so unrelated codes don't leak into the
+     * API surface.
+     */
+    private buildFailureEnvelope;
     /**
      * Gets list of supported image providers
      *

package/dist/image/ImageService.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ImageService = void 0;
 const defaultLogger_1 = require("../logging/defaultLogger");
 const types_1 = require("../llm/clients/types");
+const withRetry_1 = require("../shared/services/withRetry");
 const config_1 = require("./config");
 const image_presets_json_1 = __importDefault(require("../config/image-presets.json"));
 const PresetManager_1 = require("../shared/services/PresetManager");
@@ -33,6 +34,7 @@ const ADAPTER_ERROR_CODE_VALUES = new Set(Object.values(types_1.ADAPTER_ERROR_CO
 class ImageService {
     constructor(getApiKey, options = {}) {
         this.getApiKey = getApiKey;
+        this.retryOptions = options.retry;
         // Initialize logger - custom logger takes precedence over logLevel
         this.logger = options.logger ?? (0, defaultLogger_1.createDefaultLogger)(options.logLevel);
         // Initialize helper services
@@ -136,44 +138,58 @@ class ImageService {
                         },
                     };
                 }
-                // Generate images
+                // Generate images. Only providers marked retryable in config are ever
+                // retried — genai-electron's POST-then-poll is not idempotent (a blind
+                // retry after the POST would start a second GPU generation), and custom
+                // adapters without a config entry get the safe default (no retries).
                 this.logger.info(`ImageService: Calling adapter for provider: ${providerId}`);
-                const response = await adapter.generate({
-                    request: fullRequest,
-                    resolvedPrompt,
-                    settings: resolvedSettings,
-                    apiKey,
+                const providerRetryable = (0, config_1.getImageProviderById)(providerId)?.retryable === true;
+                const retryOnTimeout = this.retryOptions?.retryOnTimeout ?? true;
+                const retryableCodes = new Set([
+                    types_1.ADAPTER_ERROR_CODES.RATE_LIMIT_EXCEEDED,
+                    types_1.ADAPTER_ERROR_CODES.NETWORK_ERROR,
+                    ...(retryOnTimeout ? [types_1.ADAPTER_ERROR_CODES.REQUEST_TIMEOUT] : []),
+                ]);
+                return await (0, withRetry_1.withRetry)(async () => {
+                    try {
+                        const response = await adapter.generate({
+                            request: fullRequest,
+                            resolvedPrompt,
+                            settings: resolvedSettings,
+                            apiKey,
+                            signal: options?.signal,
+                            timeoutMs: options?.timeoutMs,
+                        });
+                        this.logger.info('ImageService: Image generation completed successfully');
+                        return response;
+                    }
+                    catch (error) {
+                        this.logger.error('ImageService: Error during image generation:', error);
+                        return this.buildFailureEnvelope(error, providerId, modelId);
+                    }
+                }, (result) => {
+                    if (result.object !== 'error' || !providerRetryable) {
+                        return { retry: false };
+                    }
+                    const code = String(result.error.code);
+                    const status = result.error.status;
+                    const retry = retryableCodes.has(code) ||
+                        (code === types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR &&
+                            typeof status === 'number' &&
+                            (status === 408 || status === 409 || status >= 500));
+                    return { retry, retryAfterMs: result.error.retryAfterMs };
+                }, {
+                    ...this.retryOptions,
+                    ...(options?.maxRetries !== undefined && { maxRetries: options.maxRetries }),
                     signal: options?.signal,
+                    logger: this.logger,
+                    label: `${providerId}/${modelId}`,
                 });
-                this.logger.info('ImageService: Image generation completed successfully');
-                return response;
             }
             catch (error) {
+                // Errors thrown outside the adapter call (e.g. a failing ApiKeyProvider)
                 this.logger.error('ImageService: Error during image generation:', error);
-                // Adapters throw errors stamped with an ADAPTER_ERROR_CODES code plus
-                // type/status — propagate that classification. Anything else caught here
-                // (e.g. a failing ApiKeyProvider whose error carries a foreign `.code`
-                // like ENOENT) keeps the generic fallback so unrelated codes don't leak
-                // into the API surface.
-                const thrown = error;
-                const isAdapterError = typeof thrown?.code === 'string' && ADAPTER_ERROR_CODE_VALUES.has(thrown.code);
-                return {
-                    object: 'error',
-                    providerId: providerId,
-                    modelId: modelId,
-                    error: {
-                        message: error instanceof Error
-                            ? error.message
-                            : 'An unknown error occurred during image generation',
-                        code: isAdapterError ? thrown.code : 'PROVIDER_ERROR',
-                        type: isAdapterError && typeof thrown.type === 'string'
-                            ? thrown.type
-                            : 'server_error',
-                        ...(isAdapterError &&
-                            typeof thrown.status === 'number' && { status: thrown.status }),
-                        providerError: error,
-                    },
-                };
+                return this.buildFailureEnvelope(error, providerId, modelId);
             }
         }
         catch (error) {
@@ -192,6 +208,38 @@ class ImageService {
             };
         }
     }
+    /**
+     * Builds a failure envelope from a thrown error.
+     *
+     * Adapters throw errors stamped with an ADAPTER_ERROR_CODES code plus
+     * type/status/retryAfterMs — that classification is propagated. Anything else
+     * (e.g. a failing ApiKeyProvider whose error carries a foreign `.code` like
+     * ENOENT) keeps the generic fallback so unrelated codes don't leak into the
+     * API surface.
+     */
+    buildFailureEnvelope(error, providerId, modelId) {
+        const thrown = error;
+        const isAdapterError = typeof thrown?.code === 'string' && ADAPTER_ERROR_CODE_VALUES.has(thrown.code);
+        return {
+            object: 'error',
+            providerId,
+            modelId,
+            error: {
+                message: error instanceof Error
+                    ? error.message
+                    : 'An unknown error occurred during image generation',
+                code: isAdapterError ? thrown.code : 'PROVIDER_ERROR',
+                type: isAdapterError && typeof thrown.type === 'string'
+                    ? thrown.type
+                    : 'server_error',
+                ...(isAdapterError &&
+                    typeof thrown.status === 'number' && { status: thrown.status }),
+                ...(isAdapterError &&
+                    typeof thrown.retryAfterMs === 'number' && { retryAfterMs: thrown.retryAfterMs }),
+                providerError: error,
+            },
+        };
+    }
     /**
      * Gets list of supported image providers
      *

package/dist/image/config.js

@@ -22,6 +22,8 @@ exports.SUPPORTED_IMAGE_PROVIDERS = [
         id: 'openai-images',
         displayName: 'OpenAI Images',
         description: 'DALL-E and GPT-Image models from OpenAI',
+        // Single atomic POST per generation — safe to auto-retry transient failures
+        retryable: true,
         capabilities: {
             supportsMultipleImages: true,
             supportsB64Json: true,
@@ -128,6 +130,9 @@ exports.SUPPORTED_IMAGE_PROVIDERS = [
         id: 'genai-electron-images',
         displayName: 'Local Diffusion (genai-electron)',
         description: 'Local stable-diffusion models via genai-electron wrapper',
+        // POST-then-poll: a blind retry of a mid-poll failure would start a second
+        // GPU generation, so the service-level retry layer must never touch this
+        retryable: false,
         capabilities: {
             supportsMultipleImages: true,
             supportsB64Json: true,

package/dist/llm/clients/GeminiClientAdapter.js

@@ -38,14 +38,17 @@ class GeminiClientAdapter {
      * @returns Promise resolving to success or failure response
      */
     async sendMessage(request, apiKey, options) {
-        // The SDK enforces httpOptions.timeout by aborting an internal controller and
-        // wraps any fetch rejection in a plain Error (no name/status/code), so timeouts
-        // and caller aborts cannot be classified from the error object. The adapter owns
-        // the timeout instead and classifies from its own state in the catch block.
+        // The SDK enforces httpOptions.timeout by aborting the same internal controller
+        // the caller's abortSignal funnels into, so timeout and caller abort surface as
+        // identical AbortErrors and cannot be distinguished from the error object. The
+        // adapter owns the timeout instead and classifies from its own state in the
+        // catch block.
         let timedOut = false;
         let timeoutHandle;
         try {
-            // Initialize Gemini client (note: @google/genai performs no automatic retries)
+            // Initialize Gemini client. The SDK's internal retry layer is opt-in via
+            // httpOptions.retryOptions — it must stay unset here because LLMService's
+            // withRetry owns retrying (SDK retries would multiply attempts).
             const genAI = new genai_1.GoogleGenAI({ apiKey });
             // Format the request for Gemini API
             const { contents, generationConfig, safetySettings, systemInstruction } = this.formatInternalRequestToGemini(request);

package/dist/llm/clients/MistralClientAdapter.js

@@ -91,11 +91,25 @@ class MistralClientAdapter {
                 this.logger.warn(`Mistral does not support JSON schema validation. ` +
                     `Using json_object mode - schema validation will be client-side only.`);
             }
-            // Make the API call (per-request transport options: timeout + abort signal)
-            const transportOptions = {
-                ...(options?.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }),
-                ...(options?.signal && { fetchOptions: { signal: options.signal } }),
-            };
+            // Make the API call (per-request transport options: timeout + abort signal).
+            // The SDK ignores timeoutMs whenever a signal is supplied, so when both are
+            // set they must be composed into one signal. AbortSignal.timeout carries a
+            // TimeoutError reason, which the SDK maps to RequestTimeoutError (vs a
+            // caller abort's AbortError -> RequestAbortedError), so classification in
+            // errorUtils keeps working.
+            const transportOptions = {};
+            if (options?.signal && options?.timeoutMs !== undefined) {
+                transportOptions.signal = AbortSignal.any([
+                    options.signal,
+                    AbortSignal.timeout(options.timeoutMs),
+                ]);
+            }
+            else if (options?.signal) {
+                transportOptions.signal = options.signal;
+            }
+            else if (options?.timeoutMs !== undefined) {
+                transportOptions.timeoutMs = options.timeoutMs;
+            }
             const completion = Object.keys(transportOptions).length > 0
                 ? await mistral.chat.complete(requestOptions, transportOptions)
                 : await mistral.chat.complete(requestOptions);

package/dist/shared/adapters/errorUtils.d.ts

@@ -28,7 +28,8 @@ export declare function extractRetryAfterMs(error: any): number | undefined;
  *
  * This utility handles:
  * - Common HTTP status codes (401, 402, 404, 429, 4xx, 5xx)
- * - Network connection errors (ENOTFOUND, ECONNREFUSED, timeouts)
+ * - Network connection errors (ENOTFOUND, ECONNREFUSED, timeouts), including
+ *   undici's `TypeError: fetch failed` wrapper carrying the failure on `cause`
  * - Generic JavaScript errors
  *
  * Individual adapters can further refine the mappings for provider-specific cases,

package/dist/shared/adapters/errorUtils.js

@@ -50,12 +50,37 @@ function extractRetryAfterMs(error) {
     }
     return undefined;
 }
+/**
+ * Matches an error against known error-class names. The openai/anthropic SDK
+ * error classes never assign `this.name` (instances report name "Error"), so
+ * the constructor name is checked as well.
+ */
+function matchesErrorName(e, names) {
+    return !!e && (names.includes(e.name) || names.includes(e.constructor?.name));
+}
+/**
+ * Matches the error shapes produced for connection-level failures (DNS lookup,
+ * connection refused, connect timeout). Wrappers keep the real failure on
+ * `cause`, sometimes nested (undici's `TypeError: fetch failed` inside
+ * anthropic/openai `APIConnectionError`), so the cause chain is walked too.
+ */
+function isConnectionFailure(e, depth = 0) {
+    if (!e || depth > 4)
+        return false;
+    return (e.code === 'ENOTFOUND' ||
+        e.code === 'ECONNREFUSED' ||
+        e.code === 'ETIMEDOUT' ||
+        matchesErrorName(e, ['ConnectTimeoutError', 'ConnectionError', 'APIConnectionError']) ||
+        (typeof e.type === 'string' && e.type.includes('timeout')) ||
+        isConnectionFailure(e.cause, depth + 1));
+}
 /**
  * Maps common error patterns to standardized error codes and types
  *
  * This utility handles:
  * - Common HTTP status codes (401, 402, 404, 429, 4xx, 5xx)
- * - Network connection errors (ENOTFOUND, ECONNREFUSED, timeouts)
+ * - Network connection errors (ENOTFOUND, ECONNREFUSED, timeouts), including
+ *   undici's `TypeError: fetch failed` wrapper carrying the failure on `cause`
  * - Generic JavaScript errors
  *
  * Individual adapters can further refine the mappings for provider-specific cases,
@@ -72,29 +97,37 @@ function getCommonMappedErrorDetails(error, providerMessageOverride) {
     let status;
     const retryAfterMs = extractRetryAfterMs(error);
     // Handle user-initiated aborts and client-side timeouts first — the SDKs raise
-    // these as named errors (openai: APIUserAbortError/APIConnectionTimeoutError;
-    // fetch/undici: AbortError/TimeoutError DOMExceptions)
-    if (error &&
-        (error.name === 'APIUserAbortError' ||
-            error.name === 'AbortError' ||
-            (error instanceof DOMException && error.name === 'AbortError'))) {
+    // these as typed errors (openai/anthropic: APIUserAbortError/
+    // APIConnectionTimeoutError, matched by constructor name since those classes
+    // never set this.name; Speakeasy/mistral: RequestAbortedError/
+    // RequestTimeoutError; fetch/undici: AbortError/TimeoutError DOMExceptions)
+    if (matchesErrorName(error, ['APIUserAbortError', 'AbortError', 'RequestAbortedError'])) {
         return {
             errorCode: types_1.ADAPTER_ERROR_CODES.REQUEST_ABORTED,
             errorMessage: providerMessageOverride || error.message || 'Request was aborted',
             errorType: 'abort_error',
         };
     }
-    if (error &&
-        (error.name === 'APIConnectionTimeoutError' || error.name === 'TimeoutError')) {
+    if (matchesErrorName(error, [
+        'APIConnectionTimeoutError',
+        'TimeoutError',
+        'RequestTimeoutError',
+    ])) {
         return {
             errorCode: types_1.ADAPTER_ERROR_CODES.REQUEST_TIMEOUT,
             errorMessage: providerMessageOverride || error.message || 'Request timed out',
             errorType: 'timeout_error',
         };
     }
-    // Handle API errors with HTTP status codes
-    if (error && typeof error.status === 'number') {
-        const httpStatus = error.status;
+    // Handle API errors with HTTP status codes — SDKs expose the status as either
+    // `status` (openai/anthropic) or `statusCode` (Speakeasy/mistral MistralError)
+    const numericStatus = error && typeof error.status === 'number'
+        ? error.status
+        : error && typeof error.statusCode === 'number'
+            ? error.statusCode
+            : undefined;
+    if (numericStatus !== undefined) {
+        const httpStatus = numericStatus;
         status = httpStatus;
         errorMessage = providerMessageOverride || error.message || `HTTP ${httpStatus} error`;
         // Map common HTTP status codes
@@ -143,15 +176,20 @@ function getCommonMappedErrorDetails(error, providerMessageOverride) {
                 }
         }
     }
-    // Handle network connection errors
-    else if (error && (error.code === 'ENOTFOUND' ||
-        error.code === 'ECONNREFUSED' ||
-        error.code === 'ETIMEDOUT' ||
-        error.name === 'ConnectTimeoutError' ||
-        (error.type && error.type.includes('timeout')))) {
+    // Handle network connection errors — either directly (Node error shapes) or
+    // wrapped with the real failure on `cause` (undici's `TypeError: fetch failed`,
+    // anthropic/openai APIConnectionError, Speakeasy ConnectionError)
+    else if (isConnectionFailure(error)) {
         errorCode = types_1.ADAPTER_ERROR_CODES.NETWORK_ERROR;
         errorType = 'connection_error';
         errorMessage = providerMessageOverride || error.message || 'Network connection failed';
+        // Surface the underlying cause when the top-level message is generic
+        // (undici's "fetch failed", Speakeasy's ConnectionError wrapper)
+        if (typeof error?.cause?.message === 'string' &&
+            error.cause.message &&
+            !errorMessage.includes(error.cause.message)) {
+            errorMessage = `${errorMessage}: ${error.cause.message}`;
+        }
     }
     // Handle generic JavaScript errors
     else if (error instanceof Error) {

package/dist/types/image.d.ts

@@ -5,6 +5,7 @@
  * Based on the design specification in docs/devlog/2025-10-22-genai-lite-image-api-design.md
  */
 import type { Logger, LogLevel } from '../logging/types';
+import type { RetryPolicy } from '../shared/services/withRetry';
 /**
  * Image provider ID type - represents a unique identifier for an image generation provider
  */
@@ -253,6 +254,8 @@ export interface ImageFailureResponse {
         type?: string;
         /** HTTP status code reported by the provider, when available */
         status?: number;
+        /** Provider-suggested wait before retrying, in ms (from a Retry-After header) */
+        retryAfterMs?: number;
         /** Parameter that caused the error (if applicable) */
         param?: string;
         /** Original provider error (for debugging) */
@@ -309,6 +312,13 @@ export interface ImageProviderInfo {
     capabilities: ImageProviderCapabilities;
     /** Available models from this provider */
     models?: ImageModelInfo[];
+    /**
+     * Whether transient failures from this provider are safe to auto-retry.
+     * Omit/false for providers whose generate() has non-idempotent side effects
+     * (e.g. genai-electron's POST-then-poll — a blind retry after the POST would
+     * start a second GPU generation).
+     */
+    retryable?: boolean;
 }
 /**
  * Preset configuration for image generation
@@ -363,6 +373,8 @@ export interface ImageProviderAdapter {
         apiKey: string | null;
         /** Abort signal for request-side cancellation (optional) */
         signal?: AbortSignal;
+        /** Per-request timeout override in ms; adapters fall back to their construction-time default when undefined */
+        timeoutMs?: number;
     }): Promise<ImageGenerationResponse>;
     /**
      * Optional method to get available models from this provider
@@ -398,6 +410,16 @@ export interface ImageServiceOptions {
     logLevel?: LogLevel;
     /** Custom logger implementation. If provided, logLevel is ignored. */
     logger?: Logger;
+    /**
+     * Retry policy for transient failures (rate limits, 5xx, network, timeouts)
+     * from retry-safe providers only. Defaults: maxRetries 2, initialDelayMs 500,
+     * maxDelayMs 10000, backoffFactor 2, retryOnTimeout true. Set maxRetries: 0
+     * to disable. Providers marked retryable: false (e.g. genai-electron, where a
+     * blind retry would start a second GPU generation) are never retried.
+     */
+    retry?: Partial<RetryPolicy> & {
+        retryOnTimeout?: boolean;
+    };
 }
 /**
  * Per-call options for ImageService.generateImage
@@ -410,6 +432,17 @@ export interface GenerateImageOptions {
      * requests surface as REQUEST_ABORTED / abort_error failures.
      */
     signal?: AbortSignal;
+    /**
+     * Per-request timeout in ms. Overrides the adapter's construction-time
+     * default (60s OpenAI Images, 120s genai-electron). Timeouts surface as
+     * REQUEST_TIMEOUT / timeout_error failures.
+     */
+    timeoutMs?: number;
+    /**
+     * Per-request retry cap (overrides the service-level retry.maxRetries;
+     * ignored for providers marked retryable: false).
+     */
+    maxRetries?: number;
 }
 /**
  * Result from createPrompt utility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genai-lite",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,9 @@
   },
   "author": "Luigi Acerbi <luigi.acerbi@gmail.com>",
   "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/lacerbi"
@@ -43,9 +46,9 @@
     "test:e2e:reasoning": "npm run build && jest --config jest.e2e.config.js reasoning.e2e.test.ts"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.72.1",
-    "@google/genai": "^1.0.1",
-    "@mistralai/mistralai": "^1.11.0",
+    "@anthropic-ai/sdk": "^0.110.0",
+    "@google/genai": "^2.10.0",
+    "@mistralai/mistralai": "^1.15.1",
     "js-tiktoken": "^1.0.20",
     "openai": "^6.7.0"
   },