@theihtisham/agent-shadow-brain 5.2.0 → 6.0.2

package/dist/brain/collision-detective.js

@@ -0,0 +1,233 @@
+// src/brain/collision-detective.ts — Agent Collision Detective
+// v6.0.0 — Hive Mind Edition
+//
+// Real-time (not post-hoc git) detection of two+ agents about to edit the same
+// file region. Agents declare their edit INTENT before touching the file, the
+// detective maintains active intents, and any overlapping intent produces a
+// CollisionAlert with a suggested resolution.
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+const INTENTS_PATH = path.join(os.homedir(), '.shadow-brain', 'collision-intents.json');
+const DEFAULT_INTENT_TTL_MS = 10 * 60 * 1000; // 10 minutes
+function emptyStats() {
+    return {
+        totalIntents: 0,
+        activeIntents: 0,
+        collisionsDetected: 0,
+        collisionsResolved: 0,
+        collisionsByAgent: {},
+        avgOverlapLines: 0,
+    };
+}
+export class CollisionDetective {
+    constructor() {
+        this.intents = new Map();
+        this.alerts = new Map();
+        this.stats = emptyStats();
+        this.initialized = false;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        fs.mkdirSync(path.dirname(INTENTS_PATH), { recursive: true });
+        if (fs.existsSync(INTENTS_PATH)) {
+            try {
+                const raw = fs.readFileSync(INTENTS_PATH, 'utf-8');
+                const parsed = JSON.parse(raw);
+                for (const intent of parsed.intents ?? []) {
+                    const r = {
+                        ...intent,
+                        declaredAt: new Date(intent.declaredAt),
+                        expiresAt: new Date(intent.expiresAt),
+                    };
+                    if (r.expiresAt.getTime() > Date.now()) {
+                        this.intents.set(this.keyForIntent(r), r);
+                    }
+                }
+                for (const alert of parsed.alerts ?? []) {
+                    this.alerts.set(alert.id, {
+                        ...alert,
+                        detectedAt: new Date(alert.detectedAt),
+                        conflictingIntents: alert.conflictingIntents.map(i => ({
+                            ...i,
+                            declaredAt: new Date(i.declaredAt),
+                            expiresAt: new Date(i.expiresAt),
+                        })),
+                    });
+                }
+                if (parsed.stats)
+                    this.stats = { ...emptyStats(), ...parsed.stats };
+            }
+            catch {
+                /* corrupt — start fresh */
+            }
+        }
+        this.initialized = true;
+    }
+    /** Agent declares intent to edit a file range. Returns immediate collision alert if any. */
+    async declareIntent(agentTool, sessionId, filePath, startLine, endLine, intent, ttlMs = DEFAULT_INTENT_TTL_MS) {
+        await this.init();
+        this.evictExpired();
+        const abs = path.resolve(filePath);
+        const declaration = {
+            agentTool,
+            sessionId,
+            filePath: abs,
+            startLine: Math.min(startLine, endLine),
+            endLine: Math.max(startLine, endLine),
+            intent,
+            declaredAt: new Date(),
+            expiresAt: new Date(Date.now() + ttlMs),
+        };
+        const key = this.keyForIntent(declaration);
+        this.intents.set(key, declaration);
+        this.stats.totalIntents++;
+        this.stats.activeIntents = this.intents.size;
+        this.stats.collisionsByAgent[agentTool] = this.stats.collisionsByAgent[agentTool] ?? 0;
+        const collision = this.detectForIntent(declaration);
+        if (collision) {
+            this.alerts.set(collision.id, collision);
+            this.stats.collisionsDetected++;
+            for (const conflict of collision.conflictingIntents) {
+                this.stats.collisionsByAgent[conflict.agentTool] = (this.stats.collisionsByAgent[conflict.agentTool] ?? 0) + 1;
+            }
+            const overlapSize = collision.overlapEndLine - collision.overlapStartLine + 1;
+            const n = this.stats.collisionsDetected;
+            this.stats.avgOverlapLines = this.stats.avgOverlapLines + (overlapSize - this.stats.avgOverlapLines) / n;
+        }
+        await this.persist();
+        return { intent: declaration, collision };
+    }
+    /** Release an intent — agent finished or cancelled. */
+    async releaseIntent(agentTool, sessionId, filePath) {
+        await this.init();
+        const abs = path.resolve(filePath);
+        let removed = 0;
+        for (const [key, intent] of this.intents) {
+            if (intent.agentTool === agentTool && intent.sessionId === sessionId && intent.filePath === abs) {
+                this.intents.delete(key);
+                removed++;
+            }
+        }
+        if (removed) {
+            this.stats.activeIntents = this.intents.size;
+            await this.persist();
+        }
+        return removed;
+    }
+    /** Mark a collision as resolved (by reassignment, merge, or user action). */
+    async resolveCollision(alertId, resolution) {
+        await this.init();
+        const alert = this.alerts.get(alertId);
+        if (!alert)
+            return false;
+        alert.suggestedResolution = resolution;
+        this.stats.collisionsResolved++;
+        this.alerts.delete(alertId);
+        await this.persist();
+        return true;
+    }
+    /** All active (unresolved) alerts. */
+    activeAlerts() {
+        return Array.from(this.alerts.values()).sort((a, b) => b.detectedAt.getTime() - a.detectedAt.getTime());
+    }
+    /** Current stats snapshot. */
+    getStats() {
+        this.evictExpired();
+        this.stats.activeIntents = this.intents.size;
+        return JSON.parse(JSON.stringify(this.stats));
+    }
+    /** List active intents (for dashboards / debugging). */
+    activeIntents() {
+        this.evictExpired();
+        return Array.from(this.intents.values()).sort((a, b) => a.filePath.localeCompare(b.filePath));
+    }
+    // ── Internals ─────────────────────────────────────────────────────────────
+    detectForIntent(newIntent) {
+        const conflicts = [];
+        let overlapStart = newIntent.startLine;
+        let overlapEnd = newIntent.endLine;
+        for (const existing of this.intents.values()) {
+            if (this.sameSession(existing, newIntent))
+                continue;
+            if (existing.filePath !== newIntent.filePath)
+                continue;
+            const intersectStart = Math.max(existing.startLine, newIntent.startLine);
+            const intersectEnd = Math.min(existing.endLine, newIntent.endLine);
+            if (intersectStart <= intersectEnd) {
+                conflicts.push(existing);
+                overlapStart = Math.max(overlapStart, intersectStart);
+                overlapEnd = Math.min(overlapEnd, intersectEnd);
+            }
+        }
+        if (!conflicts.length)
+            return null;
+        const severity = conflicts.length >= 2 ? 'critical'
+            : (overlapEnd - overlapStart + 1) >= 20 ? 'warning'
+                : 'info';
+        const suggestedResolution = this.buildResolutionSuggestion(newIntent, conflicts);
+        return {
+            id: `col-${crypto.randomBytes(6).toString('hex')}`,
+            filePath: newIntent.filePath,
+            conflictingIntents: [newIntent, ...conflicts],
+            overlapStartLine: overlapStart,
+            overlapEndLine: overlapEnd,
+            severity,
+            suggestedResolution,
+            detectedAt: new Date(),
+        };
+    }
+    buildResolutionSuggestion(newIntent, conflicts) {
+        const others = conflicts.map(c => `${c.agentTool} (${c.intent})`).join(', ');
+        const newer = newIntent;
+        const agents = [...new Set([newer.agentTool, ...conflicts.map(c => c.agentTool)])].join(', ');
+        return [
+            `${agents} have overlapping edit intents on ${path.basename(newer.filePath)} lines ${newer.startLine}-${newer.endLine}.`,
+            `Incoming: ${newer.agentTool} — ${newer.intent}`,
+            `Existing: ${others}`,
+            `Suggested: the newer intent waits 60s, re-plans around the in-flight edit, or spawns a merge-arbiter sub-agent.`,
+        ].join(' ');
+    }
+    keyForIntent(intent) {
+        return `${intent.filePath}::${intent.agentTool}::${intent.sessionId}::${intent.startLine}-${intent.endLine}`;
+    }
+    sameSession(a, b) {
+        return a.agentTool === b.agentTool && a.sessionId === b.sessionId;
+    }
+    evictExpired() {
+        const now = Date.now();
+        for (const [key, intent] of this.intents) {
+            if (intent.expiresAt.getTime() <= now)
+                this.intents.delete(key);
+        }
+        this.stats.activeIntents = this.intents.size;
+    }
+    async persist() {
+        try {
+            const payload = {
+                schemaVersion: 1,
+                intents: Array.from(this.intents.values()),
+                alerts: Array.from(this.alerts.values()),
+                stats: this.stats,
+            };
+            const tmp = INTENTS_PATH + '.tmp';
+            fs.writeFileSync(tmp, JSON.stringify(payload, null, 2));
+            fs.renameSync(tmp, INTENTS_PATH);
+        }
+        catch {
+            /* persistence non-fatal */
+        }
+    }
+}
+let _instance = null;
+export function getCollisionDetective() {
+    if (!_instance)
+        _instance = new CollisionDetective();
+    return _instance;
+}
+export function resetCollisionDetectiveForTests() {
+    _instance = null;
+}
+//# sourceMappingURL=collision-detective.js.map

