agent-nuvira 1.18.0 → 1.20.0

package/README.md

@@ -1339,7 +1339,7 @@ npx tsc --noEmit
 
 **Phases 1–3 (25 phases) are complete.** Phase 4 (Industry Standards & Autonomous Polish) is in progress. See [UPGRADE_ROADMAP.md](./UPGRADE_ROADMAP.md) for the full implementation journey.
 
-> 📊 **Product strategy and pitch materials:** [PRODUCT_STRATEGY.md](./PRODUCT_STRATEGY.md) — Competitive landscape, positioning map, OKR framework, and risk register. [PITCH_DECK.md](./PITCH_DECK.md) — 10-slide investor presentation outline with talking points and data.
+> 📊 **Architecture, strategy & contribution materials:** [ARCHITECTURE.md](./ARCHITECTURE.md) — Modular execution engine design with 7 module specifications, extensibility/observability systems, and phased migration plan. [ARCHITECTURE_DIAGRAMS.md](./ARCHITECTURE_DIAGRAMS.md) — Mermaid-rendered versions of all architecture diagrams (Module Architecture, Extensibility, Safe Execution, Data Flow, Observability Bus). [PRODUCT_STRATEGY.md](./PRODUCT_STRATEGY.md) — Competitive landscape, positioning map, OKR framework, and risk register. [PITCH_DECK.md](./PITCH_DECK.md) — 10-slide investor presentation outline with talking points and data. [CONTRIBUTING.md](./CONTRIBUTING.md) — Quick-reference contributor guide with docs map, dev setup, and contribution workflow.
 
 | Phase | Feature | Status |
 |---|---|---|

package/dist/agents/inspect-module.d.ts

@@ -0,0 +1,115 @@
+/**
+ * InspectModule — Scans the codebase to discover relevant files, extract
+ * structural context, and identify dependencies. Phase 5 of the architecture
+ * migration: wrap ContextGathererAgent in the modular InspectModule interface.
+ *
+ * @see ARCHITECTURE.md §3.2 — Inspect Module specification
+ */
+import type { EventBus } from '../observability/event-bus.js';
+/**
+ * A discovered file artifact with its content.
+ * Prefixed with "Inspect" to avoid collision with agent.ts's Artifact type.
+ */
+export interface InspectArtifact {
+    /** Relative path from the project root */
+    path: string;
+    /** Full file contents */
+    content: string;
+    /** Human-readable description (e.g. 'src/index.ts (12.5k characters)') */
+    description: string;
+}
+/** Statistics about the inspection run */
+export interface InspectionStats {
+    /** Total files in the project */
+    totalFiles: number;
+    /** Files that were inspected / read */
+    inspectedFiles: number;
+    /** Number of errors encountered during inspection */
+    errors: number;
+    /** Whether the LLM-based classification fell back to keyword scanning */
+    llmFallbackUsed: boolean;
+}
+/** Result of a codebase inspection */
+export interface InspectionResult {
+    /** Discovered file artifacts with full contents */
+    artifacts: InspectArtifact[];
+    /** Text representation of the project file tree */
+    fileTree: string;
+    /** File paths that are relevant to the goal */
+    relevantPaths: string[];
+    /** Inspection statistics */
+    stats: InspectionStats;
+}
+/** Parameters for the InspectModule.inspect() method */
+export interface InspectParams {
+    /** The user's goal / task description */
+    goal: string;
+    /** Working directory of the project */
+    workingDirectory: string;
+    /** Optional list of task plan descriptions for context */
+    taskDescriptions?: string[];
+    /** Maximum number of files to inspect (default: 10) */
+    maxFiles?: number;
+}
+/**
+ * PlanStep-like interface for dependency-aware planning.
+ * A minimal version of what the PlanModule produces.
+ */
+export interface PlanStepRef {
+    id: string;
+    description: string;
+}
+/**
+ * InspectModule — Scan the codebase to discover relevant files, extract
+ * structural context, and identify dependencies.
+ *
+ * @example
+ * ```typescript
+ * const module = new DefaultInspectModule();
+ * const result = await module.inspect({
+ *   goal: 'Add JWT auth',
+ *   workingDirectory: '/project',
+ * });
+ * console.log(result.artifacts.length); // Files discovered
+ * ```
+ */
+export interface InspectModule {
+    /**
+     * Scan the codebase for files relevant to the given goal.
+     * Uses LLM-based classification with keyword fallback.
+     */
+    inspect(params: InspectParams): Promise<InspectionResult>;
+    /**
+     * Synchronous fallback — scans files by keyword matching against the goal.
+     * Used when the LLM call fails or times out.
+     */
+    scanByKeywords(goal: string, workingDir: string): string[];
+}
+/**
+ * DefaultInspectModule — Built-in inspect module implementation.
+ *
+ * Wraps the existing keyword-scanning logic (previously private to
+ * ContextGathererAgent) into the modular InspectModule interface.
+ * The LLM-based file identification is delegated to the agent system
+ * via the callLLM parameter — when no callLLM is provided, only
+ * keyword-based scanning is used.
+ */
+export declare class DefaultInspectModule implements InspectModule {
+    /** The event bus for emitting observability events */
+    private eventBus;
+    constructor(eventBus?: EventBus);
+    /**
+     * Scan the codebase for files relevant to the given goal.
+     */
+    inspect(params: InspectParams): Promise<InspectionResult>;
+    /**
+     * Synchronous fallback — scan files by keyword matching against the goal.
+     * Used when the LLM call fails or as the base implementation.
+     */
+    scanByKeywords(goal: string, workingDir: string): string[];
+    /** Walk the directory tree and score files by keyword relevance */
+    private walkAndScore;
+    /** Format byte count to human-readable string */
+    private formatSize;
+}
+//# sourceMappingURL=inspect-module.d.ts.map

