@smythos/sre 1.7.41 → 1.8.0

package/src/subsystems/AgentManager/AgentData.service/connectors/SQLiteAgentDataConnector.class.ts

@@ -0,0 +1,190 @@
+import fs from 'fs';
+import path from 'path';
+import { DatabaseSync } from 'node:sqlite';
+import { AgentDataConnector } from '../AgentDataConnector';
+import { JSONContentHelper } from '@sre/helpers/JsonContent.helper';
+import { Logger } from '@sre/helpers/Log.helper';
+
+const console = Logger('SQLiteAgentDataConnector');
+
+export type SQLiteAgentDataSettings = {
+    databasePath: string;
+    tableName?: string;
+};
+
+type SQLiteRunResult = { changes?: number; lastInsertRowid?: number | bigint };
+
+export interface SQLiteStatementAdapter<T = any> {
+    all(...params: any[]): T[];
+    get(...params: any[]): T | undefined;
+    run(...params: any[]): SQLiteRunResult;
+}
+
+export interface SQLiteDatabaseAdapter {
+    prepare<T = any>(sql: string): SQLiteStatementAdapter<T>;
+    exec(sql: string): void;
+    close(): void;
+}
+
+export type SQLiteAdapterFactory = (databasePath: string) => SQLiteDatabaseAdapter;
+
+class NativeSQLiteAdapter implements SQLiteDatabaseAdapter {
+    private db: DatabaseSync;
+
+    constructor(databasePath: string) {
+        this.db = new DatabaseSync(databasePath);
+    }
+
+    public prepare<T = any>(sql: string) {
+        return this.db.prepare(sql) as unknown as SQLiteStatementAdapter<T>;
+    }
+
+    public exec(sql: string) {
+        this.db.exec(sql);
+    }
+
+    public close() {
+        this.db.close();
+    }
+}
+
+type AgentRow = {
+    id: number;
+    data: any;
+    aiAgentId: string;
+};
+
+export class SQLiteAgentDataConnector extends AgentDataConnector {
+    public name = 'SQLiteAgentDataConnector';
+    private adapter!: SQLiteDatabaseAdapter;
+    private readonly tableName: string;
+
+    constructor(protected _settings: SQLiteAgentDataSettings) {
+        super(_settings);
+        this.tableName = this.validateTableName(_settings?.tableName || 'AiAgentData');
+    }
+
+    public getAgentConfig(agentId: string): Partial<SQLiteAgentDataSettings> {
+        return {
+            databasePath: this._settings?.databasePath,
+            tableName: this.tableName,
+        };
+    }
+
+    public async start() {
+        super.start();
+        this.started = false;
+
+        if (!this._settings?.databasePath) {
+            throw new Error('SQLiteAgentDataConnector requires a databasePath setting');
+        }
+
+        this.ensureDatabaseDirectory(this._settings.databasePath);
+        this.adapter = new NativeSQLiteAdapter(this._settings.databasePath);
+        this.ensureSchema();
+
+        this.started = true;
+    }
+
+    public async stop() {
+        try {
+            this.adapter?.close();
+        } catch (error: any) {
+            console.warn('Error closing SQLite adapter', error?.message || error);
+        }
+        await super.stop();
+    }
+
+    public async getAgentData(agentId: string, version?: string) {
+        const ready = await this.ready();
+        if (!ready) {
+            throw new Error('Connector not ready');
+        }
+        const row = this.prepareStatement<AgentRow>(`SELECT id, data, aiAgentId FROM "${this.tableName}" WHERE aiAgentId = ? LIMIT 1`).get(agentId);
+
+        if (!row) {
+            throw new Error(`Agent with id ${agentId} not found`);
+        }
+
+        const parsed = this.parseData(row.data);
+        return {
+            data: parsed,
+            version: version || parsed?.version || '1.0',
+        };
+    }
+
+    public async getAgentIdByDomain(domain: string): Promise<string> {
+        return Promise.resolve('');
+    }
+
+    public async getAgentSettings(agentId: string, version?: string) {
+        const ready = await this.ready();
+        if (!ready) {
+            throw new Error('Connector not ready');
+        }
+        const agent = await this.getAgentData(agentId, version);
+        return agent?.data?.settings || {};
+    }
+
+    public async getAgentEmbodiments(agentId: string): Promise<any> {
+        const ready = await this.ready();
+        if (!ready) {
+            throw new Error('Connector not ready');
+        }
+        return [];
+    }
+
+    public async listTeamAgents(teamId: string, deployedOnly?: boolean, includeData?: boolean): Promise<any[]> {
+        const ready = await this.ready();
+        if (!ready) {
+            throw new Error('Connector not ready');
+        }
+        console.warn(`listTeamAgents is not implemented for SQLiteAgentDataConnector`);
+        return [];
+    }
+
+    public async isDeployed(agentId: string): Promise<boolean> {
+        const ready = await this.ready();
+        if (!ready) {
+            throw new Error('Connector not ready');
+        }
+        const record = await this.getAgentData(agentId).catch(() => null);
+        return !!record;
+    }
+
+    private ensureDatabaseDirectory(databasePath: string) {
+        if (databasePath === ':memory:') return;
+        const dbDir = path.dirname(path.resolve(databasePath));
+        if (!fs.existsSync(dbDir)) {
+            fs.mkdirSync(dbDir, { recursive: true });
+        }
+    }
+
+    private ensureSchema() {
+        const ddl = `
+            CREATE TABLE IF NOT EXISTS "${this.tableName}" (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                data TEXT CHECK (json_valid(data)),
+                aiAgentId TEXT NOT NULL UNIQUE
+            );
+        `;
+        this.adapter.exec(ddl);
+    }
+
+    private validateTableName(tableName: string) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+            throw new Error(`Invalid SQLite table name: ${tableName}`);
+        }
+        return tableName;
+    }
+
+    private prepareStatement<T = any>(sql: string) {
+        return this.adapter.prepare<T>(sql);
+    }
+
+    private parseData(data: any) {
+        if (Buffer.isBuffer(data)) data = data.toString('utf-8');
+        if (typeof data === 'string') return JSONContentHelper.create(data).tryParse();
+        return data;
+    }
+}

