# Prometeu DevTools Protocol

Este documento descreve o protocolo de comunicação entre o Runtime do Prometeu e ferramentas de desenvolvimento (como o Prometeu Debugger).

## Visão Geral

O protocolo é baseado em JSON, enviado via uma conexão de transporte (geralmente TCP). Cada mensagem é um objeto JSON em uma única linha (JSONL).

## Estrutura

- **[protocol.json](./protocol.json)**: Definição formal do protocolo em formato JSON.
- **[protocol.md](README.md)**: Documentação legível para humanos descrevendo os comandos, eventos e tipos.
- **[examples/](./examples)**: Exemplos de fluxos de mensagens (handshake, breakpoints, etc.) em formato JSONL.

## Versionamento

O protocolo possui uma versão explícita definida no campo `protocol_version`.

- Mudanças incompatíveis (breaking changes) incrementam a versão principal.
- Novos campos em mensagens existentes devem ser opcionais sempre que possível para manter compatibilidade retroativa.

A versão atual do protocolo é: **1**

## Handshake

Ao conectar, o Runtime envia uma mensagem de handshake para o cliente.

### Runtime -> Cliente

```json
{
  "type": "handshake",
  "protocol_version": 1,
  "runtime_version": "0.1.0",
  "cartridge": {
    "app_id": 1,
    "title": "ColorSquare",
    "app_version": "1.0.0",
    "app_mode": "Debug"
  }
}
```

### Cliente -> Runtime

O cliente deve responder com `start` ou `ok` para iniciar a sessão.

```json
{ "type": "start" }
```

## Requisições (Requests)

O cliente pode enviar as seguintes requisições para controlar a execução:

| Nome | Parâmetros | Descrição |
|------|------------|-----------|
| `pause` | `[]` | Pausa a execução da VM. |
| `resume` | `[]` | Retoma a execução da VM. |
| `step` | `[]` | Executa uma única instrução (PC). |
| `stepFrame` | `[]` | Executa até o próximo frame. |
| `getState` | `[]` | Retorna o estado atual da VM (`pc`, `stack_top`, `frame_index`, `app_id`). |
| `setBreakpoint` | `{"pc": number}` | Define um breakpoint no endereço especificado. |
| `clearBreakpoint` | `{"pc": number}` | Remove um breakpoint no endereço especificado. |

## Respostas (Responses)

Algumas requisições geram respostas específicas. Por exemplo, `getState` retorna o estado da VM.

## Eventos (Events)

O Runtime pode enviar eventos assíncronos para o cliente:

| Nome | Campos | Descrição |
|------|--------|-----------|
| `breakpointHit` | `pc`, `frame_index` | Emitido quando a execução atinge um breakpoint. |
| `log` | `level`, `source`, `msg` | Emitido quando o código em execução gera um log. |
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Estatísticas de execução enviadas periodicamente. |
| `cert` | `rule`, `used`, `limit`, `frame_index` | Informações de certificação e limites de recursos. |

## Exemplos

Veja a pasta `examples/` para fluxos de mensagens completos.