primocode 11.1.0 → 11.3.0

package/README.md

@@ -1,4 +1,4 @@
-# PrimoCode v11.1.0
+# PrimoCode v11.3.0
 
 Agente de engenharia brasileiro para o terminal, no estilo Claude Code.
 Cria arquivos de verdade, roda comandos, **controla o navegador e o desktop** —
@@ -9,7 +9,7 @@ OpenRouter, e cada apelido (`top`/`main`/`fast`) é uma **corrente**: se um mode
 está no limite de pedidos, o próximo atende. Você não vê o erro, e não paga nada.
 
 ```
- ▐▛███▜▌   Primo Code v11.1.0
+ ▐▛███▜▌   Primo Code v11.3.0
 ▝▜█████▛▘  Bem-vindo de volta, Joel
   ▘▘ ▝▝    ~/primocode  · /dir <pasta> muda
 ```
@@ -17,6 +17,20 @@ está no limite de pedidos, o próximo atende. Você não vê o erro, e não pag
 Personalize o mascote (`primo`, `fox`, `cat`) e o nome com que ele te chama —
 veja `/mascot` e `/name`.
 
+## Novidades da 11.2
+
+- **App desktop (Electron)** com a mesma tela do protótipo: conversa, Estúdio, projetos, agentes, kit da marca, avisos e busca. Ele sobe o motor sozinho e fala com ele pelo `app-server` (JSON-RPC). `primocode app` abre o app instalado; no repo, `npm run app:dev`.
+- **Celular (Android):** `primocode server --rede` e a tela **Parear celular** geram um QR com token revogável. O app do celular (`mobile/`, Capacitor) usa o mesmo motor do computador. APK de teste: `npm run mobile:build`.
+- **Motor reescrito em módulos** (`lib/motor/`, `lib/app-server/`), com turno, aprovação, voz e piloto automático. A CLI ganhou `/estudio`, `/agentes`, `/piloto`, `/avisos` e `/buscar`.
+- **Primeira execução:** uma tela só, pulável (nome, esforço, kit da marca). Poppins vai embutida, sem fonte remota.
+
+### App e celular, em duas linhas
+
+```
+npm run app:dev      # desktop (precisa de `cd app && npm install` uma vez)
+npm run mobile:build # APK debug (JDK 17 e Android SDK)
+```
+
 ## Primo (voz)
 
 `/voice` abre a tela do Primo: agenda, clima, música, máquina e um robô 3D no centro. Diga **"Primo"** para chamar; ele fala frase a frase e você pode interromper. Na primeira vez cria `~/.primocode/voz-venv` sozinho (`primocode doutor` mostra o estado). Robô offline: `"robo":"expressive"` em `~/.primocode/voz.json`.

