@iflow-mcp/jkheadley-instar 0.26.2

package/dist/paste/TruncationDetector.js

@@ -0,0 +1,220 @@
+/**
+ * TruncationDetector — detects when Telegram messages appear truncated.
+ *
+ * Runs as server-side middleware in the Telegram message ingestion path.
+ * Detects near-limit messages, rapid multi-part sends, and structurally
+ * incomplete code/log content. Returns metadata that the session can use
+ * to suggest the Drop Zone.
+ */
+// ── Constants ──────────────────────────────────────────────────────
+const TELEGRAM_LIMIT = 4096;
+const NEAR_LIMIT_THRESHOLD = 50; // within 50 chars of limit
+const RAPID_MESSAGE_WINDOW_MS = 15_000; // 15 seconds
+const MAX_RECENT_MESSAGES = 50;
+// Unclosed delimiters that suggest truncation
+const UNCLOSED_DELIMITERS = ['{', '[', '(', '`'];
+const OPENING_TO_CLOSING = {
+    '{': '}',
+    '[': ']',
+    '(': ')',
+};
+// ── Detector ───────────────────────────────────────────────────────
+export class TruncationDetector {
+    recentMessages = [];
+    /** Track which topics have already been nudged to avoid repetition */
+    nudgedTopics = new Map(); // topicId → timestamp
+    nudgeCooldownMs = 30 * 60 * 1000; // 30 minutes between nudges per topic
+    /**
+     * Analyze a Telegram message for truncation signals.
+     */
+    detect(topicId, userId, text) {
+        const now = Date.now();
+        // Store for rapid-message detection
+        this.recentMessages.push({ topicId, userId, text, timestamp: now });
+        // Trim old messages
+        while (this.recentMessages.length > MAX_RECENT_MESSAGES) {
+            this.recentMessages.shift();
+        }
+        // Check cooldown — don't flag if we recently nudged this topic
+        const lastNudge = this.nudgedTopics.get(topicId);
+        if (lastNudge && (now - lastNudge) < this.nudgeCooldownMs) {
+            return { truncationSuspected: false };
+        }
+        // Run heuristics in order of confidence
+        const nearLimit = this.checkNearLimit(text);
+        if (nearLimit.truncationSuspected) {
+            this.nudgedTopics.set(topicId, now);
+            return nearLimit;
+        }
+        const rapidMultiPart = this.checkRapidMultiPart(topicId, userId, now);
+        if (rapidMultiPart.truncationSuspected) {
+            this.nudgedTopics.set(topicId, now);
+            return rapidMultiPart;
+        }
+        const structural = this.checkStructuralIncompleteness(text);
+        if (structural.truncationSuspected) {
+            this.nudgedTopics.set(topicId, now);
+            return structural;
+        }
+        return { truncationSuspected: false };
+    }
+    /**
+     * Heuristic 1: Message is within NEAR_LIMIT_THRESHOLD chars of the
+     * Telegram limit AND ends in a way that suggests manual chopping.
+     */
+    checkNearLimit(text) {
+        if (text.length < TELEGRAM_LIMIT - NEAR_LIMIT_THRESHOLD) {
+            return { truncationSuspected: false };
+        }
+        // Check if it ends mid-word (no trailing whitespace or punctuation)
+        const lastChar = text[text.length - 1];
+        const endsCleanly = /[.!?;:)\]}\s"']/.test(lastChar);
+        if (!endsCleanly) {
+            return {
+                truncationSuspected: true,
+                reason: 'near-limit + ends mid-word',
+                confidence: 'high',
+            };
+        }
+        // Check for unclosed delimiters
+        if (this.hasUnclosedDelimiters(text)) {
+            return {
+                truncationSuspected: true,
+                reason: 'near-limit + unclosed delimiter',
+                confidence: 'high',
+            };
+        }
+        // Even near-limit with clean ending is suspicious if content looks like code/logs
+        if (this.looksLikeCode(text) && text.length > TELEGRAM_LIMIT - 20) {
+            return {
+                truncationSuspected: true,
+                reason: 'near-limit + code/log content',
+                confidence: 'medium',
+            };
+        }
+        return { truncationSuspected: false };
+    }
+    /**
+     * Heuristic 2: Multiple messages from same user in same topic
+     * within a short window, suggesting manual splitting.
+     */
+    checkRapidMultiPart(topicId, userId, now) {
+        const recent = this.recentMessages.filter(m => m.topicId === topicId &&
+            m.userId === userId &&
+            (now - m.timestamp) < RAPID_MESSAGE_WINDOW_MS);
+        if (recent.length < 2) {
+            return { truncationSuspected: false };
+        }
+        // Check if messages look like continuation
+        const prev = recent[recent.length - 2];
+        const curr = recent[recent.length - 1];
+        // Second message starts lowercase or with continuation patterns
+        const firstChar = curr.text[0];
+        const continuesLowercase = firstChar && /[a-z]/.test(firstChar);
+        const continuesCode = /^[}\])\s]/.test(curr.text) || /^(else|catch|finally|then|and|or)\b/i.test(curr.text);
+        const prevEndsAbruptly = !/[.!?]\s*$/.test(prev.text);
+        if ((continuesLowercase || continuesCode) && prevEndsAbruptly) {
+            return {
+                truncationSuspected: true,
+                reason: 'rapid multi-part messages',
+                confidence: 'medium',
+            };
+        }
+        return { truncationSuspected: false };
+    }
+    /**
+     * Heuristic 3: Content looks like code/logs but is structurally incomplete.
+     */
+    checkStructuralIncompleteness(text) {
+        if (!this.looksLikeCode(text)) {
+            return { truncationSuspected: false };
+        }
+        // Check for unclosed code fences
+        const fenceCount = (text.match(/```/g) || []).length;
+        if (fenceCount % 2 !== 0) {
+            return {
+                truncationSuspected: true,
+                reason: 'unclosed code fence',
+                confidence: 'medium',
+            };
+        }
+        // Check for trailing ellipsis
+        if (/\.\.\.\s*$/.test(text)) {
+            return {
+                truncationSuspected: true,
+                reason: 'trailing ellipsis',
+                confidence: 'medium',
+            };
+        }
+        // Unclosed delimiters in code context
+        if (this.hasUnclosedDelimiters(text)) {
+            return {
+                truncationSuspected: true,
+                reason: 'structurally incomplete (unclosed delimiters)',
+                confidence: 'medium',
+            };
+        }
+        return { truncationSuspected: false };
+    }
+    /**
+     * Check if text has significantly more opening than closing delimiters.
+     */
+    hasUnclosedDelimiters(text) {
+        for (const open of UNCLOSED_DELIMITERS) {
+            if (open === '`') {
+                // Check backtick pairs
+                const count = (text.match(/`/g) || []).length;
+                if (count % 2 !== 0)
+                    return true;
+                continue;
+            }
+            const close = OPENING_TO_CLOSING[open];
+            const openCount = this.countChar(text, open);
+            const closeCount = this.countChar(text, close);
+            // Significant imbalance suggests truncation
+            if (openCount > closeCount && (openCount - closeCount) >= 1) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Heuristic: does this text look like code or log output?
+     */
+    looksLikeCode(text) {
+        const lines = text.split('\n');
+        if (lines.length < 3)
+            return false;
+        let codeSignals = 0;
+        for (const line of lines.slice(0, 30)) {
+            // Indentation
+            if (/^\s{2,}/.test(line))
+                codeSignals++;
+            // Common code patterns
+            if (/[{}\[\]();]/.test(line))
+                codeSignals++;
+            // Log-like timestamps
+            if (/\d{2}:\d{2}:\d{2}/.test(line))
+                codeSignals++;
+            // Stack trace patterns
+            if (/^\s+at\s/.test(line) || /Error:|Exception:|Traceback/i.test(line))
+                codeSignals++;
+        }
+        return codeSignals > lines.length * 0.3;
+    }
+    countChar(text, char) {
+        let count = 0;
+        for (let i = 0; i < text.length; i++) {
+            if (text[i] === char)
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Clear nudge cooldowns (useful for testing).
+     */
+    clearCooldowns() {
+        this.nudgedTopics.clear();
+    }
+}
+//# sourceMappingURL=TruncationDetector.js.map

package/dist/paste/TruncationDetector.js.map

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

package/dist/privacy/OutputPrivacyRouter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * OutputPrivacyRouter — evaluates response sensitivity and routes to DM or shared topic.
+ *
+ * Implements Gap 10 from the User-Agent Topology Spec:
+ *   "In a public topic, a sensitive reply is visible to all group members.
+ *    The agent has no mechanism to route sensitive responses to DM instead
+ *    of the shared topic."
+ *
+ * Routing rules:
+ *   1. If response contains user-specific sensitive content → route to DM
+ *   2. If sensitivity assessment is uncertain → default to DM (fail-closed)
+ *   3. If response is clearly non-sensitive → allow shared topic
+ *
+ * Sensitivity signals (heuristic-based, no LLM needed):
+ *   - Contains patterns matching credentials, keys, tokens, passwords
+ *   - Contains personal data (emails, phone numbers, SSNs)
+ *   - Response was generated from private-scoped memory
+ *   - Explicit privacy markers from the chat planner
+ *
+ * Design:
+ *   - Fail-closed: uncertain → DM
+ *   - No false-negative tolerance: better to over-route to DM than expose sensitive data
+ *   - Deterministic: same input always produces same routing decision
+ *   - Fast: heuristic-only, no async operations
+ */
+import type { PrivacyScopeType } from '../core/types.js';
+export type RoutingDecision = 'dm' | 'shared';
+export interface RoutingResult {
+    /** Where to send the response */
+    route: RoutingDecision;
+    /** Why this routing was chosen */
+    reason: string;
+    /** Specific patterns that triggered DM routing (for audit) */
+    triggers: string[];
+    /** Overall confidence in the routing decision (0-1) */
+    confidence: number;
+}
+export interface RoutingContext {
+    /** The response text to evaluate */
+    responseText: string;
+    /** Whether the response was generated using private-scoped memory */
+    usedPrivateMemory?: boolean;
+    /** The privacy scope of the source data, if known */
+    sourceScopes?: PrivacyScopeType[];
+    /** Whether the planner explicitly marked this as sensitive */
+    explicitlySensitive?: boolean;
+    /** Whether the response is going to a shared topic (vs already a DM) */
+    isSharedTopic?: boolean;
+}
+/**
+ * Evaluate a response for sensitivity and determine routing.
+ *
+ * This is the main entry point. Returns a RoutingResult with the decision,
+ * reasoning, and triggering patterns.
+ */
+export declare function evaluateResponseSensitivity(ctx: RoutingContext): RoutingResult;
+/**
+ * Quick check: does a response need DM routing?
+ * Convenience wrapper for the full evaluateResponseSensitivity.
+ */
+export declare function shouldRouteToDm(responseText: string, opts?: {
+    usedPrivateMemory?: boolean;
+    isSharedTopic?: boolean;
+}): boolean;
+//# sourceMappingURL=OutputPrivacyRouter.d.ts.map

package/dist/privacy/OutputPrivacyRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutputPrivacyRouter.d.ts","sourceRoot":"","sources":["../../src/privacy/OutputPrivacyRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAkDzD,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,KAAK,EAAE,eAAe,CAAC;IACvB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qDAAqD;IACrD,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAClC,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAID;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa,CA+E9E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAC3D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAOV"}

package/dist/privacy/OutputPrivacyRouter.js

@@ -0,0 +1,156 @@
+/**
+ * OutputPrivacyRouter — evaluates response sensitivity and routes to DM or shared topic.
+ *
+ * Implements Gap 10 from the User-Agent Topology Spec:
+ *   "In a public topic, a sensitive reply is visible to all group members.
+ *    The agent has no mechanism to route sensitive responses to DM instead
+ *    of the shared topic."
+ *
+ * Routing rules:
+ *   1. If response contains user-specific sensitive content → route to DM
+ *   2. If sensitivity assessment is uncertain → default to DM (fail-closed)
+ *   3. If response is clearly non-sensitive → allow shared topic
+ *
+ * Sensitivity signals (heuristic-based, no LLM needed):
+ *   - Contains patterns matching credentials, keys, tokens, passwords
+ *   - Contains personal data (emails, phone numbers, SSNs)
+ *   - Response was generated from private-scoped memory
+ *   - Explicit privacy markers from the chat planner
+ *
+ * Design:
+ *   - Fail-closed: uncertain → DM
+ *   - No false-negative tolerance: better to over-route to DM than expose sensitive data
+ *   - Deterministic: same input always produces same routing decision
+ *   - Fast: heuristic-only, no async operations
+ */
+// ── Sensitivity Patterns ─────────────────────────────────────────
+/**
+ * Patterns that indicate the response contains sensitive content.
+ * Each pattern has a name (for audit logging) and a regex.
+ */
+const SENSITIVE_PATTERNS = [
+    // Credentials and secrets
+    { name: 'api-key', pattern: /\b(sk-|pk-|api[_-]?key|api[_-]?token|api[_-]?secret)\s*[:=]\s*\S+/i },
+    { name: 'bearer-token', pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/i },
+    { name: 'password', pattern: /\b(password|passwd|pwd)\s*[:=]\s*\S+/i },
+    { name: 'secret-key', pattern: /\b(secret[_-]?key|private[_-]?key|encryption[_-]?key)\s*[:=]\s*\S+/i },
+    { name: 'token-pattern', pattern: /\b[A-Za-z0-9]{32,}[._-][A-Za-z0-9]{16,}/i }, // Generic token patterns
+    { name: 'ssh-key', pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/i },
+    { name: 'connection-string', pattern: /\b(postgres|mysql|mongodb|redis):\/\/\S+:\S+@/i },
+    // Personal data (PII)
+    { name: 'email-address', pattern: /\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/ },
+    { name: 'phone-number', pattern: /\b(\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/ },
+    { name: 'ssn', pattern: /\b\d{3}-\d{2}-\d{4}\b/ },
+    { name: 'credit-card', pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/ },
+    // Financial data
+    { name: 'bank-account', pattern: /\b(account\s*#?|routing\s*#?|iban)\s*[:=]?\s*\d{6,}\b/i },
+    { name: 'pin-code', pattern: /\b(pin|PIN)\s*[:=]\s*\d{4,6}\b/ },
+];
+/**
+ * Words that strongly indicate personal/private context even without pattern matches.
+ */
+const SENSITIVE_KEYWORDS = [
+    'your password',
+    'your api key',
+    'your token',
+    'your secret',
+    'your credentials',
+    'your private',
+    'your bank',
+    'your account number',
+    'your ssn',
+    'your social security',
+    'don\'t share this',
+    'keep this private',
+    'confidential',
+];
+// ── Router ───────────────────────────────────────────────────────
+/**
+ * Evaluate a response for sensitivity and determine routing.
+ *
+ * This is the main entry point. Returns a RoutingResult with the decision,
+ * reasoning, and triggering patterns.
+ */
+export function evaluateResponseSensitivity(ctx) {
+    // Fast path: already a DM — no routing needed
+    if (ctx.isSharedTopic === false) {
+        return {
+            route: 'shared', // "shared" means "send normally" — in a DM, that's the DM
+            reason: 'Already in DM — no routing needed',
+            triggers: [],
+            confidence: 1.0,
+        };
+    }
+    const triggers = [];
+    // Check 1: Explicitly marked sensitive by planner
+    if (ctx.explicitlySensitive) {
+        triggers.push('explicit-sensitive-marker');
+        return {
+            route: 'dm',
+            reason: 'Explicitly marked as sensitive by chat planner',
+            triggers,
+            confidence: 1.0,
+        };
+    }
+    // Check 2: Uses private-scoped memory
+    if (ctx.usedPrivateMemory) {
+        triggers.push('private-memory-source');
+    }
+    // Check 3: Source data includes private scopes
+    if (ctx.sourceScopes?.includes('private')) {
+        triggers.push('private-scope-source');
+    }
+    // Check 4: Pattern matching on response text
+    for (const { name, pattern } of SENSITIVE_PATTERNS) {
+        if (pattern.test(ctx.responseText)) {
+            triggers.push(name);
+        }
+    }
+    // Check 5: Keyword matching
+    const lowerText = ctx.responseText.toLowerCase();
+    for (const keyword of SENSITIVE_KEYWORDS) {
+        if (lowerText.includes(keyword)) {
+            triggers.push(`keyword:${keyword}`);
+        }
+    }
+    // ── Decision logic ──────────────────────────────────────────
+    if (triggers.length === 0) {
+        return {
+            route: 'shared',
+            reason: 'No sensitive content detected',
+            triggers: [],
+            confidence: 0.8, // Moderate confidence — could miss novel patterns
+        };
+    }
+    // Calculate confidence based on trigger count and types
+    const hasPatternMatch = triggers.some(t => !t.startsWith('keyword:') && t !== 'private-memory-source' && t !== 'private-scope-source');
+    const hasMemorySignal = triggers.includes('private-memory-source') || triggers.includes('private-scope-source');
+    let confidence = 0.7; // Base confidence for any trigger
+    if (hasPatternMatch)
+        confidence += 0.2;
+    if (hasMemorySignal)
+        confidence += 0.1;
+    confidence = Math.min(confidence, 1.0);
+    const reason = triggers.length === 1
+        ? `Sensitive content detected: ${triggers[0]}`
+        : `${triggers.length} sensitivity signals detected: ${triggers.slice(0, 3).join(', ')}${triggers.length > 3 ? '...' : ''}`;
+    return {
+        route: 'dm',
+        reason,
+        triggers,
+        confidence,
+    };
+}
+/**
+ * Quick check: does a response need DM routing?
+ * Convenience wrapper for the full evaluateResponseSensitivity.
+ */
+export function shouldRouteToDm(responseText, opts) {
+    const result = evaluateResponseSensitivity({
+        responseText,
+        usedPrivateMemory: opts?.usedPrivateMemory,
+        isSharedTopic: opts?.isSharedTopic,
+    });
+    return result.route === 'dm';
+}
+//# sourceMappingURL=OutputPrivacyRouter.js.map

package/dist/privacy/OutputPrivacyRouter.js.map

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

package/dist/publishing/PrivateViewer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Private content viewer for Instar agents.
+ *
+ * Stores markdown content locally and serves it as rendered HTML
+ * via the agent's HTTP server. When combined with a Cloudflare Tunnel,
+ * this provides authenticated access to rendered content from anywhere.
+ *
+ * Unlike Telegraph (public), private views are gated by the agent's
+ * auth token and only accessible through the tunnel URL.
+ */
+export interface PrivateView {
+    id: string;
+    title: string;
+    markdown: string;
+    /** SHA-256 hash of the PIN, if PIN-protected */
+    pinHash?: string;
+    createdAt: string;
+    updatedAt?: string;
+}
+export interface PrivateViewerConfig {
+    /** Directory to store views */
+    viewsDir: string;
+}
+export declare class PrivateViewer {
+    private viewsDir;
+    private lastTimestamp;
+    constructor(config: PrivateViewerConfig);
+    /**
+     * Store markdown content for private viewing.
+     * If a PIN is provided, the view requires PIN entry before content is shown.
+     */
+    create(title: string, markdown: string, pin?: string): PrivateView;
+    /**
+     * Update an existing view.
+     */
+    update(id: string, title: string, markdown: string): PrivateView | null;
+    /**
+     * Get a view by ID.
+     */
+    get(id: string): PrivateView | null;
+    /**
+     * List all views.
+     */
+    list(): PrivateView[];
+    /**
+     * Delete a view.
+     */
+    delete(id: string): boolean;
+    /**
+     * Verify a PIN against a view's stored hash.
+     */
+    verifyPin(id: string, pin: string): boolean;
+    /**
+     * Render a PIN entry page for a protected view.
+     */
+    renderPinPage(view: PrivateView, error?: boolean): string;
+    /**
+     * Render a view as self-contained HTML.
+     */
+    renderHtml(view: PrivateView): string;
+    private save;
+}
+//# sourceMappingURL=PrivateViewer.d.ts.map

package/dist/publishing/PrivateViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrivateViewer.d.ts","sourceRoot":"","sources":["../../src/publishing/PrivateViewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAK;gBAEd,MAAM,EAAE,mBAAmB;IAOvC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW;IAsBlE;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAWvE;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAUnC;;OAEG;IACH,IAAI,IAAI,WAAW,EAAE;IAgBrB;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAW3B;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAU3C;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,UAAQ,GAAG,MAAM;IAyHvD;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM;IA0GrC,OAAO,CAAC,IAAI;CAIb"}