primocode 7.2.0 → 7.4.0

package/README.md

@@ -1,16 +1,35 @@
-# PrimoCode v7.1.0
+# PrimoCode v7.4.0
 
 Agente de engenharia brasileiro para o terminal, no estilo Claude Code.
-Cria arquivos de verdade, roda comandos, abre o navegador — e lembra do que fez
-entre uma sessão e outra.
+Cria arquivos de verdade, roda comandos, **controla o navegador e o desktop** —
+e lembra do que fez entre uma sessão e outra.
 
 ```
-    ╷
-  ╭─┴─╮   PrimoCode
-  │◕ ◕│   v7.1.0
-  ╰───╯   projeto: jogo-de-carro
+    ╭◠╮
+  ╭─┴─┴─╮
+ ◖┫ ● ● ┣◗     PrimoCode  v7.4.0
+  ┃  ‿  ┃      projeto: jogo-de-carro
+  ╰──┬──╯
+   ╰─┴─╯
 ```
 
+Personalize o mascote (`primo`, `fox`, `cat`) e o nome com que ele te chama —
+veja `/mascot` e `/name`.
+
+## Por que trocar o Claude Code pelo PrimoCode
+
+| | PrimoCode | Assistentes gringos de terminal |
+|---|---|---|
+| **Idioma** | Nasceu em português do Brasil — fala como gente, não como manual traduzido | Inglês primeiro; PT-BR é tradução |
+| **Chave de API** | **Não precisa.** Instala e usa — o modelo já vem hospedado | Exige conta e chave de API própria |
+| **Controla a máquina** | Navegador (Chrome real) **e** desktop: mouse, teclado, tela | Em geral só arquivos e shell |
+| **Memória** | Cada projeto lembra o que foi feito, entre sessões | Esquece ao fechar |
+| **Instalação** | Node puro, **zero dependências** — segundos | Pacotes e dependências |
+| **Cara própria** | Mascote, nome e temas que você escolhe | Fixo |
+| **Custo** | Roda em modelos rápidos e baratos (Groq/Llama) | Cobrança por token da API |
+
+Em uma frase: **é o poder de um agente de código no terminal, em português, controlando o seu computador de verdade — sem você precisar configurar chave de API nenhuma.**
+
 ## Instalação
 
 ```bash
@@ -61,6 +80,101 @@ fim. É por isso que a IA não esquece o projeto entre sessões.
 
 Alterne com `/mode primocode` ou `/mode chat`.
 
+## Ferramentas do agente
+
+| Tool | Para quê |
+|---|---|
+| `write_file` | Cria arquivo novo ou reescreve inteiro |
+| `edit_file` | **Troca um trecho exato.** É o que evita reescrever 800 linhas pra mudar uma |
+| `multi_edit` | Várias trocas no mesmo arquivo, em ordem, tudo-ou-nada |
+| `read_file` | Lê o arquivo, com `offset`/`limit` para os grandes |
+| `glob` | Acha arquivos por padrão: `**/*.js`, `src/**/*.{ts,tsx}` |
+| `grep` | Procura texto/regex **dentro** dos arquivos, com arquivo e linha |
+| `list_dir` | Árvore de arquivos |
+| `run_shell` | Roda comando na pasta do projeto |
+| `run_in_new_terminal` | Sobe servidor de dev / watch em outro terminal |
+| `write_todos` | Plano de tarefas da sessão, visível no terminal |
+| `open_in_browser` | Abre HTML ou URL no navegador padrão |
+| `spawn_agent` | Delega uma sub-tarefa a outro agente |
+
+O `edit_file` é rigoroso de propósito: se o trecho não existe, ou aparece mais
+de uma vez sem `replace_all`, ele **recusa** e devolve as linhas reais do
+arquivo — em vez de editar o lugar errado.
+
+### Controle de navegador e desktop
+
+O agente não só abre o navegador — ele **age** nele, e no computador também.
+
+| Tool | Para quê |
+|---|---|
+| `browser_open` | Abre a página num Chrome controlado (CDP) e espera carregar |
+| `browser_click` | Clica por texto visível, seletor CSS ou coordenada |
+| `browser_type` | Digita num campo (por seletor) ou onde o foco estiver |
+| `browser_key` | Enter, Tab, Escape, setas… |
+| `browser_read` | Lê o texto visível da página (conferir o resultado) |
+| `browser_screenshot` | Print da página, salvo no projeto |
+| `browser_scroll` / `browser_wait` / `browser_eval` | Rolar, esperar seletor, rodar JS |
+| `desktop_screenshot` | Print da tela inteira do usuário |
+| `desktop_click` / `desktop_move` / `desktop_drag` | Mouse na tela real |
+| `desktop_type` / `desktop_key` / `desktop_scroll` | Teclado e rolagem do sistema |
+| `desktop_size` | Resolução da tela, para calcular coordenadas |
+
+O navegador roda via Chrome DevTools Protocol (sem dependências npm).
+
+**Requisitos por plataforma** (as ferramentas dão um erro claro se faltar algo):
+
+| | Navegador | Desktop (mouse/teclado) | Screenshot da tela |
+|---|---|---|---|
+| **Windows** | Chrome ou Edge | nativo (PowerShell) | nativo (PowerShell) |
+| **macOS** | Chrome/Chromium | `brew install cliclick` | nativo (`screencapture`) |
+| **Linux** | Chrome/Chromium | `apt install xdotool` | `scrot`, `gnome-screenshot`, `spectacle`, `maim` ou ImageMagick |
+
+Variáveis de ambiente úteis:
+- `CHROME_PATH` / `PRIMOCODE_CHROME` — aponta para um Chrome fora do caminho padrão
+- `PRIMOCODE_BROWSER_HEADLESS=1` — roda o navegador sem janela (CI/servidor)
+
+## Subagentes
+
+Para tarefas com partes independentes, o agente delega:
+
+```
+Primo Code site ❯ crie o visual do site
+
+  ◆ Agente criar o CSS
+      ⎿ Write style.css
+      ⎿ criado · 40 B
+  ◆ Criei style.css com fundo #111
+
+Pronto: CSS delegado e criado
+```
+
+O subagente tem conversa própria — **não vê o seu diálogo** — e devolve só o
+resumo final. Ele não pode criar outro subagente, então a árvore nunca cresce
+sem controle.
+
+## Nunca "pronto!" falso
+
+Se uma ferramenta falha e o agente tenta encerrar dizendo que deu certo, o
+PrimoCode barra e devolve a tarefa para ele:
+
+```
+⎿ Edit app.js
+⎿ Trecho não encontrado
+    → agente tenta finish("Porta alterada")
+    → BARRADO: "NÃO terminou. Estas tools falharam..."
+⎿ Edit app.js
+⎿ 1 troca · ±0 linhas          ← agora foi de verdade
+```
+
+## Testes
+
+```bash
+npm test
+```
+
+25 verificações sobre glob, grep, edit_file, leitura por partes e bloqueio de
+caminho fora do projeto.
+
 ## Uso
 
 ```bash
