@enclave-vm/runtime 2.19.1 → 2.20.0-rc.1
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 +85 -257
- package/channels/websocket-channel.d.ts +12 -0
- package/cli.d.ts +7 -5
- package/cli.js +34 -351
- package/esm/cli.mjs +34 -351
- package/esm/index.mjs +91 -31
- package/index.d.ts +12 -11
- package/index.js +92 -31
- package/package.json +5 -5
- package/runtime-worker.d.ts +19 -6
- package/session-executor.d.ts +25 -6
- package/types.d.ts +8 -5
package/README.md
CHANGED
|
@@ -4,18 +4,19 @@
|
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
[](https://www.typescriptlang.org/)
|
|
6
6
|
|
|
7
|
-
>
|
|
7
|
+
> Building blocks of a runtime worker for EnclaveJS: session bookkeeping and channels
|
|
8
8
|
|
|
9
|
-
The @enclave-vm/runtime package
|
|
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
|
-
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
-
|
|
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
|
-
##
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
```
|
|
33
|
+
```typescript
|
|
34
|
+
import { createRuntimeWorker, createMemoryChannel, RuntimeNotImplementedError } from '@enclave-vm/runtime';
|
|
44
35
|
|
|
45
|
-
|
|
36
|
+
const worker = createRuntimeWorker({ maxSessions: 10 });
|
|
37
|
+
await worker.start(); // marks the worker as running; nothing is listening
|
|
46
38
|
|
|
47
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
-
|
|
52
|
+
// No session is left behind
|
|
53
|
+
console.log(worker.getSessions()); // []
|
|
131
54
|
|
|
132
|
-
|
|
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
|
-
##
|
|
58
|
+
## Runtime Worker
|
|
175
59
|
|
|
176
|
-
|
|
60
|
+
`createRuntimeWorker(config?)` returns a worker (the class is exported as `RuntimeWorkerImpl`).
|
|
177
61
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
-
|
|
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
|
-
|
|
191
|
-
{
|
|
192
|
-
"success": true,
|
|
193
|
-
"value": 2,
|
|
194
|
-
"stats": {
|
|
195
|
-
"duration": 15,
|
|
196
|
-
"toolCallCount": 0
|
|
197
|
-
}
|
|
198
|
-
}
|
|
199
|
-
```
|
|
78
|
+
### Configuration
|
|
200
79
|
|
|
201
|
-
|
|
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
|
-
|
|
204
|
-
GET /health
|
|
205
|
-
```
|
|
91
|
+
## Session Executor
|
|
206
92
|
|
|
207
|
-
|
|
93
|
+
`createSessionExecutor({ sessionId?, code, limits?, channel, debug? })` creates a `SessionExecutor`. It keeps the code and never runs it.
|
|
208
94
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
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
|
-
##
|
|
99
|
+
## Channels
|
|
218
100
|
|
|
219
|
-
|
|
101
|
+
A channel implements `RuntimeChannel`: `send(event)`, `onMessage(handler)`, `close()` and `isOpen`.
|
|
220
102
|
|
|
221
103
|
```typescript
|
|
222
|
-
import {
|
|
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
|
-
|
|
106
|
+
// In process: keeps the events that were sent
|
|
107
|
+
const channel = createMemoryChannel();
|
|
108
|
+
channel.getEvents();
|
|
250
109
|
|
|
251
|
-
|
|
110
|
+
// Two connected channels: what one sends, the handlers of the other receive
|
|
111
|
+
const { client, server } = createMemoryChannelPair();
|
|
252
112
|
|
|
253
|
-
|
|
254
|
-
|
|
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
|
-
|
|
118
|
+
`WebSocketChannel` is the client side only. It connects to a URL and nothing more:
|
|
266
119
|
|
|
267
|
-
|
|
268
|
-
|
|
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
|
-
|
|
271
|
-
securityLevel: 'strict',
|
|
272
|
-
tools: {
|
|
273
|
-
// Tool handlers
|
|
274
|
-
},
|
|
275
|
-
});
|
|
126
|
+
## Command Line
|
|
276
127
|
|
|
277
|
-
|
|
128
|
+
```bash
|
|
129
|
+
npx enclave-runtime --help
|
|
278
130
|
```
|
|
279
131
|
|
|
280
|
-
|
|
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
|
|
309
|
-
|
|
|
310
|
-
| [@enclave-vm/core](../
|
|
311
|
-
| [@enclave-vm/types](../
|
|
312
|
-
| [@enclave-vm/stream](../
|
|
313
|
-
| [@enclave-vm/broker](../
|
|
314
|
-
| [@enclave-vm/client](../
|
|
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
|
*/
|
|
@@ -50,6 +60,8 @@ export declare class WebSocketChannel implements RuntimeChannel {
|
|
|
50
60
|
private readonly messageHandlers;
|
|
51
61
|
private retryCount;
|
|
52
62
|
private retryTimeout;
|
|
63
|
+
/** Fails the connect that is in progress, if any. */
|
|
64
|
+
private pendingConnectFailure;
|
|
53
65
|
private messageBuffer;
|
|
54
66
|
constructor(config: WebSocketChannelConfig);
|
|
55
67
|
/**
|
package/cli.d.ts
CHANGED
|
@@ -2,16 +2,18 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* Enclave Runtime CLI
|
|
4
4
|
*
|
|
5
|
-
*
|
|
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>
|
|
12
|
-
* --host <host>
|
|
13
|
-
* --max-sessions <n>
|
|
14
|
-
* --debug
|
|
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
|