@ouro.bot/cli 0.1.0-alpha.55 → 0.1.0-alpha.551

package/skills/browser-navigation.md

@@ -0,0 +1,117 @@
+# Browser Navigation Skill
+
+When to use browser tools and how to navigate effectively.
+
+## When to Use Browser Tools
+
+Use browser navigation when:
+- The target site has no API (e.g., Airbnb, VRBO, travel blogs)
+- Content is dynamic or requires JavaScript rendering
+- Login-required pages need session-based access
+- You need to verify visual content (screenshots, layouts)
+- Price comparison requires real-time scraping
+
+Do NOT use browser tools when:
+- A dedicated API or MCP server exists (prefer `weather_lookup`, Duffel MCP, etc.)
+- The data is available via a public JSON endpoint
+- The task can be completed with `web_search`
+
+## Stealth Browsing Best Practices
+
+The `@playwright/mcp` server is configured with realistic user-agent and viewport settings. To avoid detection on travel sites:
+
+- **Add delays between navigations**: Wait 2-5 seconds between page loads. Never hammer requests in rapid succession.
+- **Vary timing**: Use random delays rather than fixed intervals (e.g., 2-5s, not exactly 3s every time).
+- **Avoid predictable patterns**: Don't navigate the same path repeatedly in short succession.
+- **Use realistic scroll behavior**: Scroll gradually through pages rather than jumping to specific elements.
+- **Respect robots.txt**: Check for rate limits and crawling restrictions.
+
+## Navigation Workflow
+
+Follow this pattern for every page interaction:
+
+1. **Navigate**: Use `browser_navigate` to load the page
+2. **Wait**: Allow the page to fully load (use `browser_wait` if needed)
+3. **Snapshot**: Take a `browser_snapshot` to understand the page structure
+4. **Extract**: Parse the accessibility tree for relevant data
+5. **Screenshot** (optional): Use `browser_screenshot` for visual confirmation
+
+## Form Filling Patterns
+
+### Login Flows
+1. Navigate to the login page
+2. Take a snapshot to identify form fields
+3. Use `browser_type` for username/password fields
+4. Use `browser_click` to submit
+5. Wait for redirect, then verify login succeeded via snapshot
+6. NEVER hardcode credentials -- use `credential_get` to retrieve login info
+
+### Sign-up Flows
+1. Use `credential_generate_password` to mint a strong password for the target domain
+2. Fill the signup form with that password
+3. If the site rejects the password policy, generate a new one that matches the site rules
+4. Once the site accepts the exact password, call `credential_store` immediately
+5. Do not claim a new credential is saved until `credential_store` succeeds
+
+### Search Forms (Hotels, Flights, Rentals)
+1. Navigate to the search page
+2. Snapshot to identify input fields
+3. Fill location/date fields with `browser_type`
+4. Select options with `browser_select_option` or `browser_click`
+5. Submit the search
+6. Wait for results to load (travel sites often have loading animations)
+7. Snapshot the results page to extract listings
+
+### Booking Forms
+1. **ALWAYS confirm with the user before proceeding to payment**
+2. Fill traveler information
+3. Use stored credentials for payment (via `credential_get` -- NEVER type raw card numbers)
+4. Screenshot the final review page for user confirmation
+5. Only click "Book" / "Confirm" after explicit user approval
+
+## Anti-Bot Detection Avoidance
+
+The stealth configuration handles most fingerprinting automatically. Additionally:
+
+- **Don't access detection endpoints**: Avoid URLs containing "captcha", "challenge", "verify"
+- **Handle CAPTCHAs**: If you encounter a CAPTCHA, pause and inform the user. Do not attempt automated solving.
+- **Rotate viewport sizes occasionally**: Use different viewport sizes across sessions
+- **Maintain cookies**: Use persistent `user-data-dir` to appear as a returning user
+- **Avoid headless tells**: The user-agent is set to a real browser string
+
+## Travel Site Patterns
+
+### Airbnb / VRBO
+1. Search by location + check-in/check-out dates + guests
+2. Results load dynamically -- scroll to load more listings
+3. Extract: title, price per night, total price, rating, number of reviews
+4. For detailed info, click into each listing and snapshot
+5. Compare top 3-5 options
+
+### Hotel Sites (Booking.com, Hotels.com)
+1. Search by destination + dates + guests + rooms
+2. Filter by price range, star rating, amenities
+3. Extract: name, price, location, rating, key amenities
+4. Check cancellation policies (important for travel planning)
+
+### Flight Comparison
+1. Prefer Duffel MCP for flight search (structured API data)
+2. Use browser only if Duffel doesn't cover the airline
+3. Google Flights is useful for price comparison but requires careful navigation
+
+## Error Handling
+
+- **Page timeouts**: Retry once after 5 seconds. If still failing, inform the user.
+- **CAPTCHAs**: Stop and ask the user to solve manually.
+- **Stale elements**: Re-snapshot the page and retry the interaction.
+- **Blocked/403**: The site may have detected automation. Wait 30 seconds and try with a different approach (e.g., direct URL instead of navigation).
+- **Session expired**: Re-login using stored credentials.
+
+## Human Confirmation Gates
+
+**ALWAYS** confirm with the user before:
+- Any booking or payment action
+- Entering personal information (name, address, phone)
+- Agreeing to terms of service
+- Subscribing to any service
+- Any action that creates a financial obligation

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

