@skvil/piertotum 1.0.0 → 1.0.2

package/README.md

@@ -1,18 +1,16 @@
 <div align="center">
-  <img src="logo.png" width="150" alt="Skvil-Piertotum logo" />
+  <img src="https://raw.githubusercontent.com/LCGF00/skvil-piertotum/main/logo.png" width="150" alt="Skvil-Piertotum logo" />
 
 # Skvil-Piertotum
 
-[![npm version](https://img.shields.io/npm/v/skvil-piertotum)](https://www.npmjs.com/package/skvil-piertotum)
-[![Node.js](https://img.shields.io/node/v/skvil-piertotum)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/@skvil/piertotum)](https://www.npmjs.com/package/@skvil/piertotum)
+[![Node.js](https://img.shields.io/node/v/@skvil/piertotum)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 **Let your Claude Code instances talk to each other.**
 
 Skvil-Piertotum is a lightweight MCP + HTTP broker that connects multiple Claude Code terminals — across projects, machines, WSL, or VMs — so they can exchange messages, share context, and even delegate tasks autonomously.
 
-</div>
-
 ```
 Claude Code (API project)          Claude Code (Frontend project)
       │                                       │
@@ -29,6 +27,8 @@ Claude Code (API project)          Claude Code (Frontend project)
               └─────────────┘
 ```
 
+</div>
+
 ---
 
 ## How it works
@@ -49,6 +49,12 @@ When `AUTO_PROCESS=true`, the MCP server polls for incoming messages and uses **
 
 **Requirements:** Node.js 18 or later (`node --version` to check).
 
+**Option A — via npm (recommended):**
+```bash
+npm install -g @skvil/piertotum
+```
+
+**Option B — from source:**
 ```bash
 git clone https://github.com/LCGF00/skvil-piertotum
 cd skvil-piertotum
@@ -60,11 +66,17 @@ npm install
 Run this once, on any machine accessible to your terminals:
 
 ```bash
-node broker.js
+# if installed globally:
+skvil-piertotum-broker
+
+# without installing (npx):
+npx --package=@skvil/piertotum skvil-piertotum-broker
+
 # custom port:
-node broker.js 5000
-# or via env:
-BROKER_PORT=5000 node broker.js
+skvil-piertotum-broker 5000
+
+# from source:
+node broker.js
 ```
 
 The broker listens on `0.0.0.0` — reachable from any IP on your network.
@@ -82,7 +94,7 @@ claude mcp add skvil-piertotum \
   -e AGENT_ID=api \
   -e AGENT_NAME="API Project" \
   -e PROJECT_NAME="my-saas" \
-  -- node /path/to/skvil-piertotum/mcp-server.js
+  -- skvil-piertotum-mcp
 
 # Terminal 2 — Frontend project
 claude mcp add skvil-piertotum \
@@ -90,9 +102,12 @@ claude mcp add skvil-piertotum \
   -e AGENT_ID=front \
   -e AGENT_NAME="Frontend Project" \
   -e PROJECT_NAME="my-saas" \
-  -- node /path/to/skvil-piertotum/mcp-server.js
+  -- skvil-piertotum-mcp
 ```
 
+> Not installed globally? Replace `skvil-piertotum-mcp` with:
+> `npx --package=@skvil/piertotum skvil-piertotum-mcp`
+
 If everything is on the same machine, use `BROKER_URL=http://localhost:4800`.
 
 ### 4. Or configure via `~/.claude.json`
@@ -102,8 +117,7 @@ If everything is on the same machine, use `BROKER_URL=http://localhost:4800`.
   "mcpServers": {
     "skvil-piertotum": {
       "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/skvil-piertotum/mcp-server.js"],
+      "command": "skvil-piertotum-mcp",
       "env": {
         "BROKER_URL": "http://192.168.1.10:4800",
         "AGENT_ID": "api",
@@ -265,14 +279,14 @@ Full endpoint reference:
 ```
 POST   /agents/register             Register an agent
 GET    /agents                      List agents
-POST   /agents/:id/heartbeat        Heartbeat (404 if not registered)
-DELETE /agents/:id                  Deregister agent
+POST   /agents/:agentId/heartbeat    Heartbeat (404 if not registered)
+DELETE /agents/:agentId              Deregister agent
 
 POST   /messages/send               Send to one agent
 POST   /messages/broadcast          Send to all agents except sender
-GET    /messages/:id                Read messages (?unread=true, ?limit=N)
-POST   /messages/:id/ack            Mark message IDs as read
-DELETE /messages/:id                Clear all messages
+GET    /messages/:agentId            Read messages (?unread=true, ?limit=N)
+POST   /messages/:agentId/ack       Mark message IDs as read
+DELETE /messages/:agentId            Clear all messages
 
 POST   /context                     Save context entry
 GET    /context                     List context keys
@@ -287,7 +301,7 @@ GET    /status                      Broker overview
 ## Design Notes
 
 - **In-memory only** — all state is lost if the broker restarts. Agents re-register automatically on the next heartbeat (within 30s). For persistence, adapt the broker to use SQLite.
-- **Resource limits** — max 100 agents, 200 messages per queue (oldest dropped), 1000 context keys, 100 KB per context value.
+- **Resource limits** — max 100 agents, 200 messages per queue (oldest dropped), 1000 context keys, 100 KB per context value, 512 KB per message.
 - **Stale agent cleanup** — agents that miss 3 heartbeats (90s) are automatically removed.
 - **Message types** — `text`, `code`, `schema`, `endpoint`, `config`. Used by agents to route and handle responses appropriately.
 - **Prompt injection protection** — in autonomous mode, incoming message content is wrapped in XML tags with a random nonce before being injected into Claude's context.

package/broker.js

@@ -33,7 +33,12 @@ process.on('unhandledRejection', (reason) => {
 const app = express();
 app.use(express.json({ limit: '5mb' }));
 
-const PORT = process.env.BROKER_PORT || process.argv[2] || 4800;
+const _rawPort = process.env.BROKER_PORT || process.argv[2] || 4800;
+const PORT = Number(_rawPort);
+if (!Number.isInteger(PORT) || PORT < 1 || PORT > 65535) {
+  _error(`[ERRO] Porta inválida: "${_rawPort}". Use um número entre 1 e 65535.`);
+  process.exit(1);
+}
 
 // ══════════════════════════════════════════════
 // Limites de recursos
@@ -102,7 +107,8 @@ app.use((req, res, next) => {
     (req.method === 'POST' && req.path.endsWith('/heartbeat'));
   if (!isPolling) {
     const ts = new Date().toLocaleTimeString('pt-BR');
-    console.log(`[${ts}] ${req.method} ${req.path}`);
+    const safePath = req.originalUrl.replace(/[\x00-\x1f\x7f]/g, '');
+    console.log(`[${ts}] ${req.method} ${safePath}`);
   }
   next();
 });
@@ -116,6 +122,9 @@ app.post('/agents/register', (req, res) => {
   if (!agentId || !name) {
     return res.status(400).json({ error: 'agentId e name são obrigatórios' });
   }
+  if (typeof agentId !== 'string' || typeof name !== 'string') {
+    return res.status(400).json({ error: 'agentId e name devem ser strings' });
+  }
 
   if (!agents.has(agentId) && agents.size >= MAX_AGENTS) {
     return res.status(429).json({ error: `Limite de ${MAX_AGENTS} agentes atingido` });
@@ -190,6 +199,9 @@ app.post('/messages/send', (req, res) => {
   if (!from || !to || !content) {
     return res.status(400).json({ error: 'from, to e content são obrigatórios' });
   }
+  if (typeof from !== 'string' || typeof to !== 'string' || typeof content !== 'string') {
+    return res.status(400).json({ error: 'from, to e content devem ser strings' });
+  }
 
   if (!agents.has(from) && from !== 'broker') {
     return res.status(400).json({ error: `Remetente "${from}" não registrado. Registre-se antes de enviar mensagens.` });
@@ -227,6 +239,9 @@ app.post('/messages/broadcast', (req, res) => {
   if (!from || !content) {
     return res.status(400).json({ error: 'from e content são obrigatórios' });
   }
+  if (typeof from !== 'string' || typeof content !== 'string') {
+    return res.status(400).json({ error: 'from e content devem ser strings' });
+  }
 
   if (!agents.has(from) && from !== 'broker') {
     return res.status(400).json({ error: `Remetente "${from}" não registrado. Registre-se antes de enviar mensagens.` });
@@ -261,6 +276,9 @@ app.post('/messages/broadcast', (req, res) => {
 // ?unread=true → apenas não lidas | ?limit=N → máximo N mensagens
 // Não marca como lidas — use POST /messages/:agentId/ack para confirmar recebimento.
 app.get('/messages/:agentId', (req, res) => {
+  if (!agents.has(req.params.agentId)) {
+    return res.status(404).json({ error: `Agente "${req.params.agentId}" não registrado` });
+  }
   const queue = messages.get(req.params.agentId) || [];
   const unreadOnly = req.query.unread === 'true';
   const limit = req.query.limit ? Math.max(1, parseInt(req.query.limit, 10) || 50) : null;
@@ -274,6 +292,9 @@ app.get('/messages/:agentId', (req, res) => {
 
 // ACK — marca mensagens específicas como lidas
 app.post('/messages/:agentId/ack', (req, res) => {
+  if (!agents.has(req.params.agentId)) {
+    return res.status(404).json({ error: `Agente "${req.params.agentId}" não registrado` });
+  }
   const { ids } = req.body;
   if (!Array.isArray(ids) || ids.length === 0) {
     return res.status(400).json({ error: 'ids deve ser um array não-vazio de message IDs' });
@@ -365,6 +386,15 @@ app.use((req, res) => {
   res.status(404).json({ error: `Rota não encontrada: ${req.method} ${req.path}` });
 });
 
+// Error handler — retorna JSON em vez de HTML (ex: body JSON malformado)
+app.use((err, req, res, _next) => {
+  if (err.type === 'entity.parse.failed') {
+    return res.status(400).json({ error: 'JSON inválido no body da requisição' });
+  }
+  _error(`[ERRO] ${err.stack || err.message}`);
+  res.status(err.status || 500).json({ error: 'Erro interno do servidor' });
+});
+
 // ══════════════════════════════════════════════
 // Console interativo do operador
 // ══════════════════════════════════════════════
@@ -454,8 +484,12 @@ function startConsole() {
   });
 
   rl.on('close', () => {
-    _log('\n  Broker encerrado.');
-    process.exit(0);
+    // Quando shutdown() chama rl.close(), o httpServer.close() cuida de sair.
+    // Só sai aqui se o readline fechou por conta própria (Ctrl+D).
+    if (!shuttingDown) {
+      _log('\n  Broker encerrado.');
+      process.exit(0);
+    }
   });
 }
 
@@ -505,7 +539,11 @@ httpServer.on('error', (err) => {
 // Shutdown gracioso (SIGTERM / SIGINT)
 // ══════════════════════════════════════════════
 
+let shuttingDown = false;
+
 const shutdown = () => {
+  if (shuttingDown) return; // evita dupla execução (SIGTERM + SIGINT rápidos)
+  shuttingDown = true;
   _log('\n  🛑 Broker encerrando...');
   if (rl) rl.close();
   httpServer.close(() => {

package/mcp-server.js

@@ -19,6 +19,15 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import os from 'os';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION = (() => {
+  try { return JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8')).version; }
+  catch { return '0.0.0'; }
+})();
 
 // ══════════════════════════════════════════════
 // Validação de configuração na inicialização
@@ -38,7 +47,7 @@ function validateBrokerUrl(raw) {
   }
 }
 
-const BROKER_URL   = validateBrokerUrl(process.env.BROKER_URL || 'http://localhost:4800');
+const BROKER_URL   = validateBrokerUrl(process.env.BROKER_URL || 'http://localhost:4800').replace(/\/+$/, '');
 const AGENT_ID     = process.env.AGENT_ID || os.hostname().toLowerCase().replace(/[^a-z0-9-]/g, '-');
 const AGENT_NAME   = process.env.AGENT_NAME || `SP-${AGENT_ID}`;
 const PROJECT_NAME = process.env.PROJECT_NAME || 'unknown';
@@ -99,7 +108,11 @@ async function brokerFetch(path, options = {}) {
       try { body = await res.json(); } catch { body = {}; }
       return { error: body.error || `HTTP ${res.status} ${res.statusText}` };
     }
-    return await res.json();
+    try {
+      return await res.json();
+    } catch {
+      return { error: `Resposta inválida do broker (não é JSON) em ${path}` };
+    }
   } catch (err) {
     if (err.name === 'TimeoutError') {
       return { error: `Broker não respondeu em ${FETCH_TIMEOUT_MS / 1000}s` };
@@ -149,7 +162,7 @@ async function register() {
 
 const server = new McpServer({
   name: 'skvil-piertotum',
-  version: '1.0.0',
+  version: PKG_VERSION,
   description: 'Comunicação entre instâncias do Claude Code via broker central'
 });
 
@@ -298,7 +311,10 @@ server.tool(
     // Marca as mensagens lidas explicitamente (ACK)
     const ids = result.messages.map(m => m.id).filter(Boolean);
     if (ids.length > 0) {
-      await brokerPost(`/messages/${AGENT_ID}/ack`, { ids });
+      const ackResult = await brokerPost(`/messages/${AGENT_ID}/ack`, { ids });
+      if (ackResult.error) {
+        process.stderr.write(`⚠️  ACK falhou: ${ackResult.error}\n`);
+      }
     }
 
     const lines = result.messages.map(m =>
@@ -356,7 +372,7 @@ server.tool(
     key: z.string().describe('Chave do contexto a ler (ex: "api-endpoints")')
   },
   async ({ key }) => {
-    const result = await brokerFetch(`/context/${key}`);
+    const result = await brokerFetch(`/context/${encodeURIComponent(key)}`);
 
     if (result.error) {
       return { content: [{ type: 'text', text: `❌ ${result.error}` }] };
@@ -583,7 +599,7 @@ async function processMessage(msg) {
 
     const responseText = sampling.content.type === 'text'
       ? sampling.content.text
-      : JSON.stringify(sampling.content);
+      : `[resposta não-texto do tipo "${sampling.content.type}" — não suportada pelo modo autônomo]`;
 
     // Envia resposta de volta ao remetente
     if (canReply) {
@@ -642,11 +658,17 @@ async function pollAndProcess() {
 
     // Processa uma mensagem por vez, em ordem; ACK individual após cada processamento
     for (const msg of result.messages) {
-      await processMessage(msg);
-      if (!autoProcessEnabled) break; // sampling falhou — não ACK nem continua o batch
+      try {
+        await processMessage(msg);
+      } catch (err) {
+        // ACK mesmo em erro para evitar poison message loop (retry infinito)
+        process.stderr.write(`⚠️  Erro ao processar mensagem ${msg.id}: ${err.message}\n`);
+      }
+      // ACK sempre — inclusive se processMessage falhou (evita poison loop)
       if (msg.id) {
         await brokerPost(`/messages/${AGENT_ID}/ack`, { ids: [msg.id] });
       }
+      if (!autoProcessEnabled) break; // sampling falhou — não continua o batch
     }
   } finally {
     isProcessing = false;
@@ -656,8 +678,10 @@ async function pollAndProcess() {
 function startAutonomousMode() {
   if (pollTimer) return; // já rodando
   process.stderr.write(`🤖 Modo autônomo ativado — polling a cada ${POLL_INTERVAL_MS / 1000}s\n`);
-  pollAndProcess(); // primeiro poll imediato — não espera o intervalo completo
-  pollTimer = setInterval(pollAndProcess, POLL_INTERVAL_MS);
+  pollAndProcess().catch(err => process.stderr.write(`⚠️  Erro no poll inicial: ${err.message}\n`));
+  pollTimer = setInterval(() => {
+    pollAndProcess().catch(err => process.stderr.write(`⚠️  Erro no poll: ${err.message}\n`));
+  }, POLL_INTERVAL_MS);
 }
 
 // ══════════════════════════════════════════════
@@ -709,7 +733,10 @@ async function main() {
   }, 30000);
 
   // Shutdown gracioso — aguarda processamento em andamento antes de sair
+  let shuttingDown = false;
   const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     clearInterval(heartbeatTimer);
     if (pollTimer) clearInterval(pollTimer);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skvil/piertotum",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP + HTTP broker for multi-instance Claude Code communication",
   "type": "module",
   "license": "MIT",
@@ -10,6 +10,9 @@
     "type": "git",
     "url": "git+https://github.com/LCGF00/skvil-piertotum.git"
   },
+  "bugs": {
+    "url": "https://github.com/LCGF00/skvil-piertotum/issues"
+  },
   "keywords": [
     "mcp",
     "claude",
@@ -28,7 +31,8 @@
     "broker.js",
     "mcp-server.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "logo.png"
   ],
   "bin": {
     "skvil-piertotum-broker": "broker.js",