id = "browser"
version = "1.0.0"
name = "Browser Hand"
description = "Autonomous web browser — navigates sites, fills forms, clicks buttons, and completes multi-step web tasks with user approval for purchases"

category = "productivity"
icon = "🌐"

tools = [
  "browser_navigate",
  "browser_click",
  "browser_type",
  "browser_screenshot",
  "browser_read_page",
  "browser_close",
  "web_search",
  "web_fetch",
  "memory_store",
  "memory_recall",
  "knowledge_add_entity",
  "knowledge_add_relation",
  "knowledge_query",
  "schedule_create",
  "schedule_list",
  "schedule_delete",
  "file_write",
  "file_read",
]

[routing]
aliases = [
  "open website",
  "navigate to",
  "fill form",
  "click button",
  "web login",
  "browser automation",
  "browse web",
  "scrape page",
]
weak_aliases = [
  "web page",
  "submit form",
  "web task",
  "browser task",
  "open browser",
  "web automation",
]

[[requires]]
key = "python3"
label = "Python 3 must be installed"
requirement_type = "binary"
check_value = "python3"
description = "Python 3 is required for installing and running the Playwright browser automation library. Python 3.8 or newer is recommended."

[requires.install]
macos = "brew install python3"
windows = "winget install Python.Python.3.12"
linux_apt = "sudo apt install python3"
linux_dnf = "sudo dnf install python3"
linux_pacman = "sudo pacman -S python"
pip = "python3 --version"
manual_url = "https://www.python.org/downloads/"
estimated_time = "1-3 min"

[[requires]]
key = "chromium"
label = "Chromium or Google Chrome must be installed"
requirement_type = "binary"
check_value = "chromium"
optional = true
description = "A Chromium-based browser is recommended. Playwright can install its own bundled browser if none is found. Google Chrome, Chromium, or any Chromium derivative will also work. You can set the CHROME_PATH environment variable to point to your browser binary."

[requires.install]
macos = "brew install --cask google-chrome"
windows = "winget install Google.Chrome"
linux_apt = "sudo apt install chromium-browser"
linux_dnf = "sudo dnf install chromium"
linux_pacman = "sudo pacman -S chromium"
manual_url = "https://www.google.com/chrome/"
estimated_time = "1-3 min"

# ─── Configurable settings ───────────────────────────────────────────────────

[[settings]]
key = "headless"
label = "Headless Mode"
description = "Run the browser without a visible window (recommended for servers)"
setting_type = "toggle"
default = "true"

[[settings]]
key = "approval_mode"
label = "Purchase Approval"
description = "Require explicit user confirmation before completing any purchase or payment"
setting_type = "toggle"
default = "true"

[[settings]]
key = "max_pages_per_task"
label = "Max Pages Per Task"
description = "Maximum number of page navigations allowed per task to prevent runaway browsing"
setting_type = "select"
default = "20"

[[settings.options]]
value = "10"
label = "10 pages (conservative)"

[[settings.options]]
value = "20"
label = "20 pages (balanced)"

[[settings.options]]
value = "50"
label = "50 pages (thorough)"

[[settings]]
key = "default_wait"
label = "Default Wait After Action"
description = "How long to wait after clicking or navigating for the page to settle"
setting_type = "select"
default = "auto"

[[settings.options]]
value = "auto"
label = "Auto-detect (wait for DOM)"

[[settings.options]]
value = "1"
label = "1 second"

[[settings.options]]
value = "3"
label = "3 seconds"

[[settings]]
key = "screenshot_on_action"
label = "Screenshot After Actions"
description = "Automatically take a screenshot after every click/navigate for visual verification"
setting_type = "toggle"
default = "false"

# ─── Agent configuration ─────────────────────────────────────────────────────

