browser-use 0.1.0 → 0.3.0

package/dist/code-use/formatting.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserStateSummary } from '../browser/views.js';
+import type { BrowserSession } from '../browser/session.js';
+export declare const format_browser_state_for_llm: (state: BrowserStateSummary, namespace: Record<string, unknown>, _browser_session: BrowserSession) => Promise<string>;

package/dist/code-use/formatting.js

@@ -0,0 +1,18 @@
+export const format_browser_state_for_llm = async (state, namespace, _browser_session) => {
+    const lines = [];
+    lines.push('## Browser State');
+    lines.push(`**URL:** ${state.url}`);
+    lines.push(`**Title:** ${state.title}`);
+    lines.push('');
+    const vars = Object.keys(namespace)
+        .filter((key) => !key.startsWith('_'))
+        .sort();
+    lines.push(`**Available:** ${vars.length > 0 ? vars.join(', ') : '(none)'}`);
+    lines.push('');
+    const dom = typeof state.llm_representation === 'function'
+        ? state.llm_representation()
+        : '';
+    lines.push('**DOM Structure:**');
+    lines.push(dom || 'Empty DOM tree (you might have to wait for page load)');
+    return lines.join('\n');
+};

package/dist/code-use/index.d.ts

@@ -0,0 +1,6 @@
+export * from './views.js';
+export * from './utils.js';
+export * from './namespace.js';
+export * from './service.js';
+export * from './formatting.js';
+export * from './notebook-export.js';

package/dist/code-use/index.js

@@ -0,0 +1,6 @@
+export * from './views.js';
+export * from './utils.js';
+export * from './namespace.js';
+export * from './service.js';
+export * from './formatting.js';
+export * from './notebook-export.js';

package/dist/code-use/namespace.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserSession } from '../browser/session.js';
+export interface CreateNamespaceOptions {
+    namespace?: Record<string, unknown>;
+}
+export declare const create_namespace: (browser_session: BrowserSession, options?: CreateNamespaceOptions) => Record<string, unknown>;

package/dist/code-use/namespace.js

@@ -0,0 +1,81 @@
+const buildExpression = (source, args) => `(${source})(${args.map((arg) => JSON.stringify(arg)).join(',')})`;
+export const create_namespace = (browser_session, options = {}) => {
+    const namespace = options.namespace ?? {};
+    namespace.browser = browser_session;
+    namespace.navigate = async (url, init = {}) => {
+        await browser_session.navigate_to(url, init);
+    };
+    namespace.go_back = async () => {
+        await browser_session.go_back();
+    };
+    namespace.go_forward = async () => {
+        await browser_session.go_forward();
+    };
+    namespace.refresh = async () => {
+        await browser_session.refresh();
+    };
+    namespace.wait = async (seconds) => {
+        await browser_session.wait(seconds);
+    };
+    namespace.click = async (index) => {
+        const node = await browser_session.get_dom_element_by_index(index);
+        if (!node) {
+            throw new Error(`Element index ${index} not found`);
+        }
+        return browser_session._click_element_node(node);
+    };
+    namespace.input = async (index, text, clear = true) => {
+        const node = await browser_session.get_dom_element_by_index(index);
+        if (!node) {
+            throw new Error(`Element index ${index} not found`);
+        }
+        return browser_session._input_text_element_node(node, text, {
+            clear,
+        });
+    };
+    namespace.select_dropdown = async (index, text) => {
+        const node = await browser_session.get_dom_element_by_index(index);
+        if (!node) {
+            throw new Error(`Element index ${index} not found`);
+        }
+        return browser_session.select_dropdown_option(node, text);
+    };
+    namespace.upload_file = async (index, file_path) => {
+        const node = await browser_session.get_dom_element_by_index(index);
+        if (!node) {
+            throw new Error(`Element index ${index} not found`);
+        }
+        return browser_session.upload_file(node, file_path);
+    };
+    namespace.screenshot = async (full_page = false) => {
+        return browser_session.take_screenshot(full_page);
+    };
+    namespace.send_keys = async (keys) => {
+        await browser_session.send_keys(keys);
+    };
+    namespace.evaluate = async (code, ...args) => {
+        const page = await browser_session.get_current_page();
+        if (!page) {
+            throw new Error('No active page for evaluate');
+        }
+        if (typeof code === 'function') {
+            return page.evaluate(code, ...args);
+        }
+        if (args.length === 0) {
+            return page.evaluate(code);
+        }
+        return page.evaluate(buildExpression(code, args));
+    };
+    namespace.done = (result = null, success = true) => {
+        namespace._task_done = true;
+        namespace._task_success = success;
+        namespace._task_result =
+            typeof result === 'string'
+                ? result
+                : result == null
+                    ? null
+                    : JSON.stringify(result);
+        return result;
+    };
+    return namespace;
+};

