primocode 10.15.2 → 10.17.0

package/lib/act.js

@@ -10,6 +10,15 @@
 
 'use strict';
 
+/* A EDIÇÃO COMPLETA de vídeo falado (20/10/2026): o motor do EDIT IA PRO, pela
+   ferramenta editor_pro ou, com servidor antigo, pelo `primocode editor` no
+   run_shell. É o caminho SE a pessoa quer o vídeo editado; quem decide é o modelo. */
+const EDICAO_DE_VIDEO_FALADO = 'SE ELA QUER A GRAVAÇÃO DELA FALANDO EDITADA DE VERDADE (a edição completa: "edita meu vídeo", "faz um reels disso", '
+    + '"coloca legenda e efeitos", corte + legenda + gancho + efeitos + sons + trilha), o caminho é o editor_pro (motor EDIT IA PRO; a skill editar-video explica): '
+    + 'acao:"cortar" {video} → leia a fala que volta, com os tempos → acao:"montar" {pasta, plano:{gancho, pecas, broll}} → entregue <pasta>/final.mp4 só com o portão PASSOU '
+    + '(atalho sem plano: acao:"editar"). Se editor_pro não estiver na sua lista de ferramentas, rode o mesmo pelo run_shell: '
+    + '`primocode editor cortar --json \'{"video":"<arquivo>"}\'` (montar e editar do mesmo jeito; a saída é uma linha de JSON).\n';
+
 const { c, Spinner, PENSANDO } = require('./ui');
 const fala = require('./fala');
 const especialistas = require('./especialistas');
@@ -31,6 +40,7 @@ const tempos = require('./tempos');
 const preLeitura = require('./pre-leitura');
 const travado = require('./travado');
 const auditoria = require('./auditoria');
+const chamadaTorta = require('./chamada-torta');
 
 // 40, não 15: com o freio de repetição (repeticao.js) e o de rodada parada,
 // volta a mais não é volta em círculo — é trabalho. Quinze acabavam no meio
