@ouro.bot/cli 0.1.0-alpha.237 → 0.1.0-alpha.239

package/skills/commerce-setup-guide.md

@@ -0,0 +1,116 @@
+# Commerce Setup Guide
+
+Human-facing guide for configuring the agent's commerce capabilities.
+
+## Architecture Overview
+
+The agent's commerce system has three pillars:
+
+1. **User Profile**: Secure storage of personal data (name, passport, payment preferences) in Vaultwarden, accessed only when needed for specific transactions.
+
+2. **Booking Delegation**: Direct API access to flight (Duffel) and hotel (LiteAPI) booking systems, plus browser automation fallback for sites without APIs.
+
+3. **Payment**: Stripe Issuing virtual cards created per-transaction, with spend limits and merchant category restrictions. Card numbers never enter the model's context.
+
+## Setup Steps
+
+### 1. Stripe Issuing (Required for Payments)
+
+- Create a Stripe account: https://dashboard.stripe.com
+- Enable Stripe Issuing (requires business verification)
+- Create a restricted API key: https://dashboard.stripe.com/apikeys
+  - Permissions needed: `issuing_cards:write`, `issuing_cards:read`
+- Store in vault: `credential_store stripe.com --password <key>`
+
+### 2. Duffel (Flights)
+
+- Create a Duffel account: https://app.duffel.com
+- Generate a sandbox token: https://app.duffel.com/tokens
+- Store in vault: `credential_store duffel.com --password <token>`
+
+### 3. LiteAPI (Hotels)
+
+- Create a LiteAPI account: https://dashboard.liteapi.travel
+- Get your sandbox API key
+- Store in vault: `credential_store liteapi.travel --password <key>`
+- Configure MCP server in agent.json (see commerce-setup.md skill for details)
+
+### 4. User Profile
+
+Store your travel profile with the agent:
+```
+user_profile_store '{"legalName":{"first":"...","last":"..."},"email":"...","phone":"...","preferences":{}}'
+```
+
+## Tool Reference
+
+### User Profile Tools
+| Tool | Description | Trust Level |
+|------|-------------|-------------|
+| `user_profile_store` | Store/update profile fields | Family |
+| `user_profile_get` | Retrieve a specific profile field | Family |
+| `user_profile_delete` | Delete entire profile | Family |
+
+### Payment Tools
+| Tool | Description | Trust Level |
+|------|-------------|-------------|
+| `stripe_create_card` | Create a virtual card | Family |
+| `stripe_deactivate_card` | Deactivate a card | Family |
+| `stripe_list_cards` | List active cards | Family |
+
+### Flight Tools
+| Tool | Description | Trust Level |
+|------|-------------|-------------|
+| `flight_search` | Search for flights | Friend |
+| `flight_hold` | Hold a flight offer | Family |
+| `flight_book` | Book a flight | Family |
+| `flight_cancel` | Cancel a booking | Family |
+
+### Hotel Tools
+Hotels are accessed through the LiteAPI MCP server. Tools are dynamically registered when the MCP server connects. Common tools include search, get rates, and book.
+
+## Security Model
+
+### Credential Gateway
+All API keys are stored in the agent's Vaultwarden vault. They are never exposed as environment variables or stored in config files. MCP servers receive credentials at startup via `vault:` env resolution.
+
+### Card Number Isolation
+Virtual card numbers exist only within the Stripe client's internal functions during a payment flow. They are never:
+- Returned to the model in tool outputs
+- Included in nerves events or logs
+- Stored in any persistent state
+- Shown in chat messages
+
+The model only sees card IDs (e.g., `ic_...`) and last-4 digits.
+
+### Trust Gating
+- **Family trust required**: All profile, payment, and booking tools
+- **Friend trust sufficient**: Flight search (read-only, no payment)
+- **Stranger/acquaintance**: No commerce access
+
+### Vault Resolution Failures
+When a `vault:` reference cannot be resolved for an MCP server:
+- The specific server is skipped (not crashed)
+- Other servers continue to start normally
+- An error event is emitted with the specific resolution failure
+- Error messages are actionable (e.g., "item not found", "field empty")
+
+## Verification Tiers
+
+### Tier 1: Real-Tested
+- User profile vault CRUD (tested against live Vaultwarden)
+- MCP credential injection (tested with real `vault:` env resolution)
+- Tool registration and guardrail enforcement
+
+### Tier 2: Mocked
+- Stripe Issuing API calls (mocked SDK)
+- Duffel flight API calls (mocked HTTP)
+- LiteAPI hotel API calls (MCP config only)
+- Full booking flow (profile -> search -> card -> book -> confirm -> deactivate)
+- Card number leakage verification
+
+### Post-Handoff
+- Real Stripe Issuing card creation (requires live Stripe account with Issuing)
+- Real Duffel booking (requires live API key)
+- Real LiteAPI hotel search (requires live MCP server)
+- Browser automation for Pattern B sites