package/dist/code-use/notebook-export.d.ts

@@ -0,0 +1,3 @@
+import type { CodeAgent } from './service.js';
+export declare const export_to_ipynb: (agent: CodeAgent, output_path: string) => string;
+export declare const session_to_python_script: (agent: CodeAgent) => string;

package/dist/code-use/notebook-export.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const export_to_ipynb = (agent, output_path) => {
+    const notebook = {
+        nbformat: 4,
+        nbformat_minor: 5,
+        metadata: {
+            kernelspec: {
+                display_name: 'Node.js',
+                language: 'javascript',
+                name: 'javascript',
+            },
+        },
+        cells: agent.session.cells.map((cell) => {
+            if (cell.cell_type === 'markdown') {
+                return {
+                    cell_type: 'markdown',
+                    metadata: {},
+                    source: cell.source.split('\n').map((entry) => `${entry}\n`),
+                };
+            }
+            return {
+                cell_type: 'code',
+                metadata: {},
+                source: cell.source.split('\n').map((entry) => `${entry}\n`),
+                execution_count: cell.execution_count,
+                outputs: cell.output
+                    ? [
+                        {
+                            output_type: 'stream',
+                            name: 'stdout',
+                            text: `${cell.output}\n`,
+                        },
+                    ]
+                    : [],
+            };
+        }),
+    };
+    const resolved = path.resolve(output_path);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, JSON.stringify(notebook, null, 2), 'utf-8');
+    return resolved;
+};
+export const session_to_python_script = (agent) => {
+    const lines = [];
+    lines.push('# Generated from browser-use code-use session');
+    lines.push('');
+    for (const cell of agent.session.cells) {
+        if (cell.cell_type !== 'code') {
+            continue;
+        }
+        lines.push(cell.source);
+        lines.push('');
+    }
+    return lines.join('\n');
+};

package/dist/code-use/service.d.ts

@@ -0,0 +1,24 @@
+import { CodeAgentHistory, CodeAgentHistoryList, NotebookSession } from './views.js';
+import type { BrowserSession } from '../browser/session.js';
+type ExecutorFn = (source: string, namespace: Record<string, unknown>) => Promise<unknown>;
+export interface CodeAgentOptions {
+    task: string;
+    browser_session: BrowserSession;
+    namespace?: Record<string, unknown>;
+    executor?: ExecutorFn;
+}
+export declare class CodeAgent {
+    task: string;
+    browser_session: BrowserSession;
+    session: NotebookSession;
+    namespace: Record<string, unknown>;
+    complete_history: CodeAgentHistory[];
+    private readonly executor;
+    constructor(options: CodeAgentOptions);
+    add_cell(source: string): import("./views.js").CodeCell;
+    execute_cell(source: string): Promise<import("./views.js").CodeCell>;
+    run(max_steps?: number): Promise<CodeAgentHistoryList>;
+    get history(): CodeAgentHistoryList;
+    close(): Promise<void>;
+}
+export {};

package/dist/code-use/service.js

