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 everyheartbeatIntervalMs (15 seconds by default):
final
The last event of a session. A session that succeeded:"ok": false and an error with a message and a code in place of result.
error
An error that is reported besides thefinal event. The broker emits one when a session is cancelled while no script is executing:
stdout and log
The protocol definesstdout (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:- Streaming-friendly - Parse events as they arrive
- Memory efficient - No buffering entire response
- Simple parsing - Split by newline, parse each line
@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:
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 typeenc wraps another event:
@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: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 ofPOST /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
Related
- EnclaveJS Overview - Streaming runtime architecture
- @enclave-vm/types - Type definitions
- @enclave-vm/stream - Stream utilities