network-ai 5.10.1 → 5.11.0

package/dist/esm/lib/fan-out.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Fan-Out / Fan-In — Parallel agent spawning and result aggregation
+ *
+ * Launches multiple agents in parallel (fan-out) and combines their results
+ * using pluggable strategies (fan-in). Supports concurrency limits, timeouts,
+ * and custom aggregation. Inspired by Claude Code's parallel agent patterns.
+ *
+ * @module FanOutFanIn
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FanOutFanIn = void 0;
+// ============================================================================
+// FAN-OUT / FAN-IN
+// ============================================================================
+/**
+ * Parallel agent execution with pluggable result aggregation.
+ *
+ * @example
+ * ```typescript
+ * const fanout = new FanOutFanIn(registry, { agentId: 'orchestrator' });
+ *
+ * const steps: FanOutStep[] = [
+ *   { agentId: 'researcher-a', payload: { action: 'search', params: { q: 'AI safety' } }, label: 'web' },
+ *   { agentId: 'researcher-b', payload: { action: 'search', params: { q: 'AI safety' } }, label: 'papers' },
+ *   { agentId: 'researcher-c', payload: { action: 'search', params: { q: 'AI safety' } }, label: 'news' },
+ * ];
+ *
+ * const results = await fanout.fanOut(steps, { concurrency: 2 });
+ * const aggregated = fanout.fanIn(results, 'merge');
+ * ```
+ */
+class FanOutFanIn {
+    registry;
+    baseContext;
+    /**
+     * @param registry Adapter registry for agent execution
+     * @param baseContext Default execution context (merged with step-level overrides)
+     */
+    constructor(registry, baseContext) {
+        this.registry = registry;
+        this.baseContext = baseContext;
+    }
+    /**
+     * Execute agents in parallel (fan-out phase).
+     *
+     * Uses a true semaphore queue — as soon as one slot frees up the next
+     * step starts, rather than waiting for an entire chunk to drain.
+     *
+     * @param steps Steps to execute
+     * @param options Concurrency and timeout settings
+     */
+    async fanOut(steps, options = {}) {
+        if (steps.length === 0)
+            return [];
+        const maxConcurrency = Math.max(1, options.concurrency ?? steps.length);
+        const continueOnError = options.continueOnError ?? true;
+        const results = new Array(steps.length);
+        return new Promise((resolve) => {
+            let activeCount = 0;
+            let nextToStart = 0;
+            let completedCount = 0;
+            let shouldAbort = false;
+            const checkDone = () => {
+                if (completedCount === steps.length) {
+                    resolve(results);
+                }
+            };
+            /** Mark all not-yet-started (and not-yet-filled) slots as SKIPPED. */
+            const markRemainingSkipped = (fromIdx) => {
+                for (let k = fromIdx; k < steps.length; k++) {
+                    if (results[k] === undefined) {
+                        results[k] = {
+                            agentId: steps[k].agentId,
+                            label: steps[k].label,
+                            index: k,
+                            result: {
+                                success: false,
+                                error: { code: 'FANOUT_SKIPPED', message: 'Skipped due to earlier failure', recoverable: false },
+                            },
+                            durationMs: 0,
+                        };
+                        completedCount++;
+                    }
+                }
+            };
+            const onTaskDone = (tagged, isFailure) => {
+                results[tagged.index] = tagged;
+                activeCount--;
+                completedCount++;
+                if (!continueOnError && isFailure && !shouldAbort) {
+                    shouldAbort = true;
+                    // Skip all tasks that haven't been picked up yet
+                    markRemainingSkipped(nextToStart);
+                }
+                checkDone();
+                if (!shouldAbort) {
+                    scheduleNext();
+                }
+            };
+            const scheduleNext = () => {
+                while (activeCount < maxConcurrency && nextToStart < steps.length && !shouldAbort) {
+                    const idx = nextToStart++;
+                    activeCount++;
+                    this.executeStep(steps[idx], idx, options.timeoutMs).then((tagged) => onTaskDone(tagged, !tagged.result.success), (reason) => {
+                        const tagged = {
+                            agentId: steps[idx].agentId,
+                            label: steps[idx].label,
+                            index: idx,
+                            result: {
+                                success: false,
+                                error: { code: 'FANOUT_ERROR', message: String(reason), recoverable: false },
+                            },
+                            durationMs: 0,
+                        };
+                        onTaskDone(tagged, true);
+                    });
+                }
+            };
+            scheduleNext();
+        });
+    }
+    /**
+     * Aggregate results (fan-in phase).
+     *
+     * @param results Tagged results from fan-out
+     * @param strategy Aggregation strategy to apply
+     * @param customReducer Required when strategy is 'custom'
+     */
+    fanIn(results, strategy = 'merge', customReducer) {
+        const totalMs = results.reduce((sum, r) => sum + r.durationMs, 0);
+        const successCount = results.filter(r => r.result.success).length;
+        const failureCount = results.length - successCount;
+        let success;
+        let data;
+        switch (strategy) {
+            case 'merge': {
+                success = successCount > 0;
+                data = results.map(r => ({
+                    agentId: r.agentId,
+                    label: r.label,
+                    success: r.result.success,
+                    data: r.result.data,
+                }));
+                break;
+            }
+            case 'firstSuccess': {
+                const first = results.find(r => r.result.success);
+                success = !!first;
+                data = first?.result.data ?? null;
+                break;
+            }
+            case 'vote': {
+                const votes = new Map();
+                for (const r of results) {
+                    if (!r.result.success)
+                        continue;
+                    const key = JSON.stringify(r.result.data);
+                    const existing = votes.get(key);
+                    if (existing) {
+                        existing.count++;
+                    }
+                    else {
+                        votes.set(key, { count: 1, data: r.result.data });
+                    }
+                }
+                let best;
+                for (const v of votes.values()) {
+                    if (!best || v.count > best.count)
+                        best = v;
+                }
+                success = !!best;
+                data = best?.data ?? null;
+                break;
+            }
+            case 'consensus': {
+                const successResults = results.filter(r => r.result.success);
+                if (successResults.length === 0) {
+                    success = false;
+                    data = null;
+                }
+                else {
+                    const first = JSON.stringify(successResults[0].result.data);
+                    const allAgree = successResults.every(r => JSON.stringify(r.result.data) === first);
+                    success = allAgree;
+                    data = allAgree ? successResults[0].result.data : null;
+                }
+                break;
+            }
+            case 'custom': {
+                if (!customReducer) {
+                    throw new Error('customReducer is required when strategy is "custom"');
+                }
+                const reduced = customReducer(results);
+                success = reduced.success;
+                data = reduced.data;
+                break;
+            }
+        }
+        return { success, strategy, data, results, totalMs, successCount, failureCount };
+    }
+    /**
+     * Convenience: fan-out + fan-in in a single call.
+     */
+    async run(steps, strategy = 'merge', options, customReducer) {
+        const results = await this.fanOut(steps, options);
+        return this.fanIn(results, strategy, customReducer);
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    async executeStep(step, index, globalTimeout) {
+        const ctx = { ...this.baseContext, ...step.context };
+        const timeout = step.timeoutMs ?? globalTimeout;
+        const start = Date.now();
+        let result;
+        if (timeout) {
+            result = await Promise.race([
+                this.registry.executeAgent(step.agentId, step.payload, ctx),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Fan-out timeout: agent "${step.agentId}" exceeded ${timeout}ms`)), timeout)),
+            ]);
+        }
+        else {
+            result = await this.registry.executeAgent(step.agentId, step.payload, ctx);
+        }
+        return {
+            agentId: step.agentId,
+            label: step.label,
+            index,
+            result,
+            durationMs: Date.now() - start,
+        };
+    }
+}
+exports.FanOutFanIn = FanOutFanIn;
+//# sourceMappingURL=fan-out.js.map

package/dist/esm/lib/fan-out.js.map

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

package/dist/esm/lib/federated-budget.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Federated Budget Tracking
+ *
+ * Tracks token spending across distributed agent swarms. Each `FederatedBudget`
+ * instance enforces a global ceiling shared among all agents that call `spend()`.
+ *
+ * When an optional `BlackboardBackend` is supplied, the budget state is written
+ * to the blackboard after every mutation. Wiring a `CrdtBackend` or `RedisBackend`
+ * as the underlying backend therefore gives automatic cross-node synchronization
+ * with no extra configuration.
+ *
+ * Architecture:
+ *   - In-memory `spent` map keyed by `agentId` holds per-agent cumulative totals.
+ *   - `spend()` is synchronous and enforces both the global ceiling and an optional
+ *     per-agent ceiling in a single check.
+ *   - A `blackboard` backend (if supplied) stores a JSON snapshot under `budgetKey`
+ *     after every `spend()` / `reset()` / `setCeiling()` call so distributed nodes
+ *     can read the latest state.
+ *   - `loadFromBlackboard()` deserializes a previously saved snapshot so a
+ *     restarted node can recover its prior accumulated spend.
+ *
+ * @example
+ * ```typescript
+ * import { FederatedBudget } from 'network-ai';
+ *
+ * const budget = new FederatedBudget({ ceiling: 10_000 });
+ *
+ * budget.spend('agent-1', 3000); // { allowed: true,  remaining: 7000 }
+ * budget.spend('agent-2', 8000); // { allowed: false, remaining: 7000 }
+ * budget.remaining();            // 7000
+ * budget.getSpendLog();          // { 'agent-1': 3000 }
+ * ```
+ *
+ * @example With blackboard persistence
+ * ```typescript
+ * import { CrdtBackend } from 'network-ai';
+ * import { FederatedBudget } from 'network-ai';
+ *
+ * const node = new CrdtBackend('node-a');
+ * const budget = new FederatedBudget({ ceiling: 50_000, blackboard: node });
+ *
+ * budget.spend('agent-1', 1000);
+ * // State is now stored in node under 'federated-budget'
+ * // Sync node to other CrdtBackend nodes to propagate the spend.
+ * ```
+ *
+ * @module FederatedBudget
+ * @version 1.0.0
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FederatedBudget = void 0;
+// ============================================================================
+// FEDERATED BUDGET
+// ============================================================================
+/**
+ * Federated token-budget tracker for distributed agent swarms.
+ *
+ * Enforces a shared global ceiling across all agents and optionally an
+ * individual per-agent ceiling. State can be persisted to any
+ * `BlackboardBackend` for cross-node visibility.
+ */
+class FederatedBudget {
+    _ceiling;
+    _dynamicCeiling;
+    _perAgentCeiling;
+    _spent = new Map();
+    _totalSpent = 0;
+    _log = [];
+    _blackboard;
+    _budgetKey;
+    _bbAgent;
+    constructor(options) {
+        if (typeof options.ceiling !== 'number' || options.ceiling <= 0 || !Number.isFinite(options.ceiling)) {
+            throw new RangeError('FederatedBudget: ceiling must be a positive finite number');
+        }
+        if (options.perAgentCeiling !== undefined &&
+            (typeof options.perAgentCeiling !== 'number' ||
+                options.perAgentCeiling <= 0 ||
+                !Number.isFinite(options.perAgentCeiling))) {
+            throw new RangeError('FederatedBudget: perAgentCeiling must be a positive finite number when provided');
+        }
+        this._ceiling = options.ceiling;
+        this._dynamicCeiling = options.ceiling;
+        this._perAgentCeiling = options.perAgentCeiling;
+        this._blackboard = options.blackboard;
+        this._budgetKey = options.budgetKey ?? 'federated-budget';
+        this._bbAgent = options.blackboardAgent ?? 'federated-budget-tracker';
+    }
+    // --------------------------------------------------------------------------
+    // PUBLIC API
+    // --------------------------------------------------------------------------
+    /**
+     * Attempt to spend `tokens` on behalf of `agentId`.
+     *
+     * The spend is allowed only when:
+     *   1. `totalSpent + tokens <= ceiling` (global ceiling not breached), AND
+     *   2. `agentSpent + tokens <= perAgentCeiling` if a per-agent ceiling is set.
+     *
+     * When allowed the internal counters are updated and the state is persisted
+     * to the blackboard (if configured).
+     *
+     * @param agentId  Identifier of the spending agent. Must be a non-empty string.
+     * @param tokens   Number of tokens to spend. Must be a positive integer.
+     * @returns        `SpendResult` with `allowed`, `remaining`, and optional `deniedReason`.
+     */
+    spend(agentId, tokens) {
+        if (!agentId || typeof agentId !== 'string') {
+            throw new TypeError('FederatedBudget.spend: agentId must be a non-empty string');
+        }
+        if (typeof tokens !== 'number' || tokens <= 0 || !Number.isFinite(tokens)) {
+            throw new RangeError('FederatedBudget.spend: tokens must be a positive finite number');
+        }
+        const agentSpent = this._spent.get(agentId) ?? 0;
+        // Check per-agent ceiling first (lower ceiling wins)
+        if (this._perAgentCeiling !== undefined && agentSpent + tokens > this._perAgentCeiling) {
+            return {
+                allowed: false,
+                remaining: this.remaining(),
+                deniedReason: 'per_agent_ceiling',
+            };
+        }
+        // Check global ceiling
+        if (this._totalSpent + tokens > this._dynamicCeiling) {
+            return {
+                allowed: false,
+                remaining: this.remaining(),
+                deniedReason: 'global_ceiling',
+            };
+        }
+        // Commit
+        this._spent.set(agentId, agentSpent + tokens);
+        this._totalSpent += tokens;
+        this._log.push({
+            agentId,
+            tokens,
+            timestamp: new Date().toISOString(),
+        });
+        this._persist();
+        return {
+            allowed: true,
+            remaining: this.remaining(),
+        };
+    }
+    /**
+     * Remaining tokens in the global pool.
+     */
+    remaining() {
+        return Math.max(0, this._dynamicCeiling - this._totalSpent);
+    }
+    /**
+     * Total tokens spent across all agents.
+     */
+    getTotalSpent() {
+        return this._totalSpent;
+    }
+    /**
+     * Tokens spent by a specific agent. Returns `0` if the agent has no spend.
+     */
+    getAgentSpent(agentId) {
+        return this._spent.get(agentId) ?? 0;
+    }
+    /**
+     * Per-agent spend totals as a plain object: `{ agentId: totalTokens }`.
+     */
+    getSpendLog() {
+        const result = {};
+        for (const [id, total] of this._spent) {
+            result[id] = total;
+        }
+        return result;
+    }
+    /**
+     * Detailed transaction log — every individual `spend()` call in order.
+     */
+    getTransactionLog() {
+        return this._log.slice();
+    }
+    /**
+     * Current global ceiling (may differ from the original if `setCeiling()` was called).
+     */
+    getCeiling() {
+        return this._dynamicCeiling;
+    }
+    /**
+     * Per-agent ceiling, or `undefined` if none was configured.
+     */
+    getPerAgentCeiling() {
+        return this._perAgentCeiling;
+    }
+    /**
+     * Dynamically adjust the global ceiling.
+     *
+     * The new ceiling must be a positive finite number. It may be set below
+     * the current `totalSpent` (no previously approved spends are reversed, but
+     * future spends will be denied until tokens are freed by a `reset()`).
+     *
+     * @param ceiling  New global ceiling.
+     */
+    setCeiling(ceiling) {
+        if (typeof ceiling !== 'number' || ceiling <= 0 || !Number.isFinite(ceiling)) {
+            throw new RangeError('FederatedBudget.setCeiling: ceiling must be a positive finite number');
+        }
+        this._dynamicCeiling = ceiling;
+        this._persist();
+    }
+    /**
+     * Reset all spend counters and clear the transaction log.
+     *
+     * The global ceiling is preserved (its current value after any `setCeiling()`
+     * calls). After a reset `remaining() === getCeiling()`.
+     *
+     * The blackboard entry (if configured) is updated with the reset state.
+     */
+    reset() {
+        this._spent.clear();
+        this._totalSpent = 0;
+        this._log.length = 0;
+        this._persist();
+    }
+    /**
+     * Spawn a child budget whose ceiling is drawn from this budget's remaining pool.
+     *
+     * RLM-style recursive budget propagation: the child gets an isolated spend
+     * tracker capped at `childCeiling` (or the full remaining amount if omitted).
+     * Call `commit()` on the returned handle to propagate the child's total spend
+     * back to the parent as a single atomic `spend()` call.
+     *
+     * This enables recursive sub-agent trees where each level can only consume
+     * what its parent has left, and costs bubble back up the chain automatically.
+     *
+     * @example
+     * ```typescript
+     * const root = new FederatedBudget({ ceiling: 10_000 });
+     * const { budget: child, commit } = root.spawnChild('sub-agent-A', 3000);
+     * child.spend('worker-1', 800);
+     * child.spend('worker-2', 600);
+     * commit(); // propagates 1400 tokens back to root
+     * root.getTotalSpent(); // 1400
+     * ```
+     *
+     * @param spenderId     agentId recorded on the parent when `commit()` is called.
+     * @param childCeiling  Optional upper bound for the child (defaults to `remaining()`).
+     * @returns             Object with the child `FederatedBudget` and a `commit` function.
+     */
+    spawnChild(spenderId, childCeiling) {
+        if (!spenderId || typeof spenderId !== 'string') {
+            throw new TypeError('FederatedBudget.spawnChild: spenderId must be a non-empty string');
+        }
+        const available = this.remaining();
+        const effectiveCeiling = Math.min(childCeiling !== undefined ? childCeiling : available, available);
+        // Guarantee a valid (positive) ceiling even when the parent is exhausted.
+        const safeCeiling = effectiveCeiling > 0 ? effectiveCeiling : 1;
+        const child = new FederatedBudget({
+            ceiling: safeCeiling,
+            perAgentCeiling: this._perAgentCeiling,
+        });
+        const commit = () => {
+            const childSpent = child.getTotalSpent();
+            if (childSpent <= 0) {
+                return { allowed: true, remaining: this.remaining() };
+            }
+            return this.spend(spenderId, childSpent);
+        };
+        return { budget: child, commit };
+    }
+    /**
+     * Restore budget state from the blackboard backend.
+     *
+     * Reads the entry stored under `budgetKey`, deserializes the snapshot, and
+     * replaces the current in-memory state. Useful when a node restarts and
+     * needs to recover its prior accumulated spend.
+     *
+     * No-op (returns `false`) when no blackboard is configured or no entry exists.
+     *
+     * @returns `true` if state was successfully loaded, `false` otherwise.
+     */
+    loadFromBlackboard() {
+        if (!this._blackboard)
+            return false;
+        const entry = this._blackboard.read(this._budgetKey);
+        if (!entry)
+            return false;
+        try {
+            const snapshot = JSON.parse(entry.value);
+            this._spent.clear();
+            for (const [id, total] of Object.entries(snapshot.spent)) {
+                this._spent.set(id, total);
+            }
+            this._totalSpent = snapshot.totalSpent;
+            this._dynamicCeiling = snapshot.ceiling;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // --------------------------------------------------------------------------
+    // PRIVATE HELPERS
+    // --------------------------------------------------------------------------
+    /** Serialize current state to the blackboard, if one is configured. */
+    _persist() {
+        if (!this._blackboard)
+            return;
+        const snapshot = {
+            ceiling: this._dynamicCeiling,
+            perAgentCeiling: this._perAgentCeiling,
+            spent: this.getSpendLog(),
+            totalSpent: this._totalSpent,
+        };
+        try {
+            this._blackboard.write(this._budgetKey, JSON.stringify(snapshot), this._bbAgent);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[FederatedBudget] Blackboard persist failed — in-memory state is ahead of disk: ${msg}`);
+        }
+    }
+}
+exports.FederatedBudget = FederatedBudget;
+//# sourceMappingURL=federated-budget.js.map

package/dist/esm/lib/federated-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federated-budget.js","sourceRoot":"","sources":["../../../lib/federated-budget.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;;;AAwFH,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAa,eAAe;IACT,QAAQ,CAAS;IAC1B,eAAe,CAAS;IACf,gBAAgB,CAAqB;IACrC,MAAM,GAAwB,IAAI,GAAG,EAAE,CAAC;IACjD,WAAW,GAAG,CAAC,CAAC;IACP,IAAI,GAAoB,EAAE,CAAC;IAC3B,WAAW,CAAgC;IAC3C,UAAU,CAAS;IACnB,QAAQ,CAAS;IAElC,YAAY,OAA+B;QACzC,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACrG,MAAM,IAAI,UAAU,CAAC,2DAA2D,CAAC,CAAC;QACpF,CAAC;QACD,IACE,OAAO,CAAC,eAAe,KAAK,SAAS;YACrC,CAAC,OAAO,OAAO,CAAC,eAAe,KAAK,QAAQ;gBAC1C,OAAO,CAAC,eAAe,IAAI,CAAC;gBAC5B,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,iFAAiF,CAAC,CAAC;QAC1G,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;QACvC,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;QAChD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;QAC1D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,eAAe,IAAI,0BAA0B,CAAC;IACxE,CAAC;IAED,6EAA6E;IAC7E,aAAa;IACb,6EAA6E;IAE7E;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAe,EAAE,MAAc;QACnC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,UAAU,CAAC,gEAAgE,CAAC,CAAC;QACzF,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEjD,qDAAqD;QACrD,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,IAAI,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACvF,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;gBAC3B,YAAY,EAAE,mBAAmB;aAClC,CAAC;QACJ,CAAC;QAED,uBAAuB;QACvB,IAAI,IAAI,CAAC,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YACrD,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;gBAC3B,YAAY,EAAE,gBAAgB;aAC/B,CAAC;QACJ,CAAC;QAED,SAAS;QACT,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC,CAAC;QAC9C,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,OAAO;YACP,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,EAAE,CAAC;QAEhB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;SAC5B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,OAAe;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,WAAW;QACT,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,iBAAiB;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAe;QACxB,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7E,MAAM,IAAI,UAAU,CAAC,sEAAsE,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAC/B,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,UAAU,CACR,SAAiB,EACjB,YAAqB;QAErB,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,IAAI,SAAS,CAAC,kEAAkE,CAAC,CAAC;QAC1F,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAC/B,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,EACrD,SAAS,CACV,CAAC;QACF,0EAA0E;QAC1E,MAAM,WAAW,GAAG,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;QAEhE,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;YAChC,OAAO,EAAE,WAAW;YACpB,eAAe,EAAE,IAAI,CAAC,gBAAgB;SACvC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,GAAgB,EAAE;YAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;YACzC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;gBACpB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;YACxD,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QAC3C,CAAC,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACnC,CAAC;IAED;;;;;;;;;;OAUG;IACH,kBAAkB;QAChB,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAmB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAe,CAAC,CAAC;YACnE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC7B,CAAC;YACD,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC;YACvC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC;YACxC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,kBAAkB;IAClB,6EAA6E;IAE7E,uEAAuE;IAC/D,QAAQ;QACd,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,MAAM,QAAQ,GAAmB;YAC/B,OAAO,EAAE,IAAI,CAAC,eAAe;YAC7B,eAAe,EAAE,IAAI,CAAC,gBAAgB;YACtC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE;YACzB,UAAU,EAAE,IAAI,CAAC,WAAW;SAC7B,CAAC;QACF,IAAI,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,mFAAmF,GAAG,EAAE,CAAC,CAAC;QACzG,CAAC;IACH,CAAC;CACF;AA9RD,0CA8RC"}