find-flight 0.1.0 → 0.2.0

package/airports.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Lightweight airport & country lookup for the find-flight runner.
+
+Given a 3-letter IATA airport code, resolve the authoritative name, city,
+state/region and ISO-3166-1 alpha-2 country code (and its English country
+name). This is the disambiguation source that prevents mis-mapping a code to
+the wrong city — e.g. ECN is Ercan (North Cyprus), not Edinburgh; MYJ is
+Matsuyama (Japan), not Mysore.
+
+Data comes from the bundled JSON files generated from the upstream airport
+list (`enums/airports.csv` in AWeirdDev/flights, ~9.7k rows):
+  * airports.json   { code: [name, city, state, country_id] }
+  * countries.json  { ISO2: "English country name" }
+
+The files resolve relative to THIS module, so the lookup works regardless of
+the process CWD (important because the extension runs the runner from an
+arbitrary directory). If a file is missing or a code is unknown, the lookup
+returns a minimal record built from the code itself rather than raising, so
+the search never hard-fails on metadata.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+_THIS = os.path.dirname(os.path.abspath(__file__))
+
+_AIRPORTS = None      # cached dict: code -> [name, city, state, country]
+_COUNTRIES = None     # cached dict: ISO2 -> "English name"
+
+
+def _load(path: str):
+    try:
+        with open(os.path.join(_THIS, path), encoding="utf-8") as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return None
+
+
+def _airports() -> dict:
+    global _AIRPORTS
+    if _AIRPORTS is None:
+        _AIRPORTS = _load("airports.json") or {}
+    return _AIRPORTS
+
+
+def _countries() -> dict:
+    global _COUNTRIES
+    if _COUNTRIES is None:
+        _COUNTRIES = _load("countries.json") or {}
+    return _COUNTRIES
+
+
+def country_name(iso2: str) -> str:
+    """ISO-3166-1 alpha-2 code -> English country name ('' if unknown)."""
+    return _countries().get((iso2 or "").upper(), "")
+
+
+def resolve(code: str) -> dict:
+    """Resolve a 3-letter IATA code to name/city/state/country metadata.
+
+    Never raises: unknown/empty codes return a record keyed on the code with
+    empty fields, so callers can still proceed (or choose to reject on 3-char
+    validation elsewhere).
+    """
+    code = (code or "").strip().upper()
+    rec = _airports().get(code, [])
+    name, city, state, iso2 = (rec + ["", "", "", ""])[:4]
+    return {
+        "code": code,
+        "name": name,
+        "city": city,
+        "state": state,
+        "country": iso2.upper(),
+        "country_name": country_name(iso2),
+    }
+
+
+def is_known(code: str) -> bool:
+    return (code or "").strip().upper() in _airports()

package/countries.json

