@qilin-agent/http-proxy 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,55 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/http-proxy/README.md
+/:
+  en: 117b4d191f773a9c
+  zh: 0b9e150f6cd23b04
+/qilin-http-proxy:
+  en: e3d33d2aa4e5270e
+  zh: 3502335e912012e5
+/qilin-http-proxy/summary:
+  en: c3b1b32ab36f5f97
+  zh: 143b744ab361f0d4
+/qilin-http-proxy/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-http-proxy/use-this-package:
+  en: 559207e93d89f1a9
+  zh: 8f6975b4c42589b4
+/qilin-http-proxy/use-this-package/writing-a-new-outbound-call:
+  en: 782b24f91ee8ce71
+  zh: af4b75a0d5a98fdc
+/qilin-http-proxy/use-this-package/what-the-policy-reads:
+  en: 5ebd23809d3f0ded
+  zh: 4913ca6a8935e2ac
+/qilin-http-proxy/use-this-package/failures:
+  en: 4248bc9a662680ed
+  zh: 4150ade9f1aa9287
+/qilin-http-proxy/understand-the-implementation:
+  en: ee4615a04fa6503d
+  zh: ee2c5fb2204a43cf
+/qilin-http-proxy/understand-the-implementation/design-philosophy:
+  en: 4c5ed05a5cd07bc3
+  zh: a6aee9a484e92a79
+/qilin-http-proxy/understand-the-implementation/source-map:
+  en: a099f88dd0c7d394
+  zh: 7325b7ea973bce13
+/qilin-http-proxy/understand-the-implementation/bypass-matching:
+  en: e9ad6c2e8ee2fc21
+  zh: c10de6995cf594bc
+/qilin-http-proxy/further-exploration:
+  en: 3712e481f8cbeb24
+  zh: 390dd890d3d66e70
+/qilin-http-proxy/model-experience:
+  en: e0af6a1073934d5a
+  zh: d8bf9c77b54ed5ae
+/qilin-http-proxy/model-experience/kv-cache-effect:
+  en: 7f12ca92e7722f98
+  zh: 97fa75de6a3f6a3f
+/qilin-http-proxy/known-limitations-and-deferred-work:
+  en: 4367d85a8e5e0101
+  zh: 68a5c63e23aed832
+/qilin-http-proxy/known-limitations-and-deferred-work/dev-note:
+  en: 8f915ac6f4fc1525
+  zh: 29b06e0aae5a30ec

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+---
+description: "Outbound HTTP proxy support for the harness: how one policy resolved from the launch environment reaches every request Node's fetch would otherwise send direct."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/http-proxy
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this package to apply one outbound HTTP proxy policy to Harness requests that use Node's built-in `fetch`, including LLM, web-search, and HTTP MCP traffic. The launcher reads standard proxy environment variables once, and ordinary `fetch` callers require no extra imports or changes. Local loopback traffic stays direct, while unsupported proxy URLs are reported and skipped for the affected scheme. Public helpers let callers route transports with their own proxy settings, prepare child-process environments, or clear proxy variables for isolated replays.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Nothing to mount, and nothing to configure. The `qilin` launcher resolves and installs the policy for every profile before the first plugin loads, so a user who exports `HTTPS_PROXY` is proxied everywhere. This is a library rather than a plugin because transport policy has one answer per process: there is no second implementation to swap and no scope narrower than the process to give one.
+
+### Writing a new outbound call
+
+Plain `fetch()` is proxied, and so is any SDK that reaches `globalThis.fetch` — the MCP HTTP transport and the pi-ai provider stack both do. Verify each SDK's actual transport; exceptions belong under [Known Limitations and Deferred Work](#known-limitations-and-deferred-work).
+
+| You are writing | Use |
+|---|---|
+| A plain request, or an SDK that reaches `globalThis.fetch` | nothing — the global dispatcher already routes it |
+| A call that must branch on whether this request is proxied | `proxyRouteFor(url)` |
+| An SDK that takes a proxy URL of its own | `proxyRouteFor(url)`, and pass `route.proxy` |
+| A spawn whose environment you build yourself | apply `proxyEnvironmentForChild()` to it (`undefined` means remove) |
+| A harness that must reach its own fixture server | apply `clearedProxyEnv()` to the spawn |
+
+`proxyRouteFor` answers with the transport that answer assumed, not just the answer: its proxied arm carries the dispatcher already routing by this policy. A caller that read the policy and then built its own transport could have an unmount land between the two and send the request somewhere its branch never cleared.
+
+Constructing `new Agent(...)` and passing it as `dispatcher` overrides the global one and silently bypasses the proxy. `verify-no-bare-dispatcher` rejects that outside this package. One call site legitimately owns its transport — `web-fetch-http` pins a request to addresses it validated, which is per-request state a process-wide dispatcher cannot hold — and says so with a `proxy-exempt:` comment on the line.
+
+That gate cannot see inside an SDK, so each outbound call site carries an `egress.spec.ts` that drives its actual transport through a fake proxy and checks the observed route. Every new outbound call site must include that transport test. Telemetry asserts its direct-route exception. These tests detect dependency changes that alter routing without changing the call site.
+
+### What the policy reads
+
+`http_proxy`, `https_proxy`, `no_proxy`, and `all_proxy`, lowercase first and uppercase as the fallback, with a blank value treated as unset. `ALL_PROXY` backs both schemes, and HTTPS falls back to the HTTP proxy last — neither Node nor undici derives the first of these on its own. Values come from the launcher's snapshot: an exported variable first, then `$QILIN_HOME/.env`. A project's own `.env` cannot carry these names — that file arrives with a clone, and the launcher refuses to start rather than let a repository choose where the harness sends its traffic.
+
+Loopback is always bypassed — `localhost`, the whole `127.0.0.0/8` range, `::1`, `0.0.0.0`, and the IPv4-mapped spellings of those. The harness's own Web UI, Connection transport, and every local test server would otherwise route through the proxy and loop. The published bypass list names only the four literal entries an environment reader can match; `proxyForUrl` recognises the range itself, because a list entry cannot express one.
+
+### Failures
+
+A proxy value the package cannot use — a SOCKS or PAC URL, an unparseable string, an unsupported scheme — is reported and skipped, and that scheme connects directly. The variable may have been exported for other tools, so it must not stop the agent from starting.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+### Design philosophy
+
+**One resolution, one matcher.** `proxyForUrl()` and the installed dispatcher must never disagree about a URL, or `qilin-web-fetch-http` would pin a connection the dispatcher meant to tunnel. The dispatcher is therefore an `Agent` whose per-origin `factory` calls `proxyForUrl()` itself, so there is no second parser to drift from the first. undici's `EnvHttpProxyAgent` cannot serve here: with no `HTTPS_PROXY` present it reuses the HTTP proxy for `https:`, which would tunnel a scheme this package keeps direct after refusing the URL the user named for it.
+
+**A child inherits the user's own values, and the resolved policy for what they left unset.** A scheme the user named in either casing reaches a child exactly as they wrote it, so a SOCKS proxy `curl` uses is never replaced by an HTTP one named for another scheme. A scheme they named in neither casing carries the resolved value instead, because otherwise the child's routing diverges from its parent's: Node's `NODE_USE_ENV_PROXY` does not read `ALL_PROXY`. The bypass list is always the resolved one — it only ever adds the loopback entries, so nothing the user wrote is lost. The cost of one routing answer for parent and child alike is that `curl` also sees the `https:` proxy this package derives from the HTTP one. One exception protects the child itself: when a value it receives is one this package refused — a SOCKS URL kept for `curl` — the `NODE_USE_ENV_PROXY` flag is withheld, because Node parses `HTTP_PROXY` and `HTTPS_PROXY` under that flag before running the program and exits on such a value. A child Node then connects directly, as this process already reported for that scheme, instead of failing to start.
+
+### Source map
+
+| File | Holds |
+|---|---|
+| `src/policy.ts` | Resolution and bypass matching; a diagnostic names the variable, never its value. Imports no transport, so it stays loadable where undici is absent. |
+| `src/install.ts` | The global dispatcher, the active-policy record, the route, and the child environment. Imports undici dynamically. |
+| `src/index.ts` | The package face: four functions and one type. |
+
+### Bypass matching
+
+An entry names a host and matches it together with every subdomain under it: `NO_PROXY=example.com` also bypasses `api.example.com`. A leading `.` or `*.` is accepted and means the same thing. An entry may carry a `:port`, and `*` bypasses everything. A bracketed or bare IPv6 literal matches either way — a bare `::1` is *not* read as host `:` port `1`, which is how undici's own matcher fails and why the resolved list carries both `::1` and `[::1]`. CIDR is not matched: an operating system's bypass list often carries `10.0.0.0/8`, which has to be rewritten as suffixes.
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Network proxy guide](../../../docs/user/guide/network-proxy.md) — what to export, and why a browser is proxied when a terminal is not.
+- [`qilin-web-fetch-http`](../../web/web-fetch-http/README.md) — the one consumer whose safety rules change under a proxy.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as transport policy only: it changes how bytes reach the network and registers no prompt, schema, or result text.
+
+#### KV Cache effect
+
+No direct invalidation: the package contributes no request tokens and never mutates a request prefix, so provider cache reuse is unaffected.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the package is a poor fit. They are current package constraints.
+
+- **No SOCKS, PAC, or operating-system proxy detection** — only `http(s)://` proxy URLs from the environment. A macOS or Windows system-proxy setting is not read, so a user who only toggled it in a proxy application must still export the variables; a SOCKS URL is reported and that scheme stays direct rather than borrowing another scheme's proxy.
+- **No custom certificate authority** — a TLS-intercepting corporate proxy needs `NODE_EXTRA_CA_CERTS` set on the process before launch, which this package neither sets nor validates.
+- **A spawned child honors the policy only on a new enough runtime, and only when every value it inherits is one Node accepts** — it reads the published environment through Node's `NODE_USE_ENV_PROXY` (22.21+, 24+), and the engines range admits 22.19 and 22.20, where such a child stays direct. A user whose environment also names a SOCKS or otherwise refused proxy leaves every child Node direct: the flag is withheld so the child can start at all. A child also matches bypass entries with Node's own `NO_PROXY` rules, which differ from this package's in their separators and IPv4-range support. Nothing in this process depends on a Node version: every in-process request reaches the global dispatcher.
+- **Telemetry is direct by design** — the OTLP exporter posts through `node:http`, which no global dispatcher reaches. Routing it would need either an `http.Agent` whose `proxyEnv` option post-dates the lowest supported Node, or the SDK's `fetch` transport, which has no compression while the shipped profile enables gzip. Telemetry is the one channel whose loss costs the user nothing, so it stays where it was; `QILIN_TELEMETRY_MODE=DISABLED` turns it off.
+- **Model-authored programs receive no proxy settings** — the Node ptc-runtime process and workflow worker do not inherit a proxy URL that may contain `user:password`. Their direct requests need their own configuration and remain subject to the execution sandbox.
+- **The regression gate sees source, not dependencies** — `verify-no-bare-dispatcher` parses `packages/*/*/src` and `apps/*/src`; tests, scripts, and the internals of a third-party SDK are outside it. That is why every outbound call site also carries an `egress.spec.ts`.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+Reaching Node's built-in `fetch` from a userland undici relies on both writing the legacy `Symbol.for('undici.globalDispatcher.1')` slot. That is an implicit cross-version coupling, not a contract — see [corepack#834](https://github.com/nodejs/corepack/issues/834) for it breaking. `tests/install.spec.ts` asserts a real request reaches a loopback proxy, so a version bump that breaks the coupling fails there rather than in the field.
+
+</details>

