@yarlisai/sandbox 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 YarlisAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -0,0 +1,138 @@
+# @yarlisai/sandbox
+
+Pluggable sandbox runner for executing untrusted user JavaScript. Built on a **Port/Adapter** pattern (ADR 0007). Swap between a `worker_threads` pool, an in-process eval, or any custom transport by changing one line.
+
+## Port signature
+
+```ts
+export interface SandboxRunner {
+  readonly name: string
+  execute(args: SandboxExecuteArgs): Promise<SandboxExecuteResult>
+  dispose(): Promise<void>
+}
+
+export interface SandboxClientConfig {
+  adapter: SandboxRunner
+}
+```
+
+`execute()` runs ONE piece of user code and resolves with its return value. `dispose()` tears the runner down (drain pool / close handles).
+
+## Install
+
+```bash
+bun add @yarlisai/sandbox@alpha
+```
+
+The default `node-worker` adapter relies on Node's built-in `worker_threads` and `vm` — no extra runtime deps.
+
+## Architecture
+
+```
+  Your app  ──►  SandboxClient  ──►  SandboxRunner (port)  ──►  [node-worker | memory | custom] (adapter)
+```
+
+- **`SandboxRunner`** — the port: `{ name, execute(args), dispose() }`
+- **`createSandboxClient({ adapter })`** — thin façade so callers don't reach into the adapter directly
+- **Adapters** — each implements `SandboxRunner`
+
+## Usage
+
+```ts
+import { createSandboxClient, nodeWorkerAdapter } from '@yarlisai/sandbox'
+
+// Production: pool of worker_threads, vm.Script + wall-clock kill switch.
+const sandbox = createSandboxClient({
+  adapter: nodeWorkerAdapter({ maxWorkers: 4, workerMemoryMb: 256 }),
+})
+
+const { result } = await sandbox.execute({
+  code: 'return params.a + params.b',
+  executionParams: { a: 1, b: 2 },
+  envVars: {},
+  contextVariables: {},
+  isCustomTool: false,
+  timeout: 5_000,
+  secureFetchImpl: (url, init) => fetch(url, init as RequestInit),
+  consoleSink: {
+    log: (m) => console.log(m),
+    info: (m) => console.info(m),
+    warn: (m) => console.warn(m),
+    error: (m) => console.error(m),
+  },
+})
+
+// Graceful shutdown.
+await sandbox.dispose()
+```
+
+## Message protocol
+
+The `node-worker` adapter speaks the following protocol over `postMessage`:
+
+```
+main → worker
+  { type: 'execute', execId, code, contextVariables, executionParams,
+    envVars, isCustomTool, syncTimeout }
+  { type: 'fetch_response', id, ok, status, statusText, headers, body, error? }
+
+worker → main
+  { type: 'fetch', id, url, init }      // proxied back to secureFetchImpl
+  { type: 'console', level, message }    // forwarded to consoleSink
+  { type: 'result', execId, value }
+  { type: 'error', execId, error: { name, message, stack } }
+```
+
+Both message types are exported as `SandboxMainToWorkerMessage` and `SandboxWorkerToMainMessage` for adapter authors who want to reuse the same worker source. The raw worker source is also exported as `WORKER_SOURCE`.
+
+## Security caveats
+
+- `node-worker` is **isolation, not sandboxing**: a `worker_threads` Worker shares the host filesystem, native crypto, and (without `resourceLimits`) memory. Code that bypasses `vm.runInContext` (e.g. by triggering an unhandled rejection deeper than the script) can in principle reach those surfaces. Combine with OS-level sandboxing if you accept code from anonymous users.
+- All `fetch()` calls inside the sandbox proxy back to `secureFetchImpl` on the main thread. **You must SSRF-validate every URL there** — the worker has no network restriction of its own.
+- The wall-clock timeout is enforced by `worker.terminate()` on the main thread. The `vm.Script` `timeout` option is a second kill switch; do not rely on it alone (microtask-starvation loops can outlast it).
+- The `memory` adapter has **no isolation**. It runs user code in the same process via `new Function()` for unit tests / dev loops only. Never accept untrusted input through it.
+
+## Writing a custom adapter
+
+```ts
+import type { SandboxRunner, SandboxExecuteArgs } from '@yarlisai/sandbox'
+
+export function myAdapter(): SandboxRunner {
+  return {
+    name: 'my-adapter',
+    async execute(args: SandboxExecuteArgs) {
+      // call your runtime (firecracker, gvisor, e2b, ...)
+      return { result: someValue }
+    },
+    async dispose() {
+      // optional teardown
+    },
+  }
+}
+```
+
+Drop it into `createSandboxClient({ adapter: myAdapter() })` — done.
+
+## Built-in adapters
+
+| Adapter | Factory | Transport | Use for |
+|---|---|---|---|
+| Node Worker | `nodeWorkerAdapter` | `worker_threads` pool + `vm.Script` | production |
+| Memory | `memoryAdapter` | `new Function(code)` in same process | unit tests, dev |
+
+## Build
+
+```bash
+bun install
+cd packages/sandbox
+bun run build
+```
+
+## Related
+
+- [`@yarlisai/core`](../core/README.md) — logger / env helpers used by sibling packages.
+- [ADR 0007 — Port/Adapter protocol](../../docs/architecture/decisions/0007-yarlisai-port-adapter.md) — the rules every service package follows.
+
+## License
+
+MIT

package/dist/adapters/memory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * In-memory adapter for the SandboxRunner port.
+ *
+ * Runs user code in the SAME process via `new Function()`. There is **no
+ * isolation, no resource limit, no timeout enforcement, and no SSRF gate**.
+ * Use only in unit tests / dev loops where you control the input code.
+ *
+ * Production callers should use `nodeWorkerAdapter`.
+ */
+import type { SandboxRunner } from '../types';
+export declare function memoryAdapter(): SandboxRunner;
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAA4C,aAAa,EAAE,MAAM,UAAU,CAAA;AAEvF,wBAAgB,aAAa,IAAI,aAAa,CA+B7C"}

package/dist/adapters/memory.js

