genai-lite 0.9.1 → 0.10.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; image generation supports cancellation too (including server-side cancel for local diffusion)
 - 🎨 **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,7 @@ export declare class GenaiElectronImageAdapter implements ImageProviderAdapter {
         resolvedPrompt: string;
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
+        signal?: AbortSignal;
     }): Promise<ImageGenerationResponse>;
     /**
      * Builds the request payload for genai-electron
@@ -41,12 +42,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 +68,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 +87,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:
@@ -18,6 +18,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GenaiElectronImageAdapter = void 0;
 const errorUtils_1 = require("../../shared/adapters/errorUtils");
+const types_1 = require("../../llm/clients/types");
 const defaultLogger_1 = require("../../logging/defaultLogger");
 /**
  * Adapter for genai-electron's local diffusion image generation
@@ -33,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)();
@@ -42,8 +43,12 @@ 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 } = config;
+        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`, {
@@ -53,16 +58,22 @@ class GenaiElectronImageAdapter {
                 steps: payload.steps,
             });
             // Start generation (returns immediately with ID)
-            const generationId = await this.startGeneration(payload);
+            generationId = await this.startGeneration(payload, signal);
             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);
             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);
         }
     }
@@ -88,12 +99,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) {
         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();
+        }, this.timeout);
         try {
             const response = await fetch(url, {
                 method: 'POST',
@@ -101,7 +128,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);
@@ -110,27 +136,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 ${this.timeout}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) {
         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})`);
+                throw this.createTimeoutError(`Generation timeout after ${this.timeout}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);
@@ -157,8 +203,36 @@ class GenaiElectronImageAdapter {
                 const error = state.error || { message: 'Unknown error', code: 'UNKNOWN_ERROR' };
                 throw this.createGenerationError(error.message, error.code);
             }
+            // Handle out-of-band cancellation (terminal status since genai-electron 0.6.0)
+            if (state.status === 'cancelled') {
+                const cancelError = new Error(`Image generation was cancelled on the server (ID: ${generationId})`);
+                cancelError.code = 'GENERATION_CANCELLED';
+                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);
         }
     }
     /**
@@ -198,11 +272,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
@@ -213,6 +291,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;
     }
     /**
@@ -231,22 +330,33 @@ class GenaiElectronImageAdapter {
         const mapped = (0, errorUtils_1.getCommonMappedErrorDetails)(error);
         // Enhance error message with context
         let errorMessage = mapped.errorMessage;
+        let errorCode = mapped.errorCode;
+        let errorType = mapped.errorType;
         // Special handling for genai-electron specific errors
-        if (error.code === 'SERVER_BUSY') {
+        if (error.code === 'GENERATION_CANCELLED') {
+            errorMessage = error.message;
+            errorCode = types_1.ADAPTER_ERROR_CODES.REQUEST_ABORTED;
+            errorType = 'abort_error';
+        }
+        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 === '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') {
@@ -258,18 +368,32 @@ class GenaiElectronImageAdapter {
         }
         // Create enhanced error with all details
         const enhancedError = new Error(errorMessage);
-        enhancedError.code = mapped.errorCode;
-        enhancedError.type = mapped.errorType;
+        enhancedError.code = errorCode;
+        enhancedError.type = errorType;
         enhancedError.status = mapped.status;
         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,6 @@ export declare class MockImageAdapter implements ImageProviderAdapter {
         resolvedPrompt: string;
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
+        signal?: AbortSignal;
     }): 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,7 @@ export declare class OpenAIImageAdapter implements ImageProviderAdapter {
         resolvedPrompt: string;
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
+        signal?: AbortSignal;
     }): 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 } = config;
         if (!apiKey) {
             throw new Error('OpenAI API key is required but was not provided');
         }
@@ -102,14 +102,14 @@ class OpenAIImageAdapter {
                 n: params.n,
                 isGptImageModel,
             });
-            // Make API call
-            const response = await client.images.generate(params);
+            // Make API call (per-request abort signal when provided)
+            const response = await client.images.generate(params, signal ? { signal } : 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);
         }
         catch (error) {
             this.logger.error('OpenAI Image API error:', error);
@@ -199,7 +199,7 @@ class OpenAIImageAdapter {
     /**
      * Processes the OpenAI API response and converts to ImageGenerationResponse
      */
