@agentium/browser 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,330 @@
+import * as _agentium_core from '@agentium/core';
+import { ModelProvider, UnifiedMemoryConfig, CostTracker, LogLevel, EventBus, MemoryManager, ToolDef } from '@agentium/core';
+
+/**
+ * Secure credential store for BrowserAgent.
+ *
+ * Secrets are stored in memory and NEVER sent to the LLM.
+ * The model works with placeholders (e.g. `{{email}}`, `{{password}}`),
+ * and the agent resolves them to real values only at execution time.
+ */
+declare class CredentialVault {
+    private secrets;
+    constructor(initial?: Record<string, string>);
+    /** Store a credential. Key names become the placeholder: `{{key}}`. */
+    set(key: string, value: string): this;
+    /** Retrieve a credential value. Returns undefined if not found. */
+    get(key: string): string | undefined;
+    has(key: string): boolean;
+    /** List available placeholder names (never exposes values). */
+    keys(): string[];
+    /**
+     * Load credentials from environment variables.
+     * Maps env var names to placeholder keys.
+     *
+     * @example
+     * vault.fromEnv({ email: "LOGIN_EMAIL", password: "LOGIN_PASS" });
+     */
+    fromEnv(mapping: Record<string, string>): this;
+    /**
+     * Replace `{{key}}` placeholders in text with actual credential values.
+     * Used internally by BrowserAgent right before executing a type action.
+     */
+    resolve(text: string): string;
+    /**
+     * Replace any occurrence of real credential values in text with
+     * their `{{key}}` placeholder. Used to sanitize logs and action history.
+     */
+    mask(text: string): string;
+}
+
+type BrowserAction = {
+    action: "click";
+    x: number;
+    y: number;
+    description: string;
+} | {
+    action: "type";
+    text: string;
+    x?: number;
+    y?: number;
+} | {
+    action: "scroll";
+    direction: "up" | "down";
+    amount?: number;
+} | {
+    action: "navigate";
+    url: string;
+} | {
+    action: "back";
+} | {
+    action: "wait";
+    ms: number;
+} | {
+    action: "screenshot";
+} | {
+    action: "done";
+    result: string;
+} | {
+    action: "fail";
+    reason: string;
+};
+interface BrowserAgentConfig {
+    name: string;
+    /** Vision-capable model (GPT-4o, Gemini, etc.) */
+    model: ModelProvider;
+    /** Extra instructions appended to the system prompt */
+    instructions?: string;
+    /** Max vision loop iterations. Default: 30 */
+    maxSteps?: number;
+    /** Run browser without visible window. Default: true */
+    headless?: boolean;
+    /** Browser viewport size. Default: 1280x720 */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Initial URL to navigate to before starting the task */
+    startUrl?: string;
+    /** Milliseconds to wait after each action for the page to settle. Default: 1500 */
+    waitAfterAction?: number;
+    /** Max consecutive identical actions before the agent auto-fails. Default: 3 */
+    maxRepeats?: number;
+    /**
+     * Include a simplified DOM/accessibility tree alongside the screenshot.
+     * Helps the model target elements more accurately. Default: false
+     */
+    useDOM?: boolean;
+    /**
+     * Path to a Playwright storageState JSON file.
+     * Restores cookies, localStorage, and sessionStorage from a previous session.
+     */
+    storageState?: string;
+    /**
+     * Enable video recording of the browser session.
+     * Pass `true` for default dir (`./browser-videos`) or `{ dir: "/path" }`.
+     */
+    recordVideo?: boolean | {
+        dir: string;
+    };
+    /**
+     * Secure credential vault. The LLM never sees real values — only
+     * placeholders like `{{email}}`, `{{password}}`. Real values are
+     * injected at execution time and scrubbed from all logs.
+     */
+    credentials?: CredentialVault;
+    /**
+     * Enable stealth mode to avoid bot detection.
+     * Pass `true` for sensible defaults or a `StealthConfig` object for fine control.
+     * Patches navigator.webdriver, plugins, permissions, WebGL, and more.
+     */
+    stealth?: boolean | StealthConfig;
+    /**
+     * Simulate human-like behavior — jittered clicks, variable typing speed,
+     * mouse movement curves, random micro-pauses.
+     * Pass `true` for defaults or a `HumanizeConfig` for fine control.
+     */
+    humanize?: boolean | HumanizeConfig;
+    /**
+     * Unified memory config — persist browser sessions, decisions, and
+     * summaries of past runs. Same config as Agent and VoiceAgent.
+     */
+    memory?: UnifiedMemoryConfig;
+    /** Skills — pre-packaged or learned tool bundles. */
+    skills?: Array<_agentium_core.Skill | string>;
+    /** Cost tracker — track vision model token usage and enforce budgets across browser runs. */
+    costTracker?: CostTracker;
+    logLevel?: LogLevel;
+    eventBus?: EventBus;
+}
+interface BrowserRunOpts {
+    /** Override startUrl from config */
+    startUrl?: string;
+    /** Per-run model API key override */
+    apiKey?: string;
+    /** Session identifier for memory persistence and event tracking */
+    sessionId?: string;
+    /** User identifier for memory personalization */
+    userId?: string;
+    /** Path to save storageState (cookies/auth) after the run completes */
+    saveStorageState?: string;
+}
+interface BrowserRunOutput {
+    /** Final text result produced by the agent */
+    result: string;
+    /** Whether the task completed successfully (vs maxSteps exhausted or fail) */
+    success: boolean;
+    /** Full action history with screenshots */
+    steps: BrowserStep[];
+    /** URL at completion */
+    finalUrl: string;
+    /** Last screenshot captured */
+    finalScreenshot: Buffer;
+    /** Total time taken in milliseconds */
+    durationMs: number;
+    /** Video file path (if recordVideo was enabled) */
+    videoPath?: string;
+}
+interface BrowserStep {
+    index: number;
+    action: BrowserAction;
+    /** Screenshot taken before this action was executed */
+    screenshot: Buffer;
+    pageUrl: string;
+    pageTitle: string;
+    timestamp: Date;
+    /** Simplified DOM snapshot (if useDOM is enabled) */
+    dom?: string;
+}
+interface StealthConfig {
+    /**
+     * Remove `navigator.webdriver` flag and patch common detection vectors
+     * (plugins, languages, permissions, WebGL, etc.). Default when stealth=true.
+     */
+    patchFingerprint?: boolean;
+    /** Custom User-Agent string. A realistic one is used by default. */
+    userAgent?: string;
+    /** Browser locale. Default: "en-US" */
+    locale?: string;
+    /** Timezone ID (IANA). Default: "America/New_York" */
+    timezone?: string;
+    /** Fake geolocation */
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    /** Ignore HTTPS certificate errors. Default: false (secure). Only enable for local testing. */
+    ignoreHTTPSErrors?: boolean;
+    /** HTTP/SOCKS proxy. Format: "http://user:pass@host:port" */
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+    };
+}
+interface HumanizeConfig {
+    /** Per-character typing delay range in ms. Default: [40, 120] */
+    typingDelay?: [number, number];
+    /** Random pixel offset added to click coordinates. Default: 3 */
+    clickJitter?: number;
+    /** Extra random pause between actions in ms range. Default: [200, 800] */
+    actionDelay?: [number, number];
+    /** Simulate human-like mouse movement to target before clicking. Default: true */
+    mouseMovement?: boolean;
+}
+interface PageInfo {
+    url: string;
+    title: string;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+}
+
+declare class BrowserAgent {
+    readonly name: string;
+    readonly eventBus: EventBus;
+    private model;
+    private instructions?;
+    private maxSteps;
+    private headless;
+    private viewport;
+    private defaultStartUrl?;
+    private waitAfterAction;
+    private maxRepeats;
+    private useDOM;
+    private storageState?;
+    private recordVideo?;
+    private credentials?;
+    private stealth?;
+    private humanize?;
+    private costTracker;
+    private memoryManager;
+    private logger;
+    /** Access the MemoryManager (if memory is configured). */
+    get memory(): MemoryManager | null;
+    constructor(config: BrowserAgentConfig);
+    run(task: string, opts?: BrowserRunOpts): Promise<BrowserRunOutput>;
+    /**
+     * Returns a ToolDef that lets a regular Agent delegate browser tasks
+     * to this BrowserAgent.
+     */
+    asTool(config?: {
+        name?: string;
+        description?: string;
+    }): ToolDef;
+    private finalize;
+    private executeAction;
+    private sleep;
+}
+
+/**
+ * Playwright wrapper with stealth anti-detection and human-like behavior.
+ */
+declare class BrowserProvider {
+    private browser;
+    private context;
+    private page;
+    private pages;
+    private activeTabId;
+    private tabCounter;
+    private _viewport;
+    private _videoDir?;
+    private _humanize?;
+    constructor();
+    launch(opts?: {
+        headless?: boolean;
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        storageState?: string;
+        recordVideo?: boolean | {
+            dir: string;
+        };
+        stealth?: boolean | StealthConfig;
+        humanize?: boolean | HumanizeConfig;
+    }): Promise<void>;
+    saveStorageState(path: string): Promise<void>;
+    navigate(url: string): Promise<void>;
+    back(): Promise<void>;
+    screenshot(): Promise<Buffer>;
+    click(x: number, y: number): Promise<void>;
+    type(text: string): Promise<void>;
+    clickAndType(x: number, y: number, text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    scroll(direction: "up" | "down", amount?: number): Promise<void>;
+    extractDOM(opts?: {
+        maxElements?: number;
+    }): Promise<string>;
+    getPageInfo(): Promise<PageInfo>;
+    waitForStable(minWait?: number): Promise<void>;
+    newTab(url?: string): Promise<string>;
+    switchTab(tabId: string): Promise<void>;
+    closeTab(tabId: string): Promise<void>;
+    listTabs(): {
+        id: string;
+        url: string;
+        active: boolean;
+    }[];
+    get currentTabId(): string;
+    getVideoPath(tabId?: string): Promise<string | null>;
+    get videoDir(): string | undefined;
+    close(): Promise<void>;
+    /** Add small random offset to coordinates to avoid pixel-perfect bot patterns. */
+    private jitter;
+    /**
+     * Simulate human mouse movement using Bézier-like interpolation.
+     * Moves from the current mouse position to the target in small steps.
+     */
+    private humanMouseMove;
+    /** Small random pause after an interaction. */
+    private humanPause;
+    private randInt;
+    private ensurePage;
+    private ensureContext;
+    private sleep;
+}
+
+export { type BrowserAction, BrowserAgent, type BrowserAgentConfig, BrowserProvider, type BrowserRunOpts, type BrowserRunOutput, type BrowserStep, CredentialVault, type HumanizeConfig, type PageInfo, type StealthConfig };

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+import * as _agentium_core from '@agentium/core';
+import { ModelProvider, UnifiedMemoryConfig, CostTracker, LogLevel, EventBus, MemoryManager, ToolDef } from '@agentium/core';
+
+/**
+ * Secure credential store for BrowserAgent.
+ *
+ * Secrets are stored in memory and NEVER sent to the LLM.
+ * The model works with placeholders (e.g. `{{email}}`, `{{password}}`),
+ * and the agent resolves them to real values only at execution time.
+ */
+declare class CredentialVault {
+    private secrets;
+    constructor(initial?: Record<string, string>);
+    /** Store a credential. Key names become the placeholder: `{{key}}`. */
+    set(key: string, value: string): this;
+    /** Retrieve a credential value. Returns undefined if not found. */
+    get(key: string): string | undefined;
+    has(key: string): boolean;
+    /** List available placeholder names (never exposes values). */
+    keys(): string[];
+    /**
+     * Load credentials from environment variables.
+     * Maps env var names to placeholder keys.
+     *
+     * @example
+     * vault.fromEnv({ email: "LOGIN_EMAIL", password: "LOGIN_PASS" });
+     */
+    fromEnv(mapping: Record<string, string>): this;
+    /**
+     * Replace `{{key}}` placeholders in text with actual credential values.
+     * Used internally by BrowserAgent right before executing a type action.
+     */
+    resolve(text: string): string;
+    /**
+     * Replace any occurrence of real credential values in text with
+     * their `{{key}}` placeholder. Used to sanitize logs and action history.
+     */
+    mask(text: string): string;
+}
+
+type BrowserAction = {
+    action: "click";
+    x: number;
+    y: number;
+    description: string;
+} | {
+    action: "type";
+    text: string;
+    x?: number;
+    y?: number;
+} | {
+    action: "scroll";
+    direction: "up" | "down";
+    amount?: number;
+} | {
+    action: "navigate";
+    url: string;
+} | {
+    action: "back";
+} | {
+    action: "wait";
+    ms: number;
+} | {
+    action: "screenshot";
+} | {
+    action: "done";
+    result: string;
+} | {
+    action: "fail";
+    reason: string;
+};
+interface BrowserAgentConfig {
+    name: string;
+    /** Vision-capable model (GPT-4o, Gemini, etc.) */
+    model: ModelProvider;
+    /** Extra instructions appended to the system prompt */
+    instructions?: string;
+    /** Max vision loop iterations. Default: 30 */
+    maxSteps?: number;
+    /** Run browser without visible window. Default: true */
+    headless?: boolean;
+    /** Browser viewport size. Default: 1280x720 */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Initial URL to navigate to before starting the task */
+    startUrl?: string;
+    /** Milliseconds to wait after each action for the page to settle. Default: 1500 */
+    waitAfterAction?: number;
+    /** Max consecutive identical actions before the agent auto-fails. Default: 3 */
+    maxRepeats?: number;
+    /**
+     * Include a simplified DOM/accessibility tree alongside the screenshot.
+     * Helps the model target elements more accurately. Default: false
+     */
+    useDOM?: boolean;
+    /**
+     * Path to a Playwright storageState JSON file.
+     * Restores cookies, localStorage, and sessionStorage from a previous session.
+     */
+    storageState?: string;
+    /**
+     * Enable video recording of the browser session.
+     * Pass `true` for default dir (`./browser-videos`) or `{ dir: "/path" }`.
+     */
+    recordVideo?: boolean | {
+        dir: string;
+    };
+    /**
+     * Secure credential vault. The LLM never sees real values — only
+     * placeholders like `{{email}}`, `{{password}}`. Real values are
+     * injected at execution time and scrubbed from all logs.
+     */
+    credentials?: CredentialVault;
+    /**
+     * Enable stealth mode to avoid bot detection.
+     * Pass `true` for sensible defaults or a `StealthConfig` object for fine control.
+     * Patches navigator.webdriver, plugins, permissions, WebGL, and more.
+     */
+    stealth?: boolean | StealthConfig;
+    /**
+     * Simulate human-like behavior — jittered clicks, variable typing speed,
+     * mouse movement curves, random micro-pauses.
+     * Pass `true` for defaults or a `HumanizeConfig` for fine control.
+     */
+    humanize?: boolean | HumanizeConfig;
+    /**
+     * Unified memory config — persist browser sessions, decisions, and
+     * summaries of past runs. Same config as Agent and VoiceAgent.
+     */
+    memory?: UnifiedMemoryConfig;
+    /** Skills — pre-packaged or learned tool bundles. */
+    skills?: Array<_agentium_core.Skill | string>;
+    /** Cost tracker — track vision model token usage and enforce budgets across browser runs. */
+    costTracker?: CostTracker;
+    logLevel?: LogLevel;
+    eventBus?: EventBus;
+}
+interface BrowserRunOpts {
+    /** Override startUrl from config */
+    startUrl?: string;
+    /** Per-run model API key override */
+    apiKey?: string;
+    /** Session identifier for memory persistence and event tracking */
+    sessionId?: string;
+    /** User identifier for memory personalization */
+    userId?: string;
+    /** Path to save storageState (cookies/auth) after the run completes */
+    saveStorageState?: string;
+}
+interface BrowserRunOutput {
+    /** Final text result produced by the agent */
+    result: string;
+    /** Whether the task completed successfully (vs maxSteps exhausted or fail) */
+    success: boolean;
+    /** Full action history with screenshots */
+    steps: BrowserStep[];
+    /** URL at completion */
+    finalUrl: string;
+    /** Last screenshot captured */
+    finalScreenshot: Buffer;
+    /** Total time taken in milliseconds */
+    durationMs: number;
+    /** Video file path (if recordVideo was enabled) */
+    videoPath?: string;
+}
+interface BrowserStep {
+    index: number;
+    action: BrowserAction;
+    /** Screenshot taken before this action was executed */
+    screenshot: Buffer;
+    pageUrl: string;
+    pageTitle: string;
+    timestamp: Date;
+    /** Simplified DOM snapshot (if useDOM is enabled) */
+    dom?: string;
+}
+interface StealthConfig {
+    /**
+     * Remove `navigator.webdriver` flag and patch common detection vectors
+     * (plugins, languages, permissions, WebGL, etc.). Default when stealth=true.
+     */
+    patchFingerprint?: boolean;
+    /** Custom User-Agent string. A realistic one is used by default. */
+    userAgent?: string;
+    /** Browser locale. Default: "en-US" */
+    locale?: string;
+    /** Timezone ID (IANA). Default: "America/New_York" */
+    timezone?: string;
+    /** Fake geolocation */
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    /** Ignore HTTPS certificate errors. Default: false (secure). Only enable for local testing. */
+    ignoreHTTPSErrors?: boolean;
+    /** HTTP/SOCKS proxy. Format: "http://user:pass@host:port" */
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+    };
+}
+interface HumanizeConfig {
+    /** Per-character typing delay range in ms. Default: [40, 120] */
+    typingDelay?: [number, number];
+    /** Random pixel offset added to click coordinates. Default: 3 */
+    clickJitter?: number;
+    /** Extra random pause between actions in ms range. Default: [200, 800] */
+    actionDelay?: [number, number];
+    /** Simulate human-like mouse movement to target before clicking. Default: true */
+    mouseMovement?: boolean;
+}
+interface PageInfo {
+    url: string;
+    title: string;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+}
+
+declare class BrowserAgent {
+    readonly name: string;
+    readonly eventBus: EventBus;
+    private model;
+    private instructions?;
+    private maxSteps;
+    private headless;
+    private viewport;
+    private defaultStartUrl?;
+    private waitAfterAction;
+    private maxRepeats;
+    private useDOM;
+    private storageState?;
+    private recordVideo?;
+    private credentials?;
+    private stealth?;
+    private humanize?;
+    private costTracker;
+    private memoryManager;
+    private logger;
+    /** Access the MemoryManager (if memory is configured). */
+    get memory(): MemoryManager | null;
+    constructor(config: BrowserAgentConfig);
+    run(task: string, opts?: BrowserRunOpts): Promise<BrowserRunOutput>;
+    /**
+     * Returns a ToolDef that lets a regular Agent delegate browser tasks
+     * to this BrowserAgent.
+     */
+    asTool(config?: {
+        name?: string;
+        description?: string;
+    }): ToolDef;
+    private finalize;
+    private executeAction;
+    private sleep;
+}
+
+/**
+ * Playwright wrapper with stealth anti-detection and human-like behavior.
+ */
+declare class BrowserProvider {
+    private browser;
+    private context;
+    private page;
+    private pages;
+    private activeTabId;
+    private tabCounter;
+    private _viewport;
+    private _videoDir?;
+    private _humanize?;
+    constructor();
+    launch(opts?: {
+        headless?: boolean;
+        viewport?: {
+            width: number;
+            height: number;
+        };
+        storageState?: string;
+        recordVideo?: boolean | {
+            dir: string;
+        };
+        stealth?: boolean | StealthConfig;
+        humanize?: boolean | HumanizeConfig;
+    }): Promise<void>;
+    saveStorageState(path: string): Promise<void>;
+    navigate(url: string): Promise<void>;
+    back(): Promise<void>;
+    screenshot(): Promise<Buffer>;
+    click(x: number, y: number): Promise<void>;
+    type(text: string): Promise<void>;
+    clickAndType(x: number, y: number, text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    scroll(direction: "up" | "down", amount?: number): Promise<void>;
+    extractDOM(opts?: {
+        maxElements?: number;
+    }): Promise<string>;
+    getPageInfo(): Promise<PageInfo>;
+    waitForStable(minWait?: number): Promise<void>;
+    newTab(url?: string): Promise<string>;
+    switchTab(tabId: string): Promise<void>;
+    closeTab(tabId: string): Promise<void>;
+    listTabs(): {
+        id: string;
+        url: string;
+        active: boolean;
+    }[];
+    get currentTabId(): string;
+    getVideoPath(tabId?: string): Promise<string | null>;
+    get videoDir(): string | undefined;
+    close(): Promise<void>;
+    /** Add small random offset to coordinates to avoid pixel-perfect bot patterns. */
+    private jitter;
+    /**
+     * Simulate human mouse movement using Bézier-like interpolation.
+     * Moves from the current mouse position to the target in small steps.
+     */
+    private humanMouseMove;
+    /** Small random pause after an interaction. */
+    private humanPause;
+    private randInt;
+    private ensurePage;
+    private ensureContext;
+    private sleep;
+}
+
+export { type BrowserAction, BrowserAgent, type BrowserAgentConfig, BrowserProvider, type BrowserRunOpts, type BrowserRunOutput, type BrowserStep, CredentialVault, type HumanizeConfig, type PageInfo, type StealthConfig };