browser-use 0.0.1 → 0.1.0

package/dist/filesystem/file-system.js

@@ -0,0 +1,412 @@
+import fsSync from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import PDFDocument from 'pdfkit';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+const require = createRequire(import.meta.url);
+const pdfParse = require('pdf-parse');
+export const INVALID_FILENAME_ERROR_MESSAGE = 'Error: Invalid filename format. Must be alphanumeric with supported extension.';
+export const DEFAULT_FILE_SYSTEM_PATH = 'browseruse_agent_data';
+const DEFAULT_EXTENSIONS = ['md', 'txt', 'json', 'csv', 'pdf'];
+const filenameRegex = new RegExp(`^[a-zA-Z0-9_\\-]+\\.(${DEFAULT_EXTENSIONS.join('|')})$`);
+export class FileSystemError extends Error {
+}
+class BaseFile {
+    name;
+    content;
+    constructor(name, content = '') {
+        this.name = name;
+        this.content = content;
+    }
+    get fullName() {
+        return `${this.name}.${this.extension}`;
+    }
+    get size() {
+        return this.content.length;
+    }
+    get lineCount() {
+        return this.content ? this.content.split(/\r?\n/).length : 0;
+    }
+    writeFileContent(content) {
+        this.content = content;
+    }
+    appendFileContent(content) {
+        this.content = `${this.content}${content}`;
+    }
+    read() {
+        return this.content;
+    }
+    async syncToDisk(dir) {
+        await fsp.writeFile(path.join(dir, this.fullName), this.content, 'utf-8');
+    }
+    syncToDiskSync(dir) {
+        fsSync.writeFileSync(path.join(dir, this.fullName), this.content, 'utf-8');
+    }
+    async write(content, dir) {
+        this.writeFileContent(content);
+        await this.syncToDisk(dir);
+    }
+    writeSync(content, dir) {
+        this.writeFileContent(content);
+        this.syncToDiskSync(dir);
+    }
+    async append(content, dir) {
+        this.appendFileContent(content);
+        await this.syncToDisk(dir);
+    }
+    appendSync(content, dir) {
+        this.appendFileContent(content);
+        this.syncToDiskSync(dir);
+    }
+    toJSON() {
+        return { name: this.name, content: this.content };
+    }
+}
+class MarkdownFile extends BaseFile {
+    get extension() {
+        return 'md';
+    }
+}
+class TxtFile extends BaseFile {
+    get extension() {
+        return 'txt';
+    }
+}
+class JsonFile extends BaseFile {
+    get extension() {
+        return 'json';
+    }
+}
+class CsvFile extends BaseFile {
+    get extension() {
+        return 'csv';
+    }
+}
+class PdfFile extends BaseFile {
+    get extension() {
+        return 'pdf';
+    }
+    async syncToDisk(dir) {
+        const filePath = path.join(dir, this.fullName);
+        await new Promise((resolve, reject) => {
+            const doc = new PDFDocument({ autoFirstPage: true });
+            const stream = fsSync.createWriteStream(filePath);
+            doc.pipe(stream);
+            doc.fontSize(12).text(this.content || '', { width: 500, align: 'left' });
+            doc.end();
+            stream.on('finish', resolve);
+            stream.on('error', reject);
+        });
+    }
+    syncToDiskSync(dir) {
+        const filePath = path.join(dir, this.fullName);
+        const script = `
+const { createWriteStream } = require('fs');
+const PDFDocument = require(${JSON.stringify(require.resolve('pdfkit'))});
+const filePath = ${JSON.stringify(filePath)};
+const content = ${JSON.stringify(this.content ?? '')};
+const doc = new PDFDocument({ autoFirstPage: true });
+const stream = createWriteStream(filePath);
+doc.pipe(stream);
+doc.fontSize(12).text(content || '', { width: 500, align: 'left' });
+doc.end();
+stream.on('finish', () => process.exit(0));
+stream.on('error', (err) => {
+	console.error(err);
+	process.exit(1);
+});
+`;
+        const result = spawnSync(process.execPath, ['-e', script], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        if (result.status !== 0) {
+            const errorMsg = result.stderr?.toString() ||
+                `Could not write to file '${this.fullName}'.`;
+            throw new FileSystemError(`Error: ${errorMsg.trim()}`);
+        }
+    }
+}
+const FILE_TYPES = {
+    md: MarkdownFile,
+    txt: TxtFile,
+    json: JsonFile,
+    csv: CsvFile,
+    pdf: PdfFile,
+};
+const TYPE_NAME_MAP = {
+    MarkdownFile,
+    TxtFile,
+    JsonFile,
+    CsvFile,
+    PdfFile,
+};
+export class FileSystem {
+    files = new Map();
+    defaultFiles = ['todo.md'];
+    baseDir;
+    dataDir;
+    extractedContentCount = 0;
+    constructor(baseDir, createDefaultFiles = true) {
+        this.baseDir = path.resolve(baseDir);
+        fsSync.mkdirSync(this.baseDir, { recursive: true });
+        this.dataDir = path.join(this.baseDir, DEFAULT_FILE_SYSTEM_PATH);
+        if (fsSync.existsSync(this.dataDir)) {
+            fsSync.rmSync(this.dataDir, { recursive: true, force: true });
+        }
+        fsSync.mkdirSync(this.dataDir, { recursive: true });
+        if (createDefaultFiles) {
+            this.createDefaultFiles();
+        }
+    }
+    createDefaultFiles() {
+        for (const filename of this.defaultFiles) {
+            const file = this.instantiateFile(filename);
+            this.files.set(filename, file);
+            fsSync.writeFileSync(path.join(this.dataDir, filename), file.read(), 'utf-8');
+        }
+    }
+    isValidFilename(filename) {
+        return filenameRegex.test(filename);
+    }
+    parseFilename(filename) {
+        const idx = filename.lastIndexOf('.');
+        if (idx === -1) {
+            throw new FileSystemError(INVALID_FILENAME_ERROR_MESSAGE);
+        }
+        const name = filename.slice(0, idx);
+        const extension = filename.slice(idx + 1).toLowerCase();
+        return [name, extension];
+    }
+    getFileClass(extension) {
+        return FILE_TYPES[extension];
+    }
+    instantiateFile(fullFilename, content = '') {
+        const [name, extension] = this.parseFilename(fullFilename);
+        const FileCtor = this.getFileClass(extension);
+        if (!FileCtor) {
+            throw new FileSystemError(INVALID_FILENAME_ERROR_MESSAGE);
+        }
+        return new FileCtor(name, content);
+    }
+    get_allowed_extensions() {
+        return Object.keys(FILE_TYPES);
+    }
+    get_dir() {
+        return this.dataDir;
+    }
+    get_file(filename) {
+        return this.files.get(filename) ?? null;
+    }
+    list_files() {
+        return Array.from(this.files.values()).map((file) => file.fullName);
+    }
+    display_file(filename) {
+        if (!this.isValidFilename(filename)) {
+            return null;
+        }
+        const file = this.get_file(filename);
+        return file ? file.read() : null;
+    }
+    async read_file(filename, externalFile = false) {
+        if (externalFile) {
+            try {
+                const [, extension] = this.parseFilename(filename);
+                if (['md', 'txt', 'json', 'csv'].includes(extension)) {
+                    const content = await fsp.readFile(filename, 'utf-8');
+                    return `Read from file ${filename}.\n<content>\n${content}\n</content>`;
+                }
+                if (extension === 'pdf') {
+                    const buffer = await fsp.readFile(filename);
+                    const parsed = await pdfParse(buffer);
+                    const totalPages = parsed.numpages ?? 0;
+                    const extraPages = Math.max(0, totalPages - 10);
+                    const snippet = parsed.text?.trim() || '';
+                    const preview = snippet
+                        .split(/\n{2,}/)
+                        .slice(0, 10)
+                        .join('\n\n');
+                    const suffix = extraPages > 0 ? `\n${extraPages} more pages...` : '';
+                    return `Read from file ${filename}.\n<content>\n${preview}${suffix}\n</content>`;
+                }
+                return `Error: Cannot read file ${filename} as ${extension} extension is not supported.`;
+            }
+            catch (error) {
+                if (error?.code === 'ENOENT') {
+                    return `Error: File '${filename}' not found.`;
+                }
+                if (error?.code === 'EACCES') {
+                    return `Error: Permission denied to read file '${filename}'.`;
+                }
+                return `Error: Could not read file '${filename}'.`;
+            }
+        }
+        if (!this.isValidFilename(filename)) {
+            return INVALID_FILENAME_ERROR_MESSAGE;
+        }
+        const file = this.get_file(filename);
+        if (!file) {
+            return `File '${filename}' not found.`;
+        }
+        try {
+            const content = file.read();
+            return `Read from file ${filename}.\n<content>\n${content}\n</content>`;
+        }
+        catch (error) {
+            return error instanceof FileSystemError
+                ? error.message
+                : `Error: Could not read file '${filename}'.`;
+        }
+    }
+    async write_file(filename, content) {
+        if (!this.isValidFilename(filename)) {
+            return INVALID_FILENAME_ERROR_MESSAGE;
+        }
+        const file = this.files.get(filename) ?? this.instantiateFile(filename);
+        this.files.set(filename, file);
+        try {
+            await file.write(content, this.dataDir);
+            return `Data written to file ${filename} successfully.`;
+        }
+        catch (error) {
+            return `Error: Could not write to file '${filename}'. ${error.message}`;
+        }
+    }
+    async append_file(filename, content) {
+        if (!this.isValidFilename(filename)) {
+            return INVALID_FILENAME_ERROR_MESSAGE;
+        }
+        const file = this.get_file(filename);
+        if (!file) {
+            return `File '${filename}' not found.`;
+        }
+        try {
+            await file.append(content, this.dataDir);
+            return `Data appended to file ${filename} successfully.`;
+        }
+        catch (error) {
+            return `Error: Could not append to file '${filename}'. ${error.message}`;
+        }
+    }
+    async replace_file_str(filename, oldStr, newStr) {
+        if (!this.isValidFilename(filename)) {
+            return INVALID_FILENAME_ERROR_MESSAGE;
+        }
+        if (!oldStr) {
+            return 'Error: Cannot replace empty string. Please provide a non-empty string to replace.';
+        }
+        const file = this.get_file(filename);
+        if (!file) {
+            return `File '${filename}' not found.`;
+        }
+        try {
+            const content = file.read().replaceAll(oldStr, newStr);
+            await file.write(content, this.dataDir);
+            return `Successfully replaced all occurrences of "${oldStr}" with "${newStr}" in file ${filename}`;
+        }
+        catch (error) {
+            return `Error: Could not replace string in file '${filename}'. ${error.message}`;
+        }
+    }
+    async save_extracted_content(content) {
+        const filename = `extracted_content_${this.extractedContentCount}.md`;
+        const file = new MarkdownFile(`extracted_content_${this.extractedContentCount}`);
+        await file.write(content, this.dataDir);
+        this.files.set(filename, file);
+        this.extractedContentCount += 1;
+        return `Extracted content saved to file ${filename} successfully.`;
+    }
+    describe() {
+        const DISPLAY_CHARS = 400;
+        let description = '';
+        for (const file of this.files.values()) {
+            if (file.fullName === 'todo.md') {
+                continue;
+            }
+            const content = file.read();
+            if (!content) {
+                description += `<file>\n${file.fullName} - [empty file]\n</file>\n`;
+                continue;
+            }
+            const lines = content.split(/\r?\n/);
+            const lineCount = lines.length;
+            if (content.length < DISPLAY_CHARS * 1.5) {
+                description += `<file>\n${file.fullName} - ${lineCount} lines\n<content>\n${content}\n</content>\n</file>\n`;
+                continue;
+            }
+            const halfChars = Math.floor(DISPLAY_CHARS / 2);
+            let startPreview = '';
+            let startLines = 0;
+            let accumulated = 0;
+            for (const line of lines) {
+                if (accumulated + line.length + 1 > halfChars) {
+                    break;
+                }
+                startPreview += `${line}\n`;
+                accumulated += line.length + 1;
+                startLines += 1;
+            }
+            let endPreview = '';
+            let endLines = 0;
+            accumulated = 0;
+            for (let i = lines.length - 1; i >= 0; i -= 1) {
+                const line = lines[i];
+                if (accumulated + line.length + 1 > halfChars) {
+                    break;
+                }
+                endPreview = `${line}\n${endPreview}`;
+                accumulated += line.length + 1;
+                endLines += 1;
+            }
+            const middleLines = lineCount - startLines - endLines;
+            if (middleLines <= 0) {
+                description += `<file>\n${file.fullName} - ${lineCount} lines\n<content>\n${content}\n</content>\n</file>\n`;
+                continue;
+            }
+            description += `<file>\n${file.fullName} - ${lineCount} lines\n<content>\n${startPreview.trim()}\n`;
+            description += `... ${middleLines} more lines ...\n`;
+            description += `${endPreview.trim()}\n</content>\n</file>\n`;
+        }
+        return description.trim();
+    }
+    get_todo_contents() {
+        const todo = this.get_file('todo.md');
+        return todo?.read() ?? '';
+    }
+    get_state() {
+        const files = {};
+        for (const [filename, file] of this.files.entries()) {
+            files[filename] = { type: file.constructor.name, data: file.toJSON() };
+        }
+        return {
+            files,
+            base_dir: this.baseDir,
+            extracted_content_count: this.extractedContentCount,
+        };
+    }
+    async nuke() {
+        await fsp.rm(this.dataDir, { recursive: true, force: true });
+    }
+    static from_state_sync(state) {
+        const fsInstance = new FileSystem(state.base_dir, false);
+        fsInstance.extractedContentCount = state.extracted_content_count;
+        for (const [filename, fileState] of Object.entries(state.files)) {
+            const FileCtor = TYPE_NAME_MAP[fileState.type];
+            if (!FileCtor) {
+                continue;
+            }
+            const file = new FileCtor(fileState.data.name, fileState.data.content);
+            fsInstance.files.set(filename, file);
+            try {
+                file.writeSync(fileState.data.content, fsInstance.dataDir);
+            }
+            catch (error) {
+                throw new FileSystemError(`Error restoring file '${filename}': ${error.message}`);
+            }
+        }
+        return fsInstance;
+    }
+    static async from_state(state) {
+        return FileSystem.from_state_sync(state);
+    }
+}

package/dist/filesystem/index.d.ts

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

package/dist/filesystem/index.js

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

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export * from './config.js';
+export * from './logging-config.js';
+export { observe, observe_debug, isLmnrAvailable, isDebugMode, getObservabilityStatus, } from './observability.js';
+export { observeDebug, observeDebugMethod, OperationTrace, trackPerformance, withObservability, PerformanceCounter, } from './observability-decorators.js';
+export { URLNotAllowedError as BaseURLNotAllowedError } from './exceptions.js';
+export * from './utils.js';
+export * from './browser/index.js';
+export * from './dom/views.js';
+export * from './dom/history-tree-processor/view.js';
+export * from './dom/history-tree-processor/service.js';
+export * from './dom/service.js';
+export * from './dom/clickable-element-processor/service.js';
+export * from './screenshots/service.js';
+export * from './controller/views.js';
+export * from './controller/registry/service.js';
+export * from './controller/service.js';
+export * from './filesystem/file-system.js';
+export * from './agent/views.js';
+export * from './telemetry/views.js';
+export * from './telemetry/service.js';
+export * from './llm/messages.js';
+export * from './llm/views.js';
+export * from './llm/base.js';
+export * from './llm/exceptions.js';
+export * from './llm/schema.js';
+export * from './tokens/views.js';
+export * from './agent/message-manager/views.js';
+export * from './agent/prompts.js';
+export * from './agent/message-manager/service.js';
+export * from './agent/service.js';
+export * from './agent/message-manager/utils.js';

package/dist/index.js

@@ -0,0 +1,33 @@
+export * from './config.js';
+export * from './logging-config.js';
+// Export observability - note observeDebug exists in both files
+export { observe, observe_debug, isLmnrAvailable, isDebugMode, getObservabilityStatus, } from './observability.js';
+export { observeDebug, observeDebugMethod, OperationTrace, trackPerformance, withObservability, PerformanceCounter, } from './observability-decorators.js';
+// Export exceptions - note URLNotAllowedError defined in both exceptions.js and browser/views.js
+export { URLNotAllowedError as BaseURLNotAllowedError } from './exceptions.js';
+export * from './utils.js';
+export * from './browser/index.js';
+export * from './dom/views.js';
+export * from './dom/history-tree-processor/view.js';
+export * from './dom/history-tree-processor/service.js';
+export * from './dom/service.js';
+export * from './dom/clickable-element-processor/service.js';
+export * from './screenshots/service.js';
+export * from './controller/views.js';
+export * from './controller/registry/service.js';
+export * from './controller/service.js';
+export * from './filesystem/file-system.js';
+export * from './agent/views.js';
+export * from './telemetry/views.js';
+export * from './telemetry/service.js';
+export * from './llm/messages.js';
+export * from './llm/views.js';
+export * from './llm/base.js';
+export * from './llm/exceptions.js';
+export * from './llm/schema.js';
+export * from './tokens/views.js';
+export * from './agent/message-manager/views.js';
+export * from './agent/prompts.js';
+export * from './agent/message-manager/service.js';
+export * from './agent/service.js';
+export * from './agent/message-manager/utils.js';

package/dist/integrations/gmail/actions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Gmail Actions for Browser Use
+ * Defines agent actions for Gmail integration including 2FA code retrieval,
+ * email reading, and authentication management.
+ */
+import type { Controller } from '../../controller/service.js';
+import { GmailService } from './service.js';
+/**
+ * Register Gmail actions with the provided controller
+ */
+export declare function registerGmailActions(controller: Controller, gmailService?: GmailService | null, accessToken?: string | null): Controller;
+export declare const register_gmail_actions: typeof registerGmailActions;

package/dist/integrations/gmail/actions.js

@@ -0,0 +1,113 @@
+/**
+ * Gmail Actions for Browser Use
+ * Defines agent actions for Gmail integration including 2FA code retrieval,
+ * email reading, and authentication management.
+ */
+import { z } from 'zod';
+import { createLogger } from '../../logging-config.js';
+import { ActionResult } from '../../agent/views.js';
+import { GmailService } from './service.js';
+const logger = createLogger('browser_use.gmail.actions');
+// Global Gmail service instance - initialized when actions are registered
+let _gmailService = null;
+// Schema for get_recent_emails action
+const GetRecentEmailsParams = z.object({
+    keyword: z
+        .string()
+        .default('')
+        .describe('A single keyword for search, e.g. github, airbnb, etc.'),
+    max_results: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(3)
+        .describe('Maximum number of emails to retrieve (1-50, default: 3)'),
+});
+/**
+ * Register Gmail actions with the provided controller
+ */
+export function registerGmailActions(controller, gmailService, accessToken) {
+    // Use provided service or create a new one with access token if provided
+    if (gmailService) {
+        _gmailService = gmailService;
+    }
+    else if (accessToken) {
+        _gmailService = new GmailService({ access_token: accessToken });
+    }
+    else {
+        _gmailService = new GmailService();
+    }
+    // Register get_recent_emails action
+    controller.registry.action('Get recent emails from the mailbox with a keyword to retrieve verification codes, OTP, 2FA tokens, magic links, or any recent email content. Keep your query a single keyword.', GetRecentEmailsParams)(async (params) => {
+        try {
+            if (!_gmailService) {
+                throw new Error('Gmail service not initialized');
+            }
+            // Ensure authentication
+            if (!_gmailService.isAuthenticated()) {
+                logger.info('📧 Gmail not authenticated, attempting authentication...');
+                const authenticated = await _gmailService.authenticate();
+                if (!authenticated) {
+                    return new ActionResult({
+                        extracted_content: 'Failed to authenticate with Gmail. Please ensure Gmail credentials are set up properly.',
+                        long_term_memory: 'Gmail authentication failed',
+                    });
+                }
+            }
+            // Use specified max_results (1-50, default 3), last 5 minutes
+            const maxResults = params.max_results;
+            const timeFilter = '5m';
+            // Build query with time filter and optional user query
+            const queryParts = [`newer_than:${timeFilter}`];
+            if (params.keyword.trim()) {
+                queryParts.push(params.keyword.trim());
+            }
+            const query = queryParts.join(' ');
+            logger.info(`🔍 Gmail search query: ${query}`);
+            // Get emails
+            const emails = await _gmailService.getRecentEmails({
+                max_results: maxResults,
+                query: query,
+                time_filter: timeFilter,
+            });
+            if (!emails.length) {
+                const queryInfo = params.keyword.trim()
+                    ? ` matching '${params.keyword}'`
+                    : '';
+                const memory = `No recent emails found from last ${timeFilter}${queryInfo}`;
+                return new ActionResult({
+                    extracted_content: memory,
+                    long_term_memory: memory,
+                });
+            }
+            // Format with full email content for large display
+            let content = `Found ${emails.length} recent email${emails.length > 1 ? 's' : ''} from the last ${timeFilter}:\n\n`;
+            for (let i = 0; i < emails.length; i++) {
+                const email = emails[i];
+                content += `Email ${i + 1}:\n`;
+                content += `From: ${email.from}\n`;
+                content += `Subject: ${email.subject}\n`;
+                content += `Date: ${email.date}\n`;
+                content += `Content:\n${email.body}\n`;
+                content += '-'.repeat(50) + '\n\n';
+            }
+            logger.info(`📧 Retrieved ${emails.length} recent emails`);
+            return new ActionResult({
+                extracted_content: content,
+                include_extracted_content_only_once: true,
+                long_term_memory: `Retrieved ${emails.length} recent emails from last ${timeFilter} for query ${query}.`,
+            });
+        }
+        catch (error) {
+            logger.error(`Error getting recent emails: ${error.message || error}`);
+            return new ActionResult({
+                error: `Error getting recent emails: ${error.message || error}`,
+                long_term_memory: 'Failed to get recent emails due to error',
+            });
+        }
+    });
+    return controller;
+}
+// Backward compatibility export
+export const register_gmail_actions = registerGmailActions;

package/dist/integrations/gmail/index.d.ts

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

package/dist/integrations/gmail/index.js

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

package/dist/integrations/gmail/service.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Gmail API Service for Browser Use
+ * Handles Gmail API authentication, email reading, and 2FA code extraction.
+ * This service provides a clean interface for agents to interact with Gmail.
+ */
+import type { gmail_v1 } from 'googleapis';
+export interface EmailData {
+    id: string;
+    thread_id: string;
+    subject: string;
+    from: string;
+    to: string;
+    date: string;
+    timestamp: number;
+    body: string;
+    raw_message: gmail_v1.Schema$Message;
+}
+export declare class GmailService {
+    private static readonly SCOPES;
+    private configDir;
+    private credentialsFile;
+    private tokenFile;
+    private accessToken;
+    private service;
+    private creds;
+    private _authenticated;
+    constructor(options?: {
+        credentials_file?: string;
+        token_file?: string;
+        config_dir?: string;
+        access_token?: string;
+    });
+    /**
+     * Check if Gmail service is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Handle OAuth authentication and token management
+     */
+    authenticate(): Promise<boolean>;
+    /**
+     * Get recent emails with optional query filter
+     */
+    getRecentEmails(options?: {
+        max_results?: number;
+        query?: string;
+        time_filter?: string;
+    }): Promise<EmailData[]>;
+    /**
+     * Parse Gmail message into readable format
+     */
+    private _parseEmail;
+    /**
+     * Extract email body from payload
+     */
+    private _extractBody;
+    /**
+     * Send an email
+     */
+    sendMessage(to: string, subject: string, body: string): Promise<gmail_v1.Schema$Message | null>;
+}