Skip to main content

@enclave-vm/client

Browser and Node.js client SDK for connecting to an EnclaveJS broker. Provides streaming execution, event handling, cancellation, and automatic reconnection.

Installation

Quick Start

Client Configuration

Together with fetch (see Node.js Usage), these are all the options. Any other option makes the constructor throw a TypeError that names it: the client has no encryption, auth, serverUrl or reconnect option. A value the client cannot use, such as a timeout of 0, throws as well.
The client does not encrypt. Requests and events travel as plain JSON over HTTP and are protected only by the transport: use an https: base URL, and send credentials with headers.

Executing Code

Basic Execution

executeStream() returns the handle at once, not a promise. execute(code, options) is the same as executeStream(code, options).wait().

Execution Options

Both methods take the same options: the three below, plus the event handlers.
Of the fields of SessionLimits, the client sends sessionTtlMs, maxToolCalls and heartbeatIntervalMs to the broker. timeout and limits.sessionTtlMs are different things. timeout is how long the client waits for the broker to say something; a session that keeps sending events, heartbeats included, stays open. limits.sessionTtlMs asks the broker to limit how long the session may last.

Event Handlers

All Event Types

The end of the session has no handler of its own: the result comes from the promise of execute(), or from wait() on the handle. Tools run on the broker. onToolCall and onToolResultApplied tell the client about them; the client executes nothing and has no API to register tools.

Event Handler Shortcuts

Session Handle

executeStream() returns a session handle for managing the execution:

Session Result

Cancelling

There are three ways to cancel a session, and they do the same:
The session ends in the client as CANCELLED, and the broker is asked to end it with DELETE {baseUrl}/sessions/:sessionId. No further event of the session is delivered after that. Cancelling does not reject: if the broker does not confirm the stop, onError is called with the code CANCEL_FAILED, and the script may still be running.

Error Handling

A session that fails is not a rejected promise. execute() and wait() resolve with success: false and an error:

Error Codes

error.code is one of the client’s codes below, or the code that the broker sent with the end of the session.

Session Lookup

getSession() asks the broker about a session. It resolves with null when the broker does not know the session, and it is the one method that rejects, with an EnclaveClientError:

Reconnection

A connection counts as lost when a request fails, when the stream ends before the session is complete, or when the broker stays silent for longer than the client waits. With autoReconnect on, the client then reconnects, up to maxReconnectAttempts times in a row and with a growing delay, and asks the broker for the events after the last one it delivered. Every event is delivered once and in order, and nothing is delivered after the final event. If the attempts are used up, or autoReconnect is off, the session fails with the code of the last failure.

Connection State

ConnectionState is re-exported from @enclave-vm/stream. The client tracks the connection of each session internally; the session handle does not expose it.

Multiple Sessions

Browser Usage

Node.js Usage

Or provide a fetch implementation of your own:
Where there is no global fetch, the fetch option is required. The implementation has to return a standard Response: the client reads the events from its body stream.

TypeScript Types