wuying-agentbay-sdk 0.6.1 → 0.8.0

package/dist/index.d.ts

@@ -1426,7 +1426,7 @@ declare class Client extends OpenApi {
         [key: string]: string;
     }, endpoint: string): string;
     /**
-     * 调用mcp工具
+     * Call MCP tool
      *
      * @param request - CallMcpToolRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1434,14 +1434,14 @@ declare class Client extends OpenApi {
      */
     callMcpToolWithOptions(request: CallMcpToolRequest, runtime: $dara.RuntimeOptions): Promise<CallMcpToolResponse>;
     /**
-     * 调用mcp工具
+     * Call MCP tool
      *
      * @param request - CallMcpToolRequest
      * @returns CallMcpToolResponse
      */
     callMcpTool(request: CallMcpToolRequest): Promise<CallMcpToolResponse>;
     /**
-     * 创建 mcp session
+     * Create MCP session
      *
      * @param tmpReq - CreateMcpSessionRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1449,14 +1449,14 @@ declare class Client extends OpenApi {
      */
     createMcpSessionWithOptions(tmpReq: CreateMcpSessionRequest, runtime: $dara.RuntimeOptions): Promise<CreateMcpSessionResponse>;
     /**
-     * 创建 mcp session
+     * Create MCP session
      *
      * @param request - CreateMcpSessionRequest
      * @returns CreateMcpSessionResponse
      */
     createMcpSession(request: CreateMcpSessionRequest): Promise<CreateMcpSessionResponse>;
     /**
-     * 删除持久化上下文
+     * Delete persistent context
      *
      * @param request - DeleteContextRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1464,14 +1464,14 @@ declare class Client extends OpenApi {
      */
     deleteContextWithOptions(request: DeleteContextRequest, runtime: $dara.RuntimeOptions): Promise<DeleteContextResponse>;
     /**
-     * 删除持久化上下文
+     * Delete persistent context
      *
      * @param request - DeleteContextRequest
      * @returns DeleteContextResponse
      */
     deleteContext(request: DeleteContextRequest): Promise<DeleteContextResponse>;
     /**
-     * 获取上下文
+     * Get context
      *
      * @param request - GetContextRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1479,14 +1479,14 @@ declare class Client extends OpenApi {
      */
     getContextWithOptions(request: GetContextRequest, runtime: $dara.RuntimeOptions): Promise<GetContextResponse>;
     /**
-     * 获取上下文
+     * Get context
      *
      * @param request - GetContextRequest
      * @returns GetContextResponse
      */
     getContext(request: GetContextRequest): Promise<GetContextResponse>;
     /**
-     * 获取上下文信息
+     * Get context information
      *
      * @param request - GetContextInfoRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1494,14 +1494,14 @@ declare class Client extends OpenApi {
      */
     getContextInfoWithOptions(request: GetContextInfoRequest, runtime: $dara.RuntimeOptions): Promise<GetContextInfoResponse>;
     /**
-     * 获取上下文信息
+     * Get context information
      *
      * @param request - GetContextInfoRequest
      * @returns GetContextInfoResponse
      */
     getContextInfo(request: GetContextInfoRequest): Promise<GetContextInfoResponse>;
     /**
-     * 获取标签
+     * Get labels
      *
      * @param request - GetLabelRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1509,14 +1509,14 @@ declare class Client extends OpenApi {
      */
     getLabelWithOptions(request: GetLabelRequest, runtime: $dara.RuntimeOptions): Promise<GetLabelResponse>;
     /**
-     * 获取标签
+     * Get labels
      *
      * @param request - GetLabelRequest
      * @returns GetLabelResponse
      */
     getLabel(request: GetLabelRequest): Promise<GetLabelResponse>;
     /**
-     * 获取特定端口的转发链接
+     * Get forwarding link for specific port
      *
      * @param request - GetLinkRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1524,14 +1524,14 @@ declare class Client extends OpenApi {
      */
     getLinkWithOptions(request: GetLinkRequest, runtime: $dara.RuntimeOptions): Promise<GetLinkResponse>;
     /**
-     * 获取特定端口的转发链接
+     * Get forwarding link for specific port
      *
      * @param request - GetLinkRequest
      * @returns GetLinkResponse
      */
     getLink(request: GetLinkRequest): Promise<GetLinkResponse>;
     /**
-     * 获取mcp资源信息
+     * Get MCP resource information
      *
      * @param request - GetMcpResourceRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1539,14 +1539,14 @@ declare class Client extends OpenApi {
      */
     getMcpResourceWithOptions(request: GetMcpResourceRequest, runtime: $dara.RuntimeOptions): Promise<GetMcpResourceResponse>;
     /**
-     * 获取mcp资源信息
+     * Get MCP resource information
      *
      * @param request - GetMcpResourceRequest
      * @returns GetMcpResourceResponse
      */
     getMcpResource(request: GetMcpResourceRequest): Promise<GetMcpResourceResponse>;
     /**
-     * 获取上下文列表
+     * Get context list
      *
      * @param request - ListContextsRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1554,7 +1554,7 @@ declare class Client extends OpenApi {
      */
     listContextsWithOptions(request: ListContextsRequest, runtime: $dara.RuntimeOptions): Promise<ListContextsResponse>;
     /**
-     * 获取上下文列表
+     * Get context list
      *
      * @param request - ListContextsRequest
      * @returns ListContextsResponse
@@ -1576,7 +1576,7 @@ declare class Client extends OpenApi {
      */
     listMcpTools(request: ListMcpToolsRequest): Promise<ListMcpToolsResponse>;
     /**
-     * 根据Lable查询Session列表
+     * Query session list by label
      *
      * @param request - ListSessionRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1584,14 +1584,14 @@ declare class Client extends OpenApi {
      */
     listSessionWithOptions(request: ListSessionRequest, runtime: $dara.RuntimeOptions): Promise<ListSessionResponse>;
     /**
-     * 根据Lable查询Session列表
+     * Query session list by label
      *
      * @param request - ListSessionRequest
      * @returns ListSessionResponse
      */
     listSession(request: ListSessionRequest): Promise<ListSessionResponse>;
     /**
-     * 修改上下文
+     * Modify context
      *
      * @param request - ModifyContextRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1599,14 +1599,14 @@ declare class Client extends OpenApi {
      */
     modifyContextWithOptions(request: ModifyContextRequest, runtime: $dara.RuntimeOptions): Promise<ModifyContextResponse>;
     /**
-     * 修改上下文
+     * Modify context
      *
      * @param request - ModifyContextRequest
      * @returns ModifyContextResponse
      */
     modifyContext(request: ModifyContextRequest): Promise<ModifyContextResponse>;
     /**
-     * 释放 mcp session
+     * Release MCP session
      *
      * @param request - ReleaseMcpSessionRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1614,14 +1614,14 @@ declare class Client extends OpenApi {
      */
     releaseMcpSessionWithOptions(request: ReleaseMcpSessionRequest, runtime: $dara.RuntimeOptions): Promise<ReleaseMcpSessionResponse>;
     /**
-     * 释放 mcp session
+     * Release MCP session
      *
      * @param request - ReleaseMcpSessionRequest
      * @returns ReleaseMcpSessionResponse
      */
     releaseMcpSession(request: ReleaseMcpSessionRequest): Promise<ReleaseMcpSessionResponse>;
     /**
-     * 设置标签
+     * Set labels
      *
      * @param request - SetLabelRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1629,14 +1629,14 @@ declare class Client extends OpenApi {
      */
     setLabelWithOptions(request: SetLabelRequest, runtime: $dara.RuntimeOptions): Promise<SetLabelResponse>;
     /**
-     * 设置标签
+     * Set labels
      *
      * @param request - SetLabelRequest
      * @returns SetLabelResponse
      */
     setLabel(request: SetLabelRequest): Promise<SetLabelResponse>;
     /**
-     * 同步上下文
+     * Sync context
      *
      * @param request - SyncContextRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1644,14 +1644,14 @@ declare class Client extends OpenApi {
      */
     syncContextWithOptions(request: SyncContextRequest, runtime: $dara.RuntimeOptions): Promise<SyncContextResponse>;
     /**
-     * 同步上下文
+     * Sync context
      *
      * @param request - SyncContextRequest
      * @returns SyncContextResponse
      */
     syncContext(request: SyncContextRequest): Promise<SyncContextResponse>;
     /**
-     * 初始化浏览器
+     * Initialize browser
      *
      * @param tmpReq - InitBrowserRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1659,21 +1659,21 @@ declare class Client extends OpenApi {
      */
     initBrowserWithOptions(request: InitBrowserRequest, runtime: $dara.RuntimeOptions): Promise<InitBrowserResponse>;
     /**
-     * 初始化浏览器
+     * Initialize browser
      *
      * @param request - InitBrowserRequest
      * @returns InitBrowserResponse
      */
     initBrowser(request: InitBrowserRequest): Promise<InitBrowserResponse>;
     /**
-     * 初始化浏览器（同步版本）
+     * Initialize browser (sync version)
      *
      * @param request - InitBrowserRequest
      * @returns InitBrowserResponse
      */
     initBrowserSync(request: InitBrowserRequest): InitBrowserResponse;
     /**
-     * 获取上传context文件url
+     * Get context file upload URL
      *
      * @param request - DeleteContextFileRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1681,14 +1681,14 @@ declare class Client extends OpenApi {
      */
     deleteContextFileWithOptions(request: DeleteContextFileRequest, runtime: $dara.RuntimeOptions): Promise<DeleteContextFileResponse>;
     /**
-     * 获取上传context文件url
+     * Get context file upload URL
      *
      * @param request - DeleteContextFileRequest
      * @returns DeleteContextFileResponse
      */
     deleteContextFile(request: DeleteContextFileRequest): Promise<DeleteContextFileResponse>;
     /**
-     * 查询context特定目录文件
+     * Query context specific directory files
      *
      * @param request - DescribeContextFilesRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1696,14 +1696,14 @@ declare class Client extends OpenApi {
      */
     describeContextFilesWithOptions(request: DescribeContextFilesRequest, runtime: $dara.RuntimeOptions): Promise<DescribeContextFilesResponse>;
     /**
-     * 查询context特定目录文件
+     * Query context specific directory files
      *
      * @param request - DescribeContextFilesRequest
      * @returns DescribeContextFilesResponse
      */
     describeContextFiles(request: DescribeContextFilesRequest): Promise<DescribeContextFilesResponse>;
     /**
-     * 获取上传context文件url
+     * Get context file upload URL
      *
      * @param request - GetContextFileDownloadUrlRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1711,14 +1711,14 @@ declare class Client extends OpenApi {
      */
     getContextFileDownloadUrlWithOptions(request: GetContextFileDownloadUrlRequest, runtime: $dara.RuntimeOptions): Promise<GetContextFileDownloadUrlResponse>;
     /**
-     * 获取上传context文件url
+     * Get context file upload URL
      *
      * @param request - GetContextFileDownloadUrlRequest
      * @returns GetContextFileDownloadUrlResponse
      */
     getContextFileDownloadUrl(request: GetContextFileDownloadUrlRequest): Promise<GetContextFileDownloadUrlResponse>;
     /**
-     * 获取上传context文件url
+     * Get context file upload URL
      *
      * @param request - GetContextFileUploadUrlRequest
      * @param runtime - runtime options for this request RuntimeOptions
@@ -1726,7 +1726,7 @@ declare class Client extends OpenApi {
      */
     getContextFileUploadUrlWithOptions(request: GetContextFileUploadUrlRequest, runtime: $dara.RuntimeOptions): Promise<GetContextFileUploadUrlResponse>;
     /**
-     * 获取上传context文件url
+     * Get context file upload URL
      *
      * @param request - GetContextFileUploadUrlRequest
      * @returns GetContextFileUploadUrlResponse
@@ -1739,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
@@ -2246,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[];
@@ -2257,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;
@@ -2278,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;
@@ -2557,6 +2592,38 @@ declare class ContextManager {
 }
 declare function newContextManager(session: SessionInterface): ContextManager;
 
+/**
+ * Represents a single file change event
+ */
+interface FileChangeEvent {
+    eventType: string;
+    path: string;
+    pathType: string;
+}
+/**
+ * Result of file change detection operations
+ */
+interface FileChangeResult extends ApiResponse {
+    events: FileChangeEvent[];
+    rawData: string;
+}
+/**
+ * Helper functions for FileChangeEvent
+ */
+declare class FileChangeEventHelper {
+    static toString(event: FileChangeEvent): string;
+    static toDict(event: FileChangeEvent): Record<string, string>;
+    static fromDict(data: Record<string, any>): FileChangeEvent;
+}
+/**
+ * Helper functions for FileChangeResult
+ */
+declare class FileChangeResultHelper {
+    static hasChanges(result: FileChangeResult): boolean;
+    static getModifiedFiles(result: FileChangeResult): string[];
+    static getCreatedFiles(result: FileChangeResult): string[];
+    static getDeletedFiles(result: FileChangeResult): string[];
+}
 /**
  * FileInfo represents information about a file or directory
  */
