@darkiceinteractive/mcp-conductor 1.1.0 → 3.0.0-beta.1

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/bridge/session-registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Bridge Session Registry
+ *
+ * Tracks `Mcp-Session-Id` values issued by the HTTP bridge. Sessions are
+ * generated on first request (or when a client presents an unknown id) and
+ * expire after a period of inactivity. Bounded to prevent unbounded growth
+ * if a misbehaving client rotates IDs.
+ *
+ * Per MCP spec 2025-03-26 Streamable HTTP transport:
+ * - session IDs MUST be globally unique and cryptographically secure
+ * - requests carrying a terminated / unknown id should return 404
+ * - servers MAY assign a new id on any request
+ */
+interface SessionRecord {
+    id: string;
+    createdAt: number;
+    lastSeenAt: number;
+}
+export declare class SessionRegistry {
+    private readonly sessions;
+    private cleanupTimer;
+    private readonly ttlMs;
+    private readonly cleanupIntervalMs;
+    private readonly maxSessions;
+    constructor(opts?: {
+        ttlMs?: number;
+        cleanupIntervalMs?: number;
+        maxSessions?: number;
+    });
+    /**
+     * Begin periodic cleanup. Called by HttpBridge.start().
+     */
+    start(): void;
+    /**
+     * Stop the cleanup timer and drop all sessions. Called by HttpBridge.stop().
+     */
+    stop(): void;
+    /**
+     * Create a new session and return its id.
+     */
+    create(): string;
+    /**
+     * Look up a session. Returns undefined if the id is unknown or expired.
+     * Expired sessions are purged lazily here even if the sweep hasn't run yet.
+     */
+    touch(id: string): SessionRecord | undefined;
+    /**
+     * Explicit termination (e.g. DELETE /session).
+     * Returns true if a session was removed.
+     */
+    terminate(id: string): boolean;
+    size(): number;
+    /**
+     * Purge sessions older than ttlMs. Exposed for tests.
+     */
+    sweep(): number;
+    /**
+     * If we're at capacity, drop the oldest (by lastSeenAt) record to make room.
+     * Prevents unbounded growth under ID rotation.
+     */
+    private evictIfFull;
+}
+export {};
+//# sourceMappingURL=session-registry.d.ts.map

package/dist/bridge/session-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../../src/bridge/session-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,IAAI,CAAC,EAAE;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;IAOD;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACH,MAAM,IAAI,MAAM;IAQhB;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAY5C;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9B,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,MAAM;IAef;;;OAGG;IACH,OAAO,CAAC,WAAW;CAepB"}

package/dist/bridge/session-registry.js

@@ -0,0 +1,124 @@
+/**
+ * Bridge Session Registry
+ *
+ * Tracks `Mcp-Session-Id` values issued by the HTTP bridge. Sessions are
+ * generated on first request (or when a client presents an unknown id) and
+ * expire after a period of inactivity. Bounded to prevent unbounded growth
+ * if a misbehaving client rotates IDs.
+ *
+ * Per MCP spec 2025-03-26 Streamable HTTP transport:
+ * - session IDs MUST be globally unique and cryptographically secure
+ * - requests carrying a terminated / unknown id should return 404
+ * - servers MAY assign a new id on any request
+ */
+import { randomUUID } from 'node:crypto';
+import { logger } from '../utils/index.js';
+import { LIFECYCLE_TIMEOUTS, MAX_BRIDGE_SESSIONS } from '../config/defaults.js';
+export class SessionRegistry {
+    sessions = new Map();
+    cleanupTimer = null;
+    ttlMs;
+    cleanupIntervalMs;
+    maxSessions;
+    constructor(opts) {
+        this.ttlMs = opts?.ttlMs ?? LIFECYCLE_TIMEOUTS.BRIDGE_SESSION_TTL_MS;
+        this.cleanupIntervalMs =
+            opts?.cleanupIntervalMs ?? LIFECYCLE_TIMEOUTS.BRIDGE_SESSION_CLEANUP_INTERVAL_MS;
+        this.maxSessions = opts?.maxSessions ?? MAX_BRIDGE_SESSIONS;
+    }
+    /**
+     * Begin periodic cleanup. Called by HttpBridge.start().
+     */
+    start() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => {
+            this.sweep();
+        }, this.cleanupIntervalMs);
+        this.cleanupTimer.unref?.();
+    }
+    /**
+     * Stop the cleanup timer and drop all sessions. Called by HttpBridge.stop().
+     */
+    stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.sessions.clear();
+    }
+    /**
+     * Create a new session and return its id.
+     */
+    create() {
+        this.evictIfFull();
+        const id = randomUUID();
+        const now = Date.now();
+        this.sessions.set(id, { id, createdAt: now, lastSeenAt: now });
+        return id;
+    }
+    /**
+     * Look up a session. Returns undefined if the id is unknown or expired.
+     * Expired sessions are purged lazily here even if the sweep hasn't run yet.
+     */
+    touch(id) {
+        const record = this.sessions.get(id);
+        if (!record)
+            return undefined;
+        const now = Date.now();
+        if (now - record.lastSeenAt > this.ttlMs) {
+            this.sessions.delete(id);
+            return undefined;
+        }
+        record.lastSeenAt = now;
+        return record;
+    }
+    /**
+     * Explicit termination (e.g. DELETE /session).
+     * Returns true if a session was removed.
+     */
+    terminate(id) {
+        return this.sessions.delete(id);
+    }
+    size() {
+        return this.sessions.size;
+    }
+    /**
+     * Purge sessions older than ttlMs. Exposed for tests.
+     */
+    sweep() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [id, record] of this.sessions) {
+            if (now - record.lastSeenAt > this.ttlMs) {
+                this.sessions.delete(id);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            logger.debug('Bridge session sweep', { removed, remaining: this.sessions.size });
+        }
+        return removed;
+    }
+    /**
+     * If we're at capacity, drop the oldest (by lastSeenAt) record to make room.
+     * Prevents unbounded growth under ID rotation.
+     */
+    evictIfFull() {
+        if (this.sessions.size < this.maxSessions)
+            return;
+        let oldestId;
+        let oldestSeen = Number.POSITIVE_INFINITY;
+        for (const [id, record] of this.sessions) {
+            if (record.lastSeenAt < oldestSeen) {
+                oldestSeen = record.lastSeenAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId) {
+            this.sessions.delete(oldestId);
+            logger.warn('Bridge session registry full, evicted oldest', { maxSessions: this.maxSessions });
+        }
+    }
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/bridge/session-registry.js.map

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

package/dist/cache/cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+    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;
+    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;gBAE/B,OAAO,EAAE,iBAAiB;IAgChC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAsDlF,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,OAAO,IAAI,IAAI;CAMhB"}