SPEC: BK-129 Browser Control Runtime

Objetivo

Criar no cerebro-kernel a fundacao canonica para automacao real por navegador, deixando de depender apenas de API quando o canal operacional exigir interface web.

O primeiro caso de uso concreto deste BK e o desbloqueio do BK-104 do rionoteatro, cuja trilha via Graph API para Facebook Page Events foi fechada como bloqueada (GraphMethodException code 100 / subcode 33).

Escopo deste slice

1. Adicionar modulo kernel/browser_control.js com:

• catalogo de perfis de browser control;
• validacao de definicoes;
• preview deterministico de plano com resolucao de placeholders.

1. Criar o diretorio kernel/config/browser_profiles/ com um perfil inicial do RNT para Page Events.
2. Expor contrato WS minimo no kernel/index.js:

• studio_browser_catalog
• studio_browser_plan_preview
• studio_browser_run_start

1. Adicionar executor real com Chromium do host para os tipos de passo ja suportados.
2. Suportar sessao autenticada por storage state quando o fluxo exigir contexto logado.
3. Disponibilizar runner CLI para preview/execucao controlada de profiles fora do Studio, com overrides operacionais para storage state e diretório de artefatos.
4. Disponibilizar capturador guiado de storage state para preparar sessao autenticada fora do repo.
5. Cobrir o modulo com teste unitario.
6. Atualizar backlog/changelog/lock do cerebro.

Fora de escopo deste slice

• automacao invisivel 24/7 sem gate humano;
• publicacao direta em producao em superficie externa autenticada;
• UI dedicada no Studio;
• remocao do gate humano para studio_browser_run_start.

Contrato WS minimo

studio_browser_catalog

Entrada:

```json

{

"type": "studio_browser_catalog",

"requestId": "abc",

"project": "rionoteatro"

}

```

Saida:

```json

{

"type": "studio_browser_catalog",

"ok": true,

"requestId": "abc",

"project": "rionoteatro",

"profiles": []

}

```

studio_browser_plan_preview

Entrada:

```json

{

"type": "studio_browser_plan_preview",

"requestId": "abc",

"profileId": "rnt-facebook-page-event-create-v1",

"inputPayload": {

"page_slug": "rionoteatro",

"event_title": "Titulo",

"event_url": "https://rionoteatro.com.br/evento/123",

"start_iso": "2026-03-20T20:00:00-03:00"

}

}

```

Saida:

```json

{

"type": "studio_browser_plan_preview",

"ok": true,

"requestId": "abc",

"profileId": "rnt-facebook-page-event-create-v1",

"plan": {}

}

```

studio_browser_run_start

Entrada:

```json

{

"type": "studio_browser_run_start",

"requestId": "abc",

"sessionKey": "studio-browser-rnt",

"profileId": "rnt-facebook-page-event-create-v1",

"confirmed": true,

"headless": true,

"storageState": "/root/.cache/cerebro/browser-storage-state/facebook-rnt.json",

"outputRoot": "/tmp/cerebro-browser-runs",

"inputPayload": {

"page_slug": "rionoteatro",

"event_title": "Titulo",

"event_url": "https://rionoteatro.com.br/evento/123",

"start_iso": "2026-03-20T20:00:00-03:00"

}

}

```

Runner CLI

Script: kernel/scripts/browser_profile_runner.js

Exemplo de preview:

```bash

node scripts/browser_profile_runner.js \

--profile rnt-facebook-page-events-probe-v1 \

--input-json '{"page_slug":"rionoteatro"}'

```

Exemplo de execucao:

```bash

node scripts/browser_profile_runner.js \

--profile rnt-facebook-page-events-probe-v1 \

--input-json '{"page_slug":"rionoteatro"}' \

--storage-state /root/.cache/cerebro/browser-storage-state/facebook-rnt.json \

--output-root /tmp/cerebro-browser-runs \

--execute --confirmed

```

Observacao:

• --storage-state injeta caminho explicito para a sessao autenticada sem depender de env;
• --output-root permite desviar screenshots/HTML para fora do repositorio durante RCA e operacao.
• o mesmo override operacional agora tambem pode ser passado no payload WS (storageState / outputRoot) para o Studio.

Captura de storage state

Script: kernel/scripts/browser_capture_storage_state.js

Exemplo:

```bash

xvfb-run -a node scripts/browser_capture_storage_state.js \

--url https://www.facebook.com/rionoteatro/events \

--output /root/.cache/cerebro/browser-storage-state/facebook-rnt.json

```

Observacao:

• o script abre uma sessao headed quando houver display;
• o operador faz login manualmente;
• ao confirmar no terminal, o storage state e salvo fora do repo para reutilizacao pelo runtime.

Fluxo alternativo recomendado: captura local + importacao segura

Quando a Meta entrar em loop de checkpoint/antibot na VPS, a captura deve ser feita na maquina local do operador e apenas importada para o Cérebro.

Importador na VPS:

```bash

node /root/cerebro/kernel/scripts/browser_import_storage_state.js \

--input /caminho/recebido/facebook-rnt-local.json

```

O importador:

• valida se o JSON tem estrutura de storage state do Playwright;
• exige sessao Meta autenticada (c_user + xs) por padrao;
• cria backup do arquivo canonico anterior antes de sobrescrever;
• grava no caminho oficial /root/.cache/cerebro/browser-storage-state/facebook-rnt.json.

Checklist operacional da captura local:

1. Na maquina local, abrir um navegador normal e concluir login/checkpoint da Meta em ambiente humano.
2. Gerar um storage state do Playwright nessa mesma maquina.
3. Enviar o JSON para a VPS por canal seguro.
4. Rodar browser_import_storage_state.js na VPS.
5. Revalidar probe e create-flow no Cérebro.

Capturador local portavel:

```bash

node browser_capture_storage_state_local.js \

--url https://www.facebook.com/rionoteatro/events \

--output ./facebook-rnt-local.json

```

Observacao:

• o arquivo kernel/scripts/browser_capture_storage_state_local.js foi criado exatamente para esse uso fora da VPS;
• ele tenta carregar playwright primeiro e cai para playwright-core se existir;
• na maquina local, o caminho mais simples e npm install playwright antes de executar.

Resumo sem importar:

```bash

node /root/cerebro/kernel/scripts/browser_import_storage_state.js \

--input /caminho/recebido/facebook-rnt-local.json \

--summary-only

```

Saida inicial:

```json

{

"type": "studio_browser_run_ack",

"ok": true,

"requestId": "abc",

"runId": "browser-run-123"

}

```

Criterios de aceite deste slice

• o catalogo retorna perfis por projeto;
• o preview falha quando input obrigatorio faltar;
• o preview resolve placeholders nos passos do perfil;
• o executor roda um fluxo local real com Chromium do host;
• o executor aceita storage state quando um profile exigir sessao autenticada;
• o runner CLI consegue gerar preview e executar perfis com gate explicito;
• o contrato fica testado em unitarios do kernel;
• o backlog do cerebro passa a referenciar o BK como trilha oficial para browser control.

Estado final das fases

1. Fase 1 | Fundacao

• concluida com runtime base, executor real via Chromium do host, perfis declarativos, runner CLI e capturador guiado.

1. Fase 2 | Captura autenticada

• concluida com storage state real preservado fora do repo em /root/.cache/cerebro/browser-storage-state/facebook-rnt.json;
• screenshot da captura preservado ao lado do arquivo (facebook-rnt.json.png).

1. Fase 3 | Probe autenticado

• concluida com execucao real do perfil rnt-facebook-page-events-probe-v1;
• comando validado:

```bash

node /root/cerebro/kernel/scripts/browser_profile_runner.js \

--profile rnt-facebook-page-events-probe-v1 \

--input-json '{"page_slug":"rionoteatro"}' \

--storage-state /root/.cache/cerebro/browser-storage-state/facebook-rnt.json \

--output-root /tmp/cerebro-browser-runs \

--execute --confirmed

```

• artefatos gerados em /tmp/cerebro-browser-runs/rnt-facebook-page-events-probe-v1-1773731903027/.

1. Fase 4 | Create-flow controlado

• concluida no sentido operacional seguro: o perfil rnt-facebook-page-event-create-v1 agora exige sessao autenticada e para antes de qualquer submit/publicacao;
• o output da run vira evidencia de draft (draft.png + draft.html) para endurecimento iterativo dos seletores reais.

1. Fase 5 | Integracao operacional

• concluida com ligacao direta ao BK-104 no rionoteatro: quando o Graph API continuar bloqueando, o cron gera a fila runtime admin/runtime/facebook_page_events_browser_queue.json e o payload sample admin/runtime/facebook_page_events_browser_sample_input.json;
• a Central de Redes Sociais passou a expor o estado desse fallback e os comandos exatos para o Cérebro rodar probe/create-flow.

Blindagem adicional apos a primeira rodada

• foi confirmado em execucao real posterior que o storage state salvo pode expirar ou perder autenticacao sem aviso;
• o runtime agora suporta assert_not_selector para falhar cedo quando o browser cair em gate de login;
• os perfis rnt-facebook-page-events-probe-v1 e rnt-facebook-page-event-create-v1 passaram a validar a ausencia dos campos email/senha antes de seguir para captura ou create-flow.
• o fluxo operacional oficial agora inclui captura local + importacao segura quando a Meta bloquear a VPS com checkpoint.

Path List (lock-files)

• docs/LOCK.md
• docs/BACKLOG.md
• docs/CHANGELOG.md
• docs/specs/BK-129-browser-control-runtime.md
• docs/changelog/2026/CL-2026-03-17-BK-129.md
• kernel/browser_control.js
• kernel/browser_executor.js
• kernel/config/browser_profiles/rnt-facebook-page-event-create-v1.json
• kernel/config/browser_profiles/rnt-facebook-page-events-probe-v1.json
• kernel/index.js
• kernel/scripts/browser_profile_runner.js
• kernel/scripts/browser_capture_storage_state.js
• kernel/tests/unit/browser-control.test.js
• kernel/tests/unit/browser-profile-runner.test.js
• kernel/tests/unit/browser-executor.test.js
• kernel/package.json
• kernel/package-lock.json
• kernel/node_modules/.package-lock.json