package/src/subsystems/AgentManager/AgentData.service/index.ts

@@ -6,12 +6,14 @@ import { CLIAgentDataConnector } from './connectors/CLIAgentDataConnector.class'
 import { AgentDataConnector } from './AgentDataConnector';
 import { LocalAgentDataConnector } from './connectors/LocalAgentDataConnector.class';
 import { NullAgentData } from './connectors/NullAgentData.class';
+import { SQLiteAgentDataConnector } from './connectors/SQLiteAgentDataConnector.class';
 export class AgentDataService extends ConnectorServiceProvider {
     public register() {
         //FIXME : register an actual account connector, not the abstract one
         ConnectorService.register(TConnectorService.AgentData, 'AgentData', AgentDataConnector);
         ConnectorService.register(TConnectorService.AgentData, 'CLI', CLIAgentDataConnector);
         ConnectorService.register(TConnectorService.AgentData, 'Local', LocalAgentDataConnector);
+        ConnectorService.register(TConnectorService.AgentData, 'SQLite', SQLiteAgentDataConnector);
 
         ConnectorService.register(TConnectorService.AgentData, 'NullAgentData', NullAgentData);
     }

package/src/subsystems/LLMManager/LLM.helper.ts

@@ -1,4 +1,4 @@
-import { type TLLMMessageBlock, TLLMMessageRole } from '@sre/types/LLM.types';
+import { type TLLMMessageBlock, TLLMMessageRole, TLLMFinishReason } from '@sre/types/LLM.types';
 
 import axios from 'axios';
 import imageSize from 'image-size';
@@ -273,4 +273,120 @@ export class LLMHelper {
         // Examples: claude-opus-4-5, claude-sonnet-4-20250514, claude-4-opus
         return /claude-(?:\w+-)?4(?:-|$)/i.test(modelId);
     }
+
+    /**
+     * Normalizes provider-specific finish reason values to TLLMFinishReason enum.
+     * Handles provider-specific values from OpenAI, Anthropic, Google AI, and other providers.
+     * 
+     * @param finishReason - The finish reason from the provider (can be string, null, or undefined)
+     * @returns Normalized TLLMFinishReason enum value
+     * 
+     * @example
+     * const normalized = LLMHelper.normalizeFinishReason('end_turn');
+     * console.log(normalized); // TLLMFinishReason.Stop
+     * 
+     * @example
+     * const normalized = LLMHelper.normalizeFinishReason('tool_use');
+     * console.log(normalized); // TLLMFinishReason.ToolCalls
+     * 
+     * @example
+     * const normalized = LLMHelper.normalizeFinishReason('SAFETY');
+     * console.log(normalized); // TLLMFinishReason.ContentFilter
+     */
+    public static normalizeFinishReason(finishReason: string | null | undefined): TLLMFinishReason {
+        if (!finishReason) {
+            return TLLMFinishReason.Stop;
+        }
+
+        const normalized = finishReason.toLowerCase().trim();
+
+        // Map standard and provider-specific values
+        switch (normalized) {
+            // Natural stop
+            case 'stop':
+            case 'end_turn': // Anthropic - natural end of turn
+            case 'stop_sequence': // Anthropic - custom stop sequence matched
+            case 'pause_turn': // Anthropic - paused for long-running operation
+                return TLLMFinishReason.Stop;
+
+            // Token/length limits
+            case 'length':
+            case 'max_tokens': // Anthropic, Google AI
+            case 'incomplete': // OpenAI Responses API - response cut short due to max tokens or content filter
+                return TLLMFinishReason.Length;
+
+            case 'model_context_window_exceeded': // Anthropic - context window exceeded
+                return TLLMFinishReason.ContextWindowLength;
+
+            // Content filtering and safety
+            case 'content_filter':
+            case 'contentfilter':
+            case 'refusal': // Anthropic - refused due to safety/policy
+            case 'safety': // Google AI - flagged by safety filters
+            case 'recitation': // Google AI - copyrighted content recitation
+            case 'language': // Google AI - unsupported language
+            case 'blocklist': // Google AI - forbidden terms
+            case 'prohibited_content': // Google AI - prohibited content
+            case 'spii': // Google AI - sensitive personally identifiable information
+                return TLLMFinishReason.ContentFilter;
+
+            // Tool/function calls
+            case 'tool_calls':
+            case 'tool_use': // Anthropic - tool invocation
+            case 'function_call': // OpenAI deprecated
+                return TLLMFinishReason.ToolCalls;
+
+            // Abort
+            case 'abort':
+                return TLLMFinishReason.Abort;
+
+            // Errors
+            case 'error':
+            case 'malformed_function_call': // Google AI - invalid function call
+                return TLLMFinishReason.Error;
+
+            // Unknown/unmapped
+            default:
+                return TLLMFinishReason.Unknown;
+        }
+    }
+
+    /**
+     * Gets a user-friendly error message based on the finish reason.
+     * 
+     * @param finishReason - The normalized finish reason enum value
+     * @returns User-friendly error message explaining why the response was interrupted
+     * 
+     * @example
+     * const message = LLMHelper.getFinishReasonErrorMessage(TLLMFinishReason.Length);
+     * console.log(message); // "Empty response. This is usually due to output token limit reached..."
+     */
+    public static getFinishReasonErrorMessage(finishReason: TLLMFinishReason): string {
+        switch (finishReason) {
+            case TLLMFinishReason.Length:
+                return 'Empty response. This is usually due to output token limit reached. Please try again with a higher \'Maximum Output Tokens\'.';
+
+            case TLLMFinishReason.ContextWindowLength:
+                return 'Context window limit exceeded. Please shorten the input prompt or summarize the previous conversation to reduce token usage.';
+            
+            case TLLMFinishReason.ContentFilter:
+                return 'The response was blocked by content filtering policies. Please modify your prompt and try again.';
+            
+            case TLLMFinishReason.Abort:
+                return 'The request was aborted before completion.';
+            
+            case TLLMFinishReason.Error:
+                return 'An error occurred while generating the response. Please try again.';
+            
+            case TLLMFinishReason.ToolCalls:
+                return 'The model attempted to call a tool but the response was incomplete.';
+            
+            case TLLMFinishReason.Unknown:
+                return 'The response was interrupted for an unknown reason. Please try again.';
+            
+            case TLLMFinishReason.Stop:
+            default:
+                return 'The model stopped before completing the response.';
+        }
+    }
 }