package/README.zh.md

@@ -0,0 +1,122 @@
+---
+description: "Harness 的出站 HTTP 代理支持：从启动环境解析出的一份策略，如何覆盖到 Node fetch 本来会直连的每一个请求。"
+kind: "package-reference"
+---
+
+# @qilin-agent/http-proxy
+
+[English](README.md) | 中文
+
+## 概述
+
+使用本包可为采用 Node 内置 `fetch` 的 Harness 请求应用一份出站 HTTP 代理策略，包括 LLM（大语言模型）、web 搜索与 HTTP MCP 流量。启动器只读取一次标准代理环境变量，普通 `fetch` 调用方无需额外引入或改动。loopback 流量保持直连；不受支持的代理 URL 会被报告，并针对受影响的协议跳过。公共辅助函数可让调用方路由采用自有代理设置的传输、准备子进程环境，或为隔离回放清除代理变量。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+无需挂载，也无需配置。`qilin` 启动器会在第一个插件加载之前，为每个 profile 解析并安装策略，因此导出了 `HTTPS_PROXY` 的用户在所有位置都会走代理。本包是库而非插件，因为传输策略每个进程只有一个答案：没有第二个实现可替换，也没有比进程更窄的作用域可赋予。
+
+### 编写新的出站调用
+
+普通 `fetch()` 会走代理，任何使用 `globalThis.fetch` 的 SDK 也一样——MCP HTTP 传输与 pi-ai 提供方栈都使用它。应验证每个 SDK 的实际传输；例外见[已知限制与延后工作](#known-limitations-and-deferred-work)。
+
+| 你要写的东西 | 使用 |
+|---|---|
+| 普通请求，或最终落到 `globalThis.fetch` 的 SDK | 什么都不用——全局 dispatcher 已经在路由它 |
+| 需要按“这次请求是否走代理”分支的调用 | `proxyRouteFor(url)` |
+| 接受自有代理 URL 的 SDK | `proxyRouteFor(url)`，把 `route.proxy` 传进去 |
+| 由你自己构造环境的 spawn | 把 `proxyEnvironmentForChild()` 应用到该 spawn（`undefined` 表示删除） |
+| 必须连到自带 fixture（测试前置数据）服务器的 harness | 把 `clearedProxyEnv()` 应用到该 spawn |
+
+`proxyRouteFor` 给出的不只是答案，还有该答案所假定的传输：走代理的那一支携带着此刻正按该策略路由的 dispatcher。若调用方先读策略、再自建传输，卸载就可能落在两次读取之间，把请求发往其分支从未放行的去处。
+
+构造 `new Agent(...)` 再作为 `dispatcher` 传入会覆盖全局 dispatcher，从而静默绕开代理。`verify-no-bare-dispatcher` 会在本包之外拒绝该写法。有一处调用点确实自有传输——`web-fetch-http` 会把请求钉在它已校验过的地址上，而这是进程级 dispatcher 无法承载的单次请求状态——它在该行用 `proxy-exempt:` 注释说明。
+
+该门禁看不进 SDK 内部，因此每个出网点都配有 `egress.spec.ts`，通过假代理驱动实际传输并检查观察到的路由。每个新的出网点必须包含该传输测试。遥测断言其直连例外。这些测试可发现调用点不变但依赖变更改变路由的情况。
+
+### 策略读取哪些值
+
+`http_proxy`、`https_proxy`、`no_proxy` 与 `all_proxy`，小写优先、大写兜底，空值视为未设置。`ALL_PROXY` 为两种协议兜底，HTTPS 最后回退到 HTTP 代理——其中第一条 Node 与 undici 都不会自行推导。取值来自启动器的快照：先看导出的环境变量，再看 `$QILIN_HOME/.env`。项目自己的 `.env` 不能携带这些名字——那个文件随 clone 一起到来，启动器宁可拒绝启动，也不让一个仓库决定 Harness 把流量发往何处。
+
+loopback 始终被绕过——`localhost`、整个 `127.0.0.0/8` 段、`::1`、`0.0.0.0`，以及它们的 IPv4 映射写法。否则 Harness 自己的 Web UI、Connection 传输以及每一个本地测试服务器都会经由代理并形成回环。发布出去的绕过列表只包含读取环境的消费者能匹配的四个字面量条目；`proxyForUrl` 自行识别整个网段，因为列表条目无法表达一个范围。
+
+### 失败处理
+
+本包无法使用的代理值——SOCKS 或 PAC URL、无法解析的字符串、不受支持的协议——会被报告并跳过，该 scheme 转为直连。该变量可能是用户为其他工具导出的，不应因此阻止 agent（智能体）启动。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+### 设计理念
+
+**一次解析，一个匹配器。** `proxyForUrl()` 与已安装的 dispatcher 绝不能对同一个 URL 给出不同答案，否则 `qilin-web-fetch-http` 会把 dispatcher 本打算隧道转发的连接固定到某个地址上。因此该 dispatcher 是一个 `Agent`，其按 origin 调用的 `factory` 自身调用 `proxyForUrl()`，不存在可能与第一个解析器产生漂移的第二个解析器。undici 的 `EnvHttpProxyAgent` 在此无法胜任：没有 `HTTPS_PROXY` 时它让 `https:` 复用 HTTP 代理，于是本包在拒绝用户为该 scheme 指定的 URL 后本应保持直连的 scheme 仍会被隧道转发。
+
+**子进程继承用户自己的值，以及用户未设置部分的解析结果。** 用户以任一大小写指定过的 scheme，会以他们书写的形式原样传给子进程，因此用户为 `curl` 设置的 SOCKS 代理绝不会被替换成为其他 scheme 指定的 HTTP 代理。两种大小写都未指定的 scheme 则携带解析值，否则子进程的路由会与父进程分歧：Node 的 `NODE_USE_ENV_PROXY` 不读 `ALL_PROXY`。绕过列表始终采用解析结果——它只会追加 loopback 条目，用户写下的内容不会丢失。让父子进程只有一个路由答案的代价是：`curl` 也会看到本包由 HTTP 代理推导出的 `https:` 代理。有一处例外是为了保护子进程自身：当子进程收到的某个值是本包拒绝过的——比如为 `curl` 保留的 SOCKS URL——就不再设置 `NODE_USE_ENV_PROXY`，因为 Node 在该标志下会在运行程序之前先解析 `HTTP_PROXY` 与 `HTTPS_PROXY`，遇到这类值直接退出。此时子 Node 直连（本进程已为该协议如此报告），而不是根本起不来。
+
+### 源码地图
+
+| 文件 | 承载 |
+|---|---|
+| `src/policy.ts` | 解析与绕过匹配；诊断只点名变量，从不带出它的值。不引入任何传输实现，因此在没有 undici 的环境中仍可加载。 |
+| `src/install.ts` | 全局 dispatcher、生效策略记录、路由与子进程环境。动态引入 undici。 |
+| `src/index.ts` | 本包的对外接口：四个函数与一个类型。 |
+
+### 绕过匹配
+
+一个条目写的是主机名，它连同其下所有子域名一起匹配：`NO_PROXY=example.com` 也会放行 `api.example.com`。前缀 `.` 或 `*.` 可以写，含义相同。条目可带 `:port`，`*` 则放行全部。带方括号与裸写的 IPv6 字面量都能匹配——裸写的 `::1` **不会**被读成主机 `:` 端口 `1`，而 undici 自带的匹配器正是这样出错的，这也是解析结果中同时携带 `::1` 与 `[::1]` 的原因。CIDR 不参与匹配：操作系统的绕过列表常含 `10.0.0.0/8`，必须改写成后缀形式。
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [网络代理指南](../../../docs/user/guide/network-proxy.zh.md)——需要导出什么，以及为什么浏览器走代理而终端不走。
+- [`qilin-web-fetch-http`](../../web/web-fetch-http/README.zh.md)——唯一一个安全规则会因代理而改变的消费方。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。本包只承担传输策略：它改变字节如何抵达网络，不注册任何提示词、schema 或结果文本。
+
+#### KV Cache 影响
+
+不会直接失效：本包不贡献任何请求 token，也从不改变请求前缀，因此提供方缓存复用不受影响。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制界定了本包不适用的场景，属于当前的包级约束。
+
+- **不支持 SOCKS、PAC 或操作系统代理探测**——只接受来自环境的 `http(s)://` 代理 URL。不会读取 macOS 或 Windows 的系统代理设置，因此仅在代理软件里拨了开关的用户仍须导出环境变量；SOCKS URL 会被报告，且该协议保持直连，不会借用另一协议的代理。
+- **不支持自定义证书颁发机构**——做 TLS 拦截的企业代理需要在启动前为进程设置 `NODE_EXTRA_CA_CERTS`，本包既不设置也不校验它。
+- **spawn 出的子进程只在足够新的运行时上遵循策略，且仅当它继承的每个值都是 Node 接受的**——它通过 Node 的 `NODE_USE_ENV_PROXY` 读取已发布的环境（22.21+、24+），而 engines 范围允许 22.19 与 22.20，在这两个版本上这样的子进程保持直连。若用户环境里还有 SOCKS 或其他被拒的代理，所有子 Node 都保持直连：不设置该标志，子进程才起得来。子进程还会按 Node 自己的 `NO_PROXY` 规则匹配绕过条目，其分隔符与 IPv4 区间处理与本包不同。本进程内不依赖任何 Node 版本：每一次进程内请求都会落到全局 dispatcher。
+- **遥测按设计直连**——OTLP 导出器通过 `node:http` 投递，全局 dispatcher 触及不到。要让它走代理，要么依赖 `http.Agent` 的 `proxyEnv`，而该选项晚于本项目支持的最低 Node 版本；要么改用 SDK 的 `fetch` 传输，但它没有压缩能力，而随附配置启用了 gzip。遥测是唯一一条丢失后不会让用户付出任何代价的通道，因此维持原状；`QILIN_TELEMETRY_MODE=DISABLED` 可关闭它。
+- **模型编写的程序不接收代理配置**——Node ptc-runtime 进程与 workflow worker 不继承可能含有 `user:password` 的代理 URL。其直接请求需要自行配置，并继续受到执行沙箱的约束。
+- **防回归门禁只看源码，看不到依赖内部**——`verify-no-bare-dispatcher` 解析 `packages/*/*/src` 与 `apps/*/src`；测试、脚本以及第三方 SDK 的内部都在其之外。这正是每个出网点还各配一份 `egress.spec.ts` 的原因。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>面向维护者的工作上下文——点击展开</summary>
+
+userland undici 能触及 Node 内置的 `fetch`，依赖的是两者都会写入 legacy 的 `Symbol.for('undici.globalDispatcher.1')` 槽位。那是跨版本的隐式耦合，不是约定——参见 [corepack#834](https://github.com/nodejs/corepack/issues/834) 中它失效的实例。`tests/install.spec.ts` 断言真实请求会抵达一个 loopback 代理，因此破坏该耦合的版本升级会在那里失败，而不是流到线上。
+
+</details>

package/lib/index.js

@@ -0,0 +1,536 @@
+//#region lib/types/policy.js
+/**
+* Proxy policy resolution: the pure, transport-free half of this package. It turns the launch
+* environment into one {@link ProxyPolicy}, and answers which proxy
+* (if any) a given URL goes through.
+*
+* Nothing here imports `undici`, so the module stays loadable in the browser-worker runtime that
+* evaluates `qilin-web-fetch-http` without a Node transport.
+* @module @qilin-agent/http-proxy/policy
+*/
+/**
+* Loopback entries merged into every policy's `noProxy`. A proxy that also serves the harness's own
+* loopback traffic turns the Web UI, the Connection transport, and every local test server into a
+* routing loop, so the bypass is not optional.
+*
+* `::1` and `[::1]` are both listed because the resolved string is also handed to undici, whose
+* matcher reads a bare `::1` as host `:` port `1` and therefore never bypasses it.
+*/
+const LOOPBACK_NO_PROXY = [
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]"
+];
+/**
+* The environment names each policy field owns, lowercase first — undici reads the lowercase name
+* first, so both casings are always written or cleared together.
+*/
+const POLICY_ENV_NAMES = {
+	httpProxy: ["http_proxy", "HTTP_PROXY"],
+	httpsProxy: ["https_proxy", "HTTPS_PROXY"],
+	noProxy: ["no_proxy", "NO_PROXY"]
+};
+/**
+* Every environment name that carries proxy configuration, including the `ALL_PROXY` fallback this
+* package resolves but never writes back. A caller that must isolate a child from the machine's
+* network policy clears exactly these.
+*/
+const PROXY_ENV_NAMES = [
+	...Object.values(POLICY_ENV_NAMES).flat(),
+	"all_proxy",
+	"ALL_PROXY"
+];
+/** Proxy URL schemes this package routes through. Everything else is reported, never silently dropped. */
+const SUPPORTED_PROTOCOLS = new Set(["http:", "https:"]);
+/** Schemes recognised well enough to name in a diagnostic instead of calling them malformed. */
+const SOCKS_PROTOCOLS = new Set([
+	"socks:",
+	"socks4:",
+	"socks4a:",
+	"socks5:",
+	"socks5h:"
+]);
+/** A policy that proxies nothing. Callers that have not installed a policy resolve URLs against this. */
+const DIRECT_POLICY = {
+	noProxy: "",
+	source: "none"
+};
+/**
+* Read one environment name in undici's precedence order — lowercase first, uppercase as the
+* fallback — treating a blank value as unset. Blank matters: undici's own `??` chain lets an empty
+* lowercase name shadow a populated uppercase one.
+*
+* @param env - the launch environment snapshot to read.
+* @param lower - the lowercase variable name.
+* @returns the trimmed value and the name that supplied it, or `undefined` when neither is set.
+*/
+function readEnv(env, lower) {
+	for (const name of [lower, lower.toUpperCase()]) {
+		const value = env.get(name)?.value.trim();
+		if (value !== void 0 && value !== "") return {
+			value,
+			name
+		};
+	}
+}
+/** A slot nobody filled. */
+const ABSENT = { kind: "absent" };
+/**
+* Validate one candidate proxy URL.
+*
+* @param candidate - the raw value and the origin to name in a diagnostic.
+* @param diagnostics - collector the rejection is appended to.
+* @returns the candidate's usability, distinguishing a rejected slot from an empty one.
+*/
+function acceptProxyUrl(candidate, diagnostics) {
+	if (candidate === void 0) return ABSENT;
+	const parsed = URL.parse(candidate.value);
+	if (parsed === null) {
+		diagnostics.push({
+			kind: "invalid",
+			origin: candidate.name,
+			message: `${candidate.name} is not a valid URL; connecting directly`
+		});
+		return { kind: "rejected" };
+	}
+	if (SOCKS_PROTOCOLS.has(parsed.protocol)) {
+		diagnostics.push({
+			kind: "socks",
+			origin: candidate.name,
+			message: `${candidate.name} names a SOCKS proxy, which is not supported; connecting directly for that scheme — set an http:// or https:// proxy URL instead`
+		});
+		return { kind: "rejected" };
+	}
+	if (!SUPPORTED_PROTOCOLS.has(parsed.protocol)) {
+		diagnostics.push({
+			kind: "invalid",
+			origin: candidate.name,
+			message: `${candidate.name} uses the unsupported ${parsed.protocol}// scheme; connecting directly for that scheme — set an http:// or https:// proxy URL instead`
+		});
+		return { kind: "rejected" };
+	}
+	return {
+		kind: "accepted",
+		value: candidate.value
+	};
+}
+/**
+* Whether a proxy URL is one this package accepts: parseable, with an `http:` or `https:` scheme.
+* The same test {@link acceptProxyUrl} applies, without its diagnostics.
+*
+* @param value - the proxy URL as an environment variable holds it.
+* @returns true when the URL would be accepted.
+*/
+function isSupportedProxyUrl(value) {
+	const parsed = URL.parse(value);
+	return parsed !== null && SUPPORTED_PROTOCOLS.has(parsed.protocol);
+}
+/**
+* Resolve one scheme's proxy from its own slot, then the fallbacks — but only when the scheme's own
+* slot was empty. A rejected slot keeps that scheme direct, so the diagnostic and the route agree.
+*
+* @param own - what the scheme's own name supplied.
+* @param fallbacks - values to try in order when `own` is absent.
+* @returns the proxy URL for that scheme, or `undefined` for a direct connection.
+*/
+function resolveScheme(own, ...fallbacks) {
+	if (own.kind === "accepted") return own.value;
+	if (own.kind === "rejected") return void 0;
+	return fallbacks.find((value) => value !== void 0);
+}
+/**
+* Merge {@link LOOPBACK_NO_PROXY} into a bypass list, preserving the caller's entries and order.
+* A list of `*` already bypasses everything and is returned unchanged.
+*
+* @param noProxy - the bypass list as the environment supplied it.
+* @returns the effective bypass list.
+*/
+function withLoopback(noProxy) {
+	const entries = (noProxy ?? "").split(/[,\s]+/).map((entry) => entry.trim()).filter((entry) => entry !== "");
+	if (entries.includes("*")) return "*";
+	const present = new Set(entries.map((entry) => entry.toLowerCase()));
+	return [...entries, ...LOOPBACK_NO_PROXY.filter((entry) => !present.has(entry))].join(",");
+}
+/**
+* Split one bypass entry into host and optional port.
+*
+* A bare IPv6 literal carries several colons and no port, so only a single-colon entry splits;
+* a bracketed literal takes its port from after the bracket. Getting this wrong is how undici
+* turns `::1` into host `:` port `1`.
+*
+* @param entry - one already-trimmed bypass entry.
+* @returns the entry's host and, when it carries one, its port.
+*/
+function splitHostPort(entry) {
+	if (entry.startsWith("[")) {
+		const close = entry.indexOf("]");
+		if (close !== -1) {
+			const rest = entry.slice(close + 1);
+			const host = entry.slice(1, close);
+			return rest.startsWith(":") ? {
+				host,
+				port: rest.slice(1)
+			} : { host };
+		}
+	}
+	const colon = entry.indexOf(":");
+	if (colon !== -1 && entry.indexOf(":", colon + 1) === -1) return {
+		host: entry.slice(0, colon),
+		port: entry.slice(colon + 1)
+	};
+	return { host: entry };
+}
+/** One IPv4 octet, so a loopback match cannot accept `127.999.1.1`. */
+const OCTET = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
+/** The whole `127.0.0.0/8` block, not just its first address. */
+const LOOPBACK_IPV4 = new RegExp(`^127\\.${OCTET}\\.${OCTET}\\.${OCTET}$`);
+/**
+* Whether a host names this machine.
+*
+* A proxy cannot meaningfully reach one: it would resolve the address in its own network, and a
+* proxy running on this machine would reach a service that only listens on loopback. The bypass
+* list carries {@link LOOPBACK_NO_PROXY} for the consumers that read an environment rather than a
+* policy, but those are four literal entries — matching them alone leaves `127.0.0.2`, the whole
+* rest of `127.0.0.0/8`, and the IPv4-mapped spelling routed through the proxy.
+*
+* @param hostname - a URL's hostname, bracketed or not.
+* @returns true when the host is loopback or the unspecified address.
+*/
+function isLoopbackHost(hostname) {
+	const host = hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	if (host === "::1" || host === "::" || host === "0.0.0.0") return true;
+	const mappedHigh = /^::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}$/.exec(host)?.[1];
+	if (mappedHigh !== void 0) return Number.parseInt(mappedHigh, 16) >>> 8 === 127;
+	return LOOPBACK_IPV4.test(host.startsWith("::ffff:") ? host.slice(7) : host);
+}
+/**
+* Decide whether a bypass list exempts one URL. An entry names a host and matches it together with
+* every subdomain under it — `example.com` also bypasses `api.example.com` — and a leading `.` or
+* `*.` is accepted as the same thing; an entry may carry a `:port`, and `*` bypasses everything.
+* CIDR notation is not matched —
+* an operating system's bypass list often carries `10.0.0.0/8`, which must be rewritten as suffixes.
+*
+* @param noProxy - the effective bypass list.
+* @param url - the request URL.
+* @returns true when the URL must bypass the proxy.
+*/
+function bypassesProxy(noProxy, url) {
+	const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+	const port = url.port !== "" ? url.port : url.protocol === "https:" ? "443" : "80";
+	for (const raw of noProxy.split(/[,\s]+/)) {
+		const entry = raw.trim().toLowerCase();
+		if (entry === "") continue;
+		if (entry === "*") return true;
+		const split = splitHostPort(entry);
+		if (split.port !== void 0 && split.port !== port) continue;
+		const candidate = split.host.replace(/^\*?\./, "").replace(/\.$/, "");
+		if (candidate === "") continue;
+		if (host === candidate || host.endsWith(`.${candidate}`)) return true;
+	}
+	return false;
+}
+/**
+* Resolve the outbound proxy policy for this process.
+*
+* A scheme's own variable wins, then `ALL_PROXY`, then — for HTTPS only — the HTTP proxy, matching
+* undici so this function and the installed dispatcher never disagree about one URL.
+*
+* @param env - the launch environment, whose own layering already prefers real variables over `.env` files.
+* @returns the policy to install plus every rejected candidate.
+*/
+function resolveProxyPolicy(env) {
+	const diagnostics = [];
+	const all = acceptProxyUrl(readEnv(env, "all_proxy"), diagnostics);
+	const allValue = all.kind === "accepted" ? all.value : void 0;
+	const envHttp = acceptProxyUrl(readEnv(env, "http_proxy"), diagnostics);
+	const envHttps = acceptProxyUrl(readEnv(env, "https_proxy"), diagnostics);
+	const httpProxy = resolveScheme(envHttp, allValue);
+	const httpsProxy = resolveScheme(envHttps, allValue, httpProxy);
+	if (httpProxy === void 0 && httpsProxy === void 0) return {
+		policy: DIRECT_POLICY,
+		diagnostics
+	};
+	return {
+		policy: {
+			...httpProxy === void 0 ? {} : { httpProxy },
+			...httpsProxy === void 0 ? {} : { httpsProxy },
+			noProxy: withLoopback(readEnv(env, "no_proxy")?.value),
+			source: "env"
+		},
+		diagnostics
+	};
+}
+/**
+* Resolve which proxy one URL goes through under a policy.
+*
+* This is the single answer both the installed dispatcher and `qilin-web-fetch-http` consult, so a URL
+* can never be pinned to a resolved address by one and tunnelled by the other.
+*
+* @param policy - the active policy.
+* @param url - the request URL.
+* @returns the proxy URL to tunnel through, or `undefined` for a direct connection.
+*/
+function proxyForUrl(policy, url) {
+	const proxy = url.protocol === "https:" ? policy.httpsProxy : url.protocol === "http:" ? policy.httpProxy : void 0;
+	if (proxy === void 0) return void 0;
+	if (isLoopbackHost(url.hostname)) return void 0;
+	return bypassesProxy(policy.noProxy, url) ? void 0 : proxy;
+}
+//#endregion
+//#region lib/types/install.js
+/**
+* Proxy installation: the transport half of this package. It owns undici's global dispatcher and the
+* process-wide record of which policy is active.
+*
+* `undici` is imported dynamically so the pure {@link ProxyPolicy} half stays loadable where no Node
+* transport exists, matching how `qilin-web-fetch-http` defers its own transport import.
+* @module @qilin-agent/http-proxy/install
+*/
+/** The active policy, or `undefined` until one is installed. Process-wide, like the dispatcher it tracks. */
+let active;
+/**
+* The proxy environment as the user exported it, or `undefined` when no policy is installed.
+*
+* Owned by the OUTERMOST install: one layered over the launcher's would otherwise record the outer
+* policy's published values as if the user had written them, and
+* hand every child a normalization the user never asked for.
+*
+* {@link proxyEnvironmentForChild} keeps a value the user set rather than the one this process resolved from
+* it, so a SOCKS proxy `curl` can use is not replaced by an HTTP proxy named for another scheme.
+*/
+let inheritedProxyEnv;
+/** The dispatcher installed with {@link active}, so a route can hand back the one already routing. */
+let installed;
+/** A route that sends nothing through a proxy, shared because it carries no per-request state. */
+const DIRECT_ROUTE = { proxied: false };
+/**
+* Decide how to send one request, and hand back the transport that decision assumed.
+*
+* @param url - the request URL.
+* @returns the proxied route with its proxy URL and dispatcher, or the direct route.
+*/
+function proxyRouteFor(url) {
+	const policy = active;
+	const dispatcher = installed;
+	if (policy === void 0 || dispatcher === void 0) return DIRECT_ROUTE;
+	const proxy = proxyForUrl(policy, url);
+	return proxy === void 0 ? DIRECT_ROUTE : {
+		proxied: true,
+		proxy,
+		dispatcher
+	};
+}
+/**
+* Publish a policy through the proxy environment variables, which is how the consumers that read an
+* environment rather than a policy object — `node:http`'s `proxyEnv` and every spawned child — see
+* the one resolved answer, including the `ALL_PROXY` fallback and the merged loopback bypass that
+* neither derives on its own. The global dispatcher does not read these; it routes by the policy.
+*
+* @param policy - the policy to publish.
+* @returns a function restoring every name this call changed.
+*/
+function applyPolicyEnv(policy) {
+	const previousInherited = inheritedProxyEnv;
+	inheritedProxyEnv = previousInherited ?? snapshotProxyEnv();
+	const published = {};
+	for (const [field, names] of Object.entries(POLICY_ENV_NAMES)) {
+		const value = policy[field];
+		for (const name of names) published[name] = value;
+	}
+	const restore = writeProxyEnv(published);
+	return () => {
+		restore();
+		inheritedProxyEnv = previousInherited;
+	};
+}
+/**
+* Read every proxy name this package publishes, as `process.env` holds it now.
+*
+* @returns one entry per name in {@link POLICY_ENV_NAMES}; `undefined` marks an absent name.
+*/
+function snapshotProxyEnv() {
+	const snapshot = {};
+	for (const names of Object.values(POLICY_ENV_NAMES)) for (const name of names) snapshot[name] = process.env[name];
+	return snapshot;
+}
+/**
+* Set every proxy name to the value `values` holds for it, removing a name whose value is `undefined`.
+*
+* @param values - the value each name in {@link POLICY_ENV_NAMES} should hold.
+* @returns a function restoring every name to what it held before this call.
+*/
+function writeProxyEnv(values) {
+	const previous = snapshotProxyEnv();
+	for (const name of Object.keys(previous)) {
+		const value = values[name];
+		if (value === void 0) Reflect.deleteProperty(process.env, name);
+		else process.env[name] = value;
+	}
+	return () => {
+		for (const [name, value] of Object.entries(previous)) if (value === void 0) Reflect.deleteProperty(process.env, name);
+		else process.env[name] = value;
+	};
+}
+/**
+* Build the global dispatcher for one policy.
+*
+* Routing runs through {@link proxyForUrl} per origin, so `fetch` and every caller that asks where a
+* URL goes read the same answer from the same matcher. undici's `EnvHttpProxyAgent` cannot express
+* this policy: with no `HTTPS_PROXY` present it reuses the HTTP proxy for `https:`, which would
+* tunnel a scheme this package deliberately keeps direct after refusing the SOCKS or malformed URL
+* the user named for it — the route and the diagnostic would then disagree.
+*
+* @param policy - the policy to route by; it must proxy at least one scheme.
+* @returns the dispatcher to install, owning every per-origin agent its factory created.
+*/
+async function createPolicyDispatcher(policy) {
+	const { Agent, Pool, ProxyAgent } = await import("undici");
+	return new Agent({ factory(origin, options) {
+		const passed = options;
+		const proxy = proxyForUrl(policy, new URL(origin.toString()));
+		if (proxy !== void 0) return new ProxyAgent({
+			...passed,
+			uri: proxy
+		});
+		return new Pool(origin, passed);
+	} });
+}
+/**
+* Route this process's outbound HTTP through `policy`.
+*
+* Installing replaces undici's global dispatcher, which is what Node's built-in `fetch` resolves, so
+* every caller that issues a plain `fetch()` is covered without knowing this package exists. A policy
+* that proxies nothing installs a direct dispatcher and leaves the environment untouched.
+*
+* A worker thread has its own `globalThis` and so its own dispatcher; installing here does not
+* reach it. No worker installs one today: both this repository ships — the workflow engine and the
+* PTC runtime — evaluate model-authored scripts, which must not receive a proxy URL that may carry
+* credentials. A worker that needs the policy has to be handed one explicitly and install it itself.
+*
+* @param policy - the resolved policy to install.
+* @returns a disposer restoring the previous dispatcher, policy, and environment, then closing the agent.
+*/
+async function installGlobalProxy(policy) {
+	const previousPolicy = active;
+	if (policy.source === "none") {
+		if (previousPolicy === void 0) {
+			active = policy;
+			return () => {
+				active = previousPolicy;
+				return Promise.resolve();
+			};
+		}
+		const previousInstalled = installed;
+		const restoreEnv = inheritedProxyEnv === void 0 ? void 0 : writeProxyEnv(inheritedProxyEnv);
+		const undici = await import("undici");
+		const previous = undici.getGlobalDispatcher();
+		const direct = new undici.Agent();
+		undici.setGlobalDispatcher(direct);
+		active = policy;
+		installed = void 0;
+		return async () => {
+			undici.setGlobalDispatcher(previous);
+			active = previousPolicy;
+			installed = previousInstalled;
+			restoreEnv?.();
+			await direct.close();
+		};
+	}
+	const restoreEnv = applyPolicyEnv(policy);
+	const { getGlobalDispatcher, setGlobalDispatcher } = await import("undici");
+	const previousDispatcher = getGlobalDispatcher();
+	const previousInstalled = installed;
+	const agent = await createPolicyDispatcher(policy);
+	setGlobalDispatcher(agent);
+	active = policy;
+	installed = agent;
+	return async () => {
+		setGlobalDispatcher(previousDispatcher);
+		active = previousPolicy;
+		installed = previousInstalled;
+		restoreEnv();
+		await agent.close();
+	};
+}
+/**
+* The proxy environment a spawned child needs.
+*
+* A child inherits the parent environment, which this process rewrote to its own resolved policy.
+* Handing that normalization straight through would replace values the user set for other tools, so
+* each proxy name the user exported is restored to what they wrote: a SOCKS proxy `curl` uses is
+* not swapped for the HTTP one this package fell back to for that scheme.
+*
+* A scheme the user named in neither casing carries the resolved value instead of being removed.
+* Without that the child's routing silently diverges from its parent's: `NODE_USE_ENV_PROXY` does
+* not read `ALL_PROXY`, so a child of a parent that resolved its proxy from that name would connect
+* directly while the parent proxies.
+*
+* The bypass list is always the resolved one. It only ever adds the loopback entries to what
+* the user wrote, so nothing is lost, and the child stops sending its own localhost traffic to a
+* proxy that cannot route it.
+*
+* The flag reaches only Node 22.21+ and 24+; an older runtime keeps that child direct. Such a child
+* also matches bypass entries with Node's own `NO_PROXY` rules, which differ from this package's in
+* their separators and IPv4-range support. Non-Node children (curl, git, pnpm) ignore the flag and
+* read the variables themselves.
+*
+* The flag is withheld when a proxy value the child receives is one this package refused. Node
+* parses `HTTP_PROXY` and `HTTPS_PROXY` under that flag before running the program, and exits on a
+* scheme other than `http:` or `https:` — so a SOCKS value kept for `curl` would stop every Node
+* child from starting. Without the flag such a child connects directly, as this process already
+* reported for that scheme, and `curl` still reads the value it was kept for.
+*
+* A worker thread is deliberately NOT served here — see the workflow engine, which runs
+* model-authored scripts and must not receive a proxy URL that may carry credentials.
+*
+* @returns names to apply to the child environment, where `undefined` means remove, or an empty
+*   object when no proxy is active.
+*/
+function proxyEnvironmentForChild() {
+	const policy = active;
+	const inherited = inheritedProxyEnv;
+	if (policy === void 0 || policy.source === "none" || inherited === void 0) return {};
+	const overlay = { NODE_USE_ENV_PROXY: "1" };
+	for (const [field, names] of Object.entries(POLICY_ENV_NAMES)) {
+		const resolved = policy[field];
+		const named = field !== "noProxy" && names.some((name) => inherited[name] !== void 0);
+		for (const name of names) overlay[name] = named ? inherited[name] : resolved;
+	}
+	if ([...POLICY_ENV_NAMES.httpProxy, ...POLICY_ENV_NAMES.httpsProxy].some((name) => overlay[name] !== void 0 && !isSupportedProxyUrl(overlay[name]))) delete overlay.NODE_USE_ENV_PROXY;
+	return overlay;
+}
+/**
+* Resolve this process's proxy policy from `env` and install it.
+*
+* Resolution, reporting, and installation are one operation because no caller needs them apart: the
+* launcher does all three in sequence before the first plugin mounts, and a policy resolved but not
+* installed routes nothing.
+*
+* A value the environment supplies but this package cannot use is reported and skipped rather than
+* thrown: the variable may have been exported for another tool, and a proxy the harness cannot use
+* must not stop the agent from starting.
+*
+* @param env - the launch environment, whose own layering already prefers real variables over `.env` files.
+* @param report - receives one message per rejected value, in the order the values were considered.
+* @returns a disposer restoring the previous dispatcher, policy, and environment.
+*/
+async function installProxyFromEnvironment(env, report) {
+	const { policy, diagnostics } = resolveProxyPolicy(env);
+	for (const diagnostic of diagnostics) report(diagnostic.message);
+	return await installGlobalProxy(policy);
+}
+/**
+* The environment overlay that removes every proxy name from a spawned child.
+*
+* A harness that replays a recorded session must reach its own fixture server, not the proxy a
+* developer or a CI runner exported; `undefined` is how a spawn removes a name it inherits.
+*
+* @returns one entry per proxy name, each `undefined`.
+*/
+function clearedProxyEnv() {
+	return Object.fromEntries(PROXY_ENV_NAMES.map((name) => [name, void 0]));
+}
+//#endregion
+export { clearedProxyEnv, installProxyFromEnvironment, proxyEnvironmentForChild, proxyRouteFor };

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Outbound HTTP proxy support for QiLin.
+ *
+ * Node's built-in `fetch` ignores `HTTP_PROXY` and friends, so every harness request would connect
+ * directly no matter what the user exported. The launcher resolves one policy from the launch
+ * environment and installs it as undici's global dispatcher, which is what `fetch` resolves — so
+ * LLM adapters, web search, MCP over HTTP, and telemetry are covered without touching their code.
+ *
+ * This is a library, not a plugin: transport policy has one answer per process, so there is nothing
+ * for a composition to mount, swap, or scope.
+ *
+ * Four functions, one per way a caller needs the policy — install it, ask how to send one request,
+ * build a child's environment, and strip the ambient one for a replay.
+ * @module @qilin-agent/http-proxy
+ */
+export { clearedProxyEnv, installProxyFromEnvironment, proxyEnvironmentForChild, proxyRouteFor, type ProxyRoute, } from './install.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/install.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Proxy installation: the transport half of this package. It owns undici's global dispatcher and the
+ * process-wide record of which policy is active.
+ *
+ * `undici` is imported dynamically so the pure {@link ProxyPolicy} half stays loadable where no Node
+ * transport exists, matching how `qilin-web-fetch-http` defers its own transport import.
+ * @module @qilin-agent/http-proxy/install
+ */
+import type { Dispatcher } from 'undici';
+import { type EnvLookup } from './policy.ts';
+/**
+ * How this process must send one request.
+ *
+ * A caller that branches on the answer needs the transport that answer assumed, or an install or
+ * disposal landing between the two would send the request somewhere the branch did not clear. The
+ * proxied arm therefore carries the dispatcher already routing by this policy: it is process-wide
+ * and long-lived, so a caller uses it and never closes it. Disposal closes that dispatcher rather
+ * than destroying it, so a request already dispatched when a policy is unmounted still finishes.
+ */
+export type ProxyRoute = {
+    readonly proxied: true;
+    readonly proxy: string;
+    readonly dispatcher: Dispatcher;
+} | {
+    readonly proxied: false;
+};
+/**
+ * Decide how to send one request, and hand back the transport that decision assumed.
+ *
+ * @param url - the request URL.
+ * @returns the proxied route with its proxy URL and dispatcher, or the direct route.
+ */
+export declare function proxyRouteFor(url: URL): ProxyRoute;
+/**
+ * The proxy environment a spawned child needs.
+ *
+ * A child inherits the parent environment, which this process rewrote to its own resolved policy.
+ * Handing that normalization straight through would replace values the user set for other tools, so
+ * each proxy name the user exported is restored to what they wrote: a SOCKS proxy `curl` uses is
+ * not swapped for the HTTP one this package fell back to for that scheme.
+ *
+ * A scheme the user named in neither casing carries the resolved value instead of being removed.
+ * Without that the child's routing silently diverges from its parent's: `NODE_USE_ENV_PROXY` does
+ * not read `ALL_PROXY`, so a child of a parent that resolved its proxy from that name would connect
+ * directly while the parent proxies.
+ *
+ * The bypass list is always the resolved one. It only ever adds the loopback entries to what
+ * the user wrote, so nothing is lost, and the child stops sending its own localhost traffic to a
+ * proxy that cannot route it.
+ *
+ * The flag reaches only Node 22.21+ and 24+; an older runtime keeps that child direct. Such a child
+ * also matches bypass entries with Node's own `NO_PROXY` rules, which differ from this package's in
+ * their separators and IPv4-range support. Non-Node children (curl, git, pnpm) ignore the flag and
+ * read the variables themselves.
+ *
+ * The flag is withheld when a proxy value the child receives is one this package refused. Node
+ * parses `HTTP_PROXY` and `HTTPS_PROXY` under that flag before running the program, and exits on a
+ * scheme other than `http:` or `https:` — so a SOCKS value kept for `curl` would stop every Node
+ * child from starting. Without the flag such a child connects directly, as this process already
+ * reported for that scheme, and `curl` still reads the value it was kept for.
+ *
+ * A worker thread is deliberately NOT served here — see the workflow engine, which runs
+ * model-authored scripts and must not receive a proxy URL that may carry credentials.
+ *
+ * @returns names to apply to the child environment, where `undefined` means remove, or an empty
+ *   object when no proxy is active.
+ */
+export declare function proxyEnvironmentForChild(): Readonly<Record<string, string | undefined>>;
+/**
+ * Resolve this process's proxy policy from `env` and install it.
+ *
+ * Resolution, reporting, and installation are one operation because no caller needs them apart: the
+ * launcher does all three in sequence before the first plugin mounts, and a policy resolved but not
+ * installed routes nothing.
+ *
+ * A value the environment supplies but this package cannot use is reported and skipped rather than
+ * thrown: the variable may have been exported for another tool, and a proxy the harness cannot use
+ * must not stop the agent from starting.
+ *
+ * @param env - the launch environment, whose own layering already prefers real variables over `.env` files.
+ * @param report - receives one message per rejected value, in the order the values were considered.
+ * @returns a disposer restoring the previous dispatcher, policy, and environment.
+ */
+export declare function installProxyFromEnvironment(env: EnvLookup, report: (message: string) => void): Promise<() => Promise<void>>;
+/**
+ * The environment overlay that removes every proxy name from a spawned child.
+ *
+ * A harness that replays a recorded session must reach its own fixture server, not the proxy a
+ * developer or a CI runner exported; `undefined` is how a spawn removes a name it inherits.
+ *
+ * @returns one entry per proxy name, each `undefined`.
+ */
+export declare function clearedProxyEnv(): Record<string, undefined>;
+//# sourceMappingURL=install.d.ts.map

