@justmpm/comunicate 0.1.4 → 0.2.0

package/README.md

@@ -124,36 +124,134 @@ comunicate-cli generate-token
 
 ## 🛠️ Tools Disponíveis
 
-### Comunicação
-
-| Tool | Descrição |
-|------|-----------|
-| `send_agent_message` | Envia mensagem para outro agente |
-| `get_agent_messages` | Lê mensagens da inbox |
-| `get_unread_count` | Conta mensagens não lidas |
-| `delete_message` | Deleta mensagem específica |
-| `clear_read_messages` | Limpa mensagens lidas |
-
-### Claims (Reserva de Arquivos)
-
-| Tool | Descrição |
-|------|-----------|
-| `claim_file` | Reserva arquivo para edição |
-| `renew_claim` | Renova claim prestes a expirar |
-| `release_file` | Libera arquivo reservado |
-| `can_edit_file` | Verifica permissão de edição |
-| `get_agent_claims` | Lista seus claims ativos |
-| `get_all_claims` | Lista todos claims (admin) |
+### Comunicação entre Agentes
+
+| Tool | Descrição | Quando Usar |
+|------|-----------|-------------|
+| `send_agent_message` | Envia mensagem para outro agente | Notificar progresso, solicitar ajuda, enviar updates |
+| `get_agent_messages` | Lê mensagens da inbox | Verificar novas mensagens, processar pendências |
+| `get_unread_count` | Conta mensagens não lidas | Verificação rápida sem carregar conteúdo |
+| `delete_message` | Deleta mensagem específica | Limpar mensagens irrelevantes |
+| `clear_read_messages` | Limpa mensagens lidas | Manutenção periódica da inbox |
+
+### Sistema de Claims (Reserva de Arquivos)
+
+| Tool | Descrição | Quando Usar |
+|------|-----------|-------------|
+| `can_edit_file` | Verifica permissão de edição | **SEMPRE** chame antes de editar qualquer arquivo |
+| `claim_file` | Reserva arquivo para edição | Quando arquivo está fora do seu domínio |
+| `renew_claim` | Renova reserva prestes a expirar | Quando faltarem < 5 min e edição não terminou |
+| `release_file` | Libera arquivo reservado | Quando terminar edição antes da expiração |
+| `get_agent_claims` | Lista suas reservas ativas | Verificar claims existentes e tempos |
+| `get_all_claims` | Lista todas as reservas (admin) | Monitorar uso do sistema |
 
 ### Administração
 
-| Tool | Descrição |
-|------|-----------|
-| `create_agent` | Cria novo agente |
-| `list_agents` | Lista agentes registrados |
-| `get_inactive_agents` | Lista agentes inativos |
+| Tool | Descrição | Quando Usar |
+|------|-----------|-------------|
+| `create_agent` | Cria novo agente | Novo projeto, nova área de responsabilidade |
+| `list_agents` | Lista agentes registrados | Ver configurações, descobrir agentIds |
+| `get_inactive_agents` | Lista agentes inativos | Monitoramento de saúde do sistema |
 
