@openclaw/proxyline 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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.
+- Updated Undici and tsx, pnpm and npm release tooling, and pinned GitHub Actions to their latest stable releases.
+
+## 0.3.6 - 2026-08-02
+
+- Fixed HTTP forwarding through HTTPS proxies to wait for the proxy TLS handshake before assigning the socket to Node's agent. Thanks @SebTardif.
+- Added a 30-second default timeout to `openProxyConnectTunnel` when `timeoutMs` is omitted; pass `0` for unbounded waits. Thanks @SebTardif.
+
 ## 0.3.5 - 2026-08-01
 
 - Fixed malformed percent-encoding in proxy credentials to fail through CONNECT promises and Node request errors with `INVALID_PROXY_USERINFO`. Thanks @SebTardif.

package/README.md

@@ -1,133 +1,97 @@
-# 🌐 Proxyline
+# Proxyline 🌐 — Keep every Node request in line.
 
-![Proxyline banner](docs/assets/readme-banner.jpg)
-
-[![npm](https://img.shields.io/npm/v/%40openclaw%2Fproxyline.svg)](https://www.npmjs.com/package/@openclaw/proxyline)
-[![node](https://img.shields.io/node/v/%40openclaw%2Fproxyline.svg)](https://nodejs.org/)
-[![license](https://img.shields.io/npm/l/%40openclaw%2Fproxyline.svg)](./LICENSE)
-
-Process-global proxy routing for Node.js. One install replaces `node:http`, `node:https`, the undici/fetch global dispatcher, and provides WebSocket and explicit HTTP CONNECT helpers for the same policy.
+[![CI](https://img.shields.io/github/actions/workflow/status/openclaw/proxyline/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/openclaw/proxyline/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40openclaw%2Fproxyline?style=flat-square)](https://www.npmjs.com/package/@openclaw/proxyline)
+[![Node.js](https://img.shields.io/node/v/%40openclaw%2Fproxyline?style=flat-square)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/openclaw/proxyline?style=flat-square)](./LICENSE)
 
-Proxyline exists to make proxy behavior **explicit, observable, and hard to bypass accidentally** — so that "all egress goes through this gateway" is something you encode in code rather than hope for from environment variables.
+![Proxyline banner](docs/assets/readme-banner.jpg)
 
-Proxyline's runtime assurances assume it is installed before application and plugin networking code is loaded. Code that captured networking functions before installation, uses raw sockets, or owns a private/native transport stack is outside the normal Proxyline model.
+Proxyline installs one process-wide proxy policy across Node's built-in HTTP(S) clients, global fetch and Undici, compatible WebSocket clients, and explicit CONNECT tunnels. It is for Node applications that need one runtime to enforce proxy routing, explain its decisions, and restore the original networking globals.
 
-Website: [proxyline.dev](https://proxyline.dev)
+Documentation is available at [proxyline.dev](https://proxyline.dev).
 
-## Highlights
+## Install
 
-- **Two modes.** `managed` forces traffic through a configured proxy and fails closed on bad config. `ambient` reads `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` for tooling that needs environment compatibility.
-- **Covers the surfaces that matter.** `http.request`, `http.get`, `https.request`, `https.get`, both global agents, the undici global dispatcher, and helpers for WebSocket agents and HTTP CONNECT sockets.
-- **Replaces caller agents.** In managed mode and active ambient mode, a per-request `http.Agent` passed by a library does not bypass the proxy. TLS options on the caller agent (`ca`, `cert`, `key`, `rejectUnauthorized`, …) are preserved so destination TLS still validates.
-- **Intentional bypasses only.** Managed mode can accept a `bypassPolicy` callback, process-wide `registerBypass()`, or async-scoped `withBypass()` calls for trusted loopback or control-plane traffic that must stay direct; every bypass is visible through `explain()`.
-- **Embeddable runtime controls.** `ifActive` handles process singleton reuse/replacement, `undici` options tune dispatcher defaults, and `isProxylineDispatcher()` identifies Proxyline-owned dispatchers without constructor-name checks.
-- **Scoped proxy CA trust.** `proxyTls.ca` / `proxyTls.caFile` trust a private CA for the proxy endpoint only — no `NODE_EXTRA_CA_CERTS` and no `NODE_TLS_REJECT_UNAUTHORIZED=0`.
-- **Observable.** `proxy.explain(url)` returns a structured decision (`proxied` / `direct` with a `reason`), and an `onEvent` callback receives `runtime.installed`, `runtime.stopped`, and per-decision events. Proxy URLs are credential-redacted.
-- **Restoreable.** `proxy.stop()` restores the captured Node HTTP(S) methods, global agents, undici dispatcher, and fetch globals. The runtime is a process-wide singleton; by default a second active install throws `RUNTIME_ALREADY_ACTIVE`, while `ifActive` can reuse or replace intentionally.
+```sh
+pnpm add @openclaw/proxyline undici@^8.5.0
+```
 
-## Install
+Or with npm:
 
-```bash
-pnpm add @openclaw/proxyline
-# or
-npm install @openclaw/proxyline
+```sh
+npm install @openclaw/proxyline undici@^8.5.0
 ```
 
-Requires Node 22.19.0+ and a host `undici` dependency compatible with `>=8.5.0 <9`.
+Proxyline requires Node.js 22.19.0 or newer and a host `undici` version in the `>=8.5.0 <9` range. The package is ESM-only and includes TypeScript declarations.
 
 ## Quick start
 
-### Managed mode
+Save this as `proxy.mjs`:
 
-```ts
+```js
 import { installGlobalProxy } from "@openclaw/proxyline";
 
 const proxy = installGlobalProxy({
   mode: "managed",
-  proxyUrl: "https://proxy.corp.example:8443",
-  proxyTls: { caFile: "/etc/proxy-ca.pem" },
-  onEvent: (event) => console.debug("[proxyline]", event),
+  proxyUrl: "http://127.0.0.1:3128",
 });
+console.log(proxy.explain("https://api.example.com/").reason);
+proxy.stop();
+```
 
-console.log(proxy.explain("https://api.example.com/"));
+```sh
+node proxy.mjs
+# managed-proxy-active
 ```
 
-### Ambient mode
+This asks Proxyline for a routing decision without connecting to the placeholder proxy. Install Proxyline before loading application or plugin code that may capture networking functions.
 
-```ts
-import { installGlobalProxy } from "@openclaw/proxyline";
+## Choose a mode
 
-const proxy = installGlobalProxy({ mode: "ambient" });
-if (!proxy.active) {
-  console.warn("no HTTP_PROXY/HTTPS_PROXY/ALL_PROXY set — egress will be direct");
-}
-```
+Proxyline has two explicit routing modes:
 
-### WebSocket
+| Mode | Configuration | Direct traffic |
+| --- | --- | --- |
+| `managed` | A required `proxyUrl` in code | Only through `bypassPolicy`, `registerBypass()`, or `withBypass()` |
+| `ambient` | `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` | Whenever the environment has no matching proxy |
 
-```ts
-import WebSocket from "ws";
+Managed mode fails during setup when its proxy configuration is missing or unsupported. Ambient mode reads the environment once at installation and stays inactive when no supported HTTP or HTTPS proxy is configured. See [Modes](./docs/modes.md) and [Environment Variables](./docs/environment-variables.md) for the complete rules.
 
-const socket = new WebSocket("wss://events.example.com/", {
-  agent: proxy.createWebSocketAgent(),
-});
-```
+## Covered traffic
 
-### Explicit HTTP CONNECT
+| Surface | How Proxyline applies the policy |
+| --- | --- |
+| `node:http` and `node:https` | Patches request methods and replaces global and caller-supplied agents |
+| Global fetch and Undici | Installs a global dispatcher and a compatible fetch stack |
+| WebSocket clients | Supplies `proxy.createWebSocketAgent()` for clients that accept a Node agent |
+| Explicit tunnels | Supplies `openProxyConnectTunnel()` for callers that need the connected socket |
 
-```ts
-import { openProxyConnectTunnel } from "@openclaw/proxyline";
+`proxy.createNodeAgent()` and `proxy.createUndiciDispatcher()` expose the same policy to libraries that accept an agent or dispatcher directly. The [surface guide](./docs/surfaces.md) describes ownership, TLS preservation, and cleanup for each API.
 
-const controller = new AbortController();
-const socket = await openProxyConnectTunnel({
-  proxyUrl: "https://proxy.corp.example:8443",
-  proxyTls: { caFile: "/etc/proxy-ca.pem" },
-  targetHost: "api.example.com",
-  targetPort: 443,
-  timeoutMs: 2_000,
-  signal: controller.signal,
-});
-```
+## Bypasses and proxy trust
 
-### Conditional Node agent
+Managed mode supports deliberate direct-routing exceptions. A `bypassPolicy` handles installation-time policy, `registerBypass()` registers an exact process-wide exception, and `withBypass()` limits an exception to one async context. Each decision remains visible through `explain()`.
 
-```ts
-import { createAmbientNodeProxyAgent } from "@openclaw/proxyline";
+For an HTTPS proxy with a private CA, use `proxyTls.ca` or `proxyTls.caFile`. That trust applies only to the proxy connection; destination TLS validation remains separate. See [Proxy TLS](./docs/proxy-tls.md).
 
-const agent = createAmbientNodeProxyAgent({
-  protocol: "https",
-  proxyTls: { caFile: "/etc/proxy-ca.pem" },
-});
-```
-
-The helper returns `undefined` when ambient proxy env is not configured, so callers can pass an agent only when needed.
-It uses Proxyline's built-in HTTP/HTTPS Node agent, and `proxyTls` applies only to HTTPS proxy endpoints. SOCKS and PAC proxy schemes remain unsupported.
+## Observability and lifecycle
 
-## Product coverage
+`proxy.explain(url)` reports `proxied` or `direct`, the reason, the surface, and a credential-redacted proxy URL when one applies. The optional `onEvent` callback receives installation, shutdown, and decision events.
 
-- `http.request` / `http.get`: covered by global method patching and global agent replacement.
-- `https.request` / `https.get`: covered by global method patching and global agent replacement.
-- `globalThis.fetch`: covered by the fetch patch, including explicit dispatcher options and later Undici global dispatcher replacement in managed mode.
-- Undici global dispatcher: installed for Undici APIs that read the current process dispatcher.
-- WebSocket clients accepting a Node `agent`: covered with `proxy.createWebSocketAgent()`.
-- Caller-built `http.Agent` / `https.Agent`: overridden in managed and active ambient mode, with TLS options preserved.
-- Explicit HTTP CONNECT sockets: covered with `openProxyConnectTunnel()`.
-- Raw `net.connect` / `tls.connect`: out of scope; see [Security](./docs/security.md).
-- Native or private transport stacks: out of scope; see [Security](./docs/security.md).
+Only one Proxyline runtime is active in a process. A second installation fails by default; `ifActive` can reuse a compatible runtime or replace it intentionally. `proxy.stop()` restores the captured Node HTTP(S) methods, global agents, Undici dispatcher, and fetch globals. See [Observability](./docs/observability.md) and the [API Reference](./docs/api-reference.md).
 
-## Why not just env vars?
+## Security boundary
 
-Environment-based proxies are best-effort. A missing variable, a stale shell, a `NO_PROXY` typo, or a library that built its own `Dispatcher` quietly turns "always through the proxy" into "sometimes direct." Proxyline encodes the policy in code, replaces caller-built agents, and exposes a structured decision so logs can prove every request went the right way.
+Proxyline is a Node-process runtime, not an operating-system sandbox. Raw `net` or `tls` sockets, native or private transport stacks, networking functions captured before installation, and DNS traffic are outside its boundary. Combine it with operating-system egress controls when code in the process is not trusted.
 
-For tooling that *should* honor whatever the operator configured, ambient mode keeps the conventional behavior — with the same observability and the same credential redaction.
+Read the [security model](./docs/security.md) before treating managed mode as an enforcement boundary.
 
 ## Documentation
 
-Full docs live in [`docs/`](./docs/README.md):
-
 - [Getting Started](./docs/getting-started.md)
-- [Modes](./docs/modes.md) — managed vs ambient
-- [Surfaces](./docs/surfaces.md) — per-API behavior
+- [Modes](./docs/modes.md)
+- [Surfaces](./docs/surfaces.md)
 - [API Reference](./docs/api-reference.md)
 - [Environment Variables](./docs/environment-variables.md)
 - [Proxy TLS](./docs/proxy-tls.md)
@@ -136,9 +100,14 @@ Full docs live in [`docs/`](./docs/README.md):
 - [Troubleshooting](./docs/troubleshooting.md)
 - [Testing](./docs/testing.md)
 
-## Limits
+## Development
 
-Proxyline is a Node-process runtime, not an operating-system sandbox. Code can still bypass it by using raw `net`, raw `tls`, custom native networking, or a library that owns a private transport stack. Anything that captured `http.request` or `https.request` before Proxyline installed also bypasses it — install before loading third-party integrations when proxy routing is a security policy. See [`docs/security.md`](./docs/security.md) for the full threat model.
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test
+pnpm docs:build
+```
 
 ## License
 

package/dist/connect.d.ts

@@ -6,9 +6,22 @@ export type OpenProxyConnectTunnelOptions = Readonly<{
     proxyTls?: ProxylineTlsOptions;
     targetHost: string;
     targetPort: number;
+    /**
+     * Overall budget for the CONNECT handshake.
+     * Omit for the default (30s). Pass `0` (or a negative value) for no timeout.
+     */
     timeoutMs?: number;
     signal?: AbortSignal;
 }>;
+/** Default CONNECT handshake budget when `timeoutMs` is omitted. */
+export declare const DEFAULT_PROXY_CONNECT_TIMEOUT_MS = 30000;
+/**
+ * Resolve the CONNECT timeout to apply.
+ * - `undefined` → default 30s
+ * - `<= 0` → no timeout (unbounded)
+ * - positive → truncated milliseconds
+ */
+export declare function resolveProxyConnectTimeoutMs(timeoutMs: number | undefined): number | undefined;
 type ProxySocket = net.Socket | tls.TLSSocket;
 export declare function formatConnectAuthority(targetHost: string, targetPort: number): string;
 export declare function openProxyConnectTunnel(options: OpenProxyConnectTunnelOptions): Promise<ProxySocket>;

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,EAAgD,KAAK,mBAAmB,EAAqC,MAAM,aAAa,CAAC;AAExI,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC;IACvB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC,CAAC;AAMH,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC;AAsB9C,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAqBrF;AAkDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,WAAW,CAAC,CA4HtB"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,EAAgD,KAAK,mBAAmB,EAAqC,MAAM,aAAa,CAAC;AAExI,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC;IACvB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC,CAAC;AAEH,oEAAoE;AACpE,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAK9F;AAMD,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC;AAsB9C,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAqBrF;AAkDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,WAAW,CAAC,CA6HtB"}

package/dist/connect.js

@@ -1,6 +1,20 @@
 import net from "node:net";
 import tls from "node:tls";
 import { ProxylineError, decodeProxyUserinfoComponent, redactProxyUrl, resolveProxyTlsCa } from "./shared.js";
+/** Default CONNECT handshake budget when `timeoutMs` is omitted. */
+export const DEFAULT_PROXY_CONNECT_TIMEOUT_MS = 30_000;
+/**
+ * Resolve the CONNECT timeout to apply.
+ * - `undefined` → default 30s
+ * - `<= 0` → no timeout (unbounded)
+ * - positive → truncated milliseconds
+ */
+export function resolveProxyConnectTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined) {
+        return DEFAULT_PROXY_CONNECT_TIMEOUT_MS;
+    }
+    return timeoutMs > 0 ? Math.trunc(timeoutMs) : undefined;
+}
 const MAX_CONNECT_RESPONSE_HEADER_BYTES = 16 * 1024;
 const INVALID_CONNECT_AUTHORITY_PATTERN = /[\u0000-\u0020\u007f]/;
 const INVALID_CONNECT_HOST_DELIMITER_PATTERN = /[/:?#@\\]/;
@@ -177,10 +191,11 @@ export async function openProxyConnectTunnel(options) {
                 onAbort();
                 return;
             }
-            if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+            const connectTimeoutMs = resolveProxyConnectTimeoutMs(options.timeoutMs);
+            if (connectTimeoutMs !== undefined) {
                 timeout = setTimeout(() => {
-                    fail(new Error(`proxy CONNECT timed out after ${Math.trunc(options.timeoutMs ?? 0)}ms`));
-                }, Math.trunc(options.timeoutMs));
+                    fail(new Error(`proxy CONNECT timed out after ${connectTimeoutMs}ms`));
+                }, connectTimeoutMs);
             }
             socket = connectToProxy(proxy, options.proxyTls);
             socket.once(proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);

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

@@ -4,7 +4,7 @@ import net from "node:net";
 import tls from "node:tls";
 import { domainToASCII } from "node:url";
 import { readProxyEnv, resolveAmbientProxyForUrl, } from "./env.js";
-import { formatConnectAuthority } from "./connect.js";
+import { formatConnectAuthority, resolveProxyConnectTimeoutMs } from "./connect.js";
 import { ProxylineError, decodeProxyUserinfoComponent, resolveProxyTlsCa } from "./shared.js";
 const MAX_CONNECT_RESPONSE_HEADER_BYTES = 16 * 1024;
 const INVALID_PROXY_TARGET_HOST_DELIMITER_PATTERN = /[/:?#@\\]/;
@@ -314,6 +314,9 @@ class ProxylineHttpForwardAgent extends http.Agent {
     }
     createConnection(_options, callback) {
         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) => {
                 callback(error, socket);
@@ -324,6 +327,7 @@ class ProxylineHttpForwardAgent extends http.Agent {
             };
             socket.once(this.#proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
             socket.once("error", onError);
+            return undefined;
         }
         return socket;
     }
@@ -541,10 +545,22 @@ class ProxylineConnectAgent extends http.Agent {
             };
             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 timeoutMs = normalizedPositiveInteger(options.timeout ?? requestTimeout);
-        if (timeoutMs !== undefined) {
-            startPendingTimeout(timeoutMs);
+        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("abort", onRequestClosed);
         request?.once("close", onRequestClosed);

package/docs/api-reference.md

@@ -264,7 +264,7 @@ type OpenProxyConnectTunnelOptions = Readonly<{
 - `proxyUrl` — `http://` or `https://`. Userinfo becomes a `Proxy-Authorization: Basic` header.
 - `proxyTls` — CA trust for HTTPS proxies. See [Proxy TLS](./proxy-tls.md).
 - `targetHost` / `targetPort` — what to ask the proxy to connect to.
-- `timeoutMs` — overall budget for the CONNECT handshake.
+- `timeoutMs` — overall budget for the CONNECT handshake. Defaults to `30000` when omitted. Pass `0` for no timeout.
 - `signal` — optional caller cancellation; aborting rejects the handshake and destroys its active proxy socket.
 
 ### `AmbientNodeProxyAgentOptions`

package/docs/surfaces.md

@@ -93,7 +93,7 @@ Properties:
 - HTTPS proxies use ALPN `http/1.1`. SNI is the proxy hostname unless that is an IP literal.
 - Userinfo in the `proxyUrl` becomes a `Proxy-Authorization: Basic ...` header.
 - A bounded `16 KiB` header buffer protects against malicious or runaway proxy responses.
-- `timeoutMs` is enforced and emits a `CONNECT_FAILED` error on expiry.
+- `timeoutMs` is enforced and emits a `CONNECT_FAILED` error on expiry. When omitted, the default is 30 seconds; pass `0` for no timeout.
 - `signal` aborts an in-progress handshake and destroys its active proxy socket.
 - Bytes the proxy sends after the response headers are re-injected with `socket.unshift()` so the caller sees the full target stream.
 - Non-2xx status lines, header overrun, premature close, and socket errors are all surfaced as `ProxylineError` with code `CONNECT_FAILED`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/proxyline",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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.18.0",
+  "packageManager": "pnpm@11.20.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -64,9 +64,9 @@
   "devDependencies": {
     "@types/node": "26.1.2",
     "@types/ws": "8.18.1",
-    "tsx": "4.23.1",
+    "tsx": "4.23.5",
     "typescript": "^7.0.2",
-    "undici": "8.9.0",
+    "undici": "8.10.0",
     "ws": "8.21.1"
   },
   "engines": {

package/src/connect.ts

@@ -7,10 +7,30 @@ export type OpenProxyConnectTunnelOptions = Readonly<{
   proxyTls?: ProxylineTlsOptions;
   targetHost: string;
   targetPort: number;
+  /**
+   * Overall budget for the CONNECT handshake.
+   * Omit for the default (30s). Pass `0` (or a negative value) for no timeout.
+   */
   timeoutMs?: number;
   signal?: AbortSignal;
 }>;
 
+/** Default CONNECT handshake budget when `timeoutMs` is omitted. */
+export const DEFAULT_PROXY_CONNECT_TIMEOUT_MS = 30_000;
+
+/**
+ * Resolve the CONNECT timeout to apply.
+ * - `undefined` → default 30s
+ * - `<= 0` → no timeout (unbounded)
+ * - positive → truncated milliseconds
+ */
+export function resolveProxyConnectTimeoutMs(timeoutMs: number | undefined): number | undefined {
+  if (timeoutMs === undefined) {
+    return DEFAULT_PROXY_CONNECT_TIMEOUT_MS;
+  }
+  return timeoutMs > 0 ? Math.trunc(timeoutMs) : undefined;
+}
+
 const MAX_CONNECT_RESPONSE_HEADER_BYTES = 16 * 1024;
 const INVALID_CONNECT_AUTHORITY_PATTERN = /[\u0000-\u0020\u007f]/;
 const INVALID_CONNECT_HOST_DELIMITER_PATTERN = /[/:?#@\\]/;
@@ -219,10 +239,11 @@ export async function openProxyConnectTunnel(
         onAbort();
         return;
       }
-      if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+      const connectTimeoutMs = resolveProxyConnectTimeoutMs(options.timeoutMs);
+      if (connectTimeoutMs !== undefined) {
         timeout = setTimeout(() => {
-          fail(new Error(`proxy CONNECT timed out after ${Math.trunc(options.timeoutMs ?? 0)}ms`));
-        }, Math.trunc(options.timeoutMs));
+          fail(new Error(`proxy CONNECT timed out after ${connectTimeoutMs}ms`));
+        }, connectTimeoutMs);
       }
       socket = connectToProxy(proxy, options.proxyTls);
       socket.once(proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);

package/src/node-http.ts

@@ -8,7 +8,7 @@ import {
   resolveAmbientProxyForUrl,
   type ProxyEnvSnapshot,
 } from "./env.js";
-import { formatConnectAuthority } from "./connect.js";
+import { formatConnectAuthority, resolveProxyConnectTimeoutMs } from "./connect.js";
 import { ProxylineError, decodeProxyUserinfoComponent, resolveProxyTlsCa, type ProxylineTlsOptions } from "./shared.js";
 import type { ProxylineSurface, ProxyResolver } from "./types.js";
 
@@ -442,6 +442,9 @@ class ProxylineHttpForwardAgent extends http.Agent {
     callback?: (error: Error | null, socket: net.Socket) => void,
   ): net.Socket {
     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 => {
         callback(error, socket);
@@ -452,6 +455,7 @@ class ProxylineHttpForwardAgent extends http.Agent {
       };
       socket.once(this.#proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
       socket.once("error", onError);
+      return undefined as unknown as net.Socket;
     }
     return socket;
   }
@@ -695,10 +699,21 @@ class ProxylineConnectAgent extends http.Agent {
       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 timeoutMs = normalizedPositiveInteger(options.timeout ?? requestTimeout);
-    if (timeoutMs !== undefined) {
-      startPendingTimeout(timeoutMs);
+    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("abort", onRequestClosed);
     request?.once("close", onRequestClosed);