# Prometeu DevTools Protocol

This document describes the communication protocol between the Prometeu Runtime and development tools (such as the Prometeu Debugger).

## Overview

The protocol is based on JSON, sent via a transport connection (usually TCP). Each message is a JSON object on a single line (JSONL).

## Structure

- **[protocol.json](protocol.json)**: Formal definition of the protocol in JSON format.
- **[protocol.md](README.md)**: Human-readable documentation describing commands, events, and types.
- **[examples/](examples)**: Examples of message flows (handshake, breakpoints, etc.) in JSONL format.

## Versioning

The protocol has an explicit version defined in the `protocol_version` field.

- Incompatible changes (breaking changes) increment the major version.
- New fields in existing messages should be optional whenever possible to maintain backward compatibility.

The current protocol version is: **1**

## Handshake

Upon connecting, the Runtime sends a handshake message to the client.

### Runtime -> Client

```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"
  }
}
```

### Client -> Runtime

The client must respond with `start` or `ok` to start the session.

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

## Requests

The client can send the following requests to control execution:

| Name | Parameters | Description |
|------|------------|-----------|
| `pause` | `[]` | Pauses VM execution. |
| `resume` | `[]` | Resumes VM execution. |
| `step` | `[]` | Executes a single instruction (PC). |
| `stepFrame` | `[]` | Executes until the next frame. |
| `getState` | `[]` | Returns the current VM state (`pc`, `stack_top`, `frame_index`, `app_id`). |
| `setBreakpoint` | `{"pc": number}` | Sets a breakpoint at the specified address. |
| `clearBreakpoint` | `{"pc": number}` | Removes a breakpoint at the specified address. |

## Responses

Some requests generate specific responses. For example, `getState` returns the VM state.

## Events

The Runtime can send asynchronous events to the client:

| Name | Fields | Description |
|------|--------|-----------|
| `breakpointHit` | `pc`, `frame_index` | Emitted when execution hits a breakpoint. |
| `log` | `level`, `source`, `msg` | Emitted when the running code generates a log. |
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Execution statistics sent periodically. |
| `cert` | `rule`, `used`, `limit`, `frame_index` | Certification information and resource limits. |

## Examples

See the `examples/` folder for complete message flows.