package/bin/primocode-rpc.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Cliente de linha de comando para testar o app-server.
+//   primocode-rpc [--ws [porta] | --stdio] <método> ['{"json":"params"}']
+// stdio (padrão) sobe `primocode server` como filho. --ws lê porta e token de
+// ~/.primocode/app-server.json. Imprime cada notificação até turn/completed
+// (ou turn/interrupted). Para métodos sem turno, imprime a resposta e sai.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const net = require('net');
+const { spawn } = require('child_process');
+const P = require('../lib/app-server/protocolo');
+
+const args = process.argv.slice(2);
+let modo = 'stdio';
+let portaWs = null;
+const resto = [];
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--stdio') modo = 'stdio';
+    else if (args[i] === '--ws') { modo = 'ws'; if (/^\d+$/.test(args[i + 1] || '')) portaWs = Number(args[++i]); }
+    else resto.push(args[i]);
+}
+const [metodo, paramsBruto] = resto;
+if (!metodo) { console.error('Uso: primocode-rpc [--ws [porta] | --stdio] <método> [\'{"json":"params"}\']'); process.exit(1); }
+let params = {};
+try { if (paramsBruto) params = JSON.parse(paramsBruto); } catch { console.error('params não é JSON válido'); process.exit(1); }
+
+const FIM = new Set(['turn/completed', 'turn/interrupted']);
+
+let sair = () => process.exit(0);
+
+function aoLinha(linha) {
+    const r = P.interpretar(linha);
+    if (r.vazio) return;
+    const msg = r.msg || r.resposta;
+    if (!msg) return;
+    console.log(JSON.stringify(msg));
+    if (msg.method && FIM.has(msg.method)) sair();
+    else if (msg.id === 1) {
+        if (msg.error || !(metodo === 'turn/start')) sair();
+        else { /* espera as notificações do turno */ }
+    }
+}
+
+const pedido = P.serializar({ jsonrpc: '2.0', id: 1, method: metodo, params });
+
+if (modo === 'stdio') {
+    const filho = spawn(process.execPath, [path.join(__dirname, 'primocode.js'), 'server', '--stdio'], { stdio: ['pipe', 'pipe', 'inherit'] });
+    const corta = P.cortador();
+    filho.stdout.setEncoding('utf8');
+    filho.stdout.on('data', (d) => { for (const l of corta.push(d)) aoLinha(l); });
+    sair = () => { filho.kill(); process.exit(0); };
+    filho.stdin.write(pedido);
+} else {
+    let info;
+    try { info = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.primocode', 'app-server.json'), 'utf8')); }
+    catch { console.error('Sem ~/.primocode/app-server.json: suba antes `primocode server --ws`.'); process.exit(1); }
+    const porta = portaWs || info.porta;
+    const sock = net.connect(porta, '127.0.0.1');
+    const chave = crypto.randomBytes(16).toString('base64');
+    sock.write(`GET /?token=${info.token} HTTP/1.1\r\nHost: 127.0.0.1:${porta}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n`
+        + `Sec-WebSocket-Key: ${chave}\r\nSec-WebSocket-Version: 13\r\n\r\n`);
+    let buf = Buffer.alloc(0);
+    let aberto = false;
+    const mascarar = (t) => {
+        const corpo = Buffer.from(t, 'utf8');
+        const m = crypto.randomBytes(4);
+        const cab = corpo.length < 126 ? Buffer.from([0x81, 0x80 | corpo.length])
+            : (() => { const h = Buffer.alloc(4); h[0] = 0x81; h[1] = 0x80 | 126; h.writeUInt16BE(corpo.length, 2); return h; })();
+        return Buffer.concat([cab, m, Buffer.from(corpo.map((b, i) => b ^ m[i % 4]))]);
+    };
+    sair = () => { try { sock.destroy(); } catch { /* já fechou */ } process.exit(0); };
+    sock.on('data', (d) => {
+        buf = Buffer.concat([buf, d]);
+        if (!aberto) {
+            const fim = buf.indexOf('\r\n\r\n');
+            if (fim < 0) return;
+            if (!/^HTTP\/1\.1 101/.test(buf.toString('latin1', 0, fim))) { console.error('Recusado: ' + buf.toString('latin1', 0, fim).split('\r\n')[0]); process.exit(1); }
+            buf = buf.subarray(fim + 4);
+            aberto = true;
+            sock.write(mascarar(pedido));
+        }
+        for (;;) {
+            if (buf.length < 2) return;
+            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; n = Number(buf.readBigUInt64BE(2)); pos = 10; }
+            if (buf.length < pos + n) return;
+            const op = buf[0] & 0x0f;
+            const corpo = buf.subarray(pos, pos + n).toString('utf8');
+            buf = buf.subarray(pos + n);
+            if (op === 0x1) aoLinha(corpo);
+            else if (op === 0x8) process.exit(0);
+        }
+    });
+    sock.on('error', (e) => { console.error('Erro: ' + e.message); process.exit(1); });
+}

package/lib/agentes-pessoais.js

