browser-use 0.2.0 → 0.3.0

package/dist/mcp/server.js

@@ -29,15 +29,16 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
 import { createLogger } from '../logging-config.js';
 import { Controller as DefaultController } from '../controller/service.js';
 import { Agent } from '../agent/service.js';
 import { BrowserSession } from '../browser/session.js';
+import { BrowserStateRequestEvent } from '../browser/events.js';
 import { BrowserProfile } from '../browser/profile.js';
 import { FileSystem } from '../filesystem/file-system.js';
-import { ChatOpenAI } from '../llm/openai/chat.js';
+import { getLlmByName } from '../llm/models.js';
 import { load_browser_use_config, get_default_llm, get_default_profile, } from '../config.js';
+import { zodSchemaToJsonSchema } from '../llm/schema.js';
 import { productTelemetry } from '../telemetry/service.js';
 import { MCPServerTelemetryEvent } from '../telemetry/views.js';
 import { get_browser_use_version } from '../utils.js';
@@ -64,6 +65,9 @@ export class MCPServer {
     toolExecutionCount = 0;
     errorCount = 0;
     abortController = null;
+    activeSessions = new Map();
+    sessionTimeoutMinutes = 10;
+    sessionCleanupInterval = null;
     constructor(name, version) {
         this.server = new Server({
             name,
@@ -75,6 +79,11 @@ export class MCPServer {
             },
         });
         this.config = load_browser_use_config();
+        const configuredTimeout = Number(process.env.BROWSER_USE_MCP_SESSION_TIMEOUT_MINUTES ?? '10');
+        this.sessionTimeoutMinutes =
+            Number.isFinite(configuredTimeout) && configuredTimeout > 0
+                ? configuredTimeout
+                : 10;
         this.startTime = Date.now() / 1000;
         this.setupHandlers();
         this.registerDefaultPrompts();
@@ -94,6 +103,20 @@ export class MCPServer {
         const llm = get_default_llm(this.config);
         return llm && typeof llm === 'object' ? { ...llm } : {};
     }
+    seedOpenAiApiKeyFromConfig(llmConfig) {
+        if (typeof process.env.OPENAI_API_KEY === 'string' &&
+            process.env.OPENAI_API_KEY.trim()) {
+            return;
+        }
+        const configuredApiKey = typeof llmConfig.api_key === 'string' ? llmConfig.api_key.trim() : '';
+        if (configuredApiKey) {
+            process.env.OPENAI_API_KEY = configuredApiKey;
+        }
+    }
+    createLlmFromModelName(modelName, llmConfig) {
+        this.seedOpenAiApiKeyFromConfig(llmConfig);
+        return getLlmByName(modelName);
+    }
     sanitizeProfileConfig(profileConfig) {
         const sanitized = { ...profileConfig };
         delete sanitized.id;
@@ -104,7 +127,7 @@ export class MCPServer {
     buildDirectSessionProfile(profileConfig) {
         const merged = {
             downloads_path: '~/Downloads/browser-use-mcp',
-            wait_between_actions: 0.5,
+            wait_between_actions: 0.1,
             keep_alive: true,
             user_data_dir: '~/.config/browseruse/profiles/default',
             is_mobile: false,
@@ -124,6 +147,11 @@ export class MCPServer {
                 .map((entry) => String(entry).trim())
                 .filter(Boolean);
         }
+        if (Array.isArray(merged.prohibited_domains)) {
+            merged.prohibited_domains = merged.prohibited_domains
+                .map((entry) => String(entry).trim())
+                .filter(Boolean);
+        }
         return new BrowserProfile(merged);
     }
     buildRetryProfile(profileConfig, allowedDomains) {
@@ -147,6 +175,11 @@ export class MCPServer {
                 .map((entry) => String(entry).trim())
                 .filter(Boolean);
         }
+        if (Array.isArray(merged.prohibited_domains)) {
+            merged.prohibited_domains = merged.prohibited_domains
+                .map((entry) => String(entry).trim())
+                .filter(Boolean);
+        }
         return new BrowserProfile(merged);
     }
     initializeLlmForDirectTools() {
@@ -154,23 +187,15 @@ export class MCPServer {
             return;
         }
         const llmConfig = this.getDefaultLlmConfig();
-        const configuredApiKey = typeof llmConfig.api_key === 'string' ? llmConfig.api_key.trim() : '';
-        const envApiKey = typeof process.env.OPENAI_API_KEY === 'string'
-            ? process.env.OPENAI_API_KEY.trim()
-            : '';
-        const apiKey = configuredApiKey || envApiKey;
-        if (!apiKey) {
-            return;
-        }
         const model = typeof llmConfig.model === 'string' && llmConfig.model.trim()
             ? llmConfig.model.trim()
             : 'gpt-4o-mini';
-        const temperature = typeof llmConfig.temperature === 'number' ? llmConfig.temperature : 0.7;
-        this.llm = new ChatOpenAI({
-            model,
-            apiKey,
-            temperature,
-        });
+        try {
+            this.llm = this.createLlmFromModelName(model, llmConfig);
+        }
+        catch (error) {
+            logger.debug(`Skipping MCP direct-tools LLM initialization for model "${model}": ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     initializeFileSystem(profileConfig) {
         if (this.fileSystem) {
@@ -212,6 +237,126 @@ export class MCPServer {
         }
         return results.join('\n');
     }
+    trackSession(session) {
+        const now = Date.now() / 1000;
+        const existing = this.activeSessions.get(session.id);
+        if (existing) {
+            existing.session = session;
+            existing.last_activity = now;
+            return;
+        }
+        this.activeSessions.set(session.id, {
+            session,
+            created_at: now,
+            last_activity: now,
+        });
+    }
+    updateSessionActivity(session) {
+        if (!session) {
+            return;
+        }
+        const tracked = this.activeSessions.get(session.id);
+        if (!tracked) {
+            this.trackSession(session);
+            return;
+        }
+        tracked.last_activity = Date.now() / 1000;
+    }
+    serializeTrackedSessions() {
+        const now = Date.now() / 1000;
+        return Array.from(this.activeSessions.entries()).map(([session_id, tracked]) => ({
+            session_id,
+            created_at: tracked.created_at,
+            last_activity: tracked.last_activity,
+            age_minutes: (now - tracked.created_at) / 60,
+            active: Boolean(tracked.session?.initialized),
+            current_session: this.browserSession?.id === session_id,
+        }));
+    }
+    async shutdownSession(session) {
+        const withKill = session;
+        if (typeof withKill.kill === 'function') {
+            await withKill.kill();
+            return;
+        }
+        if (typeof session.stop === 'function') {
+            await session.stop();
+        }
+    }
+    async closeSessionById(sessionId) {
+        const tracked = this.activeSessions.get(sessionId);
+        if (!tracked) {
+            return {
+                session_id: sessionId,
+                closed: false,
+                message: `Session ${sessionId} not found`,
+            };
+        }
+        try {
+            await this.shutdownSession(tracked.session);
+            this.activeSessions.delete(sessionId);
+            if (this.browserSession?.id === sessionId) {
+                this.browserSession = null;
+            }
+            return {
+                session_id: sessionId,
+                closed: true,
+                message: `Closed session ${sessionId}`,
+            };
+        }
+        catch (error) {
+            return {
+                session_id: sessionId,
+                closed: false,
+                message: `Failed to close session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async closeAllTrackedSessions() {
+        const sessionIds = Array.from(this.activeSessions.keys());
+        const results = await Promise.all(sessionIds.map((sessionId) => this.closeSessionById(sessionId)));
+        const closedCount = results.filter((result) => result.closed).length;
+        return {
+            closed_count: closedCount,
+            total_count: sessionIds.length,
+            results,
+        };
+    }
+    async cleanupExpiredSessions() {
+        const now = Date.now() / 1000;
+        const timeoutSeconds = this.sessionTimeoutMinutes * 60;
+        const expiredSessionIds = [];
+        for (const [sessionId, tracked] of this.activeSessions.entries()) {
+            if (now - tracked.last_activity > timeoutSeconds) {
+                expiredSessionIds.push(sessionId);
+            }
+        }
+        for (const sessionId of expiredSessionIds) {
+            const result = await this.closeSessionById(sessionId);
+            if (!result.closed) {
+                logger.warning(result.message);
+            }
+        }
+    }
+    startSessionCleanupLoop() {
+        if (this.sessionCleanupInterval) {
+            return;
+        }
+        this.sessionCleanupInterval = setInterval(() => {
+            this.cleanupExpiredSessions().catch((error) => {
+                logger.warning(`MCP session cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }, 120_000);
+        // Do not keep the Node process alive solely because of the cleanup loop.
+        this.sessionCleanupInterval.unref?.();
+    }
+    stopSessionCleanupLoop() {
+        if (!this.sessionCleanupInterval) {
+            return;
+        }
+        clearInterval(this.sessionCleanupInterval);
+        this.sessionCleanupInterval = null;
+    }
     setupHandlers() {
         // List available tools
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -315,19 +460,23 @@ export class MCPServer {
             const profileConfig = this.getDefaultProfileConfig();
             const profile = this.buildDirectSessionProfile(profileConfig);
             this.browserSession = new BrowserSession({ browser_profile: profile });
+            this.trackSession(this.browserSession);
             this.initializeLlmForDirectTools();
             this.initializeFileSystem(profileConfig);
         }
         if (!this.browserSession.initialized) {
             await this.browserSession.start();
         }
+        this.trackSession(this.browserSession);
+        this.updateSessionActivity(this.browserSession);
         return this.browserSession;
     }
     async executeControllerAction(actionName, args) {
         const controller = await this.ensureController();
         const browserSession = await this.ensureBrowserSession();
+        this.updateSessionActivity(browserSession);
         if (actionName === 'extract_structured_data' && !this.llm) {
-            throw new Error('LLM not initialized (set OPENAI_API_KEY)');
+            throw new Error('LLM not initialized. Set provider API key env vars and configure BROWSER_USE_LLM_MODEL/DEFAULT_LLM to a supported model.');
         }
         return await controller.registry.execute_action(actionName, args, {
             browser_session: browserSession,
@@ -409,13 +558,26 @@ export class MCPServer {
         this.registerTool('browser_get_state', 'Get the current state of the page including interactive elements', z
             .object({
             include_screenshot: z.boolean().default(false),
+            include_recent_events: z.boolean().default(false),
         })
-            .default({ include_screenshot: false }), async (args) => {
+            .default({ include_screenshot: false, include_recent_events: false }), async (args) => {
             const browserSession = await this.ensureBrowserSession();
-            const state = await browserSession.get_browser_state_with_recovery({
-                include_screenshot: Boolean(args?.include_screenshot),
-                cache_clickable_elements_hashes: true,
-            });
+            let state = null;
+            if (typeof browserSession.dispatch_browser_event === 'function') {
+                const dispatchResult = await browserSession.dispatch_browser_event(new BrowserStateRequestEvent({
+                    include_dom: true,
+                    include_screenshot: Boolean(args?.include_screenshot),
+                    include_recent_events: Boolean(args?.include_recent_events),
+                }));
+                state = dispatchResult?.event?.event_result ?? null;
+            }
+            if (!state) {
+                state = await browserSession.get_browser_state_with_recovery({
+                    include_screenshot: Boolean(args?.include_screenshot),
+                    include_recent_events: Boolean(args?.include_recent_events),
+                    cache_clickable_elements_hashes: true,
+                });
+            }
             return {
                 url: state.url,
                 title: state.title,
@@ -425,6 +587,10 @@ export class MCPServer {
                 pixels_below: state.pixels_below,
                 browser_errors: state.browser_errors,
                 loading_status: state.loading_status,
+                recent_events: state.recent_events,
+                pending_network_requests: state.pending_network_requests,
+                pagination_buttons: state.pagination_buttons,
+                closed_popup_messages: state.closed_popup_messages,
                 screenshot: state.screenshot,
                 interactive_elements: state.element_tree.clickable_elements_to_string(),
                 interactive_count: Object.keys(state.selector_map ?? {}).length,
@@ -450,16 +616,57 @@ export class MCPServer {
             const browserSession = await this.ensureBrowserSession();
             return browserSession.get_tabs_info();
         });
-        this.registerTool('browser_switch_tab', 'Switch to a tab by index', z.object({
-            tab_index: z.number().int(),
-        }), async (args) => this.executeControllerAction('switch_tab', {
-            page_id: Number(args?.tab_index),
-        }));
-        this.registerTool('browser_close_tab', 'Close a tab by index', z.object({
-            tab_index: z.number().int(),
-        }), async (args) => this.executeControllerAction('close_tab', {
-            page_id: Number(args?.tab_index),
-        }));
+        this.registerTool('browser_switch_tab', 'Switch to a tab by tab_id (or page_id/tab_index for compatibility)', z
+            .object({
+            tab_id: z.string().trim().length(4).optional(),
+            page_id: z.number().int().optional(),
+            tab_index: z.number().int().optional(),
+        })
+            .refine((value) => value.tab_id != null ||
+            value.page_id != null ||
+            value.tab_index != null, { message: 'Provide tab_id, page_id, or tab_index' }), async (args) => {
+            const tabId = typeof args?.tab_id === 'string' && args.tab_id.trim()
+                ? args.tab_id.trim()
+                : null;
+            if (tabId) {
+                return this.executeControllerAction('switch_tab', { tab_id: tabId });
+            }
+            const pageId = typeof args?.page_id === 'number' && Number.isFinite(args.page_id)
+                ? Number(args.page_id)
+                : Number(args?.tab_index);
+            return this.executeControllerAction('switch_tab', {
+                page_id: pageId,
+            });
+        });
+        this.registerTool('browser_close_tab', 'Close a tab by tab_id (or page_id/tab_index for compatibility)', z
+            .object({
+            tab_id: z.string().trim().length(4).optional(),
+            page_id: z.number().int().optional(),
+            tab_index: z.number().int().optional(),
+        })
+            .refine((value) => value.tab_id != null ||
+            value.page_id != null ||
+            value.tab_index != null, { message: 'Provide tab_id, page_id, or tab_index' }), async (args) => {
+            const tabId = typeof args?.tab_id === 'string' && args.tab_id.trim()
+                ? args.tab_id.trim()
+                : null;
+            if (tabId) {
+                return this.executeControllerAction('close_tab', { tab_id: tabId });
+            }
+            const pageId = typeof args?.page_id === 'number' && Number.isFinite(args.page_id)
+                ? Number(args.page_id)
+                : Number(args?.tab_index);
+            return this.executeControllerAction('close_tab', {
+                page_id: pageId,
+            });
+        });
+        this.registerTool('browser_list_sessions', 'List active browser sessions managed by this MCP server', z.object({}).strict(), async () => {
+            return this.serializeTrackedSessions();
+        });
+        this.registerTool('browser_close_session', 'Close a specific browser session by session_id', z.object({
+            session_id: z.string().trim().min(1),
+        }), async (args) => this.closeSessionById(String(args?.session_id ?? '')));
+        this.registerTool('browser_close_all', 'Close all active browser sessions managed by this MCP server', z.object({}).strict(), async () => this.closeAllTrackedSessions());
         this.registerTool('retry_with_browser_use_agent', 'Retry a complex task with the browser-use autonomous agent', z.object({
             task: z.string(),
             max_steps: z.number().int().optional().default(100),
@@ -480,26 +687,17 @@ export class MCPServer {
                     .filter(Boolean)
                 : [];
             const llmConfig = this.getDefaultLlmConfig();
-            const configuredApiKey = typeof llmConfig.api_key === 'string' ? llmConfig.api_key.trim() : '';
-            const envApiKey = typeof process.env.OPENAI_API_KEY === 'string'
-                ? process.env.OPENAI_API_KEY.trim()
-                : '';
-            const apiKey = configuredApiKey || envApiKey;
-            if (!apiKey) {
-                return 'Error: OPENAI_API_KEY not set in config or environment';
-            }
             const configuredModel = typeof llmConfig.model === 'string' && llmConfig.model.trim()
                 ? llmConfig.model.trim()
                 : 'gpt-4o';
             const llmModel = model || configuredModel;
-            const temperature = typeof llmConfig.temperature === 'number'
-                ? llmConfig.temperature
-                : 0.7;
-            const llm = new ChatOpenAI({
-                model: llmModel,
-                apiKey,
-                temperature,
-            });
+            let llm;
+            try {
+                llm = this.createLlmFromModelName(llmModel, llmConfig);
+            }
+            catch (error) {
+                return `Error: Failed to initialize LLM "${llmModel}": ${error instanceof Error ? error.message : String(error)}`;
+            }
             const profileConfig = this.getDefaultProfileConfig();
             const profile = this.buildRetryProfile(profileConfig, allowedDomains);
             const retryBrowserSession = new BrowserSession({
@@ -596,7 +794,7 @@ export class MCPServer {
         this.tools[name] = {
             description,
             inputSchema: inputSchema instanceof z.ZodType
-                ? zodToJsonSchema(inputSchema)
+                ? zodSchemaToJsonSchema(inputSchema)
                 : inputSchema,
             handler,
         };
@@ -624,7 +822,10 @@ export class MCPServer {
      */
     async initBrowserSession(browserSession) {
         this.browserSession = browserSession;
+        this.trackSession(browserSession);
         await this.browserSession.start();
+        this.trackSession(this.browserSession);
+        this.updateSessionActivity(this.browserSession);
         logger.info('Browser session initialized');
     }
     /**
@@ -644,6 +845,7 @@ export class MCPServer {
             const transport = new StdioServerTransport();
             await this.server.connect(transport);
             this.isRunning = true;
+            this.startSessionCleanupLoop();
             logger.info(`🔌 MCP Server started (${this.getToolCount()} tools, ${this.getPromptCount()} prompts registered)`);
         }
         catch (error) {
@@ -662,14 +864,15 @@ export class MCPServer {
         }
         try {
             this.isRunning = false;
+            this.stopSessionCleanupLoop();
             // Cancel any pending operations
             if (this.abortController) {
                 this.abortController.abort();
                 this.abortController = null;
             }
             // Close browser session if active
-            if (this.browserSession) {
-                await this.browserSession.stop();
+            if (this.activeSessions.size > 0) {
+                await this.closeAllTrackedSessions();
                 this.browserSession = null;
                 logger.info('Browser session closed');
             }

package/dist/observability.js

@@ -12,7 +12,7 @@ try {
         lmnrObserve = (options) => lmnr.observe(options);
         lmnrAvailable = true;
         if (process.env.BROWSER_USE_VERBOSE_OBSERVABILITY?.toLowerCase() === 'true') {
-            logger.info('Lmnr is available for observability');
+            logger.debug('Lmnr is available for observability');
         }
     }
 }
@@ -20,7 +20,7 @@ catch (error) {
     lmnrObserve = null;
     lmnrAvailable = false;
     if (process.env.BROWSER_USE_VERBOSE_OBSERVABILITY?.toLowerCase() === 'true') {
-        logger.info(`Lmnr is not available for observability (${error.message})`);
+        logger.debug(`Lmnr is not available for observability (${error.message})`);
     }
 }
 const isDebugModeEnv = () => process.env.LMNR_LOGGING_LEVEL?.toLowerCase() === 'debug';
@@ -34,14 +34,20 @@ const normalizeOptions = (options = {}) => ({
     ...options,
 });
 export const observe = (options = {}) => {
-    const normalized = normalizeOptions(options);
+    const normalized = normalizeOptions({
+        tags: ['observe', 'observe_debug'],
+        ...options,
+    });
     if (lmnrAvailable && lmnrObserve) {
         return lmnrObserve(normalized);
     }
     return createNoopDecorator();
 };
 export const observeDebug = (options = {}) => {
-    const normalized = normalizeOptions(options);
+    const normalized = normalizeOptions({
+        tags: ['observe_debug'],
+        ...options,
+    });
     if (lmnrAvailable && lmnrObserve && isDebugModeEnv()) {
         return lmnrObserve(normalized);
     }

package/dist/sandbox/index.d.ts

@@ -0,0 +1,2 @@
+export * from './views.js';
+export * from './sandbox.js';

package/dist/sandbox/index.js

@@ -0,0 +1,2 @@
+export * from './views.js';
+export * from './sandbox.js';

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,19 @@
+import { BrowserCreatedData, ErrorData, LogData, ResultData, SandboxError } from './views.js';
+export interface SandboxOptions {
+    api_key?: string | null;
+    server_url?: string | null;
+    log_level?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | string;
+    quiet?: boolean;
+    headers?: Record<string, string>;
+    cloud_profile_id?: string | null;
+    cloud_proxy_country_code?: string | null;
+    cloud_timeout?: number | null;
+    fetch_impl?: typeof fetch;
+    on_browser_created?: (event: BrowserCreatedData) => void | Promise<void>;
+    on_instance_ready?: () => void | Promise<void>;
+    on_log?: (event: LogData) => void | Promise<void>;
+    on_result?: (event: ResultData) => void | Promise<void>;
+    on_error?: (event: ErrorData) => void | Promise<void>;
+}
+export declare const sandbox: (options?: SandboxOptions) => <TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult> | TResult) => (...args: TArgs) => Promise<TResult>;
+export { SandboxError };

package/dist/sandbox/sandbox.js

@@ -0,0 +1,140 @@
+import { createLogger } from '../logging-config.js';
+import { BrowserCreatedData, ErrorData, LogData, ResultData, SandboxError, SSEEvent, SSEEventType, } from './views.js';
+const logger = createLogger('browser_use.sandbox');
+const defaultServerUrl = 'https://sandbox.api.browser-use.com/sandbox-stream';
+const maybeInvoke = async (callback, data) => {
+    if (!callback) {
+        return;
+    }
+    await callback(data);
+};
+const parseSSEChunks = async (response, onEvent) => {
+    const processLine = async (line) => {
+        if (!line.startsWith('data:')) {
+            return;
+        }
+        const jsonPayload = line.slice(5).trim();
+        if (!jsonPayload) {
+            return;
+        }
+        try {
+            await onEvent(SSEEvent.from_json(jsonPayload));
+        }
+        catch {
+            // Ignore malformed SSE entries.
+        }
+    };
+    if (!response.body) {
+        const text = await response.text();
+        for (const line of text.split(/\r?\n/)) {
+            await processLine(line);
+        }
+        return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            await processLine(line);
+        }
+    }
+    if (buffer) {
+        await processLine(buffer);
+    }
+};
+const shouldUseRemoteSandbox = (options) => Boolean(options.server_url ||
+    options.api_key ||
+    options.cloud_profile_id ||
+    options.cloud_proxy_country_code ||
+    options.cloud_timeout);
+export const sandbox = (options = {}) => (fn) => async (...args) => {
+    const remoteMode = shouldUseRemoteSandbox(options);
+    if (!remoteMode) {
+        return await fn(...args);
+    }
+    const apiKey = options.api_key?.trim() || process.env.BROWSER_USE_API_KEY?.trim();
+    if (!apiKey) {
+        throw new SandboxError('BROWSER_USE_API_KEY is required for remote sandbox execution');
+    }
+    const fetch_impl = options.fetch_impl ?? fetch;
+    const server_url = options.server_url ?? defaultServerUrl;
+    const payload = {
+        code: Buffer.from(String(fn)).toString('base64'),
+        args: Buffer.from(JSON.stringify(args)).toString('base64'),
+        env: {
+            LOG_LEVEL: String(options.log_level ?? 'INFO').toUpperCase(),
+        },
+    };
+    if (options.cloud_profile_id != null) {
+        payload.cloud_profile_id = options.cloud_profile_id;
+    }
+    if (options.cloud_proxy_country_code != null) {
+        payload.cloud_proxy_country_code = options.cloud_proxy_country_code;
+    }
+    if (options.cloud_timeout != null) {
+        payload.cloud_timeout = options.cloud_timeout;
+    }
+    const response = await fetch_impl(server_url, {
+        method: 'POST',
+        headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json',
+            ...(options.headers ?? {}),
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        throw new SandboxError(`Sandbox request failed with status ${response.status}`);
+    }
+    let executionResult = null;
+    let hasResult = false;
+    await parseSSEChunks(response, async (event) => {
+        if (event.type === SSEEventType.BROWSER_CREATED &&
+            event.data instanceof BrowserCreatedData) {
+            await maybeInvoke(options.on_browser_created, event.data);
+            if (!options.quiet && event.data.live_url) {
+                logger.info(`🔗 Live URL: ${event.data.live_url}`);
+            }
+            return;
+        }
+        if (event.type === SSEEventType.INSTANCE_READY) {
+            await maybeInvoke(options.on_instance_ready, undefined);
+            return;
+        }
+        if (event.type === SSEEventType.LOG && event.data instanceof LogData) {
+            await maybeInvoke(options.on_log, event.data);
+            if (!options.quiet) {
+                logger.info(event.data.message);
+            }
+            return;
+        }
+        if (event.type === SSEEventType.RESULT &&
+            event.data instanceof ResultData) {
+            await maybeInvoke(options.on_result, event.data);
+            if (!event.data.execution_response.success) {
+                throw new SandboxError(`Execution failed: ${event.data.execution_response.error ?? 'unknown error'}`);
+            }
+            executionResult = event.data.execution_response.result;
+            hasResult = true;
+            return;
+        }
+        if (event.type === SSEEventType.ERROR &&
+            event.data instanceof ErrorData) {
+            await maybeInvoke(options.on_error, event.data);
+            throw new SandboxError(`Execution failed: ${event.data.error || 'unknown error'}`);
+        }
+    });
+    if (!hasResult) {
+        throw new SandboxError('No result received from sandbox execution');
+    }
+    return executionResult;
+};
+export { SandboxError };