Skip to main content

@enclave-vm/types

Type definitions and Zod schemas for the EnclaveJS streaming runtime protocol. This package provides the foundation for type-safe communication between all EnclaveJS components. It holds types, constants, schemas and type guards; it sends and receives nothing.

Installation

Protocol Identifiers

Session and Call IDs

Session States

Session Limits

These are the fields of the type. What each one bounds is decided by the component that applies it: see the limits of the broker.

Stream Events

Event Types

Event Structures

Every event has protocolVersion, sessionId, a sequence number seq, a type and a payload. There is no timestamp field.
A failed session has ok: false and error: { message, code? } in its final payload.

Zod Schemas

The types have corresponding Zod schemas for runtime validation:
parseStreamEvent, parseEncryptedEnvelope, parseRuntimeChannelMessage, parseCreateSessionRequest and parseStreamEventOrEncrypted return the result of safeParse.

Available Schemas

These schemas describe the wire format. A component may accept less than a schema allows: the broker, for example, accepts session ids of a fixed alphabet and length only.

Encryption Types

These are type definitions. @enclave-vm/client, @enclave-vm/react, @enclave-vm/broker and @enclave-vm/runtime do not encrypt: they perform no handshake, the client ends a session that receives an enc event, and the broker refuses a request that requires encryption. @enclave-vm/stream exports primitives for these types, with a key exchange that is not authenticated; no package uses them. Sessions are plain JSON protected by the transport, so use HTTPS.

Event Filtering Types

A rule matches when its type filter and its content filter both match; a filter matches when one of its rules does. The broker applies these configurations; see Event Filtering.

Runtime Channel Messages

These are the messages a middleware sends to a runtime over a channel; the channel types of @enclave-vm/core sessions and of @enclave-vm/runtime carry them. The broker does not use such a channel: it runs the sandbox in process and applies tool results itself, and @enclave-vm/runtime does not execute scripts.

Reference Tokens

The type is part of the protocol definitions. The reference sidecar of @enclave-vm/core does not use it: there a reference is a string of the form __REF_<uuid>__ (see Reference Sidecar).