# Manual de uso de la herramienta Browser

Este manual explica que tools expone la herramienta browser, como usarlas y que puedes pedirle a OpenCode en la practica.

## Alcance actual

- Browser: `Chromium` controlado por `Playwright`
- Integracion: `MCP` por `stdio`
- Modo por defecto: visible (`headless: false`)
- Artefactos: capturas en `opencode-browser-tool/artifacts/`

## Esquema de respuesta estandar

Todas las tools devuelven ahora un formato unificado.

Respuesta OK:

```json
{
  "ok": true,
  "tool": "browser_<tool>",
  "data": {},
  "state": {
    "isOpen": true,
    "currentUrl": "https://..."
  }
}
```

Respuesta con error:

```json
{
  "ok": false,
  "tool": "browser_<tool>",
  "error": {
    "code": "TOOL_EXECUTION_ERROR",
    "message": "detalle del error"
  },
  "state": {
    "isOpen": false,
    "currentUrl": null
  }
}
```

## Flujo recomendado de uso

1. Abrir sesion de navegador con `browser_open`
2. Navegar con `browser_navigate`
3. Interactuar con `browser_click`, `browser_type`, `browser_press`, `browser_scroll`
4. Esperar estados estables con `browser_wait`
5. Capturar evidencia con `browser_snapshot`
6. Inspeccionar estado dinamico con `browser_evaluate`
7. Cerrar sesion con `browser_close`

Importante: todas las tools excepto `browser_open` y `browser_close` requieren sesion abierta. Si no hay sesion, devuelve error.

## Espera automatica nativa (comportamiento actual)

La herramienta ya incorpora estabilizacion automatica despues de acciones clave.

Que significa en la practica:

- despues de `browser_navigate`, `browser_click`, `browser_type`, `browser_press`, `browser_scroll` y `browser_evaluate`, la herramienta intenta esperar estado estable por si sola
- combina `domcontentloaded`, intento de `networkidle` y una ventana de "quietud" de actividad de red
- si no logra estado estable, aplica salida segura por tiempo maximo para evitar bucles de espera infinita

Resultado:

- normalmente no necesitas pedir `wait` manual para casos comunes
- `browser_wait` sigue disponible cuando quieras una condicion explicita (selector/texto/url/timeout)

---

## Tools disponibles

### `browser_help`

Devuelve un resumen operativo de la herramienta: capacidades, defaults, notas y ejemplos.

Cuando usarla:

- al empezar una sesion nueva con un agente que no conoce la tool
- para recordar comportamiento por defecto (modo visible, timeouts, auto-wait)

Parametros: ninguno.

Ejemplo:

```json
{}
```

---

### `browser_health`

Devuelve estado operativo actual del runtime browser y artifacts recientes.

Incluye:

- estado de sesion (`isOpen`, `currentUrl`)
- actividad de red interna (`inflight`, `lastActivityAgoMs`)
- comportamiento activo (`verbose`, overlay, delay humano)
- pasos recientes (`recentSteps`) para diagnostico rapido en vivo
- lista de artifacts recientes (ruta, fecha, tamano)

Parametros:

- `limit` (number, opcional): cantidad maxima de artifacts a devolver (default `5`, max `20`)

Ejemplo:

```json
{
  "limit": 5
}
```

---

### `browser_config`

Permite leer o cambiar configuracion persistente de la herramienta (guardada en `config/browser-tool.config.json`).

Parametros:

- `action` (string, opcional): `get` o `set` (default `get`)
- `browserDefaultKind` (string, opcional): `testing` o `system`
- `browserSystemExecutablePath` (string, opcional): ruta del navegador del sistema (ej. `/usr/bin/google-chrome`)
- `browserDefaultPersistentProfile` (boolean, opcional): si `true`, `browser_open` usa perfil persistente por defecto
- `browserDefaultUserDataDir` (string, opcional): ruta de perfil persistente por defecto
- `browserDefaultVerbose` (boolean, opcional): modo verbose por defecto (`true` recomendado para operacion)
- `browserDefaultVerboseOverlay` (boolean, opcional): overlay visual de estado en navegador visible
- `browserDefaultInteractionDelayMinMs` (number, opcional): minimo de delay humano en acciones interactivas
- `browserDefaultInteractionDelayMaxMs` (number, opcional): maximo de delay humano en acciones interactivas
- `reportDefaultSaveToFile` (boolean, opcional): default persistente de `browser_report.saveToFile`
- `reportDefaultFormat` (string, opcional): `json`, `markdown`, `both`

