@enclave-vm/runtime 2.19.1 → 2.19.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,18 +4,19 @@
4
4
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5
5
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
6
6
 
7
- > Standalone runtime worker for EnclaveJS - deployable execution environment
7
+ > Building blocks of a runtime worker for EnclaveJS: session bookkeeping and channels
8
8
 
9
- The @enclave-vm/runtime package provides a standalone, deployable runtime worker for EnclaveJS. It can run as a standalone process, in a container, or as a serverless function, providing secure code execution with the EnclaveJS streaming protocol.
9
+ The @enclave-vm/runtime package contains the building blocks of a runtime worker: a worker object that keeps track of sessions, a session executor, and the channels between a worker and a broker.
10
10
 
11
- ## Features
11
+ > **This package is not a runnable service.** It does not execute code, starts no server and opens no port. It has no authentication, no TLS, no CORS, no HTTP or WebSocket endpoints, no serverless entry points, and it reads no environment variables. An `execute` request never runs code: it ends with `RuntimeNotImplementedError`. To run scripts use [@enclave-vm/broker](../broker) (sessions, tools and streaming over HTTP) or [@enclave-vm/core](../core) (the sandbox).
12
12
 
13
- - **Standalone Deployment**: Run as a standalone Node.js process
14
- - **Container Ready**: Docker support with minimal image size
15
- - **Serverless Compatible**: Deploy to AWS Lambda, Vercel, etc.
16
- - **WebSocket Support**: Real-time streaming via WebSocket
17
- - **HTTP API**: REST-like HTTP interface for simple integrations
18
- - **Configurable Security**: Multiple security levels and resource limits
13
+ ## What Is in the Package
14
+
15
+ - **Runtime worker**: `createRuntimeWorker(config?)` keeps the sessions of the requests that the embedding application hands to it
16
+ - **Session executor**: `SessionExecutor` holds one session and forwards its events to a channel
17
+ - **Channels**: `MemoryChannel` (in process) and `WebSocketChannel` (client side of a WebSocket connection)
18
+ - **`RuntimeNotImplementedError`**: thrown by the operations that are not implemented
19
+ - **`enclave-runtime`**: a command line program that says a standalone worker is not implemented and exits with an error
19
20
 
20
21
  ## Installation
21
22
 
@@ -27,291 +28,118 @@ yarn add @enclave-vm/runtime
27
28
  pnpm add @enclave-vm/runtime
28
29
  ```
29
30
 
30
- ## Quick Start
31
-
32
- ### CLI Usage
33
-
34
- ```bash
35
- # Start runtime server
36
- npx enclave-runtime --port 3000
37
-
38
- # With configuration file
39
- npx enclave-runtime --config runtime.config.json
31
+ ## Usage
40
32
 
41
- # With environment variables
42
- ENCLAVE_PORT=3000 ENCLAVE_SECURITY_LEVEL=strict npx enclave-runtime
43
- ```
33
+ ```typescript
34
+ import { createRuntimeWorker, createMemoryChannel, RuntimeNotImplementedError } from '@enclave-vm/runtime';
44
35
 
45
- ### Programmatic Usage
36
+ const worker = createRuntimeWorker({ maxSessions: 10 });
37
+ await worker.start(); // marks the worker as running; nothing is listening
46
38
 
47
- ```typescript
48
- import { createRuntime } from '@enclave-vm/runtime';
49
-
50
- const runtime = await createRuntime({
51
- port: 3000,
52
- securityLevel: 'strict',
53
- timeout: 30000,
54
- maxToolCalls: 100,
55
- tools: {
56
- 'data:fetch': async (args) => {
57
- return await fetchData(args.url);
58
- },
59
- },
60
- });
61
-
62
- await runtime.start();
63
- console.log('Runtime listening on port 3000');
64
-
65
- // Graceful shutdown
66
- process.on('SIGTERM', () => runtime.stop());
67
- ```
39
+ const channel = createMemoryChannel();
68
40
 
69
- ## Configuration
70
-
71
- ### Configuration File
72
-
73
- Create `runtime.config.json`:
74
-
75
- ```json
76
- {
77
- "port": 3000,
78
- "host": "0.0.0.0",
79
- "securityLevel": "strict",
80
- "timeout": 30000,
81
- "maxToolCalls": 100,
82
- "maxIterations": 10000,
83
- "cors": {
84
- "origin": ["https://app.example.com"],
85
- "credentials": true
86
- },
87
- "auth": {
88
- "type": "bearer",
89
- "tokens": ["token1", "token2"]
90
- },
91
- "tls": {
92
- "cert": "/path/to/cert.pem",
93
- "key": "/path/to/key.pem"
41
+ try {
42
+ await worker.handleRequest({ type: 'execute', sessionId: 's_123', code: 'return 1 + 1' }, channel);
43
+ } catch (error) {
44
+ if (error instanceof RuntimeNotImplementedError) {
45
+ console.log(error.code); // 'NOT_IMPLEMENTED'
94
46
  }
95
47
  }
96
- ```
97
-
98
- ### Environment Variables
99
-
100
- | Variable | Description | Default |
101
- | ------------------------ | ----------------------------------------- | ---------- |
102
- | `ENCLAVE_PORT` | Server port | `3000` |
103
- | `ENCLAVE_HOST` | Server host | `0.0.0.0` |
104
- | `ENCLAVE_SECURITY_LEVEL` | Security level | `standard` |
105
- | `ENCLAVE_TIMEOUT` | Execution timeout (ms) | `30000` |
106
- | `ENCLAVE_MAX_TOOL_CALLS` | Max tool calls | `100` |
107
- | `ENCLAVE_AUTH_TOKEN` | Auth token (comma-separated for multiple) | - |
108
-
109
- ## Docker Deployment
110
-
111
- ```dockerfile
112
- FROM node:22-slim
113
-
114
- WORKDIR /app
115
- RUN npm install @enclave-vm/runtime
116
-
117
- EXPOSE 3000
118
- CMD ["npx", "enclave-runtime"]
119
- ```
120
-
121
- Build and run:
122
-
123
- ```bash
124
- docker build -t enclave-runtime .
125
- docker run -p 3000:3000 enclave-runtime
126
- ```
127
48
 
128
- ## WebSocket API
49
+ // The channel received a session that started and ended with an error
50
+ console.log(channel.getEvents().map((event) => event.type)); // ['session_init', 'final']
129
51
 
130
- Connect to `ws://localhost:3000/ws`:
52
+ // No session is left behind
53
+ console.log(worker.getSessions()); // []
131
54
 
132
- ```typescript
133
- const ws = new WebSocket('ws://localhost:3000/ws');
134
-
135
- ws.onopen = () => {
136
- // Start session
137
- ws.send(
138
- JSON.stringify({
139
- type: 'start',
140
- code: `
141
- const user = await callTool('getUser', { id: 1 });
142
- return user;
143
- `,
144
- }),
145
- );
146
- };
147
-
148
- ws.onmessage = (event) => {
149
- const message = JSON.parse(event.data);
150
- switch (message.type) {
151
- case 'tool_call':
152
- console.log('Tool called:', message.name);
153
- // Handle tool call and send result
154
- ws.send(
155
- JSON.stringify({
156
- type: 'tool_result',
157
- id: message.id,
158
- data: {
159
- /* result */
160
- },
161
- }),
162
- );
163
- break;
164
- case 'result':
165
- console.log('Execution result:', message.value);
166
- break;
167
- case 'error':
168
- console.error('Error:', message.error);
169
- break;
170
- }
171
- };
55
+ await worker.stop();
172
56
  ```
173
57
 
174
- ## HTTP API
58
+ ## Runtime Worker
175
59
 
176
- ### Execute Code
60
+ `createRuntimeWorker(config?)` returns a worker (the class is exported as `RuntimeWorkerImpl`).
177
61
 
178
- ```bash
179
- POST /execute
180
- Content-Type: application/json
62
+ | Member | Description |
63
+ | --------------------------------- | --------------------------------------------------------------------------------------- |
64
+ | `start()` | Marks the worker as running, so that `handleRequest()` accepts `execute` requests |
65
+ | `stop()` | Cancels and removes the sessions the worker holds |
66
+ | `isRunning` | Whether the worker is in the `running` state |
67
+ | `getStats()` | State, session counts, start time, uptime and memory usage of the process |
68
+ | `getSessions()` | The sessions the worker holds: `sessionId`, `state`, `createdAt`, `expiresAt` |
69
+ | `handleRequest(request, channel)` | Handles one request (`execute`, `cancel`, `tool_result` or `ping`) from the application |
181
70
 
182
- {
183
- "code": "return 1 + 1",
184
- "timeout": 5000
185
- }
186
- ```
71
+ `handleRequest()` trusts its caller: nothing authenticates a request or checks where it came from.
187
72
 
188
- Response:
73
+ - **`execute`** never runs the code. A valid request rejects with `RuntimeNotImplementedError` (code `NOT_IMPLEMENTED`): the channel receives `session_init`, then a `final` event with `ok: false` and `error.code: 'NOT_IMPLEMENTED'`, and the session is removed again. A request to a worker that is not running, or without a string `code`, rejects with another error.
74
+ - **`cancel`** cancels the session with that id if the worker holds it. Otherwise the request is ignored.
75
+ - **`tool_result`** passes the result to the session with that id if the worker holds it. Otherwise the request is ignored.
76
+ - **`ping`** is accepted. Nothing is sent back.
189
77
 
190
- ```json
191
- {
192
- "success": true,
193
- "value": 2,
194
- "stats": {
195
- "duration": 15,
196
- "toolCallCount": 0
197
- }
198
- }
199
- ```
78
+ ### Configuration
200
79
 
201
- ### Health Check
80
+ | Option | Default | Description |
81
+ | --------------------- | ------------- | --------------------------------------------------------------------------------------- |
82
+ | `maxSessions` | `10` | Maximum number of sessions the worker holds. A positive integer, otherwise `RangeError` |
83
+ | `debug` | `false` | Log to the console |
84
+ | `port` | `3001` | Not used: no server is started |
85
+ | `host` | `'127.0.0.1'` | Not used: no server is started |
86
+ | `wsPath` | `'/ws'` | Not used: no server is started |
87
+ | `defaultLimits` | `{}` | Accepted, not read by the worker |
88
+ | `heartbeatIntervalMs` | `15000` | Accepted, not read by the worker |
89
+ | `connectionTimeoutMs` | `30000` | Accepted, not read by the worker |
202
90
 
203
- ```bash
204
- GET /health
205
- ```
91
+ ## Session Executor
206
92
 
207
- Response:
93
+ `createSessionExecutor({ sessionId?, code, limits?, channel, debug? })` creates a `SessionExecutor`. It keeps the code and never runs it.
208
94
 
209
- ```json
210
- {
211
- "status": "healthy",
212
- "uptime": 3600,
213
- "activeSessions": 5
214
- }
215
- ```
95
+ - `execute()` always rejects with `RuntimeNotImplementedError`. The first call ends the session: the channel receives `session_init` and the `final` event described above.
96
+ - `cancel(reason?)` and `submitToolResult(callId, success, value?, error?)` go to the session.
97
+ - `getInfo()`, `state` and `isTerminal` describe the session. `dispose()` stops forwarding events to the channel.
216
98
 
217
- ## Tool Handlers
99
+ ## Channels
218
100
 
219
- Register tool handlers programmatically:
101
+ A channel implements `RuntimeChannel`: `send(event)`, `onMessage(handler)`, `close()` and `isOpen`.
220
102
 
221
103
  ```typescript
222
- import { createRuntime } from '@enclave-vm/runtime';
223
-
224
- const runtime = await createRuntime({
225
- tools: {
226
- // Simple handler
227
- 'math:add': async ({ a, b }) => a + b,
228
-
229
- // Handler with validation
230
- 'users:get': {
231
- handler: async ({ id }) => {
232
- return await db.users.findById(id);
233
- },
234
- schema: {
235
- id: { type: 'number', required: true },
236
- },
237
- },
238
-
239
- // Async generator for streaming
240
- 'data:stream': async function* ({ items }) {
241
- for (const item of items) {
242
- yield await processItem(item);
243
- }
244
- },
245
- },
246
- });
247
- ```
104
+ import { createMemoryChannel, createMemoryChannelPair, createWebSocketChannel } from '@enclave-vm/runtime';
248
105
 
249
- ## Serverless Deployment
106
+ // In process: keeps the events that were sent
107
+ const channel = createMemoryChannel();
108
+ channel.getEvents();
250
109
 
251
- ### AWS Lambda
110
+ // Two connected channels: what one sends, the handlers of the other receive
111
+ const { client, server } = createMemoryChannelPair();
252
112
 
253
- ```typescript
254
- import { createLambdaHandler } from '@enclave-vm/runtime/lambda';
255
-
256
- export const handler = createLambdaHandler({
257
- securityLevel: 'strict',
258
- timeout: 10000,
259
- tools: {
260
- // Tool handlers
261
- },
262
- });
113
+ // Client side of a WebSocket connection
114
+ const remote = createWebSocketChannel({ url: 'wss://worker.example.com/ws' });
115
+ await remote.connect();
263
116
  ```
264
117
 
265
- ### Vercel Edge
118
+ `WebSocketChannel` is the client side only. It connects to a URL and nothing more:
266
119
 
267
- ```typescript
268
- import { createEdgeHandler } from '@enclave-vm/runtime/edge';
120
+ - It sends no credentials. Authenticate the connection in the server behind the URL.
121
+ - It parses incoming messages as JSON and hands them to the handlers without validating them against a schema. Validate them in the handler.
122
+ - While it is not connected it keeps at most `maxBufferedMessages` events (default 1000) and drops the rest.
123
+ - It reconnects with exponential backoff (`reconnect.maxRetries`, default 5).
124
+ - Where there is no global `WebSocket`, it needs the `ws` package, which is not installed with this package.
269
125
 
270
- export default createEdgeHandler({
271
- securityLevel: 'strict',
272
- tools: {
273
- // Tool handlers
274
- },
275
- });
126
+ ## Command Line
276
127
 
277
- export const config = { runtime: 'edge' };
128
+ ```bash
129
+ npx enclave-runtime --help
278
130
  ```
279
131
 
280
- ## Monitoring
281
-
282
- ```typescript
283
- import { createRuntime } from '@enclave-vm/runtime';
284
-
285
- const runtime = await createRuntime({
286
- metrics: {
287
- enabled: true,
288
- endpoint: '/metrics', // Prometheus format
289
- },
290
- logging: {
291
- level: 'info',
292
- format: 'json',
293
- },
294
- });
295
-
296
- // Access metrics
297
- runtime.on('execution:complete', (stats) => {
298
- console.log(`Execution completed in ${stats.duration}ms`);
299
- });
300
-
301
- runtime.on('execution:error', (error) => {
302
- console.error('Execution failed:', error);
303
- });
304
- ```
132
+ The `enclave-runtime` program does not start a worker. It checks its arguments (`--port`, `--host`, `--max-sessions`, `--debug`), prints that a standalone worker is not implemented, and exits with code 1. `--help` prints the help and exits with code 0.
305
133
 
306
134
  ## Related Packages
307
135
 
308
- | Package | Description |
309
- | ----------------------------------------- | ---------------------------------- |
310
- | [@enclave-vm/core](../enclave-vm) | Core execution engine |
311
- | [@enclave-vm/types](../enclavejs-types) | Type definitions and Zod schemas |
312
- | [@enclave-vm/stream](../enclavejs-stream) | Streaming protocol implementation |
313
- | [@enclave-vm/broker](../enclavejs-broker) | Tool broker and session management |
314
- | [@enclave-vm/client](../enclavejs-client) | Browser/Node.js client SDK |
136
+ | Package | Description |
137
+ | ------------------------------- | ---------------------------------- |
138
+ | [@enclave-vm/core](../core) | Core execution engine |
139
+ | [@enclave-vm/types](../types) | Type definitions and Zod schemas |
140
+ | [@enclave-vm/stream](../stream) | Streaming protocol implementation |
141
+ | [@enclave-vm/broker](../broker) | Tool broker and session management |
142
+ | [@enclave-vm/client](../client) | Browser/Node.js client SDK |
315
143
 
316
144
  ## License
317
145
 
@@ -3,6 +3,10 @@
3
3
  *
4
4
  * WebSocket-based channel for remote runtime communication.
5
5
  *
6
+ * The channel connects to a URL and nothing more: it sends no credentials, and it hands every
7
+ * JSON message it receives to its handlers without checking the message against a schema.
8
+ * Authenticate the connection in the URL's server and validate messages in the handler.
9
+ *
6
10
  * @packageDocumentation
7
11
  */
8
12
  import type { StreamEvent, RuntimeChannelMessage } from '@enclave-vm/types';
@@ -29,6 +33,12 @@ export interface WebSocketChannelConfig {
29
33
  * @default 10000
30
34
  */
31
35
  connectionTimeoutMs?: number;
36
+ /**
37
+ * Events kept while the channel is not connected. Events sent beyond that are dropped
38
+ * until the channel is connected again. A positive integer.
39
+ * @default 1000
40
+ */
41
+ maxBufferedMessages?: number;
32
42
  /**
33
43
  * Debug mode
34
44
  */
package/cli.d.ts CHANGED
@@ -2,16 +2,18 @@
2
2
  /**
3
3
  * Enclave Runtime CLI
4
4
  *
5
- * Standalone runtime worker that can be deployed independently.
5
+ * A standalone runtime worker is not implemented: `@enclave-vm/runtime` does not execute code
6
+ * and starts no server. This program checks its arguments, says so, and exits with an error,
7
+ * so that nothing takes it for a running service.
6
8
  *
7
9
  * Usage:
8
10
  * npx enclave-runtime [options]
9
11
  *
10
12
  * Options:
11
- * --port <port> Port to listen on (default: 3001)
12
- * --host <host> Host to bind to (default: 0.0.0.0)
13
- * --max-sessions <n> Maximum concurrent sessions (default: 10)
14
- * --debug Enable debug logging
13
+ * --port <port> Reserved (nothing listens)
14
+ * --host <host> Reserved (nothing listens)
15
+ * --max-sessions <n> Reserved
16
+ * --debug Reserved
15
17
  * --help Show help
16
18
  *
17
19
  * @packageDocumentation