JavaScript Sandbox

The edx_code function executes JavaScript in a restricted sandbox environment designed for safety and performance.

Allowed Features

• ES6+ JavaScript: Arrow functions, template literals, const/let, destructuring
• Standard Built-ins: Math, Date, JSON, RegExp, Array, Object, String, Number
• Array Methods: map, filter, reduce, forEach, find, findIndex, some, every, etc.
• Object Methods: keys, values, entries, assign, freeze, seal, etc.
• String Methods: split, join, replace, match, search, substring, slice, etc.
• Console: console.log for debugging (availability not yet verified in testing)

Restricted Operations

The sandbox prevents access to potentially dangerous operations:

• Network: No fetch, XMLHttpRequest, or network calls (validation pending)
• Filesystem: No file read/write operations (validation pending)
• Process: No process control or system calls (validation pending)
• Imports: No require, import, or module loading (validation pending)

Note: Restrictions marked as “validation pending” have not been fully verified as of v2.6.0. Assume these operations are blocked, but verify in your test environment before relying on this behavior for security.

Global State Behavior

⚠️ Current Behavior (v2.6.0): Contrary to typical sandbox expectations, globalThis does persist state across all edx_code executions within the same agent process. Verified behavior includes:

• Global counters increment across all log entries
• Set and Map objects accumulate data over time
• Variables stored in globalThis remain accessible between invocations

// This WILL persist across events
edx_code("globalThis.__edx_counter = (globalThis.__edx_counter || 0) + 1; item['attributes']['counter'] = globalThis.__edx_counter;")

// Result: counter increments from 1 to N across all processed logs

Testing has confirmed counters incrementing across hundreds of events and Set objects successfully tracking unique values.

Use Cases for Global State

• Running counters or statistics across all events
• Deduplication tracking with Set objects
• Caching computed values that don’t change
• Accumulating data for aggregation

Important Considerations

• Global state is per-agent-pod, not pipeline-wide in distributed deployments
• State is lost if the agent pod restarts
• State is not synchronized across multiple agent replicas
• This behavior is observational and may change in future releases

State Persistence Within a Single Call

Variables declared with const or let in one edx_code call are not accessible to subsequent edx_code calls. Each edx_code execution is independent:

// This will NOT work
edx_code("const myVar = 10;")
edx_code("item['attributes']['result'] = myVar * 2;")  // Error: myVar is undefined

// Instead, store in attributes
edx_code("item['attributes']['myVar'] = 10;")
edx_code("item['attributes']['result'] = item['attributes']['myVar'] * 2;")

However, globalThis does persist between executions within the same agent process (see Global State Behavior above).

Security Considerations

While the sandbox provides isolation from dangerous operations, consider these security best practices:

• Validate Input: Don’t trust field values to be well-formed or safe
• Limit Complexity: Complex JavaScript increases execution time and memory usage
• Avoid Secrets: Don’t hardcode credentials or sensitive data in edx_code statements
• Test First: Validate transformations in test environments before production
• Monitor Behavior: Watch for unexpected patterns that might indicate injection attempts