package/skills/configure-dev-tools.md

@@ -0,0 +1,101 @@
+# Configure Dev Tools for MCP Agent Bridge
+
+Set up your development tools (Claude Code, Codex) to communicate with Ouroboros agents via MCP. One command does everything — including cross-platform WSL2 bridging on Windows.
+
+## Setup
+
+### Claude Code
+
+```bash
+ouro setup --tool claude-code --agent <agent-name>
+```
+
+This command:
+1. Registers the MCP server with Claude Code via `claude mcp add`
+2. Configures lifecycle hooks (SessionStart, Stop, PostToolUse) for passive awareness
+3. Detects dev vs installed mode automatically and uses the correct command path
+
+**On WSL2 (Windows):** The command automatically detects the WSL environment and:
+- Calls `claude.exe` (the Windows binary) instead of `claude`
+- Prefixes MCP serve and hook commands with `wsl` so Windows-side Claude Code spawns them through WSL
+- Resolves the Windows-side home directory and writes config to the Windows-side `~/.claude/`
+- After setup, open Claude Code in PowerShell — the agent is there
+
+**On native Windows (no WSL):** Not yet supported. The command prints a message directing you to install WSL2.
+
+For the full cross-machine setup flow (including cloning an agent to a new machine), see `docs/cross-machine-setup.md` in the harness repo.
+
+### Codex
+
+```bash
+ouro setup --tool codex --agent <agent-name>
+```
+
+This command:
+1. Registers the MCP server with Codex via `codex mcp add`
+2. Detects dev vs installed mode automatically
+
+## Verification
+
+After setup, verify the connection:
+
+1. **Check daemon is running**: `ouro up` (installed) or `ouro dev --repo-path <path>` (dev mode).
+2. **Test from Claude Code**: Start a new session and use the `status` tool.
+3. **Test from Codex**: Run `codex exec "Use the <agent-name> status tool"`.
+4. **Check registration**: `claude mcp list` or `codex mcp list`.
+
+## Available MCP Tools
+
+Once connected, these tools are available:
+
+### Conversation tools (new)
+- **send_message** -- Send a message and get a synchronous agent response (full turn with tools)
+- **check_response** -- Check for pending messages from the agent (after ponder or proactive surface)
+
+### Read-only tools
+- **ask** -- Ask the agent a question (uses diary, journal, and context)
+- **status** -- Get agent's current status and activity
+- **catchup** -- Get recent activity summary
+- **get_context** -- Get agent's current working context
+- **search_notes** -- Search the agent's diary for specific topics
+- **get_task** -- Get details of the agent's current task
+- **check_scope** -- Verify if something is in scope for current work
+- **check_guidance** -- Get guidance on how to approach something
+
+### Write tools
+- **delegate** -- Request the agent to handle a task (runs full conversation turn)
+- **request_decision** -- Ask agent to make a decision about something
+- **report_progress** -- Report progress on delegated work
+- **report_blocker** -- Report a blocker on delegated work
+- **report_complete** -- Report completion of delegated work
+
+## Troubleshooting
+
+### "Daemon not running" error
+Most read-only tools work without the daemon (reads filesystem directly). For write operations and `send_message`, start the daemon with `ouro up` or `ouro dev`.
+
+### MCP server not appearing
+- Run `claude mcp list` or `codex mcp list` to verify registration
+- Re-run `ouro setup` to fix
+- Restart your dev tool (MCP loads at session start)
+
+### Connection timeouts
+- Ensure `dist/` is built: `npm run build`
+- Check that the entry point path is correct (setup auto-detects this)
+
+### WSL2-specific issues
+
+**`claude.exe` not found** — Windows executables must be accessible from WSL. This is the default, but enterprise environments may disable it via `/etc/wsl.conf` setting `appendWindowsPath = false`. Check with `which claude.exe`. If missing, add Claude Code's install directory to WSL's PATH manually or update `wsl.conf`.
+
+**`cmd.exe` or `wslpath` fails** — The setup command resolves the Windows home directory using `cmd.exe /C echo %USERPROFILE%` piped through `wslpath`. If either is unavailable, the setup will fail. `wslpath` ships with all standard WSL distributions. `cmd.exe` requires Windows executables to be on PATH (see above).
+
+**MCP server hangs or returns empty** — The MCP server runs inside WSL via `wsl ouro mcp-serve --agent <name>`. If stdio piping between Windows and WSL is broken, check that the WSL distribution is running (`wsl --status`) and that no other process has claimed stdin.
+
+**Hooks not firing** — Claude Code hooks use `wsl ouro hook <event> --agent <name>`. If hooks fail silently, check that `ouro` is on PATH inside WSL (run `wsl ouro --version` from PowerShell to verify).
+
+### Removing
+```bash
+claude mcp remove ouro-<agent-name>
+# or
+codex mcp remove ouro-<agent-name>
+```

