@curless/hotel-storefront 0.27.28 → 0.29.0

package/dist/tools.js

@@ -2,6 +2,7 @@ import { DEFAULT_PAGE, FULL_CAPABILITIES, LASTING_REQUESTS, MAX_PAGE, REQUEST_KI
 import { MAX_GUESTS, isDay, nights as nightsBetween } from './dates.js';
 import { FACILITIES } from './facilities.js';
 import { DESCRIPTION_MAX, POLICY_MAX, guestText, hotelText } from './fence.js';
+import { clockOf, minutesOf, startProblem, stayWords, windowWords } from './hourly.js';
 import { formatMoney, money, multiplyMoney, toMinor } from './money.js';
 import { MAX_COMPARED, MAX_CONS, MAX_DAYS, MAX_ITEMS_PER_DAY, MAX_MOMENTS, MAX_PROS, buildItinerary, candidatesFor, compareHotels, namesMoreThanOne, } from './present.js';
 import { regionOf } from './regions.js';
@@ -131,6 +132,46 @@ const forCapabilities = (tools, n, v, caps) => {
                 out = JSON.parse(JSON.stringify(out).replaceAll(' and add-ons', ''));
             }
         }
+        // ⚠️ ONLY WHERE THERE ARE ROOMS BY THE HOUR: a connector that sells none
+        // lists no parameter for them (总线程, 2026-10-12: inputs only gain
+        // optional parameters, the descriptions only say facts).
+        if (caps.hourly) {
+            const withProps = (schema, props) => {
+                const s = schema;
+                return { ...s, properties: { ...(s.properties ?? {}), ...props } };
+            };
+            if (t.name === n.getHotel)
+                out = {
+                    ...out,
+                    inputSchema: withProps(out.inputSchema, {
+                        hourly: {
+                            type: 'boolean',
+                            description: "Today's rooms by the hour, each priced for its hours. checkIn and checkOut are not used: rooms by the hour are sold for today only.",
+                        },
+                    }),
+                };
+            if (t.name === n.listHotels)
+                out = {
+                    ...out,
+                    inputSchema: withProps(out.inputSchema, {
+                        hourly: {
+                            type: 'boolean',
+                            description: `Only ${v.nounPlural} with a room by the hour today, each priced by its cheapest block.`,
+                        },
+                    }),
+                };
+            if (t.name === n.addToTrip)
+                out = {
+                    ...out,
+                    inputSchema: withProps(out.inputSchema, {
+                        startTime: {
+                            type: 'string',
+                            pattern: '^([01]?\\d|2[0-3]):[0-5]\\d$',
+                            description: 'For a room by the hour: when the guest arrives today, HH:MM, within the start times the room lists. The date is today; checkOut is not used.',
+                        },
+                    }),
+                };
+        }
         if (t.name === n.requestBooking) {
             if (caps.requiresPhone) {
                 const schema = out.inputSchema;
@@ -167,7 +208,9 @@ const forCapabilities = (tools, n, v, caps) => {
                     // itself: the instructions carried "test environment" while this
                     // line still promised "the hotel's own reservation" (2026-09-30).
                     description: v.sandbox
-                        ? `Makes a booking in a simulated copy of ${v.brand}'s booking system, for testing: each stay gets its own confirmation code there, and none of it is a ${v.brand} reservation or holds a real room. No payment is taken and no card is collected. All of the trip is booked or none of it. Preferences - a bed type, a floor, a late arrival - ride along on the booking as requests.`
+                        ? `Makes a booking in a simulated copy of ${v.brand}'s booking system, for testing: each stay gets its own confirmation code there, and none of it is a ${v.brand} reservation or holds a real room. ${caps.prepaid
+                            ? 'A rate marked paid in advance is booked on its own, and not at once: the answer gives a card page in test mode and the time it is paid by, and the stay is booked once it is paid - no card is collected here. Every other rate is paid by nobody.'
+                            : 'No payment is taken and no card is collected.'} All of the trip is booked or none of it. Preferences - a bed type, a floor, a late arrival - ride along on the booking as requests.`
                         : `Books the trip's rooms with ${v.brand} for a named guest: each stay becomes the hotel's own reservation, with its own confirmation code, paid at the hotel. No payment is taken here and no card is collected. All of the trip is booked or none of it. Preferences - a bed type, a floor, a late arrival - ride along on the booking as requests the desk tries to meet.`,
                 };
             }
@@ -823,13 +866,13 @@ const CHANGE_SCHEMA = {
  * policies, and every trip a member badge and saving (2026-10-05 audit) -
  * fields no answer there ever carries.
  */
-export const outputSchemasFor = (schemas, caps) => {
+export const outputSchemasFor = (schemas, caps, lang, also = {}) => {
     const gone = [
         ...(caps.members ? [] : ['member', 'memberSaving']),
         ...(caps.extras ? [] : ['extras']),
         ...(caps.policies === false ? ['policies'] : []),
     ];
-    if (!gone.length)
+    if (!gone.length && !caps.hourly && !lang && !also.logoDark && !also.accent)
         return schemas;
     return Object.fromEntries(Object.entries(schemas).map(([name, schema]) => {
         const s = schema;
@@ -838,6 +881,18 @@ export const outputSchemasFor = (schemas, caps) => {
         const properties = { ...s.properties };
         for (const k of gone)
             delete properties[k];
+        // On every answer, as `common` puts it: rooms by the hour are sold here.
+        if (caps.hourly)
+            properties.hourly = BOOL;
+        // On every answer too: the language the card draws its own words in.
+        if (lang)
+            properties.lang = { enum: ['zh', 'en'] };
+        // And the dark page's logo, where the group gave one.
+        if (also.logoDark)
+            properties.logoDarkUrl = STR;
+        // And the group's own colour, where its deployment gives one.
+        if (also.accent)
+            properties.accent = { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' };
         return [name, { ...s, properties }];
     }));
 };
@@ -1145,7 +1200,48 @@ const holderOf = (deps, supplier) => {
  * room - and a booking whose confirmation has not come back yet is neither,
  * and is said as exactly that.
  */
+/**
+ * A booking as the card is given it: its money as strings, like every other
+ * price - the card never does arithmetic, and an amount sent as
+ * `{ minor, currency }` was drawn as "[object Object]" (香格里拉, 2026-10-12).
+ */
+const bookingForCard = (b) => ({
+    ...b,
+    quote: quoteForCard(b.quote),
+    ...(b.payment ? { payment: { ...b.payment, amount: formatMoney(b.payment.amount) } } : {}),
+});
+/**
+ * A booking paid here in advance, as the guest is told it - by where its
+ * money stands. Undefined for any other booking.
+ */
+const paidLine = (deps, b) => {
+    const p = b.payment;
+    if (!p)
+        return undefined;
+    const h = holderOf(deps, b.supplier);
+    const amount = formatMoney(p.amount);
+    const test = h.sandbox
+        ? ' This is a test: the card page is in test mode, no real money moves, and the booking is in the simulated system.'
+        : '';
+    switch (p.status) {
+        case 'awaiting':
+            return `**Not booked yet, and nothing paid.** ${amount} is paid on the card page by ${p.payByLocal ?? p.payBy} hotel time: ${p.url}. Once it is paid the stay is booked with ${h.name}, and ${deps.tools.listBookings} shows it; unpaid by then, the page closes and nothing is booked or charged.${test}`;
+        case 'paid':
+            return b.status === 'confirmed'
+                ? `${amount} paid in advance by card, and booked with ${h.name}: nothing more is paid at the hotel.${test}`
+                : `${amount} paid in advance by card. ${h.name} has not confirmed the booking yet - ${deps.tools.listBookings} shows when it has; if it does not take it, all ${amount} goes back.${test}`;
+        case 'lapsed':
+            return `Not paid in time: nothing was booked and nothing was charged.${test}`;
+        case 'refunding':
+            return `All ${amount} is going back to the card it was paid with${p.refundReason ? ` - ${p.refundReason}` : ''}.${test}`;
+        case 'refunded':
+            return `All ${amount} has gone back to the card it was paid with${p.refundReason ? ` - ${p.refundReason}` : ''}.${test}`;
+    }
+};
 const bookedLine = (deps, b) => {
+    const paid = paidLine(deps, b);
+    if (paid)
+        return paid;
     const total = formatMoney(b.quote.total);
     const h = holderOf(deps, b.supplier);
     if (h.caps.booking === 'pay-at-hotel') {
@@ -1180,6 +1276,8 @@ const common = (deps, key) => {
     return {
         brand: deps.vocab.brand,
         ...(deps.logoUrl ? { logoUrl: deps.logoUrl } : {}),
+        ...(deps.logoDarkUrl ? { logoDarkUrl: deps.logoDarkUrl } : {}),
+        ...(deps.accent ? { accent: deps.accent } : {}),
         ...(deps.showName ? { showName: true } : {}),
         toolNames: deps.offered
             ? Object.fromEntries(Object.entries(deps.tools).filter(([, name]) => deps.offered?.has(name)))
@@ -1190,6 +1288,10 @@ const common = (deps, key) => {
         ...(deps.vocab.sandbox ? { sandbox: true } : {}),
         ...(caps.programme ? { programme: caps.programme } : {}),
         ...(caps.codePrefix ? { codePrefix: caps.codePrefix } : {}),
+        // Sells rooms by the hour: the card draws its Overnight / By the hour
+        // switch only then - it sees answers, never the tools' parameters (香格里拉,
+        // 2026-10-12).
+        ...(caps.hourly ? { hourly: true } : {}),
         // A market: the card draws each hotel and booking as its group's.
         ...(deps.backend.suppliers
             ? { market: { name: deps.vocab.brand, suppliers: deps.backend.suppliers() } }
@@ -1197,8 +1299,19 @@ const common = (deps, key) => {
         vocab: { noun: deps.vocab.noun, nounPlural: deps.vocab.nounPlural },
         ...(deps.vocab.demo ? { demo: true, demoNote: DEMO_NOTE } : { demo: false }),
         ...(key ? memberBadge(deps, key) : {}),
+        ...(langOf(deps, key) ? { lang: langOf(deps, key) } : {}),
     };
 };
+/**
+ * The language the CARD speaks to this guest - its own buttons, labels and
+ * dates. What the server writes for the model stays English.
+ *
+ * ⚠️ PER TRIP, NOT ONLY PER BRAND (总线程, 2026-10-12): today it is the
+ * deployment's (Huazhu's single store is Chinese), and a guest's own choice -
+ * as the market's \`set_language\` keeps one per buyer - is meant to come in
+ * HERE, by \`key\`, without the card or the schema changing.
+ */
+const langOf = (deps, _key) => deps.lang;
 /**
  * When a room stops being free to cancel, the way a guest reads it: the
  * hotel's own clock when the backend knows it, else the instant in UTC - never
@@ -1220,6 +1333,7 @@ const quoteForCard = (quote, groupOf) => ({
         detail: l.detail,
         stay: l.stay,
         nights: l.nights,
+        ...(l.hourly ? { hourly: l.hourly } : {}),
         quantity: l.quantity,
         // How many were ORDERED, beside how many units that comes to: one extra
         // bed over three nights is quantity 3 and ordered 1, and the card's
@@ -1229,6 +1343,12 @@ const quoteForCard = (quote, groupOf) => ({
         total: formatMoney(l.total),
         refundable: l.refundable,
         freeCancellationUntil: l.freeCancellationUntil,
+        // The deadline on the hotel's clock, where the backend knows it - the
+        // review restates the terms beside the total (round-2 jury).
+        ...(l.freeCancellationLocal ? { freeCancellationLocal: l.freeCancellationLocal } : {}),
+        // Paid in advance: the review says so, and its button leads to the
+        // payment page rather than to a booking (香格里拉's card, 2026-10-12).
+        ...(l.payment ? { payment: l.payment } : {}),
         day: l.day,
     })),
     subtotal: formatMoney(quote.subtotal),
@@ -1247,7 +1367,7 @@ const tripText = (quote, demo) => {
     if (quote.lines.length === 0)
         return 'The trip is empty.';
     const lines = quote.lines.map((l) => l.kind === 'room'
-        ? `- ${l.quantity ?? 1}× ${l.title} at ${l.hotelName}, ${l.stay?.checkIn} to ${l.stay?.checkOut} (${l.nights} ${l.nights === 1 ? 'night' : 'nights'}) — ${formatMoney(l.total)}`
+        ? `- ${l.quantity ?? 1}× ${l.title} at ${l.hotelName}, ${l.hourly ? stayWords(l.stay, l.hourly) : `${stayWords(l.stay)} (${l.nights} ${l.nights === 1 ? 'night' : 'nights'})`} — ${formatMoney(l.total)}`
         : `- ${l.ordered ?? l.quantity}× ${l.title}${l.ordered !== undefined && l.quantity !== undefined && l.quantity !== l.ordered ? ` (${l.quantity} in all, over the stay)` : ''} — ${formatMoney(l.total)}`);
     return [
         ...lines,
@@ -1456,15 +1576,61 @@ const planGap = (plan) => {
         ? `${parts.join(', ')}; the rest are a plan, not a booking.`
         : `${parts.join(', ')}.`;
 };
+/** How many people, for a room by the hour asked for without dates. Default 2. */
+const guestsOf = (args) => Math.max(1, Math.min(MAX_GUESTS, Math.floor(Number(args.guests) || 2)));
+/**
+ * "3 room types", or - where a group sells several rates on one type - "5 rates
+ * on 2 room types": five rows are not five kinds of room.
+ */
+const offerCount = (rooms) => {
+    const types = new Set(rooms.map((r) => r.roomType?.id ?? r.id)).size;
+    return types === rooms.length
+        ? `${types} room ${types === 1 ? 'type' : 'types'}`
+        : `${rooms.length} rates on ${types} room ${types === 1 ? 'type' : 'types'}`;
+};
+/** What one room costs, as the text says it: nights, or the hours of a room by the hour. */
+const priceWords = (r) => r.hourly
+    ? `${formatMoney(r.stayTotal)} for ${r.hourly.hours} hours incl. taxes and fees, starting between ${r.hourly.earliestStart} and ${r.hourly.latestStart} today and out by ${r.hourly.latestEnd}`
+    : `${formatMoney(r.nightly)} a night, ${formatMoney(r.stayTotal)} for the stay incl. taxes and fees`;
+const LABEL_WORDS = {
+    'room-only': 'room only',
+    breakfast: 'breakfast',
+    'breakfast-1': 'breakfast for 1',
+    'breakfast-2': 'breakfast for 2',
+    'breakfast-3': 'breakfast for 3',
+    package: 'package',
+    'flash-sale': 'flash sale',
+    'night-snack': 'late-night rate',
+    'early-booking': 'booked-ahead rate',
+    promotion: 'promotion',
+};
+/** A rate's labels after its name - " [breakfast for 2, promotion]" - or nothing. */
+const labelWords = (r) => {
+    const words = [
+        ...(r.labels ?? []).map((l) => LABEL_WORDS[l]),
+        ...(r.payment === 'prepaid' ? ['paid in advance'] : []),
+    ];
+    return words.length ? ` [${words.join(', ')}]` : '';
+};
+const PAYMENT_WORDS = {
+    awaiting: 'to be paid on the card page',
+    paid: 'paid in advance by card',
+    lapsed: 'not paid in time - nothing booked or charged',
+    refunding: 'refund in full under way',
+    refunded: 'refunded in full',
+};
 const bookingLine = (b) => {
     const kinds = b.requests?.kinds ?? [];
     return [
-        `${b.confirmationCode} · ${b.hotelName} · ${b.stay.checkIn} to ${b.stay.checkOut} · ${
+        `${b.confirmationCode} · ${b.hotelName} · ${stayWords(b.stay, b.hourly)} · ${
         // ⚠️ SAID AS WHAT IT IS - see BookingStatus. Neither booked nor failed.
         b.status === 'unconfirmed'
             ? 'unconfirmed: whether it was made is not known yet, and a person is confirming it'
             : b.status}`,
         kinds.length ? ` · asked for ${kinds.map(bare).join(', ')}` : '',
+        b.payment
+            ? ` · ${PAYMENT_WORDS[b.payment.status]}${b.payment.status === 'awaiting' && b.payment.url ? ` by ${b.payment.payByLocal ?? b.payment.payBy}: ${b.payment.url}` : ''}`
+            : '',
     ].join('');
 };
 /**
@@ -1509,6 +1675,13 @@ const dateFlex = (dates, stay) => {
     // the other two are worse, which is a claim about prices that are equal.
     const beats = best?.from && chosen?.from && best.from.minor < chosen.from.minor ? best : undefined;
     const beatsBy = beats?.from?.minor;
+    // The cheapest of the window - the chosen date too - when two or more are
+    // priced in one currency; ties all marked. `best` stays what it was: a date
+    // that beats the guest's own.
+    const priced = dates.filter((d) => d.from);
+    const lowest = priced.length >= 2 && new Set(priced.map((d) => d.from?.currency)).size === 1
+        ? Math.min(...priced.map((d) => d.from?.minor ?? Number.POSITIVE_INFINITY))
+        : undefined;
     const structured = {
         dates: dates.map((d) => ({
             checkIn: d.checkIn,
@@ -1517,6 +1690,7 @@ const dateFlex = (dates, stay) => {
             ...(d.chosen ? { chosen: true } : {}),
             // The chosen date cannot match: `beatsBy` is a price strictly below it.
             ...(beatsBy !== undefined && d.from?.minor === beatsBy ? { best: true } : {}),
+            ...(lowest !== undefined && d.from?.minor === lowest ? { lowest: true } : {}),
         })),
     };
     if (!best?.from)
@@ -1814,6 +1988,7 @@ const filtersOf = (args) => {
         ...(facilities.length ? { facilities } : {}),
         ...(args.freeCancellation === true ? { freeCancellation: true } : {}),
         ...(args.breakfast === true ? { breakfast: true } : {}),
+        ...(args.hourly === true ? { hourly: true } : {}),
     };
     return Object.keys(f).length ? f : undefined;
 };
@@ -1823,6 +1998,7 @@ const filterWords = (f) => [
     ...(f.facilities ?? []).map((k) => FACILITIES.find((x) => x.key === k)?.label.toLowerCase()),
     f.freeCancellation ? 'free cancellation' : '',
     f.breakfast ? 'breakfast included' : '',
+    f.hourly ? 'rooms by the hour today' : '',
 ]
     .filter(Boolean)
     .join(', ');
@@ -2347,8 +2523,19 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
                     .join(' '),
             };
         }
+        // ⚠️ THE CHEAPEST, SAID BY US - the card never compares two prices it was
+        // handed as text. Only on named nights, in one currency, with two or more
+        // priced to compare; every hotel that ties is marked (总线程, 2026-10-12).
+        // A room by the hour is priced for its own hours, and is not in the race.
+        const stays = hotels.filter((h) => h.forStay && !h.forStay.hours);
+        const lowest = stays.length >= 2 && new Set(stays.map((h) => h.forStay?.total.currency)).size === 1
+            ? Math.min(...stays.map((h) => h.forStay?.total.minor ?? Number.POSITIVE_INFINITY))
+            : undefined;
         const forCard = hotels.map((h) => ({
             ...h,
+            ...(lowest !== undefined && h.forStay && !h.forStay.hours && h.forStay.total.minor === lowest
+                ? { lowest: true }
+                : {}),
             summary: hotelText('description', h.name, h.summary, DESCRIPTION_MAX).text,
             fromNightly: h.fromNightly ? formatMoney(h.fromNightly) : undefined,
             ...(h.forStay
@@ -2390,11 +2577,13 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
             filtersSaid && filterWords(filtersSaid) ? `Filtered to ${filterWords(filtersSaid)}.` : '',
             // What the prices on a dated list are, in one line - and how many cannot
             // be had at all, so a sold-out hotel is not described as a choice.
-            ask.stay
-                ? `Priced for ${ask.stay.checkIn} to ${ask.stay.checkOut}${ask.rooms && ask.rooms > 1 ? `, ${ask.rooms} rooms` : ''}: each price is that ${deps.vocab.noun}'s cheapest room for the whole stay, taxes included${hotels.some((h) => h.noRoomsForStay)
-                    ? `; ${hotels.filter((h) => h.noRoomsForStay).length} in this answer have no room for those nights`
-                    : ''}.`
-                : '',
+            ask.filters?.hourly && hotels.some((h) => h.forStay?.hours)
+                ? `By the hour, today: each price is that ${deps.vocab.noun}'s cheapest room by the hour, for its hours, taxes included.`
+                : ask.stay
+                    ? `Priced for ${ask.stay.checkIn} to ${ask.stay.checkOut}${ask.rooms && ask.rooms > 1 ? `, ${ask.rooms} rooms` : ''}: each price is that ${deps.vocab.noun}'s cheapest room for the whole stay, taxes included${hotels.some((h) => h.noRoomsForStay)
+                        ? `; ${hotels.filter((h) => h.noRoomsForStay).length} in this answer have no room for those nights`
+                        : ''}.`
+                    : '',
         ].filter(Boolean);
         return {
             structured: {
@@ -2437,9 +2626,13 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
     }
     if (name === t.getHotel) {
         const wanted = str(args.hotel);
-        const stay = asStay(args);
         const who = identity(deps, ctx, key);
-        const detail = await deps.backend.getHotel(wanted, stay, who);
+        // Today's rooms by the hour, on the hotel's own date - see `hourlyRooms`.
+        const byTheHour = args.hourly === true && !!deps.backend.hourlyRooms;
+        const detail = byTheHour
+            ? await deps.backend.hourlyRooms?.(wanted, guestsOf(args), who)
+            : await deps.backend.getHotel(wanted, asStay(args), who);
+        const stay = byTheHour ? detail?.stay : asStay(args);
         if (!detail) {
             const candidates = candidatesFor(deps.backend, wanted);
             return {
@@ -2488,7 +2681,8 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
         // for the two reasons a different arrival cannot fix - the dates are not
         // bookable at all, or no room type here sleeps this party - and offering a
         // week of alternatives to either is noise dressed as help.
-        const dates = detail.rooms
+        // Other arrival dates mean nothing to a room sold for today only.
+        const dates = detail.rooms && !byTheHour
             ? await deps.backend.datesAround(h.id, stay, { rooms: roomsWanted, span: 3 }, who)
             : [];
         const flex = dateFlex(dates, stay);
@@ -2562,8 +2756,10 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
                 ...flex.structured,
             },
             text: [
-                `**${h.name}** · ${enough.length} room ${enough.length === 1 ? 'type' : 'types'} for ${stay.checkIn} to ${stay.checkOut}, ${stay.guests} guests${roomsWanted > 1 ? `, ${roomsWanted} rooms` : ''}.`,
-                ...enough.map((r) => `- ${r.name} — ${formatMoney(r.nightly)} a night, ${formatMoney(r.stayTotal)} for the stay incl. taxes and fees${roomsWanted > 1 ? ` (${formatMoney(multiplyMoney(r.stayTotal, roomsWanted))} for ${roomsWanted} rooms)` : ''}${r.freeCancellationUntil ? `, free to cancel until ${freeUntilText(r)}` : r.refundable ? ', the free cancellation window has closed - cancelling now has a fee' : ', non-refundable'}`),
+                byTheHour
+                    ? `**${h.name}** · ${enough.length} ${enough.length === 1 ? 'room' : 'rooms'} by the hour for today, ${stay.checkIn}, ${stay.guests} guests.`
+                    : `**${h.name}** · ${offerCount(enough)} for ${stay.checkIn} to ${stay.checkOut}, ${stay.guests} guests${roomsWanted > 1 ? `, ${roomsWanted} rooms` : ''}.`,
+                ...enough.map((r) => `- ${r.name}${labelWords(r)} — ${priceWords(r)}${roomsWanted > 1 ? ` (${formatMoney(multiplyMoney(r.stayTotal, roomsWanted))} for ${roomsWanted} rooms)` : ''}${r.freeCancellationUntil ? `, free to cancel until ${freeUntilText(r)}` : r.refundable ? ', the free cancellation window has closed - cancelling now has a fee' : ', non-refundable'}`),
                 flex.text,
                 deps.vocab.demo ? DEMO_NOTE : '',
             ]
@@ -2840,19 +3036,80 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
                 text: `Say which room type, or which add-on. ${t.getHotel} with the dates lists the room types.`,
             };
         }
+        // A room by the hour: today, from the start the guest gave - checked here,
+        // against the starts the room takes, and never moved to fit (总线程,
+        // 2026-10-12).
+        const who = identity(deps, ctx, key);
+        const startTime = str(args.startTime);
+        const today = (startTime || !asStay(args)
+            ? deps.backend.hourlyRooms?.(hotelId, guestsOf(args), who)
+            : undefined);
+        const byTheHour = async () => (await today)?.rooms?.find((r) => r.hourly && (r.id === roomRef || r.name.toLowerCase() === roomRef.toLowerCase()));
+        if (startTime && deps.backend.hourlyRooms) {
+            const hourlyRoom = await byTheHour();
+            if (!hourlyRoom?.hourly) {
+                const sold = ((await today)?.rooms ?? []).filter((r) => r.hourly);
+                return {
+                    structured: {
+                        view: 'error',
+                        ...common(deps, key),
+                        error: 'no-such-room',
+                        query: roomRef,
+                        rooms: sold.map((r) => ({ id: r.id, name: r.name })),
+                    },
+                    text: sold.length
+                        ? `${detail.hotel.name} has no room by the hour by that name today. It has: ${sold.map((r) => `${r.name} (\`${r.id}\`, ${windowWords(r.hourly)})`).join('; ')}.`
+                        : ((await today)?.noRooms ?? `${detail.hotel.name} has no rooms by the hour today.`),
+                };
+            }
+            const bad = startProblem(hourlyRoom.hourly, startTime);
+            if (bad) {
+                return {
+                    structured: {
+                        view: 'error',
+                        ...common(deps, key),
+                        error: 'start-time',
+                        query: startTime,
+                        // The starts it does take. Not `hourly`: that is the flag above.
+                        window: hourlyRoom.hourly,
+                    },
+                    text: bad,
+                };
+            }
+            deps.trips.set(key, {
+                kind: 'room',
+                hotelId,
+                roomId: hourlyRoom.id,
+                stay: {
+                    checkIn: hourlyRoom.hourly.date,
+                    checkOut: hourlyRoom.hourly.date,
+                    guests: guestsOf(args),
+                },
+                rooms: clampCount(args.rooms ?? 1, MAX_ROOMS_PER_LINE),
+                hourly: {
+                    start: clockOf(minutesOf(startTime)),
+                    hours: hourlyRoom.hourly.hours,
+                },
+            });
+            return currentTrip(deps, key, who);
+        }
         const stay = asStay(args);
         // ⚠️ NO DATES, NO LINE. Guessing "tonight" or "this weekend" here is how a
         // connector books someone the wrong nights, and the guest finds out at the
         // desk. The trip stays as it was and the answer asks.
         if (!stay) {
+            const hourlyRoom = await byTheHour();
             return {
                 structured: {
                     view: 'needs-dates',
                     ...common(deps, key),
                     hotel: detail.hotel,
                     room: roomRef,
+                    ...(hourlyRoom?.hourly ? { window: hourlyRoom.hourly } : {}),
                 },
-                text: 'Which nights? A room needs a check-in and a check-out date before it can go into the trip.',
+                text: hourlyRoom?.hourly
+                    ? `That is a room by the hour, sold for today: it takes \`startTime\` - ${windowWords(hourlyRoom.hourly)}.`
+                    : 'Which nights? A room needs a check-in and a check-out date before it can go into the trip.',
             };
         }
         // The backend owns the calendar - it knows each hotel's own timezone, and a
@@ -2880,6 +3137,10 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
                     error: 'no-such-room',
                     query: roomRef,
                     rooms: dated.rooms.map((r) => ({ id: r.id, name: r.name })),
+                    // The hotel and the nights, so the card can take the guest straight
+                    // back to its rooms rather than to the start (round-2 jury).
+                    hotel: { id: detail.hotel.id, name: detail.hotel.name },
+                    stay,
                 },
                 text: `${detail.hotel.name} has no room type by that name for those nights. It has: ${dated.rooms.map((r) => r.name).join(', ')}.`,
             };
@@ -3035,16 +3296,20 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
             const several = booked.length > 1;
             return {
                 structured: {
+                    // ⚠️ 'booking' EVEN WHEN IT IS AWAITING PAYMENT: the card draws a view
+                    // only once it knows it, and the card-contract test holds every view
+                    // here to that. 香格里拉's card turns this into its own 'payment' step
+                    // (booking.status 'awaiting-payment', booking.payment) - and moves the
+                    // view with it.
                     view: 'booking',
                     ...common(deps, key),
-                    booking: { ...first.booking, quote: quoteForCard(first.booking.quote) },
+                    booking: bookingForCard(first.booking),
                     // ⚠️ ONE PER STAY - see `requestBooking`. The card draws each with its
                     // own code; `booking` stays the first, for a host that reads one.
                     ...(several
                         ? {
                             bookings: booked.map(({ booking, asked }) => ({
-                                ...booking,
-                                quote: quoteForCard(booking.quote),
+                                ...bookingForCard(booking),
                                 total: formatMoney(booking.quote.total),
                                 ...(asked.length ? { requested: asked } : {}),
                                 // Each its own warning colour - it rode on the first alone.
@@ -3068,7 +3333,7 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
                         ? `${booked.length} bookings, one for each stay - each hotel keeps its own nights under its own code, and each is ${holderOf(deps, first.booking.supplier).caps.changes ? 'changed or cancelled' : 'cancelled'} on its own.`
                         : '',
                     ...booked.flatMap(({ booking, asked }) => [
-                        `**${booking.confirmationCode}** · ${booking.hotelName} · ${booking.stay.checkIn} to ${booking.stay.checkOut}`,
+                        `**${booking.confirmationCode}** · ${booking.hotelName} · ${stayWords(booking.stay, booking.hourly)}`,
                         bookedLine(deps, booking),
                         ...asked,
                     ]),
@@ -3133,7 +3398,7 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
             structured: {
                 view: 'bookings',
                 ...common(deps, key),
-                bookings: bookings.map((b) => ({ ...b, quote: quoteForCard(b.quote) })),
+                bookings: bookings.map(bookingForCard),
                 count: bookings.length,
                 // What was looked for, so a card can say THAT did not match rather
                 // than "nothing in this conversation".
@@ -3267,7 +3532,7 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
                 structured: {
                     view: 'changed',
                     ...common(deps, key),
-                    booking: { ...changed, quote: quoteForCard(changed.quote) },
+                    booking: bookingForCard(changed),
                     hotelName: preview.hotelName,
                     from: stayOf(preview.from),
                     ...(preview.to ? { to: stayOf(preview.to) } : {}),
@@ -3368,19 +3633,22 @@ const answerTool = async (deps, name, rawArgs, ctx) => {
             structured: {
                 view: 'cancelled',
                 ...common(deps, key),
-                booking: { ...cancelled, quote: quoteForCard(cancelled.quote) },
+                booking: bookingForCard(cancelled),
                 fee: formatMoney(charged),
                 rule: preview.rule,
                 cancellable: false,
             },
             text: [
-                h.sandbox
-                    ? // A test booking cancelled in the simulation: no hotel, no charge (2026-10-05 audit, P2).
-                        `${cancelled.confirmationCode} is cancelled in the simulated system. ${charged.minor === 0 ? 'No fee.' : `A real booking on this rate would be charged ${formatMoney(charged)}; this one is a test, and nothing is charged.`}`
-                    : h.demo
-                        ? // Nobody charges a demonstration anything (2026-10-05 audit, P2).
-                            `${cancelled.confirmationCode} is cancelled. ${charged.minor === 0 ? 'No fee.' : `A real booking on this rate would be charged ${formatMoney(charged)}; this is a demonstration, and nothing is charged.`}`
-                        : `${cancelled.confirmationCode} is cancelled. ${charged.minor === 0 ? 'No fee.' : `The hotel charges ${formatMoney(charged)}.`}`,
+                cancelled.payment
+                    ? // Paid here in advance: what becomes of the money is the answer.
+                        `${cancelled.confirmationCode} is ${cancelled.status === 'expired' ? 'called off before it was paid' : 'cancelled'}. ${paidLine(deps, cancelled)}`
+                    : h.sandbox
+                        ? // A test booking cancelled in the simulation: no hotel, no charge (2026-10-05 audit, P2).
+                            `${cancelled.confirmationCode} is cancelled in the simulated system. ${charged.minor === 0 ? 'No fee.' : `A real booking on this rate would be charged ${formatMoney(charged)}; this one is a test, and nothing is charged.`}`
+                        : h.demo
+                            ? // Nobody charges a demonstration anything (2026-10-05 audit, P2).
+                                `${cancelled.confirmationCode} is cancelled. ${charged.minor === 0 ? 'No fee.' : `A real booking on this rate would be charged ${formatMoney(charged)}; this is a demonstration, and nothing is charged.`}`
+                            : `${cancelled.confirmationCode} is cancelled. ${charged.minor === 0 ? 'No fee.' : `The hotel charges ${formatMoney(charged)}.`}`,
                 demoBookingNote(deps, cancelled.supplier),
                 deps.vocab.demo ? DEMO_NOTE : '',
             ]