genai-lite 0.9.2 → 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
+- 🔁 **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

@@ -5,7 +5,7 @@
  * Supports stable-diffusion.cpp through HTTP wrapper with async polling for progress.
  *
  * Provider ID: 'genai-electron-images'
- * Default endpoint: http://localhost:8081
+ * Default endpoint: http://127.0.0.1:8081
  * Configure via: GENAI_ELECTRON_IMAGE_BASE_URL environment variable
  *
  * This adapter uses genai-electron's async image generation API which:
@@ -34,6 +34,8 @@ export declare class GenaiElectronImageAdapter implements ImageProviderAdapter {
         resolvedPrompt: string;
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
+        signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<ImageGenerationResponse>;
     /**
      * Builds the request payload for genai-electron
@@ -41,12 +43,24 @@ export declare class GenaiElectronImageAdapter implements ImageProviderAdapter {
     private buildRequestPayload;
     /**
      * Starts generation and returns the generation ID
+     *
+     * The adapter's timeout and the caller's abort signal share one controller,
+     * so both surface as AbortError — classification comes from adapter-side
+     * state (timer-fired flag vs signal.aborted), with the caller's abort winning.
      */
     private startGeneration;
     /**
      * Polls for generation completion with progress updates
      */
     private pollForCompletion;
+    /**
+     * Best-effort cancellation of a server-side generation
+     * (DELETE /v1/images/generations/:id, available since genai-electron 0.6.0).
+     *
+     * All failures are swallowed: 404/409 just mean there is nothing left to
+     * cancel, and cleanup must never mask the caller's primary error.
+     */
+    private cancelGeneration;
     /**
      * Converts genai-electron result to ImageGenerationResponse
      */
@@ -55,6 +69,16 @@ export declare class GenaiElectronImageAdapter implements ImageProviderAdapter {
      * Creates an HTTP error with context
      */
     private createHttpError;
+    /**
+     * Creates a timeout-typed error: name 'TimeoutError' is recognized by the
+     * shared error mapping and classified as REQUEST_TIMEOUT / timeout_error
+     */
+    private createTimeoutError;
+    /**
+     * Creates an abort-typed error: name 'AbortError' is recognized by the
+     * shared error mapping and classified as REQUEST_ABORTED / abort_error
+     */
+    private createAbortError;
     /**
      * Creates a generation error from genai-electron error codes
      */
@@ -64,7 +88,7 @@ export declare class GenaiElectronImageAdapter implements ImageProviderAdapter {
      */
     private handleError;
     /**
-     * Sleep helper for polling
+     * Sleep helper for polling; rejects immediately when the signal aborts
      */
     private sleep;
 }

package/dist/adapters/image/GenaiElectronImageAdapter.js

@@ -6,7 +6,7 @@
  * Supports stable-diffusion.cpp through HTTP wrapper with async polling for progress.
  *
  * Provider ID: 'genai-electron-images'
- * Default endpoint: http://localhost:8081
+ * Default endpoint: http://127.0.0.1:8081
  * Configure via: GENAI_ELECTRON_IMAGE_BASE_URL environment variable
  *
  * This adapter uses genai-electron's async image generation API which:
@@ -34,7 +34,7 @@ class GenaiElectronImageAdapter {
             supportsNegativePrompt: true, // full diffusion support
             defaultModelId: 'sdxl',
         };
-        this.baseURL = config?.baseURL || 'http://localhost:8081';
+        this.baseURL = config?.baseURL || 'http://127.0.0.1:8081';
         this.timeout = config?.timeout || 120000; // 120 seconds for diffusion
         this.pollInterval = 500; // Poll every 500ms
         this.logger = config?.logger ?? (0, defaultLogger_1.createDefaultLogger)();
@@ -43,8 +43,15 @@ class GenaiElectronImageAdapter {
      * Generates images using genai-electron's async API with progress polling
      */
     async generate(config) {
-        const { request, resolvedPrompt, settings } = 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) {
+                throw this.createAbortError('Image generation request was aborted before it started');
+            }
             // Build request payload
             const payload = this.buildRequestPayload(resolvedPrompt, request, settings);
             this.logger.debug(`GenaiElectron Image API: Starting generation`, {
@@ -54,16 +61,22 @@ class GenaiElectronImageAdapter {
                 steps: payload.steps,
             });
             // Start generation (returns immediately with ID)
-            const generationId = await this.startGeneration(payload);
+            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);
+            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);
         }
         catch (error) {
             this.logger.error('GenaiElectron Image API error:', error);
+            // Best-effort server-side cancellation when a started generation is being
+            // abandoned (caller abort, or client-side poll timeout — cancel frees the
+            // GPU; the DELETE is cleanup, not a reclassification)
+            if (generationId && (signal?.aborted || error?.name === 'TimeoutError')) {
+                await this.cancelGeneration(generationId);
+            }
             throw this.handleError(error, request);
         }
     }
