> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Transformation

> Transform validated code for safe execution with runtime proxies

ast-guard can transform validated code for safe execution. Transformations wrap dangerous operations with safe runtime proxies that enforce limits and provide isolation.

## Basic Usage

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { transformAgentScript } from '@enclave-vm/ast';

const code = `
  const users = await callTool('users:list', {});
  for (const user of users) {
    console.log(user.name);
  }
  return users.length;
`;

const transformed = transformAgentScript(code, {
  wrapInMain: true,       // Wrap in async function __ag_main()
  transformCallTool: true, // callTool -> __safe_callTool
  transformLoops: true,    // Guard loops with the iteration limit
  maxIterations: 10000,    // The limit, written into each loop check as a number
  prefix: '__safe_',      // Prefix for safe runtime functions
});
```

## Transformation Output

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Original:
const users = await callTool('users:list', {});
for (const user of users) {
  console.log(user.name);
}
return users.length;

// Transformed:
async function __ag_main() {
  const users = await __safe_callTool('users:list', {});
  for (const user of __safe_forOf(users)) {
    __safe_console.log(user.name);
  }
  return users.length;
}
```

## Transformation Options

| Option | Type | Default | Description |
| - | - | - | - |
| `wrapInMain` | boolean | true | Wrap code in `async function __ag_main()` |
| `transformCallTool` | boolean | true | Give every global the script names that is not a standard safe global the prefix: `callTool` becomes `__safe_callTool`, `console` becomes `__safe_console` |
| `transformLoops` | boolean | true | Guard loops with the iteration limit |
| `maxIterations` | number | - | The iteration limit of `for`, `while` and `do...while` loops, written into each loop check as a number. Without it the check compares with the runtime's `__maxIterations`, and a script that uses that name is refused |
| `additionalIdentifiers` | string\[] | `[]` | Names that keep their name: custom globals and tool namespaces of the host |
| `prefix` | string | `'__safe_'` | Prefix for safe runtime functions |
| `parseOptions` | object | - | Options passed to the parser |

## Main Wrapper

The main wrapper enables top-level await and provides an entry point:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Before transformation
const data = await callTool('fetch', {});
return data;

// After transformation
async function __ag_main() {
  const data = await __safe_callTool('fetch', {});
  return data;
}
```

The runtime calls `__ag_main()` to execute the script.

## Safe callTool

The `callTool` transformation proxies all tool calls through the runtime:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Before
await callTool('users:list', { limit: 10 });

// After
await __safe_callTool('users:list', { limit: 10 });
```

The `__safe_callTool` proxy:

* Counts tool calls against `maxToolCalls` limit
* Routes calls through the configured `toolHandler`
* Sanitizes arguments and return values

## Safe Loops

Loop transformations enforce iteration limits:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// for-of before
for (const user of users) {
  process(user);
}

// for-of after
for (const user of __safe_forOf(users)) {
  process(user);
}

// for loop before
for (let i = 0; i < 100; i++) {
  process(i);
}

// for loop after (a counter before the loop, a check at the start of its body)
let __iter_0 = 0;
for (let i = 0; i < 100; i++) {
  if (++__iter_0 > 10000) throw 'Maximum iteration limit exceeded. This limit prevents infinite loops.';
  process(i);
}
```

`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 `maxIterations` is given, as `@enclave-vm/core` does. Without `maxIterations` the 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:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Before
console.log('Hello');

// After
__safe_console.log('Hello');
```

The `__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 at `PERMISSIVE`

## Reserved Prefixes

The transformation reserves these prefixes that user code cannot use:

* `__ag_` - AgentScript internal identifiers
* `__safe_` - Safe runtime proxies

Any attempt to declare identifiers with these prefixes is blocked by the `ReservedPrefixRule`.

## Other Transforms

The package exports the transforms `@enclave-vm/core` applies after validation. Each one changes an AST in place:

| Function | What it does |
| - | - |
| `transformConcatenation(ast, options)` | Rewrites `a + b` to `__safe_concat(a, b)`, so that a runtime can count what a concatenation makes. `compoundAssignment` (default `true`) rewrites `x += y` the same way, so that it is charged like `x + y`; `arraySpread` (default `false`) wraps array literals that contain a spread, for a runtime that defines the helpers for it |
| `transformTemplateLiterals(ast)` | Rewrites a template literal with substitutions to a `__safe_template(...)` call |
| `extractLargeStrings(ast, { threshold, onExtract })` | Replaces string literals of at least `threshold` bytes with the reference id `onExtract` returns |
| `guardComputedMemberKeys(ast, parse, options)` | Wraps computed member keys so that the resolved key is checked at run time |
| `guardArrayWrites(ast, options?)` | Hands every write that can change the size of an array to the runtime: `X[K] = V` and `X.length = V` become `__safe_set(X, K, V)`, and in every other write through such a member (a compound or logical assignment, `++`, a target in a destructuring pattern or in the head of a loop) the target becomes `__safe_slot(X, K).v`. Apply it after `guardComputedMemberKeys`. `@enclave-vm/core` uses it when `memoryLimit` is set. A write to a literal index below 64 is left as it is; `options.unguardedBelow` lowers that number for a runtime whose limit holds fewer slots. The statement that binds the two runtime functions goes after the directive prologue of the program. |
| `rewriteImports(code, config)` | Rewrites imports of npm packages to CDN URLs (see below) |

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

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { rewriteImports } from '@enclave-vm/ast';

const { code, rewrittenImports } = rewriteImports(source, {
  enabled: true,
  cdnBaseUrl: 'https://esm.example.com',
  packageVersions: { react: '18.2.0' },
});
```

* Only allowed packages can be imported: the ones in `allowedPackages` when it is given, otherwise the keys of `packageVersions`. An import of another package throws. This holds for import declarations, re-exports and dynamic `import()`.
* 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; `cdnBaseUrl` is 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 when `transform: true` (default):

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave } from '@enclave-vm/core';

const enclave = new Enclave({
  transform: true, // Default - apply transformations
  toolHandler: async (name, args) => { /* ... */ },
});

// Code is automatically transformed before execution
await enclave.run(`
  const data = await callTool('fetch', {});
  return data;
`);
```

## Transformation Without Validation

You can transform code independently of validation:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { transformAgentScript, JSAstValidator, createAgentScriptPreset } from '@enclave-vm/ast';

const validator = new JSAstValidator(createAgentScriptPreset());

// Step 1: Validate
const validation = await validator.validate(code);
if (!validation.valid) {
  throw new Error('Validation failed');
}

// Step 2: Transform
const transformed = transformAgentScript(code);

// Step 3: Execute transformed code with your runtime
executeInSandbox(transformed);
```

## Related

* [Overview](https://docs.agentfront.dev/enclave/core-libraries/ast-guard/overview.md) - Getting started
* [AgentScript Preset](https://docs.agentfront.dev/enclave/core-libraries/ast-guard/agentscript-preset.md) - Preset configuration
* [enclave-vm](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/overview.md) - Runtime sandbox


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.