primocode 8.37.0 → 8.38.0

package/lib/area.js

@@ -0,0 +1,104 @@
+/**
+ * area.js — a área de transferência e o foco do terminal, sem dependência.
+ *
+ *   "No login quero que ele copie o código pra área de transferência
+ *    automaticamente. [...] Ele libera, você volta ao terminal
+ *    automaticamente."
+ *
+ * ── POR QUE FALAR COM O SISTEMA, E NÃO COM UM PACOTE ────────────────────
+ * O CLI tem zero dependências e isto não é motivo para abrir a primeira: todo
+ * sistema já tem um programa que escreve na área de transferência (pbcopy,
+ * clip, wl-copy, xclip, xsel). O que este módulo faz é achar qual existe e
+ * falar com ele — e FALHAR EM SILÊNCIO quando nenhum existe, porque copiar é
+ * conveniência: o código continua na tela e a página continua aceitando
+ * digitação. Conveniência que derruba o login não é conveniência.
+ *
+ * ── O FOCO SÓ VOLTA NO MAC, E É HONESTO DIZER ────────────────────────────
+ * Trazer o terminal para a frente depois de a página aprovar é o que fecha o
+ * laço "clicou → voltou". No macOS dá: o `TERM_PROGRAM` diz qual app é o
+ * terminal e o `osascript` o ativa. No Windows e no Linux não há um jeito
+ * geral que funcione sem depender do gerenciador de janelas — então lá o CLI
+ * apita e imprime o próximo passo, e a janela do navegador diz "volte ao
+ * terminal". Prometer o foco onde ele não vem seria pior que não prometer.
+ */
+
+'use strict';
+
+const os = require('os');
+const { execFile, execFileSync } = require('child_process');
+
+/* Cada candidato é [programa, argumentos]. A ordem dentro de cada sistema é
+   a do que existe com mais frequência: no Linux o Wayland vem primeiro
+   porque, quando ele é a sessão, o xclip existe e NÃO funciona. */
+function candidatos() {
+    const p = os.platform();
+    if (p === 'darwin') return [['pbcopy', []]];
+    if (p === 'win32') return [['clip', []]];
+    const lista = [];
+    if (process.env.WAYLAND_DISPLAY) lista.push(['wl-copy', []]);
+    lista.push(['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]);
+    if (!process.env.WAYLAND_DISPLAY) lista.push(['wl-copy', []]);
+    return lista;
+}
+
+/**
+ * Copia o texto para a área de transferência.
+ * @returns {Promise<{ok:boolean, como?:string}>}  nunca rejeita
+ */
+function copiar(texto) {
+    const fila = candidatos();
+    return new Promise((resolve) => {
+        const tentar = (i) => {
+            if (i >= fila.length) return resolve({ ok: false });
+            const [cmd, args] = fila[i];
+            let filho;
+            try {
+                filho = execFile(cmd, args, { timeout: 3000, windowsHide: true }, (erro) => {
+                    if (erro) return tentar(i + 1);
+                    resolve({ ok: true, como: cmd });
+                });
+            } catch { return tentar(i + 1); }
+            filho.on('error', () => tentar(i + 1));
+            try { filho.stdin.on('error', () => {}); filho.stdin.end(String(texto)); }
+            catch { tentar(i + 1); }
+        };
+        tentar(0);
+    });
+}
+
+/* O app do terminal, pelo que ele mesmo declara. Os cinco da lista são os que
+   têm nome de aplicativo diferente do valor da variável — os outros
+   (Warp, Alacritty, kitty, Ghostty) já se chamam pelo próprio nome. */
+const APPS_MAC = {
+    Apple_Terminal: 'Terminal',
+    'iTerm.app': 'iTerm',
+    vscode: 'Visual Studio Code',
+    Hyper: 'Hyper',
+    WezTerm: 'WezTerm',
+};
+
+/**
+ * Traz o terminal de volta para a frente. Só faz algo no macOS; nos outros
+ * sistemas devolve {ok:false, motivo} sem tentar nada.
+ */
+function voltarAoTerminal() {
+    if (os.platform() !== 'darwin') return { ok: false, motivo: 'só no macOS' };
+    const programa = process.env.TERM_PROGRAM || '';
+    const app = APPS_MAC[programa] || programa.replace(/\.app$/, '');
+    if (!app) return { ok: false, motivo: 'terminal não se identificou' };
+    try {
+        // O nome vai como ARGUMENTO do AppleScript, nunca dentro do texto do
+        // script: TERM_PROGRAM é ambiente, e ambiente é o que qualquer coisa
+        // escreve.
+        execFileSync('osascript', ['-e', 'on run argv', '-e', 'tell application (item 1 of argv) to activate',
+            '-e', 'end run', app], { timeout: 3000, stdio: 'ignore' });
+        return { ok: true, app };
+    } catch { return { ok: false, motivo: 'osascript recusou' }; }
+}
+
+/** O sino do terminal: chama a atenção de quem está olhando o navegador. */
+function apitar() {
+    try { if (process.stdout.isTTY) process.stdout.write('\x07'); } catch { /* sem tty */ }
+}
+
+module.exports = { copiar, voltarAoTerminal, apitar, candidatos, APPS_MAC };

package/lib/browser.js

@@ -770,8 +770,23 @@ async function subirRevisor() {
         // pessoa. Não há variável para ligar a janela aqui de propósito.
         '--headless=new', '--disable-gpu', '--disable-dev-shm-usage',
         '--hide-scrollbars', '--mute-audio',
+        // A exportação escondida TOCA o vídeo para gravá-lo, e o player dá
+        // play sem ninguém clicar. Sem isto o navegador recusa o play e o
+        // arquivo sai com o primeiro quadro congelado do começo ao fim.
+        // `--mute-audio` não atrapalha: ele cala o alto-falante, e o que a
+        // gravação lê é o grafo de áudio, antes dele.
+        '--autoplay-policy=no-user-gesture-required',
+        // Aba que o Chrome considera "de fundo" para de DECODIFICAR o vídeo
+        // depois de um segundo e segue só com o áudio: o readyState do <video>
+        // cai para 1 e o export desenha o chão da cena no lugar do clipe da
+        // pessoa — medido no diagnóstico, quadro a quadro. Estas quatro
+        // desligam as economias de aba de fundo; a aba ainda é trazida à
+        // frente (Page.bringToFront) ao abrir.
+        '--disable-features=Translate,BackgroundVideoPauseOptimization,MediaSuspend',
+        '--disable-background-media-suspend',
+        '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows',
+        '--disable-background-timer-throttling',
         '--no-first-run', '--no-default-browser-check',
-        '--disable-features=Translate',
         'about:blank',
     ];
     if (process.platform === 'linux' && process.getuid && process.getuid() === 0) {
@@ -914,6 +929,99 @@ async function inspecionarEscondido(url, op = {}) {
     }
 }
 
+/* Uma aba escondida, com o canal de controle aberto e os erros dela sendo
+   anotados. É a peça comum do `inspecionarEscondido`, do `rodarEscondido` e
+   do `abrirEscondido`: abrir, navegar, esperar o load, assentar. Quem chama
+   recebe a sessão e a promessa de fechar tudo no fim. */
+async function abaEscondida(url, op = {}) {
+    await subirRevisor();
+    const aba = await comTeto(
+        httpPutJson(`http://127.0.0.1:${PORTA_REVISOR}/json/new?${encodeURIComponent('about:blank')}`, 5000),
+        8000, 'a aba do revisor');
+    if (!aba || !aba.webSocketDebuggerUrl) throw new Error('o navegador escondido não abriu uma aba');
+    const s = new CDPSession();
+    const erros = [];
+    s.onEvent = (metodo, p) => {
+        const linha = _falaDoErro(metodo, p);
+        if (linha && erros.length < 25 && !erros.some((e) => e.texto === linha.texto)) erros.push(linha);
+    };
+    const fechar = async () => {
+        try { s.close(); } catch {}
+        try { await httpGetJson(`http://127.0.0.1:${PORTA_REVISOR}/json/close/${aba.id}`, 2000); } catch {}
+    };
+    try {
+        await comTeto(s.attach(aba.webSocketDebuggerUrl), 12000, 'o canal do revisor');
+        await s.send('Page.enable');
+        await s.send('Runtime.enable');
+        await s.send('Log.enable');
+        // A aba nova nasce ATRÁS do about:blank inicial, e aba de fundo é
+        // onde o Chrome economiza: para o vídeo, estrangula os timers. Trazer
+        // para a frente é o que faz a página se comportar como na tela da pessoa.
+        await s.send('Page.bringToFront').catch(() => {});
+        await s.send('Page.navigate', { url });
+        const prazo = Date.now() + (op.prazoLoad || 20000);
+        while (Date.now() < prazo) {
+            const r = await s.send('Runtime.evaluate', { expression: 'document.readyState', returnByValue: true }).catch(() => null);
+            if (r && r.result && r.result.value === 'complete') break;
+            await sleep(200);
+        }
+        await sleep(op.assentar == null ? 800 : op.assentar);
+    } catch (e) {
+        await fechar();
+        throw e;
+    }
+    return { sessao: s, erros, fechar };
+}
+
+/**
+ * Roda um script numa página escondida e espera o que ele deixar em
+ * `window.__primo`.
+ *
+ * É assim que o estúdio exporta o vídeo sem ninguém clicar: a página do
+ * player faz o trabalho que faria com o botão, e o resultado volta por aqui.
+ * O script recebe `userGesture` quando `op.gesto` é true — é o que destrava o
+ * AudioContext, que sem um gesto nasce suspenso e grava silêncio.
+ *
+ * @param {string} url
+ * @param {object} op  { script, prazo, passo, gesto, assentar }
+ * @returns {Promise<{valor:any, erros:Array, expirou?:boolean}>}
+ */
+async function rodarEscondido(url, op = {}) {
+    const aba = await abaEscondida(url, op);
+    try {
+        await aba.sessao.send('Runtime.evaluate', {
+            expression: `window.__primo = undefined; ${op.script || ''}`,
+            awaitPromise: false, returnByValue: false, userGesture: !!op.gesto,
+        });
+        const prazo = Date.now() + (op.prazo || 60000);
+        while (Date.now() < prazo) {
+            const r = await aba.sessao.send('Runtime.evaluate', {
+                expression: 'window.__primo === undefined ? null : JSON.stringify(window.__primo)',
+                returnByValue: true,
+            }).catch(() => null);
+            const v = r && r.result && r.result.value;
+            if (v) return { valor: JSON.parse(v), erros: aba.erros };
+            await sleep(op.passo || 400);
+        }
+        return { valor: null, erros: aba.erros, expirou: true };
+    } finally {
+        await aba.fechar();
+    }
+}
+
+/**
+ * Abre uma página escondida e a deixa aberta até quem chamou fechar.
+ *
+ * É o `abrir` da análise de áudio: a página faz a conta e MANDA o resultado
+ * ao estúdio sozinha, então aqui não há o que esperar — só manter a aba viva
+ * enquanto o CLI pergunta ao estúdio se já ficou pronto. Antes isso abria o
+ * navegador da PESSOA, que via uma aba piscar para uma conta que não era dela.
+ */
+async function abrirEscondido(url) {
+    const aba = await abaEscondida(url, { assentar: 0 });
+    return { fechar: aba.fechar, erros: aba.erros };
+}
+
 /* O revisor é ferramenta de uma tarefa, não um processo que fica. Deixá-lo de
    pé come memória até a pessoa desligar o computador, e ele não é o navegador
    dela — ninguém sentiria falta nem saberia que existe para fechar. */
@@ -937,5 +1045,5 @@ function fecharRevisor() {
 module.exports = {
     open, click, clickText, clickSelector, type, typeInSelector,
     key, screenshot, evaluate, waitFor, wait, scroll, close,
-    inspecionarEscondido, fecharRevisor,
+    inspecionarEscondido, rodarEscondido, abrirEscondido, fecharRevisor,
 };

package/lib/catalogo.js

@@ -99,6 +99,11 @@ const GRUPOS = [
                 + 'repetida (opcional, padrão true): false desliga o corte de fala repetida. '
                 + 'Devolve "trechos": vire cada um numa cena com {"tipo":"clipe","de":...,"ate":...}. '
                 + 'Devolve também "repetidos": o que foi tirado por ter sido dito duas vezes — CONTE isso ao usuário, com os tempos, porque é fala dele que sumiu do vídeo.' },
+            // Escreve no projeto (o .mp4 pronto), por isso `escreve: true`: é o
+            // que faz a pasta do projeto nascer quando ainda não existe.
+            { tool: 'studio_exportar', escreve: true, faz: 'gera o arquivo .mp4 de um vídeo do estúdio, sem ninguém clicar, e o deixa na pasta do projeto',
+              args: 'id: o vídeo (corte). destino (opcional): caminho do arquivo de saída — sem ele, <titulo>.mp4 na pasta do projeto. fps (opcional, padrão 30). '
+                + 'Leva o tempo do vídeo (um vídeo de 40s leva ~40s). Use quando o usuário pedir o ARQUIVO; para só mostrar, o link "ver" basta.' },
         ],
     },
     {
@@ -145,8 +150,8 @@ const GRUPOS = [
             { tool: 'remember_general', escreve: false, faz: 'grava algo sobre o usuário que vale para todo projeto (memory-geral.md)',
               args: 'fato: o que lembrar, em uma frase.' },
             // Estas duas o loop do agente atende (lib/act.js), não o tools.execute.
-            { tool: 'spawn_agent', escreve: false, faz: 'chama um subagente para uma parte da tarefa', noLoop: true,
-              args: 'description: 3 a 5 palavras, aparece na tela do usuário. prompt: instrução completa e autossuficiente — o subagente não vê esta conversa.' },
+            { tool: 'spawn_agent', escreve: false, faz: 'chama um subagente especialista para uma parte da tarefa', noLoop: true,
+              args: 'description: 3 a 5 palavras, aparece na tela do usuário. prompt: instrução completa e autossuficiente — o subagente não vê esta conversa. especialista (opcional): frontend, backend, testes, design, dados, revisor ou ambiente — cada um chega com o briefing da profissão (lib/especialistas.js); sem ele, a tarefa sugere.' },
             { tool: 'construir_app', escreve: true, noLoop: true,
               faz: 'constrói um app ou site inteiro com quatro papéis: engenheiro de prompt → protótipo → MVP → revisor que testa escondido, em laço até passar',
               args: 'pedido: o que o usuário quer, com as palavras dele. pasta (opcional): onde construir — sem ela, uma pasta nova com o nome do pedido. rodadas (opcional, 1 a 4, padrão 2): quantas voltas de correção. '

package/lib/conta.js

@@ -29,6 +29,7 @@ const os = require('os');
 const path = require('path');
 const https = require('https');
 const http = require('http');
+const area = require('./area.js');
 
 // O servidor do Conecta Primo — que NÃO é o servidor do PrimoCode. São dois
 // serviços diferentes: um responde o chat do app e a conta, o outro é o motor
@@ -105,12 +106,87 @@ function atual() {
 
 // ── entrar ───────────────────────────────────────────────────────────────
 
+/* ── O CÓDIGO CHEGA À PÁGINA SEM NINGUÉM DIGITAR ─────────────────────────
+ *
+ *   "No login quero que ele copie o código pra área de transferência
+ *    automaticamente. A tela de login deve ter só o negócio pra verificar o
+ *    código e ele já cola automaticamente o código."
+ *
+ * A regra da casa continua a mesma: O CÓDIGO NÃO VAI NO LINK. Com ele na URL,
+ * um link mandado por outra pessoa conectaria o computador DELA à conta de
+ * quem clicou. O que muda é COMO ele chega à página:
+ *
+ *   1. Enquanto espera a aprovação, o CLI serve `GET /pareamento` em
+ *      127.0.0.1, e a página pergunta ali. Só uma página aberta NESTA máquina
+ *      alcança 127.0.0.1 desta máquina — o que é mais seguro que digitar, não
+ *      menos: o link do atacante abriria a página na máquina da vítima, cujo
+ *      CLI (se estiver rodando) tem o código DA VÍTIMA, nunca o dele.
+ *   2. O código também vai para a área de transferência: no Safari, que
+ *      bloqueia http://127.0.0.1 a partir de página https, a página oferece
+ *      "Colar" — um toque, sem ler oito letras.
+ *   3. Se nada disso servir, a pessoa digita, como antes.
+ *
+ * A resposta do servidor local só sai com `Access-Control-Allow-Origin` para a
+ * ORIGEM DO SITE (a que veio no `pedido.url`). Sem isso qualquer página aberta
+ * no navegador poderia ler 127.0.0.1 e roubar o código para aprová-lo na
+ * própria conta. A porta vai na URL (`?porta=`), e a porta não é segredo: ela
+ * só diz ONDE perguntar, e quem não está nesta máquina não alcança.
+ */
+const PORTA_PAREAMENTO = Number(process.env.PRIMOCODE_PORTA_PAREAMENTO) || 7799;
+
+function servirPareamento(codigo, origemDoSite) {
+    const permitidas = new Set([origemDoSite, 'http://127.0.0.1', 'http://localhost']
+        .filter(Boolean));
+    const permitida = (origem) => {
+        if (!origem) return false;
+        if (permitidas.has(origem)) return true;
+        // Os testes e a prévia local rodam em portas variadas de 127.0.0.1.
+        return /^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/.test(origem);
+    };
+
+    const servidor = http.createServer((req, res) => {
+        const origem = req.headers.origin;
+        const cab = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
+        if (permitida(origem)) {
+            cab['Access-Control-Allow-Origin'] = origem;
+            cab.Vary = 'Origin';
+            cab['Access-Control-Allow-Methods'] = 'GET, OPTIONS';
+            cab['Access-Control-Allow-Private-Network'] = 'true';
+        }
+        if (req.method === 'OPTIONS') { res.writeHead(204, cab); return res.end(); }
+        const rota = (req.url || '/').split('?')[0];
+        if (rota !== '/pareamento' || req.method !== 'GET') {
+            res.writeHead(404, cab); return res.end('{"ok":false}');
+        }
+        // Sem origem permitida, a resposta sai SEM o cabeçalho CORS: o navegador
+        // recebe e descarta antes de a página ler. O corpo continua igual de
+        // propósito — o que protege é o cabeçalho, não esconder o corpo, e
+        // dois corpos diferentes seriam dois caminhos para manter.
+        res.writeHead(200, cab);
+        res.end(JSON.stringify({ ok: true, codigo, origem: `PrimoCode ${versao()}` }));
+    });
+
+    return new Promise((ok) => {
+        let porta = PORTA_PAREAMENTO;
+        const tentar = () => {
+            servidor.once('error', (e) => {
+                if (e.code === 'EADDRINUSE' && porta < PORTA_PAREAMENTO + 10) { porta++; tentar(); }
+                else ok({ porta: null, fechar: () => {} });   // sem servidor local: digita ou cola
+            });
+            servidor.listen(porta, '127.0.0.1', () => {
+                ok({ porta, fechar: () => { try { servidor.close(); } catch { /* já fechou */ } } });
+            });
+        };
+        tentar();
+    });
+}
+
 /**
  * O login inteiro: pede o código, abre o navegador, espera a aprovação.
  *
  * @param {object} op
  * @param {(url:string)=>any} op.abrir     abre o navegador (vem do tools.js)
- * @param {(msg:string)=>void} [op.contar] para a tela ir dizendo o que faz
+ * @param {(info:object)=>void} [op.contar] recebe {url, codigo, copiado, porta} uma vez, antes de esperar
  * @param {number} [op.minutos]            teto da espera
  */
 async function entrar({ abrir, contar = () => {}, minutos = 5 } = {}) {
@@ -124,35 +200,52 @@ async function entrar({ abrir, contar = () => {}, minutos = 5 } = {}) {
         return { ok: false, error: (pedido && pedido.error) || 'o servidor recusou abrir o login' };
     }
 
-    contar(pedido.url);
-    contar(pedido.codigo);
-    if (abrir) { try { await abrir(pedido.url); } catch { /* segue: o link está na tela */ } }
-
-    /* A espera. Dois segundos entre perguntas: mais rápido é marteladas no
-       servidor por uma pessoa que ainda está digitando a senha; mais devagar e
-       o terminal parece travado depois de a página já ter confirmado. */
-    const prazo = Date.now() + minutos * 60000;
-    while (Date.now() < prazo) {
-        await new Promise((ok) => setTimeout(ok, 2000));
-        let r;
-        try {
-            r = await pedir('/api/dispositivo/consultar',
-                { codigo: pedido.codigo, segredo: pedido.segredo }, 10000);
-        } catch { continue; }          // rede tropeçou: pergunta de novo
-        if (!r || !r.success) continue;
-        if (r.estado === 'expirado') {
-            return { ok: false, error: 'o código venceu antes de você aprovar. Tente de novo.' };
-        }
-        if (r.estado !== 'aprovado') continue;
+    let origemDoSite = null;
+    try { origemDoSite = new URL(pedido.url).origin; } catch { /* url estranha: sem CORS para ela */ }
+    const local = await servirPareamento(pedido.codigo, origemDoSite);
+    const copiado = await area.copiar(pedido.codigo);
 
-        gravar({
-            token: r.token, uid: r.uid, plano: r.plano || 'free',
-            desde: new Date().toISOString(), servidor: CONECTA,
-        });
-        return { ok: true, uid: r.uid, plano: r.plano,
-            pro: PLANOS_PRO.includes(r.plano) };
+    let url = pedido.url;
+    if (local.porta) url += (url.includes('?') ? '&' : '?') + 'porta=' + local.porta;
+
+    contar({ url, codigo: pedido.codigo, copiado: copiado.ok, porta: local.porta });
+    if (abrir) { try { await abrir(url); } catch { /* segue: o link está na tela */ } }
+
+    try {
+        /* A espera. Dois segundos entre perguntas: mais rápido é marteladas no
+           servidor por uma pessoa que ainda está digitando a senha; mais devagar e
+           o terminal parece travado depois de a página já ter confirmado. */
+        const prazo = Date.now() + minutos * 60000;
+        while (Date.now() < prazo) {
+            await new Promise((ok) => setTimeout(ok, 2000));
+            let r;
+            try {
+                r = await pedir('/api/dispositivo/consultar',
+                    { codigo: pedido.codigo, segredo: pedido.segredo }, 10000);
+            } catch { continue; }          // rede tropeçou: pergunta de novo
+            if (!r || !r.success) continue;
+            if (r.estado === 'expirado') {
+                return { ok: false, error: 'o código venceu antes de você aprovar. Tente de novo.' };
+            }
+            if (r.estado !== 'aprovado') continue;
+
+            gravar({
+                token: r.token, uid: r.uid, plano: r.plano || 'free',
+                desde: new Date().toISOString(), servidor: CONECTA,
+            });
+            /* Aprovou lá: a atenção da pessoa está no navegador. O sino e o foco
+               trazem-na de volta — o foco só no macOS, e o módulo diz por quê. */
+            area.apitar();
+            const volta = area.voltarAoTerminal();
+            return { ok: true, uid: r.uid, plano: r.plano,
+                pro: PLANOS_PRO.includes(r.plano), voltou: !!volta.ok };
+        }
+        return { ok: false, error: `passaram ${minutos} minutos sem aprovação. Rode /connect de novo.` };
+    } finally {
+        // O servidor local só existe durante a espera. Deixá-lo de pé seria
+        // uma porta respondendo um código morto para sempre.
+        local.fechar();
     }
-    return { ok: false, error: `passaram ${minutos} minutos sem aprovação. Rode /entrar de novo.` };
 }
 
 /**
@@ -194,4 +287,4 @@ function versao() {
     try { return require('../package.json').version; } catch { return '?'; }
 }
 
-module.exports = { entrar, sair, atual, sessao, dispositivos, ARQUIVO, CONECTA, PLANOS_PRO };
+module.exports = { entrar, sair, atual, sessao, dispositivos, servirPareamento, ARQUIVO, CONECTA, PLANOS_PRO, PORTA_PAREAMENTO };

package/lib/especialistas.js

@@ -0,0 +1,123 @@
+/**
+ * especialistas.js — quem o agente chama quando delega.
+ *
+ *   "Para programar a IA deve ter skills, agentes e sub-agents. Cada um
+ *    especialista em algo. Deve ser coisas surreal, entregar códigos a nível
+ *    claude."
+ *
+ * ── POR QUE UM BRIEFING, E NÃO UM PROMPT INTEIRO ────────────────────────
+ * O subagente já tem o prompt de sistema do servidor e as ferramentas. O que
+ * ele NÃO tem é ofício: "crie a folha de estilo" chega a um generalista, e
+ * generalista escreve o CSS que qualquer um escreveria. O briefing é o que um
+ * sênior daquela área diria a um colega antes de ele começar — o que olhar
+ * primeiro, o que nunca fazer, como PROVAR que acabou. Ele vai na frente da
+ * tarefa, na MESMA mensagem: o servidor não precisa conhecer os especialistas,
+ * e o /claude e o /codex os recebem igual.
+ *
+ * ── CURTO DE PROPÓSITO ──────────────────────────────────────────────────
+ * Cada briefing cabe em ~800 caracteres. O subagente vive no mesmo teto de
+ * tokens por minuto do agente principal, e cada linha aqui é uma linha a
+ * menos de arquivo lido. O que está aqui é o que muda o resultado; o resto o
+ * prompt de sistema já diz. Todo briefing termina em como provar — "pronto"
+ * sem prova é a mentira mais comum de um agente, e o especialista é
+ * justamente quem sabe o que conta como prova na área dele.
+ *
+ * ── QUEM ESCOLHE ────────────────────────────────────────────────────────
+ * O modelo, pelo campo `especialista` do spawn_agent. Quando ele não diz,
+ * `inferir` lê a tarefa e adivinha pelos sinais — errar para o generalista é
+ * barato (é o que acontecia antes), então só se decide com sinal de verdade.
+ */
+
+'use strict';
+
+const ESPECIALISTAS = {
+    frontend: {
+        faz: 'tela, HTML, CSS e o JavaScript do navegador',
+        sinais: /\b(css|html|layout|tela|interface|componente|responsiv\w*|bot[ãa]o|p[áa]gina|front-?end|estilo|folha de estilo|ui|formul[áa]rio|menu|navbar|modal)\b/gi,
+        briefing: `Você é o especialista em FRONTEND. Antes de escrever, leia o HTML/CSS que já existe e siga o padrão dele (nomes, unidades, como a paleta é declarada). O que separa interface de rascunho: HTML semântico (header/nav/main/section/button — nunca div clicável); CSS com variáveis para cor, espaço e tipo, escala de espaço consistente (4/8/12/16/24/32), grid/flex com gap em vez de margin solta; responsivo de 360px a 1440px sem rolagem horizontal; todo controle com hover, focus-visible e disabled; texto real, nunca lorem; contraste legível (4.5:1). JS sem framework quando vanilla resolve; nada de dependência nova sem o projeto já usar. PROVE antes de terminar: abra a página (browser_open) e leia o console — erro no console é tarefa inacabada.`,
+    },
+    backend: {
+        faz: 'API, servidor, dados no servidor e autenticação',
+        sinais: /\b(api|rotas?|endpoints?|servidor|banco de dados|sql|express|flask|django|fastapi|autentica\w*|back-?end|middleware|token|sess[ãa]o|webhook)\b/gi,
+        briefing: `Você é o especialista em BACKEND. Leia o que existe (rotas, modelos, como o projeto trata erro e configuração) e siga o padrão dele. Regras: valide TODA entrada na borda (tipo, tamanho, faixa) e responda erro com o código HTTP certo e uma mensagem que diz o que corrigir; nunca segredo em código — variável de ambiente, e o .env.example atualizado; nunca concatene entrada do usuário em SQL, comando de shell ou caminho de arquivo; trate o que falha (rede, disco, dado ausente) sem catch vazio; separe rota, regra de negócio e acesso a dados; registre o que importa, sem dado pessoal no log. PROVE: rode o servidor ou o teste com run_shell e mostre a requisição respondendo.`,
+    },
+    testes: {
+        faz: 'escrever e rodar testes, reproduzir bug antes de consertar',
+        sinais: /\b(testes?|testar|test|spec|jest|pytest|mocha|vitest|cobertura|reproduz\w*|regress[ãa]o|assert\w*)\b/gi,
+        briefing: `Você é o especialista em TESTES. Primeiro descubra como o projeto testa (package.json, pytest, pasta test/) e use o mesmo jeito — não traga framework novo. Para um bug: escreva PRIMEIRO o teste que reproduz e falha, depois a correção, depois veja o teste passar. Para código novo: cubra o caminho feliz, os limites (vazio, zero, máximo, unicode) e o que dá errado (entrada inválida, dependência fora). Um teste, uma afirmação clara, com nome que diz o comportamento ("recusa e-mail sem @"), sem depender de rede nem de ordem. Rode com run_shell e devolva o resultado REAL — quantos passaram, qual falhou e a linha do erro. Nunca diga "os testes passam" sem a saída na mão.`,
+    },
+    design: {
+        faz: 'identidade visual: paleta, tipografia, espaço, hierarquia',
+        sinais: /\b(design|paleta|tipografia|identidade visual|cores?|fontes?|visual|bonit[oa]|est[ée]tica|marca|logo|[íi]cones?|tema)\b/gi,
+        briefing: `Você é o especialista em DESIGN VISUAL. Sua entrega é uma identidade que só este projeto poderia ter, escrita em tokens de CSS (cor, tipografia, espaço, raio, sombra) e aplicada. Decida a partir do assunto: quem usa, em que tela, com que sentimento. Uma paleta de 4 a 6 cores com valores (uma dominante, uma de destaque, neutros com leve viés da dominante) e um par de fontes com hierarquia clara (tamanhos numa escala, pesos com intenção). Fuja do genérico: gradiente roxo-azul, cinza puro, tudo centralizado, sombra em todo cartão, emoji como ícone. Espaço em branco é design; alinhe a uma grade. Ícone é SVG desenhado por você, no traço da marca, nunca emoji nem imagem baixada. PROVE: abra a página e descreva o que se vê em 390px e em 1280px.`,
+    },
+    dados: {
+        faz: 'CSV, planilha, análise, modelagem e transformação de dados',
+        sinais: /\b(dados|csv|json|planilha|tabela|colunas?|estat[íi]stica|an[áa]lise|gr[áa]fico|dataset|pandas|migra[çc][ãa]o|etl|relat[óo]rio)\b/gi,
+        briefing: `Você é o especialista em DADOS. Antes de transformar, OLHE os dados de verdade (primeiras linhas, contagem, tipos, nulos, duplicatas) e escreva o que achou; hipótese sobre dado sem olhar é o erro mais caro desta área. Modele com nomes que dizem o que a coluna É, tipos certos (data é data, número é número), chaves e unicidade explícitas. Scripts idempotentes: rodar duas vezes dá o mesmo resultado. Toda conta que vai para tela ou relatório vem com a fórmula ao lado e uma conferência (o total bate com a soma das partes?). Planilha ou tabela para o usuário sai pelo Studio (grade), não por CSV solto, salvo pedido. Nunca invente número: o que não está nos dados fica em branco, e dito. PROVE: mostre a contagem antes e depois.`,
+    },
+    revisor: {
+        faz: 'lê o código e aponta os defeitos, sem consertar',
+        sinais: /\b(revis\w*|audit\w*|code review|aponte|defeitos?|conferir|avalie|analise o c[óo]digo|o que est[áa] errado|cr[íi]tica)\b/gi,
+        briefing: `Você é o REVISOR, e não escreveu esse código: não conserte nada — aponte. Leia inteiros os arquivos que importam antes de opinar. Procure, nesta ordem: o que QUEBRA (erro de execução, caminho que não existe, promessa sem await, estado que nunca é limpo); o que é INSEGURO (entrada sem validação, segredo em código, injeção em SQL/shell/HTML, dependência sem necessidade); o que MENTE (botão que não faz nada, texto de exemplo, "pronto" sem prova); o que vai quebrar DEPOIS (limite, vazio, concorrência). Se há página HTML, ABRA (browser_open) e leia o console: o que a máquina mediu vale mais que a sua opinião. Responda com uma lista — ARQUIVO:linha, o que está errado, o que deveria acontecer — do mais grave ao menos, no máximo oito itens, sem gosto pessoal.`,
+    },
+    ambiente: {
+        faz: 'instalar dependências, configurar e fazer rodar',
+        sinais: /\b(instal\w*|depend[êe]ncias?|npm|pnpm|yarn|pip|uv|brew|apt(-get)?|winget|ffmpeg|configur\w*|ambiente|setup|rodar o projeto|node_modules|docker|venv)\b/gi,
+        briefing: `Você é o especialista em AMBIENTE — dependências, instalação e execução. Descubra o que a máquina tem (node --version, python3 --version, qual gerenciador: npm/pnpm/yarn, pip/uv, brew/apt/winget) antes de mandar instalar; use o gerenciador que o projeto já usa (o lockfile diz). Instale só o que a tarefa pede, com a versão fixada no manifesto (package.json, requirements.txt), nunca global sem motivo. Comando que demora ou fica de pé vai em run_in_new_terminal; o resto em run_shell, lendo a saída inteira — "warning" não é erro, "ERR!" é. Falta algo no sistema (ffmpeg, git, python)? Instale pelo gerenciador do sistema e confira com --version. PROVE: o comando de rodar funcionando, e um LEIA.md com instalar e rodar que qualquer um siga.`,
+    },
+};
+
+const NOMES = Object.keys(ESPECIALISTAS);
+
+/** O especialista de nome dado, ou null para o generalista. Aceita maiúsculas e acento. */
+function porNome(nome) {
+    const n = String(nome || '').trim().toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '');
+    if (!n || n === 'geral') return null;
+    // Sinônimos que o modelo escreve: "front", "back", "qa", "reviewer", "devops".
+    const mapa = { front: 'frontend', 'front-end': 'frontend', ui: 'frontend', back: 'backend', 'back-end': 'backend',
+        api: 'backend', qa: 'testes', teste: 'testes', test: 'testes', tests: 'testes', designer: 'design', visual: 'design',
+        data: 'dados', reviewer: 'revisor', review: 'revisor', revisao: 'revisor', devops: 'ambiente', infra: 'ambiente',
+        instalacao: 'ambiente', setup: 'ambiente' };
+    const chave = mapa[n] || n;
+    return ESPECIALISTAS[chave] ? { nome: chave, ...ESPECIALISTAS[chave] } : null;
+}
+
+/**
+ * Adivinha o especialista pela tarefa. Conta os sinais de cada um; empate ou
+ * sinal fraco (menos de dois) devolve null — o generalista é o que já existia,
+ * e chamar o especialista errado é pior que não chamar nenhum.
+ */
+function inferir(prompt) {
+    const t = String(prompt || '');
+    if (!t) return null;
+    let melhor = null;
+    let pontos = 0;
+    let empate = false;
+    for (const nome of NOMES) {
+        const n = (t.match(ESPECIALISTAS[nome].sinais) || []).length;
+        if (n > pontos) { melhor = nome; pontos = n; empate = false; }
+        else if (n === pontos && n > 0) empate = true;
+    }
+    if (!melhor || pontos < 2 || empate) return null;
+    return { nome: melhor, ...ESPECIALISTAS[melhor] };
+}
+
+/** O que o modelo pediu ganha; sem pedido, o que a tarefa sugere. */
+function escolher(nome, prompt) {
+    return porNome(nome) || inferir(prompt);
+}
+
+/** A mensagem que o subagente recebe: o briefing na frente, a tarefa depois. */
+function montarTarefa(especialista, prompt) {
+    const tarefa = String(prompt || '');
+    if (!especialista) return tarefa;
+    return `${especialista.briefing}\n\nSUA TAREFA:\n${tarefa}`;
+}
+
+/** O rótulo que aparece na tela: "Agente·frontend". */
+function rotulo(especialista) {
+    return especialista ? `Agente·${especialista.nome}` : 'Agente';
+}
+
+module.exports = { ESPECIALISTAS, NOMES, porNome, inferir, escolher, montarTarefa, rotulo };