Zim

Agent travel middleware for searching flights, hotels, and car rentals, assembling policy-aware itineraries, managing traveler preferences, and preparing pay...

Security Scan

The package largely matches a travel middleware implementation, but there are multiple inconsistencies (registry vs SKILL.md), an embedded prompt-injection pattern, and runtime instructions that create persistent state and call external LLM/search/payment services — review carefully before installing or enabling.

Purpose & Capability

The code and SKILL.md implement the advertised travel middleware (flight/hotel/car search, itinerary assembly, Stripe Checkout integration, WhatsApp handler). Requested binaries (python3, bash, curl, jq) and Python deps are appropriate for this functionality. However, the registry metadata claims 'Required env vars: none' while SKILL.md and code require several sensitive environment variables (TRAVELPAYOUTS_TOKEN, TRAVELPAYOUTS_MARKER, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, OPENROUTER_API_KEY, SERPAPI_KEY). That mismatch between declared registry requirements and the actual package contents is an incoherence worth flagging.

Instruction Scope

SKILL.md + SETUP.md instructs actions beyond simple search: it documents symlinking the skill into ~/.openclaw/skills, a wrapper script (scripts/zim-wa.sh) that execs into the Python WhatsApp handler, and a persistent SQLite state at data/whatsapp_state.db. The QA scripts explicitly call external LLMs (OPENROUTER_API_KEY) and live search APIs. Those runtime instructions will cause outbound network calls, persist conversation state locally, and rely on sensitive env vars. Additionally, a prompt-injection pattern ('ignore-previous-instructions') was detected inside SKILL.md, which could indicate an attempt to influence evaluation or agent behavior. Together these widen the runtime surface and should be reviewed before use.

Install Mechanism

There is no formal install spec in the registry (skill treated as instruction-only), yet a full Python package (pyproject.toml) and many source files are included. The package expects installation (python3 -m pip install . is documented). This is not inherently malicious, but the absence of an explicit install spec / automated installer in the registry metadata is an inconsistency that can confuse users and lead to accidental execution of code without a controlled install process.

Credentials

The environment variables required by the code and SKILL.md (TRAVELPAYOUTS_TOKEN, TRAVELPAYOUTS_MARKER, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, OPENROUTER_API_KEY, SERPAPI_KEY, ZIM_BASE_URL) are relevant to the described functionality (affiliate searches, deeplinks, Stripe Checkout, external LLM). However: (1) the registry lists no required env vars, (2) several sensitive credentials are needed and would grant outbound API access if set, and (3) test/production key guidance is present but could be overlooked (e.g., do not accidentally set live Stripe keys). The number and sensitivity of env vars is proportionate to the feature set, but the mismatched metadata and the potential for misuse (live payments, LLM calls) are concerning.

Persistence & Privilege

The skill does not request 'always: true' and does not attempt to modify other skills. It does, however, document persistent local state (SQLite DB at data/whatsapp_state.db) and suggests symlinking into the user's OpenClaw skills directory and restarting the gateway for discovery. Those steps require filesystem changes and will make the skill persistent within the user's OpenClaw environment. This is expected for aWhatsApp-style agent but is an action that should be done deliberately and under supervision.

Scan Findings in Context

[ignore-previous-instructions] unexpected: A prompt-injection phrase was detected in SKILL.md. This is not expected in an operational README/instructions and could be an attempt to influence the agent's or evaluator's behavior. Treat SKILL.md content carefully and validate there are no other injected directives that alter agent decision-making.

What to consider before installing

