primocode 11.1.0 → 11.2.0

package/lib/app-server/websocket.js

@@ -0,0 +1,87 @@
+// WebSocket mínimo (RFC 6455) feito na mão: handshake, frames de texto,
+// ping/pong e close. Sem pacote. Só o que o app-server precisa.
+'use strict';
+
+const crypto = require('crypto');
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const MAX_PAYLOAD = 16 * 1024 * 1024;
+
+const aceite = (chave) => crypto.createHash('sha1').update(chave + GUID).digest('base64');
+
+/* Frame do servidor (nunca mascarado). */
+function frame(opcode, payload) {
+    const corpo = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload || ''), 'utf8');
+    const n = corpo.length;
+    let cab;
+    if (n < 126) cab = Buffer.from([0x80 | opcode, n]);
+    else if (n < 65536) { cab = Buffer.alloc(4); cab[0] = 0x80 | opcode; cab[1] = 126; cab.writeUInt16BE(n, 2); }
+    else { cab = Buffer.alloc(10); cab[0] = 0x80 | opcode; cab[1] = 127; cab.writeBigUInt64BE(BigInt(n), 2); }
+    return Buffer.concat([cab, corpo]);
+}
+
+/* Responde ao upgrade. Devolve a conexão { enviar, fechar }; o resto vem por callbacks. */
+function aceitar(req, socket, { aoTexto, aoFechar }) {
+    const chave = req.headers['sec-websocket-key'];
+    socket.write('HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n'
+        + `Sec-WebSocket-Accept: ${aceite(chave)}\r\n\r\n`);
+    socket.setNoDelay(true);
+
+    let buf = Buffer.alloc(0);
+    let fragmentos = [];
+    let fechado = false;
+
+    const fechar = (codigo = 1000) => {
+        if (fechado) return;
+        fechado = true;
+        const c = Buffer.alloc(2); c.writeUInt16BE(codigo, 0);
+        try { socket.write(frame(0x8, c)); } catch { /* socket já morreu */ }
+        try { socket.end(); } catch { /* idem */ }
+        if (aoFechar) aoFechar();
+    };
+    const enviar = (texto) => { if (!fechado) { try { socket.write(frame(0x1, texto)); } catch { /* idem */ } } };
+
+    const processar = () => {
+        for (;;) {
+            if (buf.length < 2) return;
+            const fin = (buf[0] & 0x80) !== 0;
+            const opcode = buf[0] & 0x0f;
+            const mascarado = (buf[1] & 0x80) !== 0;
+            let n = buf[1] & 0x7f;
+            let pos = 2;
+            if (n === 126) { if (buf.length < 4) return; n = buf.readUInt16BE(2); pos = 4; }
+            else if (n === 127) {
+                if (buf.length < 10) return;
+                const grande = buf.readBigUInt64BE(2);
+                if (grande > BigInt(MAX_PAYLOAD)) return fechar(1009);
+                n = Number(grande); pos = 10;
+            }
+            if (n > MAX_PAYLOAD) return fechar(1009);
+            // Cliente sempre mascara (RFC): sem máscara é protocolo quebrado.
+            if (!mascarado) return fechar(1002);
+            if (buf.length < pos + 4 + n) return;
+            const mascara = buf.subarray(pos, pos + 4);
+            const dados = Buffer.from(buf.subarray(pos + 4, pos + 4 + n));
+            for (let i = 0; i < n; i++) dados[i] ^= mascara[i % 4];
+            buf = buf.subarray(pos + 4 + n);
+
+            if (opcode === 0x8) return fechar(1000);
+            if (opcode === 0x9) { try { socket.write(frame(0xA, dados)); } catch { /* idem */ } continue; }
+            if (opcode === 0xA) continue;
+            if (opcode === 0x1 || opcode === 0x0) {
+                if (opcode === 0x1) fragmentos = [];
+                fragmentos.push(dados);
+                if (fin) { const t = Buffer.concat(fragmentos).toString('utf8'); fragmentos = []; aoTexto(t); }
+                continue;
+            }
+            return fechar(1003); // binário e o resto: não suportado
+        }
+    };
+
+    socket.on('data', (d) => { buf = Buffer.concat([buf, d]); processar(); });
+    socket.on('close', () => { if (!fechado) { fechado = true; if (aoFechar) aoFechar(); } });
+    socket.on('error', () => { /* o close vem em seguida */ });
+    return { enviar, fechar };
+}
+
+module.exports = { aceitar, frame, aceite, GUID };

package/lib/avisos.js

