@openclaw/proxyline 0.3.0 → 0.3.2

package/docs/troubleshooting.md

@@ -0,0 +1,71 @@
+# Troubleshooting
+
+## `ProxylineError: MANAGED_PROXY_URL_REQUIRED`
+
+You used `mode: "managed"` without `proxyUrl`. Managed mode does not fall back to the environment. Supply a URL or switch to `mode: "ambient"`.
+
+## `ProxylineError: UNSUPPORTED_PROXY_PROTOCOL`
+
+`proxyUrl` is not `http://` or `https://`. SOCKS and other transports are not supported.
+
+## `ProxylineError: RUNTIME_ALREADY_ACTIVE`
+
+Two parts of your code called `installProxyline` without an intervening `stop()` or compatible `ifActive` policy. Find the existing handle and reuse it, pass `ifActive: "reuse-compatible"` when the settings should match, or call `stop()` before the second install. Common causes: test setup that re-installs on every test, double-invoked entry points, hot-reload tooling that re-evaluates the entry module.
+
+## `ProxylineError: CONNECT_FAILED`
+
+Returned by `openProxyConnectTunnel`. Inspect the message for the immediate cause:
+
+- `proxy CONNECT timed out after Nms` — bump `timeoutMs` or check connectivity to the proxy.
+- A status line such as `HTTP/1.1 407 Proxy Authentication Required` — include credentials in `proxyUrl`.
+- A status line such as `HTTP/1.1 403 Forbidden` — the proxy refused the destination.
+- `proxy socket closed before CONNECT response` — the proxy disconnected. Often a TLS mismatch; verify `proxyTls.ca`.
+- `proxy CONNECT response headers exceeded 16384 bytes` — defensive cap. Unexpected from a normal proxy.
+
+## fetch / undici still goes direct
+
+- In ambient mode, a library may be using its own `Dispatcher` and passing it to `fetch` explicitly. Inspect the `dispatcher` option; it overrides the global one outside managed `globalThis.fetch`. Use `proxy.createUndiciDispatcher()` if you need a Proxyline-aware dispatcher.
+- The library was loaded **before** `installProxyline`. Some libraries cache a dispatcher at import time. Install Proxyline first.
+
+## Caller agent is being ignored
+
+That is the intended managed-mode behavior — caller agents are replaced per request. TLS-relevant options (`ca`, `key`, `cert`, `rejectUnauthorized`, `minVersion`, `maxVersion`, `ciphers`, …) are lifted off the caller's agent so destination TLS still validates. If your option is missing, see [Surfaces — TLS identity preservation](./surfaces.md#tls-identity-preservation) for the full list of preserved keys.
+
+## "ECONNREFUSED" against the proxy
+
+Verify the proxy is reachable from this process:
+
+```bash
+curl -v -x "$HTTPS_PROXY" https://api.example.com
+```
+
+If `curl` succeeds but Node fails, the most common causes are:
+
+- Wrong scheme (`HTTPS_PROXY=proxy.corp:8080` defaults to `http://proxy.corp:8080`).
+- A private CA presented by the proxy that Node does not trust. Use `proxyTls`.
+- Code captured `http.request` before Proxyline installed. Install Proxyline first.
+
+## TLS errors against the proxy
+
+The proxy presents a certificate Node does not trust. Pass `proxyTls.caFile` (or `proxyTls.ca`) — see [Proxy TLS](./proxy-tls.md). Do not disable TLS verification process-wide.
+
+## TLS errors against the destination
+
+Proxyline does not modify destination TLS. Use the same `ca` / `cert` / `key` options you would use without a proxy. When passed via an `https.Agent`, Proxyline copies them onto the request automatically.
+
+## Tests interfere with each other
+
+Each test should call `proxy.stop()` in its teardown. Without that, the next install throws `RUNTIME_ALREADY_ACTIVE` and the rest of the suite fails. The patches and the undici dispatcher are global, so leaks affect every concurrent test as well.
+
+## Ambient mode reports `active: false`
+
+No supported proxy variables are set. Check `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` (and their lowercase forms), and make sure their values use `http://` or `https://`. `NO_PROXY` alone is not enough to activate the runtime. See [Environment Variables](./environment-variables.md).
+
+## `NO_PROXY` is not matching as expected
+
+- Suffix matches need a leading `.` or `*`. `corp.example` matches only the exact host; `.corp.example` matches `api.corp.example`.
+- A port suffix (`internal.corp:8443`) restricts the match to that port.
+- IPv6 hosts may be bracketed or bare (`[::1]`, `::1`).
+- Hostnames are lowercased and trailing dots are stripped before comparison.
+
+When in doubt, use `proxy.explain(url)` — `reason: "no-proxy-match"` confirms the URL was exempted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/proxyline",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Process-global proxy routing for Node.js.",
   "type": "module",
   "license": "MIT",
