runa/docs/protocol.md

Runa Protocol

runa-protocol defines versioned request, response, and event data contracts for clients and the runa dispatcher. It is independent of transport and runtime implementation. runa accepts WebSocket text messages bound to an IPv4 or IPv6 loopback address, defaulting to 127.0.0.1:3737 without arguments. Clap parses --listen / RUNA_LISTEN on the server and --connect / RUNA_CONNECT on runa-cli; explicit flags override environment variables. The listener is unauthenticated and intended only for trusted local development. Both the REPL and VS Code use WebSockets.

Version 5

Every request and response carries version: 5. 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": 5,
  "request_id": "req-1",
  "command": {
    "operation": "send",
    "parameters": {
      "actor_ref": "xK8_pQ2-Lm5_012345678",
      "message": {
        "type": "record",
        "data": {
          "op": { "type": "string", "data": "send" },
          "value": { "type": "integer", "data": 9 },
          "target": { "type": "actor_ref", "data": "Hj2_9sM0-pQ4_7aBcD3eF" }
        }
      }
    }
  }
}

The version 5 operations are source listing/read/write, commit/history/revision retrieval/rollback, actor spawn, send, tick, inspect, actor listing, event retrieval, privileged system messages, and cancellation. Migration closures are intentionally excluded: they are host callbacks, not portable wire values.

Source paths are extensionless relative paths such as actors/counter, not behavior aliases. They exclude the source/ root and .rn extension.

Operation	Parameters	Reply kind/data
list_sources	none	sources: file array
read_source	path	source: file
check_source	source (including unsaved text)	source_checked: {diagnostics}
write_source	path, expected_source_id (null to create), source	source: file
rename_source	path, target, expected_source_id, update_actors	source: renamed file
delete_source	path, expected_source_id	acknowledged
actor_behavior	actor_ref	actor_behavior: {source_id, source}
write_actor_behavior	actor_ref, expected_source_id, source	actor_behavior: {source_id, source}
update_behavior_source	actor_ref, path, expected_source_id, temporary_source_id	source: updated original file
commit_source	path	source_committed: commit
source_history	path	source_history: commit array
revision_source	path, revision	behavior_source: {source}
rollback_source	path, revision	source: restored file
spawn	path, tagged state, positive mailbox_capacity	actor_spawned: {actor_ref}
inspect_execution	actor_ref	execution_inspected: loaded source and optional execution stack
set_breakpoints	actor_ref, implementation_id, lines	breakpoints_set: {breakpoints}
step_source	actor_ref, implementation_id, instruction_budget	debug_step_completed: {reason}
system	actor_ref, message	acknowledged

A file is {path, source_id, source} and a commit is {revision, source_id}. Commits generate readable random revision strings and capture working text without compilation. Rollback restores working source without appending history. Spawn compiles current working source even when uncommitted; compilation failures do not spawn an actor.

Rename preserves history and atomically updates installed/pending actor path bindings when update_actors is true. In-use paths require that authorization; existing destination paths are never overwritten. Delete discards working text and history and rejects installed/pending users unless all are failed, with an explicit stop-first error. Compiled artifacts are retained.

actor_behavior reads the existing temporary text, or the actor's loaded artifact rather than its current working file. Writing compiles first and schedules an actor-local safe-boundary install, retaining state/mailbox and leaving shared source/history untouched. A failed actor's implementation may be replaced without restarting or acknowledging its failed input. Reload/become clear temporary text after successful scheduling; restart retains it; removal cleans it up. update_behavior_source copies temporary text into shared working source without committing. Its original path and both source identities are checked before writing. Stale source identities/path bindings return conflict.

Actor snapshots add behavior_path (nullable installed source path), pending_behavior_path (nullable scheduled source path), and temporary_behavior (boolean). These are additive v5 metadata fields; older v5 snapshots may omit them and clients default to null/false.

Compilation diagnostics

check_source compiles a standalone text buffer with the image's native modules. It does not execute, save, commit, cache, install, or emit image_changed. Both invalid and valid source return source_checked: compiler errors/warnings are validation results; infrastructure failures still use the error envelope.

