@vinkius-core/mcp-fusion 2.12.0 → 2.13.0

package/dist/index.js

@@ -11,6 +11,7 @@
  *   ├── observability/ ← Debug Observer, Tracing
  *   ├── presenter/     ← MVA View Layer
  *   ├── prompt/        ← Prompt Engine
+ *   ├── sandbox/       ← Zero-Trust V8 Computation Delegation
  *   ├── server/        ← Server Attachment
  *   ├── exposition/    ← Flat/Grouped Topology Compiler
  *   ├── state-sync/    ← Epistemic Cache-Control
@@ -95,4 +96,7 @@ export { createProbe, buildJudgePrompt, parseJudgeResponse, evaluateProbe, evalu
 export { enrichValidationError, createToolEnhancer, } from './introspection/ContractAwareSelfHealing.js';
 /** @category Governance */
 export { createGovernanceObserver, createNoopObserver, } from './introspection/GovernanceObserver.js';
+// ── Sandbox (Zero-Trust V8 Compute Delegation) ──────────
+/** @category Sandbox */
+export { SandboxEngine, validateSandboxCode, SANDBOX_SYSTEM_INSTRUCTION } from './sandbox/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/sandbox/SandboxEngine.d.ts

@@ -0,0 +1,188 @@
+/**
+ * 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
+ *
+ * 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)                            │
+ *   │    ┌──────────┐                                 │
+ *   │    │ 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) │
+ *   │    ├──────────┤                                 │
+ *   │    │ Copy Out │ JSON.parse result                │
+ *   │    └──────────┘                                 │
+ *   │                                                 │
+ *   │  finally: 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
+ */
+export type SandboxErrorCode = 'TIMEOUT' | 'MEMORY' | 'SYNTAX' | 'RUNTIME' | 'OUTPUT_TOO_LARGE' | 'INVALID_CODE' | 'UNAVAILABLE';
+/**
+ * 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)
+     *
+     * @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).
+     *
+     * @returns A `SandboxResult` with the computed value or an error.
+     */
+    execute<T = unknown>(code: string, data: unknown): 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GACtB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,kBAAkB,GAClB,cAAc,GACd,aAAa,CAAC;AAEpB;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAsElF;;;;;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,290 @@
+/**
+ * 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
+ *
+ * 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)                            │
+ *   │    ┌──────────┐                                 │
+ *   │    │ 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) │
+ *   │    ├──────────┤                                 │
+ *   │    │ Copy Out │ JSON.parse result                │
+ *   │    └──────────┘                                 │
+ *   │                                                 │
+ *   │  finally: 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)
+     *
+     * @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).
+     *
+     * @returns A `SandboxResult` with the computed value or an error.
+     */
+    async execute(code, data) {
+        if (this._disposed) {
+            return { ok: false, error: 'SandboxEngine has been disposed.', code: 'UNAVAILABLE' };
+        }
+        // ── 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: 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 4: 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 5: Parse result ────────────────────
+            const parsed = typeof rawResult === 'string' ? JSON.parse(rawResult) : rawResult;
+            return { ok: true, value: parsed, executionMs };
+        }
+        catch (err) {
+            const executionMs = performance.now() - startMs;
+            return this._classifyError(err, executionMs);
+        }
+        finally {
+            // ── MANDATORY C++ POINTER RELEASE ────────────
+            // Order matters: release inner resources first
+            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, executionMs) {
+        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"}

package/dist/sandbox/SandboxGuard.js

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+// ── Constants ────────────────────────────────────────────
+/**
+ * Patterns that indicate the code is NOT a pure function.
+ * These are fail-fast hints, not security barriers.
+ * The V8 Isolate with an empty Context is the real security wall.
+ */
+const SUSPICIOUS_PATTERNS = [
+    { pattern: /\bimport\s*\(/, reason: 'Dynamic import() is not available in the sandbox.' },
+    { pattern: /\bimport\s+/, reason: 'ES module imports are not available in the sandbox.' },
+    { pattern: /\brequire\s*\(/, reason: 'require() is not available in the sandbox.' },
+];
+/**
+ * The code must start with one of these patterns to be recognized
+ * as a function expression or arrow function.
+ */
+const FUNCTION_PATTERNS = [
+    /^\s*\(.*\)\s*=>/s, // (x) => ...
+    /^\s*[a-zA-Z_$]\w*\s*=>/, // x => ...
+    /^\s*function\s*\(/, // function(x) { ... }
+    /^\s*function\s+\w+\s*\(/, // function name(x) { ... }
+    /^\s*async\s+\(.*\)\s*=>/s, // async (x) => ...
+    /^\s*async\s+function\s*\(/, // async function(x) { ... }
+    /^\s*async\s+[a-zA-Z_$]\w*\s*=>/, // async x => ...
+];
+// ── Guard Implementation ─────────────────────────────────
+/**
+ * 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 function validateSandboxCode(code) {
+    if (!code || typeof code !== 'string') {
+        return { ok: false, violation: 'Code must be a non-empty string.' };
+    }
+    const trimmed = code.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, violation: 'Code must be a non-empty string.' };
+    }
+    // Shape check: must look like a function
+    const looksLikeFunction = FUNCTION_PATTERNS.some(p => p.test(trimmed));
+    if (!looksLikeFunction) {
+        return {
+            ok: false,
+            violation: 'Code must be a function expression or arrow function. ' +
+                'Example: (data) => data.filter(d => d.value > 10)',
+        };
+    }
+    // Suspicious pattern check (fail-fast hints, not security)
+    for (const { pattern, reason } of SUSPICIOUS_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            return { ok: false, violation: reason };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=SandboxGuard.js.map