What to check before installing or enabling this skill: - Confirm provenance: the registry lists no homepage and the source is 'unknown'. Only enable code from sources you trust. - Verify environment variables: the package needs several sensitive keys (TRAVELPAYOUTS_TOKEN, TRAVELPAYOUTS_MARKER, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, OPENROUTER_API_KEY, SERPAPI_KEY). Do not supply production Stripe keys unless you understand and have tested payment flows; prefer test keys (sk_test_...) and restrict their use to an isolated environment. - Don’t run the QA scripts or orchestrator with live keys unless you intend to make outbound calls to LLM/search APIs — these scripts call external services and may consume quota or leak keys in logs. - Inspect and sandbox before install: because the package contains executable Python code and shell wrappers, consider installing and running it inside a contained environment (dedicated VM or container) and do a code review of entry points (scripts/zim-wa.sh, scripts/zim-whatsapp-handler.py, zim/__main__.py, zim/orchestrator.py, zim/llm_agent.py, etc.). - Be cautious about symlinking into ~/.openclaw/skills or auto-registering: that will make the skill discoverable and runnable by agents; only do this after you’ve reviewed how the wrapper sets env vars and where it persists state (data/whatsapp_state.db). - Investigate the prompt-injection signal: search SKILL.md and other files for hidden or injected directives (phrases like 'ignore previous instructions') and remove or sanitize them before enabling autonomous invocation. - If you need narrower exposure: avoid setting LLM or payment keys in the environment; run the skill in read-only or demo mode, or stub out network calls until you validate behavior. If you want, I can: (a) list files that reference specific env vars (so you can audit where secrets are used), (b) extract exact lines where the prompt-injection pattern appears, or (c) suggest a minimal safe runtime command to exercise the package without enabling payments/LLM calls.

Zim — Agent Travel Middleware

Use Zim as a travel workflow engine, not a generic search helper. Accept structured or messy travel intent, apply policy and traveler preferences, assemble coherent booking-ready options, and state clearly what is and is not automated.

What this package contains

This skill package includes:

• SKILL.md — operating instructions for the skill
• scripts/search-flights.sh — Travelpayouts/Aviasales flight search with cached-fare fallback
• scripts/search-hotels.sh — hotel deeplink generation for live availability lookup
• scripts/search-cars.sh — car rental comparison deeplinks
• references/api-guide.md — API/deeplink notes for Travelpayouts and related links
• references/agent-to-agent-booking.md — product model and truthfulness rules
• zim/ — Python package implementing:
  • travel models and itinerary assembly
  • policy / approval logic
  • traveler preference storage
  • CLI commands (zim flights, zim hotels, zim cars, zim trip, zim preferences, zim policy)
  • booking state machine and local booking persistence
  • Stripe Checkout session creation for payment collection
  • placeholder booking executor that does not complete real supplier reservations
• tests/ — package tests
• pyproject.toml — Python package metadata and dependency declarations

Do not describe this package as shell scripts only. It contains both shell helpers and a Python application.

Runtime requirements

Require all of the following when using or publishing this skill:

• Python 3.10+
• Standard shell environment for bundled scripts
• Installed command-line tools used by the shell scripts:
  • bash
  • curl
  • jq
  • python3
• Python packages declared by the package metadata / environment:
  • pydantic>=2.0
  • click>=8.0
  • httpx>=0.25
  • python-dateutil
  • stripe>=8.0
• Optional dev/test packages when running tests:
  • pytest>=7.0
  • pytest-asyncio>=0.21
  • respx>=0.21

If a downstream environment expects requirements.txt, generate it from the package metadata or install from pyproject.toml. This package currently declares dependencies in pyproject.toml, not in a checked-in requirements.txt file.

Required environment variables

Declare these explicitly when using the skill:

Variable	Required	Purpose
TRAVELPAYOUTS_TOKEN	Yes for flight/hotel affiliate search	Travelpayouts / Aviasales token used for API access and affiliate attribution
TRAVELPAYOUTS_MARKER	Yes for production affiliate attribution consistency	Affiliate marker identifier for Travelpayouts deeplinks and tracking
STRIPE_SECRET_KEY	Yes for payment flow	Stripe secret key used to create and retrieve Checkout Sessions
STRIPE_WEBHOOK_SECRET	Yes for webhook verification in deployed payment flow	Stripe webhook signature secret
ZIM_BASE_URL	No	Base URL for Stripe success/cancel redirects; defaults to http://localhost:8000