package/dist/brain/collision-detective.js.map

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

package/dist/brain/confidence-gate.d.ts

@@ -0,0 +1,69 @@
+export type GateMode = 'block' | 'downgrade' | 'flag';
+export interface GatedInput {
+    text: string;
+    confidence: number;
+    [k: string]: unknown;
+}
+export interface GateOpts {
+    threshold?: number;
+    mode: GateMode;
+    hedgeHint?: string;
+}
+export interface GatedResultBlocked {
+    blocked: true;
+    reason: string;
+    predicted: number;
+    threshold: number;
+}
+export interface GatedResultPassed<T extends GatedInput> {
+    blocked: false;
+    result: T & {
+        _warning?: string;
+    };
+    mode: GateMode;
+    predicted: number;
+    threshold: number;
+    downgraded: boolean;
+}
+export type GateOutcome<T extends GatedInput> = GatedResultBlocked | GatedResultPassed<T>;
+export interface CalibrationEntry {
+    ts: string;
+    predicted: number;
+    wasCorrect: 0 | 0.5 | 1;
+    meta?: Record<string, unknown>;
+}
+export interface CalibrationStats {
+    sampleSize: number;
+    brierScore: number;
+    expectedCalibrationError: number;
+    bucketBreakdown: Array<{
+        bucket: string;
+        samples: number;
+        meanPredicted: number;
+        meanOutcome: number;
+        gap: number;
+    }>;
+    threshold: number;
+}
+export declare class ConfidenceGate {
+    private threshold;
+    private historyCache;
+    private initialized;
+    init(): Promise<void>;
+    /** Apply the gate. Synchronous because the threshold is already loaded. */
+    gate<T extends GatedInput>(result: T, opts: GateOpts): GateOutcome<T>;
+    /** Record what actually happened so we can compute calibration stats later. */
+    recordOutcome(predicted: number, wasCorrect: boolean | 'partial', meta?: Record<string, unknown>): Promise<void>;
+    /** Brier + ECE over all recorded outcomes. */
+    stats(): Promise<CalibrationStats>;
+    setThreshold(t: number): void;
+    getThreshold(): number;
+    /** Convenience wrapper for promise-returning functions. */
+    wrap<T extends GatedInput>(fn: () => Promise<T>, opts: GateOpts): Promise<GateOutcome<T>>;
+    private loadHistory;
+    private readConfiguredThreshold;
+    private writeConfiguredThreshold;
+}
+export declare function getConfidenceGate(): ConfidenceGate;
+export declare function resetConfidenceGateForTests(): void;
+//# sourceMappingURL=confidence-gate.d.ts.map

