niceeval 0.12.1 → 0.12.2-canary.31

package/dist/agents/codex.cjs

@@ -0,0 +1,658 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexAgent = codexAgent;
+exports.installPlugins = installPlugins;
+const coverage_ts_1 = require("../assertions/coverage.cjs");
+const effect_1 = require("effect");
+const define_ts_1 = require("../define.cjs");
+const util_ts_1 = require("../util.cjs");
+const shared_ts_1 = require("./shared.cjs");
+const skills_ts_1 = require("./skills.cjs");
+const marketplace_ts_1 = require("./marketplace.cjs");
+const native_config_ts_1 = require("./native-config.cjs");
+const codex_ts_1 = require("../o11y/otlp/mappers/codex.cjs");
+const command_projection_ts_1 = require("../o11y/command-projection.cjs");
+const index_ts_1 = require("../i18n/index.cjs");
+const coding_cli_versions_ts_1 = require("./coding-cli-versions.cjs");
+const mcp_ts_1 = require("./mcp.cjs");
+const post_setup_ts_1 = require("./post-setup.cjs");
+const npm_staged_ts_1 = require("./npm-staged.cjs");
+const send_failures_ts_1 = require("../context/send-failures.cjs");
+const external_cause_ts_1 = require("../shared/external-cause.cjs");
+// ───────────────────────────────────────────────────────────────────────────
+// OpenAI Codex CLI 的 agent adapter(沙箱型)。
+//
+// 连接方式:在沙箱里 spawn `codex exec --json`,stdout JSONL → parseCodex → 标准事件流。
+// 配置:鉴权本地(config / env),模型交给实验(ctx.model),推理努力程度经 ctx.reasoningEffort,
+// 其余参数经 ctx.flags。
+// 扩展(skill / plugin / MCP)是构造参数,setup 翻译成 codex 的原生形态并写 manifest。
+// ───────────────────────────────────────────────────────────────────────────
+/** codex 的 skill 目录(`skills` 生态的「通用」目录);codex 不原生扫描它,靠下面的发现指引。 */
+const SKILL_DIR = ".agents/skills";
+/**
+ * `configFile` 的保留键:model / provider 路由 / 推理努力归 experiment 与 Adapter 的生成层,
+ * MCP 表与 OTel 导出归 Adapter。清单定稿见 docs/feature/adapters/sdk/codex-cli/README.md。
+ */
+const RESERVED_CONFIG_KEYS = [
+    "model",
+    "model_provider",
+    "model_providers",
+    "model_reasoning_effort",
+    "mcp_servers",
+    "otel",
+];
+const CODEX_CAPACITY_CODES = new Set([
+    "ADMISSION_FAILED",
+    "ADMISSION_FAILURE",
+    "ADMISSION_REJECTED",
+    "MODEL_AT_CAPACITY",
+    "MODEL_CAPACITY",
+    "MODEL_OVERLOADED",
+]);
+function normalizedCodexCode(value) {
+    if (typeof value !== "string")
+        return undefined;
+    return value.trim().toUpperCase().replace(/[ -]+/g, "_");
+}
+function codexCapacityCode(raw) {
+    if (raw === undefined)
+        return undefined;
+    for (const line of raw.split("\n")) {
+        try {
+            const value = JSON.parse(line);
+            if (!value || typeof value !== "object")
+                continue;
+            const record = value;
+            const error = record.error;
+            const candidates = [
+                record.code,
+                record.reason,
+                record.type,
+                error && typeof error === "object" ? error.code : undefined,
+                error && typeof error === "object" ? error.reason : undefined,
+                error && typeof error === "object" ? error.type : undefined,
+            ];
+            const code = candidates.map(normalizedCodexCode).find((candidate) => candidate !== undefined && CODEX_CAPACITY_CODES.has(candidate));
+            if (code !== undefined)
+                return code;
+        }
+        catch {
+            // Native stderr fallback is handled separately and remains deliberately narrow.
+        }
+    }
+    return undefined;
+}
+function codexCapacityMessage(raw) {
+    if (raw === undefined)
+        return "";
+    const messages = [];
+    for (const line of raw.split("\n")) {
+        try {
+            const value = JSON.parse(line);
+            if (!value || typeof value !== "object")
+                continue;
+            const record = value;
+            if (record.type !== "turn.failed" && record.type !== "response.failed")
+                continue;
+            const error = record.error;
+            if (error && typeof error === "object") {
+                const message = error.message;
+                if (typeof message === "string")
+                    messages.push(message);
+            }
+        }
+        catch {
+            // Native stderr fallback is handled separately and remains deliberately narrow.
+        }
+    }
+    return messages.join("\n");
+}
+const CODEX_CAPACITY_TEXT = /\bmodel(?:[ _-]+is)?[ _-]+at[ _-]+capacity\b|\badmission[ _-]+(?:failed|failure|rejected)\b/i;
+function codexCapacityFromFailure(failure) {
+    if (failure.acceptance !== "rejected")
+        return false;
+    if (failure.events !== undefined && (0, send_failures_ts_1.sendAcceptanceFromEvents)(failure.events) === "started")
+        return false;
+    for (let cause = failure.cause; cause !== undefined;) {
+        if (cause._tag === "Error" || cause._tag === "Object") {
+            const code = cause.code._tag === "Present" ? normalizedCodexCode(cause.code.value) : undefined;
+            if (code !== undefined && CODEX_CAPACITY_CODES.has(code))
+                return true;
+            cause = cause.cause._tag === "Cause" ? cause.cause.value : undefined;
+            continue;
+        }
+        cause = undefined;
+    }
+    return CODEX_CAPACITY_TEXT.test((0, send_failures_ts_1.sendFailureText)(failure));
+}
+function classifyCodexSendFailure(failure) {
+    return codexCapacityFromFailure(failure) ? { retryable: true, reason: "model_capacity" } : undefined;
+}
+function codexAcceptance(raw, events, nativeErrorText = "") {
+    const acceptance = (0, send_failures_ts_1.sendAcceptanceFromEvents)(events);
+    if (acceptance === "started")
+        return "started";
+    return codexCapacityCode(raw) !== undefined || CODEX_CAPACITY_TEXT.test(`${codexCapacityMessage(raw)}\n${nativeErrorText}`)
+        ? "rejected"
+        : acceptance;
+}
+/**
+ * `@openai/codex` 的 npm 主包只是个 node shim,真正的 CLI 在平台包里
+ * (`npm:@openai/codex@<ver>-linux-arm64`),是自带运行时的 musl 静态二进制。
+ * 装这一份:沙箱里不需要 node / npm,任务镜像带什么都能装。
+ */
+function codexPlatformPackage(platform, version) {
+    const target = platform.os === "linux" && platform.arch === "x64"
+        ? { suffix: "linux-x64", triple: "x86_64-unknown-linux-musl" }
+        : platform.os === "linux" && platform.arch === "arm64"
+            ? { suffix: "linux-arm64", triple: "aarch64-unknown-linux-musl" }
+            : platform.os === "darwin" && platform.arch === "x64"
+                ? { suffix: "darwin-x64", triple: "x86_64-apple-darwin" }
+                : platform.os === "darwin" && platform.arch === "arm64"
+                    ? { suffix: "darwin-arm64", triple: "aarch64-apple-darwin" }
+                    : undefined;
+    if (target === undefined)
+        return undefined;
+    return {
+        spec: `@openai/codex@${version}-${target.suffix}`,
+        binPath: `vendor/${target.triple}/bin/codex`,
+    };
+}
+// Codex 0.144.1 会把「hook 命令已正常退出、随后写 stdin 撞 BrokenPipe」误判成 hook
+// 失败并丢掉 stdout。0.146.0 的官方 command runner 已忽略这个竞态；配置 Plugin 时必须
+// 选择包含该修复的 CLI。未配置 Plugin 的官方基线仍保持当前已发布版本，避免引用尚未发布
+// 的 Docker/E2B 制品。
+const CODEX_PLUGIN_HOOK_SAFE_CLI_VERSION = "0.146.0";
+function codexAgent(config) {
+    const getApiKey = () => config?.apiKey ?? (0, util_ts_1.requireEnv)("CODEX_API_KEY");
+    const getBaseUrl = () => config?.baseUrl ?? (0, util_ts_1.getEnv)("CODEX_BASE_URL");
+    // PATH 是 Sandbox 受管变量,在 factory 构造时(link/配置校验期)同步拒绝,不留到 setup()
+    // 才炸,也不静默丢弃——被覆盖的 PATH 会让 hooks / 子进程读到错误的可执行文件而零报错
+    // (见 docs/feature/sandbox/library.md「PATH:受管变量与 pathPrepend」)。
+    if (config?.env && "PATH" in config.env) {
+        throw new TypeError((0, index_ts_1.t)("codex.envPathManaged"));
+    }
+    // factory 构造时快照：一份 Agent 配置服务并发 attempt，不能让调用方随后改原对象造成
+    // 不同 run/resume 轮拿到不同 Space。值不进入 shell 或 manifest，只交给 command options。
+    const agentEnv = Object.freeze({ ...(config?.env ?? {}) });
+    const agentEnvSensitiveValues = Object.freeze(Object.values(agentEnv));
+    const cliVersion = config?.plugins?.length
+        ? CODEX_PLUGIN_HOOK_SAFE_CLI_VERSION
+        : coding_cli_versions_ts_1.DEFAULT_CODEX_CLI_VERSION;
+    const cliRecipeRevision = config?.plugins?.length
+        ? "plugin-hook-safe-r1"
+        : String(coding_cli_versions_ts_1.AGENT_BASELINE_RECIPE_REVISION.codex);
+    const { ensure, installer } = (0, npm_staged_ts_1.createNpmCliInstaller)({
+        identity: {
+            agent: "codex",
+            version: cliVersion,
+            revision: cliRecipeRevision,
+        },
+        packageName: "@openai/codex",
+        bin: "codex",
+        platformPackage: (platform) => codexPlatformPackage(platform, cliVersion),
+        progress: {
+            checking: `checking Codex CLI ${cliVersion}`,
+            installing: `installing official OpenAI Codex CLI ${cliVersion}`,
+            ready: `Codex CLI ${cliVersion} ready`,
+        },
+    });
+    return (0, post_setup_ts_1.registerAgentLifecycleHookCommands)((0, define_ts_1.defineSandboxAgent)({
+        name: "codex",
+        // 官方 adapter:transcript 经生命周期 fixture 验证,全通道 complete。
+        evidenceCoverage: coverage_ts_1.completeEvidenceCoverage,
+        spanMapper: codex_ts_1.mapCodexSpans,
+        classifySendFailure: classifyCodexSendFailure,
+        ensure,
+        installers: [installer],
+        setup: (sb, ctx) => effect_1.Effect.runPromise(effect_1.Effect.scoped(effect_1.Effect.gen(function* () {
+            // 用户的原生配置文件:本地读原始字节 → 验 TOML 语法与保留键。字节 SHA-256 进
+            // manifest 与安装 checkpoint key(见 native-config.ts 的 nativeConfigCheckpointItem)。
+            let nativeConfig;
+            if (config?.configFile !== undefined) {
+                nativeConfig = yield* (0, native_config_ts_1.loadNativeConfigFileEffect)({ agent: "codex", field: "configFile", path: config.configFile });
+                yield* effect_1.Effect.try({
+                    try: () => (0, native_config_ts_1.assertTomlNativeConfig)(nativeConfig, {
+                        agent: "codex",
+                        field: "configFile",
+                        reservedKeys: RESERVED_CONFIG_KEYS,
+                    }),
+                    catch: (cause) => cause,
+                });
+            }
+            // Codex 把 Plugin 的声明态写在 config.toml、安装体写在 cache。必须在覆盖用户配置前
+            // 同时摘掉两边：覆盖后 `plugin list` 已看不见旧声明，旧安装体却仍会影响下一次 add
+            // 的版本选择。先完整收敛，再写本 Attempt 的唯一配置层。
+            if (config?.plugins?.length) {
+                const plugins = config.plugins;
+                yield* effect_1.Effect.tryPromise({
+                    try: () => resetPluginState(sb, plugins),
+                    catch: (cause) => cause,
+                });
+            }
+            // model 归属:实验决定(ctx.model);省略时不写 model 行,交给 codex CLI 原生默认,
+            // 不在 adapter 里硬编码一个会过期的模型名。
+            const modelLine = ctx.model ? `model = "${ctx.model}"\n` : "";
+            const effortLine = ctx.reasoningEffort === undefined
+                ? ""
+                : `model_reasoning_effort = "${ctx.reasoningEffort}"\n`;
+            const base = getBaseUrl();
+            // 自定义 endpoint 常从项目的私有环境注入。它仍是 Codex 的真实运行配置，但不能因
+            // Adapter 用 heredoc 写 config.toml 而进入 command/timing/error 证据；一旦在这里登记，
+            // Attempt 最终封口也会清掉随后 hook 或 CLI 错误里回显的同一值。
+            const providerSensitiveValues = base ? [base] : [];
+            const topLevel = base
+                ? modelLine + `model_provider = "s2a"\n` + effortLine
+                : modelLine + effortLine;
+            const providerTable = base
+                ? `[model_providers.s2a]\n` +
+                    `name = "s2a"\n` +
+                    `base_url = "${base}"\n` +
+                    `env_key = "CODEX_API_KEY"\n` +
+                    `wire_api = "responses"\n`
+                : "";
+            if (!nativeConfig) {
+                yield* effect_1.Effect.tryPromise({
+                    try: () => shared_ts_1.shared.writeFile(sb, "~/.codex/config.toml", providerTable ? `${topLevel}\n${providerTable}` : topLevel, { sensitiveValues: providerSensitiveValues }),
+                    catch: (cause) => cause,
+                });
+            }
+            else {
+                // codex 只读一份用户级 config.toml(没有 include / 第二配置层),Adapter 生成层与
+                // 用户文件只能同文件分段共存。TOML 没有「回到根表」的语法,顶层键必须先于任何表头,
+                // 所以布局固定为:Adapter 顶层键 → 用户文件原始字节(逐字节保留,自带表随意)→
+                // Adapter 的表([model_providers.*] 以及后续追加的 [mcp_servers.*]、[otel])。
+                // 保留键校验保证两层键不重叠,用户内容不被解析重写。
+                yield* effect_1.Effect.tryPromise({
+                    try: () => shared_ts_1.shared.writeFile(sb, "~/.codex/config.toml", topLevel),
+                    catch: (cause) => cause,
+                });
+                yield* (0, native_config_ts_1.appendNativeConfigFileEffect)(sb, nativeConfig, "~/.codex/config.toml");
+                if (providerTable) {
+                    yield* effect_1.Effect.tryPromise({
+                        try: (signal) => sb.runShell(`cat >> ~/.codex/config.toml <<'NICEEVAL_PROVIDER_EOF'\n\n${providerTable}NICEEVAL_PROVIDER_EOF\n`, { signal, sensitiveValues: providerSensitiveValues }),
+                        catch: (cause) => cause,
+                    });
+                }
+            }
+            yield* effect_1.Effect.tryPromise({
+                try: async (signal) => {
+                    if (config?.mcpServers?.length) {
+                        (0, mcp_ts_1.assertMcpServers)(config.mcpServers);
+                        const sensitiveValues = [];
+                        const mcpToml = config.mcpServers
+                            .map((s) => {
+                            // 注意是复数 mcp_servers:单数 [mcp_server.x] 会被 codex 静默忽略,
+                            // MCP 压根挂不上(实测 codex-cli 0.142.x,`codex mcp list` 可核对)。
+                            const lines = [`[mcp_servers.${s.name}]`];
+                            if ((0, mcp_ts_1.isHttpMcp)(s)) {
+                                lines.push(`url = "${s.url}"`);
+                                const headers = s.headers;
+                                if (headers && Object.keys(headers).length) {
+                                    lines.push(`[mcp_servers.${s.name}.http_headers]`);
+                                    for (const [k, v] of Object.entries(headers)) {
+                                        sensitiveValues.push(v);
+                                        lines.push(`"${k}" = "${v}"`);
+                                    }
+                                }
+                            }
+                            else {
+                                lines.push(`command = "${s.command}"`);
+                                if (s.args?.length)
+                                    lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
+                                const env = s.env;
+                                if (env && Object.keys(env).length) {
+                                    lines.push(`[mcp_servers.${s.name}.env]`);
+                                    for (const [k, v] of Object.entries(env)) {
+                                        sensitiveValues.push(v);
+                                        lines.push(`${k} = "${v}"`);
+                                    }
+                                }
+                            }
+                            return lines.join("\n");
+                        })
+                            .join("\n\n");
+                        await sb.runShell(`cat >> ~/.codex/config.toml <<'MCPEOF'\n\n${mcpToml}\nMCPEOF\n`, { sensitiveValues, signal });
+                    }
+                    const manifest = { skills: [] };
+                    if (config?.skills?.length) {
+                        manifest.skills = await (0, skills_ts_1.installSkills)(sb, config.skills, { dir: SKILL_DIR });
+                        // 发现指引不是可选装饰:没有它,codex 连一次读 skill 文件的 shell 调用都不会发生。
+                        await (0, skills_ts_1.appendProjectInstruction)(sb, (0, skills_ts_1.skillDiscoveryInstruction)(SKILL_DIR, (0, skills_ts_1.installedSkillNames)(manifest.skills)));
+                    }
+                    if (config?.plugins?.length) {
+                        manifest.nativePlugins = await installPluginsFromResetState(sb, config.plugins);
+                    }
+                    if (config?.mcpServers?.length) {
+                        // manifest 只记「挂了哪个 server、怎么连」;env / headers 里可能有 token,不落盘。
+                        manifest.mcpServers = (0, mcp_ts_1.mcpManifestEntries)(config.mcpServers);
+                    }
+                    if (nativeConfig) {
+                        // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
+                        manifest.nativeConfigFile = { agent: "codex", path: nativeConfig.path, sha256: nativeConfig.sha256 };
+                    }
+                    if (manifest.skills.length ||
+                        manifest.nativePlugins?.length ||
+                        manifest.mcpServers?.length ||
+                        manifest.nativeConfigFile) {
+                        ctx.reportSetup(manifest);
+                    }
+                    // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+                    // 钩子失败不该丢掉这份证据。
+                    await (0, post_setup_ts_1.runPostSetupHooks)(sb, ctx, "codex", config?.postSetup);
+                },
+                catch: (cause) => cause,
+            });
+        })), { signal: ctx.signal }),
+        async teardown(sb, ctx) {
+            // preTeardown 与 postSetup 成对:LIFO 镜像,先于 agent 自己的收尾步骤执行。
+            // codex 目前没有其它收尾步骤,这段就是整个 teardown。
+            await (0, post_setup_ts_1.runPreTeardownHooks)(sb, ctx, "codex", config?.preTeardown);
+        },
+        tracing: {
+            protocol: "http/json",
+            async configure(sb, ctx) {
+                const endpoint = ctx.telemetry.endpoint;
+                const otel = `\n[otel]\n` +
+                    `environment = "niceeval"\n` +
+                    `exporter = "none"\n` +
+                    `metrics_exporter = "none"\n\n` +
+                    `[otel.trace_exporter.otlp-http]\n` +
+                    `endpoint = "${endpoint}"\n` +
+                    `protocol = "json"\n`;
+                await sb.runShell(`cat >> ~/.codex/config.toml <<'EOF'\n${otel}EOF\n`);
+            },
+        },
+        async send(input, ctx) {
+            const sb = ctx.sandbox;
+            // hook trust bypass 是 runtime-only(config.toml 设不了):headless 下 codex 对非 managed
+            // 来源 hook 的交互式授信永远无人应答,不带它插件装的 hook 会被静默跳过、零报错
+            // (见 memory/codex-hook-trust-headless-silent-skip.md)。沙箱内 hook 来源全部由实验配置
+            // 声明,与 approvals/sandbox bypass 同一信任层级。
+            const flags = "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --dangerously-bypass-hook-trust";
+            const prompt = shared_ts_1.shared.shellQuote(input.text);
+            const resuming = ctx.session.id;
+            const cmd = resuming
+                ? `${shared_ts_1.shared.agentBin("codex")} exec resume ${ctx.session.id} ${flags} ${prompt}`
+                : `${shared_ts_1.shared.agentBin("codex")} exec ${flags} ${prompt}`;
+            // `codex exec --json` 持续写出 ThreadEvent JSONL。把它压成短 step 送进 runner
+            // progress，human dashboard 因而能显示真正的 tool / reasoning / assistant 活动；完整
+            // transcript 仍在命令结束后一次解析并落入 events artifact，不能让 live 文案变成第二份结果。
+            const onStdout = codexProgressReporter(ctx);
+            const apiKey = getApiKey();
+            const res = await sb.runShell(cmd, {
+                // ambient env 由 Codex 进程自然传给 SessionStart/SessionStop hooks、env_http_headers
+                // 与 agent 调起的 nmem 等子进程。鉴权字段最后覆盖，避免 env 形成第二条 key 来源。
+                env: { ...agentEnv, CODEX_API_KEY: apiKey },
+                sensitiveValues: [apiKey, ...agentEnvSensitiveValues],
+                stream: true,
+                onStdout,
+            });
+            const raw = shared_ts_1.shared.extractJsonlFromStdout(res.stdout);
+            ctx.session.capture(shared_ts_1.shared.codexThreadId(res.stdout));
+            const parsed = shared_ts_1.shared.parseCodex(raw);
+            const events = [...parsed.events];
+            let turnEvidenceCoverage;
+            if (!raw?.trim()) {
+                const reason = "Codex JSONL transcript was unavailable; tool trajectory was not observed.";
+                turnEvidenceCoverage = {
+                    events: { status: "unavailable", reason },
+                    actions: { status: "unavailable", reason },
+                    usage: { status: "unavailable", reason },
+                };
+            }
+            else if (!parsed.parseSuccess) {
+                const reason = "Some Codex JSONL transcript lines could not be parsed.";
+                turnEvidenceCoverage = {
+                    events: { status: "partial", reason },
+                    actions: { status: "partial", reason },
+                };
+            }
+            else {
+                turnEvidenceCoverage = (0, command_projection_ts_1.unclassifiedToolActionsCoverage)(events);
+            }
+            if (res.exitCode !== 0) {
+                throw (0, send_failures_ts_1.makeSendFailure)({
+                    acceptance: codexAcceptance(raw, events, res.stderr),
+                    message: shared_ts_1.shared.diagnoseFailure(res, parsed.events, raw),
+                    ...(codexCapacityCode(raw) !== undefined
+                        ? { cause: (0, external_cause_ts_1.normalizeExternalCause)({ code: codexCapacityCode(raw) }) }
+                        : {}),
+                    events,
+                    usage: parsed.usage,
+                    process: res,
+                });
+            }
+            return {
+                events,
+                usage: parsed.usage,
+                status: "completed",
+                ...(turnEvidenceCoverage === undefined ? {} : { evidenceCoverage: turnEvidenceCoverage }),
+            };
+        },
+    }), config?.postSetup, config?.preTeardown);
+}
+/** 把 Codex JSONL 的高频原始帧收敛成 dashboard 当前行的一条短 detail。 */
+function codexProgressReporter(ctx) {
+    let remainder = "";
+    return (chunk) => {
+        remainder += chunk;
+        const lines = remainder.split("\n");
+        remainder = lines.pop() ?? "";
+        for (const line of lines) {
+            const detail = codexProgressDetail(line);
+            if (detail)
+                ctx.progress({ message: detail });
+        }
+    };
+}
+function codexProgressDetail(line) {
+    let event;
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        event = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    const item = event.item;
+    if (!item || typeof item !== "object")
+        return undefined;
+    const data = item;
+    const type = typeof data.type === "string" ? data.type : "";
+    const completed = event.type === "item.completed";
+    const preview = (value, limit = 96) => {
+        if (typeof value !== "string")
+            return undefined;
+        const text = value.replace(/\s+/g, " ").trim();
+        if (!text)
+            return undefined;
+        return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+    };
+    if (type === "command_execution") {
+        const command = preview(data.command) ?? "shell";
+        return completed ? `tool: ${command} · completed` : `tool: ${command}`;
+    }
+    if (type === "mcp_tool_call") {
+        const tool = typeof data.tool === "string" ? data.tool : "MCP";
+        const server = typeof data.server === "string" ? `${data.server}.` : "";
+        return completed ? `tool: ${server}${tool} · completed` : `tool: ${server}${tool}`;
+    }
+    if (type === "web_search")
+        return completed ? "tool: web search · completed" : "tool: web search";
+    if (type === "file_change")
+        return completed ? "tool: file change · completed" : "tool: file change";
+    if (type === "reasoning") {
+        const text = preview(data.text ?? data.content);
+        return text ? `thinking: ${text}` : "thinking";
+    }
+    if (type === "agent_message") {
+        const text = preview(data.text ?? data.message);
+        return text ? `assistant: ${text}` : "assistant response";
+    }
+    return undefined;
+}
+/**
+ * 先按 `marketplace.name` 连 Marketplace(同名只连一次,`--ref` 钉版本,add 后回读注册
+ * 列表校验名字真的注册上了),再装指定 Plugin。
+ * 只按 codex 自己的 marketplace / plugin 协议走 —— 与 claude-code 的实现不共用命令、不共用类型。
+ *
+ * 注册类命令是追加式的,而 Sandbox 复用下沙箱带着上一条 attempt 的 `$HOME` 进场,所以每一步
+ * 先读沙箱真实状态、把它收敛到声明,再执行 add / install(契约见 docs/feature/adapters/
+ * architecture/coding-agent-extensions.md「安装收敛:不假设沙箱空白」)。空白沙箱读回为空,
+ * 走的是同一条代码路径。
+ */
+async function installPlugins(sb, plugins) {
+    await resetPluginState(sb, plugins);
+    return installPluginsFromResetState(sb, plugins);
+}
+/**
+ * 在 config.toml 仍保留上一条 Attempt 的 Plugin 声明时清理声明态与安装体。
+ * setup 必须先调用它再覆盖 config；直接调用 installPlugins() 时也走同一收敛入口。
+ */
+async function resetPluginState(sb, plugins) {
+    // 摘除顺序固定「先卸完全部同名插件、后摘 marketplace」:marketplace 注册一摘,
+    // `codex plugin list` 就不再列出挂在它名下的安装(真机核对 codex-cli 0.146.0),
+    // 残留的那份从此定位不到。多个插件共用一个 marketplace 时只需摘一次注册。
+    for (const plugin of plugins) {
+        await removeInstalledPlugins(sb, plugin.name);
+    }
+    const marketplaces = new Set();
+    for (const plugin of plugins) {
+        if (marketplaces.has(plugin.marketplace.name))
+            continue;
+        await dropRegisteredMarketplace(sb, plugin.marketplace.name);
+        marketplaces.add(plugin.marketplace.name);
+    }
+}
+/** 安装阶段只接受已经由 resetPluginState() 收敛过的 Sandbox。 */
+async function installPluginsFromResetState(sb, plugins) {
+    const connected = new Set();
+    const out = [];
+    for (const plugin of plugins) {
+        const { marketplace } = plugin;
+        if (!connected.has(marketplace.name)) {
+            const refFlag = marketplace.ref ? ` --ref ${shared_ts_1.shared.shellQuote(marketplace.ref)}` : "";
+            // --sparse 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+            const sparseFlags = (marketplace.sparse ?? [])
+                .map((path) => ` --sparse ${shared_ts_1.shared.shellQuote(path)}`)
+                .join("");
+            const add = await sb.runShell(`${shared_ts_1.shared.agentBin("codex")} plugin marketplace add ${shared_ts_1.shared.shellQuote(marketplace.source)}${refFlag}${sparseFlags}`);
+            if (add.exitCode !== 0) {
+                throw new Error((0, index_ts_1.t)("plugin.marketplaceFailed", {
+                    agent: "codex",
+                    name: marketplace.name,
+                    source: marketplace.source,
+                    ref: marketplace.ref ?? "(default)",
+                    tail: outputTail(add),
+                }));
+            }
+            // add 静默按目标仓库 manifest 的 name 注册,错名会拖到 plugin add 才炸;
+            // 回读注册列表立刻校验(契约与真机复现见 marketplace.ts 顶部说明)。
+            await (0, marketplace_ts_1.verifyMarketplaceName)(sb, {
+                agent: "codex",
+                listCommand: "codex plugin marketplace list --json",
+                marketplace,
+                knownNames: connected,
+            });
+            connected.add(marketplace.name);
+        }
+        const install = await sb.runShell(`${shared_ts_1.shared.agentBin("codex")} plugin add ${shared_ts_1.shared.shellQuote(`${plugin.name}@${marketplace.name}`)}`);
+        if (install.exitCode !== 0) {
+            throw new Error((0, index_ts_1.t)("plugin.installFailed", {
+                agent: "codex",
+                name: plugin.name,
+                marketplace: marketplace.name,
+                tail: outputTail(install),
+            }));
+        }
+        const resolvedVersion = await installedVersion(sb, plugin.name, marketplace.name);
+        out.push({
+            agent: "codex",
+            marketplace: {
+                name: marketplace.name,
+                source: marketplace.source,
+                ...(marketplace.ref !== undefined ? { ref: marketplace.ref } : {}),
+            },
+            name: plugin.name,
+            ...(resolvedVersion !== undefined ? { resolvedVersion } : {}),
+        });
+    }
+    return out;
+}
+function codexInstalledPlugins(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    const arr = Array.isArray(raw)
+        ? raw
+        : raw && typeof raw === "object"
+            ? raw.installed
+            : undefined;
+    if (!Array.isArray(arr))
+        return undefined;
+    return arr.filter((item) => !!item && typeof item === "object");
+}
+/** 已安装条目的可寻址 id(`<plugin>@<marketplace>`);codex 的 remove 不接受裸插件名。 */
+function codexPluginId(entry) {
+    const id = entry.pluginId ??
+        entry.id ??
+        (entry.name && entry.marketplaceName ? `${entry.name}@${entry.marketplaceName}` : undefined);
+    return id?.includes("@") ? id : undefined;
+}
+/**
+ * 与声明同名的 Plugin 已安装就先移除(不论它出自哪个 marketplace),让本条 attempt 的安装与
+ * manifest 里的解析版本同源。已装即跳过会把上一条 attempt 装出的内容记成本条的安装事实。
+ */
+async function removeInstalledPlugins(sb, name) {
+    const listCommand = "codex plugin list --json";
+    const res = await sb.runShell(`${shared_ts_1.shared.agentBin("codex")} plugin list --json`);
+    const list = res.exitCode === 0 ? codexInstalledPlugins(res.stdout) : undefined;
+    if (list === undefined) {
+        throw new Error((0, index_ts_1.t)("plugin.listFailed", { agent: "codex", command: listCommand, tail: outputTail(res) }));
+    }
+    const ids = new Set();
+    for (const entry of list) {
+        const id = codexPluginId(entry);
+        if (id && (entry.name ?? id.split("@")[0]) === name)
+            ids.add(id);
+    }
+    for (const id of ids) {
+        const remove = await sb.runShell(`${shared_ts_1.shared.agentBin("codex")} plugin remove ${shared_ts_1.shared.shellQuote(id)}`);
+        if (remove.exitCode !== 0) {
+            throw new Error((0, index_ts_1.t)("plugin.removeFailed", { agent: "codex", name: id, tail: outputTail(remove) }));
+        }
+    }
+}
+/**
+ * 按声明名字无条件摘除同名 marketplace 注册,再由调用方按声明 source 与 ref 重新 add。
+ * 不以「注册在 `marketplace list --json` 里可见」为前提:注册状态分两半——用户配置里的注册项
+ * 和磁盘上的 marketplace 数据。原生配置整层替换会抹掉前一半,残下的后一半 list 报告不出来,
+ * add 却会撞它报 `marketplace '<name>' is already added from a different source`
+ * (复用沙箱第二条 attempt 真机复现,codex-cli 0.146.0;`remove` 对这种残根照样清得掉)。
+ * 「本就没有可摘的」(`is not configured or installed`,exit 1)按已收敛处理;其它失败也不在
+ * 这里报错——紧随其后的 add 是权威失败面,摘不干净它会带着 codex 的原话失败。
+ */
+async function dropRegisteredMarketplace(sb, name) {
+    await sb.runShell(`${shared_ts_1.shared.agentBin("codex")} plugin marketplace remove ${shared_ts_1.shared.shellQuote(name)}`);
+}
+/** 装完回读版本;取不到不阻断安装(manifest 里 resolvedVersion 省略)。 */
+async function installedVersion(sb, name, marketplace) {
+    const res = await sb.runShell(`${shared_ts_1.shared.agentBin("codex")} plugin list --json --marketplace ${shared_ts_1.shared.shellQuote(marketplace)}`);
+    if (res.exitCode !== 0)
+        return undefined;
+    const list = codexInstalledPlugins(res.stdout);
+    const hit = list?.find((p) => p.pluginId === `${name}@${marketplace}` || p.id === `${name}@${marketplace}` || p.name === name);
+    return typeof hit?.version === "string" ? hit.version : undefined;
+}
+function outputTail(res, n = 12) {
+    return (res.stdout + res.stderr).trim().split("\n").slice(-n).join("\n");
+}
+exports.default = codexAgent();
+//# sourceMappingURL=codex.cjs.map