agent-dual-proxy 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.2
+
+### Changed
+
+- 移除未使用的 `undici` 依赖（本项目只用 Node 内置 `http`/`net`/`tls`）；Node 门槛从 `>=22.19.0` 降到 `>=22.0.0`。
+- `agent-gateway` 复用监听端口前先探测身份：只有本代理才复用；被其他程序占用时报错退出（退出码 1），不再把 agent 指向非代理端口。
+- 代理新增本地身份端点 `GET /__agent_dual_proxy__`，返回 `x-agent-dual-proxy: 1`，供端口复用探测与运维检查使用。
+
+### Tests
+
+- 新增身份端点、端口复用身份探测用例；更新 Node 门槛用例。
+
 ## 0.7.1
 
 ### Changed

package/README.en.md

@@ -18,7 +18,7 @@ npm install -g agent-dual-proxy
 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...]`.
+Requires Node.js ≥ 22.0.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):
 
@@ -109,7 +109,7 @@ 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.
+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 already hosts agent-dual-proxy, the launcher reuses that listener; if another program owns it, the launcher exits with an error instead of pointing the agent at a non-proxy port. 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
 
@@ -119,7 +119,7 @@ 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.
+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 identity probing.
 
 ## Boundaries
 

package/README.md

@@ -18,7 +18,7 @@ npm install -g agent-dual-proxy
 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...]`。
+要求 Node.js ≥ 22.0.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...]`。
 
 从源码安装（可选）：
 
@@ -109,7 +109,7 @@ 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)。
+注入时会替换启动环境里的 socks `ALL_PROXY`：不少客户端会优先读它，留着就绕过了 `HTTP(S)_PROXY`，双路选路白做。`NO_PROXY` 与用户原有的直连段合并而不是覆盖；回环地址默认直连，agent 自己的本地端口（hook、LSP、语言服务器）不会被代理吞掉。端口上已经有本代理时复用现有监听；被其他程序占用则报错退出，不会把 agent 指向一个非代理端口。子进程退出后代理跟着关，不留孤儿进程。各家细节见 [docs/agents.md](docs/agents.md)。
 
 ## 测试
 
@@ -119,7 +119,7 @@ npm test
 
 测试面向仓库或源码快照；首次先在源码目录 `npm install`，再 `npm test`。npm 包不含 `test/`，安装后不能直接跑这套用例。
 
-用例覆盖：HTTP 直连回退、经假代理转发、多个网关时跳过不通的、两条都不通返回 502、黑洞网关按超时换路、请求与响应两个方向的逐跳标头过滤、上游中途断开不带崩进程、CONNECT 直连隧道与经假代理隧道、CONNECT 200 同包早期数据、IPv6 字面量、缓存网关卡住时快失败换路、失败网关冷却后不再先撞、关闭时强制断开在途隧道、网关解析与去重（含自身端口排除与自环防护）、健康检查的选择与失败、健康循环记住首选、失败踢一次健康检查、健康检查重入锁、偏好缓存上限、CLI 参数校验与退出码、自签证书的 TLS 探测、非幂等重放策略（send 前后边界、方法分类、开关、日志与冷却）、上游代理认证（CONNECT/HTTP/健康检查、407）、带幂等键的发送后重放（开关/键存在性/日志），以及 AGENT 启动器的环境注入、退出码透传与端口复用。
+用例覆盖：HTTP 直连回退、经假代理转发、多个网关时跳过不通的、两条都不通返回 502、黑洞网关按超时换路、请求与响应两个方向的逐跳标头过滤、上游中途断开不带崩进程、CONNECT 直连隧道与经假代理隧道、CONNECT 200 同包早期数据、IPv6 字面量、缓存网关卡住时快失败换路、失败网关冷却后不再先撞、关闭时强制断开在途隧道、网关解析与去重（含自身端口排除与自环防护）、健康检查的选择与失败、健康循环记住首选、失败踢一次健康检查、健康检查重入锁、偏好缓存上限、CLI 参数校验与退出码、自签证书的 TLS 探测、非幂等重放策略（send 前后边界、方法分类、开关、日志与冷却）、上游代理认证（CONNECT/HTTP/健康检查、407）、带幂等键的发送后重放（开关/键存在性/日志），以及 AGENT 启动器的环境注入、退出码透传与端口复用的身份探测。
 
 ## 边界
 

package/bin/agent-gateway.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import net from 'node:net';
+import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { createDispatcher } from '../src/server.js';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createDispatcher, IDENTITY_HEADER, IDENTITY_PATH } 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';
@@ -56,11 +58,14 @@ function usage() {
   ].join('\n'));
 }
 
-/** 解析整数并校验范围；失败抛 Error，由顶层统一报一行。 */
+/** 参数错误：由顶层以退出码 2 结束。 */
+export class UsageError extends Error {}
+
+/** 解析整数并校验范围；失败抛 UsageError。 */
 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 + ')');
+    throw new UsageError('invalid value for ' + label + ': ' + raw + ' (expected integer ' + min + '..' + max + ')');
   }
   return value;
 }
@@ -100,7 +105,7 @@ function parseArgs(argv, env = process.env) {
     }
     const next = () => {
       i += 1;
-      if (i >= argv.length) throw new Error('missing value for ' + arg);
+      if (i >= argv.length) throw new UsageError('missing value for ' + arg);
       return argv[i];
     };
     if (arg === '--help' || arg === '-h') {
@@ -141,13 +146,33 @@ function parseArgs(argv, env = process.env) {
   return { opts, rest, explicit };
 }
 
-/** 端口上已经有东西在听就复用，别抢端口。 */
-// ponytail: 只判「有人在听」就复用，不验证它是不是本代理；跑错的监听会静默被当上游用。
-function portInUse(host, port) {
+/**
+ * 监听端口上是谁：free（没人听）、ours（本代理）、other（别的程序）。
+ *
+ * 只有 ours 才复用。别的程序占着端口时直接报错，不能把 agent 指向
+ * 一个根本不是代理的端口。
+ */
+export function probeListener(host, port, timeoutMs = 1500) {
+  const probeHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
   return new Promise((resolve) => {
-    const server = net.createServer();
-    server.once('error', (err) => resolve(err.code === 'EADDRINUSE'));
-    server.listen(port, host, () => server.close(() => resolve(false)));
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const req = http.get({
+      host: probeHost,
+      port,
+      path: IDENTITY_PATH,
+      timeout: timeoutMs,
+      agent: false
+    }, (res) => {
+      res.resume();
+      done(res.statusCode === 200 && res.headers[IDENTITY_HEADER] === '1' ? 'ours' : 'other');
+    });
+    req.on('timeout', () => req.destroy(new Error('probe timeout')));
+    req.on('error', (err) => done(err && err.code === 'ECONNREFUSED' ? 'free' : 'other'));
   });
 }
 
@@ -157,10 +182,15 @@ async function serve(opts) {
     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');
+  const existing = await probeListener(opts.listenHost, opts.listenPort);
+  if (existing === 'ours') {
+    process.stderr.write('[agent-gateway] reusing agent-dual-proxy on ' + url + '\n');
     return { url, close: async () => {} };
   }
+  if (existing === 'other') {
+    throw new Error('listen port ' + opts.listenPort + ' is already in use by something that is not '
+      + 'agent-dual-proxy; stop it or choose another --listen-port');
+  }
   // 启动环境里的 HTTP(S)_PROXY/ALL_PROXY 也是候选；self 排除自己。
   const gateways = collectGateways({
     upstream,
@@ -254,8 +284,20 @@ async function main() {
     }
   } catch (err) {
     process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
-    process.exitCode = 2;
+    process.exitCode = err instanceof UsageError ? 2 : 1;
+  }
+}
+
+/** 入口判断：npm 通过符号链接调用时，argv[1] 与真实路径不同，必须 realpath 比较。 */
+function isMain() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch (err) {
+    return false;
   }
 }
 
-main();
+if (isMain()) {
+  main();
+}

package/docs/agents.md

@@ -6,7 +6,8 @@
 agent-gateway run <agent>   →   起双路代理 + 把代理变量塞进子进程 + exec
 ```
 
