feat: add Bun runtime support via JSON IPC codec

Bun's node:v8 module produces a different serialization format than
Node.js. Detect Bun and use JSON for IPC payloads between the host
process and the Rust V8 sidecar. Also fix a temporal dead zone issue
where Bun's eager event delivery fires the child exit handler before
sessionHandlers is initialized.

Author: NathanFlurry

native/v8-runtime/src/bridge.rs

@@ -3,6 +3,7 @@
 use std::cell::RefCell;
 use std::collections::HashMap;
 use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::OnceLock;
 
 use v8::MapFnTo;
@@ -11,6 +12,28 @@ use v8::ValueSerializerHelper;
 
 use crate::host_call::BridgeCallContext;
 
+// JSON codec flag: when true, use JSON.stringify/JSON.parse instead of V8
+// ValueSerializer/ValueDeserializer for IPC payloads. Activated by
+// SECURE_EXEC_V8_CODEC=json for runtimes whose node:v8 module doesn't
+// produce real V8 serialization format (e.g. Bun).
+static USE_JSON_CODEC: AtomicBool = AtomicBool::new(false);
+
+/// Initialize the codec from the SECURE_EXEC_V8_CODEC environment variable.
+/// Call once at process startup before any sessions are created.
+pub fn init_codec() {
+    if let Ok(val) = std::env::var("SECURE_EXEC_V8_CODEC") {
+        if val == "json" {
+            USE_JSON_CODEC.store(true, Ordering::Relaxed);
+            eprintln!("secure-exec-v8: using JSON codec for IPC payloads");
+        }
+    }
+}
+
+/// Returns true if the JSON codec is active.
+pub fn is_json_codec() -> bool {
+    USE_JSON_CODEC.load(Ordering::Relaxed)
+}
+
 /// External references for V8 snapshot serialization.
 /// Maps function pointer indices in the snapshot to current addresses.
 /// Must be identical at snapshot creation and restore time.
@@ -50,10 +73,14 @@ impl v8::ValueDeserializerImpl for DefaultDeserializerDelegate {}
 /// Serialize a V8 value to bytes using V8's built-in ValueSerializer.
 /// Handles all V8 types natively: primitives, strings, arrays, objects,
 /// Uint8Array, Date, Map, Set, RegExp, Error, and circular references.
+/// When JSON codec is active, uses JSON.stringify instead.
 pub fn serialize_v8_value(
     scope: &mut v8::HandleScope,
     value: v8::Local<v8::Value>,
 ) -> Result<Vec<u8>, String> {
+    if is_json_codec() {
+        return serialize_json_value(scope, value);
+    }
     let context = scope.get_current_context();
     let serializer = v8::ValueSerializer::new(scope, Box::new(DefaultSerializerDelegate));
     serializer.write_header();
@@ -85,6 +112,10 @@ pub fn deserialize_v8_value<'s>(
     scope: &mut v8::HandleScope<'s>,
     data: &[u8],
 ) -> Result<v8::Local<'s, v8::Value>, String> {
+    // When JSON codec is active, incoming payloads are JSON, not V8 binary
+    if is_json_codec() {
+        return deserialize_json_value(scope, data);
+    }
     let context = scope.get_current_context();
     let deserializer =
         v8::ValueDeserializer::new(scope, Box::new(DefaultDeserializerDelegate), data);
@@ -96,6 +127,32 @@ pub fn deserialize_v8_value<'s>(
         .ok_or_else(|| "V8 ValueDeserializer: failed to deserialize value".to_string())
 }
 