@@ -0,0 +1,120 @@
+// Agentes: um arquivo por agente em ~/.primocode/agentes/<nome>.md, com frontmatter
+// (nome, descricao, icone, cor, onde, ligado) e o texto do ofício. docs/estrutura.md, seções 7 e 9.
+// Node puro. `onde`: "fora" (fora de projetos) ou o id de um projeto.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ICONES = ['workflow', 'film', 'palette', 'pen', 'folder', 'shield', 'bell', 'sliders', 'home', 'scan-search', 'flask-conical', 'git-branch', 'pen-line', 'scissors', 'captions', 'trending-up', 'send', 'sparkles'];
+const hexOk = (h) => /^#[0-9a-f]{6}$/i.test(String(h || ''));
+const pasta = (dir) => dir || process.env.PRIMOCODE_AGENTES || path.join(os.homedir(), '.primocode', 'agentes');
+
+function slug(n) {
+    return String(n || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32);
+}
+
+function ler(nome, { dir } = {}) {
+    const s = slug(nome);
+    if (!s) return null;
+    let txt;
+    try { txt = fs.readFileSync(path.join(pasta(dir), `${s}.md`), 'utf8'); } catch { return null; }
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(txt);
+    const f = {};
+    if (m) for (const l of m[1].split('\n')) { const i = l.indexOf(':'); if (i > 0) f[l.slice(0, i).trim()] = l.slice(i + 1).trim(); }
+    return {
+        nome: s, titulo: f.nome || s, descricao: f.descricao || '',
+        icone: ICONES.includes(f.icone) ? f.icone : 'workflow', cor: hexOk(f.cor) ? f.cor : '#22d3ee',
+        onde: f.onde || 'fora', ligado: f.ligado === 'true', oficio: (m ? m[2] : txt).trim(),
+    };
+}
+
+const uma = (v) => String(v == null ? '' : v).replace(/\s+/g, ' ').trim();
+
+function gravar(a, dir) {
+    const d = pasta(dir);
+    fs.mkdirSync(d, { recursive: true });
+    const txt = `---\nnome: ${uma(a.titulo)}\ndescricao: ${uma(a.descricao)}\nicone: ${a.icone}\ncor: ${a.cor}\nonde: ${uma(a.onde) || 'fora'}\nligado: ${a.ligado ? 'true' : 'false'}\n---\n${a.oficio.trim()}\n`;
+    fs.writeFileSync(path.join(d, `${a.nome}.md`), txt);
+    return ler(a.nome, { dir });
+}
+
+function listar({ dir } = {}) {
+    let nomes = [];
+    try { nomes = fs.readdirSync(pasta(dir)).filter((n) => n.endsWith('.md')); } catch { /* ainda não há */ }
+    /* Na ordem em que foram criados (o arquivo mais antigo primeiro); empate por nome. */
+    const nasc = (n) => { try { return fs.statSync(path.join(pasta(dir), n)).birthtimeMs; } catch { return 0; } };
+    return nomes.map((n) => ({ n, t: nasc(n) })).sort((a, b) => a.t - b.t || a.n.localeCompare(b.n))
+        .map(({ n }) => ler(n.slice(0, -3), { dir })).filter(Boolean);
+}
+
+function validar(c, atual) {
+    const a = { ...(atual || { icone: 'workflow', cor: '#22d3ee', onde: 'fora', ligado: false, descricao: '', oficio: '' }) };
+    if ('nome' in c && !atual) { a.titulo = uma(c.nome).slice(0, 60); a.nome = slug(c.nome); }
+    if (!atual && !a.nome) throw new Error('falta o nome (letras e números)');
+    if ('titulo' in c && atual) a.titulo = uma(c.titulo).slice(0, 60) || a.titulo;
+    if (!a.titulo) a.titulo = a.nome;
+    if ('descricao' in c) a.descricao = uma(c.descricao).slice(0, 200);
+    if ('icone' in c && c.icone) { if (!ICONES.includes(c.icone)) throw new Error(`ícone inválido (use: ${ICONES.join(', ')})`); a.icone = c.icone; }
+    if ('cor' in c && c.cor) { if (!hexOk(c.cor)) throw new Error('cor inválida (use #rrggbb)'); a.cor = String(c.cor).toLowerCase(); }
+    if ('onde' in c) a.onde = uma(c.onde) || 'fora';
+    if ('ligado' in c) a.ligado = c.ligado === true;
+    if ('oficio' in c) a.oficio = String(c.oficio || '').slice(0, 4000);
+    if (!a.oficio.trim()) throw new Error('falta o ofício (o que o agente faz)');
+    return a;
+}
+
+function criar(c, { dir } = {}) {
+    const a = validar(c, null);
+    if (ler(a.nome, { dir })) throw new Error(`já existe o agente @${a.nome}`);
+    return gravar(a, dir);
+}
+function atualizar(nome, c, { dir } = {}) {
+    const atual = ler(nome, { dir });
+    if (!atual) throw new Error(`não achei o agente ${nome}`);
+    return gravar(validar(c, atual), dir);
+}
+function alternar(nome, ligado, { dir } = {}) {
+    const atual = ler(nome, { dir });
+    if (!atual) throw new Error(`não achei o agente ${nome}`);
+    return gravar({ ...atual, ligado: typeof ligado === 'boolean' ? ligado : !atual.ligado }, dir);
+}
+function apagar(nome, { dir } = {}) {
+    const s = slug(nome);
+    if (!s || !ler(s, { dir })) throw new Error(`não achei o agente ${nome}`);
+    fs.unlinkSync(path.join(pasta(dir), `${s}.md`));
+    return { nome: s, apagado: true };
+}
+
+/* Os @agente do texto (ligados ou não) e os que a tela mandou explicitamente. */
+function mencionados(texto, extras = [], { dir } = {}) {
+    const todos = listar({ dir });
+    const vistos = new Set();
+    for (const m of String(texto || '').matchAll(/(?:^|[\s(])@([\w-]{1,32})/g)) vistos.add(slug(m[1]));
+    for (const e of Array.isArray(extras) ? extras : []) vistos.add(slug(e));
+    return todos.filter((a) => vistos.has(a.nome));
+}
+
+/* O texto que entra no pedido: chamada explícita (@) manda; os ligados vão de cardápio, curtos.
+   O plano grátis conta idas ao modelo: o modelo só chama quem o pedido pede. */
+function instrucao(texto, extras = [], { dir } = {}) {
+    const chamados = mencionados(texto, extras, { dir });
+    const nomes = new Set(chamados.map((a) => a.nome));
+    const ligados = listar({ dir }).filter((a) => a.ligado && !nomes.has(a.nome));
+    const linhas = [];
+    for (const a of chamados) {
+        linhas.push(`A pessoa chamou @${a.nome} (${a.descricao || 'agente dela'}). Chame spawn_agent com agente: "${a.nome}" e, em prompt, o pedido dela completo.`);
+    }
+    if (ligados.length) {
+        linhas.push('Agentes ligados da pessoa (chame com spawn_agent agente:"<nome>" SÓ se o pedido casa com o ofício; nenhum, se não casar):\n'
+            + ligados.map((a) => `- ${a.nome}: ${a.descricao || a.oficio.slice(0, 80)}`).join('\n'));
+    }
+    return { texto: linhas.join('\n'), chamados };
+}
+
+/* O briefing que vai na frente da tarefa do subagente (molde de lib/especialistas.js). */
+const comoEspecialista = (a) => ({ nome: a.nome, faz: a.descricao, briefing: `Você é o agente @${a.nome}. Seu ofício:\n${a.oficio}` });
+
+module.exports = { ICONES, slug, ler, listar, criar, atualizar, alternar, apagar, mencionados, instrucao, comoEspecialista };

package/lib/app-server/cli.js

@@ -0,0 +1,64 @@
+// `primocode server [--stdio | --ws [porta] [--rede]]` — sobe o app-server local.
+// stdio é o padrão: stdout fica só para o JSON-RPC, avisos vão para stderr.
+'use strict';
+
+const { criarServidor } = require('./servidor');
+
+async function main(args) {
+    const i = args.indexOf('--ws');
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log([
+            'Uso: primocode server [--stdio | --ws [porta] [--rede]]',
+            '       primocode server --pareamentos | --revogar <id>',
+            '  --stdio  JSON-RPC em linhas no stdin/stdout (padrão)',
+            '  --ws     WebSocket em 127.0.0.1 (porta livre se omitida); porta e token em ~/.primocode/app-server.json',
+            '  --rede   (com --ws) escuta na rede local, para parear um celular. Só quem tem um token de pareamento entra;',
+            '           o token de sessão continua valendo só neste computador. Sem --rede, nada sai de 127.0.0.1.',
+            '  --pareamentos       lista os celulares pareados (sem mostrar token)',
+            '  --revogar <id>      revoga um pareamento (vale na hora, mesmo com o servidor rodando)',
+        ].join('\n'));
+        return 0;
+    }
+    if (args.includes('--pareamentos') || args.includes('--revogar')) {
+        const P = require('./pareamento').criarPareamentos({ arquivo: require('path').join(require('../config/config').CONFIG_DIR, 'pareamentos.json') });
+        const k = args.indexOf('--revogar');
+        if (k >= 0) {
+            const id = args[k + 1] || '';
+            if (!P.revogar(id)) { console.error(`não existe o pareamento "${id}"`); return 1; }
+            console.log(`pareamento ${id} revogado`);
+            return 0;
+        }
+        const lista = P.listar();
+        if (!lista.length) console.log('nenhum celular pareado');
+        for (const r of lista) console.log(`${r.id}  ${r.nome}  criado ${new Date(r.criado).toLocaleString('pt-BR')}  último uso ${r.ultimoUso ? new Date(r.ultimoUso).toLocaleString('pt-BR') : 'nunca'}`);
+        return 0;
+    }
+    if (args.includes('--rede') && i < 0) { console.error('--rede só vale com --ws.'); return 1; }
+    if (i >= 0 && args.includes('--stdio')) { console.error('Use --stdio ou --ws, não os dois.'); return 1; }
+    // PRIMOCODE_MOTOR_FALSO=<arquivo.js>: um motor de mentira (sem rede), para testar a tela.
+    const falso = process.env.PRIMOCODE_MOTOR_FALSO;
+    // PRIMOCODE_CONTA_FALSA=<arquivo.js>: { buscar, abrir } de mentira para o login (sem rede, sem navegador). Só para teste.
+    const contaFalsa = process.env.PRIMOCODE_CONTA_FALSA;
+    // PRIMOCODE_TRANSCRITOR_FALSO=<arquivo.js>: async (wav) => ({ ok, texto }) no lugar do Whisper local. Só para teste de tela.
+    const transcritorFalso = process.env.PRIMOCODE_TRANSCRITOR_FALSO;
+    const srv = criarServidor({
+        ...(transcritorFalso ? { transcritor: require(require('path').resolve(transcritorFalso)) } : {}),
+        ...(falso ? { motor: require(require('path').resolve(falso)) } : {}),
+        ...(contaFalsa ? { conta: require(require('path').resolve(contaFalsa)) } : {}),
+    });
+    if (i >= 0) {
+        const pedida = /^\d+$/.test(args[i + 1] || '') ? Number(args[i + 1]) : 0;
+        const rede = args.includes('--rede');
+        const { porta } = await srv.ws({ porta: pedida, rede });
+        console.error(`app-server em ws://127.0.0.1:${porta}  (token em ${srv.arquivoInfo})`);
+        if (rede) console.error('modo --rede: escutando na rede local; só entra celular com token de pareamento (tela "Parear celular")');
+        const sair = () => srv.fechar().then(() => process.exit(0));
+        process.on('SIGINT', sair);
+        process.on('SIGTERM', sair);
+        return new Promise(() => {});   // roda até o sinal
+    }
+    srv.stdio(process.stdin, process.stdout);
+    return new Promise((resolve) => process.stdin.on('end', () => resolve(0)));
+}
+
+module.exports = { main };

