catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/browser/agent-workspace/domain-skills/zillow/scraping.md

@@ -0,0 +1,433 @@
+# Zillow — Scraping & Data Extraction
+
+Field-tested against `www.zillow.com` on 2026-04-18 using `http_get` (no browser).
+
+## Quick summary
+
+- **Search listing pages (`/homes/`, `/sold/`, `/rentals/`)** — `http_get` works with full Chrome headers. Returns ~973 KB HTML with all listing data embedded in `__NEXT_DATA__` JSON.
+- **Individual property detail pages (`/homedetails/`)** — `http_get` returns **HTTP 403** unconditionally. No header combination bypasses this.
+- **Internal API endpoints** (`/async-create-search-page-state`, `/graphql/`) — **403** for all server-side requests regardless of headers.
+- **Redfin** — `http_get` works; HTML contains both JSON-LD per listing and a stingray JSON API.
+
+---
+
+## What works: search listing pages via `__NEXT_DATA__`
+
+Zillow search pages embed all listing data in `<script id="__NEXT_DATA__">`. This is standard Next.js SSR output — it is the same data Zillow's React app hydrates from.
+
+**Required headers** — The single-word User-Agent (`"Mozilla/5.0"`) used by `http_get` internally gets 403. You must pass a full Chrome UA plus Accept/Accept-Language headers:
+
+```python
+import re, json
+from helpers import http_get
+
+HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+def extract_listings(html):
+    """Parse Zillow __NEXT_DATA__ and return list of listing dicts."""
+    m = re.search(r'<script id="__NEXT_DATA__"[^>]*>(.*?)</script>', html, re.DOTALL)
+    if not m:
+        return []
+    d = json.loads(m.group(1))
+    sps = d['props']['pageProps']['searchPageState']
+    return sps['cat1']['searchResults']['listResults']
+
+html = http_get("https://www.zillow.com/homes/San-Francisco,-CA_rb/", headers=HEADERS)
+listings = extract_listings(html)
+print(len(listings))  # 41 — always 41 per page
+```
+
+### Fields available in each listing card
+
+The `listResults` array is the canonical source. Each entry includes:
+
+| Field | Source | Example |
+|---|---|---|
+| `zpid` | listing | `15081707` |
+| `address` | listing | `"212 Spruce St, San Francisco, CA 94118"` |
+| `addressStreet`, `addressCity`, `addressState`, `addressZipcode` | listing | split address components |
+| `price` | listing | `"$4,395,000"` (formatted string) |
+| `unformattedPrice` | listing | `4395000` (int, use for math) |
+| `beds` | listing | `4` |
+| `baths` | listing | `4` |
+| `area` | listing | `4133` (sqft) |
+| `latLong` | listing | `{'latitude': 37.78867, 'longitude': -122.45361}` |
+| `statusType` | listing | `"FOR_SALE"` / `"FOR_RENT"` / `"RECENTLY_SOLD"` |
+| `detailUrl` | listing | full `https://www.zillow.com/homedetails/...` URL |
+| `zestimate` | listing | `4857200` (Zillow AI estimate, int) |
+| `imgSrc` | listing | thumbnail URL |
+| `has3DModel` | listing | `True`/`False` |
+| `hasOpenHouse` | listing | `True`/`False` |
+| `openHouseStartDate`, `openHouseEndDate` | listing | ISO strings |
+| `isFeaturedListing` | listing | sponsored/featured flag |
+| `brokerName` | listing | `"Sotheby's International Realty"` |
+| `statusText` | listing | `"FOR SALE"` display string |
+| `hdpData.homeInfo.price` | nested | raw price int (matches `unformattedPrice`) |
+| `hdpData.homeInfo.zestimate` | nested | raw zestimate int |
+| `hdpData.homeInfo.rentZestimate` | nested | monthly rent estimate |
+| `hdpData.homeInfo.homeType` | nested | `"SINGLE_FAMILY"`, `"CONDO"`, `"TOWNHOUSE"` etc. |
+| `hdpData.homeInfo.daysOnZillow` | nested | int |
+| `hdpData.homeInfo.taxAssessedValue` | nested | int |
+| `hdpData.homeInfo.lotAreaValue` + `lotAreaUnit` | nested | e.g. `2957.724`, `"sqft"` |
+| `hdpData.homeInfo.priceForHDP` | nested | reliable sold price for recently-sold listings |
+
+```python
+# Full extraction snippet
+listing = listings[0]
+hi = listing.get('hdpData', {}).get('homeInfo', {})
+
+record = {
+    "zpid":         listing['zpid'],
+    "address":      listing['address'],
+    "price_raw":    listing.get('unformattedPrice') or hi.get('price'),
+    "beds":         listing.get('beds'),
+    "baths":        listing.get('baths'),
+    "sqft":         listing.get('area'),
+    "lat":          listing['latLong']['latitude'],
+    "lon":          listing['latLong']['longitude'],
+    "status":       listing['statusType'],
+    "zestimate":    listing.get('zestimate'),
+    "rent_zest":    hi.get('rentZestimate'),
+    "home_type":    hi.get('homeType'),
+    "days_listed":  hi.get('daysOnZillow'),
+    "tax_assessed": hi.get('taxAssessedValue'),
+    "url":          listing['detailUrl'],
+}
+```
+
+### Total result count and pagination
+
+```python
+d = json.loads(re.search(r'<script id="__NEXT_DATA__"[^>]*>(.*?)</script>', html, re.DOTALL).group(1))
+sps = d['props']['pageProps']['searchPageState']
+
+# Total listings in this search
+total = sps['categoryTotals']['cat1']['totalResultCount']
+print(total)  # 1037
+
+# Each page returns exactly 41 listings. Add /<N>_p/ for subsequent pages:
+# Page 2: https://www.zillow.com/homes/San-Francisco,-CA_rb/2_p/
+# Page 3: https://www.zillow.com/homes/San-Francisco,-CA_rb/3_p/
+
+max_pages = (total + 40) // 41
+```
+
+### Scrape all pages
+
+```python
+import re, json, time
+from helpers import http_get
+
+HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+def get_listings(city_slug, page=1):
+    """city_slug: e.g. 'San-Francisco,-CA', 'Seattle,-WA', 'Austin,-TX'"""
+    if page == 1:
+        url = f"https://www.zillow.com/homes/{city_slug}_rb/"
+    else:
+        url = f"https://www.zillow.com/homes/{city_slug}_rb/{page}_p/"
+    html = http_get(url, headers=HEADERS)
+    m = re.search(r'<script id="__NEXT_DATA__"[^>]*>(.*?)</script>', html, re.DOTALL)
+    d = json.loads(m.group(1))
+    sps = d['props']['pageProps']['searchPageState']
+    total = sps['categoryTotals']['cat1']['totalResultCount']
+    listings = sps['cat1']['searchResults']['listResults']
+    return listings, total
+
+all_listings = []
+listings, total = get_listings("San-Francisco,-CA")
+all_listings.extend(listings)
+
+max_pages = (total + 40) // 41
+for page in range(2, min(max_pages + 1, 6)):   # cap at 5 pages for demo
+    time.sleep(1.0)   # polite delay
+    page_listings, _ = get_listings("San-Francisco,-CA", page)
+    all_listings.extend(page_listings)
+
+print(f"Fetched {len(all_listings)} of {total} listings")
+```
+
+---
+
+## URL patterns that work (all confirmed)
+
+| URL pattern | Status | Notes |
+|---|---|---|
+| `/homes/{city}_rb/` | **Works** | For-sale listings |
+| `/homes/{city}_rb/{N}_p/` | **Works** | Pagination |
+| `/homes/for_sale/{city}/0-1800000_price/` | **Works** | Price filter (max) |
+| `/homes/3-_beds/{city}/` | **Works** | Bed count filter |
+| `/homes/{zip}_rb/` | **Works** | ZIP code search |
+| `/san-francisco-ca/rentals/` | **Works** | Rental listings |
+| `/san-francisco-ca/sold/` | **Works** | Recently sold |
+| `/homedetails/{address}/{zpid}_zpid/` | **403** | Single property detail |
+| `/async-create-search-page-state` | **403** | Internal search API |
+| `/graphql/` | **400/403** | GraphQL endpoint |
+
+---
+
+## Rental listings
+
+Rental search pages use the same `__NEXT_DATA__` structure. However, rental listing cards have a **different schema** — individual units are nested, not a flat price:
+
+```python
+html = http_get("https://www.zillow.com/san-francisco-ca/rentals/", headers=HEADERS)
+listings = extract_listings(html)
+
+r = listings[0]
+# Multi-unit buildings:
+# r['units'] = [{'price': '$3,485+', 'beds': '0', 'roomForRent': False}, ...]
+# r['minBaseRent'] = 3485
+# r['maxBaseRent'] = 7130
+# r['availabilityCount'] = 23
+
+# Single-unit rentals:
+# r['price'] = '$2,500/mo'
+# r['unformattedPrice'] = 2500
+
+# Check which type:
+if r.get('isBuilding'):
+    price_range = f"${r['minBaseRent']}–${r['maxBaseRent']}/mo"
+    units = r.get('units', [])
+else:
+    price = r.get('unformattedPrice') or r.get('hdpData', {}).get('homeInfo', {}).get('price')
+```
+
+---
+
+## Sold listings
+
+Sold pages (`/sold/`) work identically. Key difference: `statusType` is `"RECENTLY_SOLD"` and price comes from `hdpData.homeInfo.priceForHDP` (not the `price` field which is `None` in sold cards):
+
+```python
+html = http_get("https://www.zillow.com/san-francisco-ca/sold/", headers=HEADERS)
+listings = extract_listings(html)
+
+for l in listings:
+    hi = l.get('hdpData', {}).get('homeInfo', {})
+    sold_price  = hi.get('priceForHDP')      # actual sold price
+    zestimate   = hi.get('zestimate')
+    tax_value   = hi.get('taxAssessedValue')
+    print(l['address'], f"${sold_price:,}", f"zest=${zestimate}")
+# 999 Green St APT 1702, San Francisco, CA 94133 $3,200,000 zest=$3,403,400
+# 1041 Vallejo St, San Francisco, CA 94133 $6,250,000 zest=None
+```
+
+Total sold inventory in San Francisco: **18,109** (all time in Zillow's database, paginated 41/page).
+
+---
+
+## Bot detection behavior
+
+- **Zillow detects bot status server-side** and embeds `window.__USER_SESSION_INITIAL_STATE__` and `props.isBot` in the page.
+- In field testing, the page returned `isBot: False` with the Chrome User-Agent — **Zillow does not block the search pages**.
+- The page does embed `captcha` strings in the HTML (for the CAPTCHA challenge widget code), but the challenge is NOT triggered for search pages.
+- **`/homedetails/` pages do trigger blocking** — every property detail URL tested returned HTTP 403. This is enforced before serving HTML, not via JavaScript CAPTCHA.
+- Rate limiting: 3 rapid sequential requests to `/homes/` all succeeded. Observed no 429s. Add `time.sleep(0.5–1.0)` between pages as a courtesy.
+
+---
+
+## What you do NOT get from `http_get`
+
+Because property detail pages are blocked (403), you lose:
+
+- Full property description text
+- All listing photos (you only get `imgSrc` thumbnail from search)
+- Detailed home facts (year built, parking, HVAC, school scores)
+- Price history
+- Nearby comparable sales (comps)
+- Agent contact info
+
+**To get these**, you must navigate to the `/homedetails/` URL in a browser session. The browser is not blocked (Zillow relies on JS challenges and fingerprinting that only trigger in browser context).
+
+---
+
+## Alternative: Redfin (field-tested, more accessible)
+
+Redfin allows `http_get` with no blocking for both HTML pages and its internal API.
+
+### Redfin JSON-LD per listing (easiest)
+
+Each Redfin search results page embeds one `<script type="application/ld+json">` per listing with structured property data:
+
+```python
+import re, json
+from helpers import http_get
+
+HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+html = http_get(
+    "https://www.redfin.com/city/17151/CA/San-Francisco/filter/property-type=house",
+    headers=HEADERS
+)
+print(len(html))  # ~1.6 MB
+
+# Extract all SingleFamilyResidence JSON-LD entries
+properties = []
+for s in re.findall(r'<script type="application/ld\+json">(.*?)</script>', html, re.DOTALL):
+    try:
+        d = json.loads(s)
+        if isinstance(d, list):
+            for item in d:
+                if item.get('@type') in ('SingleFamilyResidence', 'House', 'Residence', 'Apartment'):
+                    properties.append(item)
+    except Exception:
+        pass
+
+prop = properties[0]
+print("Name:", prop['name'])               # "662 Hampshire St, San Francisco, CA 94110"
+print("Address:", prop['address'])
+# {'@type': 'PostalAddress', 'streetAddress': '662 Hampshire St',
+#  'addressLocality': 'San Francisco', 'addressRegion': 'CA',
+#  'postalCode': '94110', 'addressCountry': 'US'}
+print("Rooms:", prop['numberOfRooms'])     # 3
+print("Floor size:", prop['floorSize'])    # {'@type': 'QuantitativeValue', 'value': 3350, 'unitCode': 'FTK'}
+print("URL:", prop['url'])
+# https://www.redfin.com/CA/San-Francisco/662-Hampshire-St-94110/home/1533754
+```
+
+Note: The JSON-LD schema does NOT include price (Redfin omits `offers` from the LD+JSON). Use the stingray API below for price.
+
+### Redfin stingray API (structured JSON with price)
+
+Redfin's internal GIS/search API returns rich structured data including price, MLS ID, beds, baths, sqft, agent info, and remarks. Responses are prefixed with `{}&&` — strip it before parsing:
+
+```python
+import json
+from helpers import http_get
+
+def redfin_search(region_id, region_type=6, num_homes=20, page=1, uipt="1,2,3,4,5,6"):
+    """
+    region_type: 6=city, 2=zipcode, 5=county
+    uipt: property types (1=house, 2=condo, 3=townhouse, 4=multi-family, 5=land, 6=other)
+    """
+    url = (
+        f"https://www.redfin.com/stingray/api/gis"
+        f"?al=1&num_homes={num_homes}&ord=redfin-recommended-asc"
+        f"&page_number={page}&region_id={region_id}&region_type={region_type}"
+        f"&sf=1,2,3,5,6,7&status=9&uipt={uipt}&v=8"
+    )
+    raw = http_get(url, headers={
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        "Referer": "https://www.redfin.com/",
+        "Accept": "*/*",
+    })
+    # Strip the {}&& CSRF prefix Redfin prepends to all API responses
+    assert raw.startswith('{}&&'), f"Unexpected prefix: {raw[:10]}"
+    return json.loads(raw[4:])
+
+data = redfin_search(region_id=17151)  # 17151 = San Francisco, CA
+homes = data['payload']['homes']
+
+home = homes[0]
+print("Address:", home['streetLine']['value'])  # "875 California St #703"
+print("City/State/Zip:", home['city'], home['state'], home['zip'])
+print("Price:", home['price']['value'])          # 3300000
+print("Beds:", home['beds'])                     # 3
+print("Baths:", home['baths'])                   # 2.5
+print("Sqft:", home['sqFt']['value'])            # 1828
+print("$/sqft:", home['pricePerSqFt']['value'])  # 1805
+print("Lot size:", home['lotSize']['value'])      # 9448
+print("Year built:", home['yearBuilt']['value'])  # 2021
+print("Days on market:", home['dom']['value'])    # 1
+print("MLS ID:", home['mlsId']['value'])          # "426115342"
+print("MLS Status:", home['mlsStatus'])           # "Active"
+print("Lat/Long:", home['latLong']['value'])
+print("URL:", home['url'])                        # "/CA/San-Francisco/..."
+print("Remarks:", home['listingRemarks'][:100])
+```
+
+### Redfin region IDs
+
+| City | region_id | region_type |
+|---|---|---|
+| San Francisco, CA | `17151` | `6` (city) |
+| Los Angeles, CA | `17152` | `6` |
+| New York, NY | `17834` | `6` |
+| Seattle, WA | `16163` | `6` |
+
+To find other region IDs: search on Redfin, look at the URL (e.g. `/city/17151/CA/San-Francisco`) — the number is the region_id.
+
+### Redfin stingray response structure
+
+```
+data['payload']['homes'][i]
+  .streetLine.value      → street address string
+  .city / .state / .zip  → strings
+  .price.value           → int (asking price in dollars)
+  .sqFt.value            → int (square feet)
+  .pricePerSqFt.value    → int
+  .beds                  → int
+  .baths                 → float (2.5 = 2 full + 1 half)
+  .fullBaths / .partialBaths → ints
+  .lotSize.value         → int (sq ft)
+  .yearBuilt.value       → int
+  .dom.value             → days on market (int)
+  .mlsId.value           → MLS listing number (string)
+  .mlsStatus             → "Active", "Pending", etc.
+  .listingId             → Redfin internal int
+  .propertyId            → Redfin internal int
+  .latLong.value         → {'latitude': float, 'longitude': float}
+  .url                   → relative URL "/CA/San-Francisco/..."
+  .listingRemarks        → description text (may be truncated)
+  .keyFacts              → [{'description': str, 'rank': int}]
+  .listingTags           → ['SWEEPING CITY VIEWS', ...]
+  .hoa.value             → HOA monthly (int)
+  .location.value        → neighborhood name string
+  .sashes                → [{'sashTypeName': 'New'/'Price Drop'/...}]
+  .photos.value          → photo token string
+  .numPictures           → int
+```
+
+---
+
+## Alternative APIs (no scraping required)
+
+If you need property data without scraping Zillow or Redfin at scale:
+
+| API | Free tier | Key data |
+|---|---|---|
+| **ATTOM Data** (attomdata.com) | Trial available | Ownership, AVM, tax, sale history, building characteristics |
+| **Rentcast** (rentcastapi.com) | 50 req/mo free | Rental estimates, comps, market data |
+| **RapidAPI: Zillow56** | ~100 req/mo free | Wraps Zillow data (unofficial, use at own risk) |
+| **HouseCanary** | Paid | AVM, market risk, rental value |
+| **Redfin API** (unofficial, above) | Unlimited | MLS listing data |
+| **US Census / HUD** | Free, no key | Median home values by geography, affordability |
+
+---
+
+## Gotchas
+
+- **Single User-Agent word triggers 403.** `http_get` passes `"Mozilla/5.0"` as default User-Agent — this gets blocked. Always pass the full Chrome UA via the `headers=` argument.
+
+- **`price` field is `None` for sold and rental multi-unit listings.** Use `unformattedPrice` for for-sale, `hdpData.homeInfo.priceForHDP` for sold, and `minBaseRent`/`maxBaseRent` for rentals.
+
+- **`/homedetails/` is unconditionally blocked.** Tested with full browser headers, Referer, Sec-Fetch-* headers — all return HTTP 403. Only the browser bypasses this.
+
+- **41 listings per page, hardcoded.** Zillow always returns exactly 41 results per page from `listResults`. `mapResults` was empty in all tests (server-side response only).
+
+- **`isBot: False` doesn't mean you're safe.** Zillow correctly identifies server-side requests and blocks `/homedetails/`. The `isBot` flag in `__NEXT_DATA__` is `False` for search pages but the restriction is enforced at route level for detail pages.
+
+- **Captcha strings in HTML do not mean CAPTCHA is active.** The search page includes the captcha widget JavaScript (for lazy loading if needed) but does not serve a challenge — confirmed by successfully parsing listing data from the same HTML.
+
+- **Redfin `{}&&` prefix on all API responses.** Strip with `raw[4:]` before `json.loads()`. If the prefix changes, the assertion fails explicitly.
+
+- **Redfin JSON-LD omits price.** The `SingleFamilyResidence` schema objects do not include an `offers` field — use the stingray API for pricing.
+
+- **Redfin stingray API returns all listing fields wrapped in `{'value': X, 'level': N}` dicts.** Always read `.value` for numeric fields (e.g. `home['price']['value']`, not `home['price']`). Level `1` means data is public; `2` means potentially restricted.
+
+- **Zillow total count can exceed 800 but pagination caps at page ~20.** Zillow caps search results at around 800 listings even if `totalResultCount` shows 1037. Narrow by ZIP code, neighborhood, or price range to stay within bounds.
+
+- **URL filter syntax for Zillow:** Beds: `3-_beds` prefix; price: `0-1800000_price` suffix; ZIP: use `{zip}_rb` instead of city slug. Test by building the URL in a browser and copying the pattern.

package/dist/extensions/builtin/browser/browser.md

@@ -0,0 +1,73 @@
+---
+name: browser
+description: Direct browser control via Catui's built-in Browser Harness. Use when the user wants to automate, scrape, test, or interact with web pages.
+---
+
+# Browser Harness
+
+Catui includes a vendored Browser Harness CDP bridge. Use the `browser` tool for normal work and `browser_admin` or `/browser` for install, setup, and diagnostics.
+
+For current facts or general web research, prefer Catui's `web_search` tool first. If the user already has a target URL and only needs the content, prefer `web_fetch`. Use `browser` when the task requires interacting with a page.
+
+## Core Tool Shape
+
+```json
+{
+  "code": "new_tab('https://example.com')\nwait_for_load()\nprint(page_info())",
+  "timeout": 120
+}
+```
+
+Common helpers are pre-imported inside the Python snippet:
+
+- `new_tab(url)`, `goto_url(url)`, `wait_for_load()`, `page_info()`
+- `capture_screenshot(...)`
+- `click_at_xy(x, y)`, `type_text(text)`, `press_key(key)`, `scroll(x, y)`
+- `js(expression)`, `cdp(method, **params)`, `drain_events()`
+- `list_tabs()`, `switch_tab(target)`, `current_tab()`, `ensure_real_tab()`
+- `upload_file(selector, path)`, `http_get(url, headers=None)`
+- Remote helpers: `start_remote_daemon()`, `stop_remote_daemon()`, `list_cloud_profiles()`, `sync_local_profile()`
+
+Treat the list above as the common surface, not a full inventory. If you need something lower-level, use raw `cdp(...)` or inspect the vendored helper module.
+
+First navigation should be `new_tab(url)`, not `goto_url(url)`, so the user's current tab is not overwritten.
+
+## Workflow
+
+1. If Python dependencies are missing, run `browser_admin` with `{ "action": "install" }` or `/browser install`.
+2. For setup or connection problems, run `browser_admin` with `{ "action": "doctor" }` or `/browser status`.
+3. If the daemon is not attached, run `browser_admin` with `{ "action": "setup" }` or `/browser setup`.
+4. If the user only needs knowledge retrieval, use `web_search` instead of browser automation.
+5. For a page interaction task, search `.catui/browser-workspace/domain-skills/` first for site-specific knowledge.
+6. Use screenshots to understand and verify visible browser state.
+7. After every meaningful action, verify with `capture_screenshot()` or `page_info()`.
+
+## Editable Workspace
+
+Catui copies the bundled Browser Harness workspace to:
+
+```text
+.catui/browser-workspace/
+```
+
+Use this project-local workspace for reusable browser knowledge:
+
+- `agent_helpers.py` for task-specific helper functions.
+- `domain-skills/<site>/` for durable site knowledge.
+
+If you learn a reusable site pattern, update the relevant domain skill before finishing. Capture selectors, URL patterns, private APIs, waits, framework quirks, and traps. Do not write secrets, cookies, session tokens, pixel-only instructions, or run narration.
+
+## Tactics
+
+- Prefer screenshot-driven coordinate clicks for visible UI: `capture_screenshot()` -> inspect image -> `click_at_xy(x, y)` -> screenshot again.
+- Drop to DOM/JS only when the target has no useful visible geometry.
+- Use `http_get()` for static pages or APIs instead of spending browser time.
+- If redirected to an auth wall, stop and ask the user. Do not type credentials from screenshots.
+- For raw CDP, use `cdp("Domain.method", param=value)`.
+
+## Interaction Skills
+
+When a mechanic gets tricky, consult the bundled interaction skills:
+
+- cookies, dialogs, downloads, drag-and-drop, dropdowns, iframes, cross-origin iframes
+- network requests, print as PDF, profile sync, screenshots, scrolling, shadow DOM, tabs, uploads, viewport

package/dist/extensions/builtin/browser/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: browserExtension - registers browser automation tools, /browser command, and browser skill resources
+ * [FROM]: Depends on node:child_process, node:fs, node:path, node:url, @sinclair/typebox, core/extensions-host/types
+ * [TO]: Loaded explicitly via extension config/CLI path; registered in builtin-extensions metadata as opt-in
+ * [HERE]: extensions/builtin/browser/index.ts - Browser Harness integration entry point kept under builtin source pending Q2 physical/package decision
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function browserExtension(api: ExtensionAPI): void;

package/dist/extensions/builtin/browser/index.js

@@ -0,0 +1,15 @@
+var O=Object.defineProperty;var a=(o,e)=>O(o,"name",{value:e,configurable:!0});import{spawn as N}from"node:child_process";import{cpSync as $,existsSync as g,mkdirSync as H,readdirSync as L,statSync as B}from"node:fs";import{dirname as I,join as u,resolve as U}from"node:path";import{fileURLToPath as M}from"node:url";import{Type as l}from"@sinclair/typebox";import{DEFAULT_MAX_BYTES as R,DEFAULT_MAX_LINES as D,truncateTail as _}from"../../../core/tools/truncate.js";import{getBrowserWorkspaceDir as W}from"../../../config.js";const w=I(M(import.meta.url)),j=u(w,"browser.md"),K=u(w,"install.md"),x=u(w,"src"),Y=u(w,"interaction-skills"),F=u(w,"agent-workspace"),f=120,G=[{value:"install",label:"install",description:"Install Browser Harness Python dependencies"},{value:"status",label:"status",description:"Run doctor diagnostics"},{value:"setup",label:"setup",description:"Attach to the running browser"},{value:"reload",label:"reload",description:"Restart the Browser Harness daemon"},{value:"workspace",label:"workspace",description:"Show the helper workspace path"},{value:"help",label:"help",description:"Show Browser Harness commands"}],X=l.Object({code:l.String({description:"Python code to execute with Browser Harness helpers pre-imported. Use new_tab(url), wait_for_load(), page_info(), capture_screenshot(), click_at_xy(), js(), cdp(), etc."}),timeout:l.Optional(l.Number({description:"Timeout in seconds. Defaults to 120."})),name:l.Optional(l.String({description:"Optional BU_NAME for an isolated local or remote browser daemon."}))},{additionalProperties:!1}),q=l.Object({action:l.Union([l.Literal("install"),l.Literal("doctor"),l.Literal("setup"),l.Literal("reload"),l.Literal("version")]),timeout:l.Optional(l.Number({description:"Timeout in seconds. Defaults to 120."})),name:l.Optional(l.String({description:"Optional BU_NAME for the daemon to inspect or reload."}))},{additionalProperties:!1});function E(o){if(!o.exitCode)return!1;const e=o.output.toLowerCase();return e.trim().length===0||e.includes("no suitable python runtime")||e.includes("python was not found")||e.includes("microsoft store")}a(E,"isMissingPythonRuntime");function z(){return W()}a(z,"browserWorkspacePath");function h(){const o=z();return g(o)||(H(o,{recursive:!0}),$(F,o,{recursive:!0})),o}a(h,"ensureBrowserWorkspace");function b(o){if(!g(o))return[];const e=[];for(const t of L(o)){const r=u(o,t);if(B(r).isDirectory()){e.push(...b(r));continue}t.endsWith(".md")&&e.push(r)}return e.sort()}a(b,"collectMarkdownFiles");function J(o,e){const t=h(),r=process.env.PYTHONPATH?`${x}${process.platform==="win32"?";":":"}${process.env.PYTHONPATH}`:x;return{...process.env,PYTHONIOENCODING:"utf-8",PYTHONPATH:r,BH_AGENT_WORKSPACE:t,...e?{BU_NAME:e}:{}}}a(J,"buildHarnessEnv");function v(){return process.platform==="win32"?[{command:"py",argsPrefix:["-3.11"]},{command:"py",argsPrefix:["-3"]},{command:"python",argsPrefix:[]},{command:"python3",argsPrefix:[]}]:[{command:"python3.11",argsPrefix:[]},{command:"python3",argsPrefix:[]},{command:"python",argsPrefix:[]}]}a(v,"pythonCandidates");function C(o,e,t){return new Promise((r,s)=>{const n=N(o,e,{cwd:t.cwd,env:t.env,stdio:["ignore","pipe","pipe"],windowsHide:!0});let i="",c=!1;const d=setTimeout(()=>{c||(n.kill(),c=!0,s(new Error(`browser process timed out after ${t.timeoutSeconds} seconds`)))},t.timeoutSeconds*1e3),m=a(()=>{c||(n.kill(),c=!0,s(new Error("browser process aborted")))},"onAbort");t.signal&&(t.signal.aborted?m():t.signal.addEventListener("abort",m,{once:!0}));const T=a(p=>{i+=p.toString("utf-8"),t.onUpdate?.(_(i).content||"")},"collect");n.stdout?.on("data",T),n.stderr?.on("data",T),n.on("error",p=>{clearTimeout(d),t.signal&&t.signal.removeEventListener("abort",m),c||(c=!0,s(p))}),n.on("close",p=>{if(clearTimeout(d),t.signal&&t.signal.removeEventListener("abort",m),c)return;c=!0;const P=_(i);r({exitCode:p,output:P.content||"(no output)",truncated:P.truncated})})})}a(C,"runProcess");async function y(o,e,t){const r=J(e,t.name),s=[];for(const n of v())try{const i=await C(n.command,[...n.argsPrefix,"-m","browser_harness.run",...o],{cwd:e.cwd,env:r,timeoutSeconds:t.timeoutSeconds,signal:t.signal,onUpdate:t.onUpdate});if(E(i)){s.push(`${n.command}: ${i.output||"no usable runtime"}`);continue}return i}catch(i){const c=i instanceof Error?i.message:String(i);if(!c.includes("ENOENT"))throw i;s.push(`${n.command}: ${c}`)}throw new Error(`Python 3.11+ was not found. Tried: ${s.join("; ")}`)}a(y,"runPythonModule");async function k(o,e){const t=[],r=["cdp-use==1.4.5","fetch-use==0.4.0","pillow==12.2.0","websockets==15.0.1"];for(const s of v())try{const n=await C(s.command,[...s.argsPrefix,"-m","pip","install","--disable-pip-version-check",...r],{cwd:o.cwd,env:{...process.env,PYTHONIOENCODING:"utf-8"},timeoutSeconds:e.timeoutSeconds,signal:e.signal,onUpdate:e.onUpdate});if(E(n)){t.push(`${s.command}: ${n.output||"no usable runtime"}`);continue}return n}catch(n){const i=n instanceof Error?n.message:String(n);if(!i.includes("ENOENT"))throw n;t.push(`${s.command}: ${i}`)}throw new Error(`Python 3.11+ was not found. Tried: ${t.join("; ")}`)}a(k,"installPythonDependencies");function S(o){let e=o.output;return o.truncated&&(e+=`
+
+[Output truncated to last ${D} lines or ${R/1024}KB.]`),o.exitCode&&o.exitCode!==0&&(e+=`
+
+Command exited with code ${o.exitCode}`),e}a(S,"formatToolResult");function A(o){if(/ModuleNotFoundError|No module named/.test(o))return["Browser Harness Python dependencies are missing.","Install them once with:","python -m pip install cdp-use==1.4.5 fetch-use==0.4.0 pillow==12.2.0 websockets==15.0.1"].join(`
+`)}a(A,"missingDependencyHint");function Q(){return{name:"browser",label:"browser",description:"Control the user's real Chrome/Edge browser through the vendored Browser Harness CDP bridge. Use for browser automation, scraping, screenshots, web app testing, downloads, uploads, tabs, cookies, dialogs, iframes, and remote Browser Use cloud browsers.",parameters:X,guidance:"Use new_tab(url) for first navigation so you do not clobber the user's active tab. After each meaningful visible action, use capture_screenshot() or page_info() to verify. Search .catui/browser-workspace/domain-skills before inventing site-specific logic.",execute:a(async(o,e,t,r,s)=>{const n=await y(["-c",e.code],s,{timeoutSeconds:e.timeout??f,name:e.name,signal:t,onUpdate:a(d=>r?.({content:[{type:"text",text:d}],details:null}),"onUpdate")}),i=S(n),c=A(i);if(n.exitCode&&n.exitCode!==0)throw new Error(c?`${i}
+
+${c}`:i);return{content:[{type:"text",text:c?`${i}
+
+${c}`:i}],details:{exitCode:n.exitCode,truncated:n.truncated}}},"execute")}}a(Q,"createBrowserRunTool");function V(){return{name:"browser_admin",label:"browser admin",description:"Run Browser Harness dependency install, setup, doctor, reload, or version checks against the vendored browser harness.",parameters:q,execute:a(async(o,e,t,r,s)=>{let n;if(e.action==="install")n=await k(s,{timeoutSeconds:e.timeout??f,signal:t,onUpdate:a(d=>r?.({content:[{type:"text",text:d}],details:null}),"onUpdate")});else{const d=e.action==="doctor"?["--doctor"]:e.action==="setup"?["--setup"]:e.action==="reload"?["--reload"]:["--version"];n=await y(d,s,{timeoutSeconds:e.timeout??f,name:e.name,signal:t,onUpdate:a(m=>r?.({content:[{type:"text",text:m}],details:null}),"onUpdate")})}const i=S(n),c=A(i);if(n.exitCode&&n.exitCode!==0)throw new Error(c?`${i}
+
+${c}`:i);return{content:[{type:"text",text:c?`${i}
+
+${c}`:i}],details:{exitCode:n.exitCode,truncated:n.truncated}}},"execute")}}a(V,"createBrowserAdminTool");function Z(o){o.registerTool(Q()),o.registerTool(V()),o.on("session_start",(e,t)=>{h()}),o.registerCommand("browser",{description:"Set up or inspect browser automation tools",getArgumentCompletions:a((e,t)=>{if(t&&t.tokenIndex>0)return null;const r=e.trim().toLowerCase(),s=G.filter(n=>n.value.startsWith(r));return s.length>0?s:null},"getArgumentCompletions"),handler:a(async(e,t)=>{const r=(e.trim().split(/\s+/)[0]||"help").toLowerCase();if(r==="workspace"){o.sendMessage({customType:"text",content:`Browser workspace: ${U(h())}`,display:!0});return}if(r==="install"||r==="setup"||r==="status"||r==="reload"){let s;r==="install"?s=await k(t,{timeoutSeconds:f}):s=await y([r==="status"?"--doctor":`--${r}`],t,{timeoutSeconds:f}),o.sendMessage({customType:"text",content:S(s),display:!0});return}o.sendMessage({customType:"text",content:["Browser Harness is built into Catui.","","Commands:","/browser install - install the Python dependencies used by the vendored harness","/browser status - run doctor diagnostics","/browser setup - attach to the running browser","/browser reload - stop the daemon so the next browser call restarts it","/browser workspace - show the editable helper/domain-skill workspace","","Agent tools: browser, browser_admin"].join(`
+`),display:!0})},"handler")}),o.on("resources_discover",async e=>{const t=h(),r=[...new Set([...b(Y),...b(u(t,"domain-skills")),j,K].filter(s=>g(s)))];return r.length?{skillPaths:r}:{}})}a(Z,"browserExtension");export{Z as default};