@@ -714,6 +724,8 @@ function buildMemoryContext(projectDir, projectName, pedido = '', { memoriaDaPas
         const daPasta = require('./agents-md.js').ler(projectDir);
         if (daPasta) parts.push(`[AGENTS.md — memória desta pasta: de onde a conversa parou]\n${curto(daPasta)}`);
     }
+    // A memória entre sessões (lib/memoria-usuario.js): a instrução e o índice; no servidor, só as 25 primeiras.
+    try { parts.push(require('./memoria-usuario.js').blocoDoContexto(undefined, { linhas: proprio ? undefined : 25 })); } catch { /* memória é conveniência */ }
     const geral = cfg.readGeneralMemory();
     if (geral.trim()) parts.push(`[memory-geral.md]\n${curto(geral)}`);
     const projeto = cfg.readProjectMemory(projectDir);
@@ -937,13 +949,18 @@ async function runAct(userPrompt, opts) {
         // Vídeo que o Estúdio fez se edita no Remotion Studio, não no editor por linha do tempo.
         const EDITAR_DO_ESTUDIO = 'SE ELA QUER EDITAR UM VÍDEO QUE O ESTÚDIO FEZ (não uma gravação dela): '
             + 'estudio_projeto acao:"editar" com o id do projeto abre o Remotion Studio no navegador; diga a pasta a ela e pare.\n';
+        const EDICAO_COMPLETA = EDICAO_DE_VIDEO_FALADO;
         const producao = diretor.precisaDeProducao(userPrompt);
         if (ehEdicaoDaGravacao) {
-            // A gravação da pessoa: o editor por linha do tempo (lib/video/), pelo run_shell.
-            messages.push({ role: 'system', content: EDITAR_DO_ESTUDIO + 'PARA EDITAR A GRAVAÇÃO DA PESSOA use o editor por linha do tempo via run_shell: '
-                + 'SE A PESSOA SÓ DISSE "edite esse vídeo" (sem dizer o quê), O VÍDEO É O PEDIDO: `primocode video import --json \'{"path":"<arquivo>"}\'`, '
+            /* A gravação da pessoa FALANDO: a edição completa é do motor do EDIT IA PRO
+               (lib/editor-pro.js), decisão do Joel em 20/10 depois de comparar os dois no
+               mesmo vídeo. O editor por linha do tempo (lib/video/) fica para as operações
+               soltas. Quem escolhe entre os dois é o modelo, pelo que a pessoa pediu. */
+            messages.push({ role: 'system', content: EDITAR_DO_ESTUDIO + EDICAO_COMPLETA
+                + 'SE ela pediu UMA operação solta na gravação (cortar um trecho, juntar, exportar, trocar o fundo, um efeito que segue a mão), use o editor por linha do tempo via run_shell: '
+                + 'SE A GRAVAÇÃO TRAZ PEDIDOS FALADOS ("separe em camadas", "me coloca numa praia"): `primocode video import --json \'{"path":"<arquivo>"}\'`, '
                 + 'depois `primocode video auto --json \'{}\'` (lê o que ela FALA na gravação e aplica cada efeito no momento em que diz), inspect, export e abra o mp4. '
-                + 'Senão: '
+                + 'Nos outros casos: '
                 + 'rode `primocode video help` UMA vez (lista as operações), depois import → remove_silence/remove_words → add_captions → inspect (olhe o png) → export. '
                 + 'Cada edição devolve um delta curto e tem undo: edite sem pedir licença a cada passo.\n'
                 /* "deixar os vídeos cinematográficos… fazer um color grading sozinha" (13/10). */
@@ -977,7 +994,7 @@ async function runAct(userPrompt, opts) {
                resposta é o modelo. Então isto é o caminho SE for produzir, e não
                mais uma ordem de produzir. */
             messages.push({ role: 'system', content:
-                EDITAR_DO_ESTUDIO + 'VOCÊ DECIDE o que entregar, pelo que a pessoa pediu: se ela quer só o roteiro, a ideia, um texto ou uma resposta, ESCREVA isso e pare — não produza vídeo. '
+                EDITAR_DO_ESTUDIO + EDICAO_COMPLETA + 'VOCÊ DECIDE o que entregar, pelo que a pessoa pediu: se ela quer só o roteiro, a ideia, um texto ou uma resposta, ESCREVA isso e pare — não produza vídeo. '
                 + `SE ela quer a peça pronta (formato "${producao.formato === 'apresentacao' ? 'slides' : 'video'}"), faça em três passos: `
                 + `estudio_projeto acao:"criar" com formato "${producao.formato === 'apresentacao' ? 'slides' : 'video'}" → `
                 + 'estudio_plano com "roteiro" (partes com tipo e fala; o PrimoCode faz layout, voz, ícones, música e sons) → '
@@ -1354,6 +1371,7 @@ async function runAct(userPrompt, opts) {
         const chavesDoLote = new Set();
         const leituras = toolCalls.filter(ehLeitura).filter((tc) => {
             if (tc.name === 'pesquisar_referencia' && pesquisasSecas >= 3) return false;
+            if (chamadaTorta.ehTorta(tc.arguments)) return false;
             const { repetida, chave } = repeticao.espiar(jaChamado, tc.name, tc.arguments);
             if (repetida || chavesDoLote.has(chave)) return false;
             chavesDoLote.add(chave);
@@ -1371,6 +1389,14 @@ async function runAct(userPrompt, opts) {
 
         let motivoTravou = null;
         for (const tc of toolCalls) {
+            /* O JSON da chamada veio quebrado (lib/chamada-torta.js): a
+               ferramenta não roda, e o modelo recebe o erro com os argumentos
+               crus para se corrigir — em vez de rodar com `{}` e repetir. */
+            if (chamadaTorta.ehTorta(tc.arguments)) {
+                anotar(tc, 'recusada', 'argumentos não são JSON válido');
+                messages.push({ role: 'tool', tool_call_id: tc.id, content: chamadaTorta.erroParaOModelo(tc.name, tc.arguments) });
+                continue;
+            }
             if (PARAR) break;
             prova.ver(tc);
             if (tc.name === 'finish') {
@@ -1767,9 +1793,12 @@ async function runAct(userPrompt, opts) {
     // que "parou sem concluir" não pode virar fato para o passo seguinte.
     const concluiu = Boolean(finalText) && !PARAR;
 
+    let passagemDaParada = null;
     if (paradoPorTravar && !finalText) {
         finalText = paradoPorTravar;
         if (!subagent) fala.aviso(finalText);
+        // Parou sem terminar: a memória leva o estado, não só "parei" (lib/passagem.js).
+        passagemDaParada = require('./passagem').montar({ pedido: userPrompt, motivo: finalText, registro: livro, falhasPendentes });
     }
 
     if (PARAR && !finalText) {
@@ -1784,6 +1813,7 @@ async function runAct(userPrompt, opts) {
     if (!finalText) {
         finalText = motivoDaParada({ voltas, voltasEmFalso, falhasPendentes, travou: rodadasParadas >= MAX_RODADAS_PARADAS, teto });
         if (!subagent) fala.aviso(finalText);
+        passagemDaParada = require('./passagem').montar({ pedido: userPrompt, motivo: finalText, registro: livro, falhasPendentes });
     }
 
     // Nada de arquivo mexido = nada para lembrar. E grava em `pastaAtual`, não em
@@ -1797,7 +1827,7 @@ async function runAct(userPrompt, opts) {
     // A raiz de trabalho não é projeto: um memory.md solto em ~/primocode
     // era o que um pedido de vídeo (que trabalha na raiz) deixava para trás.
     if (!subagent && temPasta && require('path').resolve(pastaAtual) !== require('path').resolve(cfg.ROOT_DIR)) {
-        cfg.appendProjectMemory(pastaAtual, `**Pedido:** ${userPrompt.slice(0, 300)}\n**Resultado:** ${finalText.slice(0, 500)}`);
+        cfg.appendProjectMemory(pastaAtual, passagemDaParada || `**Pedido:** ${userPrompt.slice(0, 300)}\n**Resultado:** ${finalText.slice(0, 500)}`);
     }
 
     // A memória GERAL é gravada sempre, tenha havido pasta ou não.
@@ -1890,7 +1920,7 @@ function lembreteDeParalelo(todos, naRodada) {
    dele, e é o que deixa o pai mandar a falha de volta para conserto (o laço
    do Qwen: planeja → despacha → confere → conserta). Pura, para o teste. */
 function entregaDoAgente(quem, texto, reg) {
-    const linhas = [`ENTREGA DO ${String(quem).toUpperCase()}`, String(texto).trim().slice(0, 4000)];
+    const linhas = [`ENTREGA DO ${String(quem).toUpperCase()}`, require('./entrega').limitar(texto, { quem }).texto];
     if (reg) {
         const lista = (nome, xs) => { if (xs && xs.length) linhas.push(`${nome}: ${xs.slice(0, 15).join(', ')}`); };
         lista('criou', reg.criados);
@@ -2040,5 +2070,5 @@ function novoPortaoDeProva() {
     };
 }
 
-module.exports = { novoPortaoDeProva, runAct, videoForaDeEdicao, entregaDoAgente, lembreteDeParalelo, buildMemoryContext, leituraPeloShell, historicoEnxuto, interromper, mandarDuranteATarefa, trabalhando, sobrasDaCaixa, entregarRecados, compactar, motivoDaParada, pareceParadaNoMeio, ehTetoDeToken, ehTransitorio, esperaDoErro,
+module.exports = { EDICAO_DE_VIDEO_FALADO, novoPortaoDeProva, runAct, videoForaDeEdicao, entregaDoAgente, lembreteDeParalelo, buildMemoryContext, leituraPeloShell, historicoEnxuto, interromper, mandarDuranteATarefa, trabalhando, sobrasDaCaixa, entregarRecados, compactar, motivoDaParada, pareceParadaNoMeio, ehTetoDeToken, ehTransitorio, esperaDoErro,
     anotacaoDoQueJaFoi, encolherParaContinuar, MAX_ITERATIONS };

package/lib/app-chat.js

@@ -0,0 +1,97 @@
+'use strict';
+// `primocode conversas --json` e `primocode conversa <id> --json`: a ponte do app (docs/app-chat.md).
+const nuvem = require('./nuvem');
+const conta = require('./conta');
+
+const PAPEIS = { user: 'voce', assistant: 'primo' };
+
+/* O texto de uma mensagem: string pura, ou as partes de texto juntas. */
+function textoDe(conteudo) {
+    if (typeof conteudo === 'string') return conteudo;
+    if (!Array.isArray(conteudo)) return '';
+    return conteudo.map((p) => (typeof p === 'string' ? p : (p && p.type === 'text' && p.text) || '')).filter(Boolean).join('\n');
+}
+
+/* O pedido feito por voz leva instruções para o agente ("(Modo voz. Termine SEMPRE…)"): no chat fica só o que a pessoa disse. */
+function semInstrucaoDeVoz(texto) {
+    return String(texto || '').split(/\s*\((?:Modo voz\.|Pedido por VOZ\.)/)[0].trim();
+}
+
+/* A resposta da voz vem como {"falar": "...", "painel": "..."}: no chat vale o painel (a resposta escrita). */
+function respostaEscrita(texto) {
+    const t = String(texto || '');
+    const i = t.indexOf('{"falar"');
+    if (i < 0) return t;
+    const antes = t.slice(0, i).trim();
+    try {
+        const d = JSON.parse(t.slice(i, t.lastIndexOf('}') + 1));
+        return String(d.painel || d.falar || antes || t).trim();
+    } catch {
+        const m = t.slice(i).match(/"painel"\s*:\s*"((?:[^"\\]|\\.)*)"/) || t.slice(i).match(/"falar"\s*:\s*"((?:[^"\\]|\\.)*)"/);
+        if (!m) return antes || t;
+        try { return JSON.parse(`"${m[1]}"`).trim(); } catch { return m[1].trim(); }
+    }
+}
+
+/* Só voce/primo passam; system e ferramenta ficam de fora. */
+function mensagensApp(mensagens) {
+    return (mensagens || []).filter((m) => PAPEIS[m.papel]).map((m) => {
+        const papel = PAPEIS[m.papel];
+        const texto = textoDe(m.texto);
+        return { papel, texto: papel === 'voce' ? semInstrucaoDeVoz(texto) : respostaEscrita(texto) };
+    });
+}
+
+/* `conversas --json [--limite N]` -> { id, limite }. */
+function analisar(argv) {
+    const out = { json: false, limite: 30, id: null, apagar: false, apagarTodas: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--json') out.json = true;
+        else if (a === '--apagar') out.apagar = true;
+        else if (a === '--apagar-todas') out.apagarTodas = true;
+        else if (a === '--limite' || a.startsWith('--limite=')) {
+            const n = Number(a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i]);
+            if (Number.isInteger(n) && n > 0) out.limite = n;
+        } else if (!a.startsWith('-') && !out.id) out.id = a;
+    }
+    return out;
+}
+
+async function main(sub, argv) {
+    const o = analisar(argv);
+    const dizer = (j) => { console.log(JSON.stringify(j)); return j.ok ? 0 : 1; };
+    if (!o.json) { console.log(`Uso: primocode ${sub}${sub === 'conversa' ? ' <id>' : ''} --json${sub === 'conversas' ? ' [--limite N]' : ''}`); return 1; }
+    if (!conta.atual()) return dizer({ ok: false, erro: 'não conectado' });
+    if (sub === 'conversa') {
+        if (!o.id) return dizer({ ok: false, erro: 'faltou o id da conversa' });
+        if (o.apagar) {
+            const a = await nuvem.apagarConversa(o.id);
+            return dizer(a.ok ? { ok: true, apagada: o.id } : { ok: false, erro: a.error || 'não consegui apagar' });
+        }
+        const l = await nuvem.listarConversas({ limite: 100 });
+        const r = await nuvem.lerConversa(o.id);
+        if (!r.ok) return dizer({ ok: false, erro: r.error || 'não consegui abrir a conversa' });
+        const achada = l.ok && l.conversas.find((x) => String(x.id) === o.id);
+        return dizer({ ok: true, id: o.id, titulo: achada ? semInstrucaoDeVoz(achada.titulo) : '(sem título)', mensagens: mensagensApp(r.mensagens) });
+    }
+    if (o.apagarTodas) {                  // em voltas de 100: listarConversas não passa disso por vez
+        let apagadas = 0;
+        for (let volta = 0; volta < 50; volta++) {
+            const l = await nuvem.listarConversas({ limite: 100 });
+            if (!l.ok) return dizer({ ok: false, erro: l.error || 'não consegui listar', apagadas });
+            if (!l.conversas.length) break;
+            for (const c of l.conversas) {
+                const a = await nuvem.apagarConversa(c.id);
+                if (!a.ok) return dizer({ ok: false, erro: a.error || 'não consegui apagar', apagadas });
+                apagadas++;
+            }
+        }
+        return dizer({ ok: true, apagadas });
+    }
+    const l = await nuvem.listarConversas({ limite: o.limite });
+    if (!l.ok) return dizer({ ok: false, erro: l.error || 'não consegui listar' });
+    return dizer({ ok: true, conversas: l.conversas.map((x) => ({ id: x.id, titulo: semInstrucaoDeVoz(x.titulo) || x.titulo, atualizada: x.atualizada })) });
+}
+
+module.exports = { textoDe, semInstrucaoDeVoz, respostaEscrita, mensagensApp, analisar, main };

package/lib/catalogo.js

@@ -143,7 +143,7 @@ const GRUPOS = [
             { tool: 'estudio_motion', escreve: true, faz: 'a máquina de motion: do assunto ao vídeo de motion pronto (cenas no After Effects, sons no tempo, trilha e voz opcionais, −14 LUFS)',
               args: 'id. assunto. formato (9:16|1:1|16:9). duracao (6 a 60 s). receita (id de estudio_midia acao:"projetos": usa o formato e a duração da ficha). '
                 + 'marca {cores:{fundo,destaque,tinta}, fontes:{titulo,texto,destaque}}. cenas [{papel, tipo?, fala?, titulo, itens, valor, rotulo, antes, depois, texto, autor, botao}] (o diretor escolhe entre 38 primitivas, 15 transições, 8 câmeras e 8 tipografias, com assinatura própria; a palavra-chave vai entre *asteriscos*). '
-                + 'elementos (termos reais do assunto). transicoes. camera. tipografia. semente. voz (texto ou {}; o whisper mede cada palavra). trilha (true ou o que buscar; false desliga). Sem cenas, o diretor monta. Prefira esta a escrever JSX. Sai em video-motion.mp4. previa:true = rascunho em segundos (meia resolução, sem mix final) para aprovar antes do final.' },
+                + 'elementos (termos reais do assunto). transicoes. camera. tipografia. semente. voz (texto ou {}; o whisper mede cada palavra). trilha (true ou o que buscar; false desliga). Sem cenas, o diretor monta. Prefira esta a escrever JSX. Sai em video-motion.mp4. previa:true = rascunho em segundos (meia resolução, sem mix final) para aprovar antes do final. gosto:false pula a tela de gosto do primeiro pedido; o gosto salvo da pessoa (~/.primocode/gosto-motion.json) já entra como peso no diretor — trate como direção, não molde.' },
             { tool: 'estudio_editar', escreve: true, faz: 'o editor por comando: muda um vídeo do estudio_motion (texto, cor, fonte, ritmo, cenas, trilha, volume, formato) e guarda versões',
               args: 'id_video. mudancas [{op, ...}]: texto {cena,valor} · cor {fundo,destaque,tinta|paleta} · fonte {titulo,texto,destaque} · ritmo {fator} · duracao {cena,segundos|total} · remover/mover/duplicar {cena,para} · trilha {valor:false|busca} · volume {alvo:voz|trilha|sfx,db} · formato {valor}. '
                 + 'previa (rascunho rápido). final (render final da versão atual). voltar_para (n da versão). listar. "Deixa mais rápido" = ritmo fator 0.8; "tira a música" = trilha valor false. Sai em versoes/vN.' },
@@ -152,6 +152,10 @@ const GRUPOS = [
                 + 'vozes: true lista as vozes. '
                 + 'Use os tempos que voltam para a duração das cenas — estimar por número de palavras erra em segundos.' },
 
+            { tool: 'editor_pro', escreve: true, faz: 'a EDIÇÃO COMPLETA de um vídeo falado da pessoa (o motor do EDIT IA PRO): corte da melhor tomada sem respiro, voz limpa e no volume, legenda animada, gancho, câmera viva, peças, b-roll, sons, trilha com ducking e portão de qualidade',
+              args: 'acao: editar | cortar | montar | preparar | estado. video (a gravação; o original nunca é tocado). pasta (a da edição, devolvida por cortar). prompt (nomes difíceis da fala). '
+                + 'cortar devolve a fala do corte com os tempos; com ela, montar recebe plano {gancho:"Texto *destaque*", pecas:[lettering|lista_check|passo_a_passo|contador|rotulo|carimbo...], broll:[{busca,de,ate,rotulo}], blocos?, estilo?, legenda?, correcoes?} e trilha (auto | arquivo | false). '
+                + 'Sai em <pasta>/final.mp4, só com o portão PASSOU. Leia a skill editar-video.' },
             { tool: 'estudio_video', escreve: true, faz: 'o que se faz com a gravação do usuário: importar, medir, cortar silêncio, transcrever, recortar a pessoa',
               args: 'id. acao: editar | camadas | importar | medir | silencio | cortar-silencio | quadro | legendas | recortar-pessoa. '
                 + 'editar: FAZ A EDIÇÃO INTEIRA sozinho — corta o silêncio, transcreve palavra por palavra e monta o plano '
@@ -252,6 +256,8 @@ const GRUPOS = [
             // ser para os outros casos). Esta tool é a única porta pra lá.
             { tool: 'remember_general', escreve: false, faz: 'grava algo sobre o usuário que vale para todo projeto (memory-geral.md)',
               args: 'fato: o que lembrar, em uma frase.' },
+            { tool: 'lembrar', escreve: false, faz: 'guarda ou apaga uma memória que dura entre sessões (~/.primocode/memoria/)',
+              args: 'acao: salvar ou apagar. nome: kebab-case curto (mesmo nome atualiza). descricao: uma linha. tipo: usuario|feedback|projeto|referencia. texto: o fato (nunca chave, token ou senha).' },
             // A troca de pasta pede o SIM do usuário, e quem pergunta é o bin:
             // por isso o loop (lib/act.js) atende, não o tools.execute.
             { tool: 'mudar_pasta', escreve: false, noLoop: true,

package/lib/chamada-torta.js

@@ -0,0 +1,81 @@
+/**
+ * chamada-torta.js — o JSON da chamada de ferramenta veio quebrado.
+ *
+ * Visto no goose (AAIF, Apache-2.0; só a ideia, código nosso): em vez de
+ * jogar fora a chamada mal formada, 1) tenta recuperar o objeto por uma
+ * cascata (JSON → cerca de markdown → objeto achado por chaves balanceadas →
+ * vírgula sobrando) e 2) se não der, DEVOLVE O ERRO AO MODELO, com os
+ * argumentos crus, para ele se corrigir na volta seguinte.
+ *
+ * Antes, o motor local fazia `catch { /* o loop pede de novo *​/ }` e rodava a
+ * ferramenta com `{}`: o `write_file` sem path respondia "path é obrigatório",
+ * o modelo não sabia que o problema era a sintaxe, e repetia o mesmo JSON.
+ *
+ * Puro, sem I/O: o teste mede a cascata inteira.
+ */
+
+'use strict';
+
+const MARCA = '__json_torto';
+const MAX_CRU = 600;
+
+/** Primeiro objeto `{…}` com chaves balanceadas (respeita aspas e escapes). */
+function objetoBalanceado(s) {
+    const ini = s.indexOf('{');
+    if (ini < 0) return null;
+    let fundo = 0, aspa = false, esc = false;
+    for (let i = ini; i < s.length; i++) {
+        const ch = s[i];
+        if (aspa) { if (esc) esc = false; else if (ch === '\\') esc = true; else if (ch === '"') aspa = false; continue; }
+        if (ch === '"') aspa = true;
+        else if (ch === '{') fundo++;
+        else if (ch === '}' && --fundo === 0) return s.slice(ini, i + 1);
+    }
+    return null;
+}
+
+const semVirgulaSobrando = (s) => s.replace(/,\s*([}\]])/g, '$1');
+
+function comoObjeto(v) {
+    if (typeof v === 'string') { try { return comoObjeto(JSON.parse(v)); } catch { return null; } }   // JSON dentro de JSON
+    if (Array.isArray(v)) return v.length === 1 ? comoObjeto(v[0]) : null;
+    return v && typeof v === 'object' ? v : null;
+}
+
+/** @returns {{ok: true, args: object, como: string} | {ok: false}} */
+function recuperar(bruto) {
+    if (bruto && typeof bruto === 'object') return { ok: true, args: bruto, como: 'objeto' };
+    const s = String(bruto == null ? '' : bruto).trim();
+    if (!s) return { ok: true, args: {}, como: 'vazio' };
+    const tentativas = [['json', s]];
+    const cerca = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (cerca) tentativas.push(['cerca', cerca[1].trim()]);
+    const solto = objetoBalanceado(s);
+    if (solto && !s.startsWith('[')) tentativas.push(['chaves balanceadas', solto]);
+    for (const [como, t] of [...tentativas]) tentativas.push([como + ' sem vírgula sobrando', semVirgulaSobrando(t)]);
+    for (const [como, t] of tentativas) {
+        try {
+            const o = comoObjeto(JSON.parse(t));
+            if (o) return { ok: true, args: o, como };
+        } catch { /* próxima */ }
+    }
+    return { ok: false };
+}
+
+/** Os argumentos que o motor entrega quando nem a cascata salvou. */
+function marcar(bruto) { return { [MARCA]: String(bruto == null ? '' : bruto) }; }
+function ehTorta(args) { return !!args && typeof args === 'object' && typeof args[MARCA] === 'string'; }
+
+/** O texto que volta ao modelo no lugar do resultado da ferramenta. */
+function erroParaOModelo(nome, args) {
+    const cru = String(args[MARCA] || '');
+    const parte = cru.length > MAX_CRU ? cru.slice(0, MAX_CRU) + `…(+${cru.length - MAX_CRU} caracteres)` : cru;
+    return JSON.stringify({
+        ok: false,
+        error: `A chamada de "${nome}" NÃO rodou: os argumentos não são um JSON válido (aspas sem fechar, vírgula no lugar errado ou texto em volta).`,
+        argumentosRecebidos: parte,
+        comoCorrigir: 'Chame a ferramenta de novo com UM objeto JSON válido. Em texto longo, escape as aspas (\\") e as quebras de linha (\\n). Se o conteúdo é grande, divida em arquivos menores.',
+    });
+}
+
+module.exports = { recuperar, marcar, ehTorta, erroParaOModelo, objetoBalanceado, MARCA };