@bradygaster/squad-sdk 0.7.0 → 0.8.2

package/dist/runtime/event-bus.js

@@ -0,0 +1,218 @@
+/**
+ * Cross-Session Event Bus (M0-5, Issue #77)
+ *
+ * Pub/sub event bus for session lifecycle events with cross-session aggregation.
+ * Enables the coordinator to observe all agent sessions from a single subscription point.
+ * Decouples event producers (sessions) from consumers (coordinator, Ralph, UI).
+ *
+ * @module runtime/event-bus
+ */
+// ============================================================================
+// Event Bus Implementation
+// ============================================================================
+/**
+ * Cross-session event aggregation bus.
+ *
+ * Key features:
+ * - Subscribe to specific event types or all events
+ * - Async/sync handler support with error isolation
+ * - No race conditions — handlers run in subscription order
+ * - Lifecycle events: session:created, session:idle, session:error, session:destroyed
+ * - Cross-session aggregation — single subscription point for all sessions
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to specific event
+ * const unsubscribe = bus.subscribe('session:created', (event) => {
+ *   console.log('New session:', event.sessionId);
+ * });
+ *
+ * // Subscribe to all events
+ * const unsubscribeAll = bus.subscribeAll((event) => {
+ *   console.log('Event:', event.type);
+ * });
+ *
+ * // Emit event
+ * await bus.emit({
+ *   type: 'session:created',
+ *   sessionId: 'abc-123',
+ *   agentName: 'Ralph',
+ *   payload: { model: 'claude-sonnet-4.5' },
+ *   timestamp: new Date()
+ * });
+ *
+ * // Clean up
+ * unsubscribe();
+ * unsubscribeAll();
+ * ```
+ */
+export class EventBus {
+    handlers = new Map();
+    allHandlers = new Set();
+    errorHandlers = new Set();
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param type - Event type to listen for
+     * @param handler - Handler function to call when event occurs
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribe('session:created', (event) => {
+     *   console.log('Session created:', event.sessionId);
+     * });
+     *
+     * // Later, remove subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribe(type, handler) {
+        if (!this.handlers.has(type)) {
+            this.handlers.set(type, new Set());
+        }
+        this.handlers.get(type).add(handler);
+        return () => this.unsubscribe(type, handler);
+    }
+    /**
+     * Subscribe to all events regardless of type.
+     * Useful for logging, monitoring, or debugging.
+     *
+     * @param handler - Handler function to call for every event
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```typescript
+     * const bus = new EventBus();
+     * const unsubscribe = bus.subscribeAll((event) => {
+     *   console.log(`[${event.type}] ${event.sessionId || 'global'}`);
+     * });
+     * ```
+     */
+    subscribeAll(handler) {
+        this.allHandlers.add(handler);
+        return () => this.allHandlers.delete(handler);
+    }
+    /**
+     * Unsubscribe a handler from a specific event type.
+     *
+     * @param type - Event type to unsubscribe from
+     * @param handler - Handler function to remove
+     */
+    unsubscribe(type, handler) {
+        this.handlers.get(type)?.delete(handler);
+        // Clean up empty handler sets
+        if (this.handlers.get(type)?.size === 0) {
+            this.handlers.delete(type);
+        }
+    }
+    /**
+     * Register an error handler for handler execution failures.
+     * Error handlers are called when a subscribed handler throws an error.
+     *
+     * @param handler - Error handler function
+     * @returns Unsubscribe function to remove this error handler
+     */
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    /**
+     * Emit an event to all matching subscribers.
+     * Handlers are called in subscription order with error isolation.
+     * One handler failure does not prevent other handlers from executing.
+     *
+     * @param event - Event to emit
+     * @returns Promise that resolves when all handlers complete
+     *
+     * @example
+     * ```typescript
+     * await bus.emit({
+     *   type: 'session:created',
+     *   sessionId: 'abc-123',
+     *   agentName: 'Ralph',
+     *   payload: { model: 'claude-sonnet-4.5' },
+     *   timestamp: new Date()
+     * });
+     * ```
+     */
+    async emit(event) {
+        const typeHandlers = this.handlers.get(event.type) ?? new Set();
+        const allPromises = [];
+        // Execute type-specific handlers
+        for (const handler of typeHandlers) {
+            allPromises.push(this.executeHandler(handler, event));
+        }
+        // Execute wildcard handlers
+        for (const handler of this.allHandlers) {
+            allPromises.push(this.executeHandler(handler, event));
+        }
+        // Wait for all handlers to complete
+        // Errors are isolated and won't throw from here
+        await Promise.all(allPromises);
+    }
+    /**
+     * Execute a single handler with error isolation.
+     * Catches and reports handler errors without propagating them.
+     *
+     * @param handler - Handler function to execute
+     * @param event - Event to pass to handler
+     */
+    async executeHandler(handler, event) {
+        try {
+            const result = handler(event);
+            if (result instanceof Promise) {
+                await result;
+            }
+        }
+        catch (error) {
+            // Isolate handler errors — one failure shouldn't crash others
+            const wrappedError = error instanceof Error ? error : new Error(String(error));
+            // Notify error handlers
+            for (const errorHandler of this.errorHandlers) {
+                try {
+                    errorHandler(wrappedError, event);
+                }
+                catch (errorHandlerError) {
+                    // Error handler itself failed — log to console as last resort
+                    console.error('EventBus error handler failed:', errorHandlerError);
+                }
+            }
+            // If no error handlers registered, log to console
+            if (this.errorHandlers.size === 0) {
+                console.error(`EventBus handler error for ${event.type}:`, wrappedError);
+            }
+        }
+    }
+    /**
+     * Remove all handlers and reset the event bus.
+     * Useful for cleanup in tests or when shutting down.
+     */
+    clear() {
+        this.handlers.clear();
+        this.allHandlers.clear();
+        this.errorHandlers.clear();
+    }
+    /**
+     * Get count of handlers for a specific event type.
+     * Useful for debugging and testing.
+     *
+     * @param type - Event type to count handlers for
+     * @returns Number of handlers subscribed to this event type
+     */
+    getHandlerCount(type) {
+        return this.handlers.get(type)?.size ?? 0;
+    }
+    /**
+     * Get count of wildcard handlers.
+     *
+     * @returns Number of handlers subscribed to all events
+     */
+    getAllHandlerCount() {
+        return this.allHandlers.size;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/runtime/event-bus.js.map

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

package/dist/runtime/event-payloads.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Typed Event Payloads for SquadEventType (Issue #304)
+ *
+ * Canonical payload types for every EventBus event type.
+ * These are the SDK-owned contracts that downstream consumers
+ * (e.g., SquadOffice visualization) depend on.
+ *
+ * @module runtime/event-payloads
+ */
+import type { SquadEventType, SquadEvent } from './event-bus.js';
+export interface SessionCreatedPayload {
+    agentName: string;
+    priority: 'low' | 'normal' | 'high' | 'critical';
+}
+export interface SessionIdlePayload {
+    agentName: string;
+    idleSince?: number;
+}
+export interface SessionErrorPayload {
+    agentName: string;
+    error: string;
+}
+export interface SessionDestroyedPayload {
+    agentName: string;
+    reason?: 'complete' | 'error' | 'abort' | 'timeout' | 'user_exit';
+}
+export interface SessionMessagePayload {
+    message: string;
+    role?: string;
+    content?: string;
+}
+export interface SessionToolCallPayload {
+    toolName: string;
+    toolArgs: Record<string, unknown>;
+    resultType?: 'success' | 'failure' | 'rejected' | 'denied';
+}
+/** Multi-phase coordinator routing - discriminated by `phase`. */
+export type CoordinatorRoutingPayload = {
+    phase: 'start';
+    messageLength: number;
+} | {
+    phase: 'routed';
+    agents: string[];
+    confidence: 'high' | 'medium' | 'low';
+    reason: string;
+} | {
+    phase: 'spawning';
+    strategy: 'direct' | 'single' | 'multi' | 'fallback';
+    agentCount: number;
+} | {
+    phase: 'complete';
+    strategy: string;
+    spawnCount: number;
+    successCount: number;
+};
+export type AgentMilestonePayload = {
+    event: 'model.fallback';
+    agentName: string;
+    failedModel: string;
+    failedTier: 'premium' | 'standard' | 'fast';
+    error: string;
+    attemptNumber: number;
+} | {
+    event: 'model.exhausted';
+    agentName: string;
+    originalModel: string;
+    originalTier: string;
+    totalAttempts: number;
+};
+export interface PoolHealthPayload {
+    activeSessions: number;
+    availableSlots: number;
+    queuedRequests: number;
+}
+export interface SquadEventPayloadMap {
+    'session:created': SessionCreatedPayload;
+    'session:idle': SessionIdlePayload;
+    'session:error': SessionErrorPayload;
+    'session:destroyed': SessionDestroyedPayload;
+    'session:message': SessionMessagePayload;
+    'session:tool_call': SessionToolCallPayload;
+    'agent:milestone': AgentMilestonePayload;
+    'coordinator:routing': CoordinatorRoutingPayload;
+    'pool:health': PoolHealthPayload;
+}
+/**
+ * A strongly-typed SquadEvent where the payload type is inferred from the
+ * event type discriminant. Use this for type-safe event construction.
+ */
+export interface TypedSquadEvent<T extends SquadEventType = SquadEventType> {
+    type: T;
+    sessionId?: string;
+    agentName?: string;
+    payload: T extends keyof SquadEventPayloadMap ? SquadEventPayloadMap[T] : unknown;
+    timestamp: Date;
+}
+/**
+ * Type guard: narrows a SquadEvent to a specific typed event.
+ */
+export declare function isSquadEventOfType<T extends SquadEventType>(event: SquadEvent, type: T): event is TypedSquadEvent<T>;
+/**
+ * Helper to construct a typed SquadEvent with payload validation at compile time.
+ */
+export declare function createSquadEvent<T extends SquadEventType>(type: T, payload: T extends keyof SquadEventPayloadMap ? SquadEventPayloadMap[T] : unknown, options?: {
+    sessionId?: string;
+    agentName?: string;
+}): TypedSquadEvent<T>;
+//# sourceMappingURL=event-payloads.d.ts.map

package/dist/runtime/event-payloads.d.ts.map

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

package/dist/runtime/event-payloads.js

@@ -0,0 +1,28 @@
+/**
+ * Typed Event Payloads for SquadEventType (Issue #304)
+ *
+ * Canonical payload types for every EventBus event type.
+ * These are the SDK-owned contracts that downstream consumers
+ * (e.g., SquadOffice visualization) depend on.
+ *
+ * @module runtime/event-payloads
+ */
+/**
+ * Type guard: narrows a SquadEvent to a specific typed event.
+ */
+export function isSquadEventOfType(event, type) {
+    return event.type === type;
+}
+/**
+ * Helper to construct a typed SquadEvent with payload validation at compile time.
+ */
+export function createSquadEvent(type, payload, options) {
+    return {
+        type,
+        sessionId: options?.sessionId,
+        agentName: options?.agentName,
+        payload,
+        timestamp: new Date(),
+    };
+}
+//# sourceMappingURL=event-payloads.js.map

package/dist/runtime/event-payloads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-payloads.js","sourceRoot":"","sources":["../../src/runtime/event-payloads.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsHH;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAiB,EACjB,IAAO;IAEP,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAO,EACP,OAAiF,EACjF,OAAoD;IAEpD,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,SAAS,EAAE,OAAO,EAAE,SAAS;QAC7B,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC"}

package/dist/runtime/health.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Health Monitor (M0-8 #83)
+ *
+ * Monitors the health of SquadClient connections and provides diagnostics.
+ * Exposes health status for external monitoring and startup validation.
+ */
+import type { SquadClient } from '../adapter/client.js';
+export interface HealthCheckResult {
+    /** Overall health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Connection state */
+    connectionState: string;
+    /** Whether the client is connected */
+    connected: boolean;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Protocol version if available */
+    protocolVersion?: number;
+    /** Timestamp of the check */
+    timestamp: Date;
+    /** Response time in milliseconds */
+    responseTimeMs?: number;
+}
+export interface HealthMonitorConfig {
+    /** Client to monitor */
+    client: SquadClient;
+    /** Timeout for health checks in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Log diagnostic information on failures */
+    logDiagnostics?: boolean;
+}
+/**
+ * Health Monitor for SquadClient connections.
+ *
+ * Provides health checks, diagnostics logging, and external health status.
+ * Use check() for startup validation before creating sessions.
+ */
+export declare class HealthMonitor {
+    private client;
+    private timeout;
+    private logDiagnostics;
+    constructor(config: HealthMonitorConfig);
+    /**
+     * Perform a health check on the client connection.
+     *
+     * This method:
+     * 1. Checks connection state
+     * 2. Attempts a ping if connected
+     * 3. Validates protocol version
+     * 4. Logs diagnostics on failure
+     *
+     * @returns Health check result with status and diagnostics
+     */
+    check(): Promise<HealthCheckResult>;
+    /**
+     * Get current status without performing a health check.
+     *
+     * @returns Basic health status based on connection state
+     */
+    getStatus(): Pick<HealthCheckResult, 'status' | 'connectionState' | 'connected' | 'timestamp'>;
+    /**
+     * Log diagnostic information on connection failures.
+     */
+    private logDiagnostic;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/runtime/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/runtime/health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAE7C,uBAAuB;IACvB,eAAe,EAAE,MAAM,CAAC;IAExB,sCAAsC;IACtC,SAAS,EAAE,OAAO,CAAC;IAEnB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;IAEhB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,MAAM,EAAE,WAAW,CAAC;IAEpB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAU;gBAEpB,MAAM,EAAE,mBAAmB;IAMvC;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAgDzC;;;;OAIG;IACH,SAAS,IAAI,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;IAqB9F;;OAEG;IACH,OAAO,CAAC,aAAa;CAQtB"}

package/dist/runtime/health.js

@@ -0,0 +1,112 @@
+/**
+ * Health Monitor (M0-8 #83)
+ *
+ * Monitors the health of SquadClient connections and provides diagnostics.
+ * Exposes health status for external monitoring and startup validation.
+ */
+import { TIMEOUTS } from './constants.js';
+/**
+ * Health Monitor for SquadClient connections.
+ *
+ * Provides health checks, diagnostics logging, and external health status.
+ * Use check() for startup validation before creating sessions.
+ */
+export class HealthMonitor {
+    client;
+    timeout;
+    logDiagnostics;
+    constructor(config) {
+        this.client = config.client;
+        this.timeout = config.timeout ?? TIMEOUTS.HEALTH_CHECK_MS;
+        this.logDiagnostics = config.logDiagnostics ?? true;
+    }
+    /**
+     * Perform a health check on the client connection.
+     *
+     * This method:
+     * 1. Checks connection state
+     * 2. Attempts a ping if connected
+     * 3. Validates protocol version
+     * 4. Logs diagnostics on failure
+     *
+     * @returns Health check result with status and diagnostics
+     */
+    async check() {
+        const startTime = Date.now();
+        const result = {
+            status: 'unhealthy',
+            connectionState: this.client.getState(),
+            connected: this.client.isConnected(),
+            timestamp: new Date(),
+        };
+        try {
+            // Check connection state
+            if (!this.client.isConnected()) {
+                result.error = 'Client not connected';
+                result.status = 'unhealthy';
+                this.logDiagnostic('Connection check failed', result.error);
+                return result;
+            }
+            // Attempt ping
+            const pingPromise = this.client.ping('health-check');
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Health check timeout')), this.timeout));
+            const pingResult = await Promise.race([pingPromise, timeoutPromise]);
+            result.responseTimeMs = Date.now() - startTime;
+            result.protocolVersion = pingResult.protocolVersion;
+            // Validate response time
+            if (result.responseTimeMs > this.timeout * 0.8) {
+                result.status = 'degraded';
+                result.error = `Slow response: ${result.responseTimeMs}ms`;
+                this.logDiagnostic('Health check degraded', result.error);
+            }
+            else {
+                result.status = 'healthy';
+            }
+            return result;
+        }
+        catch (error) {
+            result.status = 'unhealthy';
+            result.error = error instanceof Error ? error.message : String(error);
+            result.responseTimeMs = Date.now() - startTime;
+            this.logDiagnostic('Health check failed', result.error, error);
+            return result;
+        }
+    }
+    /**
+     * Get current status without performing a health check.
+     *
+     * @returns Basic health status based on connection state
+     */
+    getStatus() {
+        const connected = this.client.isConnected();
+        const connectionState = this.client.getState();
+        let status;
+        if (connected && connectionState === 'connected') {
+            status = 'healthy';
+        }
+        else if (connectionState === 'reconnecting') {
+            status = 'degraded';
+        }
+        else {
+            status = 'unhealthy';
+        }
+        return {
+            status,
+            connectionState,
+            connected,
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Log diagnostic information on connection failures.
+     */
+    logDiagnostic(message, details, error) {
+        if (!this.logDiagnostics)
+            return;
+        console.error(`[HealthMonitor] ${message}: ${details}`);
+        if (error instanceof Error && error.stack) {
+            console.error(`[HealthMonitor] Stack trace:`, error.stack);
+        }
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/runtime/health.js.map

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

package/dist/runtime/i18n.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Internationalization & Accessibility Support
+ *
+ * String externalization for CLI output with locale switching
+ * and accessibility auditing utilities.
+ *
+ * @module runtime/i18n
+ */
+import type { SquadConfig } from '../config/schema.js';
+/**
+ * Map of message keys to localized strings.
+ * Supports `{param}` interpolation placeholders.
+ */
+export type MessageCatalog = Record<string, string>;
+/** Accessibility audit finding. */
+export interface AccessibilityFinding {
+    category: 'color-contrast' | 'screen-reader' | 'verbose-mode' | 'keyboard-nav';
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+}
+/** Result of an accessibility audit against a Squad config. */
+export interface AccessibilityReport {
+    passed: boolean;
+    findings: AccessibilityFinding[];
+}
+export declare const defaultCatalog: MessageCatalog;
+/**
+ * Manages locale-specific message catalogs and string formatting.
+ */
+export declare class I18nManager {
+    private locale;
+    private catalogs;
+    constructor(locale?: string);
+    /** Register a catalog for a locale. */
+    registerCatalog(locale: string, catalog: MessageCatalog): void;
+    /** Switch the active locale. Throws if no catalog is registered. */
+    setLocale(locale: string): void;
+    /** Return the active locale. */
+    getLocale(): string;
+    /** Return all locales that have a registered catalog. */
+    getAvailableLocales(): string[];
+    /**
+     * Format a message by key, interpolating `{param}` placeholders.
+     * Falls back to 'en' if the key is missing in the active locale.
+     * Returns the raw key if no catalog contains it.
+     */
+    formatMessage(key: string, params?: Record<string, string>): string;
+}
+/**
+ * Audit a Squad configuration for accessibility concerns.
+ * Returns findings with severity levels; `passed` is true when no errors exist.
+ */
+export declare function auditAccessibility(config: SquadConfig): AccessibilityReport;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/runtime/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../src/runtime/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMvD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,gBAAgB,GAAG,eAAe,GAAG,cAAc,GAAG,cAAc,CAAC;IAC/E,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAMD,eAAO,MAAM,cAAc,EAAE,cA+B5B,CAAC;AAMF;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAA8B;gBAElC,MAAM,SAAO;IAMzB,uCAAuC;IACvC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAI9D,oEAAoE;IACpE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO/B,gCAAgC;IAChC,SAAS,IAAI,MAAM;IAInB,yDAAyD;IACzD,mBAAmB,IAAI,MAAM,EAAE;IAI/B;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM;CASpE;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CAqC3E"}