@1mcp/agent 0.29.2 → 0.30.0-beta1

package/build/core/capabilities/schemaCache.js

@@ -0,0 +1,248 @@
+import logger, { debugIf } from '../../logger/logger.js';
+/**
+ * SchemaCache provides LRU caching for tool schemas with optional TTL and request coalescing.
+ *
+ * This cache reduces redundant upstream server calls by storing loaded tool schemas
+ * and coalescing parallel requests for the same tool.
+ *
+ * @example
+ * ```typescript
+ * const cache = new SchemaCache({ maxEntries: 1000, ttlMs: 3600000 });
+ *
+ * // Load tool schema (with coalescing for parallel calls)
+ * const tool = await cache.getOrLoad('filesystem', 'read_file', async () => {
+ *   return await fetchSchemaFromServer('filesystem', 'read_file');
+ * });
+ * ```
+ */
+export class SchemaCache {
+    cache = new Map();
+    inflightRequests = new Map();
+    config;
+    stats = {
+        hits: 0,
+        misses: 0,
+        coalesced: 0,
+        evictions: 0,
+        get hitRate() {
+            const total = this.hits + this.misses;
+            return total > 0 ? (this.hits / total) * 100 : 0;
+        },
+    };
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Generate cache key from server and tool name
+     */
+    getCacheKey(server, toolName) {
+        return `${server}:${toolName}`;
+    }
+    /**
+     * Check if a cache entry has expired (TTL)
+     */
+    isExpired(entry) {
+        if (!this.config.ttlMs) {
+            return false;
+        }
+        const now = Date.now();
+        const age = now - entry.timestamp;
+        return age > this.config.ttlMs;
+    }
+    /**
+     * Evict oldest entry when cache is full (FIFO eviction by insertion time)
+     * Note: This is not true LRU - for that we'd need to track access order
+     */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTimestamp = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldestTimestamp) {
+                oldestTimestamp = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            this.stats.evictions++;
+            debugIf(() => ({ message: `Evicted oldest cache entry: ${oldestKey}` }));
+        }
+    }
+    /**
+     * Get tool schema from cache or load it using the provided loader function
+     * Implements request coalescing for parallel requests to the same tool
+     *
+     * @param server - Server name
+     * @param toolName - Tool name
+     * @param loader - Async function to load the tool schema from upstream server
+     * @returns Promise resolving to the Tool schema
+     */
+    async getOrLoad(server, toolName, loader) {
+        const cacheKey = this.getCacheKey(server, toolName);
+        // Check cache first
+        const cached = this.cache.get(cacheKey);
+        if (cached && !this.isExpired(cached)) {
+            this.stats.hits++;
+            debugIf(() => ({ message: `Cache hit: ${cacheKey}` }));
+            return cached.tool;
+        }
+        // Remove expired entry if exists
+        if (cached && this.isExpired(cached)) {
+            this.cache.delete(cacheKey);
+            debugIf(() => ({ message: `Cache entry expired: ${cacheKey}` }));
+        }
+        // Check for in-flight request (coalescing)
+        const inflight = this.inflightRequests.get(cacheKey);
+        if (inflight) {
+            this.stats.coalesced++;
+            debugIf(() => ({ message: `Coalesced request for: ${cacheKey}` }));
+            return inflight;
+        }
+        // Create new request
+        this.stats.misses++;
+        const promise = loader(server, toolName)
+            .then((tool) => {
+            // Store in cache
+            if (this.cache.size >= this.config.maxEntries) {
+                this.evictOldest();
+            }
+            this.cache.set(cacheKey, {
+                tool,
+                timestamp: Date.now(),
+            });
+            debugIf(() => ({ message: `Loaded and cached: ${cacheKey}` }));
+            return tool;
+        })
+            .finally(() => {
+            // Clean up in-flight map
+            this.inflightRequests.delete(cacheKey);
+        });
+        this.inflightRequests.set(cacheKey, promise);
+        return promise;
+    }
+    /**
+     * Check if a tool schema is currently cached (and not expired)
+     */
+    has(server, toolName) {
+        const cacheKey = this.getCacheKey(server, toolName);
+        const cached = this.cache.get(cacheKey);
+        return cached !== undefined && !this.isExpired(cached);
+    }
+    /**
+     * Get cached tool schema without loading (returns null if not cached)
+     */
+    getIfCached(server, toolName) {
+        const cacheKey = this.getCacheKey(server, toolName);
+        const cached = this.cache.get(cacheKey);
+        if (!cached) {
+            return null;
+        }
+        if (this.isExpired(cached)) {
+            this.cache.delete(cacheKey);
+            return null;
+        }
+        return cached.tool;
+    }
+    /**
+     * Manually add a tool schema to the cache
+     */
+    set(server, toolName, tool) {
+        const cacheKey = this.getCacheKey(server, toolName);
+        if (this.cache.size >= this.config.maxEntries) {
+            this.evictOldest();
+        }
+        this.cache.set(cacheKey, {
+            tool,
+            timestamp: Date.now(),
+        });
+        debugIf(() => ({ message: `Manually cached: ${cacheKey}` }));
+    }
+    /**
+     * Remove a tool schema from the cache
+     */
+    delete(server, toolName) {
+        const cacheKey = this.getCacheKey(server, toolName);
+        return this.cache.delete(cacheKey);
+    }
+    /**
+     * Clear all cached schemas
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.inflightRequests.clear();
+        logger.info(`Cleared ${size} tool schemas from cache`);
+    }
+    /**
+     * Get current cache statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get current cache size
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Get all cached tool identifiers
+     */
+    getCachedTools() {
+        const now = Date.now();
+        const tools = [];
+        for (const [cacheKey, entry] of this.cache.entries()) {
+            // Skip expired entries
+            if (this.config.ttlMs && now - entry.timestamp > this.config.ttlMs) {
+                continue;
+            }
+            const [server, toolName] = cacheKey.split(':');
+            tools.push({ server, toolName });
+        }
+        return tools;
+    }
+    /**
+     * Reset statistics counters
+     */
+    resetStats() {
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+        this.stats.coalesced = 0;
+        this.stats.evictions = 0;
+    }
+    /**
+     * Log current cache statistics (for monitoring and observability)
+     * @param forceLog - Force logging even if debug mode is off
+     */
+    logStats(forceLog = false) {
+        const stats = this.getStats();
+        const message = `SchemaCache stats: size=${this.cache.size}/${this.config.maxEntries}, hits=${stats.hits}, misses=${stats.misses}, hitRate=${stats.hitRate.toFixed(1)}%, coalesced=${stats.coalesced}, evictions=${stats.evictions}`;
+        if (forceLog) {
+            logger.info(message);
+        }
+        else {
+            debugIf(message);
+        }
+    }
+    /**
+     * Preload tool schemas in batch
+     * @returns Object with loaded count and array of failures
+     */
+    async preload(tools, loader) {
+        debugIf(() => ({ message: `Preloading ${tools.length} tool schemas` }));
+        const failed = [];
+        // Load in parallel for efficiency
+        await Promise.all(tools.map(({ server, toolName }) => this.getOrLoad(server, toolName, loader).catch((error) => {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.warn(`Failed to preload tool schema ${server}:${toolName}: ${errorMessage}`);
+            failed.push({ server, toolName, error: errorMessage });
+        })));
+        const loaded = tools.length - failed.length;
+        if (failed.length > 0) {
+            logger.warn(`Preload completed with ${failed.length} failures out of ${tools.length} tools`, { failed });
+        }
+        logger.info(`Preloaded ${loaded} tool schemas, cache size: ${this.cache.size}`);
+        return { loaded, failed };
+    }
+}
+//# sourceMappingURL=schemaCache.js.map