[agent]
name = "browser-hand"
description = "AI web browser — navigates websites, fills forms, searches products, and completes multi-step web tasks autonomously with safety guardrails"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 16384
temperature = 0.3
max_iterations = 60
system_prompt = """You are Browser Hand — an autonomous web browser agent that interacts with real websites on behalf of the user.

## Core Capabilities

You can navigate to URLs, click buttons/links, fill forms, read page content, and take screenshots. You have a real browser session that persists across tool calls within a conversation.

## Multi-Phase Pipeline

### Phase 1 — Understand the Task
Parse the user's request and plan your approach:
- What website(s) do you need to visit?
- What information do you need to find or what action do you need to perform?
- What are the success criteria?

### Phase 2 — Navigate & Observe
1. Use `browser_navigate` to go to the target URL
2. Read the page content to understand the layout
3. Identify the relevant elements (buttons, links, forms, search boxes)

### Phase 3 — Interact
1. Use `browser_click` for buttons and links (use CSS selectors or visible text)
2. Use `browser_type` for filling form fields
3. Use `browser_read_page` after each action to see the updated state
4. Use `browser_screenshot` when you need visual verification

### Phase 4 — MANDATORY Purchase/Payment Approval
**CRITICAL RULE**: Before completing ANY purchase, payment, or form submission that involves money:
1. Summarize what you are about to buy/pay for
2. Show the total cost
3. List all items in the cart
4. STOP and ask the user for explicit confirmation
5. Only proceed after receiving clear approval

NEVER auto-complete purchases. NEVER click "Place Order", "Pay Now", "Confirm Purchase", or any payment button without user approval.

### Phase 5 — Report Results
After completing the task:
1. Summarize what was accomplished
2. Include relevant details (prices, confirmation numbers, etc.)
3. Save important data to memory for future reference

## CSS Selector Cheat Sheet

Common selectors for web interaction:
- `#id` — element by ID (e.g., `#search-box`, `#add-to-cart`)
- `.class` — element by class (e.g., `.btn-primary`, `.product-title`)
- `input[name="email"]` — input by name attribute
- `input[type="search"]` — search inputs
- `button[type="submit"]` — submit buttons
- `a[href*="cart"]` — links containing "cart" in href
- `[data-testid="checkout"]` — elements with test IDs
- `select[name="quantity"]` — dropdown selectors

When CSS selectors fail, fall back to clicking by visible text content.

## Common Web Interaction Patterns

### Search Pattern
1. Navigate to site
2. Find search box: `input[type="search"]`, `input[name="q"]`, `#search`
3. Type query with `browser_type`
4. Click search button or the text will auto-submit
5. Read results

### Login Pattern
1. Navigate to login page
2. Fill email/username: `input[name="email"]` or `input[type="email"]`
3. Fill password: `input[name="password"]` or `input[type="password"]`
4. Click login button: `button[type="submit"]`, `.login-btn`
5. Verify login success by reading page

### E-commerce Pattern
1. Search for product
2. Click product from results
3. Select options (size, color, quantity)
4. Click "Add to Cart"
5. Navigate to cart
6. Review items and total
7. **STOP — Ask user for purchase approval**
8. Only proceed to checkout after approval

### Form Filling Pattern
1. Navigate to form page
2. Read form structure
3. Fill fields one by one with `browser_type`
4. Use `browser_click` for checkboxes, radio buttons, dropdowns
5. Screenshot before submission for verification
6. Submit form

## Error Recovery

- If a click fails, try a different selector or use visible text
- If a page doesn't load, wait and retry with `browser_navigate`
- If you get a CAPTCHA, inform the user — you cannot solve CAPTCHAs
- If a login is required, ask the user for credentials (never store passwords)
- If blocked or rate-limited, wait and try again, or inform the user

## Security Rules

- NEVER store passwords or credit card numbers in memory
- NEVER auto-complete payments without user approval
- NEVER navigate to URLs from untrusted sources without checking them
- NEVER fill in credentials without the user explicitly providing them
- If you encounter suspicious or phishing-like content, warn the user immediately
- Always verify you're on the correct domain before entering sensitive information

## Session Management

- Your browser session persists across messages in this conversation
- Cookies and login state are maintained
- Use `browser_close` when you're done to free resources
- The browser auto-closes when the conversation ends

Update stats via memory_store after each task:
- `browser_hand_pages_visited` — increment by pages navigated
- `browser_hand_tasks_completed` — increment by 1
- `browser_hand_screenshots_taken` — increment by screenshots captured
"""

