find-flight 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 find-flight contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# find-flight
+
+**Google Flights search for AI agents.** A [pi](https://github.com/earendil-works/pi) package that bundles:
+
+- **a `search_flights` extension tool** — deterministic, structured flight searches the agent calls directly
+- **a portable skill** — recipes and reference that work in pi, Claude Code, and Codex
+
+Powered by the [`fast-flights`](https://github.com/AWeirdDev/flights) Google Flights scraper. Read-only — it fetches real availability and prices, but does **not** book anything.
+
+## ✨ What it does
+
+- Search flights between airports on given dates (one-way or round-trip)
+- Real prices, airlines, per-leg times, duration, plane type, stop counts, carbon emissions
+- Filters: seat class, passengers, currency, language, max stops, max price, exclude basic economy
+- Returns **structured** results — correct per-direction stop counts, no ad-hoc scripts left behind
+
+## 📦 Install
+
+Requires **Python 3.10+** with fast-flights, and live network access:
+
+```bash
+pip install fast-flights
+```
+
+### As a pi package (<img src="https://img.shields.io/badge/pi-package-5B8DEF)" width="60px" align="center">)
+
+```bash
+pi install git:github.com/<your-user>/find-flight
+# or from npm if published:
+pi install npm:find-flight
+```
+
+Or install only for the current run:
+
+```bash
+pi -e git:github.com/<your-user>/find-flight
+```
+
+After install, reload pi (`/reload`) — the agent gains a `search_flights` tool automatically.
+
+### Manually (local dev / other harnesses)
+
+```bash
+# pi extension
+ln -s "$(pwd)/extensions/flight-search.ts" ~/.pi/agent/extensions/flight-search.ts
+
+# skill (pi)
+ln -s "$(pwd)/skills/find-flight" ~/.pi/agent/skills/find-flight
+# skill (Claude Code / Codex)
+ln -s "$(pwd)/skills/find-flight" ~/.agents/skills/find-flight
+ln -s "$(pwd)/skills/find-flight" ~/.claude/skills/find-flight
+```
+
+## 🚀 Usage
+
+Just ask in natural language:
+
+> *"Find one-way flights from IST to ECN on 12 September, economy, show cheapest 3"*
+>
+> *"Cheapest round-trip Istanbul to Paris, out 23 Oct return 25 Oct"*
+
+The agent calls `search_flights(from_airport, to_airport, outbound_date, trip, return_date?, seat, currency, ...)` and gets structured JSON.
+
+### Python executor (standalone)
+
+`flight_runner.py` reads a JSON query on stdin and writes structured JSON on stdout — useful for testing or scripting without the agent:
+
+```bash
+echo '{"from_airport":"IST","to_airport":"ECN","outbound_date":"2026-09-12","trip":"one-way","currency":"EUR"}' \
+  | python3 flight_runner.py
+```
+
+### CLI example
+
+```bash
+python examples/search_flights.py --from IST --to ECN --date 2026-09-12 --currency EUR --sort price --limit 3
+```
+
+## 📁 Layout
+
+```
+find-flight/
+├── package.json               # pi package manifest (extensions + skills)
+├── extensions/
+│   └── flight-search.ts       # registerTool: search_flights
+├── skills/
+│   └── find-flight/SKILL.md   # portable agent skill
+├── flight_runner.py           # Python executor (structured JSON)
+├── examples/
+│   └── search_flights.py      # CLI example
+└── README.md
+```
+
+## ⚙️ Notes / limitations
+
+- **Round-trip data (verified):** parsed results contain only the **outbound** legs; `price` is the **two-way total**. The tool reports this explicitly.
+- `multi-city` trips are not supported by the upstream library.
+- Scraping Google is subject to rate limits / IP blocks. For heavy use, plug a proxy (BrightData) or richer source (SearchApi) integration into `fast-flights`.
+- Prices are quoted in the `currency` you pass; if omitted, Google picks a default (often the local currency).
+- Config: point the runner elsewhere with `FLIGHT_RUNNER=/path/to/flight_runner.py`, or choose a different interpreter with `FLIGHT_PYTHON=...`.
+
+## 🔒 Security
+
+This package executes Python (`flight_runner.py`) that makes live network requests to Google. Review the source before installing.
+
+## License
+
+MIT

package/examples/search_flights.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Search Google Flights with fast-flights from the command line.
+
+Requires: pip install fast-flights
+
+Examples:
+    python search_flights.py --from TPE --to MYJ --date 2025-01-01
+    python search_flights.py --from TPE --to MYJ --date 2025-01-01 --trip round-trip --return-date 2025-01-08 --seat business
+    python search_flights.py --from TPE --to MYJ --date 2025-01-01 --max-stops 1 --max-price 500 --currency USD --sort price --limit 5
+    echo "Flights from TPE to MYJ on 2025-01-01 one way economy" | python search_flights.py --text
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date as Date
+
+from fast_flights import (
+    FlightsNotFound,
+    FlightQuery,
+    Passengers,
+    ResultList,
+    create_query,
+    get_flights,
+)
+
+TRIPS = ("one-way", "round-trip")
+SEATS = ("economy", "premium-economy", "business", "first")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Search Google Flights with fast-flights.")
+    p.add_argument("--text", action="store_true",
+                   help="Read a natural-language query from stdin instead of structured flags.")
+    p.add_argument("--from", dest="from_airport", required=False,
+                   help="3-letter IATA departure airport.")
+    p.add_argument("--to", dest="to_airport", required=False,
+                   help="3-letter IATA arrival airport.")
+    p.add_argument("--date", type=Date.fromisoformat,
+                   help="Departure date, YYYY-MM-DD.")
+    p.add_argument("--return-date", type=Date.fromisoformat,
+                   help="Return date for round-trip, YYYY-MM-DD.")
+    p.add_argument("--trip", choices=TRIPS, default="one-way")
+    p.add_argument("--seat", choices=SEATS, default="economy")
+    p.add_argument("--adults", type=int, default=1)
+    p.add_argument("--children", type=int, default=0)
+    p.add_argument("--currency", default="")
+    p.add_argument("--language", default="")
+    p.add_argument("--max-stops", type=int)
+    p.add_argument("--max-price", type=int)
+    p.add_argument("--sort", choices=("price", "duration"), default=None,
+                   help="Sort results by price (ascending) or total duration (ascending).")
+    p.add_argument("--limit", type=int, default=0,
+                   help="Show only the top N itineraries after sorting (0 = all).")
+    return p
+
+
+def leg(date: Date, src: str, dst: str, max_stops: int | None) -> FlightQuery:
+    src, dst = src.strip().upper(), dst.strip().upper()
+    for code in (src, dst):
+        if not code.isalpha() or len(code) != 3:
+            sys.exit(f"airport codes must be 3 letters, got {code!r}")
+    return FlightQuery(
+        date=date.strftime("%Y-%m-%d"),
+        from_airport=src,
+        to_airport=dst,
+        max_stops=max_stops,
+    )
+
+
+def build_query(args: argparse.Namespace):
+    flights = [leg(args.date, args.from_airport, args.to_airport, args.max_stops)]
+    if args.trip == "round-trip":
+        if not args.return_date:
+            sys.exit("--return-date is required for --trip round-trip")
+        flights.append(leg(args.return_date, args.to_airport, args.from_airport, args.max_stops))
+
+    return create_query(
+        flights=flights,
+        trip=args.trip,
+        seat=args.seat,
+        passengers=Passengers(adults=args.adults, children=args.children),
+        currency=args.currency,
+        language=args.language,
+        max_price=args.max_price,
+    )
+
+
+def total_duration(flight) -> int:
+    return sum(seg.duration for seg in flight.flights)
+
+
+def print_result(result: ResultList, currency: str = "") -> None:
+    if not result:
+        print("No flights found.")
+        return
+    sym = f"{currency} " if currency else "$"
+    for flight in result:
+        print(f"{sym}{flight.price}  {', '.join(flight.airlines)}  ({flight.type})")
+        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} "
+                  f"({seg.duration} min, {seg.plane_type})")
+    print(f"\n{len(result)} itinerary/ies")
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+
+    if args.text:
+        query = sys.stdin.read().strip()
+        if not query:
+            sys.exit("no text on stdin")
+        result = get_flights(query)
+    else:
+        query = build_query(args)
+        result = get_flights(query)
+
+    if args.sort == "price":
+        result.sort(key=lambda f: f.price)
+    elif args.sort == "duration":
+        result.sort(key=total_duration)
+    if args.limit:
+        result = result[: args.limit]
+
+    print_result(result, currency=args.currency)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except FlightsNotFound:
+        print("No flights found (Google returned an error/no results).")
+        raise SystemExit(1)

