@agentium/browser 3.1.0 → 3.1.1

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/loop-detector.d.ts

@@ -0,0 +1,83 @@
+import type { BrowserAction } from "./types.js";
+/**
+ * Detects two kinds of "stuck":
+ *
+ * 1. **Action loops** — the same action (after normalization) repeated too
+ *    often in a rolling window. Replaces the v2.0.x exact-string compare
+ *    that was easily fooled by tiny wording changes in `description`.
+ * 2. **Page stagnation** — the page hasn't changed (URL + interactive-
+ *    element count + DOM text hash) for several steps in a row. Useful
+ *    for catching cases where the agent keeps clicking but nothing
+ *    happens (overlay blocking, dead button).
+ *
+ * Instead of hard-failing on the first sign of trouble like v2.0.x did,
+ * we emit a graduated severity level so the agent loop can:
+ *   - 0/`none`     — fine, do nothing
+ *   - 1/`warn`     — nudge the model ("you might be repeating yourself")
+ *   - 2/`escalate` — stronger nudge ("you're definitely stuck, try a
+ *     different approach")
+ *   - 3/`abort`    — force termination
+ *
+ * Thresholds are loosely modelled on browser-use's escalating nudges.
+ */
+export type LoopSeverity = "none" | "warn" | "escalate" | "abort";
+export interface LoopAdvice {
+    severity: LoopSeverity;
+    message?: string;
+}
+export interface PageFingerprint {
+    url: string;
+    interactiveCount: number;
+    /** Cheap hash of the first ~1000 chars of visible body text. */
+    textHash: number;
+}
+export declare class LoopDetector {
+    private actionWindow;
+    private pageHistory;
+    private readonly actionWindowSize;
+    private readonly pageHistorySize;
+    /** Thresholds: repeat counts at which each severity fires. */
+    private readonly actionThresholds;
+    /** Thresholds: consecutive unchanged-page counts at which each fires. */
+    private readonly pageThresholds;
+    constructor(opts?: {
+        actionWindowSize?: number;
+        pageHistorySize?: number;
+        actionThresholds?: {
+            warn?: number;
+            escalate?: number;
+            abort?: number;
+        };
+        pageThresholds?: {
+            warn?: number;
+            escalate?: number;
+            abort?: number;
+        };
+    });
+    /**
+     * Record an action and return advice for the runtime. `severity` of
+     * `abort` means the loop should terminate now.
+     */
+    recordAction(action: BrowserAction): LoopAdvice;
+    /**
+     * Record a page fingerprint and return advice if the page has been
+     * stagnant. Counts consecutive identical fingerprints at the END of
+     * the history (so a single navigation resets the counter).
+     */
+    recordPage(fp: PageFingerprint): LoopAdvice;
+    /** Combine two advices, returning the more severe one. */
+    static combine(a: LoopAdvice, b: LoopAdvice): LoopAdvice;
+}
+/**
+ * Normalize an action for loop comparison. The goal is to canonicalize
+ * tiny variations the LLM produces (e.g. different `description`s for
+ * the same click) into a single key while keeping actions that are
+ * fundamentally different (different `index`, `text`, `url`, …) distinct.
+ */
+export declare function normalizeAction(action: BrowserAction): string;
+/**
+ * Tiny non-cryptographic string hash, stable across runs. Used for the
+ * DOM-text portion of `PageFingerprint`.
+ */
+export declare function fnvHash(s: string): number;
+//# sourceMappingURL=loop-detector.d.ts.map

package/dist/loop-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-detector.d.ts","sourceRoot":"","sources":["../src/loop-detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoD;IACrF,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoD;gBAEvE,IAAI,CAAC,EAAE;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACxE,cAAc,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACvE;IAeD;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU;IA8B/C;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,eAAe,GAAG,UAAU;IAmC3C,0DAA0D;IAC1D,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU;CAIzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA8C7D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzC"}

package/dist/prompts.d.ts

@@ -0,0 +1,20 @@
+import type { ToolDef } from "@agentium/core";
+import type { DomScrollContext } from "./types.js";
+export declare function buildSystemPrompt(viewport: {
+    width: number;
+    height: number;
+}, extraInstructions?: string, credentialKeys?: string[], options?: {
+    overrideSystemMessage?: string;
+    maxActionsPerStep?: number;
+    allowEvaluate?: boolean;
+    tools?: ToolDef[];
+    useVision?: boolean | "auto";
+    useDOM?: boolean;
+    useThinking?: boolean;
+}): string;
+export declare function buildUserMessage(task: string, pageUrl: string, pageTitle: string, stepIndex: number, actionHistory: string[], domSnapshot?: string, lastExtract?: string, scroll?: DomScrollContext, nudge?: string, stepBudget?: {
+    current: number;
+    max: number;
+}): string;
+export declare function summarizeAction(action: Record<string, unknown>): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC3C,iBAAiB,CAAC,EAAE,MAAM,EAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE;IACR,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,MAAM,CAiIR;AA6CD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,CAAC,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,gBAAgB,EACzB,KAAK,CAAC,EAAE,MAAM,EACd,UAAU,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C,MAAM,CA0DR;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA4CvE"}