@@ -2644,15 +2711,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
@@ -2672,34 +2738,42 @@ 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>;
+    /**
+     * Get file change information for the specified directory path
+     */
+    getFileChange(path: string): Promise<FileChangeResult>;
+    /**
+     * Parse raw JSON data into FileChangeEvent array
+     */
+    private parseFileChangeData;
+    /**
+     * Watch a directory for file changes and call the callback function when changes occur
+     */
+    watchDirectory(path: string, callback: (events: FileChangeEvent[]) => void, interval?: number, signal?: AbortSignal): Promise<void>;
 }
 
 /**
@@ -3055,28 +3129,28 @@ declare class BrowserAgent {
      * Perform an action on the given Playwright Page object, using ActOptions to configure behavior.
      * Returns the result of the action.
      */
-    act(page: any, options: ActOptions): Promise<ActResult>;
+    act(options: ActOptions, page: any): Promise<ActResult>;
     /**
      * Async version of act method for performing actions on the given Playwright Page object.
      */
-    actAsync(page: any, options: ActOptions): Promise<ActResult>;
+    actAsync(options: ActOptions, page: any): Promise<ActResult>;
     /**
      * Observe elements or state on the given Playwright Page object.
      * Returns a tuple containing (success, results).
      */
-    observe(page: any, options: ObserveOptions): Promise<[boolean, ObserveResult[]]>;
+    observe(options: ObserveOptions, page: any): Promise<[boolean, ObserveResult[]]>;
     /**
      * Async version of observe method.
      */
