browser-use 0.2.0 → 0.3.0

package/dist/skills/service.js

@@ -0,0 +1,266 @@
+import { CONFIG } from '../config.js';
+import { createLogger } from '../logging-config.js';
+import { build_skill_parameters_schema, get_skill_slug } from './utils.js';
+import { MissingCookieException, } from './views.js';
+const logger = createLogger('browser_use.skills');
+const toSkillParameter = (raw) => {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const record = raw;
+    const name = typeof record.name === 'string' ? record.name.trim() : '';
+    const type = typeof record.type === 'string' ? record.type.trim() : '';
+    if (!name || !type) {
+        return null;
+    }
+    if (type !== 'string' &&
+        type !== 'number' &&
+        type !== 'boolean' &&
+        type !== 'object' &&
+        type !== 'array' &&
+        type !== 'cookie') {
+        return null;
+    }
+    return {
+        name,
+        type,
+        required: typeof record.required === 'boolean' ? record.required : undefined,
+        description: typeof record.description === 'string' ? record.description : undefined,
+    };
+};
+const toSkillDefinition = (raw) => {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const record = raw;
+    const id = typeof record.id === 'string' ? record.id.trim() : '';
+    const title = typeof record.title === 'string' ? record.title.trim() : '';
+    const description = typeof record.description === 'string' ? record.description.trim() : '';
+    if (!id || !title) {
+        return null;
+    }
+    const parametersRaw = Array.isArray(record.parameters)
+        ? record.parameters
+        : [];
+    const parameters = parametersRaw
+        .map((entry) => toSkillParameter(entry))
+        .filter((entry) => entry != null);
+    const output_schema = record.output_schema && typeof record.output_schema === 'object'
+        ? record.output_schema
+        : null;
+    return {
+        id,
+        title,
+        description,
+        parameters,
+        output_schema,
+    };
+};
+export class CloudSkillService {
+    skill_ids;
+    api_key;
+    base_url;
+    fetch_impl;
+    initialized = false;
+    skills = new Map();
+    constructor(options) {
+        this.skill_ids = options.skill_ids;
+        this.api_key = options.api_key ?? process.env.BROWSER_USE_API_KEY ?? '';
+        this.base_url = options.base_url ?? CONFIG.BROWSER_USE_CLOUD_API_URL;
+        this.fetch_impl = options.fetch_impl ?? fetch;
+        if (!this.api_key) {
+            throw new Error('BROWSER_USE_API_KEY environment variable is not set');
+        }
+    }
+    async requestJson(path, init = {}) {
+        const response = await this.fetch_impl(`${this.base_url}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.api_key}`,
+                ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+                ...(init.headers ?? {}),
+            },
+        });
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = null;
+        }
+        if (!response.ok) {
+            const details = payload && typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload ?? '');
+            throw new Error(`Skill API request failed (${response.status}): ${details}`);
+        }
+        return payload;
+    }
+    async listSkillsPage(page_number, page_size) {
+        const query = new URLSearchParams({
+            page_size: String(page_size),
+            page_number: String(page_number),
+            is_enabled: 'true',
+        });
+        const payload = (await this.requestJson(`/api/v1/skills?${query.toString()}`));
+        const items = Array.isArray(payload?.items) ? payload.items : [];
+        const skills = [];
+        for (const item of items) {
+            const status = item && typeof item === 'object'
+                ? item.status
+                : undefined;
+            if (typeof status === 'string' && status !== 'finished') {
+                continue;
+            }
+            const skill = toSkillDefinition(item);
+            if (skill) {
+                skills.push(skill);
+            }
+        }
+        return skills;
+    }
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            const useWildcard = this.skill_ids.includes('*');
+            const requestedIds = new Set(this.skill_ids.filter((entry) => entry !== '*'));
+            const page_size = 100;
+            const max_pages = useWildcard ? 1 : 5;
+            const loaded = [];
+            let reachedPaginationLimit = true;
+            for (let page = 1; page <= max_pages; page += 1) {
+                const pageSkills = await this.listSkillsPage(page, page_size);
+                loaded.push(...pageSkills);
+                if (pageSkills.length < page_size) {
+                    reachedPaginationLimit = false;
+                    break;
+                }
+                if (!useWildcard && requestedIds.size > 0) {
+                    const found = new Set(loaded.map((entry) => entry.id).filter((id) => requestedIds.has(id)));
+                    if (found.size === requestedIds.size) {
+                        reachedPaginationLimit = false;
+                        break;
+                    }
+                }
+            }
+            if (useWildcard && loaded.length >= page_size) {
+                logger.warning('Wildcard "*" limited to first 100 skills. Specify explicit skill IDs if you need specific skills beyond this limit.');
+            }
+            if (!useWildcard && reachedPaginationLimit) {
+                logger.warning('Reached pagination limit (5 pages) before finding all requested skills');
+            }
+            const selected = useWildcard
+                ? loaded
+                : loaded.filter((entry) => requestedIds.has(entry.id));
+            if (!useWildcard && requestedIds.size > 0) {
+                const foundIds = new Set(selected.map((entry) => entry.id));
+                const missingIds = Array.from(requestedIds).filter((id) => !foundIds.has(id));
+                if (missingIds.length > 0) {
+                    logger.warning(`Requested skills not found or not available: ${missingIds.join(', ')}`);
+                }
+            }
+            for (const skill of selected) {
+                this.skills.set(skill.id, skill);
+            }
+            this.initialized = true;
+            logger.info(`Loaded ${this.skills.size} skills${useWildcard ? ' (wildcard mode)' : ''}`);
+        }
+        catch (error) {
+            // Match Python semantics: avoid retry loops after an initialization failure.
+            this.initialized = true;
+            throw error;
+        }
+    }
+    async get_skill(skill_id) {
+        await this.ensureInitialized();
+        return this.skills.get(skill_id) ?? null;
+    }
+    async get_all_skills() {
+        await this.ensureInitialized();
+        return Array.from(this.skills.values());
+    }
+    async execute_skill(input) {
+        await this.ensureInitialized();
+        const skill = this.skills.get(input.skill_id);
+        if (!skill) {
+            throw new Error(`Skill ${input.skill_id} not found in cache. Available skills: ${Array.from(this.skills.keys()).join(', ')}`);
+        }
+        const cookieMap = new Map();
+        for (const cookie of input.cookies ?? []) {
+            if (!cookie?.name) {
+                continue;
+            }
+            cookieMap.set(cookie.name, cookie.value ?? '');
+        }
+        const payload = {
+            ...(input.parameters ?? {}),
+        };
+        for (const param of skill.parameters) {
+            if (param.type !== 'cookie') {
+                continue;
+            }
+            const required = param.required !== false;
+            if (required && !cookieMap.has(param.name)) {
+                throw new MissingCookieException(param.name, param.description || 'No description provided');
+            }
+            if (cookieMap.has(param.name)) {
+                payload[param.name] = cookieMap.get(param.name) ?? '';
+            }
+        }
+        const validator = build_skill_parameters_schema(skill.parameters, {
+            exclude_cookies: false,
+        });
+        const validated = validator.safeParse(payload);
+        if (!validated.success) {
+            throw new Error(`Parameter validation failed for skill ${skill.title}: ${validated.error.message}`);
+        }
+        try {
+            const response = (await this.requestJson(`/api/v1/skills/${encodeURIComponent(input.skill_id)}/execute`, {
+                method: 'POST',
+                body: JSON.stringify({ parameters: validated.data }),
+            }));
+            const success = response.success === true;
+            const result = response.result ?? response.output ?? response.data ?? null;
+            const error = typeof response.error === 'string' ? response.error : null;
+            const latency_ms = typeof response.latency_ms === 'number' ? response.latency_ms : null;
+            return {
+                success,
+                result,
+                error,
+                latency_ms,
+            };
+        }
+        catch (error) {
+            const errorText = error instanceof Error
+                ? `${error.name}: ${error.message}`
+                : String(error);
+            return {
+                success: false,
+                error: `Failed to execute skill: ${errorText}`,
+            };
+        }
+    }
+    async close() {
+        this.skills.clear();
+        this.initialized = false;
+    }
+}
+export const register_skills_as_actions = async (skills, registerAction) => {
+    for (const skill of skills) {
+        const slug = get_skill_slug(skill, skills);
+        const paramSchema = build_skill_parameters_schema(skill.parameters, {
+            exclude_cookies: true,
+        });
+        const description = `${skill.description} (Skill: "${skill.title}")`;
+        registerAction(slug, description, paramSchema, skill);
+    }
+};
+export const cookies_to_map = (cookies) => {
+    const map = new Map();
+    for (const cookie of cookies) {
+        map.set(cookie.name, cookie.value);
+    }
+    return map;
+};