@@ -0,0 +1,104 @@
+import { CodeAgentHistory, CodeAgentHistoryList, CodeAgentState, CodeAgentStepMetadata, NotebookSession, } from './views.js';
+import { create_namespace } from './namespace.js';
+const AsyncFunction = Object.getPrototypeOf(async function () {
+    return undefined;
+}).constructor;
+const default_executor = async (source, namespace) => {
+    const injectableNames = Object.keys(namespace).filter((name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name));
+    const prelude = injectableNames
+        .map((name) => `const ${name} = namespace[${JSON.stringify(name)}];`)
+        .join('\n');
+    const runner = new AsyncFunction('namespace', `${prelude}\n${source}\nreturn undefined;`);
+    return runner(namespace);
+};
+export class CodeAgent {
+    task;
+    browser_session;
+    session;
+    namespace;
+    complete_history = [];
+    executor;
+    constructor(options) {
+        this.task = options.task;
+        this.browser_session = options.browser_session;
+        this.namespace = create_namespace(options.browser_session, options.namespace ? { namespace: options.namespace } : {});
+        this.session = new NotebookSession({ namespace: this.namespace });
+        this.executor = options.executor ?? default_executor;
+    }
+    add_cell(source) {
+        return this.session.add_cell(source);
+    }
+    async execute_cell(source) {
+        const cell = this.add_cell(source);
+        const startedAt = Date.now() / 1000;
+        cell.status = 'running';
+        cell.execution_count = this.session.increment_execution_count();
+        let resultItem;
+        try {
+            const output = await this.executor(cell.source, this.namespace);
+            cell.status = 'success';
+            cell.output =
+                output == null
+                    ? null
+                    : typeof output === 'string'
+                        ? output
+                        : JSON.stringify(output);
+            cell.error = null;
+            resultItem = {
+                extracted_content: cell.output,
+                error: null,
+                is_done: Boolean(this.namespace._task_done),
+                success: typeof this.namespace._task_success === 'boolean'
+                    ? this.namespace._task_success
+                    : null,
+            };
+        }
+        catch (error) {
+            cell.status = 'error';
+            cell.output = null;
+            cell.error = String(error?.message ?? error);
+            resultItem = {
+                extracted_content: null,
+                error: cell.error,
+                is_done: false,
+                success: false,
+            };
+        }
+        const page = await this.browser_session.get_current_page();
+        const state = new CodeAgentState({
+            url: typeof page?.url === 'function' ? page.url() : null,
+            title: typeof page?.title === 'function' ? await page.title() : null,
+        });
+        const metadata = new CodeAgentStepMetadata({
+            step_start_time: startedAt,
+            step_end_time: Date.now() / 1000,
+        });
+        const modelOutput = {
+            model_output: cell.source,
+            full_response: cell.source,
+        };
+        const historyItem = new CodeAgentHistory({
+            model_output: modelOutput,
+            result: [resultItem],
+            state,
+            metadata,
+        });
+        this.complete_history.push(historyItem);
+        this.session._complete_history = [...this.complete_history];
+        return cell;
+    }
+    async run(max_steps = 100) {
+        const pending = this.session.cells.filter((cell) => cell.status === 'pending');
+        const toRun = pending.slice(0, Math.max(max_steps, 0));
+        for (const cell of toRun) {
+            await this.execute_cell(cell.source);
+        }
+        return this.history;
+    }
+    get history() {
+        return new CodeAgentHistoryList(this.complete_history, null);
+    }
+    async close() {
+        // Keep lifecycle explicit; caller controls browser shutdown.
+    }
+}

package/dist/code-use/utils.d.ts

@@ -0,0 +1,4 @@
+export declare const truncate_message_content: (content: string, max_length?: number) => string;
+export declare const detect_token_limit_issue: (completion: string, completion_tokens: number | null, max_tokens: number | null, stop_reason: string | null) => [boolean, string | null];
+export declare const extract_url_from_task: (task: string) => string | null;
+export declare const extract_code_blocks: (text: string) => Record<string, string>;

package/dist/code-use/utils.js

