browser-use 0.0.1 → 0.1.0

package/dist/observability-decorators.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Observability Decorators and Utilities
+ *
+ * Provides debugging and performance tracking capabilities
+ * for browser automation operations.
+ *
+ * Note: TypeScript decorators work differently than Python.
+ * These are implemented as wrapper functions that can be used
+ * in a similar way to decorators.
+ */
+import { createLogger } from './logging-config.js';
+/**
+ * Debug observation configuration
+ */
+export interface ObserveDebugOptions {
+    /** Enable detailed logging */
+    verbose?: boolean;
+    /** Log function arguments */
+    logArgs?: boolean;
+    /** Log return values */
+    logResult?: boolean;
+    /** Log execution time */
+    logTime?: boolean;
+    /** Custom logger instance */
+    logger?: ReturnType<typeof createLogger>;
+}
+/**
+ * Observe and debug async function execution
+ * Wraps an async function to add logging and debugging capabilities
+ *
+ * @example
+ * const debuggedFn = observeDebug(myAsyncFn, { verbose: true, logArgs: true });
+ * await debuggedFn(arg1, arg2);
+ */
+export declare function observeDebug<T extends (...args: any[]) => Promise<any>>(fn: T, options?: ObserveDebugOptions): T;
+/**
+ * Method decorator for observing debug (TypeScript experimental decorators)
+ * This requires "experimentalDecorators": true in tsconfig.json
+ *
+ * @example
+ * class MyClass {
+ *   @observeDebugMethod({ verbose: true })
+ *   async myMethod(arg: string) {
+ *     // method implementation
+ *   }
+ * }
+ */
+export declare function observeDebugMethod(options?: ObserveDebugOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Performance tracking for async functions
+ * Combines time execution tracking with debug observation
+ *
+ * @example
+ * const trackedFn = trackPerformance(myAsyncFn, 'MyOperation');
+ * await trackedFn(arg1, arg2);
+ */
+export declare function trackPerformance<T extends (...args: any[]) => Promise<any>>(fn: T, operationName?: string): T;
+/**
+ * Comprehensive observability wrapper
+ * Combines debugging, performance tracking, and error handling
+ *
+ * @example
+ * const observedFn = withObservability(myAsyncFn, {
+ *   name: 'CriticalOperation',
+ *   debug: true,
+ *   trackPerformance: true,
+ *   onError: (error) => console.error('Operation failed:', error)
+ * });
+ */
+export declare function withObservability<T extends (...args: any[]) => Promise<any>>(fn: T, options?: {
+    name?: string;
+    debug?: boolean;
+    debugOptions?: ObserveDebugOptions;
+    trackPerformance?: boolean;
+    onError?: (error: Error) => void;
+    onSuccess?: (result: any) => void;
+}): T;
+/**
+ * Create a debug trace for a series of operations
+ * Useful for tracking complex workflows
+ */
+type TraceOperation = {
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    status: 'pending' | 'success' | 'error';
+    error?: Error;
+};
+export declare class OperationTrace {
+    private operations;
+    private logger;
+    private traceName;
+    constructor(traceName: string, customLogger?: ReturnType<typeof createLogger>);
+    /**
+     * Start tracking an operation
+     */
+    startOperation(name: string): void;
+    /**
+     * Mark an operation as completed successfully
+     */
+    completeOperation(name: string): void;
+    /**
+     * Mark an operation as failed
+     */
+    failOperation(name: string, error: Error): void;
+    /**
+     * Get trace summary
+     */
+    getSummary(): {
+        traceName: string;
+        totalOperations: number;
+        successCount: number;
+        errorCount: number;
+        pendingCount: number;
+        totalDuration: number;
+        operations: TraceOperation[];
+    };
+    /**
+     * Log trace summary
+     */
+    logSummary(): void;
+}
+/**
+ * Simple performance counter for tracking operation metrics
+ */
+export declare class PerformanceCounter {
+    private counters;
+    private logger;
+    constructor(customLogger?: ReturnType<typeof createLogger>);
+    /**
+     * Record an operation execution
+     */
+    record(operationName: string, durationMs: number): void;
+    /**
+     * Get statistics for an operation
+     */
+    getStats(operationName: string): {
+        count: number;
+        avgTime: number;
+        minTime: number;
+        maxTime: number;
+        totalTime: number;
+    } | null;
+    /**
+     * Get all statistics
+     */
+    getAllStats(): Map<string, ReturnType<PerformanceCounter['getStats']>>;
+    /**
+     * Log statistics summary
+     */
+    logSummary(): void;
+    /**
+     * Reset all counters
+     */
+    reset(): void;
+}
+export {};

package/dist/observability-decorators.js

@@ -0,0 +1,286 @@
+/**
+ * Observability Decorators and Utilities
+ *
+ * Provides debugging and performance tracking capabilities
+ * for browser automation operations.
+ *
+ * Note: TypeScript decorators work differently than Python.
+ * These are implemented as wrapper functions that can be used
+ * in a similar way to decorators.
+ */
+import { createLogger } from './logging-config.js';
+import { time_execution_async } from './utils.js';
+const logger = createLogger('browser_use.observability');
+/**
+ * Observe and debug async function execution
+ * Wraps an async function to add logging and debugging capabilities
+ *
+ * @example
+ * const debuggedFn = observeDebug(myAsyncFn, { verbose: true, logArgs: true });
+ * await debuggedFn(arg1, arg2);
+ */
+export function observeDebug(fn, options = {}) {
+    const { verbose = false, logArgs = true, logResult = false, logTime = true, logger: customLogger = logger, } = options;
+    const wrappedFn = async function (...args) {
+        const fnName = fn.name || 'anonymous';
+        const startTime = Date.now();
+        try {
+            // Log function entry
+            if (verbose) {
+                customLogger.debug(`→ Entering ${fnName}`);
+            }
+            // Log arguments
+            if (logArgs && args.length > 0) {
+                customLogger.debug(`${fnName} arguments:`, args);
+            }
+            // Execute function
+            const result = await fn.apply(this, args);
+            // Log execution time
+            if (logTime) {
+                const duration = Date.now() - startTime;
+                customLogger.debug(`${fnName} completed in ${duration}ms`);
+            }
+            // Log result
+            if (logResult) {
+                customLogger.debug(`${fnName} result:`, result);
+            }
+            // Log function exit
+            if (verbose) {
+                customLogger.debug(`← Exiting ${fnName}`);
+            }
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            customLogger.error(`${fnName} failed after ${duration}ms: ${error.message}`);
+            customLogger.debug(`${fnName} error stack:`, error.stack);
+            throw error;
+        }
+    };
+    // Preserve function name
+    Object.defineProperty(wrappedFn, 'name', {
+        value: fn.name,
+        configurable: true,
+    });
+    return wrappedFn;
+}
+/**
+ * Method decorator for observing debug (TypeScript experimental decorators)
+ * This requires "experimentalDecorators": true in tsconfig.json
+ *
+ * @example
+ * class MyClass {
+ *   @observeDebugMethod({ verbose: true })
+ *   async myMethod(arg: string) {
+ *     // method implementation
+ *   }
+ * }
+ */
+export function observeDebugMethod(options = {}) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = observeDebug(originalMethod, {
+            ...options,
+            logger: options.logger ||
+                createLogger(`${target.constructor.name}.${propertyKey}`),
+        });
+        return descriptor;
+    };
+}
+/**
+ * Performance tracking for async functions
+ * Combines time execution tracking with debug observation
+ *
+ * @example
+ * const trackedFn = trackPerformance(myAsyncFn, 'MyOperation');
+ * await trackedFn(arg1, arg2);
+ */
+export function trackPerformance(fn, operationName) {
+    const name = operationName || fn.name || 'anonymous';
+    return time_execution_async(name)(fn);
+}
+/**
+ * Comprehensive observability wrapper
+ * Combines debugging, performance tracking, and error handling
+ *
+ * @example
+ * const observedFn = withObservability(myAsyncFn, {
+ *   name: 'CriticalOperation',
+ *   debug: true,
+ *   trackPerformance: true,
+ *   onError: (error) => console.error('Operation failed:', error)
+ * });
+ */
+export function withObservability(fn, options = {}) {
+    const { name = fn.name, debug = false, debugOptions = {}, trackPerformance: shouldTrackPerformance = true, onError, onSuccess, } = options;
+    let wrappedFn = fn;
+    // Apply debug observation if requested
+    if (debug) {
+        wrappedFn = observeDebug(wrappedFn, debugOptions);
+    }
+    // Apply performance tracking if requested
+    if (shouldTrackPerformance) {
+        wrappedFn = trackPerformance(wrappedFn, name);
+    }
+    // Add error/success callbacks
+    if (onError || onSuccess) {
+        const callbackFn = async function (...args) {
+            try {
+                const result = await wrappedFn.apply(this, args);
+                if (onSuccess) {
+                    onSuccess(result);
+                }
+                return result;
+            }
+            catch (error) {
+                if (onError) {
+                    onError(error);
+                }
+                throw error;
+            }
+        };
+        wrappedFn = callbackFn;
+    }
+    return wrappedFn;
+}
+export class OperationTrace {
+    operations = [];
+    logger;
+    traceName;
+    constructor(traceName, customLogger) {
+        this.traceName = traceName;
+        this.logger = customLogger || createLogger(`trace.${traceName}`);
+    }
+    /**
+     * Start tracking an operation
+     */
+    startOperation(name) {
+        this.operations.push({
+            name,
+            startTime: Date.now(),
+            status: 'pending',
+        });
+        this.logger.debug(`Started operation: ${name}`);
+    }
+    /**
+     * Mark an operation as completed successfully
+     */
+    completeOperation(name) {
+        const op = this.operations.find((o) => o.name === name && o.status === 'pending');
+        if (op) {
+            op.endTime = Date.now();
+            op.duration = op.endTime - op.startTime;
+            op.status = 'success';
+            this.logger.debug(`Completed operation: ${name} (${op.duration}ms)`);
+        }
+    }
+    /**
+     * Mark an operation as failed
+     */
+    failOperation(name, error) {
+        const op = this.operations.find((o) => o.name === name && o.status === 'pending');
+        if (op) {
+            op.endTime = Date.now();
+            op.duration = op.endTime - op.startTime;
+            op.status = 'error';
+            op.error = error;
+            this.logger.error(`Failed operation: ${name} (${op.duration}ms) - ${error.message}`);
+        }
+    }
+    /**
+     * Get trace summary
+     */
+    getSummary() {
+        const successCount = this.operations.filter((o) => o.status === 'success').length;
+        const errorCount = this.operations.filter((o) => o.status === 'error').length;
+        const pendingCount = this.operations.filter((o) => o.status === 'pending').length;
+        const totalDuration = this.operations.reduce((sum, op) => sum + (op.duration || 0), 0);
+        return {
+            traceName: this.traceName,
+            totalOperations: this.operations.length,
+            successCount,
+            errorCount,
+            pendingCount,
+            totalDuration,
+            operations: this.operations,
+        };
+    }
+    /**
+     * Log trace summary
+     */
+    logSummary() {
+        const summary = this.getSummary();
+        this.logger.info(`Trace "${this.traceName}" completed: ${summary.successCount} succeeded, ${summary.errorCount} failed, ${summary.pendingCount} pending (total: ${summary.totalDuration}ms)`);
+    }
+}
+/**
+ * Simple performance counter for tracking operation metrics
+ */
+export class PerformanceCounter {
+    counters = new Map();
+    logger;
+    constructor(customLogger) {
+        this.logger = customLogger || createLogger('performance_counter');
+    }
+    /**
+     * Record an operation execution
+     */
+    record(operationName, durationMs) {
+        const current = this.counters.get(operationName) || {
+            count: 0,
+            totalTime: 0,
+            minTime: Infinity,
+            maxTime: 0,
+        };
+        this.counters.set(operationName, {
+            count: current.count + 1,
+            totalTime: current.totalTime + durationMs,
+            minTime: Math.min(current.minTime, durationMs),
+            maxTime: Math.max(current.maxTime, durationMs),
+        });
+    }
+    /**
+     * Get statistics for an operation
+     */
+    getStats(operationName) {
+        const counter = this.counters.get(operationName);
+        if (!counter) {
+            return null;
+        }
+        return {
+            count: counter.count,
+            avgTime: counter.totalTime / counter.count,
+            minTime: counter.minTime,
+            maxTime: counter.maxTime,
+            totalTime: counter.totalTime,
+        };
+    }
+    /**
+     * Get all statistics
+     */
+    getAllStats() {
+        const stats = new Map();
+        for (const [name] of this.counters) {
+            stats.set(name, this.getStats(name));
+        }
+        return stats;
+    }
+    /**
+     * Log statistics summary
+     */
+    logSummary() {
+        this.logger.info('Performance Counter Summary:');
+        for (const [name, stats] of this.getAllStats()) {
+            if (stats) {
+                this.logger.info(`  ${name}: count=${stats.count}, avg=${stats.avgTime.toFixed(2)}ms, min=${stats.minTime.toFixed(2)}ms, max=${stats.maxTime.toFixed(2)}ms`);
+            }
+        }
+    }
+    /**
+     * Reset all counters
+     */
+    reset() {
+        this.counters.clear();
+        this.logger.debug('Performance counters reset');
+    }
+}

