leapfrog-mcp 0.6.2 → 0.6.3

package/dist/crash-recovery.js

@@ -0,0 +1,242 @@
+// ─── Browser Crash Recovery Handler ───────────────────────────────────────
+//
+// Monitors browser health, provides session-level health checks, handles
+// page.on('crash') events, auto-recovery, and crash telemetry.
+// Standalone module — uses import type only for Playwright types.
+// Logger integration is left to the caller (no cross-dependency).
+const HEALTH_CHECK_TIMEOUT_MS = 3000;
+export class CrashRecovery {
+    /** Crash telemetry — all page crashes during server lifetime */
+    crashLog = [];
+    /** Sessions marked as unhealthy after a page crash (pending recovery) */
+    unhealthySessions = new Set();
+    /**
+     * Attach a disconnect handler to a Playwright Browser instance.
+     * On unexpected disconnect (crash, kill, OOM), logs the event and
+     * calls onCrash so the SessionManager can clear its state.
+     */
+    attachToBrowser(browser, onCrash) {
+        browser.on("disconnected", () => {
+            // Write directly to stderr — no logger dependency
+            const entry = {
+                ts: new Date().toISOString(),
+                level: "error",
+                event: "browser.crashed",
+                pid: process.pid,
+                message: "Browser disconnected unexpectedly. Clearing all sessions.",
+            };
+            process.stderr.write(JSON.stringify(entry) + "\n");
+            onCrash();
+        });
+    }
+    /**
+     * Attach a page.on('crash') handler to catch Akamai-style browser context
+     * crashes. On crash: close the dead page, clean up the pool slot, log the
+     * event with the URL that caused the crash, and mark the session unhealthy.
+     *
+     * @param page The Playwright page to monitor
+     * @param session The session owning this page
+     * @param onCrash Optional callback when crash is detected (e.g., for cleanup)
+     */
+    attachToPage(page, session, onCrash) {
+        page.on("crash", () => {
+            let url = "";
+            try {
+                url = page.url();
+            }
+            catch {
+                // Page may be too dead to get URL
+                url = "(unknown — page unresponsive)";
+            }
+            const crashEntry = {
+                sessionId: session.id,
+                url,
+                timestamp: Date.now(),
+                error: "Page crashed (renderer process died)",
+            };
+            this.crashLog.push(crashEntry);
+            this.unhealthySessions.add(session.id);
+            // Write directly to stderr — no logger dependency
+            const logEntry = {
+                ts: new Date().toISOString(),
+                level: "error",
+                event: "page.crashed",
+                pid: process.pid,
+                sessionId: session.id,
+                url,
+                message: "Page renderer crashed. Session marked unhealthy for auto-recovery.",
+            };
+            process.stderr.write(JSON.stringify(logEntry) + "\n");
+            // Try to close the dead page (best-effort)
+            page.close().catch(() => { });
+            if (onCrash) {
+                onCrash(session.id);
+            }
+        });
+    }
+    /**
+     * Check if a session is marked as unhealthy (crashed but not yet recovered).
+     */
+    isUnhealthy(sessionId) {
+        return this.unhealthySessions.has(sessionId);
+    }
+    /**
+     * Mark a session as recovered after auto-recovery creates a replacement page.
+     */
+    markRecovered(sessionId) {
+        this.unhealthySessions.delete(sessionId);
+    }
+    /**
+     * Auto-recover a crashed session by creating a replacement page in the same
+     * browser context and re-applying stealth init scripts.
+     *
+     * @param session The session to recover
+     * @param applyStealthFn Callback to re-apply stealth to the new page
+     * @param rewireNetworkFn Callback to re-wire network intelligence
+     * @returns The new replacement page, or null if recovery failed
+     */
+    async autoRecover(session, applyStealthFn, rewireNetworkFn) {
+        if (!this.unhealthySessions.has(session.id)) {
+            return null; // Not crashed — nothing to recover
+        }
+        try {
+            const newPage = await session.context.newPage();
+            // Re-apply stealth init scripts
+            if (applyStealthFn) {
+                await applyStealthFn(newPage);
+            }
+            // Re-wire network intelligence
+            if (rewireNetworkFn) {
+                rewireNetworkFn(newPage, session);
+            }
+            // Auto-dismiss dialogs on replacement page
+            newPage.on("dialog", (dialog) => {
+                dialog.dismiss().catch(() => { });
+            });
+            // Replace the crashed page reference in the session
+            session.page = newPage;
+            // Update pages array if tab manager initialized it
+            if (session.pages) {
+                // Find and replace the crashed page, or push new one
+                const closedIdx = session.pages.findIndex((p) => {
+                    try {
+                        return p.isClosed();
+                    }
+                    catch {
+                        return true;
+                    }
+                });
+                if (closedIdx >= 0) {
+                    session.pages[closedIdx] = newPage;
+                }
+                else {
+                    session.pages.push(newPage);
+                }
+            }
+            // Attach crash handler to the new page too
+            this.attachToPage(newPage, session);
+            // Mark as recovered
+            this.unhealthySessions.delete(session.id);
+            const logEntry = {
+                ts: new Date().toISOString(),
+                level: "info",
+                event: "page.crash_recovered",
+                pid: process.pid,
+                sessionId: session.id,
+                message: "Replacement page created after crash. Session recovered.",
+            };
+            process.stderr.write(JSON.stringify(logEntry) + "\n");
+            return newPage;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            const crashEntry = {
+                sessionId: session.id,
+                url: "(recovery failed)",
+                timestamp: Date.now(),
+                error: `Auto-recovery failed: ${error}`,
+            };
+            this.crashLog.push(crashEntry);
+            const logEntry = {
+                ts: new Date().toISOString(),
+                level: "error",
+                event: "page.crash_recovery_failed",
+                pid: process.pid,
+                sessionId: session.id,
+                error,
+                message: "Failed to create replacement page. Session is dead.",
+            };
+            process.stderr.write(JSON.stringify(logEntry) + "\n");
+            return null;
+        }
+    }
+    /**
+     * Quick health check for a single session.
+     * Verifies the page is not closed and can still evaluate JavaScript.
+     * Never throws — always returns a result object.
+     */
+    async healthCheck(session) {
+        // Check if session is marked unhealthy from a crash
+        if (this.unhealthySessions.has(session.id)) {
+            return { healthy: false, reason: "Page crashed — pending auto-recovery" };
+        }
+        try {
+            // Check if the page handle is already closed
+            if (session.page.isClosed()) {
+                return { healthy: false, reason: "Page is closed" };
+            }
+            // Try a trivial evaluate with a tight timeout
+            await Promise.race([
+                session.page.evaluate("1"),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("Health check timed out")), HEALTH_CHECK_TIMEOUT_MS)),
+            ]);
+            return { healthy: true };
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : "Unknown health check failure";
+            return { healthy: false, reason };
+        }
+    }
+    /**
+     * Run health checks on all sessions in parallel.
+     * Returns a Map from session ID to health result.
+     */
+    async healthCheckAll(sessions) {
+        const results = new Map();
+        if (sessions.size === 0)
+            return results;
+        const entries = Array.from(sessions.entries());
+        const checks = await Promise.allSettled(entries.map(([_id, session]) => this.healthCheck(session)));
+        for (let i = 0; i < entries.length; i++) {
+            const [id] = entries[i];
+            const outcome = checks[i];
+            if (outcome.status === "fulfilled") {
+                results.set(id, outcome.value);
+            }
+            else {
+                // Promise.allSettled rejection — should not happen since healthCheck never throws,
+                // but handle defensively
+                results.set(id, {
+                    healthy: false,
+                    reason: outcome.reason?.message ?? "Health check promise rejected",
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get the crash log — all page crashes during the current server lifetime.
+     * Returns an array of {sessionId, url, timestamp, error} entries.
+     */
+    getCrashLog() {
+        return [...this.crashLog];
+    }
+    /**
+     * Clear crash log (for testing or after log export).
+     */
+    clearCrashLog() {
+        this.crashLog = [];
+    }
+}
+export const crashRecovery = new CrashRecovery();
+export default crashRecovery;

package/dist/domain-knowledge.d.ts

@@ -0,0 +1,149 @@
+export interface DomainRecord {
+    domain: string;
+    stealthTier: number;
+    blockHistory: Array<{
+        timestamp: number;
+        reason: string;
+    }>;
+    waitStrategy: {
+        method: string;
+        avgLoadTime: number;
+        samples: number;
+    } | null;
+    rateLimit: {
+        minDelayMs: number;
+        lastAdjusted: number;
+    } | null;
+    consentSelector: string | null;
+    challengeResolution: {
+        method: string;
+        successCount: number;
+        lastSuccess: number;
+    } | null;
+    stableElements: Array<{
+        fingerprint: string;
+        seenCount: number;
+        firstSeen: number;
+    }>;
+    /** Consecutive visits where a tracked fingerprint was absent. Reset on re-appearance. */
+    stableElementMisses?: Record<string, number>;
+    apiEndpoints: Array<{
+        path: string;
+        method: string;
+        classification: string;
+        lastSeen: number;
+    }>;
+    elementMemory: Array<{
+        fingerprint: string;
+        lastSelector: string;
+        lastSeen: number;
+    }>;
+    banditState?: {
+        weights: number[];
+        gamma: number;
+        numArms: number;
+    };
+    visitCount: number;
+    firstVisit: number;
+    lastVisit: number;
+}
+export interface NavigationHints {
+    waitUntil?: string;
+    stealthTier?: number;
+    consentSelector?: string | null;
+    /** Whether the domain has a persisted bandit state to restore. */
+    hasBanditState?: boolean;
+}
+/**
+ * Normalize a domain string for consistent storage.
+ * Strips `www.` prefix and lowercases so that `www.wikipedia.org`
+ * and `Wikipedia.org` resolve to the same record.
+ */
+export declare function normalizeDomain(domain: string): string;
+export declare class DomainKnowledge {
+    private cache;
+    private dirty;
+    private readonly baseDir;
+    private readonly maxDomains;
+    private dirEnsured;
+    constructor(baseDir?: string, maxDomains?: number);
+    /** Load domain record from cache or disk. Creates empty if not found. */
+    load(domain: string): Promise<DomainRecord>;
+    /** Get from cache only (sync, for hot paths). */
+    get(domain: string): DomainRecord | undefined;
+    /** Merge partial updates into a domain record. Marks dirty. */
+    update(domain: string, partial: Partial<DomainRecord>): void;
+    /** Record a successful navigation — updates waitStrategy running average. */
+    recordNavigation(domain: string, method: string, durationMs: number): void;
+    /** Record a block event — escalates stealth tier if 2+ blocks in the last hour. */
+    recordBlock(domain: string, reason: string): void;
+    /** Record a consent dismissal selector for future visits. */
+    recordConsent(domain: string, selector: string): void;
+    /** Record a successful challenge resolution method for future visits. */
+    recordChallengeResolution(domain: string, method: string): void;
+    /** Get the known-good challenge resolution method for a domain. */
+    getLearnedChallengeMethod(domain: string): string | null;
+    /** Record discovered API endpoints, merging with existing. */
+    recordApiEndpoints(domain: string, endpoints: Array<{
+        path: string;
+        method: string;
+        classification: string;
+    }>): void;
+    /**
+     * Record element fingerprints from a snapshot visit.
+     * Increments seenCount for known fingerprints, adds new ones,
+     * and removes fingerprints not seen in 3+ consecutive visits.
+     */
+    recordElementFingerprints(domain: string, fingerprints: string[]): void;
+    /**
+     * Get fingerprints of stable elements (seenCount >= minSeen) for suppression.
+     * Returns them sorted by seenCount descending (highest confidence first).
+     */
+    getStableFingerprints(domain: string, minSeen?: number): string[];
+    private static readonly ELEMENT_MEMORY_CAP;
+    /** Upsert an element fingerprint → selector mapping into domain memory. */
+    recordElement(domain: string, fingerprint: string, selector: string): void;
+    /** Look up the last known selector for an element fingerprint on a domain. */
+    findElement(domain: string, fingerprint: string): string | undefined;
+    /** Flush all dirty records to disk. */
+    flush(): Promise<void>;
+    /** Flush a single domain to disk. */
+    flushDomain(domain: string): Promise<void>;
+    /** List all loaded domains (for MCP tool display). */
+    listDomains(): Array<{
+        domain: string;
+        visitCount: number;
+        lastVisit: number;
+        stealthTier: number;
+    }>;
+    /** Get full record for display. Loads from disk if needed. */
+    inspect(domain: string): Promise<DomainRecord | null>;
+    /**
+     * Return actionable navigation hints from stored domain knowledge.
+     * This is the read-side of the self-improvement loop: past visits
+     * inform future navigation strategy, stealth tier, and consent handling.
+     *
+     * Returns an empty object if no useful knowledge exists yet.
+     */
+    getNavigationHints(domain: string): Promise<NavigationHints>;
+    /** Persist bandit state into a domain record and mark dirty. */
+    saveBanditState(domain: string, state: {
+        weights: number[];
+        gamma: number;
+        numArms: number;
+    }): void;
+    /** Get the persisted bandit state for a domain (from cache). */
+    getBanditState(domain: string): {
+        weights: number[];
+        gamma: number;
+        numArms: number;
+    } | undefined;
+    private createEmpty;
+    /** Ensure the storage directory exists (once per instance). */
+    private ensureDir;
+    /** Write a single domain record to disk. */
+    private writeDomain;
+    /** LRU eviction — remove least-recently-visited domains when over cap. */
+    private evict;
+}
+export declare const domainKnowledge: DomainKnowledge;