@vinkius-core/mcp-fusion 2.12.0 → 2.13.1

package/dist/sandbox/SandboxEngine.d.ts

@@ -0,0 +1,202 @@
+/**
+ * SandboxEngine — Zero-Trust V8 Isolate for Computation Delegation
+ *
+ * Allows LLMs to send JavaScript functions as strings to be executed
+ * in a sealed V8 isolate. The data stays on the client's machine,
+ * only the result travels back to the LLM.
+ *
+ * Architecture (V8 Engineering Rules):
+ *   1. ONE Isolate per SandboxEngine (boot ~5-10ms), reused across requests
+ *   2. NEW Context per execute() call (~0.1ms), pristine and empty
+ *   3. ExternalCopy + Script + Context are ALWAYS released in `finally`
+ *   4. Execution is ALWAYS async (script.run, never runSync)
+ *   5. Context is empty — no process, require, fs, globalThis injected
+ *   6. AbortSignal kills isolate.dispose() instantly (Connection Watchdog)
+ *
+ * The `isolated-vm` package is a peerDependency (optional).
+ * If not installed, the engine throws a clear error at construction time.
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  SandboxEngine (owns 1 Isolate)                         │
+ *   │                                                         │
+ *   │  execute(code, data, { signal? })                       │
+ *   │    ┌──────────┐                                         │
+ *   │    │ Abort?   │ pre-flight signal check                  │
+ *   │    ├──────────┤                                         │
+ *   │    │ Guard    │ fail-fast syntax check                   │
+ *   │    ├──────────┤                                         │
+ *   │    │ Context  │ new per request (empty!)                 │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy In  │ ExternalCopy (deep, no refs)             │
+ *   │    ├──────────┤                                         │
+ *   │    │ Compile  │ isolate.compileScript                    │
+ *   │    ├──────────┤                                         │
+ *   │    │ Run      │ script.run (ASYNC, with timeout + abort) │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy Out │ JSON.parse result                        │
+ *   │    └──────────┘                                         │
+ *   │                                                         │
+ *   │  finally: signal.removeEventListener()                  │
+ *   │           inputCopy.release()                           │
+ *   │           script.release()                              │
+ *   │           context.release()                             │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * @module
+ */
+/**
+ * Configuration for a SandboxEngine instance.
+ *
+ * All fields are optional — sensible defaults are applied.
+ *
+ * @example
+ * ```typescript
+ * const engine = new SandboxEngine({
+ *     timeout: 3000,       // Kill after 3s
+ *     memoryLimit: 64,     // 64MB per isolate
+ *     maxOutputBytes: 512_000, // 500KB max result
+ * });
+ * ```
+ */
+export interface SandboxConfig {
+    /**
+     * Maximum execution time in milliseconds.
+     * If the script exceeds this, the V8 isolate kills it.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Maximum memory for the V8 isolate in megabytes.
+     * If exceeded, the isolate dies and is recreated on next call.
+     * @default 128
+     */
+    memoryLimit?: number;
+    /**
+     * Maximum size of the serialized output in bytes.
+     * Prevents a malicious script from returning gigabytes of data.
+     * @default 1_048_576 (1MB)
+     */
+    maxOutputBytes?: number;
+}
+/**
+ * Error codes for sandbox execution failures.
+ *
+ * - `TIMEOUT`: Script exceeded the time limit
+ * - `MEMORY`: Isolate ran out of memory (auto-recovered)
+ * - `SYNTAX`: JavaScript syntax error in the provided code
+ * - `RUNTIME`: Script threw an error during execution
+ * - `OUTPUT_TOO_LARGE`: Result exceeds `maxOutputBytes`
+ * - `INVALID_CODE`: Failed the SandboxGuard fail-fast check
+ * - `UNAVAILABLE`: `isolated-vm` is not installed
+ * - `ABORTED`: Execution was cancelled via AbortSignal (client disconnect)
+ */
+export type SandboxErrorCode = 'TIMEOUT' | 'MEMORY' | 'SYNTAX' | 'RUNTIME' | 'OUTPUT_TOO_LARGE' | 'INVALID_CODE' | 'UNAVAILABLE' | 'ABORTED';
+/**
+ * Result of a sandbox execution.
+ *
+ * @example
+ * ```typescript
+ * const result = await engine.execute('(data) => data.length', [1, 2, 3]);
+ * if (result.ok) {
+ *     console.log(result.value);       // 3
+ *     console.log(result.executionMs); // 0.42
+ * } else {
+ *     console.log(result.code);  // 'TIMEOUT'
+ *     console.log(result.error); // 'Script execution timed out (5000ms)'
+ * }
+ * ```
+ */
+export type SandboxResult<T = unknown> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly executionMs: number;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly code: SandboxErrorCode;
+};
+/**
+ * Zero-trust V8 sandbox for executing LLM-provided JavaScript.
+ *
+ * Creates a single V8 `Isolate` at construction time and reuses it
+ * across all `execute()` calls. Each call gets a fresh, empty `Context`
+ * with no dangerous globals (no `process`, `require`, `fs`, etc.).
+ *
+ * If the isolate dies (e.g., OOM), it is automatically recreated
+ * on the next `execute()` call.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new SandboxEngine({ timeout: 3000, memoryLimit: 64 });
+ *
+ * const result = await sandbox.execute(
+ *     '(data) => data.filter(d => d.risk > 90)',
+ *     [{ name: 'A', risk: 95 }, { name: 'B', risk: 30 }],
+ * );
+ *
+ * if (result.ok) {
+ *     console.log(result.value); // [{ name: 'A', risk: 95 }]
+ * }
+ *
+ * // IMPORTANT: dispose when no longer needed
+ * sandbox.dispose();
+ * ```
+ */
+export declare class SandboxEngine {
+    private readonly _timeout;
+    private readonly _memoryLimit;
+    private readonly _maxOutputBytes;
+    private _isolate;
+    private _disposed;
+    constructor(config?: SandboxConfig);
+    /**
+     * Execute a JavaScript function string against the provided data.
+     *
+     * The function is compiled and run in a sealed V8 isolate with:
+     * - No `process`, `require`, `fs`, or network access
+     * - Strict timeout enforcement (async, non-blocking)
+     * - Memory limit enforcement
+     * - Automatic C++ pointer cleanup (ExternalCopy, Script, Context)
+     * - Cooperative cancellation via AbortSignal (Connection Watchdog)
+     *
+     * @param code - A JavaScript function expression as a string.
+     *   Must be an arrow function or function expression.
+     *   Example: `(data) => data.filter(d => d.value > 10)`
+     *
+     * @param data - The data to pass into the function.
+     *   Deeply copied into the isolate (no references leak).
+     *
+     * @param options - Optional execution options.
+     * @param options.signal - AbortSignal for cooperative cancellation.
+     *   When the signal fires (e.g., MCP client disconnects), the engine
+     *   calls `isolate.dispose()` to kill the V8 C++ threads instantly.
+     *   The isolate is auto-recovered on the next `.execute()` call.
+     *
+     * @returns A `SandboxResult` with the computed value or an error.
+     */
+    execute<T = unknown>(code: string, data: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxResult<T>>;
+    /**
+     * Release all resources held by this engine.
+     *
+     * After calling `dispose()`, any subsequent `execute()` calls
+     * will return `{ ok: false, code: 'UNAVAILABLE' }`.
+     */
+    dispose(): void;
+    /**
+     * Check if the engine has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Ensure the isolate is alive. If it died (OOM), create a new one.
+     * @internal
+     */
+    private _ensureIsolate;
+    /**
+     * Classify an error from V8 execution into a typed SandboxResult.
+     * @internal
+     */
+    private _classifyError;
+}
+//# sourceMappingURL=SandboxEngine.d.ts.map

package/dist/sandbox/SandboxEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEngine.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAMH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GACtB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,SAAS,CAAC;AAEhB;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAkCtF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,CAAC,EAAE,aAAa;IAgBlC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACnC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAkH5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAUf;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAID;;;OAGG;IACH,OAAO,CAAC,cAAc;IAatB;;;OAGG;IACH,OAAO,CAAC,cAAc;CA6CzB"}

package/dist/sandbox/SandboxEngine.js

@@ -0,0 +1,343 @@
+/**
+ * SandboxEngine — Zero-Trust V8 Isolate for Computation Delegation
+ *
+ * Allows LLMs to send JavaScript functions as strings to be executed
+ * in a sealed V8 isolate. The data stays on the client's machine,
+ * only the result travels back to the LLM.
+ *
+ * Architecture (V8 Engineering Rules):
+ *   1. ONE Isolate per SandboxEngine (boot ~5-10ms), reused across requests
+ *   2. NEW Context per execute() call (~0.1ms), pristine and empty
+ *   3. ExternalCopy + Script + Context are ALWAYS released in `finally`
+ *   4. Execution is ALWAYS async (script.run, never runSync)
+ *   5. Context is empty — no process, require, fs, globalThis injected
+ *   6. AbortSignal kills isolate.dispose() instantly (Connection Watchdog)
+ *
+ * The `isolated-vm` package is a peerDependency (optional).
+ * If not installed, the engine throws a clear error at construction time.
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  SandboxEngine (owns 1 Isolate)                         │
+ *   │                                                         │
+ *   │  execute(code, data, { signal? })                       │
+ *   │    ┌──────────┐                                         │
+ *   │    │ Abort?   │ pre-flight signal check                  │
+ *   │    ├──────────┤                                         │
+ *   │    │ Guard    │ fail-fast syntax check                   │
+ *   │    ├──────────┤                                         │
+ *   │    │ Context  │ new per request (empty!)                 │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy In  │ ExternalCopy (deep, no refs)             │
+ *   │    ├──────────┤                                         │
+ *   │    │ Compile  │ isolate.compileScript                    │
+ *   │    ├──────────┤                                         │
+ *   │    │ Run      │ script.run (ASYNC, with timeout + abort) │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy Out │ JSON.parse result                        │
+ *   │    └──────────┘                                         │
+ *   │                                                         │
+ *   │  finally: signal.removeEventListener()                  │
+ *   │           inputCopy.release()                           │
+ *   │           script.release()                              │
+ *   │           context.release()                             │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * @module
+ */
+import { validateSandboxCode } from './SandboxGuard.js';
+// ── Constants ────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MEMORY_LIMIT_MB = 128;
+const DEFAULT_MAX_OUTPUT_BYTES = 1_048_576; // 1MB
+// ── Lazy Require ─────────────────────────────────────────
+/**
+ * Lazy-load isolated-vm to avoid hard dependency.
+ * Returns `null` if the package is not installed.
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _ivm = undefined;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getIvm() {
+    if (_ivm !== undefined)
+        return _ivm;
+    try {
+        // Dynamic import would be cleaner but isolated-vm uses
+        // native bindings that require synchronous resolution.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _ivm = require('isolated-vm');
+    }
+    catch {
+        _ivm = null;
+    }
+    return _ivm;
+}
+// ── Engine Implementation ────────────────────────────────
+/**
+ * Zero-trust V8 sandbox for executing LLM-provided JavaScript.
+ *
+ * Creates a single V8 `Isolate` at construction time and reuses it
+ * across all `execute()` calls. Each call gets a fresh, empty `Context`
+ * with no dangerous globals (no `process`, `require`, `fs`, etc.).
+ *
+ * If the isolate dies (e.g., OOM), it is automatically recreated
+ * on the next `execute()` call.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new SandboxEngine({ timeout: 3000, memoryLimit: 64 });
+ *
+ * const result = await sandbox.execute(
+ *     '(data) => data.filter(d => d.risk > 90)',
+ *     [{ name: 'A', risk: 95 }, { name: 'B', risk: 30 }],
+ * );
+ *
+ * if (result.ok) {
+ *     console.log(result.value); // [{ name: 'A', risk: 95 }]
+ * }
+ *
+ * // IMPORTANT: dispose when no longer needed
+ * sandbox.dispose();
+ * ```
+ */
+export class SandboxEngine {
+    _timeout;
+    _memoryLimit;
+    _maxOutputBytes;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _isolate; // ivm.Isolate
+    _disposed = false;
+    constructor(config) {
+        this._timeout = config?.timeout ?? DEFAULT_TIMEOUT_MS;
+        this._memoryLimit = config?.memoryLimit ?? DEFAULT_MEMORY_LIMIT_MB;
+        this._maxOutputBytes = config?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+        const ivm = getIvm();
+        if (!ivm) {
+            throw new Error('SandboxEngine requires the "isolated-vm" package. ' +
+                'Install it with: npm install isolated-vm');
+        }
+        this._isolate = new ivm.Isolate({ memoryLimit: this._memoryLimit });
+    }
+    /**
+     * Execute a JavaScript function string against the provided data.
+     *
+     * The function is compiled and run in a sealed V8 isolate with:
+     * - No `process`, `require`, `fs`, or network access
+     * - Strict timeout enforcement (async, non-blocking)
+     * - Memory limit enforcement
+     * - Automatic C++ pointer cleanup (ExternalCopy, Script, Context)
+     * - Cooperative cancellation via AbortSignal (Connection Watchdog)
+     *
+     * @param code - A JavaScript function expression as a string.
+     *   Must be an arrow function or function expression.
+     *   Example: `(data) => data.filter(d => d.value > 10)`
+     *
+     * @param data - The data to pass into the function.
+     *   Deeply copied into the isolate (no references leak).
+     *
+     * @param options - Optional execution options.
+     * @param options.signal - AbortSignal for cooperative cancellation.
+     *   When the signal fires (e.g., MCP client disconnects), the engine
+     *   calls `isolate.dispose()` to kill the V8 C++ threads instantly.
+     *   The isolate is auto-recovered on the next `.execute()` call.
+     *
+     * @returns A `SandboxResult` with the computed value or an error.
+     */
+    async execute(code, data, options) {
+        if (this._disposed) {
+            return { ok: false, error: 'SandboxEngine has been disposed.', code: 'UNAVAILABLE' };
+        }
+        const signal = options?.signal;
+        // ── Step 0: Pre-flight abort check ───────────────
+        // If the signal is already aborted (client disconnected before
+        // we even started), skip all V8 allocation entirely.
+        if (signal?.aborted) {
+            return {
+                ok: false,
+                error: 'Execution aborted: client disconnected before sandbox started.',
+                code: 'ABORTED',
+            };
+        }
+        // ── Step 1: Fail-fast guard ─────────────────────
+        const guard = validateSandboxCode(code);
+        if (!guard.ok) {
+            return { ok: false, error: guard.violation, code: 'INVALID_CODE' };
+        }
+        // ── Step 2: Ensure isolate is alive ─────────────
+        this._ensureIsolate();
+        const ivm = getIvm();
+        const isolate = this._isolate;
+        // ── Step 3: Wire abort kill-switch ──────────────
+        // When the signal fires, we call isolate.dispose() which
+        // immediately kills the V8 C++ threads. The _ensureIsolate()
+        // method will recreate a fresh isolate on the next call.
+        let aborted = false;
+        const onAbort = signal ? () => {
+            aborted = true;
+            try {
+                isolate.dispose();
+            }
+            catch { /* may already be dead */ }
+        } : undefined;
+        if (signal && onAbort) {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        // ── Step 4: Execute in sealed context ───────────
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let inputCopy; // ivm.ExternalCopy
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let context; // ivm.Context
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let script; // ivm.Script
+        const startMs = performance.now();
+        try {
+            // Create pristine context (NO globals injected — this IS the security)
+            context = await isolate.createContext();
+            // Deep-copy data into isolated heap (no references!)
+            inputCopy = new ivm.ExternalCopy(data);
+            await context.global.set('__input__', inputCopy.copyInto());
+            // Compile with wrapper: call the function and serialize result
+            const wrappedCode = `const __fn__ = ${code};\nJSON.stringify(__fn__(__input__));`;
+            script = await isolate.compileScript(wrappedCode);
+            // ASYNC execution — never blocks the Node.js event loop
+            const rawResult = await script.run(context, { timeout: this._timeout });
+            const executionMs = performance.now() - startMs;
+            // ── Step 5: Output size guard ───────────────
+            if (typeof rawResult === 'string' && rawResult.length > this._maxOutputBytes) {
+                return {
+                    ok: false,
+                    error: `Output size (${rawResult.length} bytes) exceeds limit (${this._maxOutputBytes} bytes). ` +
+                        'Use more selective filters to reduce the result set.',
+                    code: 'OUTPUT_TOO_LARGE',
+                };
+            }
+            // ── Step 6: Parse result ────────────────────
+            const parsed = typeof rawResult === 'string' ? JSON.parse(rawResult) : rawResult;
+            return { ok: true, value: parsed, executionMs };
+        }
+        catch (err) {
+            // If the abort listener disposed the isolate, classify as ABORTED
+            // (not MEMORY — the user disconnected, not an OOM condition)
+            if (aborted) {
+                return {
+                    ok: false,
+                    error: 'Execution aborted: client disconnected during sandbox execution.',
+                    code: 'ABORTED',
+                };
+            }
+            return this._classifyError(err);
+        }
+        finally {
+            // ── MANDATORY ABORT LISTENER CLEANUP ─────────
+            // Remove the listener to prevent memory leaks when
+            // execution completes before the signal fires.
+            if (signal && onAbort) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            // ── MANDATORY C++ POINTER RELEASE ────────────
+            // Order matters: release inner resources first.
+            // After abort-triggered dispose, these will throw
+            // but the catch blocks handle dead-isolate gracefully.
+            try {
+                inputCopy?.release();
+            }
+            catch { /* already released or isolate dead */ }
+            try {
+                script?.release();
+            }
+            catch { /* already released or isolate dead */ }
+            try {
+                context?.release();
+            }
+            catch { /* already released or isolate dead */ }
+        }
+    }
+    /**
+     * Release all resources held by this engine.
+     *
+     * After calling `dispose()`, any subsequent `execute()` calls
+     * will return `{ ok: false, code: 'UNAVAILABLE' }`.
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        try {
+            this._isolate?.dispose();
+        }
+        catch {
+            // Isolate may already be dead (OOM)
+        }
+    }
+    /**
+     * Check if the engine has been disposed.
+     */
+    get isDisposed() {
+        return this._disposed;
+    }
+    // ── Private ──────────────────────────────────────────
+    /**
+     * Ensure the isolate is alive. If it died (OOM), create a new one.
+     * @internal
+     */
+    _ensureIsolate() {
+        const ivm = getIvm();
+        // Check if isolate is still usable
+        try {
+            if (this._isolate?.isDisposed) {
+                this._isolate = new ivm.Isolate({ memoryLimit: this._memoryLimit });
+            }
+        }
+        catch {
+            // isDisposed threw → isolate is dead, recreate
+            this._isolate = new ivm.Isolate({ memoryLimit: this._memoryLimit });
+        }
+    }
+    /**
+     * Classify an error from V8 execution into a typed SandboxResult.
+     * @internal
+     */
+    _classifyError(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Timeout: isolated-vm throws a specific error
+        if (message.includes('Script execution timed out')) {
+            return {
+                ok: false,
+                error: `Script execution timed out (${this._timeout}ms). ` +
+                    'Simplify the computation or increase the timeout limit.',
+                code: 'TIMEOUT',
+            };
+        }
+        // Memory: V8 kills the isolate
+        if (message.includes('Isolate was disposed') ||
+            message.includes('out of memory') ||
+            message.includes('allocation failed')) {
+            // Mark isolate for recreation on next call
+            try {
+                this._isolate?.dispose();
+            }
+            catch { /* ignore */ }
+            return {
+                ok: false,
+                error: `Isolate ran out of memory (${this._memoryLimit}MB limit). ` +
+                    'Reduce the data size or simplify the computation.',
+                code: 'MEMORY',
+            };
+        }
+        // Syntax: V8 compilation error
+        if (message.includes('SyntaxError')) {
+            return {
+                ok: false,
+                error: `JavaScript syntax error: ${message}`,
+                code: 'SYNTAX',
+            };
+        }
+        // Runtime: any other V8 error (ReferenceError, TypeError, etc.)
+        return {
+            ok: false,
+            error: `Runtime error: ${message}`,
+            code: 'RUNTIME',
+        };
+    }
+}
+//# sourceMappingURL=SandboxEngine.js.map

package/dist/sandbox/SandboxEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEngine.js","sourceRoot":"","sources":["../../src/sandbox/SandboxEngine.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/SandboxGuard.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SandboxGuard — Fail-Fast Syntax Checker for LLM-Provided Code
+ *
+ * Provides quick feedback BEFORE sending code to the isolated-vm engine.
+ * This is NOT a security boundary — security comes from the empty V8
+ * Context (no `process`, `require`, `fs`, or `globalThis` injected).
+ *
+ * Purpose:
+ * - Validate that the code is syntactically valid JavaScript
+ * - Check that it looks like a function expression / arrow function
+ * - Provide fast, descriptive error messages to the LLM
+ *
+ * Properties:
+ * - Zero runtime dependencies (pure string analysis)
+ * - Fail-fast: rejects obviously broken code before V8 boot
+ * - NOT a security gate (LLMs can obfuscate; the Isolate is the real wall)
+ *
+ * @module
+ * @internal
+ */
+export interface GuardResult {
+    /** Whether the code passed the fail-fast check */
+    readonly ok: boolean;
+    /** Human-readable reason for rejection (present when `ok` is false) */
+    readonly violation?: string;
+}
+/**
+ * Validate LLM-provided code before sending it to the sandbox.
+ *
+ * Performs two checks:
+ * 1. **Shape check**: The code must look like a function expression
+ * 2. **Suspicious pattern check**: Fail-fast for obviously unsandboxable patterns
+ *
+ * @param code - The JavaScript code string from the LLM
+ * @returns A `GuardResult` indicating whether the code passed
+ *
+ * @example
+ * ```typescript
+ * const result = validateSandboxCode('(data) => data.filter(d => d.x > 5)');
+ * // { ok: true }
+ *
+ * const bad = validateSandboxCode('require("fs").readFileSync("/etc/passwd")');
+ * // { ok: false, violation: 'Code must be a function expression...' }
+ * ```
+ */
+export declare function validateSandboxCode(code: string): GuardResult;
+//# sourceMappingURL=SandboxGuard.d.ts.map

package/dist/sandbox/SandboxGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxGuard.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,WAAW;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC/B;AA+BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA8B7D"}