@@ -0,0 +1,36 @@
+/**
+ * In-memory adapter for the SandboxRunner port.
+ *
+ * Runs user code in the SAME process via `new Function()`. There is **no
+ * isolation, no resource limit, no timeout enforcement, and no SSRF gate**.
+ * Use only in unit tests / dev loops where you control the input code.
+ *
+ * Production callers should use `nodeWorkerAdapter`.
+ */
+export function memoryAdapter() {
+    return {
+        name: 'memory',
+        async execute(args) {
+            const { code, executionParams, envVars, contextVariables, secureFetchImpl, consoleSink } = args;
+            // Build a flat ctx object. Keys collide last-write-wins, mirroring the
+            // node-worker spread order: params, envVars, contextVariables, fetch, console.
+            const ctx = {
+                params: executionParams ?? {},
+                environmentVariables: envVars ?? {},
+                ...(contextVariables ?? {}),
+                fetch: secureFetchImpl,
+                console: consoleSink,
+            };
+            // Wrap in async IIFE so user code can `await` and `return`.
+            const wrapped = `return (async () => { ${code} })()`;
+            // eslint-disable-next-line no-new-func
+            const fn = new Function('ctx', `with (ctx) { ${wrapped} }`);
+            const value = await fn(ctx);
+            return { result: value };
+        },
+        async dispose() {
+            // Nothing to tear down.
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/adapters/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,CAAC,OAAO,CAAC,IAAwB;YACpC,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,WAAW,EAAE,GACtF,IAAI,CAAA;YAEN,uEAAuE;YACvE,+EAA+E;YAC/E,MAAM,GAAG,GAA4B;gBACnC,MAAM,EAAE,eAAe,IAAI,EAAE;gBAC7B,oBAAoB,EAAE,OAAO,IAAI,EAAE;gBACnC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC;gBAC3B,KAAK,EAAE,eAAe;gBACtB,OAAO,EAAE,WAAW;aACrB,CAAA;YAED,4DAA4D;YAC5D,MAAM,OAAO,GAAG,yBAAyB,IAAI,OAAO,CAAA;YACpD,uCAAuC;YACvC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,gBAAgB,OAAO,IAAI,CAErC,CAAA;YAErB,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;YAC3B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;QAC1B,CAAC;QACD,KAAK,CAAC,OAAO;YACX,wBAAwB;QAC1B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/adapters/node-worker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Node `worker_threads` adapter for the SandboxRunner port.
+ *
+ * Architecture:
+ *  - A small pool (default 4) of reusable Workers spawned with `{ eval: true }`
+ *    pointing at WORKER_SOURCE.
+ *  - One execution per worker at a time. Concurrent calls queue.
+ *  - Wall-clock timeout enforced by `worker.terminate()` on the main thread.
+ *    A second `vm.Script` timeout inside the worker is a belt-and-braces.
+ *  - All `fetch()` calls inside the sandbox proxy back to the caller-supplied
+ *    `secureFetchImpl` over postMessage so SSRF / authn checks can run on the
+ *    main thread.
+ *
+ * No external deps — `worker_threads` and `vm` are built into Node.
+ */
+import type { NodeWorkerAdapterConfig, SandboxRunner } from '../types';
+/**
+ * Construct a worker-pool-backed `SandboxRunner`.
+ *
+ * The returned runner owns its own pool. Call `dispose()` to drain it (e.g.
+ * between integration tests or on graceful shutdown).
+ */
+export declare function nodeWorkerAdapter(config?: NodeWorkerAdapterConfig): SandboxRunner;
+//# sourceMappingURL=node-worker.d.ts.map

package/dist/adapters/node-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-worker.d.ts","sourceRoot":"","sources":["../../src/adapters/node-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAEV,uBAAuB,EAGvB,aAAa,EAEd,MAAM,UAAU,CAAA;AAmHjB;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,uBAA4B,GAAG,aAAa,CAkJrF"}

package/dist/adapters/node-worker.js

@@ -0,0 +1,304 @@
+/**
+ * Node `worker_threads` adapter for the SandboxRunner port.
+ *
+ * Architecture:
+ *  - A small pool (default 4) of reusable Workers spawned with `{ eval: true }`
+ *    pointing at WORKER_SOURCE.
+ *  - One execution per worker at a time. Concurrent calls queue.
+ *  - Wall-clock timeout enforced by `worker.terminate()` on the main thread.
+ *    A second `vm.Script` timeout inside the worker is a belt-and-braces.
+ *  - All `fetch()` calls inside the sandbox proxy back to the caller-supplied
+ *    `secureFetchImpl` over postMessage so SSRF / authn checks can run on the
+ *    main thread.
+ *
+ * No external deps — `worker_threads` and `vm` are built into Node.
+ */
+import { Worker } from 'worker_threads';
+import { SandboxTimeoutError } from '../types';
+import { WORKER_SOURCE } from './worker-source';
+const DEFAULT_MAX_WORKERS = 4;
+const DEFAULT_WORKER_MEMORY_MB = 256;
+class WorkerPool {
+    maxWorkers;
+    workerMemoryMb;
+    workers = [];
+    waiters = [];
+    constructor(maxWorkers, workerMemoryMb) {
+        this.maxWorkers = maxWorkers;
+        this.workerMemoryMb = workerMemoryMb;
+    }
+    size() {
+        return this.workers.length;
+    }
+    acquire() {
+        return new Promise((resolve, reject) => {
+            const idle = this.workers.find((w) => !w.busy);
+            if (idle) {
+                idle.busy = true;
+                resolve(idle);
+                return;
+            }
+            if (this.workers.length < this.maxWorkers) {
+                try {
+                    const pooled = this.spawn();
+                    pooled.busy = true;
+                    resolve(pooled);
+                }
+                catch (err) {
+                    reject(err);
+                }
+                return;
+            }
+            this.waiters.push((pooled) => {
+                pooled.busy = true;
+                resolve(pooled);
+            });
+        });
+    }
+    release(pooled) {
+        pooled.busy = false;
+        const next = this.waiters.shift();
+        if (next) {
+            next(pooled);
+        }
+    }
+    retire(pooled) {
+        const idx = this.workers.indexOf(pooled);
+        if (idx >= 0)
+            this.workers.splice(idx, 1);
+        if (this.waiters.length > 0 && this.workers.length < this.maxWorkers) {
+            try {
+                const pooledNew = this.spawn();
+                const waiter = this.waiters.shift();
+                if (waiter) {
+                    pooledNew.busy = true;
+                    waiter(pooledNew);
+                }
+            }
+            catch {
+                // Best-effort. Waiters reject on their own timeout in the caller.
+            }
+        }
+    }
+    async drain() {
+        const workers = this.workers.slice();
+        this.workers = [];
+        this.waiters = [];
+        await Promise.all(workers.map((p) => p.worker.terminate().catch(() => {
+            /* swallow */
+        })));
+    }
+    spawn() {
+        const worker = new Worker(WORKER_SOURCE, {
+            eval: true,
+            resourceLimits: {
+                maxOldGenerationSizeMb: this.workerMemoryMb,
+            },
+        });
+        const pooled = { worker, busy: false };
+        this.workers.push(pooled);
+        worker.once('exit', () => {
+            this.retire(pooled);
+        });
+        worker.on('error', () => {
+            this.retire(pooled);
+        });
+        return pooled;
+    }
+}
+/**
+ * Construct a worker-pool-backed `SandboxRunner`.
+ *
+ * The returned runner owns its own pool. Call `dispose()` to drain it (e.g.
+ * between integration tests or on graceful shutdown).
+ */
+export function nodeWorkerAdapter(config = {}) {
+    const pool = new WorkerPool(config.maxWorkers ?? DEFAULT_MAX_WORKERS, config.workerMemoryMb ?? DEFAULT_WORKER_MEMORY_MB);
+    let nextExecId = 1;
+    return {
+        name: 'node-worker',
+        async execute(args) {
+            const { code, executionParams, envVars, contextVariables, isCustomTool, timeout, secureFetchImpl, consoleSink, } = args;
+            const pooled = await pool.acquire();
+            const worker = pooled.worker;
+            const execId = nextExecId++;
+            let timer = null;
+            let settled = false;
+            let terminated = false;
+            return new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    if (timer) {
+                        clearTimeout(timer);
+                        timer = null;
+                    }
+                    worker.off('message', onMessage);
+                    worker.off('error', onError);
+                    worker.off('exit', onExit);
+                };
+                const settleSuccess = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    pool.release(pooled);
+                    resolve({ result: value });
+                };
+                const settleFailure = (err, kill) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    if (kill) {
+                        terminated = true;
+                        worker.terminate().catch(() => {
+                            /* already gone */
+                        });
+                        pool.retire(pooled);
+                    }
+                    else {
+                        pool.release(pooled);
+                    }
+                    reject(err);
+                };
+                const onMessage = (msg) => {
+                    if (!msg || typeof msg !== 'object')
+                        return;
+                    switch (msg.type) {
+                        case 'console': {
+                            const level = msg.level;
+                            const sink = consoleSink[level] ?? consoleSink.log;
+                            try {
+                                sink(String(msg.message ?? ''));
+                            }
+                            catch {
+                                /* sink failures must not break execution */
+                            }
+                            return;
+                        }
+                        case 'fetch': {
+                            handleFetchRpc(worker, msg, secureFetchImpl);
+                            return;
+                        }
+                        case 'result': {
+                            if (msg.execId !== execId)
+                                return;
+                            settleSuccess(msg.value);
+                            return;
+                        }
+                        case 'error': {
+                            if (msg.execId !== execId)
+                                return;
+                            const e = new Error(msg.error?.message ?? 'Function execution failed');
+                            if (msg.error?.name)
+                                e.name = msg.error.name;
+                            if (msg.error?.stack)
+                                e.stack = msg.error.stack;
+                            settleFailure(e, false);
+                            return;
+                        }
+                    }
+                };
+                const onError = (err) => {
+                    settleFailure(err, true);
+                };
+                const onExit = (_code) => {
+                    if (settled)
+                        return;
+                    // Worker died unexpectedly. If we initiated termination, `settled`
+                    // is normally already true by the time this fires.
+                    const reason = terminated
+                        ? new SandboxTimeoutError(timeout)
+                        : new Error('Function worker exited unexpectedly');
+                    settleFailure(reason, false);
+                };
+                worker.on('message', onMessage);
+                worker.on('error', onError);
+                worker.on('exit', onExit);
+                timer = setTimeout(() => {
+                    settleFailure(new SandboxTimeoutError(timeout), true);
+                }, timeout);
+                try {
+                    worker.postMessage({
+                        type: 'execute',
+                        execId,
+                        code,
+                        contextVariables,
+                        executionParams,
+                        envVars,
+                        isCustomTool,
+                        syncTimeout: timeout,
+                    });
+                }
+                catch (err) {
+                    settleFailure(err, true);
+                }
+            });
+        },
+        async dispose() {
+            await pool.drain();
+        },
+    };
+}
+async function handleFetchRpc(worker, msg, secureFetchImpl) {
+    const { id, url, init } = msg;
+    try {
+        const res = (await secureFetchImpl(url, init));
+        let bodyText = null;
+        let status = 200;
+        let statusText = 'OK';
+        let ok = true;
+        const headersOut = {};
+        let outUrl = url;
+        if (res && typeof res === 'object') {
+            if (typeof res.status === 'number')
+                status = res.status;
+            if (typeof res.statusText === 'string')
+                statusText = res.statusText;
+            if (typeof res.ok === 'boolean')
+                ok = res.ok;
+            else
+                ok = status >= 200 && status < 300;
+            if (typeof res.url === 'string')
+                outUrl = res.url;
+            if (res.headers && typeof res.headers.entries === 'function') {
+                for (const [k, v] of res.headers.entries()) {
+                    headersOut[String(k).toLowerCase()] = String(v);
+                }
+            }
+            else if (res.headers && typeof res.headers === 'object') {
+                for (const [k, v] of Object.entries(res.headers)) {
+                    headersOut[String(k).toLowerCase()] = String(v);
+                }
+            }
+            if (typeof res.text === 'function') {
+                try {
+                    bodyText = await res.text();
+                }
+                catch {
+                    bodyText = null;
+                }
+            }
+            else if (typeof res === 'string') {
+                bodyText = res;
+            }
+        }
+        worker.postMessage({
+            type: 'fetch_response',
+            id,
+            ok,
+            status,
+            statusText,
+            headers: headersOut,
+            body: bodyText,
+            url: outUrl,
+        });
+    }
+    catch (err) {
+        worker.postMessage({
+            type: 'fetch_response',
+            id,
+            error: { name: err?.name ?? 'Error', message: err?.message ?? String(err) },
+        });
+    }
+}
+//# sourceMappingURL=node-worker.js.map

