wuying-agentbay-sdk 0.5.1 → 0.7.0

package/dist/index.d.mts

@@ -305,6 +305,7 @@ declare class CreateMcpSessionRequest extends $dara.Model {
     externalUserId?: string;
     imageId?: string;
     labels?: string;
+    mcpPolicyId?: string;
     persistenceDataList?: CreateMcpSessionRequestPersistenceDataList[];
     sessionId?: string;
     vpcResource?: boolean;
@@ -326,6 +327,7 @@ declare class CreateMcpSessionShrinkRequest extends $dara.Model {
     externalUserId?: string;
     imageId?: string;
     labels?: string;
+    mcpPolicyId?: string;
     persistenceDataListShrink?: string;
     sessionId?: string;
     vpcResource?: boolean;
@@ -704,6 +706,9 @@ declare class InitBrowserRequest extends $dara.Model {
     authorization?: string;
     persistentPath?: string;
     sessionId?: string;
+    browserOption?: {
+        [key: string]: any;
+    };
     static names(): {
         [key: string]: string;
     };
@@ -1153,6 +1158,268 @@ declare class SyncContextResponse extends $dara.Model {
     });
 }
 
+declare class DeleteContextFileRequest extends $dara.Model {
+    authorization?: string;
+    contextId?: string;
+    filePath?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class DeleteContextFileResponseBody extends $dara.Model {
+    code?: string;
+    httpStatusCode?: number;
+    message?: string;
+    requestId?: string;
+    success?: boolean;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class DeleteContextFileResponse extends $dara.Model {
+    headers?: {
+        [key: string]: string;
+    };
+    statusCode?: number;
+    body?: DeleteContextFileResponseBody;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class DescribeContextFilesRequest extends $dara.Model {
+    authorization?: string;
+    pageNumber?: number;
+    pageSize?: number;
+    parentFolderPath?: string;
+    contextId?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class DescribeContextFilesResponseBodyData extends $dara.Model {
+    fileId?: string;
+    fileName?: string;
+    filePath?: string;
+    fileType?: string;
+    gmtCreate?: string;
+    gmtModified?: string;
+    size?: number;
+    status?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+declare class DescribeContextFilesResponseBody extends $dara.Model {
+    code?: string;
+    count?: number;
+    data?: DescribeContextFilesResponseBodyData[];
+    httpStatusCode?: number;
+    message?: string;
+    requestId?: string;
+    success?: boolean;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class DescribeContextFilesResponse extends $dara.Model {
+    headers?: {
+        [key: string]: string;
+    };
+    statusCode?: number;
+    body?: DescribeContextFilesResponseBody;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class GetContextFileDownloadUrlRequest extends $dara.Model {
+    authorization?: string;
+    contextId?: string;
+    filePath?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class GetContextFileDownloadUrlResponseBodyData extends $dara.Model {
+    expireTime?: number;
+    url?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+declare class GetContextFileDownloadUrlResponseBody extends $dara.Model {
+    code?: string;
+    data?: GetContextFileDownloadUrlResponseBodyData;
+    httpStatusCode?: number;
+    message?: string;
+    requestId?: string;
+    success?: boolean;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class GetContextFileDownloadUrlResponse extends $dara.Model {
+    headers?: {
+        [key: string]: string;
+    };
+    statusCode?: number;
+    body?: GetContextFileDownloadUrlResponseBody;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class GetContextFileUploadUrlRequest extends $dara.Model {
+    authorization?: string;
+    contextId?: string;
+    filePath?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class GetContextFileUploadUrlResponseBodyData extends $dara.Model {
+    expireTime?: number;
+    url?: string;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+declare class GetContextFileUploadUrlResponseBody extends $dara.Model {
+    code?: string;
+    data?: GetContextFileUploadUrlResponseBodyData;
+    httpStatusCode?: number;
+    message?: string;
+    requestId?: string;
+    success?: boolean;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
+declare class GetContextFileUploadUrlResponse extends $dara.Model {
+    headers?: {
+        [key: string]: string;
+    };
+    statusCode?: number;
+    body?: GetContextFileUploadUrlResponseBody;
+    static names(): {
+        [key: string]: string;
+    };
+    static types(): {
+        [key: string]: any;
+    };
+    validate(): void;
+    constructor(map?: {
+        [key: string]: any;
+    });
+}
+
 declare class Client extends OpenApi {
     constructor(config: $OpenApiUtil.Config);
     getEndpoint(productId: string, regionId: string, endpointRule: string, network: string, suffix: string, endpointMap: {
@@ -1405,6 +1672,66 @@ declare class Client extends OpenApi {
      * @returns InitBrowserResponse
      */
     initBrowserSync(request: InitBrowserRequest): InitBrowserResponse;
+    /**
+     * 获取上传context文件url
+     *
+     * @param request - DeleteContextFileRequest
+     * @param runtime - runtime options for this request RuntimeOptions
+     * @returns DeleteContextFileResponse
+     */
+    deleteContextFileWithOptions(request: DeleteContextFileRequest, runtime: $dara.RuntimeOptions): Promise<DeleteContextFileResponse>;
+    /**
+     * 获取上传context文件url
+     *
+     * @param request - DeleteContextFileRequest
+     * @returns DeleteContextFileResponse
+     */
+    deleteContextFile(request: DeleteContextFileRequest): Promise<DeleteContextFileResponse>;
+    /**
+     * 查询context特定目录文件
+     *
+     * @param request - DescribeContextFilesRequest
+     * @param runtime - runtime options for this request RuntimeOptions
+     * @returns DescribeContextFilesResponse
+     */
+    describeContextFilesWithOptions(request: DescribeContextFilesRequest, runtime: $dara.RuntimeOptions): Promise<DescribeContextFilesResponse>;
+    /**
+     * 查询context特定目录文件
+     *
+     * @param request - DescribeContextFilesRequest
+     * @returns DescribeContextFilesResponse
+     */
+    describeContextFiles(request: DescribeContextFilesRequest): Promise<DescribeContextFilesResponse>;
+    /**
+     * 获取上传context文件url
+     *
+     * @param request - GetContextFileDownloadUrlRequest
+     * @param runtime - runtime options for this request RuntimeOptions
+     * @returns GetContextFileDownloadUrlResponse
+     */
+    getContextFileDownloadUrlWithOptions(request: GetContextFileDownloadUrlRequest, runtime: $dara.RuntimeOptions): Promise<GetContextFileDownloadUrlResponse>;
+    /**
+     * 获取上传context文件url
+     *
+     * @param request - GetContextFileDownloadUrlRequest
+     * @returns GetContextFileDownloadUrlResponse
+     */
+    getContextFileDownloadUrl(request: GetContextFileDownloadUrlRequest): Promise<GetContextFileDownloadUrlResponse>;
+    /**
+     * 获取上传context文件url
+     *
+     * @param request - GetContextFileUploadUrlRequest
+     * @param runtime - runtime options for this request RuntimeOptions
+     * @returns GetContextFileUploadUrlResponse
+     */
+    getContextFileUploadUrlWithOptions(request: GetContextFileUploadUrlRequest, runtime: $dara.RuntimeOptions): Promise<GetContextFileUploadUrlResponse>;
+    /**
+     * 获取上传context文件url
+     *
+     * @param request - GetContextFileUploadUrlRequest
+     * @returns GetContextFileUploadUrlResponse
+     */
+    getContextFileUploadUrl(request: GetContextFileUploadUrlRequest): Promise<GetContextFileUploadUrlResponse>;
 }
 
 interface Config {
@@ -1412,6 +1739,19 @@ interface Config {
     endpoint: string;
     timeout_ms: number;
 }
+/**
+ * Load .env file into process.env if it exists
+ * This function should be called early to ensure .env variables are available
+ */
+declare function loadDotEnv(): void;
+/**
+ * The SDK uses the following precedence order for configuration (highest to lowest):
+ * 1. Explicitly passed configuration in code.
+ * 2. Environment variables.
+ * 3. .env file.
+ * 4. Default configuration.
+ */
+declare function loadConfig(customConfig?: Config): Config;
 
 /**
  * Base interface for API responses
@@ -1733,6 +2073,49 @@ interface ContextListResult extends ApiResponse {
     /** Optional error message if the operation failed */
     errorMessage?: string;
 }
+/**
+ * Result of a presigned URL request
+ */
+interface FileUrlResult extends ApiResponse {
+    /** Request identifier for tracking API calls */
+    requestId: string;
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The presigned URL */
+    url: string;
+    /** Optional expire time (epoch seconds) */
+    expireTime?: number;
+    /** Optional error message if the operation failed */
+    errorMessage?: string;
+}
+/**
+ * Represents a file item in a context
+ */
+interface ContextFileEntry {
+    fileId?: string;
+    fileName?: string;
+    filePath: string;
+    fileType?: string;
+    gmtCreate?: string;
+    gmtModified?: string;
+    size?: number;
+    status?: string;
+}
+/**
+ * Result of context file listing
+ */
+interface ContextFileListResult extends ApiResponse {
+    /** Request identifier for tracking API calls */
+    requestId: string;
+    /** Whether the operation was successful */
+    success: boolean;
+    /** File entries under a folder */
+    entries: ContextFileEntry[];
+    /** Optional total count returned by backend */
+    count?: number;
+    /** Optional error message if the operation failed */
+    errorMessage?: string;
+}
 
 /**
  * Represents a persistent storage context in the AgentBay cloud environment.
@@ -1840,6 +2223,22 @@ declare class ContextService {
      * @returns OperationResult with requestId
      */
     delete(context: Context): Promise<OperationResult>;
+    /**
+     * Get a presigned upload URL for a file in a context.
+     */
+    getFileUploadUrl(contextId: string, filePath: string): Promise<FileUrlResult>;
+    /**
+     * Get a presigned download URL for a file in a context.
+     */
+    getFileDownloadUrl(contextId: string, filePath: string): Promise<FileUrlResult>;
+    /**
+     * Delete a file in a context.
+     */
+    deleteFile(contextId: string, filePath: string): Promise<OperationResult>;
+    /**
+     * List files under a specific folder path in a context.
+     */
+    listFiles(contextId: string, parentFolderPath: string, pageNumber?: number, pageSize?: number): Promise<ContextFileListResult>;
 }
 
 declare enum UploadStrategy {
@@ -1860,6 +2259,25 @@ interface DownloadPolicy {
 interface DeletePolicy {
     syncLocalFile: boolean;
 }
+interface ExtractPolicy {
+    extract: boolean;
+    deleteSrcFile: boolean;
+    extractToCurrentFolder: boolean;
+}
+declare class ExtractPolicyClass implements ExtractPolicy {
+    extract: boolean;
+    deleteSrcFile: boolean;
+    extractToCurrentFolder: boolean;
+    constructor(extract?: boolean, deleteSrcFile?: boolean, extractToCurrentFolder?: boolean);
+    /**
+     * Creates a new extract policy with default values
+     */
+    static default(): ExtractPolicyClass;
+    /**
+     * Converts to plain object for JSON serialization
+     */
+    toDict(): Record<string, any>;
+}
 interface WhiteList {
     path: string;
     excludePaths?: string[];
@@ -1871,12 +2289,14 @@ interface SyncPolicy {
     uploadPolicy?: UploadPolicy;
     downloadPolicy?: DownloadPolicy;
     deletePolicy?: DeletePolicy;
+    extractPolicy?: ExtractPolicy;
     bwList?: BWList;
 }
 declare class SyncPolicyImpl implements SyncPolicy {
     uploadPolicy?: UploadPolicy;
     downloadPolicy?: DownloadPolicy;
     deletePolicy?: DeletePolicy;
+    extractPolicy?: ExtractPolicy;
     bwList?: BWList;
     constructor(policy?: Partial<SyncPolicy>);
     private ensureDefaults;
@@ -1892,6 +2312,7 @@ declare class ContextSync {
 declare function newUploadPolicy(): UploadPolicy;
 declare function newDownloadPolicy(): DownloadPolicy;
 declare function newDeletePolicy(): DeletePolicy;
+declare function newExtractPolicy(): ExtractPolicy;
 declare function newSyncPolicy(): SyncPolicy;
 declare function newSyncPolicyWithDefaults(policy?: Partial<SyncPolicy>): SyncPolicy;
 declare function newContextSync(contextId: string, path: string, policy?: SyncPolicy): ContextSync;
@@ -2258,15 +2679,14 @@ declare class FileSystem {
      */
     moveFile(source: string, destination: string): Promise<BoolResult>;
     /**
-     * Reads the content of a file.
-     * Corresponds to Python's read_file() method
+     * Internal method to read a file chunk. Used for chunked file operations.
      *
      * @param path - Path to the file to read.
      * @param offset - Optional: Byte offset to start reading from (0-based).
      * @param length - Optional: Number of bytes to read. If 0, reads the entire file from offset.
      * @returns FileContentResult with file content and requestId
      */
-    readFile(path: string, offset?: number, length?: number): Promise<FileContentResult>;
+    private readFileChunk;
     /**
      * Reads the content of multiple files.
      * Corresponds to Python's read_multiple_files() method
@@ -2286,34 +2706,30 @@ declare class FileSystem {
      */
     searchFiles(path: string, pattern: string, excludePatterns?: string[]): Promise<FileSearchResult>;
     /**
-     * Writes content to a file.
-     * Corresponds to Python's write_file() method
+     * Internal method to write a file chunk. Used for chunked file operations.
      *
      * @param path - Path to the file to write.
      * @param content - Content to write to the file.
      * @param mode - Optional: Write mode. One of "overwrite", "append", or "create_new". Default is "overwrite".
      * @returns BoolResult with write result and requestId
      */
-    writeFile(path: string, content: string, mode?: string): Promise<BoolResult>;
+    private writeFileChunk;
     /**
-     * Reads a large file in chunks to handle size limitations of the underlying API.
-     * Corresponds to Python's read_large_file() method
+     * Reads the contents of a file. Automatically handles large files by chunking.
      *
      * @param path - Path to the file to read.
-     * @param chunkSize - Optional: Size of each chunk in bytes. Default is 60KB.
      * @returns FileContentResult with complete file content and requestId
      */
-    readLargeFile(path: string, chunkSize?: number): Promise<FileContentResult>;
+    readFile(path: string): Promise<FileContentResult>;
     /**
-     * Writes a large file in chunks to handle size limitations of the underlying API.
-     * Corresponds to Python's write_large_file() method
+     * Writes content to a file. Automatically handles large files by chunking.
      *
      * @param path - Path to the file to write.
      * @param content - Content to write to the file.
-     * @param chunkSize - Optional: Size of each chunk in bytes. Default is 60KB.
+     * @param mode - Optional: Write mode. One of "overwrite", "append", or "create_new". Default is "overwrite".
      * @returns BoolResult indicating success or failure with requestId
      */
-    writeLargeFile(path: string, content: string, chunkSize?: number): Promise<BoolResult>;
+    writeFile(path: string, content: string, mode?: string): Promise<BoolResult>;
 }
 
 /**
@@ -2643,6 +3059,7 @@ interface ObserveOptions {
 interface ExtractOptions<T = any> {
     instruction: string;
     schema: new (...args: any[]) => T;
+    use_text_extract: boolean;
     selector?: string;
     iframe?: boolean;
     domSettleTimeoutsMS?: number;
@@ -2695,8 +3112,62 @@ declare class BrowserAgent {
     private _callMcpTool;
 }
 
+interface BrowserViewport {
+    width: number;
+    height: number;
+}
+interface BrowserScreen {
+    width: number;
+    height: number;
+}
+interface BrowserFingerprint {
+    devices?: Array<'desktop' | 'mobile'>;
+    operatingSystems?: Array<'windows' | 'macos' | 'linux' | 'android' | 'ios'>;
+    locales?: string[];
+}
+interface BrowserProxy {
+    type: 'custom' | 'wuying';
+    server?: string;
+    username?: string;
+    password?: string;
+    strategy?: 'restricted' | 'polling';
+    pollsize?: number;
+    toMap(): Record<string, any>;
+}
+declare class BrowserProxyClass implements BrowserProxy {
+    type: 'custom' | 'wuying';
+    server?: string;
+    username?: string;
+    password?: string;
+    strategy?: 'restricted' | 'polling';
+    pollsize?: number;
+    constructor(proxyType: 'custom' | 'wuying', server?: string, username?: string, password?: string, strategy?: 'restricted' | 'polling', pollsize?: number);
+    toMap(): Record<string, any>;
+    static fromMap(m: Record<string, any> | null | undefined): BrowserProxyClass | null;
+}
 interface BrowserOption {
     persistentPath?: string;
+    useStealth?: boolean;
+    userAgent?: string;
+    viewport?: BrowserViewport;
+    screen?: BrowserScreen;
+    fingerprint?: BrowserFingerprint;
+    proxies?: BrowserProxy[];
+    /** Path to the extensions directory. Defaults to "/tmp/extensions/" */
+    extensionPath?: string;
+}
+declare class BrowserOptionClass implements BrowserOption {
+    persistentPath?: string;
+    useStealth?: boolean;
+    userAgent?: string;
+    viewport?: BrowserViewport;
+    screen?: BrowserScreen;
+    fingerprint?: BrowserFingerprint;
+    proxies?: BrowserProxy[];
+    extensionPath?: string;
+    constructor(useStealth?: boolean, userAgent?: string, viewport?: BrowserViewport, screen?: BrowserScreen, fingerprint?: BrowserFingerprint, proxies?: BrowserProxy[]);
+    toMap(): Record<string, any>;
+    fromMap(m: Record<string, any> | null | undefined): BrowserOptionClass;
 }
 declare class Browser {
     private session;
@@ -2709,12 +3180,12 @@ declare class Browser {
      * Initialize the browser instance with the given options.
      * Returns true if successful, false otherwise.
      */
-    initialize(option: BrowserOption): boolean;
+    initialize(option: BrowserOptionClass | BrowserOption): boolean;
     /**
      * Initialize the browser instance with the given options asynchronously.
      * Returns true if successful, false otherwise.
      */
-    initializeAsync(option: BrowserOption): Promise<boolean>;
+    initializeAsync(option: BrowserOptionClass | BrowserOption): Promise<boolean>;
     /**
      * Returns the endpoint URL if the browser is initialized, otherwise throws an exception.
      * When initialized, always fetches the latest CDP url from session.getLink().
@@ -2723,11 +3194,15 @@ declare class Browser {
     /**
      * Returns the current BrowserOption used to initialize the browser, or null if not set.
      */
-    getOption(): BrowserOption | null;
+    getOption(): BrowserOptionClass | null;
     /**
      * Returns true if the browser was initialized, false otherwise.
      */
     isInitialized(): boolean;
+    /**
+     * Stop the browser instance, internal use only.
+     */
+    private _stopBrowser;
 }
 
 /**
@@ -2752,7 +3227,6 @@ interface McpToolsResult extends OperationResult {
 declare class Session {
     private agentBay;
     sessionId: string;
-    resourceUrl: string;
     isVpc: boolean;
     networkInterfaceIp: string;
     httpPort: string;
@@ -2874,30 +3348,344 @@ declare class Session {
 }
 
 /**
- * Browser context configuration for session.
+ * Represents a browser extension as a cloud resource.
+ */
+declare class Extension {
+    /**
+     * The unique identifier of the extension.
+     */
+    id: string;
+    /**
+     * The name of the extension.
+     */
+    name: string;
+    /**
+     * Date and time when the extension was created.
+     */
+    createdAt?: string;
+    /**
+     * Initialize an Extension object.
+     *
+     * @param id - The unique identifier of the extension.
+     * @param name - The name of the extension.
+     * @param createdAt - Date and time when the extension was created.
+     */
+    constructor(id: string, name: string, createdAt?: string);
+}
+/**
+ * Configuration options for browser extension integration.
+ *
+ * This class encapsulates the necessary parameters for setting up
+ * browser extension synchronization and context management.
  */
-interface BrowserContext {
+declare class ExtensionOption {
+    /**
+     * ID of the extension context for browser extensions.
+     */
+    contextId: string;
+    /**
+     * List of extension IDs to be loaded/synchronized.
+     */
+    extensionIds: string[];
+    /**
+     * Initialize ExtensionOption with context and extension configuration.
+     *
+     * @param contextId - ID of the extension context for browser extensions.
+     *                   This should match the context where extensions are stored.
+     * @param extensionIds - List of extension IDs to be loaded in the browser session.
+     *                      Each ID should correspond to a valid extension in the context.
+     *
+     * @throws {Error} If contextId is empty or extensionIds is empty.
+     */
+    constructor(contextId: string, extensionIds: string[]);
+    /**
+     * String representation of ExtensionOption.
+     */
+    toString(): string;
+    /**
+     * Human-readable string representation.
+     */
+    toDisplayString(): string;
+    /**
+     * Validate the extension option configuration.
+     *
+     * @returns True if configuration is valid, false otherwise.
+     */
+    validate(): boolean;
+}
+/**
+ * Provides methods to manage user browser extensions.
+ * This service integrates with the existing context functionality for file operations.
+ *
+ * **Usage** (Simplified - Auto-detection):
+ * ```typescript
+ * // Service automatically detects if context exists and creates if needed
+ * const extensionsService = new ExtensionsService(agentBay, "browser_extensions");
+ *
+ * // Or use with empty contextId to auto-generate context name
+ * const extensionsService = new ExtensionsService(agentBay);  // Uses default generated name
+ *
+ * // Use the service immediately - initialization happens automatically
+ * const extension = await extensionsService.create("/path/to/plugin.zip");
+ * ```
+ *
+ * **Integration with ExtensionOption (Simplified)**:
+ * ```typescript
+ * // Create extensions and configure for browser sessions
+ * const extensionsService = new ExtensionsService(agentBay, "my_extensions");
+ * const ext1 = await extensionsService.create("/path/to/ext1.zip");
+ * const ext2 = await extensionsService.create("/path/to/ext2.zip");
+ *
+ * // Create extension option for browser integration (no contextId needed!)
+ * const extOption = extensionsService.createExtensionOption([ext1.id, ext2.id]);
+ *
+ * // Use with BrowserContext for session creation
+ * const browserContext = new BrowserContext({
+ *   contextId: "browser_session",
+ *   autoUpload: true,
+ *   extensionOption: extOption  // All extension config encapsulated
+ * });
+ * ```
+ *
+ * **Context Management**:
+ * - If contextId provided and exists: Uses the existing context
+ * - If contextId provided but doesn't exist: Creates context with provided name
+ * - If contextId empty or not provided: Generates default name and creates context
+ * - No need to manually manage context creation or call initialize()
+ * - Context initialization happens automatically on first method call
+ */
+declare class ExtensionsService {
+    private agentBay;
+    private contextService;
+    private extensionContext;
+    private contextId;
+    private contextName;
+    private autoCreated;
+    private _initializationPromise;
+    /**
+     * Initializes the ExtensionsService with a context.
+     *
+     * @param agentBay - The AgentBay client instance.
+     * @param contextId - The context ID or name. If empty or not provided,
+     *                   a default context name will be generated automatically.
+     *                   If the context doesn't exist, it will be automatically created.
+     *
+     * Note:
+     *   The service automatically detects if the context exists. If not,
+     *   it creates a new context with the provided name or a generated default name.
+     *   Context initialization is handled lazily on first use.
+     */
+    constructor(agentBay: AgentBay, contextId?: string);
+    /**
+     * Internal method to initialize the context.
+     * This ensures the context is ready before any operations.
+     */
+    private _initializeContext;
+    /**
+     * Ensures the service is initialized before performing operations.
+     */
+    private _ensureInitialized;
+    /**
+     * An internal helper method that encapsulates the flow of "get upload URL for a specific path and upload".
+     * Uses the existing context service for file operations.
+     *
+     * @param localPath - The path to the local file.
+     * @param remotePath - The path of the file in context storage.
+     *
+     * @throws {AgentBayError} If getting the credential or uploading fails.
+     */
+    private _uploadToCloud;
+    /**
+     * Lists all available browser extensions within this context from the cloud.
+     * Uses the context service to list files under the extensions directory.
+     *
+     * @returns Promise that resolves to an array of Extension objects.
+     * @throws {AgentBayError} If listing extensions fails.
+     */
+    list(): Promise<Extension[]>;
+    /**
+     * Uploads a new browser extension from a local path into the current context.
+     *
+     * @param localPath - Path to the local extension file (must be a .zip file).
+     * @returns Promise that resolves to an Extension object.
+     * @throws {Error} If the local file doesn't exist.
+     * @throws {Error} If the file format is not supported (only .zip is supported).
+     * @throws {AgentBayError} If upload fails.
+     */
+    create(localPath: string): Promise<Extension>;
+    /**
+     * Updates an existing browser extension in the current context with a new file.
+     *
+     * @param extensionId - ID of the extension to update.
+     * @param newLocalPath - Path to the new local extension file.
+     * @returns Promise that resolves to an Extension object.
+     * @throws {Error} If the new local file doesn't exist.
+     * @throws {Error} If the extension doesn't exist in the context.
+     * @throws {AgentBayError} If update fails.
+     */
+    update(extensionId: string, newLocalPath: string): Promise<Extension>;
+    /**
+     * Gets detailed information about a specific browser extension.
+     *
+     * @param extensionId - The ID of the extension to get info for.
+     * @returns Promise that resolves to an Extension object if found, undefined otherwise.
+     */
+    private _getExtensionInfo;
+    /**
+     * Cleans up the auto-created context if it was created by this service.
+     *
+     * @returns Promise that resolves to true if cleanup was successful or not needed, false if cleanup failed.
+     *
+     * Note:
+     *   This method only works if the context was auto-created by this service.
+     *   For existing contexts, no cleanup is performed.
+     */
+    cleanup(): Promise<boolean>;
+    /**
+     * Deletes a browser extension from the current context.
+     *
+     * @param extensionId - ID of the extension to delete.
+     * @returns Promise that resolves to true if deletion was successful, false otherwise.
+     */
+    delete(extensionId: string): Promise<boolean>;
+    /**
+     * Create an ExtensionOption for the current context with specified extension IDs.
+     *
+     * This is a convenience method that creates an ExtensionOption using the current
+     * service's contextId and the provided extension IDs. This option can then be
+     * used with BrowserContext for browser session creation.
+     *
+     * @param extensionIds - List of extension IDs to include in the option.
+     *                      These should be extensions that exist in the current context.
+     * @returns ExtensionOption configuration object for browser extension integration.
+     * @throws {Error} If extensionIds is empty or invalid.
+     *
+     * @example
+     * ```typescript
+     * // Create extensions
+     * const ext1 = await extensionsService.create("/path/to/ext1.zip");
+     * const ext2 = await extensionsService.create("/path/to/ext2.zip");
+     *
+     * // Create extension option for browser integration
+     * const extOption = extensionsService.createExtensionOption([ext1.id, ext2.id]);
+     *
+     * // Use with BrowserContext
+     * const browserContext = new BrowserContext({
+     *   contextId: "browser_session",
+     *   autoUpload: true,
+     *   extensionContextId: extOption.contextId,
+     *   extensionIds: extOption.extensionIds
+     * });
+     * ```
+     */
+    createExtensionOption(extensionIds: string[]): ExtensionOption;
+}
+
+/**
+ * Browser context configuration for session with optional extension support.
+ *
+ * This class provides browser context configuration for cloud sessions and supports
+ * automatic extension synchronization when ExtensionOption is provided.
+ *
+ * Key Features:
+ * - Browser context binding for sessions
+ * - Automatic browser data upload on session end
+ * - Optional extension integration with automatic context sync generation
+ * - Clean API with ExtensionOption encapsulation
+ *
+ * Extension Configuration:
+ * - **ExtensionOption**: Pass an ExtensionOption object with contextId and extensionIds
+ * - **No Extensions**: Don't provide extensionOption parameter (extensionContextSyncs will be undefined)
+ *
+ * Usage Examples:
+ * ```typescript
+ * // With extensions using ExtensionOption
+ * import { ExtensionOption } from "./extension";
+ *
+ * const extOption = new ExtensionOption(
+ *   "my_extensions",
+ *   ["ext1", "ext2"]
+ * );
+ *
+ * const browserContext = new BrowserContext(
+ *   "browser_session",
+ *   true,
+ *   extOption
+ * );
+ *
+ * // Without extensions (minimal configuration)
+ * const browserContext = new BrowserContext(
+ *   "browser_session",
+ *   true
+ * );
+ * // extensionContextSyncs will be undefined
+ * ```
+ */
+declare class BrowserContext {
     /** ID of the browser context to bind to the session */
     contextId: string;
     /** Whether to automatically upload browser data when the session ends */
     autoUpload: boolean;
+    /** Optional extension configuration object containing context_id and extension_ids */
+    extensionOption?: ExtensionOption;
+    /** ID of the extension context for browser extensions. Set automatically from extension_option. */
+    extensionContextId?: string;
+    /** List of extension IDs to synchronize. Set automatically from extension_option. */
+    extensionIds?: string[];
+    /** Auto-generated context syncs for extensions. None if no extension configuration provided. */
+    extensionContextSyncs?: ContextSync[];
+    /**
+     * Initialize BrowserContextImpl with optional extension support.
+     *
+     * @param contextId - ID of the browser context to bind to the session.
+     *                   This identifies the browser instance for the session.
+     * @param autoUpload - Whether to automatically upload browser data
+     *                    when the session ends. Defaults to true.
+     * @param extensionOption - Extension configuration object containing
+     *                         contextId and extensionIds. This encapsulates
+     *                         all extension-related configuration.
+     *                         Defaults to undefined.
+     *
+     * Extension Configuration:
+     * - **ExtensionOption**: Use extensionOption parameter with an ExtensionOption object
+     * - **No Extensions**: Don't provide extensionOption parameter
+     *
+     * Auto-generation:
+     * - extensionContextSyncs is automatically generated when extensionOption is provided
+     * - extensionContextSyncs will be undefined if no extensionOption is provided
+     * - extensionContextSyncs will be a ContextSync[] if extensionOption is valid
+     */
+    constructor(contextId: string, autoUpload?: boolean, extensionOption?: ExtensionOption);
+    /**
+     * Create ContextSync configurations for browser extensions.
+     *
+     * This method is called only when extensionOption is provided and contains
+     * valid extension configuration (contextId and extensionIds).
+     *
+     * @returns ContextSync[] - List of context sync configurations for extensions.
+     *                         Returns empty list if extension configuration is invalid.
+     */
+    private _createExtensionContextSyncs;
+    /**
+     * Get all context syncs including extension syncs.
+     *
+     * @returns ContextSync[] - All context sync configurations. Returns empty list if no extensions configured.
+     */
+    getAllContextSyncs(): ContextSync[];
 }
 /**
  * Configuration interface for CreateSessionParams
  */
 interface CreateSessionParamsConfig {
     labels: Record<string, string>;
-    /**
-     * @deprecated This field is deprecated and will be removed in a future version.
-     * Please use contextSync instead for more flexible and powerful data persistence.
-     */
-    contextId?: string;
     imageId?: string;
     contextSync: ContextSync[];
     /** Optional configuration for browser data synchronization */
     browserContext?: BrowserContext;
     /** Whether to create a VPC-based session. Defaults to false. */
     isVpc?: boolean;
+    /** MCP policy id to apply when creating the session. */
+    mcpPolicyId?: string;
 }
 /**
  * CreateSessionParams provides a way to configure the parameters for creating a new session
@@ -2906,25 +3694,6 @@ interface CreateSessionParamsConfig {
 declare class CreateSessionParams$1 implements CreateSessionParamsConfig {
     /** Custom labels for the Session. These can be used for organizing and filtering sessions. */
     labels: Record<string, string>;
-    /**
-     * ID of the context to bind to the session.
-     * The context can include various types of persistence like file system (volume) and cookies.
-     *
-     * @deprecated This field is deprecated and will be removed in a future version.
-     * Please use contextSync instead for more flexible and powerful data persistence.
-     *
-     * Important Limitations:
-     * 1. One session at a time: A context can only be used by one session at a time.
-     *    If you try to create a session with a context ID that is already in use by another active session,
-     *    the session creation will fail.
-     *
-     * 2. OS binding: A context is bound to the operating system of the first session that uses it.
-     *    When a context is first used with a session, it becomes bound to that session's OS.
-     *    Any attempt to use the context with a session running on a different OS will fail.
-     *    For example, if a context is first used with a Linux session, it cannot later be used
-     *    with a Windows or Android session.
-     */
-    contextId?: string;
     /** Image ID to use for the session. */
     imageId?: string;
     /**
@@ -2936,15 +3705,13 @@ declare class CreateSessionParams$1 implements CreateSessionParamsConfig {
     browserContext?: BrowserContext;
     /** Whether to create a VPC-based session. Defaults to false. */
     isVpc: boolean;
+    /** MCP policy id to apply when creating the session. */
+    mcpPolicyId?: string;
     constructor();
     /**
      * WithLabels sets the labels for the session parameters and returns the updated parameters.
      */
     withLabels(labels: Record<string, string>): CreateSessionParams$1;
-    /**
-     * WithContextID sets the context ID for the session parameters and returns the updated parameters.
-     */
-    withContextID(contextId: string): CreateSessionParams$1;
     /**
      * WithImageId sets the image ID for the session parameters and returns the updated parameters.
      */
@@ -2957,6 +3724,10 @@ declare class CreateSessionParams$1 implements CreateSessionParamsConfig {
      * WithIsVpc sets the VPC flag for the session parameters and returns the updated parameters.
      */
     withIsVpc(isVpc: boolean): CreateSessionParams$1;
+    /**
+     * WithMcpPolicyId sets the MCP policy id for the session parameters and returns the updated parameters.
+     */
+    withMcpPolicyId(mcpPolicyId: string): CreateSessionParams$1;
     /**
      * GetLabelsJSON returns the labels as a JSON string.
      * Returns an object with success status and result/error message to match Go version behavior.
@@ -3021,12 +3792,12 @@ interface SessionListResult extends ApiResponse {
  * Parameters for creating a session.
  */
 interface CreateSessionParams {
-    contextId?: string;
     labels?: Record<string, string>;
     imageId?: string;
     contextSync?: ContextSync[];
     browserContext?: BrowserContext;
     isVpc?: boolean;
+    mcpPolicyId?: string;
 }
 /**
  * Main class for interacting with the AgentBay cloud runtime environment.
@@ -3171,4 +3942,4 @@ declare function log(message: string, ...args: any[]): void;
  */
 declare function logError(message: string, error?: any): void;
 
-export { APIError, type ActOptions, ActResult, Agent, AgentBay, AgentBayError, Application, ApplicationError, ApplyMqttTokenRequest, ApplyMqttTokenResponse, ApplyMqttTokenResponseBody, ApplyMqttTokenResponseBodyData, AuthenticationError, type BWList, Browser, BrowserAgent, type BrowserContext, BrowserError, type BrowserOption, CallMcpToolRequest, CallMcpToolResponse, CallMcpToolResponseBody, Client, Command, CommandError, Context, type ContextInfoResult, ContextManager, ContextService, type ContextStatusData, type ContextStatusItem, ContextSync, type ContextSyncResult, CreateMcpSessionRequest, CreateMcpSessionRequestPersistenceDataList, CreateMcpSessionResponse, CreateMcpSessionResponseBody, CreateMcpSessionResponseBodyData, CreateMcpSessionShrinkRequest, type CreateSessionParams, type CreateSessionParamsConfig, DeleteContextRequest, DeleteContextResponse, DeleteContextResponseBody, type DeletePolicy, type DirectoryEntry, type DownloadPolicy, DownloadStrategy, type ExecutionResult, type ExtractOptions, FileError, type FileInfo, FileSystem, GetContextInfoRequest, GetContextInfoResponse, GetContextInfoResponseBody, GetContextInfoResponseBodyData, GetContextRequest, GetContextResponse, GetContextResponseBody, GetContextResponseBodyData, GetLabelRequest, GetLabelResponse, GetLabelResponseBody, GetLabelResponseBodyData, GetLinkRequest, GetLinkResponse, GetLinkResponseBody, GetLinkResponseBodyData, GetMcpResourceRequest, GetMcpResourceResponse, GetMcpResourceResponseBody, GetMcpResourceResponseBodyData, GetMcpResourceResponseBodyDataDesktopInfo, InitBrowserRequest, InitBrowserResponse, InitBrowserResponseBody, InitBrowserResponseBodyData, type InstalledApp, KeyCode, ListContextsRequest, ListContextsResponse, ListContextsResponseBody, ListContextsResponseBodyData, ListMcpToolsRequest, ListMcpToolsResponse, ListMcpToolsResponseBody, type ListSessionParams, ListSessionRequest, ListSessionResponse, ListSessionResponseBody, ListSessionResponseBodyData, type McpSession, type McpToolResult, ModifyContextRequest, ModifyContextResponse, ModifyContextResponseBody, type ObserveOptions, ObserveResult, Oss, OssError, type Process, type QueryResult, ReleaseMcpSessionRequest, ReleaseMcpSessionResponse, ReleaseMcpSessionResponseBody, Session, SessionError, type SessionInterface, SetLabelRequest, SetLabelResponse, SetLabelResponseBody, SyncContextRequest, SyncContextResponse, SyncContextResponseBody, type SyncPolicy, SyncPolicyImpl, UI, type UIElement, UIError, type UploadPolicy, UploadStrategy, type WhiteList, log, logError, newContextManager, newContextSync, newCreateSessionParams, newDeletePolicy, newDownloadPolicy, newSyncPolicy, newSyncPolicyWithDefaults, newUploadPolicy };
+export { APIError, type ActOptions, ActResult, Agent, AgentBay, AgentBayError, Application, ApplicationError, ApplyMqttTokenRequest, ApplyMqttTokenResponse, ApplyMqttTokenResponseBody, ApplyMqttTokenResponseBodyData, AuthenticationError, type BWList, Browser, BrowserAgent, BrowserContext, BrowserError, type BrowserFingerprint, type BrowserOption, BrowserOptionClass, type BrowserProxy, BrowserProxyClass, type BrowserScreen, type BrowserViewport, CallMcpToolRequest, CallMcpToolResponse, CallMcpToolResponseBody, Client, Command, CommandError, type Config, Context, type ContextInfoResult, ContextManager, ContextService, type ContextStatusData, type ContextStatusItem, ContextSync, type ContextSyncResult, CreateMcpSessionRequest, CreateMcpSessionRequestPersistenceDataList, CreateMcpSessionResponse, CreateMcpSessionResponseBody, CreateMcpSessionResponseBodyData, CreateMcpSessionShrinkRequest, type CreateSessionParams, type CreateSessionParamsConfig, DeleteContextFileRequest, DeleteContextFileResponse, DeleteContextFileResponseBody, DeleteContextRequest, DeleteContextResponse, DeleteContextResponseBody, type DeletePolicy, DescribeContextFilesRequest, DescribeContextFilesResponse, DescribeContextFilesResponseBody, type DirectoryEntry, type DownloadPolicy, DownloadStrategy, type ExecutionResult, Extension, ExtensionOption, ExtensionsService, type ExtractOptions, type ExtractPolicy, ExtractPolicyClass, FileError, type FileInfo, FileSystem, GetContextFileDownloadUrlRequest, GetContextFileDownloadUrlResponse, GetContextFileDownloadUrlResponseBody, GetContextFileUploadUrlRequest, GetContextFileUploadUrlResponse, GetContextFileUploadUrlResponseBody, GetContextInfoRequest, GetContextInfoResponse, GetContextInfoResponseBody, GetContextInfoResponseBodyData, GetContextRequest, GetContextResponse, GetContextResponseBody, GetContextResponseBodyData, GetLabelRequest, GetLabelResponse, GetLabelResponseBody, GetLabelResponseBodyData, GetLinkRequest, GetLinkResponse, GetLinkResponseBody, GetLinkResponseBodyData, GetMcpResourceRequest, GetMcpResourceResponse, GetMcpResourceResponseBody, GetMcpResourceResponseBodyData, GetMcpResourceResponseBodyDataDesktopInfo, InitBrowserRequest, InitBrowserResponse, InitBrowserResponseBody, InitBrowserResponseBodyData, type InstalledApp, KeyCode, ListContextsRequest, ListContextsResponse, ListContextsResponseBody, ListContextsResponseBodyData, ListMcpToolsRequest, ListMcpToolsResponse, ListMcpToolsResponseBody, type ListSessionParams, ListSessionRequest, ListSessionResponse, ListSessionResponseBody, ListSessionResponseBodyData, type McpSession, type McpToolResult, ModifyContextRequest, ModifyContextResponse, ModifyContextResponseBody, type ObserveOptions, ObserveResult, Oss, OssError, type Process, type QueryResult, ReleaseMcpSessionRequest, ReleaseMcpSessionResponse, ReleaseMcpSessionResponseBody, Session, SessionError, type SessionInterface, SetLabelRequest, SetLabelResponse, SetLabelResponseBody, SyncContextRequest, SyncContextResponse, SyncContextResponseBody, type SyncPolicy, SyncPolicyImpl, UI, type UIElement, UIError, type UploadPolicy, UploadStrategy, type WhiteList, loadConfig, loadDotEnv, log, logError, newContextManager, newContextSync, newCreateSessionParams, newDeletePolicy, newDownloadPolicy, newExtractPolicy, newSyncPolicy, newSyncPolicyWithDefaults, newUploadPolicy };