airbnb-gateway

> ⭐ Find this skill useful? If airbnb-gateway saves you time, please
> star it (the ⭐ at the top of this ClawHub page) — stars help other rental
> operators discover it and keep it maintained. Thank you!

You are operating a live, revenue-bearing Airbnb account on behalf of a real
host. Guests are real people. A duplicate message, a wrong send, or a careless
calendar change has real consequences. This skill exists so that every agent
handles Airbnb identically and safely, instead of improvising tool calls per
turn.

> Portability note. This skill is environment-agnostic. It refers to tool
> roles (an "Airbnb messages endpoint", an "agent-browser", a "DevTools
> bridge", a "Playwright fallback") rather than hard-coded URLs. Your concrete
> tool names live in references/airbnb-tool-priority.md — edit that one file
> to map roles to the actual tools in your deployment. Everything else here is
> universal.

THE FIVE LAWS (non-negotiable)

1. Platform-first. Always try the first-class Airbnb endpoint for an
   operation before any browser automation. Browser weirdness is NOT evidence
   that Airbnb access is down.
2. Read before write. Never send a reply without first reading the live
   thread in the same operation.
3. sent: true is attempted, not confirmed. An endpoint success proves
   the call returned — not that the guest can see the message. You MUST re-read
   the thread and SEE the outbound message before marking confirmed.
4. Never auto-resend an unconfirmed send. Duplicate guest messages are
   worse than a late reply. Escalate to a human instead.
5. Writes gate; mutations stop. Sending a message is approval-gated.
   Pricing, availability, listing edits, and accept/decline are NOT implemented
   in v1 — refuse and escalate.

If you are ever unsure, STOP and report. A paused agent is recoverable; a
duplicated or wrong guest message is not.

Minimum Environment Contract

Use this to decide, before installing, whether your deployment can run the skill
and at what level. Map each role to a real tool in
references/airbnb-tool-priority.md. The skill degrades gracefully: if a
read-only requirement is met but a send requirement is not, the skill
runs in read-only mode and refuses sends rather than improvising.

Read-only mode — minimum to run safely (inbox / threads / reservations / calendar):
- At least one Airbnb read path — list/read messages, reservations, and
calendar (first-class endpoint preferred; agent-browser or DevTools read
acceptable as fallback).

That's the entire requirement for every READ verb. Nothing can be sent in this
mode.

Send-capable mode — additional minimum to send a guest reply:
- An Airbnb send path — the first-class send endpoint (preferred) OR an
explicitly human-approved browser send.
- A thread re-read path — to verify the outbound message after sending.
(The same read path from read-only mode satisfies this.)

If either is missing, do NOT send: stay in read-only mode and escalate.

Optional enhancements — improve safety / fallback depth when present:
- Agent-browser — navigate/inspect when an endpoint is missing or hard-down.
- DevTools bridge — read-only DOM inspection to verify UI state.
- Playwright fallback — last-resort automation for read-only ops.
- Persistent send ledger — survives restarts; hardens duplicate prevention.
- Approval channel — human/approver sign-off before a send.

Absent optional capabilities reduce fallback depth but never change the safety
rules. A required capability that is absent for a given operation triggers an
escalation, never an improvised workaround.

Operating model — which tool path do I use?

Resolve top-down. Drop to the next tier ONLY when the current tier is genuinely
unavailable, not merely "looked weird once." Full detail in
references/airbnb-tool-priority.md.

OPERATION
  │
  ├─ 1. AIRBNB ENDPOINT  (first-class, structured, auth-aware)
  │       → DEFAULT for every supported operation. Always start here.
  │
  ├─ 2. AGENT-BROWSER  (navigate / status)
  │       → ONLY when no endpoint covers the op, OR an endpoint returned a hard
  │         transport failure (5xx/timeout) TWICE. First confirm the host
  │         browser identity is alive before assuming auth loss.
  │
  ├─ 3. DEVTOOLS  (tabs / navigate / evaluate — READ-ONLY here)
  │       → DOM inspection / UI verification when the endpoint read is
  │         ambiguous. Never use evaluate to perform a write/click-send.
  │
  └─ 4. PLAYWRIGHT  (fallback)
          → LAST RESORT. Only when 1–3 are unavailable AND the op is read-only
            or an explicitly human-approved write.

Safety model

Classify every operation before acting. Full table in
references/airbnb-safety-rules.md.

Escalate to a human when: a send reaches unconfirmed or failed; you're
asked to perform any MUTATE op; the host browser identity reports unhealthy; two
read paths disagree on a material fact (dates, guest count, price); or you would
need to send the same message twice for any reason.

Message send — the state machine (the core procedure)

States: drafted → attempted → (confirmed | unconfirmed | failed). Full machine
with timings in references/airbnb-message-state-machine.md.

[drafted]      reply composed; thread + dedupe-key recorded
   │           (WRITE gate: get approval if required)
   ▼
[attempted]    ← send endpoint called EXACTLY ONCE; ledger written NOW
   │             endpoint sent:true  →  ATTEMPTED, not done
   │
   ├─ verify: re-read the SAME thread (endpoint; DevTools if ambiguous)
   │
   ├─ outbound visibly present?  ── yes ──► [confirmed]   ✅ report
   ├─ absent after verify window ── no  ──► [unconfirmed] ⚠️ DO NOT RESEND, escalate
   └─ send call errored                  ► [failed]       ❌ re-read first, escalate, no blind resend

Send procedure (follow exactly)

1. Read the live thread. Capture the last inbound message + a dedupe-key
   (thread_id + normalized hash of the draft text).
2. Check the send ledger. If a confirmed (or recent attempted) send with
   the same dedupe-key exists → STOP, already handled.
3. Draft the reply → state drafted.
4. Approval gate if required — present draft + thread context, wait for "go".
5. Send exactly once via the first-class send endpoint → state attempted.
   Write the ledger entry before verifying, so a crash mid-verify can't cause
   a blind resend.
6. Verify — re-read the thread, look for the outbound text/timestamp.
7. Confirm or not — visible → confirmed; absent within window →
   unconfirmed.
8. Report final status: thread id, state, and the human action needed.

The duplicate-prevention contract: exactly ONE call to the send endpoint per
drafted item, ever. unconfirmed/failed NEVER auto-transition to a new send.
Only a human, after reading the live thread, may authorize a retry.

Reservation & calendar (READ-only in v1)

• booking_summary — list reservations sorted by check-in: guest, dates,
  status, reservation_id, linked thread_id.
• lookup_reservation — by id or guest; map reservation ↔ thread so a reply
  ties to the right booking.
• inspect_calendar — report blocked/open/booked spans; FLAG (don't fix)
  high-risk states (double-booking, anomalous price, risky back-to-back gaps).

Calendar mutation, pricing, accept/decline, and listing edits are reserved for
v2 and get their own gated workflows mirroring the send machine
(read → propose → approve → do-once → verify → report). Until then: refuse +
escalate.

Command surface

Agents speak only in these verbs; each maps to a canonical procedure. Format is
verb (TIER) — description.

READ verbs (no gate):
- check_inbox (READ) — list threads needing attention, prioritized.
- read_thread <id> (READ) — full live thread + guest-intent summary.
- lookup_reservation <id-or-guest> (READ) — reservation details + linked thread.
- booking_summary (READ) — upcoming bookings, sorted by check-in.
- inspect_calendar [range] (READ) — calendar state + flagged risks.
- verify_sent <thread> <draft> (READ) — re-check a thread for an outbound message.

WRITE verbs (gated + verified):
- draft_reply <thread> <intent> (WRITE-pre) — produce a reviewable draft; result state drafted.
- send_reply <thread> <draft> (WRITE) — run the full send state machine.

Status:
- report_status — emit structured status of the last operation.

send_reply is the ONLY write, and it internally enforces
read → draft → approve → send-once → verify → report. Agents must not decompose
it into lower-level steps to skip verification.

Future adapter compatibility

This skill is the behavioral contract. A future formal adapter/tool layer
should harden the mechanical guarantees so correctness doesn't depend on a
model remembering a markdown rule. See references/future-adapter-interface.md.

Ideal future adapter functions (call them if present, fall back to the manual
procedure if not):

• airbnb.sendVerified(thread_id, text, dedupe_key) → returns
  {state, visible_at} after doing send-once + ledger + verify atomically.
• airbnb.dedupeCheck(dedupe_key) → {already_sent: bool, last_state}.
• airbnb.readThread(thread_id) / airbnb.listInbox() /
  airbnb.listReservations() / airbnb.readCalendar(range).

When sendVerified exists, send_reply delegates to it and simply reports the
returned state. When it doesn't, send_reply runs the manual procedure above.

Anti-patterns (do NOT do these)

• ❌ Jumping to Playwright early. Endpoints exist and are preferred; falling
  to Playwright because something felt slow once is wrong.
• ❌ Treating sent: true as confirmed. It's attempted. Always verify.
• ❌ Resending from unconfirmed. This creates duplicate guest messages.
  Escalate instead.
• ❌ "Auth must be dead." Missing local browser/session state is NOT proof —
  auth is host-owned. Check browser status + an endpoint first.
• ❌ Mixing read-safe and write-risk behavior. Classify every op; never let
  a read workflow quietly perform a write.
• ❌ Improvising the send flow per turn. There is exactly ONE send
  procedure. Use it.

Maintainer notes

• Customize per deployment: references/airbnb-tool-priority.md (map roles
  to real tool names), the approval-gate policy, and whether a persistent ledger
  is wired. Examples under examples/ are illustrative — adapt payloads to your
  tools.
• Keep universal: the Five Laws, the send state machine, the safety tiers,
  and the command vocabulary. These are the portable core; don't fork them per
  deployment.
• Evolving the skill: add new operations by giving each its own gated
  workflow in the same shape as the send machine. Never add a generic "do
  anything" write. Bump version; record changes in a CHANGELOG if published.