primocode 11.0.0 → 11.1.0

package/lib/plugin/voz.js

@@ -0,0 +1,532 @@
+/**
+ * voz.js — o lado Node do modo voz.
+ *
+ * O ouvido e a boca são Python (voz/primo_voz): microfone, Whisper, a voz
+ * que fala. O que mora aqui é a ponta do terminal: instalar o que falta,
+ * subir o processo, receber o que a pessoa DISSE e mandar falar a resposta.
+ *
+ * ── O MODO VOZ NÃO PENSA ─────────────────────────────────────────────────
+ * Até a 9.x o /voice tinha um cérebro próprio: chamava o agente por conta
+ * dele, ao lado do terminal, com a própria instrução de forma, o próprio
+ * roteador de conversa e o próprio portão de permissão. Dois agentes na mesma
+ * pasta, e duas versões de cada regra — a correção de amanhã ia para uma só.
+ * Na 10.0 a fala é só uma forma de DIGITAR: o que foi dito entra na mesma
+ * fila, na mesma caixa de recados e no mesmo roteador do terminal, e a
+ * resposta final é lida em voz alta (paraFalar).
+ */
+
+'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 DICA DO COMPUTADOR ────────────────────────────────────────────────
+ * Duas razões para existir, e as duas foram medidas:
+ *
+ * 1. O servidor só oferece as ferramentas desktop_* ao modelo quando o pedido
+ *    cita palavras como "mouse", "teclado", "ícone", "atalho", "janela" (o
+ *    grupo "computador" em lib/orcamento-entrada.js do servidor). "Abre o
+ *    Safari e pesquisa X" não cita nenhuma — e o modelo ficava sem as mãos.
+ *    Esta dica as cita de propósito.
+ * 2. "Mostra o teu mouse" virou uma página HTML com as coordenadas do mouse
+ *    DA PESSOA. O certo é mexer o cursor dele, que ela vê na tela.
+ */
+const DICA_COMPUTADOR = `[COMPUTADOR] Você pode usar o mouse, o teclado, as janelas e os ícones do computador da pessoa com as ferramentas desktop_* (desktop_open_app, desktop_click_element, desktop_click, desktop_type, desktop_key para atalho, desktop_scroll). Cada movimento aparece na tela como o SEU cursor. Para abrir um app, use desktop_open_app; para clicar em algo, prefira desktop_click_element pelo nome (leia os nomes com desktop_elements); coordenadas são em pontos da tela (desktop_size). Se pedirem para "mostrar o seu mouse/cursor", MEXA o cursor com desktop_move — nunca crie uma página ou arquivo para isso.`;
+
+/* ── O QUE SAI EM VOZ ──────────────────────────────────────────────────
+ * O agente responde para a TELA, como sempre — o modo voz não muda o que ele
+ * faz nem como ele escreve. O que vai para o ouvido é um resumo falado da
+ * mesma resposta: sem markdown, sem código, sem caminho, no máximo três
+ * frases. Quem quiser o detalhe olha o terminal, que é onde ele está. */
+function paraFalar(texto, { frases = 3, teto = 420 } = {}) {
+    let t = String(texto || '')
+        .replace(/```[\s\S]*?```/g, ' ')                  // bloco de código
+        .replace(/\s+(em|no|na|de|do|da|para)\s+`[^`]*[\/\\.][^`]*`/g, '')   // "em `/pasta/x`" some inteiro
+        .replace(/`([^`]*)`/g, (_, x) => (/[\/\\.]/.test(x) ? '' : x))   // caminho some, palavra fica
+        .replace(/https?:\/\/\S+/g, '')                     // link
+        .replace(/(^|\s)[~.]?\/[\w.\-\/]+/g, ' ')              // caminho solto
+        .replace(/^\s*(#+|[-*•]|\d+[.)])\s+/gm, '')          // título e marcador
+        .replace(/[*_>|]/g, '')
+        .replace(/\(\^‿\^\)[^\n]*/g, '')                     // o mascote
+        .replace(/\s+/g, ' ')
+        .trim();
+    const partes = t.match(/[^.!?…]+[.!?…]*/g) || [];
+    let fala = '';
+    for (const p of partes.slice(0, frases)) {
+        if ((fala + p).length > teto) break;
+        fala += p;
+    }
+    return (fala || t.slice(0, teto)).trim();
+}
+
+/* O VENV DO PRIMO. As dependências opcionais (VAD, painel em tela cheia) moram
+ * em ~/.primocode/voz-venv, instaladas sob demanda: ninguém precisa quebrar o
+ * Python do sistema (PEP 668) nem perde nada se não instalar. */
+const VENV = path.join(os.homedir(), '.primocode', 'voz-venv');
+const venvPython = () => path.join(VENV, process.platform === 'win32' ? 'Scripts' : 'bin', process.platform === 'win32' ? 'python.exe' : 'python');
+
+/** Onde está o Python 3. O do venv do Primo ganha, se já existir. */
+function python() {
+    if (fs.existsSync(venvPython())) return venvPython();
+    return pythonDoSistema();
+}
+
+function pythonDoSistema() {
+    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. Um caso não se resolve 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.
+ *
+ * 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']]) {
+        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',
+    },
+};
+
+/** Confere o que é preciso, sem instalar 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 = [];
+    /* O comando que a pessoa vai COPIAR precisa funcionar na máquina dela.
+       Mandar `pip install` seco é mandar ela bater na PEP 668 de novo,
+       exatamente no mesmo lugar onde o botão "Instalar agora?" já bateu. */
+    if (pip.length) {
+        linhas.push(`${py} -m pip install --user ${pip.join(' ')}`);
+        linhas.push(`(se recusar com "externally-managed-environment", acrescente --break-system-packages)`);
+    }
+    if (falta.some((f) => f.modulo === 'sounddevice' && f.sistema)) {
+        linhas.push(COMO_SISTEMA.portaudio[process.platform] || COMO_SISTEMA.portaudio.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. */
+/* AS TENTATIVAS, EM ORDEM — e por que uma só não serve.
+ *
+ * O Python do Homebrew e o do Debian/Ubuntu RECUSAM `pip install` no ambiente
+ * do sistema: é a PEP 668, "externally-managed-environment". Uma tentativa
+ * só, sem `--break-system-packages`, falha sempre nessas máquinas — e foi o
+ * que aconteceu com o dono, no Mac dele, ao aceitar "Instalar agora?".
+ *
+ * A ordem vai da menos invasiva para a mais: `--user` primeiro, que não toca
+ * no Python do sistema; a quebra do bloqueio só quando o resto falhou.
+ */
+const TENTATIVAS_PIP = [
+    (pacotes) => ['-m', 'pip', 'install', '--user', '--quiet', ...pacotes],
+    (pacotes) => ['-m', 'pip', 'install', '--user', '--quiet', '--break-system-packages', ...pacotes],
+    (pacotes) => ['-m', 'pip', 'install', '--quiet', ...pacotes],
+    (pacotes) => ['-m', 'pip', 'install', '--quiet', '--break-system-packages', ...pacotes],
+];
+
+/** A linha que interessa de um despejo do pip. */
+function porqueOPipFalhou(saida) {
+    const texto = String(saida || '').trim();
+    if (!texto) return '';
+    if (/externally-managed-environment/i.test(texto)) {
+        return 'o Python desta máquina não deixa instalar no ambiente do sistema (PEP 668)';
+    }
+    /* A linha que começa com "error:" é a que o pip escreveu para ser lida.
+       Cortar os últimos 400 caracteres — o que se fazia antes — pega o MEIO
+       de uma frase: o dono viu "não deu: n result in a broken Homebrew
+       installation", que não é português nem inglês. */
+    const erro = texto.split('\n').reverse().find((l) => /^\s*error:/i.test(l));
+    if (erro) return erro.replace(/^\s*error:\s*/i, '').trim().slice(0, 200);
+    const ultima = texto.split('\n').filter((l) => l.trim()).pop() || '';
+    return ultima.trim().slice(0, 200);
+}
+
+function instalar(py, pacotes, aoFalar = () => {}) {
+    return new Promise((resolve) => {
+        aoFalar(`instalando ${pacotes.join(', ')} (uma vez, alguns minutos)`);
+        let ultimoErro = '';
+
+        const tentar = (i) => {
+            if (i >= TENTATIVAS_PIP.length) {
+                return resolve({ ok: false, error: ultimoErro || 'o pip não conseguiu instalar' });
+            }
+            const p = spawn(py, TENTATIVAS_PIP[i](pacotes));
+            let saida = '';
+            p.stderr.on('data', (d) => { saida += d.toString(); });
+            p.stdout.on('data', (d) => { saida += d.toString(); });
+            p.on('close', (code) => {
+                if (code === 0) return resolve({ ok: true });
+                ultimoErro = porqueOPipFalhou(saida) || `pip saiu com ${code}`;
+                tentar(i + 1);
+            });
+            p.on('error', (e) => { ultimoErro = e.message; tentar(i + 1); });
+        };
+        tentar(0);
+    });
+}
+
+/**
+ * Liga o ouvido e a boca (voz/primo_voz). O processo não pensa: devolve o que
+ * ouviu por `aoOuvir` e fala o que receber em `falar`.
+ *
+ * @param {object} op
+ * @param {string} op.python
+ * @param {string} op.servidor
+ * @param {string} op.token
+ * @param {string} op.voz
+ * @param {(texto:string)=>void} op.aoOuvir     o que a pessoa disse, já transcrito
+ * @param {(texto:string, deErro?:boolean)=>void} op.mostrar   recado para o terminal
+ * @param {()=>void} [op.aoPronto]              o microfone abriu
+ * @returns {{processo, pronto: Promise, falar:(t:string)=>void, calar:()=>void}}
+ */
+function abrir({ python: py, servidor, token, voz, aoParar = () => {}, aoOuvir, mostrar = () => {}, aoPronto = () => {} }) {
+    let p;
+    const manda = (obj) => {
+        try { p.stdin.write(JSON.stringify(obj) + '\n'); } catch { /* já fechou */ }
+    };
+    const pronto = new Promise((resolve) => {
+        p = spawn(py, ['-m', 'primo_voz'], {
+            cwd: PASTA,
+            env: {
+                ...process.env,
+                PYTHONPATH: PASTA,
+                PRIMOCODE_SERVER: servidor,
+                PRIMOCODE_TOKEN: token || '',
+                PRIMOCODE_VOZ: voz || 'antonio',
+                PRIMOCODE_CWD: process.cwd(),
+                PYTHONUNBUFFERED: '1',
+                // O Whisper deixa um semáforo para o sistema recolher na saída,
+                // e o Python avisa disso no stderr. É inofensivo; o aviso não é.
+                PYTHONWARNINGS: 'ignore::UserWarning:multiprocessing.resource_tracker',
+            },
+        });
+        let buffer = '';
+        p.stdout.on('data', (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 === 'pronto') { try { aoPronto(); } catch {} continue; }
+                if (msg.tipo === 'parar') { try { aoParar(); } catch {} continue; }
+                if (msg.tipo === 'erro') { mostrar(String(msg.texto || ''), true); continue; }
+                if (msg.tipo === 'ouvi' && String(msg.texto || '').trim()) {
+                    try { aoOuvir(String(msg.texto).trim()); } catch (e) { mostrar(e.message, true); }
+                }
+            }
+        });
+        // O Python fala com o terminal pela saída de ERRO, de propósito: o
+        // stdout inteiro é do protocolo.
+        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 }));
+    });
+    /* O processo volta junto com a promessa: o /voice não bloqueia o
+       terminal, e quem chamou precisa de um jeito de encerrar depois (/voice
+       parar, ou a saída do programa) sem matar pelo nome — o que atropelaria
+       outra sessão do PrimoCode aberta na mesma máquina. */
+    return {
+        processo: p,
+        pronto,
+        /* O texto vai BRUTO: quem resume é o Primo (voz/primo_voz/conversa.py) —
+           a voz diz o resumo, o painel mostra o resto (código, listas). */
+        falar: (texto) => { const t = String(texto || '').trim(); if (t) manda({ tipo: 'falar', texto: t, bruto: true }); },
+        // O agente começou uma ferramenta: o painel mostra "executando" e o Primo confirma ("rodando os testes").
+        ferramenta: (nome, args) => manda({ tipo: 'ferramenta', nome, args: args || {} }),
+        painel: (acao) => manda({ tipo: 'painel', acao }),
+        calar: () => manda({ tipo: 'calar' }),
+        // A bolinha na tela: 'esperando' quando o terminal termina sem falar.
+        estado: (e) => manda({ tipo: 'estado', estado: e }),
+    };
+}
+
+/* ── PREPARAR TUDO, SEM PERGUNTAR ────────────────────────────────────────
+ *
+ *   "Instale tudo que precisa, rode tudo que precisa, então fica redondinho,
+ *    já funcionando." (23/09/2026)
+ *
+ * O /voice perguntava duas vezes ("Instalar agora?", "Baixar agora?") e
+ * parava em cada falta com um comando para a pessoa copiar. Agora ele mesmo
+ * resolve o que dá para resolver, nesta ordem:
+ *
+ *   1. bibliotecas do SISTEMA (o PortAudio) — pelo Homebrew no
+ *      macOS; no Linux, `sudo -n` (só funciona sem senha; senão, o comando);
+ *   2. pacotes do Python — os obrigatórios (numpy, sounddevice) e os que
+ *      deixam tudo local (faster-whisper; o PyObjC do cursor no macOS);
+ *   3. o modelo do Whisper (transcrição local).
+ *
+ * Só o que é OBRIGATÓRIO faltar impede o modo voz de abrir. Faltar um opcional
+ * vira um aviso de uma linha, e o modo voz abre mesmo assim.
+ */
+const OPCIONAIS = () => [
+    ['faster_whisper', 'faster-whisper', 'a transcrição local (Whisper)'],
+    ['pysilero_vad', 'pysilero-vad', 'o fim de fala preciso (Silero VAD)'],
+    ['edge_tts', 'edge-tts', 'a voz neural pt-BR (Edge TTS)'],
+    ...(process.platform === 'darwin' ? [
+        ['WebKit', 'pyobjc-framework-WebKit', 'o painel em tela cheia do Primo'],
+        ['EventKit', 'pyobjc-framework-EventKit', 'os compromissos de hoje do app Calendário'],
+        ['Quartz', 'pyobjc-framework-Quartz', 'o cursor do Primo na tela'],
+        ['Vision', 'pyobjc-framework-Vision', 'ler o texto da tela (clicar pelo nome em qualquer app)'],
+    ] : []),
+];
+
+function temModulo(py, modulo) {
+    try {
+        execFileSync(py, ['-c', `import ${modulo}`], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 30000 });
+        return true;
+    } catch { return false; }
+}
+
+function rodar(cmd, args, timeout = 15 * 60 * 1000) {
+    return new Promise((resolve) => {
+        let saida = '';
+        let p;
+        try { p = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] }); }
+        catch (e) { return resolve({ ok: false, saida: e.message }); }
+        const t = setTimeout(() => { try { p.kill(); } catch {} }, timeout);
+        p.stdout.on('data', (d) => { saida += d.toString(); });
+        p.stderr.on('data', (d) => { saida += d.toString(); });
+        p.on('close', (code) => { clearTimeout(t); resolve({ ok: code === 0, saida }); });
+        p.on('error', (e) => { clearTimeout(t); resolve({ ok: false, saida: e.message }); });
+    });
+}
+
+function brew() {
+    for (const b of ['brew', '/opt/homebrew/bin/brew', '/usr/local/bin/brew']) {
+        try { execFileSync(b, ['--version'], { stdio: 'ignore', timeout: 10000 }); return b; } catch { /* próximo */ }
+    }
+    return null;
+}
+
+/** As bibliotecas do sistema que faltam, instaladas por quem der. */
+async function instalarSistema(py, falta, aoFalar) {
+    const avisos = [];
+    const precisa = [];
+    if (falta.some((f) => f.modulo === 'sounddevice' && f.sistema)) precisa.push('portaudio');
+    if (!precisa.length) return avisos;
+
+    if (process.platform === 'darwin') {
+        const b = brew();
+        if (!b) {
+            avisos.push('o Homebrew não está instalado, então não deu para instalar '
+                + precisa.join(' e ') + ' sozinho — instale em brew.sh e rode /voice de novo.');
+            return avisos;
+        }
+        const formulas = precisa;
+        aoFalar(`instalando ${formulas.join(', ')} pelo Homebrew`);
+        const r = await rodar(b, ['install', ...formulas]);
+        if (!r.ok) avisos.push(`o Homebrew não instalou ${formulas.join(', ')}: ${porqueOPipFalhou(r.saida)}`);
+        return avisos;
+    }
+    if (process.platform === 'linux') {
+        const pacotes = precisa.map(() => 'libportaudio2');
+        aoFalar(`instalando ${pacotes.join(', ')}`);
+        const r = await rodar('sudo', ['-n', 'apt-get', 'install', '-y', ...pacotes]);
+        if (!r.ok) avisos.push(`precisa de senha para instalar: sudo apt install ${pacotes.join(' ')}`);
+        return avisos;
+    }
+    avisos.push(COMO_SISTEMA.portaudio.win32);
+    return avisos;
+}
+
+/** O Whisper local, baixado antes da primeira frase. ~480 MB, uma vez. */
+async function baixarWhisper(py) {
+    const r = await new Promise((resolve) => {
+        const p = spawn(py, ['-m', 'primo_voz.transcrever', 'baixar'], {
+            cwd: PASTA, env: { ...process.env, PYTHONPATH: PASTA },
+        });
+        let fora = '';
+        let erro = '';
+        p.stdout.on('data', (d) => { fora += d.toString(); });
+        p.stderr.on('data', (d) => { erro += d.toString(); });
+        p.on('close', () => {
+            try { resolve(JSON.parse(fora.trim().split('\n').pop())); }
+            catch { resolve({ ok: false, error: erro.trim().split('\n').pop() || 'o download não respondeu' }); }
+        });
+        p.on('error', (e) => resolve({ ok: false, error: e.message }));
+    });
+    return r;
+}
+
+/**
+ * Deixa o modo voz pronto: instala e baixa tudo o que falta, sem perguntar.
+ *
+ * @param {(msg:string)=>void} aoFalar   uma linha de progresso por etapa
+ * @returns {Promise<{ok:boolean, python?:string, esperando?:boolean,
+ *                    avisos:string[], error?:string, comoResolver?:string}>}
+ */
+async function criarVenv(aoFalar) {
+    if (fs.existsSync(venvPython())) return null;
+    const base = pythonDoSistema();
+    if (!base) return null;
+    aoFalar('criando o ambiente do Primo (~/.primocode/voz-venv)');
+    const r = await rodar(base, ['-m', 'venv', VENV], 5 * 60 * 1000);
+    return r.ok ? null : `não consegui criar o ambiente do Primo (${porqueOPipFalhou(r.saida)}) — uso o Python do sistema.`;
+}
+
+async function preparar(aoFalar = () => {}) {
+    const avisoVenv = await criarVenv(aoFalar);
+    const py = python();
+    if (!py) {
+        return { ok: false, avisos: [], error: 'o modo voz precisa do Python 3, e não achei nenhum nesta máquina.',
+            comoResolver: process.platform === 'darwin' ? 'brew install python' : 'instale em python.org e abra o terminal de novo' };
+    }
+    const avisos = avisoVenv ? [avisoVenv] : [];
+
+    // 1. sistema, depois 2. os obrigatórios pelo pip.
+    let falta = faltando(py);
+    avisos.push(...await instalarSistema(py, falta, aoFalar));
+    falta = faltando(py);
+    const pipObrigatorio = falta.filter((f) => f.pacote).map((f) => f.pacote);
+    if (pipObrigatorio.length) {
+        const r = await instalar(py, pipObrigatorio, aoFalar);
+        if (!r.ok) avisos.push(`o pip não instalou ${pipObrigatorio.join(', ')}: ${r.error}`);
+        falta = faltando(py);
+    }
+    if (falta.length) {
+        const c = conferir();
+        return { ok: false, python: py, avisos, error: c.error, comoResolver: c.comoResolver };
+    }
+
+    // 2b. os opcionais: faltar um deles não impede o modo voz de abrir.
+    const opcionais = OPCIONAIS().filter(([m]) => !temModulo(py, m));
+    if (opcionais.length) {
+        const r = await instalar(py, opcionais.map(([, pacote]) => pacote), aoFalar);
+        for (const [m, , para] of opcionais) {
+            if (!temModulo(py, m)) avisos.push(`sem ${para}: ${r.ok ? 'o pacote não carregou' : r.error}`);
+        }
+    }
+
+    // 3. os modelos.
+    if (temModulo(py, 'faster_whisper')) {
+        aoFalar('preparando a transcrição local (Whisper, ~480 MB na primeira vez)');
+        const w = await baixarWhisper(py);
+        if (!w.ok) avisos.push(`a transcrição local não ficou pronta (${w.error}) — vai pelo servidor.`);
+    }
+    return { ok: true, python: py, avisos };
+}
+
+/** Primo.app em ~/Applications (Launchpad/Spotlight) + o primo-app.json com os caminhos ABSOLUTOS de node e primocode:
+ *  o app aberto pelo Finder não tem o PATH do terminal. Chamado no primeiro /voice e por `primocode voz instalar-app`. */
+function instalarApp({ python: py, dock = false } = {}) {
+    if (process.platform !== 'darwin') return { ok: false, erro: 'o app do Primo é só para macOS' };
+    try {
+        let cfg = {};
+        try { cfg = require('../config/config').loadConfig(); } catch { /* usa o padrão do app */ }
+        const arq = path.join(os.homedir(), '.primocode', 'primo-app.json');
+        fs.mkdirSync(path.dirname(arq), { recursive: true });
+        fs.writeFileSync(arq, JSON.stringify({
+            node: process.execPath, primocode: path.resolve(__dirname, '..', '..', 'bin', 'primocode.js'),
+            servidor: cfg.server || '', path: process.env.PATH || '', voz: cfg.voz || 'antonio', versao: require('../../package.json').version,
+        }, null, 2));
+        const env = { ...process.env, PYTHONPATH: PASTA, ...(dock ? { PRIMOCODE_APP_DOCK: '1' } : {}) };
+        const linhas = execFileSync(py, ['-m', 'primo_voz.appmac'], { cwd: PASTA, env, encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'ignore'] }).trim().split('\n');
+        return { ok: !!linhas[0], exe: linhas[0] || null, pythonpath: linhas[1] || PASTA, app: path.join(os.homedir(), 'Applications', 'Primo.app') };
+    } catch (e) { return { ok: false, erro: e.message }; }
+}
+
+/** `/voice painel`: só o HUD (sem microfone). Mac com PyObjC = tela cheia; senão, o quadro no terminal. */
+function abrirPainel({ python: py }) {
+    const mac = process.platform === 'darwin' && temModulo(py, 'WebKit');
+    // No Mac o painel roda pelo Primo.app (Dock e Cmd+Tab mostram "Primo" com o ícone); sem ele, o python direto.
+    let exe = null, pp = PASTA;
+    if (mac) { const r = instalarApp({ python: py }); if (r.exe) { exe = r.exe; pp = r.pythonpath; } }
+    const [cmd, args] = exe ? [exe, ['-m', 'primo_voz.hud', '--livre']] : [py, ['-m', mac ? 'primo_voz.hud' : 'primo_voz.painel_tui', ...(mac ? ['--livre'] : [])]];
+    const p = spawn(cmd, args, {
+        cwd: PASTA, env: { ...process.env, PYTHONPATH: exe ? pp : PASTA }, stdio: mac ? 'ignore' : ['pipe', 'inherit', 'inherit'],
+    });
+    return { processo: p, tela: mac };
+}
+
+/** Grava o nome do assistente em ~/.primocode/voz.json (o mesmo arquivo que voz/primo_voz/identidade.py lê). */
+function definirNome(nome) {
+    const limpo = String(nome || '').replace(/[^\p{L}\p{N} -]/gu, '').trim();
+    if (!limpo || limpo.split(/\s+/).length > 2 || limpo.length < 2 || limpo.length > 20) return null;
+    const arq = process.env.PRIMOCODE_VOZ_CONFIG || path.join(os.homedir(), '.primocode', 'voz.json');
+    let cfg = {};
+    try { cfg = JSON.parse(fs.readFileSync(arq, 'utf8')); } catch { /* primeira vez */ }
+    cfg.nome = limpo.split(/\s+/).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+    fs.mkdirSync(path.dirname(arq), { recursive: true });
+    fs.writeFileSync(arq, JSON.stringify(cfg, null, 2));
+    return cfg.nome;
+}
+
+/** As linhas do `primocode doutor` sobre o modo voz. */
+function linhasDoutor() {
+    const py = python();
+    if (!py) return [{ ok: false, item: 'Primo (voz)', detalhe: 'sem Python 3', conserto: 'brew install python' }];
+    const tem = (m) => temModulo(py, m);
+    const venv = fs.existsSync(venvPython());
+    const linha = (ok, item, detalhe, conserto) => ({ ok, item, detalhe, conserto: ok === false ? conserto : undefined });
+    return [
+        linha(venv ? true : null, 'Primo: ambiente', venv ? VENV : 'ainda não criado — /voice cria sozinho', undefined),
+        linha(tem('sounddevice') && tem('numpy'), 'Primo: microfone', 'sounddevice + numpy', '/voice instala; ou: ' + py + ' -m pip install sounddevice numpy'),
+        linha(tem('faster_whisper') ? true : null, 'Primo: Whisper local', tem('faster_whisper') ? 'instalado' : 'não instalado — usa o servidor'),
+        linha(tem('pysilero_vad') ? true : null, 'Primo: Silero VAD', tem('pysilero_vad') ? 'fim de fala preciso' : 'não instalado — usa o corte por volume'),
+        linha(process.platform === 'darwin' ? (tem('WebKit') ? true : null) : null, 'Primo: tela cheia',
+            process.platform !== 'darwin' ? 'só no Mac — aqui, painel no terminal' : tem('WebKit') ? 'pronto' : 'sem PyObjC WebKit — usa a orbe'),
+    ];
+}
+
+module.exports = { instalarApp, definirNome, VENV, abrirPainel, linhasDoutor, DICA_COMPUTADOR, paraFalar, conferir, instalar, preparar, porqueOPipFalhou, abrir, python, PASTA };

package/lib/porta.js

@@ -12,7 +12,7 @@
  * 127.0.0.1 e ::1 com um connect curto e diz qual endereço abrir. O <title> da página que responde mostra se é o SEU app
  * ou outro programa que pegou a porta.
  *
- * O /open (lib/comandos-extra.js, acharAlvoAbrir) só abre a primeira porta viva e, sem nenhuma, diz "não achei". O /porta
+ * O /open (lib/cli/comandos-extra.js, acharAlvoAbrir) só abre a primeira porta viva e, sem nenhuma, diz "não achei". O /porta
  * é o porquê: ele usa as mesmas portas do /open e mais as escritas no vite.config, no .env e no server.js.
  */
 
@@ -57,8 +57,8 @@ function declaradas(projectDir) {
         const p = PADRAO.find(([re]) => re.test(s));
         if (p) poe(p[1], p[2]);   // sem porta escrita: a de sempre da ferramenta
     }
-    // e as que o /open já procura (lib/comandos-extra.js): o /porta nunca olha menos que ele
-    for (const n of require('./comandos-extra.js').portasDoProjeto(projectDir)) poe(n, 'o padrão das ferramentas do projeto');
+    // e as que o /open já procura (lib/cli/comandos-extra.js): o /porta nunca olha menos que ele
+    for (const n of require('./cli/comandos-extra.js').portasDoProjeto(projectDir)) poe(n, 'o padrão das ferramentas do projeto');
     return out;
 }
 
@@ -141,7 +141,7 @@ async function diagnostico(projectDir, { tempo } = {}) {
     return { declaradas: dec, abertas, ...frase({ declaradas: dec, abertas, rodar: passo && passo.comando }) };
 }
 
-// o pedido que talvez seja de porta: só SUGERE ao modelo rodar `primocode porta` (lib/act.js); quem decide é ele
+// o pedido que talvez seja de porta: só SUGERE ao modelo rodar `primocode porta` (lib/session/runner/act.js); quem decide é ele
 const PEDE_PORTA = /n[ãa]o (abre|carrega|aparece|funciona)|tela (branca|em branco)|localhost|\bporta\b|servidor/i;
 
 module.exports = { declaradas, olhar, frase, diagnostico, COMUNS, PEDE_PORTA };

package/lib/pre-leitura.js

@@ -11,7 +11,7 @@
  * e confere o index.html antes de editar), num "muda a cor do botão" em
  * projeto de 10 arquivos: 9 pedidos ao modelo antes, 2 depois. Com todos os
  * arquivos grandes demais para entrar aqui, a ordem de juntar leituras e a
- * releitura sem mudança (lib/act.js, RELEITURA) ainda levam de 9 para 4.
+ * releitura sem mudança (lib/session/runner/act.js, RELEITURA) ainda levam de 9 para 4.
  *
  * O mapa do projeto já dava os NOMES. Isto põe o CONTEÚDO dos poucos arquivos
  * que quase todo pedido de página lê — o citado no pedido primeiro, depois
@@ -45,7 +45,7 @@ const JA_ENTRAM = new Set(['memory.md', 'PRIMO.md', 'AGENTS.md', 'CLAUDE.md']);
 
 /** O orçamento de agora: folgado só com provedor próprio (/api). */
 function orcamento() {
-    try { return require('./local/provedor.js').atual() ? ORCAMENTO_LOCAL : ORCAMENTO_SERVIDOR; }
+    try { return require('./provider/local/provedor.js').atual() ? ORCAMENTO_LOCAL : ORCAMENTO_SERVIDOR; }
     catch { return ORCAMENTO_SERVIDOR; }
 }
 

package/lib/preparar.js

@@ -19,7 +19,7 @@ const sem = () => process.env.PRIMOCODE_SEM_POSINSTALL === '1' || process.env.CI
 function posinstalar() {
     try {
         if (sem()) return;
-        const ec = require('./estudio/effectcraft.js');
+        const ec = require('./plugin/estudio/effectcraft.js');
         if (!ec.asset()) return;
         const filho = spawn(process.execPath, [__filename, '--fundo'], { detached: true, stdio: 'ignore', windowsHide: true });
         filho.on('error', () => {});
@@ -29,7 +29,7 @@ function posinstalar() {
 }
 
 async function baixarEffectCraft() {
-    const ec = require('./estudio/effectcraft.js');
+    const ec = require('./plugin/estudio/effectcraft.js');
     try { return await Promise.race([ec.garantir(), new Promise((r) => setTimeout(() => r({ ok: false, error: 'demorou demais (10 min)' }), 600000))]); }
     catch (e) { return { ok: false, error: e.message }; }
 }
@@ -45,7 +45,7 @@ function estudioLinhas(dep = {}) {
     const tenta = (fn, padrao) => { try { return fn(); } catch { return padrao; } };
 
     // EffectCraft (motor After Effects)
-    const ec = tenta(() => require('./estudio/effectcraft.js'));
+    const ec = tenta(() => require('./plugin/estudio/effectcraft.js'));
     if (ec) {
         const bin = process.env.PRIMOCODE_EFFECTCRAFT_BIN || path.join(os.homedir(), '.primocode', 'bin', 'effectcraft-' + ec.VERSAO);
         const tem = fs.existsSync(bin) && (fs.statSync(bin).isFile() || fs.readdirSync(bin).length > 0);
@@ -53,7 +53,7 @@ function estudioLinhas(dep = {}) {
             'rode: primocode preparar   (baixa uns 100 MB; precisa de internet)');
     }
     // ffmpeg / ffprobe
-    const ff = tenta(() => require('./estudio/video.js').ffmpeg(), null) || achar('ffmpeg');
+    const ff = tenta(() => require('./plugin/estudio/video.js').ffmpeg(), null) || achar('ffmpeg');
     poe(!!ff, 'ffmpeg', ff || 'não encontrado', { darwin: 'brew install ffmpeg', linux: 'sudo apt install ffmpeg', win32: 'winget install Gyan.FFmpeg' }[process.platform] || 'instale o ffmpeg');
     // whisper (tempo de cada palavra na legenda)
     const wbin = process.env.PRIMOCODE_WHISPER_BIN || '/opt/homebrew/bin/whisper-cli';
@@ -61,22 +61,22 @@ function estudioLinhas(dep = {}) {
     poe(w ? true : null, 'whisper', w || 'não instalado — a legenda usa o tempo estimado, sem medir cada palavra', undefined);
     if (!w) linhas[linhas.length - 1].conserto = 'opcional: brew install whisper-cpp';
     // fontes (cache do Google Fonts)
-    const cache = tenta(() => require('./estudio/glifos.js').CACHE, null);
+    const cache = tenta(() => require('./plugin/estudio/glifos.js').CACHE, null);
     const nFontes = cache && fs.existsSync(cache) ? fs.readdirSync(cache).filter((f) => /\.(ttf|otf)$/i.test(f)).length : 0;
     poe(null, 'Fontes', nFontes ? `${nFontes} em cache` : 'baixam sozinhas no primeiro vídeo (precisa de internet)');
     // sandbox
-    const sb = tenta(() => require('./sandbox.js').estado(), null);
+    const sb = tenta(() => require('./permission/sandbox.js').estado(), null);
     if (sb) poe(null, 'Sandbox', sb.ativo ? `ligado (${sb.mecanismo})` : (sb.mecanismo ? `desligado — ${sb.mecanismo} disponível; /sandbox on liga` : 'sem mecanismo neste sistema (comandos rodam sem isolamento)'));
     // marca ativa
-    const mk = tenta(() => require('./marca-kit.js').ativa([process.cwd()]), null);
+    const mk = tenta(() => require('./plugin/marca-kit.js').ativa([process.cwd()]), null);
     poe(null, 'Marca ativa', mk ? (mk.nome || mk.slug || 'sim') : 'nenhuma — primocode marca criar <nome>');
     // Primo (modo voz)
-    tenta(() => linhas.push(...require('./voz.js').linhasDoutor()), null);
+    tenta(() => linhas.push(...require('./plugin/voz.js').linhasDoutor()), null);
     // MCP
-    const mcp = tenta(() => Object.keys(require('./mcp.js').servidores()), []);
+    const mcp = tenta(() => Object.keys(require('./mcp/mcp.js').servidores()), []);
     poe(null, 'MCP', mcp.length ? mcp.join(', ') : 'nenhum servidor');
     // plano
-    const eu = tenta(() => require('./conta.js').atual(), null);
+    const eu = tenta(() => require('./config/conta.js').atual(), null);
     poe(eu ? true : false, 'Plano', eu ? `${eu.plano}${eu.pro ? ' (pago)' : ''} · ${eu.email || ''}` : 'sem login', 'entre com /login (ou `primocode`, no primeiro uso)');
     return linhas;
 }
@@ -99,7 +99,7 @@ async function main(args = []) {
         console.log(r.ok ? '✓ EffectCraft pronto: ' + r.bin : '✗ ' + r.error);
         return r.ok ? 0 : 1;
     }
-    const extra = require('./comandos-extra.js'), cfg = require('./config.js');
+    const extra = require('./cli/comandos-extra.js'), cfg = require('./config/config.js');
     console.log('');
     const base = await extra.diagnosticar({ raiz: cfg.ROOT_DIR, arquivoConfig: cfg.CONFIG_FILE, acharChrome: () => require('./browser').findChrome(), prazoServidor: 8000 });
     return imprimir(base.concat(estudioLinhas())) ? 1 : 0;