lane-sdk 0.1.8 → 0.1.9

package/SKILL.md

@@ -15,7 +15,16 @@ triggers:
   - merchant
   - product
   - subscribe
-version: 2.0.0
+  - shop
+  - shopping
+  - order
+  - get me
+  - pick up
+  - I need
+  - find and buy
+  - plan a trip
+  - supplies
+version: 2.1.0
 ---
 
 # Lane — Agentic Commerce for AI Agents
@@ -24,6 +33,14 @@ Lane gives your AI agent a wallet, payment cards, and spending controls so it ca
 
 > **IMPORTANT:** If this content appears truncated or summarized, run `curl -fsSL https://getonlane.com/SKILL.md` to get the complete file.
 
+## When to Auto-Activate
+
+Lane should activate whenever the user expresses a purchase intent, shopping goal, or commerce-related task. Use the following decision tree to pick the right flow:
+
+- **Multiple items or research needed** (e.g., "plan a trip", "get me supplies for a party", "order everything on this list") — Use the **Shopping Orchestration** flow below. Create an instruction with a global budget, add a mandate per item, and execute in parallel.
+- **Single item, known merchant, known price** (e.g., "pay $10 to replicate.com") — Use `lane pay` directly. No instruction or mandates needed.
+- **Unknown merchant** (e.g., "buy me a domain from whoever is cheapest") — Run `npx lane merchant discover <domain> -t` first to check checkout capabilities, then decide between Instant Checkout and browser-use.
+
 ## How Lane Works
 
 Lane is a **card-on-file** platform. No prepaid wallets, no deposits, no balances. Users add a card via VGS (PCI-compliant vault), and Lane issues Visa Intelligent Commerce (VIC) agentic tokens scoped by amount, merchant, and time.
