Airbnb Gateway

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 gate harder. Sending a message is approval-gated. Calendar mutations (nightly price, block/open dates) are permitted ONLY under the explicit per-operation approval gate below (see "Approved calendar mutations") and are ALWAYS verified after. Listing edits and accept/decline are NOT implemented — 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-RESTRICTED op, or a MUTATE-CAL op without the approval gate satisfied; 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.

---

Approved calendar mutations (v0.2)

Calendar blocks/opens and nightly-price changes are permitted ONLY when ALL of the following hold:

1. The operator (host) explicitly requested this specific operation in the current conversation — naming the exact date(s) or field and the desired end state.
2. The request carries the word APPROVED (or the operator replies APPROVE to your restatement of the operation). No approval word, no mutation — ask for it.
3. One operation per approval. Never batch beyond exactly what was named. Never generalize ("block June 16" does not mean "block that week").
4. Execute via the preferred tool order (native endpoint first, then agent-browser / DevTools per the tool-priority reference). For calendar mutations specifically, follow references/calendar-mutation-procedure.md step by step — it is the verified procedure; do not improvise.
5. Verify after, independently: re-read the calendar (fresh page state) and report before-state, action taken, after-state. If verification is ambiguous, report unconfirmed and STOP — never retry a mutation from ambiguous state.
6. Report reversibility: state the exact inverse operation so the operator can undo with one instruction.

Everything in MUTATE-RESTRICTED stays forbidden regardless of approval wording — escalate to the host instead.

Reservation & calendar reads

These three verbs are strictly READ (tier READ, no gate). They never change the calendar — reporting and flagging only:

• 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).

Changing the calendar (block/open dates, nightly price) is a separate, approval-gated MUTATE-CAL operation — see "Approved calendar mutations (v0.2)" above; it runs the read → propose → approve → do-once → verify → report shape and never happens as a side effect of a read. Accept/decline bookings and listing edits remain out of scope: 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 (READ) — full live thread + guest-intent summary.
• lookup_reservation (READ) — reservation details + linked thread.
• booking_summary (READ) — upcoming bookings, sorted by check-in.
• inspect_calendar [range] (READ) — calendar state + flagged risks.
• verify_sent (READ) — re-check a thread for an outbound message.

WRITE verbs (gated + verified):

• draft_reply (WRITE-pre) — produce a reviewable draft; result state drafted.
• send_reply (WRITE) — run the full send state machine.

Status:

• report_status — emit structured status of the last operation.

send_reply is the only guest-messaging write, and it internally enforces read → draft → approve → send-once → verify → report. Agents must not decompose it into lower-level steps to skip verification. Calendar mutation (MUTATE-CAL) is not a command verb here — it is the separate, approval-gated procedure in references/calendar-mutation-procedure.md (see "Approved calendar mutations (v0.2)"), which follows the same read → approve → do-once → verify → report shape.

---

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.