package/lib/app-server/enderecos.js

@@ -0,0 +1,43 @@
+// Endereços do computador para o pareamento do celular, na ordem em que valem a pena tentar.
+// Achado (02/11): com VPN (Tailscale, 100.64.0.0/10) a lista vinha com o IP da VPN primeiro, o QR levava só ele e o celular
+// no Wi-Fi não alcançava. Agora a rede local (192.168/16, 10/8, 172.16/12) vem antes, a VPN e os túneis por último,
+// e o código do QR leva TODOS (o app do celular tenta um por um).
+'use strict';
+
+const partes = (ip) => String(ip).split('.').map(Number);
+
+/* 0 = LAN doméstica/escritório (melhor), 1 = outro endereço roteável, 2 = VPN/túnel/link-local (último recurso). */
+function classe(ip, nome = '') {
+    const [a, b] = partes(ip);
+    if (/^(utun|tun|tap|ppp|ipsec|wg|tailscale|zt|vpn)/i.test(String(nome)) || /tailscale|zerotier|wireguard/i.test(String(nome))) return 2;
+    if (a === 100 && b >= 64 && b <= 127) return 2;      // CGNAT 100.64.0.0/10: Tailscale e afins
+    if (a === 169 && b === 254) return 2;                // link-local
+    if (a === 192 && b === 168) return 0;
+    if (a === 10) return 0;
+    if (a === 172 && b >= 16 && b <= 31) return 0;
+    return 1;
+}
+const peso = (ip) => { const [a, b] = partes(ip); return a === 192 && b === 168 ? 0 : a === 10 ? 1 : a === 172 ? 2 : 3; };
+
+/* `itens`: [{ ip, nome? }] ou ['ip', ...]. Estável e sem repetição. */
+function ordenar(itens) {
+    const lista = [];
+    const vistos = new Set();
+    for (const x of itens || []) {
+        const ip = typeof x === 'string' ? x : x && x.ip;
+        if (!ip || vistos.has(ip) || !/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) continue;
+        vistos.add(ip);
+        lista.push({ ip, nome: typeof x === 'string' ? '' : x.nome || '', i: lista.length });
+    }
+    lista.sort((p, q) => (classe(p.ip, p.nome) - classe(q.ip, q.nome)) || (peso(p.ip) - peso(q.ip)) || (p.i - q.i));
+    return lista.map((x) => x.ip);
+}
+
+/* Os IPv4 externos das interfaces, já ordenados. */
+function locais(interfaces) {
+    const itens = [];
+    for (const [nome, lista] of Object.entries(interfaces || {})) for (const i of lista || []) if (i.family === 'IPv4' && !i.internal) itens.push({ ip: i.address, nome });
+    return ordenar(itens);
+}
+
+module.exports = { ordenar, locais, classe };