package/build/core/capabilities/schemaCache.js.map

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

package/build/core/capabilities/schemas/metaToolSchemas.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+/**
+ * Shared Zod schemas for meta-tool inputs and outputs
+ * Used by both lazyTools.ts and metaToolProvider.ts
+ */
+/**
+ * Input schemas
+ */
+export declare const ToolListInputSchema: z.ZodObject<{
+    server: z.ZodOptional<z.ZodString>;
+    pattern: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ToolSchemaInputSchema: z.ZodObject<{
+    server: z.ZodString;
+    toolName: z.ZodString;
+}, z.core.$strip>;
+export declare const ToolInvokeInputSchema: z.ZodObject<{
+    server: z.ZodString;
+    toolName: z.ZodString;
+    args: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$strip>;
+/**
+ * Output schemas
+ */
+export declare const ToolMetadataSchema: z.ZodObject<{
+    name: z.ZodString;
+    server: z.ZodString;
+    description: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const ToolListOutputSchema: z.ZodObject<{
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        server: z.ZodString;
+        description: z.ZodString;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    servers: z.ZodArray<z.ZodString>;
+    hasMore: z.ZodBoolean;
+    nextCursor: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            not_found: "not_found";
+            validation: "validation";
+            upstream: "upstream";
+            internal: "internal";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ToolSchemaOutputSchema: z.ZodObject<{
+    schema: z.ZodObject<{}, z.core.$loose>;
+    fromCache: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            not_found: "not_found";
+            validation: "validation";
+            upstream: "upstream";
+            internal: "internal";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ToolInvokeOutputSchema: z.ZodObject<{
+    result: z.ZodObject<{}, z.core.$loose>;
+    server: z.ZodString;
+    tool: z.ZodString;
+    error: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            not_found: "not_found";
+            validation: "validation";
+            upstream: "upstream";
+            internal: "internal";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Type exports
+ */
+export type ToolListInput = z.infer<typeof ToolListInputSchema>;
+export type ToolSchemaInput = z.infer<typeof ToolSchemaInputSchema>;
+export type ToolInvokeInput = z.infer<typeof ToolInvokeInputSchema>;
+export type ToolMetadata = z.infer<typeof ToolMetadataSchema>;
+export type ToolListOutput = z.infer<typeof ToolListOutputSchema>;
+export type ToolSchemaOutput = z.infer<typeof ToolSchemaOutputSchema>;
+export type ToolInvokeOutput = z.infer<typeof ToolInvokeOutputSchema>;
+//# sourceMappingURL=metaToolSchemas.d.ts.map

package/build/core/capabilities/schemas/metaToolSchemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metaToolSchemas.d.ts","sourceRoot":"","sources":["../../../../src/core/capabilities/schemas/metaToolSchemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AAEH;;GAEG;AAEH,eAAO,MAAM,mBAAmB;;;;;;iBAM9B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAC;AAEH;;GAEG;AAEH,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;iBAY/B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;iBASjC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;iBAUjC,CAAC;AAEH;;GAEG;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/build/core/capabilities/schemas/metaToolSchemas.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+/**
+ * Shared Zod schemas for meta-tool inputs and outputs
+ * Used by both lazyTools.ts and metaToolProvider.ts
+ */
+/**
+ * Input schemas
+ */
+export const ToolListInputSchema = z.object({
+    server: z.string().optional(),
+    pattern: z.string().optional(),
+    tag: z.string().optional(),
+    limit: z.number().optional(),
+    cursor: z.string().optional(),
+});
+export const ToolSchemaInputSchema = z.object({
+    server: z.string(),
+    toolName: z.string(),
+});
+export const ToolInvokeInputSchema = z.object({
+    server: z.string(),
+    toolName: z.string(),
+    args: z.object({}).loose(),
+});
+/**
+ * Output schemas
+ */
+export const ToolMetadataSchema = z.object({
+    name: z.string(),
+    server: z.string(),
+    description: z.string(),
+    tags: z.array(z.string()).optional(),
+});
+export const ToolListOutputSchema = z.object({
+    tools: z.array(ToolMetadataSchema),
+    totalCount: z.number(),
+    servers: z.array(z.string()),
+    hasMore: z.boolean(),
+    nextCursor: z.string().optional(),
+    error: z
+        .object({
+        type: z.enum(['validation', 'upstream', 'not_found', 'internal']),
+        message: z.string(),
+    })
+        .optional(),
+});
+export const ToolSchemaOutputSchema = z.object({
+    schema: z.object({}).loose(),
+    fromCache: z.boolean().optional(),
+    error: z
+        .object({
+        type: z.enum(['validation', 'upstream', 'not_found', 'internal']),
+        message: z.string(),
+    })
+        .optional(),
+});
+export const ToolInvokeOutputSchema = z.object({
+    result: z.object({}).loose(),
+    server: z.string(),
+    tool: z.string(),
+    error: z
+        .object({
+        type: z.enum(['validation', 'upstream', 'not_found', 'internal']),
+        message: z.string(),
+    })
+        .optional(),
+});
+//# sourceMappingURL=metaToolSchemas.js.map

package/build/core/capabilities/schemas/metaToolSchemas.js.map

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

package/build/core/capabilities/toolRegistry.d.ts

@@ -0,0 +1,140 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Lightweight tool metadata (name + description only, no inputSchema)
+ */
+export interface ToolMetadata {
+    name: string;
+    server: string;
+    description: string;
+    tags?: string[];
+}
+/**
+ * Options for listing tools from registry
+ */
+export interface ListToolsOptions {
+    server?: string;
+    pattern?: string;
+    tag?: string;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Result of listing tools from registry
+ */
+export interface ListToolsResult {
+    tools: ToolMetadata[];
+    totalCount: number;
+    hasMore: boolean;
+    nextCursor?: string;
+}
+/**
+ * ToolRegistry maintains a lightweight registry of tool metadata without input schemas.
+ *
+ * This registry is used in meta-tool mode to provide fast tool discovery without
+ * loading complex input schemas. Tools are identified by separate server and toolName
+ * parameters for explicit routing.
+ *
+ * @example
+ * ```typescript
+ * const registry = ToolRegistry.build(connections);
+ *
+ * // List all tools
+ * const result = registry.listTools({});
+ *
+ * // Filter by server
+ * const filesystemTools = registry.listTools({ server: 'filesystem' });
+ *
+ * // Filter by pattern
+ * const readTools = registry.listTools({ pattern: '*read*' });
+ * ```
+ */
+export declare class ToolRegistry {
+    private tools;
+    private constructor();
+    /**
+     * Build a ToolRegistry from a map of server names to their tools
+     *
+     * @param toolsByServer - Map of server name to array of tools from that server
+     * @param serverTags - Optional map of server name to tags
+     * @returns A new ToolRegistry instance
+     */
+    static fromToolsMap(toolsByServer: Map<string, Tool[]>, serverTags?: Map<string, string[]>): ToolRegistry;
+    /**
+     * Build a ToolRegistry from tools already loaded from servers
+     * This is used when tools are fetched externally (e.g., from CapabilityAggregator)
+     *
+     * @param toolsWithServer - Array of tools with their server names
+     * @returns A new ToolRegistry instance
+     */
+    static fromToolsWithServer(toolsWithServer: Array<{
+        tool: Tool;
+        server: string;
+        tags?: string[];
+    }>): ToolRegistry;
+    /**
+     * Create an empty ToolRegistry
+     */
+    static empty(): ToolRegistry;
+    /**
+     * List tools with optional filtering and pagination
+     *
+     * @param options - Filtering and pagination options
+     * @returns Filtered and paginated tool list
+     */
+    listTools(options?: ListToolsOptions): ListToolsResult;
+    /**
+     * Get all unique server names in the registry
+     */
+    getServers(): string[];
+    /**
+     * Get all unique tags in the registry
+     */
+    getTags(): string[];
+    /**
+     * Get tool count by server
+     */
+    getToolCountByServer(): Record<string, number>;
+    /**
+     * Check if a tool exists in the registry
+     */
+    hasTool(server: string, toolName: string): boolean;
+    /**
+     * Get tool metadata without inputSchema
+     */
+    getTool(server: string, toolName: string): ToolMetadata | undefined;
+    /**
+     * Get total number of tools in registry
+     */
+    size(): number;
+    /**
+     * Get all tools in the registry
+     */
+    getAllTools(): ToolMetadata[];
+    /**
+     * Group tools by server
+     */
+    groupByServer(): Record<string, ToolMetadata[]>;
+    /**
+     * Filter the registry to only include tools from specific servers
+     *
+     * @param serverNames - Set of server names to include
+     * @returns A new ToolRegistry instance with filtered tools
+     */
+    filterByServers(serverNames: Set<string>): ToolRegistry;
+    /**
+     * Encode pagination cursor to base64 string
+     */
+    private static encodeCursor;
+    /**
+     * Decode pagination cursor from base64 string
+     */
+    private static decodeCursor;
+    /**
+     * Get tools grouped by category (based on server tags)
+     */
+    categorizeByTags(): Record<string, {
+        name: string;
+        tools: ToolMetadata[];
+    }>;
+}
+//# sourceMappingURL=toolRegistry.d.ts.map

package/build/core/capabilities/toolRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRegistry.d.ts","sourceRoot":"","sources":["../../../src/core/capabilities/toolRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAI1D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAYD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAsB;IAEnC,OAAO;IAIP;;;;;;OAMG;WACW,YAAY,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY;IAwBhH;;;;;;OAMG;WACW,mBAAmB,CAC/B,eAAe,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GACtE,YAAY;IAYf;;OAEG;WACW,KAAK,IAAI,YAAY;IAInC;;;;;OAKG;IACI,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe;IAgFjE;;OAEG;IACI,UAAU,IAAI,MAAM,EAAE;IAK7B;;OAEG;IACI,OAAO,IAAI,MAAM,EAAE;IAY1B;;OAEG;IACI,oBAAoB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAUrD;;OAEG;IACI,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzD;;OAEG;IACI,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI1E;;OAEG;IACI,IAAI,IAAI,MAAM;IAIrB;;OAEG;IACI,WAAW,IAAI,YAAY,EAAE;IAIpC;;OAEG;IACI,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAatD;;;;;OAKG;IACI,eAAe,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,YAAY;IAK9D;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAK3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAU3B;;OAEG;IACI,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;CA4BnF"}