chore: import upstream snapshot with attribution

browser_use/integrations/gmail/__init__.py

@@ -0,0 +1,24 @@
+"""
+Gmail Integration for Browser Use
+Provides Gmail API integration for email reading and verification code extraction.
+This integration enables agents to read email content and extract verification codes themselves.
+Usage:
+    from browser_use.integrations.gmail import GmailService, register_gmail_actions
+    # Option 1: Register Gmail actions with file-based authentication
+    tools = Tools()
+    register_gmail_actions(tools)
+    # Option 2: Register Gmail actions with direct access token (recommended for production)
+    tools = Tools()
+    register_gmail_actions(tools, access_token="your_access_token_here")
+    # Option 3: Use the service directly
+    gmail = GmailService(access_token="your_access_token_here")
+    await gmail.authenticate()
+    emails = await gmail.get_recent_emails()
+"""
+
+# @file purpose: Gmail integration for 2FA email authentication and email reading
+
+from .actions import register_gmail_actions
+from .service import GmailService
+
+__all__ = ['GmailService', 'register_gmail_actions']

browser_use/integrations/gmail/actions.py

@@ -0,0 +1,115 @@
+"""
+Gmail Actions for Browser Use
+Defines agent actions for Gmail integration including 2FA code retrieval,
+email reading, and authentication management.
+"""
+
+import logging
+
+from pydantic import BaseModel, Field
+
+from browser_use.agent.views import ActionResult
+from browser_use.tools.service import Tools
+
+from .service import GmailService
+
+logger = logging.getLogger(__name__)
+
+# Global Gmail service instance - initialized when actions are registered
+_gmail_service: GmailService | None = None
+
+
+class GetRecentEmailsParams(BaseModel):
+	"""Parameters for getting recent emails"""
+
+	keyword: str = Field(default='', description='A single keyword for search, e.g. github, airbnb, etc.')
+	max_results: int = Field(default=3, ge=1, le=50, description='Maximum number of emails to retrieve (1-50, default: 3)')
+
+
+def register_gmail_actions(tools: Tools, gmail_service: GmailService | None = None, access_token: str | None = None) -> Tools:
+	"""
+	Register Gmail actions with the provided tools
+	Args:
+	    tools: The browser-use tools to register actions with
+	    gmail_service: Optional pre-configured Gmail service instance
+	    access_token: Optional direct access token (alternative to file-based auth)
+	"""
+	global _gmail_service
+
+	# Use provided service or create a new one with access token if provided
+	if gmail_service:
+		_gmail_service = gmail_service
+	elif access_token:
+		_gmail_service = GmailService(access_token=access_token)
+	else:
+		_gmail_service = GmailService()
+
+	@tools.registry.action(
+		description='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.',
+		param_model=GetRecentEmailsParams,
+	)
+	async def get_recent_emails(params: GetRecentEmailsParams) -> ActionResult:
+		"""Get recent emails from the last 5 minutes with full content"""
+		try:
+			if _gmail_service is None:
+				raise RuntimeError('Gmail service not initialized')
+
+			# Ensure authentication
+			if not _gmail_service.is_authenticated():
+				logger.info('📧 Gmail not authenticated, attempting authentication...')
+				authenticated = await _gmail_service.authenticate()
+				if not authenticated:
+					return 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 10), last 5 minutes
+			max_results = params.max_results
+			time_filter = '5m'
+
+			# Build query with time filter and optional user query
+			query_parts = [f'newer_than:{time_filter}']
+			if params.keyword.strip():
+				query_parts.append(params.keyword.strip())
+
+			query = ' '.join(query_parts)
+			logger.info(f'🔍 Gmail search query: {query}')
+
+			# Get emails
+			emails = await _gmail_service.get_recent_emails(max_results=max_results, query=query, time_filter=time_filter)
+
+			if not emails:
+				query_info = f" matching '{params.keyword}'" if params.keyword.strip() else ''
+				memory = f'No recent emails found from last {time_filter}{query_info}'
+				return ActionResult(
+					extracted_content=memory,
+					long_term_memory=memory,
+				)
+
+			# Format with full email content for large display
+			content = f'Found {len(emails)} recent email{"s" if len(emails) > 1 else ""} from the last {time_filter}:\n\n'
+
+			for i, email in enumerate(emails, 1):
+				content += f'Email {i}:\n'
+				content += f'From: {email["from"]}\n'
+				content += f'Subject: {email["subject"]}\n'
+				content += f'Date: {email["date"]}\n'
+				content += f'Content:\n{email["body"]}\n'
+				content += '-' * 50 + '\n\n'
+
+			logger.info(f'📧 Retrieved {len(emails)} recent emails')
+			return ActionResult(
+				extracted_content=content,
+				include_extracted_content_only_once=True,
+				long_term_memory=f'Retrieved {len(emails)} recent emails from last {time_filter} for query {query}.',
+			)
+
+		except Exception as e:
+			logger.error(f'Error getting recent emails: {e}')
+			return ActionResult(
+				error=f'Error getting recent emails: {str(e)}',
+				long_term_memory='Failed to get recent emails due to error',
+			)
+
+	return tools

