Flight Assist

This skill is an action router — pick the step that matches the user's intent and execute only that step. Do not run other steps; do not parallelize.

Available actions:

• Diagnose env (verify byAir + Google Maps credentials)
• Set home base (record the user's home address for time-to-leave)
• Handle a precheck wake cycle (reconcile managed calendar events, then compose a user-facing notification)

Step 1 — Diagnose env

Run the env-presence check (scripts/check-env.py relative to this skill; the NanoClaw runtime mounts every tessl__* skill at /home/node/.claude/skills/tessl__<skill-name>/, so the absolute path the agent must literally invoke is):

python3 /home/node/.claude/skills/tessl__flight-assist/scripts/check-env.py

The script reads BYAIR_MCP_URL and GOOGLE_MAPS_API_KEY, prints single-line JSON on stdout, exits 0.

Parse the JSON. All true: emit flight-assist credentials present. Any false: emit one line per missing variable:

• BYAIR_MCP_URL missing. Add personal MCP link from https://byairapp.com/mcp/ to OneCLI vault and restart container.
• GOOGLE_MAPS_API_KEY missing. Create a Distance Matrix API key at https://console.cloud.google.com/apis/credentials and add to OneCLI vault. Calendar access has no flag: OneCLI's gateway injects the Google OAuth Bearer on the wire, so no credential lives in this container and no env var gates it (nanoclaw#638). If the user is diagnosing calendar writes specifically, tell them to run the reconcile (Step 3) and read its error — gateway means the gateway is not authenticating the requests, tier means this agent's tier is gated from Google by design.

Finish here.

Step 2 — Set home base

When the user provides their home address (e.g., "set my home base to 1 Infinite Loop, Cupertino, CA"), invoke the set-home-base.py script to persist it to the plugin-wide config the precheck reads for time_to_leave queries as the fallback origin when no fresh live-location snapshot is available (see Step 3's time_to_leave row for the origin-resolution ladder). While a TripIt trip is active the precheck swaps the current trip lodging in for this address (trip_origin.py, #122) — the config value is the off-trip base, not a hard override.

python3 /home/node/.claude/skills/tessl__flight-assist/scripts/set-home-base.py "<address from user>"

The script writes the address to /workspace/state/flight-assist/config.json (atomic, idempotent), preserves any other config keys, and prints {"home_address": "..."} to stdout. Exit 0 on success, exit 2 on usage/validation failure.

Emit one confirmation line to the user: Home base set: <address>. Finish here.

Step 3 — Handle the precheck wake cycle

This step fires when the precheck script wakes the agent with a data.events payload. The wake cycle does two things in order: first reconcile the managed calendar events (deterministic glue, no LLM), then compose one human-readable notification per event.

First, run the calendar reconcile once per wake cycle, before composing notifications:

python3 /home/node/.claude/skills/tessl__flight-assist/scripts/reconcile.py

It converges the calendar to byAir truth — creates/shifts the boarding block, adopts and delta-shifts the byAir flight event, removes Reclaim travel blocks inside a same-airport layover gap, and tears down events for switched-away / cancelled flights that dropped out of the active-flights index. Every write is idempotent and a no-op when the calendar already matches, so it is safe to run on every wake cycle and alongside byAir's own delay-shifts. Airport drive blocks are no longer reconciled here — they are retired to the unified drive-engine (#156), which plans and applies them from its own sweep.

It prints single-line JSON: {"status": "...", "planned": N, "executed": N, "archived": N, "failed": [...], "airport_drive": {...}}. Output keys vary by status: byair_calendar_id and archived are present only when a cycle ran (ok / no_flights) and are omitted on no_calendar, so do not depend on a key that may be absent. status: "ok" means a cycle ran. no_calendar (no flight calendar resolved from config), no_flights (nothing tracked), or {"status": "error", "error": "gateway"} (the OneCLI gateway is not authenticating the requests) or {"status": "error", "error": "tier"} (this agent's tier is gated from Google by design) all mean reconciliation is inactive this cycle. The airport_drive object is now a fixed retired marker — {"status": "retired", "engine": "drive-engine"} — since airport drives moved to the unified drive-engine (#156); it is bookkeeping only, absent on the error exits. Treat a non-empty failed list (those ops retry next cycle) as expected: proceed to the notification below. Reconcile output is calendar bookkeeping, never a user-facing message — do not surface it; proceed silently regardless of its result.

Then compose the notification. Each event is {"flight_id": int, "event": {"reason": "...", ...}}. Compose one human-readable notification per event.

The full event-shape contract is in references/event-payloads.md; consult it when an event's reason is unfamiliar.

Phrase relative-date words ("today" / "tomorrow") against the operator's local date per rules/operator-local-tz-phrasing.md (run the core current-tz script, /home/node/.claude/skills/tessl__current-tz/scripts/read-current-tz.py). Displayed airport clock times stay as-is.

The reason → notification mapping for the documented events:

For each event, fetch the per-flight state to enrich the notification (gate, terminal, ETD, ETA) by invoking get-flight-state.py:

python3 /home/node/.claude/skills/tessl__flight-assist/scripts/get-flight-state.py <flight_id>

Outputs the full state record as single-line JSON on stdout, or {"error": "..."} when the flight has no state on disk. Use the last_snapshot.dep_gate, last_snapshot.arr_gate, dep_terminal, etc. to fill in the notification template. When a template names an airport, render it from last_snapshot.dep_airport_code/dep_airport_name / arr_airport_code/arr_airport_name — the resolved airport captured at poll time. Never free-type an airport name from a numeric id or from memory of the trip.

If multiple events share the same flight_id (e.g., gate_change + delay in one cycle), compose ONE notification per flight that merges them, ordered: cancel/divert first, then time-sensitive (boarding, time_to_leave), then info (gate, delay, inbound), then logistics (carousel, arrival).

After composing, route the notification through the user's main channel (the orchestrator handles routing; the skill just produces the message text).

If no actionable text would result for an event (e.g., a duplicate notification you've already sent within the last 10 min), proceed silently — do not echo "no notification needed". Finish here.