Browser-Based Flight Search

USE BROWSER ONLY WHEN:

• User specifically asks to check Google Flights / Kayak / Skyscanner
• API search returned no results and user wants broader coverage
• Price comparison requested against external sources

Browser Commands (OpenClaw Playwright-on-CDP with ARIA Snapshots)

• browser snapshot — get ARIA tree with [ref=eN] element references
• browser type [ref=eN] "value" — type into an input field
• browser click [ref=eN] — click an element
• browser screenshot — capture current page state

Google Flights

1. Navigate to https://www.google.com/travel/flights
2. browser snapshot → ARIA tree
3. Fill origin, destination, dates using [ref] locators
4. Click search, wait 5s for results
5. browser snapshot → extract airlines, prices, durations, stops
6. Enrich with jetlag scores via POST /api/v1/flights/score before presenting

Kayak

1. Navigate to https://www.kayak.com
2. Same snapshot → fill → search → extract pattern

Skyscanner

1. Navigate to https://www.skyscanner.com
2. Same snapshot → fill → search → extract pattern

Always

• Present browser results as "comparison data" — recommend booking through our API
• Random delays (3-8s) between browser actions
• Max 10 browser searches per day per user
• Enrich all results with jetlag scores before presenting to user

Rate Limits

• Max 10 browser flight searches per day per user.
• Back off 24 hours if any site blocks the browser.

Rate Limit Tracking

Track all browser searches in workspace file ~/browser-searches.json:

{
  "date": "2026-02-22",
  "count": 3,
  "searches": [
    { "site": "google-flights", "query": "JFK-NRT 2026-03-15", "timestamp": "2026-02-22T10:30:00Z" }
  ],
  "blockedUntil": null
}

Before each browser search:

1. Read ~/browser-searches.json (create if missing)
2. If date differs from today, reset count to 0 and clear searches
3. If blockedUntil is set and in the future, refuse — tell user blocked by site
4. If count >= 10, refuse — tell user daily browser search limit reached
5. After each search, increment count and append to searches
6. If a site blocks the browser, set blockedUntil to 24 hours from now

Browser Best Practices

Context Selection

DIRECT (no proxy): Google Flights, Kayak, Booking.com, Google Hotels, Lufthansa SCRAPLING (stealth service, no proxy needed): Delta, British Airways, SecretFlying, seats.aero, Southwest, Hilton, Hyatt, TripAdvisor, TheFlightDeal, Going, SeatGuru, Google Travel (flights + hotels) PROXY (residential): United, American Airlines, Air Canada, KLM, TravelPirates SKIP BROWSER (use API):

• Hotel search → LiteAPI first, browser for enrichment only
• Deal discovery → Aerobase Deals API first, browser for verification only
• Tours/activities → Aerobase Tours API first, browser rarely needed
• Flight pricing → Amadeus/Kiwi API, browser for visual comparison
• Award search → seats.aero API, browser for airline-specific lookups

Scrapling Service (Anti-Bot Bypass)

When browser automation is blocked by anti-bot systems (Akamai, Cloudflare, Datadome, etc.), use the stealth scrapling service configured via SCRAPLING_URL environment variable. This service bypasses detection WITHOUT needing residential proxies.

Reference: Scrapling Documentation

When to use Scrapling:

• Site shows reCAPTCHA, "Access denied", or challenge page
• Normal browser is blocked or redirected
• Need to extract data from JS-heavy sites

How to invoke:

Fetch a page (returns JSON with status, title, HTML, challenge detection):

web_fetch {SCRAPLING_URL}/fetch?url=https://www.delta.com&json=1

Run JavaScript on a page:

POST {SCRAPLING_URL}/evaluate
Body: {"url": "https://seats.aero", "script": "document.title"}

Check service health:

web_fetch {SCRAPLING_URL}/health

Response fields:

• status: HTTP status code (200 = success)
• title: Page title
• challenge: "pass" | "captcha" | "blocked" | "challenge"
• cached: true if served from 5-min cache
• html: Page HTML (truncated to 50KB in JSON mode)
• html_length: Full HTML length

Fallback chain:

1. Try Scrapling service first for listed domains
2. If challenge != "pass": fall back to native browser + residential proxy
3. If proxy also fails: screenshot and tell user

Important: Scrapling responses are cached for 5 minutes. For time-sensitive data (live prices, seat maps), append &nocache=1 or wait for cache expiry.

Aggregator Search (Scrapling /search)

Pre-built search + Python-side parsing. Returns structured JSON — no browser snapshot/type/click needed. Results are parsed server-side via Scrapling's Adaptor engine (CSS selectors, find_similar for self-healing).

Google Flights:

POST {SCRAPLING_URL}/search
{"site":"google-flights","origin":"LAX","destination":"NRT","departure":"2026-03-15","return":"2026-03-22"}

Returns: {"results": [{"airline":"...","price":"...","duration":"...","stops":"..."}], "count": N}

Kayak:

POST {SCRAPLING_URL}/search
{"site":"kayak","origin":"LAX","destination":"NRT","departure":"2026-03-15","return":"2026-03-22"}

Booking.com hotels:

POST {SCRAPLING_URL}/search
{"site":"booking","destination":"Tokyo","checkin":"2026-03-15","checkout":"2026-03-22","guests":2}

Returns: {"results": [{"name":"...","price":"...","rating":"...","location":"..."}], "count": N}

Deal sites:

POST {SCRAPLING_URL}/search
{"site":"secretflying"}
POST {SCRAPLING_URL}/search
{"site":"theflightdeal"}