package/dist/adapters/node-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-worker.js","sourceRoot":"","sources":["../../src/adapters/node-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AASvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/C,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAC7B,MAAM,wBAAwB,GAAG,GAAG,CAAA;AASpC,MAAM,UAAU;IAKK;IACA;IALX,OAAO,GAAmB,EAAE,CAAA;IAC5B,OAAO,GAAa,EAAE,CAAA;IAE9B,YACmB,UAAkB,EAClB,cAAsB;QADtB,eAAU,GAAV,UAAU,CAAQ;QAClB,mBAAc,GAAd,cAAc,CAAQ;IACtC,CAAC;IAEJ,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAA;IAC5B,CAAC;IAED,OAAO;QACL,OAAO,IAAI,OAAO,CAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YAC9C,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;gBAChB,OAAO,CAAC,IAAI,CAAC,CAAA;gBACb,OAAM;YACR,CAAC;YAED,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC1C,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAA;oBAC3B,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;oBAClB,OAAO,CAAC,MAAM,CAAC,CAAA;gBACjB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,CAAC,GAAY,CAAC,CAAA;gBACtB,CAAC;gBACD,OAAM;YACR,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;gBAC3B,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;gBAClB,OAAO,CAAC,MAAM,CAAC,CAAA;YACjB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,CAAC,MAAoB;QAC1B,MAAM,CAAC,IAAI,GAAG,KAAK,CAAA;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACjC,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,MAAM,CAAC,CAAA;QACd,CAAC;IACH,CAAC;IAED,MAAM,CAAC,MAAoB;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,GAAG,IAAI,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAEzC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACrE,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAA;gBAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;gBACnC,IAAI,MAAM,EAAE,CAAC;oBACX,SAAS,CAAC,IAAI,GAAG,IAAI,CAAA;oBACrB,MAAM,CAAC,SAAS,CAAC,CAAA;gBACnB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;YACpE,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAChB,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;YAC9B,aAAa;QACf,CAAC,CAAC,CACH,CACF,CAAA;IACH,CAAC;IAEO,KAAK;QACX,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,aAAa,EAAE;YACvC,IAAI,EAAE,IAAI;YACV,cAAc,EAAE;gBACd,sBAAsB,EAAE,IAAI,CAAC,cAAc;aAC5C;SACF,CAAC,CAAA;QAEF,MAAM,MAAM,GAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;QACpD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAEzB,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;YACvB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;QACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;QAEF,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAkC,EAAE;IACpE,MAAM,IAAI,GAAG,IAAI,UAAU,CACzB,MAAM,CAAC,UAAU,IAAI,mBAAmB,EACxC,MAAM,CAAC,cAAc,IAAI,wBAAwB,CAClD,CAAA;IAED,IAAI,UAAU,GAAG,CAAC,CAAA;IAElB,OAAO;QACL,IAAI,EAAE,aAAa;QAEnB,KAAK,CAAC,OAAO,CAAC,IAAwB;YACpC,MAAM,EACJ,IAAI,EACJ,eAAe,EACf,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,eAAe,EACf,WAAW,GACZ,GAAG,IAAI,CAAA;YAER,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;YACnC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;YAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;YAE3B,IAAI,KAAK,GAAyC,IAAI,CAAA;YACtD,IAAI,OAAO,GAAG,KAAK,CAAA;YACnB,IAAI,UAAU,GAAG,KAAK,CAAA;YAEtB,OAAO,IAAI,OAAO,CAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC3D,MAAM,OAAO,GAAG,GAAG,EAAE;oBACnB,IAAI,KAAK,EAAE,CAAC;wBACV,YAAY,CAAC,KAAK,CAAC,CAAA;wBACnB,KAAK,GAAG,IAAI,CAAA;oBACd,CAAC;oBACD,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;oBAChC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;oBAC5B,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;gBAC5B,CAAC,CAAA;gBAED,MAAM,aAAa,GAAG,CAAC,KAAc,EAAE,EAAE;oBACvC,IAAI,OAAO;wBAAE,OAAM;oBACnB,OAAO,GAAG,IAAI,CAAA;oBACd,OAAO,EAAE,CAAA;oBACT,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;oBACpB,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;gBAC5B,CAAC,CAAA;gBAED,MAAM,aAAa,GAAG,CAAC,GAAU,EAAE,IAAa,EAAE,EAAE;oBAClD,IAAI,OAAO;wBAAE,OAAM;oBACnB,OAAO,GAAG,IAAI,CAAA;oBACd,OAAO,EAAE,CAAA;oBACT,IAAI,IAAI,EAAE,CAAC;wBACT,UAAU,GAAG,IAAI,CAAA;wBACjB,MAAM,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;4BAC5B,kBAAkB;wBACpB,CAAC,CAAC,CAAA;wBACF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;oBACrB,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;oBACtB,CAAC;oBACD,MAAM,CAAC,GAAG,CAAC,CAAA;gBACb,CAAC,CAAA;gBAED,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAE,EAAE;oBAC7B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;wBAAE,OAAM;oBAE3C,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;wBACjB,KAAK,SAAS,CAAC,CAAC,CAAC;4BACf,MAAM,KAAK,GAAG,GAAG,CAAC,KAA0B,CAAA;4BAC5C,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,GAAG,CAAA;4BAClD,IAAI,CAAC;gCACH,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAA;4BACjC,CAAC;4BAAC,MAAM,CAAC;gCACP,4CAA4C;4BAC9C,CAAC;4BACD,OAAM;wBACR,CAAC;wBAED,KAAK,OAAO,CAAC,CAAC,CAAC;4BACb,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,eAAe,CAAC,CAAA;4BAC5C,OAAM;wBACR,CAAC;wBAED,KAAK,QAAQ,CAAC,CAAC,CAAC;4BACd,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;gCAAE,OAAM;4BACjC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;4BACxB,OAAM;wBACR,CAAC;wBAED,KAAK,OAAO,CAAC,CAAC,CAAC;4BACb,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM;gCAAE,OAAM;4BACjC,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,IAAI,2BAA2B,CAAC,CAAA;4BACtE,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI;gCAAE,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAA;4BAC5C,IAAI,GAAG,CAAC,KAAK,EAAE,KAAK;gCAAE,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAA;4BAC/C,aAAa,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;4BACvB,OAAM;wBACR,CAAC;oBACH,CAAC;gBACH,CAAC,CAAA;gBAED,MAAM,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;oBAC7B,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;gBAC1B,CAAC,CAAA;gBAED,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE;oBAC/B,IAAI,OAAO;wBAAE,OAAM;oBACnB,mEAAmE;oBACnE,mDAAmD;oBACnD,MAAM,MAAM,GAAG,UAAU;wBACvB,CAAC,CAAC,IAAI,mBAAmB,CAAC,OAAO,CAAC;wBAClC,CAAC,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;oBACpD,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;gBAC9B,CAAC,CAAA;gBAED,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;gBAC/B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;gBAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;gBAEzB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBACtB,aAAa,CAAC,IAAI,mBAAmB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAA;gBACvD,CAAC,EAAE,OAAO,CAAC,CAAA;gBAEX,IAAI,CAAC;oBACH,MAAM,CAAC,WAAW,CAAC;wBACjB,IAAI,EAAE,SAAS;wBACf,MAAM;wBACN,IAAI;wBACJ,gBAAgB;wBAChB,eAAe;wBACf,OAAO;wBACP,YAAY;wBACZ,WAAW,EAAE,OAAO;qBACrB,CAAC,CAAA;gBACJ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,aAAa,CAAC,GAAY,EAAE,IAAI,CAAC,CAAA;gBACnC,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,KAAK,CAAC,OAAO;YACX,MAAM,IAAI,CAAC,KAAK,EAAE,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,MAAc,EACd,GAA4C,EAC5C,eAAgC;IAEhC,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,CAAA;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,CAAQ,CAAA;QAErD,IAAI,QAAQ,GAAkB,IAAI,CAAA;QAClC,IAAI,MAAM,GAAG,GAAG,CAAA;QAChB,IAAI,UAAU,GAAG,IAAI,CAAA;QACrB,IAAI,EAAE,GAAG,IAAI,CAAA;QACb,MAAM,UAAU,GAA2B,EAAE,CAAA;QAC7C,IAAI,MAAM,GAAG,GAAG,CAAA;QAEhB,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;gBAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAA;YACvD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;gBAAE,UAAU,GAAG,GAAG,CAAC,UAAU,CAAA;YACnE,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,SAAS;gBAAE,EAAE,GAAG,GAAG,CAAC,EAAE,CAAA;;gBACvC,EAAE,GAAG,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,CAAA;YACvC,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ;gBAAE,MAAM,GAAG,GAAG,CAAC,GAAG,CAAA;YAEjD,IAAI,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBAC7D,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;oBAC3C,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;gBACjD,CAAC;YACH,CAAC;iBAAM,IAAI,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC1D,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBACjD,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;gBACjD,CAAC;YACH,CAAC;YAED,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;gBAC7B,CAAC;gBAAC,MAAM,CAAC;oBACP,QAAQ,GAAG,IAAI,CAAA;gBACjB,CAAC;YACH,CAAC;iBAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBACnC,QAAQ,GAAG,GAAG,CAAA;YAChB,CAAC;QACH,CAAC;QAED,MAAM,CAAC,WAAW,CAAC;YACjB,IAAI,EAAE,gBAAgB;YACtB,EAAE;YACF,EAAE;YACF,MAAM;YACN,UAAU;YACV,OAAO,EAAE,UAAU;YACnB,IAAI,EAAE,QAAQ;YACd,GAAG,EAAE,MAAM;SACZ,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,CAAC,WAAW,CAAC;YACjB,IAAI,EAAE,gBAAgB;YACtB,EAAE;YACF,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE;SAC5E,CAAC,CAAA;IACJ,CAAC;AACH,CAAC"}

