u1s1-cli 1.14.5 → 1.15.0

package/dist/agents/codex.d.ts

@@ -0,0 +1,111 @@
+import { type McpLaunchEnv } from "../mcp-server.js";
+import type { AgentConfig } from "./agent-config.js";
+import { type RuntimePaths } from "./runtime.js";
+export declare const CODEX_GATEWAY_AGENT: "codex";
+/** config.toml 里我们的 provider id(不能用 openai、ollama 等内置保留名)。 */
+export declare const CODEX_PROVIDER_ID = "u1s1";
+/** provider 的 env_key:子进程环境里放本地 token 的变量名。 */
+export declare const CODEX_KEY_ENV = "U1S1_LOCAL_KEY";
+export interface CodexPaths extends RuntimePaths {
+    /** CODEX_HOME */
+    configDir: string;
+    /** CODEX_HOME/config.toml */
+    configToml: string;
+    /** 网关下发的模型目录,原样写成文件给 model_catalog_json 用 */
+    catalogFile: string;
+    /** 上次成功拉到的 /v1/agents/codex/config */
+    configCache: string;
+}
+export declare function codexPaths(root?: string): CodexPaths;
+/**
+ * 子进程环境里要去掉的变量(依据 Codex 0.167.2 源码):
+ *   - 会换掉配置/状态目录的:CODEX_HOME(我们自己设)、CODEX_SQLITE_HOME(状态库改放别处,
+ *     可能是用户自己的目录);
+ *   - 别的凭证:OPENAI_API_KEY、CODEX_API_KEY(`codex exec` 读它当 API Key 登录)、CODEX_ACCESS_TOKEN;
+ *     我们的 provider 只用 env_key,但有了它们 Codex 会以为已登录官方账号,去做相应的事;
+ *   - 改官方 provider 地址的 OPENAI_BASE_URL(老版本读,0.167.2 只在它的网络代理里用);
+ *   - 改请求形状的:CODEX_INTERNAL_ORIGINATOR_OVERRIDE 会换掉 originator 头和 User-Agent 前缀,
+ *     网关的客户端判定看这两样;
+ *   - 「由某包管理器管理」的标记(CODEX_MANAGED_BY_*、CODEX_MANAGED_PACKAGE_ROOT):会让它提示用
+ *     npm/bun 等升级,更新由启动器管。
+ * 只影响这一次启动的子进程环境,用户自己的 shell 与配置不动。
+ */
+export declare const CODEX_ENV_DROP: readonly string[];
+export interface CodexLaunchInput {
+    baseEnv: NodeJS.ProcessEnv;
+    /** 签名代理的一次性本地 token */
+    localToken: string;
+    /** CODEX_HOME(须已存在,否则 Codex 报错退出) */
+    home: string;
+    /** u1s1 工具服务要的变量(mcpLaunchEnv);不注入时省略 */
+    mcp?: McpLaunchEnv;
+}
+/**
+ * 本机代理地址不走用户的 HTTP(S)_PROXY:0.167.2 实测,设了 HTTP_PROXY / HTTPS_PROXY 又没有 NO_PROXY 时,
+ * Codex 把发往 http://127.0.0.1:<端口>/v1/responses 的请求也交给那个代理(连同本地 token),
+ * 代理不在本机就直接失败。用户原有的 NO_PROXY 条目保留,只补上 127.0.0.1 和 localhost。
+ */
+export declare function withLoopbackNoProxy(value: string | undefined): string;
+export declare function codexLaunchEnv(input: CodexLaunchInput): NodeJS.ProcessEnv;
+/**
+ * 启动器的 -c 覆盖放在用户参数前面:用户自己传的 -c / -m / --profile 照样生效(同名 -c 以后出现的为准)。
+ * @param proxyOrigin 签名代理的 origin,形如 http://127.0.0.1:12345(不带 /v1)
+ */
+export declare function codexLaunchArgs(proxyOrigin: string, userArgs: readonly string[]): string[];
+/**
+ * 启动器管的顶层键:每次启动重写;不在这里的键(包括 Codex 自己写的项目信任)原样保留。
+ * model 每次都写成「用户在 u1s1 config 里定的模型(仍在阵容里时),否则网关默认」:Codex 里用 /model 换的
+ * 模型只管那一次会话,和 u1s1 claude 一致(那边 --settings 的 model 也盖过客户端里 /model 的选择)。
+ */
+export declare const CODEX_MANAGED_KEYS: readonly ["model", "model_provider", "check_for_update_on_startup", "cli_auth_credentials_store", "model_catalog_json"];
+/**
+ * 跟着模型走的顶层键:Codex 的 /model 把它们和 model 一起写进 config.toml。启动器把 model 换掉时
+ * 一并去掉(回到新模型自己的默认),免得为别的模型选的思考强度带到新模型上;model 没变就保留。
+ */
+export declare const CODEX_MODEL_BOUND_KEYS: readonly ["model_reasoning_effort"];
+export interface CodexManagedSettings {
+    model: string | null;
+    /** model_catalog_json 的绝对路径;null = 不写这一项 */
+    catalogFile: string | null;
+    /** u1s1 工具服务怎么拉起;null / 省略 = 不注入(原有的 [mcp_servers.u1s1] 也去掉) */
+    mcp?: CodexMcpServer | null;
+}
+export interface CodexMcpServer {
+    command: string;
+    args: string[];
+    /** 从 Codex 环境转给服务的变量名(Codex 默认只转 HOME、PATH 等少数几个) */
+    envVars: string[];
+}
+export interface RenderedCodexConfig {
+    text: string;
+    /** 原文件里有没法逐行安全改写的写法:原文件要先备份,再整份重写 */
+    replaced: boolean;
+}
+/**
+ * 生成新的 config.toml。保守做法:不解析整份 TOML,只逐行处理我们管的东西——
+ *   - 顶层(第一个表头之前)的受管键整行去掉,换成新值,放在文件最前面;
+ *   - `[model_providers.u1s1]`、`[mcp_servers.u1s1]` 及其子表整段去掉,换成新的放在最后
+ *     (例外:用户对 u1s1 工具的审批选择 `[mcp_servers.u1s1.tools.*]`,注入时跟在新表后面保留);
+ *   - 其余每一行(用户加的键、别的表、注释、Codex 自己写的项目信任等)原样保留,顺序不变。
+ * 遇到没法逐行安全改写的写法(受管键是跨行值、在顶层或 [model_providers] 表里用点号/内联表写我们的
+ * provider)就整份重写,由调用方先把原文件备份。
+ */
+export declare function renderCodexConfig(existing: string | undefined, managed: CodexManagedSettings): RenderedCodexConfig;
+/** 网关 settings.model_catalog:必须是对象才写;CLI 不解析、不改它的内容。 */
+export declare function modelCatalogFromConfig(config: AgentConfig): Record<string, unknown> | undefined;
+/**
+ * 写 model-catalog.json 与 config.toml。返回原 config.toml 被整份重写时的备份路径(给用户一句说明)。
+ */
+export declare function writeCodexConfig(paths: CodexPaths, config: AgentConfig, now?: () => number, mcp?: CodexMcpServer | null, 
+/** 这次启动用的模型(launch.ts 按 u1s1 config 选好);undefined = 网关默认 */
+model?: string | null): string | undefined;
+/** [mcp_servers.u1s1] 的内容:同一个 node、同一份 CLI;只列要转发的变量名。 */
+export declare function codexMcpServer(command?: {
+    command: string;
+    args: string[];
+}, env?: NodeJS.ProcessEnv): CodexMcpServer;
+/**
+ * `u1s1 codex [参数…]`。返回子进程的退出码(启动前就失败返回 1)。
+ * 是否可用完全由网关配置的 enabled 决定(prepareAgentLaunch)。
+ */
+export declare function runCodex(userArgs: string[]): Promise<number>;

