@omnivoice/page-agent 0.5.0 → 0.6.1

package/README.md

@@ -56,6 +56,54 @@ AGENT_API_KEY=... AGENT_BASE_URL=https://api.openai.com/v1 AGENT_MODEL=gpt-4o-mi
 O gateway expõe `GET /config`, `POST /v1/chat/completions` e `GET /health`, e injeta a chave ao chamar o provedor.
 As variáveis `AGENT_*` estão descritas no cabeçalho de `server/agent-gateway.mjs`.
 
+`GET /config` também pode levar três campos opcionais, sempre sem a chave (o `AGENT_CONFIG` aceita os mesmos nomes
+em JSON; o ambiente vence o arquivo):
+
+| Variável | Campo em `/config` | Efeito |
+|---|---|---|
+| `AGENT_INSTRUCTIONS` | `instructions: { system }` | Texto de instruções de sistema (até 8 KB; acima disso o gateway não sobe). Só aparece se não estiver vazio. |
+| `AGENT_BRAIN` (`on`/`off`) | `brain` | Pede ao widget que ligue o segundo cérebro. Padrão `off`. O gateway só repassa o sinal. |
+| `AGENT_DEBUG` (`on`/`off`) | `debug` | Pede ao widget o diagnóstico por passo. Padrão `off`. |
+
+`AGENT_MAX_STEPS` alto aumenta o custo de loops: um agente que repete a mesma ação continua chamando o modelo
+até o limite de passos.
+
+## Segundo cérebro (opcional)
+
+Sem ele o agente é o do upstream: o modelo decide tudo e nada o impede de repetir um clique sem efeito até o limite de passos,
+de declarar sucesso sem prova ou de preencher e salvar um formulário numa tarefa de leitura. Com `brain: true` o agente
+ganha um supervisor:
+
+- **Não-progresso:** a mesma ferramenta com a mesma evidência 3 vezes seguidas encerra a tarefa com o motivo (menus que só
+  alternam aberto/fechado contam como repetição).
+- **Política de escrita:** digitar, selecionar e clicar em controles de alteração (Salvar, Criar, Excluir, Atualizar, ...) só
+  quando a TAREFA pede. Ler e navegar são livres. Verbo negado ("não altere nada") não conta como pedido. A recusa volta ao
+  agente com o motivo; 3 recusas encerram a tarefa. Modos: `task-intent` (padrão), `allow`, `deny`.
+- **Veredito:** o resultado ganha `verification` (`verified`, `unverified` ou `failed`). Só vira `verified` quando valores
+  explícitos da tarefa foram confirmados no DOM; tarefas abertas ficam `unverified` (com `[não verificado: ...]` no texto quando
+  nada mudou na página), sem serem reprovadas.
+- **Teclado:** o núcleo não tem ferramenta de tecla, então o agente não confirmava buscas nem fechava paletas e overlays. Com o
+  cérebro ele ganha `press_key` (Enter, Escape, setas, Tab, Backspace, Espaço) e `input_text` passa a tratar um `\n` no fim do texto
+  como Enter. Enter que enviaria um formulário ou ativaria um botão de alteração passa pela política de escrita.
+- **Mapa e histórico:** mapa da página (`procurar_na_pagina`, `ir_para_regiao`, `await_effect`) e compactação de passos antigos.
+
+```ts
+const widget = mountWidget({ model, baseURL, brain: true });                       // padrões
+mountWidget({ model, baseURL, brain: { writePolicy: "deny", repeatLimit: 4 } });   // opções
+```
+
+Por CDN, `data-auto-init="false"` e `PageAgent.mountWidget({ ..., brain: true })`. Com o gateway, `AGENT_BRAIN=on` faz o
+`/config` pedir o cérebro, então o front não precisa mudar. **Opt-in:** sem a flag o comportamento é idêntico e o código do
+cérebro nem é carregado (no ESM é um `import()` dinâmico). Ele guarda perfis de página em IndexedDB, por origem, sem valores
+digitados por pessoas.
+
+**Diagnóstico:** `debug: true` (ou `AGENT_DEBUG=on`) registra, por passo, o objetivo, a ferramenta e o conteúdo que o modelo
+recebeu, no console e em `window.__pageAgentDebug`. Esse conteúdo pode ter dados de clientes: use só para investigar.
+
+**Extensões:** `mountWidget` aceita `hooks` (`onBeforeStep`, `onAfterStep`, `onBeforeTask`, `onAfterTask`, `onDispose`,
+`transformPageContent`), `extensions` (`{ customTools, instructions, hooks }`) e `resolveExtensions`. Ferramentas são
+mescladas (a última vence), instruções concatenadas, ganchos encadeados em ordem, e o erro de um gancho não derruba a tarefa.
+
 ## Voz em tempo real (opcional)
 
 `@omnivoice/page-agent/voice` é um módulo à parte. **Importar o agente não o carrega**, e importá-lo, criar a
@@ -70,6 +118,8 @@ npm ci
 npm run build:package    # dist/esm, dist/iife, dist/voice e server/
 npm run verify:package   # identidade, tarball efetivo, dist atual, tipos
 npm run test:consumer    # empacota e testa o tarball num projeto novo
+npm run test:brain       # política de escrita e veredito (puros)
+npm run test:brain-e2e   # Chromium + LLM falso: loop, falso sucesso, escrita não pedida, teclado e overlay (precisa do build)
 ```
 
 `npm publish` roda o build e o guard em modo `--release` antes de enviar.