-    async processResponse(response, request, isGptImageModel) {
+    async processResponse(response, request, isGptImageModel, signal) {
         const images = [];
         for (let i = 0; i < response.data.length; i++) {
             const item = response.data[i];
@@ -224,7 +224,7 @@ class OpenAIImageAdapter {
                 if (item.url) {
                     // Fetch image from URL
                     imageUrl = item.url;
-                    const imageResponse = await fetch(item.url);
+                    const imageResponse = await fetch(item.url, signal ? { signal } : undefined);
                     if (!imageResponse.ok) {
                         throw new Error(`Failed to fetch image from URL: ${imageResponse.statusText}`);
                     }

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
  */
@@ -22,9 +22,10 @@ export declare 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
      */
-    generateImage(request: ImageGenerationRequest | ImageGenerationRequestWithPreset): Promise<ImageGenerationResponse | ImageFailureResponse>;
+    generateImage(request: ImageGenerationRequest | ImageGenerationRequestWithPreset, options?: GenerateImageOptions): Promise<ImageGenerationResponse | ImageFailureResponse>;
     /**
      * Gets list of supported image providers
      *

package/dist/image/ImageService.js

@@ -11,6 +11,7 @@ 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 config_1 = require("./config");
 const image_presets_json_1 = __importDefault(require("../config/image-presets.json"));
 const PresetManager_1 = require("../shared/services/PresetManager");
@@ -23,6 +24,9 @@ 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
  */
@@ -69,9 +73,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 +109,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)) {
@@ -125,12 +143,20 @@ class ImageService {
                     resolvedPrompt,
                     settings: resolvedSettings,
                     apiKey,
+                    signal: options?.signal,
                 });
                 this.logger.info('ImageService: Image generation completed successfully');
                 return response;
             }
             catch (error) {
                 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,
@@ -139,8 +165,12 @@ class ImageService {
                         message: error instanceof Error
                             ? error.message
                             : 'An unknown error occurred during image generation',
-                        code: 'PROVIDER_ERROR',
-                        type: 'server_error',
+                        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,
                     },
                 };

package/dist/image/config.js

@@ -174,7 +174,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.d.ts

@@ -75,6 +75,7 @@ export declare class GeminiClientAdapter implements ILLMClientAdapter {
      *
      * @param error - The error from Gemini API
      * @param request - Original request for context
+     * @param context - Adapter-side transport state captured at catch time
      * @returns Standardized LLM failure response
      */
     private createErrorResponse;

package/dist/llm/clients/GeminiClientAdapter.js

@@ -38,6 +38,12 @@ 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.
+        let timedOut = false;
+        let timeoutHandle;
         try {
             // Initialize Gemini client (note: @google/genai performs no automatic retries)
             const genAI = new genai_1.GoogleGenAI({ apiKey });
@@ -52,6 +58,26 @@ class GeminiClientAdapter {
                 contentsLength: contents.length,
                 safetySettingsCount: safetySettings?.length || 0,
             });
+            let abortSignal = options?.signal;
+            if (options?.timeoutMs !== undefined) {
+                const controller = new AbortController();
+                if (options.signal) {
+                    if (options.signal.aborted) {
+                        controller.abort();
+                    }
+                    else {
+                        options.signal.addEventListener("abort", () => controller.abort(), {
+                            once: true,
+                        });
+                    }
+                }
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort();
+                }, options.timeoutMs);
+                timeoutHandle.unref?.();
+                abortSignal = controller.signal;
+            }
             // Generate content using the modern API
             const result = await genAI.models.generateContent({
                 model: request.modelId,
@@ -60,9 +86,11 @@ class GeminiClientAdapter {
                     ...generationConfig,
                     safetySettings: safetySettings,
                     ...(systemInstruction && { systemInstruction: systemInstruction }),
-                    ...(options?.signal && { abortSignal: options.signal }),
+                    ...(abortSignal && { abortSignal }),
+                    // Keep the SDK's server-side timeout hint (X-Server-Timeout header),
+                    // padded so the adapter's local timer always fires first
                     ...(options?.timeoutMs !== undefined && {
-                        httpOptions: { timeout: options.timeoutMs },
+                        httpOptions: { timeout: options.timeoutMs + 1000 },
                     }),
                 },
             });
@@ -72,7 +100,15 @@ class GeminiClientAdapter {
         }
         catch (error) {
             this.logger.error("Gemini API error:", error);
-            return this.createErrorResponse(error, request);
+            return this.createErrorResponse(error, request, {
+                timedOut,
+                aborted: options?.signal?.aborted === true,
+            });
+        }
+        finally {
+            if (timeoutHandle !== undefined) {
+                clearTimeout(timeoutHandle);
+            }
         }
     }
     /**
@@ -312,9 +348,38 @@ class GeminiClientAdapter {
      *
      * @param error - The error from Gemini API
      * @param request - Original request for context
+     * @param context - Adapter-side transport state captured at catch time
      * @returns Standardized LLM failure response
      */
