@openclaw/proxyline 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.2 - 2026-05-17
+
+- Fixed managed Undici proxy dispatchers so HTTPS proxy endpoints addressed by IP do not send invalid IP-literal SNI.
+
+## 0.3.1 - 2026-05-16
+
+- Fixed `withBypass()` to scope temporary bypasses to the calling async context instead of process-wide state.
+- Fixed HTTPS SNI preservation when Node request options override a URL hostname.
+- Hardened package and docs release output by preserving declaration-map sources, shipping product docs, rejecting duplicate docs pages, avoiding lockfile-bypassing prepack installs, and keeping package artifact checks portable on Windows.
+
 ## 0.3.0 - 2026-05-15
 
 - Added branded Proxyline dispatcher detection, reusable active-runtime installs, scoped dynamic bypass registration, first-class undici dispatcher tuning options, and a side-effect-light dispatcher detection subpath.

package/README.md

@@ -17,7 +17,7 @@ Website: [proxyline.dev](https://proxyline.dev)
 - **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 or scoped `registerBypass()` / `withBypass()` calls for trusted loopback or control-plane traffic that must stay direct; every bypass is visible through `explain()`.
+- **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.
@@ -99,18 +99,16 @@ const agent = createAmbientNodeProxyAgent({
 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.
 
-## Feature matrix
-
-| Surface | Covered | Notes |
-| --- | --- | --- |
-| `http.request` / `http.get` | yes | global method patch + global agent swap |
-| `https.request` / `https.get` | yes | global method patch + global agent swap |
-| `fetch` / undici global dispatcher | yes | `globalThis.fetch` patch + `setGlobalDispatcher` |
-| WebSocket clients accepting a Node `agent` | yes | `proxy.createWebSocketAgent()` |
-| Caller-built `http.Agent` / `https.Agent` | overridden in managed and active ambient mode | TLS options preserved |
-| Explicit HTTP CONNECT socket | yes | `openProxyConnectTunnel()` |
-| Raw `net.connect` / `tls.connect` | no | out of scope, see [Security](./docs/security.md) |
-| Native or private transport stacks | no | out of scope, see [Security](./docs/security.md) |
+## Product coverage
+
+- `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.
+- `fetch` / undici global dispatcher: covered by the `globalThis.fetch` patch and `setGlobalDispatcher`.
+- 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).
 
 ## Why not just env vars?
 

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

@@ -1 +1 @@
-{"version":3,"file":"node-http.d.ts","sourceRoot":"","sources":["../src/node-http.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,KAAK,MAAM,YAAY,CAAC;AAI/B,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAqC,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,GAAG;IAChF,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;CAC5B,CAAC;AAEF,KAAK,cAAc,GAAG,OAAO,IAAI,CAAC,OAAO,CAAC;AAC1C,KAAK,gBAAgB,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC,KAAK,CAAC;AACxE,KAAK,gBAAgB,GAAG,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;AAC/D,KAAK,uBAAuB,GAAG,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,GAAG;IAC1E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAYF,KAAK,qBAAqB,GAAG,gBAAgB,GAAG;IAC9C,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,cAAc,EAAE,CACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,KACzB,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC,CAAC;AAOF,eAAO,MAAM,4BAA4B,gPAkB/B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC;IACjC,OAAO,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC;IACzB,eAAe,EAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IACzC,YAAY,EAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACnC,QAAQ,EAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IAC3B,gBAAgB,EAAE,OAAO,KAAK,CAAC,WAAW,CAAC;CAC5C,CAAC;AA6DF,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,cAAc,EAC/D,cAAc,EAAE,OAAO,EACvB,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAsCT;AAiiBD,qBAAa,uBAAwB,SAAQ,IAAI,CAAC,KAAK;;IACrD,SAAgB,OAAO,EAAE,gBAAgB,CAAC;gBAYvB,OAAO,EAAE,qBAAqB;IAcjD,IAAW,WAAW,IAAI,MAAM,CAI/B;IAED,IAAW,WAAW,CAAC,KAAK,EAAE,MAAM,EAEnC;IAED,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED,IAAW,QAAQ,CAAC,MAAM,EAAE,MAAM,EAEjC;IAEM,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,GAAG,MAAM;IAsCjE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI;IA6BlE,OAAO,IAAI,IAAI;CAShC;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,eAAe,GAAE,MAAM,GAAG,OAAgB,GACzC,uBAAuB,CAMzB;AAED,wBAAgB,qBAAqB,IAAI,uBAAuB,CAI/D;AAED,MAAM,MAAM,4BAA4B,GAAG;IACzC,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC,CAAC;AAMF,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAIT;AAED,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,4BAAiC,GACzC,uBAAuB,GAAG,SAAS,CAWrC"}
+{"version":3,"file":"node-http.d.ts","sourceRoot":"","sources":["../src/node-http.ts"],"names":[],"mappings":"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"}

package/dist/node-http.js

@@ -53,15 +53,18 @@ function preserveCallerAgentOptions(options) {
         }
     }
 }
+function unbracketHostname(hostname) {
+    return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
 function inferDestinationHostname(url, options) {
-    if (url !== undefined) {
-        return url instanceof URL ? url.hostname : new URL(url).hostname;
-    }
     if (typeof options.hostname === "string") {
-        return options.hostname;
+        return unbracketHostname(options.hostname);
+    }
+    if (url !== undefined) {
+        return unbracketHostname(url instanceof URL ? url.hostname : new URL(url).hostname);
     }
     if (typeof options.host === "string") {
-        return options.host.replace(/:\d*$/, "");
+        return unbracketHostname(splitHostPort(options.host).host);
     }
     return undefined;
 }

package/dist/runtime.d.ts.map

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

package/dist/runtime.js

@@ -1,6 +1,8 @@
 import http from "node:http";
 import https from "node:https";
-import { Agent as UndiciAgent, Dispatcher, FormData as UndiciFormData, Headers as UndiciHeaders, Request as UndiciRequest, Response as UndiciResponse, errors as undiciErrors, fetch as undiciFetch, getGlobalDispatcher, ProxyAgent as UndiciProxyAgent, setGlobalDispatcher, } from "undici";
+import { AsyncLocalStorage } from "node:async_hooks";
+import net from "node:net";
+import { Agent as UndiciAgent, Dispatcher, FormData as UndiciFormData, Headers as UndiciHeaders, Pool as UndiciPool, Request as UndiciRequest, Response as UndiciResponse, errors as undiciErrors, fetch as undiciFetch, getGlobalDispatcher, ProxyAgent as UndiciProxyAgent, setGlobalDispatcher, } from "undici";
 import { createAmbientProxyResolver, EMPTY_PROXY_ENV, resolveAmbientProxyForUrl, readProxyEnv, } from "./env.js";
 import { bindNodeHttpMethod, createDirectNodeAgent, createNodeProxyAgent, } from "./node-http.js";
 import { formatUrl, ProxylineError, redactProxyUrl, resolveProxyTlsCa, } from "./shared.js";
@@ -156,6 +158,12 @@ function bypassKey(url, surface) {
 }
 function createDynamicBypassRegistry() {
     const counts = new Map();
+    const scopedBypasses = new AsyncLocalStorage();
+    const hasScopedBypass = (url, surface) => {
+        const scoped = scopedBypasses.getStore();
+        return scoped !== undefined &&
+            (scoped.has(bypassKey(url, surface)) || scoped.has(bypassKey(url, undefined)));
+    };
     return {
         add: (registration) => {
             const key = bypassKey(registration.url, registration.surface);
@@ -175,8 +183,15 @@ function createDynamicBypassRegistry() {
                 }
             };
         },
-        has: (url, surface) => (counts.get(bypassKey(url, surface)) ?? 0) > 0 ||
+        has: (url, surface) => hasScopedBypass(url, surface) ||
+            (counts.get(bypassKey(url, surface)) ?? 0) > 0 ||
             (counts.get(bypassKey(url, undefined)) ?? 0) > 0,
+        runScoped: (registration, run) => {
+            const inherited = scopedBypasses.getStore();
+            const scoped = new Set(inherited);
+            scoped.add(bypassKey(registration.url, registration.surface));
+            return scopedBypasses.run(scoped, run);
+        },
     };
 }
 function proxyEnvSnapshotKey(env) {
@@ -258,10 +273,40 @@ function resolveUndiciBaseOptions(options) {
 function createUndiciAgent(options) {
     return new UndiciAgent(resolveUndiciBaseOptions(options));
 }
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stripIpServernameFromConnectOptions(options) {
+    if (!isObjectRecord(options) || typeof options.servername !== "string") {
+        return options;
+    }
+    const servername = options.servername.replace(/^\[|\]$/g, "");
+    if (net.isIP(servername) === 0) {
+        return options;
+    }
+    const next = { ...options };
+    delete next.servername;
+    return next;
+}
+function stripIpServernameFromConnect(connect) {
+    if (typeof connect !== "function") {
+        return connect;
+    }
+    return (options, callback) => connect(stripIpServernameFromConnectOptions(options), callback);
+}
+function createProxyClientFactory() {
+    return (origin, options) => {
+        const clientOptions = isObjectRecord(options)
+            ? { ...options, connect: stripIpServernameFromConnect(options.connect) }
+            : options;
+        return new UndiciPool(origin, clientOptions);
+    };
+}
 function createUndiciProxyAgent(proxyUrl, options) {
     return new UndiciProxyAgent({
         ...resolveUndiciBaseOptions(options.undici),
         uri: proxyUrl,
+        clientFactory: createProxyClientFactory(),
         ...(options.proxyCa !== undefined ? { proxyTls: { ca: options.proxyCa } } : {}),
     });
 }
@@ -624,28 +669,13 @@ export function installProxyline(options) {
             emit(options.onEvent, { type: "runtime.stopped", mode: options.mode });
         },
         withBypass: (registration, run) => {
-            const unregister = handle.registerBypass(registration);
-            try {
-                const result = run();
-                if (isPromiseLike(result)) {
-                    void Promise.resolve(result).then(unregister, unregister);
-                    return result;
-                }
-                unregister();
-                return result;
-            }
-            catch (error) {
-                unregister();
-                throw error;
+            if (stopped || proxyUrl === undefined) {
+                return run();
             }
+            return dynamicBypasses.runScoped(registration, run);
         },
     };
     activeHandle = hasActiveProxy ? handle : activeHandle;
     return handle;
 }
 export const installGlobalProxy = installProxyline;
-function isPromiseLike(value) {
-    return typeof value === "object" &&
-        value !== null &&
-        typeof value.then === "function";
-}

package/docs/CNAME

@@ -0,0 +1 @@
+proxyline.dev

package/docs/README.md

@@ -0,0 +1,34 @@
+---
+title: Overview
+permalink: /
+description: "Process-global proxy routing for Node.js. One install routes node:http, node:https, undici/fetch, plus WebSocket and HTTP CONNECT helpers through a single explicit policy."
+---
+
+# Proxyline Documentation
+
+Process-global proxy routing for Node.js. Proxyline patches the network surfaces a Node process can reach without owning a private transport stack, so a single policy applies to `node:http`, `node:https`, undici/fetch, WebSocket clients that accept agents, and explicit HTTP CONNECT helpers.
+
+## Contents
+
+- [Getting Started](./getting-started.md) — install, first proxy, shutdown.
+- [Modes](./modes.md) — `managed` vs `ambient` safety postures.
+- [Surfaces](./surfaces.md) — which network APIs Proxyline covers and how.
+- [API Reference](./api-reference.md) — every exported type, function, and field.
+- [Environment Variables](./environment-variables.md) — how `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` are interpreted.
+- [Proxy TLS](./proxy-tls.md) — scoping CA trust to the proxy endpoint.
+- [Observability](./observability.md) — events, `explain()`, credential redaction.
+- [Security](./security.md) — threat model, limits, what Proxyline does **not** do.
+- [Troubleshooting](./troubleshooting.md) — common failure modes and fixes.
+- [Testing](./testing.md) — the in-process proxy lab.
+
+## Product coverage
+
+- `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.
+- `fetch` / undici global dispatcher: covered by the `globalThis.fetch` patch and `setGlobalDispatcher`.
+- WebSocket clients accepting a Node `agent`: covered with `proxy.createWebSocketAgent()`.
+- WebSocket clients without an `agent` option: partially covered when the upgrade path reuses patched `http.request`.
+- Explicit HTTP CONNECT sockets: covered with `openProxyConnectTunnel()`.
+- Caller-built `http.Agent` / `https.Agent`: overridden per request in managed and active ambient mode.
+- Raw `net.connect` / `tls.connect`: out of scope; see [Security](./security.md).
+- Native or third-party transport stacks: out of scope; see [Security](./security.md).

package/docs/api-reference.md

@@ -0,0 +1,280 @@
+# API Reference
+
+Every public export, with the exact shape from `src/index.ts`, `src/connect.ts`, and `src/node-http.ts`.
+
+## Functions
+
+### `installProxyline(options): ProxylineHandle`
+
+Aliased as `installGlobalProxy`. Installs the runtime and returns a handle.
+
+- Throws `ProxylineError` with code `MANAGED_PROXY_URL_REQUIRED` if `mode: "managed"` is used without a `proxyUrl`.
+- Throws `ProxylineError` with code `UNSUPPORTED_PROXY_PROTOCOL` if managed-mode `proxyUrl` is not `http://` or `https://`.
+- Throws `ProxylineError` with code `RUNTIME_ALREADY_ACTIVE` if another Proxyline runtime is already installed and `ifActive` is omitted or cannot safely reuse the active runtime.
+
+In managed mode (and active ambient mode), `installProxyline`:
+
+- Captures originals for `http.request`, `http.get`, `http.globalAgent`, `https.request`, `https.get`, `https.globalAgent`.
+- Captures the current undici global dispatcher and fetch globals.
+- Installs patched `http.request`/`get`, `https.request`/`get`.
+- Replaces `http.globalAgent` and `https.globalAgent` with Proxyline's HTTP/HTTPS Node agent.
+- Calls `undici.setGlobalDispatcher` with a `ProxyAgent` (managed) or Proxyline's ambient dispatcher (ambient), and patches `globalThis.fetch` plus `Request`, `Response`, `Headers`, and `FormData` to use that dispatcher-compatible fetch stack.
+- Emits `runtime.installed`.
+
+In inactive ambient mode (no supported proxy env variables), no patches are installed; the handle returns a passive observer with `active: false`.
+
+### `openProxyConnectTunnel(options): Promise<net.Socket | tls.TLSSocket>`
+
+Opens a one-shot HTTP CONNECT tunnel through a proxy. See [Surfaces — HTTP CONNECT tunnel](./surfaces.md#http-connect-tunnel).
+
+### `hasAmbientNodeProxyConfigured(options?): boolean`
+
+Returns `true` when the ambient proxy environment would proxy a probe URL for the requested protocol. Defaults to `protocol: "https"`.
+
+```ts
+hasAmbientNodeProxyConfigured({ protocol: "https" });
+```
+
+### `createAmbientNodeProxyAgent(options?): http.Agent | undefined`
+
+Returns a Proxyline-backed Node agent when ambient env proxy settings apply, or `undefined` when no proxy is configured for the requested protocol. This is for libraries that accept a Node `agent` option but should stay direct when the operator has no proxy env configured.
+
+```ts
+const agent = createAmbientNodeProxyAgent({
+  protocol: "https",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+});
+```
+
+### `redactProxyUrl(value: string | URL): string`
+
+Strips userinfo, search, and fragment from a URL. Used internally to keep events and decisions free of credentials. Safe to use on log lines you build yourself.
+
+```ts
+redactProxyUrl("https://user:secret@proxy.example:8443/path?q=1#frag");
+// → "https://proxy.example:8443/path"
+```
+
+### `resolveProxyTlsCa(options): string | undefined`
+
+Resolves a `ProxylineTlsOptions` value to a PEM string by reading `caFile` from disk if needed. Returns `undefined` when no CA material is supplied. Exposed so callers can pre-resolve before passing values into their own TLS-using code.
+
+## Classes
+
+### `ProxylineError extends Error`
+
+```ts
+class ProxylineError extends Error {
+  readonly code: string;
+  readonly name: "ProxylineError";
+}
+```
+
+Codes:
+
+- `MANAGED_PROXY_URL_REQUIRED` — `mode: "managed"` was used without `proxyUrl`.
+- `UNSUPPORTED_PROXY_PROTOCOL` — proxy URL scheme is not `http://` or `https://`.
+- `RUNTIME_ALREADY_ACTIVE` — another Proxyline runtime is already installed.
+- `CONNECT_FAILED` — `openProxyConnectTunnel` failed (bad response, timeout, header overrun, or socket error).
+- `INVALID_CONNECT_TARGET` — `openProxyConnectTunnel` received an empty or unsafe target host, invalid bracket syntax, or an invalid target port.
+
+## Types
+
+### `ProxylineMode`
+
+```ts
+type ProxylineMode = "managed" | "ambient";
+```
+
+See [Modes](./modes.md).
+
+### `ProxylineSurface`
+
+```ts
+type ProxylineSurface =
+  | "node-http"
+  | "node-https"
+  | "undici"
+  | "websocket"
+  | "connect"
+  | "unknown";
+```
+
+Used in `explain()` decisions and event payloads to identify which network surface a decision is for. Pass it via `explain(url, { surface })`.
+
+### `ProxylineOptions`
+
+```ts
+type ProxylineOptions = Readonly<{
+  mode: ProxylineMode;
+  proxyUrl?: string | URL;
+  proxyTls?: ProxylineTlsOptions;
+  bypassPolicy?: ProxylineBypassPolicy;
+  ifActive?: "error" | "reuse-compatible" | "replace";
+  onEvent?: (event: ProxylineEvent) => void;
+  undici?: ProxylineUndiciOptions;
+}>;
+```
+
+- `mode` — required. `"managed"` or `"ambient"`.
+- `proxyUrl` — required in managed mode, ignored in ambient mode. Managed-mode URLs must be `http://` or `https://`.
+- `proxyTls` — CA trust scoped to the proxy endpoint. See [Proxy TLS](./proxy-tls.md).
+- `bypassPolicy` — managed-mode escape hatch for trusted traffic that should go direct. Ignored in ambient mode.
+- `ifActive` — process singleton behavior when Proxyline is already active. Defaults to `"error"`. `"reuse-compatible"` returns the active handle when mode/proxy/TLS/bypass/undici settings match; ambient mode also requires the captured proxy env snapshot to match. `"replace"` stops the active runtime before installing the new one.
+- `onEvent` — callback fired with every `ProxylineEvent`.
+- `undici` — default options for Proxyline-owned undici dispatchers.
+
+### `ProxylineUndiciOptions`
+
+```ts
+type ProxylineUndiciOptions = Readonly<{
+  allowH2?: boolean;
+  bodyTimeout?: number;
+  headersTimeout?: number;
+  connect?: Readonly<{
+    autoSelectFamily?: boolean;
+    autoSelectFamilyAttemptTimeout?: number;
+  }>;
+}>;
+```
+
+These options apply to the global dispatcher installed by `installGlobalProxy()` and to dispatchers returned by `createUndiciDispatcher()`.
+
+### `ProxylineTlsOptions`
+
+```ts
+type ProxylineTlsOptions = Readonly<{
+  ca?: string;     // PEM string
+  caFile?: string; // path read with fs.readFileSync(..., "utf8")
+}>;
+```
+
+When both are provided, `ca` wins.
+
+### `ProxylineDecision`
+
+```ts
+type ProxylineDecision = Readonly<{
+  kind: "proxied" | "direct" | "blocked";
+  reason: string;
+  surface: ProxylineSurface;
+  url: string;
+  proxyUrl?: string; // redacted
+}>;
+```
+
+Known `reason` values:
+
+- `"managed-proxy-active"` — managed mode applied.
+- `"managed-proxy-bypass-policy"` — managed mode was active, but `bypassPolicy` intentionally sent the URL direct.
+- `"managed-proxy-unsupported-url-scheme"` — managed mode is active, but the URL scheme is not one Proxyline can proxy.
+- `"ambient-proxy-active"` — ambient mode resolved a proxy from env.
+- `"ambient-proxy-not-configured"` — ambient mode has no proxy env set, or the URL scheme is unsupported.
+- `"no-proxy-match"` — the URL matched `NO_PROXY`.
+- `"runtime-stopped"` — `explain()` was called after `stop()`.
+
+`kind: "blocked"` is reserved for future explicit deny rules; the current implementation does not produce blocked decisions.
+
+### `ProxylineBypassRequest`
+
+```ts
+type ProxylineBypassRequest = Readonly<{
+  surface: ProxylineSurface;
+  url: string;
+}>;
+```
+
+### `ProxylineBypassPolicy`
+
+```ts
+type ProxylineBypassPolicy = (request: ProxylineBypassRequest) => boolean;
+```
+
+Return `true` to send that managed-mode request direct. Use this only for explicitly trusted destinations such as loopback control-plane endpoints.
+
+### `ProxylineEvent`
+
+```ts
+type ProxylineEvent =
+  | Readonly<{ type: "runtime.installed"; mode: ProxylineMode; active: boolean; proxyUrl?: string }>
+  | Readonly<{ type: "runtime.stopped"; mode: ProxylineMode }>
+  | Readonly<{ type: "decision"; decision: ProxylineDecision }>
+  | Readonly<{ type: "warning"; code: string; message: string }>;
+```
+
+`decision` events fire from inside `explain()`. `runtime.installed` and `runtime.stopped` fire from `installProxyline` and `handle.stop()` respectively. `warning` is reserved for future runtime diagnostics.
+
+### `ExplainOptions`
+
+```ts
+type ExplainOptions = Readonly<{
+  surface?: ProxylineSurface;
+}>;
+```
+
+### `ProxylineHandle`
+
+```ts
+type ProxylineHandle = Readonly<{
+  mode: ProxylineMode;
+  active: boolean;
+  proxyUrl?: string;
+  createNodeAgent: () => http.Agent;
+  createUndiciDispatcher: () => Dispatcher;
+  createWebSocketAgent: () => http.Agent;
+  explain: (url: string | URL, options?: ExplainOptions) => ProxylineDecision;
+  registerBypass: (registration: ProxylineBypassRegistration) => () => void;
+  stop: () => void;
+  withBypass: <T>(registration: ProxylineBypassRegistration, run: () => T) => T;
+}>;
+```
+
+- `mode` — the mode this handle was installed with.
+- `active` — `true` when the runtime is installed and forcing/respecting a proxy.
+- `proxyUrl` — redacted proxy URL string when active.
+- `createNodeAgent()` — proxy-aware `http.Agent` for ad-hoc node:http(s) use. Returns a direct agent when inactive or after `stop()`.
+- `createUndiciDispatcher()` — proxy-aware undici `Dispatcher`. Returns a direct `UndiciAgent()` when ambient-inactive or after `stop()`.
+- `createWebSocketAgent()` — same as `createNodeAgent()` but typed for WebSocket clients.
+- `explain(url, options?)` — returns a `ProxylineDecision` and emits a `decision` event.
+- `registerBypass({ url, surface? })` — managed-mode process-wide bypass. Returns an unregister callback. When `surface` is omitted, the bypass matches any surface for that exact URL.
+- `stop()` — restores the captured Node HTTP(S) stack, undici dispatcher, and fetch globals, destroys Proxyline-owned runtime agents/dispatchers, emits `runtime.stopped`. Idempotent.
+- `withBypass(registration, run)` — applies a bypass only to `run()` and async work created inside that callback.
+
+### Dispatcher Detection
+
+```ts
+isProxylineDispatcher(dispatcher: unknown): boolean;
+```
+
+Returns `true` for Proxyline-owned managed and ambient undici dispatchers. Use this instead of constructor-name checks when integrating with code that also manages undici globals. Import from `@openclaw/proxyline/dispatcher-brand` when detection must not load Proxyline's full runtime.
+
+### `OpenProxyConnectTunnelOptions`
+
+```ts
+type OpenProxyConnectTunnelOptions = Readonly<{
+  proxyUrl: string | URL;
+  proxyTls?: ProxylineTlsOptions;
+  targetHost: string;
+  targetPort: number;
+  timeoutMs?: number;
+}>;
+```
+
+- `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.
+
+### `AmbientNodeProxyAgentOptions`
+
+```ts
+type AmbientNodeProxyAgentOptions = {
+  env?: ProxyEnvSnapshot;
+  protocol?: "http" | "https";
+  proxyTls?: ProxylineTlsOptions;
+};
+```
+
+- `env` — optional env snapshot. Defaults to reading process env.
+- `protocol` — probe protocol, defaulting to `"https"`.
+- `proxyTls` — CA trust for HTTPS proxy endpoints. See [Proxy TLS](./proxy-tls.md).

package/docs/environment-variables.md

@@ -0,0 +1,70 @@
+# Environment Variables
+
+Ambient mode reads its configuration from the environment at install time. Managed mode does not.
+
+## Variables
+
+| Variable | Used for | Notes |
+| --- | --- | --- |
+| `HTTP_PROXY` | proxy for `http:` and `ws:` URLs | lower case wins when both are set |
+| `HTTPS_PROXY` | proxy for `https:` and `wss:` URLs | |
+| `ALL_PROXY` | fallback when the protocol-specific variable is unset or unsupported | |
+| `NO_PROXY` | comma- or whitespace-separated list of exemptions | matched against the destination URL |
+| `http_proxy` | lowercase alias for `HTTP_PROXY` | takes precedence over uppercase |
+| `https_proxy` | lowercase alias | |
+| `all_proxy` | lowercase alias | |
+| `no_proxy` | lowercase alias | |
+
+Empty or whitespace-only values are treated as unset.
+
+## Activation
+
+The ambient runtime is **active** when any of `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` (or their lowercase forms) is set to a supported `http://` or `https://` proxy endpoint. Bare endpoints count because Proxyline defaults them to `http://`.
+
+`NO_PROXY` alone does not activate the runtime. With only `NO_PROXY` set, `proxy.active` is `false` and Proxyline installs no patches.
+
+## Snapshot at install
+
+The values are read **once** at `installProxyline` time. Changing `process.env.HTTP_PROXY` afterwards does not retroactively activate or reconfigure Proxyline. Call `proxy.stop()` and re-install if the environment changes.
+
+## Proxy URL parsing
+
+- Bare endpoints (no scheme) default to `http://`. `HTTPS_PROXY=proxy.corp:8080` becomes `http://proxy.corp:8080`.
+- `http://` and `https://` are the only accepted schemes. Anything else is ignored.
+- Userinfo (`user:pass@`) in the proxy URL becomes a `Proxy-Authorization: Basic` header.
+
+## NO_PROXY matching
+
+Entries are split on commas and whitespace. Matching rules, in order:
+
+1. `*` alone matches everything. The URL goes direct.
+2. Entries can include a port: `internal.corp:8443`. When present, the entry only matches the URL's port (defaulting to `80` for `http`/`ws` and `443` for `https`/`wss`).
+3. Entries starting with `.` or `*` are suffix matches. `.corp.example` matches `api.corp.example` and `corp.example`. `*.corp.example` is equivalent.
+4. Other entries are exact host matches.
+5. IPv6 entries may be bracketed (`[::1]:8443`) or bare (`::1`). Bracketed forms are stripped before comparison.
+6. Hostnames are lowercased and trailing dots are stripped before comparison.
+
+When a URL matches `NO_PROXY`, `explain()` returns `kind: "direct"`, `reason: "no-proxy-match"`.
+
+## Examples
+
+```bash
+# go through the proxy for everything except internal hosts
+export HTTPS_PROXY="https://proxy.corp.example:8443"
+export NO_PROXY=".corp.example,localhost,127.0.0.1,::1"
+```
+
+```bash
+# only https traffic via proxy, http stays direct
+export HTTPS_PROXY="https://proxy.corp.example:8443"
+```
+
+```bash
+# fall through to ALL_PROXY for everything
+export ALL_PROXY="socks-not-supported://example"   # ignored — only http/https proxies are honored
+export ALL_PROXY="http://gateway.corp:3128"        # used for both http and https URLs
+```
+
+## Interaction with `fetch`
+
+The undici global dispatcher is installed with Proxyline's own ambient resolver over the same `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` snapshot Proxyline read at install time. `fetch` and `node:http` therefore agree on the proxy decision for any URL.