@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/MachineIdentity.js

@@ -0,0 +1,476 @@
+/**
+ * Machine identity management for multi-machine coordination.
+ *
+ * Each machine gets a persistent cryptographic identity:
+ * - Ed25519 key pair for signing (commits, API requests)
+ * - X25519 key pair for encryption (secret sync, pairing)
+ * - 128-bit random machine ID
+ * - Human-friendly name
+ *
+ * This is Phase 1 of the multi-machine spec.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// ── Constants ────────────────────────────────────────────────────────
+const MACHINE_DIR = 'machine';
+const MACHINES_DIR = 'machines';
+const IDENTITY_FILE = 'identity.json';
+const SIGNING_KEY_FILE = 'signing-key.pem';
+const ENCRYPTION_KEY_FILE = 'encryption-key.pem';
+const REGISTRY_FILE = 'registry.json';
+const KEY_FILE_MODE = 0o600;
+const REGISTRY_VERSION = 1;
+// ── Error Messages (human-readable) ──────────────────────────────────
+const ERRORS = {
+    KEYGEN_FAILED: (detail) => `Could not set up security for this machine. ${detail}\nTry: sudo chown -R $(whoami) .instar/machine/`,
+    IDENTITY_EXISTS: 'This machine already has an identity. Use --force to regenerate (this will require re-pairing).',
+    IDENTITY_NOT_FOUND: 'No machine identity found. Run `instar init` or `instar join` first.',
+    REGISTRY_CORRUPT: 'Machine registry is corrupted. Run `instar doctor` for diagnosis.',
+    MACHINE_NOT_FOUND: (id) => `Machine ${id} not found in registry.`,
+    MACHINE_ALREADY_REVOKED: (name) => `Machine "${name}" is already revoked.`,
+};
+// ── Key Generation ───────────────────────────────────────────────────
+/**
+ * Generate an Ed25519 key pair for signing.
+ * Returns { publicKey, privateKey } in PEM format.
+ */
+export function generateSigningKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    return { publicKey, privateKey };
+}
+/**
+ * Generate an X25519 key pair for encryption (ECDH key agreement).
+ * Returns { publicKey, privateKey } in PEM format.
+ */
+export function generateEncryptionKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519', {
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+    return { publicKey, privateKey };
+}
+/**
+ * Generate a 128-bit machine ID: "m_" + 32 random hex chars.
+ */
+export function generateMachineId() {
+    return `m_${crypto.randomBytes(16).toString('hex')}`;
+}
+/**
+ * Detect a human-friendly name for this machine.
+ * Uses hostname, falling back to a random name.
+ */
+export function detectMachineName() {
+    const hostname = os.hostname();
+    // Clean up hostname: remove .local suffix, lowercase
+    const name = hostname.replace(/\.local$/i, '').toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    return name || `machine-${crypto.randomBytes(4).toString('hex')}`;
+}
+/**
+ * Detect the platform string (e.g., "darwin-arm64", "linux-x64").
+ */
+export function detectPlatform() {
+    return `${process.platform}-${process.arch}`;
+}
+/**
+ * Detect available capabilities for this machine.
+ */
+export function detectCapabilities() {
+    // All machines start with these. Tunnel/telegram presence
+    // is determined by config, checked at runtime.
+    return ['sessions', 'jobs', 'telegram', 'tunnel'];
+}
+// ── PEM Encoding Helpers ─────────────────────────────────────────────
+/**
+ * Extract the base64-encoded key data from a PEM string.
+ */
+export function pemToBase64(pem) {
+    return pem
+        .replace(/-----BEGIN [A-Z ]+-----/g, '')
+        .replace(/-----END [A-Z ]+-----/g, '')
+        .replace(/\s/g, '');
+}
+/**
+ * Sign data with an Ed25519 private key (PEM format).
+ * Returns the signature as a base64 string.
+ */
+export function sign(data, privateKeyPem) {
+    const signature = crypto.sign(null, Buffer.from(data), privateKeyPem);
+    return signature.toString('base64');
+}
+/**
+ * Verify an Ed25519 signature against a public key (PEM format).
+ */
+export function verify(data, signature, publicKeyPem) {
+    return crypto.verify(null, Buffer.from(data), publicKeyPem, Buffer.from(signature, 'base64'));
+}
+// ── Identity Manager ─────────────────────────────────────────────────
+export class MachineIdentityManager {
+    instarDir;
+    constructor(instarDir) {
+        this.instarDir = instarDir;
+    }
+    // ── Paths ────────────────────────────────────────────────────────
+    get machineDir() {
+        return path.join(this.instarDir, MACHINE_DIR);
+    }
+    get machinesDir() {
+        return path.join(this.instarDir, MACHINES_DIR);
+    }
+    get identityPath() {
+        return path.join(this.machineDir, IDENTITY_FILE);
+    }
+    get signingKeyPath() {
+        return path.join(this.machineDir, SIGNING_KEY_FILE);
+    }
+    get encryptionKeyPath() {
+        return path.join(this.machineDir, ENCRYPTION_KEY_FILE);
+    }
+    get registryPath() {
+        return path.join(this.machinesDir, REGISTRY_FILE);
+    }
+    // ── Identity Lifecycle ───────────────────────────────────────────
+    /**
+     * Check if this machine has an identity.
+     */
+    hasIdentity() {
+        return fs.existsSync(this.identityPath);
+    }
+    /**
+     * Generate and persist a new machine identity.
+     * Creates key pairs, identity.json, and self-registers in the registry.
+     *
+     * @param options.name - Override auto-detected machine name
+     * @param options.force - Overwrite existing identity
+     * @param options.role - Initial role (default: 'awake' for first machine)
+     */
+    async generateIdentity(options) {
+        if (this.hasIdentity() && !options?.force) {
+            throw new Error(ERRORS.IDENTITY_EXISTS);
+        }
+        // Ensure directories exist
+        fs.mkdirSync(this.machineDir, { recursive: true });
+        fs.mkdirSync(this.machinesDir, { recursive: true });
+        // Generate keys
+        const signing = generateSigningKeyPair();
+        const encryption = generateEncryptionKeyPair();
+        const machineId = generateMachineId();
+        // Build identity
+        const identity = {
+            machineId,
+            signingPublicKey: pemToBase64(signing.publicKey),
+            encryptionPublicKey: pemToBase64(encryption.publicKey),
+            name: options?.name ?? detectMachineName(),
+            platform: detectPlatform(),
+            createdAt: new Date().toISOString(),
+            capabilities: detectCapabilities(),
+        };
+        // Write private keys with restricted permissions
+        this.writeSecureFile(this.signingKeyPath, signing.privateKey);
+        this.writeSecureFile(this.encryptionKeyPath, encryption.privateKey);
+        // Write identity (public data — committed to git)
+        fs.writeFileSync(this.identityPath, JSON.stringify(identity, null, 2));
+        // Self-register in the machine registry
+        const role = options?.role ?? 'awake';
+        this.registerMachine(identity, role);
+        return identity;
+    }
+    /**
+     * Load this machine's identity from disk.
+     */
+    loadIdentity() {
+        if (!this.hasIdentity()) {
+            throw new Error(ERRORS.IDENTITY_NOT_FOUND);
+        }
+        return JSON.parse(fs.readFileSync(this.identityPath, 'utf-8'));
+    }
+    /**
+     * Load this machine's Ed25519 signing private key (PEM format).
+     */
+    loadSigningKey() {
+        return fs.readFileSync(this.signingKeyPath, 'utf-8');
+    }
+    /**
+     * Load this machine's X25519 encryption private key (PEM format).
+     */
+    loadEncryptionKey() {
+        return fs.readFileSync(this.encryptionKeyPath, 'utf-8');
+    }
+    // ── Registry Management ──────────────────────────────────────────
+    /**
+     * Load the machine registry. Returns empty registry if file doesn't exist.
+     */
+    loadRegistry() {
+        if (!fs.existsSync(this.registryPath)) {
+            return { version: REGISTRY_VERSION, machines: {} };
+        }
+        try {
+            const data = JSON.parse(fs.readFileSync(this.registryPath, 'utf-8'));
+            if (typeof data.version !== 'number' || typeof data.machines !== 'object') {
+                throw new Error(ERRORS.REGISTRY_CORRUPT);
+            }
+            return data;
+        }
+        catch (e) {
+            if (e instanceof SyntaxError) {
+                throw new Error(ERRORS.REGISTRY_CORRUPT);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Save the machine registry to disk.
+     */
+    saveRegistry(registry) {
+        fs.mkdirSync(this.machinesDir, { recursive: true });
+        this.atomicWrite(this.registryPath, JSON.stringify(registry, null, 2));
+    }
+    /**
+     * Register a machine in the registry.
+     */
+    registerMachine(identity, role = 'standby') {
+        const registry = this.loadRegistry();
+        const now = new Date().toISOString();
+        registry.machines[identity.machineId] = {
+            name: identity.name,
+            status: 'active',
+            role,
+            pairedAt: now,
+            lastSeen: now,
+        };
+        this.saveRegistry(registry);
+    }
+    /**
+     * Update a machine's role in the registry.
+     */
+    updateRole(machineId, role) {
+        const registry = this.loadRegistry();
+        const entry = registry.machines[machineId];
+        if (!entry)
+            throw new Error(ERRORS.MACHINE_NOT_FOUND(machineId));
+        entry.role = role;
+        entry.lastSeen = new Date().toISOString();
+        this.saveRegistry(registry);
+    }
+    /**
+     * Update a machine's lastSeen timestamp.
+     */
+    touchMachine(machineId) {
+        const registry = this.loadRegistry();
+        const entry = registry.machines[machineId];
+        if (!entry)
+            throw new Error(ERRORS.MACHINE_NOT_FOUND(machineId));
+        entry.lastSeen = new Date().toISOString();
+        this.saveRegistry(registry);
+    }
+    /**
+     * Update a machine's last known URL (tunnel URL for cross-machine relay).
+     */
+    updateMachineUrl(machineId, url) {
+        const registry = this.loadRegistry();
+        const entry = registry.machines[machineId];
+        if (!entry)
+            throw new Error(ERRORS.MACHINE_NOT_FOUND(machineId));
+        entry.lastKnownUrl = url;
+        entry.lastSeen = new Date().toISOString();
+        this.saveRegistry(registry);
+    }
+    /**
+     * Get a machine's last known URL for cross-machine relay.
+     * Returns null if not known.
+     */
+    getMachineUrl(machineId) {
+        const registry = this.loadRegistry();
+        const entry = registry.machines[machineId];
+        return entry?.lastKnownUrl ?? null;
+    }
+    /**
+     * Revoke a machine. Marks it as revoked with reason.
+     * Does NOT handle external secret rotation — caller must do that.
+     */
+    revokeMachine(machineId, revokedBy, reason) {
+        const registry = this.loadRegistry();
+        const entry = registry.machines[machineId];
+        if (!entry)
+            throw new Error(ERRORS.MACHINE_NOT_FOUND(machineId));
+        if (entry.status === 'revoked')
+            throw new Error(ERRORS.MACHINE_ALREADY_REVOKED(entry.name));
+        entry.status = 'revoked';
+        entry.role = 'standby';
+        entry.revokedAt = new Date().toISOString();
+        entry.revokedBy = revokedBy;
+        entry.revokeReason = reason;
+        this.saveRegistry(registry);
+    }
+    /**
+     * Remove this machine's identity and keys (for `instar leave`).
+     */
+    removeLocalIdentity() {
+        for (const file of [this.identityPath, this.signingKeyPath, this.encryptionKeyPath]) {
+            if (fs.existsSync(file)) {
+                fs.unlinkSync(file);
+            }
+        }
+    }
+    /**
+     * Get the currently awake machine from the registry.
+     * Returns null if no machine is awake.
+     */
+    getAwakeMachine() {
+        const registry = this.loadRegistry();
+        for (const [machineId, entry] of Object.entries(registry.machines)) {
+            if (entry.status === 'active' && entry.role === 'awake') {
+                return { machineId, entry };
+            }
+        }
+        return null;
+    }
+    /**
+     * Get all active (non-revoked) machines.
+     */
+    getActiveMachines() {
+        const registry = this.loadRegistry();
+        return Object.entries(registry.machines)
+            .filter(([, entry]) => entry.status === 'active')
+            .map(([machineId, entry]) => ({ machineId, entry }));
+    }
+    /**
+     * Check if a machine is active (not revoked).
+     */
+    isMachineActive(machineId) {
+        const registry = this.loadRegistry();
+        const entry = registry.machines[machineId];
+        return (entry?.status === 'active') || false;
+    }
+    // ── Remote Machine Identity ─────────────────────────────────────
+    /**
+     * Store a remote machine's public identity (received during pairing).
+     * This lets us verify their signatures and encrypt data for them.
+     */
+    storeRemoteIdentity(identity) {
+        const dir = path.join(this.machinesDir, identity.machineId);
+        fs.mkdirSync(dir, { recursive: true });
+        this.atomicWrite(path.join(dir, IDENTITY_FILE), JSON.stringify(identity, null, 2));
+    }
+    /**
+     * Load a remote machine's public identity.
+     * Returns null if not found.
+     */
+    loadRemoteIdentity(machineId) {
+        const filePath = path.join(this.machinesDir, machineId, IDENTITY_FILE);
+        if (!fs.existsSync(filePath))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+        catch {
+            // @silent-fallback-ok — remote identity returns null
+            return null;
+        }
+    }
+    /**
+     * Get a machine's Ed25519 signing public key in PEM format.
+     * Works for both local and remote machines.
+     */
+    getSigningPublicKeyPem(machineId) {
+        // Check local identity first
+        if (this.hasIdentity()) {
+            const local = this.loadIdentity();
+            if (local.machineId === machineId) {
+                return base64ToSigningPem(local.signingPublicKey);
+            }
+        }
+        // Check remote identity
+        const remote = this.loadRemoteIdentity(machineId);
+        if (!remote)
+            return null;
+        return base64ToSigningPem(remote.signingPublicKey);
+    }
+    /**
+     * Get a machine's X25519 encryption public key in PEM format.
+     * Works for both local and remote machines.
+     */
+    getEncryptionPublicKeyPem(machineId) {
+        // Check local identity first
+        if (this.hasIdentity()) {
+            const local = this.loadIdentity();
+            if (local.machineId === machineId) {
+                return base64ToEncryptionPem(local.encryptionPublicKey);
+            }
+        }
+        // Check remote identity
+        const remote = this.loadRemoteIdentity(machineId);
+        if (!remote)
+            return null;
+        return base64ToEncryptionPem(remote.encryptionPublicKey);
+    }
+    // ── Helpers ──────────────────────────────────────────────────────
+    /**
+     * Write a file with restricted permissions (0600).
+     */
+    writeSecureFile(filePath, content) {
+        const dir = path.dirname(filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        // Write to temp file then rename (atomic)
+        const tmpPath = `${filePath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, content, { mode: KEY_FILE_MODE });
+        fs.renameSync(tmpPath, filePath);
+    }
+    /**
+     * Atomic write: write to temp file then rename.
+     */
+    atomicWrite(filePath, content) {
+        const tmpPath = `${filePath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, content);
+        fs.renameSync(tmpPath, filePath);
+    }
+}
+// ── Gitignore Management ─────────────────────────────────────────────
+const GITIGNORE_ENTRIES = [
+    '# Machine secrets (NEVER commit)',
+    '.instar/machine/signing-key.pem',
+    '.instar/machine/encryption-key.pem',
+    '.instar/secrets/',
+    '.instar/pairing/',
+];
+// ── PEM Reconstruction ──────────────────────────────────────────────
+/**
+ * Reconstruct Ed25519 SPKI PEM from base64-encoded key data.
+ */
+export function base64ToSigningPem(base64Key) {
+    const lines = base64Key.match(/.{1,64}/g) || [base64Key];
+    return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----\n`;
+}
+/**
+ * Reconstruct X25519 SPKI PEM from base64-encoded key data.
+ */
+export function base64ToEncryptionPem(base64Key) {
+    const lines = base64Key.match(/.{1,64}/g) || [base64Key];
+    return `-----BEGIN PUBLIC KEY-----\n${lines.join('\n')}\n-----END PUBLIC KEY-----\n`;
+}
+/**
+ * Ensure the .gitignore file contains the required entries for multi-machine.
+ * Appends missing entries without duplicating existing ones.
+ */
+export function ensureGitignore(projectDir) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    let content = '';
+    if (fs.existsSync(gitignorePath)) {
+        content = fs.readFileSync(gitignorePath, 'utf-8');
+    }
+    const linesToAdd = GITIGNORE_ENTRIES.filter(line => {
+        // Don't add comments if the actual entry already exists
+        if (line.startsWith('#'))
+            return !content.includes(line);
+        return !content.includes(line);
+    });
+    if (linesToAdd.length > 0) {
+        const append = (content.endsWith('\n') ? '' : '\n') + '\n' + linesToAdd.join('\n') + '\n';
+        fs.writeFileSync(gitignorePath, content + append);
+    }
+}
+//# sourceMappingURL=MachineIdentity.js.map

package/dist/core/MachineIdentity.js.map

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

package/dist/core/MessageSentinel.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Message Sentinel — Intelligent interrupt interpreter for agent sessions.
+ *
+ * Sits between user messages and the active session, classifying every
+ * incoming message to detect emergency signals that need immediate action.
+ *
+ * Born from the OpenClaw email deletion incident (2026-02-25): The user
+ * typed "STOP" repeatedly but the agent continued deleting emails because
+ * messages queued in the session's input buffer. By the time the session
+ * processed "stop," 200+ emails were gone.
+ *
+ * The Sentinel solves this by running in the server process (separate from
+ * the session). It can kill or pause the session immediately — before the
+ * message even enters the session's queue.
+ *
+ * Two classification layers:
+ * 1. Fast-path — regex patterns for obvious signals (<5ms)
+ * 2. LLM classification — haiku-tier for ambiguous messages (<500ms)
+ *
+ * Word count gate (2026-02-26 fix):
+ * Regex patterns ONLY fire on short messages (≤ MAX_FAST_PATH_WORDS).
+ * True emergency signals are short: "stop", "cancel", "please stop".
+ * Longer messages like "Please stop warning me about memory" are
+ * conversational and must go to the LLM or pass through to the session.
+ * Slash commands (/stop, /pause) are exempt — always unambiguous.
+ *
+ * Design principle: The entity that evaluates whether to stop must be
+ * separate from the entity performing the work.
+ */
+import type { IntelligenceProvider } from './types.js';
+export type SentinelCategory = 'emergency-stop' | 'pause' | 'redirect' | 'normal';
+export interface SentinelClassification {
+    /** What category this message falls into */
+    category: SentinelCategory;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Whether this was classified via fast-path or LLM */
+    method: 'fast-path' | 'llm' | 'default';
+    /** Classification latency in ms */
+    latencyMs: number;
+    /** The recommended action */
+    action: SentinelAction;
+    /** Optional reason for the classification */
+    reason?: string;
+}
+export type SentinelAction = {
+    type: 'kill-session';
+} | {
+    type: 'pause-session';
+} | {
+    type: 'priority-inject';
+    message: string;
+} | {
+    type: 'pass-through';
+};
+export interface MessageSentinelConfig {
+    /** Intelligence provider for LLM classification */
+    intelligence?: IntelligenceProvider;
+    /** Additional fast-path stop patterns (merged with defaults) */
+    customStopPatterns?: string[];
+    /** Additional fast-path pause patterns (merged with defaults) */
+    customPausePatterns?: string[];
+    /** Whether the Sentinel is enabled (default: true) */
+    enabled?: boolean;
+    /** Skip LLM classification and use fast-path only (default: false) */
+    fastPathOnly?: boolean;
+}
+export interface SentinelStats {
+    /** Total messages classified */
+    totalClassified: number;
+    /** By category */
+    byCategory: Record<SentinelCategory, number>;
+    /** By method */
+    byMethod: Record<string, number>;
+    /** Average latency ms */
+    avgLatencyMs: number;
+    /** Emergency stops triggered */
+    emergencyStops: number;
+}
+export declare class MessageSentinel {
+    private config;
+    private stats;
+    private customStopExact;
+    private customPauseExact;
+    constructor(config?: MessageSentinelConfig);
+    /**
+     * Classify an incoming user message.
+     *
+     * Returns the classification with recommended action.
+     * The caller (TelegramAdapter/server) decides whether to execute the action.
+     */
+    classify(message: string): Promise<SentinelClassification>;
+    /**
+     * Fast-path classification using pattern matching.
+     * Returns null if no pattern matches (falls through to LLM).
+     *
+     * Word count gate: Messages longer than MAX_FAST_PATH_WORDS skip
+     * exact matches and regex patterns. Only slash commands are exempt.
+     * This prevents conversational messages like "please stop warning me
+     * about memory" from being misclassified as emergency stops.
+     */
+    private fastClassify;
+    /**
+     * LLM-based classification for ambiguous messages.
+     */
+    private llmClassify;
+    /**
+     * Extract a valid category from an LLM response.
+     *
+     * Handles three cases:
+     * 1. Exact match: response is just the category word (ideal)
+     * 2. Extracted: response contains the category word in a sentence
+     *    (e.g., "I would classify this as normal")
+     * 3. null: no valid category found in the response
+     *
+     * Priority order when multiple categories appear: emergency-stop > pause > redirect > normal.
+     * This ensures that if the LLM says "this is normal, not emergency-stop", the higher-priority
+     * category wins — erring toward caution.
+     */
+    private extractCategory;
+    /**
+     * Map a category to its recommended action.
+     */
+    private categoryToAction;
+    /**
+     * Record classification stats.
+     */
+    private recordStats;
+    /**
+     * Get current stats.
+     */
+    getStats(): SentinelStats;
+    /**
+     * Reset stats.
+     */
+    resetStats(): void;
+    /**
+     * Check if the sentinel is enabled.
+     */
+    isEnabled(): boolean;
+}
+//# sourceMappingURL=MessageSentinel.d.ts.map

package/dist/core/MessageSentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageSentinel.d.ts","sourceRoot":"","sources":["../../src/core/MessageSentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAIvD,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;IACxC,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,MAAM,EAAE,cAAc,CAAC;IACvB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAE7B,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC7C,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;CACxB;AA+FD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,gBAAgB,CAAc;gBAE1B,MAAM,GAAE,qBAA0B;IAmB9C;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmDhE;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IA2FpB;;OAEG;YACW,WAAW;IAiEzB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,eAAe;IA4BvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;IACH,QAAQ,IAAI,aAAa;IAIzB;;OAEG;IACH,UAAU,IAAI,IAAI;IAUlB;;OAEG;IACH,SAAS,IAAI,OAAO;CAGrB"}