Family Stay Compiler

One family brief, two staged checkouts, and a deterministic guardian that keeps every traveler, condition, and room-only promotion intact.

Comment

Inspiration

Planning a hotel stay becomes surprisingly difficult when a family does not fit inside a standard “one room, two guests” search box.

As a parent of three children, I repeatedly encountered the same frustrating loop: enter everyone’s ages, inspect a room or promotion, press Back, discover that the search conditions have reset, and start again. For larger families, the problem is deeper than inconvenience. One search may return nothing even though a workable combination of two or more rooms exists. Parents are then forced to split adults and children into separate searches, compare promotions manually, and hope the separate rooms still work as one family stay.

That experience led to a different question:

What if families could search for a complete stay plan—not just an individual room?

What it does

Family Stay Compiler preserves one structured family brief throughout the planning process: dates, adults, children’s ages, room limit, adult-per-room rules, youngest-child constraints, and connecting-room preferences.

The focus demonstration begins with two adults and four children under a one-room limit. The compiler returns an honest zero result rather than hiding or silently changing the constraints. An agent can preview changing only the room limit from one to two, but the saved family brief remains unchanged until the person presses Apply this change.

Once approved, the app compiles three complete synthetic stay plans. It keeps every traveler visible, explains room allocation, and states that the verified $24 family discount applies to Room 1 only—not automatically to both rooms.

The Split Checkout Guardian then audits two staged room checkouts as one family-level decision. It verifies traveler coverage, dates, room identity, subtotals, promotion scope, cancellation terms, and proximity before the person acknowledges the result for later manual review.

The app never opens checkout, books, pays, reserves, contacts a hotel, or claims live inventory.

Why WebMCP

Family Stay Compiler exposes six page-defined WebMCP tools over the same state used by the visible interface:

  • set_family_requirements
  • find_family_stay_plans
  • preview_constraint_unlock
  • compare_family_stay_plans
  • audit_split_checkout
  • prepare_decision_receipt

This is not ordinary DOM automation. The tools directly expose the underlying family-planning actions.

preview_constraint_unlock calculates the exact feasibility difference created by one reversible constraint change while leaving the saved brief untouched.

audit_split_checkout recomputes the staged decision using the selected planId. It verifies every traveler, both dates, adult and youngest-child rules, exact room identity, subtotals, promotion scope, cancellation terms, and room proximity.

Every successful tool call creates a visible activity on the page so the person can inspect what the agent did. Invalid previews and stale or mismatched audit evidence return explicit errors without mutating the visible activity ledger.

Better UX

Conventional hotel interfaces treat each room search or checkout as an isolated transaction. That creates unnecessary work and risk for larger families:

  • family ages and dates may reset after navigating back;
  • a one-room zero result does not explain which constraint failed;
  • promotions may apply to only one of the two required rooms;
  • two separate checkouts make it difficult to confirm that every traveler and condition is still covered.

Family Stay Compiler treats the family as one party from the first search through the final review.

The person can begin with an honest zero result, inspect one reversible counterfactual, apply it deliberately, compare complete plans, and audit two staged checkouts without re-entering the family brief.

Browser Back, Forward, and reload preserve the validated decision session and human acknowledgment. Stored evidence is recomputed before restoration, so altered or stale evidence cannot reuse an earlier acknowledgment.

What people and agents do together

The agent handles the tedious work:

  • validating a complete family brief;
  • explaining why a search is infeasible;
  • calculating a one-constraint counterfactual;
  • compiling complete room allocations;
  • comparing plan trade-offs;
  • checking traveler, date, subtotal, promotion, and policy consistency;
  • preparing a review-only receipt.

The person retains the consequential decisions:

  1. whether to apply the proposed room-limit change; and
  2. whether to acknowledge the split-checkout audit for later manual review.

The agent does not silently rewrite the family’s preferences, and the person does not have to manually cross-check every traveler and promotion across two disconnected room purchases.

That shared page state is the central WebMCP interaction: agent computation remains visible, reversible, and subject to human approval.

How we built it

Family Stay Compiler was built with React, TypeScript, Vite, and WebMCP.