package/dist/adapters/worker-source.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Worker source for the Function-block sandbox.
+ *
+ * This file exports a string literal containing the JS source that runs in a
+ * `worker_threads` Worker (spawned with `{ eval: true }`). The string is
+ * intentionally self-contained — no `require` of TS-only modules, no
+ * cross-package imports — because it is parsed and executed by Node directly
+ * inside the worker. Loading via `eval: true` instead of a file path avoids
+ * Next.js bundling / `import.meta.url` resolution issues in the API route.
+ *
+ * Wire format (postMessage payloads):
+ *
+ *   main → worker:
+ *     { type: 'execute', execId, code, contextVariables, executionParams,
+ *       envVars, isCustomTool, syncTimeout }
+ *     { type: 'fetch_response', id, ok, status, statusText, headers, body, error? }
+ *
+ *   worker → main:
+ *     { type: 'fetch', id, url, init }
+ *     { type: 'console', level, message }
+ *     { type: 'result', execId, value }
+ *     { type: 'error', execId, error: { name, message, stack } }
+ *
+ * Each Worker handles ONE execution at a time. The pool serialises calls.
+ */
+export declare const WORKER_SOURCE: string;
+//# sourceMappingURL=worker-source.d.ts.map

package/dist/adapters/worker-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-source.d.ts","sourceRoot":"","sources":["../../src/adapters/worker-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,aAAa,QA4MzB,CAAA"}

