@animalabs/agent-framework 0.1.0

package/dist/src/mcpl/push-handler.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PushHandler — handles push/event messages from MCPL servers.
+ *
+ * Validates feature sets, deduplicates by eventId, converts MCPL content blocks
+ * to membrane ContentBlock[], and pushes McplPushEvents into the processing queue.
+ *
+ * Spec reference: Section 9 (Push Events).
+ */
+import type { ContentBlock } from '@animalabs/membrane';
+import type { PushEventParams, PushEventResult } from './types.js';
+import type { FeatureSetManager } from './feature-set-manager.js';
+/**
+ * A push event converted for the framework processing queue.
+ *
+ * NOTE: This interface should be added to src/types/events.ts and included
+ * in the ProcessEvent union. It is defined here for reference but the actual
+ * events.ts modification is deferred.
+ */
+export interface McplPushEvent {
+    type: 'mcpl:push-event';
+    serverId: string;
+    featureSet: string;
+    eventId: string;
+    content: ContentBlock[];
+    origin?: Record<string, unknown>;
+    timestamp: string;
+    inferenceId: string;
+    triggerInference?: boolean;
+    targetAgents?: string[];
+}
+/** Minimal responder interface for sending JSON-RPC results back. */
+interface Responder {
+    respond(result: PushEventResult): void;
+    respondError?(code: number, message: string, data?: unknown): void;
+}
+export declare class PushHandler {
+    private featureSetManager;
+    private pushEventFn;
+    private emitTraceFn;
+    private shouldTriggerInference?;
+    private dedup;
+    constructor(featureSetManager: FeatureSetManager, pushEventFn: (event: McplPushEvent) => void, emitTraceFn: (event: {
+        type: string;
+        [key: string]: unknown;
+    }) => void, shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean);
+    /**
+     * Handle a push/event message from an MCPL server.
+     *
+     * 1. Validate feature set
+     * 2. Deduplicate by eventId
+     * 3. Optionally check shouldTriggerInference callback
+     * 4. Convert content blocks
+     * 5. Push event to queue
+     * 6. Emit trace
+     * 7. Respond with accepted + inferenceId
+     */
+    handlePushEvent(serverId: string, params: PushEventParams, responder?: Responder): void;
+}
+export {};
+//# sourceMappingURL=push-handler.d.ts.map

package/dist/src/mcpl/push-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-handler.d.ts","sourceRoot":"","sources":["../../../src/mcpl/push-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAEV,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAOlE;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAgFD,qEAAqE;AACrE,UAAU,SAAS;IACjB,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACpE;AAMD,qBAAa,WAAW;IACtB,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,WAAW,CAA4D;IAC/E,OAAO,CAAC,sBAAsB,CAAC,CAAkE;IACjG,OAAO,CAAC,KAAK,CAAsB;gBAGjC,iBAAiB,EAAE,iBAAiB,EACpC,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EAC3C,WAAW,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,KAAK,IAAI,EACtE,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO;IAQ1F;;;;;;;;;;OAUG;IACH,eAAe,CACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,eAAe,EACvB,SAAS,CAAC,EAAE,SAAS,GACpB,IAAI;CAkER"}

package/dist/src/mcpl/push-handler.js

