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.

2.6 KiB Raw Blame History