Phase 20: Arquitetura de Bots Federados

Arc OS — de "um escritório" para "centro de comando para todos os projetos" Autor: Rick (Arquiteto Principal) | Data: 2026-04-02 Status: 20.1–20.5 COMPLETE Aprovado por: CEO

O Problema

O CEO gerencia múltiplos projetos (Arc OS, Msolution, RTS_001) pelo celular. Arquitetura atual: um bot Telegram → uma sessão Claude → uma janela de contexto. Isso quebra com 3+ projetos:

• Poluição da janela de contexto (200K tokens compartilhados entre projetos sem relação)
• Sem isolamento de projeto (código do msolution vaza nos prompts do citadel)
• Sem capacidade multi-usuário (não dá pra convidar um designer para o chat de um projeto)
• Contexto de reply quebrado (responder a mensagem do projeto errado = caos)

A Solução: Federação

CEO ↔ @citadel_master_bot (Master)          ← apenas comandos globais
       │
       ├── /status          → consulta todos os children
       ├── /emergency-stop  → sinal de kill para todos
       ├── /deploy all      → deploy em cascata
       │
       ├── @citadel_v2_bot (Child 1)         ← chat separado, contexto separado
       │    └── Sessão Claude #1, cwd=/opt/repos/citadel-v2
       │
       ├── @msolution_bot (Child 2)          ← pode adicionar designer ao chat
       │    └── Sessão Claude #2, cwd=/opt/repos/msol
       │
       └── @rts_bot (Child 3)               ← pode adicionar agente Morty
            └── Sessão Claude #3, cwd=/opt/repos/rts-001

Análise de Decisão: Bot Único vs Federação

Opção A: Bot Único + Seletor de Projeto

Veredicto: Funciona para CEO solo com 1-2 projetos. Quebra com 3+.

Opção B: Bots Federados (Master + Children) — ESCOLHIDA

Veredicto: Solução correta. Mais complexidade de infra, mas resolve TODOS os problemas.

Por que a Federação Vence

1. Isolamento de contexto — fator decisivo. Uma sessão Claude para 3+ projetos = overflow de contexto em 30 minutos de trabalho ativo. A federação dá a cada projeto 200K tokens limpos.
2. Prontidão multi-usuário — não é "funcionalidade futura", é uma fundação. Sem isso, o Arc OS não pode se tornar um produto.
3. Reply = RAG nativo — o Telegram já resolveu o problema de contexto. Apenas mapeamos reply → prompt GSD.

Arquitetura de Emergency Stop

CEO toca /emergency-stop no chat do Master
        │
        ▼
Master Bot (Node.js/Bun, leve, NÃO é uma sessão Claude)
        │
        ├── 1. Lê config/bot_registry.json
        │      { "children": [
        │          { "name": "citadel-v2", "tmux": "citadel", ... },
        │          { "name": "msolution", "tmux": "msolution", ... }
        │      ]}
        │
        ├── 2. Para cada child (em paralelo):
        │      a) tmux send-keys -t $SESSION "C-c" Enter      ← graceful: Ctrl+C
        │      b) sleep 2
        │      c) tmux send-keys -t $SESSION "/exit" Enter     ← saída explícita
        │      d) sleep 2
        │      e) tmux kill-session -t $SESSION                 ← força kill se ainda ativo
        │
        ├── 3. Atualiza office-state.json: todos os agentes → idle
        │
        └── 4. Responde no chat do Master:
               "EMERGENCY STOP executed.
                citadel-v2: STOPPED (was: working on hooks)
                msolution: STOPPED (was: idle)
                All agents reset to idle."

Protocolo de Kill (3 níveis)

Failsafe

Job cron a cada 5 minutos verifica /tmp/emergency-stop.flag. Se o arquivo existe e é recente (<10 min), executa a sequência de kill. Cobre o caso em que o próprio Master Bot crashou.

Smart Context Recall

Problema

O CEO responde a uma mensagem de 3 dias atrás e diz "faz o mesmo para outro módulo". O Claude não tem ideia da mensagem referenciada.

Solução: Transformação Reply → Prompt GSD

A Telegram Bot API fornece o objeto reply_to_message com o texto original completo.

CEO responde a: "I deployed hooks to VPS, everything works"
CEO escreve: "do the same for msolution"
        │
        ▼
Child Bot recebe:
{
  "message": {
    "text": "do the same for msolution",
    "reply_to_message": {
      "text": "I deployed hooks to VPS, everything works",
      "date": 1743580800,
      "message_id": 847
    }
  }
}
        │
        ▼