@@ -0,0 +1,162 @@
+/**
+ * PushHandler — handles push/event messages from MCPL servers.
+ *
+ * Validates feature sets, deduplicates by eventId, converts MCPL content blocks
+ * to membrane ContentBlock[], and pushes McplPushEvents into the processing queue.
+ *
+ * Spec reference: Section 9 (Push Events).
+ */
+import { McplFeatureSetError } from './feature-set-manager.js';
+// ============================================================================
+// Content conversion: McplContentBlock → membrane ContentBlock
+// ============================================================================
+/**
+ * Convert a single MCPL wire-format content block to a membrane ContentBlock.
+ * Same logic as hook-orchestrator.ts.
+ */
+function convertBlock(block) {
+    switch (block.type) {
+        case 'text':
+            return { type: 'text', text: block.text };
+        case 'image':
+            if (block.data && block.mimeType) {
+                return {
+                    type: 'image',
+                    source: { type: 'base64', data: block.data, mediaType: block.mimeType },
+                };
+            }
+            if (block.uri) {
+                return {
+                    type: 'image',
+                    source: { type: 'url', url: block.uri },
+                };
+            }
+            return { type: 'text', text: '[Image: no data]' };
+        case 'audio':
+            if (block.data && block.mimeType) {
+                return {
+                    type: 'audio',
+                    source: { type: 'base64', data: block.data, mediaType: block.mimeType },
+                };
+            }
+            return { type: 'text', text: '[Audio: no data]' };
+        case 'resource':
+            return { type: 'text', text: `[Resource: ${block.uri}]` };
+    }
+}
+// ============================================================================
+// LRU Dedup Set
+// ============================================================================
+/**
+ * Simple dedup set with a max capacity. When full, clears and starts fresh.
+ * Good enough for a deduplication window — exact LRU is overkill here.
+ */
+class DedupSet {
+    set = new Set();
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * Returns true if the key was already present (duplicate).
+     * Otherwise adds it and returns false.
+     */
+    checkAndAdd(key) {
+        if (this.set.has(key)) {
+            return true;
+        }
+        if (this.set.size >= this.maxSize) {
+            this.set.clear();
+        }
+        this.set.add(key);
+        return false;
+    }
+}
+// ============================================================================
+// PushHandler
+// ============================================================================
+export class PushHandler {
+    featureSetManager;
+    pushEventFn;
+    emitTraceFn;
+    shouldTriggerInference;
+    dedup = new DedupSet(1000);
+    constructor(featureSetManager, pushEventFn, emitTraceFn, shouldTriggerInference) {
+        this.featureSetManager = featureSetManager;
+        this.pushEventFn = pushEventFn;
+        this.emitTraceFn = emitTraceFn;
+        this.shouldTriggerInference = shouldTriggerInference;
+    }
+    /**
+     * Handle a push/event message from an MCPL server.
+     *
+     * 1. Validate feature set
+     * 2. Deduplicate by eventId
+     * 3. Optionally check shouldTriggerInference callback
+     * 4. Convert content blocks
+     * 5. Push event to queue
+     * 6. Emit trace
+     * 7. Respond with accepted + inferenceId
+     */
+    handlePushEvent(serverId, params, responder) {
+        // 1. Validate feature set
+        try {
+            this.featureSetManager.validateInbound(serverId, params.featureSet);
+        }
+        catch (err) {
+            const reason = err instanceof McplFeatureSetError
+                ? err.message
+                : 'Feature set validation failed';
+            responder?.respond({ accepted: false, reason });
+            return;
+        }
+        // 2. Deduplicate by eventId
+        if (this.dedup.checkAndAdd(params.eventId)) {
+            responder?.respond({ accepted: false, reason: 'duplicate' });
+            return;
+        }
+        // 3. Convert content blocks
+        const content = params.payload.content.map(convertBlock);
+        // 4. Check shouldTriggerInference callback
+        let triggerInference = true;
+        if (this.shouldTriggerInference) {
+            const textContent = content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text)
+                .join('\n');
+            const metadata = {
+                serverId,
+                featureSet: params.featureSet,
+                eventId: params.eventId,
+                eventType: 'push:event',
+                ...(params.origin ?? {}),
+            };
+            triggerInference = this.shouldTriggerInference(textContent, metadata);
+        }
+        // 5. Generate inferenceId
+        const inferenceId = `${serverId}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        // 6. Push event to queue
+        const pushEvent = {
+            type: 'mcpl:push-event',
+            serverId,
+            featureSet: params.featureSet,
+            eventId: params.eventId,
+            content,
+            origin: params.origin,
+            timestamp: params.timestamp,
+            inferenceId,
+            triggerInference,
+        };
+        this.pushEventFn(pushEvent);
+        // 7. Emit trace
+        this.emitTraceFn({
+            type: 'mcpl:push_event',
+            serverId,
+            eventId: params.eventId,
+            featureSet: params.featureSet,
+        });
+        // 8. Respond
+        responder?.respond({ accepted: true, inferenceId });
+    }
+}
+//# sourceMappingURL=push-handler.js.map

package/dist/src/mcpl/push-handler.js.map

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

package/dist/src/mcpl/scope-manager.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ScopeManager — Whitelist/blacklist enforcement and scope elevation for MCPL.
+ *
+ * Manages per-feature-set scope configurations and evaluates whether actions
+ * are approved, denied, or require user prompting. Handles `scope/elevate`
+ * requests from servers.
+ *
+ * Spec references: Section 7 (Scoped Access).
+ */
+import type { ScopeConfig, ScopeLabel, ScopeElevateParams, ScopeElevateResult } from './types.js';
+/**
+ * Callback invoked when a scope elevation requires user approval.
+ * Returns true if the user approves, false otherwise.
+ */
+export type ElevationHandler = (featureSet: string, scope: ScopeLabel) => Promise<boolean>;
+/**
+ * Manages whitelist/blacklist enforcement and scope elevation for feature sets.
+ *
+ * Evaluation order (per spec Section 7.6):
+ * 1. Check approval cache (session-level)
+ * 2. Check blacklist (if any pattern matches -> denied)
+ * 3. Check whitelist (if any pattern matches -> approved)
+ * 4. Otherwise -> prompt
+ */
+export declare class ScopeManager {
+    /** Scope configs keyed by feature set name. */
+    private configs;
+    /** Cached approvals: Set of `${featureSet}\0${label}` keys. */
+    private approvalCache;
+    /** Optional handler for user-approval prompts. */
+    private elevationHandler;
+    /**
+     * Set scope configuration for a single feature set.
+     */
+    configure(featureSet: string, config: ScopeConfig): void;
+    /**
+     * Set scope configurations for multiple feature sets at once.
+     */
+    configureAll(scopes: Record<string, ScopeConfig>): void;
+    /**
+     * Check whether a label is approved, denied, or needs prompting
+     * for the given feature set.
+     *
+     * Evaluation order:
+     * 1. Approval cache hit -> 'approved'
+     * 2. Blacklist match -> 'denied'
+     * 3. Whitelist match -> 'approved'
+     * 4. No config or no match -> 'prompt'
+     */
+    checkScope(featureSet: string, label: string): 'approved' | 'denied' | 'prompt';
+    /**
+     * Handle a `scope/elevate` request from a server.
+     *
+     * Checks scope against whitelist/blacklist, then:
+     * - 'approved' -> return approved with payload
+     * - 'denied'   -> return denied with reason
+     * - 'prompt'   -> invoke elevation handler if registered, otherwise deny
+     */
+    handleElevation(params: ScopeElevateParams): Promise<ScopeElevateResult>;
+    /**
+     * Register a custom elevation handler for user-approval prompts.
+     * The handler is called when a scope check returns 'prompt'.
+     */
+    setElevationHandler(handler: ElevationHandler): void;
+    /**
+     * Cache an approval for the session.
+     * Subsequent `checkScope()` calls with the same feature set and label
+     * will return 'approved' without re-evaluating patterns.
+     */
+    cacheApproval(featureSet: string, label: string): void;
+    /**
+     * Clear all cached approvals.
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=scope-manager.d.ts.map

package/dist/src/mcpl/scope-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-manager.d.ts","sourceRoot":"","sources":["../../../src/mcpl/scope-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,KACd,OAAO,CAAC,OAAO,CAAC,CAAC;AAkEtB;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,+CAA+C;IAC/C,OAAO,CAAC,OAAO,CAAkC;IAEjD,+DAA+D;IAC/D,OAAO,CAAC,aAAa,CAAqB;IAE1C,kDAAkD;IAClD,OAAO,CAAC,gBAAgB,CAAiC;IAEzD;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAIxD;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI;IAMvD;;;;;;;;;OASG;IACH,UAAU,CACR,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,UAAU,GAAG,QAAQ,GAAG,QAAQ;IAmCnC;;;;;;;OAOG;IACG,eAAe,CACnB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC;IA0C9B;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAIpD;;;;OAIG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAItD;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/dist/src/mcpl/scope-manager.js

@@ -0,0 +1,213 @@
+/**
+ * ScopeManager — Whitelist/blacklist enforcement and scope elevation for MCPL.
+ *
+ * Manages per-feature-set scope configurations and evaluates whether actions
+ * are approved, denied, or require user prompting. Handles `scope/elevate`
+ * requests from servers.
+ *
+ * Spec references: Section 7 (Scoped Access).
+ */
+// ============================================================================
+// Glob Matching
+// ============================================================================
+/**
+ * Simple glob-style pattern matching.
+ *
+ * Supported syntax:
+ *   - `*`  matches any sequence of characters except `/`
+ *   - `**` matches any sequence of characters including `/`
+ *   - All other characters are matched literally
+ *
+ * The pattern must match the entire text (anchored at both ends).
+ */
+function globMatch(pattern, text) {
+    // Convert glob pattern to a RegExp
+    let regexStr = '^';
+    let i = 0;
+    while (i < pattern.length) {
+        if (pattern[i] === '*' && pattern[i + 1] === '*') {
+            // `**` matches any characters including `/`
+            regexStr += '.*';
+            i += 2;
+            // Skip a trailing `/` after `**` if present (e.g., `**/foo`)
+            if (i < pattern.length && pattern[i] === '/') {
+                regexStr += '(?:/|$)';
+                i++;
+            }
+        }
+        else if (pattern[i] === '*') {
+            // `*` matches any characters except `/`
+            regexStr += '[^/]*';
+            i++;
+        }
+        else {
+            // Escape regex special characters
+            regexStr += escapeRegex(pattern[i]);
+            i++;
+        }
+    }
+    regexStr += '$';
+    try {
+        const regex = new RegExp(regexStr);
+        return regex.test(text);
+    }
+    catch {
+        // If the pattern produces an invalid regex, fall back to exact match
+        return pattern === text;
+    }
+}
+/** Escape a character for use in a RegExp. */
+function escapeRegex(char) {
+    const special = /[.+?^${}()|[\]\\]/;
+    if (special.test(char)) {
+        return '\\' + char;
+    }
+    return char;
+}
+// ============================================================================
+// ScopeManager
+// ============================================================================
+/**
+ * Manages whitelist/blacklist enforcement and scope elevation for feature sets.
+ *
+ * Evaluation order (per spec Section 7.6):
+ * 1. Check approval cache (session-level)
+ * 2. Check blacklist (if any pattern matches -> denied)
+ * 3. Check whitelist (if any pattern matches -> approved)
+ * 4. Otherwise -> prompt
+ */
+export class ScopeManager {
+    /** Scope configs keyed by feature set name. */
+    configs = new Map();
+    /** Cached approvals: Set of `${featureSet}\0${label}` keys. */
+    approvalCache = new Set();
+    /** Optional handler for user-approval prompts. */
+    elevationHandler = null;
+    /**
+     * Set scope configuration for a single feature set.
+     */
+    configure(featureSet, config) {
+        this.configs.set(featureSet, config);
+    }
+    /**
+     * Set scope configurations for multiple feature sets at once.
+     */
+    configureAll(scopes) {
+        for (const [featureSet, config] of Object.entries(scopes)) {
+            this.configs.set(featureSet, config);
+        }
+    }
+    /**
+     * Check whether a label is approved, denied, or needs prompting
+     * for the given feature set.
+     *
+     * Evaluation order:
+     * 1. Approval cache hit -> 'approved'
+     * 2. Blacklist match -> 'denied'
+     * 3. Whitelist match -> 'approved'
+     * 4. No config or no match -> 'prompt'
+     */
+    checkScope(featureSet, label) {
+        // 1. Check approval cache
+        if (this.approvalCache.has(cacheKey(featureSet, label))) {
+            return 'approved';
+        }
+        const config = this.configs.get(featureSet);
+        // No config for this feature set -> prompt
+        if (!config) {
+            return 'prompt';
+        }
+        // 2. Check blacklist first (deny wins)
+        if (config.blacklist) {
+            for (const pattern of config.blacklist) {
+                if (globMatch(pattern, label)) {
+                    return 'denied';
+                }
+            }
+        }
+        // 3. Check whitelist
+        if (config.whitelist) {
+            for (const pattern of config.whitelist) {
+                if (globMatch(pattern, label)) {
+                    return 'approved';
+                }
+            }
+        }
+        // 4. Neither matched
+        return 'prompt';
+    }
+    /**
+     * Handle a `scope/elevate` request from a server.
+     *
+     * Checks scope against whitelist/blacklist, then:
+     * - 'approved' -> return approved with payload
+     * - 'denied'   -> return denied with reason
+     * - 'prompt'   -> invoke elevation handler if registered, otherwise deny
+     */
+    async handleElevation(params) {
+        const { featureSet, scope } = params;
+        const result = this.checkScope(featureSet, scope.label);
+        if (result === 'approved') {
+            return {
+                approved: true,
+                payload: scope.payload,
+            };
+        }
+        if (result === 'denied') {
+            return {
+                approved: false,
+                reason: 'Scope denied by blacklist',
+            };
+        }
+        // result === 'prompt'
+        if (this.elevationHandler) {
+            const approved = await this.elevationHandler(featureSet, scope);
+            if (approved) {
+                // Cache the approval for the session
+                this.cacheApproval(featureSet, scope.label);
+                return {
+                    approved: true,
+                    payload: scope.payload,
+                };
+            }
+            return {
+                approved: false,
+                reason: 'User denied the elevation request',
+            };
+        }
+        // No handler registered — default to denied
+        return {
+            approved: false,
+            reason: 'User approval required',
+        };
+    }
+    /**
+     * Register a custom elevation handler for user-approval prompts.
+     * The handler is called when a scope check returns 'prompt'.
+     */
+    setElevationHandler(handler) {
+        this.elevationHandler = handler;
+    }
+    /**
+     * Cache an approval for the session.
+     * Subsequent `checkScope()` calls with the same feature set and label
+     * will return 'approved' without re-evaluating patterns.
+     */
+    cacheApproval(featureSet, label) {
+        this.approvalCache.add(cacheKey(featureSet, label));
+    }
+    /**
+     * Clear all cached approvals.
+     */
+    clearCache() {
+        this.approvalCache.clear();
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/** Build a cache key from feature set and label. */
+function cacheKey(featureSet, label) {
+    return `${featureSet}\0${label}`;
+}
+//# sourceMappingURL=scope-manager.js.map

package/dist/src/mcpl/scope-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-manager.js","sourceRoot":"","sources":["../../../src/mcpl/scope-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsBH,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,SAAS,SAAS,CAAC,OAAe,EAAE,IAAY;IAC9C,mCAAmC;IACnC,IAAI,QAAQ,GAAG,GAAG,CAAC;IACnB,IAAI,CAAC,GAAG,CAAC,CAAC;IAEV,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1B,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACjD,4CAA4C;YAC5C,QAAQ,IAAI,IAAI,CAAC;YACjB,CAAC,IAAI,CAAC,CAAC;YACP,6DAA6D;YAC7D,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC7C,QAAQ,IAAI,SAAS,CAAC;gBACtB,CAAC,EAAE,CAAC;YACN,CAAC;QACH,CAAC;aAAM,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC9B,wCAAwC;YACxC,QAAQ,IAAI,OAAO,CAAC;YACpB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,CAAC;YACN,kCAAkC;YAClC,QAAQ,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;YACpC,CAAC,EAAE,CAAC;QACN,CAAC;IACH,CAAC;IAED,QAAQ,IAAI,GAAG,CAAC;IAEhB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,OAAO,OAAO,KAAK,IAAI,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,8CAA8C;AAC9C,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,OAAO,GAAG,mBAAmB,CAAC;IACpC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IACvB,+CAA+C;IACvC,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEjD,+DAA+D;IACvD,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IAE1C,kDAAkD;IAC1C,gBAAgB,GAA4B,IAAI,CAAC;IAEzD;;OAEG;IACH,SAAS,CAAC,UAAkB,EAAE,MAAmB;QAC/C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAmC;QAC9C,KAAK,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,UAAU,CACR,UAAkB,EAClB,KAAa;QAEb,0BAA0B;QAC1B,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;YACxD,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAE5C,2CAA2C;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,uCAAuC;QACvC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACvC,IAAI,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;oBAC9B,OAAO,QAAQ,CAAC;gBAClB,CAAC;YACH,CAAC;QACH,CAAC;QAED,qBAAqB;QACrB,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACvC,IAAI,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;oBAC9B,OAAO,UAAU,CAAC;gBACpB,CAAC;YACH,CAAC;QACH,CAAC;QAED,qBAAqB;QACrB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,eAAe,CACnB,MAA0B;QAE1B,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAExD,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,OAAO;gBACL,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,2BAA2B;aACpC,CAAC;QACJ,CAAC;QAED,sBAAsB;QACtB,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YAChE,IAAI,QAAQ,EAAE,CAAC;gBACb,qCAAqC;gBACrC,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC5C,OAAO;oBACL,QAAQ,EAAE,IAAI;oBACd,OAAO,EAAE,KAAK,CAAC,OAAO;iBACvB,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,mCAAmC;aAC5C,CAAC;QACJ,CAAC;QAED,4CAA4C;QAC5C,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,wBAAwB;SACjC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,mBAAmB,CAAC,OAAyB;QAC3C,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,UAAkB,EAAE,KAAa;QAC7C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;CACF;AAED,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,oDAAoD;AACpD,SAAS,QAAQ,CAAC,UAAkB,EAAE,KAAa;IACjD,OAAO,GAAG,UAAU,KAAK,KAAK,EAAE,CAAC;AACnC,CAAC"}