package/dist/adapters/worker-source.js

@@ -0,0 +1,231 @@
+/**
+ * Worker source for the Function-block sandbox.
+ *
+ * This file exports a string literal containing the JS source that runs in a
+ * `worker_threads` Worker (spawned with `{ eval: true }`). The string is
+ * intentionally self-contained — no `require` of TS-only modules, no
+ * cross-package imports — because it is parsed and executed by Node directly
+ * inside the worker. Loading via `eval: true` instead of a file path avoids
+ * Next.js bundling / `import.meta.url` resolution issues in the API route.
+ *
+ * Wire format (postMessage payloads):
+ *
+ *   main → worker:
+ *     { type: 'execute', execId, code, contextVariables, executionParams,
+ *       envVars, isCustomTool, syncTimeout }
+ *     { type: 'fetch_response', id, ok, status, statusText, headers, body, error? }
+ *
+ *   worker → main:
+ *     { type: 'fetch', id, url, init }
+ *     { type: 'console', level, message }
+ *     { type: 'result', execId, value }
+ *     { type: 'error', execId, error: { name, message, stack } }
+ *
+ * Each Worker handles ONE execution at a time. The pool serialises calls.
+ */
+export const WORKER_SOURCE = String.raw `
+'use strict';
+
+const { parentPort } = require('worker_threads');
+const vm = require('vm');
+
+if (!parentPort) {
+  throw new Error('sandbox-worker must be spawned via worker_threads with a parentPort');
+}
+
+// Track in-flight fetch RPCs so we can settle them when main posts back.
+let nextFetchId = 1;
+const pendingFetches = new Map();
+
+function sendToParent(msg) {
+  try {
+    parentPort.postMessage(msg);
+  } catch (err) {
+    // Last resort — main is gone; nothing we can do from inside the worker.
+  }
+}
+
+function makeSecureFetch() {
+  return function secureFetch(input, init) {
+    const id = nextFetchId++;
+    const url = typeof input === 'string' ? input : (input && input.url) || input;
+
+    let initSerialisable;
+    if (init && typeof init === 'object') {
+      initSerialisable = {};
+      // Only forward the fields we know how to serialise across MessageChannel.
+      if (init.method) initSerialisable.method = init.method;
+      if (init.headers) {
+        // Headers might be a Headers instance, plain object, or [k,v][] array.
+        if (typeof init.headers.entries === 'function') {
+          const h = {};
+          for (const [k, v] of init.headers.entries()) h[k] = v;
+          initSerialisable.headers = h;
+        } else {
+          initSerialisable.headers = init.headers;
+        }
+      }
+      if (typeof init.body !== 'undefined') {
+        // Strings and JSON-serialisable objects only. Streams/blobs would
+        // throw on postMessage anyway.
+        initSerialisable.body = init.body;
+      }
+      if (init.redirect) initSerialisable.redirect = init.redirect;
+    }
+
+    return new Promise((resolve, reject) => {
+      pendingFetches.set(id, { resolve, reject });
+      sendToParent({ type: 'fetch', id, url, init: initSerialisable });
+    });
+  };
+}
+
+function makeConsole() {
+  function fwd(level) {
+    return function () {
+      const args = Array.prototype.slice.call(arguments);
+      const message = args
+        .map((a) => {
+          if (typeof a === 'string') return a;
+          try {
+            return JSON.stringify(a);
+          } catch {
+            return String(a);
+          }
+        })
+        .join(' ');
+      sendToParent({ type: 'console', level, message });
+    };
+  }
+  return {
+    log: fwd('log'),
+    info: fwd('info'),
+    warn: fwd('warn'),
+    error: fwd('error'),
+    debug: fwd('log'),
+  };
+}
+
+function buildScript({ code, isCustomTool, executionParams }) {
+  const wrapperLines = ['(async () => {', '  try {'];
+  if (isCustomTool) {
+    wrapperLines.push('    // For custom tools, make parameters directly accessible');
+    for (const key of Object.keys(executionParams || {})) {
+      wrapperLines.push('    const ' + key + ' = params.' + key + ';');
+    }
+  }
+  const userCodeStartLine = wrapperLines.length + 1;
+  const fullScript = [
+    ...wrapperLines,
+    '    ' + (code || '').split('\n').join('\n    '),
+    '  } catch (error) {',
+    '    console.error(error);',
+    '    throw error;',
+    '  }',
+    '})()',
+  ].join('\n');
+  return { fullScript, userCodeStartLine };
+}
+
+async function runOne(msg) {
+  const {
+    execId,
+    code,
+    contextVariables,
+    executionParams,
+    envVars,
+    isCustomTool,
+    syncTimeout,
+  } = msg;
+
+  try {
+    const ctx = vm.createContext({
+      params: executionParams || {},
+      environmentVariables: envVars || {},
+      ...(contextVariables || {}),
+      fetch: makeSecureFetch(),
+      console: makeConsole(),
+      // Surface a few harmless globals that user code may reach for.
+      setTimeout,
+      clearTimeout,
+      setInterval,
+      clearInterval,
+      Buffer,
+      URL,
+      URLSearchParams,
+      TextEncoder,
+      TextDecoder,
+    });
+
+    const { fullScript } = buildScript({ code, isCustomTool, executionParams });
+    const script = new vm.Script(fullScript, { filename: 'user-function.js' });
+
+    // The sync timeout stays armed inside the worker as a SECOND kill switch.
+    // The main thread also enforces a wall-clock timeout via worker.terminate().
+    // We cap the script-level timeout at the requested syncTimeout value so we
+    // do not undershoot the wall-clock deadline.
+    const result = await script.runInContext(ctx, {
+      timeout: typeof syncTimeout === 'number' && syncTimeout > 0 ? syncTimeout : 30000,
+      displayErrors: true,
+      breakOnSigint: true,
+    });
+
+    sendToParent({ type: 'result', execId, value: result });
+  } catch (err) {
+    const error = {
+      name: (err && err.name) || 'Error',
+      message: (err && err.message) || String(err),
+      stack: err && err.stack,
+    };
+    sendToParent({ type: 'error', execId, error });
+  }
+}
+
+parentPort.on('message', (msg) => {
+  if (!msg || typeof msg !== 'object') return;
+  if (msg.type === 'execute') {
+    runOne(msg);
+    return;
+  }
+  if (msg.type === 'fetch_response') {
+    const pending = pendingFetches.get(msg.id);
+    if (!pending) return;
+    pendingFetches.delete(msg.id);
+    if (msg.error) {
+      const err = new Error(msg.error.message || 'fetch failed');
+      if (msg.error.name) err.name = msg.error.name;
+      pending.reject(err);
+      return;
+    }
+    // Reconstruct a Response-shaped object that user code can interact with.
+    const headers = msg.headers || {};
+    const body = msg.body;
+    const response = {
+      ok: !!msg.ok,
+      status: msg.status,
+      statusText: msg.statusText,
+      headers: {
+        get: (name) => headers[String(name).toLowerCase()] ?? null,
+        entries: () => Object.entries(headers),
+        forEach: (cb) => {
+          for (const [k, v] of Object.entries(headers)) cb(v, k);
+        },
+      },
+      url: msg.url,
+      text: () => Promise.resolve(typeof body === 'string' ? body : JSON.stringify(body ?? '')),
+      json: () =>
+        Promise.resolve(
+          typeof body === 'string' ? (body ? JSON.parse(body) : null) : body
+        ),
+      arrayBuffer: () =>
+        Promise.resolve(
+          typeof body === 'string'
+            ? new TextEncoder().encode(body).buffer
+            : new TextEncoder().encode(JSON.stringify(body ?? '')).buffer
+        ),
+    };
+    pending.resolve(response);
+  }
+});
+`;
+//# sourceMappingURL=worker-source.js.map