package/dist/stealth.d.ts

@@ -0,0 +1,27 @@
+import type { StealthConfig } from "./types.js";
+/** Pick a random realistic user-agent string. */
+export declare function pickUserAgent(): string;
+/**
+ * JavaScript that runs inside every page to patch common bot-detection vectors.
+ * Injected via Playwright's `context.addInitScript()`.
+ */
+export declare function getStealthScript(): string;
+/**
+ * Build Playwright context options from a StealthConfig.
+ */
+export declare function buildStealthContextOpts(config: StealthConfig, viewport: {
+    width: number;
+    height: number;
+}): Record<string, unknown>;
+/**
+ * Build Playwright launch options for stealth.
+ */
+export declare function buildStealthLaunchArgs(config: StealthConfig): {
+    args: string[];
+    proxy?: {
+        server: string;
+        username?: string;
+        password?: string;
+    };
+};
+//# sourceMappingURL=stealth.d.ts.map

package/dist/stealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stealth.d.ts","sourceRoot":"","sources":["../src/stealth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAWhD,iDAAiD;AACjD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAoGzC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE,CAcA"}

package/dist/{index.d.cts → types.d.ts}

@@ -1,43 +1,5 @@
-import * as _agentium_core from '@agentium/core';
-import { ModelProvider, UnifiedMemoryConfig, ToolDef, CostTracker, LogLevel, EventBus, MemoryManager } 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;
-}
-
+import type { CostTracker, EventBus, LogLevel, ModelProvider, ToolDef, UnifiedMemoryConfig } from "@agentium/core";
+import type { CredentialVault } from "./credential-vault.js";
 /**
  * The complete set of actions a `BrowserAgent` can take during a run.
  *
@@ -47,7 +9,7 @@ declare class CredentialVault {
  * they survive layout shifts, devicePixelRatio mismatches, and "the
  * sibling 4 pixels away" failure modes.
  */
