Skip to main content
The EnclaveJS streaming protocol enables real-time communication between clients and the execution runtime. It uses NDJSON (Newline Delimited JSON) for efficient streaming. Events travel as plain JSON, protected by the transport.

Protocol Overview

The broker runs the script in an @enclave-vm/core sandbox in its own process, and it runs the tools itself. The client is told about tool calls; it does not execute them and submits no results.

Event Structure

Every event has the same envelope: There is no timestamp field.

Event Types

session_init

The first event of a session:

tool_call

The script called a tool. The broker runs it:

tool_result_applied

The result of a tool call was handed to the script. The result itself is not part of the event:

heartbeat

Keep-alive message, sent every heartbeatIntervalMs (15 seconds by default):

final

The last event of a session. A session that succeeded:
A session that failed or was cancelled has "ok": false and an error with a message and a code in place of result.

error

An error that is reported besides the final event. The broker emits one when a session is cancelled while no script is executing:

stdout and log

The protocol defines stdout (payload: { chunk }) and log (payload: { level, message, data? }) events, and the client has handlers for them. The broker does not emit them.

Events of protocol version 2

NDJSON Format

Events are sent as newline-delimited JSON:
Benefits:
  • Streaming-friendly - Parse events as they arrive
  • Memory efficient - No buffering entire response
  • Simple parsing - Split by newline, parse each line
A parser should bound the length of a line: the parsers of @enclave-vm/stream and the client refuse an event of more than 8 MiB by default.

Tool Call Flow

When a script calls a tool: There is no route or message with which a client submits a tool result: tools are registered on the broker (broker.tool(...)) and run there.

Encryption

The first-party client and broker do not encrypt. @enclave-vm/client, @enclave-vm/react, @enclave-vm/broker and @enclave-vm/runtime perform no handshake and have no encryption option: a session is plain NDJSON protected only by the transport, so use HTTPS. The protocol types in @enclave-vm/types define hello messages and an encrypted envelope, and @enclave-vm/stream exports matching primitives (ECDH P-256, HKDF-SHA-256, AES-256-GCM). They are defined, but the first-party client and broker do not use them. An application that wants payload encryption on top of TLS has to implement both ends itself; see Encrypted Sessions.

Hello Messages

ClientHello and ServerHello carry the ephemeral public keys of an ECDH key exchange:
The exchange is not authenticated. ServerHello has a reserved signatureB64 field, but nothing creates or verifies it. The exchange protects against a party that can only read the connection, not against one that can change messages.

Encrypted Envelope

An event of type enc wraps another event:
The stream primitives authenticate the header of the envelope (protocol version, session id, sequence number, key id) together with the event inside it. @enclave-vm/client does not decrypt enc events: a session that receives one fails with PARSE_ERROR.

Reconnection

The client reconnects to a session when its connection is lost, and the broker replays the events the client has not seen:

Sequence Tracking

Events include sequence numbers for ordering:
On reconnection, the client asks the broker for the events after the last one it received: GET /sessions/:sessionId/stream?fromSeq=N, where N is the next sequence number the client expects.

Event Filtering

A filter decides which events a client is sent. The body of POST /sessions may carry one (EnclaveClient has no option for it: send the request yourself, or filter on the server with createEventFilter):
mode is include (send only matching events) or exclude (do not send matching events). A rule can match by event type and by content. By default session_init and final are sent whatever the rules say. A filter that sets its own alwaysAllow list replaces that default: session_init and final are then filtered like any other event unless the list names them, so a reader that waits for final keeps it in the list. See Event Filtering for the patterns and the bounds on a filter. A filter is a convenience for the client, not a confidentiality control.

Protocol Constants