protocol.json: Definição formal do protocolo em formato JSON.
protocol.md: Documentação legível para humanos descrevendo os comandos, eventos e tipos.
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

{
  "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.

{ "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.