Bot constrói prompt GSD para Claude:
┌─────────────────────────────────────┐
│ CONTEXT (from reply):               │
│ > [2026-04-02] "I deployed hooks    │
│ > to VPS, everything works"         │
│                                     │
│ TASK (new message):                 │
│ "do the same for msolution"         │
│                                     │
│ PROJECT: msolution (from bot scope) │
└─────────────────────────────────────┘

Deep Recall (mensagens mais antigas)

Camada 1: Histórico do Thread (rápido)
  Bot armazena as últimas 50 mensagens em state/thread_history.json por chat.
  Reply → bot encontra o original → injeta no bloco CONTEXT.

Camada 2: Library Recall (fallback)
  Se mensagem não está no histórico do thread (>50 mensagens atrás) →
  bot executa /citadel-recall com texto do reply →
  puxa contexto de library-export/ → injeta no prompt.

Fluxo: reply_to_message → thread_history → library-export/ → prompt GSD

Princípio-Chave

O Claude NUNCA sabe sobre os replies do Telegram diretamente. O middleware do bot SEMPRE transforma o reply em um bloco limpo CONTEXT + TASK antes de enviar para a sessão Claude.

Especificação do Master Bot

O que o Master Bot É

• Serviço leve Bun/Node.js (~300 linhas)
• Telegram Bot API (long-polling)
• Lê config/bot_registry.json para registry de children
• Endpoint HTTP de health: /api/master/health
• Container Docker no compose compartilhado

O que o Master Bot NÃO É

• NÃO é uma sessão Claude (sem IA, sem chamadas LLM)
• NÃO é um proxy de mensagens (não encaminha mensagens para os children)
• NÃO é um armazenamento de estado (lê estado dos arquivos dos children)

Protocolo do Child Bot

Cada child bot deve:

1. Registrar em config/bot_registry.json na inicialização
2. Enviar heartbeat (a cada 60s) ao Master via arquivo: state/heartbeat_<name>.json
3. Tratar reply_to_message → injeção de CONTEXT no GSD
4. Armazenar as últimas 50 mensagens em state/thread_history.json
5. Responder ao sinal de emergency-stop (Ctrl+C graceful → /exit → kill)
6. Usar logger estruturado (shared/logger.ts) — logs em /var/log/citadel/<name>/
7. Aceitar variável de ambiente BOT_NAME para nomeação dinâmica
8. Expor /api/child/health para health checks do watchdog

Estimativa de Recursos

Sub-Phases da Phase 20

20.1 — Fundação do Master Bot

• Bot Telegram em Bun + TypeScript (long-polling)
• config/bot_registry.json — registry de children
• Comandos: /status, /emergency-stop, /list, /health
• Container Docker em docker/docker-compose.yml
• Endpoint de health: /api/master/health
• Sem IA, sem sessão Claude — orquestrador puro

20.2 — Protocolo do Child Bot (Primeiro Child)

• Define protocolo de registro do child bot
• Middleware de mensagens: reply_to_message → injeção de CONTEXT no GSD
• Histórico de thread: últimas 50 mensagens em state/thread_history.json
• Protocolo de shutdown graceful (reage ao emergency-stop)
• Piloto: migra @citadel_v2_bot do Claude Channel para bot customizado
• Heartbeat ao Master (a cada 60s via arquivo)

20.3 — Motor de Onboarding (DONE)

• /new_project <name> — entrevista interativa em 4 etapas
• Correspondência de skills (registry + library), detecção de blueprint
• Auto-provisionamento: diretórios, CLAUDE.md, MANIFEST.md, .env, registry, tmux

20.4 — Biblioteca de Skills e Remoção de Projeto (DONE)

• /remove_project <name> — tripla confirmação + nomes protegidos
• Skills da library correspondidas automaticamente e copiadas durante o onboarding
• Hook de recarga do registry para atualizações em memória

20.5 — Infraestrutura Phantom-Ready (DONE)

• shared/logger.ts — logging estruturado JSONL, divisão diária de arquivo
• shared/vault.ts — secrets criptografados AES-256-GCM (tokens no vault, não no .env)
• master-bot/watchdog.ts — monitor auto-recuperável com backoff exponencial
• Comando /watchdog para status em tempo real dos children
• Config de logrotate + script de setup do VPS
• Todos os console.log → logger estruturado

Comandos do Master Bot (Final)

Fora do Escopo (Phase 21+)

• SaaS multi-tenancy (JWT, cobrança Stripe)
• Dashboard web alternativo ao Telegram
• Comandos de voz via Telegram
• Editor de sprite de agente e customização do escritório
• Mecanismo de rotação de chave do vault
• Monitoramento de health entre múltiplos VPS

Arquitetura da Phase 20 por Rick (Arquiteto Principal). Phases 20.1–20.5 completas. Aprovado pelo CEO em 2026-04-02.