@framers/agentos 0.1.126 → 0.1.127

package/dist/cognitive_substrate/ConversationHistoryManager.js

@@ -0,0 +1,320 @@
+/**
+ * @fileoverview Manages the GMI's internal conversation history, including
+ * adding new messages, trimming to size, building prompt-compatible snapshots,
+ * and converting between ChatMessage and ConversationMessage formats.
+ *
+ * Extracted from GMI.ts to isolate conversation state management from the
+ * core cognitive engine, reducing class complexity while preserving full
+ * feature parity.
+ *
+ * @module cognitive_substrate/ConversationHistoryManager
+ */
+import { createConversationMessage, MessageRole, } from '../core/conversation/ConversationMessage.js';
+import { GMIInteractionType, } from './IGMI.js';
+const DEFAULT_MAX_CONVERSATION_HISTORY_TURNS = 20;
+/**
+ * Encapsulates all conversation history state and operations for a GMI instance.
+ *
+ * Owns the mutable `ChatMessage[]` array and provides methods to append user/tool/system
+ * messages, trim to a configurable maximum, build `ConversationMessage[]` snapshots for
+ * prompt construction, and hydrate from a previously serialized conversation.
+ *
+ * Dependencies are injected via the constructor; no direct coupling to GMI internals.
+ */
+export class ConversationHistoryManager {
+    /**
+     * Creates a new ConversationHistoryManager.
+     *
+     * @param maxHistoryLength - Maximum number of messages to retain in the conversation
+     *   history window. When exceeded, the oldest messages are removed. Defaults to 20.
+     */
+    constructor(maxHistoryLength = DEFAULT_MAX_CONVERSATION_HISTORY_TURNS) {
+        this.maxHistoryLength = maxHistoryLength;
+        /** The mutable backing store for conversation messages. */
+        this.conversationHistory = [];
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns a readonly view of the current conversation history.
+     *
+     * The returned array reference is live (reflects mutations), but callers
+     * should not mutate it directly. Use the dedicated mutation methods instead.
+     */
+    get history() {
+        return this.conversationHistory;
+    }
+    /**
+     * Appends a new turn's messages to the conversation history and trims
+     * to the configured maximum length.
+     *
+     * Handles TEXT, MULTIMODAL_CONTENT, TOOL_RESPONSE, and SYSTEM_MESSAGE
+     * interaction types. For TOOL_RESPONSE, multiple results are each appended
+     * as separate tool-role messages.
+     *
+     * @param turnInput - The incoming turn input from the GMI turn processor.
+     * @param maxMessages - Optional override for the maximum history length
+     *   (used when the persona defines a custom limit at runtime).
+     */
+    update(turnInput, maxMessages) {
+        let messageToAdd = null;
+        switch (turnInput.type) {
+            case GMIInteractionType.TEXT:
+                messageToAdd = {
+                    role: 'user',
+                    content: turnInput.content,
+                    name: turnInput.metadata?.userName || turnInput.userId,
+                };
+                break;
+            case GMIInteractionType.MULTIMODAL_CONTENT:
+                messageToAdd = {
+                    role: 'user',
+                    content: turnInput.content,
+                    name: turnInput.metadata?.userName || turnInput.userId,
+                };
+                break;
+            case GMIInteractionType.TOOL_RESPONSE: {
+                const results = Array.isArray(turnInput.content)
+                    ? turnInput.content
+                    : [turnInput.content];
+                results.forEach(result => {
+                    this.conversationHistory.push({
+                        role: 'tool',
+                        tool_call_id: result.toolCallId,
+                        name: result.toolName,
+                        content: typeof result.output === 'string'
+                            ? result.output
+                            : JSON.stringify(result.output),
+                    });
+                });
+                break;
+            }
+            case GMIInteractionType.SYSTEM_MESSAGE:
+                messageToAdd = { role: 'system', content: turnInput.content };
+                break;
+        }
+        if (messageToAdd)
+            this.conversationHistory.push(messageToAdd);
+        const effectiveMax = maxMessages ?? this.maxHistoryLength;
+        if (this.conversationHistory.length > effectiveMax) {
+            const removeCount = this.conversationHistory.length - effectiveMax;
+            this.conversationHistory.splice(0, removeCount);
+        }
+    }
+    /**
+     * Appends a single tool-call result to the conversation history.
+     *
+     * Used after internal tool execution within the GMI's ReAct loop.
+     * Formats error results with a descriptive prefix so the LLM can
+     * distinguish success from failure.
+     *
+     * @param toolCallResult - The result from a tool execution.
+     */
+    updateWithToolResult(toolCallResult) {
+        this.conversationHistory.push({
+            role: 'tool',
+            tool_call_id: toolCallResult.toolCallId,
+            name: toolCallResult.toolName,
+            content: toolCallResult.isError
+                ? `Error from tool '${toolCallResult.toolName}': ${JSON.stringify(toolCallResult.errorDetails || toolCallResult.output)}`
+                : typeof toolCallResult.output === 'string'
+                    ? toolCallResult.output
+                    : JSON.stringify(toolCallResult.output),
+        });
+    }
+    /**
+     * Builds a `ConversationMessage[]` snapshot of the current history, suitable
+     * for injection into the PromptEngine's `PromptComponents`.
+     *
+     * Each ChatMessage is converted to the richer ConversationMessage format,
+     * preserving tool_calls, role mappings, and content normalization.
+     *
+     * @returns An array of ConversationMessage objects mirroring the current history.
+     */
+    buildForPrompt() {
+        return this.conversationHistory.map(msg => this.convertToConversationMessage(msg));
+    }
+    /**
+     * Replaces the entire conversation history by hydrating from a serialized
+     * `ConversationMessage[]` (e.g., loaded from persistent storage).
+     *
+     * Messages with roles ERROR or THOUGHT are silently dropped, as they have
+     * no ChatMessage equivalent. All others are converted to ChatMessage format.
+     *
+     * @param conversationHistory - The ConversationMessage array to hydrate from.
+     */
+    hydrate(conversationHistory) {
+        this.conversationHistory = conversationHistory
+            .map(message => this.convertToChatMessage(message))
+            .filter((message) => message !== null);
+    }
+    /**
+     * Converts a single ChatMessage (LLM-provider format) to a ConversationMessage
+     * (AgentOS internal format).
+     *
+     * Handles role mapping, content normalization, and tool_calls conversion
+     * (string arguments are parsed to objects).
+     *
+     * @param chatMsg - The ChatMessage to convert.
+     * @returns The equivalent ConversationMessage.
+     */
+    convertToConversationMessage(chatMsg) {
+        const conversationMessage = createConversationMessage(this.mapChatRoleToMessageRole(chatMsg.role), this.normalizeChatMessageContent(chatMsg.content), {
+            name: chatMsg.name,
+            tool_call_id: chatMsg.tool_call_id,
+        });
+        if (chatMsg.tool_calls && chatMsg.tool_calls.length > 0) {
+            conversationMessage.tool_calls = chatMsg.tool_calls
+                .filter(tc => !!tc?.function?.name)
+                .map(tc => ({
+                id: tc.id,
+                name: tc.function.name,
+                arguments: this.parseToolCallArguments(tc.function.arguments),
+            }));
+        }
+        return conversationMessage;
+    }
+    /**
+     * Converts a single ConversationMessage (AgentOS internal format) back to a
+     * ChatMessage (LLM-provider format).
+     *
+     * Messages with roles ERROR or THOUGHT return `null` as they have no
+     * meaningful ChatMessage representation. SUMMARY messages are prefixed
+     * with `[Conversation Summary]`.
+     *
+     * @param message - The ConversationMessage to convert.
+     * @returns The equivalent ChatMessage, or null if the role is not representable.
+     */
+    convertToChatMessage(message) {
+        if (message.role === MessageRole.ERROR || message.role === MessageRole.THOUGHT) {
+            return null;
+        }
+        const role = message.role === MessageRole.SYSTEM || message.role === MessageRole.SUMMARY
+            ? 'system'
+            : message.role === MessageRole.ASSISTANT
+                ? 'assistant'
+                : message.role === MessageRole.TOOL
+                    ? 'tool'
+                    : 'user';
+        const content = message.role === MessageRole.SUMMARY && typeof message.content === 'string'
+            ? `[Conversation Summary]\n${message.content}`
+            : this.normalizeConversationMessageContent(message.content);
+        return {
+            role,
+            content,
+            name: message.name,
+            tool_call_id: message.tool_call_id,
+            tool_calls: Array.isArray(message.tool_calls)
+                ? message.tool_calls.map(toolCall => ({
+                    id: toolCall.id,
+                    type: 'function',
+                    function: {
+                        name: toolCall.name,
+                        arguments: JSON.stringify(toolCall.arguments ?? {}),
+                    },
+                }))
+                : undefined,
+        };
+    }
+    /**
+     * Directly pushes a pre-built ChatMessage into the history.
+     *
+     * Used by the GMI's main processing loop to append the assistant's own
+     * response (including any tool_calls) after LLM streaming completes.
+     *
+     * @param message - The ChatMessage to push.
+     */
+    push(message) {
+        this.conversationHistory.push(message);
+    }
+    /**
+     * Resets the conversation history to an empty array.
+     * Used during re-initialization.
+     */
+    clear() {
+        this.conversationHistory = [];
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Maps a ChatMessage role string to the richer MessageRole enum.
+     *
+     * @param role - The ChatMessage role ('system' | 'user' | 'assistant' | 'tool').
+     * @returns The corresponding MessageRole enum value.
+     */
+    mapChatRoleToMessageRole(role) {
+        switch (role) {
+            case 'system':
+                return MessageRole.SYSTEM;
+            case 'assistant':
+                return MessageRole.ASSISTANT;
+            case 'tool':
+                return MessageRole.TOOL;
+            default:
+                return MessageRole.USER;
+        }
+    }
+    /**
+     * Normalizes ChatMessage content (which may be string, null, undefined, or an
+     * array of content parts) into ConversationMessage-compatible content.
+     *
+     * @param content - The raw ChatMessage content.
+     * @returns Normalized content suitable for a ConversationMessage.
+     */
+    normalizeChatMessageContent(content) {
+        if (typeof content === 'undefined') {
+            return null;
+        }
+        if (content === null || typeof content === 'string') {
+            return content;
+        }
+        if (Array.isArray(content)) {
+            return content.map(part => ({ ...part }));
+        }
+        return content;
+    }
+    /**
+     * Normalizes ConversationMessage content into ChatMessage-compatible content.
+     *
+     * @param content - The ConversationMessage content.
+     * @returns Normalized content suitable for a ChatMessage.
+     */
+    normalizeConversationMessageContent(content) {
+        if (content === null || typeof content === 'string') {
+            return content;
+        }
+        if (Array.isArray(content)) {
+            return content.map(part => ({ ...part }));
+        }
+        return JSON.stringify(content);
+    }
+    /**
+     * Safely parses tool call arguments from their raw form (string, object, or
+     * falsy) into a `Record<string, any>`.
+     *
+     * Falls back to an empty object on parse errors or unexpected types.
+     *
+     * @param args - The raw arguments value from a tool call.
+     * @returns A parsed arguments object.
+     */
+    parseToolCallArguments(args) {
+        if (!args) {
+            return {};
+        }
+        if (typeof args === 'string') {
+            try {
+                return JSON.parse(args);
+            }
+            catch {
+                return {};
+            }
+        }
+        if (typeof args === 'object') {
+            return args;
+        }
+        return {};
+    }
+}
+//# sourceMappingURL=ConversationHistoryManager.js.map

package/dist/cognitive_substrate/ConversationHistoryManager.js.map

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

package/dist/cognitive_substrate/GMI.d.ts

@@ -9,7 +9,7 @@
  * @see ./IGMI.ts for the interface definition.
  * @see ./personas/IPersonaDefinition.ts for persona structure.
  * @see ../core/tools/IToolOrchestrator.ts for tool orchestration.
- * @see ../core/ai_utilities/IUtilityAI.ts for utility functions.
+ * @see ../nlp/ai_utilities/IUtilityAI.ts for utility functions.
  */
 import { IGMI, GMIBaseConfig, GMITurnInput, GMIOutputChunk, GMIPrimeState, ReasoningTrace, GMIHealthReport, MemoryLifecycleEvent, LifecycleActionResponse, ToolCallResult, ToolResultPayload, GMIOutput } from './IGMI';
 import { IPersonaDefinition } from './personas/IPersonaDefinition';
@@ -39,12 +39,10 @@ export declare class GMI implements IGMI {
     private currentUserContext;
     private currentTaskContext;
     private reasoningTrace;
-    private conversationHistory;
-    private selfReflectionIntervalTurns;
-    private turnsSinceLastReflection;
-    private pendingGMIEvents;
-    private eventHistory;
-    private metaPromptTriggerCounters;
+    private conversationHistoryManager;
+    private memoryBridge;
+    private sentimentTracker;
+    private metapromptExecutor;
     /**
      * Constructs a GMI instance.
      * The GMI is not fully operational until `initialize` is called.
@@ -87,12 +85,7 @@ export declare class GMI implements IGMI {
      * @private
      */
     private addTraceEntry;
-    private getCurrentPadState;
     private stringifyTurnContent;
-    private buildMemoryTags;
-    private assembleCognitiveMemoryContext;
-    private encodeCognitiveMemory;
-    private syncCognitiveMemoryForTurn;
     private getConversationIdForTurn;
     private getOrganizationIdForTurn;
     private buildToolSessionData;
@@ -106,34 +99,12 @@ export declare class GMI implements IGMI {
      * @private
      */
     private createOutputChunk;
-    /**
-     * Updates the internal conversation history with new input.
-     * @private
-     */
-    private updateConversationHistory;
-    /**
-     * Adds a tool call result to the GMI's internal conversation history.
-     * @private
-     * @param {ToolCallResult} toolCallResult - The result from the tool execution.
-     */
-    private updateConversationHistoryWithToolResult;
-    /**
-     * Creates a conversation-history snapshot compatible with `PromptComponents`.
-     * @private
-     */
-    private buildConversationHistoryForPrompt;
-    private convertChatMessageToConversationMessage;
-    private convertConversationMessageToChatMessage;
-    private normalizeConversationMessageContent;
     hydrateConversationHistory(conversationHistory: ConversationMessage[]): void;
     hydrateTurnContext(context: {
         sessionId?: string;
         conversationId?: string;
         organizationId?: string;
     }): void;
-    private mapChatRoleToMessageRole;
-    private normalizeChatMessageContent;
-    private parseToolCallArguments;
     /**
      * Builds the PromptExecutionContext for the PromptEngine.
      * @private
@@ -147,6 +118,20 @@ export declare class GMI implements IGMI {
      * @returns {boolean} True if RAG should be triggered, false otherwise.
      */
     private shouldTriggerRAGRetrieval;
+    /**
+     * Determines the prompt format type based on model provider.
+     * @param modelDetails - Model metadata from the provider manager.
+     * @param providerId - The provider identifier.
+     * @returns The prompt format type string.
+     */
+    private determinePromptFormat;
+    /**
+     * Determines the tool calling format based on model provider.
+     * @param modelDetails - Model metadata from the provider manager.
+     * @param providerId - The provider identifier.
+     * @returns The tool format string.
+     */
+    private determineToolFormat;
     /** @inheritdoc */
     processTurnStream(turnInput: GMITurnInput): AsyncGenerator<GMIOutputChunk, GMIOutput, undefined>;
     /** @inheritdoc */
@@ -158,142 +143,6 @@ export declare class GMI implements IGMI {
      * @private
      */
     private performPostTurnIngestion;
-    /**
-     * Analyzes sentiment of user input and updates sentiment history.
-     * Triggers event detection based on sentiment patterns.
-     *
-     * @param turnId - Current turn identifier
-     * @param userInput - User's input text
-     * @private
-     */
-    private analyzeTurnSentiment;
-    /**
-     * Detects emotional patterns and emits appropriate GMI events.
-     *
-     * @param turnId - Current turn identifier
-     * @param userInput - User's input text
-     * @param sentimentResult - Sentiment analysis result
-     * @param sentimentHistory - Historical sentiment data
-     * @private
-     */
-    private detectAndEmitEvents;
-    /**
-     * Emits a GMI event and stores it in event history.
-     *
-     * @param event - The event to emit
-     * @private
-     */
-    private emitEvent;
-    /**
-     * Checks all metaprompt triggers (turn_interval, event_based, manual) and executes triggered ones.
-     *
-     * @param turnId - Current turn identifier
-     * @private
-     */
-    private checkAndTriggerMetaprompts;
-    /**
-     * Gets the turn counter for a specific metaprompt.
-     *
-     * @param metapromptId - Metaprompt identifier
-     * @returns Current counter value
-     * @private
-     */
-    private getMetapromptTurnCounter;
-    /**
-     * Increments the turn counter for a specific metaprompt.
-     *
-     * @param metapromptId - Metaprompt identifier
-     * @private
-     */
-    private incrementMetapromptTurnCounter;
-    /**
-     * Resets the turn counter for a specific metaprompt to zero.
-     *
-     * @param metapromptId - Metaprompt identifier
-     * @private
-     */
-    private resetMetapromptTurnCounter;
-    /**
-     * Executes multiple metaprompts in parallel or sequence.
-     * Replaces the single-metaprompt _triggerAndProcessSelfReflection().
-     *
-     * @param metaPrompts - Array of metaprompts to execute
-     * @private
-     */
-    private executeMetaprompts;
-    /**
-     * Routes a metaprompt to its appropriate handler based on ID.
-     *
-     * @param metaPrompt - Metaprompt definition to execute
-     * @private
-     */
-    private executeMetapromptHandler;
-    /**
-     * Handler for trait adjustment metaprompt (existing self-reflection logic).
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleTraitAdjustment;
-    /**
-     * Handler for frustration recovery metaprompt.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleFrustrationRecovery;
-    /**
-     * Handler for confusion clarification metaprompt.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleConfusionClarification;
-    /**
-     * Handler for satisfaction reinforcement metaprompt.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleSatisfactionReinforcement;
-    /**
-     * Handler for error recovery metaprompt.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleErrorRecovery;
-    /**
-     * Handler for engagement boost metaprompt.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleEngagementBoost;
-    /**
-     * Generic handler for custom metaprompts not in the preset list.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @private
-     */
-    private handleGenericMetaprompt;
-    /**
-     * Executes a metaprompt with variable substitution.
-     *
-     * @param metaPrompt - Metaprompt definition
-     * @param variables - Variables to substitute in the template
-     * @returns Parsed JSON response from LLM
-     * @private
-     */
-    private executeMetapromptWithVariables;
-    /**
-     * Applies metaprompt updates to GMI state (mood, user skill, task complexity, memory).
-     *
-     * @param updates - Parsed updates from metaprompt response
-     * @param metapromptId - ID of the metaprompt that generated these updates
-     * @private
-     */
-    private applyMetapromptUpdates;
     /** @inheritdoc */
     _triggerAndProcessSelfReflection(): Promise<void>;
     /**

package/dist/cognitive_substrate/GMI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GMI.d.ts","sourceRoot":"","sources":["../../src/cognitive_substrate/GMI.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GMI.d.ts","sourceRoot":"","sources":["../../src/cognitive_substrate/GMI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,IAAI,EACJ,aAAa,EACb,YAAY,EACZ,cAAc,EAEd,aAAa,EAIb,cAAc,EAGd,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EAIvB,cAAc,EACd,iBAAiB,EACjB,SAAS,EAIV,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,kBAAkB,EAEnB,MAAM,+BAA+B,CAAC;AAavC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAE/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAWnF;;;;;GAKG;AACH,qBAAa,GAAI,YAAW,IAAI;IAC9B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,iBAAiB,EAAE,IAAI,CAAC;IAExC,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,MAAM,CAAiB;IAG/B,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,kBAAkB,CAAC,CAAsB;IACjD,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,kBAAkB,CAA0B;IACpD,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,eAAe,CAAC,CAA0B;IAGlD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,kBAAkB,CAAe;IACzC,OAAO,CAAC,kBAAkB,CAAe;IACzC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,0BAA0B,CAA8B;IAKhE,OAAO,CAAC,YAAY,CAAsC;IAG1D,OAAO,CAAC,gBAAgB,CAAoB;IAG5C,OAAO,CAAC,kBAAkB,CAAsB;IAEhD;;;;OAIG;gBACS,KAAK,CAAC,EAAE,MAAM;IAY1B;;OAEG;IACU,UAAU,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAmH1F;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAiBpC;;;OAGG;YACW,6BAA6B;IA6C3C,kBAAkB;IACX,UAAU,IAAI,kBAAkB;IAOvC,kBAAkB;IACX,0BAA0B,IAAI,MAAM;IAO3C,kBAAkB;IACX,QAAQ,IAAI,MAAM;IAEzB,kBAAkB;IACX,eAAe,IAAI,aAAa;IAEvC,kBAAkB;IACX,iBAAiB,IAAI,QAAQ,CAAC,cAAc,CAAC;IAIpD,kBAAkB;IACL,wBAAwB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAIrE,kBAAkB;IACX,yBAAyB,IAAI,uBAAuB,GAAG,SAAS;IAIvE;;;OAGG;IACH,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,wBAAwB;IAahC,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,oBAAoB;IAmB5B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAiBnB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAclB,0BAA0B,CAAC,mBAAmB,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAI5E,kBAAkB,CAAC,OAAO,EAAE;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,IAAI;IAYR;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAmBnC;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAuBjC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAU3B,kBAAkB;IAEJ,iBAAiB,CAAC,SAAS,EAAE,YAAY,GAAG,cAAc,CAAC,cAAc,EAAE,SAAS,EAAE,SAAS,CAAC;IAyb9G,kBAAkB;IACL,gBAAgB,CAC3B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,iBAAiB,EAChC,MAAM,EAAE,MAAM,GAEb,OAAO,CAAC,SAAS,CAAC;IAerB,kBAAkB;IACL,iBAAiB,CAC5B,WAAW,EAAE,cAAc,EAAE,EAC7B,OAAO,EAAE,MAAM,GAEd,OAAO,CAAC,SAAS,CAAC;IA6HrB;;;OAGG;YACW,wBAAwB;IA0DtC,kBAAkB;IACL,gCAAgC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9D;;;OAGG;IACH,OAAO,CAAC,6BAA6B;IA2CrC,kBAAkB;IACL,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAyBlG,kBAAkB;IACL,4BAA4B,IAAI,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IAiBrF,kBAAkB;IACL,gBAAgB,IAAI,OAAO,CAAC,eAAe,CAAC;IA6CzD,kBAAkB;IACL,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAwBvC"}