@enclave-vm/core package.
Installation
Enclave Class
The main class for secure code execution.Constructor
TypeError for an option outside its type or range (a limit that is not a finite integer in range, a switch that is not a boolean, an unknown security level). An option passed as undefined has its default.
CreateEnclaveOptions
See Configuration for the ranges and for what each limit covers.
Methods
run(code, toolHandler?)
Execute code in the sandbox.code- The script to execute, at most 5,242,880 characterstoolHandler- Optional tool handler for this run; replaces the one from the constructor
ExecutionResult. run() does not reject for a failing script: the failure is in the result.
initialize()
Initialize the scoring gate, for a scorer that needs it (thelocal-llm scorer loads its model here). run() initializes the gate on first use when this was not called.
getEffectiveConfig()
The limits in effect, after the security level and the options were merged.getSecurityLevel() returns the level alone, and getScoringStats() the cache statistics of the scoring gate (null without a gate).
dispose()
Clean up resources.Validating Without Executing
Enclave has no method that only validates. Validation is the job of @enclave-vm/ast, which the enclave uses itself:
run() decides. See the @enclave-vm/ast reference.
runAgentScript(code, options?)
Create an enclave, run one script and dispose the enclave.Types
SecurityLevel
ToolHandler
callTool(name, args, options) options (CallToolOptions, e.g. { throwOnError: false }) are applied inside the sandbox and are not passed to the handler.
Example:
ExecutionError
name and message are strings of bounded length (256 and 16,384 characters) whatever a script threw. An error made inside the sandbox has no stack. The values of code:
ExecutionStats
ScoringGateConfig
Adapters
WorkerPoolAdapter
The pool behindadapter: 'worker_threads'. Create one yourself to read its metrics, and pass it as sandboxAdapter:
InterpreterAdapter
A tree-walking interpreter for hosts withoutnode:vm:
doubleVm option.
The interpreter behind the adapter is exported as well, for a host that drives it without an Enclave: Interpreter (options: InterpreterOptions) and the errors a run ends with.
A script cannot catch
StepLimitError or DeadlineError. Through an Enclave they arrive as result.error.code STEP_LIMIT_EXCEEDED and EXECUTION_TIMEOUT.
Scoring Classes
ScoringGate is the gate an enclave builds from scoringGate; it can be used on its own:
RuleBasedScorer scores features, not source text. FeatureExtractor.extract(code) produces them, and throws FeatureExtractionError for text it cannot parse:
Reference Sidecar
Pass large strings between tools by reference.ReferenceSidecarOptions
getReferenceConfig(securityLevel, overrides?) returns the defaults of a level with your overrides applied. getMaxTotalResolvedSize(config) returns the limit on what one execution resolves in total: config.maxTotalResolvedSize when it is a number of at least 0, otherwise twice config.maxTotalSize.
Process-Level Functions
Node.js ends the process when a promise is rejected and nothing handles it, and that rule covers the promises of a sandbox: an async function of a script that throws and is not awaited, a failing tool call nobody awaits. The enclave therefore answers the process eventsunhandledRejection and rejectionHandled itself for every promise that is not one of the host realm. Your own rejections reach your listeners, or end the process, as before. Two functions are for a host that wants this in its own hands.
disableSandboxRejectionGuard(disabled?)
disableSandboxRejectionGuard(false) undoes it, but not at once: the guard is active again from the next execution of any enclave, and until then rejections still reach your listeners. Call it only when your application has an unhandledRejection listener that decides for itself; without one, a rejection a script leaves behind ends the process.
isHostPromise(promise)
Promise (or a subclass of it). A script cannot make its promise pass this test. With the guard disabled, your listener has to ignore every promise for which it returns false, and must not touch the reason: it is a value of the script.
--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.
Complete Example
Related
- Overview - Feature overview
- Configuration - All options
- Security Levels - Security details