package/skills/commerce-setup.md

@@ -0,0 +1,84 @@
+# Commerce Setup Wizard
+
+Step-by-step guide for setting up the agent's commerce infrastructure: payment, booking, and accommodation APIs.
+
+last_verified: 2026-04-06
+
+## Prerequisites
+
+- Agent vault must be set up (run `vault_setup` tool if not done)
+- Vault must be reachable at the configured server URL
+
+## Step 1: Stripe Issuing (Payments)
+
+1. Create a Stripe account at https://dashboard.stripe.com
+2. Enable Stripe Issuing (requires business verification)
+3. Create a restricted API key at https://dashboard.stripe.com/apikeys
+   - Enable only `issuing_cards:write` and `issuing_cards:read` permissions
+4. Store the key in the vault: `credential_store stripe.com --password <restricted_key> --notes "Stripe Issuing restricted key"`
+
+### Verification
+Run `stripe_list_cards` to verify the key works. Expected: empty list or existing cards.
+
+## Step 2: Duffel (Flights)
+
+1. Create a Duffel account at https://app.duffel.com
+2. Generate a sandbox API token at https://app.duffel.com/tokens
+   - Start with sandbox mode for testing
+   - Switch to live mode when ready for real bookings
+3. Store the key in the vault: `credential_store duffel.com --password <api_token> --notes "Duffel API token (sandbox)"`
+
+### Verification
+Run `flight_search` with any route (e.g., SFO to JFK). Expected: list of flight offers.
+
+## Step 3: LiteAPI (Hotels)
+
+1. Create a LiteAPI account at https://dashboard.liteapi.travel
+2. Get your sandbox API key from the dashboard
+3. Store the key in the vault: `credential_store liteapi.travel --password <api_key> --notes "LiteAPI sandbox key"`
+4. Configure the MCP server in agent.json:
+   ```json
+   {
+     "mcpServers": {
+       "liteapi": {
+         "command": "npx",
+         "args": ["tsx", "src/index.ts"],
+         "cwd": "/path/to/liteapi-mcp-server",
+         "env": {
+           "LITEAPI_API_KEY": "vault:liteapi.travel/apiKey"
+         }
+       }
+     }
+   }
+   ```
+
+### Verification
+The LiteAPI MCP server will start automatically when the agent boots. Check agent logs for `mcp.connect_end` event for the liteapi server.
+
+## Step 4: User Profile
+
+Store the human's travel profile:
+```
+user_profile_store '{"legalName": {"first": "...", "last": "..."}, "email": "...", "phone": "...", "preferences": {}}'
+```
+
+Optional but recommended fields: dateOfBirth, passport, driverLicense, addresses, loyaltyPrograms.
+
+## Self-Test
+
+After setup, run the commerce self-test to verify all services:
+- Stripe: creates and deactivates a test virtual card
+- Duffel: runs a test flight search
+- LiteAPI: verifies the API key is stored in the vault
+
+The self-test reports per-service health with actionable error messages:
+- "Flights working, hotels not yet -- LiteAPI key missing."
+- "Your Duffel key returned 401. Verify it at app.duffel.com/tokens."
+
+## Security Model
+
+- All API keys stored in the agent's Vaultwarden vault (not env vars)
+- Card numbers never appear in model context or logs
+- Virtual cards are single-use by default, deactivated after each transaction
+- User profile access requires family trust level
+- Vault credentials are resolved at MCP server startup, not at runtime