network-ai 4.15.2 → 5.0.0

package/dist/lib/cost-governor.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * CostGovernor — Pre-flight budget prediction for task DAGs.
+ *
+ * Walks a TaskDAG, estimates per-node token spend using a pluggable cost
+ * model, and checks the total against FederatedBudget before execution.
+ *
+ * @module CostGovernor
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostGovernor = exports.LookupCostModel = void 0;
+// ============================================================================
+// DEFAULT COST MODEL
+// ============================================================================
+/**
+ * Lookup-based cost model. Register per-agent or per-action token estimates.
+ * Falls back to a configurable default.
+ */
+class LookupCostModel {
+    agentDefaults = new Map();
+    actionOverrides = new Map();
+    defaultTokens;
+    constructor(defaultTokens = 500) {
+        this.defaultTokens = defaultTokens;
+    }
+    /** Set default token estimate for an agent */
+    setAgentDefault(agent, tokens) {
+        this.agentDefaults.set(agent, tokens);
+    }
+    /** Set token estimate for a specific agent:action pair */
+    setActionEstimate(agent, action, tokens) {
+        this.actionOverrides.set(`${agent}:${action}`, tokens);
+    }
+    estimate(agent, action, _params) {
+        const key = `${agent}:${action}`;
+        if (this.actionOverrides.has(key)) {
+            return { tokens: this.actionOverrides.get(key), confidence: 0.8 };
+        }
+        if (this.agentDefaults.has(agent)) {
+            return { tokens: this.agentDefaults.get(agent), confidence: 0.6 };
+        }
+        return { tokens: this.defaultTokens, confidence: 0.3 };
+    }
+}
+exports.LookupCostModel = LookupCostModel;
+// ============================================================================
+// COST GOVERNOR
+// ============================================================================
+/**
+ * Pre-flight budget check for task DAGs.
+ *
+ * @example
+ * ```ts
+ * const governor = new CostGovernor(budget, new LookupCostModel(1000));
+ * const prediction = governor.predict(dag.nodes);
+ * if (!prediction.withinBudget) {
+ *   console.log('DAG would exceed budget by', -prediction.budgetRemaining, 'tokens');
+ * }
+ *
+ * // As approval callback:
+ * const options = { approvalCallback: (dag) => governor.approve(dag.nodes) };
+ * ```
+ */
+class CostGovernor {
+    budget;
+    model;
+    constructor(budget, model) {
+        this.budget = budget;
+        this.model = model ?? new LookupCostModel();
+    }
+    /** Replace the cost model */
+    setCostModel(model) {
+        this.model = model;
+    }
+    /**
+     * Predict the total cost of a DAG and check against budget.
+     */
+    predict(nodes) {
+        const estimates = [];
+        const perAgent = {};
+        for (const node of nodes) {
+            const { tokens, confidence } = this.model.estimate(node.agent, node.action, node.params);
+            estimates.push({
+                taskId: node.id,
+                agent: node.agent,
+                action: node.action,
+                estimatedTokens: tokens,
+                confidence,
+            });
+            perAgent[node.agent] = (perAgent[node.agent] ?? 0) + tokens;
+        }
+        const totalTokens = estimates.reduce((sum, e) => sum + e.estimatedTokens, 0);
+        const budgetRemaining = this.budget.remaining() - totalTokens;
+        const budgetCeiling = this.budget.getCeiling();
+        const perAgentCeiling = this.budget.getPerAgentCeiling();
+        // Check per-agent overruns
+        const overBudgetAgents = [];
+        if (perAgentCeiling !== undefined) {
+            for (const [agent, predicted] of Object.entries(perAgent)) {
+                const alreadySpent = this.budget.getAgentSpent(agent);
+                if (alreadySpent + predicted > perAgentCeiling) {
+                    overBudgetAgents.push(agent);
+                }
+            }
+        }
+        const avgConfidence = estimates.length > 0
+            ? estimates.reduce((s, e) => s + e.confidence, 0) / estimates.length
+            : 0;
+        return {
+            totalTokens,
+            nodes: estimates,
+            withinBudget: budgetRemaining >= 0 && overBudgetAgents.length === 0,
+            budgetRemaining,
+            budgetCeiling,
+            perAgent,
+            overBudgetAgents,
+            averageConfidence: avgConfidence,
+        };
+    }
+    /**
+     * Approval callback for TeamRunner — returns true if DAG fits budget.
+     */
+    async approve(nodes) {
+        return this.predict(nodes).withinBudget;
+    }
+}
+exports.CostGovernor = CostGovernor;
+//# sourceMappingURL=cost-governor.js.map

package/dist/lib/cost-governor.js.map

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

package/dist/lib/cost-heatmap.d.ts

