browser-use 0.5.0 → 0.6.1

package/dist/browser/cloud/management.d.ts

@@ -0,0 +1,130 @@
+export interface CloudManagementClientOptions {
+    api_base_url?: string;
+    api_key?: string | null;
+    fetch_impl?: typeof fetch;
+}
+export interface CloudTaskView {
+    id: string;
+    sessionId: string;
+    llm?: string | null;
+    task: string;
+    status: string;
+    createdAt: string;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+    output?: string | null;
+    browserUseVersion?: string | null;
+    isSuccess?: boolean | null;
+    judgement?: string | null;
+    judgeVerdict?: boolean | null;
+    steps?: Array<Record<string, unknown>>;
+    outputFiles?: Array<Record<string, unknown>>;
+}
+export interface CloudSessionView {
+    id: string;
+    status: string;
+    startedAt: string;
+    liveUrl?: string | null;
+    finishedAt?: string | null;
+    tasks?: CloudTaskView[];
+    publicShareUrl?: string | null;
+}
+export interface CloudProfileView {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    name?: string | null;
+    lastUsedAt?: string | null;
+    cookieDomains?: string[] | null;
+}
+export interface CloudShareView {
+    shareToken: string;
+    shareUrl: string;
+    viewCount: number;
+    lastViewedAt?: string | null;
+}
+export interface PaginatedResponse<T> {
+    items: T[];
+    totalItems: number;
+    pageNumber: number;
+    pageSize: number;
+}
+export interface CreateTaskRequest {
+    task: string;
+    llm?: string | null;
+    startUrl?: string | null;
+    maxSteps?: number | null;
+    structuredOutput?: string | null;
+    sessionId?: string | null;
+    metadata?: Record<string, string> | null;
+    secrets?: Record<string, string> | null;
+    allowedDomains?: string[] | null;
+    opVaultId?: string | null;
+    highlightElements?: boolean;
+    flashMode?: boolean;
+    thinking?: boolean;
+    vision?: boolean | 'auto' | null;
+    systemPromptExtension?: string | null;
+    judge?: boolean;
+    judgeGroundTruth?: string | null;
+    judgeLlm?: string | null;
+    skillIds?: string[] | null;
+}
+export interface CreateSessionRequest {
+    profileId?: string | null;
+    proxyCountryCode?: string | null;
+    startUrl?: string | null;
+    browserScreenWidth?: number | null;
+    browserScreenHeight?: number | null;
+}
+export declare class CloudManagementClient {
+    private readonly api_base_url;
+    private readonly explicit_api_key;
+    private readonly fetch_impl;
+    constructor(options?: CloudManagementClientOptions);
+    private resolve_api_key;
+    private auth_headers;
+    private request_json;
+    private build_query;
+    list_tasks(options?: {
+        pageSize?: number;
+        pageNumber?: number;
+        sessionId?: string | null;
+        filterBy?: string | null;
+        after?: string | null;
+        before?: string | null;
+    }): Promise<PaginatedResponse<CloudTaskView>>;
+    create_task(request: CreateTaskRequest): Promise<{
+        id: string;
+        sessionId: string;
+    }>;
+    get_task(task_id: string): Promise<CloudTaskView>;
+    update_task(task_id: string, action: 'stop' | 'stop_task_and_session'): Promise<CloudTaskView>;
+    get_task_logs(task_id: string): Promise<{
+        downloadUrl: string;
+    }>;
+    list_sessions(options?: {
+        pageSize?: number;
+        pageNumber?: number;
+        filterBy?: string | null;
+    }): Promise<PaginatedResponse<CloudSessionView>>;
+    create_session(request: CreateSessionRequest): Promise<CloudSessionView>;
+    get_session(session_id: string): Promise<CloudSessionView>;
+    update_session(session_id: string, action: 'stop'): Promise<CloudSessionView>;
+    delete_session(session_id: string): Promise<void>;
+    create_session_public_share(session_id: string): Promise<CloudShareView>;
+    delete_session_public_share(session_id: string): Promise<void>;
+    list_profiles(options?: {
+        pageSize?: number;
+        pageNumber?: number;
+    }): Promise<PaginatedResponse<CloudProfileView>>;
+    create_profile(request?: {
+        name?: string | null;
+    }): Promise<CloudProfileView>;
+    get_profile(profile_id: string): Promise<CloudProfileView>;
+    update_profile(profile_id: string, request?: {
+        name?: string | null;
+    }): Promise<CloudProfileView>;
+    delete_profile(profile_id: string): Promise<void>;
+}

