Skip to main content
API reference for the @enclave-vm/client package - the client SDK for EnclaveJS.

Installation

EnclaveClient Class

The main client class for connecting to EnclaveJS brokers. It starts sessions over HTTP, reads their events as a stream, and returns their results.

Constructor

EnclaveClientConfig

These are all the options. The constructor throws a TypeError:
  • for any other option, and the message names it. The client has no encryption, auth, serverUrl or reconnect option.
  • for a value it cannot use, for example an empty baseUrl, a timeout of 0, or headers with a value that is not a string.
  • when there is no global fetch and none is passed.

Methods

execute(code, options?)

Execute code and wait for the result.
The promise resolves when the session ends. It does not reject: a session that fails or is cancelled resolves with success: false. The call is the same as executeStream(code, options).wait(). Example:

executeStream(code, options?)

Execute code and return a handle for the running session.
The handle is returned at once, not as a promise. Events go to the handlers in options as they arrive. Example:

getSession(sessionId)

Get session information from the broker.
Resolves with null when the broker answers 404. Rejects with an EnclaveClientError: SESSION_ERROR for a session ID that is not valid and for any other error status, TIMEOUT when the broker does not answer in time, NETWORK_ERROR when the request fails.

cancelSession(sessionId, reason?)

Cancel a session that this client is running. See Cancellation.
Does nothing when this client is not running a session with that ID.

Execute Options

execute() and executeStream() take the same options: ExecuteOptions together with the event handlers.
A session ID is a string that starts with s_. Anything else is refused before a request is made: execute() and executeStream() give a SESSION_ERROR result, and getSession() rejects. A session with an ID that is already running on the same client is refused the same way.

Session Handle

Session Result

Event Handling

Event Handlers

ErrorPayload and ToolProgressPhase are types of @enclave-vm/types. The final event has no handler of its own. It ends the session, and its content becomes the SessionResult that wait() and execute() resolve with. Tools run on the broker. onToolCall and onToolResultApplied tell the client about them; the client executes nothing and has no API to register tools or to submit tool results.

Processing Events

Event Types

onEvent, getEvents() and result.events work with the events themselves.

Cancellation

A session is cancelled with cancel() on its handle, with cancelSession(), or by aborting the signal it was started with. All three do the same:
  • The session ends in the client as CANCELLED, and no further event of it is delivered.
  • The broker is asked to end the session with DELETE {baseUrl}/sessions/:sessionId.
Cancelling does not reject. If the broker does not confirm the stop, onError is called with the code CANCEL_FAILED: the script may still be running. A session that is started with a signal that is already aborted ends as CANCELLED without a request being made.

Using AbortController

Transport and Credentials

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.
The headers are sent with every request of the client. The client has no method to change them: create a new client to use other credentials. A broker that sends encrypted events cannot be used with this client: an encrypted event ends the session with PARSE_ERROR.

Requests

config carries the limits of the session: { maxExecutionMs, maxToolCalls, heartbeatIntervalMs }, where maxExecutionMs is limits.sessionTtlMs. Session IDs are URL-encoded in the request paths.

Reconnection

Automatic Reconnection

A connection counts as lost when a request fails, when the stream ends before the final event, or when the broker stays silent for longer than the client waits. The client then reconnects:
  • up to maxReconnectAttempts times in a row. The count starts again when a connection delivers a new event.
  • after a delay that is based on reconnectDelay and grows with each attempt in a row.
  • asking 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 false, the session fails with the code of the last failure.

Timeouts

timeout is how long the client waits for the broker:
  • for the answer to a request.
  • for the next event on an open stream. Here the wait is never shorter than two heartbeat intervals of the session (15 seconds each, unless limits.heartbeatIntervalMs asks for another).
When the time runs out the connection counts as lost: the client reconnects if it may, otherwise the session fails with TIMEOUT. timeout does not limit how long a script runs. A session that keeps sending events, heartbeats included, stays open. To ask the broker for a limit on the duration of a session, use limits.sessionTtlMs.

Error Handling

A session that fails is not a rejected promise. execute() and wait() resolve with success: false and an error, whose code is one of the client’s codes or the code that the broker sent in the final event.

Error Codes

EnclaveClientError

getSession() rejects with an EnclaveClientError. It is the one method of the client that rejects.

Complete Example

Browser Usage

Exports

ConnectionState is re-exported from @enclave-vm/stream.