@@ -0,0 +1,104 @@
+/**
+ * CostHeatmap — Per-agent cost & performance overlay for the topology graph.
+ *
+ * Tracks token spend (with configurable USD-per-token rates), latency
+ * percentiles, throughput, and error rates per agent so the dashboard can
+ * render a cost/performance heatmap on top of the topology view.
+ *
+ * @module CostHeatmap
+ */
+/** Per-model cost rates (USD per 1K tokens) */
+export interface CostRate {
+    inputPer1k: number;
+    outputPer1k: number;
+}
+/** Recorded data point for one agent execution */
+export interface ExecutionSample {
+    timestamp: number;
+    durationMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    success: boolean;
+}
+/** Heatmap cell for a single agent */
+export interface HeatmapCell {
+    agentId: string;
+    /** Total estimated cost in USD */
+    costUsd: number;
+    /** Total tokens consumed (input + output) */
+    totalTokens: number;
+    /** Number of executions */
+    executions: number;
+    /** Error count */
+    errors: number;
+    /** Error rate (0-1) */
+    errorRate: number;
+    /** Average latency in ms */
+    avgLatencyMs: number;
+    /** p50 latency ms */
+    p50LatencyMs: number;
+    /** p95 latency ms */
+    p95LatencyMs: number;
+    /** p99 latency ms */
+    p99LatencyMs: number;
+    /** Throughput: executions per minute (over the window) */
+    throughputPerMin: number;
+    /** Normalized heat value 0-1 (higher = more expensive/slow) */
+    heat: number;
+}
+/** Full heatmap snapshot */
+export interface HeatmapSnapshot {
+    timestamp: string;
+    cells: HeatmapCell[];
+    totalCostUsd: number;
+    totalTokens: number;
+    hottestAgent: string | null;
+}
+/**
+ * Tracks per-agent cost and performance for heatmap rendering.
+ *
+ * @example
+ * ```ts
+ * const heatmap = new CostHeatmap();
+ * heatmap.setCostRate('gpt-4', { inputPer1k: 0.03, outputPer1k: 0.06 });
+ * heatmap.record('agent-1', { durationMs: 200, inputTokens: 500, outputTokens: 100, success: true });
+ * const snap = heatmap.getSnapshot();
+ * ```
+ */
+export declare class CostHeatmap {
+    private samples;
+    private costRates;
+    private agentModels;
+    private defaultRate;
+    private maxSamplesPerAgent;
+    private windowMs;
+    constructor(options?: {
+        /** Max samples to keep per agent. Default 1000 */
+        maxSamplesPerAgent?: number;
+        /** Time window for throughput calculation (ms). Default 60_000 (1 min) */
+        windowMs?: number;
+        /** Default cost rate if no model-specific rate set */
+        defaultRate?: CostRate;
+    });
+    /** Set the cost rate for a model */
+    setCostRate(model: string, rate: CostRate): void;
+    /** Associate an agent with a model (for cost lookups) */
+    setAgentModel(agentId: string, model: string): void;
+    /** Record an execution sample for an agent */
+    record(agentId: string, sample: Omit<ExecutionSample, 'timestamp'> & {
+        timestamp?: number;
+    }): void;
+    /** Get the heatmap cell for a single agent */
+    getCell(agentId: string): HeatmapCell | null;
+    /** Get the full heatmap snapshot */
+    getSnapshot(): HeatmapSnapshot;
+    /** List all tracked agent IDs */
+    listAgents(): string[];
+    /** Clear all data */
+    clear(): void;
+    /** Clear data for a specific agent */
+    clearAgent(agentId: string): void;
+    private computeCell;
+    private percentile;
+}
+//# sourceMappingURL=cost-heatmap.d.ts.map

package/dist/lib/cost-heatmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-heatmap.d.ts","sourceRoot":"","sources":["../../lib/cost-heatmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAA6C;IAC5D,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,WAAW,CAAqD;IACxE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,CAAC,EAAE;QACpB,kDAAkD;QAClD,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,0EAA0E;QAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,sDAAsD;QACtD,WAAW,CAAC,EAAE,QAAQ,CAAC;KACxB;IAMD,oCAAoC;IACpC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI;IAIhD,yDAAyD;IACzD,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAInD,8CAA8C;IAC9C,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAClE,IAAI;IAqBP,8CAA8C;IAC9C,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAM5C,oCAAoC;IACpC,WAAW,IAAI,eAAe;IAgC9B,iCAAiC;IACjC,UAAU,IAAI,MAAM,EAAE;IAItB,qBAAqB;IACrB,KAAK,IAAI,IAAI;IAIb,sCAAsC;IACtC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC,OAAO,CAAC,WAAW;IAyCnB,OAAO,CAAC,UAAU;CAKnB"}

