Basic Usage
Transformation Output
Transformation Options
Main Wrapper
The main wrapper enables top-level await and provides an entry point:__ag_main() to execute the script.
Safe callTool
ThecallTool transformation proxies all tool calls through the runtime:
__safe_callTool proxy:
- Counts tool calls against
maxToolCallslimit - Routes calls through the configured
toolHandler - Sanitizes arguments and return values
Safe Loops
Loop transformations enforce iteration limits:while and do...while loops get the same counter and check. Two things keep a script from switching the limit off:
- The counter has a name the script does not mention anywhere: the transformer never hands out a counter name that appears in the script.
- The limit is a number in the loop’s own code when
maxIterationsis given, as@enclave-vm/coredoes. WithoutmaxIterationsthe check compares with the runtime’s__maxIterations; that name is reserved, and a script that uses it fails the transform.
Safe Console
Console methods are proxied for rate limiting:__safe_console proxy:
- Counts calls against
maxConsoleCalls - Tracks output bytes against
maxConsoleOutputBytes - Hands each line to the enclave’s
consoleHandler, or to the host console atPERMISSIVE
Reserved Prefixes
The transformation reserves these prefixes that user code cannot use:__ag_- AgentScript internal identifiers__safe_- Safe runtime proxies
ReservedPrefixRule.
Other Transforms
The package exports the transforms@enclave-vm/core applies after validation. Each one changes an AST in place:
The validator’s own
transform option (validate(code, { transform: { enabled: true, ... } })) can prefix identifiers and rewrite computed keys. A computed key it rewrites is printed as one string literal, whatever characters the key holds.
rewriteImports
- Only allowed packages can be imported: the ones in
allowedPackageswhen it is given, otherwise the keys ofpackageVersions. An import of another package throws. This holds for import declarations, re-exports and dynamicimport(). - A dynamic
import('react')of an allowed package is rewritten. One whose specifier is not written as a string cannot be checked and throws. - A version is a version number, range or tag without path or URL characters;
cdnBaseUrlis an HTTPS URL without credentials, query or fragment. Anything else throws. - The allowlist is the configuration’s. Where the configuration comes from the same party as the code, the rewrite restricts nothing.
Integration with enclave-vm
enclave-vm automatically applies transformations whentransform: true (default):
Transformation Without Validation
You can transform code independently of validation:Related
- Overview - Getting started
- AgentScript Preset - Preset configuration
- enclave-vm - Runtime sandbox