browser-use 0.0.2 → 0.2.0

package/README.md

@@ -47,6 +47,15 @@ We are committed to:
 
 This is **not** a fork or competing project—it's a respectful port to serve a different programming language community.
 
+### Upstream Parity Status
+
+This Node.js/TypeScript implementation is currently **strictly aligned** with the Python `browser-use` release
+[`v0.5.11`](https://github.com/browser-use/browser-use/releases/tag/0.5.11), published on **August 10, 2025**.
+
+- 📦 Core features and behavior are aligned against that upstream tag baseline.
+- ✅ Our test strategy is maintained to be as equivalent as practical to the Python coverage and behavior checks.
+- 🔄 We expect to move this parity baseline forward to the Python **January 2026** release line very soon.
+
 ## Features
 
 - 🤖 **AI-Powered**: Built specifically for LLM-driven web automation with structured output support
@@ -74,6 +83,9 @@ pnpm add browser-use
 
 Playwright browsers will be installed automatically via postinstall hook.
 
+Use only documented public entrypoints such as `browser-use` and
+`browser-use/llm/openai`. Avoid deep imports like `browser-use/dist/...`.
+
 ### Basic Usage with Agent
 
 ```typescript
@@ -145,6 +157,47 @@ const history = await agent.run(10);
 console.log(history.final_result());
 ```
 
+### CLI Usage
+
+```bash
+# Interactive mode (when running in a TTY)
+npx browser-use
+
+# One-shot task
+npx browser-use -p "Go to example.com and extract the page title"
+
+# Positional task mode
+npx browser-use "Search for TypeScript browser automation"
+
+# Pick model/provider by model name
+npx browser-use --model claude-sonnet-4-20250514 -p "Summarize latest AI news"
+
+# Pick provider explicitly (uses provider default model)
+npx browser-use --provider anthropic -p "Summarize latest AI news"
+
+# Headless + custom browser profile settings
+npx browser-use --headless --window-width 1440 --window-height 900 -p "Check dashboard status"
+
+# Restrict navigation to trusted domains (recommended with secrets)
+npx browser-use --allowed-domains "example.com,*.example.org" -p "Log in and fetch account info"
+
+# Connect to existing Chromium via CDP
+npx browser-use --cdp-url http://localhost:9222 -p "Inspect the active tab"
+
+# MCP server mode
+npx browser-use --mcp
+```
+
+Interactive mode commands:
+
+- `help`: show interactive usage
+- `exit`: quit interactive mode
+
+Security notes:
+
+- Prefer `--allowed-domains` whenever tasks involve credentials or sensitive data.
+- `--allow-insecure` disables domain-lockdown enforcement for sensitive data and is unsafe for production.
+
 ## Advanced Usage
 
 ### Vision/Multimodal Support
@@ -565,6 +618,9 @@ yarn test test/integration-advanced.test.ts
 
 # Watch mode
 yarn test:watch
+
+# Validate published package exports
+yarn test:pack
 ```
 
 ### Code Quality
@@ -577,7 +633,7 @@ yarn lint
 yarn prettier
 
 # Type check
-yarn build
+yarn typecheck
 ```
 
 ## Architecture
@@ -585,28 +641,28 @@ yarn build
 The library follows a modular, layered architecture:
 
 ```
-┌─────────────────────────────────────────┐
+┌──────────────────────────────────────────┐
 │            Agent (Orchestrator)          │
 │  - Task execution & planning             │
 │  - LLM message management                │
 │  - Step execution loop                   │
-└─────────┬───────────────────────────────┘
+└─────────┬────────────────────────────────┘
           │
-┌─────────▼───────────────────────────────┐
+┌─────────▼────────────────────────────────┐
 │           Controller (Actions)           │
 │  - Action registry & execution           │
 │  - Built-in actions (30+)                │
 │  - Custom action support                 │
-└─────────┬───────────────────────────────┘
+└─────────┬────────────────────────────────┘
           │
-┌─────────▼───────────────────────────────┐
+┌─────────▼────────────────────────────────┐
 │        BrowserSession (Browser)          │
 │  - Playwright integration                │
 │  - Tab & page management                 │
 │  - Navigation & interaction              │
-└─────────┬───────────────────────────────┘
+└─────────┬────────────────────────────────┘
           │
-┌─────────▼───────────────────────────────┐
+┌─────────▼────────────────────────────────┐
 │         DOMService (DOM Analysis)        │
 │  - Element extraction                    │
 │  - Clickable element detection           │

package/dist/agent/service.d.ts

@@ -69,6 +69,7 @@ interface AgentConstructorParams<Context, AgentStructuredOutput> {
     include_tool_call_examples?: boolean;
     vision_detail_level?: AgentSettings['vision_detail_level'];
     session_attachment_mode?: AgentSettings['session_attachment_mode'];
+    allow_insecure_sensitive_data?: boolean;
     llm_timeout?: number;
     step_timeout?: number;
 }

package/dist/agent/service.js

@@ -7,14 +7,15 @@ import { z } from 'zod';
 import { createLogger } from '../logging-config.js';
 import { CONFIG } from '../config.js';
 import { EventBus } from '../event-bus.js';
-import { uuid7str, SignalHandler, get_browser_use_version, } from '../utils.js';
+import { uuid7str, SignalHandler, get_browser_use_version } from '../utils.js';
 import { Controller as DefaultController } from '../controller/service.js';
 import { FileSystem as AgentFileSystem, DEFAULT_FILE_SYSTEM_PATH, } from '../filesystem/file-system.js';
 import { SystemPrompt } from './prompts.js';
 import { MessageManager } from './message-manager/service.js';
 import { BrowserStateHistory } from '../browser/views.js';
 import { BrowserSession } from '../browser/session.js';
-import { BrowserProfile, DEFAULT_BROWSER_PROFILE, } from '../browser/profile.js';
+import { BrowserProfile, DEFAULT_BROWSER_PROFILE } from '../browser/profile.js';
+import { InsecureSensitiveDataError } from '../exceptions.js';
 import { HistoryTreeProcessor } from '../dom/history-tree-processor/service.js';
 import { DOMHistoryElement } from '../dom/history-tree-processor/view.js';
 import { UserMessage } from '../llm/messages.js';
@@ -128,6 +129,7 @@ const defaultAgentOptions = () => ({
     display_files_in_done_text: true,
     include_tool_call_examples: false,
     session_attachment_mode: 'copy',
+    allow_insecure_sensitive_data: false,
     vision_detail_level: 'auto',
     llm_timeout: 60,
     step_timeout: 180,
@@ -137,7 +139,11 @@ const AgentLLMOutputSchema = z.object({
     evaluation_previous_goal: z.string().optional().nullable(),
     memory: z.string().optional().nullable(),
     next_goal: z.string().optional().nullable(),
-    action: z.array(z.record(z.string(), z.any())).optional().nullable().default([]),
+    action: z
+        .array(z.record(z.string(), z.any()))
+        .optional()
+        .nullable()
+        .default([]),
 });
 const AgentLLMOutputFormat = AgentLLMOutputSchema;
 AgentLLMOutputFormat.schema = AgentLLMOutputSchema;
@@ -198,7 +204,7 @@ export class Agent {
     DoneActionModel = ActionModel;
     DoneAgentOutput = AgentOutput;
     constructor(params) {
-        const { task, llm, page = null, browser = null, browser_context = null, browser_profile = null, browser_session = null, controller = null, sensitive_data = null, initial_actions = null, register_new_step_callback = null, register_done_callback = null, register_external_agent_status_raise_error_callback = null, output_model_schema = null, use_vision = true, save_conversation_path = null, save_conversation_path_encoding = 'utf-8', max_failures = 3, retry_delay = 10, override_system_message = null, extend_system_message = null, validate_output = false, generate_gif = false, available_file_paths = [], include_attributes, max_actions_per_step = 10, use_thinking = true, flash_mode = false, max_history_items = null, page_extraction_llm = null, context = null, source = null, file_system_path = null, task_id = null, cloud_sync = null, calculate_cost = false, display_files_in_done_text = true, include_tool_call_examples = false, vision_detail_level = 'auto', session_attachment_mode = 'copy', llm_timeout = 60, step_timeout = 180, } = { ...defaultAgentOptions(), ...params };
+        const { task, llm, page = null, browser = null, browser_context = null, browser_profile = null, browser_session = null, controller = null, sensitive_data = null, initial_actions = null, register_new_step_callback = null, register_done_callback = null, register_external_agent_status_raise_error_callback = null, output_model_schema = null, use_vision = true, save_conversation_path = null, save_conversation_path_encoding = 'utf-8', max_failures = 3, retry_delay = 10, override_system_message = null, extend_system_message = null, validate_output = false, generate_gif = false, available_file_paths = [], include_attributes, max_actions_per_step = 10, use_thinking = true, flash_mode = false, max_history_items = null, page_extraction_llm = null, context = null, source = null, file_system_path = null, task_id = null, cloud_sync = null, calculate_cost = false, display_files_in_done_text = true, include_tool_call_examples = false, vision_detail_level = 'auto', session_attachment_mode = 'copy', allow_insecure_sensitive_data = false, llm_timeout = 60, step_timeout = 180, } = { ...defaultAgentOptions(), ...params };
         if (!llm) {
             throw new Error('Invalid llm, must be provided');
         }
@@ -249,6 +255,7 @@ export class Agent {
             calculate_cost,
             include_tool_call_examples,
             session_attachment_mode,
+            allow_insecure_sensitive_data,
             llm_timeout,
             step_timeout,
         };
@@ -489,7 +496,7 @@ export class Agent {
         Agent._sharedSessionStepLocks.delete(browser_session.id);
     }
     _init_browser_session(init) {
-        let { page, browser, browser_context, browser_profile, browser_session, } = init;
+        let { page, browser, browser_context, browser_profile, browser_session } = init;
         if (browser instanceof BrowserSession) {
             browser_session = browser_session ?? browser;
             browser = null;
@@ -617,6 +624,9 @@ export class Agent {
             : Boolean(allowedDomainsConfig);
         // If no allowed_domains are configured, show a security warning
         if (!hasAllowedDomains) {
+            if (!this.settings.allow_insecure_sensitive_data) {
+                throw new InsecureSensitiveDataError();
+            }
             this.logger.error('⚠️⚠️⚠️ Agent(sensitive_data=••••••••) was provided but BrowserSession(allowed_domains=[...]) is not locked down! ⚠️⚠️⚠️\n' +
                 '          ☠️ If the agent visits a malicious website and encounters a prompt-injection attack, your sensitive_data may be exposed!\n\n' +
                 '             https://docs.browser-use.com/customize/browser-settings#restrict-urls\n' +
@@ -627,7 +637,7 @@ export class Agent {
                 // User can still abort process with Ctrl+C.
                 this._sleep_blocking(10_000);
             }
-            this.logger.warning('‼️ Continuing with insecure settings for now... but this will become a hard error in the future!');
+            this.logger.warning('‼️ Continuing with insecure settings because allow_insecure_sensitive_data=true is enabled.');
         }
         // If we're using domain-specific credentials, validate domain patterns
         else if (hasDomainSpecificCredentials) {
@@ -1701,7 +1711,7 @@ export class Agent {
             throw new Error('Agent paused');
         }
     }
-    async _handle_post_llm_processing(browser_state_summary, input_messages, actions = []) {
+    async _handle_post_llm_processing(browser_state_summary, input_messages, _actions = []) {
         if (this.register_new_step_callback && this.state.last_model_output) {
             await this.register_new_step_callback(browser_state_summary, this.state.last_model_output, this.state.n_steps);
         }
@@ -1939,7 +1949,9 @@ export class Agent {
                 typeof entry.model_dump === 'function'
                 ? entry.model_dump()
                 : entry;
-            if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            if (!candidate ||
+                typeof candidate !== 'object' ||
+                Array.isArray(candidate)) {
                 return false;
             }
             return Object.keys(candidate).length === 0;
@@ -2018,7 +2030,9 @@ export class Agent {
                 typeof entry.model_dump === 'function'
                 ? entry.model_dump()
                 : entry;
-            if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            if (!candidate ||
+                typeof candidate !== 'object' ||
+                Array.isArray(candidate)) {
                 throw new Error(`Invalid action at index ${i}: expected an object with exactly one action key`);
             }
             const actionObject = candidate;

package/dist/agent/views.d.ts

@@ -55,6 +55,7 @@ export declare class ActionResult {
 }
 export interface AgentSettings {
     session_attachment_mode: 'copy' | 'strict' | 'shared';
+    allow_insecure_sensitive_data: boolean;
     use_vision: boolean;
     vision_detail_level: 'auto' | 'low' | 'high';
     use_vision_for_planner: boolean;

package/dist/agent/views.js

@@ -65,6 +65,7 @@ export class ActionResult {
 }
 export const defaultAgentSettings = () => ({
     session_attachment_mode: 'copy',
+    allow_insecure_sensitive_data: false,
     use_vision: true,
     vision_detail_level: 'auto',
     use_vision_for_planner: false,

package/dist/browser/session.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -52,7 +53,7 @@ export class BrowserSession {
             ? typeof structuredClone === 'function'
                 ? structuredClone(init.browser_profile.config)
                 : JSON.parse(JSON.stringify(init.browser_profile.config))
-            : init.profile ?? {};
+            : (init.profile ?? {});
         this.browser_profile = new BrowserProfile(sourceProfileConfig);
         this.id = init.id ?? uuid7str();
         this.browser = init.browser ?? null;
@@ -493,8 +494,7 @@ export class BrowserSession {
         }
         catch (error) {
             const sandboxEnabled = this.browser_profile.config.chromium_sandbox;
-            if (!sandboxEnabled ||
-                !this._isSandboxLaunchError(error)) {
+            if (!sandboxEnabled || !this._isSandboxLaunchError(error)) {
                 throw error;
             }
             this.logger.warning('Chromium sandbox is unavailable in this environment. Retrying launch with chromium_sandbox=false (--no-sandbox).');
@@ -3094,7 +3094,7 @@ export class BrowserSession {
      */
     _escapeSelector(selector) {
         // Escape special CSS characters
-        return selector.replace(/[!"#$%&'()*+,.\/:;<=>?@\[\\\]^`{|}~]/g, '\\$&');
+        return selector.replace(/[!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, '\\$&');
     }
     // endregion
     // region - User Data Directory Management