@@ -32,13 +32,19 @@
     "dist/*.js",
     "dist/*.d.ts",
     "dist/*.d.ts.map",
+    "src/**/*.ts",
+    "docs/*.md",
+    "docs/CNAME",
+    "scripts/prepack-build.mjs",
+    "tsconfig.json",
+    "tsconfig.build.json",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "check": "pnpm build && tsc --noEmit && pnpm coverage:run",
+    "check": "pnpm build && tsc --noEmit && pnpm coverage:run && tsx --test test/package-artifact.test.ts",
     "coverage": "pnpm build && pnpm coverage:run",
     "coverage:run": "node scripts/run-coverage.mjs",
     "docs:build": "node scripts/build-docs-site.mjs",
@@ -46,7 +52,7 @@
     "prepack": "node scripts/prepack-build.mjs",
     "prepare": "node scripts/prepack-build.mjs",
     "publish:dry-run": "pnpm publish --dry-run --access public",
-    "test": "pnpm build && tsx --test test/index.test.ts test/e2e.test.ts test/package.test.ts",
+    "test": "pnpm build && tsx --test test/index.test.ts test/e2e.test.ts test/package.test.ts test/scripts.test.ts && tsx --test test/package-artifact.test.ts",
     "typecheck": "pnpm build && tsc --noEmit"
   },
   "devDependencies": {

package/scripts/prepack-build.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+function resolveTypeScriptCompiler() {
+  try {
+    return require.resolve("typescript/bin/tsc");
+  } catch {
+    return undefined;
+  }
+}
+
+function run(command, args, env = {}) {
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    env: { ...process.env, ...env },
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const tscBin = resolveTypeScriptCompiler();
+
+if (!tscBin) {
+  console.error("TypeScript compiler is unavailable. Run `pnpm install --frozen-lockfile` before packing.");
+  process.exit(1);
+}
+
+run(process.execPath, [tscBin, "-p", "tsconfig.build.json"]);

package/src/connect.ts

@@ -0,0 +1,222 @@
+import net from "node:net";
+import tls from "node:tls";
+import { ProxylineError, type ProxylineTlsOptions, redactProxyUrl, resolveProxyTlsCa } from "./shared.js";
+
+export type OpenProxyConnectTunnelOptions = Readonly<{
+  proxyUrl: string | URL;
+  proxyTls?: ProxylineTlsOptions;
+  targetHost: string;
+  targetPort: number;
+  timeoutMs?: number;
+}>;
+
+const MAX_CONNECT_RESPONSE_HEADER_BYTES = 16 * 1024;
+const INVALID_CONNECT_AUTHORITY_PATTERN = /[\u0000-\u0020\u007f]/;
+const INVALID_CONNECT_HOST_DELIMITER_PATTERN = /[/:?#@\\]/;
+
+type ProxySocket = net.Socket | tls.TLSSocket;
+
+function resolveProxyHost(proxy: URL): string {
+  return (proxy.hostname || proxy.host).replace(/^\[|\]$/g, "");
+}
+
+function resolveProxyPort(proxy: URL): number {
+  if (proxy.port) {
+    return Number(proxy.port);
+  }
+  return proxy.protocol === "https:" ? 443 : 80;
+}
+
+function resolveProxyAuthorization(proxy: URL): string | undefined {
+  if (!proxy.username && !proxy.password) {
+    return undefined;
+  }
+  const username = decodeURIComponent(proxy.username);
+  const password = decodeURIComponent(proxy.password);
+  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+}
+
+export function formatConnectAuthority(targetHost: string, targetPort: number): string {
+  if (!Number.isInteger(targetPort) || targetPort < 1 || targetPort > 65_535) {
+    throw new ProxylineError("INVALID_CONNECT_TARGET", `Invalid CONNECT target port: ${targetPort}`);
+  }
+  if (!targetHost || INVALID_CONNECT_AUTHORITY_PATTERN.test(targetHost)) {
+    throw new ProxylineError("INVALID_CONNECT_TARGET", "CONNECT target host is empty or unsafe.");
+  }
+  const unbracketedHost =
+    targetHost.startsWith("[") && targetHost.endsWith("]")
+      ? targetHost.slice(1, -1)
+      : targetHost;
+  if (net.isIP(unbracketedHost) === 6) {
+    return `[${unbracketedHost}]:${targetPort}`;
+  }
+  if (targetHost.includes("[") || targetHost.includes("]")) {
+    throw new ProxylineError("INVALID_CONNECT_TARGET", "CONNECT target host has invalid brackets.");
+  }
+  if (targetHost.includes(":") || INVALID_CONNECT_HOST_DELIMITER_PATTERN.test(targetHost)) {
+    throw new ProxylineError("INVALID_CONNECT_TARGET", "CONNECT target host is not a host name.");
+  }
+  return `${targetHost}:${targetPort}`;
+}
+
+function connectToProxy(proxy: URL, proxyTls: ProxylineTlsOptions | undefined): ProxySocket {
+  const host = resolveProxyHost(proxy);
+  const connectOptions = {
+    host,
+    port: resolveProxyPort(proxy),
+  };
+  if (proxy.protocol === "https:") {
+    const ca = resolveProxyTlsCa(proxyTls);
+    const servername = net.isIP(host) === 0 ? host : undefined;
+    return tls.connect({
+      ...connectOptions,
+      ALPNProtocols: ["http/1.1"],
+      ...(servername !== undefined ? { servername } : {}),
+      ...(ca !== undefined ? { ca } : {}),
+    });
+  }
+  if (proxy.protocol === "http:") {
+    return net.connect(connectOptions);
+  }
+  throw new ProxylineError(
+    "UNSUPPORTED_PROXY_PROTOCOL",
+    `CONNECT tunnels support http:// and https:// proxy endpoints: ${proxy.protocol}`,
+  );
+}
+
+function assertSupportedConnectProxyProtocol(proxy: URL): void {
+  if (proxy.protocol !== "http:" && proxy.protocol !== "https:") {
+    throw new ProxylineError(
+      "UNSUPPORTED_PROXY_PROTOCOL",
+      `CONNECT tunnels support http:// and https:// proxy endpoints: ${proxy.protocol}`,
+    );
+  }
+}
+
+function writeConnectRequest(socket: net.Socket, proxy: URL, target: string): void {
+  const headers = [`CONNECT ${target} HTTP/1.1`, `Host: ${target}`, "Proxy-Connection: Keep-Alive"];
+  const authorization = resolveProxyAuthorization(proxy);
+  if (authorization !== undefined) {
+    headers.push(`Proxy-Authorization: ${authorization}`);
+  }
+  socket.write([...headers, "", ""].join("\r\n"));
+}
+
+function failConnect(proxy: URL, error: unknown): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  return new ProxylineError("CONNECT_FAILED", `Proxy CONNECT failed via ${redactProxyUrl(proxy)}: ${message}`);
+}
+
+export async function openProxyConnectTunnel(
+  options: OpenProxyConnectTunnelOptions,
+): Promise<ProxySocket> {
+  const proxy = options.proxyUrl instanceof URL ? new URL(options.proxyUrl.href) : new URL(options.proxyUrl);
+  assertSupportedConnectProxyProtocol(proxy);
+  const target = formatConnectAuthority(options.targetHost, options.targetPort);
+
+  return await new Promise<ProxySocket>((resolve, reject) => {
+    let settled = false;
+    let responseBuffer = Buffer.alloc(0);
+    let timeout: NodeJS.Timeout | undefined;
+    let socket: ProxySocket | undefined;
+
+    const cleanup = (): void => {
+      if (timeout !== undefined) {
+        clearTimeout(timeout);
+        timeout = undefined;
+      }
+      socket?.off("data", onData);
+      socket?.off("error", onError);
+      socket?.off("end", onClosed);
+      socket?.off("close", onClosed);
+      socket?.off("connect", onConnected);
+      socket?.off("secureConnect", onConnected);
+    };
+
+    const fail = (error: unknown): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      socket?.destroy();
+      reject(failConnect(proxy, error));
+    };
+
+    const succeed = (connectedSocket: ProxySocket, tunneledBytes: Buffer | undefined): void => {
+      if (settled) {
+        connectedSocket.destroy();
+        return;
+      }
+      settled = true;
+      cleanup();
+      if (tunneledBytes !== undefined && tunneledBytes.length > 0) {
+        connectedSocket.unshift(tunneledBytes);
+      }
+      resolve(connectedSocket);
+    };
+
+    const onConnected = (): void => {
+      if (socket === undefined) {
+        fail(new Error("proxy socket missing after connect"));
+        return;
+      }
+      writeConnectRequest(socket, proxy, target);
+    };
+
+    const onData = (chunk: Buffer): void => {
+      responseBuffer = Buffer.concat([responseBuffer, chunk]);
+      const headerEnd = responseBuffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) {
+        if (responseBuffer.length > MAX_CONNECT_RESPONSE_HEADER_BYTES) {
+          fail(new Error(`proxy CONNECT response headers exceeded ${MAX_CONNECT_RESPONSE_HEADER_BYTES} bytes`));
+        }
+        return;
+      }
+
+      const bodyOffset = headerEnd + 4;
+      if (bodyOffset > MAX_CONNECT_RESPONSE_HEADER_BYTES) {
+        fail(new Error(`proxy CONNECT response headers exceeded ${MAX_CONNECT_RESPONSE_HEADER_BYTES} bytes`));
+        return;
+      }
+      const responseHeader = responseBuffer.subarray(0, bodyOffset).toString("latin1");
+      const statusLine = responseHeader.split("\r\n", 1)[0] ?? "";
+      if (!/^HTTP\/1\.[01] 2\d\d\b/.test(statusLine)) {
+        fail(new Error(statusLine || "proxy returned an invalid CONNECT response"));
+        return;
+      }
+
+      if (socket === undefined) {
+        fail(new Error("proxy socket missing after CONNECT response"));
+        return;
+      }
+      const tunneledBytes =
+        responseBuffer.length > bodyOffset ? responseBuffer.subarray(bodyOffset) : undefined;
+      succeed(socket, tunneledBytes);
+    };
+
+    const onError = (error: Error): void => {
+      fail(error);
+    };
+
+    const onClosed = (): void => {
+      fail(new Error("proxy socket closed before CONNECT response"));
+    };
+
+    try {
+      if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+        timeout = setTimeout(() => {
+          fail(new Error(`proxy CONNECT timed out after ${Math.trunc(options.timeoutMs ?? 0)}ms`));
+        }, Math.trunc(options.timeoutMs));
+      }
+      socket = connectToProxy(proxy, options.proxyTls);
+      socket.once(proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
+      socket.on("data", onData);
+      socket.once("error", onError);
+      socket.once("end", onClosed);
+      socket.once("close", onClosed);
+    } catch (error) {
+      fail(error);
+    }
+  });
+}

