Module engine 

ScriptEngine + Session: a sandboxed QuickJS runtime/context.

ScriptEngine::run is the one-shot path (fresh VM, library/test convenience). Session is the persistent path: one QuickJS runtime + context reused across many Session::execute calls so user globalThis state survives between executions REPL-style while framework bindings refresh each call. The production MCP server keeps a set of Sessions with a retention policy in crate::session_table::SessionTable.

Structs

RunContext

Per-call execution context holding session-level state the script reaches via globals (vars, fs, artifacts, and the optional browser bindings page / context / request). A None entry skips installation of the matching global so pure-compute scripts don’t need the extra infrastructure.

RunOptions

Per-call overrides for a single run invocation.

ScriptCaps

Resolved, ready-to-install sandbox relaxations. Built by the host (MCP/CLI/BDD) from ferridriver_config::ScriptingConfig; the engine only consumes it. Default is the locked-down posture: no env.

ScriptEngine

Sandboxed QuickJS scripting engine.

ScriptEngineConfig

Configuration for the script engine.

Session

A persistent QuickJS runtime + context reused across many script executions for one logical session.

SessionRun

Outcome of one Session::execute: the script result plus whether the VM was left in a state the caller must discard before the next execution. Poisoning means the interpreter was force-halted mid-run (timeout interrupt) or hit an allocation fault — a plain JS throw is NOT poisoning and leaves session state intact.

Enums

ExtensionHost

Which host is running the extension/registry. Exposed to JS as the native global ferridriver.host (“mcp” | “bdd” | “script”) so one extension file can branch its contributions — e.g. only defineTool under MCP, only Given/When/Then under the test runner — without any runtime cost (a single string set once per session).

Constants

DEFAULT_GC_THRESHOLD

Default GC trigger threshold (64 MiB). QuickJS is reference-counted; the cycle GC otherwise fires adaptively at ~1.5x live size, so an object-churny automation script (big evaluate results, repeated ariaSnapshot/snapshot trees, locator chains) pays recurring mark-sweep stalls mid-run. Raising the floor lets a typical short-lived script finish with few/zero cycle-GC passes — the same lever Amazon LLRT exposes (LLRT_GC_THRESHOLD_MB, 20 MiB default). default_memory_limit (256 MiB) remains the hard backstop, and acyclic garbage is still freed immediately by refcounting, so this only defers cycle collection, not normal frees.

DEFAULT_MAX_CONSOLE_BYTES

DEFAULT_MAX_CONSOLE_ENTRIES

Default console-capture limits.

DEFAULT_MAX_CONSOLE_ENTRY_BYTES

DEFAULT_MAX_SESSION_VMS

Default cap on concurrently-retained persistent session VMs. When a new session would exceed this, the least-recently-used idle VM is evicted (its globalThis state is discarded; a later call rebuilds).

DEFAULT_MEMORY_LIMIT

Default per-script memory quota (256 MiB).

DEFAULT_SESSION_IDLE_TTL

Default idle TTL: a session VM untouched this long is reaped on the next SessionTable::acquire, independent of cap pressure, so a long-running server does not pin dead sessions’ memory indefinitely.

DEFAULT_STACK_SIZE

Default per-script JS stack size (1 MiB).

DEFAULT_TIMEOUT

Default per-script wall-clock timeout (5 minutes).