browser_use/integrations/gmail/service.py

@@ -0,0 +1,225 @@
+"""
+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 base64
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import anyio
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from browser_use.config import CONFIG
+
+logger = logging.getLogger(__name__)
+
+
+class GmailService:
+	"""
+	Gmail API service for email reading.
+	Provides functionality to:
+	- Authenticate with Gmail API using OAuth2
+	- Read recent emails with filtering
+	- Return full email content for agent analysis
+	"""
+
+	# Gmail API scopes
+	SCOPES = ['https://www.googleapis.com/auth/gmail.readonly']
+
+	def __init__(
+		self,
+		credentials_file: str | None = None,
+		token_file: str | None = None,
+		config_dir: str | None = None,
+		access_token: str | None = None,
+	):
+		"""
+		Initialize Gmail Service
+		Args:
+		    credentials_file: Path to OAuth credentials JSON from Google Cloud Console
+		    token_file: Path to store/load access tokens
+		    config_dir: Directory to store config files (defaults to browser-use config directory)
+		    access_token: Direct access token (skips file-based auth if provided)
+		"""
+		# Set up configuration directory using browser-use's config system
+		if config_dir is None:
+			self.config_dir = CONFIG.BROWSER_USE_CONFIG_DIR
+		else:
+			self.config_dir = Path(config_dir).expanduser().resolve()
+
+		# Ensure config directory exists (only if not using direct token)
+		if access_token is None:
+			self.config_dir.mkdir(parents=True, exist_ok=True)
+
+		# Set up credential paths
+		self.credentials_file = credentials_file or self.config_dir / 'gmail_credentials.json'
+		self.token_file = token_file or self.config_dir / 'gmail_token.json'
+
+		# Direct access token support
+		self.access_token = access_token
+
+		self.service = None
+		self.creds = None
+		self._authenticated = False
+
+	def is_authenticated(self) -> bool:
+		"""Check if Gmail service is authenticated"""
+		return self._authenticated and self.service is not None
+
+	async def authenticate(self) -> bool:
+		"""
+		Handle OAuth authentication and token management
+		Returns:
+		    bool: True if authentication successful, False otherwise
+		"""
+		try:
+			logger.info('🔐 Authenticating with Gmail API...')
+
+			# Check if using direct access token
+			if self.access_token:
+				logger.info('🔑 Using provided access token')
+				# Create credentials from access token
+				self.creds = Credentials(token=self.access_token, scopes=self.SCOPES)
+				# Test token validity by building service
+				self.service = build('gmail', 'v1', credentials=self.creds)
+				self._authenticated = True
+				logger.info('✅ Gmail API ready with access token!')
+				return True
+
+			# Original file-based authentication flow
+			# Try to load existing tokens
+			if os.path.exists(self.token_file):
+				self.creds = Credentials.from_authorized_user_file(str(self.token_file), self.SCOPES)
+				logger.debug('📁 Loaded existing tokens')
+
+			# If no valid credentials, run OAuth flow
+			if not self.creds or not self.creds.valid:
+				if self.creds and self.creds.expired and self.creds.refresh_token:
+					logger.info('🔄 Refreshing expired tokens...')
+					self.creds.refresh(Request())
+				else:
+					logger.info('🌐 Starting OAuth flow...')
+					if not os.path.exists(self.credentials_file):
+						logger.error(
+							f'❌ Gmail credentials file not found: {self.credentials_file}\n'
+							'Please download it from Google Cloud Console:\n'
+							'1. Go to https://console.cloud.google.com/\n'
+							'2. APIs & Services > Credentials\n'
+							'3. Download OAuth 2.0 Client JSON\n'
+							f"4. Save as 'gmail_credentials.json' in {self.config_dir}/"
+						)
+						return False
+
+					flow = InstalledAppFlow.from_client_secrets_file(str(self.credentials_file), self.SCOPES)
+					# Use specific redirect URI to match OAuth credentials
+					self.creds = flow.run_local_server(port=8080, open_browser=True)
+
+				# Save tokens for next time
+				await anyio.Path(self.token_file).write_text(self.creds.to_json())
+				logger.info(f'💾 Tokens saved to {self.token_file}')
+
+			# Build Gmail service
+			self.service = build('gmail', 'v1', credentials=self.creds)
+			self._authenticated = True
+			logger.info('✅ Gmail API ready!')
+			return True
+
+		except Exception as e:
+			logger.error(f'❌ Gmail authentication failed: {e}')
+			return False
+
+	async def get_recent_emails(self, max_results: int = 10, query: str = '', time_filter: str = '1h') -> list[dict[str, Any]]:
+		"""
+		Get recent emails with optional query filter
+		Args:
+		    max_results: Maximum number of emails to fetch
+		    query: Gmail search query (e.g., 'from:noreply@example.com')
+		    time_filter: Time filter (e.g., '5m', '1h', '1d')
+		Returns:
+		    List of email dictionaries with parsed content
+		"""
+		if not self.is_authenticated():
+			logger.error('❌ Gmail service not authenticated. Call authenticate() first.')
+			return []
+
+		try:
+			# Add time filter to query if provided
+			if time_filter and 'newer_than:' not in query:
+				query = f'newer_than:{time_filter} {query}'.strip()
+
+			logger.info(f'📧 Fetching {max_results} recent emails...')
+			if query:
+				logger.debug(f'🔍 Query: {query}')
+
+			# Get message list
+			assert self.service is not None
+			results = self.service.users().messages().list(userId='me', maxResults=max_results, q=query).execute()
+
+			messages = results.get('messages', [])
+			if not messages:
+				logger.info('📭 No messages found')
+				return []
+
+			logger.info(f'📨 Found {len(messages)} messages, fetching details...')
+
+			# Get full message details
+			emails = []
+			for i, message in enumerate(messages, 1):
+				logger.debug(f'📖 Reading email {i}/{len(messages)}...')
+
+				full_message = self.service.users().messages().get(userId='me', id=message['id'], format='full').execute()
+
+				email_data = self._parse_email(full_message)
+				emails.append(email_data)
+
+			return emails
+
+		except HttpError as error:
+			logger.error(f'❌ Gmail API error: {error}')
+			return []
+		except Exception as e:
+			logger.error(f'❌ Unexpected error fetching emails: {e}')
+			return []
+
+	def _parse_email(self, message: dict[str, Any]) -> dict[str, Any]:
+		"""Parse Gmail message into readable format"""
+		headers = {h['name']: h['value'] for h in message['payload']['headers']}
+
+		return {
+			'id': message['id'],
+			'thread_id': message['threadId'],
+			'subject': headers.get('Subject', ''),
+			'from': headers.get('From', ''),
+			'to': headers.get('To', ''),
+			'date': headers.get('Date', ''),
+			'timestamp': int(message['internalDate']),
+			'body': self._extract_body(message['payload']),
+			'raw_message': message,
+		}
+
+	def _extract_body(self, payload: dict[str, Any]) -> str:
+		"""Extract email body from payload"""
+		body = ''
+
+		if payload.get('body', {}).get('data'):
+			# Simple email body
+			body = base64.urlsafe_b64decode(payload['body']['data']).decode('utf-8')
+		elif payload.get('parts'):
+			# Multi-part email
+			for part in payload['parts']:
+				if part['mimeType'] == 'text/plain' and part.get('body', {}).get('data'):
+					part_body = base64.urlsafe_b64decode(part['body']['data']).decode('utf-8')
+					body += part_body
+				elif part['mimeType'] == 'text/html' and not body and part.get('body', {}).get('data'):
+					# Fallback to HTML if no plain text
+					body = base64.urlsafe_b64decode(part['body']['data']).decode('utf-8')
+
+		return body