primocode 8.1.1 → 8.2.1

package/bin/primocode.js

@@ -516,7 +516,9 @@ async function sendPrompt(userText) {
     // tokens). No auto, quem não vai usar ferramenta não paga por ela.
     let modo = state.mode;
     if (modo === 'auto') {
-        const escolha = escolherModo(userText);
+        // O modo do pedido ANTERIOR entra na decisão: no meio de uma tarefa,
+        // "refaz" e "agora põe música" são continuação, não papo novo.
+        const escolha = escolherModo(userText, { ultimoModo: state.modoEfetivo });
         modo = escolha.modo;
         state.modoEfetivo = modo;
         const rotulo = modo === 'primocode' ? c.warn('Primo Code') : c.brandDim('Chat');

package/lib/act.js

@@ -160,6 +160,37 @@ function summarizeForModel(result) {
     return json.length > 6000 ? json.slice(0, 6000) + '…(truncado)' : json;
 }
 
+// Quantos resultados de tool ficam INTEIROS na conversa. Os mais novos são o
+// que o modelo precisa para decidir o próximo passo; os velhos viram peso.
+const RESULTADOS_INTEIROS = 3;
+const RESTO_DO_RESULTADO = 300;
+
+/**
+ * Encolhe os resultados de tool ANTIGOS antes de mandar a conversa.
+ *
+ * Sem isto, cada página lida e cada pesquisa ficava inteira no histórico para
+ * sempre. Medido num pedido real ("pesquise sobre a empresa X e faça um
+ * vídeo"): cinco pesquisas e seis leituras de página levaram a conversa a
+ * 27.454 tokens contra um teto de 6.000 por minuto do plano grátis — a tarefa
+ * morreu no meio, depois de todo o trabalho de pesquisa já feito.
+ *
+ * Nenhuma mensagem é REMOVIDA: a API exige que cada role:'tool' continue
+ * pareada com o tool_call que a pediu. Só o texto encolhe.
+ */
+function compactar(messages) {
+    const indices = [];
+    for (let i = 0; i < messages.length; i++) if (messages[i].role === 'tool') indices.push(i);
+    if (indices.length <= RESULTADOS_INTEIROS) return messages;
+
+    const encolher = new Set(indices.slice(0, -RESULTADOS_INTEIROS));
+    return messages.map((m, i) => {
+        if (!encolher.has(i)) return m;
+        const texto = String(m.content || '');
+        if (texto.length <= RESTO_DO_RESULTADO) return m;
+        return { ...m, content: texto.slice(0, RESTO_DO_RESULTADO) + `…(resultado antigo encurtado; eram ${texto.length} caracteres)` };
+    });
+}
+
 function buildMemoryContext(projectDir, projectName) {
     const parts = [];
     const geral = cfg.readGeneralMemory();
@@ -210,7 +241,7 @@ async function runAct(userPrompt, opts) {
         let streaming = false;
 
         try {
-            await motor.requestAct(server, { messages, model, effort, token, projectDir, projectName, subagent }, (evt) => {
+            await motor.requestAct(server, { messages: compactar(messages), model, effort, 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) {
@@ -271,7 +302,7 @@ async function runAct(userPrompt, opts) {
                     messages.push({
                         role: 'tool',
                         tool_call_id: tc.id,
-                        content: `NÃO terminou. Estas tools falharam e você não corrigiu: ${falhasPendentes.join('; ')}. `
+                        content: `NÃO terminou. Estas tools falharam e você não corrigiu: ${falhasPendentes.map((f) => f.texto).join('; ')}. `
                             + 'Conserte agora (leia o arquivo antes de editar) ou, se for impossível, diga claramente ao usuário o que falhou.',
                     });
                     continue;
@@ -306,12 +337,29 @@ async function runAct(userPrompt, opts) {
             // a lista inteira e o agente conseguia dizer "concluído" com uma
             // falha real ainda pendente.
             if (result && result.ok === false) {
-                falhasPendentes.push(`${tc.name}(${tc.arguments?.path || ''}): ${result.error}`);
-            } else if (['write_file', 'edit_file'].includes(tc.name) && tc.arguments?.path) {
-                const alvo = tc.arguments.path;
-                const mantidas = falhasPendentes.filter((f) => !f.includes(`(${alvo})`));
+                falhasPendentes.push({
+                    tool: tc.name,
+                    alvo: tc.arguments?.path || '',
+                    texto: `${tc.name}(${tc.arguments?.path || ''}): ${result.error}`,
+                });
+            } else {
+                // Deu certo: some com o que ESTA tool tinha deixado pendente.
+                //
+                // Antes só write_file/edit_file limpavam, e por caminho. Uma
+                // falha já superada continuava bloqueando o finish para sempre:
+                // medido num pedido real, o browser_read errou o seletor
+                // ("main"), acertou na tentativa seguinte lendo 5.240 chars — e
+                // mesmo assim a tarefa morreu com "Parei sem concluir. A última
+                // falha foi: browser_read()". Acertar depois de errar é
+                // exatamente o que esta guarda quer premiar, não punir.
+                const alvo = tc.arguments?.path;
+                const sobrou = falhasPendentes.filter((f) => {
+                    if (f.tool === tc.name) return false;                    // a mesma tool funcionou
+                    if (alvo && f.alvo === alvo) return false;               // o mesmo arquivo foi resolvido
+                    return true;
+                });
                 falhasPendentes.length = 0;
-                falhasPendentes.push(...mantidas);
+                falhasPendentes.push(...sobrou);
             }
 
             messages.push({ role: 'tool', tool_call_id: tc.id, content: summarizeForModel(result) });
@@ -335,7 +383,7 @@ async function runAct(userPrompt, opts) {
     // depois de a primeira tentativa de seletor falhar.
     if (!finalText) {
         finalText = falhasPendentes.length
-            ? `Parei sem concluir. A última falha foi: ${falhasPendentes[falhasPendentes.length - 1]}`
+            ? `Parei sem concluir. A última falha foi: ${falhasPendentes[falhasPendentes.length - 1].texto}`
             : 'Parei sem concluir e sem explicação do modelo. Tente pedir de novo, em partes menores.';
         if (!subagent) console.log('\n' + c.warn(finalText));
     }
@@ -382,4 +430,4 @@ async function runSubagent(args, ctx) {
     return resumo;
 }
 
-module.exports = { runAct, interromper };
+module.exports = { runAct, interromper, compactar };

package/lib/catalogo.js

@@ -85,6 +85,8 @@ const GRUPOS = [
             { tool: 'studio_atualizar', escreve: false, faz: 'ajusta o que já existe, sem refazer do zero',
               args: 'id. titulo (opcional). doc (opcional).' },
             { tool: 'studio_listar',    escreve: false, faz: 'lista o que já existe no estúdio', args: null },
+            { tool: 'studio_midia',     escreve: false, faz: 'manda imagem, música ou vídeo seu para usar nas peças',
+              args: 'arquivo (opcional): caminho no projeto — sem ele, lista a galeria. nome (opcional).' },
         ],
     },
     {

package/lib/claude-engine.js

@@ -24,16 +24,55 @@ const MARCA_FIM = '<<<FIM>>>';
  */
 function extrairDecisao(texto) {
     const t = String(texto || '');
-    const inicio = t.lastIndexOf(MARCA_INICIO);
-    if (inicio === -1) return null;
-    const fim = t.indexOf(MARCA_FIM, inicio);
-    if (fim === -1) return null;
-    const bloco = t.slice(inicio + MARCA_INICIO.length, fim).trim();
-    try {
-        return JSON.parse(bloco);
-    } catch {
-        return null;
+
+    // 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;
+}
+
+/** 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 {}
+    // 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) {
+            try { return JSON.parse(s.slice(abre, k + 1)); } catch { return null; }
+        }
+    }
+    return null;
 }
 
 const catalogo = require('./catalogo');
@@ -229,7 +268,15 @@ function ultimaMensagem(messages) {
 function emitirDecisao(textoLido, onEvent) {
     const decisao = extrairDecisao(textoLido);
     if (!decisao) {
-        onEvent({ assistant_message: { content: String(textoLido || '').trim() } });
+        // Resposta sem bloco legível. Se ela AINDA ASSIM traz a marca do
+        // protocolo, o motor falhou: mostrar isso cru — com "tool_call" e
+        // JSON na cara do usuário — é pior do que dizer que falhou.
+        let conteudo = String(textoLido || '').trim();
+        if (conteudo.includes(MARCA_INICIO) || conteudo.includes(MARCA_FIM)) {
+            conteudo = conteudo.split(MARCA_INICIO)[0].trim()
+                || 'O motor Claude Code devolveu uma decisão que não consegui ler. Tente de novo, ou volte ao motor padrão com /claude off.';
+        }
+        onEvent({ assistant_message: { content: conteudo } });
         return;
     }
     if (decisao.tool_call) {

package/lib/modo.js

@@ -1,19 +1,28 @@
 /**
  * Escolha automática de modo.
  *
- * O modo primocode manda o schema das 44 ferramentas em todo pedido — ~4.700
- * tokens antes de você digitar a primeira letra. Um "oi" gasta o mesmo que uma
- * refatoração, e num plano com teto diário isso é dinheiro jogado fora (foi
+ * O modo primocode manda o schema das 45 ferramentas em todo pedido — milhares
+ * de tokens antes de você digitar a primeira letra. Um "oi" gasta o mesmo que
+ * uma refatoração, e num plano com teto diário isso é dinheiro jogado fora (foi
  * assim que a cota de 100 mil tokens/dia acabou às 15h).
  *
  * O modo chat não manda schema nenhum. Então a regra é: só paga o preço das
  * ferramentas quem vai usar ferramenta.
  *
  * A decisão é local e sem custo — nenhuma chamada ao modelo para descobrir a
- * intenção, senão o remédio custaria como a doença. É um classificador de
- * pistas, deliberadamente conservador: na dúvida, chat, porque errar para chat
- * custa uma repetição do pedido, e errar para primocode custa tokens e pode
- * escrever arquivo que ninguém pediu.
+ * intenção, senão o remédio custaria como a doença.
+ *
+ * ── POR QUE ELE OLHA O TURNO ANTERIOR ────────────────────────────────────
+ * A primeira versão julgava cada frase sozinha, e errava feio no uso real: o
+ * usuário pedia um vídeo (tarefa), e o "refaz", o "continua" e o "agora põe
+ * música de fundo" logo depois caíam no chat — o agente perdia o fio no meio
+ * do trabalho. Medido na conversa do dono: 7 erros em 18 frases, quase todos
+ * de continuação.
+ *
+ * Conversa humana não repete o objeto a cada frase. Então, QUANDO O TURNO
+ * ANTERIOR FOI UMA TAREFA, a régua abaixa: o que não é claramente cumprimento
+ * ou dúvida conceitual continua sendo trabalho. Fora de uma tarefa, a régua
+ * volta a subir — na dúvida, chat.
  */
 
 'use strict';
@@ -34,6 +43,13 @@ const VERBOS = [
     // "pesquisa no google", "aperta enter", "arrasta o arquivo".
     'clic[ao]r?', 'clique', 'digit[ae]r?', 'pesquis[ae]r?', 'apert[ae]r?',
     'arrast[ae]r?', 'rol[ae]r?', 'minimiz[ae]r?', 'maximiz[ae]r?', 'fech[ae]r?',
+    // Ajuste do que já foi criado — o vocabulário do estúdio. Sem estes, "agora
+    // põe música de fundo" caía no chat, no meio de um vídeo.
+    'p[õo]e', 'ponha', 'p[oô]r', 'coloc[ae]r?', 'tir[ae]r?', 'troc[ae]r?',
+    'inclu[ai]r?', 'insir[ae]', 'insert', 'aument[ae]r?', 'diminu[ai]r?',
+    'grav[ae]r?', 'narr[ae]r?', 'export[ae]r?', 'salv[ae]r?', 'envi[ae]r?',
+    'convert[ae]r?', 'transform[ae]r?', 'divid[ai]r?', 'junt[ae]r?',
+    'desenh[ae]r?', 'ilustr[ae]r?', 'resum[ae]r?', 'traduz[ai]r?',
 ];
 const RE_VERBO = new RegExp(`(^|\\s)(${VERBOS.join('|')})\\b`, 'i');
 
@@ -49,33 +65,75 @@ const RE_ARTEFATO = /\.(js|ts|tsx|jsx|html|css|json|md|py|sh|yml|yaml|txt|csv|en
 const RE_FERRAMENTA = /\b(navegador|browser|desktop|terminal|shell|git|npm|node|deploy|servidor|localhost|porta \d+|screenshot|print da tela|mouse|teclado|janela|[áa]rea de trabalho|aplicativo|[íi]cone)\b/i;
 const RE_PASTA = /\b(pasta|diret[óo]rio|arquivo|arquivos|reposit[óo]rio|repo|projeto)\b/i;
 
+// O que o estúdio produz. "faz uns slides", "quero um post", "monta a planilha"
+// — o substantivo sozinho já denuncia a tarefa, mesmo sem verbo claro.
+const RE_PECA = /\b(slides?|apresenta[çc][ãa]o|deck|v[íi]deo|reels?|anima[çc][ãa]o|post|banner|capa|thumbnail|arte|cartaz|planilha|tabela|documento|relat[óo]rio|artigo|proposta|contrato|diagrama|fluxograma|organograma|mapa mental|narra[çc][ãa]o|trilha|legenda)\b/i;
+
 // Conversa: cumprimento, agradecimento, pergunta conceitual.
-const RE_SAUDACAO = /^\s*(oi+|ol[áa]|e?a[íi]|bom dia|boa tarde|boa noite|tudo bem|beleza|valeu|obrigad[oa]|brigad[oa]|tchau|até|ok|okay|entendi|legal|show|massa)\b[\s!.?]*$/i;
+const RE_SAUDACAO = /^\s*(oi+|ol[áa]|e?a[íi]|bom dia|boa tarde|boa noite|tudo bem|beleza|valeu|obrigad[oa]|brigad[oa]|tchau|at[ée]|ok|okay|entendi|legal|show|massa|top|perfeito|isso|isso a[íi]|ta bom|t[áa] bom|certo)\b[\s!.?]*$/i;
 const RE_CONCEITUAL = /\b(o que [ée]|o q [ée]|que [ée]|qual (a|o|as|os)?\s*(diferen[çc]a|melhor|sentido)|por qu[êe]|pra que serve|para que serve|como funciona|como (fa[çc]o|posso|se faz|fazer)|explica|explique|me explica|significa|vale a pena|devo usar|qual usar|prefere)\b/i;
+// "o que você faz?", "o que vc sabe fazer?" — é pergunta sobre ele, não pedido.
+// Sem esta linha o "faz" batia no verbo e virava tarefa.
+const RE_SOBRE_ELE = /\bo que (voc[êe]|vc|tu)\s+(faz|sabe|consegue|pode|[ée])\b|\bquem [ée] voc[êe]\b|\bcomo voc[êe] funciona\b/i;
+
+// Satisfação: "ficou bom", "tá bom assim", "pode parar" — o usuário está
+// dizendo que ACABOU, não pedindo mais trabalho. Sem isto, no meio de uma
+// tarefa a régua abaixada mandava um elogio de volta para o agente.
+const RE_SATISFEITO = /^\s*(t[áa]|ta|ficou|est[áa]|ta[' ]?)?\s*(bom|[óo]timo|legal|show|massa|perfeito|lindo|maneiro|isso)\b(\s+(assim|mesmo|ent[ãa]o|demais))?[\s!.]*$|^\s*(pode parar|chega|s[óo] isso|era isso|nada mais)\b/i;
+
+// Continuação forte: sozinhas já significam "siga com o que estava fazendo".
+const RE_CONTINUACAO = /^\s*(refa[çz]a?|refaz|de novo|novamente|outra vez|mais uma vez|continu[ae]|prossiga|segue|siga|vai|manda|tenta( de novo| outra vez)?|tente( de novo| outra vez)?|repete|repita)\b/i;
+
+// Continuação fraca: só vale quando o turno anterior foi tarefa.
+// "agora …", "e o …?", "também …", "mais …", "sem …", "com …".
+const RE_CONTINUACAO_FRACA = /^\s*(agora|depois|ent[ãa]o|e (o|a|os|as|no|na)\b|tamb[ée]m|mais|menos|sem|com|s[óo]|apenas|troca|muda)\b/i;
 
 /**
  * Decide o modo de um pedido.
- * Devolve { modo: 'primocode'|'chat', motivo: string }.
+ *
+ * @param {string} texto  o que o usuário digitou
+ * @param {{ultimoModo?: string}} ctx  contexto da conversa; `ultimoModo` é o
+ *        modo que o pedido ANTERIOR usou de fato ('primocode' | 'chat').
+ * @returns {{modo:'primocode'|'chat', motivo:string}}
+ *
  * O motivo existe para o CLI mostrar por que escolheu — automode que decide em
  * silêncio parece defeito na primeira vez que erra.
  */
-function escolherModo(texto) {
+function escolherModo(texto, ctx = {}) {
     const t = String(texto || '').trim();
     if (!t) return { modo: 'chat', motivo: 'nada a fazer' };
 
+    const noMeioDeUmaTarefa = (ctx && ctx.ultimoModo) === 'primocode';
+
     // Cumprimento é chat mesmo que traga um verbo depois ("oi, tudo bem?").
     if (RE_SAUDACAO.test(t)) return { modo: 'chat', motivo: 'cumprimento' };
+    if (RE_SATISFEITO.test(t)) return { modo: 'chat', motivo: 'está satisfeito' };
 
-    // Pergunta conceitual ganha do verbo: "como faço para criar um site?" é
-    // dúvida, não pedido de execução.
+    // Pergunta sobre ele mesmo, e pergunta conceitual, ganham do verbo:
+    // "como faço para criar um site?" é dúvida, não pedido de execução.
+    if (RE_SOBRE_ELE.test(t)) return { modo: 'chat', motivo: 'pergunta sobre ele' };
     if (RE_CONCEITUAL.test(t)) return { modo: 'chat', motivo: 'pergunta conceitual' };
 
+    // "refaz", "de novo", "continua" — retomada, com ou sem contexto.
+    if (RE_CONTINUACAO.test(t)) return { modo: 'primocode', motivo: 'retoma a tarefa' };
+
+    // Pistas diretas.
     if (RE_ARTEFATO.test(t)) return { modo: 'primocode', motivo: 'cita arquivo ou caminho' };
     if (RE_VERBO.test(t)) return { modo: 'primocode', motivo: 'pede uma ação' };
+    if (RE_PECA.test(t)) return { modo: 'primocode', motivo: 'fala de algo para criar' };
     if (RE_DESEJO.test(t)) return { modo: 'primocode', motivo: 'expressa o que quer que exista' };
     if (RE_FERRAMENTA.test(t)) return { modo: 'primocode', motivo: 'menciona ferramenta ou máquina' };
     if (RE_PASTA.test(t)) return { modo: 'primocode', motivo: 'fala de arquivo ou projeto' };
 
+    // No meio de uma tarefa a régua abaixa: conversa não repete o objeto a cada
+    // frase, e o custo de errar aqui é o agente perder o fio.
+    if (noMeioDeUmaTarefa) {
+        if (RE_CONTINUACAO_FRACA.test(t)) return { modo: 'primocode', motivo: 'continua o que estava fazendo' };
+        // Pergunta curta no meio do trabalho costuma ser sobre o trabalho
+        // ("e não dá pra deixar rodando?"), não papo novo.
+        if (t.split(/\s+/).length <= 12) return { modo: 'primocode', motivo: 'segue a tarefa em andamento' };
+    }
+
     return { modo: 'chat', motivo: 'sem pista de tarefa' };
 }
 

package/lib/studio.js

@@ -191,8 +191,43 @@ const atualizar = ({ id, titulo, doc }) => comStudio(async () => {
     return { ok: true, ...r };
 });
 
+// ── Mídia: a imagem de fundo e a música do usuário ───────────────────────
+// Sem isto o agente não tinha como pôr foto de fundo nem trilha própria: a
+// API pede base64, e ele não ia montar data URI na mão dentro de um curl.
+const TIPOS_MIDIA = {
+    '.png': 1, '.jpg': 1, '.jpeg': 1, '.gif': 1, '.webp': 1, '.svg': 1, '.avif': 1,
+    '.mp3': 1, '.m4a': 1, '.wav': 1, '.ogg': 1, '.aac': 1, '.flac': 1, '.opus': 1, '.weba': 1,
+    '.mp4': 1, '.webm': 1, '.mov': 1,
+};
+
+const midiaListar = () => comStudio(async () => ({ ok: true, midia: await pedir('GET', '/api/midia') }));
+
+const midiaEnviar = ({ arquivo, nome }) => comStudio(async () => {
+    if (!arquivo) return { ok: false, error: 'Diga o caminho do arquivo (arquivo: "foto.jpg").' };
+    const caminho = path.resolve(arquivo);
+    if (!fs.existsSync(caminho)) return { ok: false, error: `Arquivo não existe: ${arquivo}` };
+
+    const ext = path.extname(caminho).toLowerCase();
+    if (!TIPOS_MIDIA[ext]) {
+        return { ok: false, error: `Formato não aceito: ${ext}`, aceitos: Object.keys(TIPOS_MIDIA).join(' ') };
+    }
+    const bytes = fs.statSync(caminho).size;
+    if (bytes > 60 * 1024 * 1024) return { ok: false, error: `Arquivo tem ${(bytes / 1048576).toFixed(1)} MB; o limite é 60 MB.` };
+
+    const tipo = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+        '.webp': 'image/webp', '.svg': 'image/svg+xml', '.avif': 'image/avif', '.mp3': 'audio/mpeg',
+        '.m4a': 'audio/mp4', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.aac': 'audio/aac',
+        '.flac': 'audio/flac', '.opus': 'audio/opus', '.weba': 'audio/webm', '.mp4': 'video/mp4',
+        '.webm': 'video/webm', '.mov': 'video/quicktime' }[ext] || 'application/octet-stream';
+
+    const dados = `data:${tipo};base64,` + fs.readFileSync(caminho).toString('base64');
+    const r = await pedir('POST', '/api/midia', { nome: nome || path.basename(caminho), dados }, 120000);
+    return { ok: true, ...r, comoUsar: `Use "${r.url}" em fundo.imagem, em src de uma imagem, ou em trilha.src.` };
+});
+
 module.exports = {
     BASE, PORTA, CASA,
     garantirNoAr, estaNoAr, prepararCasa, pythonCmd,
     manual, ferramentas, spec, listar, ler, criar, atualizar,
+    midiaListar, midiaEnviar,
 };

package/lib/tools.js

@@ -498,6 +498,11 @@ async function despachar(name, args, ctx) {
                 return studio.atualizar({ id: args.id, titulo: args.titulo, doc: args.doc });
             case 'studio_listar':
                 return studio.listar();
+            case 'studio_midia':
+                // Sem arquivo, lista o que já foi enviado; com arquivo, envia.
+                return args.arquivo
+                    ? studio.midiaEnviar({ arquivo: resolveInProject(args.arquivo, projectDir), nome: args.nome })
+                    : studio.midiaListar();
 
             case 'desktop_double_click':
                 return desktop.doubleClick(args.x, args.y);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "8.1.1",
+  "version": "8.2.1",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/primocode.js",
-    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js"
+    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js"
   },
   "engines": {
     "node": ">=18.17.0"

package/studio/ferramentas/corte.md

@@ -60,6 +60,39 @@ livre de direitos, ou uma das trilhas geradas acima.
 
 ---
 
+## Narração
+
+A voz que fala por cima do vídeo. Vai **na cena**, e o estúdio narra sozinho
+na hora de tocar — sem gravar nada, sem arquivo:
+
+```json
+{ "layout": "centro", "duracao": 6,
+  "narracao": "O texto que a voz vai falar nesta cena.",
+  "elementos": [ ... ] }
+```
+
+Ajuste da voz no **documento** (opcional):
+
+```json
+"voz": { "velocidade": 1, "tom": 1, "volume": 1, "lang": "pt-BR" }
+```
+
+Regras que fazem diferença:
+
+- **Escreva para o ouvido, não para o olho.** A narração NÃO repete o texto da
+  tela: a tela dá o título, a voz dá o argumento. Repetir os dois é o erro mais
+  comum, e soa a leitura de slide.
+- **Caiba na duração.** Fale ~2,5 palavras por segundo: uma cena de 6s aguenta
+  ~15 palavras. Texto mais longo que a cena é cortado no meio.
+- **Uma ideia por cena**, em uma ou duas frases curtas. Ponto final ajuda a voz
+  a respirar.
+- Para o vídeo ficar mudo de propósito, é só não pôr `narracao` em cena nenhuma.
+
+O usuário também pode gravar a própria voz pelo editor; aí a cena ganha
+`narracaoAudio` com o arquivo, e ela tem prioridade sobre a voz sintetizada.
+
+---
+
 ## Transições
 
 Na cena, `transicao` define como ela **entra**:

package/studio/web/tool.html

@@ -65,6 +65,10 @@
   document.getElementById("btn-pdf").innerHTML = svgIcone("tela");
   document.getElementById("btn-baixar").innerHTML = svgIcone("baixar");
 </script>
+<script src="/js/audio.js"></script>
+<script src="/js/narracao.js"></script>
+<script src="/js/midia.js"></script>
+<script src="/js/exportar.js"></script>
 <script src="/js/editor.js"></script>
 </body>
 </html>

package/studio/web/view.html

@@ -15,6 +15,8 @@
 <script src="/js/render.js"></script>
 <script src="/js/render-prosa.js"></script>
 <script src="/js/render-grade.js"></script>
+<script src="/js/audio.js"></script>
+<script src="/js/narracao.js"></script>
 <script src="/js/player.js"></script>
 </body>
 </html>