fluxa agentic checkout

What this skill does

# FluxA Agentic Checkout


**Skill version: 0.4.0** | **Product surface: deterministic checkout automation + explicit human handoff**

## Overview

Use this skill as the release-grade operator runbook for checkout automation. It accepts arbitrary entry links, attempts the currently implemented automation routes, and produces structured results that tell the next agent or human whether the checkout is ready, partially filled, blocked by verification, or requires manual takeover.

## How to do checkout for users

### Step 1: Check whether the URL supports automated checkout

1. Check whether the user has provided a specific product URL. If not, ask the user for the exact product link they want to buy.
2. Check whether the link falls within the currently supported automation scope. This skill is positioned as a general checkout automation skill and should determine whether there is an executable automation path for the given link. If the merchant or checkout flow is outside the currently executable scope, the skill should clearly tell the user that they need to complete the purchase manually and provide a direct link they can open.
3. If the link is supported, tell the user: "This item supports automated checkout. We can help autofill the checkout information and guide you through the purchase. I’m starting the checkout automation now."

### Step 2: Check the checkout skill execution environment
1. Check the environment. The skill must run in an environment that supports Playwright, and Chromium must be installed. Check whether `python-dotenv`, `socksio`, `playwright`, and related dependencies are already installed. If they are missing, install them first. See the `Environment setup` section for the setup steps.
2. Before installing the environment, tell the user: "To complete the automated checkout, we need to install a few required tools and the browser runtime. This may take a few minutes. I’m starting the setup now."

### Step 3: Collect the user's checkout information and generate the profile
1. Read the `Collect the user's shipping information` section and check whether the user already has a JSON file containing payment, delivery, and billing information. If not, guide the user to provide that information.
2. If the information already exists, confirm the shipping address for this purchase with the user again.

### Step 4: Run the checkout script in preview and execute modes
1. Before starting, tell the user: "I’m starting the checkout automation now. I’ll begin in preview mode so I can autofill the checkout information without submitting the order."

2. Use the user-provided `entry-url` and the generated profile JSON file to run `checkout_playwright_handoff.py` in `preview` mode first, so you can confirm that the automation flow runs correctly and fills the required information.

```bash
python3 scripts/checkout_playwright_handoff.py \
  --entry-url "https://shophomeplace.myshopify.com/products/gift-card" \
  --mode preview \
  --secrets-path /data/workspace/.clawdbot/credentials/real_card.json \
  --resident-id-number "<required only when the merchant asks for it>" \
  --out-dir artifacts/checkout-preview \
  --headless \
  --record-video
```

3. If `preview` succeeds, send the screenshots and video to the user so they can review the automated checkout preview, and tell the user: "The automated checkout preview completed successfully, and the checkout information has been filled in. Please confirm that the delivery information is correct. If everything looks right, we can proceed with the final checkout step."

   Do not delete screenshots, traces, videos, or result JSON files under the local `artifacts/` directory by default. They are part of the audit trail and manual handoff record for checkout continuation.
   Only clean up local artifacts if the user explicitly asks for cleanup, or explicitly asks to delete sensitive files among them.

4. If the page contains a required checkbox for legal consent, privacy authorization, cross-border transfer, or other local regulatory requirements, do not check it on the user's behalf by default. First ask for the user's explicit consent in natural language. Only after the user clearly agrees should you add `--confirm-legal-consent` to the command.

5. If the user confirms that the delivery information is correct, run `checkout_playwright_handoff.py` in `execute` mode for the final checkout attempt. When using the standard unified profile that includes `delivery`, you should usually add `--confirm-delivery`; otherwise the script will refuse to run.
```bash
python3 scripts/checkout_playwright_handoff.py \
  --entry-url "https://gracie-designs.myshopify.com/products/gift-card" \
  --mode execute \
  --secrets-path "$HOME/.clawdbot/credentials/real_card.json" \
  --confirm-delivery \
  --confirm-legal-consent \
  --order-label "Gracie Designs Gift Card" \
  --order-currency USD
```

6. When the flow is unsupported or blocked, speak to the user in plain language.
   Do not answer with internal labels like `unsupported_provider` or `needs_manual_verification` only.
   If the checkout page is already open but automation still cannot safely continue, return the live product or checkout link immediately so the user can finish manually.
   Preferred wording:

```text
This merchant's current checkout flow is not yet within the validated automation scope of FluxA Agentic Checkout, so you will need to complete this purchase manually for now.
You can open the link below to continue the purchase:
<product-or-checkout-url>
```

7. Query the local paid-order ledger when needed.

```bash
python3 scripts/order_manager.py get --order-id CHK-1774977424895
python3 scripts/order_manager.py list --limit 20
python3 scripts/order_manager.py search --keyword "gift card"
python3 scripts/order_manager.py summary --days 30
```

8. Judge the next action from the JSON result, not from transient browser logs.
   Use `phase`, `provider`, `handoffRequired`, `handoffReason`, `contactFilled`, `deliveryFilled`, `billingIdentityFilled`, `postalFilled`, `paymentFieldVerification`, `legalConsentChecked`, and `filledCheckoutScreenshot`.
   If `handoffRequired=true`, stop automation and pass the active context to a human operator instead of inventing a fallback flow.

## Product Capabilities

| Capability | What it does now | When to use |
|------------|------------------|-------------|
| **Checkout Routing** | Accepts entry links and chooses the validated checkout route automatically | The caller already has a product, cart, or checkout URL |
| **Deterministic Filling** | Fills supported contact, delivery, billing identity, postal, and card fields on currently supported surfaces | The caller wants a stable, replayable automation path instead of free-form browsing |
| **Profile Setup** | Collects payment, delivery, and billing details into one reusable JSON credential file | The caller needs a repeatable setup flow before preview or execute |
| **Operator Handoff** | Emits structured handoff states instead of faking unsupported automation | Verification or merchant-specific steps block safe continuation |
| **Artifacts & State** | Saves JSON results, screenshots, traces, and optional video for inspection | The caller needs auditability, debugging, or clean manual continuation |
| **Order Management** | Stores successful paid checkout records inside the skill and exposes lookup commands | The caller needs a local ledger of paid orders after execute-mode success |

## Current Implementation Status

Use this section as the product truth. Do not claim support beyond it.

### Implemented now

1. **Standard storefront checkout navigation via Playwright**
   - Accepts product, collection, cart, or direct checkout pages on currently validated storefront routes
   - Navigates into checkout with deterministic actions
   - Fills contact and delivery fields when the checkout presents a shipping step
   - Supports `preview` and `execute`
2. **Hosted checkou