primocode 10.19.0 → 11.1.0

package/lib/tools.js

@@ -1,1067 +0,0 @@
-/**
- * Ferramentas locais do agente.
- *
- * Tudo roda na máquina do usuário — o servidor só decide o que chamar.
- * Todo caminho é resolvido dentro da pasta de trabalho da sessão.
- */
-
-'use strict';
-
-const catalogo = require('./catalogo.js');
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { exec, execFile } = require('child_process');
-const sandbox = require('./sandbox.js');
-const browser = require('./browser');
-const desktop = require('./desktop');
-const cursor = require('./cursor');
-
-/* ── O CURSOR DO PRIMO NO MAC ────────────────────────────────────────────
- * No macOS, mouse e teclado passam pelo cursor dele (lib/cursor.js): a mesma
- * ação acontece de verdade, e a pessoa VÊ a seta dele indo até lá, clicando,
- * digitando. Sem o cursor (outro sistema, ou o Python não subiu), vale o
- * caminho antigo do desktop.js. */
-/* Sem o cursor, a ação vai pelo caminho antigo, que NÃO aparece na tela. Isso
-   era calado: a pessoa via o terminal dizer "ok" e nada se mexer. Agora sai
-   uma linha, uma vez por sessão, dizendo por quê — e o modelo recebe o
-   mesmo aviso junto do resultado, para contar em vez de fingir. */
-let avisouSemCursor = false;
-function semCursorVisivel(resultado, motivo) {
-    const aviso = `o cursor do Primo não abriu (${motivo || 'motivo desconhecido'}): a ação roda, mas não aparece na tela`;
-    if (!avisouSemCursor) {
-        avisouSemCursor = true;
-        try { console.log(require('./ui.js').c.warn(`  ⎿ ${aviso}`)); } catch { /* sem tela */ }
-    }
-    return resultado && typeof resultado === 'object' ? { ...resultado, avisoCursor: aviso } : resultado;
-}
-
-async function peloCursor(cmd, args, reserva) {
-    if (!cursor.disponivel()) return reserva();
-    const r = await cursor.mandar(cmd, args);
-    if (r.semCursor) return semCursorVisivel(await reserva(), r.error);
-    if (!r.ok) return { ok: false, error: r.error || 'o cursor não conseguiu', ...(r.permissao === false ? { permissao: false } : {}) };
-    return { ok: true };
-}
-
-function numero(v) { const n = Number(v); return Number.isFinite(n) ? n : null; }
-
-/** Os textos visíveis na tela, pelo OCR do cursor, no formato dos elementos. */
-async function textosDaTela() {
-    if (!cursor.disponivel()) return { ok: false, error: 'ler a tela é só no macOS' };
-    const r = await cursor.mandar('ler_tela', {}, 30000);
-    if (!r.ok) return { ok: false, error: r.error || 'não consegui ler a tela' };
-    return { ok: true, elementos: (r.textos || []).map((t) => ({ nome: t.texto, tipo: 'texto na tela', x: t.x, y: t.y })) };
-}
-
-async function clicarPeloCursor(x, y, { botao = 'left', duplo = false, rotulo } = {}) {
-    const [nx, ny] = [numero(x), numero(y)];
-    if (nx == null || ny == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
-    return peloCursor('clicar', { x: nx, y: ny, botao: botao === 'right' ? 'direito' : 'esquerdo', duplo, rotulo },
-        () => (duplo ? desktop.doubleClick(nx, ny) : desktop.click(nx, ny, botao)));
-}
-const referencia = require('./referencia');
-const snapshot = require('./snapshot');
-const casar = require('./casar');
-const estudio = require('./estudio');
-const cfg = require('./config');
-
-const IGNORAR = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache', 'vendor']);
-const MAX_ARQUIVOS_VARREDURA = 5000;
-
-function fmtBytes(n) {
-    if (n < 1024) return `${n} B`;
-    if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
-    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
-}
-
-// Todo caminho vindo do modelo é resolvido DENTRO da pasta de trabalho.
-// Sem isso o agente espalha arquivo por qualquer lugar do disco — e um
-// "../../.." viraria escrita fora da área do projeto.
-function resolveInProject(rawPath, projectDir) {
-    const base = projectDir || process.cwd();
-    // Letra de drive (C:\, D:/) é sempre absoluta — mesmo no Linux, onde o
-    // path.resolve a trataria como nome relativo e deixaria escapar da pasta.
-    if (/^[a-zA-Z]:[\\/]/.test(String(rawPath || ''))) {
-        throw new Error(`Caminho fora da pasta de trabalho: ${rawPath}`);
-    }
-    const target = path.resolve(base, rawPath || '.');
-    const rel = path.relative(base, target);
-    // `..` como SEGMENTO, não como começo de nome: "..rascunho" é legítimo.
-    if (rel === '..' || rel.startsWith('..' + path.sep) || rel.startsWith('../') || path.isAbsolute(rel)) {
-        throw new Error(`Caminho fora da pasta de trabalho: ${rawPath}`);
-    }
-    return target;
-}
-
-/* ── LER EM OUTRA PASTA ──────────────────────────────────────────────────
- * A pessoa citou outra pasta ("olha como fiz no landing-padaria"): o agente
- * pode LER e PROCURAR lá, sem trocar a pasta de trabalho (lib/outra-pasta.js).
- * Só leitura, e só nas pastas que a própria pessoa citou nesta sessão —
- * escrever continua preso na pasta de trabalho pelo resolveInProject. */
-const PASTAS_DE_CONSULTA = new Set();
-
-function liberarLeitura(dir) {
-    if (!dir) return;
-    try { if (fs.statSync(dir).isDirectory()) PASTAS_DE_CONSULTA.add(path.resolve(dir)); } catch { /* não existe */ }
-}
-
-function pastasDeConsulta() { return [...PASTAS_DE_CONSULTA]; }
-function esquecerConsultas() { PASTAS_DE_CONSULTA.clear(); }
-
-/** Caminho para LER: dentro do projeto, ou dentro de uma pasta citada. */
-function resolverParaLer(rawPath, projectDir) {
-    try {
-        return resolveInProject(rawPath, projectDir);
-    } catch (e) {
-        const bruto = String(rawPath || '').replace(/^~(?=$|[/\\])/, os.homedir());
-        if (path.isAbsolute(bruto)) {
-            const alvo = path.resolve(bruto);
-            for (const raiz of PASTAS_DE_CONSULTA) {
-                const rel = path.relative(raiz, alvo);
-                if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) return alvo;
-            }
-        }
-        throw new Error(`${e.message}. Ler fora da pasta de trabalho só vale nas pastas que o usuário citou; `
-            + 'para trabalhar em outra pasta, use mudar_pasta.');
-    }
-}
-
-/**
- * Onde procurar (glob/grep): a pasta de trabalho, ou a pasta citada.
- *
- * O schema do servidor não ganhou campo novo (cada token do núcleo conta no
- * teto do minuto): a outra pasta vem no PADRÃO absoluto —
- * "/Users/x/site/src/<estrela>.js" vira a raiz "/Users/x/site/src" e o
- * padrão "<estrela>.js". `pasta` explícito também vale, para quem mandar.
- */
-function raizDaBusca(padrao, pastaPedida, projectDir) {
-    if (pastaPedida) return { raiz: resolverParaLer(pastaPedida, projectDir), padrao, outra: true };
-    const bruto = String(padrao || '').replace(/^~(?=$|[/\\])/, os.homedir());
-    if (!padrao || !path.isAbsolute(bruto)) return { raiz: projectDir, padrao, outra: false };
-    const partes = bruto.split(/[/\\]/);
-    const i = partes.findIndex((p) => /[*?{[]/.test(p));
-    const fixo = (i === -1 ? partes : partes.slice(0, i)).join('/') || '/';
-    const resto = i === -1 ? '**/*' : partes.slice(i).join('/');
-    const raiz = resolverParaLer(fixo, projectDir);
-    return { raiz, padrao: resto, outra: path.resolve(raiz) !== path.resolve(projectDir) };
-}
-
-function treeDir(dir, maxDepth = 2, currentDepth = 0, prefix = '') {
-    if (currentDepth > maxDepth) return '';
-    let result = '';
-    try {
-        const items = fs.readdirSync(dir);
-        const dirs = [], files = [];
-        for (const item of items) {
-            if (item.startsWith('.') && item !== '.env') continue;
-            if (IGNORAR.has(item)) continue;
-            // Link quebrado não derruba a listagem inteira: entra como arquivo.
-            let ehPasta = false;
-            try { ehPasta = fs.statSync(path.join(dir, item)).isDirectory(); } catch { ehPasta = false; }
-            (ehPasta ? dirs : files).push(item);
-        }
-        dirs.sort(); files.sort();
-        const all = [...dirs, ...files];
-        for (let i = 0; i < all.length; i++) {
-            const item = all[i];
-            const isLast = i === all.length - 1;
-            result += prefix + (isLast ? '└── ' : '├── ') + item + '\n';
-            const full = path.join(dir, item);
-            if (dirs.includes(item) && currentDepth < maxDepth) {
-                result += treeDir(full, maxDepth, currentDepth + 1, prefix + (isLast ? '    ' : '│   '));
-            }
-        }
-    } catch { return ''; }
-    return result;
-}
-
-// Percorre a árvore uma vez só; grep e glob se apoiam nisto.
-function* walk(dir, base, profundidade = 0) {
-    if (profundidade > 12) return;
-    let entradas;
-    try { entradas = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-    for (const e of entradas) {
-        if (IGNORAR.has(e.name)) continue;
-        if (e.name.startsWith('.') && e.name !== '.env') continue;
-        const full = path.join(dir, e.name);
-        if (e.isDirectory()) yield* walk(full, base, profundidade + 1);
-        else yield path.relative(base, full).replace(/\\/g, '/');
-    }
-}
-
-// Glob sem dependência externa: **, *, ? e {a,b}.
-function globToRegex(pattern) {
-    let re = '';
-    for (let i = 0; i < pattern.length; i++) {
-        const ch = pattern[i];
-        if (ch === '*') {
-            if (pattern[i + 1] === '*') {
-                // **/ some caminho inteiro, inclusive "nenhuma pasta"
-                if (pattern[i + 2] === '/') { re += '(?:.*/)?'; i += 2; }
-                else { re += '.*'; i += 1; }
-            } else re += '[^/]*';
-        } else if (ch === '?') re += '[^/]';
-        else if (ch === '{') {
-            const fim = pattern.indexOf('}', i);
-            if (fim === -1) re += '\\{';
-            else {
-                re += '(?:' + pattern.slice(i + 1, fim).split(',').map((s) => s.replace(/[.+^${}()|[\]\\]/g, '\\$&')).join('|') + ')';
-                i = fim;
-            }
-        } else re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
-    }
-    return new RegExp(`^${re}$`, 'i');
-}
-
-function globFiles(pattern, projectDir) {
-    const re = globToRegex(pattern);
-    const achados = [];
-    for (const rel of walk(projectDir, projectDir)) {
-        if (achados.length >= MAX_ARQUIVOS_VARREDURA) break;
-        if (re.test(rel)) achados.push(rel);
-    }
-    return achados.sort();
-}
-
-function pareceBinario(buf) {
-    const amostra = buf.slice(0, 1024);
-    for (let i = 0; i < amostra.length; i++) if (amostra[i] === 0) return true;
-    return false;
-}
-
-function grepFiles({ pattern, glob, ignoreCase, contexto = 0, maxResultados = 100 }, projectDir) {
-    let re;
-    try { re = new RegExp(pattern, ignoreCase ? 'i' : ''); }
-    catch (e) { return { ok: false, error: `Regex inválida: ${e.message}` }; }
-
-    const filtro = glob ? globToRegex(glob) : null;
-    const resultados = [];
-    let arquivosVistos = 0;
-
-    for (const rel of walk(projectDir, projectDir)) {
-        if (resultados.length >= maxResultados) break;
-        if (filtro && !filtro.test(rel)) continue;
-        arquivosVistos++;
-
-        let buf;
-        try { buf = fs.readFileSync(path.join(projectDir, rel)); } catch { continue; }
-        if (buf.length > 2 * 1024 * 1024 || pareceBinario(buf)) continue;
-
-        const linhas = buf.toString('utf-8').split('\n');
-        for (let i = 0; i < linhas.length && resultados.length < maxResultados; i++) {
-            if (!re.test(linhas[i])) continue;
-            const de = Math.max(0, i - contexto);
-            const ate = Math.min(linhas.length - 1, i + contexto);
-            const trecho = [];
-            for (let j = de; j <= ate; j++) trecho.push(`${j + 1}${j === i ? ':' : '-'}${linhas[j]}`.slice(0, 300));
-            resultados.push({ arquivo: rel, linha: i + 1, trecho: trecho.join('\n') });
-        }
-    }
-
-    return { ok: true, arquivosVistos, total: resultados.length, resultados, truncado: resultados.length >= maxResultados };
-}
-
-/* ── O SHELL DO AGENTE NASCE SEM SEGREDO ──────────────────────────────────
-   Antes, o run_shell herdava o process.env inteiro: o agente rodava `env` e
-   lia o NPM_TOKEN, a chave da Anthropic, o GH_TOKEN de quem usa — e o que o
-   agente lê pode ir parar no modelo, num arquivo ou numa página (prompt
-   injection). Peça 3 do OpenBot (comum/desmontados/copilotkit-openbot.md):
-   o shell do agente não herda o ambiente do processo pai.
-
-   Filtro por NOME, não lista do que passa: PATH, HOME, LANG, TERM, SHELL,
-   USER, NODE_*, nvm etc. continuam — sem eles `npm`, `node` e `git` quebram.
-   Na dúvida o nome sai: um token a mais escondido custa pouco, um a menos
-   vaza. Só o caminho do agente (execute → run_shell) é filtrado; os usos
-   internos (abrir terminal, desinstalar) seguem com o ambiente inteiro.
-   O SSH_AUTH_SOCK também sai (review do Arthur, #162): com ele o agente usa o
-   ssh-agent da pessoa (`git push`, `ssh host`) sem ler ~/.ssh. Volta só com
-   `/sandbox ssh on`. */
-const NOME_SECRETO = /(TOKEN|SECRET|KEY|PASSWORD|PASSWD|CREDENTIAL|AUTH|COOKIE|SESSION)/i;
-const PREFIXO_SECRETO = /^(AWS_|OPENAI_|ANTHROPIC_|GEMINI_|GOOGLE_API|GROQ_|OPENROUTER_|AZURE_|HF_|HUGGING)/i;
-const SEMPRE_PASSA = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'TERM', 'TMPDIR', 'PWD']);
-
-function ambienteLimpo(env = process.env, permitidas = []) {
-    const limpo = {};
-    for (const [nome, valor] of Object.entries(env)) {
-        if (valor === undefined) continue;
-        if (!SEMPRE_PASSA.has(nome) && !permitidas.includes(nome) && (NOME_SECRETO.test(nome) || PREFIXO_SECRETO.test(nome))) continue;
-        limpo[nome] = valor;
-    }
-    return limpo;
-}
-
-function permitidasNoShell(cfg = sandbox.config()) {
-    return cfg.ssh_agent ? [...cfg.env_permitidas, 'SSH_AUTH_SOCK'] : cfg.env_permitidas;
-}
-
-async function runShell(command, timeout = 60000, cwd, env) {
-    return new Promise((resolve) => {
-        exec(command, { timeout, cwd: cwd || process.cwd(), maxBuffer: 10 * 1024 * 1024, env: env || process.env }, (error, stdout, stderr) => {
-            if (error) resolve({ ok: false, code: error.code ?? 1, stdout, stderr, killed: error.killed });
-            else resolve({ ok: true, code: 0, stdout, stderr });
-        });
-    });
-}
-
-// `target` vem do modelo (args.target) — que por sua vez pode ter lido de uma
-// página não confiável (prompt injection via pesquisar_referencia/browser_read).
-// 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).
-function openInBrowser(target) {
-    if (process.env.PRIMOCODE_SEM_NAVEGADOR === '1') return Promise.resolve({ ok: false, error: 'o navegador está bloqueado no modo voz: só abre quando a pessoa clica' });   // app do Primo (voz): navegador só com clique explícito
-    const p = os.platform();
-    const [cmd, args, opener] = p === 'darwin' ? ['open', [target], 'open']
-        : p === 'win32' ? ['cmd.exe', ['/c', 'start', '', target], 'start']
-        : ['xdg-open', [target], 'xdg-open'];
-    return new Promise((resolve) => {
-        execFile(cmd, args, { timeout: 10000 }, (error, stdout, stderr) => {
-            resolve(error ? { ok: false, error: (stderr || error.message || '').toString() } : { ok: true, opener });
-        });
-    });
-}
-
-async function runInNewTerminal(command, cwd) {
-    const p = os.platform();
-    const pastaAlvo = cwd || '.';
-    // pastaAlvo normalmente é a pasta do projeto, mas pode vir de input do
-    // modelo — sem checar, um valor malicioso quebra pra fora do "cd" embutido
-    // no comando que abre o terminal (AppleScript/cmd/x-terminal-emulator),
-    // que reinterpreta a string inteira como shell (achado de segurança).
-    // Recusa em vez de tentar escapar certo em três dialetos de shell ao
-    // 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).
-    /* 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;
-    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. */
-        /* Sem shell no meio: o script vai como UM argumento do osascript
-           (execFile), e dentro dele a string do AppleScript é escapada (\\ e
-           \"). Antes o comando entrava cru entre aspas duplas dentro de aspas
-           simples — `node server.js --name="x"` quebrava o AppleScript. A
-           pasta vai entre aspas simples para o shell do Terminal (a aspa
-           simples está barrada acima). */
-        const doTerminal = `cd '${pastaAlvo}' && ${command}`;
-        const script = `tell application "Terminal" to do script "${doTerminal.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-        return new Promise((resolve) => {
-            execFile('osascript', ['-e', script], { timeout: 60000 }, (erro, _o, stderr) => {
-                resolve(erro ? { ok: false, error: String(stderr || erro.message).trim() || 'falhou' } : { ok: true, opener: 'osascript' });
-            });
-        });
-    } 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. */
-        // A aspa simples do comando fecharia o `bash -c '…'`: vira '\''.
-        cmd = `x-terminal-emulator -e "bash -c '${String(command).replace(/'/g, "'\\''")}; 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' };
-}
-
-// Quando o old_string não bate, mostra as linhas do arquivo mais parecidas —
-// com número — para o modelo copiar o texto certo em vez de chutar de novo.
-function trechosParecidos(conteudo, alvo, quantas = 8) {
-    const termos = alvo
-        .split(/[\s{}();,=]+/)
-        .map((t) => t.trim().toLowerCase())
-        .filter((t) => t.length > 2);
-    if (!termos.length) return conteudo.split('\n').slice(0, quantas).map((l, i) => `${i + 1}\t${l}`);
-
-    const linhas = conteudo.split('\n');
-    const pontuadas = linhas.map((linha, i) => {
-        const baixa = linha.toLowerCase();
-        let pontos = 0;
-        for (const t of termos) if (baixa.includes(t)) pontos++;
-        return { i, linha, pontos };
-    }).filter((x) => x.pontos > 0);
-
-    pontuadas.sort((a, b) => b.pontos - a.pontos || a.i - b.i);
-    return pontuadas
-        .slice(0, quantas)
-        .sort((a, b) => a.i - b.i)
-        .map((x) => `${x.i + 1}\t${x.linha.slice(0, 200)}`);
-}
-
-// Edição cirúrgica: troca um trecho exato em vez de reescrever o arquivo.
-// É o que impede o agente de reescrever 800 linhas para mudar uma.
-/* ── O ARQUIVO MUDOU DESDE QUE O AGENTE LEU ──────────────────────────────
- * O agente lê, pensa, e edita em cima do que leu. Se a pessoa (ou o servidor de dev, ou outro agente)
- * mexeu no arquivo no meio, a edição apagava o trabalho dela sem aviso. Guardamos a impressão (sha1)
- * do que o agente viu por último — na leitura e nas próprias escritas — e recusamos editar por cima
- * de uma versão que ele não viu. Arquivo nunca lido aqui passa (o old_string já confere o trecho). */
-const crypto = require('crypto');
-const VISTOS = new Map();
-const impressao = (texto) => crypto.createHash('sha1').update(texto).digest('hex');
-const marcarVisto = (filePath, texto) => { VISTOS.set(filePath, impressao(texto)); };
-function mudouPorFora(filePath, atual) {
-    const visto = VISTOS.get(filePath);
-    if (!visto || visto === impressao(atual)) return null;
-    return { ok: false, error: 'O arquivo mudou desde a última vez que você leu (alguém editou por fora). Nada foi escrito.',
-        comoResolver: `leia de novo com read_file("${path.basename(filePath)}") e refaça a edição em cima do que está lá agora.` };
-}
-
-function editFile({ path: rawPath, old_string, new_string, replace_all }, projectDir) {
-    const filePath = resolveInProject(rawPath, projectDir);
-    if (!fs.existsSync(filePath)) return { ok: false, error: `Arquivo não existe: ${rawPath}` };
-    if (typeof old_string !== 'string' || !old_string) return { ok: false, error: 'old_string é obrigatório' };
-    if (old_string === new_string) return { ok: false, error: 'old_string e new_string são iguais' };
-
-    const original = fs.readFileSync(filePath, 'utf-8');
-    const mudou = mudouPorFora(filePath, original);
-    if (mudou) return mudou;
-    const ocorrencias = original.split(old_string).length - 1;
-
-    // Não bateu letra por letra: o casador frouxo (lib/casar.js) acha o
-    // trecho com o espaço, a indentação ou o número de linha errados — desde
-    // que seja UM lugar só. Poupa a volta "não achei → relê → edita de novo".
-    let casado = null;
-    if (ocorrencias === 0) {
-        const r = casar.achar(original, old_string);
-        if (r.erro === 'varios') {
-            return { ok: false, error: `Trecho aparece ${r.vezes} vezes (${r.como}). Inclua mais linhas em volta para ficar único.` };
-        }
-        if (!r.erro) casado = r;
-    }
-
-    if (ocorrencias === 0 && !casado) {
-        // Erro seco faz o modelo chutar de novo. Devolvendo o que EXISTE no
-        // arquivo, ele acerta na segunda tentativa.
-        return {
-            ok: false,
-            error: 'Trecho não encontrado — o arquivo não contém esse texto exato.',
-            comoCorrigir: 'Copie o old_string LITERALMENTE de "trechosParecidos" abaixo, com a mesma indentação.',
-            trechosParecidos: trechosParecidos(original, old_string),
-        };
-    }
-    if (ocorrencias > 1 && !replace_all) {
-        return { ok: false, error: `Trecho aparece ${ocorrencias} vezes. Inclua mais linhas em volta para ficar único, ou use replace_all.` };
-    }
-
-    const atualizado = casado
-        ? original.slice(0, casado.inicio) + (new_string ?? '') + original.slice(casado.fim)
-        : replace_all
-            ? original.split(old_string).join(new_string ?? '')
-            : original.replace(old_string, () => new_string ?? '');
-
-    fs.writeFileSync(filePath, atualizado, 'utf-8');
-    marcarVisto(filePath, atualizado);
-    return {
-        ok: true,
-        path: path.relative(projectDir, filePath).replace(/\\/g, '/'),
-        substituicoes: replace_all && !casado ? ocorrencias : 1,
-        casouPor: casado ? casado.como : undefined,
-        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,
-    };
-}
-
-/* O que volta ao modelo passa por um teto de ~6 mil caracteres de JSON (summarizeForModel, lib/act.js).
-   Antes a leitura devolvia até 40 mil e o teto cortava calado: o modelo via ~90 linhas de um arquivo de 600,
-   com "truncado: false", e editava às cegas o resto. Agora a leitura cabe no teto e diz até onde veio. */
-const TETO_LEITURA = 5000;
-function recortar(todas, inicio, maxLinhas) {
-    const linhas = [];
-    let tam = 0;
-    for (let i = inicio; i < todas.length && linhas.length < maxLinhas; i++) {
-        const l = `${i + 1}\t${todas[i]}`;
-        const t = JSON.stringify(l).length - 1;   // o custo dela dentro do JSON (aspas, \n escapado)
-        if (linhas.length && tam + t > TETO_LEITURA) break;
-        linhas.push(l.length > TETO_LEITURA ? l.slice(0, TETO_LEITURA) + '…(linha cortada)' : l);
-        tam += t;
-    }
-    return { content: linhas.join('\n'), de: inicio + 1, ate: inicio + linhas.length };
-}
-
-function readFile({ path: rawPath, offset, limit }, projectDir) {
-    const filePath = resolverParaLer(rawPath, projectDir);
-    const bruto = fs.readFileSync(filePath, 'utf-8');
-    marcarVisto(filePath, bruto);
-    const todas = bruto.split('\n');
-
-    // Cabe inteiro: vem inteiro, do jeito que está.
-    if (offset == null && limit == null && JSON.stringify(bruto).length <= TETO_LEITURA) {
-        return { ok: true, content: bruto, linhas: todas.length, bytes: bruto.length, truncado: false };
-    }
-
-    /* Arquivo pequeno vem INTEIRO, mesmo pedido aos pedaços: o modelo lia um
-       app.js de 393 linhas de 50 em 50, cada pedaço uma ida ao servidor
-       (teste da loja, 01/10). Inteiro, uma vez, custa menos — se couber. */
-    const inteiro = recortar(todas, 0, todas.length);
-    if (inteiro.ate === todas.length) {
-        return { ok: true, content: inteiro.content, linhas: todas.length, bytes: bruto.length, inteiro: true,
-            dica: 'veio inteiro, com o número das linhas — não precisa ler de novo' };
-    }
-    const inicio = Math.min(Math.max(0, (offset || 1) - 1), Math.max(0, todas.length - 1));
-    const pedido = Math.max(1, Number(limit) || 200);
-    const r = recortar(todas, inicio, pedido);
-    const resto = r.ate < todas.length;
-    return {
-        ok: true, content: r.content, linhas: todas.length, de: r.de, ate: r.ate, bytes: bruto.length,
-        truncado: resto,
-        ...(resto ? { proximoOffset: r.ate + 1, dica: `vieram as linhas ${r.de}–${r.ate} de ${todas.length} (o teto de uma leitura). Continue com read_file offset=${r.ate + 1}, ou use grep pra achar o trecho.` } : {}),
-    };
-}
-
-// ── multi_edit: várias trocas no mesmo arquivo, em ordem, tudo-ou-nada ────
-function multiEdit({ path: rawPath, edits }, projectDir) {
-    const filePath = resolveInProject(rawPath, projectDir);
-    if (!fs.existsSync(filePath)) return { ok: false, error: `Arquivo não existe: ${rawPath}` };
-    if (!Array.isArray(edits) || !edits.length) return { ok: false, error: 'edits (lista) é obrigatório' };
-
-    let conteudo = fs.readFileSync(filePath, 'utf-8');
-    const mudou = mudouPorFora(filePath, conteudo);
-    if (mudou) return mudou;
-    const original = conteudo;
-    const linhasAntes = conteudo.split('\n').length;
-    let substituicoes = 0;
-
-    for (let i = 0; i < edits.length; i++) {
-        const { old_string, new_string, replace_all } = edits[i] || {};
-        if (typeof old_string !== 'string' || !old_string) return { ok: false, error: `edit ${i + 1}: old_string é obrigatório` };
-        if (old_string === new_string) return { ok: false, error: `edit ${i + 1}: old_string e new_string são iguais` };
-        const ocorrencias = conteudo.split(old_string).length - 1;
-        if (ocorrencias === 0) {
-            const r = casar.achar(conteudo, old_string);
-            if (r.erro === 'varios') {
-                return { ok: false, error: `edit ${i + 1}: trecho aparece ${r.vezes}x (${r.como}) — inclua mais contexto para torná-lo único` };
-            }
-            if (r.erro) {
-                return { ok: false, error: `edit ${i + 1}: trecho não encontrado`, trechosParecidos: trechosParecidos(conteudo, old_string) };
-            }
-            conteudo = conteudo.slice(0, r.inicio) + (new_string ?? '') + conteudo.slice(r.fim);
-            substituicoes++;
-            continue;
-        }
-        if (ocorrencias > 1 && !replace_all) {
-            return { ok: false, error: `edit ${i + 1}: trecho aparece ${ocorrencias}x — use replace_all ou inclua mais contexto para torná-lo único` };
-        }
-        conteudo = replace_all ? conteudo.split(old_string).join(new_string ?? '') : conteudo.replace(old_string, () => new_string ?? '');
-        substituicoes++;
-    }
-
-    fs.writeFileSync(filePath, conteudo, 'utf-8');
-    marcarVisto(filePath, conteudo);
-    return {
-        ok: true,
-        path: path.relative(projectDir, filePath).replace(/\\/g, '/'),
-        substituicoes,
-        linhasAntes,
-        linhasDepois: conteudo.split('\n').length,
-        _antes: original,
-        _depois: conteudo,
-    };
-}
-
-// ── write_todos: lista de tarefas da sessão (estilo Claude Code) ──────────
-// Só estado + exibição — não chama nada externo. O agente planeja em voz alta
-// e o usuário acompanha o progresso.
-let TODOS = [];
-function writeTodos({ todos }) {
-    if (!Array.isArray(todos)) return { ok: false, error: 'todos (lista) é obrigatório' };
-    const status = new Set(['pending', 'in_progress', 'completed']);
-    TODOS = todos.map((t) => ({
-        content: String((t && (t.content || t.task || t.text)) || '').trim(),
-        status: status.has(t && t.status) ? t.status : 'pending',
-    })).filter((t) => t.content);
-    const feitos = TODOS.filter((t) => t.status === 'completed').length;
-    return { ok: true, todos: TODOS, total: TODOS.length, feitos };
-}
-function getTodos() { return TODOS; }
-
-/**
- * Executa uma ferramenta e NUNCA lança.
- *
- * O `await` aqui não é enfeite. O despachante abaixo faz `return browser.x(...)`
- * em vinte casos, e `try { return promessa } catch` **não** pega a rejeição dessa
- * promessa — só `return await` pega. Sem isto, qualquer falha de navegador ou
- * desktop subia por cima do loop do agente e derrubava o CLI inteiro com exit 1,
- * em vez de virar uma ação falhada que o modelo pode corrigir.
- *
- * Foi exatamente o que acontecia ao pedir uma pesquisa no Google: o seletor não
- * batia, a promessa rejeitava, e o programa morria calado no meio da tarefa.
- */
-async function execute(name, args, ctx) {
-    try {
-        return await despachar(name, args, ctx);
-    } catch (e) {
-        // Erro que sabe o que EXISTE leva a informação junto — mesma ideia do
-        // `trechosParecidos` do edit_file. Erro seco faz o modelo chutar de novo.
-        if (e && Array.isArray(e.candidatos) && e.candidatos.length) {
-            return {
-                ok: false,
-                error: e.message,
-                seletoresDisponiveis: e.candidatos,
-                comoCorrigir: 'Chame a tool de novo com um seletor de "seletoresDisponiveis", copiado LITERALMENTE. O primeiro da lista é o mais provável.',
-            };
-        }
-        return { ok: false, error: e.message || String(e) };
-    }
-}
-
-async function despachar(name, args, ctx) {
-    const projectDir = (ctx && ctx.projectDir) || process.cwd();
-    args = args || {};
-
-    {
-        switch (name) {
-            case 'write_file': {
-                // O modelo grátis manda o caminho com outro nome (file_path, caminho) ou nenhum,
-                // e o write caía na própria pasta: EISDIR, e ele tentava de novo igual (14/10).
-                if (!args.path) args.path = args.file_path || args.filePath || args.caminho || args.arquivo || args.file || '';
-                if (!String(args.path).trim()) {
-                    return { ok: false, error: 'faltou o caminho do arquivo em "path".', comoResolver: 'chame write_file de novo com path:"pasta/nome.ext" e content.' };
-                }
-                // Vídeo e áudio NÃO se escrevem com write_file. Num pedido
-                // real o agente criou um "video.mp4" de 43 bytes de texto e
-                // disse "vídeo criado com sucesso" — um arquivo falso, morto,
-                // entregue como resultado. O caminho certo existe e é dele:
-                // o Studio.
-                if (/\.(mp4|mov|avi|mkv|webm|mp3|wav|ogg|m4a|flac)$/i.test(String(args.path || ''))) {
-                    return {
-                        ok: false,
-                        error: `"${args.path}" é arquivo de vídeo/áudio, e write_file só escreve TEXTO — isso criaria um arquivo falso que não abre. `
-                            + 'Vídeo se faz no Estúdio: estudio_projeto (criar) → planejar_producao → estudio_plano → '
-                            + 'estudio_render. O render devolve o CAMINHO do arquivo — é esse o vídeo. '
-                            + 'Não monte vídeo com ffmpeg à mão.',
-                    };
-                }
-                const filePath = resolveInProject(args.path, projectDir);
-                const content = args.content || '';
-                try {
-                    if (fs.statSync(filePath).isDirectory()) {
-                        return { ok: false, error: `"${args.path}" é uma PASTA, não um arquivo.`, comoResolver: `ponha o nome do arquivo no fim: path:"${String(args.path).replace(/\/+$/, '')}/index.html" (ou o nome que for).` };
-                    }
-                } catch { /* não existe: vai ser criado */ }
-                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 = ''; } }
-                if (!created) { const mudou = mudouPorFora(filePath, antes); if (mudou) return mudou; }
-                fs.mkdirSync(path.dirname(filePath), { recursive: true });
-                fs.writeFileSync(filePath, content, 'utf-8');
-                marcarVisto(filePath, content);
-                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);
-            case 'read_file':
-                return readFile(args, projectDir);
-            case 'list_dir': {
-                /* No máximo 60 linhas (13/10: "continua listando coisas desnecessárias").
-                   Pasta grande listada inteira enche a conversa e não diz onde está o que importa. */
-                const arvore = String(treeDir(resolverParaLer(args.path, projectDir), args.depth || 2));
-                const ls = arvore.split('\n');
-                if (ls.length <= 60) return { ok: true, tree: arvore };
-                return { ok: true, tree: ls.slice(0, 60).join('\n'), cortado: ls.length - 60,
-                    dica: 'Lista grande, cortei. Não liste de novo: use glob com o padrão do que procura (ex.: "src/**/*.css") ou grep pelo nome.' };
-            }
-            /* `pasta` (opcional): procurar numa pasta que o usuário citou, sem
-               trocar a de trabalho. Os caminhos voltam relativos a ELA, e a
-               resposta diz qual é. */
-            case 'glob': {
-                const b = raizDaBusca(args.pattern || '**/*', args.pasta, projectDir);
-                const arquivos = globFiles(b.padrao || '**/*', b.raiz);
-                return { ok: true, total: arquivos.length, arquivos: arquivos.slice(0, 200), ...(b.outra ? { pasta: b.raiz } : {}) };
-            }
-            case 'grep': {
-                const b = raizDaBusca(args.glob, args.pasta, projectDir);
-                const r = grepFiles({ ...args, glob: b.padrao }, b.raiz);
-                return b.outra && r && r.ok !== false ? { ...r, pasta: b.raiz } : r;
-            }
-            case 'run_shell': {
-                /* `primocode kit …` (lib/kits.js) roda aqui dentro: a tela de gosto e a de referências abrem
-                   deste processo (no app, pela linha de protocolo do stderr dele), e o render fala no terminal. */
-                const kit = await require('./kits.js').doShell(args.command, { projectDir,
-                    abrirVideo: process.stdout.isTTY && process.env.PRIMOCODE_APP !== '1' ? (arq) => { try { openInBrowser(arq); } catch { /* sem navegador */ } } : null,
-                    aoFalar: (t) => { try { process.stdout.write(require('./ui.js').c.muted(`  ⎿ ${t}`) + '\n'); } catch { /* sem terminal */ } } });
-                if (kit) return kit;
-                // Dentro da cerca (lib/sandbox.js); desligada ou sem mecanismo cai no exec de sempre.
-                const prazo = Number(args.timeout_ms) || 60000;
-                const r = await sandbox.executar(args.command, { projectDir, timeout: prazo,
-                    env: ambienteLimpo(process.env, permitidasNoShell()) });
-                // morto pelo prazo: sem isto parecia um erro do código ("code 1", saída vazia) e o modelo "consertava" o que não quebrou
-                if (r && r.ok === false && r.killed) {
-                    const quanto = prazo >= 1000 ? `${String(+(prazo / 1000).toFixed(1)).replace('.', ',')} s` : `${prazo} ms`;
-                    return { ...r, error: `passou do prazo de ${quanto} e foi parado (não é erro do código). Comando longo (build, install, servidor, testes lentos): rode com run_background e leia com background_output, ou passe timeout_ms maior.` };
-                }
-                return r;
-            }
-            case 'run_in_new_terminal':
-                return runInNewTerminal(args.command, args.cwd || projectDir);
-            /* Em segundo plano, com a saída legível (lib/fundo.js). Mesmo env
-               filtrado do run_shell: o servidor de dev não herda as chaves. */
-            case 'run_background':
-                return require('./fundo').iniciar(args.command, { projectDir,
-                    env: ambienteLimpo(process.env, permitidasNoShell()) });
-            case 'background_output':
-                return require('./fundo').saida(args.id, { desde: args.desde });
-            case 'stop_background':
-                return require('./fundo').parar(args.id);
-            case 'open_in_browser': {
-                const alvo = /^https?:\/\//i.test(args.target || '')
-                    ? args.target
-                    : resolveInProject(args.target, projectDir);
-                /* Site da web abre À VISTA no Chrome controlado (o cursor vai na
-                   barra e digita). Arquivo do projeto continua no navegador padrão. */
-                if (/^https?:/i.test(alvo) && process.env.PRIMOCODE_BROWSER_HEADLESS !== '1' && require('./cursor').disponivel()) {
-                    try {
-                        const r = await browser.abrirVisivel(alvo);
-                        if (r && r.ok !== false) return { ok: true, opener: 'chrome à vista', url: r.url, pagina: await browser.retrato(40), comoUsar: snapshot.COMO_USAR };
-                    } catch { /* cai no navegador padrão */ }
-                }
-                return openInBrowser(alvo);
-            }
-            case 'multi_edit':
-                return multiEdit(args, projectDir);
-            case 'write_todos':
-                return writeTodos(args);
-
-            // Pesquisa de referência: abre documentação e exemplos sobre o
-            // pedido e devolve o TEXTO para o modelo aprender antes de
-            // escrever. Aparece no terminal, com as fontes — nada oculto.
-            case 'pesquisar_referencia': {
-                const r = await referencia.pesquisar({
-                    consulta: args.consulta || args.query || '',
-                    paginas: Math.max(1, Math.min(5, Number(args.paginas) || 3)),
-                });
-                // Escopo fechado ("só do site x.com"): o buscador devolve o mundo; aqui só passa o site.
-                return require('./estudio/referencias.js').filtrar(r);
-            }
-
-            // 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.
-            case 'remember_general': {
-                const entry = String(args.fato || args.entry || '').trim();
-                if (!entry) return { ok: false, error: 'Diga o que lembrar (fato).' };
-                cfg.appendGeneralMemory(entry);
-                return { ok: true, gravado: entry };
-            }
-
-            // A memória que dura entre sessões (lib/memoria-usuario.js).
-            case 'lembrar': {
-                const mem = require('./memoria-usuario.js');
-                const acao = String(args.acao || 'salvar').toLowerCase();
-                if (acao === 'apagar') return mem.apagar(args.nome);
-                if (acao === 'salvar') return mem.salvar({ nome: args.nome, descricao: args.descricao, tipo: args.tipo, texto: args.texto });
-                return { ok: false, error: 'Ação inválida. Use "salvar" ou "apagar".' };
-            }
-
-            // ── MCP: o serviço pela API dele, antes do mouse (lib/mcp.js) ──
-            case 'mcp_procurar':
-                return require('./mcp.js').procurar(args.busca || args.query || args.servico || '');
-            // Roda código de terceiro: o portão (lib/perigo.js) pergunta antes de chegar aqui.
-            case 'mcp_conectar':
-                return require('./mcp.js').conectarNovo({ nome: args.nome, command: args.comando || args.command, args: args.args, env: args.env });
-            case 'mcp_usar':
-                return require('./mcp.js').usar(args.servidor, args.ferramenta, args.argumentos || args.arguments || {}, projectDir);
-
-            // ── Navegador controlado (CDP) — o agente age numa página real ──
-            /* O navegador fala em REFS (lib/snapshot.js): abrir e clicar já
-               devolvem o retrato da página com "@e3 [button] Entrar", e o
-               selector aceita "@e3". Uma leitura a menos por passo, e nenhum
-               seletor CSS chutado. */
-            case 'browser_open': {
-                const alvo = /^https?:\/\//i.test(args.url || '')
-                    ? args.url
-                    : 'file://' + resolveInProject(args.url, projectDir);
-                // Endereço da web abre À VISTA: o cursor vai na barra e digita (browser.abrirVisivel).
-                const r = /^https?:/i.test(alvo) ? await browser.abrirVisivel(alvo) : await browser.open(alvo);
-                return r && r.ok !== false ? { ...r, pagina: await browser.retrato(40), comoUsar: snapshot.COMO_USAR } : r;
-            }
-            case 'browser_click': {
-                let r;
-                if (args.selector || snapshot.ehRef(args.text)) r = await browser.clickSelector(snapshot.seletorDaRef(args.selector || args.text));
-                else if (args.text) r = await browser.clickText(args.text);
-                else if (args.x != null && args.y != null) r = await browser.click(args.x, args.y);
-                else return { ok: false, error: 'browser_click precisa de selector (ou a ref "@e3"), text ou x/y' };
-                // O clique quase sempre muda a página: o retrato novo vai junto.
-                await new Promise((ok) => setTimeout(ok, 500));
-                return r && r.ok !== false ? { ...r, pagina: await browser.retrato(40) } : r;
-            }
-            case 'browser_type':
-                if (args.selector) return browser.typeInSelector(snapshot.seletorDaRef(args.selector), args.text || '', args.clear !== false);
-                return browser.type(args.text || '');
-            case 'browser_key':
-                return browser.key(args.key);
-            case 'browser_read': {
-                if (!args.selector) {
-                    const pagina = await browser.retrato(80);
-                    const texto = await browser.evaluate('(function(){return document.body?document.body.innerText.slice(0,2500):null;})()');
-                    if (!pagina && texto == null) return { ok: false, error: 'nada na página — ela pode não ter carregado' };
-                    return { ok: true, pagina, text: texto || '', comoUsar: snapshot.COMO_USAR };
-                }
-                const sel = `document.querySelector(${JSON.stringify(snapshot.seletorDaRef(args.selector))})`;
-                const texto = await browser.evaluate(`(function(){const e=${sel};return e?e.innerText.slice(0,6000):null;})()`);
-                return texto == null ? { ok: false, error: 'nada na página (ou seletor não encontrado)' } : { ok: true, text: texto };
-            }
-            case 'browser_screenshot':
-                // Sem path, cai num nome-padrão — mas SEMPRE dentro do projeto: sem
-                // isso o arquivo ia para o cwd real do processo, não para a pasta
-                // virtual que o CLI mostra ao usuário (o processo nunca faz chdir).
-                return browser.screenshot(resolveInProject(args.path || `screenshot-${Date.now()}.png`, projectDir));
-            case 'browser_scroll':
-                return browser.scroll(args.dy != null ? args.dy : 600);
-            case 'browser_wait':
-                return browser.waitFor(snapshot.seletorDaRef(args.selector), args.timeout_ms || 15000);
-            case 'browser_eval':
-                return { ok: true, value: await browser.evaluate(args.js || 'null') };
-
-            // ── Desktop físico — mouse, teclado e tela do usuário ───────────
-            case 'desktop_screenshot':
-                // Mesmo motivo do browser_screenshot: nome-padrão também precisa
-                // resolver dentro do projeto, não do cwd real do processo.
-                return desktop.screenshot(resolveInProject(args.path || `desktop-${Date.now()}.png`, projectDir));
-            case 'desktop_click':
-                return clicarPeloCursor(args.x, args.y, { botao: args.button || 'left', rotulo: 'clicando' });
-            case 'desktop_move': {
-                const [x, y] = [numero(args.x), numero(args.y)];
-                if (x == null || y == null) return { ok: false, error: `Coordenada inválida: x=${args.x}, y=${args.y}` };
-                return peloCursor('mover', { x, y }, () => desktop.move(x, y));
-            }
-            case 'desktop_drag': {
-                const c4 = [args.from_x, args.from_y, args.to_x, args.to_y].map(numero);
-                if (c4.some((v) => v == null)) return { ok: false, error: 'Coordenada inválida no drag' };
-                return peloCursor('arrastar', { x1: c4[0], y1: c4[1], x2: c4[2], y2: c4[3], rotulo: 'arrastando' },
-                    () => desktop.drag(...c4));
-            }
-            case 'desktop_type':
-                return peloCursor('digitar', { texto: args.text || '', rotulo: 'digitando' },
-                    () => desktop.type(args.text || ''));
-            case 'desktop_key': {
-                const r = await peloCursor('tecla', { combo: args.key || '', rotulo: String(args.key || '') },
-                    () => desktop.key(args.key));
-                // Tecla SOLTA que o cursor não conhece: o desktop.js sabe mais
-                // nomes. Combinação com tecla desconhecida ("cmd+xyz") NÃO cai
-                // lá: o osascript digitaria x, y e z com Command apertado —
-                // recortar e desfazer no app da frente.
-                if (!r.ok && /tecla desconhecida/.test(r.error || '') && !String(args.key || '').includes('+')) {
-                    return desktop.key(args.key);
-                }
-                return r;
-            }
-            case 'desktop_scroll':
-                return peloCursor('rolar', { dy: args.dy != null ? Number(args.dy) : 300, rotulo: 'rolando' },
-                    () => desktop.scroll(args.dy != null ? args.dy : 300));
-            case 'desktop_size': {
-                // No Mac, em PONTOS — a mesma unidade dos cliques e das posições
-                // dos botões. O system_profiler dava pixels físicos (2880 num
-                // Retina de 1440), e o clique caía no lugar errado.
-                if (cursor.disponivel()) {
-                    const t = await cursor.mandar('tamanho');
-                    if (t.ok) return { ok: true, width: t.largura, height: t.altura, unidade: 'pontos' };
-                }
-                return desktop.getScreenSize();
-            }
-            /* ── 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.
-             *
-             * 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, ctx);
-            case 'estudio_plano':
-                // A pasta de trabalho vai junto: o componente que a IA escreveu mora nela (index.js copia para o projeto).
-                return estudio.ferramentaPlano({ ...args, __pasta: projectDir });
-            case 'estudio_midia':
-                return estudio.ferramentaMidia(args);
-            case 'estudio_ae':
-                return estudio.ferramentaAE(args);
-            case 'estudio_motion':
-                return estudio.ferramentaMotion(args);
-            case 'estudio_editar':
-                return estudio.ferramentaEditar(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 'editor_pro':
-                // A edição completa de vídeo FALADO: o motor do EDIT IA PRO (lib/editor-pro.js, editor/).
-                return require('./editor-pro.js').ferramenta(args, ctx);
-            case 'estudio_render':
-                // A pasta de trabalho vai junto: a composição do Hyperframes que a IA escreveu mora nela.
-                return estudio.ferramentaRender({ ...args, __pasta: projectDir }, {
-                    ...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 {} },
-                });
-            case 'estudio_site':
-                return estudio.ferramentaSite(args);
-
-            case 'desktop_double_click':
-                return clicarPeloCursor(args.x, args.y, { duplo: true, rotulo: 'abrindo' });
-            case 'desktop_open_app': {
-                const app = args.app || args.name || '';
-                if (cursor.disponivel()) await cursor.mandar('rotulo', { texto: `abrindo ${app}` });
-                return desktop.openApp(app);
-            }
-            case 'desktop_windows':
-                return desktop.listWindows();
-            case 'desktop_focus':
-                return desktop.focusWindow(args.window || args.title || '');
-            case 'desktop_elements': {
-                const lidos = desktop.uiElements(args.window);
-                if (!cursor.disponivel()) return lidos;
-                // No Mac, junto dos botões da acessibilidade vão os TEXTOS
-                // que aparecem na tela (OCR), com a posição de cada um.
-                const naTela = await textosDaTela();
-                if (!naTela.ok) return lidos.ok ? { ...lidos, telaIndisponivel: naTela.error } : lidos;
-                return { ...(lidos.ok ? lidos : { ok: true, elementos: [] }),
-                    textosNaTela: naTela.elementos.slice(0, 120).map((e) => ({ texto: e.nome, x: e.x, y: e.y })) };
-            }
-            case 'desktop_click_element': {
-                if (!cursor.disponivel()) {
-                    return desktop.clickElement(args.name || args.text || '', {
-                        window: args.window, double: !!args.double, button: args.button,
-                    });
-                }
-                // Mesma escolha do desktop.clickElement, mas o clique vai pelo
-                // cursor: a pessoa vê a seta ir até o botão pelo nome.
-                const pedido = String(args.name || args.text || '').trim();
-                if (!pedido) return { ok: false, error: 'Diga o nome do elemento (o texto do botão, ícone ou campo).' };
-                const lidos = desktop.uiElements(args.window);
-                let alvo = lidos.ok ? desktop.escolherElemento(lidos.elementos, pedido) : null;
-                /* A acessibilidade não achou (ou o app não expõe botões): procura
-                   o TEXTO na tela, pelo OCR do cursor. É o que faz "clica em
-                   Salvar" funcionar em qualquer app, como no Jarvis. */
-                let naTela = null;
-                if (!alvo) {
-                    naTela = await textosDaTela();
-                    if (naTela.ok) alvo = desktop.escolherElemento(naTela.elementos, pedido);
-                }
-                if (!alvo) {
-                    return { ok: false,
-                        error: `Nenhum elemento parecido com "${pedido}"${lidos.ok ? ` na janela "${lidos.janela}"` : ''}, nem como texto na tela.`,
-                        elementosDisponiveis: [...(lidos.ok ? lidos.elementos : []), ...((naTela && naTela.ok) ? naTela.elementos : [])]
-                            .slice(0, 50).map((e) => e.nome),
-                        ...(naTela && !naTela.ok ? { telaIndisponivel: naTela.error } : {}),
-                        comoCorrigir: 'Chame de novo com um nome de "elementosDisponiveis", copiado literalmente.' };
-                }
-                const r = await clicarPeloCursor(alvo.x, alvo.y, {
-                    botao: args.button || 'left', duplo: !!args.double, rotulo: `clicando em ${alvo.nome}`.slice(0, 44),
-                });
-                if (!r.ok) return r;
-                return { ok: true, clicado: alvo.nome, tipo: alvo.tipo, x: alvo.x, y: alvo.y, duplo: !!args.double };
-            }
-
-            default:
-                /* 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. */
-                {
-                    /* O CASO QUE ACONTECE DE VERDADE tem nome: o servidor
-                       está desatualizado e continua oferecendo o Estúdio
-                       antigo (studio_criar, studio_spec…). Visto ao vivo, e a
-                       reação do modelo foi a pior possível: chutou nomes de
-                       outro produto (`repo_browser.read_file`), tentou
-                       escrever um .mp4 com write_file, e desistiu com "parei
-                       sem concluir" — sem nunca dizer ao usuário qual era o
-                       problema.
-
-                       Então a resposta separa os dois casos. Para o Estúdio
-                       velho ela EXPLICA o que houve e manda diagnosticar em
-                       voz alta se as novas não estiverem na lista dele: um
-                       "o servidor está desatualizado" é acionável; um "parei
-                       sem concluir" não é. */
-                    const velhoEstudio = /^studio_/.test(String(name));
-                    return {
-                        ok: false,
-                        error: `A ferramenta "${name}" não existe.`,
-                        parecidas: catalogo.parecidasCom(name),
-                        comoResolver: velhoEstudio
-                            ? 'O Estúdio foi TROCADO: studio_* não existe mais. As ferramentas de hoje são '
-                              + 'planejar_producao, estudio_projeto, estudio_plano, estudio_midia, estudio_ae, estudio_motion, estudio_editar, estudio_narrar, '
-                              + 'estudio_video, estudio_render e estudio_site. Use-as. '
-                              + 'Se ELAS não estiverem na sua lista de ferramentas, o servidor está desatualizado: '
-                              + 'PARE de tentar outros nomes e diga isso ao usuário em uma frase — é o que ele '
-                              + 'precisa saber para resolver.'
-                            : '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 tente variações — se '
-                              + 'nenhuma servir, diga ao usuário o que faltou, em vez de desistir calado.',
-                    };
-                }
-        }
-    }
-}
-
-async function uninstall() {
-    const configDir = path.join(os.homedir(), '.primocode');
-    console.log('Removendo PrimoCode…');
-    try {
-        if (fs.existsSync(configDir)) {
-            fs.rmSync(configDir, { recursive: true, force: true });
-            console.log('   configurações removidas');
-        }
-    } catch (e) {
-        console.log('   não consegui remover as configurações:', e.message);
-    }
-    const r = await runShell('npm uninstall -g primocode');
-    console.log(r.ok ? '   pacote global removido' : '   remova com: npm uninstall -g primocode');
-    console.log('\nSeus projetos em ~/primocode continuam lá.');
-}
-
-module.exports = {
-    fmtBytes, treeDir, runShell, ambienteLimpo, permitidasNoShell, openInBrowser, runInNewTerminal,
-    execute, uninstall, resolveInProject, globToRegex, globFiles, grepFiles, editFile,
-    multiEdit, writeTodos, getTodos,
-    liberarLeitura, pastasDeConsulta, esquecerConsultas, resolverParaLer,
-};