@agentium/browser 4.0.0 → 4.5.0

package/dist/action-space.d.cts

@@ -0,0 +1,42 @@
+import type { BrowserAction, DomElement, SearchEngine } from "./types.cjs";
+export declare const DEFAULT_MAX_ACTION_CHOICES = 40;
+export interface TabInfo {
+    id: string;
+    url: string;
+    active: boolean;
+}
+export interface ActionSpace {
+    /** Jev / TypeSafe choice criteria: label → description. */
+    criteria: Record<string, string>;
+    toAction(label: string): BrowserAction | undefined;
+}
+export declare function searchUrl(query: string, engine?: SearchEngine): string;
+export declare function isSearchResultsUrl(url: string): boolean;
+/** Bot-block / challenge pages (DDG 418, Google sorry, Cloudflare, …). */
+export declare function isBlockedPageUrl(url: string): boolean;
+export declare function isBotChallengeText(text: string): boolean;
+export declare function isResultTitle(label: string): boolean;
+export declare function looksLikeResultList(text: string): boolean;
+/** Longest non-chrome link labels — search result titles, not "email us". */
+export declare function titlesFromElements(elements: DomElement[], max?: number): string;
+export declare const SERP_TITLE_SELECTORS: string[];
+export declare function guessSearchQuery(task: string): string;
+/**
+ * Closed action list for this frame: chrome (back, scroll, done, …) plus
+ * `click_N` / `type_N` from the DOM snapshot. Used by the Jev planner and
+ * as documentation of what `executeAction` can run without free-form JSON.
+ */
+export declare function buildActionSpace(elements: DomElement[], tabs?: TabInfo[], opts?: {
+    max?: number;
+    pagesBelow?: number;
+    pagesAbove?: number;
+    allowSearch?: boolean;
+    allowDone?: boolean;
+    allowWait?: boolean;
+}): ActionSpace;
+export declare function labelToAction(label: string, extras?: {
+    typeText?: string;
+    searchQuery?: string;
+    doneResult?: string;
+}): BrowserAction | undefined;
+//# sourceMappingURL=action-space.d.ts.map

package/dist/browser-agent.d.cts

@@ -0,0 +1,134 @@
+import type { ToolDef } from "@agentium/core";
+import { ApprovalManager, EventBus, MemoryManager } from "@agentium/core";
+import type { BrowserAgentConfig, BrowserRunOpts, BrowserRunOutput } from "./types.cjs";
+export 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;
+    readonly approvalManager: ApprovalManager | null;
+    private executionPolicy?;
+    private planner;
+    private jevModel;
+    private maxActionChoices;
+    private searchEngine;
+    private jevProvider;
+    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>;
+    private runAccounted;
+    /**
+     * 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;
+    private getJev;
+    /**
+     * Ask Jev to pick one label from this frame's action space, then map it
+     * to a BrowserAction. Type/search strings come from a text model or the task.
+     */
+    private planWithJev;
+    private pageLooksBlocked;
+    private scrapeSerpTitles;
+    private inferTypeText;
+    /**
+     * 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;
+}
+//# sourceMappingURL=browser-agent.d.ts.map

package/dist/browser-agent.d.ts

@@ -48,6 +48,7 @@ export declare class BrowserAgent {
     get memory(): MemoryManager | null;
     constructor(config: BrowserAgentConfig);
     run(task: string, opts?: BrowserRunOpts): Promise<BrowserRunOutput>;
+    private runAccounted;
     /**
      * Returns a ToolDef that lets a regular Agent delegate browser tasks
      * to this BrowserAgent.

package/dist/browser-agent.d.ts.map

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

package/dist/browser-provider.d.cts

@@ -0,0 +1,242 @@
+import type { DomElement, DomSnapshot, HumanizeConfig, PageInfo, StealthConfig } from "./types.cjs";
+/**
+ * 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.
+ */
+export 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>;
+    visibleText(maxChars?: number): Promise<string>;
+    /**
+     * Grep visible page text. No LLM. Used by `search_page`.
+     */
+    searchPage(opts: {
+        pattern: string;
+        regex?: boolean;
+        caseSensitive?: boolean;
+        maxResults?: number;
+        contextChars?: number;
+    }): Promise<Array<{
+        match: string;
+        context: string;
+        index: number;
+    }>>;
+    /**
+     * querySelectorAll over the page. No LLM. Used by `find_elements`.
+     */
+    findElements(selector: string, opts?: {
+        maxResults?: number;
+    }): Promise<Array<{
+        tag: string;
+        text: string;
+        href?: string;
+    }>>;
+    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;
+}
+//# sourceMappingURL=browser-provider.d.ts.map