Returns: {"results": [{"title":"...","url":"..."}], "count": N}

Check challenge field — if not "pass", results may be incomplete (consent wall, bot block).

Multi-Step Interaction (Scrapling /interact)

For flows needing form fill, click, screenshot (check-in, login, registration):

POST {SCRAPLING_URL}/interact
{
  "url": "https://www.southwest.com/air/check-in/",
  "steps": [
    {"action": "consent"},
    {"action": "fill", "selector": "#confirmationNumber", "value": "ABC123"},
    {"action": "fill", "selector": "#firstName", "value": "John"},
    {"action": "fill", "selector": "#lastName", "value": "Doe"},
    {"action": "click", "selector": "button#form-mixin--submit-button"},
    {"action": "wait", "ms": 5000},
    {"action": "screenshot"},
    {"action": "extract", "css": "h1::text"}
  ]
}

Available actions:

• consent — auto-dismiss cookie consent walls
• fill — fill input by CSS selector (instant, like paste)
• type — type with per-key delay (more human-like, use for sensitive fields)
• click — click element by CSS selector
• wait — wait N milliseconds
• wait_for — wait for selector to appear (with timeout)
• screenshot — capture current page (returned as base64 in screenshots array)
• extract — parse page with CSS selector (results in extracted array)
• select — select dropdown option

Fetch with Screenshot or CSS Extraction

web_fetch {SCRAPLING_URL}/fetch?url=https://www.delta.com&json=1&screenshot=1
web_fetch {SCRAPLING_URL}/fetch?url=https://www.secretflying.com&json=1&extract=css&selector=article

Search + Book Pattern

1. Fire API search (Kiwi/Duffel) immediately — don't wait for browser
2. Fire Scrapling /search in parallel for comparison data
3. Show API results first (faster, \x3C2s)
4. Merge Scrapling results: "Google Flights also shows..." / "Kayak prices..."
5. For booking: use API (Duffel hold → user confirms → API completes)
6. For airline-direct booking: navigate user to airline site via VNC
7. NEVER automate payment card entry via browser

Booking Flow

• API booking (Duffel/Kiwi): Agent can search, hold, and complete with user approval
• Browser booking: Navigate to site, user completes payment via VNC
• NEVER automate payment card entry via browser (PCI compliance, 3D Secure blocks)
• For held bookings: confirm with user before paying (Duffel supports 24-72h holds)

API-First + Browser-Concurrent Pattern

For any task where we have an API:

1. Fire API request immediately (don't wait for browser)
2. Show API results to user as they arrive
3. Launch browser concurrently if enrichment would help
4. Merge browser findings: "I also found..." / "For comparison..."
5. Highlight discrepancies between API and browser data This gives the user instant results + richer context seconds later.

Launch Checklist

1. Stealth plugin is auto-loaded — no action needed
2. Choose direct or proxy context based on target domain
3. Set viewport 1440x900, locale en-US, timezone America/New_York
4. Set 30s default timeout for navigation
5. ALWAYS register error handler: page.on('pageerror', ...)

Memory Management (CRITICAL)

• Chrome watchdog kills process at 1800MB RSS
• Max 2 concurrent tabs safely (tested: 3 tabs = 1795MB = danger zone)
• ALWAYS close context after task: await context.close()
• Prefer sequential tabs over concurrent
• If opening multiple tabs: close each before opening next
• Monitor with: process.memoryUsage().rss

Cookie Consent (EU server — Helsinki)

Scrapling service handles consent dismissal automatically via page_action. For native browser, patterns to try in order:

1. button:has-text("Reject all")
2. button:has-text("Decline")
3. button:has-text("Alle ablehnen")
4. button:has-text("I decline")
5. [data-testid="reject-button"]
6. button:has-text("Manage") → then "Reject all" in second dialog Timeout: 5s for consent dialog, then proceed (some sites don't show it)

Bot Detection Response

If you see any of these, you're being blocked:

• reCAPTCHA iframe or badge
• "Please verify you are a human"
• "Access denied" / "403 Forbidden"
• Datadome challenge page
• Blank page with Cloudflare "checking your browser"
• "Pardon our interruption" (Akamai)

Response:

1. If domain is in Scrapling list: try Scrapling service first (no proxy cost)
2. If Scrapling returns challenge != "pass": fall back to native browser + PROXY
3. If on DIRECT: retry with PROXY context
4. If already on PROXY: screenshot and fallback to alternative site
5. Tell user: "I'm seeing a verification on [site]. Let me try [alternative]."
6. NEVER attempt to solve CAPTCHAs
7. Max 2 retries per site per session

Screenshot Best Practices

• Full page: page.screenshot({ fullPage: true }) — use for results
• Viewport only: page.screenshot() — use for errors/blocks
• Element: element.screenshot() — use for specific data extraction
• Always save to /tmp/ with descriptive name
• Offer to show screenshots to user when relevant

Geo-Awareness

Server is in Helsinki, Finland (EU). This means:

• Airline sites redirect to EU versions (/eu/en, .de, etc.)
• Prices show in EUR by default on many sites
• Cookie consent walls appear on almost every site
• Some US-only features/deals may not be accessible
• With US residential proxy: sites see US IP, show USD, US content

Performance Targets

• Page load: \x3C10s acceptable, \x3C5s ideal
• Search results: \x3C15s acceptable
• Check-in form: \x3C10s
• If exceeding 30s: abort, screenshot, try alternative