feat(nodejs): add includeNodeShims option to opt out of globalThis polyfills

Fixes #63 — adds ability to disable Node.js polyfill shims (fs, http,
process, Buffer, etc.) on globalThis.

When includeNodeShims: false is passed to createNodeRuntime():
- globalThis.fs, globalThis.http, globalThis.process, globalThis.Buffer
  are NOT injected into the isolate
- Useful for AI agents that need a clean globalThis scope
- fs/http are still accessible via require('fs') / await import('fs')
  when host filesystem is permitted via permissions

API:
  createNodeRuntime({ includeNodeShims: false })

Default: true (existing behavior unchanged).

Changes:
- packages/nodejs/src/kernel-runtime.ts: Added includeNodeShims to NodeRuntimeOptions
- packages/nodejs/src/driver.ts: Added includeNodeShims to NodeDriverOptions, pass to runtime config
- packages/nodejs/src/execution-driver.ts: buildFullBridgeCode() now keyed by includeNodeShims
  in a Map<boolean,string> cache; per-driver bridge code built in constructor
- packages/nodejs/test/kernel-runtime.test.ts: 3 new tests for includeNodeShims=false/true

Author: aayushprsingh

packages/nodejs/src/driver.ts

@@ -40,6 +40,8 @@ export interface NodeDriverOptions {
 	loopbackExemptPorts?: number[];
 	processConfig?: ProcessConfig;
 	osConfig?: OSConfig;
+	/** Include Node.js shims (fs, http, process, Buffer, etc.) on globalThis. Default: true. */
+	includeNodeShims?: boolean;
 }
 
 export interface NodeRuntimeDriverFactoryOptions {
@@ -260,6 +262,10 @@ export function createNodeDriver(options: NodeDriverOptions = {}): SystemDriver
 			os: {
 				...(options.osConfig ?? {}),
 			},
+			// @ts-ignore-next-line — internal field used by NodeExecutionDriver to gate bridge shims
+			...(options.includeNodeShims !== undefined
+				? { includeNodeShims: options.includeNodeShims }
+				: {}),
 		},
 	};
 }

packages/nodejs/src/execution-driver.ts

@@ -140,6 +140,10 @@ interface DriverState {
 	resolutionCache: ResolutionCache;
 	onPtySetRawMode?: (mode: boolean) => void;
 	liveStdinSource?: NodeExecutionDriverOptions["liveStdinSource"];
+	/** Pre-built bridge code for this driver, based on includeNodeShims setting. */
+	bridgeCode: string;
+	/** Whether this driver includes Node.js polyfill shims on globalThis. */
+	includeNodeShims: boolean;
 }
 
 // Shared V8 runtime process — one per Node.js process, lazy-initialized
