@nexus-cortex/core 4.26.0

package/dist/middleware/MentorshipMiddleware.js

@@ -0,0 +1,427 @@
+/**
+ * Mentorship Middleware
+ *
+ * Implements reactive mentorship system that:
+ * - Detects error patterns from tool execution results
+ * - Tracks recurring errors with timestamps and counts
+ * - Triggers mentorship guidance based on patterns
+ * - Injects thinking blocks into assistant responses
+ * - Maintains session-isolated pattern storage
+ *
+ * Extracted from CortexOrchestrator.ts as part of parallel refactor (Wave 1, Agent 4)
+ *
+ * @version 1.0.0
+ * @author Agent 4
+ */
+/**
+ * Error severity classification
+ * @internal - Reserved for future severity-based mentorship
+ */
+// type ErrorSeverity = 'low' | 'medium' | 'high';
+/**
+ * MentorshipMiddleware
+ *
+ * Provides intelligent error pattern detection and mentorship guidance injection.
+ * Maintains separate error pattern tracking for each session to ensure isolation.
+ *
+ * Key Features:
+ * - Session-scoped error pattern storage
+ * - Intelligent pattern matching (normalizes numbers, quotes)
+ * - Severity-based triggering (high/medium/low)
+ * - Thinking block injection with guidance
+ * - Pattern count tracking with timestamps
+ *
+ * @example
+ * ```typescript
+ * const mentorship = new MentorshipMiddleware();
+ *
+ * // Check if error should trigger mentorship
+ * if (mentorship.shouldTriggerMentorship(toolResult, context)) {
+ *   // Generate and inject guidance
+ * }
+ *
+ * // Track error patterns
+ * mentorship.trackErrorPattern(error, 'bash_execute');
+ *
+ * // Get patterns for analysis
+ * const patterns = mentorship.getErrorPatterns(sessionId);
+ * ```
+ */
+/** Threshold for sequential tool call nudges */
+const SEQUENTIAL_TOOL_CALL_THRESHOLD = 3;
+export class MentorshipMiddleware {
+    /**
+     * Error patterns stored per session
+     * Outer Map: sessionId -> Inner Map
+     * Inner Map: pattern string -> ErrorPattern
+     */
+    errorPatterns = new Map();
+    /** Sequential tool call counts per session (for CodeExecute nudges) */
+    sequentialCallCounts = new Map();
+    /**
+     * High severity error patterns (always trigger on 'high' threshold)
+     */
+    highSeverityPatterns = [
+        'permission denied',
+        'access denied',
+        'eacces',
+        'fatal',
+        'critical',
+        'cannot',
+        'failed to',
+        'unable to'
+    ];
+    /**
+     * Medium severity error patterns
+     */
+    mediumSeverityPatterns = [
+        'error',
+        'exception',
+        'not found',
+        'enoent',
+        'invalid',
+        'timeout'
+    ];
+    /**
+     * Check if a tool result should trigger mentorship
+     *
+     * Evaluates:
+     * 1. Is mentorship enabled in config?
+     * 2. Is error triggering enabled?
+     * 3. Is this an error result?
+     * 4. Does error meet severity threshold?
+     *
+     * @param toolResult - Tool execution result with error status
+     * @param context - Middleware context with configuration
+     * @returns true if mentorship should be triggered
+     */
+    shouldTriggerMentorship(toolResult, context) {
+        // Check if mentorship is enabled
+        if (!context.config.reactiveMentorship?.enabled ||
+            !context.config.reactiveMentorship?.triggerOnError) {
+            return false;
+        }
+        // Must be an error
+        if (!toolResult.is_error) {
+            return false;
+        }
+        // Apply severity threshold
+        const threshold = context.config.reactiveMentorship.errorSeverityThreshold || 'medium';
+        const errorContent = toolResult.content.toLowerCase();
+        // Check high severity
+        const isHighSeverity = this.highSeverityPatterns.some(pattern => errorContent.includes(pattern));
+        if (threshold === 'high' && !isHighSeverity) {
+            return false;
+        }
+        // Check medium severity
+        const isMediumSeverity = this.mediumSeverityPatterns.some(pattern => errorContent.includes(pattern));
+        if (threshold === 'medium' && !isHighSeverity && !isMediumSeverity) {
+            return false;
+        }
+        // Low severity: trigger on any error
+        return true;
+    }
+    /**
+     * Track an error pattern for pattern detection
+     *
+     * Extracts a normalized pattern from the error and tracks:
+     * - Occurrence count
+     * - First seen timestamp
+     * - Last seen timestamp
+     *
+     * Pattern normalization:
+     * - Takes first 100 characters
+     * - Replaces numbers with 'N' (e.g., "port 3000" -> "port N")
+     * - Removes quotes
+     * - Converts to lowercase
+     *
+     * @param error - Error object or message string
+     * @param toolName - Name of the tool that generated the error
+     */
+    trackErrorPattern(error, toolName) {
+        // Extract error message
+        const errorMessage = typeof error === 'string'
+            ? error
+            : error?.message || error?.toString() || 'Unknown error';
+        // Extract normalized pattern
+        const pattern = this.extractErrorPattern(errorMessage);
+        // Get session-specific pattern storage
+        // Note: We use toolName as a proxy for sessionId in standalone mode
+        // In production, this would be injected via context
+        const sessionId = toolName; // Simplified for middleware isolation
+        if (!this.errorPatterns.has(sessionId)) {
+            this.errorPatterns.set(sessionId, new Map());
+        }
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        // Update or create pattern entry
+        const existingPattern = sessionPatterns.get(pattern);
+        const now = new Date();
+        if (existingPattern) {
+            // Update existing pattern
+            existingPattern.count += 1;
+            existingPattern.lastSeen = now;
+        }
+        else {
+            // Create new pattern entry
+            sessionPatterns.set(pattern, {
+                pattern,
+                count: 1,
+                firstSeen: now,
+                lastSeen: now
+            });
+        }
+    }
+    /**
+     * Extract normalized error pattern from error message
+     *
+     * Normalization strategy:
+     * - Truncate to 100 chars (focus on error type, not specifics)
+     * - Replace all numbers with 'N' (generalize)
+     * - Remove quotes (normalize formatting)
+     * - Lowercase (case-insensitive matching)
+     *
+     * Examples:
+     * - "Error on line 42" -> "error on line n"
+     * - "Port 3000 in use" -> "port n in use"
+     * - 'File "test.js" not found' -> "file test.js not found"
+     *
+     * @param errorMessage - Raw error message
+     * @returns Normalized pattern string
+     */
+    // R12 (Cortex finding): compiled two regex literals per call. Hoisted to
+    // static fields (global-flag regexes are safe to reuse across `.replace`).
+    static NUMBER_REGEX = /[0-9]+/g;
+    static QUOTE_REGEX = /['"]/g;
+    extractErrorPattern(errorMessage) {
+        return errorMessage
+            .substring(0, 100)
+            .replace(MentorshipMiddleware.NUMBER_REGEX, 'N') // Replace numbers
+            .replace(MentorshipMiddleware.QUOTE_REGEX, '') // Remove quotes
+            .toLowerCase(); // Normalize case
+    }
+    /**
+     * Handle detected error pattern
+     *
+     * Called when a pattern reaches the detection threshold.
+     * Responsibilities:
+     * - Log pattern detection
+     * - Coordinate with helper model for guidance generation
+     * - Inject thinking block with guidance
+     *
+     * Note: In standalone middleware, this is a coordination point.
+     * Actual guidance generation happens in HelperModelMiddleware.
+     *
+     * @param pattern - Detected error pattern
+     * @param context - Middleware context
+     */
+    async handlePatternDetection(pattern, context) {
+        // Get pattern details
+        const sessionPatterns = this.errorPatterns.get(context.sessionId);
+        const errorPattern = sessionPatterns?.get(pattern);
+        if (!errorPattern) {
+            return; // Pattern not found, nothing to do
+        }
+        // Log pattern detection (if debug enabled)
+        if (context.config.debug) {
+            console.log(`[MentorshipMiddleware] Pattern detected: "${pattern}" ` +
+                `(count: ${errorPattern.count}, session: ${context.sessionId})`);
+        }
+        // In production, this would coordinate with HelperModelMiddleware
+        // to generate guidance and then inject thinking block
+        // For now, we track that pattern detection occurred
+    }
+    /**
+     * Inject thinking block into response
+     *
+     * Creates a thinking block with mentorship guidance and injects it
+     * into the assistant's response. The thinking block format depends
+     * on the model's expectations.
+     *
+     * Thinking block format:
+     * ```
+     * {
+     *   type: 'thinking',
+     *   thinking: ' **AI Mentor Insight**\n\n[guidance]'
+     * }
+     * ```
+     *
+     * @param response - Assistant response to modify
+     * @param guidance - Mentorship guidance to inject
+     * @returns Modified response with thinking block
+     */
+    injectThinkingBlock(response, guidance) {
+        // Handle different response formats
+        if (!response) {
+            return response;
+        }
+        // If response has content array, inject thinking block
+        if (response.content && Array.isArray(response.content)) {
+            // Create thinking block
+            const thinkingBlock = {
+                type: 'thinking',
+                thinking: ` **AI Mentor Insight**\n\n${guidance}`
+            };
+            // Inject at beginning of content
+            return {
+                ...response,
+                content: [thinkingBlock, ...response.content]
+            };
+        }
+        // If response is string content, wrap in array with thinking block
+        if (typeof response.content === 'string') {
+            return {
+                ...response,
+                content: [
+                    {
+                        type: 'thinking',
+                        thinking: ` **AI Mentor Insight**\n\n${guidance}`
+                    },
+                    {
+                        type: 'text',
+                        text: response.content
+                    }
+                ]
+            };
+        }
+        // Return unmodified if format not recognized
+        return response;
+    }
+    /**
+     * Get all error patterns for a session
+     *
+     * Returns error patterns tracked for the specified session.
+     * Patterns are sorted by count (descending) for analysis.
+     *
+     * @param sessionId - Session identifier
+     * @returns Array of error patterns for the session
+     */
+    getErrorPatterns(sessionId) {
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        if (!sessionPatterns) {
+            return [];
+        }
+        // Convert map to array and sort by count (descending)
+        return Array.from(sessionPatterns.values())
+            .sort((a, b) => b.count - a.count);
+    }
+    /**
+     * Clear all patterns for a session
+     *
+     * Removes all tracked error patterns for the specified session.
+     * Useful for:
+     * - Session cleanup
+     * - Testing
+     * - Manual pattern reset after intervention
+     *
+     * @param sessionId - Session identifier
+     */
+    clearPatterns(sessionId) {
+        this.errorPatterns.delete(sessionId);
+    }
+    /**
+     * Check if pattern has reached detection threshold
+     *
+     * Used internally to determine when to trigger pattern detection.
+     *
+     * @param pattern - Pattern to check
+     * @param sessionId - Session identifier
+     * @param threshold - Detection threshold (default: 3)
+     * @returns true if pattern count >= threshold
+     */
+    hasReachedThreshold(pattern, sessionId, threshold = 3) {
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        if (!sessionPatterns) {
+            return false;
+        }
+        const errorPattern = sessionPatterns.get(pattern);
+        return errorPattern ? errorPattern.count >= threshold : false;
+    }
+    /**
+     * Reset pattern count after intervention
+     *
+     * Called after mentorship guidance is provided to prevent
+     * repeated interventions for the same pattern.
+     *
+     * @param pattern - Pattern to reset
+     * @param sessionId - Session identifier
+     */
+    resetPatternCount(pattern, sessionId) {
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        if (!sessionPatterns) {
+            return;
+        }
+        const errorPattern = sessionPatterns.get(pattern);
+        if (errorPattern) {
+            errorPattern.count = 0;
+            errorPattern.lastSeen = new Date();
+        }
+    }
+    /**
+     * Get total error count for a session
+     *
+     * Utility method for monitoring and analytics.
+     *
+     * @param sessionId - Session identifier
+     * @returns Total number of errors tracked in session
+     */
+    getTotalErrorCount(sessionId) {
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        if (!sessionPatterns) {
+            return 0;
+        }
+        return Array.from(sessionPatterns.values())
+            .reduce((total, pattern) => total + pattern.count, 0);
+    }
+    /**
+     * Get unique pattern count for a session
+     *
+     * Returns the number of distinct error patterns encountered.
+     *
+     * @param sessionId - Session identifier
+     * @returns Number of unique patterns
+     */
+    getUniquePatternCount(sessionId) {
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        return sessionPatterns ? sessionPatterns.size : 0;
+    }
+    /**
+     * Check if session has any patterns
+     *
+     * @param sessionId - Session identifier
+     * @returns true if session has tracked patterns
+     */
+    hasPatterns(sessionId) {
+        const sessionPatterns = this.errorPatterns.get(sessionId);
+        return sessionPatterns ? sessionPatterns.size > 0 : false;
+    }
+    /**
+     * Check sequential tool calls and nudge toward CodeExecute.
+     *
+     * When a non-PTC model makes 3+ sequential tool calls that could be
+     * batched, returns a nudge suggesting CodeExecute for efficiency.
+     *
+     * @param sessionId - Session identifier
+     * @param _toolName - Name of the tool just called (reserved for future filtering)
+     * @param enableLocalCodeExecution - Whether local code execution is available
+     * @returns Nudge string if threshold reached, null otherwise
+     */
+    checkSequentialToolCalls(sessionId, _toolName, enableLocalCodeExecution) {
+        const count = (this.sequentialCallCounts.get(sessionId) ?? 0) + 1;
+        this.sequentialCallCounts.set(sessionId, count);
+        if (count >= SEQUENTIAL_TOOL_CALL_THRESHOLD && enableLocalCodeExecution) {
+            this.sequentialCallCounts.set(sessionId, 0);
+            return `You've made ${count} sequential tool calls. Consider using CodeExecute to chain operations and reduce round-trips.`;
+        }
+        return null;
+    }
+    /**
+     * Reset sequential call counter for a session.
+     * Call at the start of each user turn.
+     *
+     * @param sessionId - Session identifier
+     */
+    resetSequentialCalls(sessionId) {
+        this.sequentialCallCounts.delete(sessionId);
+    }
+}
+//# sourceMappingURL=MentorshipMiddleware.js.map

package/dist/middleware/MentorshipMiddleware.js.map

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

package/dist/middleware/PermissionsMiddleware.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Permissions Middleware
+ *
+ * Central authorization layer for tool execution. Evaluates permission
+ * policies before allowing tools to execute, handles approval requests,
+ * and maintains audit logs.
+ *
+ * Features:
+ * - Policy-based authorization
+ * - Priority-ordered policy evaluation
+ * - Approval flow for dangerous operations
+ * - Comprehensive audit logging
+ * - Session-based permission tracking
+ *
+ * @module middleware/PermissionsMiddleware
+ */
+import type { IPermissionsChecker, PermissionDecision, PermissionContext, PermissionAuditEntry, PermissionPolicy, ApprovalHandler, MiddlewareContext } from './contracts/MiddlewareContracts.js';
+import { PermissionAuditLogger } from './permissions/PermissionAuditLogger.js';
+/**
+ * Options for permissions middleware
+ */
+export interface PermissionsMiddlewareOptions {
+    /**
+     * Initial policies to register
+     */
+    policies?: PermissionPolicy[];
+    /**
+     * Approval handler for denied operations
+     */
+    approvalHandler?: ApprovalHandler;
+    /**
+     * Audit logger for permission decisions
+     */
+    auditLogger?: PermissionAuditLogger;
+    /**
+     * Default policy when no policies match
+     * @default 'deny'
+     */
+    defaultPolicy?: 'allow' | 'deny';
+    /**
+     * Whether to enable debug logging
+     * @default false
+     */
+    enableLogging?: boolean;
+    /**
+     * When true, every permission check returns `{ allowed: true }` without
+     * consulting policies or approval handlers. Used by YOLO mode to make a
+     * clean bypass that hard-deny policies (e.g. WhitelistPolicy with
+     * `canApprove: false`) cannot otherwise short-circuit.
+     *
+     * @default false
+     */
+    bypassAll?: boolean;
+}
+/**
+ * Permissions middleware implementation
+ *
+ * @example
+ * ```typescript
+ * const middleware = new PermissionsMiddleware({
+ *   policies: [
+ *     new WhitelistPolicy(['read_file', 'write_file']),
+ *     new FileOperationPolicy({
+ *       allowedPaths: ['/workspace'],
+ *       blockedPaths: ['/etc', '/root']
+ *     }),
+ *     new BashCommandPolicy({
+ *       allowedCommands: [],
+ *       blockedCommands: ['rm -rf /']
+ *     })
+ *   ],
+ *   approvalHandler: new CLIApprovalHandler(),
+ *   auditLogger: new PermissionAuditLogger('/path/to/audit.log')
+ * });
+ *
+ * const decision = await middleware.checkPermission(
+ *   'read_file',
+ *   { file_path: '/workspace/file.txt' },
+ *   context
+ * );
+ * ```
+ */
+export declare class PermissionsMiddleware implements IPermissionsChecker {
+    private evaluator;
+    private approvalHandler?;
+    private auditLogger?;
+    private enableLogging;
+    private bypassAll;
+    private sessionAuditCache;
+    /**
+     * Create a new permissions middleware
+     *
+     * @param options Middleware options
+     */
+    constructor(options?: PermissionsMiddlewareOptions);
+    /**
+     * Check permission for a tool execution
+     *
+     * @param toolName The name of the tool to execute
+     * @param toolInput The input parameters for the tool
+     * @param context The middleware context
+     * @returns Permission decision with reason if denied
+     */
+    checkPermission(toolName: string, toolInput: any, context: MiddlewareContext, signal?: AbortSignal): Promise<PermissionDecision>;
+    /**
+     * Request approval for a denied operation
+     *
+     * @param context The permission context
+     * @param reason The reason for denial
+     * @returns True if approved, false otherwise
+     */
+    requestApproval(context: PermissionContext, reason: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Register a permission policy
+     *
+     * @param policy The policy to register
+     */
+    registerPolicy(policy: PermissionPolicy): void;
+    /**
+     * Unregister a permission policy
+     *
+     * @param policyName The name of the policy to unregister
+     * @returns True if the policy was found and removed
+     */
+    unregisterPolicy(policyName: string): boolean;
+    /**
+     * Get all registered policies
+     */
+    getPolicies(): ReadonlyArray<PermissionPolicy>;
+    /**
+     * Get audit log entries for a session
+     *
+     * @param sessionId The session ID to query
+     * @returns Array of audit entries for the session
+     */
+    getAuditLog(sessionId: string): PermissionAuditEntry[];
+    /**
+     * Get audit log entries from persistent storage
+     *
+     * @param sessionId The session ID to query
+     * @returns Array of audit entries from storage
+     */
+    getAuditLogFromStorage(sessionId: string): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get all denied operations across all sessions
+     */
+    getAllDeniedOperations(): Promise<PermissionAuditEntry[]>;
+    /**
+     * Get audit statistics
+     */
+    getStatistics(): Promise<{
+        totalEntries: number;
+        allowedCount: number;
+        deniedCount: number;
+        approvalRequestCount: number;
+        approvalGrantedCount: number;
+        uniqueSessions: number;
+        uniqueTools: Set<string>;
+    } | null>;
+    /**
+     * Clear audit cache for a session
+     *
+     * @param sessionId The session ID to clear
+     */
+    clearSessionCache(sessionId: string): void;
+    /**
+     * Log a permission decision
+     */
+    private logDecision;
+    /**
+     * Close the middleware and cleanup resources
+     */
+    close(): Promise<void>;
+    /**
+     * Set the approval handler (for switching to YOLO mode)
+     *
+     * @param handler - The new approval handler
+     */
+    setApprovalHandler(handler: ApprovalHandler | undefined): void;
+    /**
+     * Get the current approval handler
+     */
+    getApprovalHandler(): ApprovalHandler | undefined;
+    /**
+     * Create a default permissions middleware with common policies
+     *
+     * @param workspacePath The workspace path to allow
+     * @param auditLogPath Optional path to audit log file
+     * @returns Configured permissions middleware
+     */
+    static createDefault(workspacePath: string, auditLogPath?: string): Promise<PermissionsMiddleware>;
+}
+//# sourceMappingURL=PermissionsMiddleware.d.ts.map

package/dist/middleware/PermissionsMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionsMiddleware.d.ts","sourceRoot":"","sources":["../../src/middleware/PermissionsMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAE9B;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;OAEG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;IAEpC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAEjC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,qBAAsB,YAAW,mBAAmB;IAC/D,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,WAAW,CAAC,CAAwB;IAC5C,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,SAAS,CAAU;IAG3B,OAAO,CAAC,iBAAiB,CAAkD;IAE3E;;;;OAIG;gBACS,OAAO,GAAE,4BAAiC;IAmBtD;;;;;;;OAOG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,GAAG,EACd,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,CAAC;IA4G9B;;;;;;OAMG;IACG,eAAe,CACnB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC;IAkBnB;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAI9C;;;;;OAKG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI7C;;OAEG;IACH,WAAW,IAAI,aAAa,CAAC,gBAAgB,CAAC;IAI9C;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAKtD;;;;;OAKG;IACG,sBAAsB,CAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAQlC;;OAEG;IACG,sBAAsB,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAQ/D;;OAEG;IACG,aAAa;;;;;;;;;IAQnB;;;;OAIG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;YACW,WAAW;IAkCzB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI;IAI9D;;OAEG;IACH,kBAAkB,IAAI,eAAe,GAAG,SAAS;IAIjD;;;;;;OAMG;WACU,aAAa,CACxB,aAAa,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,qBAAqB,CAAC;CAiClC"}