prometeu-runtime/devtools/debugger-protocol

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.