agent-dual-proxy 0.0.0-stage → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.7.0
+
+独立项目的首个正式版本：从 0.5.0 拆出版本回补 0.5.1–0.7.0 的核心演进，并把 agent 适配面扩展到主流 CLI。
+
+### Added
+
+- 上游代理认证：`upstreamUrl`、`gateways`、启动环境代理 URL 可带 `user:pass`，CONNECT/HTTP/TLS 探测/健康检查带 `Proxy-Authorization: Basic`；凭证不进日志、不转发给目标。
+- `upstreamUrl` 配置/CLI/env 字段：非空时覆盖 `upstreamHost`/`upstreamPort`，非法值 fail fast 且错误信息脱敏。
+- 幂等键重放：`retryNonIdempotentWithIdempotencyKey`，仅在请求带非空 `Idempotency-Key`/`X-Idempotency-Key` 时允许发送后重放非幂等请求。
+- `responseTimeoutMs`：普通 HTTP 等响应头的上限，响应体开始流之后不再计时。
+- 407 语义：上游代理拒绝认证时视为该网关失败并换路，不转发给客户端。
+- 逐跳标头过滤（RFC 9110），请求方向重写 `Host`。
+- 偏好缓存 LRU 上限（默认 1000 条）；关闭时最多等 `shutdownTimeoutMs` 再强制断开在途 socket。
+- 健康检查重入锁，周期检查与失败踢动不会并发探测。
+- CONNECT 200 同包早期数据转交客户端；IPv6 字面量不做无效的 `servername`。
+- CLI 参数校验统一为一行错误、退出码 2；帮助文本补齐新选项。
+- `agent-gateway` 内置短名扩展到 13 个：claude、codex、gemini、pi、aider、opencode、qwen、cursor（`cursor-agent`）、droid、amp、crush、goose、copilot；不在表里的用 `run -- <cmd>`。
+
+### Changed
+
+- `agent-gateway` 注入子进程环境时替换启动环境的 socks `ALL_PROXY`，`NO_PROXY` 与用户原有直连段合并而不是覆盖。
+- `agent-gateway` 的启动环境 `HTTP(S)_PROXY`/`ALL_PROXY` 会作为候选网关，自身监听端口自动排除；`env` 子命令输出增加 `ALL_PROXY`/`all_proxy`。
+- Node 要求提升到 `>=22.19.0`（与 undici 8 一致），启动时给出可读错误。
+
+### Tests
+
+- 回补上游认证、407、幂等键重放、两段超时、逐跳标头、IPv6、CONNECT 早期数据、偏好 LRU、健康重入锁、CLI 校验等用例；测试总数 109。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gambn and dsh-dual-proxy Contributors
+
+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.en.md

