@curless/hotel-storefront 0.1.0

package/dist/tools.js

@@ -0,0 +1,862 @@
+import { isDay } from './dates.js';
+import { DESCRIPTION_MAX, POLICY_MAX, hotelText } from './fence.js';
+import { formatMoney } from './money.js';
+import { MAX_EXTRA_QUANTITY, MAX_ROOMS_PER_LINE, clampCount, tripKey, } from './trip.js';
+import { DEMO_NOTE } from './vocab.js';
+// The eleven things a guest can do: find hotels, look at one on dates, see what
+// else it offers, build a trip, ask for the rooms, and deal with a booking they
+// already have.
+//
+// ⚠️ TOOL DESCRIPTIONS SAY WHAT A TOOL DOES AND NOTHING ELSE. No "always call
+// X first", no "do not use web search", no rules about the model's behaviour.
+// That is not style: the directory listings both attest that "tool descriptions
+// contain no instructions about model behavior, other tools, or external
+// instruction sources", and the shopping connector had to move nine
+// descriptions' worth of guidance into the server instructions on 2026-09-17 to
+// make that attestation true. This package starts there. Behaviour lives in
+// surface.ts, and `tool-descriptions.test.ts` holds the line.
+/**
+ * Annotations, every hint stated, and each one true of the code.
+ *
+ * OpenAI's review rejected the shopping app's v1.0.0 over exactly this - an
+ * absent `idempotentHint` reads as null, and `openWorldHint: false` was a claim
+ * the code could not support. So: reads are reads, the trip tools write OUR
+ * state and say so, and `openWorldHint` follows where the rooms actually come
+ * from - false while this serves a local demonstration file, true once a
+ * deployment points at the group's own booking system, which answers with
+ * whatever it says at that moment.
+ */
+const reads = (title, openWorld) => ({
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: openWorld,
+});
+/** Changes the trip we hold for this conversation. Nothing at the hotel moves. */
+const edits = (title, openWorld) => ({
+    title,
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: openWorld,
+});
+/** Asks the hotel to hold rooms. Takes no money, and undoing it is what the cancel tools are for. */
+const books = (title, openWorld) => ({
+    title,
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: openWorld,
+});
+const cancels = (title, openWorld) => ({
+    title,
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: openWorld,
+});
+const DATE = (what) => ({ type: 'string', description: `${what}, as YYYY-MM-DD` });
+export const buildTools = (n, v) => {
+    const open = !v.demo;
+    const stayProps = {
+        checkIn: DATE('The arrival date'),
+        checkOut: DATE('The departure date - the night before it is the last night'),
+        guests: { type: 'number', description: 'People in the room. Default 2' },
+    };
+    return [
+        {
+            name: n.listHotels,
+            description: `${v.brand} ${v.nounPlural}, shown as a card with a picture, the city and area, a rating where the ${v.noun} publishes one, and a from-price for each. \`city\` or \`query\` narrows the list; a city usually holds several ${v.nounPlural}, and all of them are returned. Dates are not needed here and no stay is priced.${v.hints.search ? ` ${v.hints.search}` : ''}`,
+            annotations: reads(`Browse ${v.brand} ${v.nounPlural}`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: "Free text over the name, city, area, description and amenities - the guest's own words",
+                    },
+                    city: { type: 'string', description: 'One city, e.g. "Hong Kong"' },
+                    limit: { type: 'number', description: 'Default 20' },
+                },
+            },
+        },
+        {
+            name: n.getHotel,
+            description: `One ${v.noun} in full: description, amenities, address, check-in and check-out times. Given \`checkIn\` and \`checkOut\` it also returns the room types that can be booked for those nights, each with its nightly rate, the stay total including taxes and fees, whether it can be cancelled free and until when, and how many rooms are left. Without dates it returns the ${v.noun} only, because a room has no price until the nights are known.${v.hints.hotel ? ` ${v.hints.hotel}` : ''}`,
+            annotations: reads(`View one ${v.brand} ${v.noun}`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    hotel: {
+                        type: 'string',
+                        description: `The ${v.noun}'s name or id${v.hints.example ? `, e.g. "${v.hints.example}"` : ''}`,
+                    },
+                    ...stayProps,
+                },
+                required: ['hotel'],
+            },
+        },
+        {
+            name: n.listExtras,
+            description: `What one ${v.noun} offers beside the room: airport transfers, dinners, guided experiences, spa and family add-ons, each with its price and whether it is charged per stay, per person or per night.`,
+            annotations: reads(`${v.brand} add-ons`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    hotel: { type: 'string', description: `The ${v.noun}'s name or id` },
+                    ...stayProps,
+                },
+                required: ['hotel'],
+            },
+        },
+        {
+            name: n.addToTrip,
+            description: `Puts room nights or an add-on into the trip and returns the whole trip, priced. A room line needs the ${v.noun}, the room type and the dates; \`rooms\` books more than one of that room type. An add-on line needs the ${v.noun} and the add-on. A line is replaced, not stacked: sending the same room and dates again sets that line's room count, and 0 removes it.`,
+            annotations: edits(`Add to the ${v.brand} trip`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    hotel: { type: 'string', description: `The ${v.noun}'s name or id` },
+                    room: {
+                        type: 'string',
+                        description: 'The room type id or name, as the hotel returned it',
+                    },
+                    extra: {
+                        type: 'string',
+                        description: 'The add-on id or name. A line names either this or `room`',
+                    },
+                    ...stayProps,
+                    rooms: {
+                        type: 'number',
+                        description: `How many of that room type, 1 to ${MAX_ROOMS_PER_LINE}. Default 1; 0 removes the line`,
+                    },
+                    quantity: {
+                        type: 'number',
+                        description: `For an add-on: how many, 1 to ${MAX_EXTRA_QUANTITY}. Default 1; 0 removes it`,
+                    },
+                },
+                required: ['hotel'],
+            },
+        },
+        {
+            name: n.viewTrip,
+            description: 'The trip as it stands: every room line and add-on with its own total, the taxes and fees, and the all-in total, laid out day by day on the card.',
+            annotations: reads(`View the ${v.brand} trip`, open),
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: n.clearTrip,
+            description: 'Empties the trip.',
+            annotations: edits(`Clear the ${v.brand} trip`, open),
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: n.requestBooking,
+            description: `Asks ${v.brand} to hold the trip's rooms for a named guest and returns a confirmation code and the moment the hold lapses. No payment is taken and no card is collected; the rooms are held, not paid for.`,
+            annotations: books(`Request a ${v.brand} booking`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: "The guest's full name, as it should appear on the booking",
+                    },
+                    email: { type: 'string', description: 'The email the confirmation goes to' },
+                    phone: { type: 'string', description: 'Optional' },
+                    notes: {
+                        type: 'string',
+                        description: 'Anything the hotel should know - a late arrival, a high floor',
+                    },
+                },
+                required: ['name', 'email'],
+            },
+        },
+        {
+            name: n.listBookings,
+            description: 'The bookings made in this conversation, newest to oldest, with their status, dates and confirmation codes. Given an email it also finds bookings made with that email.',
+            annotations: reads(`My ${v.brand} bookings`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    email: { type: 'string', description: 'The email a booking was made with' },
+                    limit: { type: 'number', description: 'Default 10' },
+                },
+            },
+        },
+        {
+            name: n.previewCancellation,
+            description: 'What cancelling a booking would cost and what would be refunded, with the rule it was worked out from and the free-cancellation deadline where the rate has one. Nothing is cancelled.',
+            annotations: reads('Preview a cancellation', open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    booking: { type: 'string', description: 'The confirmation code or booking id' },
+                    email: {
+                        type: 'string',
+                        description: 'The email the booking was made with, when it was made elsewhere',
+                    },
+                },
+                required: ['booking'],
+            },
+        },
+        {
+            name: n.cancelBooking,
+            // No other tool is named here, and that is not a stylistic choice: the
+            // directory attestation covers descriptions that instruct about other
+            // tools. The preview it returns is the same payload the preview tool
+            // returns, which is a fact about THIS tool's answer.
+            description: 'Cancels a booking. Called without `confirmed` it returns the cancellation preview - the fee, the refund and the rule behind them - and cancels nothing; it cancels only when `confirmed` is true.',
+            annotations: cancels('Cancel a booking', open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    booking: { type: 'string', description: 'The confirmation code or booking id' },
+                    confirmed: {
+                        type: 'boolean',
+                        description: 'True cancels. Anything else returns the preview',
+                    },
+                    reason: { type: 'string', description: 'Optional, kept on the booking' },
+                    email: {
+                        type: 'string',
+                        description: 'The email the booking was made with, when it was made elsewhere',
+                    },
+                },
+                required: ['booking'],
+            },
+        },
+        {
+            name: n.policies,
+            description: `What one ${v.noun} publishes about cancellation, check-in and check-out, children and extra beds, pets, deposits and accessibility. With \`topic\` it returns that topic; without, all of them.`,
+            annotations: reads(`${v.brand} policies`, open),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    hotel: { type: 'string', description: `The ${v.noun}'s name or id` },
+                    topic: {
+                        type: 'string',
+                        enum: ['cancellation', 'check-in', 'children', 'pets', 'deposit', 'accessibility'],
+                    },
+                },
+                required: ['hotel'],
+            },
+        },
+    ];
+};
+// The shape of each tool's `structuredContent`, so a reader knows what it is
+// holding without inferring it from one example.
+//
+// `view` is the discriminator and is always present - that is the part a reader
+// must be able to rely on, so it is the part declared exactly. Item internals
+// are left open on purpose: a schema that promises fields the payload sometimes
+// omits is a claim that is sometimes false, and the reader trusting it is the
+// model deciding what to tell a guest.
+const OBJ = { type: 'object' };
+const ARR = { type: 'array', items: { type: 'object' } };
+const STR = { type: 'string' };
+const BOOL = { type: 'boolean' };
+const TRIP_SCHEMA = {
+    type: 'object',
+    properties: {
+        view: { enum: ['trip', 'needs-dates', 'error'] },
+        brand: STR,
+        toolNames: OBJ,
+        vocab: OBJ,
+        demo: BOOL,
+        demoNote: STR,
+        lines: ARR,
+        stay: OBJ,
+        subtotal: STR,
+        taxesAndFees: STR,
+        total: STR,
+        days: ARR,
+        dropped: ARR,
+    },
+    required: ['view'],
+};
+const CANCEL_SCHEMA = {
+    type: 'object',
+    properties: {
+        view: { enum: ['cancellation-preview', 'cancelled', 'booking-not-found'] },
+        brand: STR,
+        toolNames: OBJ,
+        demo: BOOL,
+        demoNote: STR,
+        booking: OBJ,
+        fee: STR,
+        refund: STR,
+        rule: STR,
+        freeUntil: STR,
+        cancellable: BOOL,
+    },
+    required: ['view'],
+};
+export const buildOutputSchemas = (n) => ({
+    [n.listHotels]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['hotels', 'no-hotels'] },
+            brand: STR,
+            toolNames: OBJ,
+            vocab: OBJ,
+            demo: BOOL,
+            demoNote: STR,
+            hotels: ARR,
+            total: { type: 'number' },
+            cities: ARR,
+            query: STR,
+        },
+        required: ['view'],
+    },
+    [n.getHotel]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['hotel', 'no-rooms', 'hotel-not-found'] },
+            brand: STR,
+            toolNames: OBJ,
+            vocab: OBJ,
+            demo: BOOL,
+            demoNote: STR,
+            hotel: OBJ,
+            stay: OBJ,
+            rooms: ARR,
+            /** True when no dates were given: the card asks for them instead of showing rooms. */
+            needsDates: BOOL,
+            noRooms: STR,
+            extras: ARR,
+            policies: ARR,
+        },
+        required: ['view'],
+    },
+    [n.listExtras]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['extras', 'hotel-not-found'] },
+            brand: STR,
+            toolNames: OBJ,
+            demo: BOOL,
+            demoNote: STR,
+            hotel: OBJ,
+            extras: ARR,
+        },
+        required: ['view'],
+    },
+    [n.addToTrip]: TRIP_SCHEMA,
+    [n.viewTrip]: TRIP_SCHEMA,
+    [n.clearTrip]: TRIP_SCHEMA,
+    [n.requestBooking]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['booking', 'empty-trip', 'error'] },
+            brand: STR,
+            toolNames: OBJ,
+            demo: BOOL,
+            demoNote: STR,
+            booking: OBJ,
+            /** Always false here: this connector holds rooms and takes no money. */
+            paid: BOOL,
+            holdUntil: STR,
+            total: STR,
+        },
+        required: ['view'],
+    },
+    [n.listBookings]: {
+        type: 'object',
+        properties: {
+            view: { const: 'bookings' },
+            brand: STR,
+            toolNames: OBJ,
+            demo: BOOL,
+            demoNote: STR,
+            bookings: ARR,
+            count: { type: 'number' },
+        },
+        required: ['view'],
+    },
+    [n.previewCancellation]: CANCEL_SCHEMA,
+    [n.cancelBooking]: CANCEL_SCHEMA,
+    [n.policies]: {
+        type: 'object',
+        properties: {
+            view: { enum: ['policy', 'policies', 'policy-missing', 'hotel-not-found'] },
+            brand: STR,
+            toolNames: OBJ,
+            demo: BOOL,
+            hotel: OBJ,
+            topic: STR,
+            title: STR,
+            text: STR,
+            topics: ARR,
+            url: STR,
+        },
+        required: ['view'],
+    },
+});
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+const asStay = (args) => {
+    const checkIn = str(args.checkIn);
+    const checkOut = str(args.checkOut);
+    if (!checkIn && !checkOut)
+        return undefined;
+    const guests = typeof args.guests === 'number' ? Math.floor(args.guests) : 2;
+    return { checkIn, checkOut, guests };
+};
+/** What every payload carries, so the card can draw a header and say whose data this is. */
+const common = (deps) => ({
+    brand: deps.vocab.brand,
+    ...(deps.logoUrl ? { logoUrl: deps.logoUrl } : {}),
+    toolNames: deps.tools,
+    vocab: { noun: deps.vocab.noun, nounPlural: deps.vocab.nounPlural },
+    ...(deps.vocab.demo ? { demo: true, demoNote: DEMO_NOTE } : { demo: false }),
+});
+/** One line of a trip, flattened for the card. Prices are strings: the card never does arithmetic. */
+const quoteForCard = (quote) => ({
+    lines: quote.lines.map((l) => ({
+        kind: l.kind,
+        hotelId: l.hotelId,
+        hotelName: l.hotelName,
+        roomRef: l.roomRef,
+        extraRef: l.extraRef,
+        title: l.title,
+        detail: l.detail,
+        stay: l.stay,
+        nights: l.nights,
+        quantity: l.quantity,
+        unit: formatMoney(l.unit),
+        total: formatMoney(l.total),
+        refundable: l.refundable,
+        freeCancellationUntil: l.freeCancellationUntil,
+        day: l.day,
+    })),
+    subtotal: formatMoney(quote.subtotal),
+    taxesAndFees: formatMoney(quote.taxesAndFees),
+    total: formatMoney(quote.total),
+    ...(quote.stay ? { stay: quote.stay } : {}),
+    ...(quote.dropped ? { dropped: quote.dropped } : {}),
+});
+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} nights) — ${formatMoney(l.total)}`
+        : `- ${l.quantity}× ${l.title} — ${formatMoney(l.total)}`);
+    return [
+        ...lines,
+        `Taxes and fees ${formatMoney(quote.taxesAndFees)} · **Total ${formatMoney(quote.total)}**`,
+        ...(quote.dropped ?? []).map((d) => `Left out: ${d.title} — ${d.why}`),
+        demo ? DEMO_NOTE : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+};
+const bookingLine = (b) => `${b.confirmationCode} · ${b.hotelName} · ${b.stay.checkIn} to ${b.stay.checkOut} · ${b.status}`;
+const identity = (ctx, args) => {
+    const email = str(args.email);
+    return email ? { sessionId: ctx.session, email } : { sessionId: ctx.session };
+};
+/** The trip, priced, as both views need it. */
+const currentTrip = async (deps, key) => {
+    const lines = deps.trips.read(key);
+    const quote = await deps.backend.quote({ lines });
+    return {
+        structured: { view: 'trip', ...common(deps), ...quoteForCard(quote), count: lines.length },
+        text: tripText(quote, deps.vocab.demo),
+    };
+};
+export const handleTool = async (deps, name, rawArgs, ctx) => {
+    const args = (rawArgs ?? {});
+    const t = deps.tools;
+    const key = ctx.tripKey ?? tripKey(ctx.session, deps.vocab.brand);
+    if (name === t.listHotels) {
+        const query = str(args.query);
+        const hotels = await deps.backend.searchHotels({
+            query: query || undefined,
+            city: str(args.city) || undefined,
+            limit: typeof args.limit === 'number' ? args.limit : undefined,
+        });
+        const cities = [...new Set(hotels.map((h) => h.city))];
+        if (hotels.length === 0) {
+            return {
+                structured: { view: 'no-hotels', ...common(deps), hotels: [], total: 0, query },
+                text: `No ${deps.vocab.brand} ${deps.vocab.nounPlural} match that.`,
+            };
+        }
+        const forCard = hotels.map((h) => ({
+            ...h,
+            summary: hotelText('description', h.name, h.summary, DESCRIPTION_MAX).text,
+            fromNightly: h.fromNightly ? formatMoney(h.fromNightly) : undefined,
+        }));
+        // The whole shortlist, never one pick: a city is not a hotel.
+        const where = cities.length === 1 ? ` in ${cities[0]}` : '';
+        return {
+            structured: {
+                view: 'hotels',
+                ...common(deps),
+                hotels: forCard,
+                total: hotels.length,
+                cities,
+                query,
+            },
+            text: `${hotels.length} ${deps.vocab.brand} ${hotels.length === 1 ? deps.vocab.noun : deps.vocab.nounPlural}${where} — tap one to see rooms.`,
+        };
+    }
+    if (name === t.getHotel) {
+        const wanted = str(args.hotel);
+        const stay = asStay(args);
+        const detail = await deps.backend.getHotel(wanted, stay);
+        if (!detail) {
+            return {
+                structured: { view: 'hotel-not-found', ...common(deps), query: wanted },
+                text: `No ${deps.vocab.brand} ${deps.vocab.noun} by that name. ${t.listHotels} lists them.`,
+            };
+        }
+        const h = detail.hotel;
+        const description = hotelText('description', h.name, h.summary, DESCRIPTION_MAX);
+        const policies = await deps.backend.policies(h.id);
+        const extras = await deps.backend.extrasFor(h.id, stay);
+        const base = {
+            ...common(deps),
+            hotel: {
+                ...h,
+                summary: description.text,
+                fromNightly: h.fromNightly ? formatMoney(h.fromNightly) : undefined,
+            },
+            extras: extras.map((e) => ({ ...e, price: formatMoney(e.price) })),
+            policies: policies.map((p) => ({ topic: p.topic, title: p.title })),
+        };
+        if (!stay) {
+            return {
+                structured: { view: 'hotel', ...base, needsDates: true },
+                text: [
+                    `**${h.name}** · ${[h.area, h.city].filter(Boolean).join(', ')}`,
+                    description.fenced,
+                    'Rooms and prices need the dates - which nights is the guest staying?',
+                ]
+                    .filter(Boolean)
+                    .join('\n\n'),
+            };
+        }
+        if (detail.noRooms || !detail.rooms) {
+            return {
+                structured: { view: 'no-rooms', ...base, stay, noRooms: detail.noRooms },
+                text: detail.noRooms ?? 'Nothing is available for those nights.',
+            };
+        }
+        const rooms = detail.rooms.map((r) => ({
+            ...r,
+            nightly: formatMoney(r.nightly),
+            stayTotal: formatMoney(r.stayTotal),
+            taxesAndFees: formatMoney(r.taxesAndFees),
+        }));
+        return {
+            structured: { view: 'hotel', ...base, stay, rooms },
+            text: [
+                `**${h.name}** · ${detail.rooms.length} room ${detail.rooms.length === 1 ? 'type' : 'types'} for ${stay.checkIn} to ${stay.checkOut}, ${stay.guests} guests.`,
+                ...detail.rooms.map((r) => `- ${r.name} — ${formatMoney(r.nightly)} a night, ${formatMoney(r.stayTotal)} for the stay incl. taxes and fees${r.refundable ? `, free to cancel${r.freeCancellationUntil ? ` until ${r.freeCancellationUntil.slice(0, 10)}` : ''}` : ', non-refundable'}`),
+                deps.vocab.demo ? DEMO_NOTE : '',
+            ]
+                .filter(Boolean)
+                .join('\n'),
+        };
+    }
+    if (name === t.listExtras) {
+        const wanted = str(args.hotel);
+        const detail = await deps.backend.getHotel(wanted);
+        if (!detail) {
+            return {
+                structured: { view: 'hotel-not-found', ...common(deps), query: wanted },
+                text: `No ${deps.vocab.brand} ${deps.vocab.noun} by that name.`,
+            };
+        }
+        const extras = await deps.backend.extrasFor(detail.hotel.id, asStay(args));
+        return {
+            structured: {
+                view: 'extras',
+                ...common(deps),
+                hotel: detail.hotel,
+                extras: extras.map((e) => ({
+                    ...e,
+                    description: hotelText('add-on', detail.hotel.name, e.description, DESCRIPTION_MAX).text,
+                    price: formatMoney(e.price),
+                })),
+            },
+            text: extras.length
+                ? extras
+                    .map((e) => `- ${e.name} — ${formatMoney(e.price)} per ${e.per}`)
+                    .concat(deps.vocab.demo ? [DEMO_NOTE] : [])
+                    .join('\n')
+                : `${detail.hotel.name} has no add-ons listed here.`,
+        };
+    }
+    if (name === t.addToTrip) {
+        const wanted = str(args.hotel);
+        const detail = await deps.backend.getHotel(wanted);
+        if (!detail) {
+            return {
+                structured: { view: 'error', ...common(deps), error: 'hotel-not-found', query: wanted },
+                text: `No ${deps.vocab.brand} ${deps.vocab.noun} by that name.`,
+            };
+        }
+        const hotelId = detail.hotel.id;
+        const extraRef = str(args.extra);
+        if (extraRef) {
+            const extras = await deps.backend.extrasFor(hotelId);
+            const extra = extras.find((e) => e.id === extraRef || e.name.toLowerCase() === extraRef.toLowerCase());
+            if (!extra) {
+                return {
+                    structured: { view: 'error', ...common(deps), error: 'no-such-extra', query: extraRef },
+                    text: `${detail.hotel.name} does not offer that. ${t.listExtras} lists what it has.`,
+                };
+            }
+            const line = {
+                kind: 'extra',
+                hotelId,
+                extraId: extra.id,
+                quantity: clampCount(args.quantity ?? 1, MAX_EXTRA_QUANTITY),
+                ...(isDay(str(args.day)) ? { day: str(args.day) } : {}),
+            };
+            deps.trips.set(key, line);
+            return currentTrip(deps, key);
+        }
+        const roomRef = str(args.room);
+        if (!roomRef) {
+            return {
+                structured: { view: 'error', ...common(deps), error: 'no-room-named' },
+                text: `Say which room type, or which add-on. ${t.getHotel} with the dates lists the room types.`,
+            };
+        }
+        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) {
+            return {
+                structured: { view: 'needs-dates', ...common(deps), hotel: detail.hotel, room: roomRef },
+                text: '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
+        // second opinion computed from this process's clock would disagree with it
+        // for eight hours a day.
+        const dated = await deps.backend.getHotel(hotelId, stay);
+        if (!dated?.rooms) {
+            return {
+                structured: {
+                    view: 'needs-dates',
+                    ...common(deps),
+                    hotel: detail.hotel,
+                    room: roomRef,
+                    why: dated?.noRooms,
+                },
+                text: dated?.noRooms ?? 'Those nights cannot be booked here.',
+            };
+        }
+        const room = dated.rooms.find((r) => r.id === roomRef || r.name.toLowerCase() === roomRef.toLowerCase());
+        if (!room) {
+            return {
+                structured: {
+                    view: 'error',
+                    ...common(deps),
+                    error: 'no-such-room',
+                    query: roomRef,
+                    rooms: dated.rooms.map((r) => ({ id: r.id, name: r.name })),
+                },
+                text: `${detail.hotel.name} has no room type by that name for those nights. It has: ${dated.rooms.map((r) => r.name).join(', ')}.`,
+            };
+        }
+        deps.trips.set(key, {
+            kind: 'room',
+            hotelId,
+            roomId: room.id,
+            stay,
+            rooms: clampCount(args.rooms ?? 1, MAX_ROOMS_PER_LINE),
+        });
+        return currentTrip(deps, key);
+    }
+    if (name === t.viewTrip)
+        return currentTrip(deps, key);
+    if (name === t.clearTrip) {
+        deps.trips.clear(key);
+        return {
+            structured: { view: 'trip', ...common(deps), lines: [], count: 0, total: null },
+            text: 'The trip is empty.',
+        };
+    }
+    if (name === t.requestBooking) {
+        const lines = deps.trips.read(key);
+        if (lines.length === 0) {
+            return {
+                structured: { view: 'empty-trip', ...common(deps) },
+                text: `There is nothing in the trip yet. ${t.addToTrip} puts room nights in it.`,
+            };
+        }
+        const guest = { name: str(args.name), email: str(args.email) };
+        try {
+            const booking = await deps.backend.requestBooking({ lines }, {
+                ...guest,
+                ...(str(args.phone) ? { phone: str(args.phone) } : {}),
+                ...(str(args.notes) ? { notes: str(args.notes) } : {}),
+            }, { sessionId: ctx.session, email: guest.email });
+            deps.trips.clear(key);
+            return {
+                structured: {
+                    view: 'booking',
+                    ...common(deps),
+                    booking: { ...booking, quote: quoteForCard(booking.quote) },
+                    paid: false,
+                    holdUntil: booking.holdUntil,
+                    total: formatMoney(booking.quote.total),
+                },
+                text: [
+                    `**${booking.confirmationCode}** · ${booking.hotelName} · ${booking.stay.checkIn} to ${booking.stay.checkOut}`,
+                    `${formatMoney(booking.quote.total)} all in. **Nothing has been charged** - the rooms are held until ${booking.holdUntil?.slice(0, 16).replace('T', ' ')} UTC, and ${booking.guest.name} presents a card at check-in.`,
+                    deps.vocab.demo ? DEMO_NOTE : '',
+                ]
+                    .filter(Boolean)
+                    .join('\n'),
+            };
+        }
+        catch (err) {
+            return {
+                structured: {
+                    view: 'error',
+                    ...common(deps),
+                    error: 'not-bookable',
+                    detail: err.message,
+                },
+                text: err.message,
+            };
+        }
+    }
+    if (name === t.listBookings) {
+        const bookings = await deps.backend.listBookings(identity(ctx, args), typeof args.limit === 'number' ? args.limit : undefined);
+        return {
+            structured: {
+                view: 'bookings',
+                ...common(deps),
+                bookings: bookings.map((b) => ({ ...b, quote: quoteForCard(b.quote) })),
+                count: bookings.length,
+            },
+            text: bookings.length
+                ? bookings.map(bookingLine).join('\n')
+                : 'No bookings here. A booking made in another conversation can be found with the email it was made with.',
+        };
+    }
+    if (name === t.previewCancellation || name === t.cancelBooking) {
+        const ref = str(args.booking);
+        const who = identity(ctx, args);
+        const preview = await deps.backend.previewCancellation(ref, who);
+        if (!preview) {
+            return {
+                structured: { view: 'booking-not-found', ...common(deps), query: ref },
+                text: 'No booking here matches that code. A booking made in another conversation needs the email it was made with.',
+            };
+        }
+        const asPreview = {
+            structured: {
+                view: 'cancellation-preview',
+                ...common(deps),
+                booking: { id: preview.bookingId, confirmationCode: preview.confirmationCode },
+                fee: formatMoney(preview.fee),
+                refund: formatMoney(preview.refund),
+                rule: preview.rule,
+                freeUntil: preview.freeUntil,
+                cancellable: preview.cancellable,
+                toolToConfirm: t.cancelBooking,
+            },
+            text: [
+                `Cancelling ${preview.confirmationCode} would cost ${formatMoney(preview.fee)}${preview.fee.minor === 0 ? ' - nothing' : ''}.`,
+                preview.rule,
+                preview.cancellable
+                    ? `Say the word and it is cancelled (${t.cancelBooking} with \`confirmed\`).`
+                    : '',
+            ]
+                .filter(Boolean)
+                .join(' '),
+        };
+        // ⚠️ THE PREVIEW IS NOT ADVISORY. Cancelling without one is how a guest
+        // loses a night's rate they were never told about, so the cancel tool
+        // returns this same preview and does nothing until it is told again.
+        if (name === t.previewCancellation || args.confirmed !== true)
+            return asPreview;
+        if (!preview.cancellable)
+            return asPreview;
+        const cancelled = await deps.backend.cancelBooking(ref, who, str(args.reason) || undefined);
+        if (!cancelled)
+            return asPreview;
+        return {
+            structured: {
+                view: 'cancelled',
+                ...common(deps),
+                booking: { ...cancelled, quote: quoteForCard(cancelled.quote) },
+                fee: formatMoney(preview.fee),
+                refund: formatMoney(preview.refund),
+                rule: preview.rule,
+                cancellable: false,
+            },
+            text: `${cancelled.confirmationCode} is cancelled. ${preview.fee.minor === 0 ? 'No fee.' : `The hotel charges ${formatMoney(preview.fee)}.`}`,
+        };
+    }
+    if (name === t.policies) {
+        const wanted = str(args.hotel);
+        const detail = await deps.backend.getHotel(wanted);
+        if (!detail) {
+            return {
+                structured: { view: 'hotel-not-found', ...common(deps), query: wanted },
+                text: `No ${deps.vocab.brand} ${deps.vocab.noun} by that name.`,
+            };
+        }
+        const policies = await deps.backend.policies(detail.hotel.id);
+        const topic = str(args.topic);
+        if (topic) {
+            const one = policies.find((p) => p.topic === topic);
+            if (!one) {
+                return {
+                    structured: {
+                        view: 'policy-missing',
+                        ...common(deps),
+                        hotel: detail.hotel,
+                        topic,
+                        topics: policies.map((p) => ({ topic: p.topic, title: p.title })),
+                        url: detail.hotel.url,
+                    },
+                    // Never fill in what hotels usually do - that is how a guest is told
+                    // about a free window this one does not offer.
+                    text: `${detail.hotel.name} does not publish anything about that here.${detail.hotel.url ? ` Its own page: ${detail.hotel.url}` : ''}`,
+                };
+            }
+            const fenced = hotelText(one.title, detail.hotel.name, one.text, POLICY_MAX);
+            return {
+                structured: {
+                    view: 'policy',
+                    ...common(deps),
+                    hotel: detail.hotel,
+                    topic: one.topic,
+                    title: one.title,
+                    text: fenced.text,
+                    url: one.url,
+                },
+                text: `**${one.title} · ${detail.hotel.name}**\n\n${fenced.fenced}`,
+            };
+        }
+        const all = policies
+            .map((p) => hotelText(p.title, detail.hotel.name, p.text, POLICY_MAX).fenced)
+            .join('\n\n');
+        return {
+            structured: {
+                view: 'policies',
+                ...common(deps),
+                hotel: detail.hotel,
+                topics: policies.map((p) => ({
+                    topic: p.topic,
+                    title: p.title,
+                    text: hotelText(p.title, detail.hotel.name, p.text, POLICY_MAX).text,
+                })),
+                url: detail.hotel.url,
+            },
+            text: all || `${detail.hotel.name} publishes no policies here.`,
+        };
+    }
+    return { structured: { view: 'error', error: 'unknown-tool' }, text: `Unknown tool: ${name}` };
+};
+//# sourceMappingURL=tools.js.map