u1s1-cli 1.14.5 → 1.15.0

package/dist/agents/launch.js

@@ -0,0 +1,444 @@
+/**
+ * 官方原版客户端(`u1s1 claude` / `u1s1 codex`)共用的启动流程与文案:
+ * 登录 → 经签名代理拉网关配置(开关、刹车、阵容)→ 找到/下载原版 → 起声明了客户端的签名代理 →
+ * 由各客户端模块写配置、拼环境 → 子进程继承终端 → 透传退出码;顺带每天查一次新版。
+ *
+ * 各客户端只提供 AgentProfile(名字、条款、路径)和「怎么注入」,下载、刹车、文案都在这里一份。
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, readdirSync, statSync } from "node:fs";
+import { constants as osConstants } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Agent, fetch as undiciFetch } from "undici";
+import { AccessDeniedError, AuthError, fetchModels } from "../api.js";
+import { u1s1Dir } from "../config.js";
+import { ensureSigningProxy } from "../device-auth.js";
+import { tr } from "../i18n.js";
+import { siteLinks, siteOf } from "../site.js";
+import { loadAgentConfig } from "./agent-config.js";
+import { readAgentPrefs, resolveLaunchModel } from "./prefs.js";
+import { dailyUpdateCheck, ensureAgentRuntime, fetchLatestVersion, npmRegistryFor, RuntimeInstallError, RuntimePlanError, runtimeSpec, } from "./runtime.js";
+export function agentsRoot() {
+    return join(u1s1Dir, "agents");
+}
+export const CLAUDE_TERMS_URL = "https://code.claude.com/docs/en/legal-and-compliance";
+export const CODEX_LICENSE_URL = "https://github.com/openai/codex/blob/main/LICENSE";
+export const AGENT_PROFILES = {
+    claude: {
+        agent: "claude",
+        gatewayAgent: "claude-code",
+        product: "Claude Code",
+        termsLine: () => tr(`    Claude Code 的使用受 Anthropic 的条款约束:${CLAUDE_TERMS_URL}`, `    Use of Claude Code is subject to Anthropic's terms: ${CLAUDE_TERMS_URL}`),
+        locationLine: () => tr("    位置:~/.u1s1/agents/claude(不影响你自己装的版本和 ~/.claude)", "    Location: ~/.u1s1/agents/claude (your own install and ~/.claude are left alone)"),
+    },
+    codex: {
+        agent: "codex",
+        gatewayAgent: "codex",
+        product: "Codex CLI",
+        termsLine: () => tr(`    Codex CLI 以 Apache-2.0 许可发布:${CODEX_LICENSE_URL}`, `    Codex CLI is released under the Apache-2.0 license: ${CODEX_LICENSE_URL}`),
+        locationLine: () => tr("    位置:~/.u1s1/agents/codex(不影响你自己装的版本和 ~/.codex)", "    Location: ~/.u1s1/agents/codex (your own install and ~/.codex are left alone)"),
+    },
+};
+// ---------------------------------------------------------------- loopback
+let loopbackAgent;
+/**
+ * 请求本机签名代理(http://127.0.0.1:<端口>)专用:直连,不走用户的 HTTP(S)_PROXY。
+ * 全局 dispatcher 认 HTTP_PROXY,用户没在 NO_PROXY 里写 127.0.0.1 时,连本机代理的请求也会交给
+ * 那个代理;远端代理连不到用户本机,首次启动(还没有配置缓存)就报「拿不到启动配置」。
+ * 签名代理到网关那一跳不受影响,照旧按用户的代理设置走。
+ */
+export function loopbackFetch(url, init) {
+    const host = new URL(url).hostname;
+    if (host !== "127.0.0.1" && host !== "localhost" && host !== "[::1]") {
+        throw new Error(`loopbackFetch is only for the local signing proxy: ${url}`);
+    }
+    loopbackAgent ??= new Agent();
+    return undiciFetch(url, { ...init, dispatcher: loopbackAgent });
+}
+// ---------------------------------------------------------------- child process
+/**
+ * 起子进程、继承终端、等它退出、透传退出码。
+ *
+ * 信号:Ctrl+C / Ctrl+\ 由终端直接发给整个前台进程组,子进程自己会收到;启动器只要不被它们
+ * 打死就行,不再转发(转发会让子进程收到两次,交互界面里「按两次 Ctrl+C 退出」就成了按一次)。
+ * SIGTERM / SIGHUP 通常只发给启动器(kill、关窗口),转发给子进程。
+ * 签名代理的监听是 unref 的:必须等子进程退出后再返回。
+ */
+export function spawnAgent(bin, args, env, deps = {}) {
+    const proc = deps.proc ?? process;
+    const child = (deps.spawn ?? spawn)(bin, [...args], { env, stdio: "inherit" });
+    const swallow = () => { };
+    const forwarders = new Map();
+    for (const sig of ["SIGTERM", "SIGHUP"]) {
+        forwarders.set(sig, () => {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill(sig);
+        });
+    }
+    const ignored = process.platform === "win32" ? ["SIGINT"] : ["SIGINT", "SIGQUIT"];
+    for (const sig of ignored)
+        proc.on(sig, swallow);
+    for (const [sig, fn] of forwarders)
+        proc.on(sig, fn);
+    const cleanup = () => {
+        for (const sig of ignored)
+            proc.off(sig, swallow);
+        for (const [sig, fn] of forwarders)
+            proc.off(sig, fn);
+    };
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(code);
+        };
+        child.once("error", (e) => {
+            console.error(tr(`无法启动 ${bin}:${e.message}`, `Couldn't start ${bin}: ${e.message}`));
+            done(127);
+        });
+        child.once("exit", (code, signal) => {
+            if (code !== null)
+                return done(code);
+            const num = signal ? osConstants.signals[signal] : undefined;
+            done(128 + (num ?? 1));
+        });
+    });
+}
+// ---------------------------------------------------------------- CLI hooks (文案)
+function mb(bytes) {
+    return (bytes / 1024 / 1024).toFixed(bytes >= 100 * 1024 * 1024 ? 0 : 1);
+}
+export function consentLines(info) {
+    const profile = AGENT_PROFILES[info.agent];
+    const host = new URL(info.registry).host;
+    // 措辞按实际下载的源定(中国站默认镜像;U1S1_NPM_REGISTRY 可能改成官方源或别的镜像)
+    const source = host === "registry.npmjs.org"
+        ? tr(`官方 npm 包 ${info.npmPackage}(${host})`, `the official npm package ${info.npmPackage} (${host})`)
+        : tr(`官方 npm 包 ${info.npmPackage}(经 npm 镜像 ${host} 下载,同一份包,带完整性校验)`, `the official npm package ${info.npmPackage} (via the npm mirror ${host}; same package, integrity-checked)`);
+    const size = info.downloadBytes !== undefined || info.unpackedBytes !== undefined
+        ? [
+            info.downloadBytes !== undefined ? tr(`下载约 ${mb(info.downloadBytes)} MB`, `about ${mb(info.downloadBytes)} MB to download`) : undefined,
+            info.unpackedBytes !== undefined ? tr(`安装后约 ${mb(info.unpackedBytes)} MB`, `about ${mb(info.unpackedBytes)} MB installed`) : undefined,
+        ].filter(Boolean).join(tr(",", ", "))
+        : tr("几百 MB(暂时拿不到确切大小)", "a few hundred MB (exact size unavailable)");
+    return [
+        "",
+        tr(`  首次使用需要下载官方 ${profile.product} ${info.version}:`, `  The official ${profile.product} ${info.version} needs to be downloaded first:`),
+        tr(`    来源:${source}`, `    Source: ${source}`),
+        tr(`    大小:${size}`, `    Size: ${size}`),
+        profile.locationLine(),
+        profile.termsLine(),
+    ];
+}
+async function askConsent(info) {
+    for (const line of consentLines(info))
+        console.error(line);
+    const preset = process.env["U1S1_AGENT_INSTALL"]?.trim().toLowerCase();
+    if (preset === "yes" || preset === "y" || preset === "1")
+        return true;
+    if (!process.stdin.isTTY) {
+        console.error(tr(`  当前没有可交互的终端。请在终端里运行一次 u1s1 ${info.agent} 确认下载,或设置 U1S1_AGENT_INSTALL=yes。`, `  No interactive terminal. Run u1s1 ${info.agent} in a terminal once to confirm, or set U1S1_AGENT_INSTALL=yes.`));
+        return false;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question(tr("  现在下载吗?[Y/n] ", "  Download now? [Y/n] "))).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes" || answer === "是";
+    }
+    finally {
+        rl.close();
+    }
+}
+export function cliInstallHooks(agent = "claude") {
+    let progressShown = false;
+    const endProgress = () => {
+        if (progressShown)
+            process.stderr.write("\n");
+        progressShown = false;
+    };
+    return {
+        consent: (info) => askConsent(info),
+        log: (line) => {
+            endProgress();
+            console.error(line);
+        },
+        progress: process.stderr.isTTY
+            ? (done, total) => {
+                progressShown = true;
+                const text = total
+                    ? tr(`  已下载 ${mb(Math.min(done, total))} / 约 ${mb(total)} MB`, `  Downloaded ${mb(Math.min(done, total))} / ~${mb(total)} MB`)
+                    : tr(`  已下载 ${mb(done)} MB`, `  Downloaded ${mb(done)} MB`);
+                process.stderr.write(`\r${text}\x1b[K`);
+            }
+            : undefined,
+        text: {
+            noNpm: () => tr(`需要 npm 才能下载,但这台机器上没找到。请安装 Node.js 22 或更新版本(自带 npm,https://nodejs.org),或重新运行官网安装脚本后再试。`, `npm is required for the download but wasn't found. Install Node.js 22 or newer (includes npm, https://nodejs.org), or rerun the official install script, then try again.`),
+            npmFailed: (attempt, max) => tr(`  下载失败(第 ${attempt}/${max} 次)`, `  Download failed (attempt ${attempt}/${max})`),
+            retrying: (s) => tr(`  ${s} 秒后重试…`, `  Retrying in ${s}s…`),
+            verifyFailed: (detail) => tr(`下载的文件没通过校验(${detail}),已丢弃。`, `The download failed verification (${detail}) and was discarded.`),
+            declined: () => tr("已取消下载。", "Download cancelled."),
+            unsupported: () => tr(`这台机器的系统/架构(${process.platform}-${process.arch})没有官方版本。`, `There's no official build for this system (${process.platform}-${process.arch}).`),
+            installing: (v) => tr(`  正在下载并安装 ${v} …`, `  Downloading and installing ${v}…`),
+            installed: (v) => tr(`  已安装 ${v}`, `  Installed ${v}`),
+            overMaxTested: (s) => overMaxTestedText(s, agent),
+        },
+    };
+}
+/** 已有的某份客户端高于 max_tested、这次不用它。 */
+export function overMaxTestedText(s, agent = "claude") {
+    const max = s.maxTestedVersion;
+    const binEnv = runtimeSpec(agent).binEnv;
+    if (s.source === "env") {
+        return tr(`  ${binEnv} 指向的 ${s.bin} 是 ${s.version},高于目前验证过的最高版本 ${max}。不改动它,这次改用 u1s1 管理的、不超过 ${max} 的版本。`, `  ${s.bin} from ${binEnv} is ${s.version}, newer than the highest version verified so far (${max}). It's left as is; this run uses a u1s1-managed copy no newer than ${max} instead.`);
+    }
+    if (s.source === "path") {
+        return tr(`  本机已有的 ${s.bin} 是 ${s.version},高于目前验证过的最高版本 ${max}。不改动它,由 u1s1 另装一份不超过 ${max} 的版本来用。`, `  Your existing ${s.bin} is ${s.version}, newer than the highest version verified so far (${max}). It's left as is; u1s1 uses its own copy no newer than ${max} instead.`);
+    }
+    return tr(`  u1s1 装的 ${s.version} 高于目前验证过的最高版本 ${max},换到不超过 ${max} 的版本。`, `  The u1s1-managed ${s.version} is newer than the highest version verified so far (${max}); switching to a version no newer than ${max}.`);
+}
+/** ensureAgentRuntime 抛出的错误 → 给用户的几行说明。不认识的错误返回 false(调用方再抛)。 */
+export function printRuntimeFailure(e, agent = "claude") {
+    if (e instanceof RuntimePlanError) {
+        console.error(runtimeErrorText(e, agent));
+        return true;
+    }
+    if (!(e instanceof RuntimeInstallError))
+        return false;
+    console.error(e.message);
+    if (e.detail)
+        console.error(e.detail);
+    const max = e.skipped?.[0]?.maxTestedVersion;
+    if (max) {
+        console.error(tr(`没换成不超过 ${max} 的版本。高于 ${max} 的版本还没验证过能和 u1s1 正常配合,不会拿来用;稍后重新运行即可再试。`, `Couldn't switch to a version no newer than ${max}. Versions above ${max} haven't been verified to work with u1s1 yet, so they won't be used; run this again later to retry.`));
+    }
+    return true;
+}
+export function notOpenText() {
+    return tr("这个客户端暂未开放。现在可以用 u1s1 pi(u1s1 内置的编程助手)。", "This client isn't available yet. You can use u1s1 pi (u1s1's built-in coding assistant) for now.");
+}
+export function runtimeErrorText(e, agent = "claude") {
+    const p = e.plan;
+    const binEnv = runtimeSpec(agent).binEnv;
+    if (p.code === "env_bin_unusable") {
+        return tr(`${binEnv} 指向的 ${p.bin} 无法运行(取不到版本号)。`, `${binEnv} points to ${p.bin}, which doesn't run (no version reported).`);
+    }
+    if (p.code === "update_required") {
+        const why = p.verdict === "blocked"
+            ? tr("已被停用", "has been disabled")
+            : p.verdict === "below_min"
+                ? tr("版本太旧", "is too old")
+                : tr("高于目前验证过的最高版本", "is newer than the highest version verified so far");
+        const product = AGENT_PROFILES[agent].product;
+        return tr(`${product} ${p.version} ${why},要换到可用的版本才能启动。自动更新已关闭:运行 u1s1 agents install ${agent} 手动更新,`
+            + `或 u1s1 config set ${agent}.auto-update on 打开自动更新。`, `${product} ${p.version} ${why} and has to be replaced with an allowed version before it can start. Automatic updates are off: `
+            + `run u1s1 agents install ${agent} to update now, or u1s1 config set ${agent}.auto-update on to turn them back on.`);
+    }
+    if (p.code === "env_bin_brake") {
+        return p.verdict === "blocked"
+            ? tr(`${binEnv} 指向的版本 ${p.version} 已被停用,请换一个版本。`, `Version ${p.version} (${binEnv}) has been disabled; use a different version.`)
+            : tr(`${binEnv} 指向的版本 ${p.version} 太旧,请升级。`, `Version ${p.version} (${binEnv}) is too old; please upgrade.`);
+    }
+    return tr("暂时拿不到可安装的版本(可能连不上 npm 源),请稍后再试。", "No installable version is available right now (the npm registry may be unreachable). Please try again later.");
+}
+/** 运行时的两条附带提示:pin 被忽略、更新没装上。 */
+export function printRuntimeNotes(runtime, agent) {
+    if (runtime.pinIgnored) {
+        console.error(tr(`  锁定的版本 ${runtime.pinIgnored} 不在允许范围内,已忽略(u1s1 agents unpin ${agent} 可解除)。`, `  The pinned version ${runtime.pinIgnored} isn't allowed right now and was ignored (u1s1 agents unpin ${agent} to clear it).`));
+    }
+    if (runtime.installError) {
+        console.error(tr(`  更新没装上,继续使用 ${runtime.version}。`, `  The update didn't install; continuing with ${runtime.version}.`));
+    }
+}
+// ---------------------------------------------------------------- orchestration
+function attestationSource(cfg, models) {
+    return {
+        token: models?.clientAttestation,
+        expiresInSeconds: models?.clientAttestationExpiresInSeconds,
+        refresh: async () => {
+            const refreshed = await fetchModels(cfg);
+            return { token: refreshed.clientAttestation, expiresInSeconds: refreshed.clientAttestationExpiresInSeconds };
+        },
+    };
+}
+/**
+ * 子进程启动前的公共部分。返回 number = 启动前就失败的退出码(已向用户说明)。
+ * 是否可用完全由网关配置的 enabled 决定:停用时显示 disabled_reason,不下载、不启动。
+ */
+export async function prepareAgentLaunch(profile, paths) {
+    const { ensureAuth, login } = await import("../login.js");
+    let cfg = await ensureAuth();
+    const site = siteOf(cfg);
+    // 先拉一次 /v1/models:拿客户端证明(签名代理附在每个请求上),顺带确认登录有效
+    let models;
+    try {
+        models = await fetchModels(cfg);
+    }
+    catch (e) {
+        if (e instanceof AuthError) {
+            console.error(tr("  登录已失效(这台设备可能被移除,或账号更换过钥匙),需要重新登录。", "  Your session has expired (this device may have been removed, or the account's keys changed). Please sign in again."));
+            cfg = await login();
+            models = await fetchModels(cfg).catch(() => undefined);
+        }
+        else if (e instanceof AccessDeniedError) {
+            console.error(`  ${e.message}`);
+            console.error(tr(`  这个账号当前无法使用 u1s1。如有疑问可发邮件到 ${site.contactEmail},或在 ${siteLinks(site).dashboard} 提交工单。`, `  This account can't use u1s1 right now. Questions? Email ${site.contactEmail} or open a support ticket at ${siteLinks(site).dashboard}.`));
+            return 1;
+        }
+        // 其他(多半是网络):往下走,配置可以用缓存,真连不上时子进程自己会报错
+    }
+    const attestation = attestationSource(cfg, models);
+    // 配置经签名代理拉(与客户端请求同一条签名通路)
+    const configProxy = await ensureSigningProxy(cfg, "terminal", attestation);
+    const result = await loadAgentConfig({
+        agent: profile.gatewayAgent,
+        cacheFile: paths.configCache,
+        site: new URL(cfg.baseUrl).origin,
+        fetchConfig: () => loopbackFetch(`${configProxy.baseUrl}/agents/${profile.gatewayAgent}/config`, {
+            headers: { authorization: `Bearer ${configProxy.localKey}`, accept: "application/json" },
+            signal: AbortSignal.timeout(15_000),
+        }),
+    });
+    if (result.status === "unavailable") {
+        console.error(notOpenText());
+        return 1;
+    }
+    if (result.status === "disabled") {
+        console.error(result.reason ?? notOpenText());
+        return 1;
+    }
+    if (result.status === "auth") {
+        console.error(tr("登录已失效,请运行 u1s1 login 重新登录。", "Your session has expired. Run u1s1 login to sign in again."));
+        return 1;
+    }
+    if (result.status === "error") {
+        console.error(tr(`拿不到启动配置(${result.detail}),检查一下网络后再试。`, `Couldn't fetch the launch configuration (${result.detail}). Check your network and try again.`));
+        return 1;
+    }
+    const config = result.config;
+    const prefs = readAgentPrefs(profile.agent);
+    const model = resolveLaunchModel(profile.agent, config, {
+        prefs,
+        notify: (missing, fallback) => console.error(modelMissingText(profile.agent, missing, fallback)),
+    });
+    mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
+    let runtime;
+    try {
+        runtime = await ensureAgentRuntime(profile.agent, {
+            brake: config.runtime,
+            site: site.id,
+            agentsRoot: agentsRoot(),
+            hooks: cliInstallHooks(profile.agent),
+            probeConfigDir: paths.configDir,
+            autoUpdate: prefs.autoUpdate,
+        });
+    }
+    catch (e) {
+        if (!printRuntimeFailure(e, profile.agent))
+            throw e;
+        return 1;
+    }
+    printRuntimeNotes(runtime, profile.agent);
+    // 子进程用的代理:带上客户端名与版本,网关据此核对请求形状
+    const proxy = await ensureSigningProxy(cfg, "terminal", attestation, { name: profile.gatewayAgent, version: runtime.version });
+    return { config, model, autoUpdate: prefs.autoUpdate, runtime, proxy, site: site.id, features: models?.features };
+}
+/** 用户在 u1s1 config 里选的模型不在当前阵容里(只提示一次,见 prefs.ts)。 */
+export function modelMissingText(agent, missing, fallback) {
+    const using = fallback ? tr(`这次用默认模型 ${fallback}`, `using the default model ${fallback} instead`) : tr("这次用默认模型", "using the default model instead");
+    return tr(`  你为 ${agent} 设的默认模型 ${missing} 现在不可用,${using}。换一个:u1s1 config set ${agent}.model <模型>`, `  The default model you set for ${agent}, ${missing}, isn't available right now; ${using}. To pick another: u1s1 config set ${agent}.model <model>`);
+}
+// ---------------------------------------------------------------- resume hint
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+/**
+ * 退出时客户端自己打印「用 codex resume <id> / claude --resume <id> 继续」,但用户要经 u1s1 启动才连得上
+ * 网关。这里在它下面补一行带 u1s1 的写法。会话 id 取这次运行期间写过的最新会话文件(客户端自己的
+ * 配置目录下,启动器专用,不是用户的 ~/.codex、~/.claude):
+ *   codex   CODEX_HOME/sessions/<年>/<月>/<日>/rollout-<时间>-<id>.jsonl
+ *   claude  CLAUDE_CONFIG_DIR/projects/<目录名>/<id>.jsonl
+ */
+const SESSION_LAYOUT = {
+    codex: { dir: "sessions", file: new RegExp(`^rollout-.*-(${UUID})\\.jsonl$`), depth: 4 },
+    claude: { dir: "projects", file: new RegExp(`^(${UUID})\\.jsonl$`), depth: 2 },
+};
+/** configDir 下这次运行(since 之后)写过的最新会话的 id。 */
+export function latestSessionId(agent, configDir, since) {
+    const layout = SESSION_LAYOUT[agent];
+    let best;
+    const walk = (dir, depth) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(dir, name);
+            let st;
+            try {
+                st = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth > 1)
+                    walk(path, depth - 1);
+                continue;
+            }
+            const m = layout.file.exec(name);
+            if (m && st.mtimeMs >= since && (!best || st.mtimeMs > best.mtime))
+                best = { id: m[1], mtime: st.mtimeMs };
+        }
+    };
+    walk(join(configDir, layout.dir), layout.depth);
+    return best?.id;
+}
+/**
+ * 只在交互界面正常退出后提示:脚本调用(codex exec、claude -p)客户端自己也不打印续接提示,
+ * 我们也不加。
+ */
+export function wantsResumeHint(agent, userArgs, interactive) {
+    if (!interactive)
+        return false;
+    if (agent === "codex")
+        return !["exec", "e", "review", "login", "logout", "mcp", "mcp-server", "app-server", "completion", "apply", "a", "cloud", "sandbox", "debug", "features"].includes(userArgs[0] ?? "")
+            && !userArgs.some((a) => a === "--help" || a === "-h" || a === "--version" || a === "-V");
+    return !userArgs.some((a) => a === "-p" || a === "--print" || a === "--help" || a === "-h" || a === "--version" || a === "-v");
+}
+export function resumeHintText(agent, id) {
+    const command = agent === "codex" ? `u1s1 codex resume ${id}` : `u1s1 claude --resume ${id}`;
+    return tr(`经 u1s1 继续这次会话:${command}`, `To continue this session through u1s1, run: ${command}`);
+}
+/**
+ * 起子进程并等它退出;同时每天最多查一次新版(只管启动器自己装的那份),下次启动前更新,不挡启动。
+ * 用户关了自动更新(u1s1 config)就不查。
+ */
+export async function runPreparedAgent(input) {
+    const { prepared } = input;
+    const spec = runtimeSpec(input.agent);
+    const registry = npmRegistryFor(prepared.site);
+    const check = prepared.runtime.source === "managed" && prepared.autoUpdate
+        ? dailyUpdateCheck({
+            paths: input.paths,
+            brake: prepared.config.runtime,
+            now: Date.now(),
+            latest: () => fetchLatestVersion(registry, spec.npmPackage),
+        }).catch(() => undefined)
+        : Promise.resolve(undefined);
+    const startedAt = Date.now();
+    const code = await spawnAgent(prepared.runtime.bin, input.args, input.env);
+    if (code === 0 && input.paths.configDir && input.userArgs
+        && wantsResumeHint(input.agent, input.userArgs, !!process.stdin.isTTY && !!process.stdout.isTTY)) {
+        // 文件时间的精度与时钟差:往前放 2 秒
+        const id = latestSessionId(input.agent, input.paths.configDir, startedAt - 2_000);
+        if (id)
+            console.log(resumeHintText(input.agent, id));
+    }
+    await Promise.race([check, new Promise((r) => setTimeout(r, 1_500).unref())]);
+    return code;
+}

package/dist/agents/pi.d.ts

@@ -0,0 +1,9 @@
+import { type CliConfig } from "../config.js";
+/**
+ * TUI 退出后前台安装新版:此刻不再有模型调用和懒加载,重铺 node_modules 才安全。
+ * 不设 timeout——半路杀掉 npm 会留下残缺的全局安装,之后连启动都起不来;
+ * stdio 直通,装多久用户看得见。(同机另开的 u1s1 实例仍会被重铺波及,属残余
+ * 风险,但远好于更新自己脚下这棵树。)
+ */
+export declare function installPendingUpdate(): void;
+export declare function runAgent(cfg: CliConfig, args: string[]): Promise<void>;