duffel

Duffel Flight Booking

For a user-facing flight search or booking, first read /opt/hatch/skills/booking/SKILL.md, /opt/hatch/skills/booking/references/flights.md, and /opt/hatch/skills/booking/references/presentation.md. Those files define the discovery, privacy, presentation, and commitment rules. Use this file for the Duffel CLI contract. Do not emit HTML, call create_options, or duplicate flight choices in another widget; the native flight widget owns flight selection and uses the action chosen for the current flow.

Use only this public CLI surface:

search
seat-options
validate-booking
book
booking-status
cancellation-quote
cancel-booking

Do not invent identifiers, call undocumented endpoints, or expose off_, ord_, or ore_ ids to users. Do not show a Duffel command. Keep sensitive values out of chat unless the booking JSON, validate-booking, or book accepts them for the active checkout. Never request payment-card data or account credentials. Run each search command directly into a distinct temporary JSON file; do not pipe the search through head or a parser, which can hide errors or required offer data. After the direct search succeeds, a read-only command may inspect the saved JSON to group and rank offers, but it must not overwrite the file. Reuse the unchanged file for presentation. If an earlier search was piped, truncated, reduced, or overwritten, rerun the search directly into a new temporary JSON file and verify the complete response before presenting. A hand-built summary is not sufficient input for the required structured flight list.

Booking flow

1. Start by searching the complete itinerary and exact passenger mix together.
2. Present the shortlist through /opt/hatch/skills/booking/references/flights.md.
3. If Travel Planning delegated the search in planning only posture, return the selected itinerary to Travel Planning and stop. Do not continue into seats, traveler details, validation, or checkout until the posture changes to ready to book.
4. Optionally show seat-options and collect bookable seats.
5. Collect required passenger details and any loyalty account the user wants attached.
6. Let /opt/hatch/skills/booking/references/flights.md choose between the native path and the airline website. When it chooses the airline website, follow /opt/hatch/skills/booking/references/browser-booking.md. Recheck the itinerary and terms. Do not require the user to complete the checkout.
7. Otherwise continue through the supported native path without asking the user to choose an implementation provider. Run validate-booking until ready_to_book: true, select an exact returned Stripe Link payment method, and call book once with the same offer, booking document, and seats.
8. On success, report every carrier confirmation reference/PNR and ticket status. Do not add the Duffel name to the message. Any required provider attribution belongs to the provider-controlled approval or receipt surface.

Do not skip validation or silently change the selected offer, route, passenger mix, fare, or seats before booking.

Search and compare

Carry the requested cabin into every search with --cabin: economy, premium_economy, business, or first. The CLI defaults to economy when this flag is omitted. Before searching, check the complete dated itinerary, passenger mix, cabin, and any carrier constraints against the user's request.

duffel search --origin SFO --destination LAX --departure-date 2026-09-30 \
  --cabin business --sort duration --limit 300
duffel search --origin SFO --destination LAX --departure-date 2026-09-30 \
  --return-date 2026-10-04 --adults 2 --child-age 8 --lap-infants 1 --limit 300
duffel search --leg SFO:LAX:2026-09-30 --leg LAX:JFK:2026-10-03 --adults 2 \
  --limit 300
duffel search --origin SFO --destination LAX --departure-date 2026-09-30 \
  --max-connections 0 --sort duration --limit 300

Use --limit 300 for comparison searches so repeated fare variants from one carrier do not crowd plausible alternatives out of the inspected result set. If the CLI or provider returns a lower supported cap, use the complete result it returned and do not retry merely to reach 300. Present only the 3–6 most useful distinct offers. Start with every flight requested as one itinerary in the same search: use --return-date for a round trip and repeated --leg arguments for multi-city travel.

