u1s1-cli 1.14.6 → 1.15.1

package/dist/agents/runtime.js

@@ -0,0 +1,884 @@
+/**
+ * 第三方客户端运行时:查找、下载、版本、更新、刹车。
+ *
+ * 合规约束(规划第 6 节):原版只从官方 npm 包下载、装到 ~/.u1s1/agents/<客户端>,
+ * 用户确认后才下载;不打进我们的包、不改二进制、不动它自带的登录方式。
+ * 安装交给 npm(`npm install --prefix`),上游调整包结构(平台二进制、postinstall)由 npm 处理。
+ *
+ * 目录布局(以 claude 为例;codex 同理,可执行文件在平台包里,见 CODEX_RUNTIME):
+ *   ~/.u1s1/agents/claude/runtime/<版本>/node_modules/@anthropic-ai/claude-code/bin/claude.exe
+ *   ~/.u1s1/agents/claude/state.json     当前版本、pin、每日检查时间、待更新版本
+ *   ~/.u1s1/agents/claude/config/        CLAUDE_CONFIG_DIR(见 claude.ts;codex 是 home/,见 codex.ts)
+ *
+ * 刹车(网关 /v1/agents/:agent/config 的 runtime 字段):
+ *   - blocked_versions:不装、不用;
+ *   - min_version:低于它必须先升级;
+ *   - max_tested_version:自动更新、pin 都不越过它;启动时已装的版本高于它也要换下来——
+ *     u1s1 自己装的换成不超过它的最新版,用户自带的(PATH、U1S1_CLAUDE_BIN / U1S1_CODEX_BIN)不动,
+ *     另装一份不超限的来用。null = 不设上限。
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { stripSecretEnv } from "../secret-env.js";
+const VERSION_RE = /^v?(\d{1,9})\.(\d{1,9})\.(\d{1,9})(?:-([0-9A-Za-z.-]{1,64}))?$/;
+export function parseVersion(value) {
+    const m = typeof value === "string" ? VERSION_RE.exec(value.trim()) : null;
+    if (!m)
+        return undefined;
+    return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] };
+}
+export function isVersion(value) {
+    return typeof value === "string" && parseVersion(value) !== undefined;
+}
+/** 规范化:去掉前导 v、首尾空白;不是版本号返回 undefined。 */
+export function normalizeVersion(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const p = parseVersion(value);
+    return p ? `${p.nums.join(".")}${p.pre ? `-${p.pre}` : ""}` : undefined;
+}
+/** semver 比较(预发布段按标识符逐段比,数字段小于字母段;够用,不处理 build metadata)。 */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa || !pb)
+        throw new Error(`invalid version: ${!pa ? a : b}`);
+    for (let i = 0; i < 3; i++) {
+        const d = pa.nums[i] - pb.nums[i];
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    if (!pa.pre)
+        return 1;
+    if (!pb.pre)
+        return -1;
+    const sa = pa.pre.split(".");
+    const sb = pb.pre.split(".");
+    for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+        const x = sa[i];
+        const y = sb[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const nx = /^\d+$/.test(x);
+        const ny = /^\d+$/.test(y);
+        if (nx && ny) {
+            const d = Number(x) - Number(y);
+            if (d !== 0)
+                return d < 0 ? -1 : 1;
+        }
+        else if (nx !== ny) {
+            return nx ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/** `claude --version` 之类的输出 → 版本号(取第一个形如 x.y.z 的片段)。 */
+export function versionFromOutput(output) {
+    const m = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(output);
+    return m ? normalizeVersion(m[1]) : undefined;
+}
+export const NO_BRAKE = { blockedVersions: [] };
+/** 网关 runtime 字段 → RuntimeBrake;非法值按「没设」处理(blocked 里的非法项丢弃)。 */
+export function brakeFromApi(runtime) {
+    const r = (runtime && typeof runtime === "object" ? runtime : {});
+    const blocked = Array.isArray(r["blocked_versions"])
+        ? r["blocked_versions"].map(normalizeVersion).filter((v) => !!v)
+        : [];
+    return {
+        minVersion: normalizeVersion(r["min_version"]),
+        maxTestedVersion: normalizeVersion(r["max_tested_version"]),
+        blockedVersions: [...new Set(blocked)],
+    };
+}
+/**
+ * 安装与运行用同一套规则:blocked 不装不用、低于 min 不装不用、高于 max_tested 不装不用。
+ * 后台把 max_tested 调低,已装的更高版本下次启动时就会被换下来(见 planRuntime)。
+ */
+export function checkBrake(version, brake) {
+    if (brake.blockedVersions.some((b) => compareVersions(b, version) === 0))
+        return "blocked";
+    if (brake.minVersion && compareVersions(version, brake.minVersion) < 0)
+        return "below_min";
+    if (brake.maxTestedVersion && compareVersions(version, brake.maxTestedVersion) > 0)
+        return "above_max_tested";
+    return "ok";
+}
+export const allowedByBrake = (v, brake) => checkBrake(v, brake) === "ok";
+/**
+ * 自动更新 / 首次安装的目标:候选(官方 latest、网关的 max_tested 等)里刹车允许安装的最高版本。
+ * latest 超过 max_tested 时自然退到 max_tested(它是测过的版本,必然已发布)。
+ */
+export function bestInstallTarget(candidates, brake) {
+    let best;
+    for (const c of candidates) {
+        const v = normalizeVersion(c);
+        if (!v || !allowedByBrake(v, brake))
+            continue;
+        if (!best || compareVersions(v, best) > 0)
+            best = v;
+    }
+    return best;
+}
+export const MANAGED_AGENTS = ["claude", "codex"];
+export function isManagedAgent(value) {
+    return value === "claude" || value === "codex";
+}
+function npmOs(platform) {
+    return platform === "win32" ? "win32" : platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : undefined;
+}
+/**
+ * 官方包的 bin 就是 `bin/claude.exe`(各平台同名):postinstall 把对应平台的原生二进制
+ * 复制到这里。直接起这个文件,不经 node_modules/.bin 的 shell 包装(Windows 上是 .cmd)。
+ * 平台包名与官方 install.cjs 的 PLATFORMS 表一致。
+ */
+export const CLAUDE_RUNTIME = {
+    agent: "claude",
+    npmPackage: "@anthropic-ai/claude-code",
+    command: "claude",
+    binEnv: "U1S1_CLAUDE_BIN",
+    configDirEnv: "CLAUDE_CONFIG_DIR",
+    probeEnv: { DISABLE_AUTOUPDATER: "1" },
+    platformPackage: (version, platform, arch, musl) => {
+        const os = npmOs(platform);
+        if (!os || (arch !== "x64" && arch !== "arm64"))
+            return undefined;
+        const dir = `@anthropic-ai/claude-code-${os}-${arch}${os === "linux" && musl ? "-musl" : ""}`;
+        return { dir, name: dir, version };
+    },
+    binInNodeModules: () => "@anthropic-ai/claude-code/bin/claude.exe",
+};
+/** Codex 官方 bin/codex.js 的 PLATFORM_PACKAGE_BY_TARGET 表(0.167.2 核对);Linux 都是 musl 静态链接。 */
+const CODEX_TRIPLES = {
+    "linux-x64": "x86_64-unknown-linux-musl",
+    "linux-arm64": "aarch64-unknown-linux-musl",
+    "darwin-x64": "x86_64-apple-darwin",
+    "darwin-arm64": "aarch64-apple-darwin",
+    "win32-x64": "x86_64-pc-windows-msvc",
+    "win32-arm64": "aarch64-pc-windows-msvc",
+};
+/**
+ * Codex:主包 `@openai/codex` 只有一个 JS 入口 `bin/codex.js`,平台二进制在 optionalDependencies 里,
+ * 以 npm 别名装进来(`@openai/codex-darwin-arm64` → `npm:@openai/codex@<版本>-darwin-arm64`)。
+ * 直接起平台包里的原生二进制,不经 codex.js(那层只是找二进制、设几个「由 npm 管理」的环境变量,
+ * 让它提示用 npm 升级;更新由启动器管,不需要)。原生二进制按自己所在目录找 rg 等附带文件。
+ */
+export const CODEX_RUNTIME = {
+    agent: "codex",
+    npmPackage: "@openai/codex",
+    command: "codex",
+    binEnv: "U1S1_CODEX_BIN",
+    configDirEnv: "CODEX_HOME",
+    probeEnv: {},
+    platformPackage: (version, platform, arch) => {
+        const os = npmOs(platform);
+        if (!os || !CODEX_TRIPLES[`${os}-${arch}`])
+            return undefined;
+        return { dir: `@openai/codex-${os}-${arch}`, name: "@openai/codex", version: `${version}-${os}-${arch}` };
+    },
+    binInNodeModules: (platform, arch) => {
+        const os = npmOs(platform);
+        const triple = os ? CODEX_TRIPLES[`${os}-${arch}`] : undefined;
+        if (!os || !triple)
+            return undefined;
+        return `@openai/codex-${os}-${arch}/vendor/${triple}/bin/${os === "win32" ? "codex.exe" : "codex"}`;
+    },
+};
+export function runtimeSpec(agent) {
+    if (agent === "claude")
+        return CLAUDE_RUNTIME;
+    if (agent === "codex")
+        return CODEX_RUNTIME;
+    throw new Error(`unknown agent runtime: ${String(agent)}`);
+}
+export function runtimePaths(agentsRoot, agent) {
+    const root = join(agentsRoot, agent);
+    return {
+        root,
+        runtimeDir: join(root, "runtime"),
+        stateFile: join(root, "state.json"),
+        npmCache: join(root, ".npm-cache"),
+    };
+}
+function join(...parts) {
+    return (process.platform === "win32" ? win32 : posix).join(...parts);
+}
+export function versionDir(paths, version) {
+    return join(paths.runtimeDir, version);
+}
+/** 可执行文件在某个 node_modules 根下的位置;不支持的平台给一个不会存在的路径(installedVersions 自然认不到)。 */
+function binUnder(root, spec) {
+    const rel = spec.binInNodeModules(process.platform, process.arch, isMusl());
+    return rel ? join(root, "node_modules", ...rel.split("/")) : join(root, ".unsupported-platform");
+}
+export function managedBinPath(paths, spec, version) {
+    return binUnder(versionDir(paths, version), spec);
+}
+export function readRuntimeState(paths) {
+    try {
+        const raw = JSON.parse(readFileSync(paths.stateFile, "utf8"));
+        return {
+            current: normalizeVersion(raw["current"]),
+            pinned: normalizeVersion(raw["pinned"]),
+            lastCheckAt: typeof raw["lastCheckAt"] === "number" && Number.isFinite(raw["lastCheckAt"]) ? raw["lastCheckAt"] : undefined,
+            latest: normalizeVersion(raw["latest"]),
+            pending: normalizeVersion(raw["pending"]),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function writeRuntimeState(paths, state) {
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    const tmp = `${paths.stateFile}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, paths.stateFile);
+}
+export function updateRuntimeState(paths, patch) {
+    const next = { ...readRuntimeState(paths), ...patch };
+    for (const key of Object.keys(next))
+        if (next[key] === undefined)
+            delete next[key];
+    writeRuntimeState(paths, next);
+    return next;
+}
+/** runtime/ 下已装好的版本(目录名是版本号、可执行文件存在),从新到旧。 */
+export function installedVersions(paths, spec, exists = existsSync) {
+    let names;
+    try {
+        names = readdirSync(paths.runtimeDir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((n) => isVersion(n) && normalizeVersion(n) === n && exists(managedBinPath(paths, spec, n)))
+        .sort((a, b) => compareVersions(b, a));
+}
+/**
+ * PATH 里找命令。Windows 只认 .exe:npm 全局装出来的 claude.cmd 要经 shell 才能起,
+ * 参数转义有坑(CVE-2024-27980 之后 Node 也不再直接 spawn .cmd),不值得冒险。
+ */
+export function findOnPath(command, opts) {
+    const exists = opts.exists ?? isFile;
+    const P = opts.platform === "win32" ? win32 : posix;
+    const pathValue = opts.env["PATH"] ?? opts.env["Path"] ?? "";
+    const names = opts.platform === "win32" ? [`${command}.exe`] : [command];
+    for (const dir of pathValue.split(opts.platform === "win32" ? ";" : ":")) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = P.join(dir, name);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 跑 `<bin> --version` 取版本。环境里去掉密钥、关掉自动更新;配置目录(CLAUDE_CONFIG_DIR /
+ * CODEX_HOME)指到启动器自己的目录,免得探测用户自己装的客户端时碰到用户的 ~/.claude、~/.codex。
+ */
+export function probeVersion(bin, configDir, spec = CLAUDE_RUNTIME) {
+    const env = stripSecretEnv(process.env);
+    for (const [key, value] of Object.entries(spec.probeEnv))
+        env[key] = value;
+    if (configDir)
+        env[spec.configDirEnv] = configDir;
+    else
+        delete env[spec.configDirEnv];
+    try {
+        const r = spawnSync(bin, ["--version"], { env, encoding: "utf8", timeout: 20_000, windowsHide: true });
+        if (r.status !== 0)
+            return undefined;
+        return versionFromOutput(`${r.stdout ?? ""}`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 查找顺序:环境变量 → ~/.u1s1/agents/<客户端>(pin 优先) → PATH 里已有的同名命令 → 下载。
+ * 只做决定、不做 I/O 副作用;所有探测都是惰性的,用不到的不跑。
+ *
+ * 高于 max_tested 的版本一律不用:u1s1 自己装的换成不超过上限的版本(装不上不退回,没有
+ * fallback);环境变量指定的和 PATH 里的不替用户动,接着往下找 / 另装一份,并在 skipped 里说明。
+ */
+export async function planRuntime(input) {
+    const { brake, state } = input;
+    const autoUpdate = input.autoUpdate !== false;
+    const skipped = [];
+    const skip = (runtime) => skipped.push({ ...runtime, maxTestedVersion: brake.maxTestedVersion });
+    const notes = () => (skipped.length ? { skipped: [...skipped] } : {});
+    // 1. 环境变量:显式指定就只用它,跑不起来、被拉黑或太旧都直接报错,不悄悄换别的;
+    //    只是高于 max_tested 时不动它,往下找一份不超限的
+    const env = input.envBin ? await input.envBin() : undefined;
+    if (env) {
+        if (!env.version)
+            return { action: "error", code: "env_bin_unusable", bin: env.bin };
+        const verdict = checkBrake(env.version, brake);
+        const runtime = { source: "env", bin: env.bin, version: env.version };
+        if (verdict === "ok")
+            return { action: "use", runtime };
+        if (verdict !== "above_max_tested")
+            return { action: "error", code: "env_bin_brake", verdict, bin: env.bin, version: env.version };
+        skip(runtime);
+    }
+    const current = await input.managed();
+    const currentVerdict = current ? checkBrake(current.version, brake) : "ok";
+    const currentUsable = currentVerdict === "ok" ? current : undefined;
+    const firstManaged = input.installed().length === 0;
+    // 2. pin:优先于自动更新,但不能越过刹车(越过就忽略 pin,走自动逻辑并提示)
+    let pinIgnored;
+    if (state.pinned) {
+        if (allowedByBrake(state.pinned, brake)) {
+            if (current && compareVersions(current.version, state.pinned) === 0)
+                return { action: "use", runtime: current, ...notes() };
+            return {
+                action: "install",
+                version: state.pinned,
+                reason: "pin",
+                fallback: currentUsable,
+                needsConsent: firstManaged,
+                ...notes(),
+            };
+        }
+        pinIgnored = state.pinned;
+    }
+    // 3. 托管的当前版本
+    if (current) {
+        if (currentVerdict === "ok") {
+            const pending = state.pending;
+            if (autoUpdate && pending && compareVersions(pending, current.version) > 0 && allowedByBrake(pending, brake)) {
+                return { action: "install", version: pending, reason: "update", fallback: current, needsConsent: false, pinIgnored, ...notes() };
+            }
+            return { action: "use", runtime: current, pinIgnored, ...notes() };
+        }
+        // 被拉黑、低于最低版本或高于已验证的最高版本:必须先换,没有退路;自动更新关着就让用户自己换
+        if (!autoUpdate) {
+            return { action: "error", code: "update_required", verdict: currentVerdict, bin: current.bin, version: current.version };
+        }
+        if (currentVerdict === "above_max_tested")
+            skip(current);
+        const target = bestInstallTarget([await input.latest(), brake.maxTestedVersion, state.pending], brake);
+        if (!target)
+            return { action: "error", code: "no_version" };
+        return {
+            action: "install",
+            version: target,
+            reason: currentVerdict,
+            needsConsent: false,
+            pinIgnored,
+            ...notes(),
+        };
+    }
+    // 4. 用户机器上已有的命令,版本过得了刹车就直接用(省一次几百 MB 的下载);
+    //    高于 max_tested 的不动它,另装一份
+    const found = await input.onPath();
+    if (found) {
+        const verdict = checkBrake(found.version, brake);
+        if (verdict === "ok")
+            return { action: "use", runtime: found, pinIgnored, ...notes() };
+        if (verdict === "above_max_tested")
+            skip(found);
+    }
+    // 5. 首次下载
+    const target = bestInstallTarget([await input.latest(), brake.maxTestedVersion], brake);
+    if (!target)
+        return { action: "error", code: "no_version" };
+    return { action: "install", version: target, reason: "first", needsConsent: firstManaged, pinIgnored, ...notes() };
+}
+/**
+ * npm 查找顺序:
+ *   1. 随运行本 CLI 的 Node 一起的 npm(官方 Node 发行包的布局):
+ *        Linux/macOS: <node 所在目录>/../lib/node_modules/npm/bin/npm-cli.js
+ *        Windows:     <node.exe 所在目录>/node_modules/npm/bin/npm-cli.js
+ *      便携包里 node 在 ~/.u1s1/node/bin/node(Windows ~/.u1s1/node/node.exe),所以打包时
+ *      npm 放到 ~/.u1s1/node/lib/node_modules/npm(Windows ~/.u1s1/node/node_modules/npm)。
+ *      用当前 Node(process.execPath)直接跑 npm-cli.js,不依赖 PATH、不经 shell。
+ *   2. PATH 里的 npm。Windows 上 npm.cmd 旁边的 node_modules/npm/bin/npm-cli.js,
+ *      同样用 node 直接跑(不 spawn .cmd)。
+ */
+export function findNpm(opts) {
+    const exists = opts.exists ?? isFile;
+    const P = opts.platform === "win32" ? win32 : posix;
+    const nodeDir = P.dirname(opts.execPath);
+    const bundled = opts.platform === "win32"
+        ? P.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js")
+        : P.join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+    if (exists(bundled))
+        return { command: opts.execPath, prefixArgs: [P.normalize(bundled)], source: "bundled" };
+    const pathValue = opts.env["PATH"] ?? opts.env["Path"] ?? "";
+    for (const dir of pathValue.split(opts.platform === "win32" ? ";" : ":")) {
+        if (!dir)
+            continue;
+        if (opts.platform === "win32") {
+            if (!exists(P.join(dir, "npm.cmd")))
+                continue;
+            const cli = P.join(dir, "node_modules", "npm", "bin", "npm-cli.js");
+            if (exists(cli))
+                return { command: opts.execPath, prefixArgs: [cli], source: "path" };
+        }
+        else {
+            const npm = P.join(dir, "npm");
+            if (exists(npm))
+                return { command: npm, prefixArgs: [], source: "path" };
+        }
+    }
+    return undefined;
+}
+/** 中国站走国内 npm 镜像(同一份包,带完整性校验);U1S1_NPM_REGISTRY 可覆盖。 */
+export function npmRegistryFor(site, env = process.env) {
+    const override = env["U1S1_NPM_REGISTRY"]?.trim();
+    if (override && /^https?:\/\//.test(override))
+        return override.replace(/\/+$/, "");
+    return site === "cn" ? "https://registry.npmmirror.com" : "https://registry.npmjs.org";
+}
+/** npm 的平台二进制子包在 node_modules 下的目录名。 */
+export function platformPackage(spec, platform = process.platform, arch = process.arch, musl = isMusl()) {
+    return spec.platformPackage("0.0.0", platform, arch, musl)?.dir;
+}
+/** 某个版本的平台二进制子包(目录名 + npm 源上的名字与版本)。 */
+export function platformPackageRef(spec, version, platform = process.platform, arch = process.arch, musl = isMusl()) {
+    return spec.platformPackage(version, platform, arch, musl);
+}
+function isMusl() {
+    if (process.platform !== "linux")
+        return false;
+    try {
+        const report = process.report?.getReport();
+        return !report?.header?.glibcVersionRuntime;
+    }
+    catch {
+        return false;
+    }
+}
+function registryUrl(registry, pkg, tag) {
+    return `${registry}/${pkg.replace("/", "%2f")}/${encodeURIComponent(tag)}`;
+}
+export async function fetchPackageMeta(registry, pkg, tag, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(registryUrl(registry, pkg, tag), {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return undefined;
+        const text = await res.text();
+        if (text.length > 2 * 1024 * 1024)
+            return undefined;
+        const body = JSON.parse(text);
+        const version = normalizeVersion(body.version);
+        if (!version)
+            return undefined;
+        const dist = body.dist ?? {};
+        return {
+            version,
+            integrity: typeof dist["integrity"] === "string" ? dist["integrity"] : undefined,
+            tarball: typeof dist["tarball"] === "string" ? dist["tarball"] : undefined,
+            unpackedSize: typeof dist["unpackedSize"] === "number" ? dist["unpackedSize"] : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function fetchLatestVersion(registry, pkg, fetchImpl = fetch) {
+    return (await fetchPackageMeta(registry, pkg, "latest", fetchImpl))?.version;
+}
+/**
+ * 压缩包大小。npm 源对 HEAD 不一定给 content-length(registry.npmjs.org 就不给),
+ * 用只取 1 字节的 Range 请求读 content-range 里的总长;国内镜像会 302 到 CDN,fetch 自动跟随。
+ */
+export async function downloadSize(url, fetchImpl = fetch) {
+    if (!url)
+        return undefined;
+    try {
+        const res = await fetchImpl(url, { headers: { Range: "bytes=0-0" }, signal: AbortSignal.timeout(8_000) });
+        const range = res.headers.get("content-range");
+        let n = range ? Number(/\/(\d+)\s*$/.exec(range)?.[1]) : Number.NaN;
+        if (!(n > 0) && res.status === 200)
+            n = Number(res.headers.get("content-length"));
+        await res.body?.cancel().catch(() => { });
+        return Number.isFinite(n) && n > 0 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class RuntimeInstallError extends Error {
+    code;
+    detail;
+    /** 这次安装本来是要换下这些超出 max_tested 的版本(ensureAgentRuntime 填,给调用方说明后果) */
+    skipped;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = "RuntimeInstallError";
+    }
+}
+/**
+ * 装一个确切版本:npm install 到暂存目录 → 校验(锁文件里的 integrity 与 registry 元数据一致、
+ * 可执行文件报出的版本号就是目标版本)→ 整目录改名成 runtime/<版本>。中途失败不影响已装的版本。
+ */
+export async function installRuntime(opts) {
+    const { spec, paths, version, registry, hooks } = opts;
+    const plat = platformPackageRef(spec, version);
+    if (!plat)
+        throw new RuntimeInstallError("unsupported_platform", hooks.text.unsupported());
+    const [mainMeta, platMeta] = await Promise.all([
+        fetchPackageMeta(registry, spec.npmPackage, version),
+        fetchPackageMeta(registry, plat.name, plat.version),
+    ]);
+    const downloadBytes = await downloadSize(platMeta?.tarball);
+    if (opts.needsConsent) {
+        const ok = hooks.consent
+            ? await hooks.consent({
+                agent: spec.agent,
+                npmPackage: spec.npmPackage,
+                version,
+                registry,
+                downloadBytes,
+                unpackedBytes: platMeta?.unpackedSize !== undefined
+                    ? platMeta.unpackedSize + (mainMeta?.unpackedSize ?? 0)
+                    : undefined,
+            })
+            : false;
+        if (!ok)
+            throw new RuntimeInstallError("declined", hooks.text.declined());
+    }
+    const npm = opts.npm ?? findNpm({ execPath: process.execPath, platform: process.platform, env: process.env });
+    if (!npm)
+        throw new RuntimeInstallError("no_npm", hooks.text.noNpm());
+    mkdirSync(paths.runtimeDir, { recursive: true, mode: 0o700 });
+    const maxAttempts = opts.maxAttempts ?? 3;
+    const retryDelayMs = opts.retryDelayMs ?? 3_000;
+    hooks.log(hooks.text.installing(version));
+    let lastOutput = "";
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const staging = join(paths.runtimeDir, `.staging-${version}-${randomBytes(4).toString("hex")}`);
+        mkdirSync(staging, { recursive: true });
+        try {
+            const result = await runNpmInstall(npm, {
+                staging,
+                cache: paths.npmCache,
+                spec: `${spec.npmPackage}@${version}`,
+                registry,
+                progress: hooks.progress,
+                totalBytes: downloadBytes,
+            });
+            lastOutput = result.output;
+            if (result.code !== 0) {
+                hooks.log(hooks.text.npmFailed(attempt, maxAttempts));
+                rmSync(staging, { recursive: true, force: true });
+                if (attempt < maxAttempts) {
+                    hooks.log(hooks.text.retrying(Math.round((retryDelayMs * attempt) / 1000)));
+                    await new Promise((r) => setTimeout(r, retryDelayMs * attempt));
+                    continue;
+                }
+                throw new RuntimeInstallError("npm_failed", hooks.text.npmFailed(attempt, maxAttempts), tail(lastOutput));
+            }
+            const problem = verifyStaging({
+                spec,
+                staging,
+                version,
+                platPkg: plat.dir,
+                platVersion: plat.version,
+                mainMeta,
+                platMeta,
+                probe: (bin) => probeVersion(bin, opts.probeConfigDir, spec),
+            });
+            if (problem) {
+                rmSync(staging, { recursive: true, force: true });
+                throw new RuntimeInstallError("verify_failed", hooks.text.verifyFailed(problem), tail(lastOutput));
+            }
+            const target = versionDir(paths, version);
+            rmSync(target, { recursive: true, force: true });
+            try {
+                renameSync(staging, target);
+            }
+            catch (e) {
+                // 另一个 u1s1 进程刚好装好了同一版本:用它的
+                rmSync(staging, { recursive: true, force: true });
+                if (!existsSync(managedBinPath(paths, spec, version)))
+                    throw e;
+            }
+            const bin = managedBinPath(paths, spec, version);
+            updateRuntimeState(paths, { current: version, pending: undefined });
+            pruneOldVersions(paths, version);
+            rmSync(paths.npmCache, { recursive: true, force: true });
+            hooks.log(hooks.text.installed(version));
+            return { source: "managed", bin, version };
+        }
+        catch (e) {
+            rmSync(staging, { recursive: true, force: true });
+            throw e;
+        }
+    }
+    throw new RuntimeInstallError("npm_failed", hooks.text.npmFailed(maxAttempts, maxAttempts), tail(lastOutput));
+}
+function tail(text, lines = 15) {
+    return text.trim().split(/\r?\n/).slice(-lines).join("\n");
+}
+/** 只留当前版本;删不掉的(Windows 上还在跑的 .exe)留到下次。 */
+function pruneOldVersions(paths, keep) {
+    let names = [];
+    try {
+        names = readdirSync(paths.runtimeDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name === keep)
+            continue;
+        try {
+            rmSync(join(paths.runtimeDir, name), { recursive: true, force: true });
+        }
+        catch {
+            // 忽略
+        }
+    }
+}
+/**
+ * 完整性校验。npm 自己已按 registry 元数据里的 integrity 校验过每个压缩包;这里再确认
+ * 装进来的正是我们要的那两个包、那个版本(锁文件条目与刚取的元数据一致),
+ * 且可执行文件能跑、报出的就是目标版本(postinstall 没装上平台二进制时这里会失败)。
+ */
+export function verifyStaging(input) {
+    const { spec, staging, version, platPkg } = input;
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(join(staging, "node_modules", ".package-lock.json"), "utf8"));
+    }
+    catch {
+        return "missing node_modules/.package-lock.json";
+    }
+    const check = (pkg, meta, want = version) => {
+        const entry = lock.packages?.[`node_modules/${pkg}`];
+        if (!entry)
+            return `${pkg} not installed`;
+        if (entry.version !== want)
+            return `${pkg} version ${String(entry.version)} != ${want}`;
+        if (!entry.integrity)
+            return `${pkg} has no integrity`;
+        if (meta?.integrity && entry.integrity !== meta.integrity)
+            return `${pkg} integrity mismatch`;
+        return undefined;
+    };
+    const problem = check(spec.npmPackage, input.mainMeta) ?? check(platPkg, input.platMeta, input.platVersion ?? version);
+    if (problem)
+        return problem;
+    const bin = binUnder(staging, spec);
+    const got = (input.probe ?? ((b) => probeVersion(b, undefined, spec)))(bin);
+    if (got !== version)
+        return `binary reports ${got ?? "nothing"}, expected ${version}`;
+    return undefined;
+}
+export function npmInstallArgs(o) {
+    return [
+        "install",
+        o.spec,
+        "--prefix", o.staging,
+        "--registry", o.registry,
+        // 用自己的缓存目录:不碰用户的 ~/.npm,下载量也能按目录大小算进度
+        "--cache", o.cache,
+        "--include=optional",
+        "--no-audit",
+        "--no-fund",
+        "--no-update-notifier",
+        "--loglevel=error",
+    ];
+}
+/** npm 的子进程环境:去掉密钥;当前 Node 所在目录放到 PATH 最前,postinstall 的 `node install.cjs` 用的就是它。 */
+export function npmEnv(base, execPath, platform = process.platform) {
+    const env = stripSecretEnv(base);
+    const P = platform === "win32" ? win32 : posix;
+    const sep = platform === "win32" ? ";" : ":";
+    const pathKey = platform === "win32" ? (Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "Path") : "PATH";
+    const current = env[pathKey] ?? "";
+    env[pathKey] = current ? `${P.dirname(execPath)}${sep}${current}` : P.dirname(execPath);
+    env["npm_config_update_notifier"] = "false";
+    env["npm_config_fund"] = "false";
+    env["npm_config_audit"] = "false";
+    return env;
+}
+function runNpmInstall(npm, o) {
+    return new Promise((resolve) => {
+        const child = spawn(npm.command, [...npm.prefixArgs, ...npmInstallArgs(o)], {
+            env: npmEnv(process.env, process.execPath),
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let output = "";
+        const append = (chunk) => {
+            output += chunk.toString("utf8");
+            if (output.length > 64 * 1024)
+                output = output.slice(-64 * 1024);
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        const baseline = dirSize(o.cache);
+        const timer = o.progress
+            ? setInterval(() => o.progress(Math.max(0, dirSize(o.cache) - baseline), o.totalBytes), 1_000)
+            : undefined;
+        const done = (code) => {
+            if (timer)
+                clearInterval(timer);
+            resolve({ code, output });
+        };
+        child.on("error", (e) => {
+            output += String(e);
+            done(1);
+        });
+        child.on("exit", (code) => done(code ?? 1));
+    });
+}
+function dirSize(dir) {
+    let total = 0;
+    const walk = (d, depth) => {
+        if (depth > 8)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                walk(p, depth + 1);
+            else if (e.isFile()) {
+                try {
+                    total += statSync(p).size;
+                }
+                catch {
+                    // 忽略
+                }
+            }
+        }
+    };
+    walk(dir, 0);
+    return total;
+}
+// ---------------------------------------------------------------- daily check
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * 每天最多查一次官方最新版;算出刹车允许的目标版本高于当前托管版本时记为 pending,
+ * 下次启动前安装(planRuntime 的 update 分支)。pin 了就不记 pending。
+ */
+export async function dailyUpdateCheck(input) {
+    const state = readRuntimeState(input.paths);
+    if (!input.force && state.lastCheckAt !== undefined && input.now - state.lastCheckAt < UPDATE_CHECK_INTERVAL_MS
+        && input.now >= state.lastCheckAt) {
+        return state;
+    }
+    const latest = await input.latest();
+    if (!latest)
+        return state; // 查不到不记时间,下次启动再试
+    const patch = { lastCheckAt: input.now, latest };
+    const target = bestInstallTarget([latest, input.brake.maxTestedVersion], input.brake);
+    if (!state.pinned && state.current && target && compareVersions(target, state.current) > 0)
+        patch.pending = target;
+    else
+        patch.pending = undefined;
+    return updateRuntimeState(input.paths, patch);
+}
+export class RuntimePlanError extends Error {
+    plan;
+    constructor(plan) {
+        super(`agent runtime unavailable: ${plan.code}`);
+        this.plan = plan;
+        this.name = "RuntimePlanError";
+    }
+}
+/**
+ * 找到(必要时下载或更新)可用的客户端运行时。CLI(`u1s1 claude` / `u1s1 codex`)与桌面端共用。
+ * 失败抛 RuntimePlanError(刹车/版本问题)或 RuntimeInstallError(下载问题)。
+ */
+export async function ensureAgentRuntime(agent, opts) {
+    const spec = runtimeSpec(agent);
+    const paths = runtimePaths(opts.agentsRoot, agent);
+    const env = opts.env ?? process.env;
+    const registry = npmRegistryFor(opts.site, env);
+    const probe = (bin) => probeVersion(bin, opts.probeConfigDir, spec);
+    const state = readRuntimeState(paths);
+    let latestMemo;
+    const plan = await planRuntime({
+        brake: opts.brake,
+        state,
+        envBin: async () => {
+            const bin = env[spec.binEnv]?.trim();
+            return bin ? { bin, version: probe(bin) } : undefined;
+        },
+        managed: async () => {
+            const installed = installedVersions(paths, spec);
+            const version = state.current && installed.includes(state.current) ? state.current : installed[0];
+            if (!version)
+                return undefined;
+            const bin = managedBinPath(paths, spec, version);
+            // 托管目录只放校验过的版本,目录名就是版本号,启动时不必每次再跑一遍 --version
+            return { source: "managed", bin, version };
+        },
+        installed: () => installedVersions(paths, spec),
+        onPath: async () => {
+            const bin = findOnPath(spec.command, { env, platform: process.platform });
+            const version = bin ? probe(bin) : undefined;
+            return bin && version ? { source: "path", bin, version } : undefined;
+        },
+        latest: () => (latestMemo ??= fetchLatestVersion(registry, spec.npmPackage)),
+        autoUpdate: opts.autoUpdate,
+    });
+    if (plan.action === "error")
+        throw new RuntimePlanError(plan);
+    const overMax = opts.hooks.text.overMaxTested;
+    if (overMax)
+        for (const s of plan.skipped ?? [])
+            opts.hooks.log(overMax(s));
+    const extra = { pinIgnored: plan.pinIgnored, ...(plan.skipped ? { skipped: plan.skipped } : {}) };
+    if (plan.action === "use")
+        return { ...plan.runtime, ...extra };
+    try {
+        const installed = await (opts.install ?? installRuntime)({
+            spec,
+            paths,
+            version: plan.version,
+            registry,
+            needsConsent: plan.needsConsent,
+            hooks: opts.hooks,
+            probeConfigDir: opts.probeConfigDir,
+        });
+        return { ...installed, ...extra };
+    }
+    catch (e) {
+        if (plan.fallback && e instanceof RuntimeInstallError && e.code !== "declined") {
+            // 自动更新失败:清掉 pending,别每次启动都卡在重试上;下次每日检查会再记
+            if (plan.reason === "update")
+                updateRuntimeState(paths, { pending: undefined });
+            return { ...plan.fallback, ...extra, installError: e };
+        }
+        if (e instanceof RuntimeInstallError && plan.skipped)
+            e.skipped = plan.skipped;
+        throw e;
+    }
+}