@@ -0,0 +1,141 @@
+# agent-dual-proxy
+
+[English](README.en.md) · [中文](README.md)
+
+[![CI](https://github.com/gambn/agent-dual-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/gambn/agent-dual-proxy/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/agent-dual-proxy.svg)](https://www.npmjs.com/package/agent-dual-proxy)
+
+**A gateway manager for agents: switch between multiple gateways online, so model requests are never stuck on one flaky path.**
+
+It treats the network path from an agent to the model endpoint as a managed resource: it picks whichever configured upstream, extra proxy, launch-environment proxy, or direct connection can reach the target, keeps verifying that channel with real requests, and switches on failure — without restarting the agent or touching client configuration.
+
+## Quick start
+
+```bash
+# Standalone CLI
+npm install -g agent-dual-proxy
+
+# Wrap a CLI agent such as Claude Code
+agent-gateway run claude --resume
+```
+
+Requires Node.js ≥ 22.19.0. Built-in short names cover Claude Code, Codex CLI, Gemini CLI, Aider, OpenCode, Qwen Code, Cursor CLI, Droid, Amp, Crush, Goose, GitHub Copilot CLI, and pi; see [docs/agents.md](docs/agents.md) for the full table. For anything not listed, use `agent-gateway run -- <cmd> [args...]`.
+
+Install from source (optional):
+
+```bash
+git clone https://github.com/gambn/agent-dual-proxy.git
+cd agent-dual-proxy
+npm install
+```
+
+Two shapes, one core:
+
+- **Agent launcher** (recommended): `agent-gateway run <agent>` starts the proxy, injects the proxy environment, and execs the agent; the proxy stops when the agent exits.
+- **Standalone process**: run `dual-proxy` as a long-lived proxy, or install it as a systemd user service.
+
+## What it solves
+
+Upstream proxies are not reliable: the same proxy may reach site A but not site B, or be down for a while entirely. When two proxies are installed on one machine, which one works can change from hour to hour. A client that only knows one path fails in bursts, and retrying on a dead path only adds delay.
+
+This layer keeps all candidate paths in hand and chooses per host:
+
+```
+client → 127.0.0.1:7898
+           ├── gateway A (TLS probe passes) → upstream proxy
+           ├── gateway B (TLS probe passes) → upstream proxy
+           └── all probes fail → direct
+```
+
+The health check runs the same candidate list with a real request; the first one that returns a response below 500 becomes the global favourite.
+
+## Behaviour
+
+- Candidate gateways = `upstreamHost:upstreamPort` (or `upstreamUrl`) + `gateways` + `HTTP(S)_PROXY`/`ALL_PROXY` from the launch environment, deduplicated, excluding the proxy's own listen port, with `direct` appended last.
+- **Upstream proxy authentication**: `upstreamUrl`, `gateways`, or a proxy URL in the launch environment may carry `user:pass`; proxy connections then send `Proxy-Authorization: Basic`. 0.7.0 supports only `http://` upstream proxies: `upstreamUrl` with `https://` is an error; extra candidates (`gateways`, `--gateway`, `GATEWAY`, launch-environment proxies) with `https://` or invalid values are skipped with a redacted warning. Basic is base64, not encryption; use it only on loopback or trusted networks.
+- **CONNECT (HTTPS)**: on 443, each candidate gets a TLS handshake probe; only a candidate that passes is used to open the tunnel. On failure, the next one is tried.
+- **Plain HTTP**: the request body is buffered first (8 MB limit), and the request is replayed along the same candidate order. Connect uses `attemptTimeoutMs` (`fastFailTimeoutMs` for a known path), waiting for response headers uses `responseTimeoutMs`; the timer stops once the response body starts streaming.
+- **Idempotency-key replay**: with `retryNonIdempotentWithIdempotencyKey` on, a non-idempotent request is replayed after send only when it carries a non-empty `Idempotency-Key`/`X-Idempotency-Key`; the proxy does not verify that the upstream actually deduplicates.
+- **Replay policy (plain HTTP only; CONNECT tunnels are never replayed)**: if the TCP connection to the gateway/target is not established yet, any method is replayed. Once the connection is established, only idempotent methods are replayed (`GET`/`HEAD`/`OPTIONS`/`TRACE`/`PUT`/`DELETE`). `POST`/`PATCH` and other methods stop by default with 502 and the body `non-idempotent request may have been delivered; not replayed`; enable `retryNonIdempotentAfterSend` for the old behaviour.
+- **Fast-fail covers the connect phase only**: if the cached or health-preferred gateway cannot connect over TCP, it is skipped within 2 seconds; if it connects but never returns response headers, the request still waits the full `responseTimeoutMs` (60 seconds by default).
+- **Health check**: every `healthIntervalMs`, a `GET healthUrl` validates the channel; anything below 500 counts as reachable (401/403 means the endpoint is alive). The winner becomes the global favourite; if all candidates fail, the favourite is cleared and the next request re-scans. Set to `0` to disable.
+- **Per-host preference cache** (60 seconds by default, up to 1000 entries, LRU eviction): a cache hit skips probing; a failure switches immediately.
+- **Gateway cooldown** (30 seconds by default): after a failure, that candidate moves to the end of the order so other hosts do not hit it first; a successful health check clears the cooldown.
+- **Failure triggers a health check**: any failed path kicks a health re-check (at most once per second), instead of waiting for the next 60-second cycle.
+- **Hop-by-hop headers** are stripped per RFC 9110 (`Connection` and the fields it names, `Proxy-Connection`, `Transfer-Encoding`, etc.), and `Host` is rewritten to the target; response hop-by-hop headers are stripped too.
+- **IPv6**: CONNECT accepts literals such as `[::1]:443`; hosts are normalised by removing brackets, lowercasing, and dropping a trailing dot.
+- **Shutdown** waits up to `shutdownTimeoutMs` (1.5 seconds by default; an internal option) for in-flight requests, then force-destroys all sockets.
+- A 502 is returned when every candidate fails, and also immediately when a non-idempotent request fails after the connection is established with `retryNonIdempotentAfterSend` off and no usable idempotency-key switch (remaining candidates are not tried).
+- Logs contain the host, gateway and reason only; request contents are never logged.
+
+## As a standalone process
+
+```bash
+dual-proxy --listen-port 7898 --upstream-port 7897 \
+  --gateway 127.0.0.1:12334 --health-url https://api.deepseek.com
+
+node bin/dual-proxy.js --listen-port 7898      # if it is not on PATH
+```
+
+| Flag | Default | Description |
+| :--- | :--- | :--- |
+| `--listen-host` | `127.0.0.1` | Listen address |
+| `--listen-port` | `7898` | Listen port |
+| `--upstream-host` | `127.0.0.1` | First candidate gateway |
+| `--upstream-port` | `7897` | Port of the first candidate |
+| `--upstream-url` | — | Full URL of the first candidate, may include `user:pass`; overrides host/port |
+| `--gateway` | — | Extra candidate, repeatable |
+| `--health-url` | empty | Channel check URL |
+| `--health-interval-ms` | `60000` | Health-check interval, `0` disables |
+| `--fast-fail-ms` | `2000` | Connect timeout for a known path |
+| `--cooldown-ms` | `30000` | Cooldown for a failed gateway |
+| `--timeout-ms` | `5000` | Per-attempt/per-probe timeout |
+| `--response-timeout-ms` | `60000` | Upper bound for response headers |
+| `--pref-ttl-ms` | `60000` | Per-host preference TTL |
+| `--no-verify-tls` | off | Skip the TLS probe on 443 |
+| `--retry-non-idempotent-after-send` | off | Also replay `POST`/`PATCH` after the connection was established |
+| `--retry-non-idempotent-with-idempotency-key` | off | Allow post-send replay when `Idempotency-Key` is present |
+
+Environment variables use the same names (`LISTEN_HOST`, `LISTEN_PORT`, `UPSTREAM_HOST`, `UPSTREAM_PORT`, `UPSTREAM_URL`, `GATEWAY`, `HEALTH_URL`, `HEALTH_INTERVAL_MS`, `FAST_FAIL_MS`, `COOLDOWN_MS`, `ATTEMPT_TIMEOUT_MS`, `RESPONSE_TIMEOUT_MS`, `PREF_TTL_MS`, `VERIFY_TLS=0`, `RETRY_NON_IDEMPOTENT_AFTER_SEND=1`, `RETRY_NON_IDEMPOTENT_WITH_IDEMPOTENCY_KEY=1`).
+
+A systemd user-service template lives in `contrib/`.
+
+## For mainstream CLI agents
+
+Agents such as Claude Code, Codex CLI, and Gemini CLI share no plugin API; the only common ground is `HTTP(S)_PROXY`. The launcher does three things: start the dual proxy, inject the proxy environment into the child, and exec the agent.
+
+```bash
+agent-gateway run claude --resume   # start proxy → inject → exec
+agent-gateway run -- <any command>  # beyond the built-in table
+agent-gateway env                   # print export statements to source
+```
+
+Injection replaces a socks `ALL_PROXY` inherited from the launch environment: many clients prefer it, and leaving it in place bypasses `HTTP(S)_PROXY`, defeating the whole point. `NO_PROXY` is merged with the user's existing bypasses rather than overwritten; loopback stays direct, so an agent's own local ports (hooks, LSP, language servers) are never swallowed by the proxy. If the port is already in use, the launcher reuses the existing listener; when the child exits, the proxy is closed and no orphan process is left behind. See [docs/agents.md](docs/agents.md) for per-agent details.
+
+## Tests
+
+```bash
+npm test
+```
+
+The suite runs from the repository or the source archive; run `npm install` once in the source directory before `npm test`. The npm package does not include `test/`, so it cannot be run from an installed package.
+
+The suite covers: HTTP direct fallback, forwarding through a fake proxy, skipping a dead gateway among several, 502 when every path fails, timeout-based failover from a black-hole gateway, hop-by-hop header filtering in both directions, upstream disconnects mid-response without crashing, CONNECT direct tunnels and fake-proxy tunnels, early data arriving with the CONNECT 200, IPv6 literals, fast-fail when a cached gateway stalls, cooldown after a failure, forced tunnel teardown on shutdown, gateway parsing/deduplication (including self-exclusion and self-loop protection), health-check selection and failure, the health loop remembering the favourite, failure kicking a health check, the health-check reentrancy lock, the preference-cache cap, CLI validation and exit codes, self-signed TLS probing, the non-idempotent replay policy (send boundary, method classes, switch, logs and cooldown), upstream proxy authentication (CONNECT/HTTP/health, 407), the idempotency-key replay switch (presence checks and logs), and the agent launcher's environment injection, exit-code passthrough, and port reuse.
+
+## Boundaries
+
+- Only HTTP/1.1 `CONNECT` and plain HTTP; no transparent proxying and no UDP.
+- A plain HTTP request waits up to `responseTimeoutMs` (60 seconds by default) for response headers after the gateway connection is established; 0.7.0 does not shorten that wait, and the idempotency key only changes the replay decision after the timeout.
+- Once a CONNECT tunnel is established the proxy only forwards bytes and TLS is end-to-end; an in-tunnel failure cannot be failed over. Covering it would require MITM decryption, which conflicts with this project's no-interception design.
+- Certificates are not verified, contents are not cached, and there is no authentication. It binds to loopback by default; changing `listenHost` to a non-loopback address logs a warning at startup — that turns it into an unauthenticated proxy, at your own risk.
+- Upstream proxy authentication is HTTP Basic only; `https://` upstream proxies (TLS-to-proxy) are not supported. Basic is suitable only on loopback or trusted networks; protecting credentials to a remote proxy is outside this project's scope.
+- It only answers "can I get there", not "can I trust it" — certificate validation remains the client's responsibility.
+- The health check sends one unauthenticated `GET`; the criterion is "a response below 500", not whether credentials or model permissions are valid.
+- **At-most-once is not guaranteed**: with the default `retryNonIdempotentAfterSend: false`, `POST`/`PATCH` return 502 immediately after a failure once the connection is established (possibly delivered, not replayed), while idempotent methods are still replayed; enabling the switch restores replay-after-send at the cost of possible duplicate execution. Client SDK retries on 5xx are outside the proxy's control; for billing- or write-sensitive calls, use idempotency keys upstream.
+
+## Feedback
+
+Use GitHub Issues for questions, bugs, and suggestions: <https://github.com/gambn/agent-dual-proxy/issues>. Do not paste tokens, keys, or full request contents into an issue; see [SECURITY.md](SECURITY.md) for security reports.
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# agent-dual-proxy
 
-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.
+[中文](README.md) · [English](README.en.md)
+
+[![CI](https://github.com/gambn/agent-dual-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/gambn/agent-dual-proxy/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/agent-dual-proxy.svg)](https://www.npmjs.com/package/agent-dual-proxy)
+
+**Agent 的网关管理器：在多个网关之间在线自动切换，让模型请求不再被一条不稳的路卡死。**
+
+它把「agent 到模型端点的网络路径」当成可管理的资源：在配置的上游、额外指定的代理、启动环境里的代理和直连之间自动选一条能通的；运行中用真实请求持续验证，失败立刻切到下一条——不需要重启 agent，也不需要改客户端配置。
+
+## 快速开始
+
+```bash
+# 独立 CLI
+npm install -g agent-dual-proxy
+
+# 给 Claude Code 等 CLI agent 套上
+agent-gateway run claude --resume
+```
+
+要求 Node.js ≥ 22.19.0。内置短名覆盖 Claude Code、Codex CLI、Gemini CLI、Aider、OpenCode、Qwen Code、Cursor CLI、Droid、Amp、Crush、Goose、GitHub Copilot CLI 和 pi；完整对照见 [docs/agents.md](docs/agents.md)。不在表里的命令用 `agent-gateway run -- <cmd> [args...]`。
+
+从源码安装（可选）：
+
+```bash
+git clone https://github.com/gambn/agent-dual-proxy.git
+cd agent-dual-proxy
+npm install
+```
+
+两种用法，同一份核心：
+
+- **AGENT 启动器**（推荐）：`agent-gateway run <agent>`，起代理 + 注入代理变量 + exec，agent 退出时代理跟着关；
+- **独立进程**：`dual-proxy` 跑一个常驻代理，或挂 systemd 用户服务。
+
+## 它解决什么
+
+上游代理并不稳定：同一个代理可能对 A 站通、对 B 站不通，也可能整段时间全挂；本机同时装着两个代理时，哪个能用还会变。只认一条路的客户端在这种时候会成片失败，而在死路上重试只是拖延。
+
+这一层把候选路都握在手里，按 host 选：
+
+```
+客户端 → 127.0.0.1:7898
+           ├── 网关 A（TLS 探测通过）→ 上游代理
+           ├── 网关 B（TLS 探测通过）→ 上游代理
+           └── 都探测失败 → 直连
+```
+
+健康检查用一个真实请求把同一组候选走一遍，谁先给出 <500 的响应，谁就成为全局首选。
+
+## 行为
+
+- 候选网关 = `upstreamHost:upstreamPort`（或 `upstreamUrl`）+ `gateways` + 启动环境的 `HTTP(S)_PROXY`/`ALL_PROXY`，去重并排除自身监听端口，最后补 `direct`。
+- **上游代理认证**：`upstreamUrl`、`gateways` 或环境变量里的 HTTP 代理 URL 可带 `user:pass`；连接代理时会带 `Proxy-Authorization: Basic`。0.7.0 只支持 `http://` 上游代理：`upstreamUrl` 传 `https://` 会报错；额外候选（`gateways`、`--gateway`、`GATEWAY`、启动环境代理）里的 `https://` 或非法值会给脱敏 warning 后跳过。Basic 只是 base64，不是加密，只建议回环或受信任网络。
+- **CONNECT（HTTPS）**：443 上先对候选做 TLS 握手探测，通过的才用来开隧道；失败换下一条。
+- **普通 HTTP**：请求体先缓冲（上限 8 MB），按同一顺序换路重放；建连用 `attemptTimeoutMs`（已知路径用 `fastFailTimeoutMs`），等响应头用 `responseTimeoutMs`，响应体开始流之后不再计时。
+- **幂等键重放**：打开 `retryNonIdempotentWithIdempotencyKey` 后，非幂等请求只有在带非空 `Idempotency-Key`/`X-Idempotency-Key` 时才允许发送后重放；代理不验证上游是否真的去重。
+- **重放策略（仅普通 HTTP，CONNECT 隧道不重放）**：到网关/目标的 TCP 连接还没建立就失败时，任何方法都重放；连接建立后失败时，只重放幂等方法（`GET`/`HEAD`/`OPTIONS`/`TRACE`/`PUT`/`DELETE`）。`POST`/`PATCH` 等默认停止并回 502，响应体是 `non-idempotent request may have been delivered; not replayed`；需要旧行为时打开 `retryNonIdempotentAfterSend`。
+- **已知路径的快失败只覆盖建连阶段**：缓存或健康首选的那条网关，TCP 连不上时 2 秒内换路；如果它连上了却迟迟不回响应头，仍要等满 `responseTimeoutMs`（默认 60 秒）。
+- **健康检查**：每 `healthIntervalMs` 用 `GET healthUrl` 验证一次通道，`<500` 就算通（401/403 说明端点活着）；通过者设为全局首选，全部失败则清掉首选、下次请求重新扫描。设为 `0` 关闭。
+- **每 host 偏好缓存**（默认 60 秒，最多 1000 条，LRU 淘汰）：缓存命中跳过探测；失败即切换。
+- **失败网关冷却**（默认 30 秒）：某条路失败后进入冷却，期间排到最后，别的 host 不会再先撞它；健康检查证明它恢复时自动解除。
+- **失败即复检**：任何一条路刚失败就踢一次健康检查（1 秒内只踢一次），不用等下一个 60 秒周期。
+- **逐跳标头**按 RFC 9110 过滤（`Connection` 及其点名的字段、`Proxy-Connection`、`Transfer-Encoding` 等），`Host` 重写为目标主机；响应方向的逐跳标头同样清掉。
+- **IPv6**：CONNECT 支持 `[::1]:443` 这类字面量，host 统一去掉方括号、转小写、去掉 FQDN 末尾的点。
+- **关闭**最多等 `shutdownTimeoutMs`（默认 1.5 秒，内部选项）让在途请求自然结束，超时后强制断开所有 socket。
+- 全部候选都失败时回 502；非幂等请求在连接建立后失败且未开 `retryNonIdempotentAfterSend`、也没有可用的幂等键开关时，也会立即回 502，不再尝试剩余候选。
+- 日志只写主机、网关与原因，不记录任何请求内容。
+
+## 作为独立进程
+
+```bash
+dual-proxy --listen-port 7898 --upstream-port 7897 \
+  --gateway 127.0.0.1:12334 --health-url https://api.deepseek.com
+
+node bin/dual-proxy.js --listen-port 7898      # 没装到 PATH 时直接跑
+```
+
+| 参数 | 默认 | 说明 |
+| :--- | :--- | :--- |
+| `--listen-host` | `127.0.0.1` | 监听地址 |
+| `--listen-port` | `7898` | 监听端口 |
+| `--upstream-host` | `127.0.0.1` | 第一个候选网关 |
+| `--upstream-port` | `7897` | 第一个候选网关的端口 |
+| `--upstream-url` | — | 第一个候选的完整 URL，可含 `user:pass`；非空时覆盖 host/port |
+| `--gateway` | — | 额外候选网关，可重复 |
+| `--health-url` | 空 | 通道验证地址 |
+| `--health-interval-ms` | `60000` | 健康检查间隔，`0` 关闭 |
+| `--fast-fail-ms` | `2000` | 已知路径的建连超时 |
+| `--cooldown-ms` | `30000` | 失败网关的冷却时长 |
+| `--timeout-ms` | `5000` | 每次尝试/探测超时 |
+| `--response-timeout-ms` | `60000` | 普通 HTTP 等响应头的上限 |
+| `--pref-ttl-ms` | `60000` | 每 host 偏好缓存 TTL |
+| `--no-verify-tls` | 关 | 跳过 443 的 TLS 探测 |
+| `--retry-non-idempotent-after-send` | 关 | 连接建立后失败时也重放 `POST`/`PATCH` |
+| `--retry-non-idempotent-with-idempotency-key` | 关 | 带 `Idempotency-Key` 时允许发送后重放 |
+
+环境变量同名（`LISTEN_HOST`、`LISTEN_PORT`、`UPSTREAM_HOST`、`UPSTREAM_PORT`、`UPSTREAM_URL`、`GATEWAY`、`HEALTH_URL`、`HEALTH_INTERVAL_MS`、`FAST_FAIL_MS`、`COOLDOWN_MS`、`ATTEMPT_TIMEOUT_MS`、`RESPONSE_TIMEOUT_MS`、`PREF_TTL_MS`、`VERIFY_TLS=0`、`RETRY_NON_IDEMPOTENT_AFTER_SEND=1`、`RETRY_NON_IDEMPOTENT_WITH_IDEMPOTENCY_KEY=1`）。
+
+systemd 用户服务模板在 `contrib/`。
+
+## 给主流 CLI agent 用
+
+Claude Code / Codex CLI / Gemini CLI 等 agent 没有共用的插件 API，唯一通杀的是 `HTTP(S)_PROXY`。启动器做三件事：起双路代理、把代理变量塞进子进程、exec。
+
+```bash
+agent-gateway run claude --resume   # 起代理 → 注入变量 → exec
+agent-gateway run -- <任意命令>      # 不限内置表
+agent-gateway env                   # 打印可 source 的 export 语句
+```
+
+注入时会替换启动环境里的 socks `ALL_PROXY`：不少客户端会优先读它，留着就绕过了 `HTTP(S)_PROXY`，双路选路白做。`NO_PROXY` 与用户原有的直连段合并而不是覆盖；回环地址默认直连，agent 自己的本地端口（hook、LSP、语言服务器）不会被代理吞掉。端口已被占用时复用现有监听；子进程退出后代理跟着关，不留孤儿进程。各家细节见 [docs/agents.md](docs/agents.md)。
+
+## 测试
+
+```bash
+npm test
+```
+
+测试面向仓库或源码快照；首次先在源码目录 `npm install`，再 `npm test`。npm 包不含 `test/`，安装后不能直接跑这套用例。
+
+用例覆盖：HTTP 直连回退、经假代理转发、多个网关时跳过不通的、两条都不通返回 502、黑洞网关按超时换路、请求与响应两个方向的逐跳标头过滤、上游中途断开不带崩进程、CONNECT 直连隧道与经假代理隧道、CONNECT 200 同包早期数据、IPv6 字面量、缓存网关卡住时快失败换路、失败网关冷却后不再先撞、关闭时强制断开在途隧道、网关解析与去重（含自身端口排除与自环防护）、健康检查的选择与失败、健康循环记住首选、失败踢一次健康检查、健康检查重入锁、偏好缓存上限、CLI 参数校验与退出码、自签证书的 TLS 探测、非幂等重放策略（send 前后边界、方法分类、开关、日志与冷却）、上游代理认证（CONNECT/HTTP/健康检查、407）、带幂等键的发送后重放（开关/键存在性/日志），以及 AGENT 启动器的环境注入、退出码透传与端口复用。
+
+## 边界
+
+- 只处理 HTTP/1.1 的 `CONNECT` 与普通 HTTP；不做透明代理、不接管 UDP。
+- 普通 HTTP 请求在网关连上后要等满 `responseTimeoutMs`（默认 60 秒）才判定响应头超时；0.7.0 不缩短这个等待，幂等键只改变超时后的重放决策。
+- CONNECT 隧道建立后代理只转发字节，TLS 端到端；隧道内失败无法换路，要覆盖只能做 MITM 解密，和本项目“不拦截”的定位冲突。
+- 不校验证书，不缓存内容，不做鉴权。默认只绑回环；把 `listenHost` 改成非回环地址会在启动时告警——那等于开放一个无鉴权代理，风险自负。
+- 上游代理认证只支持 `http://` 的 Basic；不支持 `https://` 上游代理（TLS-to-proxy）。Basic 只适合回环或受信任网络，远程代理的凭证保护不在本项目范围内。
+- 只负责「到不到得了」，不负责「信不信得过」——证书校验仍是客户端的责任。
+- 健康检查只发一个无凭证 `GET`，判据是「有没有 <500 的响应」，不代表凭证或模型权限有效。
+- **不保证「至多一次」**：默认 `retryNonIdempotentAfterSend: false` 时，`POST`/`PATCH` 在连接建立后失败会直接 502（可能已送达、未重放），幂等方法仍会重放；打开该开关会恢复发送后重放，代价是可能重复执行。客户端 SDK 对 5xx 的自动重试不受代理控制，对计费或写入敏感的调用仍应在上游使用幂等键。
+
+## 反馈
+
+问题、建议与使用疑问走 GitHub Issues：<https://github.com/gambn/agent-dual-proxy/issues>。请勿在 Issue 里粘贴 token、密钥或完整请求内容；安全问题见 [SECURITY.md](SECURITY.md)。
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported versions
+
+0.7.x receives security fixes. Older versions are not supported.
+
+## Reporting a problem
+
+Use GitHub Issues: <https://github.com/gambn/agent-dual-proxy/issues>
+
+This project does not use an email address for support or security reports. Do not include tokens, API keys, proxy credentials, request bodies, or logs containing secrets in an issue. If a report needs sensitive details, open an issue with a short, non-sensitive summary and ask for a private channel first; do not post the sensitive material publicly.
+
+## Release verification
+
+Release tags and commits are SSH-signed; verify with `git tag -v v0.7.0` and compare the downloaded artifacts against `SHA256SUMS` and `BUILD-INFO.txt`.
+
+## Scope
+
+- The proxy runs locally and is unauthenticated by default. Exposing it on a non-loopback address is outside the supported configuration and is warned about at startup.
+- The proxy does not validate upstream certificates, does not cache content, and does not authenticate clients.
+- HTTP upstream proxy authentication is supported via `Proxy-Authorization: Basic`; credentials are never logged and are not forwarded to the target. Basic is base64, not encryption, so use it only on loopback or trusted networks. `https://` upstream proxies (TLS-to-proxy) are not supported and are rejected explicitly.
+- The proxy does not authenticate its own clients; keep it on loopback unless you accept the risk.
+- Reports about this project's own code, dependency handling, or the release artifacts are in scope. Reports about third-party gateways or the model provider are not.

package/bin/agent-gateway.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { createDispatcher } from '../src/server.js';
+import { collectGateways, isLoopbackHost, resolveUpstream } from '../src/gateways.js';
+import { assertNode } from '../src/engines.js';
+import { AGENT_NAMES, resolveAgent, buildProxyEnv, proxyUrl } from '../src/agents.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const LAUNCHER_OPTS = [
+  '--listen-host', '--listen-port', '--upstream-host', '--upstream-port', '--upstream-url',
+  '--gateway', '--health-url', '--health-interval-ms', '--timeout-ms', '--response-timeout-ms',
+  '--fast-fail-ms', '--cooldown-ms', '--pref-ttl-ms'
+];
+const FLAGS = [
+  '--no-verify-tls', '--retry-non-idempotent-after-send',
+  '--retry-non-idempotent-with-idempotency-key'
+];
+
+function usage() {
+  process.stdout.write([
+    'agent-gateway ' + pkg.version + ' —— 给主流 CLI agent 套一层双路代理',
+    '',
+    'Usage:',
+    '  agent-gateway run [options] <agent> [agent-args...]',
+    '  agent-gateway run [options] -- <cmd> [args...]',
+    '  agent-gateway env [options]        # 打印可 source 的导出语句',
+    '',
+    'Agents: ' + AGENT_NAMES.join(', '),
+    '',
+    'Options:',
+    '  --listen-host <host>        default 127.0.0.1',
+    '  --listen-port <port>        default 7898',
+    '  --upstream-host <host>      default 127.0.0.1',
+    '  --upstream-port <port>      default 7897',
+    '  --upstream-url <url>        full upstream URL, may include user:pass',
+    '  --gateway <host:port>       extra candidate gateway, repeatable',
+    '  --health-url <url>          verify the channel with this URL, default off',
+    '  --health-interval-ms <ms>   default 60000, 0 disables',
+    '  --timeout-ms <ms>           per-attempt timeout, default 5000',
+    '  --response-timeout-ms <ms>  header wait for plain HTTP, default 60000',
+    '  --fast-fail-ms <ms>         timeout for the known path, default 2000',
+    '  --cooldown-ms <ms>          failed gateway rest, default 30000',
+    '  --pref-ttl-ms <ms>          per-host preference TTL, default 60000',
+    '  --no-verify-tls             skip the TLS reachability probe on 443',
+    '  --retry-non-idempotent-after-send  replay POST/PATCH after the body may have',
+    '                              been sent (dangerous; default off)',
+    '  --retry-non-idempotent-with-idempotency-key',
+    '                              replay POST/PATCH after send when Idempotency-Key is present',
+    '  -h, --help',
+    '  -v, --version',
+    ''
+  ].join('\n'));
+}
+
+/** 解析整数并校验范围；失败抛 Error，由顶层统一报一行。 */
+function integer(label, raw, min, max) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error('invalid value for ' + label + ': ' + raw + ' (expected integer ' + min + '..' + max + ')');
+  }
+  return value;
+}
+
+function parseArgs(argv, env = process.env) {
+  const opts = {
+    listenHost: env.LISTEN_HOST || '127.0.0.1',
+    listenPort: integer('LISTEN_PORT', env.LISTEN_PORT ?? 7898, 1, 65535),
+    upstreamHost: env.UPSTREAM_HOST || '127.0.0.1',
+    upstreamPort: integer('UPSTREAM_PORT', env.UPSTREAM_PORT ?? 7897, 1, 65535),
+    upstreamUrl: env.UPSTREAM_URL || '',
+    attemptTimeoutMs: integer('ATTEMPT_TIMEOUT_MS', env.ATTEMPT_TIMEOUT_MS ?? 5000, 100, 60000),
+    responseTimeoutMs: integer('RESPONSE_TIMEOUT_MS', env.RESPONSE_TIMEOUT_MS ?? 60000, 100, 600000),
+    prefTtlMs: integer('PREF_TTL_MS', env.PREF_TTL_MS ?? 60000, 0, 3600000),
+    gateways: env.GATEWAY ? [env.GATEWAY] : [],
+    healthUrl: env.HEALTH_URL || '',
+    healthIntervalMs: integer('HEALTH_INTERVAL_MS', env.HEALTH_INTERVAL_MS ?? 60000, 0, 3600000),
+    fastFailTimeoutMs: integer('FAST_FAIL_MS', env.FAST_FAIL_MS ?? 2000, 100, 60000),
+    cooldownMs: integer('COOLDOWN_MS', env.COOLDOWN_MS ?? 30000, 0, 600000),
+    retryNonIdempotentAfterSend: env.RETRY_NON_IDEMPOTENT_AFTER_SEND === '1',
+    retryNonIdempotentWithIdempotencyKey: env.RETRY_NON_IDEMPOTENT_WITH_IDEMPOTENCY_KEY === '1',
+    verifyTls: env.VERIFY_TLS !== '0'
+  };
+  const rest = [];
+  let explicit = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') {
+      rest.push(...argv.slice(i + 1));
+      explicit = true;
+      break;
+    }
+    if (!arg.startsWith('-')) {
+      rest.push(...argv.slice(i));
+      break;
+    }
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) throw new Error('missing value for ' + arg);
+      return argv[i];
+    };
+    if (arg === '--help' || arg === '-h') {
+      usage();
+      process.exit(0);
+    }
+    if (arg === '--version' || arg === '-v') {
+      process.stdout.write(pkg.version + '\n');
+      process.exit(0);
+    }
+    if (FLAGS.includes(arg)) {
+      if (arg === '--no-verify-tls') opts.verifyTls = false;
+      else if (arg === '--retry-non-idempotent-after-send') opts.retryNonIdempotentAfterSend = true;
+      else if (arg === '--retry-non-idempotent-with-idempotency-key') opts.retryNonIdempotentWithIdempotencyKey = true;
+      continue;
+    }
+    if (!LAUNCHER_OPTS.includes(arg)) {
+      // 不认识的开关当作目标 agent 的参数（例如 claude 自己的 --resume）
+      rest.push(...argv.slice(i));
+      break;
+    }
+    const value = next();
+    if (arg === '--listen-host') opts.listenHost = value;
+    else if (arg === '--listen-port') opts.listenPort = integer(arg, value, 1, 65535);
+    else if (arg === '--upstream-host') opts.upstreamHost = value;
+    else if (arg === '--upstream-port') opts.upstreamPort = integer(arg, value, 1, 65535);
+    else if (arg === '--upstream-url') opts.upstreamUrl = value;
+    else if (arg === '--gateway') opts.gateways.push(value);
+    else if (arg === '--health-url') opts.healthUrl = value;
+    else if (arg === '--health-interval-ms') opts.healthIntervalMs = integer(arg, value, 0, 3600000);
+    else if (arg === '--timeout-ms') opts.attemptTimeoutMs = integer(arg, value, 100, 60000);
+    else if (arg === '--response-timeout-ms') opts.responseTimeoutMs = integer(arg, value, 100, 600000);
+    else if (arg === '--fast-fail-ms') opts.fastFailTimeoutMs = integer(arg, value, 100, 60000);
+    else if (arg === '--cooldown-ms') opts.cooldownMs = integer(arg, value, 0, 600000);
+    else if (arg === '--pref-ttl-ms') opts.prefTtlMs = integer(arg, value, 0, 3600000);
+  }
+
+  return { opts, rest, explicit };
+}
+
+/** 端口上已经有东西在听就复用，别抢端口。 */
+// ponytail: 只判「有人在听」就复用，不验证它是不是本代理；跑错的监听会静默被当上游用。
+function portInUse(host, port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err) => resolve(err.code === 'EADDRINUSE'));
+    server.listen(port, host, () => server.close(() => resolve(false)));
+  });
+}
+
+async function serve(opts) {
+  const upstream = resolveUpstream(opts);
+  if (!isLoopbackHost(opts.listenHost)) {
+    process.stderr.write('warning: listening on ' + opts.listenHost + '; this proxy has no authentication\n');
+  }
+  const url = proxyUrl(opts);
+  if (await portInUse(opts.listenHost, opts.listenPort)) {
+    process.stderr.write('[agent-gateway] reusing existing listener on ' + url + '\n');
+    return { url, close: async () => {} };
+  }
+  // 启动环境里的 HTTP(S)_PROXY/ALL_PROXY 也是候选；self 排除自己。
+  const gateways = collectGateways({
+    upstream,
+    extra: opts.gateways,
+    env: process.env,
+    self: { host: opts.listenHost, port: opts.listenPort },
+    onInvalid: (subject, reason) => process.stderr.write('warning: ' + subject + ': ' + reason + '\n')
+  });
+  const dispatcher = createDispatcher(Object.assign({}, opts, {
+    upstreamHost: upstream.host,
+    upstreamPort: upstream.port,
+    upstreamAuth: upstream.auth,
+    gateways,
+    log: (msg) => process.stderr.write('[agent-gateway] ' + msg + '\n')
+  }));
+  const addr = await dispatcher.listen();
+  dispatcher.startHealth();
+  const bound = proxyUrl({ listenHost: addr.address, listenPort: addr.port });
+  process.stderr.write('[agent-gateway] listening on ' + bound + '\n');
+  return { url: bound, close: () => dispatcher.stopHealth() || dispatcher.close() };
+}
+
+async function run(argv) {
+  const { opts, rest, explicit } = parseArgs(argv);
+  let target;
+  if (rest.length === 0) {
+    usage();
+    process.exit(2);
+  }
+  // `run claude ...` 走适配表；`run -- cmd ...` 走裸命令
+  const adapter = explicit ? null : resolveAgent(rest[0]);
+  if (adapter) {
+    target = { bin: adapter.bin, args: rest.slice(1) };
+  } else if (explicit) {
+    target = { bin: rest[0], args: rest.slice(1) };
+  } else {
+    process.stderr.write('[agent-gateway] unknown agent: ' + rest[0]
+      + '\n  known: ' + AGENT_NAMES.join(', ')
+      + '\n  or: agent-gateway run -- <cmd> [args...]\n');
+    process.exit(2);
+  }
+
+  const bridge = await serve(opts);
+  const child = spawn(target.bin, target.args, {
+    stdio: 'inherit',
+    env: buildProxyEnv(bridge.url)
+  });
+
+  const stop = async (code) => {
+    await bridge.close();
+    process.exit(code);
+  };
+  child.on('error', (err) => {
+    process.stderr.write('[agent-gateway] failed to start ' + target.bin + ': ' + err.message + '\n');
+    stop(127);
+  });
+  child.on('exit', (code, signal) => stop(code === null ? 128 + (signal ? 1 : 0) : code));
+
+  // 让 agent 自己收尾，等它的 exit 事件再关代理，避免留下孤儿进程
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+      try { child.kill(signal); } catch (e) { /* ignore */ }
+    });
+  }
+}
+
+async function printEnv(argv) {
+  const { opts } = parseArgs(argv);
+  // 以当前 shell 环境为底：NO_PROXY 会把用户原有的直连段一起带出去
+  const env = buildProxyEnv(proxyUrl(opts));
+  const keys = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy', 'ALL_PROXY', 'all_proxy', 'NO_PROXY', 'no_proxy'];
+  process.stdout.write(keys.map((key) => 'export ' + key + '=' + env[key]).join('\n') + '\n');
+}
+
+async function main() {
+  try {
+    assertNode();
+    const [command, ...rest] = process.argv.slice(2);
+    if (command === '-h' || command === '--help' || command === undefined) {
+      usage();
+    } else if (command === '-v' || command === '--version') {
+      process.stdout.write(pkg.version + '\n');
+    } else if (command === 'run') {
+      await run(rest);
+    } else if (command === 'env') {
+      await printEnv(rest);
+    } else {
+      process.stderr.write('[agent-gateway] unknown command: ' + command + '\n');
+      usage();
+      process.exit(2);
+    }
+  } catch (err) {
+    process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 2;
+  }
+}
+
+main();