package/dist/adapters/worker-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-source.js","sourceRoot":"","sources":["../../src/adapters/worker-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4MtC,CAAA"}

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import type { SandboxClient, SandboxClientConfig } from './types';
+/**
+ * Create a provider-agnostic sandbox client.
+ *
+ * @example
+ * ```ts
+ * import { createSandboxClient, nodeWorkerAdapter } from '@yarlisai/sandbox'
+ *
+ * const sandbox = createSandboxClient({
+ *   adapter: nodeWorkerAdapter({ maxWorkers: 4 }),
+ * })
+ *
+ * const { result } = await sandbox.execute({
+ *   code: 'return params.a + params.b',
+ *   executionParams: { a: 1, b: 2 },
+ *   envVars: {},
+ *   contextVariables: {},
+ *   isCustomTool: false,
+ *   timeout: 5000,
+ *   secureFetchImpl: (url, init) => fetch(url, init),
+ *   consoleSink: {
+ *     log: (m) => console.log(m),
+ *     info: (m) => console.info(m),
+ *     warn: (m) => console.warn(m),
+ *     error: (m) => console.error(m),
+ *   },
+ * })
+ * ```
+ *
+ * Swap adapters by changing only the `adapter` field — `nodeWorkerAdapter`
+ * for production, `memoryAdapter` for tests, or roll your own. All implement
+ * the same `SandboxRunner` port.
+ */
+export declare function createSandboxClient(config: SandboxClientConfig): SandboxClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EAGpB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAY9E"}