-type BrowserAction = {
+export type BrowserAction = {
     action: "click";
     /** Element index from the DOM snapshot. Preferred. */
     index?: number;
@@ -129,7 +91,7 @@ type BrowserAction = {
  * One entry in the DOM snapshot the model sees. Returned by
  * `BrowserProvider.extractDOM()` alongside the human-readable string form.
  */
-interface DomElement {
+export interface DomElement {
     /** Stable 1-based index for this step. Used by indexed actions. */
     index: number;
     /** Center coordinate in CSS pixels (fallback for the model if needed). */
@@ -157,7 +119,7 @@ interface DomElement {
  * model spatial awareness so it can decide when to scroll vs when more
  * content is below / above the fold.
  */
-interface DomScrollContext {
+export interface DomScrollContext {
     /** Approximate viewports of scrollable content above the current view. */
     pagesAbove: number;
     /** Approximate viewports of scrollable content below the current view. */
@@ -168,7 +130,7 @@ interface DomScrollContext {
     hiddenInteractive: number;
 }
 /** Combined return value of `BrowserProvider.extractDOM()`. */
-interface DomSnapshot {
+export interface DomSnapshot {
     /** Human-readable string fed to the model. */
     text: string;
     /** Structured list (stable indices) for runtime resolution. */
@@ -176,7 +138,7 @@ interface DomSnapshot {
     /** Spatial/scroll context. */
     scroll: DomScrollContext;
 }
-interface BrowserAgentConfig {
+export interface BrowserAgentConfig {
     name: string;
     /** Vision-capable model (GPT-4o, Gemini, etc.) */
     model: ModelProvider;
@@ -334,7 +296,7 @@ interface BrowserAgentConfig {
      */
     memory?: UnifiedMemoryConfig;
     /** Skills — pre-packaged or learned tool bundles. */
-    skills?: Array<_agentium_core.Skill | string>;
+    skills?: Array<import("@agentium/core").Skill | string>;
     /**
      * Custom tools that the BrowserAgent itself can invoke during a run.
      * The agent emits `{ "action": "tool", "name": "<tool>", "args": {...} }`
@@ -348,7 +310,7 @@ interface BrowserAgentConfig {
     logLevel?: LogLevel;
     eventBus?: EventBus;
 }
-interface BrowserRunOpts {
+export interface BrowserRunOpts {
     /** Override startUrl from config */
     startUrl?: string;
     /** Per-run model API key override */
@@ -362,7 +324,7 @@ interface BrowserRunOpts {
     /** Per-run override of `maxSteps`. */
     maxSteps?: number;
 }
-interface BrowserRunOutput {
+export interface BrowserRunOutput {
     /** Final text result produced by the agent */
     result: string;
     /** Whether the task completed successfully (vs maxSteps exhausted or fail) */
@@ -380,7 +342,7 @@ interface BrowserRunOutput {
     /** Extracted content from every `extract` action, in chronological order. */
     extractedContent?: string[];
 }
-interface BrowserStep {
+export interface BrowserStep {
     index: number;
     action: BrowserAction;
     /** Screenshot taken before this action was executed. May be empty if useVision=false. */
@@ -408,14 +370,14 @@ interface BrowserStep {
  * by browser-use's `AgentOutput`. Every field is optional from a runtime
  * standpoint — only `action` is required for execution.
  */
-interface AgentOutput {
+export interface AgentOutput {
     thinking?: string;
     evaluationPreviousGoal?: string;
     memory?: string;
     nextGoal?: string;
     action: BrowserAction | BrowserAction[];
 }
-interface StealthConfig {
+export interface StealthConfig {
     /**
      * Remove `navigator.webdriver` flag and patch common detection vectors
      * (plugins, languages, permissions, WebGL, etc.). Default when stealth=true.
@@ -449,7 +411,7 @@ interface StealthConfig {
         password?: string;
     };
 }
-interface HumanizeConfig {
+export interface HumanizeConfig {
     /** Per-character typing delay range in ms. Default: [40, 120] */
     typingDelay?: [number, number];
     /** Random pixel offset added to click coordinates. Default: 3 */
@@ -459,7 +421,7 @@ interface HumanizeConfig {
     /** Simulate human-like mouse movement to target before clicking. Default: true */
     mouseMovement?: boolean;
 }
-interface PageInfo {
+export interface PageInfo {
     url: string;
     title: string;
     viewportSize: {
@@ -467,335 +429,4 @@ interface PageInfo {
         height: number;
     };
 }
-
-declare class BrowserAgent {
-    readonly name: string;
-    readonly eventBus: EventBus;
-    private model;
-    private pageExtractionLLM;
-    private fallbackModel;
-    private useThinking;
-    private historyWindow;
-    private instructions?;
-    private extendSystemMessage?;
-    private overrideSystemMessage?;
-    private maxSteps;
-    private maxFailures;
-    private maxActionsPerStep;
-    private initialActions;
-    private useVision;
-    private directlyOpenUrl;
-    private headless;
-    private viewport;
-    private defaultStartUrl?;
-    private waitAfterAction;
-    private maxRepeats;
-    private useDOM;
-    private allowEvaluate;
-    private allowedDomains?;
-    private prohibitedDomains?;
-    private storageState?;
-    private cdpUrl?;
-    private recordVideo?;
-    private credentials?;
-    private stealth?;
-    private humanize?;
-    private tools;
-    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 shouldCaptureVision;
-    private detectUrlInTask;
-    private assertDomainAllowed;
-    /**
-     * Build the message array sent to the model: system prompt + a compact
-     * summary of older turns (if any) + the most recent `historyWindow`
-     * turns verbatim + the current step's user message.
-     *
-     * Inspired by browser-use's history compaction. Keeps tokens bounded
-     * while giving the model meaningful context about what it already
-     * tried.
-     */
-    private buildMessages;
-    /**
-     * Call the primary model, retrying once with `fallbackModel` on
-     * transient errors (5xx, 429, network). Returns the response or
-     * `null` if both models failed.
-     */
-    private callModelWithFallback;
-    private isTransientError;
-    /**
-     * Parse the model's raw response into an `AgentOutput`. Tolerant to
-     * three shapes:
-     *  - Full envelope: { thinking, evaluation_previous_goal, action, ... }
-     *  - Raw action object (legacy / `useThinking: false`)
-     *  - Raw action array
-     *
-     * Also strips ```json fences the model occasionally adds.
-     */
-    private parseEnvelope;
-    /**
-     * Quick post-navigation health check. If the page came back blank
-     * (no body text and no interactive elements), reload once and wait
-     * for stable. This catches the "FreightOS half-loaded font test" class
-     * of failure before the LLM ever sees it.
-     */
-    private navigationHealthCheck;
-    /**
-     * Force-finalize the run with whatever partial data the agent has.
-     * Called when:
-     *   - `maxSteps` is exhausted without an explicit `done`,
-     *   - `maxFailures` is exceeded,
-     *   - the model can't produce parseable JSON enough times to make
-     *     forward progress.
-     * The result is composed from `extractedContent` + the last few
-     * action summaries so the caller gets something useful instead of
-     * just a one-line error.
-     */
-    private forceDone;
-    private finalize;
-    /**
-     * Execute a single action. Returns `{ output?, didNavigate? }` for the
-     * caller's state tracking. May throw — the loop handles failure-budget
-     * accounting in that case.
-     */
-    private executeAction;
-    private sleep;
-    /**
-     * Parse a quoted target keyword from a click action's `description`.
-     * Returns `undefined` for generic / ambiguous labels (login buttons,
-     * close, OK, etc.) where a substring text match could fire on the
-     * wrong element.
-     */
-    private extractClickKeyword;
-}
-
-/**
- * Playwright wrapper with stealth anti-detection, human-like behavior,
- * indexed DOM element resolution, and a rich action vocabulary.
- *
- * The `BrowserProvider` is intentionally LLM-agnostic — it exposes the
- * primitives that `BrowserAgent` orchestrates via vision+DOM reasoning.
- */
-declare class BrowserProvider {
-    private browser;
-    private context;
-    private page;
-    private pages;
-    private activeTabId;
-    private tabCounter;
-    private _viewport;
-    private _videoDir?;
-    private _humanize?;
-    /**
-     * Most recent DOM snapshot (one per `extractDOM` call). Indexed actions
-     * (`clickByIndex`, `inputByIndex`, …) resolve their `index` against this.
-     */
-    private _lastDom;
-    /** True if we connected over CDP (don't tear down the browser on close). */
-    private _attached;
-    constructor();
-    launch(opts?: {
-        headless?: boolean;
-        viewport?: {
-            width: number;
-            height: number;
-        };
-        storageState?: string;
-        recordVideo?: boolean | {
-            dir: string;
-        };
-        stealth?: boolean | StealthConfig;
-        humanize?: boolean | HumanizeConfig;
-        cdpUrl?: string;
-    }): Promise<void>;
-    saveStorageState(path: string): Promise<void>;
-    navigate(url: string): Promise<void>;
-    back(): Promise<void>;
-    screenshot(): Promise<Buffer>;
-    /** Viewport size in CSS pixels (matches screenshot dimensions). */
-    get viewport(): {
-        width: number;
-        height: number;
-    };
-    /** Most recent DOM snapshot. Each entry has a stable `index`. */
-    get lastDom(): DomElement[];
-    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>;
-    /**
-     * Send arbitrary keyboard keys / shortcuts. Accepts a single
-     * Playwright key spec (`"Enter"`, `"Control+l"`, `"Shift+ArrowDown"`)
-     * or a space-separated sequence (`"Tab Tab Enter"`).
-     */
-    sendKeys(keys: string): Promise<void>;
-    scroll(direction: "up" | "down", amount?: number): Promise<void>;
-    /**
-     * Build a Playwright locator for a DOM-snapshot index. Each `extractDOM`
-     * call tags surviving elements with `data-bua-idx="<n>"`; we resolve by
-     * that attribute. Returns null if the index is unknown.
-     */
-    private locatorForIndex;
-    /**
-     * Click an element by its DOM-snapshot index. The most reliable click
-     * path on dynamic pages — survives layout shifts and DPR oddities.
-     */
-    clickByIndex(index: number, opts?: {
-        timeout?: number;
-    }): Promise<boolean>;
-    /**
-     * Focus an indexed input, optionally clear it, and type. Returns false
-     * if the index couldn't be resolved or the input couldn't be focused.
-     */
-    inputByIndex(index: number, text: string, opts?: {
-        clear?: boolean;
-        submit?: boolean;
-        timeout?: number;
-    }): Promise<boolean>;
-    uploadFileByIndex(index: number, path: string): Promise<boolean>;
-    /** Scroll the indexed element into view (no click). */
-    scrollIntoViewByIndex(index: number): Promise<boolean>;
-    /**
-     * Deterministic, DOM-based click using Playwright's text locator.
-     *
-     * Returns `true` if a matching, visible, clickable element was found and
-     * clicked within `timeout` ms; `false` otherwise (so the caller can fall
-     * back to coordinate clicking). Substring-matches by default — e.g.
-     * `clickByText("Cheapest")` matches "Cheapest · 23-28 days · $2,550".
-     */
-    clickByText(keyword: string, opts?: {
-        timeout?: number;
-    }): Promise<boolean>;
-    /**
-     * Scroll the first occurrence of `text` into view. Returns false if no
-     * match was found within the timeout.
-     */
-    findText(text: string, opts?: {
-        timeout?: number;
-    }): Promise<boolean>;
-    /**
-     * Read the options of a native `<select>` at the given DOM-snapshot
-     * index. Returns `[]` if the element is not a `<select>`.
-     */
-    dropdownOptions(index: number): Promise<{
-        value: string;
-        label: string;
-        selected: boolean;
-    }[]>;
-    /**
-     * Select an option in a native `<select>` by its visible text or value.
-     * Returns false if the element isn't a `<select>` or no option matched.
-     */
-    selectDropdown(index: number, text: string): Promise<boolean>;
-    /**
-     * Run arbitrary JS in the page context. The caller is responsible for
-     * gating this behind a config flag — the BrowserAgent only routes the
-     * `evaluate` action here when `allowEvaluate: true`.
-     *
-     * The code is wrapped in `(async () => { ... })()` and the return value
-     * is coerced to a string for the model.
-     */
-    evaluate(code: string): Promise<string>;
-    /**
-     * Returns a clean text representation of the visible page body, with
-     * optional link extraction. Used by the BrowserAgent's `extract` action
-     * — the text is passed to a (usually cheap) LLM with the user's query.
-     */
-    pageText(opts?: {
-        extractLinks?: boolean;
-        maxChars?: number;
-    }): Promise<string>;
-    /**
-     * Snapshot the interactive elements visible in the viewport, tag each
-     * with a `data-bua-idx="<n>"` attribute (used by indexed actions), and
-     * return:
-     *   - `text`: a human-readable string fed to the model
-     *   - `elements`: the structured list with stable indices
-     *   - `scroll`: spatial context (pages above/below, hidden interactive count)
-     *
-     * Five properties matter for accuracy:
-     *  - **Hit-tested**: each listed coordinate / index actually reaches the
-     *    labeled element (overlays / occlusion skip the entry).
-     *  - **Visibility filtered (with parent chain)**: an element is dropped
-     *    if itself OR any ancestor is `display:none`, `visibility:hidden`,
-     *    `pointer-events:none`, or near-zero opacity.
-     *  - **Shadow DOM piercing**: traverses open shadow roots so custom
-     *    elements / web components are visible to the agent.
-     *  - **Same-origin iframes**: walks into each accessible iframe and
-     *    includes its interactive elements (offset by the iframe's screen
-     *    position so the coordinates the model sees are still viewport-
-     *    relative).
-     *  - **`cursor: pointer` fallback pass**: catches custom React widgets
-     *    that have no semantic role/href/onclick but are clickable.
-     */
-    extractDOM(opts?: {
-        maxElements?: number;
-    }): Promise<DomSnapshot>;
-    /**
-     * Install the `__buaExtract` global on the main page. Idempotent —
-     * subsequent calls are no-ops.
-     */
-    private installExtractorScript;
-    /**
-     * The extractor source. Lives in its own method so we can also inject
-     * it into iframes that haven't yet had it loaded.
-     *
-     * This function intentionally runs entirely in the page context. It:
-     *   - traverses the regular DOM + open shadow roots (deep)
-     *   - applies a parent-chain visibility filter
-     *   - applies a `cursor:pointer` second pass for custom widgets
-     *   - hit-tests each candidate at its center to avoid overlay collisions
-     *   - returns scroll context (pages above/below, hidden counts)
-     *   - tags survivors with `data-bua-idx` for indexed actions
-     */
-    private extractorScriptSource;
-    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;
-    /**
-     * Safety net: clamp coordinates returned by the vision model to the actual
-     * viewport. If a model occasionally returns image-space coordinates from a
-     * 2x screenshot (despite our `scale: "css"` fix), this prevents Playwright
-     * from clicking at e.g. (2200, 1300) and either erroring or landing on a
-     * random off-screen element.
-     */
-    private clampToViewport;
-    /**
-     * Simulate human mouse movement using smoothstep interpolation.
-     */
-    private humanMouseMove;
-    /** Small random pause after an interaction. */
-    private humanPause;
-    private randInt;
-    private ensurePage;
-    private ensureContext;
-    private sleep;
-}
-
-export { type AgentOutput, type BrowserAction, BrowserAgent, type BrowserAgentConfig, BrowserProvider, type BrowserRunOpts, type BrowserRunOutput, type BrowserStep, CredentialVault, type DomElement, type DomScrollContext, type DomSnapshot, type HumanizeConfig, type PageInfo, type StealthConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}