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       │
└──────────┘ └─────────────────┘

Related MCP server: ACDP

🧠 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

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.