@olane/o-node 0.7.39 → 0.7.40

package/dist/src/connection/index.d.ts

@@ -2,4 +2,6 @@ export * from './o-node-connection.js';
 export * from './o-node-connection.manager.js';
 export * from './interfaces/o-node-connection.config.js';
 export * from './interfaces/o-node-connection-manager.config.js';
+export * from './o-managed-stream.js';
+export * from './stream-handler.config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/connection/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/connection/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0CAA0C,CAAC;AACzD,cAAc,kDAAkD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/connection/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0CAA0C,CAAC;AACzD,cAAc,kDAAkD,CAAC;AACjE,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}

package/dist/src/connection/index.js

@@ -2,3 +2,5 @@ export * from './o-node-connection.js';
 export * from './o-node-connection.manager.js';
 export * from './interfaces/o-node-connection.config.js';
 export * from './interfaces/o-node-connection-manager.config.js';
+export * from './o-managed-stream.js';
+export * from './stream-handler.config.js';

package/dist/src/connection/o-managed-stream.d.ts

@@ -0,0 +1,57 @@
+import type { Stream } from '@libp2p/interface';
+import type { oAddress } from '@olane/o-core';
+/**
+ * oManagedStream wraps a libp2p Stream with caller/receiver address metadata
+ * to enable proper stream reuse based on address pairs rather than protocol only.
+ *
+ * Key features:
+ * - Bidirectional cache keys: A↔B === B↔A
+ * - Automatic reusability checking
+ * - Idle time tracking for cleanup
+ */
+export declare class oManagedStream {
+    readonly stream: Stream;
+    readonly callerAddress: oAddress;
+    readonly receiverAddress: oAddress;
+    readonly direction: 'inbound' | 'outbound';
+    readonly createdAt: number;
+    private _lastUsedAt;
+    constructor(stream: Stream, callerAddress: oAddress, receiverAddress: oAddress, direction: 'inbound' | 'outbound');
+    /**
+     * Generates a bidirectional cache key from caller and receiver addresses.
+     * The key is symmetric: A↔B === B↔A
+     *
+     * @returns Cache key string in format "address1↔address2" (sorted)
+     */
+    get cacheKey(): string;
+    /**
+     * Checks if the stream is in a reusable state:
+     * - Stream status is 'open'
+     * - Write status is 'writable'
+     * - Remote read status is 'readable'
+     *
+     * @returns true if stream can be reused
+     */
+    get isReusable(): boolean;
+    /**
+     * Gets the last used timestamp
+     */
+    get lastUsedAt(): number;
+    /**
+     * Gets the age of the stream in milliseconds
+     */
+    get age(): number;
+    /**
+     * Gets the idle time in milliseconds since last use
+     */
+    get idleTime(): number;
+    /**
+     * Updates the last used timestamp to now
+     */
+    updateLastUsed(): void;
+    /**
+     * Gets a string representation of the managed stream for debugging
+     */
+    toString(): string;
+}
+//# sourceMappingURL=o-managed-stream.d.ts.map

package/dist/src/connection/o-managed-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-managed-stream.d.ts","sourceRoot":"","sources":["../../../src/connection/o-managed-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;GAQG;AACH,qBAAa,cAAc;aAKP,MAAM,EAAE,MAAM;aACd,aAAa,EAAE,QAAQ;aACvB,eAAe,EAAE,QAAQ;aACzB,SAAS,EAAE,SAAS,GAAG,UAAU;IAPnD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,WAAW,CAAS;gBAGV,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,QAAQ,EACvB,eAAe,EAAE,QAAQ,EACzB,SAAS,EAAE,SAAS,GAAG,UAAU;IAMnD;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,MAAM,CAQrB;IAED;;;;;;;OAOG;IACH,IAAI,UAAU,IAAI,OAAO,CAMxB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/src/connection/o-managed-stream.js