-端口已被占用时复用那一个；子进程退出后代理跟着关，不留孤儿进程。agent 的本地端口
+端口上已有本代理时复用它；被其他程序占用则报错退出，不会把 agent 指向非代理端口。
+子进程退出后代理跟着关，不留孤儿进程。agent 的本地端口
 （hook、LSP、语言服务器）走 `NO_PROXY` 直连，不会被代理吞掉。
 
 注入时会替换启动环境里的 socks `ALL_PROXY`：不少客户端会优先读它，留着就绕过了

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dual-proxy",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Local dual-path proxy for CLI agents: auto-selects a gateway that reaches the model endpoint, verifies the channel, fails over to direct",
   "license": "MIT",
   "type": "module",
@@ -27,11 +27,8 @@
     "test": "node --test test/*.test.js",
     "start": "node bin/dual-proxy.js"
   },
-  "dependencies": {
-    "undici": "8.12.3"
-  },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.0.0"
   },
   "files": [
     "bin",

package/src/engines.js

@@ -1,5 +1,5 @@
-/** Node 版本门槛：undici 8 要求 >= 22.19.0。 */
-export const MIN_NODE = '22.19.0';
+/** Node 版本门槛：只用到内置 http/net/tls，跟随当前维护中的 LTS 主版本。 */
+export const MIN_NODE = '22.0.0';
 
 function parts(version) {
   return String(version)
@@ -17,7 +17,7 @@ export function nodeAtLeast(version, min = MIN_NODE) {
   return c >= z;
 }
 
-/** 低于门槛时抛出可读错误，避免在 undici 里报出看不懂的运行期错误。 */
+/** 低于门槛时抛出可读错误，避免在运行期报出看不懂的语法/API 错误。 */
 export function assertNode(version = process.versions.node) {
   if (!nodeAtLeast(version)) {
     throw new Error('agent-dual-proxy requires Node >= ' + MIN_NODE + ' (current ' + version + ')');

package/src/server.js

@@ -6,6 +6,10 @@ import { hasIdempotencyKey, isIdempotent, shouldRetryAfterSend } from './retry-p
 
 const DEFAULT_LOG = (msg) => process.stderr.write('[dual-proxy] ' + msg + '\n');
 
+/** 本地身份端点：端口复用前用来确认监听者确实是本代理。 */
+export const IDENTITY_PATH = '/__agent_dual_proxy__';
+export const IDENTITY_HEADER = 'x-agent-dual-proxy';
+
 /** 合并配置：显式传入的 undefined 不应覆盖默认值。 */
 export function mergeOptions(defaults, options) {
   const merged = Object.assign({}, defaults);
@@ -224,6 +228,11 @@ export function createDispatcher(options) {
   };
 
   const server = http.createServer((req, res) => {
+    if (req.method === 'GET' && req.url === IDENTITY_PATH) {
+      res.writeHead(200, { 'content-type': 'text/plain', [IDENTITY_HEADER]: '1' });
+      res.end('agent-dual-proxy\n');
+      return;
+    }
     let target;
     try {
       target = new URL(req.url);