package/dist/lib/cost-heatmap.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * CostHeatmap — Per-agent cost & performance overlay for the topology graph.
+ *
+ * Tracks token spend (with configurable USD-per-token rates), latency
+ * percentiles, throughput, and error rates per agent so the dashboard can
+ * render a cost/performance heatmap on top of the topology view.
+ *
+ * @module CostHeatmap
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostHeatmap = void 0;
+// ============================================================================
+// HEATMAP
+// ============================================================================
+/**
+ * Tracks per-agent cost and performance for heatmap rendering.
+ *
+ * @example
+ * ```ts
+ * const heatmap = new CostHeatmap();
+ * heatmap.setCostRate('gpt-4', { inputPer1k: 0.03, outputPer1k: 0.06 });
+ * heatmap.record('agent-1', { durationMs: 200, inputTokens: 500, outputTokens: 100, success: true });
+ * const snap = heatmap.getSnapshot();
+ * ```
+ */
+class CostHeatmap {
+    samples = new Map();
+    costRates = new Map();
+    agentModels = new Map();
+    defaultRate = { inputPer1k: 0.01, outputPer1k: 0.03 };
+    maxSamplesPerAgent;
+    windowMs;
+    constructor(options) {
+        this.maxSamplesPerAgent = options?.maxSamplesPerAgent ?? 1000;
+        this.windowMs = options?.windowMs ?? 60_000;
+        if (options?.defaultRate)
+            this.defaultRate = options.defaultRate;
+    }
+    /** Set the cost rate for a model */
+    setCostRate(model, rate) {
+        this.costRates.set(model, rate);
+    }
+    /** Associate an agent with a model (for cost lookups) */
+    setAgentModel(agentId, model) {
+        this.agentModels.set(agentId, model);
+    }
+    /** Record an execution sample for an agent */
+    record(agentId, sample) {
+        let list = this.samples.get(agentId);
+        if (!list) {
+            list = [];
+            this.samples.set(agentId, list);
+        }
+        list.push({
+            timestamp: sample.timestamp ?? Date.now(),
+            durationMs: sample.durationMs,
+            inputTokens: sample.inputTokens,
+            outputTokens: sample.outputTokens,
+            success: sample.success,
+        });
+        // Evict oldest
+        if (list.length > this.maxSamplesPerAgent) {
+            list.splice(0, list.length - this.maxSamplesPerAgent);
+        }
+    }
+    /** Get the heatmap cell for a single agent */
+    getCell(agentId) {
+        const list = this.samples.get(agentId);
+        if (!list || list.length === 0)
+            return null;
+        return this.computeCell(agentId, list);
+    }
+    /** Get the full heatmap snapshot */
+    getSnapshot() {
+        const cells = [];
+        let totalCostUsd = 0;
+        let totalTokens = 0;
+        for (const [agentId, list] of this.samples) {
+            if (list.length === 0)
+                continue;
+            const cell = this.computeCell(agentId, list);
+            cells.push(cell);
+            totalCostUsd += cell.costUsd;
+            totalTokens += cell.totalTokens;
+        }
+        // Normalize heat values (relative to max cost in this snapshot)
+        const maxCost = Math.max(...cells.map(c => c.costUsd), 0.001);
+        const maxLatency = Math.max(...cells.map(c => c.p95LatencyMs), 1);
+        for (const cell of cells) {
+            // Heat = 60% cost weight + 40% latency weight
+            cell.heat = Math.min(1, 0.6 * (cell.costUsd / maxCost) + 0.4 * (cell.p95LatencyMs / maxLatency));
+        }
+        cells.sort((a, b) => b.heat - a.heat);
+        return {
+            timestamp: new Date().toISOString(),
+            cells,
+            totalCostUsd,
+            totalTokens,
+            hottestAgent: cells.length > 0 ? cells[0].agentId : null,
+        };
+    }
+    /** List all tracked agent IDs */
+    listAgents() {
+        return [...this.samples.keys()];
+    }
+    /** Clear all data */
+    clear() {
+        this.samples.clear();
+    }
+    /** Clear data for a specific agent */
+    clearAgent(agentId) {
+        this.samples.delete(agentId);
+    }
+    computeCell(agentId, list) {
+        const model = this.agentModels.get(agentId);
+        const rate = model ? (this.costRates.get(model) ?? this.defaultRate) : this.defaultRate;
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalDurationMs = 0;
+        let errors = 0;
+        const durations = [];
+        const now = Date.now();
+        let recentCount = 0;
+        for (const s of list) {
+            totalInputTokens += s.inputTokens;
+            totalOutputTokens += s.outputTokens;
+            totalDurationMs += s.durationMs;
+            durations.push(s.durationMs);
+            if (!s.success)
+                errors++;
+            if (now - s.timestamp <= this.windowMs)
+                recentCount++;
+        }
+        durations.sort((a, b) => a - b);
+        const totalTokens = totalInputTokens + totalOutputTokens;
+        const costUsd = (totalInputTokens / 1000) * rate.inputPer1k + (totalOutputTokens / 1000) * rate.outputPer1k;
+        return {
+            agentId,
+            costUsd,
+            totalTokens,
+            executions: list.length,
+            errors,
+            errorRate: list.length > 0 ? errors / list.length : 0,
+            avgLatencyMs: list.length > 0 ? totalDurationMs / list.length : 0,
+            p50LatencyMs: this.percentile(durations, 0.50),
+            p95LatencyMs: this.percentile(durations, 0.95),
+            p99LatencyMs: this.percentile(durations, 0.99),
+            throughputPerMin: this.windowMs > 0 ? (recentCount / this.windowMs) * 60_000 : 0,
+            heat: 0, // Will be normalized in getSnapshot()
+        };
+    }
+    percentile(sorted, p) {
+        if (sorted.length === 0)
+            return 0;
+        const idx = Math.ceil(p * sorted.length) - 1;
+        return sorted[Math.max(0, idx)];
+    }
+}
+exports.CostHeatmap = CostHeatmap;
+//# sourceMappingURL=cost-heatmap.js.map

