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.

​
Installation

npm install @enclave-vm/types

​
Protocol Identifiers

​
Session and Call IDs

import {
  generateSessionId,
  generateCallId,
  generateRefId,
  isSessionId,
  isCallId,
  isRefId,
  SESSION_ID_PREFIX,  // 'ses_'
  CALL_ID_PREFIX,     // 'call_'
  REF_ID_PREFIX,      // 'ref_'
  PROTOCOL_VERSION,   // 1
} from '@enclave-vm/types';

// Generate unique IDs
const sessionId = generateSessionId();  // 'ses_a1b2c3d4-...'
const callId = generateCallId();        // 'call_e5f6g7h8-...'
const refId = generateRefId();          // 'ref_i9j0k1l2-...'

// Type guards
if (isSessionId(id)) {
  // id is SessionId
}

​
Session State Machine

import { SessionState } from '@enclave-vm/types';

// Possible states
type SessionState =
  | 'running'
  | 'waiting_for_tool'
  | 'completed'
  | 'error'
  | 'cancelled';

​
Session Limits

import { DEFAULT_SESSION_LIMITS, type SessionLimits } from '@enclave-vm/types';

const limits: SessionLimits = {
  timeout: 30000,           // Max execution time (ms)
  memoryLimit: 128 * 1024 * 1024,  // Max memory (bytes)
  maxToolCalls: 100,        // Max tool invocations
  maxConsoleBytes: 1024 * 1024,    // Max console output
};

// Defaults
console.log(DEFAULT_SESSION_LIMITS);

​
Stream Events

​
Event Types

import {
  EventType,
  isSessionInitEvent,
  isStdoutEvent,
  isLogEvent,
  isToolCallEvent,
  isToolResultAppliedEvent,
  isFinalEvent,
  isHeartbeatEvent,
  isErrorEvent,
} from '@enclave-vm/types';

// Event type enum values
EventType.SESSION_INIT         // 'session_init'
EventType.STDOUT               // 'stdout'
EventType.LOG                  // 'log'
EventType.TOOL_CALL            // 'tool_call'
EventType.TOOL_RESULT_APPLIED  // 'tool_result_applied'
EventType.FINAL                // 'final'
EventType.HEARTBEAT            // 'heartbeat'
EventType.ERROR                // 'error'

​
Event Structures

import type {
  StreamEvent,
  SessionInitEvent,
  StdoutEvent,
  LogEvent,
  ToolCallEvent,
  FinalEvent,
  ErrorEvent,
} from '@enclave-vm/types';

// Session Init
const initEvent: SessionInitEvent = {
  type: 'session_init',
  sessionId: 'ses_...',
  seq: 0,
  timestamp: Date.now(),
  payload: {
    limits: { timeout: 30000 },
    encryption: null,
  },
};

// Stdout
const stdoutEvent: StdoutEvent = {
  type: 'stdout',
  sessionId: 'ses_...',
  seq: 1,
  timestamp: Date.now(),
  payload: { chunk: 'Hello, world!\n' },
};

// Log
const logEvent: LogEvent = {
  type: 'log',
  sessionId: 'ses_...',
  seq: 2,
  timestamp: Date.now(),
  payload: {
    level: 'info',  // 'debug' | 'info' | 'warn' | 'error'
    message: 'Processing started',
    data: { step: 1 },
  },
};

// Tool Call
const toolCallEvent: ToolCallEvent = {
  type: 'tool_call',
  sessionId: 'ses_...',
  seq: 3,
  timestamp: Date.now(),
  payload: {
    callId: 'call_...',
    name: 'fetchData',
    args: { url: 'https://api.example.com' },
    timeout: 5000,
  },
};

// Final
const finalEvent: FinalEvent = {
  type: 'final',
  sessionId: 'ses_...',
  seq: 10,
  timestamp: Date.now(),
  payload: {
    result: { value: 42, success: true },
    stats: {
      executionTime: 1234,
      toolCalls: 3,
      memoryUsage: 1024 * 1024,
    },
  },
};

​
Zod Schemas

All types have corresponding Zod schemas for runtime validation: 
import {
  SessionIdSchema,
  StreamEventSchema,
  SessionInitEventSchema,
  ToolCallEventSchema,
  parseStreamEvent,
} from '@enclave-vm/types';