Treat each search as a live snapshot, not a price-monitoring loop. Reuse a complete saved response while its offers remain valid. Do not refresh an identical search in a shell loop or launch duplicate searches in the background. Continue the authorized search when it needs corrected arguments, another relevant itinerary, an expired-offer refresh, or recovery of missing output. These searches do not require another user message. A CAGI or provider 429 is terminal for the current task: stop Duffel calls and report the limit; do not change the query to bypass it.

For flexible dates or airports, choose the smallest useful set of distinct searches and run them sequentially. Inspect each result before expanding and show useful results as soon as they are available. Do not silently search the Cartesian product of every possible date and airport.

Use one search ordered by the user's stated priority; default to --sort duration when they give none. Do not automatically run separate duration, price, nonstop, and one-stop passes. Add or widen --max-connections only when the user requested that constraint or the first search produced no useful match. Run a targeted --airlines search when a requested, preferred, or credibly expected carrier is absent from the broad results, even when another carrier produced useful offers. A second sort is a separate live search, so run one only when the user's requested comparison genuinely requires it.

Before presenting, group the saved offers by complete itinerary signature: all segment airports, local timestamps, marketing and operating flight numbers, and segment order. Do not let repeated fare brands for one schedule consume the shortlist. Retain a distinct fare variant only when its cabin, baggage, refundability, changeability, or price creates a material user tradeoff.

Check carrier coverage after grouping. Use the user's preferences, the active travel-plan handoff, the response's carrier metadata when present, and verified route evidence to identify a materially relevant missing carrier. Search that carrier directly with --airlines before moving to Matrix or its website. If the targeted search still has no usable offer, follow the fallback in /opt/hatch/skills/booking/references/flights.md. Never conclude that Duffel does not support an airline, or that the airline does not fly the route, from its absence in one broad result set.

Use exact three-letter airport IATA codes, not metro codes such as NYC. Resolve unambiguous places, but confirm ambiguous dates or materially different airport choices. Do not guess an obscure or ambiguous code. Results are hard-filtered and nearby-airport inventory is excluded. When multiple airport pairs are acceptable, start with the preferred pair and expand to another pair only when requested or when the first search has no useful match; do not search every pair preemptively. An active travel-plan handoff that asks for the best option across named metro-area airports counts as an explicit request: search the smallest relevant set sequentially even if the first airport has a useful match. Zero results means only that the scanned Duffel inventory contained no match. For an exact-flight request, match the number in returned Duffel offers and do not substitute a different flight or use schedule data as proof it is bookable.

Passenger pricing is fixed at search:

• --adults is the adult count.
• Repeat --child-age for each seated traveler aged 2–17, using age on the itinerary's final travel date.
• --lap-infants counts travelers under two without a seat; each must have a different accompanying adult.

Ask for missing ages once. Ask whether an infant is seated or on a lap. Do not infer it. This integration cannot reliably book an infant under two in their own seat, so do not validate or pay for that case; direct it to the airline. Do not search a known child as an adult or claim a child will be repriced at booking. Search again whenever the passenger mix changes.

Prefer one combined Duffel offer and booking for the complete itinerary. If no combined offer contains every requested leg, or the user explicitly asks for separate tickets, split only with their agreement before the first book. Explain that each booking has its own confirmation, fare conditions, approval, and payment; later offers are not held while an earlier one is purchased, so a later failure can leave earlier tickets booked. Compare the combined total. Compare useful alternatives such as cheapest, fastest, nonstop, and explicitly refundable, and identify all legs and total party price. Treat native-provider inventory as one live source, not exhaustive coverage across every airline channel.

Present the shortlist with native flight rows through widget.create_list_widget. Read the Flights section in /opt/hatch/skills/booking/references/flights.md for complete-trip rows and presentation. For list creation, redirect each search to a distinct temporary JSON file. Check the exit status and inspect the saved response for errors and available offers before creating the list. Keep the saved output unchanged:

duffel search --origin SFO --destination JFK --departure-date 2026-10-14 \
  --return-date 2026-10-18 --adults 1 --limit 300 > /tmp/sfo-jfk-flights.json

