primocode 8.42.2 → 9.1.0

package/lib/tools.js

@@ -7,6 +7,8 @@
 
 'use strict';
 
+const catalogo = require('./catalogo.js');
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -14,8 +16,7 @@ const { exec, execFile } = require('child_process');
 const browser = require('./browser');
 const desktop = require('./desktop');
 const referencia = require('./referencia');
-const studio = require('./studio');
-const acervo = require('./acervo');
+const estudio = require('./estudio');
 const cfg = require('./config');
 
 const IGNORAR = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache', 'vendor']);
@@ -171,11 +172,6 @@ async function runShell(command, timeout = 60000, cwd) {
 // execFile com array de argumentos nunca passa por shell nenhum: "target" vira
 // UM argumento, não texto que um shell reinterpreta — sem isso, um valor tipo
 // `https://x/"; touch /tmp/pwned; echo "` injetava comando (achado de segurança).
-// Quando o auto-abrir do Studio abriu pela última vez — o freio das mil abas.
-let ultimaAberturaStudio = 0;
-// Uma rodada de melhoria por tarefa (ver o aviso em studio_criar).
-let melhorouStudio = false;
-
 function openInBrowser(target) {
     const p = os.platform();
     const [cmd, args, opener] = p === 'darwin' ? ['open', [target], 'open']
@@ -199,14 +195,43 @@ async function runInNewTerminal(command, cwd) {
     // mesmo tempo (osascript, cmd.exe, sh) — "command" continua livre de
     // propósito, é o próprio contrato desta tool (abrir terminal com um
     // comando de shell de verdade).
-    if (/["'`;&|$\\]/.test(pastaAlvo)) {
+    /* A CONTRABARRA NÃO PODE ENTRAR NESTA LISTA NO WINDOWS.
+       Ela estava, e com isso a tool NUNCA funcionou lá: a pasta de trabalho é
+       sempre C:\Users\<nome>\primocode\<projeto> (path.join no win32 usa "\"),
+       então TODO caminho casava e a resposta era "Pasta com caractere não
+       permitido" — culpando a pasta criada pelo próprio produto, antes de
+       tentar abrir terminal nenhum. "sobe o servidor" quebrava 100% das vezes.
+       A contrabarra só é perigosa onde ela é ESCAPE (sh, osascript); no cmd.exe
+       ela é separador de caminho e nada mais. */
+    const proibidos = p === 'win32' ? /["'`;&|%^<>\r\n]/ : /["'`;&|$\\\r\n]/;
+    if (proibidos.test(pastaAlvo)) {
         return { ok: false, error: `Pasta com caractere não permitido: ${pastaAlvo}` };
     }
     let cmd;
-    if (p === 'darwin') cmd = `osascript -e 'tell application "Terminal" to do script "cd ${pastaAlvo} && ${command}"'`;
-    else if (p === 'win32') cmd = `start cmd /k "cd /d ${pastaAlvo} && ${command}"`;
-    else cmd = `x-terminal-emulator -e "bash -c 'cd ${pastaAlvo} && ${command}; exec bash'"`;
-    const r = await runShell(cmd);
+    let pastaDoProcesso;
+    if (p === 'darwin') {
+        /* O Terminal.app é outro processo, já rodando: ele NÃO herda a pasta
+           daqui, então o `cd` tem de ir no script mesmo. O espaço é escapado
+           com contrabarra — "\\ " neste template vira "\ " dentro da string do
+           AppleScript, que é o escape que o shell entende. Sem isso, uma pasta
+           como ~/Documents/Meus Projetos virava dois argumentos e o cd falhava
+           calado: o terminal abria na pasta errada e o comando rodava no lugar
+           errado, que é pior que não abrir. */
+        cmd = `osascript -e 'tell application "Terminal" to do script "cd ${pastaAlvo.replace(/ /g, '\\\\ ')} && ${command}"'`;
+    } else if (p === 'win32') {
+        // Aspas em volta do caminho: "C:\Users\Joel Silva\..." é comum, e sem
+        // elas o cmd corta no espaço. A aspa dupla já está barrada acima, então
+        // não há como sair delas.
+        cmd = `start cmd /k "cd /d "${pastaAlvo}" && ${command}"`;
+    } else {
+        /* No Linux o terminal é filho DESTE processo e herda a pasta — então
+           o caminho não precisa entrar na string de shell nenhuma. É a solução
+           mais segura das três: o que não é interpolado não pode ser mal
+           escapado. */
+        cmd = `x-terminal-emulator -e "bash -c '${command}; exec bash'"`;
+        pastaDoProcesso = pastaAlvo;
+    }
+    const r = await runShell(cmd, 60000, pastaDoProcesso);
     return r.ok ? { ok: true, opener: cmd.split(' ')[0] } : { ok: false, error: r.stderr || 'falhou' };
 }
 
@@ -270,6 +295,13 @@ function editFile({ path: rawPath, old_string, new_string, replace_all }, projec
         substituicoes: replace_all ? ocorrencias : 1,
         linhasAntes: original.split('\n').length,
         linhasDepois: atualizado.split('\n').length,
+        // As duas versões, para a TELA desenhar o diff. O `_` na frente marca
+        // o que é só nosso: o act.js apaga estas chaves antes de a conversa
+        // seguir, porque mandar o arquivo de volta ao modelo custaria
+        // centenas de tokens para ensinar a ele o texto que ele acabou de
+        // escrever.
+        _antes: original,
+        _depois: atualizado,
     };
 }
 
@@ -304,6 +336,7 @@ function multiEdit({ path: rawPath, edits }, projectDir) {
     if (!Array.isArray(edits) || !edits.length) return { ok: false, error: 'edits (lista) é obrigatório' };
 
     let conteudo = fs.readFileSync(filePath, 'utf-8');
+    const original = conteudo;
     const linhasAntes = conteudo.split('\n').length;
     let substituicoes = 0;
 
@@ -329,6 +362,8 @@ function multiEdit({ path: rawPath, edits }, projectDir) {
         substituicoes,
         linhasAntes,
         linhasDepois: conteudo.split('\n').length,
+        _antes: original,
+        _depois: conteudo,
     };
 }
 
@@ -401,9 +436,20 @@ async function despachar(name, args, ctx) {
                 const filePath = resolveInProject(args.path, projectDir);
                 const content = args.content || '';
                 const created = !fs.existsSync(filePath);
+                // Reescrever um arquivo que já existe é a operação mais
+                // perigosa do agente: o conteúdo antigo some inteiro. Ler o
+                // que estava lá ANTES de escrever é o que permite mostrar na
+                // tela o que foi perdido.
+                let antes = '';
+                if (!created) { try { antes = fs.readFileSync(filePath, 'utf-8'); } catch { antes = ''; } }
                 fs.mkdirSync(path.dirname(filePath), { recursive: true });
                 fs.writeFileSync(filePath, content, 'utf-8');
-                return { ok: true, created, path: path.relative(projectDir, filePath).replace(/\\/g, '/'), bytes: content.length };
+                return {
+                    ok: true, created,
+                    path: path.relative(projectDir, filePath).replace(/\\/g, '/'),
+                    bytes: content.length,
+                    ...(created ? {} : { _antes: antes, _depois: content }),
+                };
             }
             case 'edit_file':
                 return editFile(args, projectDir);
@@ -441,16 +487,6 @@ async function despachar(name, args, ctx) {
                     paginas: Math.max(1, Math.min(5, Number(args.paginas) || 3)),
                 });
 
-            // Música e efeito sonoro da internet, com licença e crédito. O
-            // arquivo vem para a pasta do projeto e sobe para o estúdio;
-            // volta a URL "/midia/…" pronta para trilha.src ou som.arquivo.
-            case 'buscar_audio':
-                return require('./audio-livre.js').buscarAudio(args, { projectDir, studio });
-
-            // A logo e a identidade visual da empresa, lidas do site dela.
-            case 'marca_da_empresa':
-                return require('./marca.js').marcaDaEmpresa(args, { projectDir, studio });
-
             // memory-geral.md fica FORA da pasta do projeto — write_file/edit_file
             // não alcançam por design (resolveInProject bloqueia ../ de propósito).
             // Esta é a única porta para lá, sem reabrir a sandbox.
@@ -514,171 +550,36 @@ async function despachar(name, args, ctx) {
                 return desktop.scroll(args.dy != null ? args.dy : 300);
             case 'desktop_size':
                 return desktop.getScreenSize();
-            // ── PrimoCode Studio — a suíte de criação (sobe sozinha) ───────
-            case 'studio_manual':
-                return studio.manual();
-            case 'studio_spec':
-                return studio.spec(args.ferramenta || args.slug || '');
-            case 'studio_criar': {
-                const r = await studio.criar({ ferramenta: args.ferramenta, titulo: args.titulo, doc: args.doc });
-                // Criou? ABRE NO NAVEGADOR, sozinho. O dono: "quando ele faz um
-                // vídeo, uma apresentação, abre automático — a pessoa não vai
-                // saber abrir". E cada "abre pra mim" digitado depois custava
-                // uma tarefa inteira de tokens para o modelo redescobrir o
-                // link. Abrir é determinístico: não se gasta modelo com isso.
-                // Fica anotado na memória geral: é assim que "lembra do
-                // vídeo tal" funciona na conversa seguinte. O id é o que
-                // permite reabrir ou ajustar sem recriar.
-                if (r && r.ok !== false && r.id) {
-                    cfg.lembrarCriacao({ ferramenta: r.ferramenta || args.ferramenta,
-                        titulo: r.titulo || args.titulo, id: r.id });
-                }
-                if (r && r.ok !== false && r.ver) {
-                    // UMA aba por tarefa. O modelo às vezes cria três versões
-                    // seguidas, e abrir todas enchia o navegador do usuário de
-                    // abas — "abre 1000 versões". A primeira abre; as outras
-                    // são avisadas a ATUALIZAR a que já existe.
-                    const agora = Date.now();
-                    if (agora - ultimaAberturaStudio > 45000) {
-                        ultimaAberturaStudio = agora;
-                        try { openInBrowser(r.ver); } catch {}
-                        r.abertoNoNavegador = true;
-                        // O estúdio revisa a peça e devolve o que ficou
-                        // monótono (mesmo fundo em tudo, transição repetida,
-                        // sem trilha). Sem este ramo o aviso mandaria "chame
-                        // finish, não ajuste" — e a revisão morreria ali, que
-                        // é justamente o "fica tudo genérico".
-                        //
-                        // UMA rodada de conserto, e acabou: mais que isso
-                        // vira o agente polindo sozinho enquanto o usuário
-                        // espera.
-                        if (Array.isArray(r.podeMelhorar) && r.podeMelhorar.length && !melhorouStudio) {
-                            melhorouStudio = true;
-                            r.aviso = 'JÁ ABERTO no navegador. Antes de finalizar, faça UMA correção: '
-                                + `use studio_atualizar no id "${r.id}" mandando SÓ as chaves que mudam, `
-                                + 'para resolver os pontos de "podeMelhorar". Depois chame finish. '
-                                + 'Não crie outro arquivo e não repita esta correção.';
-                        } else {
-                            r.aviso = 'JÁ ABERTO no navegador do usuário. Chame finish AGORA dizendo o que foi criado — não abra de novo, não leia de volta, não ajuste sem pedido.';
-                        }
-                    } else {
-                        r.aviso = `Você JÁ criou uma versão nesta tarefa, e ela está aberta no navegador. NÃO crie outra: `
-                            + `para mudar algo, use studio_atualizar com o id "${r.id}". Chame finish AGORA.`;
-                    }
-                }
-                return r;
-            }
-            case 'studio_ler':
-                return studio.ler(args.id);
-            case 'studio_atualizar':
-                return studio.atualizar({ id: args.id, titulo: args.titulo, doc: args.doc });
-            case 'studio_versoes':
-                return studio.versoesDe({ id: args.id, restaurar: args.restaurar });
-            case 'studio_listar':
-                return studio.listar();
-            case 'studio_midia':
-                // Sem arquivo, lista o que já foi enviado; com arquivo, envia.
-                return args.arquivo
-                    ? studio.midiaEnviar({ arquivo: resolveInProject(args.arquivo, projectDir), nome: args.nome })
-                    : studio.midiaListar();
-            /* ── MÍDIA DE VERDADE, VINDA DA INTERNET ──────────────────
-             *
-             * Buscar, baixar, recortar o fundo e já deixar na galeria do
-             * estúdio. O caminho inteiro é uma tool só do ponto de vista do
-             * agente (procurar → baixar), e o `paraEstudio` é o que evita a
-             * volta clássica: baixar num canto do disco e depois descobrir
-             * que a cena precisa de uma URL "/midia/...".
-             *
-             * A licença desce junto e fica gravada ao lado do arquivo. Um
-             * vídeo de cliente com foto CC BY sem crédito é problema do
-             * cliente, e descobrir isso depois de publicar é tarde. */
-            case 'midia_procurar':
-                return acervo.procurar(args.consulta || args.q || '', {
-                    tipo: args.tipo, quantos: args.quantos, orientacao: args.orientacao,
-                    licenca: args.licenca,
-                });
-            case 'midia_baixar': {
-                const r = await acervo.baixar(args.url, { titulo: args.titulo, meta: {
-                    autor: args.autor || null, licenca: args.licenca || null,
-                    fonte: args.fonte || null, pagina: args.pagina || null,
-                } });
-                if (!r.ok) return r;
-                let arquivo = r.arquivo;
-                if (args.semFundo) {
-                    const corte = await acervo.tirarFundo(arquivo);
-                    if (corte.ok) { arquivo = corte.arquivo; r.recorte = corte.metodo; r.avisoRecorte = corte.aviso; }
-                    else r.avisoRecorte = corte.error;
-                }
-                r.arquivo = arquivo;
-                if (args.paraEstudio !== false) {
-                    const g = await studio.midiaEnviar({ arquivo, nome: args.nome });
-                    // O "/midia/..." é o que vai em `src` e em `fundo.imagem`.
-                    if (g && g.ok !== false) r.src = g.url || g.src || null;
-                    else r.avisoGaleria = (g && g.error) || 'não deu para mandar para a galeria';
-                }
-                return r;
-            }
-            case 'midia_sem_fundo':
-                return acervo.tirarFundo(resolveInProject(args.arquivo, projectDir), { destino: args.destino });
-            case 'midia_creditos':
-                return { ok: true, creditos: acervo.creditos() };
-
-            case 'studio_analisar': {
-                // Ouvir o vídeo para achar as pausas. A conta acontece num
-                // navegador (é quem sabe decodificar MP4 sem instalar nada) —
-                // e ESCONDIDO: a conta não é da pessoa, e uma aba piscando no
-                // navegador dela é encanamento aparecendo. Sem Chrome nem
-                // Chromium nesta máquina, cai no navegador dela, como antes.
-                const visivel = process.env.PRIMOCODE_ANALISE_VISIVEL === '1';
-                const abrir = visivel ? openInBrowser : async (url) => {
-                    try { return await browser.abrirEscondido(url); }
-                    catch { openInBrowser(url); return null; }
-                };
-                return studio.analisarAudio({
-                    arquivo: args.arquivo, pausa: args.pausa, manter: args.manter,
-                    repetida: args.repetida, abrir, escondido: visivel ? null : browser.rodarEscondido,
-                });
-            }
-            case 'studio_exportar':
-                // O mp4 sem clique: a página do player roda escondida e gera
-                // pelo mesmo caminho do botão. Ver lib/studio.js.
-                // Com o Remotion mesclado: o vídeo quadro a quadro dele, o
-                // áudio do Studio. PRIMOCODE_SEM_REMOTION=1 desliga.
-                return studio.exportarVideo({
-                    id: args.id, destino: args.destino, fps: args.fps,
-                    escondido: browser.rodarEscondido, pasta: projectDir || process.cwd(),
-                    remotion: process.env.PRIMOCODE_SEM_REMOTION !== '1',
-                });
-
-            /* A MESMA peça, virando projeto Remotion.
-             *
-             * O Studio continua sendo o caminho normal: exporta em segundos,
-             * sem instalar nada. Isto é para quando o usuário pede Remotion
-             * pelo nome, ou quando a peça precisa do que só ele dá — render
-             * determinístico, vídeo longo, fps e codec escolhidos, ou o
-             * projeto em React para a pessoa mexer.
+            /* ── O ESTÚDIO ─────────────────────────────────────────────────
+             * Sete ferramentas, e nenhuma delas fala com servidor nenhum: o
+             * Studio antigo subia um Python em localhost:7777 porque tinha
+             * uma interface web para servir. A interface morreu — a IA faz
+             * tudo e abre o vídeo pronto — e o servidor morreu com ela.
              *
-             * Parte do documento que já existe: nada de um segundo
-             * vocabulário para o agente aprender. */
-            case 'remotion_projeto': {
-                const remotion = require('./remotion.js');
-                const peca = await studio.ler(args.id);
-                if (!peca || peca.ok === false) {
-                    return peca || { ok: false, error: `não achei a peça ${args.id}` };
-                }
-                const arq = peca.arquivo || peca;
-                const base = projectDir || cfg.ROOT_DIR;
-                const nome = cfg.slugify(args.pasta || arq.titulo || 'video') + '-remotion';
-                const destino = path.join(base, nome);
-                const r = remotion.montar({
-                    destino, titulo: arq.titulo, doc: arq.doc, fps: args.fps,
+             * Cada peça é uma PASTA, cada render é o Remotion. Ver
+             * lib/estudio/ para o porquê de cada peça.
+             */
+            case 'estudio_projeto':
+                return estudio.ferramentaProjeto(args);
+            case 'estudio_plano':
+                return estudio.ferramentaPlano(args);
+            case 'estudio_midia':
+                return estudio.ferramentaMidia(args);
+            case 'estudio_narrar':
+                return estudio.ferramentaNarrar(args);
+            case 'estudio_video':
+                // A transcrição precisa do servidor (a chave é dele), então o
+                // contexto do pedido atravessa até aqui.
+                return estudio.ferramentaVideo(args, ctx);
+            case 'estudio_render':
+                return estudio.ferramentaRender(args, {
+                    ...ctx,
+                    // O vídeo pronto abre para a pessoa assistir. É a única
+                    // coisa que abre: foi o vídeo que ela pediu.
+                    abrir: (arquivo) => { try { openInBrowser(arquivo); } catch {} },
                 });
-                if (!r.ok || !args.renderizar) return r;
-                // Só renderiza quando pedido: o `npm install` demora minutos e
-                // é escolha do usuário, não efeito colateral de criar a pasta.
-                const feito = await remotion.renderizar({ pasta: destino });
-                return Object.assign(r, { render: feito });
-            }
+            case 'estudio_site':
+                return estudio.ferramentaSite(args);
 
             case 'desktop_double_click':
                 return desktop.doubleClick(args.x, args.y);
@@ -698,7 +599,25 @@ async function despachar(name, args, ctx) {
                 });
 
             default:
-                return { ok: false, error: `Tool não implementada: ${name}` };
+                /* O MODELO PRECISA CONSEGUIR SE CORRIGIR AQUI.
+                   "Tool não implementada: studio_criar" não diz o que existe,
+                   e o que acontecia era o agente desistir e responder ao
+                   usuário que a ferramenta necessária "não está disponível".
+                   Dizendo QUAIS existem — e a mais parecida — ele chama a
+                   certa na volta seguinte, na mesma tarefa.
+
+                   Isto é rede, não conserto: a causa é a lista do servidor
+                   divergir do catálogo daqui, e ela se conserta lá. Mas a rede
+                   é o que separa uma tarefa que se recupera de uma que morre
+                   com o usuário esperando. */
+                return {
+                    ok: false,
+                    error: `A ferramenta "${name}" não existe.`,
+                    parecidas: catalogo.parecidasCom(name),
+                    comoResolver: 'chame uma das ferramentas que existem de verdade — as "parecidas" '
+                        + 'acima são as de nome mais próximo. Não invente nome de ferramenta, e não '
+                        + 'desista da tarefa por causa disto.',
+                };
         }
     }
 }

package/lib/ui.js

@@ -160,9 +160,10 @@ const TIPS = [
 ];
 
 const NEWS = [
-    'Vídeo com DIRETOR: roteiro, narração, voz e movimento antes de produzir',
-    'Ele busca e baixa imagem, logo e música — com a licença junto',
-    'A escolha da IA na abertura agora anda nas setinhas',
+    'Vídeo com DIRETOR: roteiro, narração e voz decididos antes de produzir',
+    'Ele busca e baixa imagem, logo e música — com a licença junto do arquivo',
+    '/voice abre o Primo Code Voice · /marketplace instala skills',
+    'Do "high" para cima ele PESQUISA referências antes de escrever',
     'Esc Esc a qualquer momento para o agente no meio do trabalho',
 ];
 
@@ -313,6 +314,9 @@ function actionHeader(name, args) {
     const label = ROTULOS[name] || name;
     let argStr = args ? (args.consulta || args.path || args.pattern || args.command || args.target || args.url || args.selector || args.text || args.app || args.window || args.name || args.ferramenta || args.titulo || args.description || (args.todos ? `${args.todos.length} tarefas` : '') || (args.x != null ? `${args.x},${args.y}` : '') || args.key || args.arquivo || args.id || JSON.stringify(args).slice(0,60)) : '';
     argStr = String(argStr || '').replace(/\s+/g, ' ').trim();
+    // Uma tool sem argumento nenhum caía no JSON.stringify e desenhava "{}"
+    // ao lado do nome — ruído que não diz nada.
+    if (argStr === '{}' || argStr === 'null' || argStr === 'undefined') argStr = '';
     if (argStr.length > 96) argStr = argStr.slice(0, 95) + '…';
     return `  ${c.brand('●')} ${c.bold(label)}${argStr ? '  '+c.muted(argStr) : ''}`;
 }

package/lib/voz.js

@@ -0,0 +1,239 @@
+/**
+ * voz.js — o lado Node do modo voz.
+ *
+ * O aplicativozinho da orb é Python (ver voz/primo_voz). O que mora aqui é a
+ * outra ponta: subir o processo, conversar com ele por JSON, e — a parte que
+ * importa — entregar cada pedido ao MESMO agente do terminal.
+ *
+ * ── POR QUE O CÉREBRO NÃO FOI PARA O PYTHON ──────────────────────────────
+ * O Jarvis mantinha uma sessão do Claude Code num processo filho e conversava
+ * por stream-json. Copiar aquele desenho aqui significaria uma segunda
+ * implementação do laço do agente, das quarenta ferramentas, do portão de
+ * permissão do computador e da corrente de conectores — em outra linguagem.
+ *
+ * Duas implementações do mesmo laço é a garantia de que uma delas está errada,
+ * e de que a correção de amanhã vai para só uma. Então o modo voz manda o
+ * texto para o `runAct` de sempre: as mesmas ferramentas, as mesmas skills, a
+ * mesma permissão, os mesmos conectores.
+ *
+ * ── O PEDIDO SAI DIFERENTE, E SÓ ISSO ────────────────────────────────────
+ * Uma resposta boa de ler é ruim de ouvir: lista com marcador, caminho de
+ * arquivo, bloco de código e trecho longo só funcionam para o olho. Então o
+ * pedido vai com uma instrução curta de FORMA — não de conteúdo. O agente
+ * continua fazendo o mesmo trabalho; ele só conta de outro jeito.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, execFileSync } = require('child_process');
+
+const PASTA = path.join(__dirname, '..', 'voz');
+
+/* A instrução de FORMA. Ela não muda o que o agente faz — muda como ele
+   conta. O que está proibido aqui é o que não existe em voz: marcador,
+   caminho, código, e parágrafo que ninguém segura de ouvido. */
+const COMO_FALAR = `[MODO VOZ] A sua resposta vai ser LIDA EM VOZ ALTA para a pessoa, e ela não vê tela nenhuma.
+
+Responda em no máximo 3 frases curtas, em português falado. Nada de lista com
+marcador, nada de caminho de arquivo, nada de bloco de código, nada de
+markdown — nada disso existe no ouvido de alguém.
+
+Diga o que você FEZ e o que mudou, não como. Se algo deu errado, diga em uma
+frase o que foi e o que você precisa.
+
+Faça o trabalho inteiro normalmente, com as ferramentas de sempre. O que muda
+é só o jeito de contar no fim.`;
+
+/** Onde está o Python 3. Mesmo problema do Estúdio, mesma cura. */
+function python() {
+    const nomes = process.platform === 'win32'
+        ? ['python', 'py', 'python3']
+        : ['python3', 'python', '/opt/homebrew/bin/python3', '/usr/local/bin/python3', '/usr/bin/python3'];
+    for (const n of nomes) {
+        try {
+            const v = execFileSync(n, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }).toString();
+            if (/Python 3/.test(v)) return n;
+        } catch { /* próximo */ }
+    }
+    return null;
+}
+
+/**
+ * O que falta para o modo voz abrir — e QUAL é a falta.
+ *
+ * A distinção é a diferença entre um recado que resolve e um que faz a pessoa
+ * dar voltas. Dois casos não se resolvem com pip:
+ *
+ *   · `sounddevice` instalado, mas sem o PortAudio do sistema. O import
+ *     explode com "PortAudio library not found", e mandar `pip install
+ *     sounddevice` ali é mandar instalar o que já está instalado.
+ *   · `tkinter` vem com o Python, mas algumas distribuições Linux o separam
+ *     num pacote do sistema — e `pip install tkinter` não existe.
+ *
+ * Por isso a checagem lê a MENSAGEM do erro, e não só o fato de ter falhado.
+ */
+function faltando(py) {
+    const falta = [];
+    for (const [modulo, pacote] of [['numpy', 'numpy'], ['sounddevice', 'sounddevice'], ['tkinter', null]]) {
+        try {
+            execFileSync(py, ['-c', `import ${modulo}`], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 20000 });
+        } catch (e) {
+            const saida = String((e.stderr || '') + (e.stdout || ''));
+            if (/portaudio/i.test(saida)) {
+                falta.push({ modulo, pacote: null, sistema: true, porque: 'o PortAudio, que é biblioteca do sistema' });
+            } else {
+                falta.push({ modulo, pacote });
+            }
+        }
+    }
+    return falta;
+}
+
+/** Como instalar uma biblioteca de sistema, neste sistema. */
+const COMO_SISTEMA = {
+    portaudio: {
+        darwin: 'brew install portaudio',
+        linux: 'sudo apt install libportaudio2   (ou o equivalente da sua distribuição)',
+        win32: 'no Windows ele vem junto com o sounddevice — reinstale com pip',
+    },
+    tkinter: {
+        darwin: 'brew install python-tk',
+        linux: 'sudo apt install python3-tk',
+        win32: 'reinstale o Python pelo python.org, marcando "tcl/tk"',
+    },
+};
+
+/**
+ * Confere o que é preciso, sem instalar nada.
+ *
+ * O tkinter é o caso especial: ele vem com o Python, mas em algumas
+ * distribuições Linux ele foi separado num pacote do SISTEMA — e `pip install
+ * tkinter` não existe. Dizer "instale com pip" ali seria mandar a pessoa a um
+ * lugar onde não há nada.
+ */
+function conferir() {
+    const py = python();
+    if (!py) {
+        return { ok: false, error: 'o modo voz precisa do Python 3, e não achei nenhum nesta máquina.',
+            comoResolver: 'instale em python.org e abra o terminal de novo' };
+    }
+    const falta = faltando(py);
+    if (!falta.length) return { ok: true, python: py };
+
+    const pip = falta.filter((f) => f.pacote).map((f) => f.pacote);
+    const linhas = [];
+    if (pip.length) linhas.push(`${py} -m pip install ${pip.join(' ')}`);
+    if (falta.some((f) => f.modulo === 'sounddevice' && f.sistema)) {
+        linhas.push(COMO_SISTEMA.portaudio[process.platform] || COMO_SISTEMA.portaudio.linux);
+    }
+    if (falta.some((f) => f.modulo === 'tkinter')) {
+        linhas.push(COMO_SISTEMA.tkinter[process.platform] || COMO_SISTEMA.tkinter.linux);
+    }
+
+    return {
+        ok: false,
+        python: py,
+        falta: falta.map((f) => f.modulo),
+        error: `falta o que o modo voz precisa: ${falta.map((f) => f.porque || f.modulo).join(', ')}`,
+        comoResolver: linhas.join('\n  '),
+        // Só o que o pip resolve entra no "instalar agora": oferecer instalar
+        // o que ele não instala é prometer o que não se cumpre.
+        instalavel: pip,
+    };
+}
+
+/** Instala o que dá para instalar com pip. O tkinter não passa por aqui. */
+function instalar(py, pacotes, aoFalar = () => {}) {
+    return new Promise((resolve) => {
+        aoFalar(`instalando ${pacotes.join(', ')} (uma vez, alguns minutos)`);
+        const p = spawn(py, ['-m', 'pip', 'install', '--quiet', ...pacotes]);
+        let erro = '';
+        p.stderr.on('data', (d) => { erro += d.toString(); });
+        p.on('close', (code) => resolve(code === 0
+            ? { ok: true }
+            : { ok: false, error: erro.slice(-400).trim() || `pip saiu com ${code}` }));
+        p.on('error', (e) => resolve({ ok: false, error: e.message }));
+    });
+}
+
+/**
+ * Abre o modo voz e fica de pé até a janela fechar.
+ *
+ * @param {object} op
+ * @param {string} op.python
+ * @param {string} op.servidor
+ * @param {string} op.token
+ * @param {string} op.voz
+ * @param {(texto:string)=>Promise<string>} op.pensar   o agente de verdade
+ * @param {(texto:string)=>void} op.mostrar             o que aparece no terminal
+ */
+function abrir({ python: py, servidor, token, voz, pensar, mostrar = () => {} }) {
+    return new Promise((resolve) => {
+        const p = spawn(py, ['-m', 'primo_voz'], {
+            cwd: PASTA,
+            env: {
+                ...process.env,
+                PYTHONPATH: PASTA,
+                PRIMOCODE_SERVER: servidor,
+                PRIMOCODE_TOKEN: token || '',
+                PRIMOCODE_VOZ: voz || 'antonio',
+                PYTHONUNBUFFERED: '1',
+            },
+        });
+
+        const manda = (obj) => {
+            try { p.stdin.write(JSON.stringify(obj) + '\n'); } catch { /* já fechou */ }
+        };
+
+        let buffer = '';
+        let ocupado = false;
+
+        p.stdout.on('data', async (d) => {
+            buffer += d.toString();
+            const linhas = buffer.split('\n');
+            buffer = linhas.pop();
+            for (const linha of linhas) {
+                if (!linha.trim()) continue;
+                let msg;
+                try { msg = JSON.parse(linha); } catch { continue; }
+
+                if (msg.tipo === 'fim') { try { p.kill(); } catch {} return; }
+                if (msg.tipo === 'erro') { mostrar(String(msg.texto || '')); continue; }
+                if (msg.tipo !== 'pedido') continue;
+
+                /* Um pedido por vez. A pessoa pode falar de novo enquanto ele
+                   trabalha — e dois agentes rodando ao mesmo tempo na mesma
+                   pasta é a receita para um escrever por cima do outro. */
+                if (ocupado) { manda({ tipo: 'resposta', texto: 'Ainda estou terminando o anterior.' }); continue; }
+                ocupado = true;
+
+                mostrar(String(msg.texto || ''));
+                manda({ tipo: 'estado', estado: 'pensando' });
+                try {
+                    const resposta = await pensar(String(msg.texto || ''));
+                    manda({ tipo: 'resposta', texto: resposta || 'Feito.' });
+                } catch (e) {
+                    manda({ tipo: 'erro', texto: `Não consegui: ${e.message}` });
+                } finally {
+                    ocupado = false;
+                }
+            }
+        });
+
+        // O Python fala com o terminal pela saída de ERRO, de propósito: o
+        // stdout inteiro é do protocolo, e uma linha solta ali quebraria a
+        // conversa entre os dois processos.
+        p.stderr.on('data', (d) => {
+            const texto = d.toString().trim();
+            if (texto) mostrar(texto, true);
+        });
+
+        p.on('close', () => resolve({ ok: true }));
+        p.on('error', (e) => resolve({ ok: false, error: e.message }));
+    });
+}
+
+module.exports = { conferir, instalar, abrir, python, COMO_FALAR, PASTA };