@olane/o-node 0.7.12-alpha.51 → 0.7.12-alpha.53

package/dist/src/connection/o-node-connection.d.ts

@@ -1,9 +1,11 @@
 import { Connection, Stream } from '@olane/o-config';
 import { oConnection, oRequest, oResponse } from '@olane/o-core';
 import { oNodeConnectionConfig } from './interfaces/o-node-connection.config.js';
+import { StreamHandler } from './stream-handler.js';
 export declare class oNodeConnection extends oConnection {
     protected readonly config: oNodeConnectionConfig;
     p2pConnection: Connection;
+    protected streamHandler: StreamHandler;
     constructor(config: oNodeConnectionConfig);
     setupConnectionListeners(): void;
     validate(stream?: Stream): void;

package/dist/src/connection/o-node-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAEL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,qBAAa,eAAgB,SAAQ,WAAW;IAGlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAFrD,aAAa,EAAE,UAAU,CAAC;gBAEF,MAAM,EAAE,qBAAqB;IAM5D,wBAAwB;IAYxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAmBlB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAcpC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA2E/C,YAAY,CAAC,MAAM,EAAE,MAAM;IAU3B,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}
+{"version":3,"file":"o-node-connection.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAEL,WAAW,EAGX,QAAQ,EACR,SAAS,EACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,qBAAa,eAAgB,SAAQ,WAAW;IAIlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAHrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;gBAER,MAAM,EAAE,qBAAqB;IAO5D,wBAAwB;IAYxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAmBlB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBpC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IAsC/C,YAAY,CAAC,MAAM,EAAE,MAAM;IAQ3B,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}

package/dist/src/connection/o-node-connection.js

@@ -1,9 +1,11 @@
-import { CoreUtils, oConnection, oError, oErrorCodes, oResponse, } from '@olane/o-core';
+import { oConnection, oError, oErrorCodes, } from '@olane/o-core';
+import { StreamHandler } from './stream-handler.js';
 export class oNodeConnection extends oConnection {
     constructor(config) {
         super(config);
         this.config = config;
         this.p2pConnection = config.p2pConnection;
+        this.streamHandler = new StreamHandler(this.logger);
         this.setupConnectionListeners();
     }
     setupConnectionListeners() {
@@ -26,16 +28,16 @@ export class oNodeConnection extends oConnection {
         }
     }
     async getOrCreateStream() {
-        if (this.p2pConnection.status !== 'open') {
-            throw new oError(oErrorCodes.INVALID_STATE, 'Connection not open');
-        }
-        return this.p2pConnection.newStream(this.nextHopAddress.protocol, {
+        const streamConfig = {
             signal: this.abortSignal,
             maxOutboundStreams: process.env.MAX_OUTBOUND_STREAMS
                 ? parseInt(process.env.MAX_OUTBOUND_STREAMS)
                 : 1000,
             runOnLimitedConnection: this.config.runOnLimitedConnection ?? false,
-        });
+            reusePolicy: 'none', // Default policy, can be overridden in subclasses
+            drainTimeoutMs: this.config.drainTimeoutMs,
+        };
+        return this.streamHandler.getOrCreateStream(this.p2pConnection, this.nextHopAddress.protocol, streamConfig);
     }
     async transmit(request) {
         try {
@@ -44,54 +46,18 @@ export class oNodeConnection extends oConnection {
             }
             const stream = await this.getOrCreateStream();
             this.validate(stream);
-            // Send the data with backpressure handling (libp2p v3 best practice)
+            const streamConfig = {
+                signal: this.abortSignal,
+                drainTimeoutMs: this.config.drainTimeoutMs,
+                reusePolicy: 'none', // Default policy
+            };
+            // Send the request with backpressure handling
             const data = new TextEncoder().encode(request.toString());
-            const sent = stream.send(data);
-            let lastResponse;
-            await new Promise((resolve, reject) => {
-                const abortHandler = async () => {
-                    try {
-                        await stream.abort(new Error('Request aborted'));
-                    }
-                    catch (e) {
-                        // Stream may already be closed
-                    }
-                    reject(new Error('Request aborted'));
-                };
-                // Listen for abort signal
-                if (this.abortSignal) {
-                    this.abortSignal.addEventListener('abort', abortHandler);
-                }
-                stream.addEventListener('message', async (event) => {
-                    const response = await CoreUtils.processStreamResponse(event);
-                    this.emitter.emit('chunk', response);
-                    // marked as the last chunk let's close
-                    if (response.result._last || !response.result._isStreaming) {
-                        lastResponse = response;
-                        // Clean up abort listener before closing
-                        if (this.abortSignal) {
-                            this.abortSignal.removeEventListener('abort', abortHandler);
-                        }
-                        resolve(true);
-                    }
-                });
-            });
-            stream.addEventListener('close', async () => {
-                this.logger.debug('Stream closed by remote peer, closing connection...');
-                stream.close().catch((error) => {
-                    this.logger.error('Error closing stream: ', error);
-                });
-            });
-            // If send() returns false, wait for the stream to drain before continuing
-            if (!sent) {
-                this.logger.debug('Stream buffer full, waiting for drain...');
-                await stream.onDrain({
-                    signal: AbortSignal.timeout(this.config.drainTimeoutMs ?? 30000),
-                }); // Default: 30 second timeout
-            }
-            // handle cleanup of the stream
+            await this.streamHandler.send(stream, data, streamConfig);
+            // Handle response using StreamHandler
+            const response = await this.streamHandler.handleOutgoingStream(stream, this.emitter, streamConfig);
+            // Handle cleanup of the stream
             await this.postTransmit(stream);
-            const response = oResponse.fromJSON(lastResponse);
             return response;
         }
         catch (error) {
@@ -102,14 +68,10 @@ export class oNodeConnection extends oConnection {
         }
     }
     async postTransmit(stream) {
-        if (stream.status === 'open') {
-            stream.close().catch((error) => {
-                this.logger.error('Error closing stream after transmission: ', error);
-            });
-        }
-        else {
-            this.logger.debug('Stream is not open, skipping cleanup');
-        }
+        const streamConfig = {
+            reusePolicy: 'none', // Default policy, can be overridden in subclasses
+        };
+        await this.streamHandler.close(stream, streamConfig);
     }
     async abort(error) {
         this.logger.debug('Aborting connection');

package/dist/src/connection/o-node-connection.manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAU,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAKhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IAJzD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;gBAElB,MAAM,EAAE,4BAA4B;IAOnD,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;IA2BtB;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IA4BpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;CA0BhE"}
+{"version":3,"file":"o-node-connection.manager.d.ts","sourceRoot":"","sources":["../../../src/connection/o-node-connection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAU,UAAU,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAEhG,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,qBAAa,sBAAuB,SAAQ,kBAAkB;IAKhD,QAAQ,CAAC,MAAM,EAAE,4BAA4B;IAJzD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,oBAAoB,CAAC,CAAS;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAS;gBAElB,MAAM,EAAE,4BAA4B;IAOnD,qBAAqB,CACzB,cAAc,EAAE,QAAQ,EACxB,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,UAAU,CAAC;IA4BtB;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6BlE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IA4BpC;;;;OAIG;IACH,yBAAyB,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,IAAI;CA0BhE"}

package/dist/src/connection/o-node-connection.manager.js

@@ -13,7 +13,8 @@ export class oNodeConnectionManager extends oConnectionManager {
         const existingConnection = this.getCachedLibp2pConnection(nextHopAddress);
         let p2pConnection;
         if (existingConnection && existingConnection.status === 'open') {
-            this.logger.debug('Reusing existing libp2p connection for address: ' + address.toString());
+            this.logger.debug('Reusing existing libp2p connection for address: ' +
+                nextHopAddress.toString());
             p2pConnection = existingConnection;
         }
         else {

package/dist/src/connection/stream-handler.config.d.ts

@@ -0,0 +1,46 @@
+/// <reference types="node" />
+import type { Stream } from '@libp2p/interface';
+/**
+ * Stream reuse policy determines how streams are managed across multiple requests
+ */
+export type StreamReusePolicy = 'none' | 'reuse' | 'pool';
+/**
+ * Configuration for StreamHandler behavior
+ */
+export interface StreamHandlerConfig {
+    /**
+     * Stream reuse policy:
+     * - 'none': Create new stream for each request (default)
+     * - 'reuse': Reuse existing open streams
+     * - 'pool': (Future) Maintain a pool of streams
+     */
+    reusePolicy?: StreamReusePolicy;
+    /**
+     * Timeout in milliseconds to wait for stream drain when buffer is full
+     * @default 30000 (30 seconds)
+     */
+    drainTimeoutMs?: number;
+    /**
+     * Whether this connection can run on limited connections
+     * @default false
+     */
+    runOnLimitedConnection?: boolean;
+    /**
+     * Maximum number of outbound streams
+     * @default 1000
+     */
+    maxOutboundStreams?: number;
+    /**
+     * AbortSignal for cancellation
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Context for stream lifecycle operations
+ */
+export interface StreamContext {
+    stream: Stream;
+    protocol: string;
+    config: StreamHandlerConfig;
+}
+//# sourceMappingURL=stream-handler.config.d.ts.map

package/dist/src/connection/stream-handler.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-handler.config.d.ts","sourceRoot":"","sources":["../../../src/connection/stream-handler.config.ts"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAEhC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;CAC7B"}

package/dist/src/connection/stream-handler.config.js

@@ -0,0 +1 @@
+export {};

package/dist/src/connection/stream-handler.d.ts

@@ -0,0 +1,95 @@
+/// <reference types="node" />
+import type { Connection, Stream } from '@libp2p/interface';
+import { EventEmitter } from 'events';
+import { oRequest, oResponse, Logger } from '@olane/o-core';
+import type { oRouterRequest } from '@olane/o-core';
+import type { oConnection } from '@olane/o-core';
+import type { RunResult } from '@olane/o-tool';
+import type { StreamHandlerConfig } from './stream-handler.config.js';
+/**
+ * StreamHandler centralizes all stream-related functionality including:
+ * - Message type detection (request vs response)
+ * - Stream lifecycle management (create, reuse, close)
+ * - Backpressure handling
+ * - Request/response handling
+ * - Stream routing for middleware nodes
+ */
+export declare class StreamHandler {
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Detects if a decoded message is a request
+     * Requests have a 'method' field and no 'result' field
+     */
+    isRequest(message: any): boolean;
+    /**
+     * Detects if a decoded message is a response
+     * Responses have a 'result' field and no 'method' field
+     */
+    isResponse(message: any): boolean;
+    /**
+     * Decodes a stream message event into a JSON object
+     */
+    decodeMessage(event: any): Promise<any>;
+    /**
+     * Gets an existing open stream or creates a new one based on reuse policy
+     *
+     * @param connection - The libp2p connection
+     * @param protocol - The protocol to use for the stream
+     * @param config - Stream handler configuration
+     */
+    getOrCreateStream(connection: Connection, protocol: string, config?: StreamHandlerConfig): Promise<Stream>;
+    /**
+     * Sends data through a stream with backpressure handling
+     *
+     * @param stream - The stream to send data through
+     * @param data - The data to send
+     * @param config - Configuration for timeout and other options
+     */
+    send(stream: Stream, data: Uint8Array, config?: StreamHandlerConfig): Promise<void>;
+    /**
+     * Closes a stream safely with error handling
+     *
+     * @param stream - The stream to close
+     * @param config - Configuration including reuse policy
+     */
+    close(stream: Stream, config?: StreamHandlerConfig): Promise<void>;
+    /**
+     * Handles an incoming stream on the server side
+     * Attaches message listener immediately (libp2p v3 best practice)
+     * Routes requests or executes tools based on the message
+     *
+     * @param stream - The incoming stream
+     * @param connection - The connection the stream belongs to
+     * @param toolExecutor - Function to execute tools for requests
+     */
+    handleIncomingStream(stream: Stream, connection: Connection, toolExecutor: (request: oRequest, stream: Stream) => Promise<RunResult>): Promise<void>;
+    /**
+     * Handles a request message by executing the tool and sending response
+     *
+     * @param message - The decoded request message
+     * @param stream - The stream to send the response on
+     * @param toolExecutor - Function to execute the tool
+     */
+    private handleRequestMessage;
+    /**
+     * Handles an outgoing stream on the client side
+     * Listens for response messages and emits them via the event emitter
+     *
+     * @param stream - The outgoing stream
+     * @param emitter - Event emitter for chunk events
+     * @param config - Configuration including abort signal
+     * @returns Promise that resolves with the final response
+     */
+    handleOutgoingStream(stream: Stream, emitter: EventEmitter, config?: StreamHandlerConfig): Promise<oResponse>;
+    /**
+     * Forwards a request to the next hop and relays response chunks back
+     * This implements the middleware/proxy pattern for intermediate nodes
+     *
+     * @param request - The router request to forward
+     * @param incomingStream - The stream to send responses back on
+     * @param dialFn - Function to dial the next hop connection
+     */
+    forwardRequest(request: oRouterRequest, incomingStream: Stream, dialFn: (address: string) => Promise<oConnection>): Promise<void>;
+}
+//# sourceMappingURL=stream-handler.d.ts.map

package/dist/src/connection/stream-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-handler.d.ts","sourceRoot":"","sources":["../../../src/connection/stream-handler.ts"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACL,QAAQ,EACR,SAAS,EAIT,MAAM,EAEP,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,CAAC,EAAE,MAAM;IAI3B;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAIhC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAIjC;;OAEG;IACG,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAI7C;;;;;;OAMG;IACG,iBAAiB,CACrB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,MAAM,CAAC;IA2ClB;;;;;;OAMG;IACG,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;OAKG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB5E;;;;;;;;OAQG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,GACtE,OAAO,CAAC,IAAI,CAAC;IA0ChB;;;;;;OAMG;YACW,oBAAoB;IAkBlC;;;;;;;;OAQG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,SAAS,CAAC;IA4FrB;;;;;;;OAOG;IACG,cAAc,CAClB,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC;CAyBjB"}

package/dist/src/connection/stream-handler.js

@@ -0,0 +1,297 @@
+import { oRequest, CoreUtils, oError, oErrorCodes, Logger, ResponseBuilder, } from '@olane/o-core';
+/**
+ * StreamHandler centralizes all stream-related functionality including:
+ * - Message type detection (request vs response)
+ * - Stream lifecycle management (create, reuse, close)
+ * - Backpressure handling
+ * - Request/response handling
+ * - Stream routing for middleware nodes
+ */
+export class StreamHandler {
+    constructor(logger) {
+        this.logger = logger ?? new Logger('StreamHandler');
+    }
+    /**
+     * Detects if a decoded message is a request
+     * Requests have a 'method' field and no 'result' field
+     */
+    isRequest(message) {
+        return typeof message?.method === 'string' && message.result === undefined;
+    }
+    /**
+     * Detects if a decoded message is a response
+     * Responses have a 'result' field and no 'method' field
+     */
+    isResponse(message) {
+        return message?.result !== undefined && message.method === undefined;
+    }
+    /**
+     * Decodes a stream message event into a JSON object
+     */
+    async decodeMessage(event) {
+        return CoreUtils.processStream(event);
+    }
+    /**
+     * Gets an existing open stream or creates a new one based on reuse policy
+     *
+     * @param connection - The libp2p connection
+     * @param protocol - The protocol to use for the stream
+     * @param config - Stream handler configuration
+     */
+    async getOrCreateStream(connection, protocol, config = {}) {
+        if (connection.status !== 'open') {
+            throw new oError(oErrorCodes.INVALID_STATE, 'Connection not open');
+        }
+        const reusePolicy = config.reusePolicy ?? 'none';
+        this.logger.debug('Reuse policy:', reusePolicy);
+        // Check for existing stream if reuse is enabled
+        if (reusePolicy === 'reuse') {
+            this.logger.debug('Reusing existing stream if we can find one. Stream insights:', JSON.stringify({
+                streamCount: connection.streams.length,
+                protocol: protocol,
+            }));
+            connection.streams.forEach((stream) => {
+                this.logger.debug('Stream re-use option:', stream.protocol, stream.status, stream.direction);
+            });
+            const existingStream = connection.streams.find((stream) => stream.status === 'open' && stream.protocol?.length > 0);
+            if (existingStream) {
+                this.logger.debug('Reusing existing stream');
+                return existingStream;
+            }
+        }
+        // Create new stream
+        this.logger.debug('Creating new stream');
+        return connection.newStream(protocol, {
+            signal: config.signal,
+            maxOutboundStreams: config.maxOutboundStreams ?? 1000,
+            runOnLimitedConnection: config.runOnLimitedConnection ?? false,
+        });
+    }
+    /**
+     * Sends data through a stream with backpressure handling
+     *
+     * @param stream - The stream to send data through
+     * @param data - The data to send
+     * @param config - Configuration for timeout and other options
+     */
+    async send(stream, data, config = {}) {
+        // Send the data with backpressure handling (libp2p v3 best practice)
+        const sent = stream.send(data);
+        // If send() returns false, buffer is full - wait for drain
+        if (!sent) {
+            this.logger.debug('Stream buffer full, waiting for drain...');
+            const drainTimeout = config.drainTimeoutMs ?? 30000;
+            await stream.onDrain({
+                signal: AbortSignal.timeout(drainTimeout),
+            });
+            this.logger.debug('Stream drained successfully');
+        }
+    }
+    /**
+     * Closes a stream safely with error handling
+     *
+     * @param stream - The stream to close
+     * @param config - Configuration including reuse policy
+     */
+    async close(stream, config = {}) {
+        // Don't close if reuse policy is enabled
+        if (config.reusePolicy === 'reuse') {
+            this.logger.debug('Stream reuse enabled, not closing stream');
+            return;
+        }
+        if (stream.status === 'open') {
+            try {
+                await stream.close();
+                this.logger.debug('Stream closed successfully');
+            }
+            catch (error) {
+                this.logger.debug('Error closing stream:', error.message);
+            }
+        }
+    }
+    /**
+     * Handles an incoming stream on the server side
+     * Attaches message listener immediately (libp2p v3 best practice)
+     * Routes requests or executes tools based on the message
+     *
+     * @param stream - The incoming stream
+     * @param connection - The connection the stream belongs to
+     * @param toolExecutor - Function to execute tools for requests
+     */
+    async handleIncomingStream(stream, connection, toolExecutor) {
+        // CRITICAL: Attach message listener immediately to prevent buffer overflow (libp2p v3)
+        const messageHandler = async (event) => {
+            try {
+                // avoid processing non-olane messages
+                if (!event.data) {
+                    return;
+                }
+                const message = await this.decodeMessage(event);
+                if (typeof message === 'string') {
+                    // this.logger.warn(
+                    //   'Received string message on server-side stream, ignoring',
+                    //   message,
+                    // );
+                    return;
+                }
+                if (this.isRequest(message)) {
+                    await this.handleRequestMessage(message, stream, toolExecutor);
+                }
+                else if (this.isResponse(message)) {
+                    this.logger.warn('Received response message on server-side stream, ignoring');
+                }
+                else {
+                    this.logger.warn('Received unknown message type', message);
+                }
+            }
+            catch (error) {
+                this.logger.error('Error handling stream message:', error);
+                // Error already logged, stream will be closed by remote peer or timeout
+            }
+        };
+        const closeHandler = () => {
+            this.logger.debug('Stream closed by remote peer');
+            stream.removeEventListener('message', messageHandler);
+            // stream.removeEventListener('close', closeHandler);
+        };
+        stream.addEventListener('message', messageHandler);
+        // stream.addEventListener('close', closeHandler);
+    }
+    /**
+     * Handles a request message by executing the tool and sending response
+     *
+     * @param message - The decoded request message
+     * @param stream - The stream to send the response on
+     * @param toolExecutor - Function to execute the tool
+     */
+    async handleRequestMessage(message, stream, toolExecutor) {
+        const request = new oRequest(message);
+        const responseBuilder = ResponseBuilder.create();
+        try {
+            const result = await toolExecutor(request, stream);
+            const response = await responseBuilder.build(request, result, null);
+            await CoreUtils.sendResponse(response, stream);
+        }
+        catch (error) {
+            const errorResponse = await responseBuilder.buildError(request, error);
+            await CoreUtils.sendResponse(errorResponse, stream);
+        }
+    }
+    /**
+     * Handles an outgoing stream on the client side
+     * Listens for response messages and emits them via the event emitter
+     *
+     * @param stream - The outgoing stream
+     * @param emitter - Event emitter for chunk events
+     * @param config - Configuration including abort signal
+     * @returns Promise that resolves with the final response
+     */
+    async handleOutgoingStream(stream, emitter, config = {}) {
+        return new Promise((resolve, reject) => {
+            let lastResponse;
+            const messageHandler = async (event) => {
+                // avoid processing non-olane messages
+                if (!event.data) {
+                    return;
+                }
+                try {
+                    const message = await this.decodeMessage(event);
+                    if (typeof message === 'string') {
+                        // this.logger.warn(
+                        //   'Received string message on server-side stream, ignoring',
+                        //   message,
+                        // );
+                        return;
+                    }
+                    if (this.isResponse(message)) {
+                        const response = await CoreUtils.processStreamResponse(event);
+                        // Emit chunk for streaming responses
+                        emitter.emit('chunk', response);
+                        // Check if this is the last chunk
+                        if (response.result._last || !response.result._isStreaming) {
+                            lastResponse = response;
+                            cleanup();
+                            resolve(response);
+                        }
+                    }
+                    else if (this.isRequest(message)) {
+                        this.logger.warn('Received request message on client-side stream, ignoring');
+                    }
+                    else {
+                        this.logger.warn('Received unknown message type', message);
+                    }
+                }
+                catch (error) {
+                    this.logger.error('Error handling response message:', error);
+                    cleanup();
+                    reject(error);
+                }
+            };
+            const closeHandler = () => {
+                this.logger.debug('Stream closed by remote peer');
+                cleanup();
+                if (lastResponse) {
+                    resolve(lastResponse);
+                }
+                else {
+                    reject(new oError(oErrorCodes.TIMEOUT, 'Stream closed before response received'));
+                }
+            };
+            const abortHandler = () => {
+                this.logger.debug('Request aborted');
+                cleanup();
+                try {
+                    stream.abort(new Error('Request aborted'));
+                }
+                catch (error) {
+                    this.logger.debug('Error aborting stream:', error.message);
+                }
+                reject(new oError(oErrorCodes.TIMEOUT, 'Request aborted'));
+            };
+            const cleanup = () => {
+                stream.removeEventListener('message', messageHandler);
+                // stream.removeEventListener('close', closeHandler);
+                if (config.signal) {
+                    config.signal.removeEventListener('abort', abortHandler);
+                }
+            };
+            stream.addEventListener('message', messageHandler);
+            // stream.addEventListener('close', closeHandler);
+            if (config.signal) {
+                config.signal.addEventListener('abort', abortHandler);
+            }
+        });
+    }
+    /**
+     * Forwards a request to the next hop and relays response chunks back
+     * This implements the middleware/proxy pattern for intermediate nodes
+     *
+     * @param request - The router request to forward
+     * @param incomingStream - The stream to send responses back on
+     * @param dialFn - Function to dial the next hop connection
+     */
+    async forwardRequest(request, incomingStream, dialFn) {
+        try {
+            // Connect to next hop
+            const nextHopConnection = await dialFn(request.params.address);
+            // Set up chunk relay - forward responses from next hop back to incoming stream
+            nextHopConnection.onChunk(async (response) => {
+                try {
+                    await CoreUtils.sendStreamResponse(response, incomingStream);
+                }
+                catch (error) {
+                    this.logger.error('Error forwarding chunk:', error);
+                }
+            });
+            // Transmit the request to next hop
+            await nextHopConnection.transmit(request);
+        }
+        catch (error) {
+            this.logger.error('Error forwarding request:', error);
+            // Send error response back on incoming stream using ResponseBuilder
+            const responseBuilder = ResponseBuilder.create();
+            const errorResponse = await responseBuilder.buildError(request, error);
+            await CoreUtils.sendResponse(errorResponse, incomingStream);
+        }
+    }
+}

package/dist/src/connection/stream-handler.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stream-handler.spec.d.ts.map

package/dist/src/connection/stream-handler.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-handler.spec.d.ts","sourceRoot":"","sources":["../../../src/connection/stream-handler.spec.ts"],"names":[],"mappings":""}

package/dist/src/connection/stream-handler.spec.js

@@ -0,0 +1,309 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { StreamHandler } from './stream-handler.js';
+import { EventEmitter } from 'events';
+import { oError, oErrorCodes } from '@o/o-core/src/error/o-error';
+// Mock Stream interface
+const createMockStream = (status = 'open') => {
+    const listeners = new Map();
+    return {
+        status,
+        send: vi.fn().mockReturnValue(true),
+        close: vi.fn().mockResolvedValue(undefined),
+        abort: vi.fn().mockResolvedValue(undefined),
+        onDrain: vi.fn().mockResolvedValue(undefined),
+        addEventListener: vi.fn((event, handler) => {
+            if (!listeners.has(event)) {
+                listeners.set(event, []);
+            }
+            listeners.get(event)?.push(handler);
+        }),
+        removeEventListener: vi.fn((event, handler) => {
+            const handlers = listeners.get(event);
+            if (handlers) {
+                const index = handlers.indexOf(handler);
+                if (index > -1) {
+                    handlers.splice(index, 1);
+                }
+            }
+        }),
+        // Helper to trigger events in tests
+        _triggerEvent: (event, data) => {
+            listeners.get(event)?.forEach((handler) => handler(data));
+        },
+    };
+};
+// Mock Connection interface
+const createMockConnection = (status = 'open') => {
+    return {
+        status,
+        streams: [],
+        newStream: vi.fn().mockImplementation(() => createMockStream()),
+    };
+};
+describe('StreamHandler', () => {
+    let streamHandler;
+    beforeEach(() => {
+        streamHandler = new StreamHandler();
+    });
+    describe('Message Type Detection', () => {
+        it('should identify a request message', () => {
+            const message = {
+                jsonrpc: '2.0',
+                id: '1',
+                method: 'test_method',
+                params: {},
+            };
+            expect(streamHandler.isRequest(message)).toBe(true);
+            expect(streamHandler.isResponse(message)).toBe(false);
+        });
+        it('should identify a response message', () => {
+            const message = {
+                jsonrpc: '2.0',
+                id: '1',
+                result: { success: true },
+            };
+            expect(streamHandler.isResponse(message)).toBe(true);
+            expect(streamHandler.isRequest(message)).toBe(false);
+        });
+        it('should not identify malformed message as request or response', () => {
+            const message = {
+                jsonrpc: '2.0',
+                id: '1',
+            };
+            expect(streamHandler.isRequest(message)).toBe(false);
+            expect(streamHandler.isResponse(message)).toBe(false);
+        });
+        it('should handle message with both method and result', () => {
+            const message = {
+                jsonrpc: '2.0',
+                id: '1',
+                method: 'test',
+                result: {},
+            };
+            // Should identify as request since method is present
+            expect(streamHandler.isRequest(message)).toBe(true);
+            expect(streamHandler.isResponse(message)).toBe(false);
+        });
+    });
+    describe('Stream Lifecycle - getOrCreateStream', () => {
+        it('should create a new stream with none reuse policy', async () => {
+            const connection = createMockConnection();
+            const protocol = '/test/1.0.0';
+            const stream = await streamHandler.getOrCreateStream(connection, protocol, {
+                reusePolicy: 'none',
+            });
+            expect(stream).toBeDefined();
+            expect(connection.newStream).toHaveBeenCalledWith(protocol, expect.any(Object));
+        });
+        it('should reuse existing stream with reuse policy', async () => {
+            const existingStream = createMockStream();
+            const connection = createMockConnection();
+            connection.streams = [existingStream];
+            const stream = await streamHandler.getOrCreateStream(connection, '/test/1.0.0', { reusePolicy: 'reuse' });
+            expect(stream).toBe(existingStream);
+            expect(connection.newStream).not.toHaveBeenCalled();
+        });
+        it('should create new stream when no open stream exists with reuse policy', async () => {
+            const closedStream = createMockStream('closed');
+            const connection = createMockConnection();
+            connection.streams = [closedStream];
+            const stream = await streamHandler.getOrCreateStream(connection, '/test/1.0.0', { reusePolicy: 'reuse' });
+            expect(stream).not.toBe(closedStream);
+            expect(connection.newStream).toHaveBeenCalled();
+        });
+        it('should throw error when connection is not open', async () => {
+            const connection = createMockConnection('closed');
+            await expect(streamHandler.getOrCreateStream(connection, '/test/1.0.0')).rejects.toThrow();
+        });
+        it('should pass configuration options to newStream', async () => {
+            const connection = createMockConnection();
+            const signal = new AbortController().signal;
+            await streamHandler.getOrCreateStream(connection, '/test/1.0.0', {
+                signal,
+                maxOutboundStreams: 500,
+                runOnLimitedConnection: true,
+            });
+            expect(connection.newStream).toHaveBeenCalledWith('/test/1.0.0', {
+                signal,
+                maxOutboundStreams: 500,
+                runOnLimitedConnection: true,
+            });
+        });
+    });
+    describe('Stream Lifecycle - send', () => {
+        it('should send data without backpressure', async () => {
+            const stream = createMockStream();
+            stream.send = vi.fn().mockReturnValue(true);
+            const data = new TextEncoder().encode('test data');
+            await streamHandler.send(stream, data);
+            expect(stream.send).toHaveBeenCalledWith(data);
+            expect(stream.onDrain).not.toHaveBeenCalled();
+        });
+        it('should wait for drain when backpressure occurs', async () => {
+            const stream = createMockStream();
+            stream.send = vi.fn().mockReturnValue(false);
+            const data = new TextEncoder().encode('test data');
+            await streamHandler.send(stream, data, { drainTimeoutMs: 5000 });
+            expect(stream.send).toHaveBeenCalledWith(data);
+            expect(stream.onDrain).toHaveBeenCalledWith({
+                signal: expect.any(AbortSignal),
+            });
+        });
+    });
+    describe('Stream Lifecycle - close', () => {
+        it('should close stream when reuse policy is none', async () => {
+            const stream = createMockStream();
+            await streamHandler.close(stream, { reusePolicy: 'none' });
+            expect(stream.close).toHaveBeenCalled();
+        });
+        it('should not close stream when reuse policy is reuse', async () => {
+            const stream = createMockStream();
+            await streamHandler.close(stream, { reusePolicy: 'reuse' });
+            expect(stream.close).not.toHaveBeenCalled();
+        });
+        it('should not close stream when status is not open', async () => {
+            const stream = createMockStream('closed');
+            await streamHandler.close(stream, { reusePolicy: 'none' });
+            expect(stream.close).not.toHaveBeenCalled();
+        });
+        it('should handle errors during close gracefully', async () => {
+            const stream = createMockStream();
+            stream.close = vi.fn().mockRejectedValue(new Error('Close failed'));
+            // Should not throw
+            await expect(streamHandler.close(stream)).resolves.toBeUndefined();
+        });
+    });
+    describe('Server-side - handleIncomingStream', () => {
+        it('should attach message listener immediately', async () => {
+            const stream = createMockStream();
+            const connection = createMockConnection();
+            const toolExecutor = vi.fn().mockResolvedValue({ success: true });
+            await streamHandler.handleIncomingStream(stream, connection, toolExecutor);
+            expect(stream.addEventListener).toHaveBeenCalledWith('message', expect.any(Function));
+            expect(stream.addEventListener).toHaveBeenCalledWith('close', expect.any(Function));
+        });
+        it('should execute tool when request message is received', async () => {
+            const stream = createMockStream();
+            const connection = createMockConnection();
+            const toolExecutor = vi.fn().mockResolvedValue({ success: true });
+            await streamHandler.handleIncomingStream(stream, connection, toolExecutor);
+            // Simulate receiving a request
+            const requestData = {
+                data: new TextEncoder().encode(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: '1',
+                    method: 'test_method',
+                    params: {},
+                })),
+            };
+            stream._triggerEvent('message', requestData);
+            // Wait for async handling
+            await new Promise(resolve => setTimeout(resolve, 10));
+            expect(toolExecutor).toHaveBeenCalled();
+        });
+        it('should send error response when tool execution fails', async () => {
+            const stream = createMockStream();
+            const connection = createMockConnection();
+            const toolExecutor = vi.fn().mockRejectedValue(new oError(oErrorCodes.INTERNAL_ERROR, 'Tool execution failed'));
+            await streamHandler.handleIncomingStream(stream, connection, toolExecutor);
+            const requestData = {
+                data: new TextEncoder().encode(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: '1',
+                    method: 'test_method',
+                    params: {},
+                })),
+            };
+            stream._triggerEvent('message', requestData);
+            // Wait for async handling
+            await new Promise(resolve => setTimeout(resolve, 10));
+            expect(stream.send).toHaveBeenCalled();
+        });
+        it('should clean up listeners on stream close', async () => {
+            const stream = createMockStream();
+            const connection = createMockConnection();
+            const toolExecutor = vi.fn();
+            await streamHandler.handleIncomingStream(stream, connection, toolExecutor);
+            stream._triggerEvent('close', {});
+            expect(stream.removeEventListener).toHaveBeenCalledWith('message', expect.any(Function));
+            expect(stream.removeEventListener).toHaveBeenCalledWith('close', expect.any(Function));
+        });
+    });
+    describe('Client-side - handleOutgoingStream', () => {
+        it('should resolve with response when final chunk received', async () => {
+            const stream = createMockStream();
+            const emitter = new EventEmitter();
+            const responsePromise = streamHandler.handleOutgoingStream(stream, emitter);
+            // Simulate receiving a final response
+            const responseData = {
+                data: new TextEncoder().encode(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: '1',
+                    result: { _last: true, success: true },
+                })),
+            };
+            stream._triggerEvent('message', responseData);
+            const response = await responsePromise;
+            expect(response).toBeDefined();
+            expect(response.result._last).toBe(true);
+        });
+        it('should emit chunks for streaming responses', async () => {
+            const stream = createMockStream();
+            const emitter = new EventEmitter();
+            const chunkListener = vi.fn();
+            emitter.on('chunk', chunkListener);
+            const responsePromise = streamHandler.handleOutgoingStream(stream, emitter);
+            // Send a chunk
+            const chunkData = {
+                data: new TextEncoder().encode(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: '1',
+                    result: { _isStreaming: true, _last: false, data: 'chunk 1' },
+                })),
+            };
+            stream._triggerEvent('message', chunkData);
+            // Wait for async handling
+            await new Promise(resolve => setTimeout(resolve, 10));
+            expect(chunkListener).toHaveBeenCalled();
+            // Send final chunk
+            const finalData = {
+                data: new TextEncoder().encode(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: '1',
+                    result: { _isStreaming: true, _last: true, data: 'final chunk' },
+                })),
+            };
+            stream._triggerEvent('message', finalData);
+            await responsePromise;
+        });
+        it('should reject when stream closes before response', async () => {
+            const stream = createMockStream();
+            const emitter = new EventEmitter();
+            const responsePromise = streamHandler.handleOutgoingStream(stream, emitter);
+            stream._triggerEvent('close', {});
+            await expect(responsePromise).rejects.toThrow();
+        });
+        it('should handle abort signal', async () => {
+            const stream = createMockStream();
+            const emitter = new EventEmitter();
+            const abortController = new AbortController();
+            const responsePromise = streamHandler.handleOutgoingStream(stream, emitter, {
+                signal: abortController.signal,
+            });
+            abortController.abort();
+            // Wait for abort to be processed
+            await new Promise(resolve => setTimeout(resolve, 10));
+            await expect(responsePromise).rejects.toThrow();
+            expect(stream.abort).toHaveBeenCalled();
+        });
+    });
+    describe('Message Decoding', () => {
+        it('should decode Uint8Array message', async () => {
+            const testData = { test: 'data' };
+            const encoded = new TextEncoder().encode(JSON.stringify(testData));
+            const event = { data: encoded };
+            const decoded = await streamHandler.decodeMessage(event);
+            expect(decoded).toEqual(testData);
+        });
+    });
+});