package/extensions/flight-search.ts

@@ -0,0 +1,174 @@
+/**
+ * Flight Search — a pi extension that registers a `search_flights` tool.
+ *
+ * The tool delegates to `flight_runner.py` (a small Python wrapper around the
+ * `fast-flights` Google Flights scraper) for deterministic, structured results:
+ * correct per-direction stop counts, no scratch scripts, no ad-hoc formatting.
+ *
+ * Install:
+ *   - python3 with `fast-flights` installed (the runner reports a clear error if not)
+ *   - symlink this file into your pi extensions dir so it auto-loads on /reload:
+ *       ln -s "$(pwd)/extensions/flight-search.ts" ~/.pi/agent/extensions/flight-search.ts
+ *
+ * The runner path is resolved in this order:
+ *   1. `FLIGHT_RUNNER` env var
+ *   2. `flight_runner.py` next to this file
+ *   3. default OSS folder: <repo>/flight_runner.py
+ */
+
+import { execFile } from "node:child_process";
+import { accessSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export function findRunner(): string {
+	const env = process.env.FLIGHT_RUNNER;
+	if (env) return env;
+
+	// __dirname is the dir the extension was LOADED from. If the extension is
+	// symlinked into ~/.pi/agent/extensions/, __dirname is that symlink dir, so
+	// resolve the real path of this module before looking for its neighbours.
+	let base = __dirname;
+	try {
+		base = dirname(realpathSync(__filename));
+	} catch {
+		/* fall back to __dirname */
+	}
+
+	// 1) flight_runner.py next to this file
+	const local = join(base, "flight_runner.py");
+	if (fileExists(local)) return local;
+	// 2) OSS project layout: <project>/flight_runner.py
+	const project = join(dirname(base), "flight_runner.py");
+	if (fileExists(project)) return project;
+	// 3) last resort: current working dir
+	return join(process.cwd(), "flight_runner.py");
+}
+
+function fileExists(p: string): boolean {
+	try {
+		accessSync(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function runPython(runner: string, python: string, payload: unknown, signal?: AbortSignal): Promise<string> {
+	return new Promise((resolvePromise, reject) => {
+		const child = execFile(
+			python,
+			[runner],
+			{
+				timeout: 120_000,
+				maxBuffer: 10 * 1024 * 1024,
+				signal,
+			},
+			(error, stdout, stderr) => {
+				if (error) {
+					reject(
+						new Error(
+							`flight search failed (${error.message})${stderr ? `: ${stderr.trim()}` : ""}`,
+						),
+					);
+					return;
+				}
+				resolvePromise(stdout);
+			},
+		);
+		child.stdin?.on("error", () => {}); // EPIPE if python exits early
+		child.stdin?.end(JSON.stringify(payload));
+	});
+}
+
+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.",
+	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.",
+		"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({
+		from_airport: Type.String({ description: "3-letter IATA departure airport code (e.g. 'IST')" }),
+		to_airport: Type.String({ description: "3-letter IATA arrival airport code (e.g. 'ECN')" }),
+		outbound_date: Type.String({ description: "Outbound departure date, YYYY-MM-DD" }),
+		trip: StringEnum(["one-way", "round-trip"] as const),
+		return_date: Type.Optional(
+			Type.String({ description: "Return date, YYYY-MM-DD — required when trip is round-trip" }),
+		),
+		seat: StringEnum(["economy", "premium-economy", "business", "first"] as const),
+		currency: Type.Optional(
+			Type.String({ description: "ISO currency code, e.g. EUR, USD, TRY. Omit for Google default." }),
+		),
+		language: Type.Optional(
+			Type.String({ description: "IETF language tag, e.g. en-US. Omit for Google default." }),
+		),
+		adults: Type.Optional(Type.Integer({ minimum: 0, maximum: 9 })),
+		children: Type.Optional(Type.Integer({ minimum: 0, maximum: 9 })),
+		max_stops: Type.Optional(Type.Integer({ minimum: 0 })),
+		max_price: Type.Optional(Type.Integer({ minimum: 0 })),
+		exclude_basic_economy: Type.Optional(Type.Boolean()),
+	}),
+
+	async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+		onUpdate?.({ content: [{ type: "text", text: "Searching flights…" }] });
+
+		if (params.trip === "round-trip" && !params.return_date) {
+			throw new Error("return_date is required when trip is 'round-trip'");
+		}
+
+		const runner = findRunner();
+		const python = process.env.FLIGHT_PYTHON ?? "python3";
+		const stdout = await runPython(runner, python, params, signal);
+
+		let data: unknown;
+		try {
+			data = JSON.parse(stdout);
+		} catch {
+			throw new Error(`flight search returned invalid JSON: ${stdout.slice(0, 300)}`);
+		}
+		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) {
+			return {
+				content: [{ type: "text", text: "No flights found for this search." }],
+				details: { currency: obj.currency, count: 0 },
+			};
+		}
+		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})`;
+
+		return {
+			content: [{ type: "text", text: summary }],
+			details: { currency: obj.currency, flights },
+		};
+	},
+};
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(search_flights);
+}

package/flight_runner.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Search Google Flights via fast-flights and emit structured JSON.
+
+This is the deterministic executor behind the pi `search_flights` extension
+tool (and usable standalone). It reads a JSON query object on stdin and writes
+a JSON result object on stdout.
+
+Query keys (all optional unless noted):
+  from_airport (required), to_airport (required)
+  outbound_date (required): "YYYY-MM-DD"
+  return_date: "YYYY-MM-DD" for round-trip
+  trip: "one-way" | "round-trip"
+  seat: economy | premium-economy | business | first
+  adults, children, infants_in_seat, infants_on_lap: int
+  currency: ISO code or "" (Google default)
+  language: IETF tag or ""
+  max_stops, max_price: int
+  carry_on_bags, checked_bags, hide_separate_and_self_transfer,
+  exclude_basic_economy: int/bool
+
+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...] }]
+
+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.
+
+Each leg: { "from": code, "from_name": str, "to": code, "to_name": str,
+            "date": "YYYY-MM-DD", "departure": "HH:MM", "arrival": "HH:MM",
+            "duration_minutes": int, "plane": str }
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from fast_flights import (
+    FlightsNotFound,
+    FlightQuery,
+    Passengers,
+    create_query,
+    get_flights,
+)
+
+SEATS = ("economy", "premium-economy", "business", "first")
+TRIPS = ("one-way", "round-trip")
+
+
+def _hhmm(t) -> str:
+    return f"{t[0]:02d}:{t[1]:02d}"
+
+
+def _leg(seg) -> dict:
+    return {
+        "from": seg.from_airport.code,
+        "from_name": seg.from_airport.name,
+        "to": seg.to_airport.code,
+        "to_name": seg.to_airport.name,
+        "date": "%04d-%02d-%02d" % seg.departure.date,
+        "departure": _hhmm(seg.departure.time),
+        "arrival": _hhmm(seg.arrival.time),
+        "duration_minutes": seg.duration,
+        "plane": seg.plane_type,
+    }
+
+
+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,
+        passengers=Passengers(
+            adults=int(q.get("adults", 1)),
+            children=int(q.get("children", 0)),
+            infants_in_seat=int(q.get("infants_in_seat", 0)),
+            infants_on_lap=int(q.get("infants_on_lap", 0)),
+        ),
+        currency=q.get("currency", ""),
+        language=q.get("language", ""),
+        max_stops=q.get("max_stops"),
+        max_price=q.get("max_price"),
+        carry_on_bags=int(q.get("carry_on_bags", 0)),
+        checked_bags=int(q.get("checked_bags", 0)),
+        hide_separate_and_self_transfer=bool(q.get("hide_separate_and_self_transfer", False)),
+        exclude_basic_economy=bool(q.get("exclude_basic_economy", False)),
+    )
+
+    try:
+        result = get_flights(query)
+    except FlightsNotFound:
+        return {"currency": q.get("currency", "") or "default", "flights": []}
+
+    currency = q.get("currency", "") or "default"
+    out = [
+        {
+            "price": f.price,
+            "currency": currency,
+            "is_round_trip": trip == "round-trip",
+            "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],
+        }
+        for f in result
+    ]
+    return {"currency": currency, "flights": out}
+
+
+def main() -> int:
+    try:
+        q = json.load(sys.stdin)
+        payload = run(q)
+    except Exception as e:  # noqa: BLE001 - report any failure to the caller
+        print(json.dumps({"error": str(e)}))
+        return 1
+    print(json.dumps(payload))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "find-flight",
+  "version": "0.1.0",
+  "description": "Google Flights search for agents — a pi extension (search_flights tool) + portable skill, powered by the fast-flights scraper.",
+  "keywords": [
+    "pi-package",
+    "flights",
+    "google-flights",
+    "travel",
+    "flight-search",
+    "fast-flights",
+    "trip"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fcan-dev/find-flight.git"
+  },
+  "homepage": "https://github.com/fcan-dev/find-flight#readme",
+  "bugs": {
+    "url": "https://github.com/fcan-dev/find-flight/issues"
+  },
+  "files": [
+    "extensions/",
+    "skills/",
+    "flight_runner.py",
+    "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\"",
+    "prepublishOnly": "npm run verify"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/skills/find-flight/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: find-flight
+description: Use when searching for flights, checking flight availability or prices, building flight queries, or booking research. Wraps the fast-flights Python library (Google Flights scraper) — structured queries via create_query/FlightQuery, natural-language queries, or returning ResultList flight data through get_flights.
+---
+
+# Flight Skill
+
+> Search Google Flights from Python using the **fast-flights** library. Build a query (structured or natural language), fetch results, and read `ResultList` flight data.
+
+## Overview
+
+`fast-flights` is a Python Google Flights scraper. An agent uses it by writing small Python programs: construct a search via `create_query` (or a plain sentence), call `get_flights`, and iterate the returned `ResultList`. Everything is strongly typed.
+
+```bash
+pip install fast-flights
+# deps pulled automatically: primp, protobuf>=5.27, selectolax  (Python >= 3.10)
+```
+
+## When to Use
+
+- Find flights/times/prices between airports for a date
+- Compare prices across dates, seats, or filter by stops/airlines/layovers
+- Travel-planning or trip-recommendation tasks that need real availability
+- Getting per-segment legs, durations, plane types, or carbon emissions
+
+**When NOT:** for booking/reservation actual purchase (this is read-only search), or non-flight transport.
+
+## Before you query (REQUIRED gate)
+
+**Never guess the date, the trip type, or the airport codes.** All three are common model failure points — resolve them *before* building any query:
+
+1. **Get the real current date from the system** — run `date` in a shell (or read the runtime clock), not from memory:
+   ```bash
+   date "+%Y-%m-%d"
+   ```
+   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.
+
+## Core Recipe — structured query
+
+```python
+from fast_flights import (
+    FlightQuery, Passengers, ResultList,
+    create_query, get_flights, FlightsNotFound,
+)
+
+query = create_query(
+    flights=[
+        FlightQuery(                       # one FlightQuery per leg
+            date="2025-01-01",             # "YYYY-MM-DD" or a datetime
+            from_airport="TPE",            # 3-letter IATA code
+            to_airport="MYJ",
+            max_stops=1,
+            airlines=["JL", "ONEWORLD"],   # IATA codes, or SKYTEAM/STAR_ALLIANCE/ONEWORLD
+            earliest_departure_hour=7,     # local time, 0-23
+            latest_departure_hour=18,
+            earliest_arrival_hour=10,
+            latest_arrival_hour=23,
+            max_duration_minutes=720,      # minutes
+            connecting_airports=["HND", "NRT"],
+            min_layover_minutes=60,
+            max_layover_minutes=240,
+            less_emissions_only=True,
+        ),
+    ],
+    seat="economy",                        # economy | premium-economy | business | first
+    trip="one-way",                        # one-way | round-trip (multi-city unimplemented)
+    passengers=Passengers(adults=1),       # adults/children/infants_in_seat/infants_on_lap
+    language="en-US",                      # "" lets Google decide
+    currency="USD",                        # "" lets Google decide
+    max_price=1500,                        # whole-search filters ↓
+    carry_on_bags=0,
+    checked_bags=0,
+    hide_separate_and_self_transfer=False,
+    exclude_basic_economy=False,
+)
+
+try:
+    result: ResultList = get_flights(query)
+    for flight in result:
+        print(flight.price, flight.airlines, flight.type)
+except FlightsNotFound:
+    print("no flights found")
+```
+
+### Round-trip example
+
+A round-trip is two `FlightQuery` legs in one `create_query` call — outbound then return (reverse airports, return date):
+
+```python
+query = create_query(
+    flights=[
+        FlightQuery(date="2025-01-01", from_airport="IST", to_airport="ECN"),
+        FlightQuery(date="2025-01-08", from_airport="ECN", to_airport="IST"),
+    ],
+    trip="round-trip",
+    seat="economy",
+    passengers=Passengers(adults=1),
+    currency="EUR",
+)
+```
+
+## Natural-language path (agent-friendly)
+
+`get_flights` also accepts a plain sentence instead of a `Query`:
+
+```python
+from fast_flights import get_flights
+result = get_flights(
+    "Flights from TPE to MYJ on 2025-01-01 one way economy class"
+)
+```
+
+Preferred when the request arrives as English text; use the structured recipe when the user gives discrete filters.
+
+## Reading results — the data model
+
+`ResultList` is a list of `Flights`, with metadata attached.
+
+```python
+result.metadata            # JsMetadata: .airlines[], .alliances[] (code+name)
+for flight in result:
+    # flight: Flights
+    flight.price           # int, in selected currency
+    flight.airlines        # list[str] of IATA codes
+    flight.type            # str | "multi"
+    flight.carbon          # CarbonEmission: .typical_on_route, .emission (grams)
+    for leg in flight.flights:     # SingleFlight
+        leg.from_airport   # Airport: .code, .name
+        leg.to_airport     # Airport: .code, .name
+        leg.departure      # SimpleDatetime: .date=(Y,M,D), .time=(H,M)
+        leg.arrival        # SimpleDatetime: .date=(Y,M,D), .time=(H,M)
+        leg.duration       # int, minutes
+        leg.plane_type     # str
+```
+
+**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.
+
+`FlightsNotFound` is raised when nothing matches (or Google returns an error status).
+
+### Sorting / narrowing results
+
+`ResultList` is a plain list.sort()-able list — sort by price or total duration before presenting to the user:
+
+```python
+def total_duration(flight):
+    return sum(seg.duration for seg in flight.flights)
+
+result.sort(key=lambda f: f.price)      # cheapest first
+result.sort(key=total_duration)          # shortest trip first
+best = result[0]                         # or result[:3] for top-N
+```
+
+## Options reference
+
+| Option | Where | Values / notes |
+|---|---|---|
+| `seat` | create_query | `economy`, `premium-economy`, `business`, `first` |
+| `trip` | create_query | `one-way`, `round-trip`. **round-trip needs 2+ `FlightQuery` legs**; `multi-city` unimplemented |
+| `passengers` | create_query | `Passengers(adults, children, infants_in_seat, infants_on_lap)` |
+| `language` / `currency` | create_query | any supported IETF tag / ISO code; `""` = Google default |
+| `max_price`, `carry_on_bags`, `checked_bags`, `hide_separate_and_self_transfer`, `exclude_basic_economy` | create_query | search-wide |
+| Per-leg filters | FlightQuery | `max_stops`, `airlines`, departure/arrival hour windows, `max_duration_minutes`, `connecting_airports`, `min/max_layover_minutes`, `less_emissions_only` |
+
+## Gotchas
+
+- **Hours use local airport time** on a 0–23 clock; durations/layovers are in minutes.
+- **`airlines` on non-first legs is ignored** — Google applies only the first leg's airline filter to the whole search. (The filter also accepts an alliance name.)
+- **`max_stops` can be passed once on `create_query`** as a global, and/or per-leg via `FlightQuery` (per-leg wins).
+- **Round-trip = two+ `FlightQuery` objects**; one way = one.
+- **Passengers rules:** total ≤ 9, and `infants_on_lap ≤ adults` (one lap infant needs one adult). Violations raise `AssertionError`.
+- **Read-only:** this scrapes availability; it cannot book. No guarantee against rate limits / IP blocks — proxy via an integration if scraping at scale.
+- **Live network dependency:** `get_flights` hits Google's servers at call time. For repeatable/offline testing, use `fetch_flights_html` or cached HTML, or an integration (BrightData / SearchApi).
+
+## Integrations (optional)
+
+- **BrightData** — proxy the default fetcher to protect your IP (pass `integration=BrightData(api_key=...)`). Only needed if scraping at scale.
+- **SearchApi** — richer data source. Returns `SearchApiResult` (booking options, price insights, amenities) instead of `ResultList`:
+  ```python
+  from fast_flights.integrations import SearchApi
+  result = get_flights(..., integration=SearchApi())
+  ```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Using `get_flights` without try/except | Wrap in `try/except FlightsNotFound` |
+| Round-trip with one leg | Add a second `FlightQuery` (e.g. return leg) |
+| 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 |
+| 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 |
+
+## 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.
+- **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.