Important notes:

• TRAVELPAYOUTS_TOKEN enables the current search scripts.
• TRAVELPAYOUTS_MARKER should be treated as required configuration for a production deployment even if some current scripts reuse the token as a marker fallback.
• STRIPE_SECRET_KEY should be sk_test_... in the current beta/test setup.
• Live Stripe mode is not a default assumption.

External services and API dependencies

Zim depends on these external services:

Travelpayouts / Aviasales

Used for:

• flight search API calls
• affiliate deeplink generation
• hotel affiliate/search deeplinks

Stripe

Used for:

• hosted Checkout Session creation
• payment status retrieval
• webhook-based payment confirmation flows

Linked booking/search destinations

Zim may generate outbound deeplinks to:

• Aviasales
• Hotellook
• Booking.com
• Google Hotels
• Kayak
• Discover Cars
• Rentalcars.com
• Economy Bookings

These links are for comparison or manual completion unless a real provider executor is added.

Payment and booking boundaries

Be precise about what Zim does today.

Current payment state

• Stripe Checkout integration exists.
• Stripe is currently intended for test mode / MVP flows.
• Live mode requires a verified Stripe account plus proper operational setup.
• Do not imply live payment collection is production-ready unless that has actually been configured and verified.

Current booking execution state

• The bundled PlaceholderExecutor does not create real airline, hotel, or car rental reservations.
• Zim can create booking-ready options, approval summaries, and payment requests.
• After payment, actual provider reservation automation is still pending unless a real executor is added.
• Do not say booked in plain language unless supplier-side booking execution truly happened.

Preferred truthful language:

• booking-ready options assembled
• awaiting approval
• payment link created
• payment collected; provider reservation still requires execution/manual completion

Avoid false claims like:

• your trip is fully booked
• payment completed and reservation confirmed unless a real provider confirmation exists.

Payment-data disclosure

Zim includes payment orchestration via Stripe, but payment-card handling is intentionally limited.

• Zim creates Stripe Checkout Sessions server-side using STRIPE_SECRET_KEY.
• Zim stores Stripe session IDs, payment status, totals, and related booking metadata.
• Zim attaches booking metadata such as booking ID / trip ID to Stripe objects.
• Zim may prefill customer email into Stripe Checkout.
• Zim does not directly collect, process, or store raw card numbers, CVCs, or full payment method details in the current architecture.
• Card entry is intended to occur on Stripe-hosted checkout pages.
• Webhook verification requires STRIPE_WEBHOOK_SECRET in deployed flows.

Treat booking/payment metadata as sensitive operational data even though raw card data is not stored by the package.

Quick start

Shell scripts

# Flights
bash scripts/search-flights.sh LHR DXB 2025-12-15 2025-12-20 usd 5

# Hotels
bash scripts/search-hotels.sh "Dubai" 2025-12-15 2025-12-18 usd 10

# Cars
bash scripts/search-cars.sh "Dubai Airport" 2025-12-15 2025-12-18

Python CLI

# Install package locally
python3 -m pip install .

# Search flights
zim flights LHR DXB 2026-04-15 --return-date 2026-04-20 --cabin business

# Search hotels
zim hotels Dubai 2026-04-15 2026-04-20 --stars-min 4

# Search cars
zim cars "Dubai Airport" 2026-04-15 2026-04-20 --car-class suv

# Assemble full itinerary
zim trip LHR DXB 2026-04-15 --return-date 2026-04-20 --mode business --human

WhatsApp Conversational Agent

When handling travel messages on the WhatsApp channel, use the Zim WhatsApp agent for a smoother conversational experience with stateful multi-turn flows (search → select → confirm → book).

How to invoke

bash /home/ubuntu/.openclaw/workspace/zim/scripts/zim-wa.sh "<user message>" "whatsapp:<user_phone>"

This returns JSON: {"response": "...", "success": true/false}

Send the response text back to the user on WhatsApp.

Conversation flow

The WhatsApp agent maintains state per user automatically:

1. User sends a natural language travel request → agent returns search results
2. User replies with 1, 2, or 3 → agent shows selection summary, asks YES/NO
3. User says YES → agent returns booking confirmation + deeplink
4. User says CANCEL at any point → resets to fresh search

State persists across calls via SQLite, so multi-message conversations work.

When to use the WhatsApp agent vs direct CLI

• WhatsApp channel messages → use the WhatsApp agent (zim-wa.sh)
• Structured agent-to-agent requests → use the Python CLI (zim flights, zim hotels)
• Quick searches for non-chat contexts → use shell scripts (search-flights.sh)

Agent workflow

Parse into a structured travel object

Extract as many of these fields as possible:

Core trip fields

• traveler name / profile
• mode: business or personal
• origin city / airport
• destination city / airport
• departure date
• return date
• trip purpose
• total budget or category budgets

Flight fields

• cabin class
• direct only vs flexible
• airline preferences
• refundability / flexibility
• preferred departure window
• no red-eye preference

Hotel fields

• hotel style: luxury / boutique / business / budget
• star minimum
• nightly cap
• neighborhood / landmark / meeting proximity
• chain preference

Car fields

• pickup location
• dropoff location if different
• car type / class
• provider preference

Policy / workflow fields

• approval threshold
• vendor restrictions
• class restrictions
• location radius rule
• whether the agent is allowed to auto-book vs recommend only

If key fields are missing, ask only for the minimum needed to continue.

Convert city names to IATA codes before flight search where needed. Common defaults:

• London → LHR
• Dubai → DXB
• New York → JFK
• Paris → CDG
• Singapore → SIN
• Tokyo → HND/NRT

Convert dates to YYYY-MM-DD.

Business vs personal mode

Apply ranking differently by mode.

Business mode

• prioritize direct flights
• prefer refundable / flexible fares when possible
• keep hotels near the meeting area / business district
• enforce policy caps before presenting results
• optimize for time, reliability, and compliance over small savings

Personal mode

• prioritize price/value unless preferences override
• allow more creative routing
• surface boutique / character-rich stays when relevant
• optimize for experience and fit

Running searches

Use the Python CLI when you want structured JSON for agent consumption. Use shell scripts when you want simple direct output and live deeplinks.

Assemble an itinerary, not disconnected results

Default behavior is to combine flight + hotel + car into a coherent recommendation when the request implies a trip.

Preferred response structure:

1. Trip summary
2. Recommended flight
3. Recommended hotel
4. Recommended car (if relevant)
5. Why this is the best fit
6. Action state — booking-ready / approval-needed / missing info

Presenting results

Flights

• If structured results exist, list airline / route / price / dates / deeplink
• If exact-date results are unavailable, say so clearly and provide nearby cached fare context plus a live Aviasales search link

Hotels

• Present as live hotel search options or structured Python results depending on tool path used
• Explain relevance: proximity, style, business suitability, or value

Cars

• Present comparison links or structured Python results depending on tool path used
• If a car class or airport pickup was requested, say so explicitly

Approval and state handling

When total cost exceeds threshold or any item is out of policy, say approval is required.

When payment has not been started, say so. When payment link/session exists, say so. When provider execution is still placeholder/manual, say so.

Preference memory

Surface recurring preferences as durable travel preferences when relevant:

• preferred airlines
• seat preference
• no red-eye
• hotel style
• hotel star floor
• car class

Error handling

• If TRAVELPAYOUTS_TOKEN is not set, explain that affiliate-linked flight/hotel search cannot run.
• If STRIPE_SECRET_KEY is not set, explain that checkout session creation cannot run.
• If exact flight results are empty, use nearby cached fares plus a live Aviasales link.
• If hotel APIs are unreliable, prefer working deeplinks over fake structured listings.
• If an external API errors, report it plainly and preserve working manual paths.

References

Read these only when needed:

• API details and deeplink formats: references/api-guide.md
• Booking model / truthfulness guidance: references/agent-to-agent-booking.md