Create one row per selected complete offer. Set its type to "flight" and its data to the file path and that offer's JSON pointer, for example:

{
  "flight_details_file": "/tmp/sfo-jfk-flights.json",
  "json_pointer": "/offers/0"
}

Use the original offer's zero-based index in /offers/<index>. Keep the file until widget.create_list_widget succeeds. Do not copy the offer JSON into the tool call, rewrite timestamps, remove fields, or generate a separate widget payload file. The runtime reads the selected object, maps timestamps, and stores the complete flight data. It does not retain the path or pointer. Keep all outbound, return and connecting segments in that one row. Show the whole offer price once. The server derives an identifying booking reply from those facts. For direct booking or a trip that is ready to book, omit the list-level flight_action and use the default booking CTA. For a Travel Planning handoff in planning only posture, set flight_action to {"cta_text":"Add to plan","response_message_prefix":"Add this flight to my trip plan:"} so selection returns the itinerary to the plan instead of implying checkout. Continue with the same complete offer id through validation and booking only after the flow advances to booking. Do not reinterpret a row tap as a request to buy only its first leg. Treat refundable and changeable as three-valued: yes, no, or not stated.

Fare brand, cabin, baggage, refundability, and changeability are optional provider facts. Preserve passenger/segment differences; render missing facts as “not stated.” Do not render missing facts as “none,” “not allowed,” or “non-refundable.” Airport-local times must not be timezone-converted without an explicit airport timezone. --refundable means refundable before departure with no stated positive penalty, not “cancel anytime.” Do not infer baggage or airline-standard fees.

After selection, use validate-booking's selected_offer as the canonical itinerary, price, baggage, and fare-condition snapshot.

Tracked fare monitoring

Use this flow when the user directly asks for ongoing monitoring of an already booked flight. Use this flow when the runtime hands off a validated automatic booking source for an upcoming flight. Treat either trigger as authorization to create the watch after the required booking facts are present. Do not ask whether to start monitoring after the runtime handoff. Do not require a connected email account. Ask the user only for booking facts that the requested monitoring needs and that the current context does not supply.

Collect the exact dated itinerary and passenger mix. Collect the booked cabin or fare family, included bags, and stop pattern. Collect the paid all-in total, booking currency, and known cancellation, change, or rebooking costs.

Search user goals and Tracking items for the trip. Use a matching user goal as the canonical owner. Otherwise, reuse a matching active Tracking item. If neither exists, create one Tracking item. Resolve the canonical owner before scheduling a job. Do not create a shadow trip, a price-tracker notebook entry, or a parallel tracking record. Keep confirmation references, ticket numbers, and connector identifiers out of user-visible goal text.

Store the minimum machine-readable fare state in ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json. Store the booking fingerprint, source fingerprints, traveler relationship and count, immutable booked itinerary, paid total, fare terms, current facts, last comparison, last-notified fingerprint, and cron identifiers. Use ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json only as goal-owned job state. Do not store full messages, raw connector output, names, ticket numbers, identity documents, contact data, payment data, loyalty numbers, Known Traveler Numbers, or CLEAR identifiers.

List the canonical owner's cron jobs before creating a fare job. Reuse an equivalent goal-owned fare job when one exists. If no equivalent job exists, add one fare job for the trip. Use flight-price-<goal-slug> as its identifier. Set its owner to goal:<goal-slug>. Schedule the ordinary check daily. Write a self-contained cron body because the cron worker receives neither this skill nor the surrounding conversation. Include the goal identifier, ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json, and the exact Duffel query. Include the comparison rules, alert thresholds, deduplication rule, failure behavior, and stop date. Record the cron identifier in ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json.