package/dist/client.js

@@ -0,0 +1,46 @@
+/**
+ * Create a provider-agnostic sandbox client.
+ *
+ * @example
+ * ```ts
+ * import { createSandboxClient, nodeWorkerAdapter } from '@yarlisai/sandbox'
+ *
+ * const sandbox = createSandboxClient({
+ *   adapter: nodeWorkerAdapter({ maxWorkers: 4 }),
+ * })
+ *
+ * const { result } = await sandbox.execute({
+ *   code: 'return params.a + params.b',
+ *   executionParams: { a: 1, b: 2 },
+ *   envVars: {},
+ *   contextVariables: {},
+ *   isCustomTool: false,
+ *   timeout: 5000,
+ *   secureFetchImpl: (url, init) => fetch(url, init),
+ *   consoleSink: {
+ *     log: (m) => console.log(m),
+ *     info: (m) => console.info(m),
+ *     warn: (m) => console.warn(m),
+ *     error: (m) => console.error(m),
+ *   },
+ * })
+ * ```
+ *
+ * Swap adapters by changing only the `adapter` field — `nodeWorkerAdapter`
+ * for production, `memoryAdapter` for tests, or roll your own. All implement
+ * the same `SandboxRunner` port.
+ */
+export function createSandboxClient(config) {
+    return {
+        execute(args) {
+            return config.adapter.execute(args);
+        },
+        dispose() {
+            return config.adapter.dispose();
+        },
+        get adapter() {
+            return config.adapter.name;
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA2B;IAC7D,OAAO;QACL,OAAO,CAAC,IAAwB;YAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QACrC,CAAC;QACD,OAAO;YACL,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAA;QACjC,CAAC;QACD,IAAI,OAAO;YACT,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAA;QAC5B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { memoryAdapter } from './adapters/memory';
+export { nodeWorkerAdapter } from './adapters/node-worker';
+export { WORKER_SOURCE } from './adapters/worker-source';
+export { createSandboxClient } from './client';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,cAAc,SAAS,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// @yarlisai/sandbox — pluggable sandbox runner for executing untrusted JS code.
+//
+// Add a new adapter: implement `SandboxRunner` (see types.ts) and export a factory.
+export { memoryAdapter } from './adapters/memory';
+// First-party adapters
+export { nodeWorkerAdapter } from './adapters/node-worker';
+// Re-exported for adapter authors who want to embed the same worker source.
+export { WORKER_SOURCE } from './adapters/worker-source';
+export { createSandboxClient } from './client';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,oFAAoF;AAEpF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,uBAAuB;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,cAAc,SAAS,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @yarlisai/sandbox — port for executing untrusted JS code in isolation.
+ *
+ * Adapters (`node-worker`, `memory`, custom) implement `SandboxRunner`. Callers
+ * use `createSandboxClient({ adapter })` and never see the underlying transport.
+ *
+ * The default `node-worker` adapter spawns a small pool of `worker_threads`
+ * Workers and runs each piece of user code inside `vm.Script.runInContext`
+ * with a wall-clock kill switch. The `memory` adapter runs code synchronously
+ * in the parent process — no isolation, intended for unit tests / dev loops.
+ */
+/** Console output forwarded out of the sandbox to the caller. */
+export interface ConsoleSink {
+    log: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+}
+/**
+ * Caller-supplied fetch implementation. The sandbox cannot make network calls
+ * directly — all `fetch()` invocations inside the sandbox proxy back to this
+ * function on the main thread, where workspace-scoped headers / SSRF guards
+ * can be applied before the request leaves the box.
+ */
+export type SecureFetchImpl = (url: string, init?: unknown) => Promise<Response> | Promise<unknown>;
+/** Arguments for a single `execute()` call. */
+export interface SandboxExecuteArgs {
+    /** Raw user code (JavaScript). The sandbox wraps this in an async IIFE. */
+    code: string;
+    /** Parameters made available to the script as `params.<name>`. */
+    executionParams: Record<string, unknown>;
+    /** Available to the script as `environmentVariables.<name>`. */
+    envVars: Record<string, unknown>;
+    /** Free-form context variables spread into the VM context. */
+    contextVariables: Record<string, unknown>;
+    /**
+     * If true, the wrapper destructures `executionParams` into top-level
+     * `const`s before user code runs (custom-tool ergonomics).
+     */
+    isCustomTool: boolean;
+    /** Wall-clock + in-VM timeout in milliseconds. */
+    timeout: number;
+    /** Main-thread fetch impl (SSRF / authn / quota gate). */
+    secureFetchImpl: SecureFetchImpl;
+    /** Sink for forwarded `console.*` output. */
+    consoleSink: ConsoleSink;
+}
+export interface SandboxExecuteResult {
+    /** The awaited return value of the user code. */
+    result: unknown;
+}
+/**
+ * Port: any sandbox adapter must implement this.
+ * - `execute()` runs ONE piece of user code and resolves with its return value.
+ * - `dispose()` tears the runner down (drain pool / close handles). Idempotent.
+ */
+export interface SandboxRunner {
+    readonly name: string;
+    execute(args: SandboxExecuteArgs): Promise<SandboxExecuteResult>;
+    dispose(): Promise<void>;
+}
+/** Configuration for the worker-pool adapter. */
+export interface NodeWorkerAdapterConfig {
+    /** Maximum live workers. Defaults to 4. */
+    maxWorkers?: number;
+    /** Per-worker `maxOldGenerationSizeMb`. Defaults to 256. */
+    workerMemoryMb?: number;
+}
+/** `createSandboxClient` config. */
+export interface SandboxClientConfig {
+    adapter: SandboxRunner;
+}
+/** Public client surface returned by `createSandboxClient`. */
+export interface SandboxClient {
+    execute(args: SandboxExecuteArgs): Promise<SandboxExecuteResult>;
+    dispose(): Promise<void>;
+    readonly adapter: string;
+}
+export type SandboxMainToWorkerMessage = {
+    type: 'execute';
+    execId: number;
+    code: string;
+    contextVariables: Record<string, unknown>;
+    executionParams: Record<string, unknown>;
+    envVars: Record<string, unknown>;
+    isCustomTool: boolean;
+    syncTimeout: number;
+} | {
+    type: 'fetch_response';
+    id: number;
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    body?: string | null;
+    url?: string;
+    error?: {
+        name?: string;
+        message?: string;
+    };
+};
+export type SandboxWorkerToMainMessage = {
+    type: 'fetch';
+    id: number;
+    url: string;
+    init?: unknown;
+} | {
+    type: 'console';
+    level: 'log' | 'info' | 'warn' | 'error';
+    message: string;
+} | {
+    type: 'result';
+    execId: number;
+    value: unknown;
+} | {
+    type: 'error';
+    execId: number;
+    error: {
+        name?: string;
+        message?: string;
+        stack?: string;
+    };
+};
+/**
+ * Reasons surfaced by the `node-worker` adapter when the wall-clock timeout
+ * fires. The `name` is preserved so existing matchers in apps continue to
+ * recognise the error.
+ */
+export declare class SandboxTimeoutError extends Error {
+    constructor(timeout: number);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,26 @@
+/**
+ * @yarlisai/sandbox — port for executing untrusted JS code in isolation.
+ *
+ * Adapters (`node-worker`, `memory`, custom) implement `SandboxRunner`. Callers
+ * use `createSandboxClient({ adapter })` and never see the underlying transport.
+ *
+ * The default `node-worker` adapter spawns a small pool of `worker_threads`
+ * Workers and runs each piece of user code inside `vm.Script.runInContext`
+ * with a wall-clock kill switch. The `memory` adapter runs code synchronously
+ * in the parent process — no isolation, intended for unit tests / dev loops.
+ */
+/**
+ * Reasons surfaced by the `node-worker` adapter when the wall-clock timeout
+ * fires. The `name` is preserved so existing matchers in apps continue to
+ * recognise the error.
+ */
+export class SandboxTimeoutError extends Error {
+    constructor(timeout) {
+        // Phrasing intentionally includes both "exceeded" and "timed out" so the
+        // legacy `vm.Script` watchdog message and the worker wall-clock kill share
+        // the same matcher in tests and user-facing surfaces.
+        super(`Sandbox execution exceeded ${timeout}ms timeout (execution timed out)`);
+        this.name = 'SandboxTimeoutError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmHH;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,yEAAyE;QACzE,2EAA2E;QAC3E,sDAAsD;QACtD,KAAK,CAAC,8BAA8B,OAAO,kCAAkC,CAAC,CAAA;QAC9E,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@yarlisai/sandbox",
+  "version": "0.1.0-alpha.1",
+  "description": "Pluggable sandbox runner for executing untrusted user code (worker_threads pool + in-memory fallback).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "build": "bun run clean && bunx tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "author": "YarlisAI <support@yarlis.ai>",
+  "homepage": "https://github.com/yarlisai/mybotbox-platform/tree/main/packages/sandbox#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yarlisai/mybotbox-platform.git",
+    "directory": "packages/sandbox"
+  },
+  "bugs": {
+    "url": "https://github.com/yarlisai/mybotbox-platform/issues"
+  },
+  "keywords": [
+    "yarlisai",
+    "framework",
+    "sandbox",
+    "worker_threads",
+    "code-execution",
+    "vm"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false
+}