-    createErrorResponse(error, request) {
+    createErrorResponse(error, request, context) {
+        // Classify adapter-owned aborts/timeouts first — the SDK surfaces both as
+        // plain Errors the common mapping cannot recognize (see sendMessage)
+        if (context?.aborted) {
+            return {
+                provider: request.providerId,
+                model: request.modelId,
+                error: {
+                    message: "Request was aborted",
+                    code: types_1.ADAPTER_ERROR_CODES.REQUEST_ABORTED,
+                    type: "abort_error",
+                    providerError: error,
+                },
+                object: "error",
+            };
+        }
+        if (context?.timedOut) {
+            return {
+                provider: request.providerId,
+                model: request.modelId,
+                error: {
+                    message: "Request timed out",
+                    code: types_1.ADAPTER_ERROR_CODES.REQUEST_TIMEOUT,
+                    type: "timeout_error",
+                    providerError: error,
+                },
+                object: "error",
+            };
+        }
         // Use shared error mapping utility for common error patterns
         const initialProviderMessage = error?.message;
         let { errorCode, errorMessage, errorType, status, retryAfterMs } = (0, errorUtils_1.getCommonMappedErrorDetails)(error, initialProviderMessage);

package/dist/types/image.d.ts

@@ -251,6 +251,8 @@ 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;
         /** Parameter that caused the error (if applicable) */
         param?: string;
         /** Original provider error (for debugging) */
@@ -359,6 +361,8 @@ export interface ImageProviderAdapter {
         resolvedPrompt: string;
         settings: ResolvedImageGenerationSettings;
         apiKey: string | null;
+        /** Abort signal for request-side cancellation (optional) */
+        signal?: AbortSignal;
     }): Promise<ImageGenerationResponse>;
     /**
      * Optional method to get available models from this provider
@@ -395,6 +399,18 @@ export interface ImageServiceOptions {
     /** Custom logger implementation. If provided, logLevel is ignored. */
     logger?: Logger;
 }
+/**
+ * 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;
+}
 /**
  * Result from createPrompt utility
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genai-lite",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -43,7 +43,7 @@
     "test:e2e:reasoning": "npm run build && jest --config jest.e2e.config.js reasoning.e2e.test.ts"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.2",
+    "@anthropic-ai/sdk": "^0.72.1",
     "@google/genai": "^1.0.1",
     "@mistralai/mistralai": "^1.11.0",
     "js-tiktoken": "^1.0.20",