Ejemplo lectura:

```json
{
  "action": "get"
}
```

Ejemplo cambio persistente:

```json
{
  "action": "set",
  "browserDefaultKind": "system",
  "browserSystemExecutablePath": "/usr/bin/google-chrome",
  "browserDefaultPersistentProfile": true,
  "browserDefaultUserDataDir": "/home/pancho/.chrome-perfil-google-real",
  "browserDefaultVerbose": true,
  "browserDefaultVerboseOverlay": true,
  "browserDefaultInteractionDelayMinMs": 1000,
  "browserDefaultInteractionDelayMaxMs": 3000,
  "reportDefaultSaveToFile": false,
  "reportDefaultFormat": "json"
}
```

---

### `browser_diagnostics`

Devuelve eventos recientes de diagnostico capturados durante la sesion:

- `console` (log, warn, error, etc.)
- `pageerror` (errores JS no capturados)
- `requestfailed` (peticiones de red fallidas)

Parametros:

- `limit` (number, opcional): maximo de eventos devueltos (default `20`, max `200`)

Ejemplo:

```json
{
  "limit": 20
}
```

---

### `browser_diagnostics_clear`

Limpia el buffer interno de diagnostico.

Uso recomendado: antes de arrancar una prueba nueva para leer solo eventos de ese flujo.

Parametros: ninguno.

```json
{}
```

---

### `browser_observe`

Toma una "foto de estado" de la pagina durante el flujo y, opcionalmente, una captura.

Uso recomendado:

- cuando el flujo parece bloqueado
- cuando no avanza tras una accion
- antes de abortar una prueba para entender que esta viendo el navegador

Parametros:

- `screenshot` (boolean, opcional, default `true`)
- `label` (string, opcional)

Ejemplo:

```json
{
  "screenshot": true,
  "label": "mid-flow-check"
}
```

---

### `browser_handle_consent`

Intenta pulsar botones comunes de consentimiento.

Parametros:

- `action` (string, opcional): `reject` (default) o `accept`

Ejemplo:

```json
{
  "action": "reject"
}
```

---

### `browser_handle_human_check`

Intenta resolver controles comunes de verificacion humana (incluyendo checkbox de reCAPTCHA cuando es clicable).

Estrategia actual:

- intenta clic en checkboxs dentro de iframes comunes de reCAPTCHA
- intenta selectores de captcha tambien en pagina principal
- usa fallback por coordenadas para controles detectados por texto

Uso recomendado:

- cuando aparece bloqueo tipo `sorry/index`
- cuando el flujo queda detenido en "comprueba que eres humano"

Parametros: ninguno.

```json
{}
```

---

### `browser_open`

Abre una sesion de `Chromium`.

Parametros:

- `headless` (boolean, opcional): por defecto `false`
- `startUrl` (string, opcional)
- `width` (number, opcional, default `1440`)
- `height` (number, opcional, default `900`)
- `browserKind` (string, opcional): `testing` (Playwright managed) o `system` (browser del sistema)
- `executablePath` (string, opcional): ruta binaria explicita del navegador
- `persistentProfile` (boolean, opcional): activar perfil persistente
- `userDataDir` (string, opcional): ruta del perfil persistente (requerido si `persistentProfile=true`)
- `verbose` (boolean, opcional, default `true`): muestra estado paso a paso en respuestas
- `verboseOverlay` (boolean, opcional, default `true`): muestra estado en overlay visual en navegador visible
- `interactionDelayMinMs` (number, opcional, default `1000`)
- `interactionDelayMaxMs` (number, opcional, default `3000`)
- `recordVideo` (boolean, opcional, default `false`)
- `recordTrace` (boolean, opcional, default `false`)
- `recordLabel` (string, opcional, default `session`)

Ejemplo:

```json
{
  "headless": false,
  "startUrl": "http://localhost:3000",
  "width": 1440,
  "height": 900,
  "browserKind": "system",
  "persistentProfile": true,
  "userDataDir": "/home/pancho/.chrome-perfil-google-real",
  "verbose": true,
  "verboseOverlay": true,
  "interactionDelayMinMs": 1000,
  "interactionDelayMaxMs": 3000,
  "recordVideo": true,
  "recordTrace": true,
  "recordLabel": "case-123"
}
```

Notas:

- `recordVideo` sigue desactivado por defecto para evitar consumo innecesario.
- si activas `recordVideo` o `recordTrace`, los artifacts se generan al cerrar sesion con `browser_close`.
- con `verbose=true`, la tool muestra estado actual y aplica guardas de estabilidad antes de pasos sensibles.

