@diegosouzacdv/jev-browser-mcp 0.7.1 → 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.1"],
+      "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.1
+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.1
+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.1 --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,24 +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, 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 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,
+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
@@ -185,11 +210,15 @@ Cada plano pode usar:
   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 somente GET com a sessão da página; `inspect_cookies`
+- `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. As três ações exigem
-  `local_only: true` e página em loopback. `http_request` fica restrito à mesma
-  origem, não segue redirecionamentos e limita/redige o corpo opcional;
+  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;
@@ -202,6 +231,9 @@ Cada plano pode usar:
 - `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
@@ -215,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;
@@ -238,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
@@ -266,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:
@@ -290,9 +341,13 @@ da mesma origem e respeita o limite configurado para captura de corpos.
 `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.
-URLs cobertas por uma asserção são retidas em um buffer separado limitado por
-`jev_browser_mcp.browser.max_network_history_events` (4096 eventos nesta
-configuração). A captura de página também observa requisições de iframes.
+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
@@ -478,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
@@ -502,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:
 
@@ -583,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` é
@@ -628,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
@@ -703,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
@@ -752,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

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() {

package/mcp_servers/jev-browser-npm/src/browser-flow-runs.mjs

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+
+export function createBrowserFlowRunStore({ maxEntries, retentionMs, now = Date.now, createId = randomUUID }) {
+  const runs = new Map();
+
+  const pruneExpired = () => {
+    for (const [runId, run] of runs) {
+      if (run.status !== "running" && run.finishedAt + retentionMs <= now()) runs.delete(runId);
+    }
+  };
+
+  const makeRoom = () => {
+    pruneExpired();
+    while (runs.size >= maxEntries) {
+      const completed = [...runs].find(([, run]) => run.status !== "running");
+      if (!completed) throw new Error("all background flow slots are in use");
+      runs.delete(completed[0]);
+    }
+  };
+
+  const snapshot = (run) => ({
+    run_id: run.id,
+    status: run.status,
+    elapsed_ms: Math.max(0, now() - run.startedAt),
+    ...(run.finishedAt === undefined ? {} : { finished_at: new Date(run.finishedAt).toISOString() }),
+    ...(run.result === undefined ? {} : { result: run.result }),
+    ...(run.error === undefined ? {} : { error: run.error }),
+  });
+
+  return Object.freeze({
+    start(execute) {
+      if (typeof execute !== "function") throw new TypeError("background flow must be a function");
+      makeRoom();
+      const run = { id: createId(), status: "running", startedAt: now() };
+      runs.set(run.id, run);
+      run.finished = Promise.resolve().then(execute).then((result) => {
+        run.result = result;
+        run.status = "completed";
+      }, (error) => {
+        run.error = String(error?.message || error).slice(0, 1000);
+        run.status = "failed";
+      }).finally(() => {
+        run.finishedAt = now();
+      });
+      return { run_id: run.id, status: run.status };
+    },
+    async get(runId, waitMs = 0) {
+      pruneExpired();
+      const run = runs.get(runId);
+      if (!run) return undefined;
+      if (run.status === "running" && waitMs > 0) {
+        await Promise.race([run.finished, new Promise((resolve) => setTimeout(resolve, waitMs))]);
+      }
+      return snapshot(run);
+    },
+  });
+}