package/dist/agents/inspect-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-module.d.ts","sourceRoot":"","sources":["../../src/agents/inspect-module.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAK9D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4BAA4B;IAC5B,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE1D;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC5D;AAYD;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IACxD,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAW;gBAEf,QAAQ,CAAC,EAAE,QAAQ;IAI/B;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmF/D;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAwB1D,mEAAmE;IACnE,OAAO,CAAC,YAAY;IAgDpB,iDAAiD;IACjD,OAAO,CAAC,UAAU;CAKnB"}

package/dist/agents/inspect-module.js

@@ -0,0 +1,180 @@
+/**
+ * InspectModule — Scans the codebase to discover relevant files, extract
+ * structural context, and identify dependencies. Phase 5 of the architecture
+ * migration: wrap ContextGathererAgent in the modular InspectModule interface.
+ *
+ * @see ARCHITECTURE.md §3.2 — Inspect Module specification
+ */
+import { join, relative } from 'node:path';
+import { existsSync, readFileSync, statSync, readdirSync } from 'node:fs';
+import { getEventBus, EventNames } from '../observability/event-bus.js';
+import { buildProjectFileTree } from './utils/file-tree.js';
+// ─── Constants ──────────────────────────────────────────────────────────────
+// Reuse constants from the shared file-tree utility to avoid duplication
+import { SOURCE_EXTENSIONS, IGNORE_DIRS } from './utils/file-tree.js';
+/** Maximum characters per file when reading */
+const MAX_FILE_CHARS = 100_000;
+// ─── Default InspectModule ─────────────────────────────────────────────────
+/**
+ * DefaultInspectModule — Built-in inspect module implementation.
+ *
+ * Wraps the existing keyword-scanning logic (previously private to
+ * ContextGathererAgent) into the modular InspectModule interface.
+ * The LLM-based file identification is delegated to the agent system
+ * via the callLLM parameter — when no callLLM is provided, only
+ * keyword-based scanning is used.
+ */
+export class DefaultInspectModule {
+    /** The event bus for emitting observability events */
+    eventBus;
+    constructor(eventBus) {
+        this.eventBus = eventBus ?? getEventBus();
+    }
+    /**
+     * Scan the codebase for files relevant to the given goal.
+     */
+    async inspect(params) {
+        const { goal, workingDirectory, taskDescriptions, maxFiles = 10 } = params;
+        // ── Emit: scanning started ───────────────────────────────────────
+        this.eventBus.emit(EventNames.INSPECT_SCANNING, {
+            directory: workingDirectory,
+            goal,
+        }, 'inspect-module');
+        // 1. Build the project file tree
+        const fileTree = await buildProjectFileTree(workingDirectory);
+        const totalFiles = fileTree.split('\n').filter((l) => l.includes('📄')).length;
+        // 2. Use keyword scanning to identify relevant paths
+        //    (Phase 5 uses keyword scanning as the base implementation.
+        //     TODO: Phase 6 — emit INSPECT_LLM_CLASSIFY when LLM-based classification is added.)
+        const relevantPaths = this.scanByKeywords(goal, workingDirectory);
+        // Limit to maxFiles
+        const limitedPaths = relevantPaths.slice(0, maxFiles);
+        // 3. Read the identified files
+        const artifacts = [];
+        const errors = [];
+        for (const filePath of limitedPaths) {
+            const absolutePath = join(workingDirectory, filePath);
+            if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+                errors.push(`File not found: ${filePath}`);
+                continue;
+            }
+            try {
+                const size = statSync(absolutePath).size;
+                if (size > MAX_FILE_CHARS) {
+                    errors.push(`File too large: ${filePath} (${this.formatSize(size)})`);
+                    continue;
+                }
+                const content = readFileSync(absolutePath, 'utf-8');
+                // ── Emit: file found event ───────────────────────────────────
+                this.eventBus.emit(EventNames.INSPECT_FILE_FOUND, {
+                    path: filePath,
+                    extension: filePath.slice(filePath.lastIndexOf('.')),
+                    size,
+                }, 'inspect-module');
+                artifacts.push({
+                    path: filePath,
+                    content,
+                    description: `${filePath} (${this.formatSize(content.length)} characters)`,
+                });
+            }
+            catch {
+                errors.push(`Could not read: ${filePath}`);
+            }
+        }
+        const stats = {
+            totalFiles,
+            inspectedFiles: artifacts.length,
+            errors: errors.length,
+            // Phase 5 always uses keyword scanning; Phase 6+ will set this based
+            // on whether the LLM classifier fell back to keyword matching.
+            llmFallbackUsed: true,
+        };
+        // ── Emit: completed event ────────────────────────────────────────
+        this.eventBus.emit(EventNames.INSPECT_COMPLETED, {
+            artifactCount: artifacts.length,
+            errors: errors.length,
+            totalFiles,
+        }, 'inspect-module');
+        return {
+            artifacts,
+            fileTree,
+            relevantPaths: limitedPaths,
+            stats,
+        };
+    }
+    /**
+     * Synchronous fallback — scan files by keyword matching against the goal.
+     * Used when the LLM call fails or as the base implementation.
+     */
+    scanByKeywords(goal, workingDir) {
+        const stopWords = new Set([
+            'the', 'a', 'an', 'in', 'to', 'for', 'of', 'and', 'or', 'is',
+            'add', 'fix', 'update', 'change', 'remove', 'create', 'implement',
+            'with', 'on', 'at', 'by', 'from', 'as', 'be', 'this', 'that',
+        ]);
+        const keywords = goal
+            .toLowerCase()
+            .split(/[\s,.-]+/)
+            .filter((w) => w.length > 2 && !stopWords.has(w));
+        if (keywords.length === 0)
+            return [];
+        const scored = this.walkAndScore(workingDir, keywords, 0);
+        return scored
+            .sort((a, b) => b.score - a.score)
+            .filter((s) => s.score > 0)
+            .slice(0, 10)
+            .map((s) => s.path);
+    }
+    // ─── Private Helpers ─────────────────────────────────────────────────
+    /** Walk the directory tree and score files by keyword relevance */
+    walkAndScore(dir, keywords, depth, baseDir) {
+        const root = baseDir ?? dir;
+        if (depth > 5)
+            return [];
+        const results = [];
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        for (const entry of entries) {
+            if (IGNORE_DIRS.has(entry.name))
+                continue;
+            const entryPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const subResults = this.walkAndScore(entryPath, keywords, depth + 1, root);
+                results.push(...subResults);
+            }
+            else if (entry.isFile()) {
+                const ext = entry.name.slice(entry.name.lastIndexOf('.'));
+                if (!SOURCE_EXTENSIONS.has(ext))
+                    continue;
+                let score = 0;
+                const lowerName = entry.name.toLowerCase();
+                const lowerPath = entryPath.toLowerCase();
+                for (const kw of keywords) {
+                    if (lowerName.includes(kw))
+                        score += 3;
+                    else if (lowerPath.includes(kw))
+                        score += 1;
+                }
+                if (score > 0) {
+                    const relPath = relative(root, entryPath);
+                    results.push({ path: relPath, score });
+                }
+            }
+        }
+        return results;
+    }
+    /** Format byte count to human-readable string */
+    formatSize(bytes) {
+        if (bytes < 1024)
+            return String(bytes);
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(1)}k`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+    }
+}
+//# sourceMappingURL=inspect-module.js.map

package/dist/agents/inspect-module.js.map

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

package/dist/agents/module-registry.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ModuleRegistry — Plugin-based module loading system for the agent execution engine.
+ *
+ * Replaces the hardcoded `createAgent()` switch statement with a registry that
+ * allows modules (agents) to be registered, discovered, and loaded at runtime.
+ * Built-in agents are pre-registered; custom agents can be added by plugins
+ * or via the SDK's `registerAgent()` function.
+ *
+ * @see ARCHITECTURE.md §4.1 — Extensibility System
+ */
+import { Agent } from './agent.js';
+import type { EventBus } from '../observability/event-bus.js';
+/** Factory function that creates a new Agent instance */
+export type AgentFactory = () => Agent;
+/** Metadata about a registered module */
+export interface ModuleMetadata {
+    /** The agent type string used in task plans (e.g. 'planner', 'writer') */
+    agentType: string;
+    /** Human-readable name of the agent (e.g. 'Planner', 'Writer') */
+    name: string;
+    /** Short description of what this agent does */
+    description: string;
+    /** Emoji icon for the spinner / UI display */
+    icon: string;
+    /** Whether this module is built-in (true) or added by a plugin (false) */
+    isBuiltin: boolean;
+}
+/** Error thrown when a module lookup fails */
+export declare class ModuleNotFoundError extends Error {
+    constructor(agentType: string);
+}
+/**
+ * ModuleRegistry — Central registry for agent modules.
+ *
+ * Manages a collection of agent factories with metadata. Supports lookup,
+ * listing, and dynamic registration at runtime.
+ *
+ * @example
+ * ```typescript
+ * const registry = ModuleRegistry.createWithBuiltins();
+ * const planner = registry.getModule('planner'); // → PlannerAgent instance
+ * ```
+ */
+export declare class ModuleRegistry {
+    /** Agent factory functions, keyed by agentType */
+    private factories;
+    /** Module metadata, keyed by agentType */
+    private metadata;
+    /** The event bus for emitting observability events */
+    private eventBus;
+    constructor(eventBus?: EventBus);
+    /**
+     * Register an agent module with the registry.
+     *
+     * @param agentType - The agent type string used in task plans
+     * @param factory   - Factory function that returns a new Agent instance
+     * @param meta      - Metadata describing the module
+     *
+     * @throws {Error} If `agentType` is already registered (use `override` to replace)
+     */
+    register(agentType: string, factory: AgentFactory, meta: Omit<ModuleMetadata, 'agentType' | 'isBuiltin'> & {
+        isBuiltin?: boolean;
+    }): void;
+    /**
+     * Register an agent module, silently replacing any existing registration.
+     * Useful for plugin overrides and hot-reload scenarios.
+     */
+    registerOrOverride(agentType: string, factory: AgentFactory, meta: Omit<ModuleMetadata, 'agentType' | 'isBuiltin'> & {
+        isBuiltin?: boolean;
+    }): void;
+    /**
+     * Unregister an agent module.
+     * Safe to call for non-existent agent types (no-op).
+     */
+    unregister(agentType: string): boolean;
+    /**
+     * Get an Agent instance for the given agent type.
+     *
+     * @param agentType - The agent type string (e.g. 'planner', 'writer')
+     * @returns A new Agent instance
+     * @throws {ModuleNotFoundError} If no module is registered for `agentType`
+     */
+    getModule(agentType: string): Agent;
+    /**
+     * Check if an agent type is registered.
+     */
+    hasModule(agentType: string): boolean;
+    /**
+     * Get metadata for a registered agent type.
+     * Returns undefined if the agent type is not registered.
+     */
+    getMetadata(agentType: string): ModuleMetadata | undefined;
+    /**
+     * List all registered modules, optionally filtered by a predicate.
+     */
+    listModules(filter?: (meta: ModuleMetadata) => boolean): ModuleMetadata[];
+    /**
+     * Get the icon for an agent type, or a default icon if not found.
+     */
+    getIcon(agentType: string): string;
+    /**
+     * Get the number of registered modules.
+     */
+    get size(): number;
+    /**
+     * Create a ModuleRegistry pre-populated with all built-in agents.
+     */
+    static createWithBuiltins(eventBus?: EventBus): ModuleRegistry;
+}
+/**
+ * Get or create the global ModuleRegistry singleton.
+ *
+ * First call creates a registry with all built-in agents pre-registered.
+ * Subsequent calls return the same instance.
+ * Use `resetModuleRegistry()` to clear and re-initialize (useful in tests).
+ */
+export declare function getModuleRegistry(): ModuleRegistry;
+/**
+ * Reset the global module registry.
+ * Primarily useful in tests to get a clean slate.
+ */
+export declare function resetModuleRegistry(): void;
+/**
+ * Set the global module registry (for dependency injection in tests).
+ * Returns the previous registry instance (or null).
+ */
+export declare function setModuleRegistry(registry: ModuleRegistry): ModuleRegistry | null;
+//# sourceMappingURL=module-registry.d.ts.map

package/dist/agents/module-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-registry.d.ts","sourceRoot":"","sources":["../../src/agents/module-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAenC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAI9D,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,MAAM,KAAK,CAAC;AAEvC,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,8CAA8C;AAC9C,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,SAAS,EAAE,MAAM;CAI9B;AAID;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,kDAAkD;IAClD,OAAO,CAAC,SAAS,CAAmC;IACpD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAqC;IACrD,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAW;gBAEf,QAAQ,CAAC,EAAE,QAAQ;IAM/B;;;;;;;;OAQG;IACH,QAAQ,CACN,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9E,IAAI;IAsBP;;;OAGG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9E,IAAI;IAiBP;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAetC;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAQnC;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI1D;;OAEG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,cAAc,EAAE;IAKzE;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIlC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,cAAc;CAiG/D;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,GAAG,IAAI,CAIjF"}