---

### `browser_close`

Cierra la sesion activa de navegador.

Parametros: ninguno.

Ejemplo:

```json
{}
```

---

### `browser_navigate`

Navega la pagina activa a una URL.

Parametros:

- `url` (string, requerido)
- `waitUntil` (string, opcional): `load`, `domcontentloaded`, `networkidle` (default `domcontentloaded`)

Ejemplo:

```json
{
  "url": "http://localhost:3000/login",
  "waitUntil": "domcontentloaded"
}
```

---

### `browser_click`

Hace click sobre un selector CSS.

Nota: antes del click intenta mover el puntero al centro del elemento para hacer la interaccion mas natural.

Parametros:

- `selector` (string, requerido)
- `timeoutMs` (number, opcional, default `10000`)

Ejemplo:

```json
{
  "selector": "button[type='submit']",
  "timeoutMs": 10000
}
```

---

### `browser_hover`

Hace hover sobre un elemento por selector.

Parametros:

- `selector` (string, requerido)
- `timeoutMs` (number, opcional, default `10000`)

Ejemplo:

```json
{
  "selector": ".menu-item-settings",
  "timeoutMs": 10000
}
```

---

### `browser_type`

Escribe texto en un elemento por selector.

Nota: antes de escribir intenta mover puntero y enfocar el campo con click.

Parametros:

- `selector` (string, requerido)
- `text` (string, requerido)
- `clear` (boolean, opcional, default `true`)
- `timeoutMs` (number, opcional, default `10000`)

Ejemplo:

```json
{
  "selector": "input[name='email']",
  "text": "usuario@dominio.com",
  "clear": true,
  "timeoutMs": 10000
}
```

---

### `browser_select`

Selecciona una opcion en un elemento `<select>` por valor.

Parametros:

- `selector` (string, requerido)
- `value` (string, requerido)
- `timeoutMs` (number, opcional, default `10000`)

Ejemplo:

```json
{
  "selector": "#tipoConsentimiento",
  "value": "quirurgico",
  "timeoutMs": 10000
}
```

---

### `browser_press`

Envia una tecla al contexto de teclado de la pagina.

Parametros:

- `key` (string, requerido). Ejemplos: `Enter`, `Escape`, `Tab`, `Control+A`.

Ejemplo:

```json
{
  "key": "Enter"
}
```

---

### `browser_scroll`

Hace scroll en pagina completa o dentro de un elemento.

Parametros:

- `x` (number, opcional, default `0`)
- `y` (number, opcional, default `400`)
- `selector` (string, opcional): si se envia, el scroll se aplica al elemento

Nota: cuando el scroll es de pagina, se aplica en varios pasos cortos para que el desplazamiento sea visible y progresivo.
Si no hay desplazamiento por rueda, aplica fallback `window.scrollBy`.

La salida incluye metricas utiles:

- `startY`, `endY`, `maxY`, `movedY` para scroll de pagina
- `movedX`, `movedY` para scroll de elemento

Ejemplo pagina:

```json
{
  "y": 700
}
```

Ejemplo elemento:

```json
{
  "selector": ".lista-scroll",
  "y": 500
}
```

---

### `browser_wait`

Espera a que se cumpla una condicion.

Nota: en esta version es opcional para muchos flujos, porque la herramienta ya aplica espera automatica nativa tras acciones comunes.

Parametros:

- `for` (string, requerido): `selector`, `text`, `url`, `timeout`
- `value` (string, requerido para `selector`, `text`, `url`)
- `timeoutMs` (number, opcional, default `10000`)

Nota para `for: timeout`:

- si envias `value`, se interpreta como milisegundos de espera
- si no envias `value`, usa `timeoutMs`

Ejemplo por selector:

```json
{
  "for": "selector",
  "value": ".toast-success",
  "timeoutMs": 10000
}
```

Ejemplo por tiempo:

```json
{
  "for": "timeout",
  "timeoutMs": 1500
}
```

---

### `browser_snapshot`

Toma screenshot y lo guarda en `artifacts/`.

Parametros:

- `label` (string, opcional)
- `fullPage` (boolean, opcional, default `true`)

Ejemplo:

```json
{
  "label": "post-login",
  "fullPage": true
}
```

---

### `browser_evaluate`

Ejecuta JavaScript en la pagina. Puede recibir una funcion en texto (con `arg`) o una expresion directa.