Run exactly one Duffel search during each fare cron run. Search the complete itinerary and passenger mix together with --limit 30. Do not use a browser or web search for repricing or retry a failed scheduled search; let the next scheduled run try again. Retain only results that match the booked dated flight numbers, airports, passenger count, cabin or fare family, included bags, stop pattern, and material refund or change restrictions. Compare a candidate only when its priced scope exactly matches the baseline's complete priced scope, including every outbound, return, or multi-city leg, dated segment identity, passenger mix, cabin or fare family, included bags, stop pattern, currency, and taxes or fees basis. Do not compare a one-way or single-leg offer with a round-trip or multi-leg paid total. Do not prorate a booking total across legs unless provider-authored line-item prices establish the exact segment amount. When priced scope is missing or mismatched, record the check as non-comparable in ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json. When priced scope is missing or mismatched, clear any pending candidate tied to that mismatch. When priced scope is missing or mismatched, keep the run silent unless degraded-coverage policy separately triggers. Compute actionable net savings after known cancellation, change, and rebooking costs.

Treat these baseline gaps as missing priced scope. When the booked fare family is not stated, a basic, light, saver, or otherwise more restrictive fare brand is never comparable. When the paid total includes seats, bags, or other extras, record them separately and compare fares only after removing them or adding the candidate's current price for the same extras. When the booking source does not establish whether the paid total covers every traveler, do not compare it.

When no pending candidate exists, persist the best threshold-crossing comparable candidate in ~/workspace/goals/<goal-slug>/hidden_files/travel/flight.json with comparable itinerary signature, total, currency, and check time. Do not notify the user for the first threshold-crossing candidate. Temporarily update the same fare cron to run once about one hour after the current run. When a pending candidate exists, run one Duffel search. Compare equivalent inventory against the pending candidate and booked facts. Confirm the pending candidate only when equivalent inventory still qualifies above either threshold. When the pending candidate is confirmed, continue to the persistence and notification rules below. Clear the pending candidate when equivalent inventory disappears, no longer matches the exact comparable criteria, or falls below both thresholds. Retain the pending candidate with a source-failure record when the confirmation search cannot complete because a source failed. Restore the same fare cron to daily cadence after a confirmed candidate, disconfirmed candidate, or source failure. Keep the run silent after a disconfirmed candidate or source failure unless degraded-coverage policy triggers.

Alert only when confirmed net savings exceed either 10 percent of the original paid total or the booking-currency equivalent of USD 100. Convert USD 100 with a fresh FX source. Record the FX source time. When reliable FX is unavailable, apply only the percentage threshold.

Before notifying, read the goal's recent Tracking activities for a later change to the booked itinerary, such as a rebooked leg or an added traveler. When the booking changed, update the baseline, clear the pending candidate, and keep the run silent.

Persist the comparison and stable alert fingerprint before notifying the user. Add one concise Tracking activity before notifying the user. State when the fare was confirmed and that fares can change before the user acts. Ask whether the user wants the main agent to investigate a credit, refund, or rebooking path. When the user accepts, run one fresh Duffel search before quoting savings. Treat the user's answer as authorization for investigation and preparation only. Do not cancel, rebook, contact a provider, accept terms, or spend money without the approval required for that action. Do not promise that a credit or refund will be granted.

Keep checks silent when no comparable result exists, the price is unchanged, or the movement stays below both thresholds. After three consecutive expected source failures, add a degraded-coverage activity to Tracking. Stop the fare job when the useful change or cancellation window closes, the trip is cancelled without a replacement, or the Tracking item is completed. Remove the fare job when the Tracking lifecycle ends.

Seats

Use seat-options only after shortlisting. It returns passenger-specific, bookable Duffel services; an omitted seat is unavailable, while $0.00 is a bookable seat with no added fee. Use row and section for adjacency. Seats on opposite sides of an aisle are not adjacent. Seat maps are carrier-dependent and inventory remains live.

Choose at most one seat per passenger per segment. Do not duplicate a seat. Pass every choice to validation and booking using the returned one-based passenger and segment numbers:

duffel validate-booking --offer-id off_… --booking-json '{...}' \
  --seat 1:1:28B --seat 2:1:28C

Passenger details

After offer selection, ask in chat for only the values required by the booking JSON or validation:

• each traveler's legal given/family name, birth date, title, and gender;
• one reachable trip email and phone, reusable for passengers when designated as their shared contact;
• the accompanying adult for each lap infant; and
• passport details only when validation requires them.

Use chat-supplied values only for this checkout; do not persist them elsewhere or repeat them to the user. Never request payment-card data or account credentials in chat.

Allowed titles are mr, ms, mrs, miss, and dr; gender is m or f. A required passport uses type: "passport", its number as unique_identifier, a two-letter uppercase issuing_country_code, and expires_on in YYYY-MM-DD. Do not send an empty document, invent identity data, or ticket an unborn traveler; explain that booking must wait until birth. Do not promise the same fare, availability, or adjacent seats later.

Mention loyalty once. If the user wants an account attached, collect its airline IATA code and account number in chat and add it to the matching passenger's loyalty_programme_accounts. Validation must confirm support and attachment; omit a failed account only with the user's agreement. Mention optional seat availability once without blocking.

Keep passengers in search order. Do not include Duffel passenger ids or fields owned by the CLI (id, infant_passenger_id, user_id, type, selected_offers, services, payment, or payments). The CLI assigns offer slots, validates age/type compatibility, and rejects other undocumented fields before checkout.

{
  "data": {
    "passengers": [{
      "given_name": "Legal given name",
      "family_name": "Legal family name",
      "born_on": "1990-01-01",
      "title": "ms",
      "gender": "f",
      "email": "trip-contact@example.com",
      "phone_number": "+14155550123",
      "loyalty_programme_accounts": [
        {"airline_iata_code": "UA", "account_number": "…"}
      ]
    }]
  }
}

For a lap infant, add "accompanying_adult": 1, using the adult's one-based position in the passenger array.

Validate before payment

duffel validate-booking --offer-id off_… --booking-json '{...}'

Validation refreshes the live offer and checks expiry/current total, passenger count/order/ages/types, required contacts and documents, lap-infant linkage, seats, and loyalty. It creates no Stripe request and has no HITL. Ask for every required_missing or invalid item together and rerun. Optional omissions do not block, but requested loyalty must not be silently discarded.

Before book, compare every selected_offer.slices[].from and .to with the chosen airports. Stop on any mismatch. Do not infer a route from search args, flight number, or city name.

A first booking may require the user's account email and legal name for a Duffel payment profile. This is not a passenger and is created internally only after purchase approval. When validation requests it, pass the same values to validation and booking:

duffel validate-booking --offer-id off_… --booking-json '{...}' \
  --customer-email owner@example.com \
  --customer-given-name Account --customer-family-name Owner

Book once

stripe-link payment-methods list --format json

duffel book --offer-id off_… --payment-method-id pm_… \
  --booking-json '{...}' --seat 1:1:28B --seat 2:1:28C \
  --customer-email owner@example.com \
  --customer-given-name Account --customer-family-name Owner

If Stripe Link is disconnected, explain the one-time virtual-card flow and provide its connection link. If the user cannot use that connection, an airline-site fallback is allowed only when its secure browser handoff or provider-owned payment surface actually renders for the user. Do not offer to receive a card number, expiry, security code, billing address, or other payment credential in chat. Do not transfer chat-supplied card data into the browser. If neither secure path is available, stop at the prepared itinerary, say payment is blocked, and provide the exact safe handoff; do not invent a chat-card workaround. Omit --customer-* when validation did not request them.

book refreshes and revalidates before any Stripe request. Its single approval covers the itinerary, passengers, seats/fees, fare conditions, total, optional first-time booking profile, one-time virtual card, 3DS, and immediate paid order. Do not use Duffel balance, held-order, inline-card, or separate order/payment flows.