package/lib/types/policy.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Proxy policy resolution: the pure, transport-free half of this package. It turns the launch
+ * environment into one {@link ProxyPolicy}, and answers which proxy
+ * (if any) a given URL goes through.
+ *
+ * Nothing here imports `undici`, so the module stays loadable in the browser-worker runtime that
+ * evaluates `qilin-web-fetch-http` without a Node transport.
+ * @module @qilin-agent/http-proxy/policy
+ */
+/**
+ * The one thing resolution needs from an environment: a name in, the winning value out. The
+ * launcher's snapshot satisfies this structurally and is passed unchanged, so this module names no
+ * package to describe its input — and a test builds one from an object literal.
+ */
+export interface EnvLookup {
+    /**
+     * Resolve one variable name.
+     * @param name - the variable name.
+     * @returns the winning entry, or `undefined` when nothing supplies it.
+     */
+    get(name: string): {
+        readonly value: string;
+    } | undefined;
+}
+/**
+ * Loopback entries merged into every policy's `noProxy`. A proxy that also serves the harness's own
+ * loopback traffic turns the Web UI, the Connection transport, and every local test server into a
+ * routing loop, so the bypass is not optional.
+ *
+ * `::1` and `[::1]` are both listed because the resolved string is also handed to undici, whose
+ * matcher reads a bare `::1` as host `:` port `1` and therefore never bypasses it.
+ */
+export declare const LOOPBACK_NO_PROXY: readonly string[];
+/**
+ * The environment names each policy field owns, lowercase first — undici reads the lowercase name
+ * first, so both casings are always written or cleared together.
+ */
+export declare const POLICY_ENV_NAMES: {
+    readonly httpProxy: readonly ["http_proxy", "HTTP_PROXY"];
+    readonly httpsProxy: readonly ["https_proxy", "HTTPS_PROXY"];
+    readonly noProxy: readonly ["no_proxy", "NO_PROXY"];
+};
+/**
+ * Every environment name that carries proxy configuration, including the `ALL_PROXY` fallback this
+ * package resolves but never writes back. A caller that must isolate a child from the machine's
+ * network policy clears exactly these.
+ */
+export declare const PROXY_ENV_NAMES: readonly string[];
+/**
+ * One resolved outbound proxy policy. Plain data with no methods: worker threads receive it through
+ * `workerData`'s structured clone, so both sides run the identical policy rather than each re-reading
+ * an environment they may not share.
+ */
+export interface ProxyPolicy {
+    /** Proxy for `http:` origins, or absent for a direct connection. Always a validated `http(s):` URL. */
+    readonly httpProxy?: string;
+    /** Proxy for `https:` origins, or absent for a direct connection. Always a validated `http(s):` URL. */
+    readonly httpsProxy?: string;
+    /** The bypass list, already merged with {@link LOOPBACK_NO_PROXY}. Empty when nothing is bypassed. */
+    readonly noProxy: string;
+    /** Which layer supplied the winning proxy URL; `env` when either field came from the environment. */
+    readonly source: 'env' | 'none';
+}
+/** A policy that proxies nothing. Callers that have not installed a policy resolve URLs against this. */
+export declare const DIRECT_POLICY: ProxyPolicy;
+/** Why one candidate proxy value was not used. Callers decide whether this warns or fails the load. */
+export interface ProxyDiagnostic {
+    /** `socks` for a SOCKS or PAC URL this package cannot route; `invalid` for anything unparseable. */
+    readonly kind: 'socks' | 'invalid';
+    /** The environment variable that supplied the rejected value. */
+    readonly origin: string;
+    /** Operator-facing sentence naming the rejection and the way forward. Carries no credential. */
+    readonly message: string;
+}
+/** A resolved policy plus every candidate value that was rejected on the way to it. */
+export interface ProxyResolution {
+    /** The policy to install. Never carries a rejected value. */
+    readonly policy: ProxyPolicy;
+    /** Rejections, in the order the candidates were considered. Empty on a clean resolution. */
+    readonly diagnostics: readonly ProxyDiagnostic[];
+}
+/**
+ * Whether a proxy URL is one this package accepts: parseable, with an `http:` or `https:` scheme.
+ * The same test {@link acceptProxyUrl} applies, without its diagnostics.
+ *
+ * @param value - the proxy URL as an environment variable holds it.
+ * @returns true when the URL would be accepted.
+ */
+export declare function isSupportedProxyUrl(value: string): boolean;
+/**
+ * Whether a host names this machine.
+ *
+ * A proxy cannot meaningfully reach one: it would resolve the address in its own network, and a
+ * proxy running on this machine would reach a service that only listens on loopback. The bypass
+ * list carries {@link LOOPBACK_NO_PROXY} for the consumers that read an environment rather than a
+ * policy, but those are four literal entries — matching them alone leaves `127.0.0.2`, the whole
+ * rest of `127.0.0.0/8`, and the IPv4-mapped spelling routed through the proxy.
+ *
+ * @param hostname - a URL's hostname, bracketed or not.
+ * @returns true when the host is loopback or the unspecified address.
+ */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Decide whether a bypass list exempts one URL. An entry names a host and matches it together with
+ * every subdomain under it — `example.com` also bypasses `api.example.com` — and a leading `.` or
+ * `*.` is accepted as the same thing; an entry may carry a `:port`, and `*` bypasses everything.
+ * CIDR notation is not matched —
+ * an operating system's bypass list often carries `10.0.0.0/8`, which must be rewritten as suffixes.
+ *
+ * @param noProxy - the effective bypass list.
+ * @param url - the request URL.
+ * @returns true when the URL must bypass the proxy.
+ */
+export declare function bypassesProxy(noProxy: string, url: URL): boolean;
+/**
+ * Resolve the outbound proxy policy for this process.
+ *
+ * A scheme's own variable wins, then `ALL_PROXY`, then — for HTTPS only — the HTTP proxy, matching
+ * undici so this function and the installed dispatcher never disagree about one URL.
+ *
+ * @param env - the launch environment, whose own layering already prefers real variables over `.env` files.
+ * @returns the policy to install plus every rejected candidate.
+ */
+export declare function resolveProxyPolicy(env: EnvLookup): ProxyResolution;
+/**
+ * Resolve which proxy one URL goes through under a policy.
+ *
+ * This is the single answer both the installed dispatcher and `qilin-web-fetch-http` consult, so a URL
+ * can never be pinned to a resolved address by one and tunnelled by the other.
+ *
+ * @param policy - the active policy.
+ * @param url - the request URL.
+ * @returns the proxy URL to tunnel through, or `undefined` for a direct connection.
+ */
+export declare function proxyForUrl(policy: ProxyPolicy, url: URL): string | undefined;
+//# sourceMappingURL=policy.d.ts.map

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@qilin-agent/http-proxy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Process-wide outbound HTTP proxy policy for QiLin: resolve it from the launch environment and install it as undici's global dispatcher",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/util/http-proxy"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "dependencies": {
+    "undici": "^8.10.0"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }