@enclave-vm/runtime 2.20.0 → 2.20.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.
Files changed (2) hide show
  1. package/README.md +48 -44
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,34 +1,24 @@
1
1
  # @enclave-vm/runtime
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@enclave-vm/runtime.svg)](https://www.npmjs.com/package/@enclave-vm/runtime)
4
- [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
6
-
7
- > Building blocks of a runtime worker for EnclaveJS: session bookkeeping and channels
8
-
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.
3
+ Building blocks of an EnclaveJS runtime worker (session bookkeeping and channels), for developers who want to build a worker of their own. It does not execute code.
10
4
 
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).
5
+ [![npm version](https://img.shields.io/npm/v/@enclave-vm/runtime.svg)](https://www.npmjs.com/package/@enclave-vm/runtime)
6
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/agentfront/enclave/blob/main/LICENSE)
7
+ [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](https://nodejs.org)
12
8
 
13
- ## What Is in the Package
9
+ The package builds on [`@enclave-vm/core`](https://www.npmjs.com/package/@enclave-vm/core) (sessions), [`@enclave-vm/stream`](https://www.npmjs.com/package/@enclave-vm/stream) and [`@enclave-vm/types`](https://www.npmjs.com/package/@enclave-vm/types). It contains a worker object that keeps track of sessions, a session executor, and the channels between a worker and a broker.
14
10
 
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
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`](https://www.npmjs.com/package/@enclave-vm/broker) (sessions, tools and streaming over HTTP) or [`@enclave-vm/core`](https://www.npmjs.com/package/@enclave-vm/core) (the sandbox).
20
12
 
21
- ## Installation
13
+ ## Install
22
14
 
23
15
  ```bash
24
16
  npm install @enclave-vm/runtime
25
- # or
26
- yarn add @enclave-vm/runtime
27
- # or
28
- pnpm add @enclave-vm/runtime
29
17
  ```
30
18
 
31
- ## Usage
19
+ Requires Node.js 18 or later. `WebSocketChannel` also needs the `ws` package where there is no global `WebSocket` (see [Channels](#channels)).
20
+
21
+ ## Quick start
32
22
 
33
23
  ```typescript
34
24
  import { createRuntimeWorker, createMemoryChannel, RuntimeNotImplementedError } from '@enclave-vm/runtime';
@@ -55,7 +45,7 @@ console.log(worker.getSessions()); // []
55
45
  await worker.stop();
56
46
  ```
57
47
 
58
- ## Runtime Worker
48
+ ## Runtime worker
59
49
 
60
50
  `createRuntimeWorker(config?)` returns a worker (the class is exported as `RuntimeWorkerImpl`).
61
51
 
@@ -70,25 +60,25 @@ await worker.stop();
70
60
 
71
61
  `handleRequest()` trusts its caller: nothing authenticates a request or checks where it came from.
72
62
 
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.
63
+ - **`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, a request without a string `code`, a session id that is in use, or a worker at `maxSessions` rejects with another error.
74
64
  - **`cancel`** cancels the session with that id if the worker holds it. Otherwise the request is ignored.
75
65
  - **`tool_result`** passes the result to the session with that id if the worker holds it. Otherwise the request is ignored.
76
66
  - **`ping`** is accepted. Nothing is sent back.
77
67
 
78
68
  ### Configuration
79
69
 
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 |
70
+ | Option | Type | Default | Meaning |
71
+ | --------------------- | ------------------------ | ------------- | --------------------------------------------------------------------------------------- |
72
+ | `maxSessions` | `number` | `10` | Maximum number of sessions the worker holds. A positive integer, otherwise `RangeError` |
73
+ | `debug` | `boolean` | `false` | Log to the console |
74
+ | `port` | `number` | `3001` | Not used: no server is started |
75
+ | `host` | `string` | `'127.0.0.1'` | Not used: no server is started |
76
+ | `wsPath` | `string` | `'/ws'` | Not used: no server is started |
77
+ | `defaultLimits` | `Partial<SessionLimits>` | `{}` | Accepted, not read by the worker |
78
+ | `heartbeatIntervalMs` | `number` | `15000` | Accepted, not read by the worker |
79
+ | `connectionTimeoutMs` | `number` | `30000` | Accepted, not read by the worker |
90
80
 
91
- ## Session Executor
81
+ ## Session executor
92
82
 
93
83
  `createSessionExecutor({ sessionId?, code, limits?, channel, debug? })` creates a `SessionExecutor`. It keeps the code and never runs it.
94
84
 
@@ -120,10 +110,10 @@ await remote.connect();
120
110
  - It sends no credentials. Authenticate the connection in the server behind the URL.
121
111
  - It parses incoming messages as JSON and hands them to the handlers without validating them against a schema. Validate them in the handler.
122
112
  - 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).
113
+ - It reconnects with exponential backoff (`reconnect.maxRetries`, default 5). `connectionTimeoutMs` defaults to 10000.
124
114
  - Where there is no global `WebSocket`, it needs the `ws` package, which is not installed with this package.
125
115
 
126
- ## Command Line
116
+ ## Command line
127
117
 
128
118
  ```bash
129
119
  npx enclave-runtime --help
@@ -131,16 +121,30 @@ npx enclave-runtime --help
131
121
 
132
122
  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.
133
123
 
134
- ## Related Packages
124
+ ## Security notes
125
+
126
+ - Nothing in this package authenticates or authorizes: `handleRequest()` acts on every request it is given, and `WebSocketChannel` sends no credentials.
127
+ - There is no transport security of its own: no TLS and no encryption. Use a `wss:` URL and authenticate in the server you connect to.
128
+ - Messages received over a `WebSocketChannel` are not validated.
129
+ - No code is executed, so no sandbox is involved. For sandboxed execution see `@enclave-vm/core` and `@enclave-vm/broker`.
130
+
131
+ ## Related packages
132
+
133
+ | Package | Role |
134
+ | ---------------------------------------------------------------------- | --------------------------------------- |
135
+ | [@enclave-vm/core](https://www.npmjs.com/package/@enclave-vm/core) | The sandbox that executes scripts |
136
+ | [@enclave-vm/broker](https://www.npmjs.com/package/@enclave-vm/broker) | Tool broker, sessions and HTTP routes |
137
+ | [@enclave-vm/types](https://www.npmjs.com/package/@enclave-vm/types) | Protocol types and Zod schemas |
138
+ | [@enclave-vm/stream](https://www.npmjs.com/package/@enclave-vm/stream) | NDJSON and reconnection helpers |
139
+ | [@enclave-vm/client](https://www.npmjs.com/package/@enclave-vm/client) | Browser and Node.js client for a broker |
140
+
141
+ ## Documentation
135
142
 
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 |
143
+ - Documentation: https://agentfront.dev/docs/guides/enclave
144
+ - Repository: https://github.com/agentfront/enclave
145
+ - Architecture: https://github.com/agentfront/enclave/blob/main/README-ARCHITECTURE.md
146
+ - Security policy: https://github.com/agentfront/enclave/blob/main/SECURITY.md
143
147
 
144
148
  ## License
145
149
 
146
- Apache-2.0
150
+ Apache-2.0. See [LICENSE](https://github.com/agentfront/enclave/blob/main/LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@enclave-vm/runtime",
3
- "version": "2.20.0",
3
+ "version": "2.20.1",
4
4
  "description": "Building blocks of a runtime worker for EnclaveJS: session bookkeeping and channels (does not execute code)",
5
5
  "author": "AgentFront <info@agentfront.dev>",
6
6
  "homepage": "https://github.com/agentfront/enclave",
@@ -36,9 +36,9 @@
36
36
  "enclave-runtime": "./cli.js"
37
37
  },
38
38
  "dependencies": {
39
- "@enclave-vm/core": "2.20.0",
40
- "@enclave-vm/stream": "2.20.0",
41
- "@enclave-vm/types": "2.20.0"
39
+ "@enclave-vm/core": "2.20.1",
40
+ "@enclave-vm/stream": "2.20.1",
41
+ "@enclave-vm/types": "2.20.1"
42
42
  },
43
43
  "devDependencies": {
44
44
  "ws": "^8.19.0"