package/lib/app-server/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = { ...require('./servidor'), protocolo: require('./protocolo'), websocket: require('./websocket') };

package/lib/app-server/pareamento.js

@@ -0,0 +1,61 @@
+// Pareamento do celular (docs/estrutura.md, seção 15). Cada celular tem um token PRÓPRIO, separado do
+// token de sessão do motor: dá para listar quem está pareado e revogar um sem derrubar o resto.
+// Só o hash SHA-256 fica no disco (`pareamentos.json`, 0600); o token aparece uma única vez, na criação.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const PREFIXO = 'pcp_';
+const hash = (t) => crypto.createHash('sha256').update(String(t)).digest('hex');
+
+function criarPareamentos({ arquivo }) {
+    function ler() {
+        try { const d = JSON.parse(fs.readFileSync(arquivo, 'utf8')); return Array.isArray(d.pareamentos) ? d.pareamentos : []; } catch { return []; }
+    }
+    function gravar(lista) {
+        fs.mkdirSync(path.dirname(arquivo), { recursive: true });
+        fs.writeFileSync(arquivo, JSON.stringify({ pareamentos: lista }, null, 2), { mode: 0o600 });
+        try { fs.chmodSync(arquivo, 0o600); } catch { /* sem chmod */ }
+    }
+    const publico = (r) => ({ id: r.id, nome: r.nome, criado: r.criado, ultimoUso: r.ultimoUso || null });
+
+    return {
+        /* Gera o token e guarda só o hash. O token volta aqui e em nenhum outro lugar. */
+        criar(nome) {
+            const token = PREFIXO + crypto.randomBytes(24).toString('hex');
+            const r = { id: crypto.randomBytes(4).toString('hex'), nome: String(nome || '').trim().slice(0, 60) || 'Celular', criado: Date.now(), ultimoUso: null, hash: hash(token) };
+            gravar([...ler(), r]);
+            return { ...publico(r), token };
+        },
+        listar() { return ler().map(publico); },
+        revogar(id) {
+            const lista = ler();
+            const resto = lista.filter((r) => r.id !== id);
+            if (resto.length === lista.length) return false;
+            gravar(resto);
+            return true;
+        },
+        /* O registro público de quem tem esse token, ou null. Relê o arquivo: revogar de fora vale na hora. */
+        validar(token) {
+            const t = String(token || '');
+            if (!t.startsWith(PREFIXO)) return null;
+            const h = Buffer.from(hash(t));
+            for (const r of ler()) {
+                const o = Buffer.from(String(r.hash || ''));
+                if (o.length === h.length && crypto.timingSafeEqual(o, h)) return publico(r);
+            }
+            return null;
+        },
+        marcarUso(id) {
+            const lista = ler();
+            const r = lista.find((x) => x.id === id);
+            if (!r || Date.now() - (r.ultimoUso || 0) < 30000) return;
+            r.ultimoUso = Date.now();
+            try { gravar(lista); } catch { /* sem gravar o uso */ }
+        },
+    };
+}
+
+module.exports = { criarPareamentos, PREFIXO };