@@ -0,0 +1,76 @@
+/**
+ * oManagedStream wraps a libp2p Stream with caller/receiver address metadata
+ * to enable proper stream reuse based on address pairs rather than protocol only.
+ *
+ * Key features:
+ * - Bidirectional cache keys: A↔B === B↔A
+ * - Automatic reusability checking
+ * - Idle time tracking for cleanup
+ */
+export class oManagedStream {
+    constructor(stream, callerAddress, receiverAddress, direction) {
+        this.stream = stream;
+        this.callerAddress = callerAddress;
+        this.receiverAddress = receiverAddress;
+        this.direction = direction;
+        this.createdAt = Date.now();
+        this._lastUsedAt = this.createdAt;
+    }
+    /**
+     * Generates a bidirectional cache key from caller and receiver addresses.
+     * The key is symmetric: A↔B === B↔A
+     *
+     * @returns Cache key string in format "address1↔address2" (sorted)
+     */
+    get cacheKey() {
+        // Sort addresses to ensure bidirectionality
+        const addresses = [
+            this.callerAddress.value,
+            this.receiverAddress.value,
+        ].sort();
+        return `${addresses[0]}↔${addresses[1]}`;
+    }
+    /**
+     * Checks if the stream is in a reusable state:
+     * - Stream status is 'open'
+     * - Write status is 'writable'
+     * - Remote read status is 'readable'
+     *
+     * @returns true if stream can be reused
+     */
+    get isReusable() {
+        return (this.stream.status === 'open' &&
+            this.stream.writeStatus === 'writable' &&
+            this.stream.remoteReadStatus === 'readable');
+    }
+    /**
+     * Gets the last used timestamp
+     */
+    get lastUsedAt() {
+        return this._lastUsedAt;
+    }
+    /**
+     * Gets the age of the stream in milliseconds
+     */
+    get age() {
+        return Date.now() - this.createdAt;
+    }
+    /**
+     * Gets the idle time in milliseconds since last use
+     */
+    get idleTime() {
+        return Date.now() - this._lastUsedAt;
+    }
+    /**
+     * Updates the last used timestamp to now
+     */
+    updateLastUsed() {
+        this._lastUsedAt = Date.now();
+    }
+    /**
+     * Gets a string representation of the managed stream for debugging
+     */
+    toString() {
+        return `oManagedStream(${this.cacheKey}, ${this.direction}, ${this.stream.status})`;
+    }
+}

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;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAEpC,qBAAa,eAAgB,SAAQ,WAAW;IAKlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAJrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,iBAAiB,CAAC;gBAEV,MAAM,EAAE,qBAAqB;IAO5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAmBlB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBpC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA2C/C,YAAY,CAAC,MAAM,EAAE,MAAM;IAQ3B,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;AACpD,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAEpC,qBAAa,eAAgB,SAAQ,WAAW;IAKlC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAJrD,aAAa,EAAE,UAAU,CAAC;IACjC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,WAAW,EAAE,iBAAiB,CAAC;gBAEV,MAAM,EAAE,qBAAqB;IAO5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAmBlB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IA6BpC,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;IA2C/C,YAAY,CAAC,MAAM,EAAE,MAAM;IAQ3B,KAAK,CAAC,KAAK,EAAE,KAAK;IAMlB,KAAK;CAKZ"}

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

@@ -30,7 +30,15 @@ export class oNodeConnection extends oConnection {
             reusePolicy: this.reusePolicy,
             drainTimeoutMs: this.config.drainTimeoutMs,
         };