-## 📖 Exemplos de Uso
+## 📖 Fluxos de Trabalho Comuns
+
+### 1. Criar e Configurar Agentes
+
+```
+Admin executa: create_agent
+  ↓
+Recebe token único (GUARDAR!)
+  ↓
+Entrega token ao respectivo agente
+  ↓
+Agente usa token em todas as operações
+```
+
+### 2. Enviar e Receber Mensagens
+
+```
+Agente A: send_agent_message(tokenA, "agente-b", "API pronta!")
+  ↓
+Mensagem vai para inbox-agente-b.json
+  ↓
+Agente B: get_agent_messages(tokenB)
+  ↓
+Recebe e processa mensagem
+```
+
+### 3. Editar Arquivos (Verificação de Domínios)
+
+```
+Antes de editar QUALQUER arquivo:
+
+Agente: can_edit_file(token, "src/types/api.ts")
+  ↓
+Se PERMITIDO → edite diretamente
+  ↓
+Se NEGADO (fora do domínio):
+  claim_file(token, "src/types/api.ts", 30, "Adicionando tipos")
+  ↓
+Edita o arquivo
+  ↓
+release_file(token, "src/types/api.ts") [opcional mas recomendado]
+```
+
+## 🔑 Conceitos Importantes
+
+### Tokens
+
+#### Admin Token
+
+- Configurado na variável de ambiente `COMUNICATE_ADMIN_TOKEN` no arquivo de configuração do MCP
+- Usado para validar operações administrativas (`create_agent`, `list_agents`, `get_inactive_agents`, `get_all_claims`)
+- **Apenas o administrador do sistema** deve ter acesso a este token
+- Serve como camada de segurança para garantir que apenas administradores possam gerenciar agentes
+
+#### Agent Token
+
+- Gerado pelo `create_agent` quando um admin cria um novo agente
+- **CADA AGENTE TEM SEU PRÓPRIO TOKEN ÚNICO**
+- Usado em TODAS as operações do agente (mensagens, claims, etc.)
+- **GUARDE O TOKEN!** Não será mostrado novamente
+
+### Segurança entre Agentes
+
+O sistema garante que:
+- ✅ Agentes normais não podem criar outros agentes (sem adminToken)
+- ✅ Agentes normais não podem ver todos os claims do sistema (sem adminToken)
+- ✅ Cada agente só acessa sua própria inbox
+- ✅ Claims previnem conflitos de edição
+
+### Domínios
+
+Domínios são pastas onde um agente pode editar arquivos **sem precisar reservar**.
+
+```
+Exemplo:
+Agente Frontend: domains = ["src/components", "src/pages"]
+  ✅ Pode editar: src/components/Button.tsx
+  ✅ Pode editar: src/pages/Home.tsx
+  ❌ Não pode editar: src/api/users.ts (precisa de claim)
+```
+
+### Claims (Reservas)
+
+Um **claim** é uma reserva temporária de um arquivo fora do domínio do agente.
+
+```
+1. Agente verifica: can_edit_file → "File not in agent domains"
+2. Agente reserva: claim_file → "Arquivo reservado por 30 min"
+3. Agente edita o arquivo
+4. Agente libera: release_file [ou espera expirar]
+```
+
+**Regras:**
+- Apenas um agente pode ter claim de um arquivo por vez
+- Claims expiram automaticamente
+- Renove quando faltarem < 5 minutos
+- Libere assim que terminar para boa convivência
+
+## 📋 Exemplos de Uso
 
 ### Criar um agente (admin)
 
@@ -166,27 +264,44 @@ comunicate-cli generate-token
 }
 ```
 
+**Retorno:**
+```
+✅ Agente backend criado
+Token: a1b2c3d4e5f6789012345678abcdef00
+
+⚠️ Guarde este token! Ele não será mostrado novamente.
+```
+
 ### Enviar mensagem
 
 ```json
 {
-  "token": "token-do-agente",
+  "token": "a1b2c3d4e5f6789012345678abcdef00",
   "recipientId": "frontend",
-  "message": "API pronta!",
+  "message": "API /users pronta! Contrato: { id, name, email }",
   "type": "task_update",
   "priority": "high"
 }
 ```
 
-### Reservar arquivo
+### Verificar e reservar arquivo
 
 ```json
+// 1. Verificar permissão
+{
+  "token": "a1b2c3d4e5f6789012345678abcdef00",
+  "filePath": "src/types/api.ts"
+}
+// Retorno: ❌ Não pode editar (fora do domínio)
+
+// 2. Reservar
 {
-  "token": "token-do-agente",
+  "token": "a1b2c3d4e5f6789012345678abcdef00",
   "filePath": "src/types/api.ts",
   "durationMinutes": 30,
-  "reason": "Adicionando tipos"
+  "reason": "Definindo contratos da API"
 }
+// Retorno: ✅ Arquivo reservado até 2026-02-08T23:30:00Z
 ```
 
 ## 🔒 Segurança
@@ -195,6 +310,7 @@ comunicate-cli generate-token
 - **Retry com Backoff**: Escrita atômica com retry automático
 - **Claims Auto-Limpo**: Expirados são removidos automaticamente
 - **Sequence em Claims**: Prevenção de race conditions
+- **Separação de Domínios**: Agentes só acessam arquivos autorizados
 
 ## 🖥️ Otimizado para Windows