@agentium/browser 4.0.0 → 4.5.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, EventBus, Logger, MemoryManager, RunContext, ToolExecutor, choice, jev } from "@agentium/core";
+import { ApprovalManager, EventBus, Logger, MemoryManager, RunContext, ToolExecutor, choice, getAccountingContext, jev, meteredGenerate, withAccountingContext } from "@agentium/core";
 import { z } from "zod/v3";
 function searchUrl(query, engine = "duckduckgo") {
 	const q = encodeURIComponent(query.trim());
@@ -1621,6 +1621,35 @@ var BrowserAgent = class {
 		if (config.memory) this.memoryManager = new MemoryManager(config.memory);
 	}
 	async run(task, opts) {
+		const parent = getAccountingContext();
+		const tracker = this.costTracker ?? parent?.tracker;
+		if (!tracker) return this.runAccounted(task, opts);
+		const ctx = opts?.context ?? new 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 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}`;
@@ -1751,49 +1780,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);
 				}
@@ -2026,7 +2034,7 @@ var BrowserAgent = class {
 		};
 		try {
 			signal?.throwIfAborted();
-			const r = await this.model.generate(messages, reqOpts);
+			const r = await meteredGenerate(this.model, messages, reqOpts);
 			signal?.throwIfAborted();
 			return {
 				response: r,
@@ -2041,7 +2049,7 @@ var BrowserAgent = class {
 					fallback: this.fallbackModel.modelId
 				});
 				try {
-					const r = await this.fallbackModel.generate(messages, reqOpts);
+					const r = await meteredGenerate(this.fallbackModel, messages, reqOpts);
 					signal?.throwIfAborted();
 					return {
 						response: r,
@@ -2095,7 +2103,7 @@ var BrowserAgent = class {
 		const provider = this.getJev();
 		args.signal?.throwIfAborted();
 		try {
-			const response = await provider.generate([{
+			const response = await meteredGenerate(provider, [{
 				role: "user",
 				content: JSON.stringify({
 					task: args.task,
@@ -2182,7 +2190,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 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 });
@@ -2479,7 +2487,7 @@ var BrowserAgent = class {
 					role: "user",
 					content: `Query: ${action.query}\n\nPage content:\n${pageText}`
 				}];
-				const response = await model.generate(messages, {
+				const response = await meteredGenerate(model, messages, {
 					temperature: 0,
 					maxTokens: 2048,
 					signal: ctx.signal

package/dist/loop-detector.d.cts

@@ -0,0 +1,83 @@
+import type { BrowserAction } from "./types.cjs";
+/**
+ * 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/prompts.d.cts

@@ -0,0 +1,21 @@
+import type { ToolDef } from "@agentium/core";
+import type { TabInfo } from "./action-space.cjs";
+import type { DomScrollContext } from "./types.cjs";
+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;
+}, tabs?: TabInfo[]): string;
+export declare function summarizeAction(action: Record<string, unknown>): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/stealth.d.cts

@@ -0,0 +1,27 @@
+import type { StealthConfig } from "./types.cjs";
+/** 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