[dashboard]
[[dashboard.metrics]]
label = "Pages Visited"
memory_key = "browser_hand_pages_visited"
format = "number"

[[dashboard.metrics]]
label = "Tasks Completed"
memory_key = "browser_hand_tasks_completed"
format = "number"

[[dashboard.metrics]]
label = "Screenshots"
memory_key = "browser_hand_screenshots_taken"
format = "number"

# ─── Token & Performance Metadata ─────────────────────────────────────────────

[metadata]
frequency = "continuous"
token_consumption = "low"
default_active = true
activation_warning = "Browser hand runs continuously but mainly consumes tokens when actively performing web tasks."

# ─── Internationalization (optional) ─────────────────────────────────────────
# All i18n sections are optional. Without them, the English values above are used.
# To localize, add [i18n.LANG] sections (e.g. zh, ja, ko, es, fr, de).
# Settings translations are also optional — omit to keep English labels.

# ─── Chinese (简体中文) ────────────────────────────────────────────────────

[i18n.zh]
name = "浏览器 Hand"
description = "自主网页浏览器——导航网站、填写表单、点击按钮，经用户批准后完成多步骤网页任务"
category = "生产力"

[i18n.zh.settings.headless]
label = "无头模式"
description = "在不显示浏览器窗口的情况下运行（推荐用于服务器环境）"

[i18n.zh.settings.approval_mode]
label = "购买审批"
description = "在完成任何购买或支付操作前，需要用户明确确认"

[i18n.zh.settings.max_pages_per_task]
label = "每任务最大页面数"
description = "每个任务允许的最大页面导航次数，防止无限浏览"

[i18n.zh.settings.default_wait]
label = "操作后默认等待"
description = "点击或导航后等待页面稳定的时长"

[i18n.zh.settings.screenshot_on_action]
label = "操作后截图"
description = "每次点击/导航后自动截图，用于视觉验证"

# ─── Japanese (日本語) ────────────────────────────────────────────────────

[i18n.ja]
name = "ブラウザ Hand"
description = "自律型ウェブブラウザ——サイトのナビゲーション、フォーム入力、ボタンクリック、ユーザー承認付きの複数ステップWebタスクの実行"
category = "生産性"

[i18n.ja.settings.headless]
label = "ヘッドレスモード"
description = "ブラウザウィンドウを表示せずに実行する（サーバー環境に推奨）"

[i18n.ja.settings.approval_mode]
label = "購入承認"
description = "購入や支払いを完了する前にユーザーの明示的な確認を求める"

[i18n.ja.settings.max_pages_per_task]
label = "タスクあたりの最大ページ数"
description = "暴走的なブラウジングを防ぐため、タスクごとに許可されるページ遷移の最大数"

[i18n.ja.settings.default_wait]
label = "操作後のデフォルト待機時間"
description = "クリックやナビゲーション後、ページが安定するまでの待機時間"

[i18n.ja.settings.screenshot_on_action]
label = "操作後のスクリーンショット"
description = "クリック/ナビゲーションのたびに自動的にスクリーンショットを撮影し、視覚的に確認する"

# ─── Spanish (Español) ────────────────────────────────────────────────────

[i18n.es]
name = "Hand de Navegador"
description = "Navegador web autónomo — navega sitios, completa formularios, hace clic en botones y realiza tareas web de múltiples pasos con aprobación del usuario para compras"
category = "Productividad"

[i18n.es.settings.headless]
label = "Modo sin interfaz"
description = "Ejecutar el navegador sin ventana visible (recomendado para servidores)"

[i18n.es.settings.approval_mode]
label = "Aprobación de compras"
description = "Requerir confirmación explícita del usuario antes de completar cualquier compra o pago"

[i18n.es.settings.max_pages_per_task]
label = "Máximo de páginas por tarea"
description = "Número máximo de navegaciones de página permitidas por tarea para evitar navegación descontrolada"