Each diagnostic is {severity: "error"|"warning", message, range}. A non-null range is {start: {line, character}, end: {line, character}}, with zero-based lines, UTF-16 code-unit columns, and an exclusive end. Ranges refer to the exact submitted text, not the current contents of a source path. range: null denotes an error without a location in the submitted source. There are no synthetic locations inferred from compiler display strings.

Compilation failures from spawn/reload/become/temporary behavior writes also carry an optional diagnostics array in ProtocolError, retaining the existing runtime_failure code and human-readable message. This is an additive v5 field: absent diagnostics deserialize as an empty list and are omitted when empty. Source checking is single-file; it does not resolve other image files as modules.

Execution inspection

inspect_execution is an additive, read-only v5 operation. It returns {actor_ref, incarnation, implementation_id, source_id, source, behavior_path, execution, debugger}. Source is the exact original text of the installed artifact, not working source or a pending temporary replacement. The nullable behavior path is a logical binding, not a guarantee that a mutable file still matches the code. Idle/failed actors return execution: null; removed actors return not_found. Inspection does not tick, mutate the image, consume events, or emit image_changed.

A non-null execution is {vm_steps, awaiting, call_depth, frames, frames_truncated}. Frames are ordered innermost first, limited to 64 including the current frame; call_depth reports the full number of saved callers. Each frame is {kind: "current"|"caller", instruction_pointer, source_instruction_pointer, function, range}. Current IP is the next instruction at a completed step boundary; while awaiting, it is the await instruction from the last safe snapshot, not an IP observed inside a borrowed pending future. Caller IPs are saved return addresses; source IPs identify the preceding call instruction. Source IP, function, and range may be null when debug information is unavailable. Ranges use the same zero-based UTF-16/exclusive-end coordinates as diagnostics and refer only to the returned loaded source.

Only the head Rune VM's visible frames are captured, not native stacks or stacks hidden inside nested futures. Pending async steps are not counted as completed VM steps. Snapshots contain no VM stack values or mutable execution handles. There is no locals inspection, post-mortem stack retention, or DAP contract. Responses are point-in-time; clients must pause explicitly for stable inspection.

Source debugger controls

These additive v5 mutations are available to trusted clients and broadcast image_changed. Both require the expected implementation_id display string; a stale installed identity returns conflict without mutation. Pending shared or temporary source replacements do not retarget the controls.

set_breakpoints replaces the selected actor's list with up to 128 zero-based 32-bit line numbers; [] clears it. Returned breakpoints are sorted/deduplicated {line, instruction_pointers} entries. Addresses identify mapped line entries (line transitions, function entries, or labeled branch targets); an empty list means the requested line is unverified. No relocation to another line occurs. During ticks, a hit pauses that actor before execution. Resume skips that stopped address once, not all subsequent hits.

step_source requires a paused actor with an active handler/shutdown invocation, and a positive budget no greater than 10,000. It advances only that actor, stopping at the next mapped line or call-depth change (step-into), another breakpoint, pending async operation, completion/failure/removal, or budget exhaustion. reason is one of step, breakpoint, budget, awaiting, completed, failed, removed. Failure is an executed actor transition with explicit reason and failure text in its ordinary snapshot, not an infrastructure success fallback. Nonfailed surviving actors remain paused, including at a completed handler boundary; drafts/sends commit only on normal completion. Another explicit step may poll a pending async operation once; steps do not block waiting for it. Native calls remain cooperative, not preemptible.

execution_inspected adds debugger: {breakpoints, stop_reason} even when execution is null. Older replies may omit it; Rust defaults to an empty configuration and no reason. stop_reason is nullable and uses the same reason strings as step replies. Installation clears breakpoints; restart/cancel retain them for unchanged loaded code and clear stop reasons. Debugger state is actor local, shared by clients, and in-memory; it is not owned by a client connection. There are no conditions, hit counts, step-over/out, or gutter/DAP breakpoints yet.

