primocode 11.0.0 → 11.2.0

package/lib/tool/tools.js

@@ -0,0 +1,1101 @@
+/**
+ * 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('../skill/catalogo.js');
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { exec, execFile } = require('child_process');
+const sandbox = require('../permission/sandbox.js');
+const browser = require('../browser');
+const desktop = require('../plugin/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('../tui/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('../session/snapshot');
+const casar = require('./casar');
+const estudio = require('../plugin/estudio');
+const cfg = require('../config/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/tool/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/session/runner/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 {
+        const r = await despachar(name, require('./reparar-entrada').reparar(args, require('./reparar-entrada').SCHEMAS[name]), ctx);
+        // Escreveu arquivo? O verificador mais barato da linguagem roda e o erro volta junto (lib/tool/diagnostico.js).
+        if (name === 'write_file' || name === 'edit_file' || name === 'multi_edit') {
+            return require('./diagnostico').anexar(r, (ctx && ctx.projectDir) || process.cwd());
+        }
+        return r;
+    } 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/plugin/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('../plugin/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('../tui/ui.js').c.muted(`  ⎿ ${t}`) + '\n'); } catch { /* sem terminal */ } } });
+                if (kit) return kit;
+                // Dentro da cerca (lib/permission/sandbox.js); desligada ou sem mecanismo cai no exec de sempre.
+                // em_segundo_plano: devolve um id na hora; a saída se lê com background_output e o fim chega como aviso.
+                if (args.em_segundo_plano === true || args.em_segundo_plano === 'true') {
+                    return require('../fundo').iniciar(args.command, { projectDir, env: ambienteLimpo(process.env, permitidasNoShell()) });
+                }
+                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': {
+                const r = require('../fundo').iniciar(args.command, { projectDir,
+                    env: ambienteLimpo(process.env, permitidasNoShell()) });
+                /* Servidor de dev no ar abre sozinho no navegador, com o botão de edição visual (lib/plugin/auto-preview.js). */
+                const AP = require('../plugin/auto-preview');
+                if (r && r.ok && AP.ehServidorDev(args.command) && AP.ativo(ctx)) {
+                    const p = await AP.abrirQuandoPronto(r.id, { ...ctx, projectDir, comando: args.command });
+                    if (p) return { ...r, preview: { url: p.urlAberta, edicaoVisual: p.visual, aberto: p.aberto,
+                        aviso: p.aberto ? 'O app já foi aberto no navegador da pessoa (com o botão "✎ Editar"). Não abra de novo.' : 'Não consegui abrir o navegador; diga a URL pra pessoa.' } };
+                }
+                return r;
+            }
+            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);
+            case 'agentes_buscar':
+                return require('../agentes').ferramentaBuscar(args || {});
+            case 'capacidade_buscar':
+                return require('../agentes').ferramentaCapacidade(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 'perguntar':
+                return require('./perguntar').perguntar(args, ctx);
+            case 'buscar_web':
+                return require('./web').buscarWeb(args);
+            case 'ler_url':
+                return require('./web').lerUrl(args);
+            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('../plugin/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/mcp.js) ──
+            case 'mcp_procurar':
+                return require('../mcp/mcp.js').procurar(args.busca || args.query || args.servico || '');
+            // Roda código de terceiro: o portão (lib/permission/perigo.js) pergunta antes de chegar aqui.
+            case 'mcp_conectar':
+                return require('../mcp/mcp.js').conectarNovo({ nome: args.nome, command: args.comando || args.command, args: args.args, env: args.env });
+            case 'mcp_usar':
+                return require('../mcp/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/session/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/plugin/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_criar':
+                // A porta simples: abre o projeto e chama plano, motion e render por dentro. ctx.progresso alimenta a tela.
+                return estudio.ferramentaCriar(args, {
+                    ...ctx, projectDir,
+                    abrir: (arquivo) => { try { openInBrowser(arquivo); } catch {} },
+                });
+            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/plugin/editor-pro.js, editor/).
+                return require('../plugin/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,
+};