prometeu-runtime/devtools/debugger-protocol/README.md

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: Formal definition of the protocol in JSON format.
• protocol.md: Human-readable documentation describing commands, events, and types.
• 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

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

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