package/src/dispatcher-brand.ts

@@ -0,0 +1,13 @@
+import type { Dispatcher } from "undici";
+
+export const PROXYLINE_DISPATCHER_BRAND = Symbol.for("@openclaw/proxyline.dispatcher");
+
+type ProxylineDispatcher = Dispatcher & {
+  [PROXYLINE_DISPATCHER_BRAND]?: true;
+};
+
+export function isProxylineDispatcher(dispatcher: unknown): boolean {
+  return typeof dispatcher === "object" &&
+    dispatcher !== null &&
+    (dispatcher as ProxylineDispatcher)[PROXYLINE_DISPATCHER_BRAND] === true;
+}

package/src/env.ts

@@ -0,0 +1,250 @@
+import { formatUrl, redactProxyUrl } from "./shared.js";
+import type { ProxyResolver } from "./types.js";
+
+export type ProxyEnvKey =
+  | "HTTP_PROXY"
+  | "HTTPS_PROXY"
+  | "ALL_PROXY"
+  | "NO_PROXY"
+  | "http_proxy"
+  | "https_proxy"
+  | "all_proxy"
+  | "no_proxy";
+
+type LowerProxyEnvKey = "http_proxy" | "https_proxy" | "all_proxy" | "no_proxy";
+
+export type ProxyEnvSnapshot = Readonly<Record<ProxyEnvKey, string | undefined>>;
+
+export const EMPTY_PROXY_ENV: ProxyEnvSnapshot = {
+  HTTP_PROXY: undefined,
+  HTTPS_PROXY: undefined,
+  ALL_PROXY: undefined,
+  NO_PROXY: undefined,
+  http_proxy: undefined,
+  https_proxy: undefined,
+  all_proxy: undefined,
+  no_proxy: undefined,
+};
+
+export function readProxyEnv(): ProxyEnvSnapshot {
+  return {
+    HTTP_PROXY: process.env.HTTP_PROXY,
+    HTTPS_PROXY: process.env.HTTPS_PROXY,
+    ALL_PROXY: process.env.ALL_PROXY,
+    NO_PROXY: process.env.NO_PROXY,
+    http_proxy: process.env.http_proxy,
+    https_proxy: process.env.https_proxy,
+    all_proxy: process.env.all_proxy,
+    no_proxy: process.env.no_proxy,
+  };
+}
+
+function normalizeEnvValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function upperProxyEnvKey(key: LowerProxyEnvKey): ProxyEnvKey {
+  switch (key) {
+    case "http_proxy":
+      return "HTTP_PROXY";
+    case "https_proxy":
+      return "HTTPS_PROXY";
+    case "all_proxy":
+      return "ALL_PROXY";
+    case "no_proxy":
+      return "NO_PROXY";
+  }
+}
+
+export function readProxyEnvValue(
+  env: ProxyEnvSnapshot,
+  key: LowerProxyEnvKey,
+): string | undefined {
+  return normalizeEnvValue(env[key]) ?? normalizeEnvValue(env[upperProxyEnvKey(key)]);
+}
+
+export function proxyUrlWithDefaultScheme(proxyUrl: string): string {
+  return proxyUrl.includes("://") ? proxyUrl : `http://${proxyUrl}`;
+}
+
+function normalizeAmbientProxyUrl(proxyUrl: string | undefined): string | undefined {
+  if (proxyUrl === undefined) {
+    return undefined;
+  }
+  try {
+    const url = new URL(proxyUrlWithDefaultScheme(proxyUrl));
+    return url.protocol === "http:" || url.protocol === "https:" ? url.href : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function defaultPort(protocol: string): number {
+  if (protocol === "http:" || protocol === "ws:") {
+    return 80;
+  }
+  if (protocol === "https:" || protocol === "wss:") {
+    return 443;
+  }
+  return 0;
+}
+
+function matchesNoProxy(url: URL, env: ProxyEnvSnapshot): boolean {
+  const rawNoProxy = readProxyEnvValue(env, "no_proxy")?.toLowerCase();
+  if (!rawNoProxy) {
+    return false;
+  }
+  if (rawNoProxy === "*") {
+    return true;
+  }
+
+  const hostname = normalizeNoProxyHost(url.hostname);
+  const port = Number.parseInt(url.port, 10) || defaultPort(url.protocol);
+  for (const rawEntry of rawNoProxy.split(/[,\s]/)) {
+    if (!rawEntry) {
+      continue;
+    }
+    const { host: parsedHost, port: entryPort } = parseNoProxyEntry(rawEntry);
+    let entryHost = normalizeNoProxyHost(parsedHost);
+    if (entryPort && entryPort !== port) {
+      continue;
+    }
+
+    if (!/^[.*]/.test(entryHost)) {
+      if (hostname === entryHost) {
+        return true;
+      }
+      continue;
+    }
+    if (entryHost.startsWith("*")) {
+      entryHost = entryHost.slice(1);
+    }
+    if (
+      entryHost.startsWith(".") &&
+      (hostname === entryHost.slice(1) || hostname.endsWith(entryHost))
+    ) {
+      return true;
+    }
+    if (!entryHost.startsWith(".") && hostname.endsWith(entryHost)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function normalizeNoProxyHost(hostname: string): string {
+  const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return normalized.startsWith("[") && normalized.endsWith("]")
+    ? normalized.slice(1, -1)
+    : normalized;
+}
+
+function parseNoProxyEntry(entry: string): { host: string; port: number } {
+  const bracketedIpv6 = entry.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (bracketedIpv6) {
+    return {
+      host: bracketedIpv6[1] ?? "",
+      port: bracketedIpv6[2] ? Number.parseInt(bracketedIpv6[2], 10) : 0,
+    };
+  }
+
+  const lastColon = entry.lastIndexOf(":");
+  const hasSingleColon = lastColon !== -1 && entry.indexOf(":") === lastColon;
+  if (hasSingleColon) {
+    const possiblePort = entry.slice(lastColon + 1);
+    if (/^\d+$/.test(possiblePort)) {
+      return {
+        host: entry.slice(0, lastColon),
+        port: Number.parseInt(possiblePort, 10),
+      };
+    }
+  }
+
+  return { host: entry, port: 0 };
+}
+
+function proxyEnvKeyForProtocol(protocol: string): LowerProxyEnvKey | undefined {
+  if (protocol === "http:" || protocol === "ws:") {
+    return "http_proxy";
+  }
+  if (protocol === "https:" || protocol === "wss:") {
+    return "https_proxy";
+  }
+  return undefined;
+}
+
+function supportsProxyForUrlProtocol(protocol: string): boolean {
+  return protocol === "http:" || protocol === "https:" || protocol === "ws:" || protocol === "wss:";
+}
+
+function resolveAmbientProxyEnvValue(
+  env: ProxyEnvSnapshot,
+  key: LowerProxyEnvKey,
+): string | undefined {
+  return normalizeAmbientProxyUrl(readProxyEnvValue(env, key));
+}
+
+export function resolveAmbientProxyForUrl(
+  url: string | URL,
+  env: ProxyEnvSnapshot,
+): string | undefined {
+  let parsedUrl: URL;
+  try {
+    parsedUrl = url instanceof URL ? new URL(url.href) : new URL(url);
+  } catch {
+    return undefined;
+  }
+  const protocol = parsedUrl.protocol;
+  if (!supportsProxyForUrlProtocol(protocol)) {
+    return undefined;
+  }
+  if (matchesNoProxy(parsedUrl, env)) {
+    return undefined;
+  }
+  const protocolProxyKey = proxyEnvKeyForProtocol(protocol);
+  if (protocolProxyKey === undefined) {
+    return undefined;
+  }
+  return (
+    resolveAmbientProxyEnvValue(env, protocolProxyKey) ??
+    resolveAmbientProxyEnvValue(env, "all_proxy")
+  );
+}
+
+export function createAmbientProxyResolver(env: ProxyEnvSnapshot): ProxyResolver {
+  const configuredProxy =
+    resolveAmbientProxyEnvValue(env, "http_proxy") ??
+    resolveAmbientProxyEnvValue(env, "https_proxy") ??
+    resolveAmbientProxyEnvValue(env, "all_proxy");
+  return {
+    active: configuredProxy !== undefined,
+    describeProxy: () =>
+      configuredProxy
+        ? redactProxyUrl(proxyUrlWithDefaultScheme(configuredProxy))
+        : undefined,
+    explain: (url, surface) => {
+      const formattedUrl = formatUrl(url);
+      const parsedUrl = new URL(formattedUrl);
+      const proxyUrl = resolveAmbientProxyForUrl(formattedUrl, env);
+      if (proxyUrl !== undefined) {
+        return {
+          kind: "proxied",
+          reason: "ambient-proxy-active",
+          surface,
+          url: formattedUrl,
+          proxyUrl: redactProxyUrl(proxyUrl),
+        };
+      }
+      return {
+        kind: "direct",
+        reason: supportsProxyForUrlProtocol(parsedUrl.protocol) && matchesNoProxy(parsedUrl, env)
+          ? "no-proxy-match"
+          : "ambient-proxy-not-configured",
+        surface,
+        url: formattedUrl,
+      };
+    },
+    getProxyForUrl: (url) => resolveAmbientProxyForUrl(url, env) ?? "",
+  };
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { openProxyConnectTunnel, type OpenProxyConnectTunnelOptions } from "./connect.js";
+export {
+  createAmbientNodeProxyAgent,
+  hasAmbientNodeProxyConfigured,
+  type AmbientNodeProxyAgentOptions,
+} from "./node-http.js";
+export { installGlobalProxy, installProxyline } from "./runtime.js";
+export { isProxylineDispatcher, PROXYLINE_DISPATCHER_BRAND } from "./dispatcher-brand.js";
+export {
+  ProxylineError,
+  redactProxyUrl,
+  resolveProxyTlsCa,
+  type ProxylineTlsOptions,
+} from "./shared.js";
+export type {
+  ExplainOptions,
+  ProxylineBypassRegistration,
+  ProxylineBypassPolicy,
+  ProxylineBypassRequest,
+  ProxylineDecision,
+  ProxylineEvent,
+  ProxylineHandle,
+  ProxylineMode,
+  ProxylineOptions,
+  ProxylineSurface,
+  ProxylineUndiciOptions,
+} from "./types.js";