tywrap 0.1.1 → 0.2.0

package/dist/runtime/node.js

@@ -1,15 +1,26 @@
 /**
- * Node.js runtime bridge (minimal MVP)
+ * Node.js Runtime Bridge with Optional Connection Pooling
+ *
+ * NodeBridge is the unified Node.js runtime bridge that supports both single-process
+ * (correctness-first) and multi-process (pooled) configurations. By default, it runs
+ * in single-process mode for maximum compatibility with the original NodeBridge behavior.
+ *
+ * For high-throughput workloads, configure pooling via minProcesses/maxProcesses options.
  */
 import { existsSync } from 'node:fs';
 import { delimiter, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { decodeValueAsync } from '../utils/codec.js';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'events';
+import { globalCache } from '../utils/cache.js';
+import { autoRegisterArrowDecoder, decodeValueAsync } from '../utils/codec.js';
 import { getDefaultPythonPath } from '../utils/python.js';
 import { getVenvBinDir, getVenvPythonExe } from '../utils/runtime.js';
 import { RuntimeBridge } from './base.js';
-import { BridgeDisposedError, BridgeExecutionError, BridgeProtocolError, BridgeTimeoutError, } from './errors.js';
-import { TYWRAP_PROTOCOL, TYWRAP_PROTOCOL_VERSION } from './protocol.js';
+import { BridgeDisposedError, BridgeProtocolError } from './errors.js';
+import { BridgeCore, ensureJsonFallback, ensurePythonEncoding, getMaxLineLengthFromEnv, getPathKey, normalizeEnv, validateBridgeInfo, } from './bridge-core.js';
+import { getComponentLogger } from '../utils/logger.js';
+const log = getComponentLogger('NodeBridge');
 function resolveDefaultScriptPath() {
     try {
         return fileURLToPath(new URL('../../runtime/python_bridge.py', import.meta.url));
@@ -24,16 +35,47 @@ function resolveVirtualEnv(virtualEnv, cwd) {
     const pythonPath = join(binDir, getVenvPythonExe());
     return { venvPath, binDir, pythonPath };
 }
+/**
+ * Node.js runtime bridge for executing Python code.
+ *
+ * By default, runs in single-process mode for correctness-first behavior.
+ * Configure minProcesses/maxProcesses for process pooling in high-throughput scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Single-process mode (default)
+ * const bridge = new NodeBridge();
+ *
+ * // Multi-process pooling for high throughput
+ * const pooledBridge = new NodeBridge({
+ *   minProcesses: 2,
+ *   maxProcesses: 8,
+ *   enableCache: true,
+ * });
+ * ```
+ */
 export class NodeBridge extends RuntimeBridge {
-    child;
-    nextId = 1;
-    pending = new Map();
+    processPool = [];
+    roundRobinIndex = 0;
+    cleanupTimer;
     options;
-    stderrBuffer = '';
+    emitter = new EventEmitter();
     disposed = false;
-    protocolError = false;
-    initPromise;
     bridgeInfo;
+    initPromise;
+    // Performance monitoring
+    stats = {
+        totalRequests: 0,
+        totalTime: 0,
+        cacheHits: 0,
+        poolHits: 0,
+        poolMisses: 0,
+        processSpawns: 0,
+        processDeaths: 0,
+        memoryPeak: 0,
+        averageTime: 0,
+        cacheHitRate: 0,
+    };
     constructor(options = {}) {
         super();
         const cwd = options.cwd ?? process.cwd();
@@ -42,31 +84,58 @@ export class NodeBridge extends RuntimeBridge {
         const scriptPath = options.scriptPath ?? resolveDefaultScriptPath();
         const resolvedScriptPath = isAbsolute(scriptPath) ? scriptPath : resolve(cwd, scriptPath);
         this.options = {
+            // Default to single-process mode for backward compatibility
+            minProcesses: options.minProcesses ?? 1,
+            maxProcesses: options.maxProcesses ?? 1,
+            maxIdleTime: options.maxIdleTime ?? 300000, // 5 minutes
+            maxRequestsPerProcess: options.maxRequestsPerProcess ?? 1000,
             pythonPath: options.pythonPath ?? venv?.pythonPath ?? getDefaultPythonPath(),
             scriptPath: resolvedScriptPath,
             virtualEnv,
             cwd,
             timeoutMs: options.timeoutMs ?? 30000,
+            maxLineLength: options.maxLineLength,
+            inheritProcessEnv: options.inheritProcessEnv ?? false,
             enableJsonFallback: options.enableJsonFallback ?? false,
+            enableCache: options.enableCache ?? false,
             env: options.env ?? {},
+            warmupCommands: options.warmupCommands ?? [],
         };
+        // Start cleanup scheduler for pooled mode
+        this.startCleanupScheduler();
     }
     async init() {
         if (this.disposed) {
             throw new BridgeDisposedError('Bridge has been disposed');
         }
-        if (this.child) {
-            return;
+        if (this.processPool.length >= this.options.minProcesses) {
+            return; // Already initialized
         }
         if (this.initPromise) {
             return this.initPromise;
         }
+        this.initPromise = this.doInit();
+        return this.initPromise;
+    }
+    async doInit() {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- script path is user-configured
         if (!existsSync(this.options.scriptPath)) {
             throw new BridgeProtocolError(`Python bridge script not found at ${this.options.scriptPath}`);
         }
-        this.initPromise = this.startProcess();
-        return this.initPromise;
+        const require = createRequire(import.meta.url);
+        await autoRegisterArrowDecoder({
+            loader: () => require('apache-arrow'),
+        });
+        // Ensure minimum processes are available
+        while (this.processPool.length < this.options.minProcesses) {
+            await this.spawnProcess();
+        }
+        // Validate protocol version
+        await this.refreshBridgeInfo();
+        // Warm up processes if configured
+        if (this.options.warmupCommands.length > 0) {
+            await this.warmupProcesses();
+        }
     }
     async getBridgeInfo(options = {}) {
         await this.init();
@@ -80,247 +149,502 @@ export class NodeBridge extends RuntimeBridge {
     }
     async call(module, functionName, args, kwargs) {
         await this.init();
-        return this.send({ method: 'call', params: { module, functionName, args, kwargs } });
+        const startTime = performance.now();
+        const cacheKey = this.options.enableCache
+            ? this.safeCacheKey('runtime_call', module, functionName, args, kwargs)
+            : null;
+        if (cacheKey) {
+            const cached = await globalCache.get(cacheKey);
+            if (cached !== null) {
+                this.stats.cacheHits++;
+                this.updateStats(performance.now() - startTime);
+                return cached;
+            }
+        }
+        try {
+            const result = await this.executeRequest({
+                method: 'call',
+                params: { module, functionName, args, kwargs },
+            });
+            const duration = performance.now() - startTime;
+            // Cache result for pure functions (simple heuristic)
+            if (cacheKey && this.isPureFunctionCandidate(functionName, args)) {
+                await globalCache.set(cacheKey, result, {
+                    computeTime: duration,
+                    dependencies: [module],
+                });
+            }
+            this.updateStats(duration);
+            return result;
+        }
+        catch (error) {
+            this.updateStats(performance.now() - startTime, true);
+            throw error;
+        }
     }
     async instantiate(module, className, args, kwargs) {
         await this.init();
-        return this.send({ method: 'instantiate', params: { module, className, args, kwargs } });
+        const startTime = performance.now();
+        try {
+            const result = await this.executeRequest({
+                method: 'instantiate',
+                params: { module, className, args, kwargs },
+            });
+            this.updateStats(performance.now() - startTime);
+            return result;
+        }
+        catch (error) {
+            this.updateStats(performance.now() - startTime, true);
+            throw error;
+        }
     }
     async callMethod(handle, methodName, args, kwargs) {
         await this.init();
-        return this.send({ method: 'call_method', params: { handle, methodName, args, kwargs } });
+        const startTime = performance.now();
+        try {
+            const result = await this.executeRequest({
+                method: 'call_method',
+                params: { handle, methodName, args, kwargs },
+            });
+            this.updateStats(performance.now() - startTime);
+            return result;
+        }
+        catch (error) {
+            this.updateStats(performance.now() - startTime, true);
+            throw error;
+        }
     }
     async disposeInstance(handle) {
         await this.init();
-        await this.send({ method: 'dispose_instance', params: { handle } });
+        await this.executeRequest({
+            method: 'dispose_instance',
+            params: { handle },
+        });
     }
-    async dispose() {
-        this.disposed = true;
-        this.initPromise = undefined;
-        this.bridgeInfo = undefined;
-        if (!this.child) {
-            return;
+    /**
+     * Execute request with intelligent process selection
+     */
+    async executeRequest(payload) {
+        let worker = this.selectOptimalWorker();
+        // Spawn new process if none available and under limit
+        if (!worker && this.processPool.length < this.options.maxProcesses) {
+            try {
+                worker = await this.spawnProcess();
+                this.stats.poolMisses++;
+            }
+            catch (error) {
+                throw new Error(`Failed to spawn worker process: ${error}`);
+            }
         }
-        this.child.kill('SIGTERM');
-        this.child = undefined;
+        // Wait for worker if all are busy
+        worker ??= await this.waitForAvailableWorker();
+        this.stats.poolHits++;
+        return this.sendToWorker(worker, payload);
     }
-    async send(payload) {
-        if (this.disposed) {
-            throw new BridgeDisposedError('Bridge has been disposed');
+    /**
+     * Select optimal worker based on load and performance
+     */
+    selectOptimalWorker() {
+        // For single-process mode, allow concurrent requests to the same worker.
+        // BridgeCore handles request ID multiplexing, so multiple in-flight requests are safe.
+        // This preserves original NodeBridge behavior where concurrent calls were allowed.
+        if (this.options.maxProcesses === 1 && this.processPool.length === 1) {
+            const worker = this.processPool[0];
+            if (worker && !worker.quarantined && worker.process.exitCode === null) {
+                return worker;
+            }
+            return null;
+        }
+        // For multi-worker pools, use busy status for load balancing
+        const availableWorkers = this.processPool.filter(w => !w.busy && !w.quarantined && w.process.exitCode === null);
+        if (availableWorkers.length === 0) {
+            return null;
         }
-        const id = this.nextId++;
-        const message = { id, protocol: TYWRAP_PROTOCOL, ...payload };
-        const text = `${JSON.stringify(message)}\n`;
-        let timer;
-        const promise = new Promise((resolvePromise, reject) => {
-            timer = setTimeout(() => {
-                this.pending.delete(id);
-                const stderrTail = this.stderrBuffer.trim();
-                const msg = stderrTail
-                    ? `Python call timed out. Recent stderr from Python:\n${stderrTail}`
-                    : 'Python call timed out';
-                reject(new BridgeTimeoutError(msg));
-            }, this.options.timeoutMs);
-            const resolveWrapped = (v) => {
-                resolvePromise(v);
+        // Simple round-robin for now, could be enhanced with load-based selection
+        const worker = availableWorkers[this.roundRobinIndex % availableWorkers.length];
+        this.roundRobinIndex = (this.roundRobinIndex + 1) % availableWorkers.length;
+        return worker ?? null;
+    }
+    /**
+     * Wait for any worker to become available
+     */
+    async waitForAvailableWorker(timeoutMs = 5000) {
+        return new Promise((resolvePromise, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error('Timeout waiting for available worker'));
+            }, timeoutMs);
+            const checkWorker = () => {
+                const worker = this.selectOptimalWorker();
+                if (worker) {
+                    clearTimeout(timeout);
+                    resolvePromise(worker);
+                }
+                else {
+                    // Check again in 10ms
+                    setTimeout(checkWorker, 10);
+                }
             };
-            this.pending.set(id, { resolve: resolveWrapped, reject, timer });
+            checkWorker();
         });
+    }
+    /**
+     * Send request to specific worker
+     */
+    async sendToWorker(worker, payload) {
+        worker.busy = true;
+        worker.requestCount++;
+        worker.lastUsed = Date.now();
+        const startTime = performance.now();
         try {
-            if (!this.child?.stdin) {
-                throw new BridgeProtocolError('Python process not available');
-            }
-            this.child.stdin.write(text);
+            const result = await worker.core.send(payload);
+            const duration = performance.now() - startTime;
+            worker.stats.totalTime += duration;
+            worker.stats.totalRequests++;
+            worker.stats.averageTime = worker.stats.totalTime / worker.stats.totalRequests;
+            return result;
         }
-        catch (err) {
-            this.pending.delete(id);
-            if (timer) {
-                clearTimeout(timer);
-            }
-            throw new BridgeProtocolError(`IPC failure: ${err.message}`);
+        catch (error) {
+            worker.stats.errorCount++;
+            throw error;
+        }
+        finally {
+            worker.busy = false;
         }
-        return promise;
-    }
-    errorFrom(err) {
-        const e = new BridgeExecutionError(`${err.type}: ${err.message}`);
-        e.traceback = err.traceback;
-        return e;
     }
-    handleProtocolError(details, line) {
-        if (this.protocolError) {
+    quarantineWorker(worker, error) {
+        if (worker.quarantined) {
             return;
         }
-        this.protocolError = true;
-        const snippet = line ? (line.length > 500 ? `${line.slice(0, 500)}…` : line) : undefined;
-        const hint = 'Ensure your Python code does not print to stdout and that the bridge outputs only JSON lines.';
-        const msg = snippet
-            ? `Protocol error from Python bridge. ${details}\n${hint}\nOffending line: ${snippet}`
-            : `Protocol error from Python bridge. ${details}\n${hint}`;
-        const error = new BridgeProtocolError(msg);
-        for (const [, p] of this.pending) {
-            p.reject(error);
-        }
-        this.pending.clear();
-        this.child?.kill('SIGTERM');
-        this.child = undefined;
-        this.initPromise = undefined;
-        this.bridgeInfo = undefined;
+        worker.quarantined = true;
+        log.warn('Quarantining worker', { workerId: worker.id, error: String(error) });
+        this.terminateWorker(worker, { force: true })
+            .then(() => {
+            if (!this.disposed && this.processPool.length < this.options.minProcesses) {
+                this.spawnProcess().catch(spawnError => {
+                    log.error('Failed to spawn replacement worker after quarantine', {
+                        error: String(spawnError),
+                    });
+                });
+            }
+        })
+            .catch(terminateError => {
+            log.warn('Failed to terminate quarantined worker', {
+                workerId: worker.id,
+                error: String(terminateError),
+            });
+        });
     }
-    async startProcess() {
-        try {
-            const { spawn } = await import('child_process');
-            const allowedPrefixes = ['TYWRAP_'];
-            const allowedKeys = new Set(['PATH', 'PYTHONPATH', 'VIRTUAL_ENV', 'PYTHONHOME']);
-            const baseEnv = new Map();
-            for (const [k, v] of Object.entries(process.env)) {
-                if (allowedKeys.has(k) || allowedPrefixes.some(p => k.startsWith(p))) {
-                    baseEnv.set(k, v);
+    /**
+     * Spawn new worker process with optimizations
+     */
+    async spawnProcess() {
+        const { spawn } = await import('child_process');
+        const workerId = `worker_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        const env = this.buildEnv();
+        env.PYTHONUNBUFFERED = '1'; // Ensure immediate output
+        env.PYTHONDONTWRITEBYTECODE = '1'; // Skip .pyc files for faster startup
+        const maxLineLength = this.options.maxLineLength ?? getMaxLineLengthFromEnv(env);
+        const childProcess = spawn(this.options.pythonPath, [this.options.scriptPath], {
+            cwd: this.options.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env,
+        });
+        const worker = {
+            process: childProcess,
+            id: workerId,
+            requestCount: 0,
+            lastUsed: Date.now(),
+            busy: false,
+            quarantined: false,
+            core: null,
+            stats: {
+                totalRequests: 0,
+                totalTime: 0,
+                averageTime: 0,
+                errorCount: 0,
+            },
+        };
+        worker.core = new BridgeCore({
+            write: (data) => {
+                if (!worker.process.stdin?.writable) {
+                    throw new BridgeProtocolError('Worker process stdin not writable');
                 }
+                worker.process.stdin.write(data);
+            },
+        }, {
+            timeoutMs: this.options.timeoutMs,
+            maxLineLength,
+            decodeValue: decodeValueAsync,
+            onFatalError: (error) => this.quarantineWorker(worker, error),
+            onTimeout: (error) => this.quarantineWorker(worker, error),
+        });
+        // Setup process event handlers
+        this.setupProcessHandlers(worker);
+        this.processPool.push(worker);
+        this.stats.processSpawns++;
+        return worker;
+    }
+    /**
+     * Setup event handlers for worker process
+     */
+    setupProcessHandlers(worker) {
+        const childProcess = worker.process;
+        childProcess.stdout?.on('data', (chunk) => {
+            worker.core.handleStdoutData(chunk);
+        });
+        childProcess.stderr?.on('data', (chunk) => {
+            worker.core.handleStderrData(chunk);
+            const errorText = chunk.toString().trim();
+            if (errorText) {
+                log.warn('Worker stderr', { workerId: worker.id, output: errorText });
             }
-            const env = {
-                ...Object.fromEntries(baseEnv),
-                ...this.options.env,
-            };
-            if (this.options.virtualEnv) {
-                const venv = resolveVirtualEnv(this.options.virtualEnv, this.options.cwd);
-                env.VIRTUAL_ENV = venv.venvPath;
-                const currentPath = env.PATH ?? process.env.PATH ?? '';
-                env.PATH = `${venv.binDir}${delimiter}${currentPath}`;
-            }
-            if (!env.PYTHONUTF8) {
-                env.PYTHONUTF8 = '1';
+        });
+        // Handle process exit
+        childProcess.on('exit', code => {
+            log.warn('Worker exited', { workerId: worker.id, code });
+            worker.core.handleProcessExit();
+            this.handleWorkerExit(worker, code);
+        });
+        // Handle process errors
+        childProcess.on('error', error => {
+            log.error('Worker error', { workerId: worker.id, error: String(error) });
+            worker.core.handleProcessError(error);
+            this.handleWorkerExit(worker, -1);
+        });
+    }
+    /**
+     * Handle worker process exit
+     */
+    handleWorkerExit(worker, _code) {
+        if (!this.processPool.includes(worker)) {
+            return;
+        }
+        worker.core.clear();
+        // Remove from pool
+        const index = this.processPool.indexOf(worker);
+        if (index >= 0) {
+            this.processPool.splice(index, 1);
+            this.stats.processDeaths++;
+        }
+        // Spawn replacement if needed and not disposing
+        if (!this.disposed && this.processPool.length < this.options.minProcesses) {
+            this.spawnProcess().catch(error => {
+                log.error('Failed to spawn replacement worker', { error: String(error) });
+            });
+        }
+    }
+    /**
+     * Warm up processes with configured commands
+     */
+    async warmupProcesses() {
+        const warmupPromises = this.processPool.map(async (worker) => {
+            for (const cmd of this.options.warmupCommands) {
+                try {
+                    await this.sendToWorker(worker, {
+                        method: cmd.method,
+                        params: cmd.params,
+                    });
+                }
+                catch (error) {
+                    log.warn('Warmup command failed', { workerId: worker.id, error: String(error) });
+                }
             }
-            if (!env.PYTHONIOENCODING) {
-                env.PYTHONIOENCODING = 'UTF-8';
+        });
+        await Promise.all(warmupPromises);
+    }
+    safeCacheKey(prefix, ...inputs) {
+        try {
+            return globalCache.generateKey(prefix, ...inputs);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Heuristic to determine if function result should be cached
+     */
+    isPureFunctionCandidate(functionName, args) {
+        // Simple heuristics - could be made more sophisticated
+        const pureFunctionPatterns = [
+            /^(get|fetch|read|load|find|search|query|select)_/i,
+            /^(compute|calculate|process|transform|convert)_/i,
+            /^(encode|decode|serialize|deserialize)_/i,
+        ];
+        const impureFunctionPatterns = [
+            /^(set|save|write|update|insert|delete|create|modify)_/i,
+            /^(send|post|put|patch)_/i,
+            /random|uuid|timestamp|now|current/i,
+        ];
+        // Don't cache if function name suggests mutation
+        if (impureFunctionPatterns.some(pattern => pattern.test(functionName))) {
+            return false;
+        }
+        // Cache if function name suggests pure computation
+        if (pureFunctionPatterns.some(pattern => pattern.test(functionName))) {
+            return true;
+        }
+        // Don't cache if args contain mutable objects (very basic check)
+        const hasComplexArgs = args.some(arg => arg !== null && typeof arg === 'object' && !(arg instanceof Date));
+        return !hasComplexArgs && args.length <= 3; // Cache simple calls with few args
+    }
+    /**
+     * Update performance statistics
+     */
+    updateStats(duration, _error = false) {
+        this.stats.totalRequests++;
+        this.stats.totalTime += duration;
+        const currentMemory = process.memoryUsage().heapUsed;
+        if (currentMemory > this.stats.memoryPeak) {
+            this.stats.memoryPeak = currentMemory;
+        }
+    }
+    /**
+     * Get performance statistics
+     */
+    getStats() {
+        const avgTime = this.stats.totalRequests > 0 ? this.stats.totalTime / this.stats.totalRequests : 0;
+        const hitRate = this.stats.totalRequests > 0 ? this.stats.cacheHits / this.stats.totalRequests : 0;
+        return {
+            ...this.stats,
+            averageTime: avgTime,
+            cacheHitRate: hitRate,
+            poolSize: this.processPool.length,
+            busyWorkers: this.processPool.filter(w => w.busy).length,
+            memoryUsage: process.memoryUsage(),
+            workerStats: this.processPool.map(w => ({
+                id: w.id,
+                requestCount: w.requestCount,
+                averageTime: w.stats.averageTime,
+                errorCount: w.stats.errorCount,
+                busy: w.busy,
+                pendingRequests: w.core.getPendingCount(),
+            })),
+        };
+    }
+    /**
+     * Cleanup idle processes
+     */
+    async cleanup() {
+        const now = Date.now();
+        const idleWorkers = this.processPool.filter(w => !w.busy &&
+            now - w.lastUsed > this.options.maxIdleTime &&
+            this.processPool.length > this.options.minProcesses);
+        for (const worker of idleWorkers) {
+            await this.terminateWorker(worker);
+        }
+        // Restart workers that have handled too many requests
+        const overusedWorkers = this.processPool.filter(w => !w.busy && w.requestCount >= this.options.maxRequestsPerProcess);
+        for (const worker of overusedWorkers) {
+            await this.terminateWorker(worker);
+            if (this.processPool.length < this.options.minProcesses) {
+                await this.spawnProcess();
             }
-            // Respect explicit request for JSON fallback only; otherwise fast-fail by default
-            if (this.options.enableJsonFallback && !env.TYWRAP_CODEC_FALLBACK) {
-                env.TYWRAP_CODEC_FALLBACK = 'json';
+        }
+    }
+    /**
+     * Gracefully terminate a worker
+     */
+    async terminateWorker(worker, options = {}) {
+        if (worker.busy && !options.force) {
+            return;
+        }
+        const index = this.processPool.indexOf(worker);
+        if (index >= 0) {
+            this.processPool.splice(index, 1);
+            this.stats.processDeaths++;
+        }
+        worker.core.handleProcessExit();
+        worker.core.clear();
+        // Graceful termination
+        try {
+            if (worker.process.exitCode === null) {
+                worker.process.kill('SIGTERM');
+                // Force kill if not terminated in 5 seconds
+                setTimeout(() => {
+                    if (worker.process.exitCode === null) {
+                        worker.process.kill('SIGKILL');
+                    }
+                }, 5000);
             }
-            let child;
+        }
+        catch (error) {
+            log.warn('Error terminating worker', { workerId: worker.id, error: String(error) });
+        }
+    }
+    /**
+     * Start cleanup scheduler
+     */
+    startCleanupScheduler() {
+        this.cleanupTimer = setInterval(async () => {
             try {
-                child = spawn(this.options.pythonPath, [this.options.scriptPath], {
-                    cwd: this.options.cwd,
-                    stdio: ['pipe', 'pipe', 'pipe'],
-                    env,
-                });
+                await this.cleanup();
             }
-            catch (err) {
-                throw new BridgeProtocolError(`Failed to start Python process: ${err.message}`);
+            catch (error) {
+                log.error('Cleanup error', { error: String(error) });
             }
-            const startupError = await new Promise(done => {
-                child.once('error', e => done(e));
-                child.once('spawn', () => done(null));
-            });
-            if (startupError) {
-                throw new BridgeProtocolError(`Failed to start Python process: ${startupError.message}`);
+        }, 60000); // Cleanup every minute
+    }
+    /**
+     * Dispose all resources
+     */
+    async dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        // Terminate all workers
+        const terminationPromises = this.processPool.map(worker => this.terminateWorker(worker, { force: true }));
+        await Promise.all(terminationPromises);
+        this.processPool.length = 0;
+        this.emitter.removeAllListeners();
+    }
+    buildEnv() {
+        const allowedPrefixes = ['TYWRAP_'];
+        const allowedKeys = new Set(['path', 'pythonpath', 'virtual_env', 'pythonhome']);
+        const baseEnv = {};
+        if (this.options.inheritProcessEnv) {
+            for (const [key, value] of Object.entries(process.env)) {
+                // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+                baseEnv[key] = value;
             }
-            this.child = child;
-            this.protocolError = false;
-            this.child?.on('error', err => {
-                const msg = `Python process error: ${err instanceof Error ? err.message : String(err)}`;
-                for (const [, p] of this.pending) {
-                    p.reject(new BridgeProtocolError(msg));
-                }
-                this.pending.clear();
-                this.child = undefined;
-                this.initPromise = undefined;
-                this.bridgeInfo = undefined;
-            });
-            let buffer = '';
-            this.child.stdout?.on('data', (chunk) => {
-                buffer += chunk.toString();
-                let idx;
-                while ((idx = buffer.indexOf('\n')) !== -1) {
-                    const line = buffer.slice(0, idx);
-                    buffer = buffer.slice(idx + 1);
-                    if (!line.trim()) {
-                        continue;
-                    }
-                    (async () => {
-                        try {
-                            const msg = JSON.parse(line);
-                            if (msg.protocol !== TYWRAP_PROTOCOL) {
-                                this.handleProtocolError(`Invalid protocol. Expected ${TYWRAP_PROTOCOL} but received ${String(msg.protocol)}`, line);
-                                return;
-                            }
-                            if (typeof msg.id !== 'number') {
-                                this.handleProtocolError('Invalid response id', line);
-                                return;
-                            }
-                            const pending = this.pending.get(msg.id);
-                            if (!pending) {
-                                this.handleProtocolError(`Unexpected response id ${msg.id}`, line);
-                                return;
-                            }
-                            this.pending.delete(msg.id);
-                            if (pending.timer) {
-                                clearTimeout(pending.timer);
-                            }
-                            if (msg.error) {
-                                pending.reject(this.errorFrom(msg.error));
-                            }
-                            else {
-                                try {
-                                    const decoded = await decodeValueAsync(msg.result);
-                                    pending.resolve(decoded);
-                                }
-                                catch (err) {
-                                    pending.reject(new BridgeProtocolError(`Failed to decode Python response: ${err instanceof Error ? err.message : String(err)}`));
-                                }
-                            }
-                        }
-                        catch (err) {
-                            const parseMessage = err instanceof Error ? err.message : String(err);
-                            this.handleProtocolError(`Invalid JSON: ${parseMessage}`, line);
-                        }
-                    })().catch(() => {
-                        /* ignore */
-                    });
-                }
-            });
-            this.child?.stderr?.on('data', (chunk) => {
-                // Buffer stderr for better error diagnostics on failures/exits
-                try {
-                    this.stderrBuffer += chunk.toString();
-                    // Truncate to last 8KB to avoid unbounded growth
-                    const MAX = 8 * 1024;
-                    if (this.stderrBuffer.length > MAX) {
-                        this.stderrBuffer = this.stderrBuffer.slice(this.stderrBuffer.length - MAX);
-                    }
-                }
-                catch {
-                    // ignore
-                }
-            });
-            this.child?.on('exit', () => {
-                for (const [, p] of this.pending) {
-                    const stderrTail = this.stderrBuffer.trim();
-                    const msg = stderrTail
-                        ? `Python process exited. Stderr:\n${stderrTail}`
-                        : 'Python process exited';
-                    p.reject(new BridgeProtocolError(msg));
+        }
+        else {
+            for (const [key, value] of Object.entries(process.env)) {
+                if (allowedKeys.has(key.toLowerCase()) ||
+                    allowedPrefixes.some(prefix => key.startsWith(prefix))) {
+                    // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+                    baseEnv[key] = value;
                 }
-                this.pending.clear();
-                this.child = undefined;
-                this.initPromise = undefined;
-                this.bridgeInfo = undefined;
-            });
-            await this.refreshBridgeInfo();
+            }
         }
-        catch (err) {
-            this.child?.kill('SIGTERM');
-            this.child = undefined;
-            this.initPromise = undefined;
-            throw err;
+        let env = normalizeEnv(baseEnv, this.options.env);
+        if (this.options.virtualEnv) {
+            const venv = resolveVirtualEnv(this.options.virtualEnv, this.options.cwd);
+            env.VIRTUAL_ENV = venv.venvPath;
+            const pathKey = getPathKey(env);
+            // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+            const currentPath = env[pathKey] ?? '';
+            // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+            env[pathKey] = `${venv.binDir}${delimiter}${currentPath}`;
         }
+        ensurePythonEncoding(env);
+        ensureJsonFallback(env, this.options.enableJsonFallback);
+        env = normalizeEnv(env, {});
+        return env;
     }
     async refreshBridgeInfo() {
-        const info = await this.send({ method: 'meta', params: {} });
-        if (info.protocol !== TYWRAP_PROTOCOL || info.protocolVersion !== TYWRAP_PROTOCOL_VERSION) {
-            throw new BridgeProtocolError('Invalid bridge info payload');
-        }
+        const info = await this.executeRequest({ method: 'meta', params: {} });
+        validateBridgeInfo(info);
         this.bridgeInfo = info;
     }
 }
+/**
+ * @deprecated Use NodeBridge with minProcesses/maxProcesses options instead.
+ * This alias is provided for backward compatibility.
+ */
+export { NodeBridge as OptimizedNodeBridge };
 //# sourceMappingURL=node.js.map