[i18n.es.settings.default_wait]
label = "Espera predeterminada tras acción"
description = "Cuánto tiempo esperar después de hacer clic o navegar para que la página se estabilice"

[i18n.es.settings.screenshot_on_action]
label = "Captura de pantalla tras acciones"
description = "Tomar automáticamente una captura de pantalla después de cada clic/navegación para verificación visual"

# ─── French (Français) ────────────────────────────────────────────────────

[i18n.fr]
name = "Hand Navigateur"
description = "Navigateur web autonome — navigue sur les sites, remplit les formulaires, clique sur les boutons et exécute des tâches web multi-étapes avec approbation utilisateur pour les achats"
category = "Productivité"

[i18n.fr.settings.headless]
label = "Mode sans interface"
description = "Exécuter le navigateur sans fenêtre visible (recommandé pour les serveurs)"

[i18n.fr.settings.approval_mode]
label = "Approbation des achats"
description = "Exiger la confirmation explicite de l'utilisateur avant de finaliser tout achat ou paiement"

[i18n.fr.settings.max_pages_per_task]
label = "Pages maximum par tâche"
description = "Nombre maximum de navigations de page autorisées par tâche pour éviter une navigation incontrôlée"

[i18n.fr.settings.default_wait]
label = "Attente par défaut après action"
description = "Durée d'attente après un clic ou une navigation pour que la page se stabilise"

[i18n.fr.settings.screenshot_on_action]
label = "Capture d'écran après action"
description = "Prendre automatiquement une capture d'écran après chaque clic/navigation pour vérification visuelle"

# ─── German (Deutsch) ────────────────────────────────────────────────────

[i18n.de]
name = "Browser-Hand"
description = "Autonomer Webbrowser — navigiert Websites, füllt Formulare aus, klickt Schaltflächen und führt mehrstufige Webaufgaben mit Benutzerfreigabe für Käufe aus"
category = "Produktivität"

[i18n.de.settings.headless]
label = "Headless-Modus"
description = "Browser ohne sichtbares Fenster ausführen (empfohlen für Server)"

[i18n.de.settings.approval_mode]
label = "Kaufgenehmigung"
description = "Ausdrückliche Benutzerbestätigung vor dem Abschluss eines Kaufs oder einer Zahlung erforderlich"

[i18n.de.settings.max_pages_per_task]
label = "Maximale Seiten pro Aufgabe"
description = "Maximale Anzahl erlaubter Seitennavigationen pro Aufgabe, um unkontrolliertes Surfen zu verhindern"

[i18n.de.settings.default_wait]
label = "Standard-Wartezeit nach Aktion"
description = "Wartezeit nach einem Klick oder einer Navigation, bis sich die Seite stabilisiert hat"

[i18n.de.settings.screenshot_on_action]
label = "Screenshot nach Aktion"
description = "Nach jedem Klick/jeder Navigation automatisch einen Screenshot für visuelle Überprüfung erstellen"

# ─── Korean (한국어) ────────────────────────────────────────────────────

[i18n.ko]
name = "브라우저 Hand"
description = "자율 웹 브라우저 — 사이트 탐색, 양식 작성, 버튼 클릭, 구매 시 사용자 승인을 받아 다단계 웹 작업 수행"
category = "생산성"

[i18n.ko.settings.headless]
label = "헤드리스 모드"
description = "브라우저 창을 표시하지 않고 실행 (서버 환경에 권장)"

[i18n.ko.settings.approval_mode]
label = "구매 승인"
description = "구매 또는 결제 완료 전 사용자의 명시적 확인 필요"

[i18n.ko.settings.max_pages_per_task]
label = "작업당 최대 페이지 수"
description = "작업당 허용되는 최대 페이지 탐색 횟수 (무한 브라우징 방지)"

[i18n.ko.settings.default_wait]
label = "동작 후 기본 대기"
description = "클릭 또는 탐색 후 페이지가 안정될 때까지 대기하는 시간"

[i18n.ko.settings.screenshot_on_action]
label = "동작 후 스크린샷"
description = "클릭/탐색 후 자동으로 스크린샷을 캡처하여 시각적으로 검증"