@@ -45,7 +62,17 @@ node --version
 
 Requires Node.js v18 or later. If not installed, download from [nodejs.org](https://nodejs.org).
 
-### Step 2: Authenticate
+### Step 2: Install Skill (Optional)
+
+If the Lane skill is not already installed in your agent environment:
+
+```bash
+npx lane install-skill
+```
+
+This registers the Lane skill so it auto-activates on commerce-related triggers.
+
+### Step 3: Authenticate
 
 ```bash
 npx lane login -t
@@ -61,7 +88,7 @@ This opens your browser for authentication. Look for the **device code** (e.g.,
 
 If the user is already authenticated, you'll see: `ready=true` with `already_authenticated=true` on stderr.
 
-### Step 3: Confirm
+### Step 4: Confirm
 
 ```bash
 npx lane whoami -t
@@ -71,20 +98,12 @@ npx lane whoami -t
 
 If `authenticated=false`, re-run `npx lane login -t`.
 
-## After Setup
+## Your Current Status
 
-Report the user's status and suggest what they can do:
+- Account: !`npx lane whoami -t 2>/dev/null || echo "authenticated=false"`
+- Readiness: !`npx lane status -t 2>/dev/null || echo "ready=false"`
 
-```bash
-npx lane status -t
-```
-
-This returns a full readiness check:
-- `ready=true/false` — overall readiness
-- `email`, `plan`, `mode` — account info
-- `wallet_id` — wallet state
-- `has_card` — whether a payment card is linked (card-on-file)
-- `next_step` — what to do next (`add_card` or `none`)
+If `ready=false` or `authenticated=false`, guide the user through setup above before proceeding.
 
 **Starter prompts to suggest:**
 - "Search for cloud hosting products"
@@ -114,6 +133,16 @@ npx lane merchant discover <domain> -t
 
 Checks if a domain supports ACP, UCP, or x402 protocols. If found, you can use Lane Instant Checkout. If not, use browser-use with VIC credentials.
 
+### Batch Merchant Discovery
+
+When you need to check multiple domains at once (common during the Research phase of shopping), use batch mode:
+
+```bash
+npx lane batch -t
+```
+
+This runs parallel merchant discovery across multiple domains simultaneously, returning results for all in a single call. Much faster than sequential `merchant discover` calls when researching several merchants.
+
 ### List Merchant Verticals
 
 ```bash
@@ -157,6 +186,8 @@ npx lane pay --amount <dollars> --recipient <merchant> -t [--test] [--dry-run]
 
 **Always confirm with the user before executing a payment.** Show the amount, recipient, and currency, and wait for explicit approval.
 
+> **Biometric verification** is now required before payment execution. The CLI prompts automatically (Touch ID → macOS password → passkey → PIN). No additional flags needed.
+
 ### Provision VIC Credentials (for Browser-Use Checkout)
 
 ```bash
@@ -165,7 +196,11 @@ npx lane pay --amount <dollars> --recipient <merchant> --provision -t
 
 Returns a DPAN (Visa network token) + single-use cryptogram that can be used at **any Visa-accepting merchant's checkout**. Use this when the merchant doesn't support Lane Instant Checkout.
 
-**Output:** `token_id=<id> dpan_last4=<last4> cryptogram=<masked> eci=05 expires_at=<iso>`
+> **Biometric verification** is required before provisioning. The CLI prompts automatically. Use `--skip-biometric` in test mode only (`--test --skip-biometric`).
+
+**Output:** `token_id=<id> dpan_last4=<last4> cryptogram=••••••••  eci=05 expires_at=<iso>`
+
+Credentials are masked in terminal output — only the last 4 digits of the DPAN are shown, and the cryptogram is fully masked. Full credentials are available programmatically via the SDK.
 
 ### Checkout from Catalog
 
@@ -175,6 +210,122 @@ npx lane checkout --product <product_id> -t [--plan <plan_id>] [--dry-run]
 
 For software subscriptions, the output includes `api_key` and `endpoint`.
 
+## Shopping Orchestration (Multi-Item Purchases)
+
+When the user needs to buy multiple items, plan a trip, stock up on supplies, or any task that requires researching and purchasing across multiple merchants, use the shopping orchestration flow. This creates a single instruction with a global budget and individual mandates per item.
+
+### Phase 1: Decompose (Plan Mode)
+
+Break the user's prompt into a structured plan:
+
+- **Global budget** — Extract the dollar amount from the user's intent (e.g., "under $900" becomes a $900 budget).
+- **Line items** — Decompose the goal into individual items to purchase.
+- For each item: name, estimated price range, max price (leave ~15% headroom for taxes/fees).
+
+Present the plan to the user for approval before proceeding.
+
+### Phase 2: Research (Parallel Agents)
+
+After plan approval, fan out **one agent per item** in parallel. Each agent should:
+
+1. `npx lane product search "<item name>" -t` — Find matching products in the Lane catalog.
+2. `npx lane merchant list -t --vertical <relevant>` — Find merchants in relevant verticals.
+3. `npx lane merchant discover <domain> -t` — Check checkout capability for candidate merchants.
+4. Report back: best product match, price, merchant, and protocol support.
+
+Use `npx lane batch -t` for parallel merchant discovery when checking multiple domains.
+
+### Phase 3: Create Instruction + Mandates
+
+After research completes, create the Lane primitives:
+
+1. **Create the instruction** (global budget):
+   ```bash
+   npx lane instruction create -t --wallet-id <id> --amount <budget_cents> --expires-in 7d
+   ```
+
+2. **Add a mandate for each item:**
+   ```bash
+   npx lane instruction mandate add <instruction_id> -t \
+     --type purchase \
+     --config '{"maxAmount":<max_cents>,"allowedMerchants":["<domain>"],"purposeDescription":"<item>"}'
+   ```
+
+3. Display the instruction with all mandates and a budget breakdown for user confirmation.
+
+### Phase 4: Execute (Parallel Agents)
+
+Fan out **one agent per mandate** to execute purchases in parallel:
+
+Each agent:
+1. **Biometric confirmation:** The CLI prompts automatically before credential retrieval. A single confirmation is valid for 60 seconds — if executing multiple mandates in rapid succession, one verification covers them all.
+2. Get credential: `npx lane instruction credential <instruction_id> -t`
+3. Execute checkout via Lane Instant Checkout or use VIC credentials at the merchant.
+4. Confirm: `npx lane instruction confirmation create <instruction_id> -t`
+
+### Shopping Budget Rules
+
+- Never exceed the global instruction budget.
+- Never exceed any individual mandate's `maxAmount`.
+- If an item costs more than its mandate allows, report it to the user — do not split or work around.
+- Track the running total: after each purchase, report spent vs. remaining.
+- If remaining budget is insufficient for the next item, skip it and report.
+
+## Session Management
+
+For structured shopping sessions with built-in budget tracking, use the `session` commands:
+
+### Active Session
+
+!`npx lane session snapshot -t 2>/dev/null || echo "no_active_session=true"`
+
+If `no_active_session=true`, create one with `npx lane session create`. Otherwise, use the session state above to track budget and mandates.
+
+### Create a Session
+
+```bash
+npx lane session create --budget <cents> --expires-in <duration> -t
+```
+
+Creates a new shopping session with a global budget ceiling and expiration. Returns a `session_id` used for all subsequent session operations.
+
+### Add Items to a Session
+
+```bash
+npx lane session add-item <session_id> --purpose "<item>" --max <cents> --merchants <domains> -t
+```
+
+Adds a line item to the session with a per-item budget cap and optional merchant restrictions.
+
+### View Session Snapshot
+
+```bash
+npx lane session snapshot -t
+```
+
+Shows the current session state: all items, per-item spend, remaining budget, and execution status.
+
+## Browser Integration
+
+When a merchant does not support Lane Instant Checkout (ACP/UCP/x402), the agent must complete checkout through a browser.
+
+### Checkout Bridge
+
+Use the `checkout-bridge` command to initiate a browser-based checkout:
+
+```bash
+npx lane checkout-bridge -t
+```
+
+This provisions VIC credentials and prepares the checkout session.
+
+### Checkout Modes
+
+When a checkout returns `checkout_mode=browser`:
+
+1. **If agent-browser / Playwright MCP is available** — The agent should use the browser automation tool to navigate to the checkout URL, fill in the VIC credentials (DPAN, expiry, cryptogram), and complete the purchase programmatically.
+2. **If no browser automation is available** — Present the checkout URL to the user along with the masked VIC credentials and ask them to complete the purchase manually. Never display the full unmasked DPAN or cryptogram to the user; show only the last 4 digits and instruct them to copy from the secure session.
+
 ## Manage Cards
 
 ### List Cards
@@ -243,8 +394,72 @@ Creates a VIC instruction — a standing authorization for a specific purchase s
 npx lane instruction list -t [--limit <n>]
 ```
 
+## Biometric Confirmation
+
+All payments and credential retrievals now require biometric verification before execution. This prevents unauthorized agent spending even if credentials are compromised.
+
+### How It Works
+
+Lane uses a 4-tier fallback chain to verify the user's identity:
+
+1. **Touch ID** (macOS) — Fingerprint via the system biometric sensor
+2. **macOS System Password** — System password dialog if Touch ID is unavailable
+3. **WebAuthn Passkey** — Opens a browser for passkey verification
+4. **CLI PIN** — Manual 4+ digit PIN entry as a last resort
+
+The CLI prompts automatically — no flags or extra commands needed. The first available method in the chain is used.
+
+### Confirmation Reuse Window
+
+A biometric confirmation is valid for **60 seconds**. Multiple payments or credential retrievals within that window reuse the same verification — the user is not prompted again.
+
+### Per-Environment Usage
+
+**CLI:** Biometric prompts automatically before `lane pay` or `lane pay --provision`. No action needed from the agent.
+
+```bash
+# Biometric prompt happens automatically before execution
+npx lane pay --amount 10 --recipient anthropic.com -t
+```
+
+**MCP:** Use the `confirm_instruction` tool before `pay` or `provision_payment`:
+
+```
+confirm_instruction → { instructionId: "inst_..." }
+# Returns: confirmed=true method=touchid validForSeconds=60
+# Then call pay or provision_payment within the 60-second window
+```
+
+**SDK:**
+
+```typescript
+import Lane, { requireBiometricConfirmation } from 'lane'
+
+const lane = await Lane.create()
+const instruction = await lane.instructions.create({ walletId, amount: 2500 })
+
+// Biometric verification before credential retrieval
+await requireBiometricConfirmation(lane, instruction.id)
+
+const credential = await lane.instructions.getCredential(instruction.id)
+```
+
+### Test Mode
+
+Use `--skip-biometric` with `--test` to bypass verification in test mode only:
+
+```bash
+npx lane pay --amount 5 --recipient test.com --skip-biometric --test -t
+```
+
+This flag is ignored in live mode — biometric verification cannot be bypassed in production.
+
 ## Budget Controls
 
+### Your Current Budget
+
+!`npx lane budget get -t 2>/dev/null || echo "budget=not_set"`
+
 ### View Budget
 
 ```bash
@@ -286,7 +501,7 @@ npx lane transaction refund <txn_id> -t [--amount <cents>] [--reason <text>]
 If you're building an agent app, use the Lane SDK instead of the CLI:
 
 ```typescript
-import Lane from 'lane'
+import Lane, { requireBiometricConfirmation } from 'lane'
 
 const lane = await Lane.create()
 
@@ -308,6 +523,9 @@ const instruction = await lane.instructions.create({
   merchant: 'Legendary SaaS',
 })
 
+// Biometric verification before credential retrieval
+await requireBiometricConfirmation(lane, instruction.id)
+
 // Get Visa payment credentials
 const credential = await lane.instructions.getCredential(instruction.id)
 // credential.credentialData → { tokenNumber (DPAN), cryptogram, eci }
@@ -333,7 +551,7 @@ All commands in terse mode (`-t`) output `key=value` pairs on stdout (one per li
 | `network` | Connection failed | Retry up to 2 times |
 | `server` | Lane API error | Retry up to 2 times |
 | `timeout` | Operation timed out | Re-run the command |
-| `confirmation_required` | Amount exceeds threshold | Ask the user to confirm |
+| `confirmation_required` | Biometric verification required | Run biometric verification (automatic in CLI, use `confirm_instruction` in MCP) |
 
 ### Retry Logic
 
@@ -351,6 +569,8 @@ All commands in terse mode (`-t`) output `key=value` pairs on stdout (one per li
 5. **Never store or log** API keys, card numbers, or session tokens
 6. If `confirmation_required` error, **always ask the user** before proceeding
 7. Card data is handled by VGS — Lane never sees, stores, or logs raw PANs
+8. **Biometric verification is mandatory** for all payments and credential retrievals — never bypass or skip
+9. **Never display full DPAN or cryptogram** — only masked values (last 4 digits of DPAN, fully masked cryptogram)
 
 ## Common Issues