Deploy Tripplanner backend

.gitignore

@@ -0,0 +1,27 @@
+# Environment
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+
+# Playwright
+browser_data/
+.playwright/
+
+# Logs
+*.log
+
+# macOS
+.DS_Store

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-slim
+
+# Playwright system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
+    libcups2 libdrm2 libdbus-1-3 libxkbcommon0 libx11-6 libxcomposite1 \
+    libxdamage1 libxext6 libxfixes3 libxrandr2 libgbm1 libasound2 \
+    libpango-1.0-0 libcairo2 libatspi2.0-0 libx11-xcb1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+RUN playwright install chromium --with-deps
+
+COPY . .
+
+EXPOSE 7860
+CMD ["python", "-m", "uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,140 @@
 ---
 title: Tripplanner Backend
-emoji: 🦀
+emoji: ✈️
 colorFrom: blue
-colorTo: yellow
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Tripplanner
+
+A travel-benefits stacking app that finds dates where your credit card perks align — so you can book trips that squeeze maximum value out of every benefit you already have.
+
+## What It Does
+
+Tripplanner searches for windows where three high-value perks overlap:
+
+- **Delta companion certificate** (Delta Reserve Amex) — a second ticket at taxes only
+- **IHG 4th-night-free** (IHG Premier Mastercard) — book 4 nights on points, pay for 3
+- **Resy dining credits** (Delta Reserve Amex) — up to $20/month at Resy restaurants
+
+When all three line up on the same trip — same destination, same travel dates — you get flights, hotel, and dinner at a fraction of the normal cost. Tripplanner does the calendar math and site-checking so you don't have to do it manually.
+
+## Architecture
+
+```
+Browser (React + Vite)
+        |
+        v
+FastAPI backend  ←→  Orchestrator agent (claude-sonnet-4-6)
+                              |
+              ┌───────────────┼───────────────┐
+              v               v               v
+     Delta subagent    IHG subagent    Resy subagent
+   (claude-haiku-4-5) (claude-haiku-4-5) (claude-haiku-4-5)
+     + Playwright        + Playwright      + Playwright
+```
+
+The orchestrator fans out to three browser subagents that run in parallel. Each subagent gets a fresh AI context and its own Playwright browser instance. They navigate their assigned site, extract availability and pricing data, then return structured results to the orchestrator, which finds overlapping date windows and ranks them.
+
+## Cards Supported
+
+| Card | Benefit Used |
+|------|-------------|
+| Delta Reserve Amex | Companion certificate (domestic main cabin or first) |
+| Delta Reserve Amex | Resy dining credit ($20/month) |
+| Delta Reserve Amex | Delta Stays credit |
+| IHG Premier Mastercard | 4th night free on points redemptions |
+
+## Prerequisites
+
+- Python 3.11+
+- Node 18+
+- An [Anthropic API key](https://console.anthropic.com/)
+
+## Setup
+
+### 1. Clone the repo
+
+```bash
+git clone <repo-url>
+cd "Trip finder with claude"
+```
+
+### 2. Install Python dependencies
+
+```bash
+cd backend
+pip install -r requirements.txt
+```
+
+### 3. Install Playwright browser
+
+```bash
+playwright install chromium
+```
+
+### 4. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in your Anthropic API key:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### 5. Start the backend
+
+```bash
+python -m uvicorn backend.main:app --reload
+```
+
+### 6. Start the frontend
+
+In a second terminal:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+### 7. Open the app
+
+Navigate to [http://localhost:5173](http://localhost:5173).
+
+### 8. First run: set up browser sessions
+
+**You only need to do this once.**
+
+On first launch, click **"Setup Browser Sessions"**. A Chromium window will open. Log in to each of the three sites in that window:
+
+1. [delta.com](https://www.delta.com) — sign in to your SkyMiles account
+2. [ihg.com](https://www.ihg.com) — sign in to your IHG One Rewards account
+3. [resy.com](https://resy.com) — sign in to your Resy account
+
+Once you're logged in to all three, close the setup window and return to the app. Sessions are saved to disk in `browser_data/` and reused on every subsequent run. You won't be prompted again unless the sessions expire.
+
+## How It Works
+
+1. You enter a destination, travel window, and trip length in the UI.
+2. The FastAPI backend spins up an orchestrator agent.
+3. The orchestrator launches three subagents in parallel — one per site.
+4. Each subagent opens a Playwright browser using your saved session, navigates to the relevant search page, and extracts available dates, award availability, and pricing.
+5. The orchestrator collects results, finds date ranges where Delta companion availability, IHG 4th-night-free award space, and Resy restaurant options all overlap in the destination city.
+6. Ranked results appear in the UI, showing estimated cash value of the stacked benefits for each date window.
+
+## Privacy
+
+No credentials are stored by the app. Playwright authenticates using your browser's own saved session cookies (written to `browser_data/`, which is git-ignored). Your username and password never pass through the app.
+
+## Troubleshooting
+
+- **Session expired**: if a subagent reports it can't access your account, click "Setup Browser Sessions" again and re-log in to the affected site.
+- **Port conflict**: the backend defaults to `8000` and the frontend to `5173`. Set `PORT` in `.env` to override the backend port.
+- **Slow first search**: the three Playwright browsers launch cold on the first query. Subsequent searches reuse warm sessions and are faster.

backend/.env.example

@@ -0,0 +1,4 @@
+GEMINI_API_KEY=AIza...
+BROWSER_USER_DATA_DIR=./browser_data
+# Port for the FastAPI server
+PORT=8000

backend/agents/delta_agent.py

@@ -0,0 +1,128 @@
+"""
+Delta.com browser agent — finds companion certificate availability.
+Uses google-genai (Gemini Flash free tier) with Playwright browser tools.
+"""
+
+import json
+import os
+import re
+from typing import Callable
+
+from google import genai
+from google.genai import types
+
+from ..models import Cabin, FlightOption, TripSearchRequest
+from ..tools.browser import BrowserSession
+
+_MODEL = "gemini-1.5-flash"
+_MAX_ITER = 30
+_ECONOMY_CLASSES = ["L", "U", "T", "X", "V"]
+_FIRST_CLASSES = ["Z", "D", "I"]
+
+
+def _system_prompt(request: TripSearchRequest) -> str:
+    cabin = "economy" if request.preferred_cabin == Cabin.economy else "first class"
+    eligible = _ECONOMY_CLASSES if request.preferred_cabin == Cabin.economy else _FIRST_CLASSES
+    dests = ", ".join(request.destinations)
+    return f"""You are a travel research assistant navigating delta.com to find companion certificate availability.
+
+## Goal
+Search delta.com for flights from {request.origin} to: {dests}.
+Date window: {request.earliest_departure} to {request.latest_return}.
+Trip length: ~{request.trip_duration_nights} nights. Cabin: {cabin}.
+
+## Companion Certificate Rules
+- Companion flies for taxes only (~$80).
+- Economy eligible fare classes: L, U, T, X, V
+- First class eligible fare classes: Z, D, I
+- Hawaii (HNL) is domestic — eligible.
+- Use the Price Calendar to find eligible dates.
+
+## Steps
+1. User is already logged in — do NOT log in.
+2. Go to My Profile → Certificates, eCredits & Vouchers. Confirm cert is present.
+3. For each destination: search round-trip with flexible dates, use Price Calendar,
+   find dates with eligible fare classes ({", ".join(eligible)}), note outbound date,
+   return date, fare class, and base price.
+
+## Output
+After searching ALL destinations, output ONLY a JSON array, no prose, no fences:
+[{{"destination":"<IATA>","outbound_date":"<YYYY-MM-DD>","return_date":"<YYYY-MM-DD>",
+"fare_class":"<letter>","base_price":<float>,"companion_taxes":80.0,
+"eligible_for_companion_cert":true,"cabin":"{cabin}"}}]
+Omit destinations with no eligible flights. Output JSON only."""
+
+
+def _user_prompt(request: TripSearchRequest) -> str:
+    return (
+        f"Search delta.com companion cert availability: {request.origin} → "
+        f"{', '.join(request.destinations)}. "
+        f"Dates {request.earliest_departure} – {request.latest_return}, "
+        f"~{request.trip_duration_nights} nights. Return JSON array."
+    )
+
+
+def _parse(text: str) -> list[FlightOption]:
+    text = re.sub(r"```(?:json)?\s*", "", text).strip().rstrip("`").strip()
+    s, e = text.find("["), text.rfind("]")
+    if s == -1 or e <= s:
+        return []
+    try:
+        items = json.loads(text[s : e + 1])
+    except json.JSONDecodeError:
+        return []
+    out = []
+    for item in items:
+        try:
+            out.append(FlightOption(**item))
+        except Exception:
+            pass
+    return out
+
+
+async def search_companion_cert(
+    request: TripSearchRequest,
+    browser: BrowserSession,
+    progress: Callable[[str], None],
+) -> list[FlightOption]:
+    client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+    config = types.GenerateContentConfig(
+        system_instruction=_system_prompt(request),
+        tools=browser.gemini_tools,
+    )
+    contents = [types.Content(role="user", parts=[types.Part(text=_user_prompt(request))])]
+
+    progress(f"Delta: searching {request.origin} → {', '.join(request.destinations)}")
+
+    last_text = ""
+    for i in range(_MAX_ITER):
+        response = await client.aio.models.generate_content(
+            model=_MODEL, contents=contents, config=config
+        )
+        contents.append(response.candidates[0].content)
+
+        try:
+            if response.text:
+                last_text = response.text
+        except ValueError:
+            pass
+
+        fn_calls = response.function_calls
+        if not fn_calls:
+            progress("Delta: navigation complete.")
+            break
+
+        fn_parts = []
+        for fc in fn_calls:
+            progress(f"Delta [{i+1}/{_MAX_ITER}]: {fc.name}")
+            result = await browser.execute_tool(fc.name, dict(fc.args))
+            fn_parts.append(types.Part(
+                function_response=types.FunctionResponse(name=fc.name, response={"result": result})
+            ))
+        contents.append(types.Content(role="user", parts=fn_parts))
+    else:
+        progress(f"Delta: reached max iterations, parsing partial results.")
+
+    options = _parse(last_text)
+    progress(f"Delta: found {len(options)} eligible flight(s).")
+    return options

backend/agents/ihg_agent.py

@@ -0,0 +1,140 @@
+"""
+IHG.com browser agent — finds reward-night (points) availability.
+Uses google-genai (Gemini Flash free tier) with Playwright browser tools.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import date
+from typing import Callable
+
+from google import genai
+from google.genai import types
+
+from ..models import HotelOption
+from ..tools.browser import BrowserSession
+
+_MODEL = "gemini-1.5-flash"
+_MAX_ITER = 30
+
+
+def _system_prompt(
+    destination: str, check_in: date, check_out: date,
+    preferred_brands: list[str], nights: int, nights_paid: int, nights_free: int,
+) -> str:
+    brands = ", ".join(preferred_brands)
+    return f"""You are an IHG hotel search assistant. Search ihg.com for reward-night availability.
+
+## Search
+Destination: {destination} | Check-in: {check_in} | Check-out: {check_out}
+Nights: {nights} total ({nights_paid} paid, {nights_free} free via 4th-night-free benefit)
+Preferred brands (in order): {brands}
+
+## Steps
+1. Go to https://www.ihg.com/hotels/us/en/find-hotels/hotel/list
+2. Enter "{destination}", set dates {check_in} → {check_out}.
+3. CRITICAL: Toggle "Use Points" ON before searching. Cash rates don't qualify.
+4. Only include brands: {brands}
+5. Only include hotels with points availability on ALL nights.
+6. total_points = points_per_night × {nights_paid}
+
+## Output — JSON array only, no prose, no fences:
+[{{"destination":"{destination}","property_name":"<name>","brand":"<brand>",
+"check_in":"{check_in}","check_out":"{check_out}",
+"points_per_night":<int>,"total_points":<int>,
+"nights_paid":{nights_paid},"nights_free":{nights_free},"cash_rate":<float|null>}}]
+Return [] if nothing found."""
+
+
+def _parse(text: str, destination: str, check_in: date, check_out: date) -> list[HotelOption]:
+    m = re.search(r"```(?:json)?\s*([\s\S]*?)```", text)
+    text = m.group(1).strip() if m else text
+    s, e = text.find("["), text.rfind("]")
+    if s == -1 or e == -1:
+        return []
+    try:
+        items = json.loads(text[s : e + 1])
+    except json.JSONDecodeError:
+        return []
+    out = []
+    for item in items:
+        try:
+            for k in ("check_in", "check_out"):
+                if isinstance(item.get(k), str):
+                    item[k] = date.fromisoformat(item[k])
+            out.append(HotelOption(**item))
+        except Exception:
+            pass
+    return out
+
+
+async def _search_one(
+    destination: str, check_in: date, check_out: date,
+    browser: BrowserSession, preferred_brands: list[str],
+    nights: int, progress: Callable[[str], None],
+) -> list[HotelOption]:
+    nights_free = nights // 4
+    nights_paid = nights - nights_free
+
+    client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+    config = types.GenerateContentConfig(
+        system_instruction=_system_prompt(
+            destination, check_in, check_out, preferred_brands, nights, nights_paid, nights_free
+        ),
+        tools=browser.gemini_tools,
+    )
+    contents = [types.Content(role="user", parts=[types.Part(text=(
+        f"Search ihg.com for reward-night availability in {destination} "
+        f"from {check_in} to {check_out}. Toggle Use Points. Return JSON array."
+    ))])]
+
+    last_text = ""
+    for i in range(_MAX_ITER):
+        response = await client.aio.models.generate_content(
+            model=_MODEL, contents=contents, config=config
+        )
+        contents.append(response.candidates[0].content)
+        try:
+            if response.text:
+                last_text = response.text
+        except ValueError:
+            pass
+
+        fn_calls = response.function_calls
+        if not fn_calls:
+            break
+
+        fn_parts = []
+        for fc in fn_calls:
+            progress(f"IHG [{destination}]: {fc.name} (step {i+1})")
+            result = await browser.execute_tool(fc.name, dict(fc.args))
+            fn_parts.append(types.Part(
+                function_response=types.FunctionResponse(name=fc.name, response={"result": result})
+            ))
+        contents.append(types.Content(role="user", parts=fn_parts))
+
+    results = _parse(last_text, destination, check_in, check_out)
+    progress(f"IHG [{destination}]: {len(results)} property(ies) found.")
+    return results
+
+
+async def search_points_availability(
+    destinations: list[str],
+    date_pairs: list[tuple[date, date]],
+    browser: BrowserSession,
+    preferred_brands: list[str],
+    nights: int,
+    progress: Callable[[str], None],
+) -> list[HotelOption]:
+    all_results: list[HotelOption] = []
+    for destination in destinations:
+        for check_in, check_out in date_pairs:
+            progress(f"IHG: {destination} {check_in} → {check_out}")
+            all_results.extend(await _search_one(
+                destination, check_in, check_out, browser, preferred_brands, nights, progress
+            ))
+    progress(f"IHG: complete — {len(all_results)} total option(s).")
+    return all_results

backend/agents/resy_agent.py

@@ -0,0 +1,123 @@
+"""
+Resy.com browser agent — finds restaurants eligible for the $20 monthly dining credit.
+Uses google-genai (Gemini Flash free tier) with Playwright browser tools.
+"""
+
+import json
+import os
+import re
+from collections.abc import Callable
+from datetime import date
+
+from google import genai
+from google.genai import types
+
+from ..models import RestaurantOption
+from ..tools.browser import BrowserSession
+
+_MODEL = "gemini-1.5-flash"
+_MAX_ITER = 20
+
+
+def _system_prompt(cities: list[str], dinner_dates: list[date], party_size: int) -> str:
+    pairs = "\n".join(f"  - {c}: {d}" for c, d in zip(cities, dinner_dates))
+    return f"""You are a restaurant-discovery assistant on Resy.com.
+
+## Mission
+Find 2–3 dinner options per city below. Return ONE JSON array when done.
+
+## Resy credit facts
+- Delta Reserve Amex $20/month credit applies to ANY Resy booking. Set resy_credit_eligible=true always.
+- Global Dining Access (GDA) badge appears on select listings. Set global_dining_access=true only if you see it.
+
+## Strategy
+1. Navigate to resy.com for each city (e.g. https://resy.com/cities/hnl for Honolulu).
+2. Search dinner availability on the dinner date, party size {party_size}, 7pm–9pm slots.
+3. Find 2–3 restaurants per city.
+
+## Cities and dinner dates:
+{pairs}
+Party size: {party_size}
+
+## Output — JSON array only, no prose, no fences:
+[{{"city":"<city>","name":"<restaurant>","cuisine":"<type>","reservation_date":"<YYYY-MM-DD>",
+"party_size":{party_size},"resy_credit_eligible":true,"global_dining_access":<bool>}}]"""
+
+
+def _parse(text: str, party_size: int) -> list[RestaurantOption]:
+    text = re.sub(r"```(?:json)?\s*", "", text).strip().rstrip("`").strip()
+    s, e = text.find("["), text.rfind("]")
+    if s == -1 or e == -1:
+        return []
+    try:
+        items = json.loads(text[s : e + 1])
+    except json.JSONDecodeError:
+        return []
+    out = []
+    for item in items:
+        try:
+            rd = item.get("reservation_date")
+            if isinstance(rd, str):
+                rd = date.fromisoformat(rd)
+            out.append(RestaurantOption(
+                city=item["city"], name=item["name"],
+                cuisine=item.get("cuisine", ""),
+                reservation_date=rd,
+                party_size=item.get("party_size", party_size),
+                resy_credit_eligible=item.get("resy_credit_eligible", True),
+                global_dining_access=item.get("global_dining_access", False),
+            ))
+        except (KeyError, ValueError):
+            pass
+    return out
+
+
+async def find_resy_restaurants(
+    cities: list[str],
+    dinner_dates: list[date],
+    party_size: int,
+    browser: BrowserSession,
+    progress: Callable[[str], None],
+) -> list[RestaurantOption]:
+    client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+    config = types.GenerateContentConfig(
+        system_instruction=_system_prompt(cities, dinner_dates, party_size),
+        tools=browser.gemini_tools,
+    )
+    contents = [types.Content(role="user", parts=[types.Part(text=(
+        "Search Resy for restaurants in each city in the system prompt. Return the JSON array when done."
+    ))])]
+
+    progress(f"Resy: searching {len(cities)} city/cities…")
+
+    last_text = ""
+    for i in range(_MAX_ITER):
+        response = await client.aio.models.generate_content(
+            model=_MODEL, contents=contents, config=config
+        )
+        contents.append(response.candidates[0].content)
+        try:
+            if response.text:
+                last_text = response.text
+        except ValueError:
+            pass
+
+        fn_calls = response.function_calls
+        if not fn_calls:
+            break
+
+        fn_parts = []
+        for fc in fn_calls:
+            progress(f"Resy: {fc.name}…")
+            try:
+                result = await browser.execute_tool(fc.name, dict(fc.args))
+            except Exception as exc:
+                result = f"Error: {exc}"
+            fn_parts.append(types.Part(
+                function_response=types.FunctionResponse(name=fc.name, response={"result": result})
+            ))
+        contents.append(types.Content(role="user", parts=fn_parts))
+
+    results = _parse(last_text, party_size)
+    progress(f"Resy: found {len(results)} restaurant(s).")
+    return results

backend/main.py

@@ -0,0 +1,176 @@
+import asyncio
+import json
+import logging
+import os
+import uuid
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from dotenv import load_dotenv
+from fastapi import BackgroundTasks, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+
+from .models import SearchProgress, SearchResponse, TripResult, TripSearchRequest
+from .orchestrator import run_trip_search
+
+load_dotenv()
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# In-memory store: search_id -> {"status": str, "results": list | None, "queue": asyncio.Queue}
+searches: dict[str, dict] = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    api_key = os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        logger.warning(
+            "GEMINI_API_KEY is not set. Trip search will fail until it is configured."
+        )
+    else:
+        logger.info("GEMINI_API_KEY found — ready to serve requests.")
+    yield
+
+
+app = FastAPI(title="Tripplanner API", version="0.1.0", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://localhost:5174",
+                   "http://localhost:5175", "http://localhost:3000",
+                   "*"],  # Vercel preview URLs
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ---------------------------------------------------------------------------
+# Background task wrapper
+# ---------------------------------------------------------------------------
+
+async def _run_search(search_id: str, request: TripSearchRequest) -> None:
+    """Run the trip search and feed progress into the per-search queue."""
+    queue: asyncio.Queue = searches[search_id]["queue"]
+    try:
+        async for progress in run_trip_search(request):
+            await queue.put(progress)
+            if isinstance(progress, SearchProgress) and progress.step == "done":
+                break
+    except Exception as exc:
+        logger.exception("Error in background trip search %s", search_id)
+        # Push an error sentinel so the SSE stream can close cleanly
+        error_progress = SearchProgress(
+            step="error", message=str(exc), progress=0
+        )
+        await queue.put(error_progress)
+        searches[search_id]["status"] = "error"
+        return
+
+    searches[search_id]["status"] = "done"
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/api/health")
+async def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.post("/api/session/upload")
+async def upload_session(request: Request) -> dict:
+    """Accept a Playwright storage-state JSON from the local session_setup.py script."""
+    secret = os.getenv("SESSION_UPLOAD_SECRET", "")
+    if secret and request.headers.get("X-Session-Secret") != secret:
+        raise HTTPException(status_code=403, detail="Invalid session secret")
+    body = await request.body()
+    session_path = os.path.join(
+        os.getenv("BROWSER_USER_DATA_DIR", "./browser_data"), "sessions.json"
+    )
+    os.makedirs(os.path.dirname(session_path), exist_ok=True)
+    with open(session_path, "wb") as f:
+        f.write(body)
+    logger.info("Session state uploaded (%d bytes)", len(body))
+    return {"status": "ok", "bytes": len(body)}
+
+
+@app.post("/api/search", response_model=dict)
+async def start_search(
+    request: TripSearchRequest, background_tasks: BackgroundTasks
+) -> dict:
+    search_id = str(uuid.uuid4())
+    searches[search_id] = {
+        "status": "running",
+        "results": None,
+        "queue": asyncio.Queue(),
+    }
+    background_tasks.add_task(_run_search, search_id, request)
+    return {"search_id": search_id}
+
+
+@app.get("/api/search/{search_id}")
+async def get_search(search_id: str) -> dict:
+    entry = searches.get(search_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail="Search not found")
+    return {"status": entry["status"], "results": entry["results"]}
+
+
+@app.get("/api/search/{search_id}/stream")
+async def stream_search(search_id: str) -> StreamingResponse:
+    entry = searches.get(search_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail="Search not found")
+
+    async def event_generator() -> AsyncGenerator[str, None]:
+        queue: asyncio.Queue = entry["queue"]
+        while True:
+            try:
+                item = await asyncio.wait_for(queue.get(), timeout=30.0)
+            except asyncio.TimeoutError:
+                # Send a keep-alive comment so the connection doesn't drop
+                yield ": keep-alive\n\n"
+                continue
+
+            if isinstance(item, SearchProgress):
+                payload = item.model_dump()
+                yield f"data: {json.dumps(payload)}\n\n"
+
+                if item.step == "done":
+                    # Emit the final results as a separate "results" event
+                    results = entry.get("results")
+                    if results is not None:
+                        results_payload = [
+                            r.model_dump() if isinstance(r, TripResult) else r
+                            for r in results
+                        ]
+                        yield f"event: results\ndata: {json.dumps(results_payload)}\n\n"
+                    break
+
+                if item.step == "error":
+                    break
+
+            elif isinstance(item, list):
+                # The orchestrator may push the final TripResult list directly
+                entry["results"] = item
+                results_payload = [
+                    r.model_dump() if isinstance(r, TripResult) else r
+                    for r in item
+                ]
+                yield f"event: results\ndata: {json.dumps(results_payload)}\n\n"
+                break
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+            "Connection": "keep-alive",
+        },
+    )

backend/models.py

@@ -0,0 +1,76 @@
+from pydantic import BaseModel
+from datetime import date
+from typing import Optional
+from enum import Enum
+
+
+class Cabin(str, Enum):
+    economy = "economy"
+    first = "first"
+
+
+class TripSearchRequest(BaseModel):
+    origin: str                          # e.g. "JAX" or "GNV"
+    destinations: list[str]              # e.g. ["HNL", "LAX", "JFK"]
+    earliest_departure: date
+    latest_return: date
+    party_size: int = 2
+    trip_duration_nights: int = 4
+    preferred_cabin: Cabin = Cabin.economy
+    ihg_brands: list[str] = ["Kimpton", "InterContinental", "Hotel Indigo"]
+
+
+class FlightOption(BaseModel):
+    destination: str
+    outbound_date: date
+    return_date: date
+    fare_class: str                      # e.g. "L", "U", "Z"
+    base_price: float                    # price for one ticket
+    companion_taxes: float               # taxes the companion pays (~$80)
+    eligible_for_companion_cert: bool
+    cabin: Cabin
+
+
+class HotelOption(BaseModel):
+    destination: str
+    property_name: str
+    brand: str
+    check_in: date
+    check_out: date
+    points_per_night: int
+    total_points: int                    # for nights_paid only
+    nights_paid: int
+    nights_free: int                     # from 4th-night-free benefit
+    cash_rate: Optional[float] = None   # nightly cash rate if available
+
+
+class RestaurantOption(BaseModel):
+    city: str
+    name: str
+    cuisine: str
+    reservation_date: date
+    party_size: int
+    resy_credit_eligible: bool
+    global_dining_access: bool
+
+
+class TripResult(BaseModel):
+    destination: str
+    flight: FlightOption
+    hotel: Optional[HotelOption] = None
+    restaurant: Optional[RestaurantOption] = None
+    total_cash_out_of_pocket: float
+    total_points_required: int
+    benefits_captured: list[str]
+    score: float                         # 0–100, higher = better value
+
+
+class SearchProgress(BaseModel):
+    step: str                            # "delta" | "ihg" | "resy" | "done"
+    message: str
+    progress: int                        # 0–100
+
+
+class SearchResponse(BaseModel):
+    search_id: str
+    results: list[TripResult]

backend/orchestrator.py

@@ -0,0 +1,275 @@
+"""
+orchestrator.py — Tripplanner search orchestrator.
+
+Coordinates Delta, IHG, and Resy subagents sequentially over a single shared
+BrowserSession, then merges their results into ranked TripResult objects.
+"""
+
+from __future__ import annotations
+
+import os
+import asyncio
+from typing import Callable
+
+from .models import (
+    TripSearchRequest,
+    FlightOption,
+    HotelOption,
+    RestaurantOption,
+    TripResult,
+    SearchProgress,
+)
+from .tools.browser import BrowserSession
+from .agents.delta_agent import search_companion_cert
+from .agents.ihg_agent import search_points_availability
+from .agents.resy_agent import find_resy_restaurants
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+def calculate_cash_out_of_pocket(
+    flight: FlightOption,
+    hotel: HotelOption | None,
+) -> float:
+    """
+    Return the total cash the traveler pays.
+
+    The companion's ticket is covered by the certificate; they only owe the
+    companion_taxes.  Hotel is redeemed with points so costs $0 cash.
+    Restaurant dining credit is separate from this calculation.
+    """
+    # Primary ticket + companion taxes (companion cert covers the fare itself)
+    return flight.base_price + flight.companion_taxes
+
+
+def collect_benefits(
+    flight: FlightOption,
+    hotel: HotelOption | None,
+    restaurant: RestaurantOption | None,
+) -> list[str]:
+    """Return human-readable benefit strings for a trip combination."""
+    benefits: list[str] = []
+
+    if flight.eligible_for_companion_cert:
+        benefits.append("Delta companion certificate used")
+
+    if hotel is not None:
+        if hotel.nights_free > 0:
+            benefits.append(
+                f"IHG 4th night free ({hotel.nights_free} night{'s' if hotel.nights_free != 1 else ''} free)"
+            )
+        else:
+            benefits.append(f"IHG points redemption at {hotel.property_name}")
+
+    if restaurant is not None:
+        if restaurant.resy_credit_eligible:
+            benefits.append("Resy $20 dining credit eligible")
+        if restaurant.global_dining_access:
+            benefits.append(f"Global Dining Access reservation at {restaurant.name}")
+
+    return benefits
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _score_trip(
+    flight: FlightOption,
+    hotel: HotelOption | None,
+    restaurant: RestaurantOption | None,
+) -> float:
+    """
+    Score a trip combination on a 0–100 scale.
+
+    Breakdown:
+      +40  companion cert eligible
+      +30  hotel found with points availability
+      +15  restaurant found
+      +15  value score (lower cash out of pocket relative to flight base price)
+    """
+    score = 0.0
+
+    if flight.eligible_for_companion_cert:
+        score += 40.0
+
+    if hotel is not None:
+        score += 30.0
+
+    if restaurant is not None:
+        score += 15.0
+
+    # Value component: full +15 when cash_out == companion_taxes only (i.e.
+    # traveler saved the most), scaling down as cash_out approaches base_price*2.
+    cash_out = calculate_cash_out_of_pocket(flight, hotel)
+    max_possible_cash = flight.base_price * 2  # both tickets at full price
+    if max_possible_cash > 0:
+        savings_ratio = 1.0 - (cash_out / max_possible_cash)
+        # Clamp to [0, 1] so edge cases don't break the scale.
+        savings_ratio = max(0.0, min(1.0, savings_ratio))
+        score += savings_ratio * 15.0
+
+    return round(score, 2)
+
+
+def _extract_date_pairs(
+    flights: list[FlightOption],
+) -> list[tuple[str, str]]:
+    """Return (check_in_iso, check_out_iso) pairs from flight results."""
+    return [
+        (flight.outbound_date.isoformat(), flight.return_date.isoformat())
+        for flight in flights
+    ]
+
+
+def _extract_destinations(flights: list[FlightOption]) -> list[str]:
+    return list(dict.fromkeys(flight.destination for flight in flights))
+
+
+def _extract_cities_and_arrival_dates(
+    flights: list[FlightOption],
+) -> tuple[list[str], list[str]]:
+    cities = list(dict.fromkeys(flight.destination for flight in flights))
+    arrival_dates = list(
+        dict.fromkeys(flight.outbound_date.isoformat() for flight in flights)
+    )
+    return cities, arrival_dates
+
+
+def _find_matching_hotel(
+    flight: FlightOption,
+    hotels: list[HotelOption],
+) -> HotelOption | None:
+    """Return the first HotelOption whose destination and dates overlap the flight."""
+    for hotel in hotels:
+        if hotel.destination != flight.destination:
+            continue
+        # Dates overlap when check_in <= return_date AND check_out >= outbound_date
+        if hotel.check_in <= flight.return_date and hotel.check_out >= flight.outbound_date:
+            return hotel
+    return None
+
+
+def _find_matching_restaurant(
+    flight: FlightOption,
+    restaurants: list[RestaurantOption],
+) -> RestaurantOption | None:
+    """Return the first RestaurantOption matching the flight city and arrival date."""
+    for restaurant in restaurants:
+        if (
+            restaurant.city == flight.destination
+            and restaurant.reservation_date == flight.outbound_date
+        ):
+            return restaurant
+    return None
+
+
+def _emit(
+    callback: Callable[[SearchProgress], None],
+    step: str,
+    message: str,
+    progress: int,
+) -> None:
+    callback(SearchProgress(step=step, message=message, progress=progress))
+
+
+# ---------------------------------------------------------------------------
+# Main orchestrator
+# ---------------------------------------------------------------------------
+
+async def run_trip_search(
+    request: TripSearchRequest,
+    progress_callback: Callable[[SearchProgress], None],
+) -> list[TripResult]:
+    """
+    Coordinate Delta, IHG, and Resy subagents and return ranked TripResult list.
+
+    All three agents share a single BrowserSession so that login state is
+    preserved across site transitions.
+    """
+    user_data_dir = os.environ.get("BROWSER_USER_DATA_DIR", "./browser_data")
+
+    async with BrowserSession(user_data_dir=user_data_dir) as browser:
+
+        # --- Step 1: Delta companion certificate search ---
+        _emit(
+            progress_callback,
+            step="delta",
+            message="Checking companion certificate availability...",
+            progress=10,
+        )
+        flights: list[FlightOption] = await search_companion_cert(
+            request, browser
+        )
+
+        # --- Step 2: IHG points availability ---
+        _emit(
+            progress_callback,
+            step="ihg",
+            message="Checking IHG points availability...",
+            progress=40,
+        )
+        destinations = _extract_destinations(flights)
+        date_pairs = _extract_date_pairs(flights)
+        hotels: list[HotelOption] = await search_points_availability(
+            destinations, date_pairs, browser
+        )
+
+        # --- Step 3: Resy dining options ---
+        _emit(
+            progress_callback,
+            step="resy",
+            message="Finding Resy dining options...",
+            progress=70,
+        )
+        cities, arrival_dates = _extract_cities_and_arrival_dates(flights)
+        restaurants: list[RestaurantOption] = await find_resy_restaurants(
+            cities, arrival_dates, request.party_size, browser
+        )
+
+    # BrowserSession closed — merge results in memory.
+
+    # --- Step 4: Merge and rank ---
+    _emit(
+        progress_callback,
+        step="merging",
+        message="Ranking trip combinations...",
+        progress=90,
+    )
+
+    results: list[TripResult] = []
+    for flight in flights:
+        hotel = _find_matching_hotel(flight, hotels)
+        restaurant = _find_matching_restaurant(flight, restaurants)
+
+        cash_out = calculate_cash_out_of_pocket(flight, hotel)
+        points_required = hotel.total_points if hotel is not None else 0
+        benefits = collect_benefits(flight, hotel, restaurant)
+        score = _score_trip(flight, hotel, restaurant)
+
+        results.append(
+            TripResult(
+                destination=flight.destination,
+                flight=flight,
+                hotel=hotel,
+                restaurant=restaurant,
+                total_cash_out_of_pocket=cash_out,
+                total_points_required=points_required,
+                benefits_captured=benefits,
+                score=score,
+            )
+        )
+
+    results.sort(key=lambda r: r.score, reverse=True)
+
+    # --- Step 5: Done ---
+    _emit(
+        progress_callback,
+        step="done",
+        message="Search complete!",
+        progress=100,
+    )
+
+    return results

backend/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "tripplanner-backend"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "playwright>=1.45.0",
+    "google-genai>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.0.0",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.backends.legacy:build"

backend/requirements.txt

@@ -0,0 +1,7 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+playwright>=1.45.0
+google-genai>=1.0.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0
+httpx>=0.27.0

backend/tools/browser.py

@@ -0,0 +1,434 @@
+"""
+BrowserSession — async Playwright wrapper for the Tripplanner browser-automation layer.
+
+AI subagents (claude-haiku with tool_use) call the exposed methods to navigate
+delta.com, ihg.com, and resy.com.  A persistent Chromium profile keeps users
+logged in between runs.
+
+Usage:
+    async with BrowserSession(user_data_dir="/tmp/tripplanner-profile") as browser:
+        await browser.navigate("https://www.delta.com")
+        text = await browser.get_page_text()
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from pathlib import Path
+from typing import Any
+
+from playwright.async_api import async_playwright, BrowserContext, Page, TimeoutError as PWTimeoutError
+
+
+class BrowserSession:
+    """Async context manager wrapping a Chromium browser.
+
+    On Render (or any headless environment), set BROWSER_USER_DATA_DIR to a
+    persistent disk path and upload sessions.json via /api/session/upload.
+    Locally, run scripts/session_setup.py once to log in interactively.
+    """
+
+    def __init__(
+        self,
+        user_data_dir: str,
+        headless: bool | None = None,
+        viewport: dict[str, int] | None = None,
+        slow_mo: float = 0,
+    ) -> None:
+        self._user_data_dir = user_data_dir
+        # Auto-detect headless: if no DISPLAY env var, force headless (i.e. on Render)
+        if headless is None:
+            self._headless = not bool(os.getenv("DISPLAY", "")) or os.getenv("RENDER") == "true"
+        else:
+            self._headless = headless
+        self._viewport = viewport or {"width": 1280, "height": 900}
+        self._slow_mo = slow_mo
+
+        self._pw = None
+        self._context: BrowserContext | None = None
+        self._page: Page | None = None
+
+    def _session_file(self) -> Path | None:
+        """Return path to sessions.json if available.
+
+        Priority:
+          1. BROWSER_SESSION_JSON env var (base64-encoded) — for HF Spaces / ephemeral envs
+          2. sessions.json on disk (uploaded via /api/session/upload)
+        """
+        # 1. Decode from env var (HF Spaces stores secrets as env vars)
+        b64 = os.getenv("BROWSER_SESSION_JSON", "")
+        if b64:
+            out = Path(self._user_data_dir) / "sessions.json"
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_bytes(base64.b64decode(b64))
+            return out
+
+        # 2. File on disk (Render persistent disk or local upload)
+        p = Path(self._user_data_dir) / "sessions.json"
+        return p if p.exists() else None
+
+    # ------------------------------------------------------------------
+    # Async context manager
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> "BrowserSession":
+        self._pw = await async_playwright().start()
+        session_file = self._session_file()
+
+        if session_file:
+            # Render / deployed: use a regular (non-persistent) context with saved storage state.
+            browser = await self._pw.chromium.launch(
+                headless=self._headless,
+                slow_mo=self._slow_mo,
+            )
+            self._context = await browser.new_context(
+                storage_state=str(session_file),
+                viewport=self._viewport,
+            )
+        else:
+            # Local: use a persistent profile so the user stays logged in.
+            self._context = await self._pw.chromium.launch_persistent_context(
+                self._user_data_dir,
+                headless=self._headless,
+                viewport=self._viewport,
+                slow_mo=self._slow_mo,
+            )
+
+        if self._context.pages:
+            self._page = self._context.pages[0]
+        else:
+            self._page = await self._context.new_page()
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        if self._context:
+            await self._context.close()
+        if self._pw:
+            await self._pw.stop()
+
+    # ------------------------------------------------------------------
+    # Browser action methods
+    # ------------------------------------------------------------------
+
+    async def navigate(self, url: str) -> str:
+        """Navigate to a URL and return the page title."""
+        try:
+            await self._page.goto(url, wait_until="domcontentloaded")
+            title = await self._page.title()
+            return title or "(no title)"
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def click(self, selector: str | None = None, text: str | None = None) -> str:
+        """Click an element by CSS selector OR by visible text (not both).
+
+        Returns a confirmation string or an error message.
+        """
+        try:
+            if selector and text:
+                return "Error: provide selector OR text, not both."
+            if selector:
+                await self._page.click(selector)
+                return f"Clicked selector: {selector}"
+            if text:
+                await self._page.get_by_text(text, exact=False).first.click()
+                return f"Clicked element with text: {text!r}"
+            return "Error: provide selector or text."
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def fill(self, selector: str, value: str) -> str:
+        """Clear and fill an input field, then return confirmation."""
+        try:
+            await self._page.fill(selector, value)
+            return f"Filled {selector!r} with value."
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def get_text(self, selector: str, limit: int = 20) -> list[str]:
+        """Return the inner text of all elements matching *selector*, up to *limit* items."""
+        try:
+            texts = await self._page.locator(selector).all_inner_texts()
+            return texts[:limit]
+        except Exception as exc:
+            return [f"Error: {exc}"]
+
+    async def get_page_text(self) -> str:
+        """Return visible page text (body), truncated to 8000 characters."""
+        try:
+            text = await self._page.inner_text("body")
+            return text[:8000]
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def wait_for(self, selector: str, timeout: int = 10000) -> bool:
+        """Wait until *selector* appears in the DOM.  Returns True on success, False on timeout."""
+        try:
+            await self._page.wait_for_selector(selector, timeout=timeout)
+            return True
+        except PWTimeoutError:
+            return False
+        except Exception:
+            return False
+
+    async def select_option(self, selector: str, value: str) -> str:
+        """Select an <option> by value in a <select> element."""
+        try:
+            await self._page.select_option(selector, value=value)
+            return f"Selected option {value!r} in {selector!r}."
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def press_key(self, key: str) -> str:
+        """Send a keyboard key to the focused element (e.g. 'Enter', 'Tab')."""
+        try:
+            await self._page.keyboard.press(key)
+            return f"Pressed key: {key}"
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def scroll_down(self) -> str:
+        """Scroll the page down by ~800 px."""
+        try:
+            await self._page.mouse.wheel(0, 800)
+            return "Scrolled down."
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    async def screenshot_base64(self) -> str:
+        """Take a full-page screenshot and return it as a base64-encoded PNG string."""
+        try:
+            png_bytes = await self._page.screenshot(full_page=True)
+            return base64.b64encode(png_bytes).decode()
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    # ------------------------------------------------------------------
+    # Anthropic tool definitions
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def tool_definitions(cls) -> list[dict]:
+        """Return Anthropic-compatible tool definitions for all browser methods.
+
+        Pass the result directly to ``client.messages.create(tools=...)``.
+        """
+        return [
+            {
+                "name": "navigate",
+                "description": "Navigate the browser to a URL and return the page title.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "url": {
+                            "type": "string",
+                            "description": "The full URL to navigate to (e.g. 'https://www.delta.com').",
+                        }
+                    },
+                    "required": ["url"],
+                },
+            },
+            {
+                "name": "click",
+                "description": (
+                    "Click an element on the page.  Provide EITHER 'selector' (CSS) "
+                    "OR 'text' (visible text match), not both."
+                ),
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "selector": {
+                            "type": "string",
+                            "description": "CSS selector of the element to click.",
+                        },
+                        "text": {
+                            "type": "string",
+                            "description": "Visible text of the element to click.",
+                        },
+                    },
+                    "required": [],
+                },
+            },
+            {
+                "name": "fill",
+                "description": "Clear and type a value into an input or textarea element.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "selector": {
+                            "type": "string",
+                            "description": "CSS selector of the input element.",
+                        },
+                        "value": {
+                            "type": "string",
+                            "description": "The text to enter into the field.",
+                        },
+                    },
+                    "required": ["selector", "value"],
+                },
+            },
+            {
+                "name": "get_text",
+                "description": (
+                    "Return the inner text of all elements matching a CSS selector, "
+                    "up to 'limit' results."
+                ),
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "selector": {
+                            "type": "string",
+                            "description": "CSS selector to match elements.",
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Maximum number of text strings to return (default 20).",
+                        },
+                    },
+                    "required": ["selector"],
+                },
+            },
+            {
+                "name": "get_page_text",
+                "description": "Return the full visible text of the current page, truncated to 8000 characters.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            },
+            {
+                "name": "wait_for",
+                "description": (
+                    "Wait for a CSS selector to appear in the DOM.  "
+                    "Returns true on success, false on timeout."
+                ),
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "selector": {
+                            "type": "string",
+                            "description": "CSS selector to wait for.",
+                        },
+                        "timeout": {
+                            "type": "integer",
+                            "description": "Maximum wait time in milliseconds (default 10000).",
+                        },
+                    },
+                    "required": ["selector"],
+                },
+            },
+            {
+                "name": "select_option",
+                "description": "Select an option by value in a <select> element.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "selector": {
+                            "type": "string",
+                            "description": "CSS selector of the <select> element.",
+                        },
+                        "value": {
+                            "type": "string",
+                            "description": "The option value to select.",
+                        },
+                    },
+                    "required": ["selector", "value"],
+                },
+            },
+            {
+                "name": "press_key",
+                "description": "Send a keyboard key press to the focused element (e.g. 'Enter', 'Tab', 'Escape').",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "key": {
+                            "type": "string",
+                            "description": "The key to press (Playwright key name, e.g. 'Enter', 'Tab').",
+                        }
+                    },
+                    "required": ["key"],
+                },
+            },
+            {
+                "name": "scroll_down",
+                "description": "Scroll the current page down by approximately 800 pixels.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            },
+            {
+                "name": "screenshot_base64",
+                "description": "Take a full-page screenshot and return it as a base64-encoded PNG string (for debugging).",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            },
+        ]
+
+    # ------------------------------------------------------------------
+    # Tool dispatcher
+    # ------------------------------------------------------------------
+
+    async def dispatch_tool(self, name: str, input: dict) -> str:
+        """Dispatch a tool call by name to the matching method.
+
+        Returns the result as a string (serialised if necessary).
+        Unknown names and bad inputs are caught and returned as error strings.
+        """
+        _dispatch: dict[str, Any] = {
+            "navigate": self.navigate,
+            "click": self.click,
+            "fill": self.fill,
+            "get_text": self.get_text,
+            "get_page_text": self.get_page_text,
+            "wait_for": self.wait_for,
+            "select_option": self.select_option,
+            "press_key": self.press_key,
+            "scroll_down": self.scroll_down,
+            "screenshot_base64": self.screenshot_base64,
+        }
+
+        method = _dispatch.get(name)
+        if method is None:
+            return f"Error: unknown tool '{name}'."
+
+        try:
+            result = await method(**input)
+            # Coerce non-string results (bool, list) to strings for uniform AI consumption.
+            if isinstance(result, list):
+                return "\n".join(str(item) for item in result)
+            return str(result)
+        except TypeError as exc:
+            return f"Error: bad arguments for '{name}': {exc}"
+        except Exception as exc:
+            return f"Error: {exc}"
+
+    # Aliases used by subagents
+    async def execute_tool(self, name: str, input: dict) -> str:
+        return await self.dispatch_tool(name, input)
+
+    @property
+    def tools(self) -> list[dict]:
+        return BrowserSession.tool_definitions()
+
+    def get_tool_definitions(self) -> list[dict]:
+        return BrowserSession.tool_definitions()
+
+    @property
+    def gemini_tools(self):
+        """Return google-genai Tool objects for all browser methods."""
+        from google.genai import types as gtypes
+        return [gtypes.Tool(function_declarations=[
+            gtypes.FunctionDeclaration(
+                name=t["name"],
+                description=t["description"],
+                parameters=t["input_schema"],
+            )
+            for t in BrowserSession.tool_definitions()
+        ])]