@framers/agentos 0.1.29 → 0.1.31

package/dist/discovery/CapabilityContextAssembler.js

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Capability Context Assembler — tiered, token-budgeted context builder.
+ * @module @framers/agentos/discovery/CapabilityContextAssembler
+ *
+ * Assembles the capability discovery context for injection into agent prompts.
+ * Enforces hard token budgets per tier to prevent context rot.
+ *
+ * Three tiers (inspired by Anthropic's defer_loading + Redis Tool RAG):
+ *
+ * Tier 0 (~150 tokens): Category summaries — always in context
+ *   "Available categories: Information (4), Developer (3), Communication (8)..."
+ *
+ * Tier 1 (~200 tokens): Retrieved summaries — per-turn semantic retrieval
+ *   "1. web-search (tool, 0.87): Search web. Params: query, max_results"
+ *
+ * Tier 2 (~1500 tokens): Full details — top-2 most relevant capabilities
+ *   Full JSON schema or SKILL.md content
+ *
+ * Token budgets are hard-enforced by the assembler, NOT the LLM.
+ * This is critical for preventing context rot (Chroma 2025).
+ */
+import { DEFAULT_DISCOVERY_CONFIG } from './types.js';
+import { CapabilityEmbeddingStrategy } from './CapabilityEmbeddingStrategy.js';
+// ============================================================================
+// CONTEXT ASSEMBLER
+// ============================================================================
+export class CapabilityContextAssembler {
+    constructor(strategy) {
+        this.cachedTier0 = null;
+        this.cachedTier0Version = 0;
+        this.strategy = strategy ?? new CapabilityEmbeddingStrategy();
+    }
+    // ============================================================================
+    // TIER 0: CATEGORY SUMMARIES
+    // ============================================================================
+    /**
+     * Build Tier 0 category summary text.
+     * Regenerated only when capabilities change (tracked by version).
+     */
+    buildTier0(capabilities, version) {
+        if (this.cachedTier0 && this.cachedTier0Version === version) {
+            return this.cachedTier0;
+        }
+        // Group by category
+        const categories = new Map();
+        for (const cap of capabilities) {
+            const cat = cap.category || 'other';
+            const entry = categories.get(cat) ?? { names: [], count: 0 };
+            entry.names.push(cap.name);
+            entry.count++;
+            categories.set(cat, entry);
+        }
+        // Sort categories by count descending
+        const sorted = Array.from(categories.entries()).sort((a, b) => b[1].count - a[1].count);
+        const lines = ['Available capability categories:'];
+        for (const [category, { names, count }] of sorted) {
+            // Show first 4 names, then count
+            const displayNames = names.slice(0, 4).join(', ');
+            const suffix = count > 4 ? ` (+${count - 4} more)` : '';
+            lines.push(`- ${capitalize(category)}: ${displayNames}${suffix} (${count})`);
+        }
+        lines.push('Use discover_capabilities tool to get details on any capability.');
+        const text = lines.join('\n');
+        this.cachedTier0 = text;
+        this.cachedTier0Version = version;
+        return text;
+    }
+    // ============================================================================
+    // ASSEMBLY
+    // ============================================================================
+    /**
+     * Assemble discovery context from search results.
+     *
+     * Takes raw search results (already filtered and graph-reranked),
+     * applies token budgets, and produces the final tiered result.
+     */
+    assemble(tier0Text, searchResults, config = DEFAULT_DISCOVERY_CONFIG, timings) {
+        const startTime = performance.now();
+        // --- Tier 0 ---
+        const tier0Tokens = estimateTokens(tier0Text);
+        // --- Tier 1: Build compact summaries within budget ---
+        const tier1 = [];
+        let tier1Tokens = 0;
+        const tier1Header = 'Relevant capabilities:\n';
+        tier1Tokens += estimateTokens(tier1Header);
+        const tier1Candidates = searchResults
+            .filter((r) => r.score >= config.tier1MinRelevance)
+            .slice(0, config.tier1TopK);
+        for (const candidate of tier1Candidates) {
+            const summary = this.strategy.buildCompactSummary(candidate.descriptor);
+            const lineText = `${tier1.length + 1}. ${summary}`;
+            const lineTokens = estimateTokens(lineText);
+            if (tier1Tokens + lineTokens > config.tier1TokenBudget)
+                break;
+            tier1Tokens += lineTokens;
+            tier1.push({
+                capability: candidate.descriptor,
+                relevanceScore: candidate.score,
+                summaryText: lineText,
+            });
+        }
+        // --- Tier 2: Full details within budget ---
+        const tier2 = [];
+        let tier2Tokens = 0;
+        // Take top N from Tier 1 for full expansion
+        const tier2Candidates = tier1.slice(0, config.tier2TopK);
+        for (const candidate of tier2Candidates) {
+            const fullText = this.strategy.buildFullDetailText(candidate.capability);
+            const fullTokens = estimateTokens(fullText);
+            if (tier2Tokens + fullTokens > config.tier2TokenBudget)
+                break;
+            tier2Tokens += fullTokens;
+            tier2.push({
+                capability: candidate.capability,
+                fullText,
+            });
+        }
+        const totalTokens = tier0Tokens + tier1Tokens + tier2Tokens;
+        const queryTimeMs = performance.now() - startTime;
+        return {
+            tier0: tier0Text,
+            tier1,
+            tier2,
+            tokenEstimate: {
+                tier0Tokens,
+                tier1Tokens,
+                tier2Tokens,
+                totalTokens,
+            },
+            diagnostics: {
+                queryTimeMs,
+                embeddingTimeMs: timings?.embeddingTimeMs ?? 0,
+                graphTraversalTimeMs: timings?.graphTraversalTimeMs ?? 0,
+                candidatesScanned: searchResults.length,
+                capabilitiesRetrieved: tier1.length + tier2.length,
+            },
+        };
+    }
+    /**
+     * Render a CapabilityDiscoveryResult into a single string
+     * suitable for injection into PromptBuilder.
+     */
+    renderForPrompt(result) {
+        const parts = [];
+        // Tier 0: Always present
+        parts.push(result.tier0);
+        // Tier 1: Retrieved summaries
+        if (result.tier1.length > 0) {
+            parts.push('');
+            parts.push('Relevant capabilities:');
+            for (const item of result.tier1) {
+                parts.push(item.summaryText);
+            }
+        }
+        // Tier 2: Full details
+        if (result.tier2.length > 0) {
+            parts.push('');
+            parts.push('--- Detailed Capability Reference ---');
+            for (const item of result.tier2) {
+                parts.push('');
+                parts.push(item.fullText);
+            }
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Invalidate the Tier 0 cache (e.g., after capabilities change).
+     */
+    invalidateCache() {
+        this.cachedTier0 = null;
+        this.cachedTier0Version = 0;
+    }
+}
+// ============================================================================
+// HELPERS
+// ============================================================================
+/**
+ * Rough token estimation (~4 chars per token for English text).
+ * Used for budget enforcement — not exact, but close enough for budgeting.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Capitalize the first letter of a string.
+ */
+function capitalize(s) {
+    if (!s)
+        return s;
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=CapabilityContextAssembler.js.map

package/dist/discovery/CapabilityContextAssembler.js.map

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

package/dist/discovery/CapabilityDiscoveryEngine.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Capability Discovery Engine — main orchestrator.
+ * @module @framers/agentos/discovery/CapabilityDiscoveryEngine
+ *
+ * Coordinates the capability index, relationship graph, and context assembler
+ * to provide tiered, semantic capability discovery for AgentOS agents.
+ *
+ * Architecture:
+ *   User Message → CapabilityIndex.search() → CapabilityGraph.rerank()
+ *                → CapabilityContextAssembler.assemble() → CapabilityDiscoveryResult
+ *
+ * Performance targets:
+ *   - Initialize: ~3s (one-time embedding generation for ~100 capabilities)
+ *   - Per-turn discover(): ~50ms cold (embedding) / ~5ms warm (cache hit)
+ *   - Context tokens: ~1,850 (down from ~20,000 with static dumps)
+ */
+import type { IEmbeddingManager } from '../rag/IEmbeddingManager.js';
+import type { IVectorStore } from '../rag/IVectorStore.js';
+import type { CapabilityDiscoveryConfig, CapabilityDiscoveryResult, CapabilityDescriptor, CapabilityIndexSources, DiscoveryQueryOptions, ICapabilityDiscoveryEngine, PresetCoOccurrence } from './types.js';
+export declare class CapabilityDiscoveryEngine implements ICapabilityDiscoveryEngine {
+    private readonly index;
+    private readonly graph;
+    private readonly assembler;
+    private readonly config;
+    private indexVersion;
+    private initialized;
+    constructor(embeddingManager: IEmbeddingManager, vectorStore: IVectorStore, config?: Partial<CapabilityDiscoveryConfig>);
+    /**
+     * Initialize the engine: build index + graph from all capability sources.
+     *
+     * @param sources - Tools, skills, extensions, channels, and manifest entries
+     * @param presetCoOccurrences - Co-occurrence data from agent presets
+     */
+    initialize(sources: CapabilityIndexSources, presetCoOccurrences?: PresetCoOccurrence[]): Promise<void>;
+    /**
+     * Discover capabilities relevant to a user message.
+     *
+     * Flow:
+     * 1. Semantic search against capability embeddings
+     * 2. Graph-based re-ranking (boost related capabilities)
+     * 3. Token-budgeted tiered assembly
+     *
+     * Returns a CapabilityDiscoveryResult with Tier 0/1/2 context.
+     */
+    discover(userMessage: string, options?: DiscoveryQueryOptions): Promise<CapabilityDiscoveryResult>;
+    /**
+     * Get full detail for a specific capability by ID.
+     */
+    getCapabilityDetail(id: string): CapabilityDescriptor | undefined;
+    /**
+     * Refresh the index incrementally.
+     * Called when manifest files change or new capabilities are added at runtime.
+     */
+    refreshIndex(sources?: Partial<CapabilityIndexSources>): Promise<void>;
+    isInitialized(): boolean;
+    listCapabilityIds(): string[];
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): Readonly<CapabilityDiscoveryConfig>;
+    /**
+     * Get index statistics.
+     */
+    getStats(): {
+        capabilityCount: number;
+        graphNodes: number;
+        graphEdges: number;
+        indexVersion: number;
+    };
+    /**
+     * Render a discovery result into a string suitable for prompt injection.
+     */
+    renderForPrompt(result: CapabilityDiscoveryResult): string;
+    private emptyResult;
+}
+//# sourceMappingURL=CapabilityDiscoveryEngine.d.ts.map

package/dist/discovery/CapabilityDiscoveryEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityDiscoveryEngine.d.ts","sourceRoot":"","sources":["../../src/discovery/CapabilityDiscoveryEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EAEtB,qBAAqB,EACrB,0BAA0B,EAC1B,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAUpB,qBAAa,yBAA0B,YAAW,0BAA0B;IAC1E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAS;gBAG1B,gBAAgB,EAAE,iBAAiB,EACnC,WAAW,EAAE,YAAY,EACzB,MAAM,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC;IAiB7C;;;;;OAKG;IACG,UAAU,CACd,OAAO,EAAE,sBAAsB,EAC/B,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,GACzC,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;;OASG;IACG,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,yBAAyB,CAAC;IAgErC;;OAEG;IACH,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAQjE;;;OAGG;IACG,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B5E,aAAa,IAAI,OAAO;IAIxB,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,yBAAyB,CAAC;IAIhD;;OAEG;IACH,QAAQ,IAAI;QACV,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB;IASD;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM;IAQ1D,OAAO,CAAC,WAAW;CAoBpB"}

package/dist/discovery/CapabilityDiscoveryEngine.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Capability Discovery Engine — main orchestrator.
+ * @module @framers/agentos/discovery/CapabilityDiscoveryEngine
+ *
+ * Coordinates the capability index, relationship graph, and context assembler
+ * to provide tiered, semantic capability discovery for AgentOS agents.
+ *
+ * Architecture:
+ *   User Message → CapabilityIndex.search() → CapabilityGraph.rerank()
+ *                → CapabilityContextAssembler.assemble() → CapabilityDiscoveryResult
+ *
+ * Performance targets:
+ *   - Initialize: ~3s (one-time embedding generation for ~100 capabilities)
+ *   - Per-turn discover(): ~50ms cold (embedding) / ~5ms warm (cache hit)
+ *   - Context tokens: ~1,850 (down from ~20,000 with static dumps)
+ */
+import { DEFAULT_DISCOVERY_CONFIG } from './types.js';
+import { CapabilityIndex } from './CapabilityIndex.js';
+import { CapabilityGraph } from './CapabilityGraph.js';
+import { CapabilityContextAssembler } from './CapabilityContextAssembler.js';
+// ============================================================================
+// CAPABILITY DISCOVERY ENGINE
+// ============================================================================
+export class CapabilityDiscoveryEngine {
+    constructor(embeddingManager, vectorStore, config) {
+        this.indexVersion = 0;
+        this.initialized = false;
+        this.config = { ...DEFAULT_DISCOVERY_CONFIG, ...config };
+        this.index = new CapabilityIndex(embeddingManager, vectorStore, this.config.collectionName, this.config.embeddingModelId);
+        this.graph = new CapabilityGraph();
+        this.assembler = new CapabilityContextAssembler(this.index.getEmbeddingStrategy());
+    }
+    // ============================================================================
+    // INITIALIZATION
+    // ============================================================================
+    /**
+     * Initialize the engine: build index + graph from all capability sources.
+     *
+     * @param sources - Tools, skills, extensions, channels, and manifest entries
+     * @param presetCoOccurrences - Co-occurrence data from agent presets
+     */
+    async initialize(sources, presetCoOccurrences) {
+        // 1. Build the vector index (normalizes sources + embeds + stores)
+        await this.index.buildIndex(sources);
+        // 2. Build the relationship graph
+        const allCapabilities = this.index.getAllCapabilities();
+        this.graph.buildGraph(allCapabilities, presetCoOccurrences);
+        this.indexVersion++;
+        this.initialized = true;
+    }
+    // ============================================================================
+    // DISCOVERY
+    // ============================================================================
+    /**
+     * Discover capabilities relevant to a user message.
+     *
+     * Flow:
+     * 1. Semantic search against capability embeddings
+     * 2. Graph-based re-ranking (boost related capabilities)
+     * 3. Token-budgeted tiered assembly
+     *
+     * Returns a CapabilityDiscoveryResult with Tier 0/1/2 context.
+     */
+    async discover(userMessage, options) {
+        if (!this.initialized) {
+            return this.emptyResult();
+        }
+        const queryConfig = { ...this.config, ...options?.config };
+        const embeddingStart = performance.now();
+        // 1. Semantic search
+        // Retrieve more candidates than needed for graph re-ranking to work effectively
+        const searchTopK = queryConfig.tier1TopK * 2;
+        const searchResults = await this.index.search(userMessage, searchTopK, {
+            kind: options?.kind,
+            category: options?.category,
+            onlyAvailable: options?.onlyAvailable,
+        });
+        const embeddingTimeMs = performance.now() - embeddingStart;
+        // 2. Graph-based re-ranking
+        let finalResults = searchResults;
+        let graphTraversalTimeMs = 0;
+        if (queryConfig.useGraphReranking && searchResults.length > 0) {
+            const graphStart = performance.now();
+            const reranked = this.graph.rerank(searchResults.map((r) => ({ id: r.descriptor.id, score: r.score })), queryConfig.graphBoostFactor);
+            // Map back to CapabilitySearchResult format
+            finalResults = reranked
+                .map((r) => {
+                const descriptor = this.index.getCapability(r.id);
+                if (!descriptor)
+                    return null;
+                return { descriptor, score: r.score };
+            })
+                .filter((r) => r !== null);
+            graphTraversalTimeMs = performance.now() - graphStart;
+        }
+        // 3. Build Tier 0 category summary
+        const tier0 = this.assembler.buildTier0(this.index.getAllCapabilities(), this.indexVersion);
+        // 4. Assemble tiered result with token budgets
+        return this.assembler.assemble(tier0, finalResults, queryConfig, {
+            embeddingTimeMs,
+            graphTraversalTimeMs,
+        });
+    }
+    // ============================================================================
+    // DETAIL ACCESS
+    // ============================================================================
+    /**
+     * Get full detail for a specific capability by ID.
+     */
+    getCapabilityDetail(id) {
+        return this.index.getCapability(id);
+    }
+    // ============================================================================
+    // INDEX MANAGEMENT
+    // ============================================================================
+    /**
+     * Refresh the index incrementally.
+     * Called when manifest files change or new capabilities are added at runtime.
+     */
+    async refreshIndex(sources) {
+        if (!sources)
+            return;
+        // Normalize and upsert new sources
+        const fullSources = {
+            tools: sources.tools,
+            skills: sources.skills,
+            extensions: sources.extensions,
+            channels: sources.channels,
+            manifests: sources.manifests,
+        };
+        const newDescriptors = this.index.normalizeSources(fullSources);
+        for (const desc of newDescriptors) {
+            await this.index.upsertCapability(desc);
+        }
+        // Rebuild graph with all capabilities
+        const allCapabilities = this.index.getAllCapabilities();
+        this.graph.buildGraph(allCapabilities);
+        this.indexVersion++;
+        this.assembler.invalidateCache();
+    }
+    // ============================================================================
+    // ACCESSORS
+    // ============================================================================
+    isInitialized() {
+        return this.initialized;
+    }
+    listCapabilityIds() {
+        return this.index.listIds();
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get index statistics.
+     */
+    getStats() {
+        return {
+            capabilityCount: this.index.size(),
+            graphNodes: this.graph.nodeCount(),
+            graphEdges: this.graph.edgeCount(),
+            indexVersion: this.indexVersion,
+        };
+    }
+    /**
+     * Render a discovery result into a string suitable for prompt injection.
+     */
+    renderForPrompt(result) {
+        return this.assembler.renderForPrompt(result);
+    }
+    // ============================================================================
+    // INTERNAL
+    // ============================================================================
+    emptyResult() {
+        return {
+            tier0: 'No capabilities indexed. Discovery engine not initialized.',
+            tier1: [],
+            tier2: [],
+            tokenEstimate: {
+                tier0Tokens: 10,
+                tier1Tokens: 0,
+                tier2Tokens: 0,
+                totalTokens: 10,
+            },
+            diagnostics: {
+                queryTimeMs: 0,
+                embeddingTimeMs: 0,
+                graphTraversalTimeMs: 0,
+                candidatesScanned: 0,
+                capabilitiesRetrieved: 0,
+            },
+        };
+    }
+}
+//# sourceMappingURL=CapabilityDiscoveryEngine.js.map

package/dist/discovery/CapabilityDiscoveryEngine.js.map

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

package/dist/discovery/CapabilityEmbeddingStrategy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Capability Embedding Strategy
+ * @module @framers/agentos/discovery/CapabilityEmbeddingStrategy
+ *
+ * Constructs the embedding text for each capability descriptor.
+ * The strategy captures WHEN a capability is useful (intent-oriented),
+ * not just what it does (description-only).
+ *
+ * Design informed by:
+ * - ToolLLM Neural API Retriever: embedding API docs (name, description, params)
+ *   achieves NDCG@5 of 84.9 on 16K+ APIs
+ * - MCP-RAG: decomposing tools into parameter-level embeddings improves matching
+ * - Context Rot (Chroma 2025): keeping embedded text concise maximizes retrieval precision
+ */
+import type { CapabilityDescriptor } from './types.js';
+/**
+ * Builds optimized embedding text for capability descriptors.
+ *
+ * The embedding text is structured to maximize semantic match with user intents:
+ * 1. Name/display name — captures exact-match queries
+ * 2. Description — core semantic content
+ * 3. Category + tags — captures categorical queries ("communication tool")
+ * 4. Parameter names — captures action queries ("I need to search for X")
+ * 5. Dependencies — captures composition queries ("tool that works with GitHub")
+ */
+export declare class CapabilityEmbeddingStrategy {
+    /**
+     * Build the text that will be embedded for a capability.
+     * Designed to be concise (typically 100-300 tokens) while capturing
+     * the key semantic signals for retrieval.
+     */
+    buildEmbeddingText(cap: CapabilityDescriptor): string;
+    /**
+     * Build a compact summary text for Tier 1 display.
+     * This is shown to the LLM when a capability is retrieved as relevant.
+     * Kept to ~30-50 tokens per capability.
+     */
+    buildCompactSummary(cap: CapabilityDescriptor): string;
+    /**
+     * Build the full detail text for Tier 2 injection.
+     * Includes full schema and/or SKILL.md content.
+     */
+    buildFullDetailText(cap: CapabilityDescriptor): string;
+}
+//# sourceMappingURL=CapabilityEmbeddingStrategy.d.ts.map

package/dist/discovery/CapabilityEmbeddingStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityEmbeddingStrategy.d.ts","sourceRoot":"","sources":["../../src/discovery/CapabilityEmbeddingStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMvD;;;;;;;;;GASG;AACH,qBAAa,2BAA2B;IACtC;;;;OAIG;IACH,kBAAkB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM;IA0CrD;;;;OAIG;IACH,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM;IAiCtD;;;OAGG;IACH,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM;CAkCvD"}