Importante: si, puede inyectar y ejecutar logica JavaScript en runtime. Eso incluye leer variables del DOM y tambien modificarlas temporalmente dentro de la sesion de prueba.

Parametros:

- `script` (string, requerido): funcion JS serializada
- `arg` (object, opcional): dato de entrada a la funcion

Ejemplo:

```json
{
  "script": "(arg) => ({ title: document.title, arg })",
  "arg": { "source": "qa" }
}
```

Ejemplo con expresion directa:

```json
{
  "script": "document.title"
}
```

---

### `browser_query`

Lee estado DOM/UI por selector sin tener que escribir JavaScript para casos comunes.

Parametros:

- `selector` (string, requerido)
- `mode` (string, opcional): `text`, `html`, `value`, `exists`, `visible`, `enabled`, `count`, `attributes`

Ejemplos:

```json
{
  "selector": "#email",
  "mode": "value"
}
```

```json
{
  "selector": ".toast-success",
  "mode": "exists"
}
```

---

### `browser_report`

Genera un reporte consolidado de ejecucion a partir de pasos, diagnostico y artifacts.

Parametros:

- `format` (string, opcional): `json`, `markdown`, `both` (default `both`)
- `includeSteps` (boolean, opcional, default `true`)
- `includeDiagnostics` (boolean, opcional, default `true`)
- `includeArtifacts` (boolean, opcional, default `true`)
- `saveToFile` (boolean, opcional): por defecto usa configuracion persistente (`true` al instalar)
- `label` (string, opcional, default `report`)
- `limitSteps` (number, opcional, default `200`)
- `limitDiagnostics` (number, opcional, default `50`)

Ejemplo:

```json
{
  "format": "both",
  "saveToFile": true,
  "label": "consent-flow",
  "includeSteps": true,
  "includeDiagnostics": true,
  "includeArtifacts": true
}
```

Resultado esperado:

- reporte estructurado para uso del agente
- opcionalmente archivos `.json` y `.md` en `artifacts/`

Comportamiento recomendado:

- por defecto queda guardando a archivo (`saveToFile=true`) para no perder evidencia
- puedes desactivarlo temporalmente en una ejecucion concreta (`saveToFile=false`)
- para cambiar el default de forma persistente usa `browser_config`

---

## Que puede pedirle el usuario a OpenCode

Ejemplos utiles:

- "Abre el browser, entra a `http://localhost:3000` y valida que aparece el boton `Iniciar sesion`."
- "Rellena email y password, envia el formulario y espera una URL que contenga `/dashboard`."
- "Haz scroll hasta el final, toma captura y guardala con etiqueta `dashboard-final`."
- "Ejecuta un `browser_evaluate` para devolver cantidad de filas de la tabla `.orders-table`."
- "Usa `browser_query` para comprobar si `.btn-guardar` esta visible y habilitado."
- "Ejecuta `browser_health` y dime si hay sesion abierta y cuales son los ultimos artifacts."
- "Al terminar la prueba, genera `browser_report` en `both` y guardalo a archivo para revisar resultado y evidencia."

## Limites actuales de esta version

- El diagnostico actual es en memoria de sesion (no persiste historico entre reinicios del proceso).
- Video/trace se activan manualmente por ejecucion; todavia no hay politica automatica "solo en fallo".
- No hay politica de seguridad final para navegacion externa (pendiente de fases posteriores).
- El modo recomendado de v1 es `Chromium managed by Playwright`.

## Errores tipicos y recuperacion

- `Browser session is not open`: ejecuta `browser_open` antes de usar otras tools.
- `Timeout` en `browser_wait`: valida si ya cambio URL/estado con `browser_evaluate`; si ya estas dentro, continua.
- Si la pagina parece bloqueada: ejecuta `browser_observe` para capturar estado/screenshot antes de cortar.
- Si aparece banner de consentimiento: ejecuta `browser_handle_consent` (`reject` o `accept`) y continua.
- Si aparece verificacion humana: ejecuta `browser_handle_human_check`; si no desbloquea, dejar evidencia y hacer handoff manual.
- Selector no encontrado en `browser_click` o `browser_type`: confirma selector con `browser_evaluate` y reintenta con uno mas estable.
- Flujo lento de red: deja que actue la espera nativa; si no alcanza, usa `browser_wait` explicito por selector de estado final.
- Error al evaluar JS en `browser_evaluate`: envia una funcion valida en texto, por ejemplo `(arg) => ({ title: document.title, arg })`.