@@ -0,0 +1 @@
+{"AD":"Andorra","AE":"United","Arab":"Emirates","AF":"Afghanistan","AG":"Antigua","and":"the","AI":"Anguilla","AL":"Albania","AM":"Armenia","AO":"Angola","AQ":"Antarctica","AR":"Argentina","AS":"American","Samoa":"YE","Austria":"AU","Australia":"AW","Aruba":"AX","Aland":"Islands","AZ":"Azerbaijan","BA":"Bosnia","BB":"Barbados","BD":"Bangladesh","BE":"Belgium","BF":"Burkina","Faso":"BG","Bulgaria":"BH","Bahrain":"BI","Burundi":"BJ","Benin":"BL","Saint":"Vincent","BM":"Bermuda","BN":"Brunei","Darussalam":"BO","Bolivia":"BQ","Bonaire":"(Caribbean","Netherlands)":"BR","Brazil":"BS","Bahamas":"BT","Bhutan":"BV","Bouvet":"Island","BW":"Botswana","BY":"Belarus","BZ":"Belize","CA":"Canada","CC":"Cocos","(Keeling)":"Islands","CD":"Democratic","Republic":"DE","the":"Congo","CF":"Central","African":"Republic","CG":"Republic","of":"the","Congo":"CH","Switzerland":"CI","Cote":"d'Ivoire","CK":"Cook","Islands":"VN","Chile":"CM","Cameroon":"CN","China":"TZ","Colombia":"CR","Costa":"Rica","CU":"Cuba","CV":"Cape","Verde":"CW","Curacao":"CX","Christmas":"Island","CY":"Cyprus","CZ":"Czech","Germany":"DJ","Djibouti":"DK","Denmark":"DM","Dominica":"DO","Dominican":"Republic","DZ":"Algeria","EC":"Ecuador","EE":"Estonia","EG":"Egypt","EH":"Western","Sahara":"ER","Eritrea":"ES","Spain":"ET","Ethiopia":"FI","Finland":"FJ","Fiji":"FK","Falkland":"Islands","(Malvinas)":"FM","Micronesia":"FO","Faroe":"Islands","FR":"France","GA":"Gabon","GB":"United","Kingdom":"GD","Grenada":"GE","Georgia":"GF","French":"Guiana","GG":"Guernsey","GH":"Ghana","GI":"Gibraltar","GL":"Greenland","GM":"Gambia","GN":"Guinea","GP":"Guadeloupe","GQ":"Equatorial","Guinea":"PH","Greece":"GS","South":"Africa","Guatemala":"GU","Guam":"GW","Guinea-Bissau":"GY","Guyana":"HK","Hong":"Kong","HM":"Heard","Honduras":"HR","Croatia":"HT","Haiti":"HU","Hungary":"ID","Indonesia":"IE","Ireland":"IL","Israel":"IM","Isle":"of","Man":"IN","India":"IO","British":"Virgin","Ocean":"Territory","IQ":"Iraq","IR":"Iran","IS":"Iceland","IT":"Italy","JE":"Jersey","JM":"Jamaica","JO":"Jordan","JP":"Japan","KE":"Kenya","KG":"Kyrgyzstan","KH":"Cambodia","KI":"Kiribati","KM":"Comoros","KN":"Saint","Kitts":"and","Nevis":"KP","North":"Korea","KR":"South","Korea":"KW","Kuwait":"KY","Cayman":"Islands","KZ":"Kazakhstan","LA":"Laos","LB":"Lebanon","LC":"Saint","Lucia":"LI","Liechtenstein":"LK","Sri":"Lanka","LR":"Liberia","LS":"Lesotho","LT":"Lithuania","LU":"Luxembourg","LV":"Latvia","LY":"Libya","MA":"Morocco","MC":"Monaco","MD":"Moldova","ME":"Montenegro","MF":"Saint","Martin":"MG","Madagascar":"MH","Marshall":"Islands","MK":"North","Macedonia":"ML","Mali":"MM","Myanmar":"MN","Mongolia":"MO","Macao":"MP","Northern":"Mariana","Martinique":"MR","Mauritania":"MS","Montserrat":"MT","Malta":"MU","Mauritius":"MV","Maldives":"MW","Malawi":"MX","Mexico":"MY","Malaysia":"MZ","Mozambique":"NA","Namibia":"NC","New":"Zealand","NE":"Niger","NF":"Norfolk","Island":"NG","Nigeria":"NI","Nicaragua":"NL","Netherlands":"NO","Norway":"NP","Nepal":"NR","Nauru":"NU","Niue":"NZ","OM":"Oman","PA":"Panama","PE":"Peru","PF":"French","Polynesia":"PG","Papua":"New","Philippines":"PK","Pakistan":"PL","Poland":"PM","PN":"Pitcairn","PR":"Puerto","Rico":"PS","Palestine":"(West","Bank":"and","Gaza)":"PT","Portugal":"PW","Palau":"PY","Paraguay":"QA","Qatar":"RE","Reunion":"RO","Romania":"RS","Serbia":"RU","Russia":"RW","Rwanda":"SA","Saudi":"Arabia","SB":"Solomon","Seychelles":"SD","Sudan":"SE","Sweden":"SG","Singapore":"SH","SI":"Slovenia","SJ":"Svalbard","Mayen":"SK","Slovakia":"SL","Sierra":"Leone","SM":"San","Marino":"SN","Senegal":"SO","Somalia":"SR","Suriname":"SS","ST":"Sao","Tome":"and","Principe":"SV","El":"Salvador","SX":"Sint","Maarten":"SY","Syria":"SZ","Swaziland":"TC","Turks":"and","Caicos":"Islands","TD":"Chad","TF":"French","Southern":"Territories","TG":"Togo","TH":"Thailand","TJ":"Tajikistan","TK":"Tokelau","TL":"Timor-Leste","TM":"Turkmenistan","TN":"Tunisia","TO":"Tonga","TR":"Turkey","TT":"Trinidad","TV":"Tuvalu","TW":"Taiwan,","Province":"of","Tanzania":"UA","Ukraine":"UG","Uganda":"UM","U.S.":"Virgin","Outlying":"Islands","US":"United","States":"UY","Uruguay":"UZ","Uzbekistan":"VA","Holy":"See","(Vatican":"City","State)":"VC","Grenadines":"VE","Venezuela":"VG","Vietnam":"VU","Vanuatu":"WF","Wallis":"and","Futuna":"WS","Yemen":"YT","Mayotte":"ZA","ZM":"Zambia","ZW":"Zimbabwe"}

package/examples/search_flights.py

@@ -90,6 +90,28 @@ def total_duration(flight) -> int:
     return sum(seg.duration for seg in flight.flights)
 
 
