@enclave-vm/core 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.
package/README.md CHANGED
@@ -1,79 +1,75 @@
1
1
  # @enclave-vm/core
2
2
 
3
+ A sandbox for running AgentScript, the JavaScript subset that language models write to call tools, in Node.js. It validates a script, transforms it, runs it in a reduced realm behind a membrane with limits on time, iterations, tool calls and memory, and returns a plain-data result.
4
+
3
5
  [![npm version](https://img.shields.io/npm/v/@enclave-vm/core.svg)](https://www.npmjs.com/package/@enclave-vm/core)
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
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/agentfront/enclave/blob/main/LICENSE)
6
7
 
7
- > Secure AgentScript execution environment with defense-in-depth architecture
8
+ It is the runtime of [Enclave](https://github.com/agentfront/enclave). The static checks come from [`@enclave-vm/ast`](https://www.npmjs.com/package/@enclave-vm/ast); [`@enclave-vm/broker`](https://www.npmjs.com/package/@enclave-vm/broker) runs this package behind HTTP routes; [`@enclave-vm/browser`](https://www.npmjs.com/package/@enclave-vm/browser) is the counterpart for the browser.
8
9
 
9
- The @enclave-vm/core package provides a hardened execution environment for running LLM-generated JavaScript code (AgentScript) safely. It combines AST validation, code transformation, runtime guards, and VM sandboxing to prevent sandbox escapes and resource exhaustion.
10
+ ## How the Layers Fit Together
10
11
 
11
- ## Security
12
+ A script goes through these steps, in this order:
12
13
 
13
- | Metric | Value |
14
- | -------------- | ---------------------------------------------------------------------- |
15
- | Security Tests | 1900+ tests, 100% pass rate |
16
- | Attack Vectors | 150+ blocked (including function gadget attacks) |
17
- | CVE Protection | Covers known vm2, isolated-vm, node-vm exploits |
18
- | Defense Layers | 6 (Pre-Scanner, AST, Transform, Scoring, VM/Worker Pool, Sanitization) |
14
+ 1. **Pre-scanner** (`@enclave-vm/ast`): the source text, before anything parses it: size, lines, string literals, nesting, regex literals, bidirectional, invisible and look-alike characters.
15
+ 2. **AgentScript transform** (`transformAgentScript` of `@enclave-vm/ast`): the script is wrapped in `async function __ag_main()`, `callTool` becomes `__safe_callTool`, and loops get iteration checks. The validator receives the script as this step returns it.
16
+ 3. **AST validation** (`@enclave-vm/ast`): the AgentScript preset by default, an allowlist of syntax, globals and property keys.
17
+ 4. **Transformation after validation**: the deadline is checked in every function and loop body, concatenation is counted, and every computed key that is not a literal is checked at run time (`guardComputedMemberKeys`). What a static rule cannot decide, such as a property name the script builds while it runs, is decided here.
18
+ 5. **Scoring gate** (optional, off by default): a heuristic risk score from the script's tool calls.
19
+ 6. **Runtime sandbox**: by default a double VM in this process: the script runs in an inner realm that holds only the allowed globals, inside a parent realm that checks every tool call. Optionally the whole sandbox runs in a worker thread with a heap limit and a hard stop.
20
+ 7. **Output**: the returned value is copied into plain data, errors become bounded text without a stack from the sandbox, and oversized values are refused.
19
21
 
20
- For the full security audit report, see [SECURITY-AUDIT.md](./SECURITY-AUDIT.md). The invariants of the sandbox by layer, and the ones that are still open, are listed in [SECURITY-TESTS.md](../../SECURITY-TESTS.md): in process the time and memory limits are the enclave's own accounting, not the engine's (see [How `timeout` Is Enforced](#how-timeout-is-enforced) and [What `memoryLimit` Counts](#what-memorylimit-counts)).
22
+ ### What it does not do
21
23
 
22
- ## Features
24
+ - **It is not process isolation.** The default sandbox runs in your process and thread. A script that computes is stopped by checks in its own code; a single built-in call that does all its work natively is not interrupted (see [How `timeout` Is Enforced](#how-timeout-is-enforced)). For a stop the script cannot influence, use the [worker pool](#worker-pool-adapter); for tenants that must not share a process, or a host that must survive whatever a script allocates, run one enclave per process or container.
25
+ - **`memoryLimit` is the enclave's own accounting**, not a limit of the engine's heap (see [What `memoryLimit` Counts](#what-memorylimit-counts)).
26
+ - **It does not stop your `toolHandler`.** A tool call it stops waiting for keeps running in the host.
27
+ - **The scoring gate is a heuristic.** A low score is not evidence that a script is safe.
23
28
 
24
- - **Defense-in-Depth**: 6 layers of security (Pre-Scanner → AST → transformation → AI Scoring → VM/Worker Pool → output sanitization)
25
- - **Worker Pool Adapter**: Optional worker threads around the sandbox, with a heap limit per worker and a hard stop
26
- - **Safe Tool Calls**: Secure `callTool()` execution with iteration and call limits
27
- - **Reference Sidecar**: Handle large data without embedding it in the script
28
- - **Configurable Security Levels**: From STRICT to PERMISSIVE based on trust level
29
- - **Resource Limits**: Timeout, memory accounting, iteration limits, and tool call limits
30
- - **AI Scoring Gate**: Optional heuristic risk score for a script, from its tool calls and argument names
31
- - **Zero Dependencies on Vulnerable Packages**: Uses Node.js native `vm` module
29
+ The invariants of the sandbox by layer, and the ones that are still open, are listed in [SECURITY-TESTS.md](https://github.com/agentfront/enclave/blob/main/SECURITY-TESTS.md). [SECURITY-AUDIT.md](https://github.com/agentfront/enclave/blob/main/libs/core/SECURITY-AUDIT.md) is the audit report written for v2.4.0, kept as a record.
32
30
 
33
31
  ## Installation
34
32
 
35
33
  ```bash
36
34
  npm install @enclave-vm/core
37
- # or
38
- yarn add @enclave-vm/core
39
- # or
40
- pnpm add @enclave-vm/core
41
35
  ```
42
36
 
37
+ `@huggingface/transformers` and `vectoriadb` are optional peer dependencies, used only by the `local-llm` scorer of the [scoring gate](#ai-scoring-gate).
38
+
43
39
  ## Quick Start
44
40
 
45
41
  ```typescript
46
42
  import { Enclave } from '@enclave-vm/core';
47
43
 
48
- // Create enclave with a tool handler
49
44
  const enclave = new Enclave({
50
45
  timeout: 5000,
51
46
  maxToolCalls: 10,
52
47
  maxIterations: 1000,
53
48
  toolHandler: async (toolName, args) => {
54
- // Your tool execution logic
55
- return { success: true, data: `Called ${toolName}` };
49
+ if (toolName === 'getUser') return { id: args.id, name: 'Alice' };
50
+ if (toolName === 'getOrders') return [{ id: 1 }, { id: 2 }];
51
+ throw new Error(`Unknown tool: ${toolName}`);
56
52
  },
57
53
  });
58
54
 
59
- // Execute AgentScript code
60
55
  const result = await enclave.run(`
61
56
  const user = await callTool('getUser', { id: 123 });
62
57
  const orders = await callTool('getOrders', { userId: user.id });
63
- return { user, orderCount: orders.length };
58
+ return { user: user.name, orderCount: orders.length };
64
59
  `);
65
60
 
66
61
  if (result.success) {
67
- console.log('Result:', result.value);
62
+ console.log(result.value); // { user: 'Alice', orderCount: 2 }
68
63
  } else {
69
- console.error('Error:', result.error);
64
+ console.error(result.error);
70
65
  }
71
66
 
72
- // Always dispose when done
73
67
  enclave.dispose();
74
68
  ```
75
69
 
76
- ### Portable AgentScript runner
70
+ `runAgentScript(code, options)` creates an enclave, runs one script and disposes of it.
71
+
72
+ ### Portable AgentScript Runner
77
73
 
78
74
  Use the Worker entry when the host cannot load Node's `vm` or worker-thread modules. `AgentScriptRunner` pre-scans raw source, transforms AgentScript, validates the AST, and then runs it in the bounded interpreter. `InterpreterAdapter` is a lower-level adapter and does not perform those validation steps by itself.
79
75
 
@@ -107,26 +103,30 @@ The runner supports Node and Cloudflare Workers with `nodejs_compat`. Tool and h
107
103
  ```typescript
108
104
  interface CreateEnclaveOptions {
109
105
  // Execution limits
110
- timeout?: number; // Execution timeout in ms (default: 30000; by security level)
106
+ timeout?: number; // Execution timeout in ms (default: by security level, 30000 at STANDARD)
111
107
  toolCallGraceMs?: number; // How long a tool call in progress at the timeout may still take (default: same as timeout)
112
- maxToolCalls?: number; // Maximum tool calls allowed (default: 100; by security level)
113
- maxIterations?: number; // Maximum loop iterations (default: 10000; by security level)
108
+ maxToolCalls?: number; // Maximum tool calls allowed (default: by security level, 100 at STANDARD)
109
+ maxIterations?: number; // Maximum loop iterations (default: by security level, 10000 at STANDARD)
114
110
  memoryLimit?: number; // Memory limit in bytes, as the enclave counts it (default: 1048576, 1 MB; 0: off)
115
111
 
116
112
  // Security
117
113
  securityLevel?: SecurityLevel; // 'STRICT' | 'SECURE' | 'STANDARD' | 'PERMISSIVE' (default: 'STANDARD')
118
114
  preset?: AstPreset; // AST validation preset (default: 'agentscript')
115
+ preScan?: { preset?; config? }; // Pre-scanner preset or single limits (see "What the Pre-Scanner Checks")
119
116
  validate?: boolean; // Enable AST validation (default: true)
120
117
  transform?: boolean; // Enable code transformation (default: true)
121
118
  realmGlobals?: 'allowlist' | 'security-level'; // What exists in the script's realm (see "What the Script's Realm Holds")
119
+ secureProxyConfig?: Partial<SecureProxyLevelConfig>; // Override the membrane settings of the level
122
120
 
123
121
  // Where the sandbox runs
124
- adapter?: 'vm' | 'worker_threads'; // In this process (default) or in a pool of worker threads (see "Worker Pool Adapter")
122
+ adapter?: 'vm' | 'worker_threads'; // In this process (default) or in a pool of worker threads ('isolated-vm' is reserved, not implemented)
125
123
  workerPoolConfig?: Partial<WorkerPoolConfig>;
124
+ sandboxAdapter?: SandboxAdapter; // An adapter of your own
126
125
 
127
126
  // Tool execution
128
127
  toolHandler?: ToolHandler; // Function to execute tool calls
129
128
  toolNamespaces?: ToolNamespaces; // Expose tools as `ns.method(args)` (see "Tool Namespaces")
129
+ toolBridge?: { mode?: 'string' | 'direct'; maxPayloadBytes?: number; acknowledgeInsecureDirect?: boolean }; // default: 'string', 5 MB, false
130
130
 
131
131
  // Console
132
132
  consoleHandler?: ConsoleHandler; // Receive console calls as (level, message) instead of the host console (see "Console Handler")
@@ -137,21 +137,26 @@ interface CreateEnclaveOptions {
137
137
  globals?: Record<string, unknown>; // Additional globals for the VM
138
138
  allowFunctionsInGlobals?: boolean; // Allow functions in globals (default: false)
139
139
  maxGlobalFunctionCalls?: number; // Cap on calls into functions from globals (default: 10 × maxToolCalls)
140
+ allowBuiltins?: boolean; // default: false
140
141
 
141
- // Errors
142
+ // Results and errors
142
143
  sanitizeStackTraces?: boolean; // Redact paths/frames in every returned error (default: by security level)
144
+ maxSanitizeDepth?: number; // Deepest returned value (default: by security level)
145
+ maxSanitizeProperties?: number; // Most properties in a returned value (default: by security level)
143
146
 
144
147
  // Sidecar (large data handling)
145
148
  sidecar?: ReferenceSidecarOptions;
146
149
 
147
150
  // Scoring gate
148
- scoringGate?: ScoringGateConfig; // See "AI Scoring Gate" section
151
+ scoringGate?: ScoringGateConfig; // See "AI Scoring Gate"
149
152
 
150
153
  // Double VM security layer
151
- doubleVm?: PartialDoubleVmConfig; // See "Double VM Security Layer" section
154
+ doubleVm?: PartialDoubleVmConfig; // See "Double VM"
152
155
  }
153
156
  ```
154
157
 
158
+ `toolBridge.mode: 'direct'` throws at construction unless `acknowledgeInsecureDirect: true` is set as well.
159
+
155
160
  ### Option Values
156
161
 
157
162
  The constructor checks its options and throws a `TypeError` for a value outside the documented type or range:
@@ -177,16 +182,26 @@ The constructor checks its options and throws a `TypeError` for a value outside
177
182
 
178
183
  The portable interpreter additionally charges copied host-function results and tool responses by their serialized size to the cumulative allocation budget.
179
184
 
180
- A script that goes over the limit fails with `MEMORY_LIMIT_EXCEEDED`, and a script cannot switch the accounting off or reset it. With a limit set, a returned value whose serialized size is estimated above the limit (above 50 MB where the limit is larger) fails with `SERIALIZATION_LIMIT_EXCEEDED`. The limit is an estimate: where the host must survive whatever a script allocates, use the [worker pool](#worker-pool-adapter-optional), whose workers have a heap limit of the engine, or a child process or container with a memory limit of the operating system.
185
+ A script that goes over the limit fails with `MEMORY_LIMIT_EXCEEDED`, and a script cannot switch the accounting off or reset it. With a limit set, a returned value whose serialized size is estimated above the limit (above 50 MB where the limit is larger) fails with `SERIALIZATION_LIMIT_EXCEEDED`. The limit is an estimate: where the host must survive whatever a script allocates, use the [worker pool](#worker-pool-adapter), whose workers have a heap limit of the engine, or a child process or container with a memory limit of the operating system.
181
186
 
182
- ### Security Levels
187
+ ## Security Levels
183
188
 
184
- | Level | Description | Use Case |
185
- | ------------ | ------------------------------------------ | -------------------- |
186
- | `STRICT` | Maximum security, absolute minimum globals | Untrusted code |
187
- | `SECURE` | High security with safe utility functions | Semi-trusted code |
188
- | `STANDARD` | Balanced security for most use cases | Trusted code |
189
- | `PERMISSIVE` | Adds console for debugging | Internal/development |
189
+ The security level sets the defaults of the limits, the globals a script may use, and how the membrane answers a refused property.
190
+
191
+ | Setting | `STRICT` | `SECURE` | `STANDARD` (default) | `PERMISSIVE` |
192
+ | -------------------------------------------- | -------- | -------- | -------------------- | ------------------- |
193
+ | `timeout` | 5 s | 15 s | 30 s | 60 s |
194
+ | `maxIterations` | 1,000 | 5,000 | 10,000 | 100,000 |
195
+ | `maxToolCalls` | 10 | 50 | 100 | 1,000 |
196
+ | `maxConsoleCalls` | 100 | 500 | 1,000 | 10,000 |
197
+ | `maxConsoleOutputBytes` | 64 KB | 256 KB | 1 MB | 10 MB |
198
+ | `maxSanitizeDepth` / `maxSanitizeProperties` | 5 / 50 | 10 / 100 | 20 / 500 | 50 / 1,000 |
199
+ | `sanitizeStackTraces` | on | on | off | off |
200
+ | `allowFunctionsInGlobals` | off | off | off | on |
201
+ | A refused `constructor` | throws | throws | throws | allowed |
202
+ | Other refused properties | throw | throw | throw | read as `undefined` |
203
+
204
+ The values are exported as `SECURITY_LEVEL_CONFIGS`.
190
205
 
191
206
  ```typescript
192
207
  import { Enclave } from '@enclave-vm/core';
@@ -201,53 +216,34 @@ const enclave = new Enclave({
201
216
 
202
217
  ### Allowed Globals by Security Level
203
218
 
204
- Both AST validation and runtime sandbox enforce the same allowed globals for defense-in-depth:
205
-
206
- | Global | STRICT | SECURE | STANDARD | PERMISSIVE |
207
- | --------------------- | ------ | ------ | -------- | ---------- |
208
- | **Core API** | | | | |
209
- | `callTool` | ✅ | ✅ | ✅ | ✅ |
210
- | **Data Types** | | | | |
211
- | `Math` | ✅ | ✅ | ✅ | ✅ |
212
- | `JSON` | ✅ | ✅ | ✅ | ✅ |
213
- | `Array` | ✅ | ✅ | ✅ | ✅ |
214
- | `Object` | ✅ | ✅ | ✅ | ✅ |
215
- | `String` | ✅ | ✅ | ✅ | ✅ |
216
- | `Number` | ✅ | ✅ | ✅ | ✅ |
217
- | `Date` | ✅ | ✅ | ✅ | ✅ |
218
- | **Constants** | | | | |
219
- | `undefined` | ✅ | ✅ | ✅ | ✅ |
220
- | `NaN` | ✅ | ✅ | ✅ | ✅ |
221
- | `Infinity` | ✅ | ✅ | ✅ | ✅ |
222
- | **Utility Functions** | | | | |
223
- | `parseInt` | ❌ | ✅ | ✅ | ✅ |
224
- | `parseFloat` | ❌ | ✅ | ✅ | ✅ |
225
- | `isNaN` | ❌ | ✅ | ✅ | ✅ |
226
- | `isFinite` | ❌ | ✅ | ✅ | ✅ |
227
- | `encodeURI` | ❌ | ✅ | ✅ | ✅ |
228
- | `decodeURI` | ❌ | ✅ | ✅ | ✅ |
229
- | `encodeURIComponent` | ❌ | ✅ | ✅ | ✅ |
230
- | `decodeURIComponent` | ❌ | ✅ | ✅ | ✅ |
231
- | **Debugging** | | | | |
232
- | `console` | ❌ | ❌ | ❌ | ✅ |
219
+ Both AST validation and the runtime sandbox use the same allowed globals:
220
+
221
+ | Global | STRICT | SECURE | STANDARD | PERMISSIVE |
222
+ | -------------------------------------------------------------------- | ------ | ------ | -------- | ---------- |
223
+ | `callTool` | Yes | Yes | Yes | Yes |
224
+ | `Math`, `JSON`, `Array`, `Object`, `String`, `Number`, `Date` | Yes | Yes | Yes | Yes |
225
+ | `undefined`, `NaN`, `Infinity` | Yes | Yes | Yes | Yes |
226
+ | `parseInt`, `parseFloat`, `isNaN`, `isFinite` | No | Yes | Yes | Yes |
227
+ | `encodeURI`, `decodeURI`, `encodeURIComponent`, `decodeURIComponent` | No | Yes | Yes | Yes |
228
+ | `console` | No | No | No | Yes |
233
229
 
234
230
  With a `consoleHandler`, `console` is allowed at every level (see [Console Handler](#console-handler)).
235
231
 
236
- ### Blocked Globals (All Security Levels)
232
+ ### Refused Globals
237
233
 
238
- These dangerous globals are **always blocked** regardless of security level:
234
+ With the default `agentscript` preset, every global that is not in the table above is refused, at every security level. Among them:
239
235
 
240
- | Category | Blocked Globals |
236
+ | Category | Globals |
241
237
  | ------------------ | ------------------------------------------------------------------------------ |
242
238
  | **Code Execution** | `eval`, `Function`, `AsyncFunction`, `GeneratorFunction` |
243
239
  | **System Access** | `process`, `require`, `module`, `exports`, `__dirname`, `__filename`, `Buffer` |
244
240
  | **Global Objects** | `window`, `globalThis`, `self`, `global`, `this` |
245
241
  | **Prototype** | `constructor`, `__proto__`, `prototype` |
246
242
  | **Reflection** | `Proxy`, `Reflect` |
247
- | **Async Flooding** | `Promise`, `setTimeout`, `setInterval`, `setImmediate`, `queueMicrotask` |
243
+ | **Async** | `Promise`, `setTimeout`, `setInterval`, `setImmediate`, `queueMicrotask` |
248
244
  | **Network** | `fetch`, `XMLHttpRequest`, `WebSocket` |
249
245
  | **Workers** | `Worker`, `SharedWorker`, `ServiceWorker` |
250
- | **Memory Hazards** | `Map`, `Set`, `WeakMap`, `WeakSet`, `WeakRef`, `FinalizationRegistry` |
246
+ | **Collections** | `Map`, `Set`, `WeakMap`, `WeakSet`, `WeakRef`, `FinalizationRegistry` |
251
247
  | **Binary/Wasm** | `WebAssembly`, `ArrayBuffer`, `SharedArrayBuffer`, `Atomics` |
252
248
  | **Error Types** | `Error`, `TypeError`, `ReferenceError`, `SyntaxError`, `RangeError` |
253
249
  | **Symbols/Regex** | `Symbol`, `RegExp` |
@@ -261,6 +257,87 @@ The tables above are what the validator accepts. The realm the script runs in ag
261
257
  - **Scripts run in strict mode.** `this` is `undefined` outside a method call, an assignment to an undeclared name is a `ReferenceError`, and a function has no `caller` or `arguments.callee`. A write that cannot happen throws a `TypeError` instead of being silently ignored: assigning over a built-in method (`obj.toString = ...`; the built-in prototypes are frozen) or changing a frozen object, such as an error the runtime threw.
262
258
  - **Regular expressions cannot run.** AgentScript has none, and with the realm allowlist the realm refuses them too, including the ones the engine builds from a string argument of `match`, `matchAll` and `search`. String operations that take plain strings (`split(',')`, `replace('a', 'b')`, `includes`) are unaffected.
263
259
 
260
+ ### AST Presets
261
+
262
+ The `preset` option selects the **AST validation**. With `transform` on (the default), it is applied to the script as `transformAgentScript` returns it (the `__ag_main` wrapper, `__safe_callTool`, the loop checks), and before the transforms that follow validation (see [How the Layers Fit Together](#how-the-layers-fit-together)). It is separate from `securityLevel`, which sets the runtime limits and, for the `agentscript` and `babel` presets, the allowed globals.
263
+
264
+ | Preset | Description | Custom globals in validation |
265
+ | ------------- | ------------------------------------------------------------------------------ | ---------------------------- |
266
+ | `agentscript` | Default. The AgentScript allowlist | Yes |
267
+ | `babel` | AgentScript plus `Babel.transform()` for TSX/JSX (see `createRestrictedBabel`) | Yes |
268
+ | `strict` | The STRICT preset of `@enclave-vm/ast` | No |
269
+ | `secure` | The SECURE preset | No |
270
+ | `standard` | The STANDARD preset | No |
271
+ | `permissive` | The PERMISSIVE preset | No |
272
+
273
+ Only the `agentscript` and `babel` presets take your custom globals into their allowlist; the other presets use their own fixed rule sets, and custom globals are still available at run time. With these four presets the realm keeps the standard globals that the level does not remove (`realmGlobals: 'security-level'`), so choose them only for code you trust more than generated code.
274
+
275
+ ```typescript
276
+ import { Enclave } from '@enclave-vm/core';
277
+
278
+ const enclave = new Enclave({
279
+ preset: 'agentscript', // AST validation preset (default)
280
+ securityLevel: 'STRICT', // Runtime security level
281
+ toolHandler: async (name, args) => {
282
+ /* ... */
283
+ },
284
+ });
285
+ ```
286
+
287
+ ## Tools
288
+
289
+ ### Tool Handler
290
+
291
+ ```typescript
292
+ type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
293
+ ```
294
+
295
+ Called for every `callTool()` and `toolNamespaces` method call that passes the enclave's checks. Arguments reach it as copied plain data, and its result is sanitized before the script sees it. The script's `callTool` options (`CallToolOptions`) are applied inside the sandbox and are not passed to the handler.
296
+
297
+ ### Tool Namespaces
298
+
299
+ Expose tools to scripts as namespaced functions instead of (or alongside) `callTool()`:
300
+
301
+ ```typescript
302
+ const enclave = new Enclave({
303
+ toolHandler: async (name, args) => callMyTool(name, args),
304
+ toolNamespaces: {
305
+ mail: ['list', 'send'], // mail.list(args) calls the tool 'mail.list'
306
+ users: { get: 'users:get' }, // users.get(args) calls the tool 'users:get'
307
+ },
308
+ });
309
+
310
+ const result = await enclave.run(`
311
+ const inbox = await mail.list({ unread: true });
312
+ const sender = await users.get({ id: inbox[0].from });
313
+ return sender.name;
314
+ `);
315
+ ```
316
+
317
+ A namespace method call **is** a `callTool()` call: `mail.list(args, options)` behaves exactly like `callTool('mail.list', args, options)`. It counts toward `maxToolCalls`, goes through the double VM's rate limit, operation-name and suspicious-sequence checks, its result is sanitized, and it reaches your `toolHandler`. `args` defaults to `{}`. Each namespace is a frozen, null-prototype object created inside the sandbox, so aliasing (`const m = mail; m.list()`) and destructuring work and no host object is exposed.
318
+
319
+ The constructor throws a `TypeError` (`Invalid toolNamespaces: ...`) for names that are not identifiers, prototype keys (`__proto__`, `constructor`, `prototype`), names starting with `__`, reserved words and sandbox globals used as namespaces (`callTool`, `Math`, `console`, ...), identifiers the AgentScript validator refuses (`process`, `fetch`, ...), namespaces that collide with a custom global, duplicated methods, and tool names every adapter cannot carry (empty, over 256 characters, or outside letters, digits, `:`, `.`, `_` and `-` starting with a letter, including a generated `<namespace>.<method>` name).
320
+
321
+ Prefer namespaces over exposing tools as functions in `globals`: functions in `globals` are gated and sanitized (see [Custom Globals](#custom-globals)), but the suspicious-sequence detectors only see tool calls.
322
+
323
+ ### callTool Options
324
+
325
+ Scripts can pass options as the third argument of `callTool` (or the second argument of a namespace method):
326
+
327
+ ```javascript
328
+ const r = await callTool('users:get', { id }, { throwOnError: false });
329
+ if (r.success) {
330
+ return r.data;
331
+ }
332
+ return { failed: r.error.message }; // r.error: { name, message, code?, toolName }
333
+ ```
334
+
335
+ | Option | Default | Description |
336
+ | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
337
+ | `throwOnError` | `true` | `false`: resolve to `{ success: true, data }` or, when the tool fails, `{ success: false, error }` instead of throwing |
338
+
339
+ Only failures of the tool itself (the handler threw or rejected, or its result could not be delivered) are returned this way; the error object is plain data with no stack. Refusals by the enclave (abort, `maxToolCalls`, rate limit, operation-name and suspicious-sequence checks, invalid arguments) always throw. Options are applied inside the sandbox and are not passed to the `toolHandler`.
340
+
264
341
  ### Console Handler
265
342
 
266
343
  Without a `consoleHandler`, `console` is allowed only at `PERMISSIVE` and writes to the host process console. With one, scripts may use `console` at every security level and each call goes to the handler instead:
@@ -282,43 +359,159 @@ await enclave.run(`console.info('users', { count: 2 }); return 1;`); // logger.i
282
359
  - Supported by the double VM (default), the `vm` adapter and the `worker_threads` adapter. A custom `sandboxAdapter` receives the handler as `context.consoleHandler`; the built-in `InterpreterAdapter` passes it one line of text per call, like the other adapters.
283
360
  - Combining a `consoleHandler` with a `console` entry in `globals` throws a `TypeError`.
284
361
 
285
- ### AST Presets
286
-
287
- The `preset` option controls **AST-level validation** - what JavaScript constructs are allowed before code transformation. This is separate from `securityLevel` which controls runtime security.
362
+ ## Custom Globals
288
363
 
289
- | Preset | Description | Custom Globals |
290
- | ------------- | --------------------------------------------- | ---------------- |
291
- | `agentscript` | Default. Safe subset for LLM-generated code | ✅ Supported |
292
- | `strict` | Maximum restrictions, blocks most JS features | ❌ Not supported |
293
- | `secure` | High security with essential features | ❌ Not supported |
294
- | `standard` | Balanced security for general use | ❌ Not supported |
295
- | `permissive` | Minimal AST restrictions | ❌ Not supported |
364
+ You can provide custom globals to the VM:
296
365
 
297
366
  ```typescript
298
- import { Enclave } from '@enclave-vm/core';
299
-
300
367
  const enclave = new Enclave({
301
- preset: 'agentscript', // AST validation preset (default)
302
- securityLevel: 'STRICT', // Runtime security level
368
+ globals: {
369
+ config: { apiUrl: 'https://api.example.com' },
370
+ helpers: {
371
+ formatDate: (date: Date) => date.toISOString(),
372
+ },
373
+ },
374
+ allowFunctionsInGlobals: true, // Required when globals contain functions
303
375
  toolHandler: async (name, args) => {
304
376
  /* ... */
305
377
  },
306
378
  });
379
+
380
+ const result = await enclave.run(`
381
+ const url = config.apiUrl;
382
+ const formatted = helpers.formatDate(new Date());
383
+ return { url, formatted };
384
+ `);
307
385
  ```
308
386
 
309
- **Key Differences:**
387
+ Set `allowFunctionsInGlobals: true` only when you intentionally provide functions: a function in `globals` is code of your host that a script can call, and what it can reach through its closure is yours to judge.
388
+
389
+ Every call from the script into a function from `globals` (including functions nested in objects) goes through the enclave's gate:
390
+
391
+ - it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls` (default: 10 × `maxToolCalls`), not toward `maxToolCalls`;
392
+ - its arguments are copied into plain host data first, the way tool arguments are: the function receives null-prototype objects, arrays, primitives and `Date`s, never a live script value, and a call that passes a function or a symbol is refused. The script's `this` is not passed either;
393
+ - in the double VM (the default) it shares the operation rate limit (`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
394
+ - its return value is sanitized like a tool result: the script receives a plain-data copy, and a value containing functions or symbols, or exceeding the sanitize depth/size limits, is refused;
395
+ - an error it throws reaches the script as a plain error without the host stack;
396
+ - calling it with `new` is refused.
397
+
398
+ The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or `callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
399
+
400
+ Values passed in `globals` are **read-only** inside the sandbox. They are the host's own objects, shared by every execution of the enclave, so a script cannot assign to them, add or delete properties, freeze them, or call a built-in method that changes its receiver (`push`, `sort`, `Map.prototype.set`, `Date.prototype.setTime`, ...): the attempt throws, or is ignored at `PERMISSIVE`. Reading works as before, and an array returned by a built-in method (`map`, `filter`, `slice`, ...) is the script's own copy, which it can sort or extend. To let scripts keep state, return it from a tool instead.
401
+
402
+ A custom global cannot be named `Object`: the sandbox provides its own. The constructor throws.
403
+
404
+ <details>
405
+ <summary>What the constructor accepts in <code>globals</code>, and further details</summary>
310
406
 
311
- | Aspect | `preset` (AST) | `securityLevel` (Runtime) |
312
- | ------------------------ | ---------------------------- | --------------------------- |
313
- | When applied | Before execution | During execution |
314
- | What it controls | JavaScript syntax/constructs | Resource limits, timeouts |
315
- | Function expressions | Blocked in `agentscript` | N/A |
316
- | Getter/setter syntax | Blocked in `agentscript` | N/A |
317
- | Custom globals whitelist | Only `agentscript` preset | Always available at runtime |
407
+ A function is not started when the script calls it with the stack nearly full (less than 128 KB left): the call throws a `RangeError` in the script, and the function has not run. The check only decides whether a function starts: it is never started halfway. It says nothing about a function that did start. An async function that is still in progress when `toolCallGraceMs` is over is left behind like a tool call, and `run()` ends without its result reaching the script.
318
408
 
319
- **Note:** Only the `agentscript` preset supports the `allowedGlobals` option for whitelisting custom global identifiers in AST validation. Other presets use their own fixed rule sets.
409
+ The validation of `globals` judges what a script can reach through a value, not only what the value has itself. The methods of a class are functions in `globals`: an instance of a class with methods needs `allowFunctionsInGlobals: true`, and so does a function in a property that is not enumerable or is keyed by a symbol. Code that runs when a property is read is refused whatever is allowed: a getter or setter, on the value or on its class, and a Proxy of an object. That includes a `Buffer` (pass a `Uint8Array`) and an `Error` object (pass its message). A function passed as a global is judged as a function; what hangs on it is not looked at. An instance of a class without methods or accessors is plain data and is accepted, unless `secureProxyConfig.blockConstructor` is off (as at `PERMISSIVE`): then a script can read its `constructor`, which is a function.
320
410
 
321
- ## Worker Pool Adapter (Optional)
411
+ A **regular expression** passed in `globals` can be read (`source`, `flags`, `global`, ...) but not run: `test`, `exec` and its use as the pattern of `match`, `matchAll`, `replace`, `search` or `split` throw, at every security level. A match would run the host's pattern on a text the script chooses, outside the rules that apply to the script's own expressions, and with the `g` or `y` flag it writes `lastIndex` on the host's object. Pass a function that does the matching, or let the script build the expression from `source` and `flags` where the preset allows `RegExp`. The same goes for `match`, `matchAll` and `search` on a `String` object (`new String(...)`) passed in `globals`; a plain string is not affected.
412
+
413
+ With the single VM, an object of the script's own that a host built-in hands back to a callback (the object a script gave `reduce` to collect into) stays the script's and stays writable. The runtime recognises it by its prototype chain, which ends in the sandbox's `Object.prototype`. An object without a prototype (`Object.create(null)`) carries nothing that says who made it and is treated as the host's, so it arrives read-only in the callback: collect into `{}` or an array.
414
+
415
+ Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets, Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`) hand elements to the script directly, so a function (or an object with methods) stored there would be called without the gate. The constructor refuses it with an error naming the path, e.g. `Custom global "cfg" contains a function inside a collection at hooks.0.run`. Every own entry counts there, enumerable or not, and Map and Set subclasses are refused inside collections. Arrays anywhere in `globals` must be plain arrays (no Proxy, no custom prototype), since those can hide entries from validation. Promises, WeakMaps, iterators and generators are refused anywhere in `globals`, since their contents cannot be validated.
416
+
417
+ </details>
418
+
419
+ ## Execution Result
420
+
421
+ ```typescript
422
+ interface ExecutionResult<T> {
423
+ success: boolean;
424
+ value?: T; // Result when success is true
425
+ error?: {
426
+ message: string;
427
+ name: string;
428
+ code?: string; // Error code (e.g., 'VALIDATION_ERROR'; see "Error Codes")
429
+ stack?: string; // Only for errors made outside the sandbox
430
+ data?: Record<string, unknown>;
431
+ };
432
+ stats: {
433
+ duration: number; // Execution time in ms
434
+ toolCallCount: number; // Number of tool calls made
435
+ iterationCount: number; // Number of loop iterations
436
+ memoryUsage?: number; // Peak tracked memory in bytes (when memoryLimit is set)
437
+ startTime: number;
438
+ endTime: number;
439
+ };
440
+ scoringResult?: ScoringGateResult; // When a scoring gate evaluated the script
441
+ }
442
+ ```
443
+
444
+ **`result.error` is plain, bounded text.** Whatever a script threw, `name` and `message` are strings: `name` of at most 256 characters, `message` of at most 16,384. A thrown string is the message; a thrown `null`, `undefined` or other primitive is named in the message (`The script threw null`); an object without a string `message` is reported as `The script threw a value that is not an error`. An object a script makes to look like the memory-limit error is not reported as one. The message of a validation failure is cut to 500 characters per issue and 32,768 in total; `error.data.issues` holds the issues.
445
+
446
+ **Errors made inside the sandbox have no `stack`.** No sandbox realm captures a stack trace, so `error.stack` is `undefined` for the script and absent from `result.error` for what a script throws and for what the runtime raises inside the sandbox (a limit, a failed tool call). This holds for the double VM and the single VM, in process and in a worker. Errors the host makes outside a sandbox realm (an adapter that fails, a worker pool error, an error of the `InterpreterAdapter`, which has no realm of its own) keep their stack. With `sanitizeStackTraces` on (the default for `STRICT` and `SECURE`), such a stack is sanitized, whichever stage raised the error: stack frames become `at [REDACTED]` and paths, URLs and file locations in the remaining lines are redacted.
447
+
448
+ ### Error Codes
449
+
450
+ | Code | Description |
451
+ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
452
+ | `VALIDATION_ERROR` | AST validation failed, or the script is too large or not a string |
453
+ | `SECURITY_VIOLATION` | The script contains a dynamic import (also with `validate: false`), or a blocked operation was recorded at `STRICT` or `SECURE` |
454
+ | `SCORING_BLOCKED` | Refused by the scoring gate |
455
+ | `DOUBLE_VM_EXECUTION_ERROR` | The script failed in the double VM (the default): an error it did not catch, a failed tool call, the tool-call or iteration limit, a timeout |
456
+ | `VM_EXECUTION_ERROR` | The same with `doubleVm: { enabled: false }`; with either VM, the timeout of a script that was only waiting |
457
+ | `MEMORY_LIMIT_EXCEEDED` | `memoryLimit` exceeded |
458
+ | `SERIALIZATION_LIMIT_EXCEEDED` | The returned value is larger than the memory limit allows |
459
+ | `EXECUTION_ERROR` | The adapter itself failed; with the worker pool `error.name` is the pool's error (`WorkerTimeoutError`, ...) |
460
+ | `ENCLAVE_ERROR` | Any other failure outside the sandbox, such as a script with a syntax error |
461
+ | `EXECUTION_TIMEOUT`, `STEP_LIMIT_EXCEEDED` | The timeout and the step budget of the `InterpreterAdapter` |
462
+
463
+ For the limits `error.message` says which one ended the script: `Script execution timed out ...`, `Maximum iteration limit exceeded ...`, `Maximum tool call limit exceeded ...`.
464
+
465
+ ### How `timeout` Is Enforced
466
+
467
+ - The time is the script's: the clock starts when the sandbox is ready to run it. Validation, the transform and the creation of the sandbox adapter (once per enclave; with the worker pool that starts the worker threads) come before it. Waiting for a free worker counts, and a script whose time has passed while it waited is not started: `run()` returns `ExecutionAbortedError`.
468
+ - Until the script's first `await`, Node's `vm` interrupts it at the deadline.
469
+ - After that, the script checks the clock itself: the transformer inserts a check at the start of every function and loop body and in front of a parameter default, so synchronous work, recursion and promise chains that never yield are stopped at the deadline as well. A script that catches the timeout error cannot enter another function or loop iteration. The deadline is cooperative: it is looked at between the steps of the script's own code.
470
+ - A tool call in progress at the deadline is not cut off, and its result is delivered. This does not hold with `adapter: 'worker_threads'`: there the deadline fails a tool call still in progress with `Execution aborted` (`EXECUTION_ABORTED`) at once, without waiting for `toolCallGraceMs`, and the handler's later result is not delivered to the script. From then on the next tool call or call into a host function is refused with `Execution aborted`. The same holds for an async function from `globals`.
471
+ - That wait has an end: `toolCallGraceMs` after the deadline the execution ends with the timeout error, whatever is still in progress, and `error.data.pendingHostCalls` says how many calls were left running. The default is the value of `timeout`, so `run()` takes at most twice `timeout`. `0` ends every execution at the deadline; `Infinity` waits for the handler however long it takes, as versions up to 2.18 did (a handler that never settles then keeps `run()` from settling).
472
+ - When `run()` has returned, for whatever reason, the script is finished for the host as well. What it left behind (a tool call it did not await, with a `then` on it) can no longer call a tool, a function from `globals` or the console, and it ends within a bounded number of steps: its next checks throw `Script execution has ended`.
473
+ - A script that only waits is ended as well. Waiting takes no code: a thenable that never calls back (`return { then: () => 0 }`) is enough, and nothing runs that could look at the clock. So the enclave keeps count of what the host has in flight for the script (tool calls, async functions from `globals`), and from the deadline on `run()` returns the timeout error as soon as that count is zero. A sandbox has no timers and no I/O, so nothing else could wake the script. (With `adapter: 'worker_threads'` the pool ends such a script like a busy one: with its worker, five seconds after the deadline.)
474
+ - Not covered: a single built-in call that does all its work natively, and a script run with `transform: false`. The engine finishes one call into a built-in before the next check, so `timeout` does not bound its duration. And the enclave cannot stop your `toolHandler`: a call it stops waiting for keeps running in the host, so a tool that changes something should be safe to repeat, or have a time limit of its own. For a stop the script cannot influence, use `adapter: 'worker_threads'`: a script that is still running five seconds after its timeout is terminated with its worker (see [Worker Pool Adapter](#worker-pool-adapter)). A process you can terminate does the same for everything else that runs in it.
475
+
476
+ ## What the Pre-Scanner Checks
477
+
478
+ `Enclave` runs the pre-scanner on the script as it was written, before anything parses it, with the pre-scanner preset named like the AST `preset`:
479
+
480
+ | AST preset | Pre-scanner preset | Script | Lines | String literals | Regex literals | Bidirectional controls | Invisible characters |
481
+ | ----------------------- | ------------------ | ---------------------------------------------------- | ------------------------------- | --------------------------- | ------------------------------------------- | ---------------------- | -------------------- |
482
+ | `agentscript` (default) | `agentscript` | 100 KB, nesting 20 | 1,000 of at most 2,000 chars | 10 KB each, 100 KB in total | refused | refused | refused |
483
+ | `strict` | `strict` | 500 KB, nesting 30 | 2,000 of at most 5,000 chars | 50 KB each, 500 KB in total | 10 of at most 100 chars, analyzed for ReDoS | refused | refused |
484
+ | `secure` | `secure` | 1 MB, nesting 40 | 5,000 of at most 8,000 chars | 100 KB each, 1 MB in total | 20 of at most 200 chars, analyzed | refused | allowed |
485
+ | `standard`, `babel` | `standard` | 5 MB, nesting 50 | 10,000 of at most 10,000 chars | 500 KB each, 5 MB in total | 30 of at most 500 chars, analyzed | allowed | allowed |
486
+ | `permissive` | `permissive` | 5,242,880 chars (the enclave's maximum), nesting 100 | 100,000 of at most 50,000 chars | 1 MB each, 10 MB in total | allowed | allowed | allowed |
487
+
488
+ Every preset except `permissive` also refuses a null byte, more consecutive operators than its limit, and one of a fixed list of letters that look like ASCII letters (Cyrillic and Greek look-alikes of `a`, `c`, `e`, `o`, `p`, `x`, `y`, and the full-width `a` and `e`), anywhere in the text.
489
+
490
+ The `preScan` option picks another preset or changes single limits of the one in force; the pre-scanner's own absolute maximums still hold:
491
+
492
+ ```typescript
493
+ // The limits enclaves had before 2.19.2, whatever the AST preset
494
+ const enclave = new Enclave({ preScan: { preset: 'standard' } });
495
+
496
+ // The agentscript pre-scanner with room for larger string literals (for the reference sidecar, say).
497
+ // The limit on one literal and the limit on all literals together are separate: raise both.
498
+ const enclave = new Enclave({
499
+ preScan: {
500
+ config: {
501
+ maxInputSize: 1024 * 1024,
502
+ maxLineLength: 100000,
503
+ maxStringLength: 512 * 1024,
504
+ maxTotalStringContent: 1024 * 1024,
505
+ },
506
+ },
507
+ });
508
+ ```
509
+
510
+ A line is at most 100,000 characters under any configuration (the pre-scanner's absolute maximum), so a literal longer than that has to be a template literal over several lines.
511
+
512
+ With `validate: false` the pre-scanner does not run; a script is limited to 5,242,880 characters in any case.
513
+
514
+ ## Worker Pool Adapter
322
515
 
323
516
  `adapter: 'worker_threads'` runs each script in a worker thread taken from a pool. Inside the worker the script runs in the **same sandbox** as in process: the double VM by default. The worker thread is a layer around that sandbox and adds what only a separate thread can:
324
517
 
@@ -350,7 +543,7 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
350
543
  - **Console output** without a `consoleHandler` is printed by the host with a `[Worker]` prefix.
351
544
  - **`toolBridge.mode: 'direct'`** does not apply: requests and responses always cross as strings.
352
545
 
353
- ### When to Use Worker Pool
546
+ ### When to Use the Worker Pool
354
547
 
355
548
  | Scenario | Recommendation |
356
549
  | ------------------------------------- | ------------------------------------ |
@@ -360,22 +553,14 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
360
553
  | Tenants that must not share a process | One enclave per process or container |
361
554
  | A host that must survive any script | One enclave per process or container |
362
555
 
363
- ### Worker Pool Presets
364
-
365
- | Level | minWorkers | maxWorkers | memoryLimit | messagesPerSec |
366
- | ---------- | ---------- | ---------- | ----------- | -------------- |
367
- | STRICT | 2 | 4 | 64MB | 100 |
368
- | SECURE | 2 | 8 | 128MB | 500 |
369
- | STANDARD | 2 | 16 | 256MB | 1000 |
370
- | PERMISSIVE | 4 | 32 | 512MB | 5000 |
371
-
372
- ### Worker Pool Configuration Options
556
+ ### Worker Pool Configuration
373
557
 
374
558
  | Option | Default | Description |
375
559
  | ------------------------ | --------- | ---------------------------------------------------------------- |
376
560
  | `minWorkers` | 2 | Minimum warm workers |
377
561
  | `maxWorkers` | CPU count | Maximum concurrent workers |
378
562
  | `memoryLimitPerWorker` | 128MB | Heap limit of each worker (its old generation); 0: none |
563
+ | `memoryCheckIntervalMs` | 1000 | Interval of the memory monitor |
379
564
  | `maxMessagesPerSecond` | 1000 | Messages a worker may send per second while it runs an execution |
380
565
  | `maxPendingToolCalls` | 100 | Tool calls one execution may have in flight |
381
566
  | `maxMessageSizeBytes` | 16MB | Largest single message a worker may send |
@@ -384,7 +569,14 @@ A worker thread is **not a sandbox by itself**: it has the whole Node.js API and
384
569
  | `queueTimeoutMs` | 30000 | Longest wait for a free worker |
385
570
  | `idleTimeoutMs` | 30000 | Time before idle worker release |
386
571
 
387
- These are the defaults of `WorkerPoolConfig`. An enclave starts from the preset of its security level (the table above, exported as `WORKER_POOL_PRESETS`), and `workerPoolConfig` overrides single settings of it.
572
+ These are the defaults of `WorkerPoolConfig` (`DEFAULT_WORKER_POOL_CONFIG`). An enclave starts from the preset of its security level, exported as `WORKER_POOL_PRESETS`, and `workerPoolConfig` overrides single settings of it:
573
+
574
+ | Level | minWorkers | maxWorkers | memoryLimitPerWorker | maxMessagesPerSecond | maxMessageSizeBytes | maxExecutionsPerWorker |
575
+ | ---------- | ---------- | ---------- | -------------------- | -------------------- | ------------------- | ---------------------- |
576
+ | STRICT | 2 | 4 | 64MB | 100 | 1MB | 100 |
577
+ | SECURE | 2 | 8 | 128MB | 500 | 4MB | 500 |
578
+ | STANDARD | 2 | 16 | 256MB | 1000 | 16MB | 1000 |
579
+ | PERMISSIVE | 4 | 32 | 512MB | 5000 | 64MB | 5000 |
388
580
 
389
581
  Executions beyond `maxWorkers` wait in a queue (`maxQueueSize`, `queueTimeoutMs`). The wait counts against the script's `timeout`, so size `maxWorkers` for the concurrency you expect.
390
582
 
@@ -413,11 +605,18 @@ An execution the pool ends itself ends its worker too, and the pool starts a new
413
605
 
414
606
  `memoryLimitPerWorker` is the limit of the worker's old generation, passed to the engine as the worker's `resourceLimits`. The engine allows the young generation on top of it, and the pool sets that to 24 MB, so the most a worker can hold is the sum of the two: its budget. (Left to the engine the young generation of such a worker is 192 MB on Node.js 24 and 48 MB on Node.js 22, measured on a 64-bit machine.)
415
607
 
608
+ **What the limit does not guarantee** is that the host process survives. A worker thread shares the process, and Node.js says of these limits that the process may still abort. With the default `memoryLimit` the sandbox's own accounting stops a script long before the worker's limit is reached. Treat the worker's limit as a backstop that usually works. A host that must survive whatever a script allocates needs the enclave in a child process or a container with a memory limit of the operating system.
609
+
610
+ <details>
611
+ <summary>Heap flags of the process, the memory monitor, and measurements</summary>
612
+
416
613
  **A heap flag on the process replaces it.** When the host process runs with `--max-old-space-size`, on the command line or in `NODE_OPTIONS`, that value becomes the heap limit of every worker thread, whatever limit a worker was created with (this is Node.js behaviour; `worker.resourceLimits` goes on reporting the limit that was asked for). The pool therefore reads the actual limit of each new worker. When the engine does not apply the configured one, the pool logs a warning once and enforces the limit itself: while a worker executes, it reads the worker's heap every 100 ms and terminates the worker when its heap and external memory exceed the budget. The execution fails with `WorkerMemoryError`. Where the engine does enforce the heap limit, the same read bounds what the engine does not count: memory the worker holds outside its heap counts against the budget while it executes. This is approximate, because a script can allocate between two reads: with a 64 MB limit and `--max-old-space-size=4096`, a script that kept allocating was stopped when its worker held about 290 MB, with the process at 0.5 GB resident; without the check it went on until the process was at 4.4 GB. Reading a worker's heap from outside needs Node.js 22.16 or later; on an older 22.x the pool can only warn that the limit is not enforced.
417
614
 
418
615
  **The memory monitor** (`memoryCheckIntervalMs`) asks every worker for its memory use and recycles a worker that holds more than its budget. It compares what the worker itself holds, its heap plus its external memory. (`rss` is no measure of a worker: inside a worker thread it is the resident size of the whole process.)
419
616
 
420
- **What the limit does not guarantee** is that the host process survives. A worker thread shares the process, and Node.js says of these limits that the process may still abort. When a worker reaches its limit, Node.js ends the worker and lets the engine finish what it is doing; an allocation burst that outruns that is a fatal out-of-memory error for the whole process. A worker that runs plain JavaScript, limited to 64 MB and keeping 50 KB strings in a tight loop, aborted the process in 6 of 6 runs on Node.js 24.18. Inside the sandbox the same loop ended only its worker when the machine was idle (40 of 40 processes), but with the engine's default young generation it aborted 13 of 480 processes that ran 12 at a time: one garbage collection can move more into the old generation than the 16 MB Node.js allows the engine to finish with. That is why the pool sets the young generation to 24 MB; with it, 0 of 480 processes aborted under the same load. One allocation that is larger than that allowance still ends the process. With the default `memoryLimit` the sandbox's own accounting stops a script long before the worker's limit is reached. Treat the worker's limit as a backstop that usually works. A host that must survive whatever a script allocates needs the enclave in a child process or a container with a memory limit of the operating system.
617
+ **Why the process can still abort.** When a worker reaches its limit, Node.js ends the worker and lets the engine finish what it is doing; an allocation burst that outruns that is a fatal out-of-memory error for the whole process. A worker that runs plain JavaScript, limited to 64 MB and keeping 50 KB strings in a tight loop, aborted the process in 6 of 6 runs on Node.js 24.18. Inside the sandbox the same loop ended only its worker when the machine was idle (40 of 40 processes), but with the engine's default young generation it aborted 13 of 480 processes that ran 12 at a time: one garbage collection can move more into the old generation than the 16 MB Node.js allows the engine to finish with. That is why the pool sets the young generation to 24 MB; with it, 0 of 480 processes aborted under the same load. One allocation that is larger than that allowance still ends the process.
618
+
619
+ </details>
421
620
 
422
621
  ### Layers
423
622
 
@@ -438,8 +637,6 @@ An execution the pool ends itself ends its worker too, and the pool starts a new
438
637
  schema, runs the tool bridge, owns the watchdog
439
638
  ```
440
639
 
441
- ### Security Features
442
-
443
640
  - **The double VM inside the worker**: the same realm, membrane and limits as an in-process execution (a single VM with `doubleVm: { enabled: false }`)
444
641
  - **`worker.terminate()`**: hard stop for a script nothing else can interrupt
445
642
  - **`resourceLimits`**: a heap limit per worker, enforced by V8, or by the pool when a heap flag of the process overrides it ([The Worker Heap Limit](#the-worker-heap-limit))
@@ -449,11 +646,9 @@ An execution the pool ends itself ends its worker too, and the pool starts a new
449
646
  - **Idle confirmation**: a worker is given to the next execution only when it has confirmed that nothing of the last script is left in it
450
647
  - **Pool recovery**: a worker that is terminated or dies is removed and replaced, so the pool is not left short. Running out of memory is the one way a worker can still take the process with it ([The Worker Heap Limit](#the-worker-heap-limit))
451
648
 
452
- ## Double VM Security Layer
453
-
454
- The Double VM provides defense-in-depth by running user code in a nested VM structure. User code runs in an **Inner VM** which is isolated inside a **Parent VM**, providing enhanced protection against VM escape attacks.
649
+ ## Double VM
455
650
 
456
- ### Configuration
651
+ By default the script runs in an **inner VM** created inside a **parent VM**. The inner realm holds the script and its allowed globals; the parent realm sits between it and the host and checks every tool call before it leaves: operation names, a rate limit, and patterns of calls. `doubleVm: { enabled: false }` runs the script in a single VM.
457
652
 
458
653
  ```typescript
459
654
  const enclave = new Enclave({
@@ -465,13 +660,12 @@ const enclave = new Enclave({
465
660
  parentTimeoutBuffer: 1000, // Extra timeout buffer for parent VM (ms)
466
661
  parentValidation: {
467
662
  validateOperationNames: true, // Validate tool names against patterns
468
- allowedOperationPattern: /^(db|api):[a-z]+$/i, // Whitelist pattern
469
- blockedOperationPatterns: [/^shell:/i, /^system:/i], // Blacklist patterns
663
+ allowedOperationPattern: /^(db|api):[a-z]+$/i, // Allowlist pattern
664
+ blockedOperationPatterns: [/^shell:/i, /^system:/i], // Blocklist patterns
470
665
  maxOperationsPerSecond: 100, // Rate limiting
471
666
  blockSuspiciousSequences: true, // Enable suspicious pattern detection
472
667
  rapidEnumerationThreshold: 30, // Max same-operation calls in 5s
473
668
  rapidEnumerationOverrides: {
474
- // Per-operation overrides for rapidEnumerationThreshold
475
669
  search: 100, // Allow 100 search calls
476
670
  'users.list': 50, // Allow 50 user list calls
477
671
  },
@@ -482,57 +676,30 @@ const enclave = new Enclave({
482
676
 
483
677
  ### Parent Validation Options
484
678
 
485
- | Option | Type | Default | Description |
486
- | --------------------------- | ----------------------- | ------- | -------------------------------------------- |
487
- | `validateOperationNames` | `boolean` | `true` | Enable operation name validation |
488
- | `allowedOperationPattern` | `RegExp` | - | Whitelist pattern for operation names |
489
- | `blockedOperationPatterns` | `RegExp[]` | - | Blacklist patterns for operation names |
490
- | `maxOperationsPerSecond` | `number` | `100` | Rate limit for operations per second |
491
- | `blockSuspiciousSequences` | `boolean` | `true` | Enable suspicious pattern detection |
492
- | `rapidEnumerationThreshold` | `number` | `30` | Max same-operation calls in 5 seconds |
493
- | `rapidEnumerationOverrides` | `Record<string,number>` | `{}` | Per-operation thresholds (overrides default) |
494
- | `suspiciousPatterns` | `SuspiciousPattern[]` | `[]` | Custom suspicious pattern detectors |
679
+ | Option | Type | Default | Description |
680
+ | --------------------------- | ----------------------- | ------- | --------------------------------------------------- |
681
+ | `validateOperationNames` | `boolean` | `true` | Enable operation name validation |
682
+ | `allowedOperationPattern` | `RegExp` | - | Allowlist pattern for operation names |
683
+ | `blockedOperationPatterns` | `RegExp[]` | - | Blocklist patterns for operation names |
684
+ | `maxOperationsPerSecond` | `number` | `100` | Rate limit for operations per second |
685
+ | `blockSuspiciousSequences` | `boolean` | `true` | Enable suspicious pattern detection |
686
+ | `rapidEnumerationThreshold` | `number` | `30` | Max same-operation calls in 5 seconds |
687
+ | `rapidEnumerationOverrides` | `Record<string,number>` | `{}` | Per-operation thresholds (overrides default) |
688
+ | `suspiciousPatterns` | `SuspiciousPattern[]` | `[]` | Custom pattern detectors, next to the built-in ones |
495
689
 
496
- ### Built-in Suspicious Pattern Detection
690
+ ### Built-in Suspicious Patterns
497
691
 
498
- When `blockSuspiciousSequences: true`, the following patterns are detected:
692
+ With `blockSuspiciousSequences: true`, a tool call that matches one of these patterns is refused. They are heuristics over tool names and the order of calls:
499
693
 
500
694
  | Pattern ID | Description |
501
695
  | --------------------- | --------------------------------------------------- |
502
- | `EXFIL_LIST_SEND` | List/query followed by send/export (data exfil) |
696
+ | `EXFIL_LIST_SEND` | List/query followed by send/export |
503
697
  | `RAPID_ENUMERATION` | Same operation called too many times (configurable) |
504
698
  | `CREDENTIAL_EXFIL` | Credential access followed by external operation |
505
- | `BULK_OPERATION` | Bulk/batch operations (mass data extraction) |
506
- | `DELETE_AFTER_ACCESS` | Delete operation after data access (cover-up) |
699
+ | `BULK_OPERATION` | Bulk/batch operations |
700
+ | `DELETE_AFTER_ACCESS` | Delete operation after data access |
507
701
 
508
- ### Configuring Rapid Enumeration Detection
509
-
510
- The `RAPID_ENUMERATION` pattern blocks excessive repeated calls to the same operation. Use `rapidEnumerationThreshold` and `rapidEnumerationOverrides` to tune this:
511
-
512
- ```typescript
513
- const enclave = new Enclave({
514
- toolHandler: async (name, args) => {
515
- /* ... */
516
- },
517
- doubleVm: {
518
- parentValidation: {
519
- // Default: Block if same operation called >30 times in 5 seconds
520
- rapidEnumerationThreshold: 30,
521
-
522
- // Per-operation overrides
523
- rapidEnumerationOverrides: {
524
- search: 100, // Search can be called 100 times (pagination)
525
- 'db.query': 50, // Database queries up to 50 times
526
- 'users.filter': 200, // High-volume filtering allowed
527
- },
528
- },
529
- },
530
- });
531
- ```
532
-
533
- ### Custom Suspicious Patterns
534
-
535
- You can add custom pattern detectors:
702
+ A custom detector receives the operation name, its arguments and the history of earlier calls:
536
703
 
537
704
  ```typescript
538
705
  const enclave = new Enclave({
@@ -561,8 +728,6 @@ const enclave = new Enclave({
561
728
 
562
729
  The AI Scoring Gate gives a script a risk score from 0 to 100 before it runs and refuses the script when the score reaches a threshold. The score is a heuristic over features of the script's text: the tools it calls, their argument names and literal values, their order, and the loops they are in. It flags patterns that look like exfiltration, bulk access or access to sensitive fields; a low score is not evidence that a script is safe. The gate runs after AST validation and before execution, and is off unless configured.
563
730
 
564
- ### Configuration
565
-
566
731
  ```typescript
567
732
  const enclave = new Enclave({
568
733
  toolHandler: async (name, args) => {
@@ -602,13 +767,13 @@ A call through a tool namespace (`mail.send(args)`) is scored as the tool call i
602
767
  | Type | What the score is computed from |
603
768
  | -------------- | --------------------------------------------------------------------------------------------------------- |
604
769
  | `disabled` | No scoring |
605
- | `rule-based` | Eight TypeScript rules over the extracted features, zero dependencies |
770
+ | `rule-based` | Eight TypeScript rules over the extracted features, no dependencies |
606
771
  | `local-llm` | Your `customAnalyzer`, or a built-in keyword heuristic over the extracted features (no model computes it) |
607
772
  | `external-api` | The answer of your scoring service, which receives the extracted features |
608
773
 
609
- The `local-llm` scorer loads a Hugging Face model at initialization when the optional dependency `@huggingface/transformers` is installed, but it never calls it: no score is computed from the model. Set `ENCLAVE_DISABLE_LOCAL_LLM_MODEL=1` to skip the load. Its `mode: 'similarity'` searches a VectoriaDB index that is created empty and that the configuration cannot fill, so it scores like the default mode.
774
+ The `local-llm` scorer loads a Hugging Face model at initialization when the optional dependency `@huggingface/transformers` is installed, but it never calls it: no score is computed from the model. Set `ENCLAVE_DISABLE_LOCAL_LLM_MODEL=1` to skip the load. Its `mode: 'similarity'` searches a VectoriaDB index that is created empty and that the configuration cannot fill, so it scores like the default mode. Call `await enclave.initialize()` before the first `run()` when a scorer needs initialization.
610
775
 
611
- ### Custom Analyzer (Extensibility)
776
+ ### Custom Analyzer
612
777
 
613
778
  A custom analyzer replaces the keyword heuristic of the `local-llm` scorer, for example with a call to a model or a static analyzer of your own:
614
779
 
@@ -617,16 +782,12 @@ import { Enclave, type LocalLlmConfig } from '@enclave-vm/core';
617
782
 
618
783
  const myAnalyzer: NonNullable<LocalLlmConfig['customAnalyzer']> = {
619
784
  async analyze(prompt, features) {
620
- // Call your external LLM or static analyzer
621
785
  const response = await fetch('https://my-analyzer-api.com/score', {
622
786
  method: 'POST',
623
787
  body: JSON.stringify({ prompt, features }),
624
788
  });
625
789
  const result = await response.json();
626
- return {
627
- score: result.riskScore,
628
- signals: result.signals,
629
- };
790
+ return { score: result.riskScore, signals: result.signals };
630
791
  },
631
792
  // Optional lifecycle methods
632
793
  async initialize() {
@@ -651,17 +812,10 @@ const enclave = new Enclave({
651
812
  });
652
813
  ```
653
814
 
654
- ### CustomAnalyzer Interface
655
-
656
815
  ```typescript
657
816
  interface CustomAnalyzer {
658
- // Analyze prompt and features, return risk score and signals
659
817
  analyze(prompt: string, features: ExtractedFeatures): Promise<{ score: number; signals: RiskSignal[] }>;
660
-
661
- // Optional: Initialize resources (e.g., connect to external service)
662
818
  initialize?(): Promise<void>;
663
-
664
- // Optional: Cleanup resources
665
819
  dispose?(): void;
666
820
  }
667
821
  ```
@@ -670,33 +824,38 @@ interface CustomAnalyzer {
670
824
 
671
825
  The Reference Sidecar keeps large strings outside the sandbox. The script holds a short reference token in place of the data and can pass it on to another tool. This is for scripts that move large data from one tool to another, not for scripts that read it.
672
826
 
673
- ### How It Works
674
-
675
827
  1. **Storing**: A string of at least `extractionThreshold` bytes is stored in the sidecar and replaced by a reference token (`__REF_<uuid>__`). This applies to a string literal in the script's source and to a tool result that is a string as a whole. A tool that returns an object or an array is returned as it is, with every string in it.
676
828
  2. **The script holds a token**: Nothing is resolved for the script, lazily or otherwise. The token is an ordinary short string, and the script has no way to read the stored data.
677
829
  3. **Resolving at the tool boundary**: A token in the arguments of a tool call, at any depth, is replaced with the stored data before the `toolHandler` is called.
678
830
 
679
831
  The sidecar belongs to one execution and is disposed when `run()` returns.
680
832
 
681
- ### Enabling Sidecar
682
-
683
833
  ```typescript
684
834
  const enclave = new Enclave({
685
- toolHandler: async (name, args) => {
686
- /* ... */
687
- },
688
835
  sidecar: {
689
836
  enabled: true,
690
- maxTotalSize: 10 * 1024 * 1024, // 10MB total storage
691
- maxReferenceSize: 1 * 1024 * 1024, // 1MB per reference
692
- extractionThreshold: 1024, // Store strings of 1KB and more
693
- maxResolvedSize: 5 * 1024 * 1024, // 5MB resolved for one tool call
694
- allowComposites: false, // Refuse string concatenation with refs
837
+ extractionThreshold: 100, // Store strings of 100 bytes and more
838
+ allowComposites: false, // Refuse: ref + "suffix"
839
+ },
840
+ toolHandler: async (name, args) => {
841
+ if (name === 'getLargeText') {
842
+ // A 1MB string: stored in the sidecar, the script gets a token
843
+ return 'x'.repeat(1024 * 1024);
844
+ }
845
+ if (name === 'saveText') {
846
+ // args.text is the 1MB string again: the token was resolved
847
+ return { saved: args.text.length };
848
+ }
695
849
  },
696
850
  });
697
- ```
698
851
 
699
- ### Sidecar Options
852
+ const result = await enclave.run(`
853
+ const text = await callTool('getLargeText', {});
854
+ // text is a reference token here, not the data
855
+ return await callTool('saveText', { text });
856
+ `);
857
+ // result.value: { saved: 1048576 }
858
+ ```
700
859
 
701
860
  | Option | Type | Default | Description |
702
861
  | ---------------------- | --------- | -------------------- | ------------------------------------------------------------------------ |
@@ -720,413 +879,12 @@ const enclave = new Enclave({
720
879
 
721
880
  `maxTotalResolvedSize` bounds what one execution resolves in total: a stored value counts once, the first time it is resolved, and a concatenation of references counts every time it is built. A tool call whose arguments would go over it, or over `maxResolvedSize`, is refused (`REFERENCE_RESOLUTION_LIMIT`) and the handler is not called.
722
881
 
723
- ### Example with Sidecar
724
-
725
- ```typescript
726
- const enclave = new Enclave({
727
- sidecar: {
728
- enabled: true,
729
- extractionThreshold: 100, // Store strings of 100 bytes and more
730
- allowComposites: false, // Refuse: ref + "suffix"
731
- },
732
- toolHandler: async (name, args) => {
733
- if (name === 'getLargeText') {
734
- // A 1MB string: stored in the sidecar, the script gets a token
735
- return 'x'.repeat(1024 * 1024);
736
- }
737
- if (name === 'saveText') {
738
- // args.text is the 1MB string again: the token was resolved
739
- return { saved: args.text.length };
740
- }
741
- },
742
- });
743
-
744
- const result = await enclave.run(`
745
- const text = await callTool('getLargeText', {});
746
- // text is a reference token here, not the data
747
- return await callTool('saveText', { text });
748
- `);
749
- ```
750
-
751
- ### Concatenation
752
-
753
- With `allowComposites: false` (the default at `STRICT` and `SECURE`), concatenating a reference token with anything throws inside the script: a token can only be passed on as it is.
754
-
755
- ```javascript
756
- // Throws when allowComposites is false
757
- const combined = ref + '-suffix';
758
- ```
759
-
760
- With `allowComposites: true` (the default at `STANDARD` and `PERMISSIVE`), the concatenation yields a composite handle, and a tool that is passed the handle receives the concatenated text.
761
-
762
- ## Tool Namespaces
763
-
764
- Expose tools to scripts as namespaced functions instead of (or alongside) `callTool()`:
765
-
766
- ```typescript
767
- const enclave = new Enclave({
768
- toolHandler: async (name, args) => callMyTool(name, args),
769
- toolNamespaces: {
770
- mail: ['list', 'send'], // mail.list(args) calls the tool 'mail.list'
771
- users: { get: 'users:get' }, // users.get(args) calls the tool 'users:get'
772
- },
773
- });
774
-
775
- const result = await enclave.run(`
776
- const inbox = await mail.list({ unread: true });
777
- const sender = await users.get({ id: inbox[0].from });
778
- return sender.name;
779
- `);
780
- ```
781
-
782
- A namespace method call **is** a `callTool()` call: `mail.list(args, options)` behaves exactly like
783
- `callTool('mail.list', args, options)`. It counts toward `maxToolCalls`, goes through the double VM's
784
- rate limit, operation-name and suspicious-sequence checks, its result is sanitized, and it reaches your
785
- `toolHandler`. `args` defaults to `{}`. Each namespace is a frozen, null-prototype object created
786
- inside the sandbox, so aliasing (`const m = mail; m.list()`) and destructuring work and no host object
787
- is exposed.
788
-
789
- The constructor throws a `TypeError` (`Invalid toolNamespaces: ...`) for names that are not identifiers,
790
- prototype keys (`__proto__`, `constructor`, `prototype`), names starting with `__`, reserved words and
791
- sandbox globals used as namespaces (`callTool`, `Math`, `console`, ...), identifiers the AgentScript
792
- validator refuses (`process`, `fetch`, ...), namespaces that collide with a custom global, duplicated
793
- methods, and tool names every adapter cannot carry (empty, over 256 characters, or outside letters, digits,
794
- `:`, `.`, `_` and `-` starting with a letter, including a generated `<namespace>.<method>` name).
795
-
796
- Prefer namespaces over exposing tools as functions in `globals`: functions in `globals` are gated and
797
- sanitized (see "Custom Globals"), but the suspicious-sequence detectors only see tool calls.
798
-
799
- ## callTool Options
800
-
801
- Scripts can pass options as the third argument of `callTool` (or the second argument of a namespace
802
- method):
803
-
804
- ```javascript
805
- const r = await callTool('users:get', { id }, { throwOnError: false });
806
- if (r.success) {
807
- return r.data;
808
- }
809
- return { failed: r.error.message }; // r.error: { name, message, code?, toolName }
810
- ```
811
-
812
- | Option | Default | Description |
813
- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
814
- | `throwOnError` | `true` | `false`: resolve to `{ success: true, data }` or, when the tool fails, `{ success: false, error }` instead of throwing |
815
-
816
- Only failures of the tool itself (the handler threw or rejected, or its result could not be delivered)
817
- are returned this way; the error object is plain data with no stack. Refusals by the enclave (abort,
818
- `maxToolCalls`, rate limit, operation-name and suspicious-sequence checks, invalid arguments) always
819
- throw. Options are applied inside the sandbox and are not passed to the `toolHandler`.
820
-
821
- ## Custom Globals
822
-
823
- You can provide custom globals to the VM:
824
-
825
- ```typescript
826
- const enclave = new Enclave({
827
- globals: {
828
- config: { apiUrl: 'https://api.example.com' },
829
- helpers: {
830
- formatDate: (date: Date) => date.toISOString(),
831
- },
832
- },
833
- allowFunctionsInGlobals: true, // Required when globals contain functions
834
- toolHandler: async (name, args) => {
835
- /* ... */
836
- },
837
- });
838
-
839
- const result = await enclave.run(`
840
- const url = config.apiUrl;
841
- const formatted = helpers.formatDate(new Date());
842
- return { url, formatted };
843
- `);
844
- ```
845
-
846
- **Security Note**: Set `allowFunctionsInGlobals: true` only when you intentionally provide functions. Functions in globals can potentially leak host scope via closures.
847
-
848
- Every call from the script into a function from `globals` (including functions nested in objects) goes
849
- through the enclave's gate:
850
-
851
- - it is refused once the execution is aborted, and counts toward `maxGlobalFunctionCalls`
852
- (default: 10 × `maxToolCalls`), not toward `maxToolCalls`;
853
- - its arguments are copied into plain host data first, the way tool arguments are: the function
854
- receives null-prototype objects, arrays, primitives and `Date`s, never a live script value, and a
855
- call that passes a function or a symbol is refused. The script's `this` is not passed either;
856
- - in the double VM (the default) it shares the operation rate limit
857
- (`doubleVm.parentValidation.maxOperationsPerSecond`) with tool calls;
858
- - its return value is sanitized like a tool result: the script receives a plain-data copy, and a
859
- value containing functions or symbols, or exceeding the sanitize depth/size limits, is refused;
860
- - an error it throws reaches the script as a plain error without the host stack;
861
- - calling it with `new` is refused.
862
-
863
- The suspicious-sequence detectors only look at tool calls, so expose tools with `toolNamespaces` or
864
- `callTool()`, not as functions. The `worker_threads` adapter never passes functions into the sandbox.
865
-
866
- A function is not started when the script calls it with the stack nearly full (less than 128 KB
867
- left): the call throws a `RangeError` in the script, and the function has not run. The check only
868
- decides whether a function starts: it is never started halfway. It says nothing about a function
869
- that did start. An async function that is still in progress when `toolCallGraceMs` is over is left
870
- behind like a tool call, and `run()` ends without its result reaching the script.
871
-
872
- The validation of `globals` judges what a script can reach through a value, not only what the
873
- value has itself. The methods of a class are functions in `globals`: an instance of a class with
874
- methods needs `allowFunctionsInGlobals: true`, and so does a function in a property that is not
875
- enumerable or is keyed by a symbol. Code that runs when a property is read is refused whatever is
876
- allowed: a getter or setter, on the value or on its class, and a Proxy of an object. That
877
- includes a `Buffer` (pass a `Uint8Array`) and an `Error` object (pass its message). A function
878
- passed as a global is judged as a function; what hangs on it is not looked at.
879
- An instance of a class without methods or accessors is plain data and is accepted, unless
880
- `secureProxyConfig.blockConstructor` is off (as at `PERMISSIVE`): then a script can read its
881
- `constructor`, which is a function.
882
-
883
- Values passed in `globals` are **read-only** inside the sandbox. They are the host's own objects, shared
884
- by every execution of the enclave, so a script cannot assign to them, add or delete properties, freeze
885
- them, or call a built-in method that changes its receiver (`push`, `sort`, `Map.prototype.set`,
886
- `Date.prototype.setTime`, ...): the attempt throws, or is ignored at `PERMISSIVE`. Reading works as
887
- before, and an array returned by a built-in method (`map`, `filter`, `slice`, ...) is the script's own
888
- copy, which it can sort or extend. To let scripts keep state, return it from a tool instead.
889
-
890
- A **regular expression** passed in `globals` can be read (`source`, `flags`, `global`, ...) but not
891
- run: `test`, `exec` and its use as the pattern of `match`, `matchAll`, `replace`, `search` or `split`
892
- throw, at every security level. A match would run the host's pattern on a text the script chooses,
893
- outside the rules that apply to the script's own expressions, and with the `g` or `y` flag it writes
894
- `lastIndex` on the host's object. Pass a function that does the matching, or let the script build
895
- the expression from `source` and `flags` where the preset allows `RegExp`. The same goes for
896
- `match`, `matchAll` and `search` on a `String` object (`new String(...)`) passed in `globals`;
897
- a plain string is not affected.
898
-
899
- A custom global cannot be named `Object`: the sandbox provides its own. The constructor throws.
900
-
901
- With the single VM, an object of the script's own that a host built-in hands back to a callback
902
- (the object a script gave `reduce` to collect into) stays the script's and stays writable. The
903
- runtime recognises it by its prototype chain, which ends in the sandbox's `Object.prototype`. An
904
- object without a prototype (`Object.create(null)`) carries nothing that says who made it and is
905
- treated as the host's, so it arrives read-only in the callback: collect into `{}` or an array.
906
-
907
- Inside arrays, Maps and Sets only plain data is allowed (primitives, plain objects, arrays, Maps, Sets,
908
- Dates, RegExps, typed arrays): the built-in methods of those collections (`forEach`, iteration, `get`)
909
- hand elements to the script directly, so a function (or an object with methods) stored there would be
910
- called without the gate. The constructor refuses it with an error naming the path, e.g.
911
- `Custom global "cfg" contains a function inside a collection at hooks.0.run`. Every own entry counts there,
912
- enumerable or not, and Map and Set subclasses are refused inside collections. Arrays anywhere in `globals`
913
- must be plain arrays (no Proxy, no custom prototype), since those can hide entries from validation.
914
- Promises, WeakMaps, iterators and generators are refused anywhere in `globals`, since their contents cannot
915
- be validated.
916
-
917
- ## Execution Result
918
-
919
- ```typescript
920
- interface ExecutionResult<T> {
921
- success: boolean;
922
- value?: T; // Result when success is true
923
- error?: {
924
- message: string;
925
- name: string;
926
- code?: string; // Error code (e.g., 'VALIDATION_ERROR'; see "Error Codes")
927
- stack?: string; // Only for errors made outside the sandbox
928
- data?: Record<string, unknown>;
929
- };
930
- stats: {
931
- duration: number; // Execution time in ms
932
- toolCallCount: number; // Number of tool calls made
933
- iterationCount: number; // Number of loop iterations
934
- memoryUsage?: number; // Peak tracked memory in bytes (when memoryLimit is set)
935
- startTime: number;
936
- endTime: number;
937
- };
938
- scoringResult?: ScoringGateResult; // When a scoring gate evaluated the script
939
- }
940
- ```
941
-
942
- **`result.error` is plain, bounded text.** Whatever a script threw, `name` and `message` are strings: `name`
943
- of at most 256 characters, `message` of at most 16,384. A thrown string is the message; a thrown `null`,
944
- `undefined` or other primitive is named in the message (`The script threw null`); an object without a
945
- string `message` is reported as `The script threw a value that is not an error`. An object a script makes
946
- to look like the memory-limit error is not reported as one. The message of a validation failure is cut to
947
- 500 characters per issue and 32,768 in total; `error.data.issues` holds the issues.
948
-
949
- **Errors made inside the sandbox have no `stack`.** No sandbox realm captures a stack trace, so
950
- `error.stack` is `undefined` for the script and absent from `result.error` for what a script throws and
951
- for what the runtime raises inside the sandbox (a limit, a failed tool call). This holds for the double VM
952
- and the single VM, in process and in a worker. Errors the host makes outside a sandbox realm (an adapter
953
- that fails, a worker pool error, an error of the `InterpreterAdapter`, which has no realm of its own) keep
954
- their stack. With `sanitizeStackTraces` on (the default for `STRICT` and `SECURE`), such a stack is
955
- sanitized, whichever stage raised the error: stack frames become `at [REDACTED]` and paths, URLs and file
956
- locations in the remaining lines are redacted.
957
-
958
- ### Error Codes
959
-
960
- | Code | Description |
961
- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
962
- | `VALIDATION_ERROR` | AST validation failed, or the script is too large or not a string |
963
- | `SECURITY_VIOLATION` | The script contains a dynamic import (also with `validate: false`), or a blocked operation was recorded at `STRICT` or `SECURE` |
964
- | `SCORING_BLOCKED` | Refused by the scoring gate |
965
- | `DOUBLE_VM_EXECUTION_ERROR` | The script failed in the double VM (the default): an error it did not catch, a failed tool call, the tool-call or iteration limit, a timeout |
966
- | `VM_EXECUTION_ERROR` | The same with `doubleVm: { enabled: false }`; with either VM, the timeout of a script that was only waiting |
967
- | `MEMORY_LIMIT_EXCEEDED` | `memoryLimit` exceeded |
968
- | `SERIALIZATION_LIMIT_EXCEEDED` | The returned value is larger than the memory limit allows |
969
- | `EXECUTION_ERROR` | The adapter itself failed; with the worker pool `error.name` is the pool's error (`WorkerTimeoutError`, ...) |
970
- | `ENCLAVE_ERROR` | Any other failure outside the sandbox, such as a script with a syntax error |
971
- | `EXECUTION_TIMEOUT`, `STEP_LIMIT_EXCEEDED` | The timeout and the step budget of the `InterpreterAdapter` |
972
-
973
- For the limits `error.message` says which one ended the script: `Script execution timed out ...`,
974
- `Maximum iteration limit exceeded ...`, `Maximum tool call limit exceeded ...`.
975
-
976
- ### How `timeout` Is Enforced
977
-
978
- - The time is the script's: the clock starts when the sandbox is ready to run it. Validation, the
979
- transform and the creation of the sandbox adapter (once per enclave; with the worker pool that
980
- starts the worker threads) come before it. Waiting for a free worker counts, and a script whose
981
- time has passed while it waited is not started: `run()` returns `ExecutionAbortedError`.
982
- - Until the script's first `await`, Node's `vm` interrupts it at the deadline.
983
- - After that, the script checks the clock itself: the transformer inserts a check at the start of
984
- every function and loop body and in front of a parameter default, so synchronous work, recursion
985
- and promise chains that never yield are stopped at the deadline as well. A script that catches
986
- the timeout error cannot enter another function or loop iteration. The deadline is cooperative:
987
- it is looked at between the steps of the script's own code.
988
- - A tool call in progress at the deadline is not cut off, and its result is delivered. From then on
989
- the next tool call or call into a host function is refused with `Execution aborted`. The same
990
- holds for an async function from `globals`.
991
- - That wait has an end: `toolCallGraceMs` after the deadline the execution ends with the timeout
992
- error, whatever is still in progress, and `error.data.pendingHostCalls` says how many calls
993
- were left running. The default is the value of `timeout`, so `run()` takes at most twice
994
- `timeout`. `0` ends every execution at the deadline; `Infinity` waits for the handler however
995
- long it takes, as versions up to 2.18 did (a handler that never settles then keeps `run()` from
996
- settling).
997
- - When `run()` has returned, for whatever reason, the script is finished for the host as well.
998
- What it left behind (a tool call it did not await, with a `then` on it) can no longer call a
999
- tool, a function from `globals` or the console, and it ends within a bounded number of steps:
1000
- its next checks throw `Script execution has ended`.
1001
- - A script that only waits is ended as well. Waiting takes no code: a thenable that never calls
1002
- back (`return { then: () => 0 }`) is enough, and nothing runs that could look at the clock. So
1003
- the enclave keeps count of what the host has in flight for the script (tool calls, async
1004
- functions from `globals`), and from the deadline on `run()` returns the timeout error as soon as
1005
- that count is zero. A sandbox has no timers and no I/O, so nothing else could wake the script.
1006
- (With `adapter: 'worker_threads'` the pool ends such a script like a busy one: with its worker,
1007
- five seconds after the deadline.)
1008
- - Not covered: a single built-in call that does all its work natively, and a script run with
1009
- `transform: false`. The engine finishes one call into a built-in before the next check, so
1010
- `timeout` does not bound its duration. And the enclave cannot stop your
1011
- `toolHandler`: a call it stops waiting for keeps running in the host, so a tool that changes
1012
- something should be safe to repeat, or have a time limit of its own. For a
1013
- stop the script cannot influence, use `adapter: 'worker_threads'`: a script that is still
1014
- running five seconds after its timeout is terminated with its worker (see
1015
- [Worker Pool Adapter](#worker-pool-adapter-optional)). A process you can terminate does the
1016
- same for everything else that runs in it.
1017
-
1018
- ## Defense-in-Depth Architecture
1019
-
1020
- ```
1021
- ┌─────────────────────────────────────────────────────────────┐
1022
- │ User Code Input │
1023
- └─────────────────────────────────────────────────────────────┘
1024
- │
1025
- ▼
1026
- ┌─────────────────────────────────────────────────────────────┐
1027
- │ Layer 0: Pre-Scanner (ast-guard, preset of the AST preset) │
1028
- │ ├── Input size, line and string limits │
1029
- │ ├── Nesting depth limits │
1030
- │ ├── Regex literals refused (agentscript) or analyzed │
1031
- │ └── Bidirectional, invisible and look-alike characters │
1032
- └─────────────────────────────────────────────────────────────┘
1033
- │
1034
- ▼
1035
- ┌─────────────────────────────────────────────────────────────┐
1036
- │ Layer 1: AST Validation (ast-guard) │
1037
- │ ├── NoEvalRule - Blocks eval(), Function() │
1038
- │ ├── NoGlobalAccessRule - Blocks dangerous globals │
1039
- │ ├── AllowedSyntaxRule - Syntax allowlist │
1040
- │ ├── UnknownGlobalRule - Only the allowed globals │
1041
- │ └── ReservedPrefixRule - Blocks reserved prefixes │
1042
- └─────────────────────────────────────────────────────────────┘
1043
- │
1044
- ▼
1045
- ┌─────────────────────────────────────────────────────────────┐
1046
- │ Layer 2: Code Transformation │
1047
- │ ├── Wraps in async function __ag_main() │
1048
- │ ├── callTool → __safe_callTool (tracked) │
1049
- │ ├── Loops → __safe_for, __safe_forOf (guarded) │
1050
- │ └── String literals → extracted to sidecar (if enabled) │
1051
- └─────────────────────────────────────────────────────────────┘
1052
- │
1053
- ▼
1054
- ┌─────────────────────────────────────────────────────────────┐
1055
- │ Layer 3: AI Scoring Gate (optional, heuristic) │
1056
- │ ├── Features of the script's tool calls │
1057
- │ ├── Exfiltration-like tool sequences │
1058
- │ ├── Sensitive field names │
1059
- │ └── Risk scoring (0-100) with thresholds │
1060
- └─────────────────────────────────────────────────────────────┘
1061
- │
1062
- ▼
1063
- ┌─────────────────────────────────────────────────────────────┐
1064
- │ Layer 4: Runtime Sandbox │
1065
- │ ├── Standard: Node.js vm (prototype isolation) │
1066
- │ ├── Optional: Worker Pool (heap limit, hard stop) │
1067
- │ │ ├── Dual-layer: worker thread + VM context │
1068
- │ │ ├── Hard halt via worker.terminate() │
1069
- │ │ └── Per-worker memory limits │
1070
- │ ├── __safe_callTool - Enforces maxToolCalls │
1071
- │ ├── __safe_forOf - Enforces maxIterations │
1072
- │ └── Timeout enforcement │
1073
- └─────────────────────────────────────────────────────────────┘
1074
- │
1075
- ▼
1076
- ┌─────────────────────────────────────────────────────────────┐
1077
- │ Layer 5: Output Sanitization │
1078
- │ ├── Returned values copied into plain data │
1079
- │ ├── Errors as bounded text, no stack from the sandbox │
1080
- │ └── Refuses oversized return values │
1081
- └─────────────────────────────────────────────────────────────┘
1082
- │
1083
- ▼
1084
- ┌─────────────────────────────────────────────────────────────┐
1085
- │ Safe Execution Result │
1086
- └─────────────────────────────────────────────────────────────┘
1087
- ```
1088
-
1089
- ### What the Pre-Scanner Checks
1090
-
1091
- `Enclave` runs the pre-scanner on the script as it was written, before anything parses it, with the pre-scanner preset named like the AST `preset`:
1092
-
1093
- | AST preset | Pre-scanner preset | Script | Lines | String literals | Regex literals | Bidirectional controls | Invisible characters |
1094
- | ----------------------- | ------------------ | ---------------------------------------------------- | ------------------------------- | --------------------------- | ------------------------------------------- | ---------------------- | -------------------- |
1095
- | `agentscript` (default) | `agentscript` | 100 KB, nesting 20 | 1,000 of at most 2,000 chars | 10 KB each, 100 KB in total | refused | refused | refused |
1096
- | `strict` | `strict` | 500 KB, nesting 30 | 2,000 of at most 5,000 chars | 50 KB each, 500 KB in total | 10 of at most 100 chars, analyzed for ReDoS | refused | refused |
1097
- | `secure` | `secure` | 1 MB, nesting 40 | 5,000 of at most 8,000 chars | 100 KB each, 1 MB in total | 20 of at most 200 chars, analyzed | refused | allowed |
1098
- | `standard`, `babel` | `standard` | 5 MB, nesting 50 | 10,000 of at most 10,000 chars | 500 KB each, 5 MB in total | 30 of at most 500 chars, analyzed | allowed | allowed |
1099
- | `permissive` | `permissive` | 5,242,880 chars (the enclave's maximum), nesting 100 | 100,000 of at most 50,000 chars | 1 MB each, 10 MB in total | allowed | allowed | allowed |
1100
-
1101
- Every preset except `permissive` also refuses a null byte, more consecutive operators than its limit, and one of a fixed list of letters that look like ASCII letters (Cyrillic and Greek look-alikes of `a`, `c`, `e`, `o`, `p`, `x`, `y`, and the full-width `a` and `e`), anywhere in the text.
1102
-
1103
- The `preScan` option picks another preset or changes single limits of the one in force; the pre-scanner's own absolute maximums still hold:
1104
-
1105
- ```typescript
1106
- // The limits enclaves had before 2.19.2, whatever the AST preset
1107
- const enclave = new Enclave({ preScan: { preset: 'standard' } });
1108
-
1109
- // The agentscript pre-scanner with room for larger string literals (for the reference sidecar, say).
1110
- // The limit on one literal and the limit on all literals together are separate: raise both.
1111
- const enclave = new Enclave({
1112
- preScan: {
1113
- config: {
1114
- maxInputSize: 1024 * 1024,
1115
- maxLineLength: 100000,
1116
- maxStringLength: 512 * 1024,
1117
- maxTotalStringContent: 1024 * 1024,
1118
- },
1119
- },
1120
- });
1121
- ```
1122
-
1123
- A line is at most 100,000 characters under any configuration (the pre-scanner's absolute maximum), so a literal longer than that has to be a template literal over several lines.
1124
-
1125
- With `validate: false` the pre-scanner does not run; a script is limited to 5,242,880 characters in any case.
882
+ With `allowComposites: false` (the default at `STRICT` and `SECURE`), concatenating a reference token with anything throws inside the script: a token can only be passed on as it is. With `allowComposites: true` (the default at `STANDARD` and `PERMISSIVE`), the concatenation yields a composite handle, and a tool that is passed the handle receives the concatenated text.
1126
883
 
1127
884
  ## Runtime Notes
1128
885
 
1129
- ### Node.js 24 (V8 13.x)
886
+ <details>
887
+ <summary>Node.js 24 (V8 13.x): compiled code is not shared between sandboxes</summary>
1130
888
 
1131
889
  V8 13.x, which every Node.js 24 release ships, can crash the process when the same compiled code is instantiated in a second context: once a function has baseline (Sparkplug) code, a garbage collection that starts while a fresh closure of it is being entered reads a stale register (`SIGSEGV` in `ClearStaleLeftTrimmedPointerVisitor`). Running one script repeatedly, in fresh contexts, is exactly that pattern. Node.js 22 does not have the defect and V8 14.1 (Node.js 25) fixed it.
1132
890
 
@@ -1143,56 +901,28 @@ What that costs, measured on Node.js 24.18.0 and 22.21.1 (arm64) with a small sc
1143
901
 
1144
902
  The last column rose because the engine compares a new source with every source of the same length it still holds (V8 hashes a long string by its length alone), and the bootstraps of two scripts of one length used to differ only near their end. They now differ at their start, and on an affected engine they also differ in length.
1145
903
 
904
+ </details>
905
+
1146
906
  ### A script at a full stack
1147
907
 
1148
- A script can recurse until the stack is full and, on the way back up, call everything it has at
1149
- every level. What the enclave guarantees there:
1150
-
1151
- - **What the script catches is its own.** Every call into the runtime enters through a function of
1152
- the script's realm, so the `RangeError` of a stack overflow is an error of that realm whatever
1153
- was being called.
1154
- - **The runtime's code and yours start with room to finish.** V8 refuses to compile a function for
1155
- its first call when less than about 40 KB of stack is left (measured: 39.9 KB with Node.js 24,
1156
- 46.4 KB with Node.js 22), so code that starts in that zone fails wherever it first calls
1157
- something new. A call into the runtime needs 64 KB; a function from `globals`, a
1158
- `consoleHandler` and the host console need 128 KB, checked on the host right before they start.
1159
- With less, the script gets a `RangeError` (a console line for a `consoleHandler` is dropped)
1160
- and nothing of the host has run. Without this, a write to `process.stdout` that is cut off
1161
- halfway leaves that stream waiting forever, and that is not specific to the sandbox.
1162
- - **A tool handler starts from an empty stack**, whatever the script's stack looks like when it
1163
- makes the call.
1164
- - The check costs about 2.7 microseconds per call into the runtime and about 5.5 per call into
1165
- your code. Reading a property is not checked, and has no need to be: `globals` cannot hold
1166
- getters or proxies, so no code of yours runs on a read (see [Custom Globals](#custom-globals)).
1167
-
1168
- What it does not prevent: **Node.js writes to the process's stderr** when a promise is rejected
1169
- while the stack is full. Its own bookkeeping for the rejection is JavaScript and cannot run there,
1170
- and it prints a block (`Exception in PromiseRejectCallback`, with the source line that was
1171
- executing) from native code. A script can produce such blocks at a few megabytes per second for as
1172
- long as it runs, and the printed line is a line of the script. Nothing in JavaScript can intercept
1173
- that write, in a worker thread either. If your stderr is collected, give it a size limit and do not
1174
- parse it for decisions; a child process whose stderr you control is the complete answer.
908
+ A script can recurse until the stack is full and, on the way back up, call everything it has at every level. What the enclave guarantees there:
909
+
910
+ - **What the script catches is its own.** Every call into the runtime enters through a function of the script's realm, so the `RangeError` of a stack overflow is an error of that realm whatever was being called.
911
+ - **The runtime's code and yours start with room to finish.** V8 refuses to compile a function for its first call when less than about 40 KB of stack is left (measured: 39.9 KB with Node.js 24, 46.4 KB with Node.js 22), so code that starts in that zone fails wherever it first calls something new. A call into the runtime needs 64 KB; a function from `globals`, a `consoleHandler` and the host console need 128 KB, checked on the host right before they start. With less, the script gets a `RangeError` (a console line for a `consoleHandler` is dropped) and nothing of the host has run. Without this, a write to `process.stdout` that is cut off halfway leaves that stream waiting forever, and that is not specific to the sandbox.
912
+ - **A tool handler starts from an empty stack**, whatever the script's stack looks like when it makes the call.
913
+ - The check costs about 2.7 microseconds per call into the runtime and about 5.5 per call into your code. Reading a property is not checked, and has no need to be: `globals` cannot hold getters or proxies, so no code of yours runs on a read (see [Custom Globals](#custom-globals)).
914
+
915
+ What it does not prevent: **Node.js writes to the process's stderr** when a promise is rejected while the stack is full. Its own bookkeeping for the rejection is JavaScript and cannot run there, and it prints a block (`Exception in PromiseRejectCallback`, with the source line that was executing) from native code. A script can produce such blocks at a few megabytes per second for as long as it runs, and the printed line is a line of the script. Nothing in JavaScript can intercept that write, in a worker thread either. If your stderr is collected, give it a size limit and do not parse it for decisions; a child process whose stderr you control is the complete answer.
1175
916
 
1176
917
  ### Promise rejections a script leaves behind
1177
918
 
1178
- Node.js ends the process when a promise is rejected and nothing handles it, and the rule covers
1179
- the promises of a sandbox: an async function that throws and is not awaited, a failing tool call
1180
- nobody awaits. The enclave therefore answers the two process events `unhandledRejection` and
1181
- `rejectionHandled` itself for every promise that is not one of the host realm (it wraps
1182
- `process.emit` the first time a sandbox is used). The process goes on, none of your listeners is
1183
- called with a script's promise or reason, and your own rejections reach your listeners, or end the
1184
- process, exactly as before.
919
+ Node.js ends the process when a promise is rejected and nothing handles it, and the rule covers the promises of a sandbox: an async function that throws and is not awaited, a failing tool call nobody awaits. The enclave therefore answers the two process events `unhandledRejection` and `rejectionHandled` itself for every promise that is not one of the host realm (it wraps `process.emit` the first time a sandbox is used). The process goes on, none of your listeners is called with a script's promise or reason, and your own rejections reach your listeners, or end the process, exactly as before.
1185
920
 
1186
- - Under `--unhandled-rejections=strict` Node.js raises the exception before it emits anything, and
1187
- under `=warn` it prints its warning first: use the default mode (`throw`) or `none`.
921
+ - Under `--unhandled-rejections=strict` Node.js raises the exception before it emits anything, and under `=warn` it prints its warning first: use the default mode (`throw`) or `none`.
1188
922
  - Promises of `vm` contexts your application created itself are covered as well.
1189
- - `disableSandboxRejectionGuard()` turns this off. Your `unhandledRejection` listener then has to
1190
- ignore every promise for which `isHostPromise(promise)` is false, without touching the reason.
1191
- `disableSandboxRejectionGuard(false)` turns it back on from the next execution of an enclave.
1192
- - Test runners that give tests a stand-in `process` object (Jest does) are not covered: there the
1193
- runner reports a script's rejection as a failure of the test.
1194
- - In the sandbox, `Symbol.for` refuses keys in the `nodejs.` namespace: Node.js looks up some of
1195
- its own protocols in that registry, among them the method `util.inspect` calls on a value.
923
+ - `disableSandboxRejectionGuard()` turns this off. Your `unhandledRejection` listener then has to ignore every promise for which `isHostPromise(promise)` is false, without touching the reason. `disableSandboxRejectionGuard(false)` turns it back on from the next execution of an enclave.
924
+ - Test runners that give tests a stand-in `process` object (Jest does) are not covered: there the runner reports a script's rejection as a failure of the test.
925
+ - In the sandbox, `Symbol.for` refuses keys in the `nodejs.` namespace: Node.js looks up some of its own protocols in that registry, among them the method `util.inspect` calls on a value.
1196
926
 
1197
927
  ### Memory under sustained load
1198
928
 
@@ -1200,44 +930,59 @@ V8 keeps every script it compiled in its compilation cache until several major g
1200
930
 
1201
931
  ## API Reference
1202
932
 
1203
- ### Enclave Class
933
+ ### Enclave
1204
934
 
1205
935
  ```typescript
1206
936
  class Enclave {
1207
937
  constructor(options?: CreateEnclaveOptions);
1208
938
 
1209
- // Execute AgentScript code
1210
- run<T = unknown>(code: string): Promise<ExecutionResult<T>>;
939
+ // Execute AgentScript code; a toolHandler passed here replaces the one of the options
940
+ run<T = unknown>(code: string, toolHandler?: ToolHandler): Promise<ExecutionResult<T>>;
941
+
942
+ // Initialize the scoring gate's scorer, for scorers that need it
943
+ initialize(): Promise<void>;
944
+
945
+ getSecurityLevel(): SecurityLevel;
946
+ getEffectiveConfig(): {
947
+ securityLevel;
948
+ timeout;
949
+ maxIterations;
950
+ maxToolCalls;
951
+ sanitizeStackTraces;
952
+ maxSanitizeDepth;
953
+ maxSanitizeProperties;
954
+ memoryLimit;
955
+ realmGlobals;
956
+ };
957
+ // Cache statistics of the scoring gate: { size, maxEntries, totalHits, totalMisses, hitRate, enabled }, or null
958
+ getScoringStats(): object | null;
1211
959
 
1212
960
  // Clean up resources
1213
961
  dispose(): void;
1214
962
  }
1215
- ```
1216
-
1217
- ### ToolHandler Type
1218
963
 
1219
- ```typescript
1220
- type ToolHandler = (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
964
+ function runAgentScript<T = unknown>(code: string, options?: CreateEnclaveOptions): Promise<ExecutionResult<T>>;
1221
965
  ```
1222
966
 
1223
- Called for every `callTool()` and `toolNamespaces` method call that passes the enclave's checks. The
1224
- script's `callTool` options (`CallToolOptions`) are applied inside the sandbox and are not passed to
1225
- the handler.
967
+ ### Entry points
1226
968
 
1227
- ## Testing
969
+ | Import | Contents |
970
+ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
971
+ | `@enclave-vm/core` | `Enclave`, `runAgentScript`, the adapters (`WorkerPoolAdapter`, `InterpreterAdapter`), scoring, sidecar, session, Babel and secure-proxy utilities, and the types |
972
+ | `@enclave-vm/core/worker` | `AgentScriptRunner`, `PortableEnclave`, `InterpreterAdapter`, `Interpreter`: no Node `vm`, worker-thread or child-process modules |
1228
973
 
1229
- ```bash
1230
- # Run tests
1231
- npx nx test core
974
+ ## Related Packages
1232
975
 
1233
- # Run tests with coverage
1234
- npx nx test core --coverage
1235
- ```
976
+ - [`@enclave-vm/ast`](https://www.npmjs.com/package/@enclave-vm/ast): the validator, presets, pre-scanner and transforms used here
977
+ - [`@enclave-vm/browser`](https://www.npmjs.com/package/@enclave-vm/browser): the sandbox for browsers, in nested iframes
978
+ - [`@enclave-vm/broker`](https://www.npmjs.com/package/@enclave-vm/broker): tool registry, secrets and session routes around this package
1236
979
 
1237
- ## Related Packages
980
+ ## Documentation
1238
981
 
1239
- - [`@enclave-vm/ast`](../ast) - AST validation rules used by enclave
982
+ - Guides and reference: https://agentfront.dev/docs/guides/enclave
983
+ - Repository: https://github.com/agentfront/enclave
984
+ - Reporting a vulnerability: [SECURITY.md](https://github.com/agentfront/enclave/blob/main/SECURITY.md)
1240
985
 
1241
986
  ## License
1242
987
 
1243
- Apache-2.0
988
+ Apache-2.0. See [LICENSE](https://github.com/agentfront/enclave/blob/main/LICENSE).