package/dist/credential-vault.d.cts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export 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;
+}
+//# sourceMappingURL=credential-vault.d.ts.map

package/dist/index.cjs

@@ -1622,6 +1622,35 @@ var BrowserAgent = class {
 		if (config.memory) this.memoryManager = new _agentium_core.MemoryManager(config.memory);
 	}
 	async run(task, opts) {
+		const parent = (0, _agentium_core.getAccountingContext)();
+		const tracker = this.costTracker ?? parent?.tracker;
+		if (!tracker) return this.runAccounted(task, opts);
+		const ctx = opts?.context ?? new _agentium_core.RunContext({
+			sessionId: opts?.sessionId ?? `browser_${Date.now()}`,
+			userId: opts?.userId,
+			tenantId: opts?.tenantId,
+			signal: opts?.signal,
+			runMode: opts?.runMode,
+			executionPolicy: this.executionPolicy,
+			eventBus: this.eventBus
+		});
+		return (0, _agentium_core.withAccountingContext)({
+			...parent,
+			tracker,
+			runId: ctx.runId,
+			rootRunId: parent?.rootRunId ?? parent?.runId ?? ctx.runId,
+			parentRunId: parent?.runId,
+			sessionId: ctx.sessionId,
+			tenantId: ctx.tenantId,
+			userId: ctx.userId,
+			agentName: this.name,
+			eventBus: this.eventBus
+		}, () => this.runAccounted(task, {
+			...opts,
+			context: ctx
+		}));
+	}
+	async runAccounted(task, opts) {
 		const startTime = Date.now();
 		const maxSteps = opts?.maxSteps ?? this.maxSteps;
 		const sessionId = opts?.context?.sessionId ?? opts?.sessionId ?? `browser_${startTime}`;
@@ -1752,49 +1781,28 @@ var BrowserAgent = class {
 					vision: wantVision
 				});
 				let envelope = null;
