u1s1-cli 1.14.5 → 1.15.0

package/dist/config.js

@@ -259,8 +259,11 @@ export function findModel(query) {
     }
     return undefined;
 }
+export function isDefaultAgent(value) {
+    return value === "pi" || value === "claude" || value === "codex";
+}
 export const u1s1Dir = join(homedir(), ".u1s1");
-const configFile = join(u1s1Dir, "config.json");
+export const configFile = join(u1s1Dir, "config.json");
 /** pi keeps auth/models/settings/sessions under this dir — isolated from any real pi install. */
 export const agentDir = join(u1s1Dir, "agent");
 export const agentSettingsFile = join(agentDir, "settings.json");
@@ -368,6 +371,7 @@ export function configFromFile(file, env = process.env, currentCnApiBase = SITES
         model: file.model,
         modelProvider: typeof file.modelProvider === "string" ? file.modelProvider : undefined,
         email: typeof file.email === "string" && file.email ? file.email : undefined,
+        ...(isDefaultAgent(file.defaultAgent) ? { defaultAgent: file.defaultAgent } : {}),
     };
 }
 /**
@@ -442,6 +446,36 @@ export function saveConfig(cfg) {
     resetLang();
 }
 /** Persist the user's preferred model to both stores. */
+/**
+ * 只改 config.json 里的 defaultAgent 一个键,其余原样保留(还没登录、文件不存在时也能写)。
+ * 不经 saveConfig:那会把默认 baseUrl 等生效值一并写死进文件。
+ */
+export function saveDefaultAgent(agent) {
+    updateRawConfigFile((file) => {
+        if (agent === undefined)
+            delete file["defaultAgent"];
+        else
+            file["defaultAgent"] = agent;
+    });
+}
+/**
+ * 只改 config.json 里 mutate 碰到的键,其余原样保留(不经 saveConfig,理由同 saveDefaultAgent)。
+ * 文件在但读不出来时不覆盖(里面可能有登录凭据),抛错让用户先修好。
+ */
+export function updateRawConfigFile(mutate) {
+    const raw = readJsonFile(configFile);
+    if (existsSync(configFile) && (!raw || typeof raw !== "object" || Array.isArray(raw))) {
+        throw new Error(tr(`${configFile} 格式不正确,没有改动它。`, `${configFile} is malformed; it was left unchanged.`));
+    }
+    const file = { ...raw };
+    mutate(file);
+    writePrivateFile(configFile, JSON.stringify(file, null, 2) + "\n");
+}
+/** config.json 的原始内容(不叠加环境变量);不存在或解析失败为 undefined。 */
+export function readRawConfigFile() {
+    const raw = readJsonFile(configFile);
+    return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : undefined;
+}
 export function persistPreferredModel(cfg, provider, modelId) {
     const next = { ...cfg, model: modelId, modelProvider: provider };
     saveConfig(next);

package/dist/device-auth.d.ts

@@ -1,6 +1,7 @@
 import { webcrypto } from "node:crypto";
 import { type IncomingMessage } from "node:http";
 import { type CliConfig } from "./config.js";
+import { type GatewayFetchFailure } from "./gateway-route.js";
 export declare function hasDeviceCredential(cfg: CliConfig): boolean;
 export declare function generateDeviceKeyPair(): Promise<{
     privateJwk: webcrypto.JsonWebKey;
@@ -49,31 +50,52 @@ interface SigningProxy {
     localKey: string;
     token: string;
     client: ClientSurface;
+    agent?: LaunchedAgent;
     attestation: AttestationHolder;
 }
-/** Attach a fresh (self-healing) attestation header to an outbound proxy request. */
-export declare function attachAttestationHeader(holder: AttestationHolder, headers: Headers): Promise<void>;
-export type ClientSurface = "terminal" | "web" | "desktop";
-/** What a failed gateway fetch looked like at the socket level; never carries request content. */
-export interface GatewayFetchFailure {
-    /** Node/undici error code such as ECONNRESET or UND_ERR_CONNECT_TIMEOUT; "unknown" when absent. */
-    code: string;
-    /** One-line message for the user and the retry classifier, e.g. "fetch failed (ECONNRESET: read ECONNRESET)". */
-    detail: string;
+/**
+ * Which client the launcher started behind this proxy. Sent as `x-u1s1-agent` /
+ * `x-u1s1-agent-version` so the Gateway knows which request shape to check
+ * (workers/gateway/src/launcher-agents.ts). The headers carry no authority of
+ * their own: the Gateway still requires the DPoP proof and a valid attestation.
+ */
+export interface LaunchedAgent {
+    name: "pi" | "claude-code" | "codex";
+    /** The client's own version (e.g. Claude Code `2.1.322`), not the CLI's. */
+    version?: string;
 }
+export declare const AGENT_HEADER = "x-u1s1-agent";
+export declare const AGENT_VERSION_HEADER = "x-u1s1-agent-version";
 /**
- * undici reports every transport failure as a bare "fetch failed" and puts the
- * real reason (reset, DNS, TLS, connect timeout) in `cause`, sometimes as an
- * AggregateError from happy eyeballs. Keep the original message first so the
- * agent's retry patterns still match.
+ * With a declared agent the proxy owns both headers: whatever the child sent is
+ * replaced (or dropped when no version is declared). Without one the request
+ * passes through exactly as before this option existed.
  */
-export declare function describeFetchFailure(error: unknown): GatewayFetchFailure;
-export declare function isConnectPhaseFailure(failure: GatewayFetchFailure): boolean;
+export declare function applyAgentHeaders(headers: Headers, agent: LaunchedAgent | undefined): void;
+/**
+ * Errors the proxy produces itself (wrong local token, path outside /v1, body too large) are final:
+ * retrying cannot fix them. Codex retries 401/403/413 like transient failures (five times) and then
+ * shows the raw JSON, so for a declared `codex` child they become 400 with `error.code:
+ * "invalid_prompt"`, which Codex reports once and displays as `error.message`. Other clients keep
+ * the original status codes.
+ */
+export declare function localFinalError(agent: LaunchedAgent | undefined, status: number, message: string): {
+    status: number;
+    body: {
+        error: {
+            message: string;
+            code?: string;
+        };
+    };
+};
+/** Attach a fresh (self-healing) attestation header to an outbound proxy request. */
+export declare function attachAttestationHeader(holder: AttestationHolder, headers: Headers): Promise<void>;
+export type ClientSurface = "terminal" | "web" | "desktop";
+export { describeFetchFailure, isConnectPhaseFailure, type GatewayFetchFailure } from "./gateway-route.js";
 /** One listener per process (telemetry); failures are reported only when the local caller is still waiting. */
 export declare function onGatewayFetchFailure(listener: ((failure: GatewayFetchFailure) => void) | undefined): void;
 /**
  * pi accepts static provider headers only. Keep it behind a loopback proxy that
  * replaces the local bearer credential with a fresh DPoP proof per request.
  */
-export declare function ensureSigningProxy(cfg: CliConfig, fallbackClient?: ClientSurface, attestationSource?: ClientAttestationSource): Promise<SigningProxy>;
-export {};
+export declare function ensureSigningProxy(cfg: CliConfig, fallbackClient?: ClientSurface, attestationSource?: ClientAttestationSource, agent?: LaunchedAgent): Promise<SigningProxy>;

package/dist/device-auth.js

@@ -2,7 +2,7 @@ import { createHash, randomBytes, randomUUID, webcrypto } from "node:crypto";
 import { createServer } from "node:http";
 import { VERSION } from "./config.js";
 import { tr } from "./i18n.js";
-import { edgeFallbackOrigin } from "./site.js";
+import { describeFetchFailure, gatewayFetch, plainGatewaySender } from "./gateway-route.js";
 const enc = new TextEncoder();
 const SIGNING_PROXY_REQUEST_LIMIT_BYTES = 32 * 1024 * 1024;
 let cachedPrivate;
@@ -67,20 +67,22 @@ export async function dpopHeaders(cfg, method, url) {
 }
 /** Fetch a gateway route with a fresh proof; generic keys remain a read-only compatibility fallback. */
 export async function authorizedFetch(cfg, input, init = {}) {
-    const url = String(input);
-    const headers = new Headers(init.headers);
-    if (hasDeviceCredential(cfg)) {
-        const signed = await dpopHeaders(cfg, init.method ?? "GET", url);
-        for (const [name, value] of Object.entries(signed))
-            headers.set(name, value);
-    }
-    else if (cfg.apiKey) {
-        headers.set("authorization", `Bearer ${cfg.apiKey}`);
-    }
-    else {
+    if (!hasDeviceCredential(cfg) && !cfg.apiKey) {
         throw new Error(tr("还没有登录，请运行 u1s1 login", "Not signed in. Run u1s1 login."));
     }
-    return fetch(url, { ...init, headers });
+    // 中国站主域建连失败时会换到大陆加速入口重发(gateway-route.ts);DPoP 绑定 URL,每次按实际 URL 重签
+    return gatewayFetch(input, init, async (url, attemptInit, attempt) => {
+        const headers = new Headers(attemptInit.headers);
+        if (hasDeviceCredential(cfg)) {
+            const signed = await dpopHeaders(cfg, attemptInit.method ?? "GET", url);
+            for (const [name, value] of Object.entries(signed))
+                headers.set(name, value);
+        }
+        else {
+            headers.set("authorization", `Bearer ${cfg.apiKey}`);
+        }
+        return plainGatewaySender(url, { ...attemptInit, headers }, attempt);
+    });
 }
 /**
  * Headers to replay on the loopback response. fetch() has already decoded the
@@ -128,6 +130,37 @@ export async function readSigningProxyRequestBody(request, maxBytes = SIGNING_PR
     }
     return chunks.length ? Buffer.concat(chunks, total) : undefined;
 }
+export const AGENT_HEADER = "x-u1s1-agent";
+export const AGENT_VERSION_HEADER = "x-u1s1-agent-version";
+function sameAgent(a, b) {
+    return a?.name === b?.name && a?.version === b?.version;
+}
+/**
+ * With a declared agent the proxy owns both headers: whatever the child sent is
+ * replaced (or dropped when no version is declared). Without one the request
+ * passes through exactly as before this option existed.
+ */
+export function applyAgentHeaders(headers, agent) {
+    if (!agent)
+        return;
+    headers.set(AGENT_HEADER, agent.name);
+    if (agent.version)
+        headers.set(AGENT_VERSION_HEADER, agent.version);
+    else
+        headers.delete(AGENT_VERSION_HEADER);
+}
+/**
+ * Errors the proxy produces itself (wrong local token, path outside /v1, body too large) are final:
+ * retrying cannot fix them. Codex retries 401/403/413 like transient failures (five times) and then
+ * shows the raw JSON, so for a declared `codex` child they become 400 with `error.code:
+ * "invalid_prompt"`, which Codex reports once and displays as `error.message`. Other clients keep
+ * the original status codes.
+ */
+export function localFinalError(agent, status, message) {
+    if (agent?.name === "codex")
+        return { status: 400, body: { error: { message, code: "invalid_prompt" } } };
+    return { status, body: { error: { message } } };
+}
 // Refresh once we are within a day of the server-side 7-day expiry; back off for
 // a while after a failed refresh so a flaky Gateway is not hammered per request.
 const ATTESTATION_REFRESH_MARGIN_MS = 24 * 60 * 60 * 1000;
@@ -210,41 +243,7 @@ function clientSurface(fallback) {
     }
     return process.versions.electron ? "desktop" : fallback;
 }
-/**
- * undici reports every transport failure as a bare "fetch failed" and puts the
- * real reason (reset, DNS, TLS, connect timeout) in `cause`, sometimes as an
- * AggregateError from happy eyeballs. Keep the original message first so the
- * agent's retry patterns still match.
- */
-export function describeFetchFailure(error) {
-    const message = error instanceof Error ? error.message : "signing proxy failed";
-    let cause = error instanceof Error ? error.cause : undefined;
-    if (cause instanceof AggregateError && cause.errors.length)
-        cause = cause.errors[0];
-    const causeRecord = typeof cause === "object" && cause !== null ? cause : {};
-    const code = typeof causeRecord.code === "string" && causeRecord.code
-        ? causeRecord.code
-        : typeof error?.code === "string"
-            ? error.code
-            : "unknown";
-    const causeMessage = typeof causeRecord.message === "string" ? causeRecord.message.split("\n")[0].slice(0, 200) : "";
-    if (!causeMessage && code === "unknown")
-        return { code, detail: message };
-    const reason = causeMessage && !causeMessage.includes(code) && code !== "unknown"
-        ? `${code}: ${causeMessage}`
-        : causeMessage || code;
-    return { code, detail: `${message} (${reason})` };
-}
-/**
- * 只认建连阶段的失败(请求还没发出去,换个入口重发不会重复扣费)。ECONNRESET / 读超时这类
- * 可能发生在请求已送达之后,不重试,照旧报给用户。
- */
-const CONNECT_PHASE_CODES = new Set([
-    "ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ENETUNREACH", "EHOSTUNREACH", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT",
-]);
-export function isConnectPhaseFailure(failure) {
-    return CONNECT_PHASE_CODES.has(failure.code);
-}
+export { describeFetchFailure, isConnectPhaseFailure } from "./gateway-route.js";
 let gatewayFetchFailureListener;
 /** One listener per process (telemetry); failures are reported only when the local caller is still waiting. */
 export function onGatewayFetchFailure(listener) {
@@ -254,12 +253,12 @@ export function onGatewayFetchFailure(listener) {
  * pi accepts static provider headers only. Keep it behind a loopback proxy that
  * replaces the local bearer credential with a fresh DPoP proof per request.
  */
-export async function ensureSigningProxy(cfg, fallbackClient = "terminal", attestationSource) {
+export async function ensureSigningProxy(cfg, fallbackClient = "terminal", attestationSource, agent) {
     if (!hasDeviceCredential(cfg))
         throw new Error(tr("当前安装需要重新登录，以创建设备凭证", "Please sign in again to create a device credential for this install."));
     const client = clientSurface(fallbackClient);
     const current = signingProxy;
-    if (current && current.token === cfg.deviceToken && current.client === client) {
+    if (current && current.token === cfg.deviceToken && current.client === client && sameAgent(current.agent, agent)) {
         updateAttestationHolder(current.attestation, attestationSource);
         return current;
     }
@@ -267,22 +266,22 @@ export async function ensureSigningProxy(cfg, fallbackClient = "terminal", attes
     updateAttestationHolder(attestation, attestationSource);
     const localKey = `local-${randomBytes(32).toString("hex")}`;
     const upstreamOrigin = new URL(cfg.baseUrl).origin;
-    // 中国站主域建连失败时换到大陆加速入口重试一次,本进程之后都走它(site.ts edgeFallbackOrigin)
-    const fallbackOrigin = edgeFallbackOrigin(upstreamOrigin);
-    let activeOrigin = upstreamOrigin;
+    const localError = (res, status, message) => {
+        const final = localFinalError(agent, status, message);
+        res.writeHead(final.status, { "content-type": "application/json" });
+        res.end(JSON.stringify(final.body));
+    };
     const server = createServer(async (req, res) => {
         try {
             if (req.headers.authorization !== `Bearer ${localKey}` || !req.url) {
-                res.writeHead(401, { "content-type": "application/json" });
-                res.end(JSON.stringify({ error: { message: "local signing proxy authentication failed" } }));
+                localError(res, 401, "local signing proxy authentication failed");
                 return;
             }
             // Only proxy the gateway namespace. Absolute-form request targets must not
             // be allowed to override the configured upstream origin and steal a proof.
             const localUrl = new URL(req.url, "http://127.0.0.1");
             if (!localUrl.pathname.startsWith("/v1/")) {
-                res.writeHead(403, { "content-type": "application/json" });
-                res.end(JSON.stringify({ error: { message: "signing proxy only serves /v1/*" } }));
+                localError(res, 403, "signing proxy only serves /v1/*");
                 return;
             }
             const upstreamAbort = new AbortController();
@@ -301,25 +300,15 @@ export async function ensureSigningProxy(cfg, fallbackClient = "terminal", attes
                 outboundHeaders.set("x-u1s1-client", client);
                 outboundHeaders.set("x-u1s1-version", VERSION);
                 outboundHeaders.set("x-u1s1-platform", `${process.platform}-${process.arch}`);
+                applyAgentHeaders(outboundHeaders, agent);
                 await attachAttestationHeader(attestation, outboundHeaders);
-                const send = (origin) => authorizedFetch(cfg, new URL(pathAndQuery, origin).toString(), {
+                // 中国站主域建连失败时 authorizedFetch 会换到大陆加速入口,和启动时的请求共用选路状态
+                const upstream = await authorizedFetch(cfg, new URL(pathAndQuery, upstreamOrigin).toString(), {
                     method: req.method ?? "GET",
                     headers: outboundHeaders,
                     body,
                     signal: upstreamAbort.signal,
                 });
-                const origin = activeOrigin;
-                let upstream;
-                try {
-                    upstream = await send(origin);
-                }
-                catch (error) {
-                    if (!fallbackOrigin || origin === fallbackOrigin || upstreamAbort.signal.aborted
-                        || !isConnectPhaseFailure(describeFetchFailure(error)))
-                        throw error;
-                    upstream = await send(fallbackOrigin);
-                    activeOrigin = fallbackOrigin;
-                }
                 res.writeHead(upstream.status, forwardedResponseHeaders(upstream.headers));
                 if (upstream.body) {
                     for await (const chunk of upstream.body)
@@ -334,8 +323,7 @@ export async function ensureSigningProxy(cfg, fallbackClient = "terminal", attes
         catch (error) {
             if (error instanceof SigningProxyRequestTooLargeError && !res.destroyed) {
                 req.resume();
-                res.writeHead(413, { "content-type": "application/json" });
-                res.end(JSON.stringify({ error: { message: "local signing proxy request body is too large" } }));
+                localError(res, 413, "local signing proxy request body is too large");
                 return;
             }
             if (res.destroyed)
@@ -368,6 +356,7 @@ export async function ensureSigningProxy(cfg, fallbackClient = "terminal", attes
         localKey,
         token: cfg.deviceToken,
         client,
+        ...(agent ? { agent: { ...agent } } : {}),
         attestation,
     };
     return signingProxy;

package/dist/embed.d.ts

@@ -11,3 +11,16 @@ export { applyWebUiBranding } from "./webui-brand.js";
 export { DASHBOARD_URL } from "./brand.js";
 export { SITES, siteForBaseUrl, siteLinks, type Site, type SiteId, type SiteLinks } from "./site.js";
 export { hasNudge, markNudge, readNudges, type NudgeKey } from "./nudges.js";
+export { ensureAgentRuntime, RuntimeInstallError, RuntimePlanError, type DownloadInfo, type EnsureRuntimeOptions, type EnsuredRuntime, type InstallHooks, type RuntimeBrake, type SkippedRuntime, } from "./agents/runtime.js";
+export { agentLaunchEnv, claudeLaunchArgs, claudePaths, type ClaudeLaunchInput } from "./agents/claude.js";
+export { codexLaunchArgs, codexLaunchEnv, codexPaths, writeCodexConfig, type CodexLaunchInput, type CodexPaths, } from "./agents/codex.js";
+export { loadAgentConfig, loadPublicAgentRuntime, type AgentConfig, type AgentConfigResult, type PublicAgentRuntimeResult, } from "./agents/agent-config.js";
+export { bestInstallTarget, checkBrake, compareVersions, dailyUpdateCheck, downloadSize, fetchLatestVersion, fetchPackageMeta, findNpm, findOnPath, installedVersions, isManagedAgent, MANAGED_AGENTS, managedBinPath, NO_BRAKE, normalizeVersion, npmRegistryFor, planRuntime, platformPackageRef, probeVersion, readRuntimeState, runtimeSpec, type BrakeVerdict, type FoundRuntime, type ManagedAgent, type NpmCommand, type PackageMeta, type RuntimePlan, type RuntimeState, } from "./agents/runtime.js";
+export { AGENT_PROFILES, agentsRoot, CLAUDE_TERMS_URL, CODEX_LICENSE_URL, notOpenText, overMaxTestedText, runtimeErrorText, type LaunchPaths, } from "./agents/launch.js";
+export { launchPaths } from "./agents/status.js";
+export { parseAgentConfig, readConfigCache, type AgentModel, type GatewayAgentName } from "./agents/agent-config.js";
+export { chooseAgentModel, isModelId, readAgentPrefs, saveAgentPrefs, type AgentPrefs } from "./agents/prefs.js";
+export { CONFIG_KEYS, isConfigKey, readConfigValue, writeConfigValue, type ConfigKey, type ConfigValue, } from "./config-command.js";
+export { isDefaultAgent, readRawConfigFile, saveDefaultAgent, type DefaultAgent } from "./config.js";
+export { isExistingUser } from "./launcher.js";
+export { gatewayFetch } from "./gateway-route.js";

package/dist/embed.js

@@ -11,3 +11,18 @@ export { applyWebUiBranding } from "./webui-brand.js";
 export { DASHBOARD_URL } from "./brand.js";
 export { SITES, siteForBaseUrl, siteLinks } from "./site.js";
 export { hasNudge, markNudge, readNudges } from "./nudges.js";
+// 启动器:桌面端复用同一套运行时下载/更新/刹车与子进程注入逻辑
+export { ensureAgentRuntime, RuntimeInstallError, RuntimePlanError, } from "./agents/runtime.js";
+export { agentLaunchEnv, claudeLaunchArgs, claudePaths } from "./agents/claude.js";
+export { codexLaunchArgs, codexLaunchEnv, codexPaths, writeCodexConfig, } from "./agents/codex.js";
+export { loadAgentConfig, loadPublicAgentRuntime, } from "./agents/agent-config.js";
+// 启动器(桌面端服务层):状态、刹车、偏好与 `u1s1 config` 读写都走 CLI 的同一份实现
+export { bestInstallTarget, checkBrake, compareVersions, dailyUpdateCheck, downloadSize, fetchLatestVersion, fetchPackageMeta, findNpm, findOnPath, installedVersions, isManagedAgent, MANAGED_AGENTS, managedBinPath, NO_BRAKE, normalizeVersion, npmRegistryFor, planRuntime, platformPackageRef, probeVersion, readRuntimeState, runtimeSpec, } from "./agents/runtime.js";
+export { AGENT_PROFILES, agentsRoot, CLAUDE_TERMS_URL, CODEX_LICENSE_URL, notOpenText, overMaxTestedText, runtimeErrorText, } from "./agents/launch.js";
+export { launchPaths } from "./agents/status.js";
+export { parseAgentConfig, readConfigCache } from "./agents/agent-config.js";
+export { chooseAgentModel, isModelId, readAgentPrefs, saveAgentPrefs } from "./agents/prefs.js";
+export { CONFIG_KEYS, isConfigKey, readConfigValue, writeConfigValue, } from "./config-command.js";
+export { isDefaultAgent, readRawConfigFile, saveDefaultAgent } from "./config.js";
+export { isExistingUser } from "./launcher.js";
+export { gatewayFetch } from "./gateway-route.js";

package/dist/gateway-route.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 中国站网关的「主域 ↔ 大陆加速入口」选路,整个进程共用一份状态。
+ *
+ * 国内有些网络连不上 api 主域(DNS 污染、黑洞、拒连),但能连 api-cn 加速入口(同一个网关)。
+ * 规则(沿用 1.14.5 签名代理的原则):
+ * - 只在建连阶段失败时换入口重发:那时请求还没发出去,重发不会重复扣费。请求已发出后的失败
+ *   (ECONNRESET、读超时、调用方超时/取消)一律照旧报错,不重发。
+ * - 本进程还没确认哪个入口能用时,主域用较短的建连超时(PRIMARY_CONNECT_TIMEOUT_MS)试一次,
+ *   不再等全局 30 秒;换过去成功的入口记住,之后的请求(模型列表、账户、签名代理……)直接走它。
+ * - 两个入口都建连失败时,用正常超时再连一次主域(海外用户解析不到 api-cn,主域只是慢)。
+ * - 只对中国站官方 API 域名生效;国际站和自定义地址原样直连。
+ */
+/** 一次请求失败在传输层长什么样;绝不带请求内容。 */
+export interface GatewayFetchFailure {
+    /** Node/undici error code such as ECONNRESET or UND_ERR_CONNECT_TIMEOUT; "unknown" when absent. */
+    code: string;
+    /** One-line message for the user and the retry classifier, e.g. "fetch failed (ECONNRESET: read ECONNRESET)". */
+    detail: string;
+}
+/**
+ * undici reports every transport failure as a bare "fetch failed" and puts the
+ * real reason (reset, DNS, TLS, connect timeout) in `cause`, sometimes as an
+ * AggregateError from happy eyeballs. Keep the original message first so the
+ * agent's retry patterns still match.
+ */
+export declare function describeFetchFailure(error: unknown): GatewayFetchFailure;
+export declare function isConnectPhaseFailure(failure: GatewayFetchFailure): boolean;
+/**
+ * 还没确认入口时,直连主域的建连超时(含 DNS + TCP + TLS)。
+ * 取舍:正常线路握手 1–2 秒;IPv6 不通时 happy eyeballs 要先耗 2 秒再换 IPv4,6 秒留足余量。
+ * 更慢的丢包线路(1.14.4 为它把全局建连超时放宽到 30 秒)会改走加速入口,本来也更快;
+ * 加速入口也连不上时仍会用全局超时再连一次主域,所以只是慢,不会因此连不上。
+ */
+export declare const PRIMARY_CONNECT_TIMEOUT_MS = 6000;
+export interface GatewayAttempt {
+    /** 只在「还没确认入口、先试主域」那一次给出;发送方要用它代替全局 dispatcher。 */
+    connectTimeoutMs?: number;
+}
+/** 真正发一次请求。签名请求要按每次的 URL 重新签 DPoP,所以由调用方提供。 */
+export type GatewaySender = (url: string, init: RequestInit, attempt: GatewayAttempt) => Promise<Response>;
+type Route = "primary" | "edge";
+/** 本进程对这个 origin 已经确认走的入口(测试和诊断用)。 */
+export declare function gatewayRouteFor(origin: string): Route | undefined;
+/** 测试用:清空选路状态,可换一套「主域 → 备用入口」映射(本地起假服务端)和更短的建连超时。 */
+export declare function resetGatewayRoutesForTests(resolver?: (origin: string) => string | null, connectTimeoutMs?: number): void;
+/**
+ * 默认发送方。短建连超时要靠自带的 undici dispatcher,而 dispatcher 必须交给同一份 undici 的 fetch
+ * (Node 自带 fetch 混用会出解压问题,见 pi 的 http-dispatcher.js)。CLI 启动时 pi 已把全局 fetch
+ * 换成这份 undici;没换(或被测试替换)时就用全局 fetch 的默认建连超时,选路规则不变。
+ */
+export declare const plainGatewaySender: GatewaySender;
+/**
+ * 发一个网关请求;是中国站官方 API 域名时按上面的规则在主域和加速入口之间选路。
+ * 请求体必须可重放(string / Buffer / undefined),流式 body 不要走这里的回退。
+ */
+export declare function gatewayFetch(input: string | URL, init?: RequestInit, send?: GatewaySender): Promise<Response>;
+export {};

package/dist/gateway-route.js

@@ -0,0 +1,157 @@
+import { EnvHttpProxyAgent, fetch as undiciFetch } from "undici";
+import { edgeFallbackOrigin } from "./site.js";
+/**
+ * undici reports every transport failure as a bare "fetch failed" and puts the
+ * real reason (reset, DNS, TLS, connect timeout) in `cause`, sometimes as an
+ * AggregateError from happy eyeballs. Keep the original message first so the
+ * agent's retry patterns still match.
+ */
+export function describeFetchFailure(error) {
+    const message = error instanceof Error ? error.message : "signing proxy failed";
+    let cause = error instanceof Error ? error.cause : undefined;
+    if (cause instanceof AggregateError && cause.errors.length)
+        cause = cause.errors[0];
+    const causeRecord = typeof cause === "object" && cause !== null ? cause : {};
+    const code = typeof causeRecord.code === "string" && causeRecord.code
+        ? causeRecord.code
+        : typeof error?.code === "string"
+            ? error.code
+            : "unknown";
+    const causeMessage = typeof causeRecord.message === "string" ? causeRecord.message.split("\n")[0].slice(0, 200) : "";
+    if (!causeMessage && code === "unknown")
+        return { code, detail: message };
+    const reason = causeMessage && !causeMessage.includes(code) && code !== "unknown"
+        ? `${code}: ${causeMessage}`
+        : causeMessage || code;
+    return { code, detail: `${message} (${reason})` };
+}
+/**
+ * 只认建连阶段的失败(请求还没发出去,换个入口重发不会重复扣费)。ECONNRESET / 读超时这类
+ * 可能发生在请求已送达之后,不重试,照旧报给用户。
+ */
+const CONNECT_PHASE_CODES = new Set([
+    "ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ENETUNREACH", "EHOSTUNREACH", "ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT",
+]);
+/** Node 在 TLS 握手完成前断开时的固定文案:此时一个 HTTP 字节都还没发,和拒连一样安全。 */
+const TLS_HANDSHAKE_RESET = "before secure TLS connection was established";
+export function isConnectPhaseFailure(failure) {
+    if (CONNECT_PHASE_CODES.has(failure.code))
+        return true;
+    return failure.code === "ECONNRESET" && failure.detail.includes(TLS_HANDSHAKE_RESET);
+}
+/**
+ * 还没确认入口时,直连主域的建连超时(含 DNS + TCP + TLS)。
+ * 取舍:正常线路握手 1–2 秒;IPv6 不通时 happy eyeballs 要先耗 2 秒再换 IPv4,6 秒留足余量。
+ * 更慢的丢包线路(1.14.4 为它把全局建连超时放宽到 30 秒)会改走加速入口,本来也更快;
+ * 加速入口也连不上时仍会用全局超时再连一次主域,所以只是慢,不会因此连不上。
+ */
+export const PRIMARY_CONNECT_TIMEOUT_MS = 6_000;
+/** key 是主域 origin;没有记录 = 本进程还没确认哪个入口能用。 */
+const routes = new Map();
+let fallbackResolver = edgeFallbackOrigin;
+/** 本进程对这个 origin 已经确认走的入口(测试和诊断用)。 */
+export function gatewayRouteFor(origin) {
+    return routes.get(origin);
+}
+let primaryConnectTimeoutMs = PRIMARY_CONNECT_TIMEOUT_MS;
+/** 测试用:清空选路状态,可换一套「主域 → 备用入口」映射(本地起假服务端)和更短的建连超时。 */
+export function resetGatewayRoutesForTests(resolver = edgeFallbackOrigin, connectTimeoutMs = PRIMARY_CONNECT_TIMEOUT_MS) {
+    routes.clear();
+    fallbackResolver = resolver;
+    primaryConnectTimeoutMs = connectTimeoutMs;
+}
+const shortConnectDispatchers = new Map();
+function shortConnectDispatcher(timeoutMs) {
+    let dispatcher = shortConnectDispatchers.get(timeoutMs);
+    if (dispatcher === undefined) {
+        try {
+            // 与 pi 的全局 dispatcher 同款(同样认 HTTP(S)_PROXY / NO_PROXY),只是建连超时更短
+            dispatcher = new EnvHttpProxyAgent({
+                allowH2: false,
+                proxyTunnel: true,
+                connect: { timeout: timeoutMs, autoSelectFamilyAttemptTimeout: 2_000 },
+            });
+        }
+        catch {
+            dispatcher = null;
+        }
+        shortConnectDispatchers.set(timeoutMs, dispatcher);
+    }
+    return dispatcher;
+}
+/**
+ * 默认发送方。短建连超时要靠自带的 undici dispatcher,而 dispatcher 必须交给同一份 undici 的 fetch
+ * (Node 自带 fetch 混用会出解压问题,见 pi 的 http-dispatcher.js)。CLI 启动时 pi 已把全局 fetch
+ * 换成这份 undici;没换(或被测试替换)时就用全局 fetch 的默认建连超时,选路规则不变。
+ */
+export const plainGatewaySender = (url, init, attempt) => {
+    const dispatcher = attempt.connectTimeoutMs && globalThis.fetch === undiciFetch
+        ? shortConnectDispatcher(attempt.connectTimeoutMs)
+        : null;
+    if (!dispatcher)
+        return fetch(url, init);
+    return undiciFetch(url, { ...init, dispatcher });
+};
+function withOrigin(url, origin) {
+    return new URL(`${url.pathname}${url.search}`, origin).toString();
+}
+function retryableAtConnect(error, init) {
+    if (init.signal?.aborted)
+        return false;
+    return isConnectPhaseFailure(describeFetchFailure(error));
+}
+/**
+ * 发一个网关请求;是中国站官方 API 域名时按上面的规则在主域和加速入口之间选路。
+ * 请求体必须可重放(string / Buffer / undefined),流式 body 不要走这里的回退。
+ */
+export async function gatewayFetch(input, init = {}, send = plainGatewaySender) {
+    const url = new URL(String(input));
+    const primary = url.origin;
+    const edge = fallbackResolver(primary);
+    if (!edge)
+        return send(url.toString(), init, {});
+    const primaryUrl = withOrigin(url, primary);
+    const edgeUrl = withOrigin(url, edge);
+    const route = routes.get(primary);
+    if (route === "edge") {
+        try {
+            return await send(edgeUrl, init, {});
+        }
+        catch (error) {
+            if (!retryableAtConnect(error, init))
+                throw error;
+            const resp = await send(primaryUrl, init, {});
+            routes.set(primary, "primary");
+            return resp;
+        }
+    }
+    // 已确认主域能用:正常超时直连;只有这次建连又失败了才去试加速入口
+    const firstAttempt = route === "primary" ? {} : { connectTimeoutMs: primaryConnectTimeoutMs };
+    let firstError;
+    try {
+        const resp = await send(primaryUrl, init, firstAttempt);
+        routes.set(primary, "primary");
+        return resp;
+    }
+    catch (error) {
+        if (!retryableAtConnect(error, init))
+            throw error;
+        firstError = error;
+    }
+    try {
+        const resp = await send(edgeUrl, init, {});
+        routes.set(primary, "edge");
+        return resp;
+    }
+    catch (error) {
+        if (!retryableAtConnect(error, init))
+            throw error;
+    }
+    // 两个入口都没连上:第一次用的是短超时时,再按全局超时给主域一次机会(海外慢线路)
+    if (firstAttempt.connectTimeoutMs) {
+        const resp = await send(primaryUrl, init, {});
+        routes.set(primary, "primary");
+        return resp;
+    }
+    throw firstError;
+}