@livekit/agents 1.0.27 → 1.0.31

package/dist/connection_pool.cjs

@@ -0,0 +1,242 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var connection_pool_exports = {};
+__export(connection_pool_exports, {
+  ConnectionPool: () => ConnectionPool
+});
+module.exports = __toCommonJS(connection_pool_exports);
+var import_mutex = require("@livekit/mutex");
+var import_utils = require("./utils.cjs");
+class ConnectionPool {
+  maxSessionDuration;
+  markRefreshedOnGet;
+  connectCb;
+  closeCb;
+  connectTimeout;
+  // Track connections and their creation timestamps
+  connections = /* @__PURE__ */ new Map();
+  // Available connections ready for reuse
+  available = /* @__PURE__ */ new Set();
+  // Connections queued for closing
+  toClose = /* @__PURE__ */ new Set();
+  // Mutex for connection operations
+  connectLock = new import_mutex.Mutex();
+  // Prewarm task reference
+  prewarmController;
+  constructor(options) {
+    this.maxSessionDuration = options.maxSessionDuration;
+    this.markRefreshedOnGet = options.markRefreshedOnGet ?? false;
+    this.connectCb = options.connectCb;
+    this.closeCb = options.closeCb;
+    this.connectTimeout = options.connectTimeout ?? 1e4;
+  }
+  /**
+   * Create a new connection.
+   *
+   * @param timeout - Connection timeout in milliseconds
+   * @returns The new connection object
+   * @throws If connectCb is not provided or connection fails
+   */
+  async _connect(timeout) {
+    const connection = await this.connectCb(timeout);
+    this.connections.set(connection, Date.now());
+    return connection;
+  }
+  /**
+   * Drain and close all connections queued for closing.
+   */
+  async _drainToClose() {
+    const connectionsToClose = Array.from(this.toClose);
+    this.toClose.clear();
+    for (const conn of connectionsToClose) {
+      await this._maybeCloseConnection(conn);
+    }
+  }
+  /**
+   * Close a connection if closeCb is provided.
+   *
+   * @param conn - The connection to close
+   */
+  async _maybeCloseConnection(conn) {
+    if (this.closeCb) {
+      await this.closeCb(conn);
+    }
+  }
+  _abortError() {
+    const error = new Error("The operation was aborted.");
+    error.name = "AbortError";
+    return error;
+  }
+  /**
+   * Get an available connection or create a new one if needed.
+   *
+   * @param timeout - Connection timeout in milliseconds
+   * @returns An active connection object
+   */
+  async get(timeout) {
+    const unlock = await this.connectLock.lock();
+    try {
+      await this._drainToClose();
+      const now = Date.now();
+      while (this.available.size > 0) {
+        const conn = this.available.values().next().value;
+        this.available.delete(conn);
+        if (this.maxSessionDuration === void 0 || now - (this.connections.get(conn) ?? 0) <= this.maxSessionDuration) {
+          if (this.markRefreshedOnGet) {
+            this.connections.set(conn, now);
+          }
+          return conn;
+        }
+        if (this.connections.has(conn)) {
+          this.connections.delete(conn);
+        }
+        this.toClose.delete(conn);
+        await this._maybeCloseConnection(conn);
+      }
+      return await this._connect(timeout ?? this.connectTimeout);
+    } finally {
+      unlock();
+    }
+  }
+  /**
+   * Mark a connection as available for reuse.
+   *
+   * If connection has been removed, it will not be added to the pool.
+   *
+   * @param conn - The connection to make available
+   */
+  put(conn) {
+    if (this.connections.has(conn)) {
+      this.available.add(conn);
+      return;
+    }
+  }
+  /**
+   * Remove a specific connection from the pool.
+   *
+   * Marks the connection to be closed during the next drain cycle.
+   *
+   * @param conn - The connection to remove
+   */
+  remove(conn) {
+    this.available.delete(conn);
+    if (this.connections.has(conn)) {
+      this.toClose.add(conn);
+      this.connections.delete(conn);
+      void (async () => {
+        const unlock = await this.connectLock.lock();
+        try {
+          if (!this.toClose.has(conn)) return;
+          await this._maybeCloseConnection(conn);
+          this.toClose.delete(conn);
+        } finally {
+          unlock();
+        }
+      })();
+    }
+  }
+  /**
+   * Clear all existing connections.
+   *
+   * Marks all current connections to be closed during the next drain cycle.
+   */
+  invalidate() {
+    for (const conn of this.connections.keys()) {
+      this.toClose.add(conn);
+    }
+    this.connections.clear();
+    this.available.clear();
+  }
+  /**
+   * Initiate prewarming of the connection pool without blocking.
+   *
+   * This method starts a background task that creates a new connection if none exist.
+   * The task automatically cleans itself up when the connection pool is closed.
+   */
+  prewarm() {
+    if (this.prewarmController || this.connections.size > 0) {
+      return;
+    }
+    const controller = new AbortController();
+    this.prewarmController = controller;
+    this._prewarmImpl(controller.signal).catch(() => {
+    });
+  }
+  async _prewarmImpl(signal) {
+    const unlock = await this.connectLock.lock();
+    try {
+      if (signal.aborted) {
+        return;
+      }
+      if (this.connections.size === 0) {
+        const conn = await this._connect(this.connectTimeout);
+        this.available.add(conn);
+      }
+    } finally {
+      unlock();
+    }
+  }
+  /**
+   * Get a connection from the pool and automatically return it when done.
+   * Handles abort signals and ensures proper cleanup.
+   *
+   * @param fn - Function to execute with the connection
+   * @param options - Options including timeout and abort signal
+   * @returns The result of the function
+   */
+  async withConnection(fn, options) {
+    var _a;
+    if ((_a = options == null ? void 0 : options.signal) == null ? void 0 : _a.aborted) {
+      throw this._abortError();
+    }
+    const conn = await this.get(options == null ? void 0 : options.timeout);
+    const signal = options == null ? void 0 : options.signal;
+    try {
+      const fnPromise = fn(conn);
+      const result = signal ? await Promise.race([
+        fnPromise.then((value) => ({ type: "result", value })),
+        (0, import_utils.waitForAbort)(signal).then(() => ({ type: "abort" }))
+      ]).then((r) => {
+        if (r.type === "abort") throw this._abortError();
+        return r.value;
+      }) : await fnPromise;
+      this.put(conn);
+      return result;
+    } catch (error) {
+      this.remove(conn);
+      throw error;
+    }
+  }
+  /**
+   * Close all connections, draining any pending connection closures.
+   */
+  async close() {
+    if (this.prewarmController) {
+      this.prewarmController.abort();
+      this.prewarmController = void 0;
+    }
+    this.invalidate();
+    await this._drainToClose();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConnectionPool
+});
+//# sourceMappingURL=connection_pool.cjs.map

