@egain/ai-agent-sdk 0.1.0

package/dist/core/message/Transcript.js

@@ -0,0 +1,355 @@
+/**
+ * # Transcript
+ *
+ * The Transcript feature automatically records all messages sent and received
+ * during a conversation, providing a complete history for display, debugging,
+ * or analytics.
+ *
+ * ## Overview
+ *
+ * Transcript is enabled by default and automatically captures:
+ * - Customer messages (sent)
+ * - Agent responses (received)
+ * - System messages
+ * - Context messages
+ *
+ * ## Quick Start
+ *
+ * Access the transcript through the agent instance:
+ *
+ * ```typescript
+ * // Get all transcript entries
+ * const entries = agent.getTranscript();
+ *
+ * // Get as JSON (for display or storage)
+ * const json = agent.getTranscriptAsJSON();
+ *
+ * // Get transcript size
+ * const count = agent.getTranscriptSize();
+ *
+ * // Clear transcript
+ * agent.clearTranscript();
+ * ```
+ *
+ * ## Configuration
+ *
+ * Configure transcript behavior when creating the agent:
+ *
+ * ```typescript
+ * const agent = new AiAgent({
+ *   id: "agent-id",
+ *   endpoint: "https://your-endpoint.com",
+ *   transcriptConfig: {
+ *     enabled: true,                    // Enable/disable transcript
+ *     excludeRoles: ["heartbeat"],      // Exclude heartbeat messages
+ *     excludePersonas: ["system"]       // Exclude system messages
+ *   }
+ * });
+ * ```
+ *
+ * ## Filtering Entries
+ *
+ * Retrieve filtered transcript entries:
+ *
+ * ```typescript
+ * // Get only received messages
+ * const received = agent.getTranscript({ direction: 'received' });
+ *
+ * // Get messages from a specific time range
+ * const recent = agent.getTranscript({
+ *   fromTimestamp: Date.now() - 3600000  // Last hour
+ * });
+ *
+ * // Get only agent messages
+ * const agentMessages = agent.getTranscript({ persona: 'agent' });
+ * ```
+ *
+ * ## Transcript Events
+ *
+ * Listen for transcript updates in real-time:
+ *
+ * ```typescript
+ * agent.on('transcriptUpdate', (event) => {
+ *   const { entry } = event.payload;
+ *   console.log(`${entry.direction}: ${entry.message.content}`);
+ * });
+ * ```
+ *
+ * ## Use Cases
+ *
+ * - **Chat UI**: Display conversation history
+ * - **Analytics**: Track conversation patterns
+ * - **Debugging**: Review message flow
+ * - **Persistence**: Save conversations to database
+ *
+ * @module Transcript
+ * @category Features
+ */
+/**
+ * Transcript storage class for managing conversation history.
+ *
+ * The Transcript class provides a complete record of all messages
+ * exchanged during a conversation. It supports filtering, JSON export,
+ * and real-time updates.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const transcript = new Transcript();
+ *
+ * // Add a message
+ * transcript.add(message, 'sent', sessionId, agentId);
+ *
+ * // Get all entries
+ * const entries = transcript.getEntries();
+ *
+ * // Get as JSON for storage
+ * const json = transcript.getEntriesAsJSON();
+ *
+ * // Get entry count
+ * console.log(`${transcript.size()} messages`);
+ *
+ * // Clear all entries
+ * transcript.clear();
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * const transcript = new Transcript({
+ *   enabled: true,
+ *   excludeRoles: ['heartbeat'],  // Don't record heartbeats
+ * });
+ * ```
+ *
+ * @example Filtering entries
+ * ```typescript
+ * // Get only agent responses
+ * const agentResponses = transcript.getEntries({
+ *   direction: 'received',
+ *   persona: 'agent'
+ * });
+ *
+ * // Get messages from the last 5 minutes
+ * const recentMessages = transcript.getEntries({
+ *   fromTimestamp: Date.now() - 300000
+ * });
+ * ```
+ *
+ * @category Features
+ * @group Transcript
+ */
+export class Transcript {
+    /**
+     * Create a new Transcript instance
+     * @param config - Optional configuration for filtering
+     */
+    constructor(config = {}) {
+        this.entries = [];
+        this.config = {
+            enabled: config.enabled ?? true,
+            includeMessageTypes: config.includeMessageTypes ?? [],
+            excludeRoles: config.excludeRoles ?? [],
+            excludePersonas: config.excludePersonas ?? [],
+        };
+    }
+    /**
+     * Add a message to the transcript.
+     *
+     * Messages are automatically filtered based on configuration.
+     * If the transcript is disabled or the message matches an exclude filter,
+     * it will not be recorded.
+     *
+     * @param message - The message to add
+     * @param direction - Whether the message was 'sent' or 'received'
+     * @param sessionId - Optional session ID for context
+     * @param agentId - Optional agent ID for context
+     *
+     * @example
+     * ```typescript
+     * transcript.add(
+     *   new Message('customer', 'human', 'Hello!'),
+     *   'sent',
+     *   'session-123',
+     *   'agent-456'
+     * );
+     * ```
+     */
+    add(message, direction, sessionId, agentId) {
+        if (!this.config.enabled) {
+            return;
+        }
+        // Check if message should be filtered out
+        if (!this.shouldInclude(message)) {
+            return;
+        }
+        const entry = {
+            message,
+            direction,
+            timestamp: message.timestamp || Date.now(),
+            sessionId,
+            agentId,
+        };
+        this.entries.push(entry);
+    }
+    /**
+     * Get transcript entries, optionally filtered.
+     *
+     * @param options - Optional filtering options
+     * @returns Array of transcript entries matching the filter
+     *
+     * @example
+     * ```typescript
+     * // Get all entries
+     * const all = transcript.getEntries();
+     *
+     * // Get only sent messages
+     * const sent = transcript.getEntries({ direction: 'sent' });
+     *
+     * // Get messages from last hour
+     * const recent = transcript.getEntries({
+     *   fromTimestamp: Date.now() - 3600000
+     * });
+     * ```
+     */
+    getEntries(options) {
+        let filtered = [...this.entries];
+        if (options) {
+            // Filter by timestamp range
+            if (options.fromTimestamp !== undefined) {
+                filtered = filtered.filter((entry) => entry.timestamp >= options.fromTimestamp);
+            }
+            if (options.toTimestamp !== undefined) {
+                filtered = filtered.filter((entry) => entry.timestamp <= options.toTimestamp);
+            }
+            // Filter by direction
+            if (options.direction && options.direction !== 'both') {
+                filtered = filtered.filter((entry) => entry.direction === options.direction);
+            }
+            // Filter by persona
+            if (options.persona) {
+                filtered = filtered.filter((entry) => entry.message.persona === options.persona);
+            }
+            // Filter by role
+            if (options.role) {
+                filtered = filtered.filter((entry) => entry.message.role === options.role);
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Get transcript entries as plain JSON-serializable objects.
+     *
+     * Useful for storing transcripts in databases, sending to APIs,
+     * or displaying in UI components.
+     *
+     * @param options - Optional filtering options
+     * @returns Array of plain objects representing transcript entries
+     *
+     * @example
+     * ```typescript
+     * const json = transcript.getEntriesAsJSON();
+     *
+     * // Each entry includes:
+     * // {
+     * //   messageId, persona, role, content, messageData,
+     * //   timestamp, from, to, agentId, sessionId,
+     * //   direction, entryTimestamp
+     * // }
+     *
+     * // Save to database
+     * await db.saveTranscript(json);
+     * ```
+     */
+    getEntriesAsJSON(options) {
+        const entries = this.getEntries(options);
+        return entries.map((entry) => ({
+            messageId: entry.message.messageId,
+            persona: entry.message.persona,
+            role: entry.message.role,
+            content: entry.message.content,
+            messageData: entry.message.messageData,
+            timestamp: entry.message.timestamp,
+            from: entry.message.from,
+            to: entry.message.to,
+            agentId: entry.agentId ?? entry.message.agentId,
+            sessionId: entry.sessionId ?? entry.message.sessionId,
+            direction: entry.direction,
+            entryTimestamp: entry.timestamp,
+        }));
+    }
+    /**
+     * Get the number of entries in the transcript.
+     * @returns Number of recorded messages
+     */
+    size() {
+        return this.entries.length;
+    }
+    /**
+     * Clear all transcript entries.
+     *
+     * This removes all recorded messages. Use with caution as
+     * this action cannot be undone.
+     */
+    clear() {
+        this.entries = [];
+    }
+    /**
+     * Check if a message should be included based on configuration filters
+     * @param message - The message to check
+     * @returns True if message should be included
+     */
+    shouldInclude(message) {
+        // Check exclude roles
+        if (this.config.excludeRoles.length > 0) {
+            if (this.config.excludeRoles.includes(message.role)) {
+                return false;
+            }
+        }
+        // Check exclude personas
+        if (this.config.excludePersonas.length > 0) {
+            if (this.config.excludePersonas.includes(message.persona)) {
+                return false;
+            }
+        }
+        // If includeMessageTypes is specified, check if message type matches
+        // Note: This is a simplified check. In a real implementation, you might
+        // want to map message persona/role combinations to message types
+        if (this.config.includeMessageTypes.length > 0) {
+            // For now, we'll include all messages if includeMessageTypes is specified
+            // This can be enhanced to map persona/role to message types
+            // For example: agent + human = 'agent_message', customer + human = 'customer_message'
+        }
+        return true;
+    }
+    /**
+     * Update transcript configuration at runtime.
+     *
+     * @param config - New configuration options (partial update)
+     *
+     * @example
+     * ```typescript
+     * // Disable transcript temporarily
+     * transcript.updateConfig({ enabled: false });
+     *
+     * // Re-enable with new exclusions
+     * transcript.updateConfig({
+     *   enabled: true,
+     *   excludeRoles: ['heartbeat', 'token']
+     * });
+     * ```
+     */
+    updateConfig(config) {
+        if (config.enabled !== undefined) {
+            this.config.enabled = config.enabled;
+        }
+        if (config.includeMessageTypes !== undefined) {
+            this.config.includeMessageTypes = config.includeMessageTypes;
+        }
+        if (config.excludeRoles !== undefined) {
+            this.config.excludeRoles = config.excludeRoles;
+        }
+        if (config.excludePersonas !== undefined) {
+            this.config.excludePersonas = config.excludePersonas;
+        }
+    }
+}
+//# sourceMappingURL=Transcript.js.map

package/dist/core/message/Transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transcript.js","sourceRoot":"","sources":["../../../src/core/message/Transcript.ts"],"names":[],"mappings":"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"}

package/dist/core/message/handlers/AgentMessageHandler.d.ts

@@ -0,0 +1,26 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { Message } from '../Message.js';
+import { MessageHandlerResult } from '../types.js';
+/**
+ * Handler for agent messages (main chat responses)
+ * Processes agent messages and extracts follow-up options, escalation data, sources, and reasoning
+ */
+export declare class AgentMessageHandler extends BaseMessageHandler {
+    canHandle(message: Message): boolean;
+    handle(message: Message): MessageHandlerResult;
+    /**
+     * Checks if message has follow-up question options
+     * Only processes messages with role "follow up question agent"
+     */
+    private hasFollowUpOptions;
+    /**
+     * Processes escalation data from an agent message
+     * Handles both live escalations (transfer to human agent) and alternate engagement options
+     */
+    private processEscalation;
+    /**
+     * Builds an array of alternate engagement options based on escalation configuration
+     */
+    private buildEscalationOptions;
+}
+//# sourceMappingURL=AgentMessageHandler.d.ts.map

package/dist/core/message/handlers/AgentMessageHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentMessageHandler.d.ts","sourceRoot":"","sources":["../../../../src/core/message/handlers/AgentMessageHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,kBAAkB;IACzD,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAIpC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB;IAqD9C;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAqCzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAyC/B"}

package/dist/core/message/handlers/AgentMessageHandler.js

@@ -0,0 +1,130 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { PERSONA, ROLE } from '../types.js';
+/**
+ * Handler for agent messages (main chat responses)
+ * Processes agent messages and extracts follow-up options, escalation data, sources, and reasoning
+ */
+export class AgentMessageHandler extends BaseMessageHandler {
+    canHandle(message) {
+        return message.persona === PERSONA.AGENT;
+    }
+    handle(message) {
+        // Extract sessionId and agentId from messageData if available
+        const sessionId = message.sessionId;
+        const agentId = message.agentId;
+        // Build from object - agent is the sender
+        const from = {
+            name: message.from || 'AI Agent',
+            isAi: true,
+        };
+        // Build to object - customer is the recipient
+        const to = {
+            name: message.to || 'Customer',
+            isAi: false,
+        };
+        // Process escalation scenarios
+        const escalationResult = this.processEscalation(message);
+        // Check if there are follow-up options
+        const hasFollowUpOptions = this.hasFollowUpOptions(message);
+        // Build message object with persona, role, content, raw data, and additional fields
+        const messageObj = {
+            persona: message.persona,
+            role: message.role,
+            content: message.content,
+            raw: message.messageData || {},
+            ...(escalationResult.escalationType && { escalationType: escalationResult.escalationType }),
+            ...(escalationResult.escalationData && { escalationData: escalationResult.escalationData }),
+            ...(message.messageData?.sources && { sources: message.messageData.sources }),
+            ...(message.messageData?.reasoning && { reasoning: message.messageData.reasoning }),
+            ...(escalationResult.isEscalation !== undefined && { showReasoning: escalationResult.isEscalation }),
+            ...(message.role === ROLE.CUSTOMER_SUPPORT && { showFeedback: true }),
+            ...(hasFollowUpOptions && { showOptions: true }),
+        };
+        // Build result in the required format
+        const result = {
+            type: 'agent_message',
+            messageId: message.messageId,
+            timestamp: message.timestamp || Date.now(),
+            sessionId: sessionId,
+            agentId: agentId,
+            from: from,
+            to: to,
+            message: messageObj,
+        };
+        return result;
+    }
+    /**
+     * Checks if message has follow-up question options
+     * Only processes messages with role "follow up question agent"
+     */
+    hasFollowUpOptions(message) {
+        if (message.role !== ROLE.FOLLOW_UP_QUESTION) {
+            return false;
+        }
+        const options = message.messageData?.options;
+        return !!(options && Array.isArray(options) && options.length > 0);
+    }
+    /**
+     * Processes escalation data from an agent message
+     * Handles both live escalations (transfer to human agent) and alternate engagement options
+     */
+    processEscalation(message) {
+        const isEscalation = !!message.messageData?.escalation;
+        const escalationData = message.messageData?.escalationData;
+        const result = {
+            isEscalation,
+            escalationType: null,
+            escalationData: undefined,
+        };
+        if (!isEscalation || !escalationData) {
+            return result;
+        }
+        // Check for live escalation
+        if (escalationData.live) {
+            result.escalationType = 'live';
+            result.escalationData = escalationData;
+            return result;
+        }
+        // Build alternate engagement options
+        const escalationOptions = this.buildEscalationOptions(escalationData);
+        if (escalationOptions.length > 0) {
+            result.escalationType = 'alternate';
+            result.escalationData = {
+                ...escalationData,
+                options: escalationOptions,
+            };
+        }
+        return result;
+    }
+    /**
+     * Builds an array of alternate engagement options based on escalation configuration
+     */
+    buildEscalationOptions(escalationData) {
+        const options = [];
+        if (escalationData.phone) {
+            options.push({
+                label: 'EG_CALL',
+                type: 'phone',
+                value: escalationData.phoneNumber,
+                icon: 'icon_phone_call_svg',
+            });
+        }
+        if (escalationData.sms) {
+            options.push({
+                label: 'EG_ALT_CONTACT_SMS',
+                type: 'sms',
+                value: escalationData.smsNumber,
+                icon: 'icon_messaging',
+            });
+        }
+        if (escalationData.email) {
+            options.push({
+                label: 'EG_EMAIL',
+                type: 'email',
+                icon: 'icon_email_svg',
+            });
+        }
+        return options;
+    }
+}
+//# sourceMappingURL=AgentMessageHandler.js.map

package/dist/core/message/handlers/AgentMessageHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentMessageHandler.js","sourceRoot":"","sources":["../../../../src/core/message/handlers/AgentMessageHandler.ts"],"names":[],"mappings":"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"}

package/dist/core/message/handlers/ChatHistoryHandler.d.ts

@@ -0,0 +1,12 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { Message } from '../Message.js';
+import { MessageHandlerResult } from '../types.js';
+/**
+ * Handler for chat history messages
+ * Processes system messages containing chat history data
+ */
+export declare class ChatHistoryHandler extends BaseMessageHandler {
+    canHandle(message: Message): boolean;
+    handle(message: Message): MessageHandlerResult;
+}
+//# sourceMappingURL=ChatHistoryHandler.d.ts.map

package/dist/core/message/handlers/ChatHistoryHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatHistoryHandler.d.ts","sourceRoot":"","sources":["../../../../src/core/message/handlers/ChatHistoryHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,kBAAkB;IACxD,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAOpC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB;CAyC/C"}

package/dist/core/message/handlers/ChatHistoryHandler.js

@@ -0,0 +1,49 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { PERSONA, ROLE } from '../types.js';
+/**
+ * Handler for chat history messages
+ * Processes system messages containing chat history data
+ */
+export class ChatHistoryHandler extends BaseMessageHandler {
+    canHandle(message) {
+        return (message.persona === PERSONA.SYSTEM &&
+            message.role === ROLE.CHAT_HISTORY);
+    }
+    handle(message) {
+        const sessionId = message.sessionId;
+        const agentId = message.agentId;
+        const chatHistory = message.messageData?.chat_history;
+        // Build from object - system is the sender
+        const from = {
+            name: message.from || 'System',
+            isAi: false,
+        };
+        // Build to object - customer is the recipient
+        const to = {
+            name: message.to || 'Customer',
+            isAi: false,
+        };
+        // Build message object with persona, role, content, raw data, and chat history
+        const messageObj = {
+            persona: message.persona,
+            role: message.role,
+            content: message.content,
+            raw: message.messageData || {},
+            ...(chatHistory && { chatHistory }),
+        };
+        // Build result in the required format
+        const result = {
+            type: 'chat_history_processed',
+            messageId: message.messageId,
+            timestamp: message.timestamp || Date.now(),
+            sessionId: sessionId,
+            agentId: agentId,
+            from: from,
+            to: to,
+            message: messageObj,
+            hasHistory: !!chatHistory,
+        };
+        return result;
+    }
+}
+//# sourceMappingURL=ChatHistoryHandler.js.map

package/dist/core/message/handlers/ChatHistoryHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatHistoryHandler.js","sourceRoot":"","sources":["../../../../src/core/message/handlers/ChatHistoryHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAE5C;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,kBAAkB;IACxD,SAAS,CAAC,OAAgB;QACxB,OAAO,CACL,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,MAAM;YAClC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,YAAY,CACnC,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAgB;QACrB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC;QAEtD,2CAA2C;QAC3C,MAAM,IAAI,GAAG;YACX,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ;YAC9B,IAAI,EAAE,KAAK;SACZ,CAAC;QAEF,8CAA8C;QAC9C,MAAM,EAAE,GAAG;YACT,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,UAAU;YAC9B,IAAI,EAAE,KAAK;SACZ,CAAC;QAEF,+EAA+E;QAC/E,MAAM,UAAU,GAAG;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;YAC9B,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;SACpC,CAAC;QAEF,sCAAsC;QACtC,MAAM,MAAM,GAAyB;YACnC,IAAI,EAAE,wBAAwB;YAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;YAC1C,SAAS,EAAE,SAAS;YACpB,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,IAAI;YACV,EAAE,EAAE,EAAE;YACN,OAAO,EAAE,UAAU;YACnB,UAAU,EAAE,CAAC,CAAC,WAAW;SAC1B,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/core/message/handlers/ErrorMessageHandler.d.ts

@@ -0,0 +1,12 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { Message } from '../Message.js';
+import { MessageHandlerResult } from '../types.js';
+/**
+ * Handler for error messages
+ * Processes metadata error messages indicating an error occurred
+ */
+export declare class ErrorMessageHandler extends BaseMessageHandler {
+    canHandle(message: Message): boolean;
+    handle(message: Message): MessageHandlerResult;
+}
+//# sourceMappingURL=ErrorMessageHandler.d.ts.map

package/dist/core/message/handlers/ErrorMessageHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorMessageHandler.d.ts","sourceRoot":"","sources":["../../../../src/core/message/handlers/ErrorMessageHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,kBAAkB;IACzD,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAOpC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB;CAyC/C"}

package/dist/core/message/handlers/ErrorMessageHandler.js

@@ -0,0 +1,49 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { PERSONA, ROLE } from '../types.js';
+/**
+ * Handler for error messages
+ * Processes metadata error messages indicating an error occurred
+ */
+export class ErrorMessageHandler extends BaseMessageHandler {
+    canHandle(message) {
+        return (message.persona === PERSONA.METADATA &&
+            message.role === ROLE.ERROR);
+    }
+    handle(message) {
+        const sessionId = message.sessionId;
+        const agentId = message.agentId;
+        const errorCode = message.messageData?.error_code;
+        // Build from object - metadata/system is the sender
+        const from = {
+            name: message.from || 'System',
+            isAi: false,
+        };
+        // Build to object - customer/client is the recipient
+        const to = {
+            name: message.to || 'Client',
+            isAi: false,
+        };
+        // Build message object with persona, role, content, and raw data
+        const messageObj = {
+            persona: message.persona,
+            role: message.role,
+            content: message.content,
+            raw: message.messageData || {},
+            ...(errorCode && { errorCode }),
+        };
+        // Build result in the required format
+        const result = {
+            type: 'error_message',
+            messageId: message.messageId,
+            timestamp: message.timestamp || Date.now(),
+            sessionId: sessionId,
+            agentId: agentId,
+            from: from,
+            to: to,
+            message: messageObj,
+            errorCode,
+        };
+        return result;
+    }
+}
+//# sourceMappingURL=ErrorMessageHandler.js.map

package/dist/core/message/handlers/ErrorMessageHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorMessageHandler.js","sourceRoot":"","sources":["../../../../src/core/message/handlers/ErrorMessageHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAE5C;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,kBAAkB;IACzD,SAAS,CAAC,OAAgB;QACxB,OAAO,CACL,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,QAAQ;YACpC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAC5B,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAgB;QACrB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC;QAElD,oDAAoD;QACpD,MAAM,IAAI,GAAG;YACX,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ;YAC9B,IAAI,EAAE,KAAK;SACZ,CAAC;QAEF,qDAAqD;QACrD,MAAM,EAAE,GAAG;YACT,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,QAAQ;YAC5B,IAAI,EAAE,KAAK;SACZ,CAAC;QAEF,iEAAiE;QACjE,MAAM,UAAU,GAAG;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;YAC9B,GAAG,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;SAChC,CAAC;QAEF,sCAAsC;QACtC,MAAM,MAAM,GAAyB;YACnC,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;YAC1C,SAAS,EAAE,SAAS;YACpB,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,IAAI;YACV,EAAE,EAAE,EAAE;YACN,OAAO,EAAE,UAAU;YACnB,SAAS;SACV,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}