package/dist/agents/codex.js

@@ -0,0 +1,392 @@
+/**
+ * `u1s1 codex`:以子进程启动官方原版 Codex CLI,经本机签名代理用设备凭证访问网关。
+ *
+ * 注入(规划 4.4,对着 Codex 0.167.2 的源码与实跑核对过):
+ *   CODEX_HOME=~/.u1s1/agents/codex/home         配置、会话、历史、日志都在这里,与用户自己的 ~/.codex 互不影响
+ *   home/config.toml                             启动器每次重写受管的几项(见 renderCodexConfig),其余原样保留
+ *   U1S1_LOCAL_KEY=<本地 token>                  [model_providers.u1s1] 的 env_key 读它,发 Authorization: Bearer
+ *   -c model_providers.u1s1.base_url="http://127.0.0.1:<端口>/v1"   端口每次随机,用命令行覆盖
+ *   -c model_provider="u1s1"                     命令行一层的优先级高于仓库里的 .codex/config.toml
+ *   -c features.daemon_auto_start=false          不用跨会话常驻的共享后台服务(见 codexLaunchArgs)
+ *   -c analytics.enabled=false                   不向官方上报使用指标
+ *   -c features.plugins=false                    不做插件同步(插件带来的 MCP 工具、/plugins 命令随之不可用)
+ *   NO_PROXY / no_proxy 补上 127.0.0.1、localhost  否则设了 HTTP(S)_PROXY 时连本机代理也走用户代理
+ *   [mcp_servers.u1s1]                           u1s1 工具服务(搜索、读网页、生图,见 mcp-server.ts);env_vars 只列变量名,
+ *                                                由 Codex 从自己的环境转给服务,代理地址和本地 token 不落盘
+ *
+ * provider 不设 requires_openai_auth(默认 false),所以不出现登录页;cli_auth_credentials_store="file"
+ * 不碰系统钥匙串。真实凭证(设备令牌、设备私钥)只留在启动器进程里:子进程环境从 stripSecretEnv 起步、
+ * 再显式写入上面几项;本地 token 只对本进程的签名代理有效,进程退出即作废。
+ * 不改二进制,不删除也不禁用它自带的登录方式(`codex login` 照常可用,凭据落在上面的 CODEX_HOME)。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writePrivateFile } from "../config.js";
+import { lang, tr } from "../i18n.js";
+import { MCP_ENV_NAMES, MCP_SERVER_NAME, MCP_TRACE_ENV, mcpInjectionDisabled, mcpLaunchEnv, mcpServerCommand, } from "../mcp-server.js";
+import { stripSecretEnv } from "../secret-env.js";
+import { AGENT_PROFILES, agentsRoot, prepareAgentLaunch, runPreparedAgent } from "./launch.js";
+import { runtimePaths } from "./runtime.js";
+export const CODEX_GATEWAY_AGENT = "codex";
+/** config.toml 里我们的 provider id(不能用 openai、ollama 等内置保留名)。 */
+export const CODEX_PROVIDER_ID = "u1s1";
+/** provider 的 env_key:子进程环境里放本地 token 的变量名。 */
+export const CODEX_KEY_ENV = "U1S1_LOCAL_KEY";
+export function codexPaths(root = agentsRoot()) {
+    const base = runtimePaths(root, "codex");
+    const home = join(base.root, "home");
+    return {
+        ...base,
+        configDir: home,
+        configToml: join(home, "config.toml"),
+        catalogFile: join(base.root, "model-catalog.json"),
+        configCache: join(base.root, "agent-config.json"),
+    };
+}
+/**
+ * 子进程环境里要去掉的变量(依据 Codex 0.167.2 源码):
+ *   - 会换掉配置/状态目录的:CODEX_HOME(我们自己设)、CODEX_SQLITE_HOME(状态库改放别处,
+ *     可能是用户自己的目录);
+ *   - 别的凭证:OPENAI_API_KEY、CODEX_API_KEY(`codex exec` 读它当 API Key 登录)、CODEX_ACCESS_TOKEN;
+ *     我们的 provider 只用 env_key,但有了它们 Codex 会以为已登录官方账号,去做相应的事;
+ *   - 改官方 provider 地址的 OPENAI_BASE_URL(老版本读,0.167.2 只在它的网络代理里用);
+ *   - 改请求形状的:CODEX_INTERNAL_ORIGINATOR_OVERRIDE 会换掉 originator 头和 User-Agent 前缀,
+ *     网关的客户端判定看这两样;
+ *   - 「由某包管理器管理」的标记(CODEX_MANAGED_BY_*、CODEX_MANAGED_PACKAGE_ROOT):会让它提示用
+ *     npm/bun 等升级,更新由启动器管。
+ * 只影响这一次启动的子进程环境,用户自己的 shell 与配置不动。
+ */
+export const CODEX_ENV_DROP = [
+    "CODEX_HOME",
+    "CODEX_SQLITE_HOME",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "CODEX_API_KEY",
+    "CODEX_ACCESS_TOKEN",
+    "CODEX_INTERNAL_ORIGINATOR_OVERRIDE",
+    "CODEX_MANAGED_BY_NPM",
+    "CODEX_MANAGED_BY_BUN",
+    "CODEX_MANAGED_BY_PNPM",
+    "CODEX_MANAGED_BY_VITE_PLUS",
+    "CODEX_MANAGED_PACKAGE_ROOT",
+    CODEX_KEY_ENV,
+    // u1s1 工具服务的变量只由启动器设;关掉注入时也不留用户环境里的旧值
+    ...MCP_ENV_NAMES.filter((name) => name !== "U1S1_LANG"),
+];
+/**
+ * 本机代理地址不走用户的 HTTP(S)_PROXY:0.167.2 实测,设了 HTTP_PROXY / HTTPS_PROXY 又没有 NO_PROXY 时,
+ * Codex 把发往 http://127.0.0.1:<端口>/v1/responses 的请求也交给那个代理(连同本地 token),
+ * 代理不在本机就直接失败。用户原有的 NO_PROXY 条目保留,只补上 127.0.0.1 和 localhost。
+ */
+export function withLoopbackNoProxy(value) {
+    const entries = (value ?? "").split(",").map((e) => e.trim()).filter(Boolean);
+    for (const host of ["127.0.0.1", "localhost"])
+        if (!entries.includes(host))
+            entries.push(host);
+    return entries.join(",");
+}
+export function codexLaunchEnv(input) {
+    const env = stripSecretEnv(input.baseEnv);
+    for (const key of CODEX_ENV_DROP)
+        delete env[key];
+    env["CODEX_HOME"] = input.home;
+    env[CODEX_KEY_ENV] = input.localToken;
+    if (input.mcp)
+        Object.assign(env, input.mcp);
+    const noProxy = withLoopbackNoProxy([env["NO_PROXY"], env["no_proxy"]].filter(Boolean).join(","));
+    env["NO_PROXY"] = noProxy;
+    env["no_proxy"] = noProxy;
+    return env;
+}
+/** -c 的值按 TOML 解析;用 JSON 字符串字面量(也是合法的 TOML 基本字符串)。 */
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * 启动器的 -c 覆盖放在用户参数前面:用户自己传的 -c / -m / --profile 照样生效(同名 -c 以后出现的为准)。
+ * @param proxyOrigin 签名代理的 origin,形如 http://127.0.0.1:12345(不带 /v1)
+ */
+export function codexLaunchArgs(proxyOrigin, userArgs) {
+    if (!/^http:\/\/127\.0\.0\.1:\d+$/.test(proxyOrigin)) {
+        throw new Error(`proxy origin must be a loopback origin without a path: ${proxyOrigin}`);
+    }
+    return [
+        "-c", `model_providers.${CODEX_PROVIDER_ID}.base_url=${tomlString(`${proxyOrigin}/v1`)}`,
+        "-c", `model_provider=${tomlString(CODEX_PROVIDER_ID)}`,
+        // 不起/不连「共享后台服务」:那是跨会话常驻的进程,会带着上一次的端口和本地 token;有 -c 时
+        // 它本来也会退回进程内模式,只是每次启动都弹一条警告(0.167.2 实测)
+        "-c", "features.daemon_auto_start=false",
+        // 关掉直连官方的两类后台请求:指标上报、插件同步(0.167.2 实测关掉后工具调用、子代理、/compact、
+        // /model 都正常;交互界面启动时拉一次公告没有公开开关,保留)
+        "-c", "analytics.enabled=false",
+        "-c", "features.plugins=false",
+        ...userArgs,
+    ];
+}
+// ---------------------------------------------------------------- config.toml
+/**
+ * 启动器管的顶层键:每次启动重写;不在这里的键(包括 Codex 自己写的项目信任)原样保留。
+ * model 每次都写成「用户在 u1s1 config 里定的模型(仍在阵容里时),否则网关默认」:Codex 里用 /model 换的
+ * 模型只管那一次会话,和 u1s1 claude 一致(那边 --settings 的 model 也盖过客户端里 /model 的选择)。
+ */
+export const CODEX_MANAGED_KEYS = [
+    "model",
+    "model_provider",
+    "check_for_update_on_startup",
+    "cli_auth_credentials_store",
+    "model_catalog_json",
+];
+/**
+ * 跟着模型走的顶层键:Codex 的 /model 把它们和 model 一起写进 config.toml。启动器把 model 换掉时
+ * 一并去掉(回到新模型自己的默认),免得为别的模型选的思考强度带到新模型上;model 没变就保留。
+ */
+export const CODEX_MODEL_BOUND_KEYS = ["model_reasoning_effort"];
+const MANAGED_HEADER = [
+    "# u1s1: the keys right below this comment and the [model_providers.u1s1] and [mcp_servers.u1s1] tables",
+    "# are rewritten every time u1s1 codex starts; everything else in this file is kept as is.",
+];
+/** 旧版的说明行(只提 provider 表),重写时一并去掉 */
+const LEGACY_MANAGED_HEADER = [
+    "# u1s1: the keys right below this comment and the [model_providers.u1s1] table are rewritten",
+    "# every time u1s1 codex starts; everything else in this file is kept as is.",
+];
+const LEGACY_MANAGED_MARK = "# u1s1:";
+const HEADER_RE = /^\s*\[\[?\s*([^\]]*?)\s*\]\]?\s*(?:#.*)?$/;
+/** 表头名规范化:去掉各段的引号与空白(`model_providers."u1s1"` → `model_providers.u1s1`)。 */
+function tableName(raw) {
+    return raw.split(".").map((part) => part.trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1")).join(".");
+}
+function keyOf(line) {
+    const m = /^\s*("([^"]*)"|'([^']*)'|[A-Za-z0-9_.-]+)\s*=/.exec(line);
+    if (!m)
+        return undefined;
+    return m[2] ?? m[3] ?? m[1].split(".").map((p) => p.trim()).join(".");
+}
+/** `key = "值"` / `key = '值'` 的字符串值;别的写法返回 undefined。 */
+function stringValueOf(line) {
+    const m = /=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\s*(?:#.*)?$/.exec(line);
+    if (!m)
+        return undefined;
+    if (m[2] !== undefined)
+        return m[2];
+    try {
+        return JSON.parse(`"${m[1]}"`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 值是不是在这一行内结束的简单值(多行字符串、跨行数组/内联表都不算)。 */
+function singleLineValue(line) {
+    const value = line.slice(line.indexOf("=") + 1).trim();
+    return !/^("""|'''|\[|\{)/.test(value);
+}
+function providerTable() {
+    return [
+        `[model_providers.${CODEX_PROVIDER_ID}]`,
+        `name = ${tomlString("u1s1")}`,
+        // 真正的地址每次由 -c 覆盖;直接用这个目录起 codex 时连不上,不会把请求发到别处
+        `base_url = ${tomlString("http://127.0.0.1:0/v1")}`,
+        `env_key = ${tomlString(CODEX_KEY_ENV)}`,
+        `env_key_instructions = ${tomlString(tr("请用 u1s1 codex 启动。", "Start it with u1s1 codex."))}`,
+        `wire_api = ${tomlString("responses")}`,
+        "requires_openai_auth = false",
+    ];
+}
+function mcpTable(server) {
+    return [
+        `[mcp_servers.${MCP_SERVER_NAME}]`,
+        `command = ${tomlString(server.command)}`,
+        `args = [${server.args.map(tomlString).join(", ")}]`,
+        // 超时用 Codex 的默认值(0.167.2 源码:启动 30 秒、单次调用 300 秒;生图最长约 150 秒加下载,够用)
+        `env_vars = [${server.envVars.map(tomlString).join(", ")}]`,
+    ];
+}
+/** 受管的表:我们整段重写的 `[model_providers.u1s1]`、`[mcp_servers.u1s1]` 及其子表。 */
+const MANAGED_TABLES = [`model_providers.${CODEX_PROVIDER_ID}`, `mcp_servers.${MCP_SERVER_NAME}`];
+function isManagedTable(section) {
+    return MANAGED_TABLES.some((t) => section === t || section.startsWith(`${t}.`));
+}
+/**
+ * `[mcp_servers.u1s1.tools.<工具>]`:用户在 Codex 里对某个工具选「总是允许」时,Codex 写在这里
+ * (0.167.2 实测写 `approval_mode = "approve"`)。注入时原样保留、放在我们的表后面;不注入时去掉
+ * (只剩子表没有 command,Codex 会当成配置不完整)。
+ */
+function isMcpToolTable(section) {
+    return section.startsWith(`mcp_servers.${MCP_SERVER_NAME}.tools.`);
+}
+function managedTopLevel(model) {
+    const lines = [...MANAGED_HEADER];
+    if (model.model)
+        lines.push(`model = ${tomlString(model.model)}`);
+    lines.push(`model_provider = ${tomlString(CODEX_PROVIDER_ID)}`, 
+    // 更新由启动器管(max_tested_version 以内),不让它自己查、也不弹升级提示
+    "check_for_update_on_startup = false", 
+    // 凭据(如果用户自己 codex login)写在 CODEX_HOME 的文件里,不碰系统钥匙串
+    `cli_auth_credentials_store = ${tomlString("file")}`);
+    if (model.catalogFile)
+        lines.push(`model_catalog_json = ${tomlString(model.catalogFile)}`);
+    return lines;
+}
+/**
+ * 生成新的 config.toml。保守做法:不解析整份 TOML,只逐行处理我们管的东西——
+ *   - 顶层(第一个表头之前)的受管键整行去掉,换成新值,放在文件最前面;
+ *   - `[model_providers.u1s1]`、`[mcp_servers.u1s1]` 及其子表整段去掉,换成新的放在最后
+ *     (例外:用户对 u1s1 工具的审批选择 `[mcp_servers.u1s1.tools.*]`,注入时跟在新表后面保留);
+ *   - 其余每一行(用户加的键、别的表、注释、Codex 自己写的项目信任等)原样保留,顺序不变。
+ * 遇到没法逐行安全改写的写法(受管键是跨行值、在顶层或 [model_providers] 表里用点号/内联表写我们的
+ * provider)就整份重写,由调用方先把原文件备份。
+ */
+export function renderCodexConfig(existing, managed) {
+    const top = managedTopLevel(managed);
+    const table = [...providerTable(), ...(managed.mcp ? ["", ...mcpTable(managed.mcp)] : [])];
+    const fresh = () => [...top, "", ...table, ""].join("\n");
+    if (existing === undefined || existing.trim() === "")
+        return { text: fresh(), replaced: false };
+    const managedKeys = new Set(CODEX_MANAGED_KEYS);
+    const modelBound = new Set(CODEX_MODEL_BOUND_KEYS);
+    // 原文件顶层的 model;和这次要写的不同(或读不出)时,跟着模型走的键一起去掉
+    let previousModel;
+    for (const line of existing.replace(/\r\n/g, "\n").split("\n")) {
+        const header = HEADER_RE.exec(line);
+        if (header && !/^\s*#/.test(line))
+            break;
+        if (keyOf(line) === "model")
+            previousModel = stringValueOf(line);
+    }
+    const modelChanged = previousModel !== (managed.model ?? undefined);
+    const keptTop = [];
+    const keptTables = [];
+    const keptMcpTools = [];
+    let section = null; // null = 顶层
+    let skipping = false;
+    let inMcpTools = false;
+    let unsafe = false;
+    for (const line of existing.replace(/\r\n/g, "\n").split("\n")) {
+        const header = HEADER_RE.exec(line);
+        if (header && !/^\s*#/.test(line)) {
+            section = tableName(header[1] ?? "");
+            inMcpTools = isMcpToolTable(section);
+            skipping = !inMcpTools && isManagedTable(section);
+            if (inMcpTools)
+                keptMcpTools.push(line);
+            else if (!skipping)
+                keptTables.push(line);
+            continue;
+        }
+        if (skipping)
+            continue;
+        if (inMcpTools) {
+            keptMcpTools.push(line);
+            continue;
+        }
+        const key = keyOf(line);
+        if (section === null) {
+            if (line.startsWith(LEGACY_MANAGED_MARK) || MANAGED_HEADER.includes(line) || LEGACY_MANAGED_HEADER.includes(line))
+                continue;
+            if (key && managedKeys.has(key)) {
+                if (!singleLineValue(line))
+                    unsafe = true;
+                continue;
+            }
+            if (key && modelChanged && modelBound.has(key) && singleLineValue(line))
+                continue;
+            if (key && (key === "model_providers" || key.startsWith("model_providers.")))
+                unsafe = true;
+            if (key && (key === "mcp_servers" || key.startsWith(`mcp_servers.${MCP_SERVER_NAME}`)))
+                unsafe = true;
+            keptTop.push(line);
+        }
+        else {
+            if (section === "model_providers" && key && (key === CODEX_PROVIDER_ID || key.startsWith(`${CODEX_PROVIDER_ID}.`)))
+                unsafe = true;
+            if (section === "mcp_servers" && key && (key === MCP_SERVER_NAME || key.startsWith(`${MCP_SERVER_NAME}.`)))
+                unsafe = true;
+            keptTables.push(line);
+        }
+    }
+    if (unsafe)
+        return { text: fresh(), replaced: true };
+    const trimBlank = (lines) => {
+        while (lines.length && lines[0].trim() === "")
+            lines.shift();
+        while (lines.length && lines[lines.length - 1].trim() === "")
+            lines.pop();
+        return lines;
+    };
+    const parts = [top.join("\n")];
+    if (trimBlank(keptTop).length)
+        parts.push(keptTop.join("\n"));
+    if (trimBlank(keptTables).length)
+        parts.push(keptTables.join("\n"));
+    parts.push(table.join("\n"));
+    if (managed.mcp && trimBlank(keptMcpTools).length)
+        parts.push(keptMcpTools.join("\n"));
+    return { text: parts.join("\n\n") + "\n", replaced: false };
+}
+/** 网关 settings.model_catalog:必须是对象才写;CLI 不解析、不改它的内容。 */
+export function modelCatalogFromConfig(config) {
+    const catalog = config.settings?.["model_catalog"];
+    return catalog && typeof catalog === "object" && !Array.isArray(catalog) ? catalog : undefined;
+}
+/**
+ * 写 model-catalog.json 与 config.toml。返回原 config.toml 被整份重写时的备份路径(给用户一句说明)。
+ */
+export function writeCodexConfig(paths, config, now = Date.now, mcp = null, 
+/** 这次启动用的模型(launch.ts 按 u1s1 config 选好);undefined = 网关默认 */
+model = config.defaultModel) {
+    mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
+    const catalog = modelCatalogFromConfig(config);
+    if (catalog)
+        writePrivateFile(paths.catalogFile, JSON.stringify(catalog) + "\n");
+    else
+        rmSync(paths.catalogFile, { force: true });
+    let existing;
+    try {
+        existing = readFileSync(paths.configToml, "utf8");
+    }
+    catch {
+        existing = undefined;
+    }
+    const rendered = renderCodexConfig(existing, {
+        model,
+        catalogFile: catalog ? paths.catalogFile : null,
+        mcp,
+    });
+    let backup;
+    if (rendered.replaced && existing !== undefined && existsSync(paths.configToml)) {
+        backup = `${paths.configToml}.${now()}.bak`;
+        renameSync(paths.configToml, backup);
+    }
+    if (rendered.text !== existing)
+        writePrivateFile(paths.configToml, rendered.text);
+    return backup;
+}
+/** [mcp_servers.u1s1] 的内容:同一个 node、同一份 CLI;只列要转发的变量名。 */
+export function codexMcpServer(command = mcpServerCommand(), env = process.env) {
+    const envVars = [...MCP_ENV_NAMES];
+    if (env[MCP_TRACE_ENV])
+        envVars.push(MCP_TRACE_ENV);
+    return { ...command, envVars };
+}
+// ---------------------------------------------------------------- run
+/**
+ * `u1s1 codex [参数…]`。返回子进程的退出码(启动前就失败返回 1)。
+ * 是否可用完全由网关配置的 enabled 决定(prepareAgentLaunch)。
+ */
+export async function runCodex(userArgs) {
+    const paths = codexPaths();
+    const prepared = await prepareAgentLaunch(AGENT_PROFILES.codex, paths);
+    if (typeof prepared === "number")
+        return prepared;
+    const mcp = mcpInjectionDisabled()
+        ? undefined
+        : mcpLaunchEnv({ proxyBaseUrl: prepared.proxy.baseUrl, localToken: prepared.proxy.localKey, features: prepared.features, lang: lang() });
+    const backup = writeCodexConfig(paths, prepared.config, Date.now, mcp ? codexMcpServer() : null, prepared.model);
+    if (backup) {
+        console.error(tr(`  ${paths.configToml} 里有 u1s1 没法逐项改写的写法,已整份重写;原文件备份在 ${backup}。`, `  ${paths.configToml} had entries u1s1 couldn't update in place, so it was rewritten; the original is saved as ${backup}.`));
+    }
+    const env = codexLaunchEnv({ baseEnv: process.env, localToken: prepared.proxy.localKey, home: paths.configDir, mcp });
+    const args = codexLaunchArgs(new URL(prepared.proxy.baseUrl).origin, userArgs);
+    return runPreparedAgent({ agent: "codex", paths, prepared, args, env, userArgs });
+}

package/dist/agents/launch.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 官方原版客户端(`u1s1 claude` / `u1s1 codex`)共用的启动流程与文案:
+ * 登录 → 经签名代理拉网关配置(开关、刹车、阵容)→ 找到/下载原版 → 起声明了客户端的签名代理 →
+ * 由各客户端模块写配置、拼环境 → 子进程继承终端 → 透传退出码;顺带每天查一次新版。
+ *
+ * 各客户端只提供 AgentProfile(名字、条款、路径)和「怎么注入」,下载、刹车、文案都在这里一份。
+ */
+import { spawn } from "node:child_process";
+import { type ApiFeatures } from "../api.js";
+import { type SiteId } from "../site.js";
+import { type AgentConfig, type GatewayAgentName } from "./agent-config.js";
+import { RuntimePlanError, type DownloadInfo, type EnsuredRuntime, type InstallHooks, type ManagedAgent, type RuntimePaths, type SkippedRuntime } from "./runtime.js";
+export declare function agentsRoot(): string;
+export interface AgentProfile {
+    /** 子命令名,也是 ~/.u1s1/agents 下的目录名 */
+    agent: ManagedAgent;
+    /** 网关里的客户端名(/v1/agents/:agent/config、x-u1s1-agent) */
+    gatewayAgent: Extract<GatewayAgentName, "claude-code" | "codex">;
+    /** 产品名(只作事实陈述,如「官方 Claude Code」) */
+    product: string;
+    /** 下载前提示里的许可/条款一行 */
+    termsLine: () => string;
+    /** 下载前提示里的安装位置一行 */
+    locationLine: () => string;
+}
+export declare const CLAUDE_TERMS_URL = "https://code.claude.com/docs/en/legal-and-compliance";
+export declare const CODEX_LICENSE_URL = "https://github.com/openai/codex/blob/main/LICENSE";
+export declare const AGENT_PROFILES: Record<ManagedAgent, AgentProfile>;
+/**
+ * 请求本机签名代理(http://127.0.0.1:<端口>)专用:直连,不走用户的 HTTP(S)_PROXY。
+ * 全局 dispatcher 认 HTTP_PROXY,用户没在 NO_PROXY 里写 127.0.0.1 时,连本机代理的请求也会交给
+ * 那个代理;远端代理连不到用户本机,首次启动(还没有配置缓存)就报「拿不到启动配置」。
+ * 签名代理到网关那一跳不受影响,照旧按用户的代理设置走。
+ */
+export declare function loopbackFetch(url: string, init: RequestInit): Promise<Response>;
+/**
+ * 起子进程、继承终端、等它退出、透传退出码。
+ *
+ * 信号:Ctrl+C / Ctrl+\ 由终端直接发给整个前台进程组,子进程自己会收到;启动器只要不被它们
+ * 打死就行,不再转发(转发会让子进程收到两次,交互界面里「按两次 Ctrl+C 退出」就成了按一次)。
+ * SIGTERM / SIGHUP 通常只发给启动器(kill、关窗口),转发给子进程。
+ * 签名代理的监听是 unref 的:必须等子进程退出后再返回。
+ */
+export declare function spawnAgent(bin: string, args: readonly string[], env: NodeJS.ProcessEnv, deps?: {
+    spawn?: typeof spawn;
+    proc?: Pick<NodeJS.Process, "on" | "off">;
+}): Promise<number>;
+export declare function consentLines(info: DownloadInfo): string[];
+export declare function cliInstallHooks(agent?: ManagedAgent): InstallHooks;
+/** 已有的某份客户端高于 max_tested、这次不用它。 */
+export declare function overMaxTestedText(s: SkippedRuntime, agent?: ManagedAgent): string;
+/** ensureAgentRuntime 抛出的错误 → 给用户的几行说明。不认识的错误返回 false(调用方再抛)。 */
+export declare function printRuntimeFailure(e: unknown, agent?: ManagedAgent): boolean;
+export declare function notOpenText(): string;
+export declare function runtimeErrorText(e: RuntimePlanError, agent?: ManagedAgent): string;
+/** 运行时的两条附带提示:pin 被忽略、更新没装上。 */
+export declare function printRuntimeNotes(runtime: EnsuredRuntime, agent: ManagedAgent): void;
+export interface LaunchPaths extends RuntimePaths {
+    /** 客户端自己的配置目录(CLAUDE_CONFIG_DIR / CODEX_HOME);探测版本时也指到这里 */
+    configDir: string;
+    /** 上次成功拉到的 /v1/agents/:agent/config */
+    configCache: string;
+}
+export interface PreparedLaunch {
+    config: AgentConfig;
+    /** 这次启动用的模型:用户在 u1s1 config 里选的(仍在阵容里时),否则网关默认 */
+    model: string | null;
+    /** u1s1 config 的 <客户端>.auto-update;关着时不做每日查新 */
+    autoUpdate: boolean;
+    runtime: EnsuredRuntime;
+    /** 声明了客户端名与版本的签名代理 */
+    proxy: {
+        baseUrl: string;
+        localKey: string;
+    };
+    site: SiteId;
+    /** /v1/models 的能力开关(搜索、云端渲染、生图);没拉到时为 undefined。MCP 工具服务按它决定提供哪些工具 */
+    features: ApiFeatures | undefined;
+}
+/**
+ * 子进程启动前的公共部分。返回 number = 启动前就失败的退出码(已向用户说明)。
+ * 是否可用完全由网关配置的 enabled 决定:停用时显示 disabled_reason,不下载、不启动。
+ */
+export declare function prepareAgentLaunch(profile: AgentProfile, paths: LaunchPaths): Promise<PreparedLaunch | number>;
+/** 用户在 u1s1 config 里选的模型不在当前阵容里(只提示一次,见 prefs.ts)。 */
+export declare function modelMissingText(agent: ManagedAgent, missing: string, fallback: string | null): string;
+/** configDir 下这次运行(since 之后)写过的最新会话的 id。 */
+export declare function latestSessionId(agent: ManagedAgent, configDir: string, since: number): string | undefined;
+/**
+ * 只在交互界面正常退出后提示:脚本调用(codex exec、claude -p)客户端自己也不打印续接提示,
+ * 我们也不加。
+ */
+export declare function wantsResumeHint(agent: ManagedAgent, userArgs: readonly string[], interactive: boolean): boolean;
+export declare function resumeHintText(agent: ManagedAgent, id: string): string;
+/**
+ * 起子进程并等它退出;同时每天最多查一次新版(只管启动器自己装的那份),下次启动前更新,不挡启动。
+ * 用户关了自动更新(u1s1 config)就不查。
+ */
+export declare function runPreparedAgent(input: {
+    agent: ManagedAgent;
+    paths: RuntimePaths & {
+        configDir?: string;
+    };
+    /** 用户自己的参数(不含启动器加的);判断要不要补续接提示 */
+    userArgs?: readonly string[];
+    prepared: PreparedLaunch;
+    args: readonly string[];
+    env: NodeJS.ProcessEnv;
+}): Promise<number>;