@diegosouzacdv/jev-browser-mcp 0.7.0 → 0.7.2

package/docs/jev-browser-mcp.md

@@ -17,7 +17,7 @@ versão em produção, use o número explícito no argumento do pacote:
   "mcpServers": {
     "jev-browser": {
       "command": "npx",
-      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.7.0"],
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.7.2"],
       "env": {
         "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
         "JEV_BROWSER_MODE": "computer"
@@ -32,7 +32,7 @@ um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
 de configuração. Para instalar no projeto Node do próprio harness:
 
 ```sh
-npm install @diegosouzacdv/jev-browser-mcp@0.7.0
+npm install @diegosouzacdv/jev-browser-mcp@0.7.2
 ```
 
 Se o harness executa o MCP repetidamente nesta máquina, instale uma versão
@@ -40,7 +40,7 @@ fixa globalmente para evitar a resolução e o download feitos pelo `npx` em cad
 inicialização:
 
 ```sh
-npm install --global @diegosouzacdv/jev-browser-mcp@0.7.0
+npm install --global @diegosouzacdv/jev-browser-mcp@0.7.2
 ```
 
 Depois configure o servidor MCP com `command: "jev-browser-mcp"` e `args: []`.
@@ -48,8 +48,8 @@ Para atualizar, rode `npm install --global
 @diegosouzacdv/jev-browser-mcp@<versão>` e reinicie o processo do harness.
 
 O padrão `computer` exige Chrome ou Edge instalado. Se optar por `harness`,
-configure `JEV_BROWSER_MODE=harness` antes de instalar o navegador gerenciado
-pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.7.0 --install-browser`.
+configure `JEV_BROWSER_MODE=harness` antes de instalar o navegador gerenciado
+pelo Playwright com `npx --yes @diegosouzacdv/jev-browser-mcp@0.7.2 --install-browser`.
 
 O padrão é `computer`: o pacote abre o Chrome/Edge instalado e usa um perfil
 persistente exclusivo por processo MCP em `browser.computer_user_data_dir`. O
@@ -85,22 +85,49 @@ publicada.
 
 ### Contrato do pacote
 
-O executável oferece `browser_health`, `describe_actions`, `choose_next_action`
-e `run_browser_flow`, mantém uma sessão do browser por processo e reutiliza
-essa sessão entre chamadas. `browser_health` informa versão, sessão e
+O executável oferece `browser_health`, `describe_actions`, `choose_next_action`,
+`run_browser_flow`, `run_test_suite` e `get_browser_flow_result`, mantém uma sessão do browser
+por processo e reutiliza essa sessão entre chamadas. `browser_health` informa versão, sessão e
 capacidades; `describe_actions` publica o schema atual das ações, opções,
-aliases e placeholders. Consulte essas ferramentas antes de construir um plano
-para evitar nomes de campos desatualizados. O plano
-passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
-hover, espera, teclas aprovadas, asserções por elemento, upload restrito a uma
-raiz local configurada e reações idempotentes a um comentário único. Também
-aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
-JavaScript enviado pelo harness nem coordenadas. Além de papel/nome acessível,
+aliases, placeholders, campos obrigatórios de `flow`/plano e requisitos
+condicionais por ação. `run_browser_flow` agrega campos obrigatórios ausentes
+em todos os planos e etapas antes de abrir o navegador. Consulte essas ferramentas
+antes de construir um plano para evitar nomes de campos desatualizados. O plano
+passado ao Jev continua declarativo: clique, preenchimento, seleção nativa,
+hover, espera, teclas aprovadas, asserções por elemento, upload restrito ao
+staging da sessão ou a uma raiz local configurada e reações idempotentes a um
+comentário único. Também
+aceita um nome de iframe para as ações que ocorrem dentro dele. Não aceita
+JavaScript enviado pelo harness nem coordenadas. Além de papel/nome acessível,
 aceita `label`, `placeholder`, `title`, `text`, `test_id` e `selector`; CSS/XPath
 são o último recurso e geram um aviso no resultado. Ele usa a
-biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
-Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
-`stderr` para não misturar com JSON-RPC.
+biblioteca Playwright diretamente, sem iniciar um segundo servidor MCP do
+Playwright. O transporte MCP usa `stdio`; toda saída de diagnóstico vai para
+`stderr` para não misturar com JSON-RPC.
+
+### Validar o MCP com Chromium e uma aplicação sintética
+
+O teste ponta a ponta do pacote inicia o servidor MCP real por `stdio`, abre o
+Chromium controlado pelo Playwright e exercita uma aplicação HTTP local
+descartável. Ele cobre descoberta das ferramentas, busca com resposta 200,
+erro 503 com corpo, upload de fixture Unicode seguido de download e comparação
+de conteúdo, além de execução em segundo plano e relatório de suíte. Não acessa
+SAFI, redes externas, bancos ou serviços remotos.
+
+No checkout do repositório, instale as dependências e o navegador uma vez e
+execute somente esse cenário:
+
+```sh
+npm ci
+node mcp_servers/jev-browser-npm/bin/jev-browser-mcp.cjs --install-browser
+node --test mcp_servers/jev-browser-npm/tests/stdio.test.mjs
+```
+
+O teste cria e remove sua aplicação e seus arquivos temporários. Para validar
+Oracle, PostgreSQL ou servidores FTP/FTPS/SFTP, configure serviços de teste
+isolados e credenciais pelo ambiente e use os perfis explicitamente descritos
+em “Perfis e integrações de teste”; o cenário sintético não representa essas
+integrações reais.
 
 O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
 página pode conter instruções maliciosas. O Jev recebe a captura acessível com
@@ -174,18 +201,39 @@ Cada plano pode usar:
 - `assert_network` valida resposta HTTP observada (inclusive sucesso 2xx ou erro
   esperado); `wait_for_request` aguarda uma resposta usando `*` como curinga na
   URL e filtros opcionais de método/status; `assert_ws` confere texto, pares
-  JSON esperados ou código de fechamento de WebSocket;
+  JSON esperados ou código de fechamento de WebSocket. `wait_for_request`
+  consulta o histórico desde o começo da chamada, inclusive requisições feitas
+  durante a navegação inicial e dentro de iframes; URLs cobertas por uma
+  asserção ficam retidas mesmo quando a SPA excede o buffer circular;
 - `evaluate` lê somente caminhos de propriedades como `navigator.mediaDevices`,
   `document.readyState` ou `location.pathname`. Não aceita código, chamadas de
   função, armazenamento local ou propriedades de credenciais. Strings e números
   voltam diretamente; objetos e arrays retornam somente tipo, chaves e tamanho,
   sem despejar seus valores;
+- `http_request` executa GET/HEAD e, com perfil DEV/HML e autorização explícita,
+  também POST/PUT/PATCH/DELETE com a sessão da página; aceita JSON ou multipart,
+  limita a resposta e pode extrair campos escalares para variáveis do fluxo.
+  `inspect_cookies`
+  retorna apenas metadados e valores redigidos; `read_angular_state` devolve o
+  nome do estado e nomes dos parâmetros, sem valores. Inspeções continuam
+  exigindo `local_only: true` e página em loopback. `http_request` exige
+  `local_only` ou um perfil, fica restrito à mesma origem, não segue
+  redirecionamentos e não inclui o corpo sem `include_body: true`;
+- `frame: "first"` seleciona o primeiro iframe; `frame: {"url_contains":"..."}`
+  localiza um iframe pela URL. Uma string diferente continua buscando o nome ou
+  título exato do frame;
+- `navigate_menu` aceita `path` para menus acessíveis ou `screen` para procurar
+  código/nome pela tela Acesso Rápido do SAFI. O segundo caminho usa a interface
+  do SAFI e preserva as verificações de acesso do próprio aplicativo;
 - `new_tab`, `switch_tab` e `new_context` abrem/selecionam abas e criam contexto
   separado dentro do fluxo; `target_page: "popup"` mantém popups abertos para
   passos posteriores;
 - `if_visible` em um clique torna a ação condicional e
   `when: {"visible":"..."}` em cada plano limita as opções do Jev às que
   correspondem à tela atual;
+- `near: {"text":"..."}` com `role` e `name` procura o controle com esse nome
+  entre os elementos posteriores à âncora; o nome pedido não é descartado nem
+  substituído pelo primeiro botão/link seguinte;
 - `fill` é alias de `type`, `press_key` de `press`, `duration_ms` de `wait.ms` e
   `value` de campos de texto. `timeout_ms` funciona por etapa. Placeholders usam
   `{nome}`; referências desconhecidas e `{{nome}}` são recusadas antes da
@@ -199,11 +247,18 @@ Cada plano pode usar:
 - `clear_storage` limpa cookies, local/session storage, IndexedDB, Cache Storage
   e service workers do contexto atual. Como opção de fluxo,
   `options.clear_storage: true` também recarrega a página antes do snapshot inicial;
-- `assert_text`, `assert_value`, `assert_visible`, `assert_hidden` e
-  `assert_enabled`; `assert_text`
-  pode receber apenas `role` quando a região, como `alert`, não tem nome acessível;
+- `assert_text`, `assert_value`, `assert_attribute`, `assert_visible`,
+  `assert_hidden` e `assert_enabled`; `assert_attribute` compara um atributo
+  por igualdade ou substring e não inclui o valor observado no resultado;
+  `assert_text` pode receber apenas `role` quando a região, como `alert`, não tem
+  nome acessível;
 - `upload_file` para input rotulado, botão que abre o seletor de arquivo ou
   dropzone;
+- `generate_fixture`, `assert_download`, `assert_db`, `assert_log`,
+  `start_email_capture`, `assert_email`, `assert_remote_file`,
+  `delete_remote_file` e `run_hook` cobrem dados e serviços externos de teste;
+  os limites, pré-requisitos e regras por ambiente estão na seção
+  [Perfis e integrações de teste](#perfis-e-integrações-de-teste);
 - `target_page: "popup"` para continuar no popup aberto com `expect_popup: true`;
   locators semânticos também atravessam open Shadow DOM. Shadow DOM fechado não
   é acessível ao Playwright;
@@ -222,7 +277,10 @@ As proteções e evidências por etapa usam estes campos:
 - `confirm_modal` combina o clique no gatilho, a conferência do texto e o clique
   afirmativo em uma única etapa protegida. Também aceita os aliases
   `trigger`/`confirm`, por exemplo
-  `{"action":"confirm_modal","trigger":"Salvar","expected_text":"Confirma a alteração?","confirm":"OK"}`;
+  `{"action":"confirm_modal","trigger":"Salvar","trigger_match":"contains","expected_text":"Confirma a alteração?","confirm":"OK"}`.
+  O nome do gatilho é exato por padrão; `trigger_match` também aceita `exact` e
+  `regex`. O texto esperado é conferido antes de clicar no botão afirmativo. O
+  clique no gatilho ainda respeita a autorização de mutação;
 - `mutating: true` marca etapas que gravam dados ou disparam efeitos externos.
   O MCP também classifica botões conhecidos como `Salvar`, `Emitir`, `Cancelar`
   ou `Sim` pelo nome e pelo controle resolvido, inclusive quando o plano usa um
@@ -250,10 +308,19 @@ booleanos. Use `{pedido}` em `flow`, `expected_outcome` e nos campos textuais do
 plano para reutilizar um valor sem editar o roteiro em vários lugares. A ação
 `extract` lê `text` (padrão), `value` ou `attribute` de um elemento e salva o
 resultado na variável indicada por `as`; etapas seguintes podem usar
-`{documento}`. O valor extraído é tratado como sensível e fica oculto no
-resultado por padrão; use `sensitive: false` só quando for apropriado exibi-lo.
-`resolved_target.match_strategy` informa quando um rótulo foi
-associado por proximidade (`label-proximity`) em vez de um `label[for]` direto.
+`{documento}`. O valor extraído é tratado como sensível e fica oculto no
+resultado por padrão; use `sensitive: false` só quando for apropriado exibi-lo.
+Valores que correspondem a segredos já detectados continuam redigidos. Para
+provar que um atributo corresponde a um valor sem devolvê-lo ao harness, use
+`assert_attribute` com `match: "exact"` (padrão) ou `match: "contains"`.
+Por exemplo, para validar o caminho de um documento em um iframe:
+
+```json
+{"action":"assert_attribute","selector":"iframe#documento","attribute":"src","expected":"/documento.pdf","match":"contains"}
+```
+
+`resolved_target.match_strategy` informa quando um rótulo foi
+associado por proximidade (`label-proximity`) em vez de um `label[for]` direto.
 
 A ação `assert_network` verifica respostas observadas depois da etapa anterior,
 incluindo respostas 2xx ou erros esperados como 404. Exemplo:
@@ -271,11 +338,26 @@ incluindo respostas 2xx ou erros esperados como 404. Exemplo:
 Essa asserção aparece na evidência como `response_status`, separado do campo
 `status` da etapa (`passed` ou `failed`). `message_contains` lê somente resposta
 da mesma origem e respeita o limite configurado para captura de corpos.
-`assert_network`, `wait_for_request` e `expected_outcome.request` consultam o
-histórico limitado de respostas depois do marcador da etapa ou do início do
-fluxo. O limite vem de `jev_browser_mcp.browser.max_network_history_events` e
-está em 4096 eventos nesta configuração; assim, chamadas anteriores ao marcador
-não satisfazem a asserção.
+`assert_network` consulta respostas desde o marcador da etapa e usa a resposta
+da navegação inicial como fallback quando nenhuma resposta posterior corresponde.
+`wait_for_request` e `expected_outcome.request` consultam desde o início do fluxo.
+O MCP arma observadores de `wait_for_request` antes dos passos quando o padrão
+pode ser resolvido; se depender de variável extraída, arma assim que a variável
+estiver disponível. A observação retém a resposta mesmo que ela termine durante
+um clique ou que tráfego posterior ultrapasse o buffer circular. `assert_network`
+mantém respostas correspondentes no histórico limitado por
+`jev_browser_mcp.browser.max_network_history_events`. A captura de página também
+observa requisições de iframes.
+Um único plano `fast_path` composto apenas por `assert_network` e
+`wait_for_request` não espera um snapshot visual, então endpoints que respondem
+sem HTML também podem ser verificados. `navigation_http_status` registra um
+status HTTP de erro recebido pela navegação inicial; ele não é uma falha de rede.
+
+`options.capture_network: "all"` inclui até o limite de diagnóstico eventos
+com URL sem query string, método, status, tipo de recurso, duração e cabeçalhos
+de resposta de uma allowlist. `capture_network_url_contains` filtra as URLs.
+Quando o Chromium informa cookies bloqueados, `blocked_cookies` mostra nome,
+domínio, caminho, flags e motivo, sem revelar valores.
 
 Para aguardar a API antes de abrir a interface, passe
 `options.wait_for_http: {"url":"http://localhost:8000/health","timeout_ms":30000}`.
@@ -312,10 +394,38 @@ controle próximo ao texto visível do rótulo.
 `15287210`; `row_containing_exact` continua disponível para texto de célula
 exato. `check` e `uncheck` alteram checkboxes, e `select_option` aceita rótulo
 exato (`option`), valor (`value`) ou rótulo parcial único (`label_contains`).
-`navigate_menu` percorre uma lista de rótulos exatos e abre `#open_btn` quando o
-primeiro item ainda está oculto. Se vários itens visíveis tiverem o mesmo
-rótulo, seleciona a última ocorrência, útil quando o submenu recém-aberto
-repete o nome da categoria pai.
+`navigate_menu` percorre uma lista de rótulos exatos e abre `#open_btn` quando o
+primeiro item ainda está oculto. Se vários itens visíveis tiverem o mesmo
+rótulo, seleciona a última ocorrência, útil quando o submenu recém-aberto
+repete o nome da categoria pai. Para o SAFI, `screen` pesquisa o nome ou código
+na tela Acesso Rápido, exige um resultado único e clica no link oficial da linha;
+por exemplo, `{"action":"navigate_menu","screen":"TCN00022"}`.
+
+Em uma instância local do SAFI, `http_request` pode obter a lista de telas pela
+sessão já aberta sem ler o HTML:
+
+```json
+{
+  "flow": "Consultar telas disponíveis no perfil atual do SAFI",
+  "initial_url": "http://localhost:8011/safi/",
+  "candidate_plans": {
+    "inspect": {
+      "description": "Ler a lista de telas do SAFI no ambiente local",
+      "steps": [{
+        "action": "http_request",
+        "url": "/safi/api/menu/telas_menu",
+        "include_body": true
+      }]
+    }
+  },
+  "options": { "local_only": true, "fast_path": true }
+}
+```
+
+O endpoint usa a sessão atual e pode retornar uma lista específica do perfil.
+Os valores de cookies nunca são retornados. O acesso ao menu continua sujeito
+às permissões verificadas pela própria interface; não use esse diagnóstico
+contra produção.
 
 ```json
 {
@@ -423,21 +533,173 @@ asserções são aceitos. `comment` também é aceito em planos e passos, mas é
 ignorado e não é enviado ao Jev. Campos fora do contrato continuam sendo
 recusados.
 
-### Upload de arquivos
-
-Defina `JEV_BROWSER_UPLOAD_ROOT` como uma pasta absoluta que contenha os arquivos
-de fixture. Cada caminho passado ao fluxo também precisa ser absoluto; o MCP
-resolve links simbólicos e recusa qualquer arquivo fora dessa raiz. Só aceita
-arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e 25 MiB no
-total do passo, conforme `jev_browser_mcp.browser` em `config/ui-testing.json`.
-Os bytes são lidos e validados no processo local antes de serem entregues ao
-Playwright. O MCP não envia esses bytes ao Jev nem os inclui diretamente na
-resposta; texto que o próprio site exibir na interface ainda pode aparecer no
-snapshot devolvido ao harness.
-
-```json
-{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/fixtures/nota.pdf"}
-```
+### Upload de arquivos
+
+Por padrão, `browser_health` cria e devolve `upload_staging_directory` dentro do
+projeto local: `<JEV_BROWSER_PROJECT_ROOT ou diretório de trabalho do MCP>/.jev-browser/tmp/uploads/mcp-<pid>-<sessão>`.
+O harness deve copiar para essa pasta somente os arquivos de fixture que o
+fluxo precisa, e usar o caminho absoluto retornado por `browser_health`. Se o
+processo MCP iniciar com outro diretório de trabalho, defina
+`JEV_BROWSER_PROJECT_ROOT` como o caminho absoluto do projeto. Em um MCP remoto,
+esse caminho pertence ao host do servidor; o harness precisa conseguir gravar
+no mesmo host ou volume.
+
+Cada caminho passado ao fluxo precisa ser absoluto; o MCP resolve links
+simbólicos e recusa qualquer arquivo fora do staging privado daquela sessão e
+da raiz explícita configurada, se houver.
+Só aceita arquivos regulares, até 5 arquivos por passo, 10 MiB por arquivo e
+25 MiB no total do passo, conforme `jev_browser_mcp.browser` em
+`config/ui-testing.json`. O operador pode ajustar os limites no arquivo ou com
+`JEV_BROWSER_MAX_UPLOAD_FILE_BYTES` e
+`JEV_BROWSER_MAX_UPLOAD_TOTAL_BYTES`; o teto total precisa ser pelo menos o
+limite por arquivo. `browser_health` e `describe_actions` mostram os valores
+ativos. Esse teto pertence ao MCP e ao navegador local; alterá-lo não aumenta
+o limite de arquivo aceito pelo provedor Jev. Os bytes são lidos e validados no
+processo local antes de serem entregues ao Playwright. O MCP não envia esses
+bytes ao Jev nem os inclui diretamente na resposta; texto que o próprio site
+exibir na interface ainda pode aparecer no snapshot devolvido ao harness.
+
+Depois de um fluxo que usa `upload_file`, `generate_fixture` ou multipart com
+arquivos, o MCP remove todos os arquivos e subpastas da pasta exclusiva da
+sessão, inclusive quando o fluxo falha. Arquivos fornecidos pela raiz
+`JEV_BROWSER_UPLOAD_ROOT` não são apagados. Um
+`dry_run` ou `confirmation_required` preserva os arquivos para que a próxima
+chamada confirmada possa usá-los; o encerramento normal do servidor também
+limpa essa pasta. O diretório e os diretórios pais permanecem, prontos para uma
+próxima chamada. O original fora da pasta de staging não é tocado.
+
+`JEV_BROWSER_UPLOAD_ROOT` continua disponível como uma raiz explícita adicional;
+o MCP aceita arquivos tanto dela quanto do staging privado do projeto e nunca
+apaga arquivos da raiz explícita. A pasta privada gerenciada no projeto continua
+disponível para fixtures geradas pelo MCP e multipart; só o staging gerenciado
+é limpo automaticamente. Não aponte para o disco inteiro ou para a pasta home.
+
+Fixtures `generate_fixture` aceitam `kind: "pdf"`, `"text"` ou `"bytes"`,
+`as`, `file_name` (inclusive Unicode), `content` para PDF/texto e `size_bytes`
+para bytes determinísticos. São criadas em
+`.jev-browser/tmp/uploads/` dentro do projeto e expostas como variável para
+passos seguintes. O tamanho máximo é o menor entre
+`max_upload_file_bytes` configurado e **47 MiB**, limite atual do provedor Jev
+para um arquivo. `assert_download` compara SHA-256, tamanho e tipo MIME do
+último download com o fixture informado. O original do fixture continua sendo
+temporário e é limpo no teardown do fluxo ou da suíte.
+
+### Perfis e integrações de teste
+
+O MCP lê perfis opcionais de `.jev-browser/profiles.json` no projeto. Para outro
+arquivo dentro do projeto, defina `JEV_BROWSER_PROFILES_FILE` com caminho
+absoluto. O arquivo é JSON versão 1 e nunca deve conter senhas ou tokens:
+campos como `connection_env`, `password_env` e `username_env` guardam somente o
+nome da variável de ambiente, e os valores são lidos pelo processo MCP.
+
+Exemplo mínimo de perfil DEV:
+
+```json
+{
+  "version": 1,
+  "profiles": {
+    "dev": {
+      "environment": "dev",
+      "application_origins": ["http://localhost:8000"],
+      "database": {
+        "engine": "postgresql",
+        "connection_env": "JEV_TEST_DATABASE_URL",
+        "timeout_ms": 5000,
+        "max_rows": 100
+      },
+      "log_sources": {"api": "logs/test-api.log"},
+      "smtp_capture": {"port": 0, "bind_address": "127.0.0.1", "max_messages": 20},
+      "remotes": {},
+      "hooks": {}
+    }
+  }
+}
+```
+
+`database.engine` suporta `postgresql` e `oracle`. PostgreSQL usa
+`connection_env`; Oracle usa `connect_env`, `user_env` e `password_env`. Ambos
+exigem `timeout_ms` e `max_rows`. `assert_db` aceita apenas um `SELECT` sem
+comandos adicionais, usa binds, transação somente leitura, timeout e teto de
+linhas do perfil. Configure também as credenciais para uma identidade de banco
+com privilégios somente de leitura; a transação read-only do MCP complementa
+essa separação. Essa ação é somente leitura em DEV, HML e PRD.
+
+`application_origins` é a allowlist de origens HTTP. `http_request` usa a sessão
+da página, aceita `GET`, `HEAD`, `POST`, `PUT`, `PATCH` e `DELETE`, JSON ou
+multipart. POST/PUT/PATCH/DELETE exigem `options.allow_mutations: true` e um
+perfil DEV/HML cuja allowlist inclua a origem. PRD recusa mutações. HML só
+permite escrita na aplicação com essa autorização explícita. Para uma página
+local sem perfil, `local_only: true` só libera GET/HEAD em loopback.
+`extract` usa caminhos JSON e só expõe valores escalares; campos com nomes
+sensíveis entram na redação automática.
+
+`log_sources` define nomes e caminhos de arquivos que o MCP pode consultar.
+`assert_log` lê apenas essas origens e pode restringir o trecho ao que foi
+escrito desde o início do fluxo ou desde `step:N`; logs são sempre somente
+leitura. Configure caminhos absolutos apenas quando a política local exigir;
+prefira caminhos relativos ao projeto.
+
+`smtp_capture` sobe um servidor de captura limitado a `127.0.0.1` ou `::1`;
+`port: 0` escolhe uma porta livre. Use `start_email_capture` antes de acionar o
+envio na aplicação e depois `assert_email` com destinatário, assunto ou corpo.
+O servidor guarda as mensagens somente em memória durante a chamada/suíte e as
+remove no teardown. A resposta e o relatório registram a asserção e horário,
+sem incluir assunto ou corpo.
+
+`remotes` permite verificar arquivos em FTP, FTPS ou SFTP, limitado a um
+`root` remoto configurado. Credenciais vêm de `username_env` e `password_env`;
+SFTP também exige `host_fingerprint_env` para validar a chave do host.
+Configure cada usuário remoto em uma pasta isolada/chroot compatível com o
+`root` allowlisted.
+`assert_remote_file` verifica existência e, opcionalmente, tamanho e SHA-256.
+`delete_remote_file` é destrutivo: só funciona em perfil DEV com
+`allow_mutations: true`. Banco e logs permanecem somente leitura em todos os
+ambientes.
+
+`hooks` são scripts Node nomeados e allowlisted, com caminho dentro do projeto,
+argumentos declarados (`string`, `integer` ou `boolean`), comprimento máximo e
+`timeout_ms` obrigatório. Não há shell nem comando arbitrário; hooks só podem
+ser definidos/executados em DEV e precisam de `allow_mutations: true`. PRD
+recusa hooks e qualquer etapa marcada `mutating: true`.
+
+### Suítes JSON e relatórios
+
+Guarde uma definição por PBI em `.jev-browser/suites/<id>.json`. Ela possui
+`version: 1`, `id`, `criteria` e opcionalmente `description`, `params`,
+`environment_profile`, `flows`, `setup` e `teardown`. Cada fluxo reutilizável
+tem `flow`, `candidate_plans` e opcionalmente `initial_url`, `expected_outcome`,
+`params` e `options`; cada critério tem `id`, `description` e `flow`, que pode
+referenciar um fluxo pelo nome ou declará-lo inline. Placeholders usam
+`{nome}` e recebem prioridade dos parâmetros do pedido sobre os parâmetros do
+arquivo.
+
+Antes de abrir o navegador, `run_test_suite` valida todo o JSON, caminhos de
+relatório, placeholders, limites, perfil e todas as etapas de setup, critérios
+e teardown. Executa sequencialmente por padrão e tenta teardown mesmo se setup
+ou critério falhar. A suíte mantém a sessão do browser e a captura de integrações
+durante suas etapas, depois limpa os arquivos temporários. Um relatório
+Markdown é salvo por padrão em `.jev-browser/reports/`; `report_path` aceita um
+caminho relativo dentro do projeto. O relatório inclui status por critério,
+passos, duração, localizadores, evidências de rede, banco, logs, e-mail, arquivos,
+screenshots e limpeza. URLs de evidência perdem query, fragmento e segmentos que
+parecem IDs; valores de campos e corpos de mensagens não são incluídos. Valores
+secretos conhecidos por variáveis de ambiente e parâmetros sensíveis são
+redigidos. O tamanho do arquivo é limitado por
+`max_test_suite_report_bytes`; se o relatório atingir o teto, o resultado
+informa `report_truncated: true` e o próprio Markdown marca o truncamento.
+
+Para permitir polling quando a chamada for longa, use `background: true` e
+consulte o `run_id` com `get_browser_flow_result`. A definição da suíte precisa
+ser criada no projeto do processo MCP antes da chamada. `describe_actions`
+publica o formato da suíte, ferramentas, opções, ações, campos condicionais e
+limites atualmente configurados; `browser_health` informa versões e capacidades.
+
+Consulte `browser_health` para descobrir a pasta da sessão e, então, passe o
+caminho absoluto do arquivo preparado pelo harness:
+
+```json
+{"action":"upload_file","target":"input","label":"Nota fiscal","file_path":"/projeto/.jev-browser/tmp/uploads/mcp-1234-pid-1234/nota.pdf"}
+```
 
 Para uma área de arrastar, use o papel e o nome acessível da dropzone. Para um
 botão que abre a janela nativa, use `target: "button"`; sem `target`, a presença
@@ -447,9 +709,9 @@ de `label` seleciona o input e `role`/`name` seleciona esse botão.
 {"action":"upload_file","target":"dropzone","role":"region","name":"Anexos","file_paths":["/fixtures/a.pdf","/fixtures/b.png"]}
 ```
 
-Se `JEV_BROWSER_UPLOAD_ROOT` não estiver definido, a ação recusa a execução. O
-limite evita que um plano transforme o MCP em leitor arbitrário de arquivos do
-computador.
+O limite evita que um plano transforme o MCP em leitor arbitrário de arquivos
+do computador; sem uma raiz explícita, só a pasta temporária isolada da sessão
+é autorizada.
 
 Exemplo de chamada:
 
@@ -528,7 +790,9 @@ compartilhe esse arquivo. `storage_state` não pode ser combinado com
 `fresh_context` ou `clear_storage`.
 
 `browser.max_flow_steps` limita os passos de cada plano candidato; os planos
-não são somados. `browser.max_text_entry_chars` limita cada valor digitado. O
+não são somados. O padrão é 24 e pode ser aumentado em `config/ui-testing.json`
+ou por `JEV_BROWSER_MAX_FLOW_STEPS` (por exemplo, `30`).
+`options.max_flow_steps` pode reduzir esse teto por chamada. `browser.max_text_entry_chars` limita cada valor digitado. O
 resultado contém `status`, o plano escolhido, as ações executadas, a última
 captura acessível e se o texto descritivo esperado apareceu. `expected_outcome`
 como string é descrição, não uma asserção: `expected_outcome_visible` é
@@ -547,12 +811,17 @@ quando nenhuma dessas condições se aplica; confiança do Jev, sozinha, não
 comprova o resultado. `environment_error` identifica falha de
 navegação, autenticação ou sessão do browser; `navigation_error` contém o código
 detectado, como `ERR_CONNECTION_REFUSED`, `AUTHENTICATION_REQUIRED` ou
-`BROWSER_DISCONNECTED`, e `reason` orienta a recuperação. Se uma navegação falhar
+`BROWSER_DISCONNECTED`, `BROWSER_PAGE_NOT_RESTORED` ou
+`BROWSER_PROFILE_IN_USE`, e `reason` orienta a recuperação. Se uma navegação falhar
 e a chamada seguinte tentar reutilizar a página, o MCP informa que a navegação
 anterior não carregou; reinicie a navegação com
 `continue_from_current_page: false` (ou o alias `reuse_page: false`). Uma sessão
-desconectada pode ser reaberta por `browser_health`; o fluxo só é repetido
-automaticamente uma vez se nenhuma etapa mutável tiver sido executada.
+desconectada pode ser reaberta por `browser_health`. `run_browser_flow` também
+tenta reconectar e repetir uma vez quando a desconexão acontece antes da primeira
+etapa; a repetição exige `initial_url`. Sem essa URL, o resultado informa
+`BROWSER_PAGE_NOT_RESTORED`, e chamadas posteriores em `reuse_page` continuam
+recusadas até uma nova navegação explícita. Se qualquer etapa já executou ou
+há token de confirmação de mutação, o MCP não repete o fluxo automaticamente.
 
 `current_url` é devolvido para diagnóstico sem query string nem fragmento; IDs
 longos no caminho também podem ser redigidos. `timings_ms.ready_ms` mede a espera
@@ -568,9 +837,14 @@ origem são capturadas mesmo quando usam transferência chunked e não enviam
 `Content-Length`. Corpos acima do limite, com formato inválido ou que não
 podem ser lidos com segurança são omitidos e explicados em `warnings`.
 
-`jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
-seletores e condições. `JEV_BROWSER_UPLOAD_ROOT` libera uploads somente dentro
-de uma pasta absoluta escolhida pelo operador.
+`jev_browser_mcp.browser.max_action_timeout_seconds` limita esperas por ações,
+seletores e condições. `JEV_BROWSER_PROJECT_ROOT` troca o diretório de projeto
+usado para staging quando o diretório de trabalho do MCP não é o projeto. A
+pasta `.jev-browser/tmp/uploads` deve ser tratada como temporária e ignorada
+pelo Git. `JEV_BROWSER_UPLOAD_ROOT` adiciona uma raiz absoluta escolhida pelo
+operador para arquivos fornecidos pelo harness; o MCP não apaga arquivos dessa
+raiz. O staging privado do projeto continua ativo para fixtures e multipart
+gerados pelo MCP.
 `jev_browser_mcp.browser.max_upload_files`, `max_upload_path_chars`,
 `max_upload_file_bytes` e `max_upload_total_bytes` limitam quantidade e tamanho.
 Não configure a raiz como o disco inteiro ou a pasta home: use uma pasta de
@@ -584,8 +858,9 @@ continua informada mesmo quando a lista é truncada.
 
 O `run_browser_flow` aceita `options` com `fast_path`, `snapshot_scope`,
 `block_trackers`, `block_fonts`, `local_only`, `busy_selectors`,
-`auto_angular_idle`, `login_url_contains`, `login_text`, `capture_console_errors`,
-`capture_network_errors`, `capture_network_error_bodies`, `ready_timeout_seconds`,
+`auto_angular_idle`, `login_url_contains`, `login_text`, `capture_console_errors`,
+`capture_network_errors`, `capture_network_error_bodies`, `capture_network`,
+`capture_network_url_contains`, `ready_timeout_seconds`,
 `ready_network_idle`, `ready_stable_ms`, `ready_text`, `ready`, `continue_from_current_page`,
 `reuse_page`, `reuse_page_match`, `step_timeout_seconds`, `max_flow_steps`, `return_snapshot`,
 `screenshot_on_failure`, `screenshot_on_success`, `trace_on_failure`,
@@ -642,6 +917,16 @@ uma lista combina condições, e todas precisam passar. `has_value` aceita
 `ready_network_idle: true` solicita uma espera best-effort por `networkidle`.
 `ready_timeout_seconds` limita a espera de inicialização e `ready_stable_ms`
 define a janela usada para considerar o snapshot estável.
+
+Se a duração prevista ultrapassar o timeout de chamada do harness, passe
+`background: true` em `run_browser_flow`. A chamada retorna um `run_id`; consulte
+`get_browser_flow_result` com esse ID e, opcionalmente, `wait_ms` de até 30000
+para aguardar a conclusão, mantendo esse valor abaixo do timeout do harness.
+No resultado da consulta, `status` indica se a execução terminou; o status do
+fluxo em si fica em `result.status`. Os resultados ficam na memória do processo
+MCP por 30 minutos e saem antes se o limite de execuções retidas for atingido.
+Reiniciar o servidor apaga execuções e resultados pendentes. O modo síncrono
+permanece disponível para fluxos curtos.
 
 `console_levels` aceita `log`, `info`, `debug`, `warn` e `error`. Com
 `console_levels: ["log","warn","error"]` e `capture_network_errors`, o retorno
@@ -649,6 +934,8 @@ traz mensagens do console agrupadas por texto e nível (`console_messages` com
 `count`), além de `console_errors` para compatibilidade. `network_failures`
 contém eventos limitados em quantidade e tamanho. Mensagens idênticas do console
 são agrupadas em uma entrada com `count`.
+Controles sem nome acessível aparecem em um único aviso com a contagem e alguns
+exemplos, em vez de gerar uma mensagem por controle.
 Respostas HTTP 4xx/5xx e requisições que falham são listadas; query strings,
 fragmentos, valores de formulário e nomes de arquivo são removidos ou
 sanitizados. `capture_network_error_bodies: true` lê somente respostas JSON
@@ -689,8 +976,9 @@ Para testar microfone, conceda permissão no escopo da chamada:
 ```
 
 `fake_media` aceita tanto o caminho WAV direto quanto o objeto
-`{"audio":"caminho.wav"}`. Exige um WAV RIFF válido dentro de
-`JEV_BROWSER_UPLOAD_ROOT` e respeita os mesmos limites de upload. Ao informar
+`{"audio":"caminho.wav"}`. Exige um WAV RIFF válido dentro do staging privado
+do projeto ou de `JEV_BROWSER_UPLOAD_ROOT` e respeita os mesmos limites de
+upload. Ao informar
 `fake_media`, o MCP concede automaticamente a permissão `microphone`, adiciona
 as opções de dispositivo falso do Chromium e usa o arquivo como entrada de
 áudio. Sem esse arquivo, a
@@ -718,12 +1006,12 @@ Chrome/Edge; em outros sistemas, usa o `SingletonLock` do Chromium. O caminho
 padrão já separa processos por PID; configure `JEV_BROWSER_PROFILE` para mudar
 a raiz e `JEV_BROWSER_SESSION_ID` para nomear a instância.
 Resultados MCP incluem `server_version`; erros também começam com a versão do
-servidor para facilitar a comparação entre instalações. A ferramenta
-`browser_health` informa se a sessão está ativa e tenta reconectar um browser
-que encerrou desde a chamada anterior. Passe `{"restart":true}` para fechar e
-reiniciar somente o navegador administrado por este processo MCP. Um fluxo pode
-ser repetido automaticamente uma vez após `BROWSER_DISCONNECTED` quando nenhuma
-etapa mutável foi executada.
+servidor para facilitar a comparação entre instalações. A ferramenta
+`browser_health` informa se a sessão está ativa e tenta reconectar um browser
+que encerrou desde a chamada anterior. Passe `{"restart":true}` para fechar e
+reiniciar somente o navegador administrado por este processo MCP. Perfil ocupado
+é devolvido como `BROWSER_PROFILE_IN_USE` com o PID detectado e não provoca
+encerramento do Chrome/Edge existente.
 
 `harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
 `computer_user_data_dir` deve ficar fora do repositório e conter `{browser}` e

package/mcp_servers/jev-browser-npm/bin/jev-browser-mcp.cjs

@@ -11,7 +11,10 @@ Usage:
 
 Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
 the environment. The default mode is computer; use JEV_BROWSER_MODE=harness to select isolated headless mode.
-For upload_file, set JEV_BROWSER_UPLOAD_ROOT to a dedicated fixture directory.
+browser_health reports the project-local upload staging directory by default.
+Set JEV_BROWSER_UPLOAD_ROOT for a dedicated persistent fixture directory.
+JEV_BROWSER_MAX_FLOW_STEPS, JEV_BROWSER_MAX_UPLOAD_FILE_BYTES and
+JEV_BROWSER_MAX_UPLOAD_TOTAL_BYTES override the corresponding configured caps.
 `;
 
 async function main() {