// Validate a session ID
const result = SessionIdSchema.safeParse('ses_abc123');
if (result.success) {
  console.log('Valid session ID:', result.data);
}

// Parse and validate stream events
const parsed = parseStreamEvent(jsonData);
if (parsed.success) {
  const event = parsed.data;
  // event is typed as StreamEvent
}

​
Available Schemas

SchemaDescription
SessionIdSchemaSession ID format validation
CallIdSchemaCall ID format validation
RefIdSchemaReference ID format validation
SessionLimitsSchemaSession limits configuration
StreamEventSchemaUnion of all event types
SessionInitEventSchemaSession init event
StdoutEventSchemaStdout event
LogEventSchemaLog event
ToolCallEventSchemaTool call event
FinalEventSchemaFinal event
ErrorEventSchemaError event

​
Encryption Types

import {
  SupportedCurve,      // 'P-256' | 'P-384' | 'P-521'
  EncryptionAlgorithm, // 'AES-GCM'
  KeyDerivation,       // 'HKDF'
  EncryptionMode,      // 'none' | 'required' | 'optional'
  AES_GCM_NONCE_SIZE,  // 12
  AES_GCM_TAG_SIZE,    // 16
  AES_256_KEY_SIZE,    // 32
  isEncryptedEnvelope,
} from '@enclave-vm/types';

import type {
  EncryptedEnvelope,
  ClientHello,
  ServerHello,
} from '@enclave-vm/types';

// Client hello for key exchange
const clientHello: ClientHello = {
  type: 'client_hello',
  publicKey: 'base64-encoded-public-key',
  curve: 'P-256',
};

// Server hello response
const serverHello: ServerHello = {
  type: 'server_hello',
  publicKey: 'base64-encoded-server-public-key',
  sessionId: 'ses_...',
};

// Encrypted envelope
const envelope: EncryptedEnvelope = {
  type: 'encrypted',
  payload: {
    ciphertext: 'base64-encrypted-data',
    nonce: 'base64-nonce',
    tag: 'base64-auth-tag',
  },
};

​
Event Filtering Types

import {
  FilterMode,
  PatternType,
  DEFAULT_ALWAYS_ALLOW,
} from '@enclave-vm/types';

import type {
  ContentPattern,
  TypeFilter,
  ContentFilter,
  EventFilterConfig,
} from '@enclave-vm/types';

// Filter modes
FilterMode.INCLUDE  // Only include matching events
FilterMode.EXCLUDE  // Exclude matching events

// Pattern types
PatternType.EXACT   // Exact string match
PatternType.PREFIX  // Prefix match
PatternType.REGEX   // Regular expression
PatternType.GLOB    // Glob pattern (*, ?)

// Filter configuration
const filterConfig: EventFilterConfig = {
  typeFilter: {
    mode: FilterMode.EXCLUDE,
    types: ['heartbeat'],  // Exclude heartbeats
  },
  contentFilter: {
    patterns: [
      {
        type: PatternType.PREFIX,
        content: 'DEBUG:',
      },
    ],
    mode: FilterMode.EXCLUDE,
  },
};

​
Runtime Channel Messages

import {
  RuntimeChannelMessageType,
  parseRuntimeChannelMessage,
} from '@enclave-vm/types';

import type {
  ToolResultSubmitMessage,
  CancelMessage,
  RuntimeChannelMessage,
} from '@enclave-vm/types';

// Submit tool result
const toolResult: ToolResultSubmitMessage = {
  type: 'tool_result',
  payload: {
    callId: 'call_...',
    result: { data: 'fetched data' },
    error: null,
  },
};

// Cancel execution
const cancel: CancelMessage = {
  type: 'cancel',
  payload: {
    sessionId: 'ses_...',
    reason: 'User requested cancellation',
  },
};

​
Reference Tokens

import {
  isRefToken,
  createRefToken,
} from '@enclave-vm/types';

import type { RefToken } from '@enclave-vm/types';

// Create a reference token for large data
const token = createRefToken();
// { __ref: 'ref_uuid-here' }

// Check if value is a reference token
if (isRefToken(value)) {
  // value has type RefToken
  console.log(value.__ref);
}