package/dist/skills/utils.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import type { SkillDefinition, SkillParameterSchema } from './views.js';
+export declare const get_skill_slug: (skill: SkillDefinition, all_skills: SkillDefinition[]) => string;
+export declare const build_skill_parameters_schema: (parameters: SkillParameterSchema[], options?: {
+    exclude_cookies?: boolean;
+}) => z.ZodObject<Record<string, z.ZodTypeAny>>;

package/dist/skills/utils.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+const normalizeSlug = (title) => {
+    const cleaned = title
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '')
+        .replace(/[\s-]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return cleaned || 'skill';
+};
+const normalizeTypeSchema = (param) => {
+    switch (param.type) {
+        case 'string':
+        case 'cookie':
+            return z.string();
+        case 'number':
+            return z.number();
+        case 'boolean':
+            return z.boolean();
+        case 'array':
+            return z.array(z.unknown());
+        case 'object':
+            return z.record(z.string(), z.unknown());
+        default:
+            return z.unknown();
+    }
+};
+export const get_skill_slug = (skill, all_skills) => {
+    const slug = normalizeSlug(skill.title);
+    const duplicateCount = all_skills.filter((entry) => {
+        return normalizeSlug(entry.title) === slug;
+    }).length;
+    if (duplicateCount > 1) {
+        return `${slug}_${skill.id.slice(0, 4)}`;
+    }
+    return slug;
+};
+export const build_skill_parameters_schema = (parameters, options = {}) => {
+    const { exclude_cookies = false } = options;
+    const shape = {};
+    for (const param of parameters) {
+        if (exclude_cookies && param.type === 'cookie') {
+            continue;
+        }
+        const description = typeof param.description === 'string' ? param.description.trim() : '';
+        const required = param.required !== false;
+        let schema = normalizeTypeSchema(param);
+        if (description) {
+            schema = schema.describe(description);
+        }
+        shape[param.name] = required ? schema : schema.optional();
+    }
+    return z.object(shape);
+};

