Package com.tnsai.tools.code

Class JsExecutionTools

java.lang.Object

com.tnsai.tools.code.JsExecutionTools

All Implemented Interfaces:

AutoCloseable

public class JsExecutionTools
extends Object
implements AutoCloseable

Function-shape JavaScript tools — runs user code through Node.js inside the framework's Sandbox SPI using the process backend by default with ResourceLimits.standard() and a requested NetPolicy.denyAll() policy that the portable process backend cannot enforce. Replaces the legacy GraalVM Polyglot implementation; a node binary on the host's PATH is now required.

One typed @Tool method:

Method	Backend	Idempotent
jsExecute(java.lang.String, long)	Sandbox SPI + Node.js	false

Last-expression semantics are preserved across the Node.js boundary by a small wrapper that evals the user code in strict mode, captures stdout/stderr through Node's normal streams, and emits the last expression value via a private marker on stdout. The Java side parses the marker out and surfaces it as the Result: line — compatible with the previous GraalVM-based output shape.

Implements AutoCloseable for forward-compat — sandbox lifetime is per-execute so close() is currently a no-op.

Since:

0.10.0 (TNS-343 — migration to Sandbox SPI)

Constructor Summary

Constructors

Constructor	Description
JsExecutionTools()	Default constructor — pins the "process" backend so the host's node binary is used directly.
JsExecutionTools(com.tnsai.quality.sandbox.SandboxFactory factory, com.tnsai.quality.sandbox.SandboxSpec spec, String nodePath)	Full control: explicit sandbox backend + spec + node path.
JsExecutionTools(String nodePath)	Explicit node binary path; process sandbox backend.

Method Summary

Modifier and Type	Method	Description
void	close()	No persistent resources held — sandbox lifetime is per-execute.
String	jsExecute(String code, long timeoutMs)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

JsExecutionTools

public JsExecutionTools()

Default constructor — pins the "process" backend so the host's node binary is used directly. Consumers who want stronger isolation pass an explicit factory + image-bearing spec via the full-control constructor — SandboxFactory.preferred() can pick a container backend that requires spec.image(), which has no sensible default for "run host node".

JsExecutionTools

public JsExecutionTools(String nodePath)

Explicit node binary path; process sandbox backend.

JsExecutionTools

public JsExecutionTools(com.tnsai.quality.sandbox.SandboxFactory factory,
 com.tnsai.quality.sandbox.SandboxSpec spec,
 String nodePath)

Full control: explicit sandbox backend + spec + node path. The spec's ResourceLimits.timeout() is used as the upper bound; jsExecute(java.lang.String, long)'s timeoutMs parameter further clamps to MAX_TIMEOUT_MS.

Method Details

jsExecute

@Tool(name="js_execute",
      description="Run a JavaScript snippet through Node.js using the configured Sandbox backend with timeout and output caps. The default configuration uses the process backend with a scrubbed environment and temporary working directory; its filesystem access remains that of the host process, and its requested deny-all network policy is not enforced unless a stronger backend is configured. Returns stdout plus the last expression\'s value. {timeoutMs} clamps to [0, 30000]; 0 \u2192 default 5000ms. Throws TimeoutException on overrun.",
      keywords={"code","execute","run","javascript","js","sandbox","node","eval"},
      idempotent=false)
public String jsExecute(@ToolParam(description="JavaScript source code")
 String code,
 @ToolParam(description="Per-call timeout in milliseconds (clamped to 30000); 0 \u2192 default 5000",required=false,defaultValue="0")
 long timeoutMs)
                 throws TimeoutException,
InterruptedException

Throws:

TimeoutException

InterruptedException

close

public void close()

No persistent resources held — sandbox lifetime is per-execute.

Specified by:

close in interface AutoCloseable