package/dist/connection_pool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connection_pool.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { Mutex } from '@livekit/mutex';\nimport { waitForAbort } from './utils.js';\n\n/**\n * Helper class to manage persistent connections like websockets.\n */\nexport interface ConnectionPoolOptions<T> {\n  /**\n   * Maximum duration in milliseconds before forcing reconnection.\n   * If not set, connections will never expire based on duration.\n   */\n  maxSessionDuration?: number;\n\n  /**\n   * If true, the session will be marked as fresh when get() is called.\n   * Only used when maxSessionDuration is set.\n   */\n  markRefreshedOnGet?: boolean;\n\n  /**\n   * Async callback to create new connections.\n   * @param timeout - Connection timeout in milliseconds\n   * @returns A new connection object\n   */\n  connectCb: (timeout: number) => Promise<T>;\n\n  /**\n   * Optional async callback to close connections.\n   * @param conn - The connection to close\n   */\n  closeCb?: (conn: T) => Promise<void>;\n\n  /**\n   * Default connection timeout in milliseconds.\n   * Defaults to 10000 (10 seconds).\n   */\n  connectTimeout?: number;\n}\n\n/**\n * Connection pool for managing persistent WebSocket connections.\n *\n * Reuses connections efficiently and automatically refreshes them after max duration.\n * Prevents creating too many connections in a single conversation.\n */\nexport class ConnectionPool<T> {\n  private readonly maxSessionDuration?: number;\n  private readonly markRefreshedOnGet: boolean;\n  private readonly connectCb: (timeout: number) => Promise<T>;\n  private readonly closeCb?: (conn: T) => Promise<void>;\n  private readonly connectTimeout: number;\n\n  // Track connections and their creation timestamps\n  private readonly connections: Map<T, number> = new Map();\n  // Available connections ready for reuse\n  private readonly available: Set<T> = new Set();\n  // Connections queued for closing\n  private readonly toClose: Set<T> = new Set();\n  // Mutex for connection operations\n  private readonly connectLock = new Mutex();\n  // Prewarm task reference\n  private prewarmController?: AbortController;\n\n  constructor(options: ConnectionPoolOptions<T>) {\n    this.maxSessionDuration = options.maxSessionDuration;\n    this.markRefreshedOnGet = options.markRefreshedOnGet ?? false;\n    this.connectCb = options.connectCb;\n    this.closeCb = options.closeCb;\n    this.connectTimeout = options.connectTimeout ?? 10_000;\n  }\n\n  /**\n   * Create a new connection.\n   *\n   * @param timeout - Connection timeout in milliseconds\n   * @returns The new connection object\n   * @throws If connectCb is not provided or connection fails\n   */\n  private async _connect(timeout: number): Promise<T> {\n    const connection = await this.connectCb(timeout);\n    this.connections.set(connection, Date.now());\n    return connection;\n  }\n\n  /**\n   * Drain and close all connections queued for closing.\n   */\n  private async _drainToClose(): Promise<void> {\n    const connectionsToClose = Array.from(this.toClose);\n    this.toClose.clear();\n\n    for (const conn of connectionsToClose) {\n      await this._maybeCloseConnection(conn);\n    }\n  }\n\n  /**\n   * Close a connection if closeCb is provided.\n   *\n   * @param conn - The connection to close\n   */\n  private async _maybeCloseConnection(conn: T): Promise<void> {\n    if (this.closeCb) {\n      await this.closeCb(conn);\n    }\n  }\n\n  private _abortError(): Error {\n    const error = new Error('The operation was aborted.');\n    error.name = 'AbortError';\n    return error;\n  }\n\n  /**\n   * Get an available connection or create a new one if needed.\n   *\n   * @param timeout - Connection timeout in milliseconds\n   * @returns An active connection object\n   */\n  async get(timeout?: number): Promise<T> {\n    const unlock = await this.connectLock.lock();\n    try {\n      await this._drainToClose();\n      const now = Date.now();\n\n      // Try to reuse an available connection that hasn't expired\n      while (this.available.size > 0) {\n        const conn = this.available.values().next().value as T;\n        this.available.delete(conn);\n\n        if (\n          this.maxSessionDuration === undefined ||\n          now - (this.connections.get(conn) ?? 0) <= this.maxSessionDuration\n        ) {\n          if (this.markRefreshedOnGet) {\n            this.connections.set(conn, now);\n          }\n          return conn;\n        }\n\n        // Connection expired; close it now so callers observing get() see it closed promptly.\n        // (Also makes tests deterministic: closeCb should have been called by the time get() resolves.)\n        if (this.connections.has(conn)) {\n          this.connections.delete(conn);\n        }\n        this.toClose.delete(conn);\n        await this._maybeCloseConnection(conn);\n      }\n\n      return await this._connect(timeout ?? this.connectTimeout);\n    } finally {\n      unlock();\n    }\n  }\n\n  /**\n   * Mark a connection as available for reuse.\n   *\n   * If connection has been removed, it will not be added to the pool.\n   *\n   * @param conn - The connection to make available\n   */\n  put(conn: T): void {\n    if (this.connections.has(conn)) {\n      this.available.add(conn);\n      return;\n    }\n  }\n\n  /**\n   * Remove a specific connection from the pool.\n   *\n   * Marks the connection to be closed during the next drain cycle.\n   *\n   * @param conn - The connection to remove\n   */\n  remove(conn: T): void {\n    this.available.delete(conn);\n    if (this.connections.has(conn)) {\n      this.toClose.add(conn);\n      this.connections.delete(conn);\n      // Important for Node websockets: if we just \"mark to close later\" but remove listeners,\n      // the ws library can buffer incoming frames in memory. Close ASAP in background.\n      void (async () => {\n        const unlock = await this.connectLock.lock();\n        try {\n          if (!this.toClose.has(conn)) return;\n          await this._maybeCloseConnection(conn);\n          this.toClose.delete(conn);\n        } finally {\n          unlock();\n        }\n      })();\n    }\n  }\n\n  /**\n   * Clear all existing connections.\n   *\n   * Marks all current connections to be closed during the next drain cycle.\n   */\n  invalidate(): void {\n    for (const conn of this.connections.keys()) {\n      this.toClose.add(conn);\n    }\n    this.connections.clear();\n    this.available.clear();\n  }\n\n  /**\n   * Initiate prewarming of the connection pool without blocking.\n   *\n   * This method starts a background task that creates a new connection if none exist.\n   * The task automatically cleans itself up when the connection pool is closed.\n   */\n  prewarm(): void {\n    if (this.prewarmController || this.connections.size > 0) {\n      return;\n    }\n\n    const controller = new AbortController();\n    this.prewarmController = controller;\n\n    // Start prewarm in background\n    this._prewarmImpl(controller.signal).catch(() => {\n      // Ignore errors during prewarm\n    });\n  }\n\n  private async _prewarmImpl(signal: AbortSignal): Promise<void> {\n    const unlock = await this.connectLock.lock();\n    try {\n      if (signal.aborted) {\n        return;\n      }\n\n      if (this.connections.size === 0) {\n        const conn = await this._connect(this.connectTimeout);\n        this.available.add(conn);\n      }\n    } finally {\n      unlock();\n    }\n  }\n\n  /**\n   * Get a connection from the pool and automatically return it when done.\n   * Handles abort signals and ensures proper cleanup.\n   *\n   * @param fn - Function to execute with the connection\n   * @param options - Options including timeout and abort signal\n   * @returns The result of the function\n   */\n  async withConnection<R>(\n    fn: (conn: T) => Promise<R>,\n    options?: {\n      timeout?: number;\n      signal?: AbortSignal;\n    },\n  ): Promise<R> {\n    // Check if already aborted before getting connection\n    if (options?.signal?.aborted) {\n      throw this._abortError();\n    }\n\n    const conn = await this.get(options?.timeout);\n\n    const signal = options?.signal;\n\n    try {\n      const fnPromise = fn(conn);\n      const result = signal\n        ? await Promise.race([\n            fnPromise.then((value) => ({ type: 'result' as const, value })),\n            waitForAbort(signal).then(() => ({ type: 'abort' as const })),\n          ]).then((r) => {\n            if (r.type === 'abort') throw this._abortError();\n            return r.value;\n          })\n        : await fnPromise;\n      // Return connection to pool on success\n      this.put(conn);\n      return result;\n    } catch (error) {\n      // Remove connection from pool on error (don't return it)\n      this.remove(conn);\n      throw error;\n    }\n  }\n\n  /**\n   * Close all connections, draining any pending connection closures.\n   */\n  async close(): Promise<void> {\n    // Cancel prewarm task if running\n    if (this.prewarmController) {\n      this.prewarmController.abort();\n      this.prewarmController = undefined;\n    }\n\n    this.invalidate();\n    await this._drainToClose();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/connection_pool.d.cts

@@ -0,0 +1,123 @@
+/**
+ * Helper class to manage persistent connections like websockets.
+ */
+export interface ConnectionPoolOptions<T> {
+    /**
+     * Maximum duration in milliseconds before forcing reconnection.
+     * If not set, connections will never expire based on duration.
+     */
+    maxSessionDuration?: number;
+    /**
+     * If true, the session will be marked as fresh when get() is called.
+     * Only used when maxSessionDuration is set.
+     */
+    markRefreshedOnGet?: boolean;
+    /**
+     * Async callback to create new connections.
+     * @param timeout - Connection timeout in milliseconds
+     * @returns A new connection object
+     */
+    connectCb: (timeout: number) => Promise<T>;
+    /**
+     * Optional async callback to close connections.
+     * @param conn - The connection to close
+     */
+    closeCb?: (conn: T) => Promise<void>;
+    /**
+     * Default connection timeout in milliseconds.
+     * Defaults to 10000 (10 seconds).
+     */
+    connectTimeout?: number;
+}
+/**
+ * Connection pool for managing persistent WebSocket connections.
+ *
+ * Reuses connections efficiently and automatically refreshes them after max duration.
+ * Prevents creating too many connections in a single conversation.
+ */
+export declare class ConnectionPool<T> {
+    private readonly maxSessionDuration?;
+    private readonly markRefreshedOnGet;
+    private readonly connectCb;
+    private readonly closeCb?;
+    private readonly connectTimeout;
+    private readonly connections;
+    private readonly available;
+    private readonly toClose;
+    private readonly connectLock;
+    private prewarmController?;
+    constructor(options: ConnectionPoolOptions<T>);
+    /**
+     * Create a new connection.
+     *
+     * @param timeout - Connection timeout in milliseconds
+     * @returns The new connection object
+     * @throws If connectCb is not provided or connection fails
+     */
+    private _connect;
+    /**
+     * Drain and close all connections queued for closing.
+     */
+    private _drainToClose;
+    /**
+     * Close a connection if closeCb is provided.
+     *
+     * @param conn - The connection to close
+     */
+    private _maybeCloseConnection;
+    private _abortError;
+    /**
+     * Get an available connection or create a new one if needed.
+     *
+     * @param timeout - Connection timeout in milliseconds
+     * @returns An active connection object
+     */
+    get(timeout?: number): Promise<T>;
+    /**
+     * Mark a connection as available for reuse.
+     *
+     * If connection has been removed, it will not be added to the pool.
+     *
+     * @param conn - The connection to make available
+     */
+    put(conn: T): void;
+    /**
+     * Remove a specific connection from the pool.
+     *
+     * Marks the connection to be closed during the next drain cycle.
+     *
+     * @param conn - The connection to remove
+     */
+    remove(conn: T): void;
+    /**
+     * Clear all existing connections.
+     *
+     * Marks all current connections to be closed during the next drain cycle.
+     */
+    invalidate(): void;
+    /**
+     * Initiate prewarming of the connection pool without blocking.
+     *
+     * This method starts a background task that creates a new connection if none exist.
+     * The task automatically cleans itself up when the connection pool is closed.
+     */
+    prewarm(): void;
+    private _prewarmImpl;
+    /**
+     * Get a connection from the pool and automatically return it when done.
+     * Handles abort signals and ensures proper cleanup.
+     *
+     * @param fn - Function to execute with the connection
+     * @param options - Options including timeout and abort signal
+     * @returns The result of the function
+     */
+    withConnection<R>(fn: (conn: T) => Promise<R>, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<R>;
+    /**
+     * Close all connections, draining any pending connection closures.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connection_pool.d.ts.map

package/dist/connection_pool.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Helper class to manage persistent connections like websockets.
+ */
+export interface ConnectionPoolOptions<T> {
+    /**
+     * Maximum duration in milliseconds before forcing reconnection.
+     * If not set, connections will never expire based on duration.
+     */
+    maxSessionDuration?: number;
+    /**
+     * If true, the session will be marked as fresh when get() is called.
+     * Only used when maxSessionDuration is set.
+     */
+    markRefreshedOnGet?: boolean;
+    /**
+     * Async callback to create new connections.
+     * @param timeout - Connection timeout in milliseconds
+     * @returns A new connection object
+     */
+    connectCb: (timeout: number) => Promise<T>;
+    /**
+     * Optional async callback to close connections.
+     * @param conn - The connection to close
+     */
+    closeCb?: (conn: T) => Promise<void>;
+    /**
+     * Default connection timeout in milliseconds.
+     * Defaults to 10000 (10 seconds).
+     */
+    connectTimeout?: number;
+}
+/**
+ * Connection pool for managing persistent WebSocket connections.
+ *
+ * Reuses connections efficiently and automatically refreshes them after max duration.
+ * Prevents creating too many connections in a single conversation.
+ */
+export declare class ConnectionPool<T> {
+    private readonly maxSessionDuration?;
+    private readonly markRefreshedOnGet;
+    private readonly connectCb;
+    private readonly closeCb?;
+    private readonly connectTimeout;
+    private readonly connections;
+    private readonly available;
+    private readonly toClose;
+    private readonly connectLock;
+    private prewarmController?;
+    constructor(options: ConnectionPoolOptions<T>);
+    /**
+     * Create a new connection.
+     *
+     * @param timeout - Connection timeout in milliseconds
+     * @returns The new connection object
+     * @throws If connectCb is not provided or connection fails
+     */
+    private _connect;
+    /**
+     * Drain and close all connections queued for closing.
+     */
+    private _drainToClose;
+    /**
+     * Close a connection if closeCb is provided.
+     *
+     * @param conn - The connection to close
+     */
+    private _maybeCloseConnection;
+    private _abortError;
+    /**
+     * Get an available connection or create a new one if needed.
+     *
+     * @param timeout - Connection timeout in milliseconds
+     * @returns An active connection object
+     */
+    get(timeout?: number): Promise<T>;
+    /**
+     * Mark a connection as available for reuse.
+     *
+     * If connection has been removed, it will not be added to the pool.
+     *
+     * @param conn - The connection to make available
+     */
+    put(conn: T): void;
+    /**
+     * Remove a specific connection from the pool.
+     *
+     * Marks the connection to be closed during the next drain cycle.
+     *
+     * @param conn - The connection to remove
+     */
+    remove(conn: T): void;
+    /**
+     * Clear all existing connections.
+     *
+     * Marks all current connections to be closed during the next drain cycle.
+     */
+    invalidate(): void;
+    /**
+     * Initiate prewarming of the connection pool without blocking.
+     *
+     * This method starts a background task that creates a new connection if none exist.
+     * The task automatically cleans itself up when the connection pool is closed.
+     */
+    prewarm(): void;
+    private _prewarmImpl;
+    /**
+     * Get a connection from the pool and automatically return it when done.
+     * Handles abort signals and ensures proper cleanup.
+     *
+     * @param fn - Function to execute with the connection
+     * @param options - Options including timeout and abort signal
+     * @returns The result of the function
+     */
+    withConnection<R>(fn: (conn: T) => Promise<R>, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<R>;
+    /**
+     * Close all connections, draining any pending connection closures.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connection_pool.d.ts.map

package/dist/connection_pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection_pool.d.ts","sourceRoot":"","sources":["../src/connection_pool.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAE3C;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAGxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAE/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAE3C,OAAO,CAAC,iBAAiB,CAAC,CAAkB;gBAEhC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAQ7C;;;;;;OAMG;YACW,QAAQ;IAMtB;;OAEG;YACW,aAAa;IAS3B;;;;OAIG;YACW,qBAAqB;IAMnC,OAAO,CAAC,WAAW;IAMnB;;;;;OAKG;IACG,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAoCvC;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAOlB;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAoBrB;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAQlB;;;;;OAKG;IACH,OAAO,IAAI,IAAI;YAcD,YAAY;IAgB1B;;;;;;;OAOG;IACG,cAAc,CAAC,CAAC,EACpB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GACA,OAAO,CAAC,CAAC,CAAC;IA+Bb;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B"}