@@ -83,6 +197,9 @@ primocode -f app.js "onde está o bug?" # com arquivo anexado
 | `/run <comando>` | Executa no shell, dentro da pasta do projeto |
 | `/open <arquivo\|url>` | Abre no navegador |
 | `/status` | Health check do servidor |
+| `/name <nome>` | Como o Primo te chama na saudação |
+| `/mascot primo\|fox\|cat` | Escolhe o mascote (mostra os três) |
+| `/config` | Mostra suas preferências e onde ficam salvas |
 | `/clear` · `/cls` | Limpa conversa / tela |
 | `/uninstall` | Remove o PrimoCode (seus projetos ficam) |
 | `/exit` | Sair |

package/bin/primocode.js

@@ -13,7 +13,8 @@ const fs = require('fs');
 const os = require('os');
 
 const pkg = require('../package.json');
-const { c, welcomeBox, Spinner } = require('../lib/ui');
+const ui = require('../lib/ui');
+const { c, welcomeBox, Spinner } = ui;
 const api = require('../lib/api');
 const tools = require('../lib/tools');
 const cfg = require('../lib/config');
@@ -35,6 +36,7 @@ const HELP = `
 ${c.bold('Comandos')}
   ${c.brand('/project')}              lista projetos ou muda: /project <nome>
   ${c.brand('/mode')}                 alterna: /mode primocode|chat
+  ${c.brand('/model')}                alterna: /model main|fast
   ${c.brand('/attach')} <arquivo>     anexa arquivo ao próximo pedido
   ${c.brand('/files')}                lista anexos   ${c.brand('/detach')} remove
   ${c.brand('/tree')} [n]             árvore do projeto
@@ -42,6 +44,9 @@ ${c.bold('Comandos')}
   ${c.brand('/run')} <comando>        executa no shell do projeto
   ${c.brand('/open')} <arquivo|url>   abre no navegador
   ${c.brand('/status')}               checa o servidor
+  ${c.brand('/name')} <nome>          como o Primo te chama
+  ${c.brand('/mascot')} <estilo>      mascote: primo|fox|cat
+  ${c.brand('/config')}               mostra suas preferências
   ${c.brand('/clear')}                limpa a conversa   ${c.brand('/cls')} limpa a tela
   ${c.brand('/uninstall')}            remove o PrimoCode
   ${c.brand('/exit')}                 sair
@@ -178,7 +183,7 @@ async function runChat(promptForModel, userTextForMemory) {
             model: state.config.model,
             token: state.config.token,
         }, (evt) => {
-            if (evt.erro) { if (!started) sp.stop(); console.log(c.err(`\nerro: ${evt.erro}`)); return; }
+            if (evt.erro) { if (!started) sp.stop(); console.log('\n' + c.err(ui.friendlyError(evt.erro))); return; }
             if (evt.delta) {
                 if (!started) { sp.stop(); process.stdout.write('\n'); started = true; }
                 text += evt.delta;
@@ -188,7 +193,7 @@ async function runChat(promptForModel, userTextForMemory) {
         });
     } catch (e) {
         sp.stop();
-        console.log(c.err(`\n${e.message || e}`));
+        console.log('\n' + c.err(ui.friendlyError(e)));
         return;
     }
     sp.stop();
@@ -294,6 +299,47 @@ async function handleSlash(text) {
             break;
         }
 
+        case 'name': {
+            if (!rest) { console.log(c.muted(`  Nome atual: ${state.config.userName || '(nenhum)'}`)); break; }
+            state.config.userName = rest;
+            cfg.saveConfig({ userName: rest });
+            console.log(c.ok(`Feito! Vou te chamar de ${rest}.`));
+            break;
+        }
+
+        case 'mascot': {
+            const estilos = ['primo', 'fox', 'cat'];
+            const m = rest.toLowerCase();
+            if (!m) {
+                console.log('');
+                for (const e of estilos) {
+                    console.log(`  ${e === state.config.mascot ? c.brand('● ' + e) : c.muted('○ ' + e)}`);
+                    ui.mascot(e).forEach((l) => console.log('   ' + l));
+                    console.log('');
+                }
+                console.log(c.muted('  Escolha: /mascot <estilo>'));
+                break;
+            }
+            if (!estilos.includes(m)) { console.log(c.err(`Uso: /mascot ${estilos.join('|')}`)); break; }
+            state.config.mascot = m;
+            cfg.saveConfig({ mascot: m });
+            console.log('');
+            ui.mascot(m).forEach((l) => console.log('  ' + l));
+            console.log(c.ok(`\nMascote: ${m}`));
+            break;
+        }
+
+        case 'config': {
+            console.log('');
+            console.log(`  ${c.muted('nome')}      ${c.white(state.config.userName || '(nenhum)')}`);
+            console.log(`  ${c.muted('mascote')}   ${c.white(state.config.mascot || 'primo')}`);
+            console.log(`  ${c.muted('modelo')}    ${c.white(state.config.model)}`);
+            console.log(`  ${c.muted('modo')}      ${c.white(state.mode)}`);
+            console.log(`  ${c.muted('servidor')}  ${c.dim(state.config.server)}`);
+            console.log(c.muted(`\n  ${cfg.CONFIG_FILE}`));
+            break;
+        }
+
         case 'clear': state.history = []; console.log(c.ok('Conversa limpa.')); break;
         case 'cls': process.stdout.write('\x1Bc'); break;
 
@@ -373,7 +419,10 @@ async function main() {
         process.exit(0);
     }
 
-    console.log(welcomeBox(VERSION, state.workDir ? shortPath(state.workDir) : null));
+    console.log(welcomeBox(VERSION, state.workDir ? shortPath(state.workDir) : null, {
+        mascot: state.config.mascot,
+        userName: state.config.userName,
+    }));
     rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: makePrompt() });
     rl.prompt();
 
@@ -400,7 +449,7 @@ async function main() {
                 if (isSlash(text)) await handleSlash(text);
                 else await sendPrompt(text);
             } catch (e) {
-                console.log(c.err(`\n${e.message || e}`));
+                console.log('\n' + c.err(ui.friendlyError(e)));
             }
         }
         busy = false;

package/lib/act.js

@@ -1,52 +1,124 @@
 // Loop do agente autônomo — streaming via /api/act/stream.
 //
 // O contrato com o servidor é uma conversa completa (`messages`, estilo OpenAI).
-// Cada volta do loop: o servidor devolve tool_calls -> executamos AQUI, com await,
-// e devolvemos o resultado na próxima volta. Sem isso o modelo fica cego e repete
-// a mesma tool até estourar o limite.
+// Cada volta: o servidor devolve tool_calls -> executamos AQUI, com await, e
+// devolvemos o resultado na volta seguinte. Sem isso o modelo fica cego e
+// repete a mesma tool até estourar o limite.
+//
+// spawn_agent roda este mesmo loop recursivamente, com conversa própria: o
+// subagente não enxerga o diálogo do usuário e devolve só o resumo final.
 
 'use strict';
 
-const { c, actionHeader, Spinner } = require('./ui');
+const { c, actionHeader, Spinner, friendlyError } = require('./ui');
 const tools = require('./tools');
 const api = require('./api');
 const cfg = require('./config');
 
 const MAX_ITERATIONS = 15;
+const MAX_PROFUNDIDADE = 2; // principal + 1 nível de subagente
+
+function ident(profundidade) {
+    return '  '.repeat(profundidade);
+}
 
-function logResult(kind, result) {
-    const prefix = c.muted('  ⎿ ');
+function logResult(kind, result, profundidade) {
+    const p = ident(profundidade) + c.muted('  ⎿ ');
     if (!result) return;
-    if (result.ok === false) { console.log(prefix + c.err(result.error || `exit ${result.code ?? 'erro'}`)); return; }
+    if (result.ok === false) { console.log(p + c.err(result.error || `exit ${result.code ?? 'erro'}`)); return; }
 
     switch (kind) {
         case 'write_file':
-            console.log(prefix + c.muted(`${result.created ? 'created' : 'updated'} · ${tools.fmtBytes(result.bytes)}`));
+            console.log(p + c.muted(`${result.created ? 'criado' : 'atualizado'} · ${tools.fmtBytes(result.bytes)}`));
             return;
+        case 'edit_file': {
+            const delta = result.linhasDepois - result.linhasAntes;
+            const sinal = delta > 0 ? c.ok(`+${delta}`) : delta < 0 ? c.err(`${delta}`) : c.muted('±0');
+            console.log(p + c.muted(`${result.substituicoes} troca${result.substituicoes > 1 ? 's' : ''} · `) + sinal + c.muted(' linhas'));
+            return;
+        }
         case 'read_file':
-            console.log(prefix + c.muted(`${tools.fmtBytes(result.bytes || 0)}${result.truncated ? ' (truncated)' : ''}`));
+            console.log(p + c.muted(result.de
+                ? `linhas ${result.de}–${result.ate} de ${result.linhas}`
+                : `${result.linhas} linhas · ${tools.fmtBytes(result.bytes || 0)}${result.truncado ? ' (cortado)' : ''}`));
             return;
         case 'list_dir': {
-            const lines = (result.tree || '').split('\n').filter(Boolean);
-            for (const l of lines.slice(0, 8)) console.log(prefix + c.muted(l));
-            if (lines.length > 8) console.log(prefix + c.muted(`… +${lines.length - 8}`));
+            const linhas = (result.tree || '').split('\n').filter(Boolean);
+            for (const l of linhas.slice(0, 8)) console.log(p + c.muted(l));
+            if (linhas.length > 8) console.log(p + c.muted(`… +${linhas.length - 8}`));
             return;
         }
-        case 'run_shell':
-            console.log(prefix + c.ok('exit 0'));
+        case 'glob':
+            console.log(p + c.muted(`${result.total} arquivo${result.total === 1 ? '' : 's'}`));
+            for (const f of (result.arquivos || []).slice(0, 5)) console.log(p + c.dim(f));
+            if ((result.arquivos || []).length > 5) console.log(p + c.dim(`… +${result.arquivos.length - 5}`));
             return;
+        case 'grep': {
+            console.log(p + c.muted(`${result.total} ocorrência${result.total === 1 ? '' : 's'} em ${result.arquivosVistos} arquivos`));
+            for (const r of (result.resultados || []).slice(0, 5)) {
+                console.log(p + c.dim(`${r.arquivo}:${r.linha}`));
+            }
+            if ((result.resultados || []).length > 5) console.log(p + c.dim(`… +${result.resultados.length - 5}`));
+            return;
+        }
+        case 'run_shell': {
+            const saida = (result.stdout || '').trim().split('\n').filter(Boolean);
+            for (const l of saida.slice(0, 6)) console.log(p + c.muted(l.slice(0, 160)));
+            if (saida.length > 6) console.log(p + c.muted(`… +${saida.length - 6} linhas`));
+            if (!saida.length) console.log(p + c.ok('exit 0'));
+            return;
+        }
         case 'open_in_browser':
-        case 'run_in_new_terminal':
-            console.log(prefix + c.muted(result.opener || 'ok'));
+            console.log(p + c.muted(result.opener || 'aberto'));
+            return;
+        case 'multi_edit': {
+            const delta = result.linhasDepois - result.linhasAntes;
+            const sinal = delta > 0 ? c.ok(`+${delta}`) : delta < 0 ? c.err(`${delta}`) : c.muted('±0');
+            console.log(p + c.muted(`${result.substituicoes} trocas · `) + sinal + c.muted(' linhas'));
+            return;
+        }
+        case 'write_todos': {
+            const marca = { completed: c.ok('✔'), in_progress: c.brand('▶'), pending: c.dim('○') };
+            for (const t of result.todos || []) {
+                const texto = t.status === 'completed' ? c.dim(t.content) : c.white(t.content);
+                console.log(p + `${marca[t.status] || c.dim('○')} ${texto}`);
+            }
+            console.log(p + c.muted(`${result.feitos}/${result.total} concluídas`));
+            return;
+        }
+        case 'browser_open':
+            console.log(p + c.muted(result.url || 'aberto'));
+            return;
+        case 'browser_read':
+            console.log(p + c.muted(`${(result.text || '').length} caracteres lidos da página`));
+            return;
+        case 'browser_screenshot':
+        case 'desktop_screenshot':
+            console.log(p + c.muted(`${result.path} · ${tools.fmtBytes(result.bytes || 0)}`));
+            return;
+        case 'browser_click':
+        case 'browser_type':
+        case 'browser_key':
+        case 'browser_scroll':
+        case 'browser_wait':
+        case 'browser_eval':
+        case 'desktop_click':
+        case 'desktop_move':
+        case 'desktop_drag':
+        case 'desktop_type':
+        case 'desktop_key':
+        case 'desktop_scroll':
+        case 'desktop_size':
+            console.log(p + c.ok('ok') + (result.text || result.tag || result.selector || result.width ? c.muted(' · ' + (result.selector || result.tag || (result.width ? `${result.width}×${result.height}` : ''))) : ''));
             return;
     }
 }
 
-// O que mandamos de volta ao modelo. Cortamos saídas gigantes para não
-// estourar a janela de contexto na iteração seguinte.
+// O que volta para o modelo. Cortamos saídas gigantes para não estourar a
+// janela de contexto na iteração seguinte.
 function summarizeForModel(result) {
     const json = JSON.stringify(result);
-    return json.length > 4000 ? json.slice(0, 4000) + '…(truncado)' : json;
+    return json.length > 6000 ? json.slice(0, 6000) + '…(truncado)' : json;
 }
 
 function buildMemoryContext(projectDir, projectName) {
@@ -59,24 +131,31 @@ function buildMemoryContext(projectDir, projectName) {
 }
 
 async function runAct(userPrompt, opts) {
-    const { server, model, token, history, projectDir, projectName, ensureWorkDir } = opts || {};
+    const {
+        server, model, token, history, projectDir, projectName,
+        ensureWorkDir, profundidade = 0, subagent = false,
+    } = opts || {};
+
     // A pasta só nasce quando o agente for mesmo mexer em arquivo. Um "oi"
     // não deve deixar diretório vazio espalhado pelo disco.
     let workDirReady = !ensureWorkDir;
+    const falhasPendentes = [];
+    let tentativasDeEncerrar = 0;
 
-    // Conversa completa desta tarefa: histórico recente + memória + pedido.
     const messages = [];
-    const memory = buildMemoryContext(projectDir, projectName);
-    if (memory) messages.push({ role: 'system', content: `Memória persistente:\n\n${memory}` });
-    for (const m of (history || []).slice(-20)) {
-        if (m && m.role && m.content) messages.push({ role: m.role, content: m.content });
+    if (!subagent) {
+        const memory = buildMemoryContext(projectDir, projectName);
+        if (memory) messages.push({ role: 'system', content: `Memória persistente:\n\n${memory}` });
+        for (const m of (history || []).slice(-20)) {
+            if (m && m.role && m.content) messages.push({ role: m.role, content: m.content });
+        }
     }
     messages.push({ role: 'user', content: userPrompt });
 
     let finalText = '';
 
     for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
-        const sp = new Spinner('Primo Code pensando').start();
+        const sp = new Spinner(subagent ? 'subagente trabalhando' : 'Primo Code pensando').start();
 
         const toolCalls = [];
         let assistantText = '';
@@ -84,40 +163,46 @@ async function runAct(userPrompt, opts) {
         let streaming = false;
 
         try {
-            await api.requestAct(server, { messages, model, token, projectDir, projectName }, (evt) => {
+            await api.requestAct(server, { messages, model, token, projectDir, projectName, subagent }, (evt) => {
                 if (evt.erro) { streamError = evt.erro; return; }
                 if (evt.tool_call) { toolCalls.push(evt.tool_call); return; }
                 if (evt.delta) {
                     if (!streaming) { sp.stop(); streaming = true; }
                     assistantText += evt.delta;
-                    process.stdout.write(c.white(evt.delta));
+                    if (!subagent) process.stdout.write(c.white(evt.delta));
                 }
                 if (evt.assistant_message) assistantText = evt.assistant_message.content || assistantText;
             });
         } catch (e) {
             sp.stop();
-            console.log(c.err(`\nErro: ${e.message || e}`));
+            const amigavel = friendlyError(e);
+            if (subagent) return { assistantMessage: { role: 'assistant', content: `Subagente falhou: ${amigavel}` } };
+            console.log('\n' + c.err(amigavel));
             throw e;
         }
         sp.stop();
 
         if (streamError) {
-            console.log(c.err(`\nErro: ${streamError}`));
-            return { assistantMessage: { role: 'assistant', content: `Erro: ${streamError}` } };
+            const amigavel = friendlyError(streamError);
+            if (subagent) return { assistantMessage: { role: 'assistant', content: `Subagente falhou: ${amigavel}` } };
+            console.log('\n' + c.err(amigavel));
+            return { assistantMessage: { role: 'assistant', content: amigavel } };
         }
 
         // Sem tool_calls: o modelo respondeu e acabou.
         if (!toolCalls.length) {
             finalText = assistantText.trim();
-            if (finalText && !streaming) console.log('\n' + c.white(finalText));
-            else if (streaming) process.stdout.write('\n');
+            if (!subagent) {
+                if (finalText && !streaming) console.log('\n' + c.white(finalText));
+                else if (streaming) process.stdout.write('\n');
+            }
             break;
         }
 
-        if (streaming) process.stdout.write('\n');
+        if (streaming && !subagent) process.stdout.write('\n');
 
-        // Registra na conversa o turno do assistente COM os tool_calls.
-        // A API exige que cada mensagem role:'tool' venha depois deste turno.
+        // Registra o turno do assistente COM os tool_calls. A API exige que
+        // cada mensagem role:'tool' venha logo depois deste turno.
         messages.push({
             role: 'assistant',
             content: assistantText || null,
@@ -131,26 +216,55 @@ async function runAct(userPrompt, opts) {
         let finished = null;
         for (const tc of toolCalls) {
             if (tc.name === 'finish') {
+                // Encerrar com falha pendente é como o agente dizia "pronto!"
+                // sem ter mudado nada. Devolvemos a tarefa para ele.
+                if (falhasPendentes.length && tentativasDeEncerrar < 2) {
+                    tentativasDeEncerrar++;
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: tc.id,
+                        content: `NÃO terminou. Estas tools falharam e você não corrigiu: ${falhasPendentes.join('; ')}. `
+                            + 'Conserte agora (leia o arquivo antes de editar) ou, se for impossível, diga claramente ao usuário o que falhou.',
+                    });
+                    continue;
+                }
                 finished = (tc.arguments && tc.arguments.summary) || 'Concluído.';
                 messages.push({ role: 'tool', tool_call_id: tc.id, content: 'ok' });
                 continue;
             }
 
+            if (tc.name === 'spawn_agent') {
+                const r = await runSubagent(tc.arguments || {}, {
+                    server, model, token, projectDir, projectName, profundidade,
+                });
+                messages.push({ role: 'tool', tool_call_id: tc.id, content: r });
+                continue;
+            }
+
             if (!workDirReady) { ensureWorkDir(); workDirReady = true; }
 
-            console.log(actionHeader(tc.name, tc.arguments));
+            console.log(ident(profundidade) + actionHeader(tc.name, tc.arguments));
             const result = await tools.execute(tc.name, tc.arguments, { projectDir });
-            logResult(tc.name, result);
+            logResult(tc.name, result, profundidade);
+
+            // Uma escrita bem-sucedida limpa a dívida: o agente se corrigiu.
+            if (result && result.ok === false) falhasPendentes.push(`${tc.name}(${tc.arguments?.path || ''}): ${result.error}`);
+            else if (['write_file', 'edit_file'].includes(tc.name)) falhasPendentes.length = 0;
+
             messages.push({ role: 'tool', tool_call_id: tc.id, content: summarizeForModel(result) });
         }
 
-        if (finished) { finalText = finished; console.log('\n' + c.white(finished)); break; }
+        if (finished) {
+            finalText = finished;
+            if (!subagent) console.log('\n' + c.white(finished));
+            break;
+        }
     }
 
     if (!finalText) finalText = 'Cheguei ao limite de passos sem concluir. Refaça o pedido em partes menores.';
 
     // Nada de arquivo mexido = nada para lembrar.
-    if (projectName && workDirReady) {
+    if (!subagent && projectName && workDirReady) {
         cfg.appendProjectMemory(projectDir, `**Pedido:** ${userPrompt.slice(0, 300)}\n**Resultado:** ${finalText.slice(0, 500)}`);
     }
 
@@ -160,4 +274,27 @@ async function runAct(userPrompt, opts) {
     };
 }
 
+async function runSubagent(args, ctx) {
+    const { server, model, token, projectDir, projectName, profundidade } = ctx;
+    const descricao = args.description || 'sub-tarefa';
+
+    if (profundidade + 1 >= MAX_PROFUNDIDADE) {
+        return 'Recusado: subagente não pode criar outro subagente. Faça você mesmo.';
+    }
+    if (!args.prompt) return 'Recusado: prompt do subagente vazio.';
+
+    console.log(ident(profundidade) + `  ${c.magenta('◆')} ${c.bold(c.magenta('Agente'))} ${c.muted(descricao)}`);
+
+    const r = await runAct(args.prompt, {
+        server, model, token, projectDir, projectName,
+        history: [],
+        profundidade: profundidade + 1,
+        subagent: true,
+    });
+
+    const resumo = r.assistantMessage.content || 'sem resultado';
+    console.log(ident(profundidade) + `  ${c.magenta('◆')} ${c.muted(resumo.slice(0, 120))}`);
+    return resumo;
+}
+
 module.exports = { runAct };