package/dist/observability.d.ts

@@ -0,0 +1,23 @@
+type SpanType = 'DEFAULT' | 'LLM' | 'TOOL';
+export interface ObserveOptions {
+    name?: string | null;
+    ignoreInput?: boolean;
+    ignoreOutput?: boolean;
+    metadata?: Record<string, unknown> | null;
+    spanType?: SpanType;
+    [key: string]: unknown;
+}
+type AnyFunc = (...args: any[]) => any;
+type Decorator<T extends AnyFunc> = (fn: T) => T;
+export declare const observe: (options?: ObserveOptions) => Decorator<AnyFunc>;
+export declare const observeDebug: (options?: ObserveOptions) => Decorator<AnyFunc>;
+export declare const observe_debug: (options?: ObserveOptions) => Decorator<AnyFunc>;
+export declare const isLmnrAvailable: () => boolean;
+export declare const isDebugMode: () => boolean;
+export declare const getObservabilityStatus: () => {
+    lmnrAvailable: boolean;
+    debugMode: boolean;
+    observeActive: boolean;
+    observeDebugActive: boolean;
+};
+export {};

package/dist/observability.js

@@ -0,0 +1,58 @@
+import { createRequire } from 'node:module';
+import { config as loadEnv } from 'dotenv';
+import { createLogger } from './logging-config.js';
+loadEnv();
+const require = createRequire(import.meta.url);
+const logger = createLogger('browser_use.observability');
+let lmnrObserve = null;
+let lmnrAvailable = false;
+try {
+    const lmnr = require('lmnr');
+    if (typeof lmnr?.observe === 'function') {
+        lmnrObserve = (options) => lmnr.observe(options);
+        lmnrAvailable = true;
+        if (process.env.BROWSER_USE_VERBOSE_OBSERVABILITY?.toLowerCase() === 'true') {
+            logger.info('Lmnr is available for observability');
+        }
+    }
+}
+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})`);
+    }
+}
+const isDebugModeEnv = () => process.env.LMNR_LOGGING_LEVEL?.toLowerCase() === 'debug';
+const createNoopDecorator = () => (fn) => fn;
+const normalizeOptions = (options = {}) => ({
+    name: options.name ?? null,
+    ignoreInput: options.ignoreInput ?? false,
+    ignoreOutput: options.ignoreOutput ?? false,
+    metadata: options.metadata ?? null,
+    spanType: options.spanType ?? 'DEFAULT',
+    ...options,
+});
+export const observe = (options = {}) => {
+    const normalized = normalizeOptions(options);
+    if (lmnrAvailable && lmnrObserve) {
+        return lmnrObserve(normalized);
+    }
+    return createNoopDecorator();
+};
+export const observeDebug = (options = {}) => {
+    const normalized = normalizeOptions(options);
+    if (lmnrAvailable && lmnrObserve && isDebugModeEnv()) {
+        return lmnrObserve(normalized);
+    }
+    return createNoopDecorator();
+};
+export const observe_debug = observeDebug;
+export const isLmnrAvailable = () => lmnrAvailable;
+export const isDebugMode = () => isDebugModeEnv();
+export const getObservabilityStatus = () => ({
+    lmnrAvailable,
+    debugMode: isDebugModeEnv(),
+    observeActive: lmnrAvailable,
+    observeDebugActive: lmnrAvailable && isDebugModeEnv(),
+});

package/dist/screenshots/index.d.ts

@@ -0,0 +1 @@
+export * from './service.js';

package/dist/screenshots/index.js

@@ -0,0 +1 @@
+export * from './service.js';

package/dist/screenshots/service.d.ts

@@ -0,0 +1,6 @@
+export declare class ScreenshotService {
+    private screenshotsDir;
+    constructor(agentDirectory: string);
+    store_screenshot(screenshot_b64: string, step_number: number): Promise<string>;
+    get_screenshot(screenshot_path: string): Promise<string | null>;
+}

package/dist/screenshots/service.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const decodeBase64 = (data) => Buffer.from(data, 'base64');
+export class ScreenshotService {
+    screenshotsDir;
+    constructor(agentDirectory) {
+        this.screenshotsDir = path.join(agentDirectory, 'screenshots');
+        fs.mkdirSync(this.screenshotsDir, { recursive: true });
+    }
+    async store_screenshot(screenshot_b64, step_number) {
+        const filename = `step_${step_number}.png`;
+        const filepath = path.join(this.screenshotsDir, filename);
+        await fs.promises.writeFile(filepath, decodeBase64(screenshot_b64));
+        return filepath;
+    }
+    async get_screenshot(screenshot_path) {
+        if (!screenshot_path) {
+            return null;
+        }
+        try {
+            const data = await fs.promises.readFile(screenshot_path);
+            return data.toString('base64');
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/sync/auth.d.ts

@@ -0,0 +1,27 @@
+import { type AxiosInstance } from 'axios';
+export declare const TEMP_USER_ID = "99999999-9999-9999-9999-999999999999";
+export declare class DeviceAuthClient {
+    private readonly baseUrl;
+    private readonly clientId;
+    private readonly scope;
+    private readonly httpClient?;
+    private authConfig;
+    private _deviceId;
+    constructor(baseUrl?: string, httpClient?: AxiosInstance);
+    get device_id(): string;
+    get is_authenticated(): boolean;
+    get api_token(): string | null;
+    get user_id(): string;
+    private get client();
+    private buildUrl;
+    private postForm;
+    start_device_authorization(agent_session_id?: string | null): Promise<Record<string, any>>;
+    poll_for_token(device_code: string, interval?: number, timeout?: number): Promise<Record<string, any> | null>;
+    authenticate(agent_session_id?: string | null, show_instructions?: boolean): Promise<boolean>;
+    get_headers(): {
+        Authorization: string;
+    } | {
+        Authorization?: undefined;
+    };
+    clear_auth(): void;
+}