leapfrog-mcp 0.6.2 → 0.6.4

package/dist/adaptive-wait.d.ts

@@ -0,0 +1,72 @@
+import type { Page } from "playwright-core";
+import type { Session, SnapshotResult } from "./types.js";
+import { type ClassificationResult } from "./page-classifier.js";
+import type { SessionManager } from "./session-manager.js";
+type WaitStrategy = "load" | "domcontentloaded" | "networkidle";
+export interface AdaptiveNavigateOptions {
+    /** Wait strategy to start with. Default: "load" */
+    waitUntil?: WaitStrategy;
+    /** Enable auto-retry stealth escalation. Default: true */
+    autoRetry?: boolean;
+    /** Max escalation level (0-5). Default: 3 */
+    maxRetryLevel?: number;
+    /** Stealth mode override from bandit selection. Applied per-page via stealth.applyToPage(). */
+    stealthModeOverride?: 'off' | 'passive' | 'active';
+    /** Bandit arm index for this navigation (passed through for outcome tracking). */
+    banditArmIndex?: number;
+}
+export type PageQuality = "GOOD" | "EMPTY" | "TIMEOUT" | "BLOCKED";
+export interface AdaptiveNavigateResult {
+    /** The snapshot result from the best attempt */
+    snapshot: SnapshotResult;
+    /** Page classification */
+    classification: ClassificationResult;
+    /** Final page URL after navigation */
+    url: string;
+    /** Page title */
+    title: string;
+    /** The page quality assessment */
+    quality: PageQuality;
+    /** Which waitUntil strategy succeeded */
+    finalStrategy: WaitStrategy;
+    /** Escalation metadata if stealth retries were used */
+    escalation?: EscalationMeta;
+    /** Bandit arm index used for this navigation (for outcome tracking) */
+    banditArmIndex?: number;
+    /** Stealth mode override applied by the bandit */
+    stealthModeOverride?: string;
+    /** The session that owns the page (may change if session was rotated) */
+    session: Session;
+    /** The page instance (may change if session was rotated) */
+    page: Page;
+}
+export interface EscalationMeta {
+    /** Level at which navigation succeeded (0-5) */
+    level: number;
+    /** Human-readable label for the level */
+    label: string;
+    /** Total retries attempted */
+    attempts: number;
+    /** Whether the session was rotated (Level 3+) */
+    sessionRotated: boolean;
+    /** New session ID if rotated */
+    newSessionId?: string;
+}
+/**
+ * Adaptive navigate: replaces the naive page.goto() in the navigate tool.
+ *
+ * 1. Tries the requested waitUntil strategy
+ * 2. Evaluates page quality (snapshot + classification)
+ * 3. Retries with alternative strategies if EMPTY/TIMEOUT
+ * 4. Escalates with stealth retries if BLOCKED/CHALLENGE
+ *
+ * Returns a rich result with snapshot, classification, escalation metadata,
+ * and the final session/page (which may differ if session was rotated).
+ */
+export declare function adaptiveNavigate(page: Page, session: Session, url: string, sessionManager: SessionManager, options?: AdaptiveNavigateOptions): Promise<AdaptiveNavigateResult>;
+/**
+ * Format the AdaptiveNavigateResult into the text output for the MCP tool response.
+ * Matches the existing navigate output format with optional escalation metadata.
+ */
+export declare function formatAdaptiveResult(result: AdaptiveNavigateResult): string;
+export {};