@agentium/browser 3.1.0 → 3.1.2

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,CA0D7D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzC"}

package/dist/prompts.d.ts

@@ -0,0 +1,21 @@
+import type { ToolDef } from "@agentium/core";
+import type { TabInfo } from "./action-space.js";
+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;
+}, tabs?: TabInfo[]): 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,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,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,CA2IR;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,EAC7C,IAAI,CAAC,EAAE,OAAO,EAAE,GACf,MAAM,CAkER;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAwDvE"}

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"}