@enclave-vm/core 2.19.2 → 2.20.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -1
- package/bounded-json.d.ts +33 -0
- package/enclave.d.ts +4 -1
- package/esm/index.mjs +875 -147
- package/esm/worker.mjs +1647 -67
- package/index.js +883 -155
- package/interpreter/interpreter.d.ts +4 -5
- package/package.json +3 -3
- package/portable-enclave.d.ts +51 -0
- package/portable-globals.d.ts +2 -0
- package/realm-regex-backstop.d.ts +18 -0
- package/scoring/scoring-gate.d.ts +2 -0
- package/sidecar/reference-resolver.d.ts +7 -2
- package/src/adapters/worker-pool/package.json +3 -3
- package/src/adapters/worker-pool/worker-script.js +657 -109
- package/types.d.ts +13 -3
- package/worker.d.ts +2 -0
- package/worker.js +1637 -67
package/README.md
CHANGED
|
@@ -73,6 +73,33 @@ if (result.success) {
|
|
|
73
73
|
enclave.dispose();
|
|
74
74
|
```
|
|
75
75
|
|
|
76
|
+
### Portable AgentScript runner
|
|
77
|
+
|
|
78
|
+
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
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
import { AgentScriptRunner } from '@enclave-vm/core/worker';
|
|
82
|
+
|
|
83
|
+
const runner = new AgentScriptRunner({
|
|
84
|
+
securityLevel: 'STANDARD',
|
|
85
|
+
timeout: 5000,
|
|
86
|
+
maxSteps: 1_000_000,
|
|
87
|
+
maxToolCalls: 20,
|
|
88
|
+
maxHostFunctionCalls: 200,
|
|
89
|
+
hostFunctions: { getTool: (name) => ({ name }) },
|
|
90
|
+
toolHandler: async (name, args) => ({ name, args }),
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
try {
|
|
94
|
+
const result = await runner.run("return getTool('example').name;");
|
|
95
|
+
console.log(result);
|
|
96
|
+
} finally {
|
|
97
|
+
runner.dispose();
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The runner supports Node and Cloudflare Workers with `nodejs_compat`. Tool and host-function arguments and results cross as bounded plain data. Steps, call depth, pending calls, allocation, tool calls, console output, bridge payloads and sidecar storage all have finite limits. `maxSteps` bounds interpreted CPU work, including work charged for built-in operations. `timeout` is checked between interpreter steps and at I/O boundaries; deployed Cloudflare Workers do not advance their clocks during CPU-only work, so it is not a hard wall-time cutoff there. Synchronous host callbacks cannot be preempted. Unsupported VM-only options and pre-scan overrides fail at construction.
|
|
102
|
+
|
|
76
103
|
## Configuration
|
|
77
104
|
|
|
78
105
|
### CreateEnclaveOptions
|
|
@@ -146,7 +173,9 @@ The constructor checks its options and throws a `TypeError` for a value outside
|
|
|
146
173
|
|
|
147
174
|
- **Text**: concatenation (`a + b`, and `x += y`, which is charged like `x + y`) and the methods that multiply their input (`repeat`, `padStart`, `padEnd`, `join`).
|
|
148
175
|
- **Arrays**: no single array is larger than the limit holds, at 8 bytes per element, and what an operation adds is charged: `push`, `unshift`, `splice`, `fill`, the elements `concat`, `flat`, `flatMap` and a spread literal add, and what `Array.from` makes out of something that is not an array.
|
|
149
|
-
- **Not counted**: a copy is free, so a script can hold many arrays that are each within the limit; object literals, Maps and Sets are not counted.
|
|
176
|
+
- **Not counted by the VM adapter**: a copy is free, so a script can hold many arrays that are each within the limit; object literals, Maps and Sets are not counted.
|
|
177
|
+
|
|
178
|
+
The portable interpreter additionally charges copied host-function results and tool responses by their serialized size to the cumulative allocation budget.
|
|
150
179
|
|
|
151
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.
|
|
152
181
|
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* JSON text measured as it is written, for the host side of a tool call.
|
|
3
|
+
*
|
|
4
|
+
* A value referenced many times is written as many times, so the JSON text of a small value can
|
|
5
|
+
* be far longer than the value is large, and writing it calls every getter and `toJSON` on the
|
|
6
|
+
* way each time. {@link stringifyWithin} writes the text with `JSON.stringify` and gives up as soon
|
|
7
|
+
* as it would be longer than a limit, so the work done on a value that does not fit is in
|
|
8
|
+
* proportion to the limit. The realms of the sandbox have their own copy of the same rule (the
|
|
9
|
+
* tool bridges and the console).
|
|
10
|
+
*
|
|
11
|
+
* @packageDocumentation
|
|
12
|
+
*/
|
|
13
|
+
/** Thrown by {@link stringifyWithin} when the text would be longer than its limit. */
|
|
14
|
+
export declare class JsonTooLargeError extends Error {
|
|
15
|
+
constructor(limit: number);
|
|
16
|
+
}
|
|
17
|
+
/** A separate work limit for values with many members omitted from their JSON text. */
|
|
18
|
+
export declare class JsonTraversalLimitError extends Error {
|
|
19
|
+
constructor(limit: number);
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* The JSON text of `value`, as `JSON.stringify` writes it, or a {@link JsonTooLargeError} as soon
|
|
23
|
+
* as it would be longer than `limit` bytes. What each member adds is counted as it is written,
|
|
24
|
+
* and the count is a lower bound of its UTF-8 bytes (a code unit is at least one byte, an escape
|
|
25
|
+
* only adds), so a value whose text is within the limit is never given up. The members
|
|
26
|
+
* `JSON.stringify` visits are bounded separately, including members it omits (a function,
|
|
27
|
+
* undefined). The work cap allows at least 10,000 visits and at most 1,000,000. A traversal
|
|
28
|
+
* refusal raises {@link JsonTraversalLimitError}. Any other error of `JSON.stringify` (a cycle, a BigInt,
|
|
29
|
+
* a getter that throws) is thrown as it is.
|
|
30
|
+
*/
|
|
31
|
+
export declare function stringifyWithin(value: unknown, limit: number): string | undefined;
|
|
32
|
+
/** The number of bytes `value` takes in UTF-8. */
|
|
33
|
+
export declare function utf8Length(value: string): number;
|
package/enclave.d.ts
CHANGED
|
@@ -86,7 +86,10 @@ export declare class Enclave {
|
|
|
86
86
|
* @param toolHandler Optional tool handler (overrides constructor config)
|
|
87
87
|
* @returns Execution result
|
|
88
88
|
*/
|
|
89
|
-
run<T = unknown>(code: string, toolHandler?: ToolHandler
|
|
89
|
+
run<T = unknown>(code: string, toolHandler?: ToolHandler, options?: {
|
|
90
|
+
onToolBridgeFailure?: () => void;
|
|
91
|
+
maxToolResultBytes?: number;
|
|
92
|
+
}): Promise<ExecutionResult<T>>;
|
|
90
93
|
/**
|
|
91
94
|
* Single exit for returned errors: with `sanitizeStackTraces` on, strip host paths, file
|
|
92
95
|
* locations and frames from the stack, whichever stage (validation, transform, compile,
|