@@ -3181,7 +3181,7 @@ export class BrowserSession {
      * Create a temporary user data directory
      */
     async _createTempUserDataDir() {
-        const osTempDir = require('os').tmpdir();
+        const osTempDir = os.tmpdir();
         const tempDir = path.join(osTempDir, `browser-use-${Date.now()}-${Math.random().toString(36).slice(2)}`);
         fs.mkdirSync(tempDir, { recursive: true });
         return tempDir;

package/dist/cli.d.ts

@@ -1,2 +1,38 @@
 #!/usr/bin/env node
+import type { BaseChatModel } from './llm/base.js';
+type CliModelProvider = 'openai' | 'anthropic' | 'google' | 'deepseek' | 'groq' | 'openrouter' | 'azure' | 'aws-anthropic' | 'aws' | 'ollama';
+export interface ParsedCliArgs {
+    help: boolean;
+    version: boolean;
+    debug: boolean;
+    allow_insecure: boolean;
+    headless: boolean | null;
+    window_width: number | null;
+    window_height: number | null;
+    user_data_dir: string | null;
+    profile_directory: string | null;
+    allowed_domains: string[] | null;
+    cdp_url: string | null;
+    model: string | null;
+    provider: CliModelProvider | null;
+    prompt: string | null;
+    mcp: boolean;
+    positional: string[];
+}
+export declare const CLI_HISTORY_LIMIT = 100;
+export declare const parseCliArgs: (argv: string[]) => ParsedCliArgs;
+export declare const isInteractiveExitCommand: (value: string) => boolean;
+export declare const isInteractiveHelpCommand: (value: string) => boolean;
+export declare const normalizeCliHistory: (history: unknown[], maxLength?: number) => string[];
+export declare const getCliHistoryPath: (configDir?: string | null) => string;
+export declare const loadCliHistory: (historyPath?: string) => Promise<string[]>;
+export declare const saveCliHistory: (history: string[], historyPath?: string) => Promise<void>;
+export declare const shouldStartInteractiveMode: (task: string | null, options?: {
+    forceInteractive?: boolean;
+    inputIsTTY?: boolean;
+    outputIsTTY?: boolean;
+}) => boolean;
+export declare const getLlmFromCliArgs: (args: ParsedCliArgs) => BaseChatModel;
+export declare const getCliUsage: () => string;
+export declare function main(argv?: string[]): Promise<void>;
 export {};