@@ -151,8 +155,8 @@ async function getSharedV8Runtime(): Promise<V8Runtime> {
 	if (sharedV8Runtime?.isAlive) return sharedV8Runtime;
 	if (sharedV8RuntimePromise) return sharedV8RuntimePromise;
 
-	// Build bridge code for snapshot warmup
-	const bridgeCode = buildFullBridgeCode();
+	// Build bridge code for snapshot warmup (always with shims for the shared runtime)
+	const bridgeCode = buildFullBridgeCode(true);
 
 	sharedV8RuntimePromise = createV8Runtime({
 		warmupBridgeCode: bridgeCode,
@@ -765,10 +769,12 @@ function buildBridgeDispatchShim(): string {
 const BRIDGE_DISPATCH_SHIM = buildBridgeDispatchShim();
 
 // Cache assembled bridge code (same across all executions)
-let bridgeCodeCache: string | null = null;
+// Keyed by includeNodeShims flag so drivers with different settings get correct code
+const bridgeCodeCache = new Map<boolean, string>();
 
-function buildFullBridgeCode(): string {
-	if (bridgeCodeCache) return bridgeCodeCache;
+function buildFullBridgeCode(includeNodeShims: boolean = true): string {
+	const cached = bridgeCodeCache.get(includeNodeShims);
+	if (cached !== undefined) return cached;
 
 	// Assemble the full bridge code IIFE from component scripts.
 	// Only include code that can run without bridge calls (snapshot phase).
@@ -778,12 +784,18 @@ function buildFullBridgeCode(): string {
 		V8_POLYFILLS,
 		getIsolateRuntimeSource("globalExposureHelpers"),
 		getInitialBridgeGlobalsSetupCode(),
-		getRawBridgeCode(),
-		getBridgeAttachCode(),
 	];
 
-	bridgeCodeCache = parts.join("\n");
-	return bridgeCodeCache;
+	// Only include Node.js shims (fs, http, process globals, etc.) when explicitly requested.
+	// For AI agent use cases, users may want a clean globalThis with no injected polyfills.
+	if (includeNodeShims) {
+		parts.push(getRawBridgeCode());
+		parts.push(getBridgeAttachCode());
+	}
+
+	const code = parts.join("\n");
+	bridgeCodeCache.set(includeNodeShims, code);
+	return code;
 }
 
 export class NodeExecutionDriver implements RuntimeDriver {
@@ -853,6 +865,11 @@ export class NodeExecutionDriver implements RuntimeDriver {
 		osConfig.homedir ??= DEFAULT_SANDBOX_HOME;
 		osConfig.tmpdir ??= DEFAULT_SANDBOX_TMPDIR;
 
+		// Determine whether to include Node.js polyfill shims on globalThis.
+		// When false, globalThis has no injected fs, http, process, Buffer, etc.
+		// Useful for AI agent use cases that need a clean global scope.
+		const includeNodeShims = (options.runtime as any).includeNodeShims ?? true;
+
 		const bridgeBase64TransferLimitBytes = normalizePayloadLimit(
 			options.payloadLimits?.base64TransferBytes,
 			DEFAULT_BRIDGE_BASE64_TRANSFER_BYTES,
@@ -893,6 +910,8 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			resolutionCache: createResolutionCache(),
 			onPtySetRawMode: options.onPtySetRawMode,
 			liveStdinSource: options.liveStdinSource,
+			bridgeCode: buildFullBridgeCode(includeNodeShims),
+			includeNodeShims,
 		};
 
 		// Validate and flatten bindings once at construction time
@@ -1284,8 +1303,8 @@ export class NodeExecutionDriver implements RuntimeDriver {
 				}
 			}
 
-			// Build bridge code with embedded config
-			const bridgeCode = buildFullBridgeCode();
+			// Use the pre-built bridge code from constructor (respects includeNodeShims)
+			const bridgeCode = this.state.bridgeCode;
 
 			// Build post-restore script with per-execution config
 			const bindingKeys = this.flattenedBindings

packages/nodejs/src/kernel-runtime.ts

@@ -72,6 +72,18 @@ export interface NodeRuntimeOptions {
    * before the CWD-based node_modules fallback in the ModuleAccessFileSystem.
    */
   packageRoots?: Array<{ hostPath: string; vmPath: string }>;
+  /**
+   * Include Node.js polyfill shims (fs, http, process, Buffer, etc.) on globalThis.
+   *
+   * When false: globalThis is clean — useful for AI agents that need full
+   * control over the global scope without any injected Node.js globals.
+   *
+   * You can still access these modules via `require('fs')` or `await import('fs')`
+   * when the host filesystem is accessible via permissions.
+   *
+   * Default: true (include shims, for backward compatibility).
+   */
+  includeNodeShims?: boolean;
 }
 
 const allowKernelProcSelfRead: Pick<Permissions, 'fs'> = {
@@ -409,6 +421,7 @@ class NodeRuntimeDriver implements RuntimeDriver {
   private _loopbackExemptPorts?: number[];
   private _moduleAccessCwd?: string;
   private _packageRoots?: Array<{ hostPath: string; vmPath: string }>;
+  private _includeNodeShims: boolean;
 
   constructor(options?: NodeRuntimeOptions) {
     this._memoryLimit = options?.memoryLimit ?? 128;
@@ -417,6 +430,7 @@ class NodeRuntimeDriver implements RuntimeDriver {
     this._loopbackExemptPorts = options?.loopbackExemptPorts;
     this._moduleAccessCwd = options?.moduleAccessCwd;
     this._packageRoots = options?.packageRoots;
+    this._includeNodeShims = options?.includeNodeShims ?? true;
   }
 
   async init(kernel: KernelInterface): Promise<void> {
@@ -724,6 +738,7 @@ class NodeRuntimeDriver implements RuntimeDriver {
           homedir: ctx.env.HOME || '/root',
           tmpdir: ctx.env.TMPDIR || '/tmp',
         },
+        includeNodeShims: this._includeNodeShims,
       });
 
       // Wire PTY raw mode callback when stdin is a terminal

packages/nodejs/test/kernel-runtime.test.ts

@@ -969,3 +969,58 @@ describe('Node RuntimeDriver', () => {
     }, 10_000);
   });
 });
+
+  describe('includeNodeShims option', () => {
+    let kernel: Kernel;
+
+    afterEach(async () => {
+      await kernel?.dispose();
+    });
+
+    it('globalThis.fs is undefined when includeNodeShims is false', async () => {
+      // With includeNodeShims: false, the bridge does NOT inject fs/http/etc.
+      // onto globalThis. This is useful for AI agents that need a clean scope.
+      const vfs = new SimpleVFS();
+      kernel = createKernel({ filesystem: vfs as any });
+      await kernel.mount(createNodeRuntime({ includeNodeShims: false }));
+
+      // Use exec() with node fallback (fixes #64 — exec falls back to node
+      // when sh is not registered)
+      const result = await kernel.exec(
+        
+ode -e "console.log(typeof fs)",
+      );
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe('undefined');
+    });
+
+    it('globalThis.fs is an object when includeNodeShims is true (default)', async () => {
+      // Default behavior: bridge injects fs, http, process, Buffer etc. onto globalThis.
+      const vfs = new SimpleVFS();
+      kernel = createKernel({ filesystem: vfs as any });
+      await kernel.mount(createNodeRuntime({ includeNodeShims: true }));
+
+      const result = await kernel.exec(
+        
+ode -e "console.log(typeof fs)",
+      );
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe('object');
+    });
+
+    it('exec with includeNodeShims=false still works via node fallback', async () => {
+      const vfs = new SimpleVFS();
+      kernel = createKernel({ filesystem: vfs as any });
+      await kernel.mount(createNodeRuntime({ includeNodeShims: false }));
+
+      const result = await kernel.exec(
+        
+ode -e "console.log('hello from no-shims runtime')",
+      );
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe('hello from no-shims runtime');
+    });
+  });