The trusted approval must show compact passenger names, plus a separate lap-infant row with name, birth date, accompanying adult, and no seat; city and airport codes, flights, operating carriers, schedules, fare/cabin, selected seats, masked loyalty, baggage, refund/change conditions, price breakdown, and legal links. Label absent provider conditions as not stated.

After success, treat a requested loyalty account marked not_confirmed_on_order as unverified, not rejected: explain that the booking response did not confirm it, it may still be attached, and the user should check with the airline using the PNR and add it only if absent. Do not claim attachment failed solely because the response omitted it. Do not retry or rebook a successful order to repair loyalty.

Recovery

For a Stripe Link requires_action result, use only user_action.url as a link. Do not share or open an action_url inside provider_response.

Result	Action
Validation failure or expired offer before approval	Correct all fields together. If the offer expired, search again for the requested itinerary and present the fresh offer and terms for purchase approval. No spend exists.
requires_action with resolution: auto_resume	If user_action.kind is open_url, send one Markdown link with user_action.label as its text and user_action.url as its destination. Wait for the user to complete it, then rerun the identical book. If user_action is absent, stop and report the blocker.
requires_action with resolution: replacement_required	If user_action.kind is open_url, send one Markdown link with user_action.label as its text and user_action.url as its destination. Do not rerun book. After the user completes the action and asks to continue, start a fresh search and obtain new payment approval. If user_action is absent, stop and report the blocker.
requires_action without a recognized resolution	If user_action.kind is open_url, send one Markdown link with user_action.label as its text and user_action.url as its destination, then stop. Do not infer whether the existing request can resume. If user_action is absent, stop and report the blocker.
failed, terminal_status, or unsupported	Report the Stripe Link result and stop. Do not retry book or create another spend request.
Partially completed split booking	Stop. Report the successful bookings and PNRs plus every unpurchased leg. Do not buy a replacement or cancel anything without the user's explicit instruction.
Definitive native-provider rejection	Say no booking was created and the card was not captured; any temporary authorization will fall off on the issuer's schedule. Do not retry until the user explicitly requests a new attempt in a later message.
Timeout, 5xx, or ambiguous mutation	Do not claim success/failure or retry. Inspect booking-status; otherwise escalate.
Ambiguous customer-profile creation	No payment started; do not retry profile creation. Escalate for profile recovery.
Success with resource_authorization.persisted: false	Report the PNR/order and warn later management may be unavailable. Do not repeat the booking.

Identical offer plus normalized booking data form a resumable checkout identity. A newly searched offer is a new checkout and can create another authorization hold, so do not use it as an automatic retry.

Review, cancellation, and limits

duffel booking-status
duffel booking-status ord_…
duffel cancellation-quote ord_…
duffel cancel-booking ore_…

Without an id, booking-status lists locally authorized orders and can recover a lost order id. cancellation-quote does not cancel; report its exact known refund, destination, airline credits, and expiry. A null refund amount is unknown, not zero: say that the carrier did not provide a quote. cancel-booking re-checks the exact quote and asks once before the irreversible cancellation. Do not invent an unknown refund or fee.

Unsupported: paid bags or other services, partial-passenger cancellation, date/time or name changes, pets, unaccompanied-minor service, check-in, and boarding passes. Do not improvise with raw APIs; direct the user to the airline or support.

Approval rules

• No HITL: search, seat options, validation, booking status, cancellation quote.
• Exactly one HITL: native book, airline browser checkout, or cancellation. The airline browser checkout uses the same single purchase-approval boundary as book.
• Any change to flight, date, passengers, fare, services, or total requires a fresh purchase approval.
• Retry an unchanged failed search only when its response explicitly says retriable: true; stop on a CAGI or provider 429. Corrected searches, expired-offer refreshes, and missing-output recovery follow Search and compare. Scheduled fare checks keep their one-search-per-run rule. Other reads may be retried. Do not automatically retry an ambiguous mutation.