-				let modelUsed = this.model;
-				if (this.planner === "jev") {
-					const planned = await this.planWithJev({
-						task,
-						url: pageInfo.url,
-						title: pageInfo.title,
-						elements,
-						tabs,
-						actionHistory,
-						lastExtract: lastExtractResult,
-						pagesBelow: scrollCtx?.pagesBelow,
-						pagesAbove: scrollCtx?.pagesAbove,
-						apiKey: opts?.apiKey,
-						signal: ctx.signal
-					});
-					envelope = planned.envelope;
-					modelUsed = planned.modelUsed;
-					if (this.costTracker && planned.usage) this.costTracker.track({
-						runId: sessionId,
-						agentName: this.name,
-						modelId: modelUsed.modelId,
-						usage: planned.usage,
-						sessionId,
-						userId
-					});
-				} else {
+				if (this.planner === "jev") envelope = (await this.planWithJev({
+					task,
+					url: pageInfo.url,
+					title: pageInfo.title,
+					elements,
+					tabs,
+					actionHistory,
+					lastExtract: lastExtractResult,
+					pagesBelow: scrollCtx?.pagesBelow,
+					pagesAbove: scrollCtx?.pagesAbove,
+					apiKey: opts?.apiKey,
+					signal: ctx.signal
+				})).envelope;
+				else {
 					const messages = this.buildMessages(systemPrompt, historyTurns, userText, wantVision ? screenshot : null);
-					const { response, modelUsed: used } = await this.callModelWithFallback(messages, opts?.apiKey, ctx.signal);
-					modelUsed = used;
+					const { response } = await this.callModelWithFallback(messages, opts?.apiKey, ctx.signal);
 					if (!response) {
 						consecutiveFailures++;
 						actionHistory.push(`(model call failed — retrying, ${consecutiveFailures}/${this.maxFailures})`);
 						if (consecutiveFailures > this.maxFailures) return await this.forceDone(browser, steps, startTime, opts, extractedContent, actionHistory, "model");
 						continue;
 					}
-					if (this.costTracker && response.usage) this.costTracker.track({
-						runId: sessionId,
-						agentName: this.name,
-						modelId: modelUsed.modelId,
-						usage: response.usage,
-						sessionId,
-						userId
-					});
 					const raw = typeof response.message.content === "string" ? response.message.content : "";
 					envelope = this.parseEnvelope(raw);
 				}
@@ -2027,7 +2035,7 @@ var BrowserAgent = class {
 		};
 		try {
 			signal?.throwIfAborted();
-			const r = await this.model.generate(messages, reqOpts);
+			const r = await (0, _agentium_core.meteredGenerate)(this.model, messages, reqOpts);
 			signal?.throwIfAborted();
 			return {
 				response: r,
@@ -2042,7 +2050,7 @@ var BrowserAgent = class {
 					fallback: this.fallbackModel.modelId
 				});
 				try {
-					const r = await this.fallbackModel.generate(messages, reqOpts);
+					const r = await (0, _agentium_core.meteredGenerate)(this.fallbackModel, messages, reqOpts);
 					signal?.throwIfAborted();
 					return {
 						response: r,
@@ -2096,7 +2104,7 @@ var BrowserAgent = class {
 		const provider = this.getJev();
 		args.signal?.throwIfAborted();
 		try {
-			const response = await provider.generate([{
+			const response = await (0, _agentium_core.meteredGenerate)(provider, [{
 				role: "user",
 				content: JSON.stringify({
 					task: args.task,
@@ -2183,7 +2191,7 @@ var BrowserAgent = class {
 		const model = this.pageExtractionLLM ?? (this.model.providerId === "jev" ? null : this.model);
 		if (!model) return guessSearchQuery(task);
 		try {
-			const response = await model.generate([{
+			const response = await (0, _agentium_core.meteredGenerate)(model, [{
 				role: "user",
 				content: `Task: ${task}\nThe next browser action is ${pick}. Reply with ONLY the text to type into that field. No quotes.`
 			}], { signal });
@@ -2480,7 +2488,7 @@ var BrowserAgent = class {
 					role: "user",
 					content: `Query: ${action.query}\n\nPage content:\n${pageText}`
 				}];
-				const response = await model.generate(messages, {
+				const response = await (0, _agentium_core.meteredGenerate)(model, messages, {
 					temperature: 0,
 					maxTokens: 2048,
 					signal: ctx.signal

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+export type { ActionSpace, TabInfo } from "./action-space.cjs";
+export { buildActionSpace, guessSearchQuery, isBlockedPageUrl, isBotChallengeText, isResultTitle, isSearchResultsUrl, labelToAction, looksLikeResultList, searchUrl, titlesFromElements, } from "./action-space.cjs";
+export { BrowserAgent } from "./browser-agent.cjs";
+export { BrowserProvider } from "./browser-provider.cjs";
+export { CredentialVault } from "./credential-vault.cjs";
+export type { AgentOutput, BrowserAction, BrowserAgentConfig, BrowserPlanner, BrowserRunOpts, BrowserRunOutput, BrowserStep, DomElement, DomScrollContext, DomSnapshot, HumanizeConfig, PageInfo, SearchEngine, StealthConfig, } from "./types.cjs";
+//# sourceMappingURL=index.d.ts.map