package/dist/skills/views.d.ts

@@ -0,0 +1,40 @@
+export type SkillParameterType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'cookie';
+export interface SkillParameterSchema {
+    name: string;
+    type: SkillParameterType;
+    required?: boolean | null;
+    description?: string | null;
+}
+export interface SkillDefinition {
+    id: string;
+    title: string;
+    description: string;
+    parameters: SkillParameterSchema[];
+    output_schema?: Record<string, unknown> | null;
+}
+export interface SkillExecutionResult {
+    success: boolean;
+    result?: unknown;
+    error?: string | null;
+    latency_ms?: number | null;
+}
+export interface BrowserCookie {
+    name: string;
+    value: string;
+}
+export interface ExecuteSkillInput {
+    skill_id: string;
+    parameters: Record<string, unknown>;
+    cookies: BrowserCookie[];
+}
+export interface SkillService {
+    get_skill?(skill_id: string): Promise<SkillDefinition | null>;
+    get_all_skills(): Promise<SkillDefinition[]>;
+    execute_skill(input: ExecuteSkillInput): Promise<SkillExecutionResult>;
+    close?(): Promise<void> | void;
+}
+export declare class MissingCookieException extends Error {
+    cookie_name: string;
+    cookie_description: string;
+    constructor(cookie_name: string, cookie_description: string);
+}

package/dist/skills/views.js

@@ -0,0 +1,10 @@
+export class MissingCookieException extends Error {
+    cookie_name;
+    cookie_description;
+    constructor(cookie_name, cookie_description) {
+        super(`Missing required cookie '${cookie_name}': ${cookie_description}`);
+        this.name = 'MissingCookieException';
+        this.cookie_name = cookie_name;
+        this.cookie_description = cookie_description;
+    }
+}

package/dist/sync/auth.js

