# Solace Browser Integration
# Source: solaceagi.com/agents/claude.md | Updated: 2026-03-04

## What Solace Is
Solace Browser is a Chromium fork with a native Yinyang sidebar. It is NOT a browser extension.
Solace Hub starts first, launches Yinyang Server on port 8888, and controls the browser lifecycle.
Agents connect to the local webservice or MCP boundary exposed by that Hub-managed runtime.
- Recipes: replayable workflows at $0.001/task (no LLM tokens on replay)
- Sessions: cookies + auth tokens survive across tasks (log in once, reuse forever)
- Evidence: every action is hash-chained, ALCOA+ compliant, FDA Part 11 ready
- YinYang: real-time AI companion on every page (top rail + bottom rail + notifications)
- MCP: 8 tools available via Model Context Protocol (stdio JSON-RPC 2.0)

## Quick Start
```bash
# Check if running
curl -s http://localhost:8888/api/status | python3 -c "import sys,json; d=json.load(sys.stdin); ready = bool(d.get('running')) or d.get('status') in ('ready','ok','healthy'); print('OK' if ready else 'NOT RUNNING')"
# Preferred: start Solace Hub first. Hub starts Yinyang Server, then controls Browser.
~/projects/solace-browser/scripts/start-hub.sh

# Developer fallback for server-only testing:
python3 ~/projects/solace-browser/yinyang-server.py --port 8888 --headless
```

## Auth (OAuth3)
Local runtime tokens are minted by the Hub-owned runtime itself:
```bash
curl -X POST http://localhost:8888/oauth3/token \
  -H "Content-Type: application/json" \
  -d '{"user_id":"local-agent","scopes":["browser.navigate","browser.click","browser.fill","browser.screenshot","browser.evaluate"],"ttl_seconds":300}'
# Then include: -H "Authorization: Bearer <token>" on action calls.
```

Cloud tokens on solaceagi.com use a separate contract:
```bash
# Mint a cloud bearer from your paid API key
curl -X POST https://solaceagi.com/api/v1/oauth3/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"sw_sk_..."}'

# Mint a scoped vault token for sync/storage APIs
curl -X POST https://solaceagi.com/api/v1/oauth3/tokens \
  -H "Authorization: Bearer sw_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"scopes":["files.read","files.write"]}'
# Response field is "token" — send it back as: X-OAuth3-Token: o3_...
```


## Core API

### Navigate
```bash
curl -X POST http://localhost:8888/api/navigate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOLACE_TOKEN" \
  -d '{"url": "https://example.com", "wait_for": "networkidle"}'
```

### Click
```bash
curl -X POST http://localhost:8888/api/click \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOLACE_TOKEN" \
  -d '{"selector": "#submit-button"}'
```

### Fill
```bash
curl -X POST http://localhost:8888/api/fill \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOLACE_TOKEN" \
  -d '{"selector": "input[name=email]", "value": "user@example.com"}'
```

### Screenshot (saves to artifacts/)
```bash
curl -X POST http://localhost:8888/api/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOLACE_TOKEN" \
  -d '{"full_page": true}'
# Response: {"filepath": "artifacts/screenshot-YYYYMMDD-HHMMSS.png", "size": N}
```

### Evaluate JavaScript
```bash
curl -X POST http://localhost:8888/api/evaluate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOLACE_TOKEN" \
  -d '{"expression": "document.title"}'
```

### ARIA Snapshot (structured page understanding)
```bash
curl http://localhost:8888/api/aria-snapshot \
  -H "Authorization: Bearer $SOLACE_TOKEN"
# Returns JSON accessibility tree — best for understanding page structure
```

### Page Snapshot (DOM + ARIA + metadata)
```bash
curl http://localhost:8888/api/page-snapshot \
  -H "Authorization: Bearer $SOLACE_TOKEN"
# Returns combined structured snapshot for robust verification loops
```

### Response Contract (critical)
```bash
# Do not trust HTTP status alone.
# Parse JSON and require success == true before next step.
# Some runtimes may return HTTP 200 with an error payload.
# Good: {"success": true, ...}
# Failure: {"error": "Page.fill: Timeout 30000ms exceeded."}
```

## MCP Integration (Model Context Protocol)
```json
# Add to .claude/settings.json:
{
  "mcpServers": {
    "solace": {
      "command": "python3",
      "args": ["/path/to/solace-browser/yinyang_mcp_server.py"]
    }
  }
}
```
Then use natively: `solace:navigate()`, `solace:screenshot()`, `solace:evaluate()`, etc.
8 tools available. Every MCP call is OAuth3-scoped and SHA-256 evidenced.

## Evidence
Every action is SHA-256 captured automatically to the Solace audit directory.
Evidence location: ~/.solace/audit/
Verify: `python3 src/audit/chain.py verify ~/.solace/audit/<bundle_dir>`

## Best Practices
1. Always screenshot BEFORE clicking (creates evidence of what agent saw)
2. Use /api/aria-snapshot for page structure; /api/screenshot for visual layout
3. Request minimal OAuth3 scopes (read-only if possible)
4. Set budget_usd on every token (hard-stop on cost overrun)
5. Treat any response without {"success": true} as a failed step
6. Use /agents.json as canonical contract (not /api/agents.json)

## Pricing
- Free: BYOK, community recipes, local-only
- Starter: $8/mo — cloud twin + private store + managed LLM
- Pro: $28/mo — OAuth3 vault + 90-day evidence + managed LLM
- Team: $88/mo — team tokens + shared recipes + cloud sync
- Enterprise: $188/mo — SOC2 audit + dedicated nodes + white-label
- Replay: $0.001/task after first successful run