package/skills/travel-planning.md

@@ -0,0 +1,138 @@
+# Travel Planning Skill
+
+Compose all travel infrastructure to plan and book trips effectively.
+
+## Research Phase
+
+### Destination Research
+1. Use `geocode_search` to find candidate destinations and get coordinates
+2. Use `weather_lookup` to check climate for travel dates
+3. Use `travel_advisory` to check US State Dept safety levels (1-4):
+   - Level 1: Exercise Normal Precautions
+   - Level 2: Exercise Increased Caution
+   - Level 3: Reconsider Travel
+   - Level 4: Do Not Travel
+4. Use browser tools (see `browser-navigation` skill) for destination reviews, travel blogs, local tips
+5. Compare multiple destinations on weather, safety, cost, and flight availability
+
+### Information Gathering Workflow
+```
+geocode_search -> get coordinates
+weather_lookup -> check weather at coordinates
+travel_advisory -> check safety level
+browser tools -> reviews, local info, pricing
+```
+
+## Flight Search
+
+### Using Duffel MCP (when available)
+- Search via `duffel_search_flights` tool (first-class MCP tool)
+- Provide: origin, destination, dates, passengers, cabin class
+- Compare options on price, duration, stops, airline
+
+### Using Browser (fallback)
+- Use browser-navigation skill patterns for Google Flights, airline sites
+- Add delays between searches to avoid detection
+
+### Comparison Criteria
+Present top 3-5 options comparing:
+- Total price (including bags, seat selection)
+- Duration and number of stops
+- Airline and aircraft
+- Departure/arrival times
+- Cancellation/change policy
+
+## Accommodation Search
+
+### Hotel Search
+- Use Expedia MCP when available (`expedia_search_hotels` tool)
+- Compare: price per night, total stay cost, location, rating, amenities
+- Check cancellation policies (crucial for travel planning)
+
+### Vacation Rentals (Browser-based)
+- Use browser-navigation skill for Airbnb/VRBO
+- Search by location, dates, guests, budget
+- Compare: price, location proximity, reviews, amenities, host rating
+- Screenshot listings for user review
+
+### Comparison Criteria
+- Price per night and total cost
+- Location (distance to key attractions/activities)
+- Reviews and ratings
+- Amenities (WiFi, kitchen, parking, pool)
+- Cancellation flexibility
+
+## Booking Workflow
+
+### Critical Safety Gates
+- **ALWAYS confirm with user before any booking action**
+- **ALWAYS confirm before entering payment information**
+- **ALWAYS confirm before agreeing to terms**
+- **Never proceed with a financial commitment without explicit approval**
+
+### Credential Handling
+
+Credentials are managed through the credential access layer, which stores
+agent-owned secrets in the agent's Bitwarden/Vaultwarden credential vault.
+Stored passwords stay in the vault. A brand-new signup password may enter
+model context briefly when the agent explicitly generates or types it during
+an interactive sign-up flow.
+
+- Use `credential_get` to check what credentials exist for a domain (metadata only, never passwords)
+- Use `credential_generate_password` to mint a strong password for a new sign-up
+- Use `credential_store` to save credentials the agent acquired after the site accepts them
+- The credential gateway automatically injects secrets into API requests via `getRawSecret()`
+- Use browser-navigation skill form patterns for entering credentials during interactive sessions
+
+**How credentials work:**
+- Agent-owned credentials live in the agent's Bitwarden/Vaultwarden vault
+- Travel credentials such as Duffel and Stripe are ordinary vault credential items
+- The agent can sign up for services and store its own credentials
+- Existing stored passwords are never returned to the model — only metadata (domain, username, notes)
+
+### Post-Booking
+- Save confirmation details (confirmation number, dates, hotel name, airline, booking reference)
+- Save to diary/journal for future reference
+- Set reminders for check-in windows
+- Note cancellation deadlines
+
+## Preference Management
+
+### Storing Preferences
+Track and reference these travel preferences:
+- Preferred airlines and alliance status
+- Preferred hotel chains and loyalty numbers
+- Seat preferences (window/aisle, extra legroom)
+- Dietary needs for in-flight meals
+- Budget ranges (per night for hotels, per flight)
+- Must-have amenities (WiFi, gym, pool)
+
+### Using Preferences
+- Reference stored preferences when searching
+- Apply airline preferences to flight comparisons
+- Apply hotel brand preferences to accommodation searches
+- Adjust budget ranges based on destination
+
+## Tool Reference
+
+### Native Tools (always available)
+- `weather_lookup` - Current weather and daily forecast by city or coordinates (Open-Meteo, zero config)
+- `travel_advisory` - US State Dept advisory by country code
+- `geocode_search` - Location/POI search with coordinates
+- `credential_get` - Check credential metadata for a domain (never returns passwords)
+- `credential_generate_password` - Generate a strong password for a new sign-up (family trust)
+- `credential_store` - Store credentials the agent acquired (family trust)
+- `credential_list` - List stored credential domains
+- `credential_delete` - Delete stored credentials (family trust)
+
+### MCP Tools (when configured)
+- Browser tools via `@playwright/mcp` - see `browser-navigation` skill
+- Duffel flight search (when MCP server available)
+- Expedia hotel search (when MCP server available)
+
+### Human Confirmation Required For
+- Any booking or payment
+- Entering personal information
+- Agreeing to terms of service
+- Creating financial obligations
+- Sharing credentials with third parties