primocode 9.8.0-beta.0 → 9.8.0-beta.2

package/lib/claude-engine.js

@@ -0,0 +1,630 @@
+/**
+ * claude-engine.js — motor alternativo do agente: Claude Code local em vez
+ * de OpenRouter/Groq via primocode-server.
+ *
+ * Implementa a MESMA forma que lib/api.js (requestAct(server, payload,
+ * onEvent)) — é o que permite lib/act.js trocar de motor sem saber disso.
+ * Ver docs/superpowers/specs/2026-08-15-claude-engine-design.md.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync, execFileSync } = require('child_process');
+
+/* ── O MOTOR EXTERNO NÃO APARECE ────────────────────────────────────────
+ *
+ *   "O Primo Code abre esses processos ocultamente (em segundo plano) e usa
+ *    apenas o modelo dessas ferramentas. Toda a interface, comandos, agentes e
+ *    experiência continuam sendo 100% do Primo Code."
+ *
+ * `execFileSync` sem `stdio` HERDA o stderr do pai — é o padrão do Node, e não
+ * parece nada até o dia em que o motor imprime um aviso de versão, de
+ * atualização ou de configuração. Aquilo cai no meio da tela do PrimoCode, com
+ * a cara e o vocabulário de outro produto, no meio de uma tarefa.
+ *
+ * Com o stderr CAPTURADO ele some da tela e ganha um segundo uso: `e.stderr` só
+ * existe quando é canalizado, e o tratamento de erro daqui (e o do
+ * codex-engine) já lia esse campo — estava lendo `null` desde sempre, e a
+ * mensagem de falha do motor saía sem o motivo que ele mesmo tinha escrito.
+ *
+ * `windowsHide` é a outra metade do "ocultamente": sem ele, cada chamada
+ * pisca um console preto na frente de quem usa Windows. */
+const SEM_APARECER = { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true };
+
+
+const MARCA_INICIO = '<<<PRIMOCODE>>>';
+const MARCA_FIM = '<<<FIM>>>';
+
+/**
+ * O modelo que o /claude pede.
+ *
+ *   "Ele usa o modelo Opus 5 [no Claude]."
+ *
+ * Vai o APELIDO (`opus`), não o identificador completo: o apelido é o que o
+ * Claude Code resolve para o Opus do dia, e um identificador fixo aqui
+ * envelheceria dentro de um pacote publicado no npm — a pessoa atualizaria o
+ * Claude Code, o modelo sairia de catálogo, e o PrimoCode pediria um modelo
+ * que não existe mais.
+ *
+ * Quem quiser outro põe PRIMOCODE_CLAUDE_MODELO. Vazio manda sem `--model`, e
+ * aí vale o padrão da conta da pessoa.
+ */
+const MODELO_CLAUDE = process.env.PRIMOCODE_CLAUDE_MODELO !== undefined
+    ? process.env.PRIMOCODE_CLAUDE_MODELO
+    : 'opus';
+
+/** Os argumentos do modelo, ou nenhum quando a escolha é do dono da conta. */
+function argsDoModelo() {
+    return MODELO_CLAUDE ? ['--model', MODELO_CLAUDE] : [];
+}
+
+/**
+ * Acha o ÚLTIMO bloco marcado no texto (pode vir ruído de terminal — prompt
+ * ANSI, texto solto — antes e depois) e devolve o JSON de dentro dele.
+ * null quando não achou bloco válido: quem chama decide o que fazer.
+ */
+function extrairDecisao(texto) {
+    const t = String(texto || '');
+
+    // Varre TODOS os blocos completos e fica com o último que dá para ler.
+    //
+    // A versão anterior fazia lastIndexOf(INICIO) e depois procurava o FIM
+    // para frente. Bastava o modelo escrever a marca de abertura mais uma vez
+    // — explicando o formato, ou começando um bloco e desistindo — para o FIM
+    // não existir depois dela: a extração devolvia null e o protocolo CRU ia
+    // parar na tela do usuário, com tool_call e tudo. Foi o que aconteceu num
+    // pedido real de vídeo.
+    const blocos = [];
+    let i = 0;
+    while (true) {
+        const inicio = t.indexOf(MARCA_INICIO, i);
+        if (inicio === -1) break;
+        const fim = t.indexOf(MARCA_FIM, inicio + MARCA_INICIO.length);
+        if (fim === -1) break;                       // bloco aberto e não fechado: ignora
+        blocos.push(t.slice(inicio + MARCA_INICIO.length, fim));
+        i = fim + MARCA_FIM.length;
+    }
+
+    for (let k = blocos.length - 1; k >= 0; k--) {
+        const lido = lerJSON(blocos[k]);
+        if (lido) return lido;
+    }
+    return null;
+}
+
+/** JSON com quebra de linha CRUA dentro das aspas — o jeito mais comum de o
+ * motor falhar. O Claude escreve o content de um write_file com linhas de
+ * verdade em vez de \n, o JSON.parse recusa, e o turno inteiro morria com
+ * "decisão que não consegui ler". O conserto é mecânico: dentro de string,
+ * controle vira escape. */
+function consertarControles(s) {
+    let saida = '';
+    let dentro = false, escapa = false;
+    for (const c of String(s || '')) {
+        if (dentro && !escapa && (c === '\n' || c === '\r' || c === '\t')) {
+            saida += c === '\n' ? '\\n' : c === '\r' ? '\\r' : '\\t';
+            continue;
+        }
+        if (escapa) { escapa = false; saida += c; continue; }
+        if (c === '\\') { escapa = true; saida += c; continue; }
+        if (c === '"') dentro = !dentro;
+        saida += c;
+    }
+    return saida;
+}
+
+/** O JSON do bloco, tolerando o que o modelo costuma acrescentar sem querer. */
+function lerJSON(bruto) {
+    let s = String(bruto || '').trim();
+    // Cerca de markdown em volta do JSON — o modelo põe por hábito.
+    s = s.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
+    try { return JSON.parse(s); } catch {}
+    try { return JSON.parse(consertarControles(s)); } catch {}
+    s = consertarControles(s);
+    // Sobrou texto depois do objeto? Corta no fecha-chaves que casa com o primeiro.
+    const abre = s.indexOf('{');
+    if (abre === -1) return null;
+    let nivel = 0, dentro = false, escapa = false;
+    for (let k = abre; k < s.length; k++) {
+        const c = s[k];
+        if (escapa) { escapa = false; continue; }
+        if (c === '\\') { escapa = true; continue; }
+        if (c === '"') { dentro = !dentro; continue; }
+        if (dentro) continue;
+        if (c === '{') nivel++;
+        else if (c === '}' && --nivel === 0) {
+            const trecho = s.slice(abre, k + 1);
+            try { return JSON.parse(trecho); } catch {}
+            try { return JSON.parse(consertarControles(trecho)); } catch { return null; }
+        }
+    }
+    return null;
+}
+
+const catalogo = require('./catalogo');
+
+/** Serializa lib/catalogo.js em texto — única fonte de verdade, sem
+ * duplicar a lista de ferramentas num arquivo separado. */
+function catalogoParaTexto() {
+    const linhas = [];
+    for (const grupo of catalogo.GRUPOS) {
+        linhas.push(`## ${grupo.nome} — ${grupo.resumo}`);
+        for (const item of grupo.itens) {
+            const args = item.args ? ` | args: ${item.args}` : ' | sem args';
+            linhas.push(`- ${item.tool}: ${item.faz}${args}`);
+        }
+        linhas.push('');
+    }
+    return linhas.join('\n').trim();
+}
+
+/** Texto completo que ensina o Claude Code a se comportar como motor do
+ * PrimoCode. Vira o conteúdo de ~/.claude/skills/primocode-engine/SKILL.md
+ * (Task 4) e é referenciado na primeira mensagem de cada sessão. */
+function textoBootstrap() {
+    return `---
+name: primocode-engine
+description: Skill instalada pelo PrimoCode para o modo /claude — motor de decisão do agente, não um agente autônomo.
+---
+
+# PrimoCode — modo motor
+
+Você está sendo usado como o "cérebro" do PrimoCode, um CLI que executa
+tarefas de engenharia. Não use suas próprias ferramentas nativas (Read,
+Write, Edit, Bash, Glob, Grep, WebFetch, etc.) — quem executa é o
+PrimoCode, não você. Sua única saída é dizer QUAL ferramenta do PrimoCode
+chamar, com quais argumentos, ou a resposta final.
+
+## Ferramentas disponíveis
+
+${catalogoParaTexto()}
+
+## Formato de resposta — obrigatório
+
+Termine toda resposta com exatamente um bloco, sem nada depois dele.
+
+Para chamar uma ferramenta:
+
+${MARCA_INICIO}
+{"tool_call": {"name": "write_file", "arguments": {"path": "index.html", "content": "..."}}}
+${MARCA_FIM}
+
+Para terminar a tarefa (sem mais ferramenta pra chamar):
+
+${MARCA_INICIO}
+{"assistant_message": "frase curta do que foi feito"}
+${MARCA_FIM}
+
+Nunca omita o bloco. Nunca escreva mais de um bloco por resposta.`;
+}
+
+const SKILL_DIR = () => path.join(os.homedir(), '.claude', 'skills', 'primocode-engine');
+const SKILL_PATH = () => path.join(SKILL_DIR(), 'SKILL.md');
+
+/** Grava (ou regrava) a skill em ~/.claude/skills/primocode-engine/SKILL.md.
+ * Sempre reescreve com o texto atual — barato, e garante que uma versão
+ * nova do PrimoCode (com ferramenta nova em catalogo.js) atualiza a skill
+ * sozinha na próxima vez que /claude ligar. */
+function garantirSkill() {
+    const dir = SKILL_DIR();
+    fs.mkdirSync(dir, { recursive: true });
+    const caminho = SKILL_PATH();
+    fs.writeFileSync(caminho, textoBootstrap(), 'utf-8');
+    return { ok: true, caminho };
+}
+
+/** executor(cmd) roda um comando e devolve a saída, ou lança. Default:
+ * execSync de verdade. Testes injetam uma função fake — sem mock framework. */
+function temClaudeCode(executor = (cmd) => execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })) {
+    try { executor('claude --version'); return true; }
+    catch { return false; }
+}
+
+function temOrca(executor = (cmd) => execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })) {
+    try { executor('orca --version'); return true; }
+    catch { return false; }
+}
+
+/** executor aqui devolve TEXTO (o JSON cru de `orca status --json`), não
+ * só "roda ou lança" — por isso um default diferente do de cima. */
+function orcaAlcancavel(executor = (cmd) => execSync(cmd, { encoding: 'utf-8' })) {
+    try {
+        const saida = executor('orca status --json');
+        const j = JSON.parse(saida);
+        return !!(j && j.result && j.result.runtime && j.result.runtime.reachable);
+    } catch {
+        return false;
+    }
+}
+
+/** Função pura — nenhum I/O aqui, só decide. */
+function escolherCaminho({ temClaude, temOrcaCli, orcaOk }) {
+    if (!temClaude) return 'sem-claude';
+    if (temOrcaCli && orcaOk) return 'A';
+    return 'B';
+}
+
+// Handle do terminal ORCA desta execução do processo — sessão contínua
+// enquanto o CLI ficar de pé. Cursor de leitura por handle, pra "terminal
+// read --cursor" trazer só o que é novo desde o turno anterior.
+let sessao = { handle: null, cursor: '0', bootstrapEnviado: false };
+
+function rodarOrca(args, opts = {}) {
+    return execFileSync('orca', args,
+        { encoding: 'utf-8', timeout: opts.timeout || 15000, ...SEM_APARECER });
+}
+
+let contadorId = 0;
+/** Id sintético pro tool_call — o bloco marcado do Claude Code não traz um
+ * (só existe UM tool_call por resposta, pela própria regra do bootstrap),
+ * mas lib/act.js precisa de tc.id pra parear com a mensagem role:'tool' que
+ * vem depois. Único dentro do processo já basta. */
+function proximoId() {
+    contadorId += 1;
+    return `claude-engine-${contadorId}`;
+}
+
+// Caminho A (sessão contínua via ORCA) tem um problema arquitetural real,
+// achado rodando de verdade na verificação manual (Task 9 do plano): o
+// Claude Code interativo desenha a TUI em tela alternada, e
+// `orca terminal read` (scrollback linha a linha) nunca enxerga esse
+// conteúdo — o tail fica preso no eco do comando de lançamento. `orca
+// terminal show`'s preview mostra a tela renderizada de verdade, mas é só
+// um recorte das últimas linhas visíveis, sem garantia de conter o bloco
+// marcado inteiro numa resposta mais longa que o painel. Até esse
+// mecanismo de leitura ser resolvido, o Caminho B (testado de ponta a
+// ponta, funciona) é o único confiável — força ele sempre, mesmo com ORCA
+// disponível. O código do Caminho A fica pronto pra quando isso for
+// resolvido, só não é escolhido.
+const CAMINHO_A_HABILITADO = false;
+
+async function garantirEngine() {
+    // execFileSync('claude', …) no caminho headless não resolve o shim
+    // .cmd/.bat do Windows sem shell:true — quebraria em EVERY turno, mesmo
+    // com a detecção acima (que usa execSync com shell) passando. Recusa
+    // antes de instalar a skill: honesto e seguro, em vez de "sucesso" que
+    // quebra na primeira mensagem real.
+    if (process.platform === 'win32') {
+        return {
+            ok: false,
+            error: 'O motor Claude Code ainda não funciona no Windows.',
+            comoResolver: 'Aguarde uma próxima versão, ou escolha outra opção no /api.',
+        };
+    }
+    if (!temClaudeCode()) {
+        return {
+            ok: false,
+            error: 'Claude Code não está instalado nesta máquina.',
+            comoResolver: 'Instale o Claude Code (veja https://docs.claude.com/claude-code) e escolha Claude Code no /api de novo.',
+        };
+    }
+    garantirSkill();
+    const orcaCli = CAMINHO_A_HABILITADO && temOrca();
+    const caminho = escolherCaminho({
+        temClaude: true,
+        temOrcaCli: orcaCli,
+        orcaOk: orcaCli ? orcaAlcancavel() : false,
+    });
+    return { ok: true, caminho };
+}
+
+function abrirTerminalOrca() {
+    // --dangerously-skip-permissions aqui não dá poder novo ao Claude Code:
+    // a skill (textoBootstrap) já instrui ele a nunca usar suas próprias
+    // ferramentas nativas. A flag só pula os PRÓPRIOS prompts de permissão
+    // dele, que travariam a sessão sem ninguém pra responder.
+    const saida = rodarOrca(['terminal', 'create', '--command', 'claude --dangerously-skip-permissions', '--title', 'PrimoCode', '--json']);
+    const r = JSON.parse(saida);
+    // `orca terminal create --json` aninha o handle em result.terminal.handle,
+    // não em result.handle — confirmado rodando o comando de verdade (Task 9).
+    return r.result.terminal.handle;
+}
+
+function esperarIdleOrca(handle, timeoutMs) {
+    rodarOrca(['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)], { timeout: timeoutMs + 5000 });
+}
+
+function ultimaMensagem(messages) {
+    const m = (messages || [])[messages.length - 1];
+    return m && m.content ? String(m.content) : '';
+}
+
+/** Devolve a decisão pro onEvent — tool_call, ou assistant_message (com
+ * degradação pra texto puro quando o bloco marcado não veio, em vez de
+ * travar o turno em silêncio). */
+/* ─────────────────────────────────────────────── o que não deu para ler ──
+   O motor às vezes devolve algo que este lado não sabe processar: bloco com
+   sintaxe torta, ou uma ferramenta que não existe. O usuário via isso na
+   tela — "O motor Claude Code devolveu uma decisão que não consegui ler" —
+   e a tarefa parava.
+
+   Erro de forma não é assunto do usuário. Quem errou a forma foi o motor, e
+   quem sabe consertar é ele. Então o problema volta PARA ELE, dizendo
+   exatamente o que estava errado, e ele reescreve a ação. Só depois de
+   algumas tentativas seguidas é que alguém precisa saber.
+
+   `pedirCorrecao` é preenchido por quem chamou (o caminho headless ou o
+   ORCA), porque só eles sabem como falar com o motor de novo. */
+function diagnosticar(cru, nomesValidos) {
+    if (cru.includes(MARCA_INICIO) && !cru.includes(MARCA_FIM)) {
+        return 'você abriu ' + MARCA_INICIO + ' e nunca fechou com ' + MARCA_FIM + '.';
+    }
+    if (!cru.includes(MARCA_INICIO) && cru.includes(MARCA_FIM)) {
+        return 'apareceu ' + MARCA_FIM + ' sem o ' + MARCA_INICIO + ' antes.';
+    }
+    const dentro = /<<<PRIMOCODE>>>([\s\S]*?)<<<FIM>>>/.exec(cru);
+    if (dentro) {
+        try {
+            JSON.parse(dentro[1].trim());
+            return 'o JSON até é válido, mas não tem "tool_call" nem "assistant_message" na raiz.';
+        } catch (e) {
+            return 'o conteúdo entre as marcas não é JSON válido: ' + e.message
+                + '. Lembre de escapar quebra de linha como \\n dentro das strings.';
+        }
+    }
+    if (nomesValidos) return 'a ferramenta pedida não existe. As que existem: ' + nomesValidos + '.';
+    return 'não achei um bloco marcado na sua resposta.';
+}
+
+function textoDeCorrecao(cru, motivo) {
+    return 'A sua última resposta não pôde ser executada: ' + motivo
+        + '\n\nO que você mandou foi:\n---\n' + String(cru).slice(0, 1200) + '\n---\n\n'
+        + 'Reescreva AGORA a mesma intenção numa ação que o sistema reconheça. '
+        + 'Responda com exatamente UM bloco:\n'
+        + MARCA_INICIO + '\n{"tool_call":{"name":"<uma ferramenta do catálogo>","arguments":{...}}}\n' + MARCA_FIM
+        + '\nou, se era só texto para a pessoa, ' + MARCA_INICIO
+        + '\n{"assistant_message":"..."}\n' + MARCA_FIM
+        + '\nNada fora do bloco.';
+}
+
+const MAX_CORRECOES = 3;
+
+async function emitirDecisao(textoLido, onEvent, pedirCorrecao, tentativa, validos) {
+    tentativa = tentativa || 0;
+    const decisao = extrairDecisao(textoLido);
+    if (!decisao) {
+        const cru = String(textoLido || '').trim();
+        // Traz a marca do protocolo mas o bloco não dá para ler? O motor
+        // TENTOU chamar ferramenta e errou a sintaxe. Em vez de mostrar isso
+        // ao usuário, devolvemos o problema ao motor com o diagnóstico e
+        // pedimos a mesma intenção escrita direito.
+        if (cru.includes(MARCA_INICIO) || cru.includes(MARCA_FIM)) {
+            if (pedirCorrecao && tentativa < MAX_CORRECOES) {
+                const motivo = diagnosticar(cru);
+                try {
+                    const novo = await pedirCorrecao(textoDeCorrecao(cru, motivo));
+                    return await emitirDecisao(novo, onEvent, pedirCorrecao, tentativa + 1, validos);
+                } catch (e) {
+                    // A correção em si falhou (motor fora do ar, tempo
+                    // esgotado). Cai no caminho antigo, que o loop repete.
+                }
+            }
+            onEvent({ erro: 'Failed to call a function: o motor Claude devolveu um bloco ilegível — repetindo a rodada.' });
+            return;
+        }
+        // Sem marca nenhuma: é resposta em texto, e texto é resposta válida.
+        onEvent({ assistant_message: { content: cru } });
+        return;
+    }
+    if (decisao.tool_call) {
+        // Ferramenta que não existe é o outro jeito de o motor devolver algo
+        // que este lado não sabe processar. Antes viraria uma ação falhada
+        // com "ferramenta desconhecida" — ruído para o usuário por um erro
+        // que é do motor. Volta para ele, com a lista do que existe.
+        const nome = decisao.tool_call.name;
+        if (validos && validos.length && validos.indexOf(nome) === -1) {
+            if (pedirCorrecao && tentativa < MAX_CORRECOES) {
+                try {
+                    const novo = await pedirCorrecao(textoDeCorrecao(
+                        JSON.stringify(decisao),
+                        'a ferramenta "' + nome + '" não existe. As que existem: ' + validos.join(', ') + '.'));
+                    return await emitirDecisao(novo, onEvent, pedirCorrecao, tentativa + 1, validos);
+                } catch (e) { /* motor mudo: segue e deixa o loop tratar */ }
+            }
+            onEvent({ erro: 'Failed to call a function: ferramenta "' + nome + '" não existe — repetindo a rodada.' });
+            return;
+        }
+        // lib/act.js usa tc.id pra parear a mensagem role:'tool' com este
+        // tool_call (messages.push({ tool_call_id: tc.id, ... })) — sem id
+        // aqui, esse pareamento quebra.
+        onEvent({ tool_call: { id: proximoId(), name: nome, arguments: decisao.tool_call.arguments || {} } });
+    }
+    else if (decisao.assistant_message) {
+        // O modelo pode confundir a forma com a do tool_call (que É um
+        // objeto) e emitir {"assistant_message": {"content": "..."}} em vez
+        // de string pura. Sem essa coerção, `content` vira um objeto
+        // aninhado e lib/act.js quebra com TypeError no `.trim()` — a
+        // travessia direta que este arquivo inteiro existe pra evitar.
+        const am = decisao.assistant_message;
+        const conteudo = typeof am === 'string'
+            ? am
+            : (am && typeof am.content === 'string' ? am.content : JSON.stringify(am));
+        onEvent({ assistant_message: { content: conteudo } });
+    }
+    else onEvent({ assistant_message: { content: JSON.stringify(decisao) } });
+}
+
+async function requestActViaOrca(payload, onEvent) {
+    if (!sessao.handle) {
+        try {
+            sessao.handle = abrirTerminalOrca();
+            sessao.cursor = '0';
+            sessao.bootstrapEnviado = false;
+            esperarIdleOrca(sessao.handle, 30000);
+        } catch (e) {
+            // Mesmo tratamento do try/catch abaixo: se o terminal não
+            // chegou a ficar pronto (timeout do tui-idle, por exemplo), o
+            // handle nunca foi confirmado usável — zera pra próxima
+            // chamada abrir um terminal novo do zero, em vez de deixar
+            // sessao.handle setado com algo que nunca funcionou.
+            sessao.handle = null;
+            throw e;
+        }
+    }
+    let texto = ultimaMensagem(payload.messages);
+    if (!sessao.bootstrapEnviado) {
+        texto = 'Use a skill primocode-engine para esta sessão inteira — ela está em ~/.claude/skills/primocode-engine/SKILL.md.\n\n' + texto;
+        sessao.bootstrapEnviado = true;
+    }
+    try {
+        rodarOrca(['terminal', 'send', '--terminal', sessao.handle, '--text', texto, '--enter']);
+        esperarIdleOrca(sessao.handle, 120000);
+        const lida = rodarOrca(['terminal', 'read', '--terminal', sessao.handle, '--cursor', sessao.cursor, '--json']);
+        const leitura = JSON.parse(lida);
+        // Mesma correção do handle: `terminal read --json` também aninha em
+        // result.terminal — e o texto vem como ARRAY de linhas (`tail`), não
+        // uma string única (`text`). Confirmado rodando de verdade (Task 9).
+        const t = leitura.result.terminal || {};
+        sessao.cursor = t.nextCursor != null ? String(t.nextCursor) : sessao.cursor;
+        // No terminal a correção é só mais uma mensagem na MESMA sessão: o
+        // motor já tem o protocolo e a conversa toda em contexto, então
+        // basta dizer o que saiu errado.
+        const pedirCorrecao = (aviso) => {
+            rodarOrca(['terminal', 'send', '--terminal', sessao.handle, '--text', aviso, '--enter']);
+            esperarIdleOrca(sessao.handle, 120000);
+            const outra = JSON.parse(rodarOrca(['terminal', 'read', '--terminal', sessao.handle,
+                '--cursor', sessao.cursor, '--json']));
+            const t2 = outra.result.terminal || {};
+            sessao.cursor = t2.nextCursor != null ? String(t2.nextCursor) : sessao.cursor;
+            return (t2.tail || []).join('\n');
+        };
+        await emitirDecisao((t.tail || []).join('\n'), onEvent, pedirCorrecao, 0, nomesDasTools(payload));
+    } catch (e) {
+        // Handle obsoleto (terminal fechado, ORCA reiniciou) — documentado
+        // pelo próprio `orca agent-context` como terminal_handle_stale. Zera
+        // a sessão: a PRÓXIMA chamada abre um terminal novo do zero. Esta
+        // chamada ainda falha (o usuário vê o erro e pode só pedir de novo).
+        sessao.handle = null;
+        throw e;
+    }
+}
+
+/** Sem sessão viva (caminho B), o histórico inteiro vira texto a cada
+ * chamada — mas `content` sozinho perde a mensagem quando é um turno de
+ * tool_calls (content vem null ali, o que importa está em tool_calls) ou
+ * uma resposta de ferramenta (role:'tool'). Reconstrói os dois casos em
+ * vez de deixar "assistant: null" no texto. */
+function linhaDoHistorico(m) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+        const chamadas = m.tool_calls
+            .map((tc) => `chamou ${tc.function.name} com ${tc.function.arguments}`)
+            .join('; ');
+        return `assistant: ${chamadas}`;
+    }
+    if (m.role === 'tool') return `resultado da ferramenta (${m.tool_call_id}): ${m.content}`;
+    return `${m.role}: ${m.content}`;
+}
+
+/**
+ * O protocolo INTEIRO, mais a conversa, num prompt só.
+ *
+ * A versão anterior dizia "use a skill primocode-engine" e confiava que o
+ * headless a carregaria — quando não carregava, o Claude respondia sem bloco
+ * nenhum e o turno morria. Prompt maior, mas o motor tem contexto de sobra e
+ * o formato SEMPRE chega.
+ *
+ * SEM o cabeçalho YAML da skill: ele começa com "---", e um prompt que começa
+ * com traço o parser de argumentos lê como OPÇÃO — "error: unknown option
+ * '---'" na cara do usuário, com o protocolo inteiro despejado no terminal.
+ * Foi exatamente o que aconteceu.
+ *
+ * Isto é o que o /claude e o /codex têm em comum, e é de propósito que more
+ * num lugar só: são dois motores, e tem de ser UM protocolo.
+ */
+function corpoDoProtocolo() {
+    return textoBootstrap().replace(/^---[\s\S]*?---\s*/, '');
+}
+
+/** O pedido de conserto: o protocolo de novo, mais o que saiu errado. Sem a
+ *  conversa — o assunto aqui é a FORMA, e repetir o histórico inteiro só
+ *  gastaria contexto no que não é o problema. */
+function promptDeCorrecao(aviso) {
+    return corpoDoProtocolo() + '\n\n' + aviso;
+}
+
+function promptDoProtocolo(payload) {
+    const historico = (payload.messages || []).map(linhaDoHistorico).join('\n\n');
+    return corpoDoProtocolo()
+        + '\n\nIMPORTANTE: no JSON do bloco, escreva quebras de linha como \\n (escapadas), nunca linha de verdade.'
+        + '\n\n# A conversa até aqui\n\n' + historico
+        + '\n\nResponda com exatamente UM bloco marcado.';
+}
+
+async function requestActViaHeadless(payload, onEvent) {
+    const corpoBootstrap = corpoDoProtocolo();
+    const prompt = promptDoProtocolo(payload);
+    // --dangerously-skip-permissions: mesma razão do caminho ORCA acima —
+    // a skill já proíbe o Claude Code de usar suas próprias ferramentas
+    // nativas; a flag só evita que ele pare pedindo permissão pra si mesmo
+    // numa chamada headless sem ninguém pra responder.
+    // O prompt vai por STDIN, nunca por argumento: argumento tem limite de
+    // tamanho (a conversa cresce) e qualquer conteúdo começando com traço
+    // seria lido como opção. stdin não tem nenhum dos dois problemas.
+    const saida = execFileSync('claude', [
+        '-p',
+        '--output-format', 'json',
+        '--dangerously-skip-permissions',
+        ...argsDoModelo(),
+    ], { encoding: 'utf-8', timeout: 180000, input: prompt, maxBuffer: 32 * 1024 * 1024,
+        env: process.env, ...SEM_APARECER });
+    const r = JSON.parse(saida);
+    // A correção é uma segunda ida ao motor, com o mesmo protocolo e o
+    // diagnóstico do que saiu errado. Barata: o prompt é curto, e evita que
+    // um erro de sintaxe do motor vire erro na cara do usuário.
+    const pedirCorrecao = (aviso) => {
+        const s = execFileSync('claude', [
+            '-p', '--output-format', 'json', '--dangerously-skip-permissions',
+            ...argsDoModelo(),
+        ], {
+            encoding: 'utf-8', timeout: 120000, maxBuffer: 32 * 1024 * 1024,
+            env: process.env,
+            input: promptDeCorrecao(aviso),
+            ...SEM_APARECER,
+        });
+        return JSON.parse(s).result || '';
+    };
+    await emitirDecisao(r.result || '', onEvent, pedirCorrecao, 0, nomesDasTools(payload));
+}
+
+/** Os nomes que o sistema realmente sabe executar, tirados do payload. */
+function nomesDasTools(payload) {
+    return ((payload && payload.tools) || [])
+        .map((t) => (t && t.function && t.function.name) || t.name)
+        .filter(Boolean);
+}
+
+/** Mesma forma de api.requestAct(server, payload, onEvent) — `server` não
+ * é usado aqui (não existe servidor neste motor), fica só pra manter a
+ * assinatura uniforme com o outro lado da escolha em lib/act.js. */
+async function requestAct(server, payload, onEvent) {
+    try {
+        const engineInfo = await garantirEngine();
+        if (!engineInfo.ok) {
+            onEvent({ erro: `${engineInfo.error} ${engineInfo.comoResolver || ''}`.trim() });
+            return;
+        }
+        if (engineInfo.caminho === 'A') await requestActViaOrca(payload, onEvent);
+        else await requestActViaHeadless(payload, onEvent);
+    } catch (e) {
+        onEvent({ erro: e.message });
+    }
+}
+
+module.exports = {
+    MARCA_INICIO, MARCA_FIM, extrairDecisao,
+    catalogoParaTexto, textoBootstrap,
+    // O protocolo sai daqui para o lib/codex-engine.js usar o MESMO. Ele é o
+    // que faz um motor de fora virar cérebro do PrimoCode: o texto que
+    // ensina o formato, a leitura do bloco marcado e a volta para consertar
+    // o que veio torto. Reimplementar aquilo no outro motor seria manter dois
+    // protocolos que divergem na primeira correção de um deles.
+    linhaDoHistorico, nomesDasTools, promptDoProtocolo, promptDeCorrecao,
+    MODELO_CLAUDE, argsDoModelo,
+    SKILL_DIR, SKILL_PATH, garantirSkill,
+    temClaudeCode, temOrca, orcaAlcancavel, escolherCaminho,
+    garantirEngine, requestAct, emitirDecisao,
+    _emitirDecisao: emitirDecisao,
+};