@agentick/core 0.0.1

package/dist/mcp/client.js

@@ -0,0 +1,138 @@
+/**
+ * MCP Client Service
+ *
+ * Wraps the official @modelcontextprotocol/sdk Client to manage connections
+ * to multiple MCP servers.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {} from "./types";
+import { Logger } from "../index";
+/**
+ * Wrapper around official MCP SDK Client
+ * Manages connections to multiple MCP servers
+ */
+export class MCPClient {
+    logger = Logger.for(this);
+    clients = new Map();
+    tools = new Map(); // refreshed on connect
+    /**
+     * Connect to an MCP server using the official SDK
+     */
+    async connect(config) {
+        const existing = this.getClient(config.serverName);
+        if (existing) {
+            return existing;
+        }
+        const client = new Client({
+            name: "@agentick/engine",
+            version: "1.0.0",
+        }, {
+        // Capabilities are optional - Client will work without explicit capabilities
+        // The SDK handles tool discovery automatically
+        });
+        // Create transport based on config
+        const transport = this.createTransport(config);
+        // Connect using SDK
+        await client.connect(transport);
+        // List and cache tools
+        await this.listTools(config.serverName);
+        client.onclose = () => {
+            this.disconnect(config.serverName);
+            this.logger.warn({ serverName: config.serverName }, "MCP client disconnected");
+        };
+        client.onerror = (error) => {
+            this.disconnect(config.serverName);
+            this.logger.error({ err: error, serverName: config.serverName }, "MCP client error");
+        };
+        this.clients.set(config.serverName, client);
+        return client;
+    }
+    /**
+     * Get an existing client connection
+     */
+    getClient(serverName) {
+        return this.clients.get(serverName);
+    }
+    /**
+     * List tools from an MCP server
+     */
+    async listTools(serverName) {
+        const tools = this.tools.get(serverName);
+        if (tools) {
+            return tools;
+        }
+        const client = await this.getClient(serverName);
+        if (!client) {
+            throw new Error(`MCP client not found for server name: ${serverName}`);
+        }
+        const toolsList = await client.listTools();
+        const mcpTools = toolsList.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description || "",
+            inputSchema: tool.inputSchema,
+        }));
+        this.tools.set(serverName, mcpTools);
+        return mcpTools;
+    }
+    /**
+     * Disconnect from an MCP server
+     */
+    async disconnect(serverName) {
+        this.clients.delete(serverName);
+        this.tools.delete(serverName);
+    }
+    /**
+     * Disconnect from all servers
+     */
+    async disconnectAll() {
+        const promises = Array.from(this.clients.keys()).map((name) => this.disconnect(name));
+        await Promise.all(promises);
+    }
+    /**
+     * Call a tool on an MCP server
+     */
+    async callTool(serverName, toolName, input) {
+        const client = this.clients.get(serverName);
+        if (!client) {
+            throw new Error(`MCP server "${serverName}" is not connected`);
+        }
+        // Use SDK's callTool method
+        const result = await client.callTool({
+            name: toolName,
+            arguments: input,
+        });
+        return result;
+    }
+    /**
+     * Create transport based on config
+     */
+    createTransport(config) {
+        switch (config.transport) {
+            case "stdio":
+                if (!config.connection.command) {
+                    throw new Error("Stdio transport requires command in connection config");
+                }
+                return new StdioClientTransport({
+                    command: config.connection.command,
+                    args: config.connection.args || [],
+                });
+            case "sse":
+                if (!config.connection.url) {
+                    throw new Error("SSE transport requires url in connection config");
+                }
+                return new SSEClientTransport(new URL(config.connection.url));
+            case "websocket":
+                // Use Streamable HTTP (modern replacement for WebSocket)
+                if (!config.connection.url) {
+                    throw new Error("Streamable HTTP transport requires url in connection config");
+                }
+                return new StreamableHTTPClientTransport(new URL(config.connection.url));
+            default:
+                throw new Error(`Unsupported MCP transport: ${config.transport}`);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/mcp/client.js.map

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

package/dist/mcp/component.d.ts

@@ -0,0 +1,95 @@
+/**
+ * MCP Tool Component
+ *
+ * A component that connects to an MCP server and registers its tools.
+ * Supports runtime configuration (auth tokens, etc.) and tool filtering.
+ */
+import React from "react";
+import type { EngineComponent } from "../component/component";
+import { MCPClient } from "./client";
+import type { MCPConfig, MCPServerConfig } from "./types";
+import type { JSX } from "../jsx/jsx-runtime";
+import type { ComponentBaseProps } from "../jsx/jsx-types";
+/**
+ * Props for MCPToolComponent
+ */
+export interface MCPToolComponentProps extends ComponentBaseProps, Partial<EngineComponent> {
+    /**
+     * MCP server name (used as identifier)
+     */
+    server: string;
+    /**
+     * Base MCP server configuration (Cursor-style or full MCPConfig)
+     * This is the static configuration defined at component creation time.
+     */
+    config: MCPServerConfig | MCPConfig;
+    /**
+     * Runtime configuration (merged with base config).
+     * Useful for user-specific auth tokens, dynamic URLs, etc.
+     * Can be passed from user context, execution input, etc.
+     */
+    runtimeConfig?: Partial<MCPConfig>;
+    /**
+     * List of tool names to exclude from registration.
+     * If provided, only tools NOT in this list will be registered.
+     */
+    exclude?: string[];
+    /**
+     * List of tool names to include (whitelist).
+     * If provided, only tools in this list will be registered.
+     * Takes precedence over exclude.
+     */
+    include?: string[];
+    /**
+     * Optional MCPClient instance (for sharing connections across components).
+     * If not provided, creates a new instance.
+     */
+    mcpClient?: MCPClient;
+    /**
+     * Optional prefix for tool names (to avoid conflicts).
+     * Example: prefix="mcp_" → tool "read_file" becomes "mcp_read_file"
+     */
+    toolPrefix?: string;
+}
+/**
+ * MCPToolComponent connects to an MCP server and registers its tools into the context.
+ *
+ * Usage:
+ * ```tsx
+ * // Simple usage with Cursor-style config
+ * <MCPToolComponent
+ *   server="postgres"
+ *   config={{
+ *     command: 'npx',
+ *     args: ['-y', '@modelcontextprotocol/server-postgres', 'postgresql://localhost/mydb'],
+ *   }}
+ * />
+ *
+ * // With runtime config (auth token from user context)
+ * <MCPToolComponent
+ *   server="api-server"
+ *   config={{
+ *     transport: 'sse',
+ *     connection: { url: 'https://api.example.com/mcp' },
+ *   }}
+ *   runtimeConfig={{
+ *     auth: { type: 'bearer', token: userContext.apiToken },
+ *   }}
+ *   exclude={['dangerous_tool']}
+ * />
+ *
+ * // With tool filtering
+ * <MCPToolComponent
+ *   server="filesystem"
+ *   config={{ command: 'npx', args: [...] }}
+ *   include={['read_file', 'list_directory']} // Only these tools
+ *   toolPrefix="fs_"
+ * />
+ * ```
+ */
+export declare function MCPToolComponent(props: MCPToolComponentProps): React.ReactElement | null;
+/**
+ * Factory function for creating MCPToolComponent in JSX
+ */
+export declare function MCPTool(props: MCPToolComponentProps): JSX.Element;
+//# sourceMappingURL=component.d.ts.map

package/dist/mcp/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/mcp/component.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAA4B,MAAM,OAAO,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AA4C3D;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB,EAAE,OAAO,CAAC,eAAe,CAAC;IACzF;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IAEpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA4GxF;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAEjE"}

package/dist/mcp/component.js

@@ -0,0 +1,185 @@
+/**
+ * MCP Tool Component
+ *
+ * A component that connects to an MCP server and registers its tools.
+ * Supports runtime configuration (auth tokens, etc.) and tool filtering.
+ */
+import React, { useEffect, useRef } from "react";
+import { MCPClient } from "./client";
+import { MCPService } from "./service";
+import { useCom } from "../hooks";
+/**
+ * Normalizes Cursor-style config to full MCPConfig
+ */
+function normalizeMCPConfig(serverName, config) {
+    // If it's already a full MCPConfig, return as-is
+    if ("transport" in config && "connection" in config) {
+        return config;
+    }
+    // Convert Cursor-style config (assumes stdio transport)
+    const mcpServerConfig = config;
+    return {
+        serverName,
+        transport: "stdio",
+        connection: {
+            command: mcpServerConfig.command,
+            args: mcpServerConfig.args || [],
+            env: mcpServerConfig.env,
+        },
+    };
+}
+/**
+ * Merges base config with runtime config (runtime overrides base)
+ */
+function mergeMCPConfig(base, runtime) {
+    if (!runtime) {
+        return base;
+    }
+    return {
+        ...base,
+        ...runtime,
+        connection: {
+            ...base.connection,
+            ...runtime.connection,
+        },
+        auth: runtime.auth || base.auth,
+    };
+}
+/**
+ * MCPToolComponent connects to an MCP server and registers its tools into the context.
+ *
+ * Usage:
+ * ```tsx
+ * // Simple usage with Cursor-style config
+ * <MCPToolComponent
+ *   server="postgres"
+ *   config={{
+ *     command: 'npx',
+ *     args: ['-y', '@modelcontextprotocol/server-postgres', 'postgresql://localhost/mydb'],
+ *   }}
+ * />
+ *
+ * // With runtime config (auth token from user context)
+ * <MCPToolComponent
+ *   server="api-server"
+ *   config={{
+ *     transport: 'sse',
+ *     connection: { url: 'https://api.example.com/mcp' },
+ *   }}
+ *   runtimeConfig={{
+ *     auth: { type: 'bearer', token: userContext.apiToken },
+ *   }}
+ *   exclude={['dangerous_tool']}
+ * />
+ *
+ * // With tool filtering
+ * <MCPToolComponent
+ *   server="filesystem"
+ *   config={{ command: 'npx', args: [...] }}
+ *   include={['read_file', 'list_directory']} // Only these tools
+ *   toolPrefix="fs_"
+ * />
+ * ```
+ */
+export function MCPToolComponent(props) {
+    const ctx = useCom();
+    // Refs for managing state across renders
+    const mcpClientRef = useRef(null);
+    const mcpServiceRef = useRef(null);
+    const registeredToolNamesRef = useRef([]);
+    const hasInitializedRef = useRef(false);
+    // Initialize refs on first render
+    if (!mcpClientRef.current) {
+        mcpClientRef.current = props.mcpClient || new MCPClient();
+        mcpServiceRef.current = new MCPService(mcpClientRef.current);
+    }
+    // Mount/unmount effect
+    useEffect(() => {
+        if (hasInitializedRef.current) {
+            return;
+        }
+        hasInitializedRef.current = true;
+        const baseConfig = normalizeMCPConfig(props.server, props.config);
+        const effectiveConfig = mergeMCPConfig(baseConfig, props.runtimeConfig);
+        const mcpClient = mcpClientRef.current;
+        const mcpService = mcpServiceRef.current;
+        const initMCP = async () => {
+            try {
+                // Discover tools from MCP server
+                const tools = await mcpService.connectAndDiscover(effectiveConfig);
+                // Filter tools based on include/exclude
+                let filteredTools = tools;
+                if (props.include && props.include.length > 0) {
+                    // Whitelist: only include specified tools
+                    filteredTools = tools.filter((t) => props.include.includes(t.name));
+                }
+                else if (props.exclude && props.exclude.length > 0) {
+                    // Blacklist: exclude specified tools
+                    filteredTools = tools.filter((t) => !props.exclude.includes(t.name));
+                }
+                // Register each filtered tool
+                for (const mcpToolDef of filteredTools) {
+                    // Apply tool prefix if specified
+                    const toolName = props.toolPrefix
+                        ? `${props.toolPrefix}${mcpToolDef.name}`
+                        : mcpToolDef.name;
+                    // Create tool with prefixed name
+                    const toolDef = {
+                        ...mcpToolDef,
+                        name: toolName,
+                    };
+                    mcpService.registerMCPTool(effectiveConfig, toolDef, ctx);
+                    registeredToolNamesRef.current.push(toolName);
+                }
+                // Call onMount callback if provided
+                if (props.onMount) {
+                    await props.onMount(ctx);
+                }
+            }
+            catch (error) {
+                console.error(`Failed to initialize MCP server "${props.server}":`, error);
+                // Call onMount even on error (for error handling)
+                if (props.onMount) {
+                    await props.onMount(ctx);
+                }
+            }
+        };
+        initMCP();
+        // Cleanup on unmount
+        return () => {
+            // Remove registered tools
+            for (const toolName of registeredToolNamesRef.current) {
+                ctx.removeTool(toolName);
+            }
+            registeredToolNamesRef.current = [];
+            // Disconnect MCP client if we created it (not shared)
+            if (!props.mcpClient && mcpClient) {
+                mcpClient.disconnect(baseConfig.serverName);
+            }
+            // Call onUnmount callback if provided
+            if (props.onUnmount) {
+                props.onUnmount(ctx);
+            }
+        };
+    }, [
+        ctx,
+        props.server,
+        props.config,
+        props.runtimeConfig,
+        props.include,
+        props.exclude,
+        props.toolPrefix,
+        props.mcpClient,
+        props.onMount,
+        props.onUnmount,
+    ]);
+    // MCP components don't render anything
+    return null;
+}
+/**
+ * Factory function for creating MCPToolComponent in JSX
+ */
+export function MCPTool(props) {
+    return React.createElement(MCPToolComponent, props);
+}
+//# sourceMappingURL=component.js.map

package/dist/mcp/component.js.map

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

package/dist/mcp/create-mcp-tool.d.ts

@@ -0,0 +1,191 @@
+/**
+ * MCP Tool Creation
+ *
+ * Factory functions for creating MCP tools that work like regular tools:
+ * - Pass to models: engine.execute({ tools: [tool] })
+ * - Run directly: await tool.run(input)
+ * - Use in JSX: <MyMCPTool />
+ *
+ * Three main entry points:
+ * 1. createMCPTool() - Component factory with discovery, for JSX usage
+ * 2. createMCPToolFromDefinition() - Direct creation from known definition
+ * 3. discoverMCPTools() - Batch discovery of all tools on a server
+ */
+import React from "react";
+import { MCPClient } from "./client";
+import type { MCPConfig, MCPServerConfig, MCPToolDefinition } from "./types";
+import type { ExecutableTool } from "../tool/tool";
+import { type MCPToolComponentProps } from "./component";
+/**
+ * Normalizes Cursor-style config to full MCPConfig.
+ *
+ * Cursor-style: { command: 'npx', args: [...], env: {...} }
+ * Full MCPConfig: { serverName, transport, connection: {...} }
+ */
+export declare function normalizeMCPConfig(serverName: string, config: MCPServerConfig | MCPConfig): MCPConfig;
+/**
+ * Merges base config with runtime overrides.
+ * Runtime values take precedence.
+ */
+export declare function mergeMCPConfig(base: MCPConfig, runtime?: Partial<MCPConfig>): MCPConfig;
+/**
+ * Options for createMCPTool().
+ * Extends MCPToolComponentProps but adds `toolName` for single-tool selection.
+ */
+export interface CreateMCPToolOptions extends Omit<MCPToolComponentProps, "include" | "exclude" | "mcpClient"> {
+    /**
+     * Specific tool name to discover.
+     * If omitted, registers first tool found.
+     */
+    toolName?: string;
+    /**
+     * Shared MCPClient instance.
+     * If not provided, creates a new one.
+     */
+    client?: MCPClient;
+}
+/**
+ * Creates an MCP tool component that discovers and registers on mount.
+ *
+ * Use this when you need:
+ * - Dynamic discovery at runtime
+ * - Runtime configuration (auth tokens)
+ * - JSX-based tool declaration
+ *
+ * @example Basic usage
+ * ```tsx
+ * const ReadFile = createMCPTool({
+ *   server: 'filesystem',
+ *   config: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/path'] },
+ *   toolName: 'read_file',
+ * });
+ *
+ * function MyAgent() {
+ *   return (
+ *     <>
+ *       <ReadFile />
+ *       <Model />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With runtime auth
+ * ```tsx
+ * const APITool = createMCPTool({
+ *   server: 'api',
+ *   config: { transport: 'sse', connection: { url: 'https://api.example.com/mcp' } },
+ *   toolName: 'query',
+ * });
+ *
+ * // Runtime config from user context
+ * <APITool runtimeConfig={{ auth: { type: 'bearer', token: userToken } }} />
+ * ```
+ */
+export declare function createMCPTool(options: CreateMCPToolOptions): React.FC<Partial<CreateMCPToolOptions>>;
+/**
+ * Options for createMCPToolFromDefinition().
+ */
+export interface CreateMCPToolFromDefinitionOptions {
+    /** Active MCPClient with server connection. */
+    client: MCPClient;
+    /** MCP server configuration. */
+    config: MCPConfig;
+    /** Tool definition from discovery. */
+    definition: MCPToolDefinition;
+    /** Override tool name. */
+    name?: string;
+}
+/**
+ * Creates an ExecutableTool from an MCP tool definition.
+ *
+ * Use this when you already have:
+ * - An active MCPClient connection
+ * - The tool definition from discovery
+ *
+ * @example
+ * ```typescript
+ * const client = new MCPClient();
+ * const service = new MCPService(client);
+ *
+ * // Connect and discover
+ * const config: MCPConfig = {
+ *   serverName: 'filesystem',
+ *   transport: 'stdio',
+ *   connection: { command: 'npx', args: [...] }
+ * };
+ * const tools = await service.connectAndDiscover(config);
+ *
+ * // Create specific tool
+ * const readFile = createMCPToolFromDefinition({
+ *   client,
+ *   config,
+ *   definition: tools.find(t => t.name === 'read_file')!,
+ * });
+ *
+ * // Pass to model
+ * engine.execute({ tools: [readFile] });
+ *
+ * // Or run directly
+ * const result = await readFile.run({ path: '/file.txt' });
+ * ```
+ */
+export declare function createMCPToolFromDefinition(options: CreateMCPToolFromDefinitionOptions): ExecutableTool;
+/**
+ * Options for discoverMCPTools().
+ */
+export interface DiscoverMCPToolsOptions {
+    /** MCP server configuration. */
+    config: MCPConfig;
+    /**
+     * Shared MCPClient.
+     * If not provided, creates a new one.
+     */
+    client?: MCPClient;
+    /** Prefix for all tool names. */
+    toolPrefix?: string;
+    /**
+     * Whitelist: only include these tools.
+     * Takes precedence over exclude.
+     */
+    include?: string[];
+    /** Blacklist: exclude these tools. */
+    exclude?: string[];
+}
+/**
+ * Discovers all tools from an MCP server and creates ExecutableTools.
+ *
+ * Use this for batch tool registration or when you need all tools
+ * from a server without JSX.
+ *
+ * @example Basic discovery
+ * ```typescript
+ * const tools = await discoverMCPTools({
+ *   config: {
+ *     serverName: 'filesystem',
+ *     transport: 'stdio',
+ *     connection: { command: 'npx', args: [...] }
+ *   },
+ * });
+ *
+ * // Pass all to model
+ * engine.execute({ tools });
+ * ```
+ *
+ * @example With filtering
+ * ```typescript
+ * const tools = await discoverMCPTools({
+ *   config,
+ *   include: ['read_file', 'list_directory'], // Only these
+ *   toolPrefix: 'fs_',
+ * });
+ * ```
+ *
+ * @example Register with COM
+ * ```typescript
+ * const tools = await discoverMCPTools({ config });
+ * tools.forEach(tool => ctx.addTool(tool));
+ * ```
+ */
+export declare function discoverMCPTools(options: DiscoverMCPToolsOptions): Promise<ExecutableTool[]>;
+//# sourceMappingURL=create-mcp-tool.d.ts.map

package/dist/mcp/create-mcp-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-mcp-tool.d.ts","sourceRoot":"","sources":["../../src/mcp/create-mcp-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAM3E;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,SAAS,CAiBX;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAYvF;AAMD;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAChD,qBAAqB,EACrB,SAAS,GAAG,SAAS,GAAG,WAAW,CACpC;IACC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,GAC5B,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CA0BzC;AAMD;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,+CAA+C;IAC/C,MAAM,EAAE,SAAS,CAAC;IAElB,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;IAElB,sCAAsC;IACtC,UAAU,EAAE,iBAAiB,CAAC;IAE9B,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAC1C,cAAc,CAWhB;AAMD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,cAAc,EAAE,CAAC,CA0B3B"}