@openclaw/proxyline 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.8 - 2026-08-31
+
+- Fixed HTTP-forward Node agents to enforce the default 30-second proxy handshake timeout and cancel pending sockets when callers abort or destroy requests; explicit `0` remains unbounded. (#27) Thanks @SebTardif.
+- Fixed Node proxy request hooks to follow the request selected by finite connection pools across origins, keeping queued requests' timeouts and cancellation independent. (#27)
+- Hardened ambient `NO_PROXY` hostname normalization against dot-heavy input, docs table-of-contents text extraction, and proxy/TLS test isolation. (#24) Thanks @vincentkoc.
+- Fixed HTTP-forward agent shutdown to destroy pending proxy sockets and settle requests before the connection handshake completes. (#23) Thanks @SebTardif.
+- Fixed throwing `onEvent` observers to preserve successful installation and leave the proxy runtime stoppable and replaceable. (#23) Thanks @SebTardif.
+- Updated Node types, tsx, ws, and pnpm tooling. (#21, #22)
+
 ## 0.3.7 - 2026-08-02
 
 - Fixed Node HTTP/HTTPS proxy agents to apply the default 30-second CONNECT timeout when callers omit a request timeout; explicit `0` remains unbounded. Thanks @SebTardif.

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,aAAa,GACb,WAAW,GACX,UAAU,GACV,YAAY,GACZ,aAAa,GACb,WAAW,GACX,UAAU,CAAC;AAEf,KAAK,gBAAgB,GAAG,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEjF,eAAO,MAAM,eAAe,EAAE,gBAS7B,CAAC;AAEF,wBAAgB,YAAY,IAAI,gBAAgB,CAW/C;AAoBD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,gBAAgB,GACpB,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AAuHD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,GAAG,EAAE,gBAAgB,GACpB,MAAM,GAAG,SAAS,CAsBpB;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAmC/E"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,aAAa,GACb,WAAW,GACX,UAAU,GACV,YAAY,GACZ,aAAa,GACb,WAAW,GACX,UAAU,CAAC;AAEf,KAAK,gBAAgB,GAAG,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEjF,eAAO,MAAM,eAAe,EAAE,gBAS7B,CAAC;AAEF,wBAAgB,YAAY,IAAI,gBAAgB,CAW/C;AAoBD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,gBAAgB,GACpB,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AA4HD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,GAAG,EAAE,gBAAgB,GACpB,MAAM,GAAG,SAAS,CAsBpB;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,CAmC/E"}

package/dist/env.js

@@ -103,7 +103,12 @@ function matchesNoProxy(url, env) {
     return false;
 }
 function normalizeNoProxyHost(hostname) {
-    const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+    const value = hostname.trim().toLowerCase();
+    let end = value.length;
+    while (end > 0 && value[end - 1] === ".") {
+        end -= 1;
+    }
+    const normalized = value.slice(0, end);
     return normalized.startsWith("[") && normalized.endsWith("]")
         ? normalized.slice(1, -1)
         : normalized;

package/dist/node-http.d.ts

@@ -9,8 +9,10 @@ export type NodeHttpRequestOptions = http.RequestOptions & https.RequestOptions
 type NodeHttpMethod = typeof http.request;
 type NodeAgentFactory = (options: NodeHttpRequestOptions) => http.Agent;
 type NodeAgentOptions = http.AgentOptions & https.AgentOptions;
+declare const pendingRequestSymbol: unique symbol;
 type NodeAgentRequestOptions = http.RequestOptions & https.RequestOptions & {
     secureEndpoint?: boolean;
+    [pendingRequestSymbol]?: http.ClientRequest;
 };
 type NodeProxyAgentOptions = NodeAgentOptions & {
     defaultProtocol?: "http" | "https";

package/dist/node-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-http.d.ts","sourceRoot":"","sources":["../src/node-http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node-http.d.ts","sourceRoot":"","sources":["../src/node-http.ts"],"names":[],"mappings":"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"}

package/dist/node-http.js

@@ -6,6 +6,7 @@ import { domainToASCII } from "node:url";
 import { readProxyEnv, resolveAmbientProxyForUrl, } from "./env.js";
 import { formatConnectAuthority, resolveProxyConnectTimeoutMs } from "./connect.js";
 import { ProxylineError, decodeProxyUserinfoComponent, resolveProxyTlsCa } from "./shared.js";
+const pendingRequestSymbol = Symbol("proxyline.pendingRequest");
 const MAX_CONNECT_RESPONSE_HEADER_BYTES = 16 * 1024;
 const INVALID_PROXY_TARGET_HOST_DELIMITER_PATTERN = /[/:?#@\\]/;
 const INVALID_PROXY_TARGET_HOST_CONTROL_PATTERN = /[\u0000-\u0020\u007f]/;
@@ -295,9 +296,25 @@ function destinationTlsConnectOptions(options, socket) {
     delete tlsOptions.agent;
     return tlsOptions;
 }
-class ProxylineHttpForwardAgent extends http.Agent {
+class ProxylineRequestAgent extends http.Agent {
+    addRequest(req, options) {
+        http.Agent.prototype.addRequest.call(this, req, options);
+    }
+    createSocket(req, options, callback) {
+        // Node chooses queued requests by origin, not global FIFO, and clones options.
+        http.Agent.prototype.createSocket.call(this, req, { ...options, [pendingRequestSymbol]: req }, callback);
+    }
+    takePendingRequest(options) {
+        const request = options[pendingRequestSymbol];
+        // Node retains these options in pooled socket listeners after handoff.
+        delete options[pendingRequestSymbol];
+        return request;
+    }
+}
+class ProxylineHttpForwardAgent extends ProxylineRequestAgent {
     options;
     #keepAlive;
+    #pendingConnectSockets = new Set();
     #proxy;
     #proxyTls;
     constructor(proxy, options, proxyTls) {
@@ -310,34 +327,170 @@ class ProxylineHttpForwardAgent extends http.Agent {
     addRequest(req, options) {
         setForwardProxyRequestPath(req, options);
         setProxyRequestHeaders(req, this.#proxy, this.#keepAlive);
-        http.Agent.prototype.addRequest.call(this, req, options);
+        super.addRequest(req, options);
     }
-    createConnection(_options, callback) {
+    createConnection(options, callback) {
+        const request = this.takePendingRequest(options);
         const socket = connectToProxy(this.#proxy, this.#proxyTls);
         // When Node supplies an async callback, deliver the socket only through that
         // path. Returning the same socket as well double-invokes Agent setup and can
         // hand an unready TLS proxy socket to plain HTTP forward traffic.
         if (callback !== undefined) {
-            const onError = (error) => {
+            this.#pendingConnectSockets.add(socket);
+            let pendingTimeout;
+            let settled = false;
+            let originalRequestSetTimeout;
+            let hookedRequestSetTimeout;
+            let originalRequestDestroy;
+            let hookedRequestDestroy;
+            const restoreRequestDestroyHook = () => {
+                if (request !== undefined &&
+                    originalRequestDestroy !== undefined &&
+                    request.destroy === hookedRequestDestroy) {
+                    request.destroy = originalRequestDestroy;
+                }
+                originalRequestDestroy = undefined;
+                hookedRequestDestroy = undefined;
+            };
+            const startPendingTimeout = (timeoutMs) => {
+                if (pendingTimeout !== undefined) {
+                    clearTimeout(pendingTimeout);
+                }
+                pendingTimeout = setTimeout(() => {
+                    request?.emit("timeout");
+                    if (!settled) {
+                        fail(new ProxylineError("CONNECT_FAILED", "proxy connection timed out"));
+                    }
+                }, timeoutMs);
+                pendingTimeout.unref?.();
+            };
+            const clearPendingTimeout = () => {
+                if (pendingTimeout !== undefined) {
+                    clearTimeout(pendingTimeout);
+                    pendingTimeout = undefined;
+                }
+            };
+            const restoreRequestTimeoutHook = () => {
+                if (request !== undefined &&
+                    originalRequestSetTimeout !== undefined &&
+                    request.setTimeout === hookedRequestSetTimeout) {
+                    request.setTimeout = originalRequestSetTimeout;
+                }
+                originalRequestSetTimeout = undefined;
+                hookedRequestSetTimeout = undefined;
+            };
+            const cleanup = () => {
+                clearPendingTimeout();
+                this.#pendingConnectSockets.delete(socket);
+                restoreRequestTimeoutHook();
+                restoreRequestDestroyHook();
+                socket.off(this.#proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
+                socket.off("error", onError);
+                socket.off("close", onClosed);
+                request?.off("abort", onRequestClosed);
+                request?.off("close", onRequestClosed);
+                request?.off("error", onRequestClosed);
+                request?.off("timeout", onRequestTimedOut);
+            };
+            const finish = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
                 callback(error, socket);
             };
+            const fail = (error) => {
+                socket.destroy();
+                finish(error);
+            };
+            const onError = (error) => {
+                finish(error);
+            };
+            const onClosed = () => {
+                finish(new ProxylineError("CONNECT_FAILED", "proxy socket closed before connection completed"));
+            };
             const onConnected = () => {
-                socket.off("error", onError);
-                callback(null, socket);
+                finish(null);
             };
+            const onRequestTimedOut = () => {
+                if (!settled) {
+                    fail(new ProxylineError("CONNECT_FAILED", "proxy connection timed out"));
+                }
+            };
+            const onRequestClosed = () => {
+                if (!settled) {
+                    fail(new ProxylineError("CONNECT_FAILED", "request closed before proxy connection completed"));
+                }
+            };
+            if (request !== undefined) {
+                originalRequestSetTimeout = request.setTimeout;
+                hookedRequestSetTimeout = function hookedSetTimeout(timeout, callback) {
+                    const result = originalRequestSetTimeout?.call(this, timeout, callback) ?? this;
+                    const timeoutMs = normalizedPositiveInteger(timeout);
+                    if (timeoutMs !== undefined) {
+                        startPendingTimeout(timeoutMs);
+                    }
+                    else {
+                        clearPendingTimeout();
+                    }
+                    return result;
+                };
+                request.setTimeout = hookedRequestSetTimeout;
+            }
+            // Prefer explicit agent/request timeout. Default 30s only when both are omitted.
+            // Explicit values go through normalizedPositiveInteger first so fractional/invalid
+            // timeouts keep the historical no-pending-timer behavior (not Math.trunc to 1ms).
+            const requestTimeout = request?.timeout;
+            const rawTimeout = options.timeout !== undefined ? options.timeout : requestTimeout;
+            if (rawTimeout === undefined) {
+                const connectTimeoutMs = resolveProxyConnectTimeoutMs(undefined);
+                if (connectTimeoutMs !== undefined) {
+                    startPendingTimeout(connectTimeoutMs);
+                }
+            }
+            else {
+                const timeoutMs = normalizedPositiveInteger(rawTimeout);
+                if (timeoutMs !== undefined) {
+                    startPendingTimeout(timeoutMs);
+                }
+            }
+            request?.once("timeout", onRequestTimedOut);
             socket.once(this.#proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
             socket.once("error", onError);
+            socket.once("close", onClosed);
+            // Node defers ClientRequest.destroy() until the async socket callback.
+            if (request !== undefined) {
+                originalRequestDestroy = request.destroy;
+                hookedRequestDestroy = function hookedDestroy(error) {
+                    const result = originalRequestDestroy?.call(this, error) ?? this;
+                    onRequestClosed();
+                    return result;
+                };
+                request.destroy = hookedRequestDestroy;
+            }
+            request?.once("abort", onRequestClosed);
+            request?.once("close", onRequestClosed);
+            request?.once("error", onRequestClosed);
+            if (request?.destroyed) {
+                onRequestClosed();
+            }
             return undefined;
         }
         return socket;
     }
+    destroy() {
+        for (const socket of this.#pendingConnectSockets) {
+            socket.destroy(new ProxylineError("CONNECT_FAILED", "proxy connection failed because agent was destroyed"));
+        }
+        this.#pendingConnectSockets.clear();
+        super.destroy();
+    }
 }
-class ProxylineConnectAgent extends http.Agent {
+class ProxylineConnectAgent extends ProxylineRequestAgent {
     options;
     #keepAlive;
     #pendingConnectSockets = new Set();
-    #pendingRequests = new WeakMap();
-    #pendingRequestQueue = [];
     #proxy;
     #proxyTls;
     constructor(proxy, options, proxyTls) {
@@ -347,33 +500,8 @@ class ProxylineConnectAgent extends http.Agent {
         this.#proxy = proxy;
         this.#proxyTls = proxyTls;
     }
-    addRequest(req, options) {
-        this.#pendingRequests.set(options, req);
-        this.#pendingRequestQueue.push(req);
-        req.once("socket", () => this.#removePendingRequest(req));
-        req.once("close", () => this.#removePendingRequest(req));
-        try {
-            http.Agent.prototype.addRequest.call(this, req, options);
-        }
-        catch (error) {
-            this.#pendingRequests.delete(options);
-            this.#removePendingRequest(req);
-            throw error;
-        }
-    }
-    #removePendingRequest(req) {
-        const index = this.#pendingRequestQueue.indexOf(req);
-        if (index !== -1) {
-            this.#pendingRequestQueue.splice(index, 1);
-        }
-    }
     createConnection(options, callback) {
-        const mappedRequest = this.#pendingRequests.get(options);
-        const request = mappedRequest ?? this.#pendingRequestQueue.shift();
-        this.#pendingRequests.delete(options);
-        if (mappedRequest !== undefined) {
-            this.#removePendingRequest(mappedRequest);
-        }
+        const request = this.takePendingRequest(options);
         if (callback === undefined) {
             throw new ProxylineError("INVALID_CONNECT_CALLBACK", "CONNECT agents require an async socket callback.");
         }

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAIV,eAAe,EACf,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AAs0BpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAgI3E;AAED,eAAO,MAAM,kBAAkB,yBAAmB,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAIV,eAAe,EACf,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AA00BpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAgI3E;AAED,eAAO,MAAM,kBAAkB,yBAAmB,CAAC"}

package/dist/runtime.js

@@ -145,7 +145,12 @@ function normalizeProxyUrl(value) {
     return url;
 }
 function emit(onEvent, event) {
-    onEvent?.(event);
+    try {
+        onEvent?.(event);
+    }
+    catch {
+        // Observer failures must not fail install or leave patched globals unstoppable.
+    }
 }
 function isProxyableUrlProtocol(protocol) {
     return protocol === "http:" ||
@@ -662,12 +667,6 @@ export function installProxyline(options) {
             undici: options.undici,
         })
         : undefined;
-    emit(options.onEvent, {
-        type: "runtime.installed",
-        mode: options.mode,
-        active: hasActiveProxy,
-        ...(redactedProxyUrl ? { proxyUrl: redactedProxyUrl } : {}),
-    });
     const handle = {
         mode: options.mode,
         active: hasActiveProxy,
@@ -725,6 +724,12 @@ export function installProxyline(options) {
         },
     };
     activeHandle = hasActiveProxy ? handle : activeHandle;
+    emit(options.onEvent, {
+        type: "runtime.installed",
+        mode: options.mode,
+        active: hasActiveProxy,
+        ...(redactedProxyUrl ? { proxyUrl: redactedProxyUrl } : {}),
+    });
     return handle;
 }
 export const installGlobalProxy = installProxyline;

package/docs/surfaces.md

@@ -22,6 +22,10 @@ Per request, Proxyline:
 
 This means caller agents are not just ignored — the per-request agent is replaced before the original method runs, so even libraries that read `req.agent` after construction see the proxy agent.
 
+HTTP-forward proxy connections and CONNECT handshakes default to a 30-second connection timeout. A request's `timeout` option or `req.setTimeout(ms)` can change the pending handshake timeout; use `0` to leave it unbounded. Expiry emits `timeout` on that request and fails the pending connection with `CONNECT_FAILED`. This applies to the explicit Node helper agents as well as patched requests.
+
+For HTTP-forward requests, `req.destroy()` or `req.abort()` also cancels a pending connection to the proxy. This applies to long-lived helper agents: cancellation releases the pending socket without destroying the whole agent or affecting another queued request.
+
 ### TLS identity preservation
 
 When the caller supplied an `https.Agent` with TLS options, the following keys are lifted into the request so the destination TLS handshake still validates correctly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/proxyline",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Process-global proxy routing for Node.js.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "url": "https://github.com/openclaw/proxyline/issues"
   },
   "homepage": "https://proxyline.dev",
-  "packageManager": "pnpm@11.20.0",
+  "packageManager": "pnpm@11.21.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -62,12 +62,12 @@
     "crabbox:warmup": "crabbox warmup"
   },
   "devDependencies": {
-    "@types/node": "26.1.2",
+    "@types/node": "26.2.0",
     "@types/ws": "8.18.1",
-    "tsx": "4.23.5",
+    "tsx": "4.23.12",
     "typescript": "^7.0.2",
     "undici": "8.10.0",
-    "ws": "8.21.1"
+    "ws": "8.21.3"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/env.ts

@@ -134,7 +134,12 @@ function matchesNoProxy(url: URL, env: ProxyEnvSnapshot): boolean {
 }
 
 function normalizeNoProxyHost(hostname: string): string {
-  const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  const value = hostname.trim().toLowerCase();
+  let end = value.length;
+  while (end > 0 && value[end - 1] === ".") {
+    end -= 1;
+  }
+  const normalized = value.slice(0, end);
   return normalized.startsWith("[") && normalized.endsWith("]")
     ? normalized.slice(1, -1)
     : normalized;

package/src/node-http.ts

@@ -19,17 +19,27 @@ export type NodeHttpRequestOptions = http.RequestOptions & https.RequestOptions
 type NodeHttpMethod = typeof http.request;
 type NodeAgentFactory = (options: NodeHttpRequestOptions) => http.Agent;
 type NodeAgentOptions = http.AgentOptions & https.AgentOptions;
+const pendingRequestSymbol = Symbol("proxyline.pendingRequest");
 type NodeAgentRequestOptions = http.RequestOptions & https.RequestOptions & {
   secureEndpoint?: boolean;
+  [pendingRequestSymbol]?: http.ClientRequest;
 };
 type NodeAddRequestAgent = http.Agent & {
   addRequest(req: http.ClientRequest, options: NodeAgentRequestOptions): void;
 };
+type NodeCreateSocketAgent = http.Agent & {
+  createSocket(
+    req: http.ClientRequest,
+    options: NodeAgentRequestOptions,
+    callback: (error: Error | null, socket?: net.Socket) => void,
+  ): void;
+};
 type RequestSetTimeout = (
   this: http.ClientRequest,
   timeout: number,
   callback?: () => void,
 ) => http.ClientRequest;
+type RequestDestroy = (this: http.ClientRequest, error?: Error) => http.ClientRequest;
 type NodeAgentWithOptions = http.Agent & {
   options?: NodeAgentOptions;
 };
@@ -417,9 +427,34 @@ function destinationTlsConnectOptions(
   return tlsOptions;
 }
 
-class ProxylineHttpForwardAgent extends http.Agent {
+abstract class ProxylineRequestAgent extends http.Agent {
+  public addRequest(req: http.ClientRequest, options: NodeAgentRequestOptions): void {
+    (http.Agent.prototype as unknown as NodeAddRequestAgent).addRequest.call(this, req, options);
+  }
+
+  public createSocket(
+    req: http.ClientRequest,
+    options: NodeAgentRequestOptions,
+    callback: (error: Error | null, socket?: net.Socket) => void,
+  ): void {
+    // Node chooses queued requests by origin, not global FIFO, and clones options.
+    (http.Agent.prototype as unknown as NodeCreateSocketAgent).createSocket.call(
+      this, req, { ...options, [pendingRequestSymbol]: req }, callback,
+    );
+  }
+
+  protected takePendingRequest(options: NodeAgentRequestOptions): http.ClientRequest | undefined {
+    const request = options[pendingRequestSymbol];
+    // Node retains these options in pooled socket listeners after handoff.
+    delete options[pendingRequestSymbol];
+    return request;
+  }
+}
+
+class ProxylineHttpForwardAgent extends ProxylineRequestAgent {
   public readonly options: NodeAgentOptions;
   readonly #keepAlive: boolean;
+  readonly #pendingConnectSockets = new Set<net.Socket>();
   readonly #proxy: URL;
   readonly #proxyTls: ProxylineTlsOptions | undefined;
 
@@ -431,42 +466,189 @@ class ProxylineHttpForwardAgent extends http.Agent {
     this.#proxyTls = proxyTls;
   }
 
-  public addRequest(req: http.ClientRequest, options: NodeAgentRequestOptions): void {
+  public override addRequest(req: http.ClientRequest, options: NodeAgentRequestOptions): void {
     setForwardProxyRequestPath(req as http.ClientRequest & { _header?: string | null }, options);
     setProxyRequestHeaders(req, this.#proxy, this.#keepAlive);
-    (http.Agent.prototype as unknown as NodeAddRequestAgent).addRequest.call(this, req, options);
+    super.addRequest(req, options);
   }
 
   public override createConnection(
-    _options: NodeAgentRequestOptions,
+    options: NodeAgentRequestOptions,
     callback?: (error: Error | null, socket: net.Socket) => void,
   ): net.Socket {
+    const request = this.takePendingRequest(options);
     const socket = connectToProxy(this.#proxy, this.#proxyTls);
     // When Node supplies an async callback, deliver the socket only through that
     // path. Returning the same socket as well double-invokes Agent setup and can
     // hand an unready TLS proxy socket to plain HTTP forward traffic.
     if (callback !== undefined) {
-      const onError = (error: Error): void => {
+      this.#pendingConnectSockets.add(socket);
+      let pendingTimeout: ReturnType<typeof setTimeout> | undefined;
+      let settled = false;
+      let originalRequestSetTimeout: RequestSetTimeout | undefined;
+      let hookedRequestSetTimeout: RequestSetTimeout | undefined;
+      let originalRequestDestroy: RequestDestroy | undefined;
+      let hookedRequestDestroy: RequestDestroy | undefined;
+
+      const restoreRequestDestroyHook = (): void => {
+        if (
+          request !== undefined &&
+          originalRequestDestroy !== undefined &&
+          request.destroy === hookedRequestDestroy
+        ) {
+          request.destroy = originalRequestDestroy;
+        }
+        originalRequestDestroy = undefined;
+        hookedRequestDestroy = undefined;
+      };
+
+      const startPendingTimeout = (timeoutMs: number): void => {
+        if (pendingTimeout !== undefined) {
+          clearTimeout(pendingTimeout);
+        }
+        pendingTimeout = setTimeout(() => {
+          request?.emit("timeout");
+          if (!settled) {
+            fail(new ProxylineError("CONNECT_FAILED", "proxy connection timed out"));
+          }
+        }, timeoutMs);
+        pendingTimeout.unref?.();
+      };
+
+      const clearPendingTimeout = (): void => {
+        if (pendingTimeout !== undefined) {
+          clearTimeout(pendingTimeout);
+          pendingTimeout = undefined;
+        }
+      };
+
+      const restoreRequestTimeoutHook = (): void => {
+        if (
+          request !== undefined &&
+          originalRequestSetTimeout !== undefined &&
+          request.setTimeout === hookedRequestSetTimeout
+        ) {
+          request.setTimeout = originalRequestSetTimeout;
+        }
+        originalRequestSetTimeout = undefined;
+        hookedRequestSetTimeout = undefined;
+      };
+
+      const cleanup = (): void => {
+        clearPendingTimeout();
+        this.#pendingConnectSockets.delete(socket);
+        restoreRequestTimeoutHook();
+        restoreRequestDestroyHook();
+        socket.off(this.#proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
+        socket.off("error", onError);
+        socket.off("close", onClosed);
+        request?.off("abort", onRequestClosed);
+        request?.off("close", onRequestClosed);
+        request?.off("error", onRequestClosed);
+        request?.off("timeout", onRequestTimedOut);
+      };
+      const finish = (error: Error | null): void => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
         callback(error, socket);
       };
+      const fail = (error: Error): void => {
+        socket.destroy();
+        finish(error);
+      };
+      const onError = (error: Error): void => {
+        finish(error);
+      };
+      const onClosed = (): void => {
+        finish(new ProxylineError("CONNECT_FAILED", "proxy socket closed before connection completed"));
+      };
       const onConnected = (): void => {
-        socket.off("error", onError);
-        callback(null, socket);
+        finish(null);
+      };
+      const onRequestTimedOut = (): void => {
+        if (!settled) {
+          fail(new ProxylineError("CONNECT_FAILED", "proxy connection timed out"));
+        }
       };
+      const onRequestClosed = (): void => {
+        if (!settled) {
+          fail(new ProxylineError("CONNECT_FAILED", "request closed before proxy connection completed"));
+        }
+      };
+
+      if (request !== undefined) {
+        originalRequestSetTimeout = request.setTimeout;
+        hookedRequestSetTimeout = function hookedSetTimeout(timeout, callback) {
+          const result = originalRequestSetTimeout?.call(this, timeout, callback) ?? this;
+          const timeoutMs = normalizedPositiveInteger(timeout);
+          if (timeoutMs !== undefined) {
+            startPendingTimeout(timeoutMs);
+          } else {
+            clearPendingTimeout();
+          }
+          return result;
+        };
+        request.setTimeout = hookedRequestSetTimeout;
+      }
+
+      // Prefer explicit agent/request timeout. Default 30s only when both are omitted.
+      // Explicit values go through normalizedPositiveInteger first so fractional/invalid
+      // timeouts keep the historical no-pending-timer behavior (not Math.trunc to 1ms).
+      const requestTimeout = (request as { timeout?: unknown } | undefined)?.timeout;
+      const rawTimeout = options.timeout !== undefined ? options.timeout : requestTimeout;
+      if (rawTimeout === undefined) {
+        const connectTimeoutMs = resolveProxyConnectTimeoutMs(undefined);
+        if (connectTimeoutMs !== undefined) {
+          startPendingTimeout(connectTimeoutMs);
+        }
+      } else {
+        const timeoutMs = normalizedPositiveInteger(rawTimeout);
+        if (timeoutMs !== undefined) {
+          startPendingTimeout(timeoutMs);
+        }
+      }
+      request?.once("timeout", onRequestTimedOut);
+
       socket.once(this.#proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
       socket.once("error", onError);
+      socket.once("close", onClosed);
+      // Node defers ClientRequest.destroy() until the async socket callback.
+      if (request !== undefined) {
+        originalRequestDestroy = request.destroy;
+        hookedRequestDestroy = function hookedDestroy(this: http.ClientRequest, error?: Error) {
+          const result = originalRequestDestroy?.call(this, error) ?? this;
+          onRequestClosed();
+          return result;
+        };
+        request.destroy = hookedRequestDestroy;
+      }
+      request?.once("abort", onRequestClosed);
+      request?.once("close", onRequestClosed);
+      request?.once("error", onRequestClosed);
+      if (request?.destroyed) {
+        onRequestClosed();
+      }
       return undefined as unknown as net.Socket;
     }
     return socket;
   }
+
+  public override destroy(): void {
+    for (const socket of this.#pendingConnectSockets) {
+      socket.destroy(new ProxylineError("CONNECT_FAILED", "proxy connection failed because agent was destroyed"));
+    }
+    this.#pendingConnectSockets.clear();
+    super.destroy();
+  }
 }
 
-class ProxylineConnectAgent extends http.Agent {
+class ProxylineConnectAgent extends ProxylineRequestAgent {
   public readonly options: NodeAgentOptions;
   readonly #keepAlive: boolean;
   readonly #pendingConnectSockets = new Set<net.Socket>();
-  readonly #pendingRequests = new WeakMap<NodeAgentRequestOptions, http.ClientRequest>();
-  readonly #pendingRequestQueue: http.ClientRequest[] = [];
   readonly #proxy: URL;
   readonly #proxyTls: ProxylineTlsOptions | undefined;
 
@@ -478,37 +660,11 @@ class ProxylineConnectAgent extends http.Agent {
     this.#proxyTls = proxyTls;
   }
 
-  public addRequest(req: http.ClientRequest, options: NodeAgentRequestOptions): void {
-    this.#pendingRequests.set(options, req);
-    this.#pendingRequestQueue.push(req);
-    req.once("socket", () => this.#removePendingRequest(req));
-    req.once("close", () => this.#removePendingRequest(req));
-    try {
-      (http.Agent.prototype as unknown as NodeAddRequestAgent).addRequest.call(this, req, options);
-    } catch (error) {
-      this.#pendingRequests.delete(options);
-      this.#removePendingRequest(req);
-      throw error;
-    }
-  }
-
-  #removePendingRequest(req: http.ClientRequest): void {
-    const index = this.#pendingRequestQueue.indexOf(req);
-    if (index !== -1) {
-      this.#pendingRequestQueue.splice(index, 1);
-    }
-  }
-
   public override createConnection(
     options: NodeAgentRequestOptions,
     callback?: (error: Error | null, socket: net.Socket) => void,
   ): net.Socket {
-    const mappedRequest = this.#pendingRequests.get(options);
-    const request = mappedRequest ?? this.#pendingRequestQueue.shift();
-    this.#pendingRequests.delete(options);
-    if (mappedRequest !== undefined) {
-      this.#removePendingRequest(mappedRequest);
-    }
+    const request = this.takePendingRequest(options);
     if (callback === undefined) {
       throw new ProxylineError("INVALID_CONNECT_CALLBACK", "CONNECT agents require an async socket callback.");
     }

package/src/runtime.ts

@@ -283,7 +283,11 @@ function normalizeProxyUrl(value: string | URL | undefined): URL | undefined {
 }
 
 function emit(onEvent: ProxylineOptions["onEvent"], event: ProxylineEvent): void {
-  onEvent?.(event);
+  try {
+    onEvent?.(event);
+  } catch {
+    // Observer failures must not fail install or leave patched globals unstoppable.
+  }
 }
 
 function isProxyableUrlProtocol(protocol: string): boolean {
@@ -942,12 +946,6 @@ export function installProxyline(options: ProxylineOptions): ProxylineHandle {
         },
       )
     : undefined;
-  emit(options.onEvent, {
-    type: "runtime.installed",
-    mode: options.mode,
-    active: hasActiveProxy,
-    ...(redactedProxyUrl ? { proxyUrl: redactedProxyUrl } : {}),
-  });
 
   const handle: ProxylineHandle = {
     mode: options.mode,
@@ -1012,6 +1010,12 @@ export function installProxyline(options: ProxylineOptions): ProxylineHandle {
   };
 
   activeHandle = hasActiveProxy ? handle : activeHandle;
+  emit(options.onEvent, {
+    type: "runtime.installed",
+    mode: options.mode,
+    active: hasActiveProxy,
+    ...(redactedProxyUrl ? { proxyUrl: redactedProxyUrl } : {}),
+  });
   return handle;
 }