-        return this.streamHandler.getOrCreateStream(this.p2pConnection, this.nextHopAddress.protocol, streamConfig);
+        // Build stream addresses for address-based caching
+        const streamAddresses = this.callerAddress && this.nextHopAddress
+            ? {
+                callerAddress: this.callerAddress,
+                receiverAddress: this.nextHopAddress,
+                direction: 'outbound',
+            }
+            : undefined;
+        return this.streamHandler.getOrCreateStream(this.p2pConnection, this.nextHopAddress.protocol, streamConfig, streamAddresses);
     }
     async transmit(request) {
         try {

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

@@ -34,6 +34,17 @@ export interface StreamHandlerConfig {
      * AbortSignal for cancellation
      */
     signal?: AbortSignal;
+    /**
+     * Maximum number of streams to cache
+     * Older streams will be evicted when limit is reached
+     * @default unlimited
+     */
+    maxCachedStreams?: number;
+    /**
+     * Time in milliseconds after which idle cached streams are closed
+     * @default unlimited (streams remain cached until closed by peer)
+     */
+    streamIdleTimeout?: number;
 }
 /**
  * Context for stream lifecycle operations

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

@@ -1 +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"}
+{"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;IAErB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;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.d.ts

@@ -4,8 +4,9 @@ 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 { oAddress } from '@olane/o-core';
 import type { RunResult } from '@olane/o-tool';
-import type { StreamHandlerConfig } from './stream-handler.config.js';
+import type { StreamHandlerConfig, StreamReusePolicy } from './stream-handler.config.js';
 /**
  * StreamHandler centralizes all stream-related functionality including:
  * - Message type detection (request vs response)
@@ -16,6 +17,7 @@ import type { StreamHandlerConfig } from './stream-handler.config.js';
  */
 export declare class StreamHandler {
     private logger;
+    private streamCache;
     constructor(logger?: Logger);
     /**
      * Detects if a decoded message is a request
@@ -40,14 +42,64 @@ export declare class StreamHandler {
      * @throws Error if JSON parsing fails even with JSON5 fallback
      */
     private extractAndParseJSON;
+    /**
+     * Builds a bidirectional cache key from caller and receiver addresses
+     * The key is symmetric: A↔B === B↔A
+     *
+     * @param callerAddress - The caller's address
+     * @param receiverAddress - The receiver's address
+     * @returns Cache key string
+     */
+    private buildCacheKey;
+    /**
+     * Caches a managed stream for reuse
+     *
+     * @param managedStream - The managed stream to cache
+     */
+    private cacheStream;
+    /**
+     * Removes a stream from the cache
+     *
+     * @param stream - The stream to remove
+     */
+    private removeStreamFromCache;
+    /**
+     * Sets up cleanup listener for stream close events
+     *
+     * @param stream - The stream to monitor
+     */
+    private setupStreamCleanup;
+    /**
+     * Extracts the remote peer's address from a connection
+     * Falls back to creating an address from the peer ID if no address metadata is available
+     *
+     * @param connection - The libp2p connection
+     * @returns The remote peer's oAddress
+     */
+    extractRemotePeerAddress(connection: Connection): oAddress;
+    /**
+     * Caches an inbound stream for bidirectional reuse
+     * This allows the same stream to be reused for responses
+     *
+     * @param stream - The inbound stream to cache
+     * @param callerAddress - The address of the caller
+     * @param receiverAddress - The address of the receiver (local node)
+     * @param reusePolicy - Whether to enable caching
+     */
+    cacheInboundStream(stream: Stream, callerAddress: oAddress, receiverAddress: oAddress, reusePolicy?: StreamReusePolicy): void;
     /**
      * 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
+     * @param streamAddresses - Optional addresses for address-based stream reuse
      */
-    getOrCreateStream(connection: Connection, protocol: string, config?: StreamHandlerConfig): Promise<Stream>;
+    getOrCreateStream(connection: Connection, protocol: string, config?: StreamHandlerConfig, streamAddresses?: {
+        callerAddress: oAddress;
+        receiverAddress: oAddress;
+        direction: 'inbound' | 'outbound';
+    }): Promise<Stream>;
     /**
      * Sends data through a stream using length-prefixed encoding (libp2p v3 best practice)
      * Each message is automatically prefixed with a varint indicating the message length

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

@@ -1 +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;AAItE;;;;;;;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;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAqC3B;;;;;;OAMG;IACG,iBAAiB,CACrB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,MAAM,CAAC;IAwDlB;;;;;;;;OAQG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,MAAM,GAAE,mBAAwB,GAC/B,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;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;IA+BhB;;;;;;OAMG;YACW,oBAAoB;IA6BlC;;;;;;;;;;OAUG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,mBAAwB,EAChC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,EAC1E,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAC1B,OAAO,CAAC,SAAS,CAAC;IAiErB;;;;;;;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"}
+{"version":3,"file":"stream-handler.d.ts","sourceRoot":"","sources":["../../../src/connection/stream-handler.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 import { oRequest, oResponse, CoreUtils, oError, oErrorCodes, Logger, ResponseBuilder, } from '@olane/o-core';
 import { lpStream } from '@olane/o-config';
 import JSON5 from 'json5';
+import { oManagedStream } from './o-managed-stream.js';
 /**
  * StreamHandler centralizes all stream-related functionality including:
  * - Message type detection (request vs response)
@@ -11,6 +12,7 @@ import JSON5 from 'json5';
  */
 export class StreamHandler {
     constructor(logger) {
+        this.streamCache = new Map();
         this.logger = logger ?? new Logger('StreamHandler');
     }
     /**
@@ -71,48 +73,171 @@ export class StreamHandler {
             }
         }
     }
+    /**
+     * Builds a bidirectional cache key from caller and receiver addresses
+     * The key is symmetric: A↔B === B↔A
+     *
+     * @param callerAddress - The caller's address
+     * @param receiverAddress - The receiver's address
+     * @returns Cache key string
+     */
+    buildCacheKey(callerAddress, receiverAddress) {
+        const addresses = [callerAddress.value, receiverAddress.value].sort();
+        return `${addresses[0]}↔${addresses[1]}`;
+    }
+    /**
+     * Caches a managed stream for reuse
+     *
+     * @param managedStream - The managed stream to cache
+     */
+    cacheStream(managedStream) {
+        this.streamCache.set(managedStream.cacheKey, managedStream);
+        this.logger.debug('Cached stream', {
+            cacheKey: managedStream.cacheKey,
+            direction: managedStream.direction,
+            streamId: managedStream.stream.id,
+        });
+    }
+    /**
+     * Removes a stream from the cache
+     *
+     * @param stream - The stream to remove
+     */
+    removeStreamFromCache(stream) {
+        // Find and remove the stream from cache
+        for (const [key, managedStream] of this.streamCache.entries()) {
+            if (managedStream.stream.id === stream.id) {
+                this.streamCache.delete(key);
+                this.logger.debug('Removed stream from cache', {
+                    cacheKey: key,
+                    streamId: stream.id,
+                });
+                break;
+            }
+        }
+    }
+    /**
+     * Sets up cleanup listener for stream close events
+     *
+     * @param stream - The stream to monitor
+     */
+    setupStreamCleanup(stream) {
+        // Listen for stream close event
+        stream.addEventListener('close', () => {
+            this.removeStreamFromCache(stream);
+        });
+    }
+    /**
+     * Extracts the remote peer's address from a connection
+     * Falls back to creating an address from the peer ID if no address metadata is available
+     *
+     * @param connection - The libp2p connection
+     * @returns The remote peer's oAddress
+     */
+    extractRemotePeerAddress(connection) {
+        // Try to get address from connection metadata if available
+        // For now, create address from peer ID as fallback
+        const peerId = connection.remotePeer.toString();
+        // Import oAddress at runtime to avoid circular dependency
+        const { oAddress: oAddressClass } = require('@olane/o-core');
+        return new oAddressClass(`o://peer/${peerId}`);
+    }
+    /**
+     * Caches an inbound stream for bidirectional reuse
+     * This allows the same stream to be reused for responses
+     *
+     * @param stream - The inbound stream to cache
+     * @param callerAddress - The address of the caller
+     * @param receiverAddress - The address of the receiver (local node)
+     * @param reusePolicy - Whether to enable caching
+     */
+    cacheInboundStream(stream, callerAddress, receiverAddress, reusePolicy = 'none') {
+        if (reusePolicy !== 'reuse') {
+            return;
+        }
+        const cacheKey = this.buildCacheKey(callerAddress, receiverAddress);
+        // Check if already cached
+        if (this.streamCache.has(cacheKey)) {
+            this.logger.debug('Stream already cached', { cacheKey });
+            return;
+        }
+        const managedStream = new oManagedStream(stream, callerAddress, receiverAddress, 'inbound');
+        this.cacheStream(managedStream);
+        this.setupStreamCleanup(stream);
+    }
     /**
      * 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
+     * @param streamAddresses - Optional addresses for address-based stream reuse
      */
-    async getOrCreateStream(connection, protocol, config = {}) {
+    async getOrCreateStream(connection, protocol, config = {}, streamAddresses) {
         this.logger.debug(`Getting or creating stream for protocol: ${protocol}, connection`, {
             status: connection.status,
             remoteAddr: connection.remoteAddr.toString(),
             streamCount: connection.streams.length,
             reusePolicy: config.reusePolicy ?? 'none',
+            hasAddresses: !!streamAddresses,
         });
         if (connection.status !== 'open') {
             throw new oError(oErrorCodes.INVALID_STATE, 'Connection not open');
         }
         const reusePolicy = config.reusePolicy ?? 'none';
-        this.logger.debug('Checking for existing reusable stream', connection.streams.map((s) => ({
+        // Check address-based cache if reuse is enabled and addresses provided
+        if (reusePolicy === 'reuse' && streamAddresses) {
+            const cacheKey = this.buildCacheKey(streamAddresses.callerAddress, streamAddresses.receiverAddress);
+            const cachedStream = this.streamCache.get(cacheKey);
+            if (cachedStream?.isReusable) {
+                this.logger.debug('Reusing cached stream by address', {
+                    cacheKey,
+                    streamId: cachedStream.stream.id,
+                    direction: cachedStream.direction,
+                });
+                cachedStream.updateLastUsed();
+                return cachedStream.stream;
+            }
+            else if (cachedStream) {
+                // Stream exists but not reusable, remove from cache
+                this.logger.debug('Removing non-reusable stream from cache', {
+                    cacheKey,
+                    status: cachedStream.stream.status,
+                });
+                this.streamCache.delete(cacheKey);
+            }
+        }
+        this.logger.debug('No reusable cached stream found, checking connection streams', connection.streams.map((s) => ({
             status: s.status,
             protocol: s.protocol,
             writeStatus: s.writeStatus,
             remoteReadStatus: s.remoteReadStatus,
             id: s.id,
         })));
-        // Check for existing stream if reuse is enabled
-        if (reusePolicy === 'reuse') {
+        // Fallback to protocol-based check (legacy behavior)
+        if (reusePolicy === 'reuse' && !streamAddresses) {
             const existingStream = connection.streams.find((stream) => stream.status === 'open' &&
                 stream.protocol === protocol &&
                 stream.writeStatus === 'writable' &&
                 stream.remoteReadStatus === 'readable');
             if (existingStream) {
-                this.logger.debug('Reusing existing stream', existingStream.id, existingStream.direction);
+                this.logger.debug('Reusing existing stream by protocol (legacy)', existingStream.id, existingStream.direction);
                 return existingStream;
             }
         }
         // Create new stream
+        this.logger.debug('Creating new stream', { protocol });
         const stream = await connection.newStream(protocol, {
             signal: config.signal,
             maxOutboundStreams: config.maxOutboundStreams ?? 1000,
             runOnLimitedConnection: config.runOnLimitedConnection ?? false,
         });
+        // Cache the stream if reuse is enabled and addresses are provided
+        if (reusePolicy === 'reuse' && streamAddresses) {
+            const managedStream = new oManagedStream(stream, streamAddresses.callerAddress, streamAddresses.receiverAddress, streamAddresses.direction);
+            this.cacheStream(managedStream);
+            this.setupStreamCleanup(stream);
+        }
         return stream;
     }
     /**

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,EAAE,QAAQ,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAErE,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;IAehC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAiC5D"}
+{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAoB,MAAM,eAAe,CAAC;AAErE,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;IAehC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAiC5D"}

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

@@ -34,6 +34,11 @@ export class oNodeTool extends oTool(oServerNode) {
         }
     }
     async handleStream(stream, connection) {
+        // Extract caller address from connection
+        const callerAddress = this.streamHandler.extractRemotePeerAddress(connection);
+        // Cache inbound stream for bidirectional reuse (if reuse policy is enabled)
+        // The cacheInboundStream method will check the reuse policy
+        this.streamHandler.cacheInboundStream(stream, callerAddress, this.address, 'reuse');
         // Use StreamHandler for consistent stream handling
         // This follows libp2p v3 best practices for length-prefixed streaming
         await this.streamHandler.handleIncomingStream(stream, connection, async (request, stream) => {

package/dist/test/o-managed-stream.spec.d.ts

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

package/dist/test/o-managed-stream.spec.d.ts.map

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

package/dist/test/o-managed-stream.spec.js

@@ -0,0 +1,122 @@
+import { expect } from 'chai';
+import { oManagedStream } from '../src/connection/o-managed-stream.js';
+import { oAddress } from '@olane/o-core';
+describe('oManagedStream', () => {
+    let mockStream;
+    let callerAddress;
+    let receiverAddress;
+    beforeEach(() => {
+        // Create mock stream
+        mockStream = {
+            id: 'test-stream-id',
+            status: 'open',
+            writeStatus: 'writable',
+            remoteReadStatus: 'readable',
+            direction: 'outbound',
+            protocol: '/o/test',
+            addEventListener: () => { },
+        };
+        callerAddress = new oAddress('o://caller');
+        receiverAddress = new oAddress('o://receiver');
+    });
+    describe('Construction', () => {
+        it('should create managed stream with correct properties', () => {
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            expect(managedStream.stream).to.equal(mockStream);
+            expect(managedStream.callerAddress).to.equal(callerAddress);
+            expect(managedStream.receiverAddress).to.equal(receiverAddress);
+            expect(managedStream.direction).to.equal('outbound');
+            expect(managedStream.createdAt).to.be.a('number');
+            expect(managedStream.lastUsedAt).to.equal(managedStream.createdAt);
+        });
+    });
+    describe('Cache Key Generation', () => {
+        it('should generate bidirectional cache key (A→B === B→A)', () => {
+            const streamAtoB = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            const streamBtoA = new oManagedStream(mockStream, receiverAddress, callerAddress, 'inbound');
+            // Cache keys should be identical regardless of direction
+            expect(streamAtoB.cacheKey).to.equal(streamBtoA.cacheKey);
+        });
+        it('should generate different keys for different address pairs', () => {
+            const address1 = new oAddress('o://node-1');
+            const address2 = new oAddress('o://node-2');
+            const address3 = new oAddress('o://node-3');
+            const stream1 = new oManagedStream(mockStream, address1, address2, 'outbound');
+            const stream2 = new oManagedStream(mockStream, address1, address3, 'outbound');
+            expect(stream1.cacheKey).to.not.equal(stream2.cacheKey);
+        });
+        it('should create stable, sorted cache keys', () => {
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            const expectedKey = [callerAddress.value, receiverAddress.value]
+                .sort()
+                .join('↔');
+            expect(managedStream.cacheKey).to.equal(expectedKey);
+        });
+    });
+    describe('Reusability Check', () => {
+        it('should be reusable when stream is open, writable, and readable', () => {
+            mockStream.status = 'open';
+            mockStream.writeStatus = 'writable';
+            mockStream.remoteReadStatus = 'readable';
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            expect(managedStream.isReusable).to.be.true;
+        });
+        it('should not be reusable when stream is closed', () => {
+            mockStream.status = 'closed';
+            mockStream.writeStatus = 'writable';
+            mockStream.remoteReadStatus = 'readable';
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            expect(managedStream.isReusable).to.be.false;
+        });
+        it('should not be reusable when stream is not writable', () => {
+            mockStream.status = 'open';
+            mockStream.writeStatus = 'closed';
+            mockStream.remoteReadStatus = 'readable';
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            expect(managedStream.isReusable).to.be.false;
+        });
+        it('should not be reusable when remote is not readable', () => {
+            mockStream.status = 'open';
+            mockStream.writeStatus = 'writable';
+            mockStream.remoteReadStatus = 'closed';
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            expect(managedStream.isReusable).to.be.false;
+        });
+    });
+    describe('Timestamp Management', () => {
+        it('should update lastUsedAt when updateLastUsed is called', async () => {
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            const initialLastUsed = managedStream.lastUsedAt;
+            // Wait a bit to ensure timestamp difference
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            managedStream.updateLastUsed();
+            expect(managedStream.lastUsedAt).to.be.greaterThan(initialLastUsed);
+        });
+        it('should calculate age correctly', async () => {
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            // Wait a bit
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            expect(managedStream.age).to.be.greaterThan(0);
+            expect(managedStream.age).to.be.lessThan(1000); // Should be less than 1 second
+        });
+        it('should calculate idle time correctly', async () => {
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            // Wait a bit without using
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            expect(managedStream.idleTime).to.be.greaterThan(0);
+            // Update and check idle time resets
+            managedStream.updateLastUsed();
+            expect(managedStream.idleTime).to.be.lessThan(5);
+        });
+    });
+    describe('String Representation', () => {
+        it('should provide meaningful toString output', () => {
+            const managedStream = new oManagedStream(mockStream, callerAddress, receiverAddress, 'outbound');
+            const str = managedStream.toString();
+            expect(str).to.include('oManagedStream');
+            expect(str).to.include(managedStream.cacheKey);
+            expect(str).to.include('outbound');
+            expect(str).to.include('open');
+        });
+    });
+});

package/dist/test/stream-handler-caching.spec.d.ts

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

package/dist/test/stream-handler-caching.spec.d.ts.map

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

package/dist/test/stream-handler-caching.spec.js

@@ -0,0 +1,261 @@
+import { expect } from 'chai';
+import { StreamHandler } from '../src/connection/stream-handler.js';
+import { oAddress } from '@olane/o-core';
+describe('StreamHandler Address-Based Caching', () => {
+    let streamHandler;
+    let mockConnection;
+    let mockStream;
+    let callerAddress;
+    let receiverAddress;
+    beforeEach(() => {
+        streamHandler = new StreamHandler();
+        // Create mock connection
+        mockConnection = {
+            status: 'open',
+            remotePeer: {
+                toString: () => 'test-peer-id',
+            },
+            remoteAddr: {
+                toString: () => '/memory/test',
+            },
+            streams: [],
+            newStream: async () => mockStream,
+        };
+        // Create mock stream
+        mockStream = {
+            id: 'test-stream-id',
+            status: 'open',
+            writeStatus: 'writable',
+            remoteReadStatus: 'readable',
+            direction: 'outbound',
+            protocol: '/o/test',
+            addEventListener: () => { },
+        };
+        callerAddress = new oAddress('o://caller');
+        receiverAddress = new oAddress('o://receiver');
+    });
+    describe('getOrCreateStream with Address-Based Caching', () => {
+        it('should create new stream when cache is empty', async () => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            const stream = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            expect(stream).to.equal(mockStream);
+        });
+        it('should reuse cached stream with same caller-receiver pair', async () => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            // First call creates and caches
+            const stream1 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            // Second call should reuse
+            const stream2 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            expect(stream1).to.equal(stream2);
+        });
+        it('should reuse stream bidirectionally (A→B same as B→A)', async () => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            // First: caller → receiver
+            const streamAtoB = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            const stream1 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAtoB);
+            // Second: receiver → caller (reversed)
+            const streamBtoA = {
+                callerAddress: receiverAddress,
+                receiverAddress: callerAddress,
+                direction: 'inbound',
+            };
+            const stream2 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamBtoA);
+            // Should be the same stream due to bidirectional caching
+            expect(stream1).to.equal(stream2);
+        });
+        it('should create new stream for different address pairs', async () => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            const otherReceiver = new oAddress('o://other-receiver');
+            // Create new mock stream for second call
+            const mockStream2 = {
+                ...mockStream,
+                id: 'test-stream-id-2',
+            };
+            let streamCount = 0;
+            mockConnection.newStream = async () => {
+                streamCount++;
+                return (streamCount === 1 ? mockStream : mockStream2);
+            };
+            // First pair
+            const stream1 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            });
+            // Different pair
+            const stream2 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, {
+                callerAddress,
+                receiverAddress: otherReceiver,
+                direction: 'outbound',
+            });
+            // Should be different streams
+            expect(stream1.id).to.not.equal(stream2.id);
+        });
+        it('should not cache when reusePolicy is none', async () => {
+            const config = {
+                reusePolicy: 'none',
+            };
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            let callCount = 0;
+            mockConnection.newStream = async () => {
+                callCount++;
+                return {
+                    ...mockStream,
+                    id: `stream-${callCount}`,
+                };
+            };
+            const stream1 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            const stream2 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            // Should be different streams (not cached)
+            expect(stream1.id).to.not.equal(stream2.id);
+        });
+        it('should remove non-reusable streams from cache', async () => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            // First call creates and caches
+            const stream1 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            // Make stream non-reusable
+            mockStream.status = 'closed';
+            // Create new mock stream for second call
+            const mockStream2 = {
+                ...mockStream,
+                id: 'test-stream-id-2',
+                status: 'open',
+            };
+            mockConnection.newStream = async () => mockStream2;
+            // Second call should create new stream (old one not reusable)
+            const stream2 = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            expect(stream1.id).to.not.equal(stream2.id);
+        });
+        it('should fall back to protocol-based check when addresses not provided', async () => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            // Add mock stream to connection streams
+            mockConnection.streams = [mockStream];
+            // Call without streamAddresses
+            const stream = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config);
+            // Should find and return the existing stream by protocol
+            expect(stream).to.equal(mockStream);
+        });
+    });
+    describe('extractRemotePeerAddress', () => {
+        it('should extract address from connection peer ID', () => {
+            const address = streamHandler.extractRemotePeerAddress(mockConnection);
+            expect(address.value).to.include('o://peer/');
+            expect(address.value).to.include('test-peer-id');
+        });
+    });
+    describe('cacheInboundStream', () => {
+        it('should cache inbound stream when reuse is enabled', async () => {
+            streamHandler.cacheInboundStream(mockStream, callerAddress, receiverAddress, 'reuse');
+            // Try to get the cached stream
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            const stream = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            // Should reuse the cached inbound stream
+            expect(stream).to.equal(mockStream);
+        });
+        it('should not cache when reusePolicy is none', async () => {
+            streamHandler.cacheInboundStream(mockStream, callerAddress, receiverAddress, 'none');
+            // Try to get stream - should create new one
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            const newMockStream = { ...mockStream, id: 'new-stream-id' };
+            mockConnection.newStream = async () => newMockStream;
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            const stream = await streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            // Should not reuse (was not cached)
+            expect(stream.id).to.equal('new-stream-id');
+        });
+        it('should not cache duplicate streams', () => {
+            // Cache first time
+            streamHandler.cacheInboundStream(mockStream, callerAddress, receiverAddress, 'reuse');
+            // Try to cache again - should be no-op
+            streamHandler.cacheInboundStream(mockStream, callerAddress, receiverAddress, 'reuse');
+            // No error should occur, and stream should still be cached
+            // (This test mainly ensures no exception is thrown)
+        });
+    });
+    describe('Stream Cleanup', () => {
+        it('should remove stream from cache on close event', (done) => {
+            const config = {
+                reusePolicy: 'reuse',
+            };
+            let closeListener;
+            // Override addEventListener to capture the close listener
+            mockStream.addEventListener = (event, listener) => {
+                if (event === 'close') {
+                    closeListener = listener;
+                }
+            };
+            const streamAddresses = {
+                callerAddress,
+                receiverAddress,
+                direction: 'outbound',
+            };
+            streamHandler
+                .getOrCreateStream(mockConnection, '/o/test', config, streamAddresses)
+                .then(() => {
+                expect(closeListener).to.not.be.undefined;
+                // Simulate close event
+                if (closeListener) {
+                    closeListener();
+                }
+                // Create new stream for next call
+                const newMockStream = { ...mockStream, id: 'new-stream-after-close' };
+                mockConnection.newStream = async () => newMockStream;
+                // Try to get stream again - should create new one since old one was removed
+                return streamHandler.getOrCreateStream(mockConnection, '/o/test', config, streamAddresses);
+            })
+                .then((stream) => {
+                expect(stream.id).to.equal('new-stream-after-close');
+                done();
+            })
+                .catch(done);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.39",
+  "version": "0.7.40",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -40,7 +40,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.29.0",
-    "@olane/o-test": "0.7.39",
+    "@olane/o-test": "0.7.40",
     "@tsconfig/node20": "^20.1.6",
     "@types/jest": "^30.0.0",
     "@types/json5": "^2.2.0",
@@ -60,13 +60,13 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.7.39",
-    "@olane/o-core": "0.7.39",
-    "@olane/o-protocol": "0.7.39",
-    "@olane/o-tool": "0.7.39",
+    "@olane/o-config": "0.7.40",
+    "@olane/o-core": "0.7.40",
+    "@olane/o-protocol": "0.7.40",
+    "@olane/o-tool": "0.7.40",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0",
     "json5": "^2.2.3"
   },
-  "gitHead": "9c992e3bda91a7d2b587392a1db5cff47a2ca23a"
+  "gitHead": "d2d7cb62d69249fe63d4cb293dbbdfc44d250f17"
 }