System message shape is {kind: "stop"|"kill"|"restart"|"pause"|"resume"|"reload"} or {kind: "become", path: "actors/other"}. This is a trusted host request; actor ctx.send and ctx.send_from accept only ordinary data. Stop runs optional on_shutdown after the active handler and removes the actor on success. Kill removes the actor immediately without shutdown, including failed actors. Removed references return not_found; state, mailbox, and retained logs are discarded. Failed actors are not automatically removed. A Stopped event denotes removal, and image_changed invalidates actor lists. Restart is independent of stop/kill and retains identity, mailbox, the loaded script and state; removed actors cannot be restarted. Reload/become defer installation to the next handler boundary. Normal scheduling advances through tick; the explicit debugger step operation advances only its selected paused actor.

Responses echo the request ID and carry either a typed reply or a protocol error. Events use a separate versioned envelope. Actor and source snapshots are wire DTOs, not serialized runtime objects; implementation identities are represented by their stable display strings. Public actor identity is a 21-character URL-safe NanoID string carried in actor_ref. The server maps known service failures to the defined error codes and otherwise uses runtime_failure rather than claiming a more specific category.

Portable values

Spawn state, send messages, snapshot state/mailbox/reservations, and migration event states use the same tagged value shape:

Value	JSON
Null	{"type":"null"}
Boolean	{"type":"bool","data":true}
Signed 64-bit integer	{"type":"integer","data":42}
String	{"type":"string","data":"hello"}
List	{"type":"list","data":[<value>, ...]}
Record	{"type":"record","data":{"key":<value>, ...}}
Actor reference	{"type":"actor_ref","data":"<21-character-NanoID>"}

References are distinct from strings. Their shape is validated even when nested; existence is checked when a reference is used as a send destination, not merely stored as data. The old message envelope and protocol v2 are not accepted. The REPL's natural JSON and $actor/$record conveniences are client syntax, not wire encodings.

Each state/message permits a maximum nesting depth of 32 (root depth 0), 4,096 nodes, and 1 MiB of UTF-8 string/key bytes. Requests are also subject to the transport's 1 MiB total message limit, including tags and envelope. Unsupported value tags, malformed references, floats, and out-of-range integers fail decoding; well-formed requests exceeding value limits receive invalid_request. Invalid Rune transition output fails the actor without acknowledging the reserved message, changing committed state, or enqueueing any of its sends.

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 transport limits each request to 1 MiB before parsing. Malformed JSON or an oversized message terminates that connection with an error; no protocol response is emitted when a request cannot be decoded. A WebSocket disconnect closes only that client connection. The listener allows up to 16 simultaneous clients and serializes each dispatch through the same image. WebSocket response payloads are capped at 1 MiB, with one in-flight dispatch per client and a bounded shared dispatch queue. Every local client can use the full development API; loopback binding is not authentication or authorization. Remote access must not be enabled until appropriate authentication and authorization exist. The runa-client crate validates response protocol versions and request IDs. Its WebSocketClient connects to loopback endpoints using bounded WebSocket messages and correlation checks, validating interleaved notifications while waiting for responses. Connection establishment has a 5-second timeout; WebSocket writes and response waits have 30-second timeouts. A failed network request invalidates that client connection. No automatic retry is performed: loss of a response does not imply that the operation failed to commit.

The interactive REPL uses WebSockets and never owns the image. Disconnecting clients does not stop actors or reset source history; reconnecting clients can retrieve them through list_actors and list_sources. The network executable loads source/actors/counter.rn on image startup, not on connection. The stdio transport and child-process client have been removed.

The TypeScript VS Code client issues list_actors, inspect_actor, source file/version-control operations, spawn, send, tick, and system. VS Code automatically displays writable image files under a source directory in its dedicated Runa sidebar's source tree, without modifying workspace folders, and caches read-only commit documents by connection, path, and revision. It preserves i64 inputs and bounds the complete outgoing envelope as well as incoming messages. It enforces loopback endpoints, bounded UTF-8 text messages, version/request-ID/reply-kind checks, and portable snapshot value validation. It decodes JSON integers as bigint and prints them losslessly, including signed 64-bit state and unsigned 64-bit telemetry. It uses the same 5-second connect and 30-second request timeouts, closes on transport/protocol corruption, and never retries automatically. A well-formed server error is surfaced without invalidating the stream. Server notifications trigger automatic refreshes of the actor tree and open snapshot documents. Manual refresh remains available.