+/// Serialize a V8 value to JSON bytes using V8's built-in JSON.stringify.
+/// Used when SECURE_EXEC_V8_CODEC=json for runtimes like Bun.
+pub fn serialize_json_value(
+    scope: &mut v8::HandleScope,
+    value: v8::Local<v8::Value>,
+) -> Result<Vec<u8>, String> {
+    let context = scope.get_current_context();
+    let json_str = v8::json::stringify(scope, value)
+        .ok_or_else(|| "JSON.stringify failed".to_string())?;
+    let _ = context; // context used implicitly by stringify
+    Ok(json_str.to_rust_string_lossy(scope).into_bytes())
+}
+
+/// Deserialize JSON bytes to a V8 value using V8's built-in JSON.parse.
+pub fn deserialize_json_value<'s>(
+    scope: &mut v8::HandleScope<'s>,
+    data: &[u8],
+) -> Result<v8::Local<'s, v8::Value>, String> {
+    let json_str = std::str::from_utf8(data)
+        .map_err(|e| format!("JSON codec: invalid UTF-8: {}", e))?;
+    let v8_str = v8::String::new(scope, json_str)
+        .ok_or_else(|| "JSON codec: failed to create V8 string".to_string())?;
+    v8::json::parse(scope, v8_str)
+        .ok_or_else(|| "JSON codec: JSON.parse failed".to_string())
+}
+
 /// Pre-allocated serialization buffers reused across bridge calls within a session.
 /// Grows to high-water mark; cleared (not deallocated) between calls via buf.clear().
 pub struct SessionBuffers {

native/v8-runtime/src/main.rs

@@ -294,6 +294,9 @@ fn main() {
     // Close all inherited FDs > 2 before doing anything else
     close_inherited_fds();
 
+    // Initialize codec from env before any sessions are created
+    bridge::init_codec();
+
     // Initialize V8 platform on the main thread before any session threads
     isolate::init_v8_platform();
 

packages/nodejs/src/bridge-handlers.ts

@@ -14,7 +14,14 @@ import { Duplex, PassThrough } from "node:stream";
 import { readFileSync, realpathSync, existsSync } from "node:fs";
 import { dirname as pathDirname, join as pathJoin, resolve as pathResolve } from "node:path";
 import { createRequire } from "node:module";
-import { serialize } from "node:v8";
+import v8Mod from "node:v8";
+
+// Bun's node:v8 module doesn't produce real V8 serialization format
+const _isBun = typeof (globalThis as Record<string, unknown>).Bun !== "undefined";
+function ipcSerialize(value: unknown): Buffer {
+	if (_isBun) return Buffer.from(JSON.stringify(value), "utf-8");
+	return Buffer.from(v8Mod.serialize(value));
+}
 import {
 	randomFillSync,
 	randomUUID,
@@ -4884,7 +4891,7 @@ export function buildNetworkBridgeHandlers(deps: NetworkBridgeDeps): NetworkBrid
 						registerPendingHttpResponse(options.serverId, requestId, resolve);
 					});
 					state.pendingRequests += 1;
-					deps.sendStreamEvent("http_request", serialize({
+					deps.sendStreamEvent("http_request", ipcSerialize({
 						requestId,
 						serverId: options.serverId,
 						request: requestJson,

packages/nodejs/src/execution-driver.ts

@@ -1414,8 +1414,13 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			let exports: T | undefined;
 			if (options.mode === "run" && result.exports) {
 				try {
-					const { deserialize } = await import("node:v8");
-					exports = deserialize(result.exports) as T;
+					if (typeof (globalThis as Record<string, unknown>).Bun !== "undefined") {
+						// Bun: JSON codec — payload is JSON bytes
+						exports = JSON.parse(Buffer.from(result.exports).toString("utf-8")) as T;
+					} else {
+						const { deserialize } = await import("node:v8");
+						exports = deserialize(result.exports) as T;
+					}
 				} catch {
 					exports = undefined;
 				}

packages/v8/src/runtime.ts

@@ -13,6 +13,26 @@ import { IpcClient } from "./ipc-client.js";
 import type { BinaryFrame } from "./ipc-binary.js";
 import type { V8Session, V8SessionOptions } from "./session.js";
 
+// Bun's node:v8 module doesn't produce real V8 serialization format.
+// Detect Bun and use JSON codec instead.
+const isBun = typeof (globalThis as Record<string, unknown>).Bun !== "undefined";
+
+/** Serialize a value for IPC — JSON when running under Bun, V8 otherwise. */
+function ipcSerialize(value: unknown): Buffer {
+	if (isBun) {
+		return Buffer.from(JSON.stringify(value), "utf-8");
+	}
+	return Buffer.from(v8.serialize(value));
+}
+
+/** Deserialize an IPC payload — JSON when running under Bun, V8 otherwise. */
+function ipcDeserialize(buf: Buffer | Uint8Array): unknown {
+	if (isBun) {
+		return JSON.parse(Buffer.from(buf).toString("utf-8"));
+	}
+	return v8.deserialize(buf);
+}
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -104,6 +124,9 @@ export async function createV8Runtime(
 		...process.env as Record<string, string>,
 		SECURE_EXEC_V8_TOKEN: authToken,
 	};
+	if (isBun) {
+		childEnv.SECURE_EXEC_V8_CODEC = "json";
+	}
 	if (options?.maxSessions != null) {
 		childEnv.SECURE_EXEC_V8_MAX_SESSIONS = String(options.maxSessions);
 	}
@@ -116,6 +139,16 @@ export async function createV8Runtime(
 	// Forward V8 runtime stderr to host stderr for debugging
 	child.stderr?.pipe(process.stderr);
 
+	// Message routing: session-level handlers registered per session_id.
+	// Declared before the exit handler so Bun's eager event delivery
+	// doesn't hit the temporal dead zone.
+	const sessionHandlers = new Map<
+		string,
+		(frame: BinaryFrame) => void
+	>();
+	// Per-session reject functions for rejecting in-flight execute() promises
+	const sessionRejects = new Map<string, (err: Error) => void>();
+
 	// Track whether the process is alive
 	let processAlive = true;
 	let exitError: Error | null = null;
@@ -187,14 +220,6 @@ export async function createV8Runtime(
 	let ipcClient: IpcClient | null = null;
 	let disposed = false;
 
-	// Message routing: session-level handlers registered per session_id
-	const sessionHandlers = new Map<
-		string,
-		(frame: BinaryFrame) => void
-	>();
-	// Per-session reject functions for rejecting in-flight execute() promises
-	const sessionRejects = new Map<string, (err: Error) => void>();
-
 	ipcClient = new IpcClient({
 		socketPath,
 		onMessage: (frame) => {
@@ -336,8 +361,8 @@ export async function createV8Runtime(
 						throw new Error("IPC client is not connected");
 					}
 
-					// Inject globals — V8-serialize { processConfig, osConfig }
-					const globalsPayload = v8.serialize({
+					// Inject globals — serialize { processConfig, osConfig }
+					const globalsPayload = ipcSerialize({
 						processConfig: execOptions.processConfig,
 						osConfig: execOptions.osConfig,
 					});
@@ -373,7 +398,7 @@ export async function createV8Runtime(
 									// Deserialize args and call handler
 									void (async () => {
 										try {
-											const args = v8.deserialize(
+											const args = ipcDeserialize(
 												frame.payload,
 											) as unknown[];
 											const result = await handler(
@@ -400,7 +425,7 @@ export async function createV8Runtime(
 													status: 0,
 													payload:
 														result !== undefined
-															? Buffer.from(v8.serialize(result))
+															? ipcSerialize(result)
 															: Buffer.alloc(0),
 												});
 											}