@darkiceinteractive/mcp-conductor 2.0.0-alpha.1 → 3.0.0-beta.2

package/dist/bridge/pool.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Backend Connection Pool
+ *
+ * Maintains persistent stdio connections to MCP backend servers, multiplexes
+ * JSON-RPC requests over the same channel, and respawns crashed backends
+ * within 1 second. Eliminates per-request spawn overhead.
+ *
+ * Design:
+ * - Each server gets [min, max] connections whose lifecycle is managed here
+ * - JSON-RPC multiplexing: requests tagged with a unique id; responses routed
+ *   back to the correct in-flight caller via a pending-map
+ * - Idle timer: connections unused for `idleTimeoutMs` are gracefully closed
+ * - Crash recovery: `close` event triggers automatic respawn
+ *
+ * @module bridge/pool
+ */
+import { EventEmitter } from 'node:events';
+import type { ConnectionPoolConfig } from '../config/schema.js';
+export interface PoolStats {
+    totalConnections: number;
+    idleConnections: number;
+    busyConnections: number;
+    serversTracked: number;
+    pendingAcquires: number;
+}
+/** Opaque handle returned by `acquire()`. Pass back to `release()`. */
+export interface PooledConnection {
+    readonly id: string;
+    readonly serverKey: string;
+    /** Send a multiplexed JSON-RPC call; resolves with the parsed response. */
+    call(method: string, params?: unknown): Promise<unknown>;
+}
+/**
+ * Factory function that creates a new stdio channel to a backend.
+ * Returns a send function and a closer; delivers received lines via callback.
+ */
+export type ConnectionFactory = (opts: {
+    onLine: (line: string) => void;
+    onClose: () => void;
+    onError: (err: Error) => void;
+}) => {
+    write: (line: string) => boolean;
+    close: () => void;
+};
+/**
+ * A connection pool for MCP backend servers.
+ *
+ * Usage:
+ * ```ts
+ * pool.registerServer('my-server', factory);
+ * const conn = await pool.acquire('my-server');
+ * const result = await conn.call('tools/list');
+ * pool.release(conn);
+ * ```
+ */
+export declare class ConnectionPool extends EventEmitter {
+    private readonly opts;
+    private readonly servers;
+    private isShuttingDown;
+    constructor(options?: ConnectionPoolConfig);
+    /**
+     * Register a backend server with its connection factory.
+     * Call this before `acquire()`. Pre-warms `minConnectionsPerServer`
+     * connections immediately.
+     */
+    registerServer(serverKey: string, factory: ConnectionFactory): void;
+    /**
+     * Acquire an idle connection for `serverKey`.
+     *
+     * If all connections are busy and count < max, spawns a new one.
+     * If at max, waits up to `acquireTimeoutMs` for a release.
+     */
+    acquire(serverKey: string): Promise<PooledConnection>;
+    /**
+     * Return a connection to the pool.
+     * Idle timer is (re)started; if waiters are queued, hands off immediately.
+     */
+    release(connection: PooledConnection): void;
+    /** Gracefully drain all connections and stop accepting new ones. */
+    shutdown(): Promise<void>;
+    /** Snapshot of pool health metrics. */
+    stats(): PoolStats;
+    private _findIdle;
+    private _markBusy;
+    private _toPublic;
+    private _rpcCall;
+    private _spawnConnection;
+    private _handleLine;
+    private _handleClose;
+    private _handleError;
+    private _startIdleTimer;
+    private _closeInternal;
+    private _drainWaiters;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/bridge/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/bridge/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAMhE,MAAM,WAAW,SAAS;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AA6CD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE;IACrC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B,KAAK;IACJ,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAaF;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,cAAc,CAAS;gBAEnB,OAAO,GAAE,oBAAyB;IAK9C;;;;OAIG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAoBnE;;;;;OAKG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuC3D;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAuB3C,oEAAoE;IAC9D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB/B,uCAAuC;IACvC,KAAK,IAAI,SAAS;IA6BlB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,QAAQ;YAkBF,gBAAgB;IAiD9B,OAAO,CAAC,WAAW;IAkCnB,OAAO,CAAC,YAAY;IA6CpB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,aAAa;CAUtB"}

package/dist/bridge/pool.js

@@ -0,0 +1,384 @@
+/**
+ * Backend Connection Pool
+ *
+ * Maintains persistent stdio connections to MCP backend servers, multiplexes
+ * JSON-RPC requests over the same channel, and respawns crashed backends
+ * within 1 second. Eliminates per-request spawn overhead.
+ *
+ * Design:
+ * - Each server gets [min, max] connections whose lifecycle is managed here
+ * - JSON-RPC multiplexing: requests tagged with a unique id; responses routed
+ *   back to the correct in-flight caller via a pending-map
+ * - Idle timer: connections unused for `idleTimeoutMs` are gracefully closed
+ * - Crash recovery: `close` event triggers automatic respawn
+ *
+ * @module bridge/pool
+ */
+import { EventEmitter } from 'node:events';
+import { logger } from '../utils/index.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// ConnectionPool
+// ─────────────────────────────────────────────────────────────────────────────
+const DEFAULT_OPTIONS = {
+    minConnectionsPerServer: 1,
+    maxConnectionsPerServer: 4,
+    idleTimeoutMs: 300_000,
+    acquireTimeoutMs: 5_000,
+};
+/**
+ * A connection pool for MCP backend servers.
+ *
+ * Usage:
+ * ```ts
+ * pool.registerServer('my-server', factory);
+ * const conn = await pool.acquire('my-server');
+ * const result = await conn.call('tools/list');
+ * pool.release(conn);
+ * ```
+ */
+export class ConnectionPool extends EventEmitter {
+    opts;
+    servers = new Map();
+    isShuttingDown = false;
+    constructor(options = {}) {
+        super();
+        this.opts = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Register a backend server with its connection factory.
+     * Call this before `acquire()`. Pre-warms `minConnectionsPerServer`
+     * connections immediately.
+     */
+    registerServer(serverKey, factory) {
+        if (this.servers.has(serverKey))
+            return;
+        const entry = {
+            key: serverKey,
+            connections: new Map(),
+            waiting: [],
+            factory,
+            spawning: 0,
+        };
+        this.servers.set(serverKey, entry);
+        // Pre-warm minimum connections
+        for (let i = 0; i < this.opts.minConnectionsPerServer; i++) {
+            this._spawnConnection(entry).catch((err) => {
+                logger.warn('ConnectionPool: pre-warm spawn failed', { serverKey, err: String(err) });
+            });
+        }
+    }
+    /**
+     * Acquire an idle connection for `serverKey`.
+     *
+     * If all connections are busy and count < max, spawns a new one.
+     * If at max, waits up to `acquireTimeoutMs` for a release.
+     */
+    async acquire(serverKey) {
+        if (this.isShuttingDown) {
+            throw new Error(`ConnectionPool is shutting down`);
+        }
+        const entry = this.servers.get(serverKey);
+        if (!entry) {
+            throw new Error(`ConnectionPool: unknown server "${serverKey}". Call registerServer() first.`);
+        }
+        // Try to find an idle connection
+        const idle = this._findIdle(entry);
+        if (idle) {
+            return this._markBusy(idle);
+        }
+        // Spawn a new connection if under max
+        const totalActive = entry.connections.size + entry.spawning;
+        if (totalActive < this.opts.maxConnectionsPerServer) {
+            const conn = await this._spawnConnection(entry);
+            return this._markBusy(conn);
+        }
+        // All at max — wait for a release
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const idx = entry.waiting.indexOf(waiter);
+                if (idx !== -1)
+                    entry.waiting.splice(idx, 1);
+                reject(new Error(`ConnectionPool: acquire timeout after ${this.opts.acquireTimeoutMs}ms for "${serverKey}"`));
+            }, this.opts.acquireTimeoutMs);
+            // Allow the timer to be GC'd without blocking Node exit
+            if (timer.unref)
+                timer.unref();
+            const waiter = { resolve, reject, timer };
+            entry.waiting.push(waiter);
+        });
+    }
+    /**
+     * Return a connection to the pool.
+     * Idle timer is (re)started; if waiters are queued, hands off immediately.
+     */
+    release(connection) {
+        const entry = this.servers.get(connection.serverKey);
+        if (!entry)
+            return;
+        const internal = entry.connections.get(connection.id);
+        if (!internal || internal.closed)
+            return;
+        internal.busy = false;
+        // Drain waiting queue first
+        if (entry.waiting.length > 0) {
+            const waiter = entry.waiting.shift();
+            clearTimeout(waiter.timer);
+            // Mark busy synchronously before handing off
+            internal.busy = true;
+            waiter.resolve(this._toPublic(internal));
+            return;
+        }
+        // Start idle timer
+        this._startIdleTimer(entry, internal);
+    }
+    /** Gracefully drain all connections and stop accepting new ones. */
+    async shutdown() {
+        this.isShuttingDown = true;
+        for (const entry of this.servers.values()) {
+            // Reject all waiting acquires
+            for (const waiter of entry.waiting) {
+                clearTimeout(waiter.timer);
+                waiter.reject(new Error('ConnectionPool shut down'));
+            }
+            entry.waiting.length = 0;
+            // Close all connections
+            for (const conn of entry.connections.values()) {
+                this._closeInternal(conn);
+            }
+        }
+        this.servers.clear();
+        logger.info('ConnectionPool: shut down complete');
+    }
+    /** Snapshot of pool health metrics. */
+    stats() {
+        let total = 0;
+        let idle = 0;
+        let busy = 0;
+        let pending = 0;
+        for (const entry of this.servers.values()) {
+            for (const conn of entry.connections.values()) {
+                if (conn.closed)
+                    continue;
+                total++;
+                if (conn.busy)
+                    busy++;
+                else
+                    idle++;
+            }
+            pending += entry.waiting.length;
+        }
+        return {
+            totalConnections: total,
+            idleConnections: idle,
+            busyConnections: busy,
+            serversTracked: this.servers.size,
+            pendingAcquires: pending,
+        };
+    }
+    // ───────────────────────────────────────────────────────────────────────────
+    // Private helpers
+    // ───────────────────────────────────────────────────────────────────────────
+    _findIdle(entry) {
+        for (const conn of entry.connections.values()) {
+            if (!conn.busy && !conn.closed)
+                return conn;
+        }
+        return undefined;
+    }
+    _markBusy(conn) {
+        conn.busy = true;
+        // Cancel idle timer if active
+        if (conn.idleTimer) {
+            clearTimeout(conn.idleTimer);
+            conn.idleTimer = null;
+        }
+        return this._toPublic(conn);
+    }
+    _toPublic(internal) {
+        return {
+            id: internal.id,
+            serverKey: internal.serverKey,
+            call: (method, params) => this._rpcCall(internal, method, params),
+        };
+    }
+    _rpcCall(conn, method, params) {
+        if (conn.closed || !conn.writeLine) {
+            return Promise.reject(new Error(`Connection ${conn.id} is closed`));
+        }
+        const id = conn.nextRequestId++;
+        const message = JSON.stringify({ jsonrpc: '2.0', id, method, params: params ?? {} });
+        return new Promise((resolve, reject) => {
+            conn.pending.set(id, { resolve, reject });
+            const ok = conn.writeLine(message + '\n');
+            if (!ok) {
+                conn.pending.delete(id);
+                reject(new Error(`Write failed on connection ${conn.id}`));
+            }
+        });
+    }
+    async _spawnConnection(entry) {
+        entry.spawning++;
+        const id = `${entry.key}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+        const internal = {
+            id,
+            serverKey: entry.key,
+            busy: false,
+            idleTimer: null,
+            pending: new Map(),
+            nextRequestId: 1,
+            lineBuffer: '',
+            writeLine: null,
+            close: () => { },
+            closed: false,
+            createdAt: Date.now(),
+        };
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const transport = entry.factory({
+                onLine: (line) => this._handleLine(internal, line),
+                onClose: () => this._handleClose(entry, internal),
+                onError: (err) => {
+                    if (!resolved) {
+                        resolved = true;
+                        entry.spawning--;
+                        entry.connections.delete(id);
+                        reject(err);
+                    }
+                    else {
+                        this._handleError(entry, internal, err);
+                    }
+                },
+            });
+            internal.writeLine = transport.write;
+            internal.close = transport.close;
+            entry.connections.set(id, internal);
+            entry.spawning--;
+            resolved = true;
+            logger.debug('ConnectionPool: spawned connection', { id, server: entry.key });
+            resolve(internal);
+        });
+    }
+    _handleLine(conn, raw) {
+        // Accumulate partial lines
+        conn.lineBuffer += raw;
+        // Process all complete newline-terminated JSON objects
+        let nl;
+        while ((nl = conn.lineBuffer.indexOf('\n')) !== -1) {
+            const line = conn.lineBuffer.slice(0, nl).trim();
+            conn.lineBuffer = conn.lineBuffer.slice(nl + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                logger.warn('ConnectionPool: unparseable line from backend', { conn: conn.id, line: line.slice(0, 200) });
+                continue;
+            }
+            if (msg.id !== undefined) {
+                const pending = conn.pending.get(msg.id);
+                if (pending) {
+                    conn.pending.delete(msg.id);
+                    if (msg.error) {
+                        pending.reject(new Error(msg.error.message ?? 'RPC error'));
+                    }
+                    else {
+                        pending.resolve(msg.result);
+                    }
+                }
+            }
+        }
+    }
+    _handleClose(entry, conn) {
+        if (conn.closed)
+            return;
+        conn.closed = true;
+        conn.writeLine = null;
+        // Reject all in-flight calls
+        for (const [, pending] of conn.pending) {
+            pending.reject(new Error(`Connection ${conn.id} to "${entry.key}" closed unexpectedly`));
+        }
+        conn.pending.clear();
+        if (conn.idleTimer) {
+            clearTimeout(conn.idleTimer);
+            conn.idleTimer = null;
+        }
+        entry.connections.delete(conn.id);
+        logger.warn('ConnectionPool: connection closed', { id: conn.id, server: entry.key });
+        if (this.isShuttingDown)
+            return;
+        // Respawn to maintain minimum floor
+        const activeCount = entry.connections.size + entry.spawning;
+        if (activeCount < this.opts.minConnectionsPerServer) {
+            setTimeout(() => {
+                if (!this.isShuttingDown) {
+                    this._spawnConnection(entry)
+                        .then((newConn) => {
+                        logger.info('ConnectionPool: respawned connection after crash', {
+                            newId: newConn.id,
+                            server: entry.key,
+                        });
+                        // Drain any waiters that accumulated during the crash
+                        this._drainWaiters(entry);
+                    })
+                        .catch((err) => {
+                        logger.error('ConnectionPool: respawn failed', { server: entry.key, err: String(err) });
+                    });
+                }
+            }, 0).unref?.();
+        }
+        this.emit('connectionClosed', entry.key, conn.id);
+    }
+    _handleError(entry, conn, err) {
+        logger.error('ConnectionPool: connection error', { id: conn.id, server: entry.key, err: err.message });
+        this._handleClose(entry, conn);
+    }
+    _startIdleTimer(entry, conn) {
+        if (conn.idleTimer)
+            clearTimeout(conn.idleTimer);
+        conn.idleTimer = setTimeout(() => {
+            const currentCount = entry.connections.size;
+            if (!conn.busy && currentCount > this.opts.minConnectionsPerServer) {
+                logger.debug('ConnectionPool: closing idle connection', { id: conn.id, server: entry.key });
+                this._closeInternal(conn);
+                entry.connections.delete(conn.id);
+            }
+        }, this.opts.idleTimeoutMs);
+        // Do not block Node.js exit for idle timers
+        if (conn.idleTimer.unref)
+            conn.idleTimer.unref();
+    }
+    _closeInternal(conn) {
+        if (conn.closed)
+            return;
+        conn.closed = true;
+        conn.writeLine = null;
+        for (const [, pending] of conn.pending) {
+            pending.reject(new Error(`Connection ${conn.id} closed`));
+        }
+        conn.pending.clear();
+        if (conn.idleTimer) {
+            clearTimeout(conn.idleTimer);
+            conn.idleTimer = null;
+        }
+        try {
+            conn.close();
+        }
+        catch {
+            // Ignore close errors
+        }
+    }
+    _drainWaiters(entry) {
+        while (entry.waiting.length > 0) {
+            const idle = this._findIdle(entry);
+            if (!idle)
+                break;
+            const waiter = entry.waiting.shift();
+            clearTimeout(waiter.timer);
+            idle.busy = true;
+            waiter.resolve(this._toPublic(idle));
+        }
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/bridge/pool.js.map

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

package/dist/cache/cache.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CacheLayer — three-tier cache composition (memory LRU + disk CBOR + delta).
+ *
+ * Call flow:
+ *   get(server, tool, args)
+ *     → memory LRU hit?  → return CacheHit (source: 'memory')
+ *     → disk hit?        → promote to memory, return CacheHit (source: 'disk')
+ *     → miss             → return null (caller must fetch from backend)
+ *
+ * Stale-while-revalidate (SWR):
+ *   All staleness decisions are made here, not in DiskCache, so that
+ *   vi.useFakeTimers() in tests correctly affects TTL checks at all tiers.
+ *
+ * Bridge wiring order (per spec):
+ *   cache check → cache miss → reliability gateway (Agent C) → backend
+ *
+ * @module cache/cache
+ */
+import type { CacheHit, CacheStats, CacheLayerOptions, DeltaResult } from './index.js';
+export interface ExtendedCacheHit extends CacheHit {
+    needsRevalidation?: boolean;
+}
+export declare class CacheLayer {
+    private lru;
+    private disk;
+    private registry;
+    private options;
+    private unsubscribe;
+    private diskMisses;
+    private ttlMap;
+    /** Keys currently being background-revalidated; prevents SWR thundering herd. */
+    private revalidating;
+    constructor(options: CacheLayerOptions);
+    get(server: string, tool: string, args: unknown): Promise<ExtendedCacheHit | null>;
+    set(server: string, tool: string, args: unknown, result: unknown, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    invalidate(server: string, pattern?: string): Promise<number>;
+    delta(server: string, tool: string, args: unknown, current: unknown): Promise<DeltaResult>;
+    stats(): CacheStats;
+    clear(): Promise<void>;
+    wouldCache(server: string, tool: string): boolean;
+    /**
+     * Deduplicated background revalidation helper for stale-while-revalidate.
+     *
+     * Marks the cache key as being revalidated so subsequent concurrent `get()`
+     * calls that would also see `needsRevalidation: true` get `false` instead,
+     * preventing a thundering herd of parallel refreshes.
+     *
+     * The key is removed from the revalidating set on completion (success or
+     * failure), allowing a future `get()` to schedule a fresh revalidation if
+     * the entry is still stale at that point.
+     *
+     * @param server   MCP server name.
+     * @param tool     Tool name.
+     * @param args     Original call arguments (used to build the cache key).
+     * @param fetchFn  Async function that calls the backend and returns the fresh result.
+     * @returns        A promise that resolves when the background refresh completes.
+     *                 Callers should `.catch()` the returned promise to handle errors.
+     */
+    refreshInBackground(server: string, tool: string, args: unknown, fetchFn: () => Promise<unknown>): Promise<void>;
+    destroy(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvF,MAAM,WAAW,gBAAiB,SAAQ,QAAQ;IAChD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAA6B;IAC3C,iFAAiF;IACjF,OAAO,CAAC,YAAY,CAAqB;gBAE7B,OAAO,EAAE,iBAAiB;IAgChC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IA0DlF,GAAG,CACP,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC,IAAI,CAAC;IAkBV,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO7D,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAMhG,KAAK,IAAI,UAAU;IAab,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAKjD;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAAmB,CACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IAqBhB,OAAO,IAAI,IAAI;CAMhB"}