package/src/subsystems/LLMManager/LLM.inference.ts

@@ -8,8 +8,9 @@ import { BinaryInput } from '@sre/helpers/BinaryInput.helper';
 import { Logger } from '@sre/helpers/Log.helper';
 import { AccessCandidate } from '@sre/Security/AccessControl/AccessCandidate.class';
 import { IAgent } from '@sre/types/Agent.types';
-import { TLLMChatResponse, TLLMMessageRole, TLLMModel, TLLMParams } from '@sre/types/LLM.types';
+import { TLLMChatResponse, TLLMMessageRole, TLLMModel, TLLMParams, TLLMEvent, TLLMFinishReason } from '@sre/types/LLM.types';
 
+import { LLMHelper } from './LLM.helper';
 import { LLMConnector } from './LLM.service/LLMConnector';
 import { IModelsProviderRequest, ModelsProviderConnector } from './ModelsProvider.service/ModelsProviderConnector';
 
@@ -96,29 +97,33 @@ export class LLMInference {
 
             const result = this._llmConnector.postProcess(response?.content);
             if (result.error) {
-                // If the model stopped before completing the response, this is usually due to output token limit reached.
-                if (response.finishReason !== 'stop') {
-                    throw new Error('The model stopped before completing the response, this is usually due to output token limit reached.');
+                // If the model stopped before completing the response normally, provide specific error message
+                if (response.finishReason !== TLLMFinishReason.Stop) {
+                    const errorMessage = LLMHelper.getFinishReasonErrorMessage(response.finishReason);
+                    throw new Error(errorMessage);
                 }
 
-                // If the model stopped due to other reasons, throw the error
+                // If the model stopped normally but there's a postProcess error, throw the postProcess error
                 throw new Error(result.error);
             }
             return result;
         } catch (error: any) {
             // Attempt fallback for custom models (only if not already in fallback)
             if (!isInFallback) {
-                try {
-                    const fallbackParams = await this.getSafeFallbackParams(params);
-                    const fallbackResult = await this.executeFallback('prompt', { query, contextWindow, files, params: fallbackParams, onFallback });
-
-                    // If fallback succeeded, return the result
-                    if (fallbackResult !== null) {
-                        return fallbackResult;
+                const isCustomModel = await this._modelProviderReq.isUserCustomLLM(this._model);
+                if (isCustomModel) {
+                    try {
+                        const fallbackParams = await this.getSafeFallbackParams(params);
+                        const fallbackResult = await this.executeFallback('prompt', { query, contextWindow, files, params: fallbackParams, onFallback });
+
+                        // If fallback succeeded, return the result
+                        if (fallbackResult !== null) {
+                            return fallbackResult;
+                        }
+                    } catch (fallbackError) {
+                        // If fallback also failed, log it but continue to throw original error
+                        logger.warn('Fallback also failed:', fallbackError);
                     }
-                } catch (fallbackError) {
-                    // If fallback also failed, log it but continue to throw original error
-                    logger.warn('Fallback also failed:', fallbackError);
                 }
             }
 
@@ -147,41 +152,20 @@ export class LLMInference {
             onFallback({ model: this._model });
         }
 
-        try {
-            return await this._llmConnector.user(AccessCandidate.agent(params.agentId)).streamRequest(params);
-        } catch (error) {
-            // Attempt fallback for custom models (only if not already in fallback)
-            if (!isInFallback) {
-                try {
-                    const fallbackParams = await this.getSafeFallbackParams(params);
-                    const fallbackResult = await this.executeFallback('promptStream', {
-                        query,
-                        contextWindow,
-                        files,
-                        params: fallbackParams,
-                        onFallback,
-                    });
-
-                    // If fallback succeeded, return the result
-                    if (fallbackResult !== null) {
-                        return fallbackResult;
-                    }
-                } catch (fallbackError) {
-                    // If fallback also failed, log it but continue to return error emitter
-                    logger.warn('Fallback also failed:', fallbackError);
-                }
-            }
+        // Connectors now always return emitters (they don't throw errors)
+        const primaryEmitter = await this._llmConnector.user(AccessCandidate.agent(params.agentId)).streamRequest(params);
 
-            // If fallback was not attempted or failed, return error emitter
-            logger.error('Error in streamRequest:', error);
+        // Only wrap with fallback capability if this is a custom model (not already in fallback)
+        // For regular models, return the emitter directly - errors flow naturally to the caller
+        if (!isInFallback) {
+            const isCustomModel = await this._modelProviderReq.isUserCustomLLM(this._model);
 
-            const dummyEmitter = new EventEmitter();
-            process.nextTick(() => {
-                dummyEmitter.emit('error', error);
-                dummyEmitter.emit('end');
-            });
-            return dummyEmitter;
+            if (isCustomModel) {
+                return this.wrapWithFallback(primaryEmitter, { query, contextWindow, files, params, onFallback });
+            }
         }
+
+        return primaryEmitter;
     }
 
     /**
@@ -232,19 +216,20 @@ export class LLMInference {
 
     /**
      * Executes fallback logic for custom models when the primary model fails.
-     * This method checks if a fallback model is configured and invokes the appropriate LLM method.
+     * Checks if a fallback model is configured and switches to it.
      * Prevents infinite loops by passing a flag to indicate we're in a fallback attempt.
      *
+     * **Important**: This method should only be called for custom models (already verified by caller).
+     *
      * @param methodName - The name of the method being called ('prompt' or 'promptStream')
      * @param args - The original arguments passed to the method
-     * @returns The result from the fallback execution, or null if fallback should not be attempted
+     * @returns The result from the fallback execution, or null if no fallback is configured
      */
     private async executeFallback(methodName: 'prompt' | 'promptStream', args: TPromptParams): Promise<any> {
-        const isCustomModel = await this._modelProviderReq.isUserCustomLLM(this._model);
         const fallbackModel = await this._modelProviderReq.getFallbackLLM(this._model);
 
-        // Only execute fallback if it's a custom model with a configured fallback
-        if (!isCustomModel || !fallbackModel) {
+        // Only execute fallback if a fallback model is configured
+        if (!fallbackModel) {
             return null;
         }
 
@@ -266,6 +251,93 @@ export class LLMInference {
         }
     }
 
+    /**
+     * Wraps an emitter with fallback capability using a proxy pattern.
+     * This creates a transparent proxy that forwards all events from the source emitter.
+     * On error, it attempts to switch to a fallback model and seamlessly redirects events.
+     *
+     * **Important**: This method is only called for custom models that have fallback configured.
+     * Regular models return their emitters directly without wrapping, so errors flow naturally.
+     *
+     * **Design Pattern**: Proxy/Decorator with listener-based event forwarding
+     * **Coupling**: Minimal - reads event types from TLLMEvent enum (single source of truth)
+     * **Reliability**: Uses listeners (not emit interception) to avoid timing issues with async emits
+     *
+     * Note: We use the TLLMEvent enum as the source of truth for all event types.
+     * This provides a good balance between decoupling and reliability. The enum already
+     * defines all possible LLM events, and connectors emit these standard events.
+     *
+     * @param sourceEmitter - The custom model's event emitter
+     * @param args - The original prompt arguments for fallback execution
+     * @returns A proxy emitter that transparently handles primary/fallback switching
+     */
+    private wrapWithFallback(sourceEmitter: EventEmitter, args: TPromptParams): EventEmitter {
+        const proxyEmitter = new EventEmitter();
+        let fallbackAttempted = false;
+
+        /**
+         * Attaches forwarding listeners for all event types in TLLMEvent.
+         * Uses listeners instead of emit() interception to avoid timing issues with setImmediate.
+         * 
+         * @param source - The emitter to forward events from
+         * @param skipErrors - If true, skips forwarding error events (handled separately)
+         */
+        const forwardAllEvents = (source: EventEmitter, skipErrors: boolean) => {
+            // Get all event types from TLLMEvent enum
+            const eventTypes = Object.values(TLLMEvent);
+            
+            for (const eventType of eventTypes) {
+                // Skip error events if we're intercepting them
+                if (skipErrors && eventType === TLLMEvent.Error) {
+                    continue;
+                }
+                
+                // Attach listener to forward this event type
+                source.on(eventType, (...eventArgs: any[]) => {
+                    proxyEmitter.emit(eventType, ...eventArgs);
+                });
+            }
+        };
+
+        // Handle error events for fallback logic
+        const handleError = async (error: Error) => {
+            if (fallbackAttempted) return;
+            fallbackAttempted = true;
+
+            // Stop forwarding from primary emitter
+            sourceEmitter.removeAllListeners();
+
+            try {
+                const fallbackParams = await this.getSafeFallbackParams(args.params);
+                const fallbackEmitter = await this.executeFallback('promptStream', {
+                    ...args,
+                    params: fallbackParams,
+                });
+
+                if (fallbackEmitter) {
+                    // Forward all events from fallback emitter (including errors)
+                    forwardAllEvents(fallbackEmitter, false);
+                    logger.info('Successfully switched to fallback stream');
+                    return;
+                }
+            } catch (fallbackError) {
+                logger.warn('Fallback attempt failed:', fallbackError);
+            }
+
+            // If we get here, fallback failed or was not available - emit error on proxy
+            proxyEmitter.emit(TLLMEvent.Error, error);
+            proxyEmitter.emit(TLLMEvent.End, [], [], TLLMFinishReason.Error);
+        };
+
+        // Attach error handler FIRST to intercept errors
+        sourceEmitter.once(TLLMEvent.Error, handleError);
+
+        // Forward all non-error events from primary emitter
+        forwardAllEvents(sourceEmitter, true);
+
+        return proxyEmitter;
+    }
+
     public async imageGenRequest({ query, files, params }: TPromptParams) {
         params.prompt = query;
         return this._llmConnector.user(AccessCandidate.agent(params.agentId)).imageGenRequest(params);
@@ -280,24 +352,21 @@ export class LLMInference {
     //@deprecated
     public async streamRequest(params: any, agent: string | IAgent) {
         const agentId = isAgent(agent) ? (agent as IAgent).id : agent;
-        try {
-            if (!params.messages || !params.messages?.length) {
-                throw new Error('Input messages are required.');
-            }
-
-            const model = params.model || this._model;
-
-            return await this._llmConnector.user(AccessCandidate.agent(agentId)).streamRequest({ ...params, model });
-        } catch (error) {
-            logger.error('Error in streamRequest:', error);
-
-            const dummyEmitter = new EventEmitter();
+        if (!params.messages || !params.messages?.length) {
+            // Return an emitter with error/end events for validation errors
+            const errorEmitter = new EventEmitter();
+            const validationError = new Error('Input messages are required.');
             process.nextTick(() => {
-                dummyEmitter.emit('error', error);
-                dummyEmitter.emit('end');
+                errorEmitter.emit(TLLMEvent.Error, validationError);
+                errorEmitter.emit(TLLMEvent.End, [], [], TLLMFinishReason.Error);
             });
-            return dummyEmitter;
+            return errorEmitter;
         }
+
+        const model = params.model || this._model;
+
+        // Connectors now always return emitters (they don't throw errors)
+        return await this._llmConnector.user(AccessCandidate.agent(agentId)).streamRequest({ ...params, model });
     }
 
     //@deprecated

package/src/subsystems/LLMManager/LLM.service/LLMConnector.ts

@@ -112,6 +112,7 @@ export abstract class LLMConnector extends Connector {
                 const response = await this.request({
                     acRequest: candidate.readRequest,
                     body: preparedParams.body,
+                    abortSignal: preparedParams.abortSignal,
                     context: {
                         modelEntryName: preparedParams.modelEntryName,
                         agentId: preparedParams.agentId,
@@ -137,6 +138,7 @@ export abstract class LLMConnector extends Connector {
                 const requestParams = {
                     acRequest: candidate.readRequest,
                     body: preparedParams.body,
+                    abortSignal: preparedParams.abortSignal,
                     context: {
                         modelEntryName: preparedParams.modelEntryName,
                         agentId: preparedParams.agentId,
@@ -262,15 +264,18 @@ export abstract class LLMConnector extends Connector {
 
     private async prepareParams(candidate: AccessCandidate, params: TLLMConnectorParams): Promise<TLLMPreparedParams> {
         const modelsProvider: ModelsProviderConnector = ConnectorService.getModelsProviderConnector();
-        // Assign file from the original parameters to avoid overwriting the original constructor
-        const files = params?.files;
-        delete params?.files; // need to remove files to avoid any issues during JSON.stringify() especially when we have large files
+        // Extract files and abortSignal from the original parameters to avoid overwriting the original constructor
+        const { files, abortSignal, ...restParams } = params;
 
-        const clonedParams = JSON.parse(JSON.stringify(params)); // Avoid mutation of the original params
+        const clonedParams = JSON.parse(JSON.stringify(restParams)); // Avoid mutation of the original params
 
         // Format the parameters to ensure proper type of values
         const _params: TLLMPreparedParams = this.formatParamValues(clonedParams);
 
+        // Re-attach non-serializable properties ignored before cloning
+        _params.abortSignal = abortSignal;
+        _params.files = files;
+
         const model = _params.model;
         const teamId = await this.getTeamId(candidate);
 
@@ -307,8 +312,6 @@ export abstract class LLMConnector extends Connector {
         }
 
         _params.model = await modelProviderCandidate.getModelId(model);
-        // Attach the files again after formatting the parameters
-        _params.files = files;
 
         const features = modelInfo?.features || [];
 
@@ -327,6 +330,9 @@ export abstract class LLMConnector extends Connector {
             xai: await this.prepareXAIToolsInfo(_params),
         };
 
+        // Filter out default and system-specific outputs (e.g., _debug, _error) to isolate custom outputs for structured response
+        _params.structuredOutputs = _params?.outputs?.filter((output) => !output.default && !['_debug', '_error'].includes(output.name)) || [];
+
         // The input adapter transforms the standardized parameters into the specific format required by the target LLM provider
         _params.agentId = candidate.id;
         const body = await this.reqBodyAdapter(_params);
@@ -461,6 +467,7 @@ export abstract class LLMConnector extends Connector {
             }
 
             //FIXME: to revisit by Alaa-eddine
+            // TODO: This part is a bit confusing. We send “consistent” messages to the LLM, but they still aren’t truly consistent. For example, we send { role: 'system', content: 'You are a helpful assistant.' }, which isn’t compatible with Google AI. However, we still need to mark it as `system` because we later convert it to `systemInstruction`. We should revisit the architecture later and make the flow simpler and more straightforward.
             if (key === 'messages') {
                 _value = this.getConsistentMessages(_value);
             }