+def load_airports():
+    """Try to ""import airports"" for city/country metadata; fall back to a no-op."""
+    try:
+        import airports as a
+        return a
+    except Exception:
+        return None
+
+
+AP = load_airports()
+
+
+def place(code: str) -> str:
+    if AP:
+        r = AP.resolve(code)
+        if r["country"]:
+            return f"{code} {r['city']}, {r['country']}".strip()
+        if r["name"]:
+            return f"{code} ({r['name']})"
+    return code
+
+
 def print_result(result: ResultList, currency: str = "") -> None:
     if not result:
         print("No flights found.")
@@ -100,7 +122,7 @@ def print_result(result: ResultList, currency: str = "") -> None:
         for seg in flight.flights:
             dep = f"{seg.departure.date[0]}-{seg.departure.date[1]:02d}-{seg.departure.date[2]:02d} {seg.departure.time[0]:02d}:{seg.departure.time[1]:02d}"
             arr = f"{seg.arrival.date[0]}-{seg.arrival.date[1]:02d}-{seg.arrival.date[2]:02d} {seg.arrival.time[0]:02d}:{seg.arrival.time[1]:02d}"
-            print(f"  {seg.from_airport.code} {dep} -> {seg.to_airport.code} {arr} "
+            print(f"  {place(seg.from_airport.code)} {dep} -> {place(seg.to_airport.code)} {arr} "
                   f"({seg.duration} min, {seg.plane_type})")
     print(f"\n{len(result)} itinerary/ies")
 

package/extensions/flight-search.ts

@@ -88,11 +88,11 @@ const search_flights = {
 	name: "search_flights",
 	label: "Search Flights",
 	description:
-		"Search real Google Flights availability between two airports on given dates via fast-flights. Returns structured JSON: price (currency), airline(s), number of stops, and each flight leg with airports, times, duration and plane type. For round-trips, price is the two-way total and only the outbound legs are returned. Use for finding flights, checking prices/availability, comparing routes, dates, seats, or airlines.",
+		"Search real Google Flights availability between two airports on given dates via fast-flights. Pass 3-letter IATA airport codes (from_airport/to_airport); the tool resolves each code to its airport name, city and ISO-3166 country so you know exactly which city the code refers to before reading results. Returns structured JSON: the resolved route (airport/city/country), price (currency), airline(s), number of stops, and each flight leg with airports, city/country, times, duration and plane type. For round-trips it runs a native round-trip query and returns the TRUE two-way total price with the outbound legs, plus one-way reference fares showing return-leg schedules (return_options). Use for finding flights, checking prices/availability, comparing routes, dates, seats, or airlines.",
 	promptSnippet: "Search live Google Flights for price/availability between airports",
 	promptGuidelines: [
 		"Use search_flights for real flight prices and availability instead of guessing or writing ad-hoc scraping scripts.",
-		"Before calling search_flights, verify airport codes (from_airport/to_airport must be 3-letter IATA codes) and resolve dates to YYYY-MM-DD; ask the user if the code, trip type, or dates are unclear.",
+		"Pass 3-letter IATA airport codes (from_airport/to_airport); the tool resolves each code to its airport name, city and ISO-3166 country so you can confirm a code really means the city the user wants (e.g. ECN = Ercan/Cyprus). Resolve dates to YYYY-MM-DD; ask the user if the code, trip type, or dates are unclear.",
 		"search_flights prices carry the currency you pass; pass a currency (e.g. 'EUR', 'TRY', 'USD') unless the user prefers Google's default.",
 	],
 	parameters: Type.Object({
@@ -137,34 +137,84 @@ const search_flights = {
 		const obj = data as Record<string, unknown>;
 		if (obj.error) throw new Error(`flight search error: ${obj.error}`);
 
-		const flights = (obj.flights ?? []) as Array<Record<string, unknown>>;
-		if (flights.length === 0) {
+		const currency = (obj.currency as string | undefined) ?? "";
+
+		// Human-friendly duration: show minutes too when under 2h (e.g. 1h 35m).
+		const fmtDuration = (min: number) => {
+			const m = Math.round(min || 0);
+			const h = Math.floor(m / 60);
+			const r = m % 60;
+			return h > 0 ? `${h}h${r ? ` ${r}m` : ""}` : `${r}m`;
+		};
+
+		// Render one direction of flights (outbound or return).
+		const renderDirection = (
+			label: string,
+			flights: Array<Record<string, unknown>>,
+			routeSummary?: string,
+		) => {
+			const sorted = [...flights].sort((a, b) => Number(a.price) - Number(b.price));
+			const top = sorted.slice(0, 10);
+			const header = `## ${label}${routeSummary ? ` — ${routeSummary}` : ""}`;
+			if (top.length === 0) return `${header}\nNo ${label.toLowerCase()} flights found.`;
+			const lines = top.map((f, i) => {
+				const legs = (f.legs as Array<Record<string, string>>) ?? [];
+				const where = (l: Record<string, string>, prefix: "from" | "to") => {
+					const code = l[prefix];
+					const city = l[`${prefix}_city`] ?? "";
+					const country = l[`${prefix}_country`] ?? "";
+					const ctx = city || country ? ` (${city}, ${country})` : "";
+					return `${code}${ctx}`;
+				};
+				const seg = legs
+					.map(
+						(l) =>
+							`${where(l, "from")} ${l.departure} → ${where(l, "to")} ${l.arrival} ${l.date} ` +
+						`(${fmtDuration(Number(l.duration_minutes) || 0)}, ${l.plane})`,
+					)
+					.join(", ");
+				const airline = (f.airlines as string[] | undefined)?.join("/") ?? "";
+				const stops = Number(f.stops) || 0;
+				return `${i + 1}. ${f.currency ?? currency} ${f.price} · ${airline} · ${stops === 0 ? "direct" : `${stops} stop${stops > 1 ? "s" : ""}`}\n   ${seg}`;
+			});
+			return `${header}\n${lines.join("\n")}\n\n${sorted.length} itinerary/ies (showing cheapest ${top.length})`;
+		};
+
+		// ---- round-trip: native RT query (true two-way price) + return reference ----
+		if (obj.trip === "round-trip") {
+			const rt = (obj.round_trip ?? []) as Array<Record<string, unknown>>;
+			const retOpts = (obj.return_options ?? []) as Array<Record<string, unknown>>;
+			const or = obj.outbound_route as Record<string, unknown> | undefined;
+			const rr = obj.return_route as Record<string, unknown> | undefined;
+			const outboundSummary = (or?.summary as string | undefined) ?? "";
+			const returnSummary = (rr?.summary as string | undefined) ?? "";
+			const parts: string[] = [];
+			parts.push(renderDirection("Round-trip (true two-way total, outbound legs shown)", rt, outboundSummary));
+			parts.push(renderDirection("Return leg options (one-way reference fares — NOT round-trip prices)", retOpts, returnSummary));
+			const text = parts.join("\n\n");
 			return {
-				content: [{ type: "text", text: "No flights found for this search." }],
-				details: { currency: obj.currency, count: 0 },
+				content: [{ type: "text", text }],
+				details: {
+					currency,
+					trip: "round-trip",
+					outbound_route: or,
+					return_route: rr,
+					round_trip: rt,
+					return_options: retOpts,
+					note: obj.note,
+				},
 			};
 		}
-		flights.sort((a, b) => Number(a.price) - Number(b.price));
-		const top = flights.slice(0, 10);
-
-		const lines = top.map((f, i) => {
-			const legs = (f.legs as Array<Record<string, string>>) ?? [];
-			const seg = legs.map(
-				(l) =>
-					`${l.from} ${l.departure} → ${l.to} ${l.arrival} ${l.date} (${Math.round(
-						(Number(l.duration_minutes) || 0) / 60,
-					)}h, ${l.plane})`,
-			).join(", ");
-			const rt = f.is_round_trip ? " (round-trip total)" : "";
-			const airline = (f.airlines as string[] | undefined)?.join("/") ?? "";
-			const stops = Number(f.stops) || 0;
-			return `${i + 1}. ${f.currency} ${f.price}${rt} · ${airline} · ${stops === 0 ? "direct" : `${stops} stop`}\n   ${seg}`;
-		});
-		const summary = `${lines.join("\n")}\n\n${flights.length} itinerary/ies (showing cheapest ${top.length})`;
 
+		// ---- one-way (and legacy flat shape) ----
+		const route = obj.route as Record<string, unknown> | undefined;
+		const routeSummary = (route?.summary as string | undefined) ?? "";
+		const flights = (obj.flights ?? []) as Array<Record<string, unknown>>;
+		const rendered = renderDirection("Flights", flights, routeSummary);
+		const text = `${rendered}\n\nRoute: ${routeSummary}`;
 		return {
-			content: [{ type: "text", text: summary }],
-			details: { currency: obj.currency, flights },
+			content: [{ type: "text", text }],
+			details: { currency, trip: "one-way", route, flights },
 		};
 	},
 };

package/flight_runner.py

@@ -21,20 +21,44 @@ Query keys (all optional unless noted):
 Errors are reported as JSON with {"error": "..."} and a non-zero exit code, so
 the caller can distinguish "no flights" (valid empty result) from a failure.
 
-Output shape (ResultList -> list):
-  [{ "price": int, "currency": str, "is_round_trip": bool, "airlines": [..],
-     "type": str, "carbon": {"typical_on_route": int, "emission": int},
-     "stops": int, "legs": [leg...] }]
+Output shapes:
 
-IMPORTANT (fast-flights behavior, verified): `flight.flights` contains ONLY the
-OUTBOUND legs. For a round-trip, `price` is the TOTAL round-trip fare, but no
-return-leg detail is present in the parsed data. So the output describes the
-outbound itinerary; set `is_round_trip` when return was requested so the caller
-knows `price` is the two-way total.
+  one-way   -> { currency, trip: "one-way", route, flights: [flight...] }
+  round-trip-> { currency, trip: "round-trip", outbound_route, return_route,
+                 round_trip: [flight...], return_options: [flight...], note }
+
+Each flight: { "price": int, "currency": str, "price_type": str,
+                "airlines": [..], "type": str,
+                "carbon": {"typical_on_route": int, "emission": int},
+                "stops": int, "legs": [leg...] }
+
+ROUND-TRIP PRICING (fast-flights behavior, verified 2026-09-11): a single
+native round-trip query (two FlightQuery legs, trip="round-trip") returns
+flight.price as the TRUE two-way total fare, and flight.flights with ONLY the
+outbound legs — the return direction is not in the data (no booking token
+links a specific outbound with a specific return). NEVER estimate a
+round-trip price by summing two one-way fares: one-way fares (especially
+business) are often far higher than half the RT fare (e.g. IST<->BRU direct
+business 2026-11-20/22 was USD 855 RT vs ~USD 1422 as a sum of one-ways).
+
+So for round-trips the runner:
+  1. runs the native RT query -> `round_trip[]`: true two-way totals with
+     outbound legs (price_type "round-trip-total") — this is the price to
+     present;
+  2. runs ONE one-way search for the return direction -> `return_options[]`:
+     real return-leg schedules priced at one-way fares for reference ONLY
+     (price_type "one-way-reference").
 
 Each leg: { "from": code, "from_name": str, "to": code, "to_name": str,
+            "from_city": str, "to_city": str,
+            "from_country": str, "to_country": str,
+            "from_country_name": str, "to_country_name": str,
             "date": "YYYY-MM-DD", "departure": "HH:MM", "arrival": "HH:MM",
             "duration_minutes": int, "plane": str }
+
+Metadata: airport names/cities and ISO-3166 country codes are resolved from
+the bundled lookup (airports.py + airports.json/countries.json) so the caller
+knows exactly which city and country each code refers to (disambiguation).
 """
 from __future__ import annotations
 
@@ -49,6 +73,8 @@ from fast_flights import (
     get_flights,
 )
 
+import airports as airport_lookup
+
 SEATS = ("economy", "premium-economy", "business", "first")
 TRIPS = ("one-way", "round-trip")
 
@@ -58,11 +84,21 @@ def _hhmm(t) -> str:
 
 
 def _leg(seg) -> dict:
+    f = airport_lookup.resolve(seg.from_airport.code)
+    t = airport_lookup.resolve(seg.to_airport.code)
     return {
         "from": seg.from_airport.code,
-        "from_name": seg.from_airport.name,
+        "from_name": f["name"] or seg.from_airport.name,
+        "from_city": f["city"],
+        "from_state": f["state"],
+        "from_country": f["country"],
+        "from_country_name": f["country_name"],
         "to": seg.to_airport.code,
-        "to_name": seg.to_airport.name,
+        "to_name": t["name"] or seg.to_airport.name,
+        "to_city": t["city"],
+        "to_state": t["state"],
+        "to_country": t["country"],
+        "to_country_name": t["country_name"],
         "date": "%04d-%02d-%02d" % seg.departure.date,
         "departure": _hhmm(seg.departure.time),
         "arrival": _hhmm(seg.arrival.time),
@@ -71,32 +107,10 @@ def _leg(seg) -> dict:
     }
 
 
-def run(q: dict) -> dict:
-    seat = q.get("seat", "economy")
-    trip = q.get("trip", "one-way")
-    if seat not in SEATS:
-        raise ValueError(f"seat must be one of {SEATS}")
-    if trip not in TRIPS:
-        raise ValueError(f"trip must be one of {TRIPS}")
-
-    outbound_date = q["outbound_date"]
-    src = q["from_airport"].strip().upper()
-    dst = q["to_airport"].strip().upper()
-    for code in (src, dst):
-        if not (code.isalpha() and len(code) == 3):
-            raise ValueError(f"airport code must be 3 letters, got {code!r}")
-
-    legs = [FlightQuery(date=outbound_date, from_airport=src, to_airport=dst)]
-    return_date = q.get("return_date")
-    if trip == "round-trip":
-        if not return_date:
-            raise ValueError("return_date is required for round-trip")
-        legs.append(FlightQuery(date=return_date, from_airport=dst, to_airport=src))
-
-    query = create_query(
-        flights=legs,
-        trip=trip,
-        seat=seat,
+def _query_params(q: dict) -> dict:
+    """Common fast-flights params shared by both trip directions."""
+    return dict(
+        seat=q.get("seat", "economy"),
         passengers=Passengers(
             adults=int(q.get("adults", 1)),
             children=int(q.get("children", 0)),
@@ -113,17 +127,29 @@ def run(q: dict) -> dict:
         exclude_basic_economy=bool(q.get("exclude_basic_economy", False)),
     )
 
+
+def _search_direction(date: str, src: str, dst: str, q: dict) -> list:
+    """Run a single one-way search src->dst on date and return the flight list.
+
+    One-way fares. Used for trip="one-way", and (for round-trips) as a
+    reference search for the RETURN direction's leg schedules — the native RT
+    query does not include return legs.
+    """
+    query = create_query(
+        flights=[FlightQuery(date=date, from_airport=src, to_airport=dst)],
+        trip="one-way",
+        **_query_params(q),
+    )
     try:
         result = get_flights(query)
     except FlightsNotFound:
-        return {"currency": q.get("currency", "") or "default", "flights": []}
-
+        return []
     currency = q.get("currency", "") or "default"
-    out = [
+    return [
         {
             "price": f.price,
             "currency": currency,
-            "is_round_trip": trip == "round-trip",
+            "price_type": "one-way",
             "airlines": f.airlines,
             "type": f.type,
             "carbon": {
@@ -135,7 +161,113 @@ def run(q: dict) -> dict:
         }
         for f in result
     ]
-    return {"currency": currency, "flights": out}
+
+
+def _search_round_trip(out_date: str, ret_date: str, src: str, dst: str, q: dict) -> list:
+    """Native fast-flights round-trip query (both legs in ONE query).
+
+    Returns flights whose `price` is the TRUE two-way round-trip total fare.
+    `legs` contain only the OUTBOUND direction (fast-flights limitation,
+    verified) — return-leg schedules must come from a separate one-way search.
+    """
+    query = create_query(
+        flights=[
+            FlightQuery(date=out_date, from_airport=src, to_airport=dst),
+            FlightQuery(date=ret_date, from_airport=dst, to_airport=src),
+        ],
+        trip="round-trip",
+        **_query_params(q),
+    )
+    try:
+        result = get_flights(query)
+    except FlightsNotFound:
+        return []
+    currency = q.get("currency", "") or "default"
+    return [
+        {
+            "price": f.price,  # true two-way round-trip total
+            "price_type": "round-trip-total",
+            "currency": currency,
+            "airlines": f.airlines,
+            "type": f.type,
+            "carbon": {
+                "typical_on_route": f.carbon.typical_on_route,
+                "emission": f.carbon.emission,
+            },
+            "stops": len(f.flights) - 1,
+            "legs": [_leg(x) for x in f.flights],  # outbound legs only
+        }
+        for f in result
+    ]
+
+
+def _route(src: str, dst: str) -> dict:
+    """Resolved endpoint metadata + a ready-to-read summary."""
+    route = {
+        "from": airport_lookup.resolve(src),
+        "to": airport_lookup.resolve(dst),
+    }
+    route["summary"] = (
+        f"{route['from']['code']} {route['from']['city']}, "
+        f"{route['from']['country_name'] or route['from']['country']} -> "
+        f"{route['to']['code']} {route['to']['city']}, "
+        f"{route['to']['country_name'] or route['to']['country']}"
+    )
+    return route
+
+
+def run(q: dict) -> dict:
+    seat = q.get("seat", "economy")
+    trip = q.get("trip", "one-way")
+    if seat not in SEATS:
+        raise ValueError(f"seat must be one of {SEATS}")
+    if trip not in TRIPS:
+        raise ValueError(f"trip must be one of {TRIPS}")
+
+    outbound_date = q["outbound_date"]
+    src = q["from_airport"].strip().upper()
+    dst = q["to_airport"].strip().upper()
+    for code in (src, dst):
+        if not (code.isalpha() and len(code) == 3):
+            raise ValueError(f"airport code must be 3 letters, got {code!r}")
+        if not airport_lookup.is_known(code):
+            raise ValueError(
+                f"unknown airport code {code!r}: not in the airport database "
+                f"(resolve it to a valid IATA code first)"
+            )
+
+    currency = q.get("currency", "") or "default"
+
+    if trip == "round-trip":
+        return_date = q.get("return_date")
+        if not return_date:
+            raise ValueError("return_date is required for round-trip")
+        # Native RT query for the TRUE two-way price (+outbound legs), plus a
+        # one-way reference search so return-leg schedules are still visible.
+        payload = {
+            "currency": currency,
+            "trip": "round-trip",
+            "outbound_route": _route(src, dst),
+            "return_route": _route(dst, src),
+            "round_trip": _search_round_trip(outbound_date, return_date, src, dst, q),
+            "return_options": _search_direction(return_date, dst, src, q),
+            "note": (
+                "round_trip[].price is the true two-way round-trip total from a "
+                "native fast-flights RT query; its legs cover the outbound "
+                "direction only. return_options[] are one-way fares for the "
+                "return direction (schedule reference, NOT round-trip prices). "
+                "Do not add one-way fares to estimate round-trip prices."
+            ),
+        }
+        return payload
+
+    # one-way: keep the flat, backward-compatible shape.
+    return {
+        "currency": currency,
+        "trip": "one-way",
+        "route": _route(src, dst),
+        "flights": _search_direction(outbound_date, src, dst, q),
+    }
 
 
 def main() -> int:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "find-flight",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Google Flights search for agents — a pi extension (search_flights tool) + portable skill, powered by the fast-flights scraper.",
   "keywords": [
     "pi-package",
@@ -25,12 +25,15 @@
     "extensions/",
     "skills/",
     "flight_runner.py",
+    "airports.py",
+    "airports.json",
+    "countries.json",
     "examples/",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "verify": "python3 -c \"import json,sys; from pathlib import Path; Path('flight_runner.py')\" && python3 -m py_compile flight_runner.py && echo \"runner OK\"",
+    "verify": "python3 -c \"import json,sys; from pathlib import Path; Path('flight_runner.py')\" && python3 -m py_compile flight_runner.py airports.py && python3 -c \"import airports; assert airports.is_known('IST') and airports.country_name('TR')=='Turkey'\" && echo \"runner OK\"",
     "prepublishOnly": "npm run verify"
   },
   "publishConfig": {

package/skills/find-flight/SKILL.md

@@ -35,7 +35,11 @@ pip install fast-flights
    ```
    Then resolve relative/ambiguous dates ("next Friday", "11-13 September") against this real year. Format every date as `YYYY-MM-DD`.
 2. **Confirm one-way vs round-trip.** If the user didn't explicitly say, ASK: one-way (1 leg, needs only `date`+`from`+`to`) vs round-trip (2+ legs, needs a `return_date` too). Do not assume. If a stay duration or "until" date is given, that implies round-trip — but still confirm the dates.
-3. **Verify the airport codes — never guess what a 3-letter IATA code means.** Models routinely map codes to the wrong city (e.g. misreading `ECN` as Edinburgh when it is really Ercan, or inventing a code). Before searching, confirm what `from_airport`/`to_airport` actually are: look the code up in the upstream airport list (`enums/airports.csv` in `AWeirdDev/flights`, ~9.7k rows, by code + name) or against a known route. If you can't verify a code, ask the user instead of assuming.
+3. **Verify the airport codes — never guess what a 3-letter IATA code means.** Models routinely map codes to the wrong city (e.g. misreading `ECN` as Edinburgh when it is really Ercan, or inventing a code). Before searching, confirm what `from_airport`/`to_airport` actually are: look the code up in the upstream airport list (`enums/airports.csv` in `AWeirdDev/flights`, ~9.7k rows, by code + name + country) or against a known route. If you can't verify a code, ask the user instead of assuming.
+
+   **Country & airport awareness is built into the tools in this package.** The `search_flights` tool and `flight_runner.py` bundle a code → (airport name, city, state, ISO-3166 country) lookup (`airports.py` + `airports.json`/`countries.json`). Every search resolves both endpoint codes to their city and country **before** calling Google Flights, rejects an unknown code with a clear error, and returns per-leg `*_city`, `*_state`, `*_country` and `*_country_name` fields plus a human-readable `route.summary` (e.g. `IST Istanbul, Turkey -> ECN Nicosia, Cyprus`). So the agent never has to guess a code's meaning — the tool surfaces it.
+
+   Still treat output resolution as a *cross-check*, not a replacement for intent: an ambiguous request (e.g. user says "St. John's" but a code resolves elsewhere) should still be confirmed against the user's intent.
 
 ## Core Recipe — structured query
 
@@ -101,6 +105,8 @@ query = create_query(
 )
 ```
 
+`flight.price` on the result is the **true two-way total fare**; `flight.flights` contains only the **outbound** legs (no return segments are in the data).
+
 ## Natural-language path (agent-friendly)
 
 `get_flights` also accepts a plain sentence instead of a `Query`:
@@ -135,9 +141,13 @@ for flight in result:
         leg.plane_type     # str
 ```
 
+**Country & airport codes (the bundled tools add these).** When you call `search_flights` or `flight_runner.py` (not raw fast-flights), each leg is enriched with the resolved airport metadata from the bundled lookup — `from_city`, `from_state`, `from_country` (ISO-3166 alpha-2), `from_country_name`, and the matching `to_*` fields — plus `from_name`/`to_name`. A top-level `route` object gives both endpoints' resolved metadata and a ready-to-read `route.summary` like `IST Istanbul, Turkey -> ECN Nicosia, Cyprus`. This is how the agent knows the country and airport code with certainty instead of guessing.
+
 **Currency is NOT attached to prices.** `flight.price` is a bare `int` with no currency symbol or code. The currency that the price is quoted in is whatever you passed to `create_query(currency=...)` (or Google's default if you passed `""` — often the local currency, e.g. Turkish Lira for a Turkey-originating route). When presenting prices, surface the currency explicitly: track the `currency` you passed (or the user's expected currency) and label every price with it. Never hardcode a currency symbol in your output format — it may not match the price's actual currency.
 
-**Round-trip: `price` is the total, but only OUTBOUND legs are returned (verified).** For a `round-trip` query, `flight.flights` contains **only the outbound legs** — the parsed data does not include return-leg detail. `flight.price` is the **two-way total fare**. So: count stops and display legs from `flight.flights` as the outbound itinerary, and tell the user that `price` covers both directions but only outbound flight times are available. Do NOT invent or assume return-leg segments that aren't in the data.
+**Round-trip legs — raw `fast-flights` gives only OUTBOUND (verified).** A single `create_query(..., trip="round-trip")` returns `flight.flights` with **only the outbound legs** — no return-leg detail — and `flight.price` as the **two-way total fare**. So on raw fast-flights, count stops/display legs as the outbound itinerary; do NOT invent return segments that aren't in the data.
+
+**Round-trip legs — the bundled tools price the true RT fare.** `search_flights` / `flight_runner.py` run the **native round-trip query** (both legs in one `create_query`) as the price source: `round_trip[].price` is the **true two-way total** and its `legs` cover the **outbound direction only**. They additionally run **one one-way search for the return direction** (`return_options[]`) so real return-leg schedules are visible; those prices are **one-way reference fares, NOT round-trip prices** (a `price_type` field marks each entry: `round-trip-total` vs `one-way`). Each direction gets its own `outbound_route` / `return_route` metadata. No pairing is manufactured between a specific outbound and a specific return, because the API exposes no booking token linking them.
 
 `FlightsNotFound` is raised when nothing matches (or Google returns an error status).
 
@@ -193,13 +203,14 @@ best = result[0]                         # or result[:3] for top-N
 | Expecting `multi-city` to work | Unimplemented — treat as not supported today |
 | Passing `airlines` to multiple legs expecting per-leg filtering | Only first leg's `airlines` is applied |
 | Assuming 24h timestamps | Times are `(hour, minute)` on a 0–23 clock |
-| Guessing what a 3-letter airport code means | Verify it against the upstream `enums/airports.csv` (or a known route) before searching |
+| Guessing what a 3-letter airport code means | Verify it against the upstream `enums/airports.csv` (or a known route) before searching; the bundled `search_flights` tool resolves codes to city + country for you |
 | Hardcoding a currency symbol in output | `price` has no currency — track/pass `currency` and label prices with it |
-| Assuming return legs are in the round-trip data | `flights` holds only outbound legs; `price` is the two-way total — label it as such |
+| Summing two one-way fares to quote a round-trip price | One-way fares (esp. business) are often far higher than half the RT fare (verified: IST↔BRU direct business 2026-11-20/22 = USD 855 RT vs ~USD 1,422 summed one-ways). Always use the native round-trip query / `round_trip[].price` |
+| Assuming return legs are in raw round-trip data | Raw `fast-flights` returns only outbound legs (but with the true two-way price); the bundled `search_flights` tool adds a one-way return-direction search (`return_options[]`) so return-leg schedules ARE shown there |
 
 ## Real-world notes
 
 - Version: `fast-flights` 3.x. See upstream repo `AWeirdDev/flights` and docs `aweirddev.github.io/flights`.
 - Run a ready-made CLI: `python examples/search_flights.py --from TPE --to MYJ --date 2025-01-01 --seat economy`.
-- **Round-trip data (verified):** the parsed result contains only outbound legs; `price` is the two-way total. Present it as such.
+- **Round-trip pricing (verified 2026-09-11):** a single native `create_query(trip="round-trip")` returns the **true two-way total** in `flight.price` with **outbound legs only**. The bundled `search_flights` / `flight_runner.py` use that native query as the price source (`round_trip[]`) plus a one-way return-direction search for leg schedules (`return_options[]`, one-way reference fares). Never estimate RT prices by summing one-ways.
 - **pi extension:** if the `search_flights` custom tool is active (via `extensions/flight-search.ts`), prefer calling it over writing ad-hoc Python — it returns structured, correctly-labelled results and leaves no scratch files. `flight_runner.py` is the equivalent standalone executor.