package/dist/src/o-node.tool.d.ts

@@ -8,6 +8,7 @@ declare const oNodeTool_base: typeof oServerNode;
  * @returns A new class that extends the base class and implements the oTool interface
  */
 export declare class oNodeTool extends oNodeTool_base {
+    private streamHandler;
     handleProtocol(address: oAddress): Promise<void>;
     initialize(): Promise<void>;
     handleStream(stream: Stream, connection: Connection): Promise<void>;

package/dist/src/o-node.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,EAGR,QAAQ,EAIT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAIrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IACzC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAUhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA+CnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CA2B5D"}
+{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EAET,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAKrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IAC/C,OAAO,CAAC,aAAa,CAAiB;IAEhC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAUhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CA2B5D"}

package/dist/src/o-node.tool.js

@@ -1,8 +1,9 @@
-import { CoreUtils, oRequest, ResponseBuilder, ChildJoinedEvent, } from '@olane/o-core';
+import { ChildJoinedEvent, } from '@olane/o-core';
 import { oTool } from '@olane/o-tool';
 import { oServerNode } from './nodes/server.node.js';
 import { oNodeTransport } from './router/o-node.transport.js';
 import { oNodeAddress } from './router/o-node.address.js';
+import { StreamHandler } from './connection/stream-handler.js';
 /**
  * oTool is a mixin that extends the base class and implements the oTool interface
  * @param Base - The base class to extend
@@ -20,6 +21,7 @@ export class oNodeTool extends oTool(oServerNode) {
     }
     async initialize() {
         await super.initialize();
+        this.streamHandler = new StreamHandler(this.logger);
         await this.handleProtocol(this.address);
         if (this.staticAddress &&
             this.staticAddress?.toString() !== this.address.toString()) {
@@ -28,37 +30,18 @@ export class oNodeTool extends oTool(oServerNode) {
     }
     async handleStream(stream, connection) {
         this.logger.debug('Handling connection: ', connection.id);
-        // CRITICAL: Attach message listener immediately to prevent buffer overflow (libp2p v3)
-        // Per libp2p migration guide: "If no message event handler is added, streams will
-        // buffer incoming data until a pre-configured limit is reached, after which the stream will be reset."
-        const messageHandler = async (event) => {
-            if (!event.data) {
-                this.logger.warn('Malformed event data');
-                return;
-            }
-            const requestConfig = await CoreUtils.processStream(event);
-            const request = new oRequest(requestConfig);
-            // Use ResponseBuilder with automatic error handling and metrics tracking
-            const responseBuilder = ResponseBuilder.create().withMetrics(this.metrics);
-            let response;
+        // Use StreamHandler for consistent stream handling
+        // This follows libp2p v3 best practices for immediate message listener attachment
+        await this.streamHandler.handleIncomingStream(stream, connection, async (request, stream) => {
             try {
                 const result = await this.execute(request, stream);
-                response = await responseBuilder.build(request, result, null);
+                // Return the raw result - StreamHandler will build and send the response
+                return result;
             }
             catch (error) {
                 this.logger.error('Error executing tool: ', request.toString(), error, typeof error);
-                response = await responseBuilder.buildError(request, error);
+                throw error; // StreamHandler will handle error response building
             }
-            // Send the response
-            await CoreUtils.sendResponse(response, stream);
-        };
-        // Attach listener synchronously before any async operations
-        stream.addEventListener('message', messageHandler);
-        stream.addEventListener('close', () => {
-            this.logger.debug('Stream closed by remote peer');
-            stream.close().catch((error) => {
-                this.logger.error('Error closing stream: ', error);
-            });
         });
     }
     async _tool_identify() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.12-alpha.51",
+  "version": "0.7.12-alpha.53",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -54,12 +54,12 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.7.12-alpha.51",
-    "@olane/o-core": "0.7.12-alpha.51",
-    "@olane/o-protocol": "0.7.12-alpha.51",
-    "@olane/o-tool": "0.7.12-alpha.51",
+    "@olane/o-config": "0.7.12-alpha.53",
+    "@olane/o-core": "0.7.12-alpha.53",
+    "@olane/o-protocol": "0.7.12-alpha.53",
+    "@olane/o-tool": "0.7.12-alpha.53",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0"
   },
-  "gitHead": "b877e1e95a2bf32845ec30072eb72422fd25aba7"
+  "gitHead": "f6cd4162b80dd265aba3a8bf322a009fa0ff81e4"
 }