@@ -89,12 +102,28 @@ class GenaiElectronImageAdapter {
     }
     /**
      * Starts generation and returns the generation ID
+     *
+     * The adapter's timeout and the caller's abort signal share one controller,
+     * 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) {
+    async startGeneration(payload, signal, effectiveTimeout) {
         const url = `${this.baseURL}/v1/images/generations`;
-        // Create abort controller for timeout
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let timedOut = false;
+        const abortFromCaller = () => controller.abort();
+        if (signal) {
+            if (signal.aborted) {
+                controller.abort();
+            }
+            else {
+                signal.addEventListener('abort', abortFromCaller, { once: true });
+            }
+        }
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, effectiveTimeout);
         try {
             const response = await fetch(url, {
                 method: 'POST',
@@ -102,7 +131,6 @@ class GenaiElectronImageAdapter {
                 body: JSON.stringify(payload),
                 signal: controller.signal,
             });
-            clearTimeout(timeoutId);
             if (!response.ok) {
                 const errorText = await response.text();
                 throw this.createHttpError(response.status, errorText, url);
@@ -111,27 +139,47 @@ class GenaiElectronImageAdapter {
             return data.id;
         }
         catch (error) {
-            clearTimeout(timeoutId);
-            // Handle AbortError
             if (error.name === 'AbortError') {
-                throw new Error(`Request timeout after ${this.timeout}ms (connecting to ${this.baseURL})`);
+                if (signal?.aborted) {
+                    throw this.createAbortError('Image generation request was aborted before it started');
+                }
+                if (timedOut) {
+                    throw this.createTimeoutError(`Request timeout after ${effectiveTimeout}ms (connecting to ${this.baseURL})`);
+                }
             }
             throw error;
         }
+        finally {
+            clearTimeout(timeoutId);
+            signal?.removeEventListener('abort', abortFromCaller);
+        }
     }
     /**
      * Polls for generation completion with progress updates
      */