package/lib/app-server/protocolo.js

@@ -0,0 +1,86 @@
+// JSON-RPC 2.0 em linhas (NDJSON). Só texto: parse, montagem e erros padrão.
+// Node puro, sem dependência. Contrato em docs/estrutura.md, seção 3.
+'use strict';
+
+const ERRO = Object.freeze({
+    PARSE: -32700,
+    PEDIDO_INVALIDO: -32600,
+    METODO: -32601,
+    PARAMS: -32602,
+    INTERNO: -32603,
+    // Faixa livre do JSON-RPC (-32000..-32099): erros do PrimoCode.
+    OCUPADO: -32000,
+    NAO_ACHEI: -32001,
+    NEGADO: -32002,
+    AINDA_NAO: -32003,
+});
+
+const MENSAGEM = Object.freeze({
+    [ERRO.PARSE]: 'JSON inválido',
+    [ERRO.PEDIDO_INVALIDO]: 'Pedido inválido',
+    [ERRO.METODO]: 'Método não existe',
+    [ERRO.PARAMS]: 'Parâmetros inválidos',
+    [ERRO.INTERNO]: 'Erro interno',
+});
+
+/* Erro com código, para os métodos lançarem: throw erro(ERRO.PARAMS, 'falta texto'). */
+function erro(codigo, mensagem, data) {
+    const e = new Error(mensagem || MENSAGEM[codigo] || 'Erro');
+    e.codigo = codigo;
+    if (data !== undefined) e.data = data;
+    return e;
+}
+
+/* Error não vira JSON sozinho (sai `{}`): troca por { mensagem }. */
+function substituto(_chave, valor) {
+    if (valor instanceof Error) return { mensagem: valor.message, nome: valor.name };
+    if (typeof valor === 'bigint') return String(valor);
+    return valor;
+}
+
+const serializar = (obj) => JSON.stringify(obj, substituto) + '\n';
+
+const resposta = (id, resultado) => ({ jsonrpc: '2.0', id, result: resultado === undefined ? null : resultado });
+const respostaErro = (id, codigo, mensagem, data) => {
+    const error = { code: codigo, message: mensagem || MENSAGEM[codigo] || 'Erro' };
+    if (data !== undefined) error.data = data;
+    return { jsonrpc: '2.0', id: id === undefined ? null : id, error };
+};
+const notificacao = (method, params) => ({ jsonrpc: '2.0', method, params });
+
+/* Uma linha → { msg } ou { erro: <resposta de erro pronta> }.
+   Aceita pedido (com id) e notificação (sem id). Lote ([...]) não é suportado. */
+function interpretar(linha) {
+    const texto = String(linha || '').trim();
+    if (!texto) return { vazio: true };
+    let msg;
+    try { msg = JSON.parse(texto); } catch { return { erro: respostaErro(null, ERRO.PARSE) }; }
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg) || msg.jsonrpc !== '2.0') {
+        return { erro: respostaErro(msg && msg.id, ERRO.PEDIDO_INVALIDO, 'Pedido inválido (precisa de jsonrpc "2.0", sem lote)') };
+    }
+    if (typeof msg.method !== 'string' || !msg.method) {
+        // Respostas do cliente (id sem method) não são pedido: ignoradas pelo servidor.
+        if ('id' in msg && ('result' in msg || 'error' in msg)) return { resposta: msg };
+        return { erro: respostaErro(msg.id, ERRO.PEDIDO_INVALIDO, 'Falta "method"') };
+    }
+    if (msg.params !== undefined && (msg.params === null || typeof msg.params !== 'object')) {
+        return { erro: respostaErro(msg.id, ERRO.PARAMS, 'params precisa ser objeto') };
+    }
+    return { msg };
+}
+
+/* Corta um fluxo de bytes em linhas inteiras. push(texto) devolve as linhas completas. */
+function cortador() {
+    let resto = '';
+    return {
+        push(pedaco) {
+            resto += pedaco;
+            const partes = resto.split('\n');
+            resto = partes.pop();
+            return partes;
+        },
+        sobra: () => resto,
+    };
+}
+
+module.exports = { ERRO, erro, serializar, resposta, respostaErro, notificacao, interpretar, cortador };