Kilo Orchestrator

Orquestrador local de agentes Kilo Code baseado em MCP para Windows 11.

O Kilo Orchestrator é um sistema local desenvolvido para coordenar múltiplos agentes Kilo Code trabalhando em diferentes ambientes de desenvolvimento, inicialmente VS Code e Android Studio.

O sistema funciona como um núcleo central de comunicação, gerenciamento de tarefas, distribuição de trabalho, acompanhamento de execução, aprovação humana e verificação dos resultados.

---

🎯 Objetivo

O objetivo principal é permitir que diferentes agentes Kilo Code trabalhem de forma coordenada em um mesmo projeto.

Exemplo:

┌──────────────────────┐
│       USUÁRIO        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│      KILO HUB        │
│                      │
│ Orquestração         │
│ Tarefas              │
│ Agentes              │
│ Mensagens            │
│ Aprovações           │
│ Verificação          │
│ Auditoria            │
└──────────┬───────────┘
           │
     MCP Streamable HTTP
           │
      ┌────┴─────┐
      ▼          ▼
┌──────────┐ ┌─────────────────┐
│ VS Code  │ │ Android Studio  │
│ Kilo Code│ │ Kilo Code       │
└──────────┘ └─────────────────┘

---

🧠 Conceito

O Kilo Orchestrator não substitui o Kilo Code.

Ele funciona como uma camada de coordenação entre os agentes.

Cada agente continua trabalhando dentro da sua própria IDE e projeto.

O Kilo Hub controla:

• agentes;
• tarefas;
• mensagens;
• estados;
• dependências;
• permissões;
• aprovações;
• execução;
• verificação;
• eventos;
• auditoria.

---

🏗️ Arquitetura

A arquitetura utiliza princípios de Clean Architecture e Arquitetura Hexagonal, mantendo o núcleo do sistema independente de infraestrutura específica.

                       USUÁRIO
                          │
                          ▼
                  ┌───────────────┐
                  │    KILO HUB   │
                  └───────┬───────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
     Tarefas           Agentes          Mensagens
        │                 │                 │
        └─────────────────┼─────────────────┘
                          │
                          ▼
                   MCP Streamable HTTP
                     ┌────┴────┐
                     │         │
                     ▼         ▼
                  VS Code   Android Studio
                  Kilo      Kilo

---

🛠️ Tecnologias

Camada	Tecnologia
Sistema operacional	Windows 11
Runtime	Node.js 24 LTS
Linguagem	TypeScript
Protocolo dos agentes	MCP
Transporte MCP	Streamable HTTP
HTTP/API	Express
Validação	Zod
Banco de dados	SQLite
Driver SQLite	better-sqlite3
Eventos da interface	WebSocket
Dashboard	HTML + CSS + TypeScript
Testes unitários	Vitest
Testes HTTP	Supertest
Testes E2E	Playwright
Logging	Pino
Identificadores	UUID
IA local opcional	Ollama / LM Studio
Bridge VS Code	Somente se necessário
Bridge Android Studio	Kotlin + IntelliJ Platform SDK, somente se necessário

A arquitetura final deliberadamente não utiliza Java/Spring como núcleo. Java/Kotlin permanece como opção para integração específica com Android Studio caso um bridge seja realmente necessário.

---

📁 Estrutura do projeto

kilo-orchestrator/
│
├── apps/
│   └── kilo-hub/
│       ├── src/
│       │   ├── bootstrap/
│       │   ├── domain/
│       │   ├── application/
│       │   ├── infrastructure/
│       │   ├── interfaces/
│       │   ├── mcp/
│       │   ├── dashboard/
│       │   └── config/
│       │
│       ├── tests/
│       ├── package.json
│       └── tsconfig.json
│
├── bridges/
│   ├── vscode/
│   └── android-studio/
│
├── packages/
│   ├── protocol/
│   ├── schemas/
│   └── shared/
│
├── docs/
│   ├── ARCHITECTURE.md
│   ├── PROTOCOL.md
│   ├── SECURITY.md
│   ├── MCP.md
│   ├── WINDOWS.md
│   └── ADR/
│
├── scripts/
│   ├── check-environment.ps1
│   ├── start.ps1
│   ├── stop.ps1
│   └── status.ps1
│
├── .env.example
├── .gitignore
├── README.md
└── package.json

O monorepo permite compartilhar contratos entre o Hub, protocolo, schemas e integrações. Os contratos críticos serão versionados em JSON Schema.

---

🔌 MCP

O Model Context Protocol (MCP) é a principal interface de integração do sistema.

Transporte principal:

MCP Streamable HTTP

Endpoint padrão:

http://127.0.0.1:8787/mcp

O sistema será inicialmente executado apenas localmente no Windows.

---

🔐 Segurança

A segurança será considerada desde o início do desenvolvimento.

Principais mecanismos:

• execução somente em localhost;
• autenticação;
• token de acesso;
• validação de Origin;
• proteção contra DNS rebinding;
• controle de workspace;
• proteção contra path traversal;
• limite de payload;
• limite de tamanho de mensagens;
• limite de arquivos por tarefa;
• timeout de execução;
• limite de tentativas;
• controle de concorrência;
• Policy Engine;
• aprovação humana;
• auditoria;
• controle de comandos.

O acesso fora da raiz autorizada do workspace deve ser rejeitado.

---

🛡️ Controle de comandos

Agentes não poderão enviar comandos arbitrários como uma simples string.

Exemplo de estrutura permitida:

{
  "executable": "git",
  "args": ["status"],
  "cwd": "C:/Projects/backend"
}

O Policy Engine deverá verificar:

executável
argumentos
diretório de trabalho
risco
necessidade de aprovação

Operações perigosas exigirão aprovação humana.

Exemplos:

git reset --hard
git push --force
git clean -fd
exclusão de arquivos
alterações destrutivas
alterações de segurança

---

🤖 Agentes

Os agentes inicialmente previstos são:

KILO_VSCODE
KILO_ANDROID_STUDIO

Fluxo:

VS Code
   │
   ▼
Kilo Hub
   │
   ▼
Android Studio

E também:

Android Studio
   │
   ▼
Kilo Hub
   │
   ▼
VS Code

O objetivo do MVP-2 é adicionar o agente do Android Studio sem modificar o núcleo do Hub.

---

📋 Tarefas

O Kilo Hub será responsável pelo gerenciamento das tarefas.

Principais operações:

criar tarefa
atribuir tarefa
iniciar tarefa
atualizar tarefa
cancelar tarefa
repetir tarefa
verificar tarefa
finalizar tarefa

Estados serão controlados explicitamente por uma máquina de estados.

---

🔗 Task Graph

As tarefas poderão possuir dependências.

Exemplo:

Tarefa A
   │
   ▼
Tarefa B
   │
   ├──────────► Tarefa C
   │
   ▼
Tarefa D

O sistema deverá controlar:

• dependências;
• DAG;
• detecção de ciclos;
• dispatcher;
• retry;
• timeout;
• recuperação.

---

👤 Aprovação humana

O sistema será human-in-the-loop.

Quando uma operação exigir aprovação:

Agente
  │
  ▼
Kilo Hub
  │
  ▼
Policy Engine
  │
  ▼
Aprovação necessária
  │
  ▼
USUÁRIO
  │
  ├── Aprovar
  ├── Editar
  └── Rejeitar

A aprovação será registrada no histórico de auditoria.

---

🧪 Verificação

O sistema não deverá considerar uma tarefa concluída apenas porque o agente informou que terminou.

A verificação poderá utilizar:

build
test
lint
diff
contract

Fluxo:

Agente
   │
   ▼
Resultado
   │
   ▼
VerificationService
   │
   ├── Build
   ├── Testes
   ├── Lint
   ├── Diff
   └── Contratos
   │
   ▼
Resultado da verificação

O Verification Engine faz parte da evolução planejada do MVP-5.

---

🧠 IA local

A IA local é opcional.

O núcleo não ficará diretamente dependente de um modelo específico.

Arquitetura:

PlannerProvider
│
├── HumanPlanner
├── OllamaPlanner
└── LMStudioPlanner

Modo padrão:

HYBRID

O sistema poderá utilizar modelos locais para:

• planejamento;
• decomposição de tarefas;
• diagnóstico;
• replanejamento;
• análise de resultados;
• julgamento auxiliar.

O modelo de IA não terá autoridade para ignorar o Policy Engine, a aprovação humana ou a Verification Engine.

---

💾 Persistência

O MVP utiliza:

SQLite

O banco armazenará informações como:

agents
projects
tasks
messages
task_events
approvals
audit_events

O banco local deverá ficar fora do repositório Git.

Local padrão:

%LOCALAPPDATA%\KiloOrchestrator\data\kilo-hub.sqlite

---

📡 API REST

Endpoints planejados:

GET    /api/v1/health

GET    /api/v1/agents
GET    /api/v1/agents/:id

GET    /api/v1/projects
POST   /api/v1/projects

GET    /api/v1/tasks
POST   /api/v1/tasks
GET    /api/v1/tasks/:id

POST   /api/v1/tasks/:id/cancel
POST   /api/v1/tasks/:id/retry

GET    /api/v1/tasks/:id/events

GET    /api/v1/approvals
POST   /api/v1/approvals/:id/approve
POST   /api/v1/approvals/:id/reject
POST   /api/v1/approvals/:id/edit-approve

---

🔄 WebSocket

Endpoint:

/ws

Eventos previstos:

agent.connected
agent.disconnected
agent.updated

task.created
task.updated
task.progress
task.completed
task.failed

approval.created
approval.updated

message.created
message.delivered
message.acked

verification.started
verification.completed

---

📊 Observabilidade

No MVP:

• logs estruturados;
• histórico de tarefas;
• status dos agentes;
• linha do tempo de eventos;
• métricas básicas.

No futuro:

OpenTelemetry
Prometheus

Não será adicionada infraestrutura externa de observabilidade no MVP.

---

🪵 Auditoria

O sistema deverá registrar:

quem
o quê
quando
tarefa
agente
decisão
estado anterior
estado posterior
resultado

Especialmente:

aprovações
rejeições
execução de comandos
alterações de workspace
conexões de agentes
autenticação
negações de política

---

🔢 Protocolo

O protocolo interno atual é:

KO/2

Regras:

major = alteração incompatível
minor = extensão compatível

Os agentes deverão declarar:

protocolVersion

O Hub deverá rejeitar versões incompatíveis que não sejam suportadas.

---

⚙️ Configuração

Exemplo:

KILO_HUB_PORT
KILO_HUB_TOKEN
KILO_HUB_DB_PATH

KILO_PLANNER_MODE
KILO_PLANNER_PROVIDER

OLLAMA_BASE_URL
LMSTUDIO_BASE_URL

Segredos nunca deverão:

ser enviados ao Git
ser registrados em logs
ser enviados aos agentes
ser exibidos no Dashboard

---

🪟 Windows 11

O projeto foi projetado inicialmente para:

Windows 11

Scripts previstos:

scripts/
├── check-environment.ps1
├── start.ps1
├── stop.ps1
└── status.ps1

Inicialmente:

npm run start

Posteriormente:

Windows Task Scheduler

para inicialização automática.

---

🚀 Desenvolvimento

Instalar dependências:

npm install

Executar em desenvolvimento:

npm run dev

Compilar:

npm run build

Executar testes:

npm test

Executar testes E2E:

npm run test:e2e

Executar produção:

npm run start

Verificar ambiente:

.\scripts\check-environment.ps1

Os comandos de desenvolvimento definidos na arquitetura são npm install, npm run dev, npm run build, npm test, npm run test:e2e e npm run start.

---

🗺️ Roadmap

MVP-0 — Prova do MCP

Node.js
   ↓
MCP Server
   ↓
Kilo VS Code

Implementar:

• health;
• uma ferramenta MCP;
• um resource;
• autenticação;
• logs.

Objetivo:

Kilo consegue chamar a ferramenta
Kilo Hub responde

---

MVP-1 — Kilo Hub

Implementar:

• Node.js;
• TypeScript;
• MCP Streamable HTTP;
• SQLite;
• tarefas;
• agentes;
• mensagens;
• Dashboard;
• autenticação.

Primeiro agente:

Kilo VS Code

---

MVP-2 — Dois agentes

Adicionar:

Kilo Android Studio

Objetivo:

VS Code Kilo
      ↓
   Kilo Hub
      ↓
Android Studio Kilo

E também o fluxo inverso.

---

MVP-3 — Controle humano

Adicionar:

• ApprovalService;
• PolicyEngine;
• AuditLog;
• aprovação;
• edição;
• rejeição.

---

MVP-4 — Task Graph

Adicionar:

• dependências;
• DAG;
• detecção de ciclos;
• dispatcher;
• retry;
• timeout;
• recovery.

---

MVP-5 — Verification

Adicionar:

• build;
• testes;
• lint;
• diff;
• contratos.

---

MVP-6 — IA local

Adicionar:

• PlannerProvider;
• OllamaPlanner;
• LMStudioPlanner;
• JudgeProvider;
• Replanning.

---

MVP-7 — IDE Bridges

Somente criar bridges caso a integração MCP direta não seja suficiente.

VS Code Bridge
Android Studio Bridge

O Bridge não substitui o MCP.

---

MVP-8 — Produto para Windows

Adicionar:

• instalador;
• atalho na área de trabalho;
• inicialização automática;
• Task Scheduler;
• backup;
• health check.

A ordem completa de implementação foi definida de forma incremental, começando pelo MCP e chegando posteriormente ao empacotamento para Windows.

---

🚫 O que NÃO faz parte do MVP

Não utilizar inicialmente:

Kafka
RabbitMQ
Redis
PostgreSQL
Kubernetes
Docker obrigatório
React obrigatório
NestJS
microservices
cloud deployment
agentes remotos
banco distribuído

Também não criar bridges se a integração MCP direta resolver o problema.

---

🏁 Primeiro objetivo real

O primeiro objetivo do projeto é:

Kilo Code VS Code
       ↓
MCP Streamable HTTP
       ↓
Kilo Hub
       ↓
SQLite
       ↓
Dashboard

E conseguir:

enviar mensagem
receber mensagem
criar tarefa
atualizar tarefa
visualizar status

Depois disso, o segundo objetivo será adicionar o Kilo Code do Android Studio sem alterar o núcleo do sistema.

---

📌 Status do projeto

Projeto: Kilo Orchestrator
Versão: 1.0
Protocolo: KO/2
Plataforma: Windows 11
Arquitetura: Clean / Hexagonal
Runtime: Node.js 24 LTS
Linguagem: TypeScript
Banco: SQLite
Integração: MCP
Status: Em desenvolvimento

---

📄 Licença

Este projeto é distribuído sob a licença:

MIT License

---

👨‍💻 Projeto

Desenvolvido para uso local, com foco em:

automação
orquestração de agentes
desenvolvimento de software
integração entre IDEs
IA local
segurança
verificação
produtividade

Kilo Orchestrator — vários agentes, um núcleo de coordenação.