runa/docs/protocol.md

Runa Protocol

runa-protocol defines versioned request, response, and event data contracts for clients and the runa-server dispatcher. It is independent of transport and runtime implementation. The runa-server executable currently accepts JSON Lines over stdin and emits one response line per valid request to stdout. It is a local child-process transport, not a network endpoint, and provides no authentication.

Version 1

Every request and response carries version: 1. Requests also carry a non-empty request_id used to correlate the response. A server must reject unsupported versions with unsupported_version rather than interpreting a request using a different contract. Events carry the protocol version and do not have a request ID.

Requests have a tagged command object:

{
  "version": 1,
  "request_id": "req-1",
  "command": {
    "operation": "send",
    "parameters": {
      "actor_id": 7,
      "message": { "kind": 2, "value": 9 }
    }
  }
}

The version 1 operations are behavior publication, rollback, lookup, source retrieval, actor spawn, send, tick, inspect, actor listing, event retrieval, stop, restart, pause, resume, cancellation, and behavior installation. Migration closures are intentionally excluded: they are host callbacks, not portable wire values.

Responses echo the request ID and carry either a typed reply or a protocol error. Events use a separate versioned envelope. Actor and behavior snapshots are wire DTOs, not serialized runtime objects; implementation identities are represented by their stable display strings. The server maps known service failures to the defined error codes and otherwise uses runtime_failure rather than claiming a more specific category.

get_events drains and returns the events currently accumulated by this single-worker image. It is not a durable subscription or replayable event log. The stdio transport limits each request line to 1 MiB before parsing. Malformed JSON or an oversized line terminates the stream with an error on stderr; no protocol response is emitted when a request cannot be decoded. EOF cleanly terminates the process. Any future network transport must impose its own message and request-size limits before dispatch.

The current validation checks the protocol version, request ID, positive actor/revision identifiers where required, non-empty behavior names, mailbox capacity, and instruction budget. Behavior-name grammar, actor existence, current behavior revisions, mailbox capacity at send time, and all runtime invariants remain authoritative at the application-service boundary.