@@ -0,0 +1,98 @@
+export const truncate_message_content = (content, max_length = 10000) => {
+    if (content.length <= max_length) {
+        return content;
+    }
+    return `${content.slice(0, max_length)}\n\n[... truncated ${content.length - max_length} characters for history]`;
+};
+export const detect_token_limit_issue = (completion, completion_tokens, max_tokens, stop_reason) => {
+    if (stop_reason === 'max_tokens') {
+        return [true, `Response terminated due to max_tokens (${stop_reason})`];
+    }
+    if (completion_tokens != null &&
+        max_tokens != null &&
+        max_tokens > 0 &&
+        completion_tokens / max_tokens >= 0.9) {
+        return [
+            true,
+            `Response used ${(completion_tokens / max_tokens) * 100}% of max_tokens (${completion_tokens}/${max_tokens})`,
+        ];
+    }
+    if (completion.length >= 6) {
+        const last6 = completion.slice(-6);
+        const repeated = completion.split(last6).length - 1;
+        if (repeated >= 40) {
+            return [
+                true,
+                `Repetitive output detected: last 6 chars "${last6}" appears ${repeated} times`,
+            ];
+        }
+    }
+    return [false, null];
+};
+export const extract_url_from_task = (task) => {
+    const withoutEmails = task.replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, '');
+    const matches = [];
+    const patterns = [
+        /https?:\/\/[^\s<>"']+/g,
+        /(?:www\.)?[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*\.[a-zA-Z]{2,}(?:\/[^\s<>"']*)?/g,
+    ];
+    for (const pattern of patterns) {
+        const found = withoutEmails.match(pattern) ?? [];
+        for (const entry of found) {
+            const trimmed = entry.replace(/[.,;:!?()[\]]+$/g, '');
+            matches.push(trimmed.startsWith('http://') || trimmed.startsWith('https://')
+                ? trimmed
+                : `https://${trimmed}`);
+        }
+    }
+    const unique = [...new Set(matches)];
+    if (unique.length !== 1) {
+        return null;
+    }
+    return unique[0];
+};
+export const extract_code_blocks = (text) => {
+    const blocks = {};
+    const regex = /(`{3,})(\w+)(?:\s+(\w+))?\n([\s\S]*?)\1(?:\n|$)/g;
+    let match;
+    let pythonIndex = 0;
+    while ((match = regex.exec(text)) != null) {
+        const langRaw = match[2].toLowerCase();
+        const name = match[3] ?? null;
+        const content = match[4].replace(/\s+$/, '');
+        if (!content) {
+            continue;
+        }
+        const lang = langRaw === 'javascript' || langRaw === 'js'
+            ? 'js'
+            : langRaw === 'markdown' || langRaw === 'md'
+                ? 'markdown'
+                : langRaw === 'sh' || langRaw === 'shell'
+                    ? 'bash'
+                    : langRaw;
+        if (!['python', 'js', 'bash', 'markdown'].includes(lang)) {
+            continue;
+        }
+        if (name) {
+            blocks[name] = content;
+            continue;
+        }
+        if (lang === 'python') {
+            blocks[`python_${pythonIndex}`] = content;
+            pythonIndex += 1;
+            continue;
+        }
+        blocks[lang] = content;
+    }
+    if (pythonIndex > 0) {
+        blocks.python = blocks.python_0;
+    }
+    else {
+        const genericMatches = [...text.matchAll(/```\n([\s\S]*?)```/g)].map((entry) => entry[1].trim());
+        const generic = genericMatches.filter(Boolean).join('\n\n');
+        if (generic) {
+            blocks.python = generic;
+        }
+    }
+    return blocks;
+};

package/dist/code-use/views.d.ts

@@ -0,0 +1,108 @@
+import type { UsageSummary } from '../tokens/views.js';
+export type CellType = 'code' | 'markdown';
+export type ExecutionStatus = 'pending' | 'running' | 'success' | 'error';
+export interface CodeCellInit {
+    id?: string;
+    cell_type?: CellType;
+    source: string;
+    output?: string | null;
+    execution_count?: number | null;
+    status?: ExecutionStatus;
+    error?: string | null;
+    browser_state?: string | null;
+}
+export declare class CodeCell {
+    id: string;
+    cell_type: CellType;
+    source: string;
+    output: string | null;
+    execution_count: number | null;
+    status: ExecutionStatus;
+    error: string | null;
+    browser_state: string | null;
+    constructor(init: CodeCellInit);
+}
+export interface CodeAgentModelOutput {
+    model_output: string;
+    full_response: string;
+}
+export interface CodeAgentResult {
+    extracted_content?: string | null;
+    error?: string | null;
+    is_done: boolean;
+    success?: boolean | null;
+}
+export declare class CodeAgentState {
+    url: string | null;
+    title: string | null;
+    screenshot_path: string | null;
+    constructor(init: {
+        url?: string | null;
+        title?: string | null;
+        screenshot_path?: string | null;
+    });
+    get_screenshot(): string | null;
+}
+export declare class CodeAgentStepMetadata {
+    input_tokens: number | null;
+    output_tokens: number | null;
+    step_start_time: number;
+    step_end_time: number;
+    constructor(init: {
+        input_tokens?: number | null;
+        output_tokens?: number | null;
+        step_start_time: number;
+        step_end_time: number;
+    });
+    get duration_seconds(): number;
+}
+export declare class CodeAgentHistory {
+    model_output: CodeAgentModelOutput | null;
+    result: CodeAgentResult[];
+    state: CodeAgentState;
+    metadata: CodeAgentStepMetadata | null;
+    screenshot_path: string | null;
+    constructor(init: {
+        model_output?: CodeAgentModelOutput | null;
+        result?: CodeAgentResult[];
+        state: CodeAgentState;
+        metadata?: CodeAgentStepMetadata | null;
+        screenshot_path?: string | null;
+    });
+}
+export declare class CodeAgentHistoryList {
+    private readonly complete_history;
+    private readonly usage_summary;
+    constructor(complete_history: CodeAgentHistory[], usage_summary?: UsageSummary | null);
+    get history(): CodeAgentHistory[];
+    get usage(): UsageSummary | null;
+    final_result(): string | null;
+    is_done(): boolean;
+    is_successful(): boolean | null;
+    errors(): (string | null)[];
+    has_errors(): boolean;
+    urls(): (string | null)[];
+    action_results(): CodeAgentResult[];
+    extracted_content(): string[];
+    number_of_steps(): number;
+    total_duration_seconds(): number;
+}
+export declare class NotebookSession {
+    id: string;
+    cells: CodeCell[];
+    current_execution_count: number;
+    namespace: Record<string, unknown>;
+    _complete_history: CodeAgentHistory[];
+    _usage_summary: UsageSummary | null;
+    constructor(init?: {
+        id?: string;
+        cells?: CodeCell[];
+        current_execution_count?: number;
+        namespace?: Record<string, unknown>;
+    });
+    add_cell(source: string): CodeCell;
+    get_cell(cell_id: string): CodeCell | null;
+    get_latest_cell(): CodeCell;
+    increment_execution_count(): number;
+    get history(): CodeAgentHistoryList;
+}