@justmpm/comunicate 0.1.0

package/AGENTS.md

@@ -0,0 +1,518 @@
+# @justmpm/comunicate - Guia Completo
+
+Sistema de Comunicação Entre Agentes usando arquivos JSON locais (File-Based Architecture) otimizado para Windows.
+
+---
+
+## 📋 Índice
+
+1. [Visão Geral](#visão-geral)
+2. [Arquitetura](#arquitetura)
+3. [Instalação](#instalação)
+4. [Configuração](#configuração)
+5. [Tools MCP](#tools-mcp)
+6. [Fluxos de Trabalho](#fluxos-de-trabalho)
+7. [CLI](#cli)
+8. [Exemplos](#exemplos)
+9. [Segurança](#segurança)
+10. [Troubleshooting](#troubleshooting)
+
+---
+
+## Visão Geral
+
+O **@justmpm/comunicate** é um servidor MCP (Model Context Protocol) que permite comunicação entre múltiplos agentes através de arquivos JSON locais.
+
+### Por que File-Based?
+
+- ✅ **Zero dependências** - Sem banco de dados ou servidor externo
+- ✅ **Portátil** - Viaja com o projeto (controle de versão)
+- ✅ **Debug fácil** - Arquivos JSON human-readable
+- ✅ **No-lock** - Cada agente escreve apenas no seu próprio arquivo
+- ✅ **Otimizado Windows** - File system nativo
+
+### Conceitos Fundamentais
+
+| Conceito | Descrição |
+|----------|-----------|
+| **Agente** | Entidade que pode enviar/receber mensagens |
+| **Inbox** | Caixa de entrada exclusiva de cada agente |
+| **Domínio** | Diretórios que um agente pode editar naturalmente |
+| **Claim** | Reserva temporária de arquivo fora do domínio |
+| **Heartbeat** | Sinal de vida do agente |
+
+---
+
+## Arquitetura
+
+```
+.comunicate/
+├── registry/
+│   ├── agents.json       # Registro de agentes (com heartbeat)
+│   ├── tasks.json        # Tarefas
+│   └── claims.json       # Arquivos reservados (com sequence)
+├── messages/
+│   ├── inbox-*.json      # Caixas de entrada
+│   └── archive/          # Mensagens arquivadas (gzip)
+└── context/
+    ├── api-contracts.json
+    ├── decisions.json
+    └── progress.json
+```
+
+### Metáfora
+
+> É como uma sala de equipe onde cada pessoa tem seu próprio quadro de avisos. Você só escreve no seu quadro, mas pode ler os dos outros. Se precisar escrever no quadro de outra pessoa, você precisa pedir permissão (claim).
+
+---
+
+## Instalação
+
+### Pré-requisitos
+
+- Node.js 18+
+- Windows (otimizado para este SO)
+
+### Passo a Passo
+
+```powershell
+# 1. Clone ou copie o projeto
+cd comunicate-ai
+
+# 2. Instale dependências
+npm install
+
+# 3. Compile TypeScript
+npm run build
+
+# 4. Execute setup automatizado
+powershell -ExecutionPolicy Bypass -File setup.ps1
+```
+
+O script `setup.ps1` irá:
+- Criar estrutura de pastas
+- Gerar arquivos JSON iniciais
+- Criar token de admin
+- Mostrar configuração para Claude
+
+---
+
+## Configuração
+
+### 1. Configurar Token de Admin
+
+```powershell
+# Temporário (sessão atual)
+$env:COMUNICATE_ADMIN_TOKEN="seu-token-aqui"
+
+# Permanente (Windows)
+[Environment]::SetEnvironmentVariable("COMUNICATE_ADMIN_TOKEN", "seu-token-aqui", "User")
+```
+
+### 2. Configurar Claude Desktop
+
+Edite `%APPDATA%\Claude\settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "@justmpm/comunicate": {
+      "command": "node",
+      "args": [
+        "C:/caminho/completo/para/dist/mcp-server.js"
+      ],
+      "env": {
+        "COMUNICATE_ADMIN_TOKEN": "seu-token-aqui"
+      }
+    }
+  }
+}
+```
+
+> ⚠️ **IMPORTANTE**: Use barras normais (`/`) ou duplas barras invertidas (`\\`) nos caminhos Windows.
+
+### 3. Reinicie o Claude Desktop
+
+Após configurar, feche e reabra o Claude Desktop.
+
+---
+
+## Tools MCP
+
+### Comunicação
+
+#### `send_agent_message`
+Envia mensagem para outro agente.
+
+```json
+{
+  "token": "token-do-agente",
+  "recipientId": "frontend",
+  "message": "API pronta!",
+  "type": "task_update",
+  "priority": "high"
+}
+```
+
+**Tipos:** `text`, `assistance_request`, `task_update`, `notification`  
+**Prioridades:** `low`, `normal`, `high`, `urgent`
+
+---
+
+#### `get_agent_messages`
+Lê mensagens da inbox.
+
+```json
+{
+  "token": "token-do-agente",
+  "includeRead": false,
+  "markAsRead": true,
+  "limit": 10
+}
+```
+
+---
+
+#### `get_unread_count`
+Retorna número de mensagens não lidas.
+
+```json
+{
+  "token": "token-do-agente"
+}
+```
+
+---
+
+### Claims (Reserva de Arquivos)
+
+#### `claim_file`
+Reserva arquivo fora do domínio para edição.
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts",
+  "durationMinutes": 30,
+  "reason": "Adicionando tipos da API"
+}
+```
+
+> O claim expira automaticamente após o tempo definido.
+
+---
+
+#### `renew_claim`
+Renova um claim prestes a expirar (só funciona se faltarem < 5 min).
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts",
+  "additionalMinutes": 15
+}
+```
+
+---
+
+#### `release_file`
+Libera um arquivo reservado antes do tempo.
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts"
+}
+```
+
+---
+
+#### `can_edit_file`
+Verifica se pode editar um arquivo (domínio ou claim ativo).
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/components/Button.tsx"
+}
+```
+
+---
+
+### Administração (requer token de admin)
+
+#### `create_agent`
+Cria novo agente.
+
+```json
+{
+  "adminToken": "token-admin",
+  "agentId": "backend",
+  "capabilities": ["api", "database", "auth"],
+  "domains": ["src/api", "src/models"]
+}
+```
+
+**Regras para agentId:**
+- Apenas letras minúsculas, números e hífens
+- Exemplos válidos: `backend`, `frontend-v2`, `test-runner`
+
+---
+
+#### `list_agents`
+Lista todos os agentes registrados.
+
+```json
+{
+  "adminToken": "token-admin"
+}
+```
+
+---
+
+#### `get_inactive_agents`
+Lista agentes sem heartbeat (possivelmente "mortos").
+
+```json
+{
+  "adminToken": "token-admin",
+  "timeoutMinutes": 5
+}
+```
+
+---
+
+## Fluxos de Trabalho
+
+### Fluxo 1: Criar Agente e Enviar Mensagem
+
+```
+1. Admin executa: create_agent
+   → Recebe token único do agente
+   
+2. Agente salva seu token
+
+3. Agente A executa: send_agent_message
+   → Mensagem vai para inbox-B.json
+   
+4. Agente B executa: get_agent_messages
+   → Lê e processa mensagens
+```
+
+### Fluxo 2: Coordenação com Claims
+
+```
+Backend (domínio: src/models):
+  ✅ Pode editar: src/models/user.ts
+  ❌ Não pode: src/components/Button.tsx
+
+Frontend (domínio: src/components):
+  ✅ Pode editar: src/components/Button.tsx
+  ❌ Não pode: src/models/user.ts
+
+Quando Frontend precisa editar src/types/api.ts:
+  1. Executa: can_edit_file → false
+  2. Executa: claim_file → success
+  3. Executa: can_edit_file → true
+  4. [edita o arquivo]
+  5. Executa: release_file (ou espera expirar)
+```
+
+### Fluxo 3: Monitoramento de Saúde
+
+```
+Cada agente deve:
+  - Chamar qualquer tool periodicamente (atualiza lastSeen)
+  - Ou chamar updateAgentHeartbeat() via código
+
+Admin pode executar:
+  get_inactive_agents → lista agentes "zumbis"
+```
+
+---
+
+## CLI
+
+Além das tools MCP, existe uma CLI para administração:
+
+```bash
+# Listar agentes
+npm run cli -- list-agents
+
+# Criar agente
+npm run cli -- create-agent backend
+
+# Listar claims
+npm run cli -- list-claims
+
+# Verificar saúde
+npm run cli -- check-health 5
+
+# Gerar token aleatório
+npm run cli -- generate-token
+```
+
+---
+
+## Exemplos
+
+### Exemplo 1: Backend notifica Frontend
+
+```typescript
+// Backend envia atualização
+const result = sendMessage(
+  BACKEND_TOKEN,
+  'frontend',
+  'API /users pronta! Contrato: { id, name, email }',
+  { type: 'task_update', priority: 'normal' }
+);
+```
+
+### Exemplo 2: Frontend reserva arquivo
+
+```typescript
+// Verifica se pode editar
+const check = canEditFile('frontend', 'src/types/api.ts');
+if (!check.allowed) {
+  // Reserva arquivo
+  const claim = claimFile(
+    'frontend',
+    'src/types/api.ts',
+    30,
+    'Adicionando tipos'
+  );
+  
+  if (claim.success) {
+    // Agora pode editar
+    editFile('src/types/api.ts', ...);
+    
+    // Libera quando terminar
+    releaseFile('frontend', 'src/types/api.ts');
+  }
+}
+```
+
+### Exemplo 3: Notificações em tempo real
+
+```typescript
+import { startNotificationListener } from './comunicate/core/notifications';
+
+const listener = startNotificationListener('frontend', {
+  onMessage: (msg) => {
+    console.log(`Nova mensagem de ${msg.senderId}: ${msg.content}`);
+  }
+});
+
+// ... quando quiser parar:
+listener.stop();
+```
+
+---
+
+## Segurança
+
+### Timing-Safe Comparison
+
+Todos os tokens são comparados usando `crypto.timingSafeEqual()` para prevenir timing attacks.
+
+### Token de Admin
+
+- Armazene em variável de ambiente `COMUNICATE_ADMIN_TOKEN`
+- Nunca commite tokens em repositório
+- Use tokens longos e aleatórios (32+ caracteres hex)
+
+### Claims
+
+- Claims expiram automaticamente
+- Só um agente pode ter claim de um arquivo por vez
+- Sequence number previne race conditions
+
+### Domínios
+
+- Defina domínios restritos ao criar agente
+- Agente só edita arquivos dentro de seus domínios sem claim
+
+---
+
+## Troubleshooting
+
+### "Token inválido"
+
+- Verifique se o token está completo (32 caracteres hex)
+- Confirme que o agente está ativo (`list_agents`)
+- Verifique se há espaços extras
+
+### "File claimed by X"
+
+- Outro agente já reservou o arquivo
+- Espere expirar ou peça para liberar
+- Use `get_all_claims` (admin) para verificar
+
+### Mensagens não aparecem
+
+- Verifique se está usando `includeRead: true`
+- Confirme o `recipientId` no envio
+- Verifique o arquivo inbox-*.json manualmente
+
+### File watcher não funciona
+
+- O sistema tem fallback automático para polling
+- No Windows, polling é mais confiável que file watcher
+- Considere usar `startPolling()` explicitamente
+
+### Permissão negada ao escrever JSON
+
+- Verifique permissões da pasta `.comunicate/`
+- Execute como administrador se necessário
+- Verifique se outro processo está usando os arquivos
+
+---
+
+## Dicas
+
+1. **Organize domínios por responsabilidade**
+   - `backend`: `src/api`, `src/models`
+   - `frontend`: `src/components`, `src/hooks`
+   - `shared`: `src/types`, `src/utils` (use claims)
+
+2. **Renove claims antes de expirar**
+   - Se uma tarefa demorar mais que o previsto
+   - Renove quando faltarem < 5 minutos
+
+3. **Use prioridades adequadamente**
+   - `urgent`: Bugs críticos, system down
+   - `high`: Features importantes, deadlines
+   - `normal`: Comunicação rotineira
+   - `low`: Informações, updates
+
+4. **Limpe mensagens lidas periodicamente**
+   - Use `clear_read_messages` para manter inbox limpa
+   - Mensagens antigas são arquivadas automaticamente
+
+---
+
+## Referência Rápida
+
+### Criar Agente
+```json
+{"adminToken": "...", "agentId": "backend", "capabilities": ["api"], "domains": ["src/api"]}
+```
+
+### Enviar Mensagem
+```json
+{"token": "...", "recipientId": "frontend", "message": "...", "type": "task_update", "priority": "normal"}
+```
+
+### Reservar Arquivo
+```json
+{"token": "...", "filePath": "src/types/api.ts", "durationMinutes": 30, "reason": "..."}
+```
+
+### Ler Mensagens
+```json
+{"token": "...", "includeRead": false, "markAsRead": true, "limit": 10}
+```
+
+---
+
+**Versão 0.1.0** | Arquitetura File-Based | Otimizado para Windows