package/dist/browser/cloud/management.js

@@ -0,0 +1,140 @@
+import { CONFIG } from '../../config.js';
+import { DeviceAuthClient } from '../../sync/auth.js';
+import { CloudBrowserAuthError, CloudBrowserError } from './views.js';
+const stripTrailingSlash = (input) => input.replace(/\/+$/, '');
+export class CloudManagementClient {
+    api_base_url;
+    explicit_api_key;
+    fetch_impl;
+    constructor(options = {}) {
+        this.api_base_url = stripTrailingSlash(options.api_base_url ?? CONFIG.BROWSER_USE_CLOUD_API_URL);
+        this.explicit_api_key = options.api_key ?? null;
+        this.fetch_impl = options.fetch_impl ?? fetch;
+    }
+    resolve_api_key() {
+        if (this.explicit_api_key?.trim()) {
+            return this.explicit_api_key.trim();
+        }
+        if (process.env.BROWSER_USE_API_KEY?.trim()) {
+            return process.env.BROWSER_USE_API_KEY.trim();
+        }
+        const savedToken = new DeviceAuthClient(this.api_base_url).api_token?.trim();
+        return savedToken || null;
+    }
+    auth_headers(extra_headers = {}) {
+        const api_key = this.resolve_api_key();
+        if (!api_key) {
+            throw new CloudBrowserAuthError('No authentication token found. Set BROWSER_USE_API_KEY to use cloud APIs.');
+        }
+        return {
+            'X-Browser-Use-API-Key': api_key,
+            'Content-Type': 'application/json',
+            ...extra_headers,
+        };
+    }
+    async request_json(path, init) {
+        const response = await this.fetch_impl(`${this.api_base_url}${path}`, {
+            ...init,
+            headers: this.auth_headers(init.headers),
+        });
+        const text = await response.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = text;
+            }
+        }
+        if (!response.ok) {
+            const details = payload && typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload ?? '');
+            if (response.status === 401 || response.status === 403) {
+                throw new CloudBrowserAuthError(`Cloud API authentication failed (${response.status})`);
+            }
+            throw new CloudBrowserError(`Cloud API request failed (${response.status}): ${details}`);
+        }
+        return payload;
+    }
+    build_query(params) {
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null && String(value).length > 0) {
+                query.set(key, String(value));
+            }
+        }
+        const rendered = query.toString();
+        return rendered ? `?${rendered}` : '';
+    }
+    async list_tasks(options = {}) {
+        return await this.request_json(`/api/v2/tasks${this.build_query(options)}`, { method: 'GET' });
+    }
+    async create_task(request) {
+        return await this.request_json('/api/v2/tasks', {
+            method: 'POST',
+            body: JSON.stringify(request),
+        });
+    }
+    async get_task(task_id) {
+        return await this.request_json(`/api/v2/tasks/${encodeURIComponent(task_id)}`, { method: 'GET' });
+    }
+    async update_task(task_id, action) {
+        return await this.request_json(`/api/v2/tasks/${encodeURIComponent(task_id)}`, {
+            method: 'PATCH',
+            body: JSON.stringify({ action }),
+        });
+    }
+    async get_task_logs(task_id) {
+        return await this.request_json(`/api/v2/tasks/${encodeURIComponent(task_id)}/logs`, { method: 'GET' });
+    }
+    async list_sessions(options = {}) {
+        return await this.request_json(`/api/v2/sessions${this.build_query(options)}`, { method: 'GET' });
+    }
+    async create_session(request) {
+        return await this.request_json('/api/v2/sessions', {
+            method: 'POST',
+            body: JSON.stringify(request),
+        });
+    }
+    async get_session(session_id) {
+        return await this.request_json(`/api/v2/sessions/${encodeURIComponent(session_id)}`, { method: 'GET' });
+    }
+    async update_session(session_id, action) {
+        return await this.request_json(`/api/v2/sessions/${encodeURIComponent(session_id)}`, {
+            method: 'PATCH',
+            body: JSON.stringify({ action }),
+        });
+    }
+    async delete_session(session_id) {
+        await this.request_json(`/api/v2/sessions/${encodeURIComponent(session_id)}`, { method: 'DELETE' });
+    }
+    async create_session_public_share(session_id) {
+        return await this.request_json(`/api/v2/sessions/${encodeURIComponent(session_id)}/public-share`, { method: 'POST' });
+    }
+    async delete_session_public_share(session_id) {
+        await this.request_json(`/api/v2/sessions/${encodeURIComponent(session_id)}/public-share`, { method: 'DELETE' });
+    }
+    async list_profiles(options = {}) {
+        return await this.request_json(`/api/v2/profiles${this.build_query(options)}`, { method: 'GET' });
+    }
+    async create_profile(request = {}) {
+        return await this.request_json('/api/v2/profiles', {
+            method: 'POST',
+            body: JSON.stringify(request),
+        });
+    }
+    async get_profile(profile_id) {
+        return await this.request_json(`/api/v2/profiles/${encodeURIComponent(profile_id)}`, { method: 'GET' });
+    }
+    async update_profile(profile_id, request = {}) {
+        return await this.request_json(`/api/v2/profiles/${encodeURIComponent(profile_id)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(request),
+        });
+    }
+    async delete_profile(profile_id) {
+        await this.request_json(`/api/v2/profiles/${encodeURIComponent(profile_id)}`, { method: 'DELETE' });
+    }
+}

package/dist/browser/events.d.ts

@@ -80,10 +80,20 @@ export declare class CloseTabEvent extends BrowserEvent<void> {
 }
 export declare class ScreenshotEvent extends BrowserEvent<string> {
     full_page: boolean;
-    clip: Record<string, number> | null;
+    clip: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
     constructor(init?: EventBusEventInit<string> & {
         full_page?: boolean;
-        clip?: Record<string, number> | null;
+        clip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | null;
     });
 }
 export declare class BrowserStateRequestEvent extends BrowserEvent<BrowserStateSummary> {
@@ -175,12 +185,60 @@ export declare class BrowserConnectedEvent extends BrowserEvent<void> {
         cdp_url: string;
     });
 }
+export declare class BrowserReconnectingEvent extends BrowserEvent<void> {
+    cdp_url: string;
+    attempt: number;
+    max_attempts: number;
+    constructor(init: EventBusEventInit<void> & {
+        cdp_url: string;
+        attempt: number;
+        max_attempts: number;
+    });
+}
+export declare class BrowserReconnectedEvent extends BrowserEvent<void> {
+    cdp_url: string;
+    attempt: number;
+    downtime_seconds: number;
+    constructor(init: EventBusEventInit<void> & {
+        cdp_url: string;
+        attempt: number;
+        downtime_seconds: number;
+    });
+}
 export declare class BrowserStoppedEvent extends BrowserEvent<void> {
     reason: string | null;
     constructor(init?: EventBusEventInit<void> & {
         reason?: string | null;
     });
 }
+export declare class CaptchaSolverStartedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    vendor: string;
+    url: string;
+    started_at: number;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        vendor: string;
+        url: string;
+        started_at: number;
+    });
+}
+export declare class CaptchaSolverFinishedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    vendor: string;
+    url: string;
+    duration_ms: number;
+    finished_at: number;
+    success: boolean;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        vendor: string;
+        url: string;
+        duration_ms: number;
+        finished_at: number;
+        success: boolean;
+    });
+}
 export declare class TabCreatedEvent extends BrowserEvent<void> {
     target_id: TargetID;
     url: string;
@@ -341,5 +399,5 @@ export declare class DialogOpenedEvent extends BrowserEvent<void> {
         frame_id?: string | null;
     });
 }
-export declare const BROWSER_EVENT_CLASSES: readonly [typeof ElementSelectedEvent, typeof NavigateToUrlEvent, typeof ClickElementEvent, typeof ClickCoordinateEvent, typeof TypeTextEvent, typeof ScrollEvent, typeof SwitchTabEvent, typeof CloseTabEvent, typeof ScreenshotEvent, typeof BrowserStateRequestEvent, typeof GoBackEvent, typeof GoForwardEvent, typeof RefreshEvent, typeof WaitEvent, typeof SendKeysEvent, typeof UploadFileEvent, typeof GetDropdownOptionsEvent, typeof SelectDropdownOptionEvent, typeof ScrollToTextEvent, typeof BrowserStartEvent, typeof BrowserStopEvent, typeof BrowserLaunchEvent, typeof BrowserKillEvent, typeof BrowserConnectedEvent, typeof BrowserStoppedEvent, typeof TabCreatedEvent, typeof TabClosedEvent, typeof AgentFocusChangedEvent, typeof TargetCrashedEvent, typeof NavigationStartedEvent, typeof NavigationCompleteEvent, typeof BrowserErrorEvent, typeof SaveStorageStateEvent, typeof StorageStateSavedEvent, typeof LoadStorageStateEvent, typeof StorageStateLoadedEvent, typeof DownloadStartedEvent, typeof DownloadProgressEvent, typeof FileDownloadedEvent, typeof AboutBlankDVDScreensaverShownEvent, typeof DialogOpenedEvent];
+export declare const BROWSER_EVENT_CLASSES: readonly [typeof ElementSelectedEvent, typeof NavigateToUrlEvent, typeof ClickElementEvent, typeof ClickCoordinateEvent, typeof TypeTextEvent, typeof ScrollEvent, typeof SwitchTabEvent, typeof CloseTabEvent, typeof ScreenshotEvent, typeof BrowserStateRequestEvent, typeof GoBackEvent, typeof GoForwardEvent, typeof RefreshEvent, typeof WaitEvent, typeof SendKeysEvent, typeof UploadFileEvent, typeof GetDropdownOptionsEvent, typeof SelectDropdownOptionEvent, typeof ScrollToTextEvent, typeof BrowserStartEvent, typeof BrowserStopEvent, typeof BrowserLaunchEvent, typeof BrowserKillEvent, typeof BrowserConnectedEvent, typeof BrowserReconnectingEvent, typeof BrowserReconnectedEvent, typeof BrowserStoppedEvent, typeof TabCreatedEvent, typeof TabClosedEvent, typeof AgentFocusChangedEvent, typeof TargetCrashedEvent, typeof NavigationStartedEvent, typeof NavigationCompleteEvent, typeof BrowserErrorEvent, typeof SaveStorageStateEvent, typeof StorageStateSavedEvent, typeof LoadStorageStateEvent, typeof StorageStateLoadedEvent, typeof DownloadStartedEvent, typeof DownloadProgressEvent, typeof FileDownloadedEvent, typeof AboutBlankDVDScreensaverShownEvent, typeof DialogOpenedEvent];
 export declare const BROWSER_EVENT_NAMES: string[];

package/dist/browser/events.js

@@ -276,6 +276,34 @@ export class BrowserConnectedEvent extends BrowserEvent {
         this.cdp_url = init.cdp_url;
     }
 }
+export class BrowserReconnectingEvent extends BrowserEvent {
+    cdp_url;
+    attempt;
+    max_attempts;
+    constructor(init) {
+        super('BrowserReconnectingEvent', {
+            ...init,
+            event_timeout: resolveEventTimeout('BrowserReconnectingEvent', 30, init.event_timeout),
+        });
+        this.cdp_url = init.cdp_url;
+        this.attempt = init.attempt;
+        this.max_attempts = init.max_attempts;
+    }
+}
+export class BrowserReconnectedEvent extends BrowserEvent {
+    cdp_url;
+    attempt;
+    downtime_seconds;
+    constructor(init) {
+        super('BrowserReconnectedEvent', {
+            ...init,
+            event_timeout: resolveEventTimeout('BrowserReconnectedEvent', 30, init.event_timeout),
+        });
+        this.cdp_url = init.cdp_url;
+        this.attempt = init.attempt;
+        this.downtime_seconds = init.downtime_seconds;
+    }
+}
 export class BrowserStoppedEvent extends BrowserEvent {
     reason;
     constructor(init = {}) {
@@ -286,6 +314,42 @@ export class BrowserStoppedEvent extends BrowserEvent {
         this.reason = init.reason ?? null;
     }
 }
+export class CaptchaSolverStartedEvent extends BrowserEvent {
+    target_id;
+    vendor;
+    url;
+    started_at;
+    constructor(init) {
+        super('CaptchaSolverStartedEvent', {
+            ...init,
+            event_timeout: resolveEventTimeout('CaptchaSolverStartedEvent', 5, init.event_timeout),
+        });
+        this.target_id = init.target_id;
+        this.vendor = init.vendor;
+        this.url = init.url;
+        this.started_at = init.started_at;
+    }
+}
+export class CaptchaSolverFinishedEvent extends BrowserEvent {
+    target_id;
+    vendor;
+    url;
+    duration_ms;
+    finished_at;
+    success;
+    constructor(init) {
+        super('CaptchaSolverFinishedEvent', {
+            ...init,
+            event_timeout: resolveEventTimeout('CaptchaSolverFinishedEvent', 5, init.event_timeout),
+        });
+        this.target_id = init.target_id;
+        this.vendor = init.vendor;
+        this.url = init.url;
+        this.duration_ms = init.duration_ms;
+        this.finished_at = init.finished_at;
+        this.success = init.success;
+    }
+}
 export class TabCreatedEvent extends BrowserEvent {
     target_id;
     url;
@@ -529,6 +593,8 @@ export const BROWSER_EVENT_CLASSES = [
     BrowserLaunchEvent,
     BrowserKillEvent,
     BrowserConnectedEvent,
+    BrowserReconnectingEvent,
+    BrowserReconnectedEvent,
     BrowserStoppedEvent,
     TabCreatedEvent,
     TabClosedEvent,

package/dist/browser/profile.d.ts

@@ -137,6 +137,7 @@ export interface BrowserProfileSpecificOptions {
     block_ip_addresses: boolean;
     keep_alive: Nullable<boolean>;
     enable_default_extensions: boolean;
+    captcha_solver: boolean;
     window_size: Nullable<ViewportSize>;
     window_height: Nullable<number>;
     window_width: Nullable<number>;

package/dist/browser/profile.js

@@ -344,6 +344,7 @@ const DEFAULT_BROWSER_PROFILE_OPTIONS = {
     block_ip_addresses: false,
     keep_alive: null,
     enable_default_extensions: getEnableDefaultExtensionsDefault(),
+    captcha_solver: true,
     window_size: null,
     window_height: null,
     window_width: null,

package/dist/browser/session.d.ts

@@ -5,6 +5,7 @@ import { BrowserStateSummary, type TabInfo } from './views.js';
 import { type WaitUntilState } from './events.js';
 import { DOMElementNode, type SelectorMap } from '../dom/views.js';
 import { SessionManager } from './session-manager.js';
+import { type CaptchaWaitResult } from './watchdogs/captcha-watchdog.js';
 import type { BaseWatchdog } from './watchdogs/base.js';
 export interface BrowserSessionInit {
     id?: string;
@@ -22,6 +23,21 @@ export interface BrowserSessionInit {
     downloaded_files?: string[];
     closed_popup_messages?: string[];
 }
+export interface ChromeProfileInfo {
+    directory: string;
+    name: string;
+    email?: string;
+}
+export declare const systemChrome: {
+    findExecutable(): string | null;
+    getUserDataDir(executablePath?: string | null): string | null;
+    listProfiles(userDataDir?: string | null): ChromeProfileInfo[];
+};
+export interface BrowserSessionFromSystemChromeInit extends Omit<BrowserSessionInit, 'browser_profile' | 'profile'> {
+    browser_profile?: BrowserProfile;
+    profile?: Partial<BrowserProfileOptions>;
+    profile_directory?: string | null;
+}
 export interface BrowserStateOptions {
     cache_clickable_elements_hashes?: boolean;
     include_screenshot?: boolean;
@@ -78,7 +94,18 @@ export declare class BrowserSession {
     private readonly _maxRecentEvents;
     private _watchdogs;
     private _defaultWatchdogsAttached;
+    private _captchaWatchdog;
+    readonly RECONNECT_WAIT_TIMEOUT = 54;
+    private _reconnecting;
+    private _reconnectTask;
+    private _reconnectWaitPromise;
+    private _resolveReconnectWait;
+    private _intentionalStop;
+    private _disconnectAwareBrowser;
+    private _browserDisconnectHandler;
     constructor(init?: BrowserSessionInit);
+    static from_system_chrome(init?: BrowserSessionFromSystemChromeInit): BrowserSession;
+    static list_chrome_profiles(): ChromeProfileInfo[];
     attach_watchdog(watchdog: BaseWatchdog): void;
     attach_watchdogs(watchdogs: BaseWatchdog[]): void;
     detach_watchdog(watchdog: BaseWatchdog): void;
@@ -89,6 +116,7 @@ export declare class BrowserSession {
         cdp_url: string;
     }>;
     attach_default_watchdogs(): void;
+    wait_if_captcha_solving(timeoutSeconds?: number): Promise<CaptchaWaitResult | null>;
     private _formatTabId;
     private _createTabInfo;
     private _buildSyntheticTargetId;
@@ -110,6 +138,10 @@ export declare class BrowserSession {
     describe(): string;
     get _owns_browser_resources(): boolean;
     get is_stopping(): boolean;
+    get is_reconnecting(): boolean;
+    get should_gate_watchdog_events(): boolean;
+    get is_cdp_connected(): boolean;
+    wait_for_reconnect(timeoutSeconds?: number): Promise<void>;
     claim_agent(agentId: string, mode?: 'exclusive' | 'shared'): boolean;
     claimAgent(agentId: string, mode?: 'exclusive' | 'shared'): boolean;
     release_agent(agentId?: string): boolean;
@@ -125,6 +157,22 @@ export declare class BrowserSession {
     private _waitWithAbort;
     private _withAbort;
     private _toPlaywrightOptions;
+    set_extra_headers(headers: Record<string, string>): Promise<void>;
+    private _applyConfiguredExtraHttpHeaders;
+    private _usesRemoteBrowserConnection;
+    private _connectToConfiguredBrowser;
+    private _ensureBrowserContextFromBrowser;
+    private _beginReconnectWait;
+    private _endReconnectWait;
+    private _detachRemoteDisconnectHandler;
+    private _attachRemoteDisconnectHandler;
+    private _handleUnexpectedRemoteDisconnect;
+    private _restorePagesAfterReconnect;
+    reconnect(options?: {
+        preferred_url?: string | null;
+        preferred_tab_index?: number;
+    }): Promise<void>;
+    private _auto_reconnect;
     private _isSandboxLaunchError;
     private _createNoSandboxLaunchOptions;
     private _launchChromiumWithSandboxFallback;
@@ -255,11 +303,17 @@ export declare class BrowserSession {
      */
     wait_for_element(selector: string, timeout?: number): Promise<void>;
     /**
-     * Take a screenshot of the current page
+     * Take a screenshot of the current page.
      * @param full_page Whether to capture the full scrollable page
+     * @param clip Optional clip region for partial screenshots
      * @returns Base64 encoded PNG screenshot
      */
-    take_screenshot(full_page?: boolean): Promise<string | null>;
+    take_screenshot(full_page?: boolean, clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null): Promise<string | null>;
     /**
      * Add a request event listener to the current page
      */