@@ -100,7 +100,7 @@ export class DeviceAuthClient {
         const response = await this.postForm('/api/v1/oauth/device/authorize', {
             client_id: this.clientId,
             scope: this.scope,
-            agent_session_id: agent_session_id ?? undefined,
+            agent_session_id: agent_session_id ?? '',
             device_id: this.device_id,
         });
         return response.data;
@@ -160,7 +160,7 @@ export class DeviceAuthClient {
             const replaceHost = (value) => value?.replace(this.baseUrl, frontendBase);
             const verificationUri = replaceHost(deviceAuth.verification_uri);
             const verificationUriComplete = replaceHost(deviceAuth.verification_uri_complete);
-            if (show_instructions) {
+            if (show_instructions && CONFIG.BROWSER_USE_CLOUD_SYNC) {
                 const divider = '─'.repeat(terminalWidth());
                 logger.info(divider);
                 logger.info('🌐  View the details of this run in Browser Use Cloud:');
@@ -200,6 +200,11 @@ export class DeviceAuthClient {
     }
     clear_auth() {
         this.authConfig = { api_token: null, user_id: null, authorized_at: null };
-        saveAuthConfig(this.authConfig);
+        try {
+            fs.unlinkSync(CLOUD_AUTH_PATH());
+        }
+        catch {
+            /* noop */
+        }
     }
 }

package/dist/sync/service.d.ts

@@ -3,19 +3,19 @@ import { DeviceAuthClient } from './auth.js';
 export interface CloudSyncOptions {
     baseUrl?: string;
     enableAuth?: boolean;
+    allowSessionEventsForAuth?: boolean;
 }
 export declare class CloudSync {
     private readonly baseUrl;
-    private readonly enableAuth;
-    readonly auth_client?: DeviceAuthClient;
-    private pendingEvents;
-    private authTask;
+    private readonly enabled;
+    readonly auth_client: DeviceAuthClient;
     private sessionId;
+    private allowSessionEventsForAuth;
+    private authFlowActive;
     constructor(options?: CloudSyncOptions);
     handle_event(event: BaseEvent): Promise<void>;
     private sendEvent;
-    private backgroundAuth;
-    private resendPendingEvents;
+    set_auth_flow_active(): void;
     wait_for_auth(): Promise<void>;
     authenticate(showInstructions?: boolean): Promise<boolean>;
 }

package/dist/sync/service.js

@@ -7,40 +7,39 @@ const stripTrailingSlash = (input) => input.replace(/\/+$/, '');
 const ensureArray = (value) => Array.isArray(value) ? value : [value];
 export class CloudSync {
     baseUrl;
-    enableAuth;
+    enabled;
     auth_client;
-    pendingEvents = [];
-    authTask = null;
     sessionId = null;
+    allowSessionEventsForAuth;
+    authFlowActive = false;
     constructor(options = {}) {
+        const enableAuth = options.enableAuth ?? true;
         this.baseUrl = stripTrailingSlash(options.baseUrl ?? CONFIG.BROWSER_USE_CLOUD_API_URL);
-        this.enableAuth = options.enableAuth ?? true;
-        this.auth_client = this.enableAuth
-            ? new DeviceAuthClient(this.baseUrl)
-            : undefined;
+        this.enabled = CONFIG.BROWSER_USE_CLOUD_SYNC && enableAuth;
+        this.allowSessionEventsForAuth = options.allowSessionEventsForAuth ?? false;
+        this.auth_client = new DeviceAuthClient(this.baseUrl);
     }
     async handle_event(event) {
         try {
+            if (!this.enabled) {
+                return;
+            }
             if (event.event_type === 'CreateAgentSessionEvent' &&
-                event?.id) {
+                event?.id != null) {
                 this.sessionId = String(event.id);
             }
-            if (event.event_type === 'CreateAgentStepEvent') {
-                const raw = event;
-                const step = raw?.step ?? raw?.payload?.step;
-                if (step === 2 &&
-                    this.enableAuth &&
-                    this.auth_client &&
-                    !this.authTask) {
-                    if (this.sessionId) {
-                        this.authTask = this.backgroundAuth(this.sessionId);
-                    }
-                    else {
-                        logger.warning('Cannot start cloud auth, session_id missing');
-                    }
+            if (this.auth_client.is_authenticated) {
+                await this.sendEvent(event);
+                return;
+            }
+            if (this.allowSessionEventsForAuth || this.authFlowActive) {
+                await this.sendEvent(event);
+                if (event.event_type === 'CreateAgentSessionEvent') {
+                    this.authFlowActive = true;
                 }
+                return;
             }
-            await this.sendEvent(event);
+            logger.debug(`Skipping event ${event.event_type} - user not authenticated`);
         }
         catch (error) {
             logger.error(`Failed to handle ${event.event_type}: ${error.message}`);
@@ -49,13 +48,18 @@ export class CloudSync {
     async sendEvent(event) {
         try {
             const headers = {};
-            const authClient = this.auth_client;
-            const userId = authClient ? authClient.user_id : TEMP_USER_ID;
-            event.user_id = userId;
-            if (authClient) {
-                Object.assign(headers, authClient.get_headers());
-                event.device_id = authClient.device_id;
+            const currentUserId = event.user_id ?? null;
+            if (this.auth_client.is_authenticated) {
+                if (currentUserId !== TEMP_USER_ID) {
+                    event.user_id = this.auth_client.user_id;
+                }
             }
+            else if (!currentUserId) {
+                event.user_id = TEMP_USER_ID;
+            }
+            Object.assign(headers, this.auth_client.get_headers());
+            event.device_id =
+                event.device_id ?? this.auth_client.device_id;
             const payload = typeof event?.toJSON === 'function'
                 ? event.toJSON()
                 : { ...event };
@@ -63,84 +67,45 @@ export class CloudSync {
             await axios.post(`${this.baseUrl}/api/v1/events`, {
                 events: events.map((entry) => ({
                     ...entry,
-                    device_id: entry.device_id ?? authClient?.device_id,
+                    device_id: entry.device_id ?? this.auth_client.device_id,
                 })),
             }, { headers, timeout: 10_000 });
         }
         catch (error) {
             const status = error?.response?.status;
-            if (status === 401 &&
-                this.auth_client &&
-                !this.auth_client.is_authenticated) {
-                this.pendingEvents.push(event);
-                return;
-            }
             if (status) {
-                logger.debug(`Cloud sync HTTP ${status}: ${error?.response?.data ?? error}`);
+                logger.debug(`Failed to send sync event: POST ${this.baseUrl}/api/v1/events ${status} - ${String(error?.response?.data ?? '')}`);
             }
             else if (error?.code === 'ECONNABORTED') {
-                logger.warning(`Cloud sync timeout sending ${event.event_type}`);
+                logger.debug(`Event send timed out after 10 seconds: ${event}`);
             }
             else {
-                logger.warning(`Cloud sync error: ${error?.message ?? error}`);
-            }
-        }
-    }
-    async backgroundAuth(agentSessionId) {
-        const authClient = this.auth_client;
-        if (!authClient) {
-            return;
-        }
-        try {
-            if (authClient.is_authenticated) {
-                const frontend = CONFIG.BROWSER_USE_CLOUD_UI_URL ||
-                    this.baseUrl.replace('//api.', '//cloud.');
-                const sessionUrl = `${stripTrailingSlash(frontend)}/agent/${agentSessionId}`;
-                const divider = '─'.repeat(Math.max((process.stdout?.columns ?? 80) - 40, 20));
-                logger.info(divider);
-                logger.info('🌐  View the details of this run in Browser Use Cloud:');
-                logger.info(`    👉  ${sessionUrl}`);
-                logger.info(divider + '\n');
-                return;
-            }
-            const success = await authClient.authenticate(agentSessionId, true);
-            if (success) {
-                await this.resendPendingEvents();
-            }
-        }
-        catch (error) {
-            logger.debug(`Cloud sync auth error: ${error.message}`);
-        }
-    }
-    async resendPendingEvents() {
-        if (!this.pendingEvents.length) {
-            return;
-        }
-        const events = [...this.pendingEvents];
-        this.pendingEvents = [];
-        for (const event of events) {
-            try {
-                await this.sendEvent(event);
-            }
-            catch (error) {
-                logger.warning(`Failed to resend event ${event.event_type}: ${error.message}`);
+                logger.debug(`Unexpected error sending event ${event}: ${typeOfError(error)}`);
             }
         }
     }
-    async wait_for_auth() {
-        if (this.authTask) {
-            try {
-                await this.authTask;
-            }
-            catch {
-                /* ignore */
-            }
-        }
+    set_auth_flow_active() {
+        this.authFlowActive = true;
+        this.allowSessionEventsForAuth = true;
     }
+    // Backward-compatible no-op; auth is no longer background-scheduled here.
+    async wait_for_auth() { }
     async authenticate(showInstructions = true) {
-        if (!this.auth_client) {
+        if (!this.enabled) {
             return false;
         }
+        if (this.auth_client.is_authenticated) {
+            if (showInstructions) {
+                logger.info('✅ Already authenticated! Skipping OAuth flow.');
+            }
+            return true;
+        }
         return this.auth_client.authenticate(this.sessionId, showInstructions);
     }
 }
+const typeOfError = (error) => {
+    if (error instanceof Error) {
+        return `${error.name}: ${error.message}`;
+    }
+    return String(error);
+};