# 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:

```text
┌──────────────────────┐
│       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.

```text
                       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

```text
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:

```text
MCP Streamable HTTP
```

Endpoint padrão:

```text
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:

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

O Policy Engine deverá verificar:

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

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

Exemplos:

```text
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:

```text
KILO_VSCODE
KILO_ANDROID_STUDIO
```

Fluxo:

```text
VS Code
   │
   ▼
Kilo Hub
   │
   ▼
Android Studio
```

E também:

```text
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:

```text
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:

```text
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:

```text
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:

```text
build
test
lint
diff
contract
```

Fluxo:

```text
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:

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

Modo padrão:

```text
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:

```text
SQLite
```

O banco armazenará informações como:

```text
agents
projects
tasks
messages
task_events
approvals
audit_events
```

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

Local padrão:

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

---

# 📡 API REST

Endpoints planejados:

```http
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:

```text
/ws
```

Eventos previstos:

```text
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:

```text
OpenTelemetry
Prometheus
```

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

---

# 🪵 Auditoria

O sistema deverá registrar:

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

Especialmente:

```text
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 é:

```text
KO/2
```

Regras:

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

Os agentes deverão declarar:

```text
protocolVersion
```

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

---

# ⚙️ Configuração

Exemplo:

```text
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:

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

---

# 🪟 Windows 11

O projeto foi projetado inicialmente para:

```text
Windows 11
```

Scripts previstos:

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

Inicialmente:

```powershell
npm run start
```

Posteriormente:

```text
Windows Task Scheduler
```

para inicialização automática.

---

# 🚀 Desenvolvimento

Instalar dependências:

```powershell
npm install
```

Executar em desenvolvimento:

```powershell
npm run dev
```

Compilar:

```powershell
npm run build
```

Executar testes:

```powershell
npm test
```

Executar testes E2E:

```powershell
npm run test:e2e
```

Executar produção:

```powershell
npm run start
```

Verificar ambiente:

```powershell
.\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

```text
Node.js
   ↓
MCP Server
   ↓
Kilo VS Code
```

Implementar:

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

Objetivo:

```text
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:

```text
Kilo VS Code
```

---

## MVP-2 — Dois agentes

Adicionar:

```text
Kilo Android Studio
```

Objetivo:

```text
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.

```text
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:

```text
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 é:

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

E conseguir:

```text
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

```text
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:

```text
MIT License
```

---

## 👨‍💻 Projeto

Desenvolvido para uso local, com foco em:

```text
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.**