The application separates deterministic planning logic from the interface and WebMCP registration layer. The human interface and all six tools call the same pure domain functions and update the same page state.

The planning engine evaluates flexible family sizes and room limits while enforcing active constraints such as:

  • room capacity;
  • an adult in each occupied room;
  • the youngest child remaining with an adult;
  • room proximity preferences;
  • exact traveler coverage;
  • room-specific promotion eligibility.

The Split Checkout Guardian compares staged room parts against the selected compiled plan. It blocks the audit if room identity, travelers, dates, subtotals, or promotion evidence differ.

The final release passed:

  • 24 Vitest unit and integration tests;
  • 12 desktop and mobile Playwright end-to-end tests;
  • TypeScript type checking;
  • the production build;
  • real WebMCP discovery and invocation in ChatGPT’s in-app browser.

All six tools were discovered and invoked successfully against the production deployment, with visible shared-page updates.

Challenges we ran into

The hardest problem was not building another hotel search form. It was representing the family’s complete situation without silently losing constraints.

A room limit does not mean every room count is feasible. For example, two adults cannot supervise four occupied rooms when every room requires an adult. Children’s ages, room capacity, proximity, promotions, cancellation terms, and checkout totals must remain attached to the same decision.

Another challenge was making counterfactual assistance safe. An agent may discover that changing one condition unlocks feasible plans, but it should not silently overwrite the family’s saved requirements. We therefore separated preview from Apply and gave the person the final decision.

The split-checkout audit also had to be strict. Matching only the total price was not enough. The guardian needed to verify room identity, every traveler, dates, subtotals, promotion scope, and terms—and reject stale or altered evidence.

Finally, we resisted overstating the prototype. Real inventory and promotions are provider-specific, so this challenge build uses explicit deterministic fixtures rather than presenting synthetic availability as live hotel data.

Accomplishments that we're proud of

We are proud that the project turns a real family-travel frustration into a reusable person-agent interaction model.

The final build:

  • supports flexible family sizes and one-to-four-room search limits;
  • explains infeasibility instead of returning an unexplained empty screen;
  • previews one reversible constraint change without mutating the saved brief;
  • keeps every traveler visible across multi-room plans;
  • makes room-specific promotion scope explicit;
  • audits two staged checkouts as one family decision;
  • restores validated evidence across Back, Forward, and reload;
  • prepares a review-only receipt without initiating a transaction;
  • exposes six working WebMCP tools through one shared human-agent interface.

Most importantly, it treats the family as one party—even when the stay requires multiple rooms and separate checkouts.

What we learned

We learned that WebMCP is most valuable when it does more than automate clicks.

A conventional browser agent might fill in a form, navigate away, and lose the context that mattered. With WebMCP, the page exposes meaningful planning operations while remaining a visible shared workspace. The agent handles structured calculation and cross-checking; the person controls exceptions and consequential decisions.

We also learned that a good zero-result experience is a product feature. “No rooms found” is rarely enough. Families need to know which constraint caused the failure and what one change could make a valid plan possible.

Finally, promotions should be treated as evidence with scope—not as a banner. A discount shown for one room checkout should never be assumed to apply to every room the family requires.

What's next for Family Stay Compiler

The next step would be to connect the compiler to authorized hotel or OTA inventory through clearly separated provider adapters.

The deterministic fixture source could then be replaced by an authorized inventory adapter without rewriting the family brief, constraint engine, WebMCP tools, guardian, or shared review interface.

Future improvements could answer questions such as:

  • Which single constraint is preventing a feasible plan?
  • What changes if connecting rooms are preferred rather than required?
  • Would adding another adult unlock an additional valid allocation?
  • Which promotion produces the lowest comparable total across every required room?
  • Can a provider hold both room parts long enough for a coordinated purchase?

Longer term, Family Stay Compiler could become a family travel decision layer across multiple booking providers—helping parents understand the complete stay before making disconnected purchases.

Demo boundary

All hotel, room, rate, promotion, and traveler data in this challenge build is synthetic.

There is no backend, database, analytics, authentication, scraping, live inventory, booking, payment, reservation, or hotel contact. The decision receipt is for review only.

Built With

Share this project:

Updates

Submission history