-    observeAsync(page: any, options: ObserveOptions): Promise<[boolean, ObserveResult[]]>;
+    observeAsync(options: ObserveOptions, page: any): Promise<[boolean, ObserveResult[]]>;
     /**
      * Extract information from the given Playwright Page object.
      */
-    extract<T>(page: any, options: ExtractOptions<T>): Promise<[boolean, T[]]>;
+    extract<T>(options: ExtractOptions<T>, page: any): Promise<[boolean, T[]]>;
     /**
      * Async version of extract method.
      */
-    extractAsync<T>(page: any, options: ExtractOptions<T>): Promise<[boolean, T[]]>;
+    extractAsync<T>(options: ExtractOptions<T>, page: any): Promise<[boolean, T[]]>;
     private _getPageAndContextIndex;
     private _getPageAndContextIndexAsync;
     private _callMcpTool;
@@ -3122,7 +3196,10 @@ interface BrowserOption {
     viewport?: BrowserViewport;
     screen?: BrowserScreen;
     fingerprint?: BrowserFingerprint;
+    solveCaptchas?: boolean;
     proxies?: BrowserProxy[];
+    /** Path to the extensions directory. Defaults to "/tmp/extensions/" */
+    extensionPath?: string;
 }
 declare class BrowserOptionClass implements BrowserOption {
     persistentPath?: string;
@@ -3131,8 +3208,10 @@ declare class BrowserOptionClass implements BrowserOption {
     viewport?: BrowserViewport;
     screen?: BrowserScreen;
     fingerprint?: BrowserFingerprint;
+    solveCaptchas?: boolean;
     proxies?: BrowserProxy[];
-    constructor(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, solveCaptchas?: boolean, proxies?: BrowserProxy[]);
     toMap(): Record<string, any>;
     fromMap(m: Record<string, any> | null | undefined): BrowserOptionClass;
 }
@@ -3194,7 +3273,6 @@ interface McpToolsResult extends OperationResult {
 declare class Session {
     private agentBay;
     sessionId: string;
-    resourceUrl: string;
     isVpc: boolean;
     networkInterfaceIp: string;
     httpPort: string;
@@ -3316,13 +3394,330 @@ 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
@@ -3593,4 +3988,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 BrowserFingerprint, type BrowserOption, BrowserOptionClass, type BrowserProxy, BrowserProxyClass, type BrowserScreen, type BrowserViewport, 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, DeleteContextFileRequest, DeleteContextFileResponse, DeleteContextFileResponseBody, DeleteContextRequest, DeleteContextResponse, DeleteContextResponseBody, type DeletePolicy, DescribeContextFilesRequest, DescribeContextFilesResponse, DescribeContextFilesResponseBody, type DirectoryEntry, type DownloadPolicy, DownloadStrategy, type ExecutionResult, type ExtractOptions, 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, 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, type FileChangeEvent, FileChangeEventHelper, type FileChangeResult, FileChangeResultHelper, 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 };