package/dist/brain/confidence-gate.d.ts.map

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

package/dist/brain/confidence-gate.js

@@ -0,0 +1,244 @@
+// src/brain/confidence-gate.ts — Active output filter for confidence-tagged results
+// v6.0.2 — Hive Mind Edition
+//
+// CalibrationMonitor is passive: it watches claims roll past and scores them.
+// This module is the active half: given a `{text, confidence}` result, it
+// can block it, downgrade its tone, or flag it with a warning — depending on
+// the gate mode chosen by the caller.
+//
+// Why three modes? Different callers want different ergonomics:
+//   - block:     hard gate for tool calls / autonomous agents that must not
+//                act on shaky info.
+//   - downgrade: chat surfaces, where we still want to say something but
+//                visibly hedge so the user doesn't trust it blindly.
+//   - flag:     observability layer that lets downstream logic decide.
+//
+// Calibration history (predicted → outcome) is logged as JSONL so the
+// reliability of `confidence` itself is auditable. Brier score + ECE on
+// .stats() lets us tell whether the gate threshold is well-chosen.
+//
+// Exposed: ConfidenceGate, getConfidenceGate(), resetConfidenceGateForTests().
+//   .gate(result, opts)
+//   .recordOutcome(predicted, wasCorrect, meta?)
+//   .stats()
+//   .setThreshold(t), .getThreshold()
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const HOME_DIR = path.join(os.homedir(), '.shadow-brain');
+const HISTORY_PATH = path.join(HOME_DIR, 'calibration-history.jsonl');
+const CONFIG_PATH = path.join(HOME_DIR, 'config.json');
+const DEFAULT_THRESHOLD = 0.6;
+const ECE_BUCKETS = 10;
+export class ConfidenceGate {
+    constructor() {
+        this.threshold = DEFAULT_THRESHOLD;
+        this.historyCache = null;
+        this.initialized = false;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        fs.mkdirSync(HOME_DIR, { recursive: true });
+        this.threshold = this.readConfiguredThreshold();
+        this.initialized = true;
+    }
+    /** Apply the gate. Synchronous because the threshold is already loaded. */
+    gate(result, opts) {
+        if (!this.initialized)
+            this.threshold = this.readConfiguredThreshold();
+        const threshold = opts.threshold ?? this.threshold;
+        const predicted = clamp(result.confidence, 0, 1);
+        if (predicted >= threshold) {
+            return {
+                blocked: false,
+                result,
+                mode: opts.mode,
+                predicted,
+                threshold,
+                downgraded: false,
+            };
+        }
+        switch (opts.mode) {
+            case 'block':
+                return {
+                    blocked: true,
+                    reason: `Confidence ${(predicted * 100).toFixed(0)}% below threshold ${(threshold * 100).toFixed(0)}%`,
+                    predicted,
+                    threshold,
+                };
+            case 'downgrade': {
+                const hedged = {
+                    ...result,
+                    text: hedge(result.text, predicted, opts.hedgeHint),
+                    _warning: `low-confidence (${(predicted * 100).toFixed(0)}%)`,
+                };
+                return { blocked: false, result: hedged, mode: 'downgrade', predicted, threshold, downgraded: true };
+            }
+            case 'flag':
+            default:
+                return {
+                    blocked: false,
+                    result: { ...result, _warning: `low-confidence (${(predicted * 100).toFixed(0)}%)` },
+                    mode: 'flag',
+                    predicted,
+                    threshold,
+                    downgraded: false,
+                };
+        }
+    }
+    /** Record what actually happened so we can compute calibration stats later. */
+    async recordOutcome(predicted, wasCorrect, meta) {
+        await this.init();
+        const entry = {
+            ts: new Date().toISOString(),
+            predicted: clamp(predicted, 0, 1),
+            wasCorrect: wasCorrect === 'partial' ? 0.5 : wasCorrect ? 1 : 0,
+            meta,
+        };
+        try {
+            fs.appendFileSync(HISTORY_PATH, JSON.stringify(entry) + '\n');
+        }
+        catch { /* non-fatal */ }
+        if (this.historyCache)
+            this.historyCache.push(entry);
+    }
+    /** Brier + ECE over all recorded outcomes. */
+    async stats() {
+        await this.init();
+        const entries = this.loadHistory();
+        if (!entries.length) {
+            return {
+                sampleSize: 0,
+                brierScore: 0,
+                expectedCalibrationError: 0,
+                bucketBreakdown: [],
+                threshold: this.threshold,
+            };
+        }
+        let brierSum = 0;
+        for (const e of entries) {
+            const d = e.predicted - e.wasCorrect;
+            brierSum += d * d;
+        }
+        const brier = brierSum / entries.length;
+        const buckets = [];
+        for (let i = 0; i < ECE_BUCKETS; i++) {
+            const lo = i / ECE_BUCKETS;
+            const hi = (i + 1) / ECE_BUCKETS;
+            const inBucket = entries.filter(e => e.predicted >= lo && (i === ECE_BUCKETS - 1 ? e.predicted <= hi : e.predicted < hi));
+            if (!inBucket.length)
+                continue;
+            const meanPredicted = avg(inBucket.map(e => e.predicted));
+            const meanOutcome = avg(inBucket.map(e => e.wasCorrect));
+            buckets.push({
+                bucket: `${lo.toFixed(1)}-${hi.toFixed(1)}`,
+                samples: inBucket.length,
+                meanPredicted: +meanPredicted.toFixed(3),
+                meanOutcome: +meanOutcome.toFixed(3),
+                gap: +Math.abs(meanPredicted - meanOutcome).toFixed(3),
+            });
+        }
+        const ece = buckets.reduce((s, b) => s + (b.samples / entries.length) * b.gap, 0);
+        return {
+            sampleSize: entries.length,
+            brierScore: +brier.toFixed(4),
+            expectedCalibrationError: +ece.toFixed(4),
+            bucketBreakdown: buckets,
+            threshold: this.threshold,
+        };
+    }
+    setThreshold(t) {
+        this.threshold = clamp(t, 0, 1);
+        this.writeConfiguredThreshold(this.threshold);
+    }
+    getThreshold() { return this.threshold; }
+    /** Convenience wrapper for promise-returning functions. */
+    async wrap(fn, opts) {
+        await this.init();
+        const result = await fn();
+        return this.gate(result, opts);
+    }
+    // -- Internals -----------------------------------------------------------
+    loadHistory() {
+        if (this.historyCache)
+            return this.historyCache;
+        if (!fs.existsSync(HISTORY_PATH)) {
+            this.historyCache = [];
+            return this.historyCache;
+        }
+        const out = [];
+        try {
+            const lines = fs.readFileSync(HISTORY_PATH, 'utf-8').split('\n');
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    out.push(JSON.parse(line));
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+        catch { /* fall through with empty cache */ }
+        this.historyCache = out;
+        return out;
+    }
+    readConfiguredThreshold() {
+        try {
+            if (!fs.existsSync(CONFIG_PATH))
+                return DEFAULT_THRESHOLD;
+            const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+            const raw = cfg.confidenceGate;
+            if (typeof raw === 'number')
+                return clamp(raw, 0, 1);
+            if (raw && typeof raw === 'object' && typeof raw.threshold === 'number')
+                return clamp(raw.threshold, 0, 1);
+            return DEFAULT_THRESHOLD;
+        }
+        catch {
+            return DEFAULT_THRESHOLD;
+        }
+    }
+    writeConfiguredThreshold(t) {
+        try {
+            let cfg = {};
+            if (fs.existsSync(CONFIG_PATH)) {
+                try {
+                    cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+                }
+                catch {
+                    cfg = {};
+                }
+            }
+            cfg.confidenceGate = t;
+            fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+        }
+        catch { /* non-fatal */ }
+    }
+}
+function hedge(text, confidence, hint) {
+    const pct = Math.round(confidence * 100);
+    const verifyTarget = hint || 'the key claims';
+    return `I'm only ${pct}% confident — verify ${verifyTarget} first:\n\n${text}`;
+}
+function clamp(x, lo, hi) {
+    if (Number.isNaN(x))
+        return lo;
+    return x < lo ? lo : x > hi ? hi : x;
+}
+function avg(xs) {
+    if (!xs.length)
+        return 0;
+    let s = 0;
+    for (const x of xs)
+        s += x;
+    return s / xs.length;
+}
+let _instance = null;
+export function getConfidenceGate() {
+    if (!_instance)
+        _instance = new ConfidenceGate();
+    return _instance;
+}
+export function resetConfidenceGateForTests() { _instance = null; }
+//# sourceMappingURL=confidence-gate.js.map

package/dist/brain/confidence-gate.js.map

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

package/dist/brain/constitution.d.ts

@@ -0,0 +1,59 @@
+export type RuleSeverity = 'must' | 'should' | 'never';
+export type RuleScope = 'all' | 'code' | 'commits' | 'tests';
+export interface ConstitutionRule {
+    id: string;
+    severity: RuleSeverity;
+    scope: RuleScope;
+    title: string;
+    text: string;
+    keywords: string[];
+    source: 'file' | 'proposed' | 'approved';
+}
+export interface Violation {
+    rule: ConstitutionRule;
+    confidence: number;
+    evidence: string;
+}
+export interface ValidateResult {
+    violations: Violation[];
+    passed: ConstitutionRule[];
+}
+interface InjectOpts {
+    scope?: RuleScope;
+    maxRules?: number;
+}
+export declare class Constitution {
+    private rules;
+    private approved;
+    private projectRoot;
+    private watcher;
+    private initialized;
+    private embeddings;
+    private vectorCache;
+    constructor(projectRoot?: string);
+    init(): Promise<void>;
+    /** Prepend the most relevant constitution rules to a prompt as a preamble. */
+    injectInto(prompt: string, opts?: InjectOpts): string;
+    /**
+     * Score `text` against every rule. Uses both keyword matching (fast, precise)
+     * and semantic similarity (slower, fuzzy). Reports a confidence in [0,1].
+     */
+    validate(text: string): Promise<ValidateResult>;
+    /** Build a candidate rule from an observed pattern. Template-only, no LLM. */
+    proposeRule(observation: string): ConstitutionRule;
+    /** Persist a user-approved rule to constitution-approved.json. */
+    approve(rule: ConstitutionRule): Promise<ConstitutionRule>;
+    listRules(): ConstitutionRule[];
+    dispose(): void;
+    private allRules;
+    private loadFromDisk;
+    private startWatcher;
+    private cachedEmbed;
+    private extractEvidence;
+    private logViolation;
+}
+export declare function parseConstitutionMarkdown(md: string): ConstitutionRule[];
+export declare function getConstitution(projectRoot?: string): Constitution;
+export declare function resetConstitutionForTests(): void;
+export {};
+//# sourceMappingURL=constitution.d.ts.map

package/dist/brain/constitution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constitution.d.ts","sourceRoot":"","sources":["../../src/brain/constitution.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AACvD,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;CAC1C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,UAAU,UAAU;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,WAAW,CAAoC;gBAE3C,WAAW,GAAE,MAAsB;IAIzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,8EAA8E;IAC9E,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM;IAgBzD;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAgCrD,8EAA8E;IAC9E,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB;IAgBlD,kEAAkE;IAC5D,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAUhE,SAAS,IAAI,gBAAgB,EAAE;IAE/B,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,QAAQ;IAEhB,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,YAAY;YAcN,WAAW;IAQzB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,YAAY;CAarB;AAID,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAkCxE;AA2CD,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CAGlE;AACD,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD"}