package/dist/lib/cost-heatmap.js.map

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

package/dist/lib/coverage-reporter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * CoverageReporter — Lightweight code coverage reporting without external deps
+ *
+ * Integrates with Node.js built-in V8 coverage (`NODE_V8_COVERAGE`).
+ * Parses V8 coverage JSON output into a structured report with file-level
+ * line and function coverage metrics. Supports thresholds and reporters.
+ *
+ * Usage:
+ *   // Run tests with V8 coverage:
+ *   // NODE_V8_COVERAGE=./coverage npx ts-node test.ts
+ *
+ *   const reporter = new CoverageReporter({ coverageDir: './coverage' });
+ *   const report = await reporter.collect();
+ *   reporter.printSummary(report);
+ *   reporter.enforce(report, { linePct: 80, branchPct: 70 });
+ *
+ * @module CoverageReporter
+ * @version 1.0.0
+ */
+/** Coverage stats for a single file */
+export interface FileCoverage {
+    /** File path (relative to project root) */
+    file: string;
+    /** Total functions found */
+    totalFunctions: number;
+    /** Functions with at least one call */
+    coveredFunctions: number;
+    /** Function coverage percentage (0-100) */
+    functionPct: number;
+    /** Total byte ranges */
+    totalRanges: number;
+    /** Ranges with count > 0 */
+    coveredRanges: number;
+    /** Range coverage percentage (0-100) */
+    rangePct: number;
+}
+/** Aggregate coverage report */
+export interface CoverageReport {
+    /** Individual file coverage */
+    files: FileCoverage[];
+    /** Aggregate function coverage % */
+    totalFunctionPct: number;
+    /** Aggregate range coverage % */
+    totalRangePct: number;
+    /** Total files analyzed */
+    fileCount: number;
+    /** Timestamp */
+    generatedAt: number;
+}
+/** Coverage thresholds */
+export interface CoverageThresholds {
+    /** Minimum function coverage % (0-100) */
+    functionPct?: number;
+    /** Minimum range/branch coverage % (0-100) */
+    rangePct?: number;
+    /** Per-file minimum function coverage % */
+    perFileFunctionPct?: number;
+}
+/** Coverage reporter configuration */
+export interface CoverageReporterConfig {
+    /** Directory containing V8 coverage JSON files */
+    coverageDir: string;
+    /** Project root for relative path computation */
+    projectRoot?: string;
+    /** File patterns to include (substring match) */
+    include?: string[];
+    /** File patterns to exclude (substring match) */
+    exclude?: string[];
+}
+/**
+ * CoverageReporter — Collects and reports V8 code coverage data.
+ */
+export declare class CoverageReporter {
+    private readonly config;
+    constructor(config: CoverageReporterConfig);
+    /**
+     * Collect coverage data from V8 coverage directory.
+     */
+    collect(): Promise<CoverageReport>;
+    /**
+     * Print a summary table to console.
+     */
+    printSummary(report: CoverageReport): void;
+    /**
+     * Enforce coverage thresholds. Throws if below threshold.
+     */
+    enforce(report: CoverageReport, thresholds: CoverageThresholds): void;
+    private findCoverageFiles;
+    private shouldInclude;
+    private toRelativePath;
+}
+//# sourceMappingURL=coverage-reporter.d.ts.map

package/dist/lib/coverage-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-reporter.d.ts","sourceRoot":"","sources":["../../lib/coverage-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgCH,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,oCAAoC;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0BAA0B;AAC1B,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAE9C,MAAM,EAAE,sBAAsB;IAS1C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;IAyDxC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAsB1C;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,GAAG,IAAI;YAkCvD,iBAAiB;IAe/B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc;CAYvB"}