WebSocket transport and notifications

Actor editing and log subscriptions (v5)

• edit_actor {actor_ref,state,messages}: state is a tagged portable value or null to leave it unchanged. messages is null to leave the mailbox unchanged, or {reserved,queued} where reserved is a tagged value or null for no reservation, and queued is an ordered array of tagged values. At least one edit is required. Only paused/failed actors with no active execution are editable; values and mailbox capacity are validated atomically.
• set_log_level {actor_ref,level}: level is one of trace, debug, info, warn, error, fatal. Both mutations return acknowledged and invalidate image views. Actor snapshots include log_level.
• logs {actors,follow,after}: actors is an array of references (empty means all); after is an exclusive u64 sequence cursor. Reply kind logs carries {entries,next_sequence,has_more}, with at most 128 entries per page. Each entry is {sequence,actor_ref,level,message}. Missing actors are errors. History queries are read-only and do not invalidate views.
• With follow true, the connection registers the filter before history is read. Subsequent notification envelopes carry {event:"log",data:{sequence,actor_ref,level,message}}. Reissuing logs replaces the filter; follow false unsubscribes. Matching entries newer than the reply's cursor are emitted after its reply, allowing history/follow deduplication by sequence. Other connections receive no log events. Transport and client buffers are bounded at 1,024 entries; lag is an explicit connection error, not a guaranteed-delivery stream. Disconnect removes the subscription. Image invalidations remain coalescible and independent of logs.

On quit, exit, Ctrl+C, or end-of-input, the CLI completes the WebSocket close handshake with a 5-second deadline before releasing the connection. A failed handshake is reported rather than treating an abrupt reset as a normal close.

Connect to ws://127.0.0.1:3737/ (or a configured numeric loopback endpoint) and offer the runa-debug WebSocket subprotocol. The server requires and echoes that subprotocol. Plain TCP JSON Lines is no longer accepted by the network listener. The request/response contract is version 5. Each WebSocket text message contains exactly one JSON request, response, or notification, without newline framing. Binary messages and malformed requests terminate the connection. Fragmented text is supported with a 1 MiB aggregate message limit; individual frames are also limited to 1 MiB. Compression is not enabled. Upgrade handshakes have a 5-second timeout and writes have a 30-second timeout so stalled peers do not hold client slots forever.

The endpoint accepts only the root path and rejects requests carrying an Origin header: browser-origin access is not enabled for this unauthenticated local API. This is not authentication; local non-browser clients retain full development privileges.

Every upgraded connection automatically receives non-destructive invalidations:

{
  "version": 5,
  "event": {
    "event": "image_changed",
    "data": { "revision": 42 }
  }
}

Successful mutating requests (spawn, send, tick, lifecycle controls, source writes/commits/rollback, and system messages) increment a server-session revision and notify all connected clients, including the initiator. Read-only requests, failed mutations, and get_events do not generate invalidations. A tick invalidates snapshots even when it only advances execution telemetry or causes an actor failure. A successful send invalidates mailbox snapshots before any handler runs. Notifications may appear between requests and their replies; clients must distinguish them from correlated responses.

Revisions increase within one server session, not across server restarts. Slow subscribers retain only the latest unsent revision; gaps are expected. These notifications are hints to re-fetch authoritative data, not individual runtime events, a durable log, an atomic snapshot revision, or replay. On connection/reconnection, fetch a full listing first. The VS Code client coalesces bursts and schedules another refresh if an invalidation arrives during an in-flight read. Refresh never advances the scheduler or calls get_events; the REPL's explicit events command still drains the separate runtime queue.

The current validation checks the protocol version, request ID, actor-reference shape, structured-value limits, revision ID shape, non-empty paths, mailbox capacity, and instruction budget. Canonical source paths, actor existence, expected source identities, mailbox capacity at send time, and all runtime invariants remain authoritative at the application-service boundary.