-    async pollForCompletion(generationId, onProgress) {
+    async pollForCompletion(generationId, onProgress, signal, effectiveTimeout) {
         const url = `${this.baseURL}/v1/images/generations/${generationId}`;
         const startTime = Date.now();
         while (true) {
+            // Check caller abort (before timeout — user intent wins)
+            if (signal?.aborted) {
+                throw this.createAbortError(`Image generation request was aborted (ID: ${generationId})`);
+            }
             // Check overall timeout
-            if (Date.now() - startTime > this.timeout) {
-                throw new Error(`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
-            const response = await fetch(url);
+            let response;
+            try {
+                response = await fetch(url, signal ? { signal } : undefined);
+            }
+            catch (error) {
+                if (error.name === 'AbortError' && signal?.aborted) {
+                    throw this.createAbortError(`Image generation request was aborted (ID: ${generationId})`);
+                }
+                throw error;
+            }
             if (!response.ok) {
                 const errorText = await response.text();
                 throw this.createHttpError(response.status, errorText, url);
@@ -165,7 +213,29 @@ class GenaiElectronImageAdapter {
                 throw cancelError;
             }
             // Wait before next poll
-            await this.sleep(this.pollInterval);
+            await this.sleep(this.pollInterval, signal);
+        }
+    }
+    /**
+     * Best-effort cancellation of a server-side generation
+     * (DELETE /v1/images/generations/:id, available since genai-electron 0.6.0).
+     *
+     * All failures are swallowed: 404/409 just mean there is nothing left to
+     * cancel, and cleanup must never mask the caller's primary error.
+     */
+    async cancelGeneration(generationId) {
+        const url = `${this.baseURL}/v1/images/generations/${generationId}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 5000);
+        try {
+            await fetch(url, { method: 'DELETE', signal: controller.signal });
+            this.logger.debug(`GenaiElectron Image API: Requested cancellation of generation ${generationId}`);
+        }
+        catch (error) {
+            this.logger.debug(`GenaiElectron Image API: Best-effort cancellation failed for ${generationId}:`, error);
+        }
+        finally {
+            clearTimeout(timeoutId);
         }
     }
     /**
@@ -205,11 +275,15 @@ class GenaiElectronImageAdapter {
      */
     createHttpError(status, errorText, url) {
         let errorMessage = `HTTP ${status} error`;
+        let serverCode;
         try {
             const errorData = JSON.parse(errorText);
             if (errorData.error?.message) {
                 errorMessage = errorData.error.message;
             }
+            if (typeof errorData.error?.code === 'string') {
+                serverCode = errorData.error.code;
+            }
         }
         catch {
             // Not JSON, use raw text
@@ -220,6 +294,27 @@ class GenaiElectronImageAdapter {
         const error = new Error(`${errorMessage} (${url})`);
         error.status = status;
         error.url = url;
+        if (serverCode) {
+            error.code = serverCode;
+        }
+        return error;
+    }
+    /**
+     * Creates a timeout-typed error: name 'TimeoutError' is recognized by the
+     * shared error mapping and classified as REQUEST_TIMEOUT / timeout_error
+     */
+    createTimeoutError(message) {
+        const error = new Error(message);
+        error.name = 'TimeoutError';
+        return error;
+    }
+    /**
+     * Creates an abort-typed error: name 'AbortError' is recognized by the
+     * shared error mapping and classified as REQUEST_ABORTED / abort_error
+     */
+    createAbortError(message) {
+        const error = new Error(message);
+        error.name = 'AbortError';
         return error;
     }
     /**
@@ -248,19 +343,34 @@ class GenaiElectronImageAdapter {
         }
         else if (error.code === 'SERVER_BUSY') {
             errorMessage = 'Image generation server is busy. Wait for current generation to complete.';
-            error.type = 'rate_limit_error';
+            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})`;
-            error.type = 'connection_error';
+            errorCode = types_1.ADAPTER_ERROR_CODES.NETWORK_ERROR;
+            errorType = 'connection_error';
         }
         else if (error.code === 'BACKEND_ERROR') {
             errorMessage = `Diffusion backend error: ${error.message}`;
-            error.type = 'server_error';
+            errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+            errorType = 'server_error';
         }
         else if (error.code === 'IO_ERROR') {
             errorMessage = `Image I/O error: ${error.message}`;
-            error.type = 'server_error';
+            errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+            errorType = 'server_error';
         }
         // Add baseURL context for network errors
         if (mapped.errorCode === 'NETWORK_ERROR') {
@@ -275,15 +385,32 @@ 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;
     }
     /**
-     * Sleep helper for polling
+     * Sleep helper for polling; rejects immediately when the signal aborts
      */
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    sleep(ms, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(this.createAbortError('Image generation request was aborted'));
+                return;
+            }
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(this.createAbortError('Image generation request was aborted'));
+            };
+            const timer = setTimeout(() => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            }, ms);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
     }
 }
 exports.GenaiElectronImageAdapter = GenaiElectronImageAdapter;

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

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

package/dist/adapters/image/MockImageAdapter.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MockImageAdapter = void 0;
+const types_1 = require("../../llm/clients/types");
 /**
  * Mock adapter for testing image generation
  */
@@ -26,7 +27,13 @@ class MockImageAdapter {
      * Generates mock images
      */
     async generate(config) {
-        const { request, resolvedPrompt } = config;
+        const { request, resolvedPrompt, signal } = config;
+        if (signal?.aborted) {
+            const error = new Error('Image generation request was aborted');
+            error.code = types_1.ADAPTER_ERROR_CODES.REQUEST_ABORTED;
+            error.type = 'abort_error';
+            throw error;
+        }
         const count = request.count || 1;
         // Create mock image data (1x1 PNG)
         const mockImageBuffer = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');

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

@@ -35,6 +35,8 @@ export declare class OpenAIImageAdapter implements ImageProviderAdapter {
         resolvedPrompt: string;
         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 } = 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
-            const response = await client.images.generate(params);
+            // 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);
+            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) {
+    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);
+                    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

@@ -5,7 +5,7 @@
  * manages presets, validates requests, and handles settings resolution.
  */
 import type { ApiKeyProvider } from '../types';
-import type { ImageGenerationRequest, ImageGenerationRequestWithPreset, ImageGenerationResponse, ImageFailureResponse, ImageProviderInfo, ImageModelInfo, ImageProviderId, ImagePreset, ImageServiceOptions } from '../types/image';
+import type { ImageGenerationRequest, ImageGenerationRequestWithPreset, ImageGenerationResponse, ImageFailureResponse, ImageProviderInfo, ImageModelInfo, ImageProviderId, ImagePreset, ImageServiceOptions, GenerateImageOptions } from '../types/image';
 /**
  * Main service for image generation operations
  */
@@ -17,14 +17,26 @@ export declare class ImageService {
     private requestValidator;
     private settingsResolver;
     private modelResolver;
+    private retryOptions;
     constructor(getApiKey: ApiKeyProvider, options?: ImageServiceOptions);
     /**
      * Generates images based on the request
      *
      * @param request - Image generation request
+     * @param options - Per-call options (e.g. an AbortSignal for cancellation)
      * @returns Promise resolving to response or error
      */
-    generateImage(request: ImageGenerationRequest | ImageGenerationRequestWithPreset): Promise<ImageGenerationResponse | ImageFailureResponse>;
+    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

@@ -11,6 +11,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 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");
@@ -23,12 +25,16 @@ const ImageSettingsResolver_1 = require("./services/ImageSettingsResolver");
 const ImageModelResolver_1 = require("./services/ImageModelResolver");
 // Type assertion for the imported JSON
 const defaultImagePresets = image_presets_json_1.default;
+// Error codes adapters stamp on the errors they throw; used to decide whether a
+// caught error's classification is safe to surface on the failure envelope
+const ADAPTER_ERROR_CODE_VALUES = new Set(Object.values(types_1.ADAPTER_ERROR_CODES));
 /**
  * Main service for image generation operations
  */
 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
@@ -69,9 +75,10 @@ class ImageService {
      * Generates images based on the request
      *
      * @param request - Image generation request
+     * @param options - Per-call options (e.g. an AbortSignal for cancellation)
      * @returns Promise resolving to response or error
      */
-    async generateImage(request) {
+    async generateImage(request, options) {
         this.logger.info('ImageService.generateImage called');
         try {
             // Resolve model information
@@ -104,6 +111,19 @@ class ImageService {
             const adapter = this.adapterRegistry.getAdapter(providerId);
             // Get API key
             try {
+                // Short-circuit if the caller already aborted — don't touch the adapter
+                if (options?.signal?.aborted) {
+                    return {
+                        object: 'error',
+                        providerId: providerId,
+                        modelId: modelId,
+                        error: {
+                            message: 'Image generation request was aborted',
+                            code: types_1.ADAPTER_ERROR_CODES.REQUEST_ABORTED,
+                            type: 'abort_error',
+                        },
+                    };
+                }
                 const apiKey = await this.getApiKey(providerId);
                 // Validate API key if adapter supports it
                 if (apiKey && adapter.validateApiKey && !adapter.validateApiKey(apiKey)) {
@@ -118,32 +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);
-                return {
-                    object: 'error',
-                    providerId: providerId,
-                    modelId: modelId,
-                    error: {
-                        message: error instanceof Error
-                            ? error.message
-                            : 'An unknown error occurred during image generation',
-                        code: 'PROVIDER_ERROR',
-                        type: 'server_error',
-                        providerError: error,
-                    },
-                };
+                return this.buildFailureEnvelope(error, providerId, modelId);
             }
         }
         catch (error) {
@@ -162,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,
@@ -174,7 +179,9 @@ exports.IMAGE_ADAPTER_CONFIGS = {
         timeout: 60000, // 60 seconds for image generation
     },
     'genai-electron-images': {
-        baseURL: process.env.GENAI_ELECTRON_IMAGE_BASE_URL || 'http://localhost:8081',
+        // 127.0.0.1 (not localhost) avoids a ~2s/request IPv6-fallback stall on
+        // Windows — especially costly for the 500ms polling loop
+        baseURL: process.env.GENAI_ELECTRON_IMAGE_BASE_URL || 'http://127.0.0.1:8081',
         timeout: 120000, // 120 seconds for local diffusion
         checkHealth: false, // Optional health checks
     },

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export type { OpenRouterClientConfig } from "./llm/clients/OpenRouterClientAdapt
 export { MistralClientAdapter } from "./llm/clients/MistralClientAdapter";
 export type { MistralClientConfig } from "./llm/clients/MistralClientAdapter";
 export { ImageService } from "./image/ImageService";
-export type { ImageProviderId, ImageMimeType, ImageResponseFormat, ImageQuality, ImageStyle, DiffusionSampler, ImageProgressStage, ImageProgressCallback, DiffusionSettings, OpenAISpecificSettings, ImageGenerationSettings, ResolvedImageGenerationSettings, ImageUsage, GeneratedImage, ImageGenerationRequestBase, ImageGenerationRequest, ImageGenerationRequestWithPreset, ImageGenerationResponse, ImageFailureResponse, ImageProviderCapabilities, ImageModelInfo, ImageProviderInfo, ImagePreset, ImageProviderAdapterConfig, ImageProviderAdapter, ImageServiceOptions, CreatePromptResult, } from "./types/image";
+export type { ImageProviderId, ImageMimeType, ImageResponseFormat, ImageQuality, ImageStyle, DiffusionSampler, ImageProgressStage, ImageProgressCallback, DiffusionSettings, OpenAISpecificSettings, ImageGenerationSettings, ResolvedImageGenerationSettings, ImageUsage, GeneratedImage, ImageGenerationRequestBase, ImageGenerationRequest, ImageGenerationRequestWithPreset, ImageGenerationResponse, ImageFailureResponse, ImageProviderCapabilities, ImageModelInfo, ImageProviderInfo, ImagePreset, ImageProviderAdapterConfig, ImageProviderAdapter, ImageServiceOptions, GenerateImageOptions, CreatePromptResult, } from "./types/image";
 export { renderTemplate } from "./prompting/template";
 export { countTokens, getSmartPreview, extractRandomVariables } from "./prompting/content";
 export { parseStructuredContent, parseRoleTags, extractInitialTaggedContent, extractMarkerDelimitedContent, parseTemplateWithMetadata } from "./prompting/parser";

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
  */
@@ -251,6 +252,10 @@ export interface ImageFailureResponse {
         code?: string | number;
         /** Error type (authentication_error, rate_limit_error, etc.) */
         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) */
@@ -307,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
@@ -359,6 +371,10 @@ export interface ImageProviderAdapter {
         resolvedPrompt: string;
         settings: ResolvedImageGenerationSettings;
         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
@@ -394,6 +410,39 @@ 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
+ */
+export interface GenerateImageOptions {
+    /**
+     * Abort signal to cancel the request (client-side — the provider may still
+     * process an already-dispatched request; for local diffusion the adapter
+     * additionally issues a best-effort server-side cancellation). Aborted
+     * 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.9.2",
+  "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.71.2",
-    "@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"
   },