wuying-agentbay-sdk 0.6.1 → 0.7.0

package/dist/index.mjs

@@ -129,10 +129,10 @@ var require_main = __commonJS({
   "node_modules/dotenv/lib/main.js"(exports, module) {
     "use strict";
     init_esm_shims();
-    var fs2 = __require("fs");
-    var path3 = __require("path");
+    var fs3 = __require("fs");
+    var path4 = __require("path");
     var os = __require("os");
-    var crypto = __require("crypto");
+    var crypto2 = __require("crypto");
     var packageJson = require_package();
     var version = packageJson.version;
     var LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg;
@@ -245,7 +245,7 @@ var require_main = __commonJS({
       if (options && options.path && options.path.length > 0) {
         if (Array.isArray(options.path)) {
           for (const filepath of options.path) {
-            if (fs2.existsSync(filepath)) {
+            if (fs3.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -253,16 +253,16 @@ var require_main = __commonJS({
           possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
         }
       } else {
-        possibleVaultPath = path3.resolve(process.cwd(), ".env.vault");
+        possibleVaultPath = path4.resolve(process.cwd(), ".env.vault");
       }
-      if (fs2.existsSync(possibleVaultPath)) {
+      if (fs3.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
     }
     __name(_vaultPath, "_vaultPath");
     function _resolveHome(envPath) {
-      return envPath[0] === "~" ? path3.join(os.homedir(), envPath.slice(1)) : envPath;
+      return envPath[0] === "~" ? path4.join(os.homedir(), envPath.slice(1)) : envPath;
     }
     __name(_resolveHome, "_resolveHome");
     function _configVault(options) {
@@ -281,7 +281,7 @@ var require_main = __commonJS({
     }
     __name(_configVault, "_configVault");
     function configDotenv(options) {
-      const dotenvPath = path3.resolve(process.cwd(), ".env");
+      const dotenvPath = path4.resolve(process.cwd(), ".env");
       let encoding = "utf8";
       const debug = Boolean(options && options.debug);
       const quiet = options && "quiet" in options ? options.quiet : true;
@@ -305,13 +305,13 @@ var require_main = __commonJS({
       }
       let lastError;
       const parsedAll = {};
-      for (const path4 of optionPaths) {
+      for (const path5 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs2.readFileSync(path4, { encoding }));
+          const parsed = DotenvModule.parse(fs3.readFileSync(path5, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e) {
           if (debug) {
-            _debug(`Failed to load ${path4} ${e.message}`);
+            _debug(`Failed to load ${path5} ${e.message}`);
           }
           lastError = e;
         }
@@ -326,7 +326,7 @@ var require_main = __commonJS({
         const shortPaths = [];
         for (const filePath of optionPaths) {
           try {
-            const relative = path3.relative(process.cwd(), filePath);
+            const relative = path4.relative(process.cwd(), filePath);
             shortPaths.push(relative);
           } catch (e) {
             if (debug) {
@@ -363,7 +363,7 @@ var require_main = __commonJS({
       const authTag = ciphertext.subarray(-16);
       ciphertext = ciphertext.subarray(12, -16);
       try {
-        const aesgcm = crypto.createDecipheriv("aes-256-gcm", key, nonce);
+        const aesgcm = crypto2.createDecipheriv("aes-256-gcm", key, nonce);
         aesgcm.setAuthTag(authTag);
         return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
       } catch (error) {
@@ -4209,6 +4209,28 @@ function defaultConfig() {
   };
 }
 __name(defaultConfig, "defaultConfig");
+var dotEnvLoaded = false;
+function loadDotEnv() {
+  if (dotEnvLoaded) {
+    return;
+  }
+  try {
+    const envPath = path2.resolve(process.cwd(), ".env");
+    if (fs.existsSync(envPath)) {
+      const envConfig = dotenv.parse(fs.readFileSync(envPath));
+      for (const k in envConfig) {
+        if (!process.env.hasOwnProperty(k)) {
+          process.env[k] = envConfig[k];
+        }
+      }
+      log(`Loaded .env file at: ${envPath}`);
+      dotEnvLoaded = true;
+    }
+  } catch (error) {
+    log(`Warning: Failed to load .env file: ${error}`);
+  }
+}
+__name(loadDotEnv, "loadDotEnv");
 function loadConfig(customConfig) {
   if (customConfig) {
     return customConfig;
@@ -4229,16 +4251,16 @@ function loadConfig(customConfig) {
   const envPath = path2.resolve(process.cwd(), ".env");
   if (fs.existsSync(envPath)) {
     const envConfig = dotenv.parse(fs.readFileSync(envPath));
-    for (const k in envConfig) {
-      if (!process.env.hasOwnProperty(k)) {
-        if (k === "AGENTBAY_REGION_ID") config.region_id = envConfig[k];
-        else if (k === "AGENTBAY_ENDPOINT") config.endpoint = envConfig[k];
-        else if (k === "AGENTBAY_TIMEOUT_MS") {
-          const timeout = parseInt(envConfig[k], 10);
-          if (!isNaN(timeout) && timeout > 0) {
-            config.timeout_ms = timeout;
-          }
-        }
+    if (!process.env.AGENTBAY_REGION_ID && envConfig.AGENTBAY_REGION_ID) {
+      config.region_id = envConfig.AGENTBAY_REGION_ID;
+    }
+    if (!process.env.AGENTBAY_ENDPOINT && envConfig.AGENTBAY_ENDPOINT) {
+      config.endpoint = envConfig.AGENTBAY_ENDPOINT;
+    }
+    if (!process.env.AGENTBAY_TIMEOUT_MS && envConfig.AGENTBAY_TIMEOUT_MS) {
+      const timeout = parseInt(envConfig.AGENTBAY_TIMEOUT_MS, 10);
+      if (!isNaN(timeout) && timeout > 0) {
+        config.timeout_ms = timeout;
       }
     }
     log(`Loaded .env file at: ${envPath}`);
@@ -5329,7 +5351,7 @@ var _ContextManager = class _ContextManager {
   async info() {
     return this.infoWithParams();
   }
-  async infoWithParams(contextId, path3, taskType) {
+  async infoWithParams(contextId, path4, taskType) {
     const request = new GetContextInfoRequest({
       authorization: `Bearer ${this.session.getAPIKey()}`,
       sessionId: this.session.getSessionId()
@@ -5337,8 +5359,8 @@ var _ContextManager = class _ContextManager {
     if (contextId) {
       request.contextId = contextId;
     }
-    if (path3) {
-      request.path = path3;
+    if (path4) {
+      request.path = path4;
     }
     if (taskType) {
       request.taskType = taskType;
@@ -5388,7 +5410,7 @@ var _ContextManager = class _ContextManager {
   async sync() {
     return this.syncWithParams();
   }
-  async syncWithParams(contextId, path3, mode) {
+  async syncWithParams(contextId, path4, mode) {
     const request = new SyncContextRequest({
       authorization: `Bearer ${this.session.getAPIKey()}`,
       sessionId: this.session.getSessionId()
@@ -5396,8 +5418,8 @@ var _ContextManager = class _ContextManager {
     if (contextId) {
       request.contextId = contextId;
     }
-    if (path3) {
-      request.path = path3;
+    if (path4) {
+      request.path = path4;
     }
     if (mode) {
       request.mode = mode;
@@ -5527,10 +5549,10 @@ var _FileSystem = class _FileSystem {
    * @param path - Path to the directory to create.
    * @returns BoolResult with creation result and requestId
    */
-  async createDirectory(path3) {
+  async createDirectory(path4) {
     try {
       const args = {
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool(
         "create_directory",
@@ -5565,10 +5587,10 @@ var _FileSystem = class _FileSystem {
    * @param dryRun - Optional: If true, preview changes without applying them.
    * @returns BoolResult with edit result and requestId
    */
-  async editFile(path3, edits, dryRun = false) {
+  async editFile(path4, edits, dryRun = false) {
     try {
       const args = {
-        path: path3,
+        path: path4,
         edits,
         dryRun
       };
@@ -5603,10 +5625,10 @@ var _FileSystem = class _FileSystem {
    * @param path - Path to the file or directory to inspect.
    * @returns FileInfoResult with file info and requestId
    */
-  async getFileInfo(path3) {
+  async getFileInfo(path4) {
     try {
       const args = {
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool(
         "get_file_info",
@@ -5649,10 +5671,10 @@ var _FileSystem = class _FileSystem {
    * @param path - Path to the directory to list.
    * @returns DirectoryListResult with directory entries and requestId
    */
-  async listDirectory(path3) {
+  async listDirectory(path4) {
     try {
       const args = {
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool(
         "list_directory",
@@ -5720,18 +5742,17 @@ var _FileSystem = class _FileSystem {
     }
   }
   /**
-   * 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
    */
-  async readFile(path3, offset = 0, length = 0) {
+  async readFileChunk(path4, offset = 0, length = 0) {
     try {
       const args = {
-        path: path3
+        path: path4
       };
       if (offset > 0) {
         args.offset = offset;
@@ -5797,8 +5818,8 @@ var _FileSystem = class _FileSystem {
         for (const line of lines) {
           const colonIndex = line.indexOf(":");
           if (colonIndex > 0 && currentPath === "" && !line.substring(0, colonIndex).includes(" ")) {
-            const path3 = line.substring(0, colonIndex).trim();
-            currentPath = path3;
+            const path4 = line.substring(0, colonIndex).trim();
+            currentPath = path4;
             if (line.length > colonIndex + 1) {
               const contentStart = line.substring(colonIndex + 1).trim();
               if (contentStart) {
@@ -5818,8 +5839,8 @@ var _FileSystem = class _FileSystem {
         if (currentPath) {
           fileContents[currentPath] = currentContent.join("\n");
         }
-        for (const path3 in fileContents) {
-          fileContents[path3] = fileContents[path3].replace(/\n+$/, "");
+        for (const path4 in fileContents) {
+          fileContents[path4] = fileContents[path4].replace(/\n+$/, "");
         }
       }
       return {
@@ -5845,10 +5866,10 @@ var _FileSystem = class _FileSystem {
    * @param excludePatterns - Optional: Array of patterns to exclude.
    * @returns FileSearchResult with search results and requestId
    */
-  async searchFiles(path3, pattern, excludePatterns = []) {
+  async searchFiles(path4, pattern, excludePatterns = []) {
     try {
       const args = {
-        path: path3,
+        path: path4,
         pattern
       };
       if (excludePatterns.length > 0) {
@@ -5885,15 +5906,14 @@ var _FileSystem = class _FileSystem {
     }
   }
   /**
-   * 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
    */
-  async writeFile(path3, content, mode = "overwrite") {
+  async writeFileChunk(path4, content, mode = "overwrite") {
     try {
       const validModes = ["overwrite", "append", "create_new"];
       if (!validModes.includes(mode)) {
@@ -5906,7 +5926,7 @@ var _FileSystem = class _FileSystem {
         };
       }
       const args = {
-        path: path3,
+        path: path4,
         content,
         mode
       };
@@ -5935,16 +5955,15 @@ var _FileSystem = class _FileSystem {
     }
   }
   /**
-   * 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
    */
-  async readLargeFile(path3, chunkSize = DEFAULT_CHUNK_SIZE) {
+  async readFile(path4) {
+    const chunkSize = DEFAULT_CHUNK_SIZE;
     try {
-      const fileInfoResult = await this.getFileInfo(path3);
+      const fileInfoResult = await this.getFileInfo(path4);
       if (!fileInfoResult.success) {
         return {
           requestId: fileInfoResult.requestId,
@@ -5958,7 +5977,7 @@ var _FileSystem = class _FileSystem {
           requestId: fileInfoResult.requestId,
           success: false,
           content: "",
-          errorMessage: `Path does not exist or is a directory: ${path3}`
+          errorMessage: `Path does not exist or is a directory: ${path4}`
         };
       }
       const fileSize = fileInfoResult.fileInfo.size || 0;
@@ -5978,7 +5997,7 @@ var _FileSystem = class _FileSystem {
           length = fileSize - offset;
         }
         try {
-          const chunkResult = await this.readFile(path3, offset, length);
+          const chunkResult = await this.readFileChunk(path4, offset, length);
           if (!chunkResult.success) {
             return chunkResult;
           }
@@ -6009,25 +6028,25 @@ var _FileSystem = class _FileSystem {
     }
   }
   /**
-   * 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
    */
-  async writeLargeFile(path3, content, chunkSize = DEFAULT_CHUNK_SIZE) {
+  async writeFile(path4, content, mode = "overwrite") {
+    const chunkSize = DEFAULT_CHUNK_SIZE;
     try {
       const contentLen = content.length;
       if (contentLen <= chunkSize) {
-        return await this.writeFile(path3, content, "overwrite");
+        return await this.writeFileChunk(path4, content, mode);
       }
       const firstChunkEnd = Math.min(chunkSize, contentLen);
-      const firstResult = await this.writeFile(
-        path3,
+      const firstResult = await this.writeFileChunk(
+        path4,
         content.substring(0, firstChunkEnd),
-        "overwrite"
+        mode
       );
       if (!firstResult.success) {
         return firstResult;
@@ -6035,8 +6054,8 @@ var _FileSystem = class _FileSystem {
       let chunkCount = 1;
       for (let offset = firstChunkEnd; offset < contentLen; ) {
         const end = Math.min(offset + chunkSize, contentLen);
-        const chunkResult = await this.writeFile(
-          path3,
+        const chunkResult = await this.writeFileChunk(
+          path4,
           content.substring(offset, end),
           "append"
         );
@@ -6156,12 +6175,12 @@ var _Oss = class _Oss {
    * @returns OSSUploadResult with upload result and requestId
    * @throws APIError if the operation fails.
    */
-  async upload(bucket, object, path3) {
+  async upload(bucket, object, path4) {
     try {
       const args = {
         bucket,
         object,
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool("oss_upload", args);
       return {
@@ -6188,11 +6207,11 @@ var _Oss = class _Oss {
    * @returns OSSUploadResult with upload result and requestId
    * @throws APIError if the operation fails.
    */
-  async uploadAnonymous(url, path3) {
+  async uploadAnonymous(url, path4) {
     try {
       const args = {
         url,
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool("oss_upload_anonymous", args);
       return {
@@ -6220,12 +6239,12 @@ var _Oss = class _Oss {
    * @returns OSSDownloadResult with download result and requestId
    * @throws APIError if the operation fails.
    */
-  async download(bucket, object, path3) {
+  async download(bucket, object, path4) {
     try {
       const args = {
         bucket,
         object,
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool("oss_download", args);
       return {
@@ -6252,11 +6271,11 @@ var _Oss = class _Oss {
    * @returns OSSDownloadResult with download result and requestId
    * @throws APIError if the operation fails.
    */
-  async downloadAnonymous(url, path3) {
+  async downloadAnonymous(url, path4) {
     try {
       const args = {
         url,
-        path: path3
+        path: path4
       };
       const result = await this.session.callMcpTool("oss_download_anonymous", args);
       return {
@@ -7314,6 +7333,7 @@ var _BrowserOptionClass = class _BrowserOptionClass {
     this.screen = screen;
     this.fingerprint = fingerprint;
     this.proxies = proxies;
+    this.extensionPath = "/tmp/extensions/";
     if (proxies !== void 0) {
       if (!Array.isArray(proxies)) {
         throw new Error("proxies must be a list");
@@ -7325,6 +7345,9 @@ var _BrowserOptionClass = class _BrowserOptionClass {
   }
   toMap() {
     const optionMap = {};
+    if (process.env.AGENTBAY_BROWSER_BEHAVIOR_SIMULATE) {
+      optionMap["behaviorSimulate"] = process.env.AGENTBAY_BROWSER_BEHAVIOR_SIMULATE !== "0";
+    }
     if (this.useStealth !== void 0) {
       optionMap["useStealth"] = this.useStealth;
     }
@@ -7347,6 +7370,9 @@ var _BrowserOptionClass = class _BrowserOptionClass {
     if (this.proxies !== void 0) {
       optionMap["proxies"] = this.proxies.map((proxy) => proxy.toMap());
     }
+    if (this.extensionPath !== void 0) {
+      optionMap["extensionPath"] = this.extensionPath;
+    }
     return optionMap;
   }
   fromMap(m) {
@@ -7384,6 +7410,9 @@ var _BrowserOptionClass = class _BrowserOptionClass {
         return BrowserProxyClass.fromMap(proxyData);
       }).filter(Boolean);
     }
+    if (map.extensionPath !== void 0) {
+      this.extensionPath = map.extensionPath;
+    }
     return this;
   }
 };
@@ -7544,7 +7573,6 @@ var _Session = class _Session {
    * @param sessionId - The ID of this session.
    */
   constructor(agentBay, sessionId) {
-    this.resourceUrl = "";
     // VPC-related information
     this.isVpc = false;
     // Whether this session uses VPC resources
@@ -7555,7 +7583,6 @@ var _Session = class _Session {
     this.mcpTools = [];
     this.agentBay = agentBay;
     this.sessionId = sessionId;
-    this.resourceUrl = "";
     this.fileSystem = new FileSystem(this);
     this.command = new Command(this);
     this.code = new Code(this);
@@ -7845,7 +7872,6 @@ var _Session = class _Session {
       }
       if (data?.resourceUrl) {
         sessionInfo.resourceUrl = data.resourceUrl;
-        this.resourceUrl = data.resourceUrl;
       }
       if (data?.desktopInfo) {
         const desktopInfo = data.desktopInfo;
@@ -8157,6 +8183,7 @@ var _AgentBay = class _AgentBay {
    */
   constructor(options = {}) {
     this.sessions = /* @__PURE__ */ new Map();
+    loadDotEnv();
     this.apiKey = options.apiKey || process.env.AGENTBAY_API_KEY || "";
     if (!this.apiKey) {
       throw new AuthenticationError(
@@ -8289,9 +8316,6 @@ var _AgentBay = class _AgentBay {
       log("session_id =", sessionId);
       log("resource_url =", resourceUrl);
       const session = new Session(this, sessionId);
-      if (resourceUrl) {
-        session.resourceUrl = resourceUrl;
-      }
       session.isVpc = params.isVpc || false;
       if (data.networkInterfaceIp) {
         session.networkInterfaceIp = data.networkInterfaceIp;
@@ -8496,6 +8520,366 @@ var AgentBay = _AgentBay;
 // src/agent/index.ts
 init_esm_shims();
 
+// src/extension.ts
+init_esm_shims();
+import * as fs2 from "fs";
+import * as path3 from "path";
+import * as crypto from "crypto";
+import fetch2 from "node-fetch";
+var EXTENSIONS_BASE_PATH = "/tmp/extensions";
+var _Extension = class _Extension {
+  /**
+   * 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, name, createdAt) {
+    this.id = id;
+    this.name = name;
+    this.createdAt = createdAt;
+  }
+};
+__name(_Extension, "Extension");
+var Extension = _Extension;
+var _ExtensionOption = class _ExtensionOption {
+  /**
+   * 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, extensionIds) {
+    if (!contextId || !contextId.trim()) {
+      throw new Error("contextId cannot be empty");
+    }
+    if (!extensionIds || extensionIds.length === 0) {
+      throw new Error("extensionIds cannot be empty");
+    }
+    this.contextId = contextId;
+    this.extensionIds = extensionIds;
+  }
+  /**
+   * String representation of ExtensionOption.
+   */
+  toString() {
+    return `ExtensionOption(contextId='${this.contextId}', extensionIds=${JSON.stringify(this.extensionIds)})`;
+  }
+  /**
+   * Human-readable string representation.
+   */
+  toDisplayString() {
+    return `Extension Config: ${this.extensionIds.length} extension(s) in context '${this.contextId}'`;
+  }
+  /**
+   * Validate the extension option configuration.
+   * 
+   * @returns True if configuration is valid, false otherwise.
+   */
+  validate() {
+    try {
+      if (!this.contextId || !this.contextId.trim()) {
+        return false;
+      }
+      if (!this.extensionIds || this.extensionIds.length === 0) {
+        return false;
+      }
+      for (const extId of this.extensionIds) {
+        if (typeof extId !== "string" || !extId.trim()) {
+          return false;
+        }
+      }
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+};
+__name(_ExtensionOption, "ExtensionOption");
+var ExtensionOption = _ExtensionOption;
+var _ExtensionsService = class _ExtensionsService {
+  /**
+   * 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, contextId = "") {
+    this._initializationPromise = null;
+    if (!agentBay) {
+      throw new AgentBayError("AgentBay instance is required");
+    }
+    if (!agentBay.context) {
+      throw new AgentBayError("AgentBay instance must have a context service");
+    }
+    this.agentBay = agentBay;
+    this.contextService = agentBay.context;
+    this.autoCreated = true;
+    if (!contextId || contextId.trim() === "") {
+      contextId = `extensions-${Math.floor(Date.now() / 1e3)}`;
+      log(`Generated default context name: ${contextId}`);
+    }
+    this.contextName = contextId;
+    this._initializationPromise = this._initializeContext();
+  }
+  /**
+   * Internal method to initialize the context.
+   * This ensures the context is ready before any operations.
+   */
+  async _initializeContext() {
+    try {
+      const contextResult = await this.contextService.get(this.contextName, true);
+      if (!contextResult.success || !contextResult.context) {
+        throw new AgentBayError(`Failed to create extension repository context: ${this.contextName}`);
+      }
+      this.extensionContext = contextResult.context;
+      this.contextId = this.extensionContext.id;
+    } catch (error) {
+      throw new AgentBayError(`Failed to initialize ExtensionsService: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  /**
+   * Ensures the service is initialized before performing operations.
+   */
+  async _ensureInitialized() {
+    if (this._initializationPromise) {
+      await this._initializationPromise;
+      this._initializationPromise = null;
+    }
+  }
+  /**
+   * 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.
+   */
+  async _uploadToCloud(localPath, remotePath) {
+    try {
+      const urlResult = await this.contextService.getFileUploadUrl(this.contextId, remotePath);
+      if (!urlResult.success || !urlResult.url) {
+        throw new AgentBayError(`Failed to get upload URL: ${urlResult.url || "No URL returned"}`);
+      }
+      const preSignedUrl = urlResult.url;
+      const fileBuffer = fs2.readFileSync(localPath);
+      const response = await fetch2(preSignedUrl, {
+        method: "PUT",
+        body: fileBuffer
+      });
+      if (!response.ok) {
+        throw new AgentBayError(`HTTP error uploading file: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      if (error instanceof AgentBayError) {
+        throw error;
+      }
+      throw new AgentBayError(`An error occurred while uploading the file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  /**
+   * 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.
+   */
+  async list() {
+    await this._ensureInitialized();
+    try {
+      const fileListResult = await this.contextService.listFiles(
+        this.contextId,
+        EXTENSIONS_BASE_PATH,
+        1,
+        // pageNumber
+        100
+        // pageSize - reasonable limit for extensions
+      );
+      if (!fileListResult.success) {
+        throw new AgentBayError("Failed to list extensions: Context file listing failed.");
+      }
+      const extensions = [];
+      for (const fileEntry of fileListResult.entries) {
+        const extensionId = fileEntry.fileName || fileEntry.filePath;
+        extensions.push(new Extension(
+          extensionId,
+          fileEntry.fileName || extensionId,
+          fileEntry.gmtCreate
+        ));
+      }
+      return extensions;
+    } catch (error) {
+      if (error instanceof AgentBayError) {
+        throw error;
+      }
+      throw new AgentBayError(`An error occurred while listing browser extensions: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  /**
+   * 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.
+   */
+  async create(localPath) {
+    await this._ensureInitialized();
+    if (!fs2.existsSync(localPath)) {
+      throw new Error(`The specified local file was not found: ${localPath}`);
+    }
+    const fileExtension = path3.extname(localPath).toLowerCase();
+    if (fileExtension !== ".zip") {
+      throw new Error(`Unsupported plugin format '${fileExtension}'. Only ZIP format (.zip) is supported.`);
+    }
+    const extensionId = `ext_${crypto.randomBytes(16).toString("hex")}${fileExtension}`;
+    const extensionName = path3.basename(localPath);
+    const remotePath = `${EXTENSIONS_BASE_PATH}/${extensionId}`;
+    await this._uploadToCloud(localPath, remotePath);
+    return new Extension(extensionId, extensionName);
+  }
+  /**
+   * 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.
+   */
+  async update(extensionId, newLocalPath) {
+    await this._ensureInitialized();
+    if (!fs2.existsSync(newLocalPath)) {
+      throw new Error(`The specified new local file was not found: ${newLocalPath}`);
+    }
+    const existingExtensions = await this.list();
+    const extensionExists = existingExtensions.some((ext) => ext.id === extensionId);
+    if (!extensionExists) {
+      throw new Error(`Browser extension with ID '${extensionId}' not found in the context. Cannot update.`);
+    }
+    const remotePath = `${EXTENSIONS_BASE_PATH}/${extensionId}`;
+    await this._uploadToCloud(newLocalPath, remotePath);
+    return new Extension(extensionId, path3.basename(newLocalPath));
+  }
+  /**
+   * 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.
+   */
+  async _getExtensionInfo(extensionId) {
+    await this._ensureInitialized();
+    try {
+      const extensions = await this.list();
+      return extensions.find((ext) => ext.id === extensionId);
+    } catch (error) {
+      logError(`An error occurred while getting extension info for '${extensionId}':`, error);
+      return void 0;
+    }
+  }
+  /**
+   * 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.
+   */
+  async cleanup() {
+    await this._ensureInitialized();
+    if (!this.autoCreated) {
+      return true;
+    }
+    try {
+      const deleteResult = await this.contextService.delete(this.extensionContext);
+      if (deleteResult) {
+        log(`Extension context deleted: ${this.contextName} (ID: ${this.contextId})`);
+        return true;
+      } else {
+        logError(`Warning: Failed to delete extension context: ${this.contextName}`, new Error("Delete operation returned false"));
+        return false;
+      }
+    } catch (error) {
+      logError(`Warning: Failed to delete extension context:`, error);
+      return false;
+    }
+  }
+  /**
+   * 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.
+   */
+  async delete(extensionId) {
+    await this._ensureInitialized();
+    const remotePath = `${EXTENSIONS_BASE_PATH}/${extensionId}`;
+    try {
+      const deleteResult = await this.contextService.deleteFile(this.contextId, remotePath);
+      return deleteResult.success;
+    } catch (error) {
+      logError(`An error occurred while deleting browser extension '${extensionId}':`, error);
+      return false;
+    }
+  }
+  /**
+   * 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) {
+    if (!this.contextId) {
+      throw new Error("Service not initialized. Please call an async method first or ensure context is created.");
+    }
+    return new ExtensionOption(
+      this.contextId,
+      extensionIds
+    );
+  }
+};
+__name(_ExtensionsService, "ExtensionsService");
+var ExtensionsService = _ExtensionsService;
+
 // src/context-sync.ts
 init_esm_shims();
 var UploadStrategy = /* @__PURE__ */ ((UploadStrategy2) => {
@@ -8506,12 +8890,41 @@ var DownloadStrategy = /* @__PURE__ */ ((DownloadStrategy2) => {
   DownloadStrategy2["DownloadAsync"] = "DownloadAsync";
   return DownloadStrategy2;
 })(DownloadStrategy || {});
+var _ExtractPolicyClass = class _ExtractPolicyClass {
+  constructor(extract = true, deleteSrcFile = true, extractToCurrentFolder = false) {
+    this.extract = true;
+    this.deleteSrcFile = true;
+    this.extractToCurrentFolder = false;
+    this.extract = extract;
+    this.deleteSrcFile = deleteSrcFile;
+    this.extractToCurrentFolder = extractToCurrentFolder;
+  }
+  /**
+   * Creates a new extract policy with default values
+   */
+  static default() {
+    return new _ExtractPolicyClass();
+  }
+  /**
+   * Converts to plain object for JSON serialization
+   */
+  toDict() {
+    return {
+      extract: this.extract,
+      deleteSrcFile: this.deleteSrcFile,
+      extractToCurrentFolder: this.extractToCurrentFolder
+    };
+  }
+};
+__name(_ExtractPolicyClass, "ExtractPolicyClass");
+var ExtractPolicyClass = _ExtractPolicyClass;
 var _SyncPolicyImpl = class _SyncPolicyImpl {
   constructor(policy) {
     if (policy) {
       this.uploadPolicy = policy.uploadPolicy;
       this.downloadPolicy = policy.downloadPolicy;
       this.deletePolicy = policy.deletePolicy;
+      this.extractPolicy = policy.extractPolicy;
       this.bwList = policy.bwList;
     }
     this.ensureDefaults();
@@ -8526,6 +8939,9 @@ var _SyncPolicyImpl = class _SyncPolicyImpl {
     if (!this.deletePolicy) {
       this.deletePolicy = newDeletePolicy();
     }
+    if (!this.extractPolicy) {
+      this.extractPolicy = newExtractPolicy();
+    }
     if (!this.bwList) {
       this.bwList = {
         whiteLists: [
@@ -8543,6 +8959,7 @@ var _SyncPolicyImpl = class _SyncPolicyImpl {
       uploadPolicy: this.uploadPolicy,
       downloadPolicy: this.downloadPolicy,
       deletePolicy: this.deletePolicy,
+      extractPolicy: this.extractPolicy,
       bwList: this.bwList
     };
   }
@@ -8550,9 +8967,9 @@ var _SyncPolicyImpl = class _SyncPolicyImpl {
 __name(_SyncPolicyImpl, "SyncPolicyImpl");
 var SyncPolicyImpl = _SyncPolicyImpl;
 var _ContextSync = class _ContextSync {
-  constructor(contextId, path3, policy) {
+  constructor(contextId, path4, policy) {
     this.contextId = contextId;
-    this.path = path3;
+    this.path = path4;
     this.policy = policy;
   }
   // WithPolicy sets the policy and returns the context sync for chaining
@@ -8585,11 +9002,20 @@ function newDeletePolicy() {
   };
 }
 __name(newDeletePolicy, "newDeletePolicy");
+function newExtractPolicy() {
+  return {
+    extract: true,
+    deleteSrcFile: true,
+    extractToCurrentFolder: false
+  };
+}
+__name(newExtractPolicy, "newExtractPolicy");
 function newSyncPolicy() {
   return {
     uploadPolicy: newUploadPolicy(),
     downloadPolicy: newDownloadPolicy(),
     deletePolicy: newDeletePolicy(),
+    extractPolicy: newExtractPolicy(),
     bwList: {
       whiteLists: [
         {
@@ -8605,13 +9031,98 @@ function newSyncPolicyWithDefaults(policy) {
   return new SyncPolicyImpl(policy).toJSON();
 }
 __name(newSyncPolicyWithDefaults, "newSyncPolicyWithDefaults");
-function newContextSync(contextId, path3, policy) {
-  return new ContextSync(contextId, path3, policy);
+function newContextSync(contextId, path4, policy) {
+  return new ContextSync(contextId, path4, policy);
 }
 __name(newContextSync, "newContextSync");
 
 // src/session-params.ts
 init_esm_shims();
+var _BrowserContext = class _BrowserContext {
+  /**
+   * 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, autoUpload = true, extensionOption) {
+    this.contextId = contextId;
+    this.autoUpload = autoUpload;
+    this.extensionOption = extensionOption;
+    if (extensionOption) {
+      this.extensionContextId = extensionOption.contextId;
+      this.extensionIds = extensionOption.extensionIds;
+      this.extensionContextSyncs = this._createExtensionContextSyncs();
+    } else {
+      this.extensionContextId = void 0;
+      this.extensionIds = [];
+      this.extensionContextSyncs = void 0;
+    }
+  }
+  /**
+   * 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.
+   */
+  _createExtensionContextSyncs() {
+    if (!this.extensionIds || this.extensionIds.length === 0 || !this.extensionContextId) {
+      return [];
+    }
+    const whiteLists = this.extensionIds.map((extId) => ({
+      path: extId,
+      excludePaths: []
+    }));
+    const syncPolicy = {
+      uploadPolicy: {
+        ...newUploadPolicy(),
+        autoUpload: false
+      },
+      extractPolicy: {
+        ...newExtractPolicy(),
+        extract: true,
+        deleteSrcFile: true
+      },
+      bwList: {
+        whiteLists
+      }
+    };
+    const extensionSync = new ContextSync(
+      this.extensionContextId,
+      "/tmp/extensions/",
+      syncPolicy
+    );
+    return [extensionSync];
+  }
+  /**
+   * Get all context syncs including extension syncs.
+   * 
+   * @returns ContextSync[] - All context sync configurations. Returns empty list if no extensions configured.
+   */
+  getAllContextSyncs() {
+    return this.extensionContextSyncs || [];
+  }
+};
+__name(_BrowserContext, "BrowserContext");
+var BrowserContext = _BrowserContext;
 var _CreateSessionParams = class _CreateSessionParams {
   constructor() {
     this.labels = {};
@@ -8674,8 +9185,8 @@ var _CreateSessionParams = class _CreateSessionParams {
   /**
    * AddContextSync adds a context sync configuration to the session parameters.
    */
-  addContextSync(contextId, path3, policy) {
-    const contextSync = new ContextSync(contextId, path3, policy);
+  addContextSync(contextId, path4, policy) {
+    const contextSync = new ContextSync(contextId, path4, policy);
     this.contextSync.push(contextSync);
     return this;
   }
@@ -8697,10 +9208,15 @@ var _CreateSessionParams = class _CreateSessionParams {
    * Convert to plain object for JSON serialization
    */
   toJSON() {
+    let allContextSyncs = [...this.contextSync];
+    if (this.browserContext && "getAllContextSyncs" in this.browserContext) {
+      const extensionSyncs = this.browserContext.getAllContextSyncs();
+      allContextSyncs = allContextSyncs.concat(extensionSyncs);
+    }
     return {
       labels: this.labels,
       imageId: this.imageId,
-      contextSync: this.contextSync,
+      contextSync: allContextSyncs,
       browserContext: this.browserContext,
       isVpc: this.isVpc,
       mcpPolicyId: this.mcpPolicyId
@@ -8714,7 +9230,18 @@ var _CreateSessionParams = class _CreateSessionParams {
     params.labels = config.labels || {};
     params.imageId = config.imageId;
     params.contextSync = config.contextSync || [];
-    params.browserContext = config.browserContext;
+    if (config.browserContext) {
+      if ("getAllContextSyncs" in config.browserContext) {
+        params.browserContext = config.browserContext;
+      } else {
+        const bc = config.browserContext;
+        params.browserContext = new BrowserContext(
+          bc.contextId,
+          bc.autoUpload,
+          bc.extensionOption
+        );
+      }
+    }
     params.isVpc = config.isVpc || false;
     params.mcpPolicyId = config.mcpPolicyId;
     return params;
@@ -8740,6 +9267,7 @@ export {
   AuthenticationError,
   Browser,
   BrowserAgent,
+  BrowserContext,
   BrowserError,
   BrowserOptionClass,
   BrowserProxyClass,
@@ -8770,6 +9298,10 @@ export {
   DescribeContextFilesResponse,
   DescribeContextFilesResponseBody,
   DownloadStrategy,
+  Extension,
+  ExtensionOption,
+  ExtensionsService,
+  ExtractPolicyClass,
   FileError,
   FileSystem,
   GetContextFileDownloadUrlRequest,
@@ -8835,6 +9367,8 @@ export {
   UI,
   UIError,
   UploadStrategy,
+  loadConfig,
+  loadDotEnv,
   log,
   logError,
   newContextManager,
@@ -8842,6 +9376,7 @@ export {
   newCreateSessionParams,
   newDeletePolicy,
   newDownloadPolicy,
+  newExtractPolicy,
   newSyncPolicy,
   newSyncPolicyWithDefaults,
   newUploadPolicy