@@ -0,0 +1,64 @@
+// Avisos e fila de aprovação: ~/.primocode/avisos.json (docs/estrutura.md, seções 7 e 9). Node puro.
+// tipo: "aviso" (o agente terminou algo, ou deu erro) | "aprovacao" (espera sim ou não).
+// estado: "novo" → "lido"; aprovação: "pendente" → "resolvido".
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MAX = 200;
+const arquivo = (a) => a || process.env.PRIMOCODE_AVISOS || path.join(os.homedir(), '.primocode', 'avisos.json');
+
+function ler({ arquivo: a } = {}) {
+    try { const l = JSON.parse(fs.readFileSync(arquivo(a), 'utf8')); return Array.isArray(l) ? l : []; } catch { return []; }
+}
+function gravar(lista, a) {
+    const f = arquivo(a);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(lista.slice(0, MAX), null, 1), { mode: 0o600 });
+}
+
+function criar(dados, { arquivo: a } = {}) {
+    const aprov = dados.tipo === 'aprovacao';
+    const av = {
+        id: `n${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+        tipo: aprov ? 'aprovacao' : 'aviso',
+        estado: aprov ? 'pendente' : 'novo',
+        nivel: dados.nivel === 'erro' ? 'erro' : 'ok',
+        texto: String(dados.texto || '').slice(0, 600),
+        agente: dados.agente || null, thread: dados.thread || null, aprovacao: dados.aprovacao || null,
+        criado: Date.now(),
+    };
+    gravar([av, ...ler({ arquivo: a })], a);
+    return av;
+}
+
+const contagem = (l) => ({
+    naoLidos: l.filter((x) => x.estado === 'novo').length,
+    praAprovar: l.filter((x) => x.estado === 'pendente').length,
+});
+
+function listar({ arquivo: a } = {}) { const l = ler({ arquivo: a }); return { avisos: l, ...contagem(l) }; }
+
+/* Marca como lido um aviso (id) ou todos. Aprovação pendente não some ao ler: só ao responder. */
+function marcarLido({ id, todos } = {}, { arquivo: a } = {}) {
+    const l = ler({ arquivo: a });
+    let achou = false;
+    for (const x of l) if ((todos || x.id === id) && x.estado === 'novo') { x.estado = 'lido'; achou = true; }
+    if (!todos && !l.some((x) => x.id === id)) throw new Error(`não achei o aviso ${id}`);
+    if (achou) gravar(l, a);
+    return { avisos: l, ...contagem(l) };
+}
+
+/* A aprovação foi respondida (pelo cartão ou pelo aviso). */
+function resolverAprovacao(aprovacaoId, resposta, { arquivo: a } = {}) {
+    const l = ler({ arquivo: a });
+    const x = l.find((n) => n.tipo === 'aprovacao' && n.aprovacao === aprovacaoId && n.estado === 'pendente');
+    if (!x) return null;
+    x.estado = 'resolvido'; x.resposta = resposta || null;
+    gravar(l, a);
+    return x;
+}
+
+module.exports = { ler, criar, listar, marcarLido, resolverAprovacao, contagem };

package/lib/cli/sessao.js

@@ -242,6 +242,8 @@ const SLASH_COMANDOS = [
     ['/version', 'versão'],
     ['/exit', 'sair'],
 ];
+// A CLI nova (lib/cli-nova.js): /estudio /agentes /piloto /avisos /buscar entram no menu e no autopreenchimento.
+SLASH_COMANDOS.splice(Math.max(0, SLASH_COMANDOS.findIndex(([n]) => n === '/marca')), 0, ...require('../cli-nova.js').SLASH_NOVOS);
 
 /* /api: a chave da própria pessoa — lib/cli/comando-api.js. */
 const comandoApi = require('./comando-api.js').criar({ rl: () => rl, ask: (...a) => ask(...a), askSecret: (...a) => askSecret(...a) });
@@ -440,6 +442,8 @@ function barraDeStatus() {
     // Modelo que respondeu · contexto · tokens de hoje (os mesmos do /usage) — lib/cli/statusline.js.
     const SL = require('./statusline.js');
     direita.push(...SL.partes({ modelo: SL.modelo(), ctxPct: uso.pct, tokensHoje: SL.tokensDeHoje(), c }));
+    const aprovar = require('../cli-nova.js').praAprovar();
+    if (aprovar) direita.push(c.warn(`${aprovar} pra aprovar`));
     direita.push(state.trabalhando && rl && rl.ocupado
         ? c.warn('trabalhando') + c.dim(' · ') + c.white('esc esc') + c.dim(' para')
         : c.white('tab') + c.dim(' modos  ') + c.white('ctrl+p') + c.dim(' comandos'));
@@ -1190,7 +1194,10 @@ async function sendPrompt(userText, { digitado = false } = {}) {
         const m = state.mode === 'auto' ? (state.modoEfetivo || 'auto') : state.mode;
         if (!state.semTerminal) {
             console.log('\n  ' + `${COR_MODO[m] || COR_MODO.auto}▣${c.reset} ` + c.white(NOME_MODO[m] || m)
-                + c.dim(` · ${effort.normalizar(state.config.effort)} · ${((Date.now() - inicio) / 1000).toFixed(1)}s`) + '\n');
+                + c.dim(` · ${effort.normalizar(state.config.effort)} · ${((Date.now() - inicio) / 1000).toFixed(1)}s`));
+            const nAcoes = require('../cli-nova.js').zerar();
+            if (nAcoes) console.log(require('../cli-nova.js').fecho({ segundos: (Date.now() - inicio) / 1000, acoes: nAcoes }, { c }));
+            console.log('');
             // O que o agente deixou de pé (run_background), com o endereço pra abrir.
             const rodape = require('../fundo.js').linhasRodape(require('../fundo.js').listar(), c);
             if (rodape.length) console.log(rodape.join('\n') + '\n');
@@ -1354,6 +1361,7 @@ async function enviarPedido(userText) {
                     i === 0 ? require('../plugin/estudio/referencias.js').instrucao() : '',
                     // As imagens do pedido (arrastadas ou coladas): guardadas para o Estúdio importar, e ditas ao agente.
                     i === 0 ? (() => { const R = require('../plugin/estudio/referencias.js'); return R.instrucaoDasImagens(R.guardarImagens(R.imagensNoTexto(userText))); })() : '',
+                    i === 0 ? require('../cli-nova.js').instrucaoDeAgentes(userText).texto : '',
                     i === 0 ? plan.notaOutraPasta || '' : ''].filter(Boolean).join('\n\n'),
             });
 
@@ -2113,7 +2121,18 @@ async function handleSlash(text) {
            listava os nomes, em ordem alfabética, e quem procurava "o de ontem"
            tinha de abrir pasta por pasta. Agora vem do mais recente, com
            quando mexeu e o tamanho, e um número para entrar. */
+        case 'estudio': case 'agentes': case 'piloto': case 'avisos': case 'buscar': {
+            const r = require('../cli-nova.js').COMANDOS[nome](rest, { c, dir: process.env.PRIMOCODE_AGENTES });
+            for (const l of r.linhas) console.log(l);
+            if (r.pedido) await sendPrompt(`${r.instrucao}\n\nPEDIDO: ${r.pedido}`);
+            break;
+        }
+
         case 'projects': {
+            if (/^(criar|novo|editar|arquivar)\b/.test(rest)) {
+                for (const l of require('../cli-nova.js').projetos(rest, { c }).linhas) console.log(l);
+                break;
+            }
             const lista = extra.listarProjetos(cfg.ROOT_DIR);
             const numero = /^\d+$/.test(rest) ? Number(rest) : 0;
             if (!rest || (numero && cmd.toLowerCase() === 'projetos') || (numero && numero <= lista.length)) {
@@ -3774,6 +3793,14 @@ async function main() {
     if (process.argv[2] === 'marca') {
         process.exit(await require('../plugin/marca-kit.js').main(process.argv.slice(3)));
     }
+    if (process.argv[2] === 'app') {
+        const r = require('../cli-nova.js').app();
+        console.log(r.texto); process.exit(r.ok ? 0 : 1);
+    }
+    /* `primocode server`: o app-server local (lib/app-server/). stdout é do JSON-RPC. */
+    if (process.argv[2] === 'server') {
+        process.exit(await require('../app-server/cli.js').main(process.argv.slice(3)));
+    }
     if (process.argv[2] === 'mcp') {
         process.exit(await require('../mcp/mcp.js').main(process.argv.slice(3)));
     }

package/lib/cli-nova.js

@@ -0,0 +1,237 @@
+// A CLI nova (docs/estrutura.md, seção 5): comandos de barra /estudio /projetos /agentes /piloto /avisos /buscar,
+// `primocode app`, @agente no prompt, células com os verbos do PrimoCode e a status line.
+// Só COMPÕE os módulos que o app já usa (projetos-meta, agentes, avisos, estudio/criar, estudio/historico,
+// config): nenhuma regra é duplicada aqui. Cada comando devolve linhas de texto; quem imprime é a CLI. Node puro.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const cfg = () => require('./config/config');
+const sem = (s) => String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+const sim = (v) => /^(on|liga|ligar|ligado|sim|s|1|true)$/i.test(String(v || ''));
+const nao = (v) => /^(off|desliga|desligar|desligado|nao|não|n|0|false)$/i.test(String(v || ''));
+const cor = (c, nome) => (c && c[nome]) || ((t) => t);
+
+/* ── Células: o molde do Codex CLI com os verbos do PrimoCode ───────────────── */
+const VERBOS = [
+    [/^(read_file|list_dir|list_files|glob|grep|search_files|tree|ler_arquivo|listar)/, 'Explorou'],
+    [/^(web_search|search_web|pesquisar|buscar_web)/, 'Pesquisou na web por'],
+    [/^(run_command|bash|shell|run|exec)/, 'Rodou'],
+    [/^(edit_file|apply_patch|str_replace|replace_in_file|editar)/, 'Editou'],
+    [/^(write_file|create_file|estudio_criar|criar_arquivo)/, 'Criou'],
+    [/^(spawn_agent|mcp_|call_agent|chamar)/, 'Chamou'],
+];
+const verboDe = (nome) => { const v = VERBOS.find(([re]) => re.test(String(nome || ''))); return v ? v[1] : 'Chamou'; };
+
+/** `• Verbo alvo`; Editou ganha (+N −M). Minimizada = só a primeira linha; aberta traz o detalhe recuado. */
+function celula(item, { c, aberta = false } = {}) {
+    const dim = cor(c, 'dim'); const brand = cor(c, 'brand');
+    const verbo = item.verbo || verboDe(item.nome);
+    let l = `${brand('•')} ${verbo}${item.alvo ? ' ' + item.alvo : ''}`;
+    if (verbo === 'Editou' && (item.mais != null || item.menos != null)) l += dim(` (+${item.mais || 0} −${item.menos || 0})`);
+    const linhas = [l];
+    if (aberta && item.detalhe) for (const d of String(item.detalhe).split('\n').slice(0, 12)) linhas.push(dim('    ' + d));
+    return linhas;
+}
+function plano(passos, { c } = {}) {
+    const ok = cor(c, 'ok'); const dim = cor(c, 'dim');
+    return passos.map((p) => (p.feito ? `  ${ok('✔')} ${dim(p.texto)}` : `  □ ${p.texto}`));
+}
+const fecho = ({ segundos = 0, acoes = 0 } = {}, { c } = {}) =>
+    cor(c, 'dim')(`  Trabalhou por ${Math.max(0, Math.round(segundos))}s • ${acoes} ${acoes === 1 ? 'ação' : 'ações'}`);
+const interrompida = ({ c } = {}) => cor(c, 'warn')('  ■ Conversa interrompida');
+
+/* Conta as ações do turno (a tela do terminal chama contar a cada item `acao`). */
+const turno = { acoes: 0 };
+const contar = () => { turno.acoes++; };
+const zerar = () => { const n = turno.acoes; turno.acoes = 0; return n; };
+
+/* ── Status line ────────────────────────────────────────────────────────────── */
+const NOMES_ESFORCO = { low: 'Leve', medium: 'Médio', high: 'Alto', ultra: 'Ultra', ultracode: 'Ultra' };
+const tok = (n) => (n >= 1000 ? `${Math.round(n / 1000)}k` : String(n || 0));
+
+/** `~/primocode/<projeto> · Alto · 34% ctx · 28k tok hoje · ● trabalhando · N pra aprovar`. ctx laranja ≥70%, vermelho ≥100%. */
+function statusLinha(e = {}, { c } = {}) {
+    const dim = cor(c, 'dim'); const sep = dim(' · ');
+    const p = [];
+    p.push(cor(c, 'brandDim')(e.pasta || '~/primocode'));
+    p.push(cor(c, 'white')(NOMES_ESFORCO[String(e.esforco || '').toLowerCase()] || e.esforco || 'Alto'));
+    if (e.ctxPct != null) p.push(e.ctxPct >= 100 ? cor(c, 'err')(`${e.ctxPct}% ctx`) : e.ctxPct >= 70 ? cor(c, 'warn')(`${e.ctxPct}% ctx`) : dim(`${e.ctxPct}% ctx`));
+    if (e.tokensHoje) p.push(dim(`${tok(e.tokensHoje)} tok hoje`));
+    if (e.trabalhando) p.push(cor(c, 'warn')('● trabalhando'));
+    if (e.praAprovar) p.push(cor(c, 'warn')(`${e.praAprovar} pra aprovar`));
+    return p.join(sep);
+}
+const praAprovar = () => { try { return require('./avisos').contagem(require('./avisos').ler()).praAprovar; } catch { return 0; } };
+
+/* ── @agente no prompt ──────────────────────────────────────────────────────── */
+/** O texto que entra como instrução do turno: o agente citado (mesmo desligado) vira chamada, os ligados vão de cardápio. */
+function instrucaoDeAgentes(texto, { dir } = {}) {
+    try { return require('./agentes-pessoais').instrucao(texto, [], { dir }); } catch { return { texto: '', chamados: [] }; }
+}
+/** Nomes do `@` na hora de digitar: agentes primeiro (com o ofício), arquivos depois. */
+function completarArroba(prefixo, { projeto, dir } = {}) {
+    const q = sem(String(prefixo || '').replace(/^@/, ''));
+    const ags = require('./agentes-pessoais').listar({ dir }).filter((a) => sem(a.nome).startsWith(q))
+        .map((a) => ({ tipo: 'agente', valor: '@' + a.nome, descricao: a.descricao || a.oficio.slice(0, 60) }));
+    let arqs = [];
+    if (projeto) {
+        try {
+            arqs = fs.readdirSync(projeto, { withFileTypes: true }).filter((d) => !d.name.startsWith('.') && sem(d.name).startsWith(q))
+                .map((d) => ({ tipo: d.isDirectory() ? 'pasta' : 'arquivo', valor: '@' + d.name + (d.isDirectory() ? '/' : ''), descricao: '' }));
+        } catch { /* sem projeto */ }
+    }
+    return ags.concat(arqs.slice(0, 20));
+}
+
+/* ── Comandos de barra ──────────────────────────────────────────────────────── */
+const TIPOS_ESTUDIO = [['slides', 'apresentação em PDF'], ['video', 'vídeo curto vertical'], ['motion', 'animação de motion'], ['carrossel', 'carrossel (sem receita no Estúdio ainda)'], ['anuncio', 'anúncio de 15 s'], ['abertura', 'abertura de canal de 5 s']];
+
+/** `/estudio [tipo] [briefing]` → { linhas, pedido?, tipo? }. Com tipo e briefing, devolve o `pedido` para a sessão mandar ao motor. */
+function estudio(rest, { c } = {}) {
+    const { QUADRADOS, instrucaoDoTipo } = require('./plugin/estudio/criar');
+    const [t0, ...r] = String(rest || '').trim().split(/\s+/).filter(Boolean);
+    const tipo = sem(t0).replace(/^v[ií]deo$/, 'video');
+    const linhas = [];
+    if (!t0) {
+        linhas.push(cor(c, 'white')('O que vamos criar?'));
+        for (const [n, d] of TIPOS_ESTUDIO) linhas.push(`  ${cor(c, 'brand')(n.padEnd(10))}${cor(c, 'muted')(d)}`);
+        linhas.push(cor(c, 'dim')('  /estudio <tipo> [o que criar]'));
+        return { linhas };
+    }
+    if (!TIPOS_ESTUDIO.some(([n]) => n === tipo) && !QUADRADOS[tipo]) return { linhas: [cor(c, 'err')(`Tipo "${t0}" não existe. Use: ${TIPOS_ESTUDIO.map(([n]) => n).join(', ')}.`)], erro: true };
+    if (tipo === 'carrossel') return { linhas: [cor(c, 'warn')('Carrossel ainda não tem receita no Estúdio. Descreva como slides ou peça direto na conversa.')], erro: true };
+    const briefing = r.join(' ');
+    if (!briefing) return { linhas: [cor(c, 'white')(`O que vamos criar em ${tipo}?`), cor(c, 'dim')(`  /estudio ${tipo} <descrição do que criar>`)], tipo };
+    return { linhas: [], tipo, pedido: briefing, instrucao: instrucaoDoTipo(tipo) };
+}
+
+/** `/projetos`: lista · `criar <nome>` · `editar <id> nome=… icone=… cor=… descricao=…` · `arquivar <id>`. Mesmo módulo do app. */
+function projetos(rest, { c } = {}) {
+    const P = require('./projetos-meta');
+    const [op, ...r] = String(rest || '').trim().split(/\s+/).filter(Boolean);
+    try {
+        if (op === 'criar' || op === 'novo') { const p = P.criar({ nome: r.join(' ') }); return { linhas: [cor(c, 'ok')(`Projeto criado: ${p.nome}`) + cor(c, 'muted')(`  (${p.caminho})`)], projeto: p }; }
+        if (op === 'editar') {
+            const [id, ...kv] = r; const m = {};
+            for (const x of kv) { const i = x.indexOf('='); if (i > 0) m[x.slice(0, i)] = x.slice(i + 1); }
+            const p = P.atualizar(id, m);
+            return { linhas: [cor(c, 'ok')(`Projeto atualizado: ${p.nome} · ${p.icone} · ${p.cor}`)], projeto: p };
+        }
+        if (op === 'arquivar') { const x = P.arquivar(r[0]); return { linhas: [cor(c, 'ok')(`Arquivado ${x.id} (os arquivos ficam).`)] }; }
+    } catch (e) { return { linhas: [cor(c, 'err')(e.message)], erro: true }; }
+    const l = P.listar();
+    if (!l.length) return { linhas: [cor(c, 'muted')('Nenhum projeto ainda.')] };
+    return { linhas: l.map((p, i) => `  ${String(i + 1).padStart(2)}  ${cor(c, 'white')(p.nome.padEnd(24))}${cor(c, 'dim')(`${p.icone} ${p.cor}${p.descricao ? ' · ' + p.descricao : ''}`)}`), lista: l };
+}
+
+/** `/agentes`: lista · ligar|desligar <nome> · criar <nome> | <descrição> | <ofício> · apagar <nome>. */
+function agentes(rest, { c, dir } = {}) {
+    const A = require('./agentes-pessoais');
+    const [op, ...r] = String(rest || '').trim().split(/\s+/).filter(Boolean);
+    try {
+        if (op === 'ligar' || op === 'desligar') { const a = A.alternar(r[0], op === 'ligar', { dir }); return { linhas: [cor(c, 'ok')(`@${a.nome} ${a.ligado ? 'ligado' : 'desligado'}`)] }; }
+        if (op === 'apagar') { const x = A.apagar(r[0], { dir }); return { linhas: [cor(c, 'ok')(`@${x.nome} apagado`)] }; }
+        if (op === 'criar') {
+            const [nome, descricao, oficio] = r.join(' ').split('|').map((s) => s.trim());
+            const a = A.criar({ nome, descricao: descricao || '', oficio: oficio || descricao || '' }, { dir });
+            return { linhas: [cor(c, 'ok')(`@${a.nome} criado`) + cor(c, 'muted')('  (desligado: /agentes ligar ' + a.nome + ')')] };
+        }
+    } catch (e) { return { linhas: [cor(c, 'err')(e.message)], erro: true }; }
+    const l = A.listar({ dir });
+    if (!l.length) return { linhas: [cor(c, 'muted')('Nenhum agente. Crie: /agentes criar <nome> | <o que faz> | <ofício>')] };
+    return { linhas: l.map((a) => `  ${a.ligado ? cor(c, 'ok')('●') : cor(c, 'dim')('○')} ${cor(c, 'white')('@' + a.nome.padEnd(16))}${cor(c, 'dim')(a.descricao || a.oficio.slice(0, 60))}`), lista: l };
+}
+
+/** `/piloto [on|off] [grupo]`: grava `piloto` e `grupo` na config; quem roda o ciclo é o app-server (lib/piloto.js). */
+function piloto(rest, { c } = {}) {
+    const ps = String(rest || '').trim().split(/\s+/).filter(Boolean);
+    const mudar = {};
+    for (const p of ps) { if (sim(p)) mudar.piloto = true; else if (nao(p)) mudar.piloto = false; else if (/^grupo$/i.test(p)) mudar.grupo = true; else if (/^solo$/i.test(p)) mudar.grupo = false; }
+    if (Object.keys(mudar).length) cfg().saveConfig(mudar);
+    const e = cfg().loadConfig();
+    const ligados = require('./agentes-pessoais').listar().filter((a) => a.ligado).length;
+    return { linhas: [
+        `${e.piloto === true ? cor(c, 'ok')('● Piloto ligado') : cor(c, 'dim')('○ Piloto desligado')}${e.grupo === true ? cor(c, 'muted')(' · em grupo') : ''}  ${cor(c, 'muted')(`${ligados} agente${ligados === 1 ? '' : 's'} ligado${ligados === 1 ? '' : 's'}`)}`,
+        cor(c, 'dim')('  O ciclo roda no app-server (primocode app/server); aqui só liga e desliga.'),
+    ], ligado: e.piloto === true, grupo: e.grupo === true };
+}
+
+/** `/avisos`: a fila. `a <n>` aprova, `r <n>` recusa, `ler [n|todos]` marca lido. */
+function avisos(rest, { c, arquivo } = {}) {
+    const V = require('./avisos');
+    const [op, n] = String(rest || '').trim().split(/\s+/).filter(Boolean);
+    const arq = arquivo ? { arquivo } : {};
+    const lista = () => V.ler(arq).filter((x) => x.estado === 'pendente' || x.estado === 'novo');
+    try {
+        if (op === 'a' || op === 'r') {
+            const x = lista()[Number(n) - 1];
+            if (!x || x.tipo !== 'aprovacao') return { linhas: [cor(c, 'err')('Escolha o número de uma aprovação pendente: /avisos a 1')], erro: true };
+            V.resolverAprovacao(x.aprovacao, op === 'r' ? 'nao' : 'agora', arq);
+            return { linhas: [cor(c, 'ok')(`${op === 'r' ? 'Recusado' : 'Aprovado'}: ${x.texto}`)] };
+        }
+        if (op === 'ler') {
+            const x = n && n !== 'todos' ? lista()[Number(n) - 1] : null;
+            V.marcarLido(n === 'todos' || !n ? { todos: true } : { id: x && x.id }, arq);
+            return { linhas: [cor(c, 'ok')('Marcado como lido.')] };
+        }
+    } catch (e) { return { linhas: [cor(c, 'err')(e.message)], erro: true }; }
+    const l = lista();
+    const k = V.contagem(V.ler(arq));
+    if (!l.length) return { linhas: [cor(c, 'muted')('Nada pra ver. Fila vazia.')] };
+    return { linhas: [
+        ...l.map((x, i) => `  ${String(i + 1).padStart(2)}  ${x.tipo === 'aprovacao' ? cor(c, 'warn')('aprovar') : cor(c, x.nivel === 'erro' ? 'err' : 'ok')('aviso  ')}  ${x.texto}${x.agente ? cor(c, 'dim')(' · @' + x.agente) : ''}`),
+        cor(c, 'dim')(`  ${k.praAprovar} pra aprovar · ${k.naoLidos} não lidos · a <n> aprova · r <n> recusa · ler [n|todos]`),
+    ], lista: l };
+}
+
+/** `/buscar <texto>`: projetos, agentes, vídeos/slides do Estúdio e conversas salvas. */
+function buscar(rest, { c, dir } = {}) {
+    const q = sem(rest).trim();
+    if (!q) return { linhas: [cor(c, 'dim')('Uso: /buscar <texto>  (projetos, agentes, vídeos, conversas)')], erro: true };
+    const achei = (txt) => sem(txt).includes(q);
+    const out = [];
+    const sec = (t, itens) => { if (itens.length) { out.push(cor(c, 'white')(t)); out.push(...itens.slice(0, 8)); } };
+    const tenta = (f, d) => { try { return f(); } catch { return d; } };
+    sec('Projetos', tenta(() => require('./projetos-meta').listar(), []).filter((p) => achei(`${p.nome} ${p.descricao}`)).map((p) => `  ${p.nome}${cor(c, 'dim')('  ' + p.caminho)}`));
+    sec('Agentes', tenta(() => require('./agentes-pessoais').listar({ dir }), []).filter((a) => achei(`${a.nome} ${a.descricao} ${a.oficio}`)).map((a) => `  @${a.nome}${cor(c, 'dim')('  ' + (a.descricao || ''))}`));
+    sec('Vídeos e slides', tenta(() => require('./plugin/estudio/historico').historico({ busca: rest, limite: 8 }).itens, []).map((i) => `  ${i.titulo}${cor(c, 'dim')('  ' + (i.principal || i.pasta))}`));
+    const pt = path.join(os.homedir(), '.primocode', 'threads');
+    sec('Conversas', tenta(() => fs.readdirSync(pt).filter((n) => n.endsWith('.json')).map((n) => JSON.parse(fs.readFileSync(path.join(pt, n), 'utf8'))), [])
+        .filter((t) => !t.arquivada && achei(t.titulo)).map((t) => `  ${t.titulo}${cor(c, 'dim')('  ' + t.id)}`));
+    return { linhas: out.length ? out : [cor(c, 'muted')(`Nada achado para "${rest}".`)] };
+}
+
+const SLASH_NOVOS = [
+    ['/estudio', 'escolhe o que criar: slides, vídeo, motion, anúncio, abertura'],
+    ['/agentes', 'seus agentes: lista · ligar · desligar · criar · apagar'],
+    ['/piloto', 'piloto automático: on | off [grupo]'],
+    ['/avisos', 'fila de aprovação e avisos · a <n> aprova · r <n> recusa'],
+    ['/buscar', 'procura em projetos, agentes, vídeos e conversas'],
+];
+const COMANDOS = { estudio, projetos, agentes, piloto, avisos, buscar };
+
+/* ── primocode app ──────────────────────────────────────────────────────────── */
+function appInstalado({ env = process.env, plataforma = process.platform, existe = fs.existsSync } = {}) {
+    const alvos = env.PRIMOCODE_APP ? [env.PRIMOCODE_APP] : plataforma === 'darwin'
+        ? ['/Applications/PrimoCode.app', path.join(os.homedir(), 'Applications', 'PrimoCode.app')]
+        : plataforma === 'win32' ? [path.join(env.LOCALAPPDATA || '', 'Programs', 'PrimoCode', 'PrimoCode.exe')]
+            : ['/opt/PrimoCode/primocode', path.join(os.homedir(), '.local', 'bin', 'primocode-app')];
+    return alvos.find((a) => a && existe(a)) || null;
+}
+/** `primocode app`: abre o desktop se instalado; senão diz como. `abrir(caminho)` é injetável (teste não abre nada). */
+function app({ abrir, ...o } = {}) {
+    const a = appInstalado(o);
+    if (!a) return { ok: false, texto: 'O app desktop não está instalado. Baixe em primocode.app (ou rode `primocode server --ws` para usar outra tela). Dentro do repo: `cd app && npm install && npm start`.' };
+    const faz = abrir || ((p) => {
+        const { spawn } = require('child_process');
+        const [bin, args] = process.platform === 'darwin' ? ['open', [p]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', p]] : [p, []];
+        spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+    });
+    faz(a);
+    return { ok: true, texto: `Abrindo o PrimoCode (${a}).`, caminho: a };
+}
+
+module.exports = { celula, plano, fecho, interrompida, verboDe, contar, zerar, statusLinha, praAprovar, instrucaoDeAgentes, completarArroba, SLASH_NOVOS, COMANDOS, estudio, projetos, agentes, piloto, avisos, buscar, app, appInstalado };

package/lib/config/config.js

@@ -340,6 +340,11 @@ function loadConfig() {
         permissoes: file.permissoes || 'auto',
         // O parceiro do /team (lib/team.js): quem revisa o que o PrimoCode faz. null = sozinho.
         team: file.team || null,
+        // Piloto automático e agentes em grupo (docs/estrutura.md, seção 9). Desligados por padrão.
+        piloto: file.piloto === true,
+        grupo: file.grupo === true,
+        // A tela de primeira execução do app (docs/estrutura.md, 16.7): some depois de feita ou pulada.
+        inicioFeito: file.inicioFeito === true,
         rootDir: ROOT_DIR,
         _file: file,
     };
@@ -349,8 +354,8 @@ function saveConfig(partial) {
     ensureDir(CONFIG_DIR);
     const cur = (() => { try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; } })();
     // Só persiste o que faz sentido guardar — nada de campos derivados.
-    const { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes, team } = { ...cur, ...partial };
-    const next = { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes, team };
+    const { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes, team, piloto, grupo, inicioFeito } = { ...cur, ...partial };
+    const next = { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes, team, piloto, grupo, inicioFeito };
     fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), 'utf8');
     return next;
 }

package/lib/motor/aprovacao.js

@@ -0,0 +1,114 @@
+// Aprovações e perguntas por evento (docs/estrutura.md, seções 3 e 6.7).
+// O motor PEDE emitindo `approval/requested` ou `question/requested` e espera;
+// quem desenha (a tela do app) responde pelo app-server, e o pedido destrava.
+// Node puro, sem dependência. Sem ninguém respondendo, o turno espera: a tela
+// (ou `cancelar()`, no interromper) decide. O padrão de quem cancela é NÃO.
+'use strict';
+
+const { EVENTOS, novoId } = require('./eventos');
+
+const MAX_PERGUNTAS = 4;
+const MAX_OPCOES = 4;
+const NENHUMA = 'Nenhuma dessas';
+
+/* Uma pergunta limpa: texto, até 4 opções com rótulo e descrição curta. */
+function limparPergunta(p) {
+    const opcoes = (Array.isArray(p && p.opcoes) ? p.opcoes : []).slice(0, MAX_OPCOES).map((o) => (
+        typeof o === 'string' ? { rotulo: o } : { rotulo: String((o && o.rotulo) || ''), descricao: o && o.descricao ? String(o.descricao) : undefined }
+    )).filter((o) => o.rotulo);
+    return { pergunta: String((p && p.pergunta) || '').trim(), opcoes };
+}
+
+function criarPortao({ emitir } = {}) {
+    const pend = new Map();        // id → { tipo, resolver, perguntas? }
+    const saida = typeof emitir === 'function' ? emitir : () => {};
+
+    const status = (estado, rotulo) => saida({ evento: EVENTOS.STATUS, id: novoId(), tipo: 'status', estado, rotulo });
+    const esperando = () => status('esperando', 'esperando você');
+    const voltar = () => { if (!pend.size) status('rodando', 'trabalhando'); };
+
+    function fechar(id, estado, extra) {
+        saida({ evento: EVENTOS.ITEM_TERMINOU, id, tipo: pend.get(id).tipo === 'aprovacao' ? 'aprovacao' : 'pergunta', estado, ...(extra || {}) });
+        pend.delete(id);
+        voltar();
+    }
+
+    /* Mesma assinatura do `autorizar` do runAct: (frase, info) → 'agora' | 'sessao' | 'nao'. */
+    function autorizar(frase, info = {}) {
+        const id = novoId();
+        return new Promise((resolver) => {
+            pend.set(id, { tipo: 'aprovacao', resolver });
+            saida({
+                evento: EVENTOS.APROVACAO, id, tipo: 'aprovacao', estado: 'esperando',
+                texto: String(frase || ''), categoria: info.tipo || 'computador',
+                motivo: info.motivo || undefined, primeira: !!info.primeira,
+            });
+            esperando();
+        });
+    }
+
+    /* `perguntas`: até 4, cada uma com até 4 opções (a tela soma "Nenhuma dessas").
+       Resolve com [{ indice, rotulo, nota, nenhuma }] na mesma ordem; nunca rejeita. */
+    function perguntar({ titulo, perguntas } = {}) {
+        const lista = (Array.isArray(perguntas) ? perguntas : []).slice(0, MAX_PERGUNTAS).map(limparPergunta).filter((p) => p.pergunta);
+        if (!lista.length) return Promise.resolve([]);
+        const id = novoId();
+        return new Promise((resolver) => {
+            pend.set(id, { tipo: 'pergunta', resolver, perguntas: lista });
+            saida({
+                evento: EVENTOS.PERGUNTA, id, tipo: 'pergunta', estado: 'esperando',
+                titulo: titulo || undefined, perguntas: lista, nenhuma: NENHUMA,
+            });
+            esperando();
+        });
+    }
+
+    /* A tela respondeu a uma aprovação: { aceitar, recusar, sempre }. */
+    function responderAprovacao(id, r = {}) {
+        const p = pend.get(id);
+        if (!p || p.tipo !== 'aprovacao') return false;
+        const resposta = r.recusar ? 'nao' : r.sempre ? 'sessao' : r.aceitar ? 'agora' : 'nao';
+        fechar(id, resposta === 'nao' ? 'erro' : 'ok', { resposta });
+        p.resolver(resposta);
+        return true;
+    }
+
+    /* A tela respondeu a uma pergunta: respostas = [{ indice | null, nota }]. */
+    function responderPergunta(id, respostas) {
+        const p = pend.get(id);
+        if (!p || p.tipo !== 'pergunta') return false;
+        const lista = Array.isArray(respostas) ? respostas : [];
+        const saidaR = p.perguntas.map((q, i) => {
+            const r = lista[i] || {};
+            const n = Number.isInteger(r.indice) && r.indice >= 0 && r.indice < q.opcoes.length ? r.indice : null;
+            return { indice: n, rotulo: n === null ? NENHUMA : q.opcoes[n].rotulo, nota: r.nota ? String(r.nota).slice(0, 2000) : undefined, nenhuma: n === null };
+        });
+        fechar(id, 'ok', { respostas: saidaR });
+        p.resolver(saidaR);
+        return true;
+    }
+
+    /* Turno interrompido ou terminado: tudo o que esperava resolve como NÃO / nenhuma. */
+    function cancelar() {
+        for (const [id, p] of [...pend]) {
+            fechar(id, 'interrompido');
+            p.resolver(p.tipo === 'aprovacao' ? 'nao' : p.perguntas.map(() => ({ indice: null, rotulo: NENHUMA, nenhuma: true })));
+        }
+    }
+
+    /* mudar_pasta do agente: uma pergunta de sim/não, com "Nenhuma dessas" valendo não. */
+    async function mudarPasta({ caminho, motivo }) {
+        const r = await perguntar({
+            titulo: 'O Primo quer trabalhar em outra pasta',
+            perguntas: [{ pergunta: `Trabalhar em ${caminho} a partir de agora?${motivo ? ` Motivo: ${motivo}` : ''}`,
+                opcoes: [{ rotulo: 'Sim, trocar', descricao: caminho }, { rotulo: 'Não, ficar onde está' }] }],
+        });
+        if (r[0] && r[0].indice === 0) return { ok: true, caminho };
+        try { require('../tool/tools').liberarLeitura(caminho); } catch { /* sem leitura extra */ }
+        return { ok: false };
+    }
+
+    return { autorizar, perguntar, mudarPasta, responderAprovacao, responderPergunta, cancelar, pendentes: () => [...pend.keys()] };
+}
+
+module.exports = { criarPortao, NENHUMA, MAX_PERGUNTAS, MAX_OPCOES };