@pulsemcp/air-adapter-codex 0.5.0

package/dist/codex-adapter.js

@@ -0,0 +1,967 @@
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, copyFileSync, rmSync, statSync, } from "fs";
+import { join, dirname, relative } from "path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { buildManifest, deleteManifest, diffManifest, getManifestPath, loadManifest, writeManifest, parseQualifiedId, resolveReference, } from "@pulsemcp/air-core";
+import { scanLocalSkills } from "./scan-local-skills.js";
+/** Matches an env/header value that is exactly a single `${VAR}` reference. */
+const WHOLE_VAR_RE = /^\$\{([^}]+)\}$/;
+/** Matches a value that contains a `${VAR}` reference anywhere within it. */
+const CONTAINS_VAR_RE = /\$\{[^}]+\}/;
+export class CodexAdapter {
+    name = "codex";
+    displayName = "OpenAI Codex";
+    /**
+     * Map AIR lifecycle event names to Codex `config.toml` hook event names.
+     *
+     * Accepts both snake_case AIR names and PascalCase Codex lifecycle names as
+     * identity mappings, so hook authors targeting the Codex runtime can write
+     * Codex-native event names directly without translating to snake_case.
+     *
+     * AIR events without a Codex equivalent (session_end, subagent_stop,
+     * pre_compact, notification) are intentionally absent — `reconcileConfigHooks`
+     * warns and skips registration when it encounters an unrecognized event.
+     * Codex's PermissionRequest event has no AIR analog and is therefore not
+     * generated by AIR (but user-authored PermissionRequest hooks are preserved).
+     */
+    static AIR_TO_CODEX_EVENT = {
+        // snake_case AIR names
+        session_start: "SessionStart",
+        pre_tool_call: "PreToolUse",
+        post_tool_call: "PostToolUse",
+        user_prompt_submit: "UserPromptSubmit",
+        stop: "Stop",
+        // PascalCase Codex event names (identity — hook authors targeting Codex
+        // often write these directly).
+        SessionStart: "SessionStart",
+        PreToolUse: "PreToolUse",
+        PostToolUse: "PostToolUse",
+        UserPromptSubmit: "UserPromptSubmit",
+        Stop: "Stop",
+        PermissionRequest: "PermissionRequest",
+    };
+    async isAvailable() {
+        try {
+            execSync("which codex", { stdio: "pipe" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    generateConfig(artifacts, root, _workDir) {
+        const pluginActivations = root?.default_plugins
+            ? this.resolveActivations(artifacts.plugins, root.default_plugins, "plugin")
+            : [];
+        const plugins = {};
+        for (const a of pluginActivations)
+            plugins[a.qualified] = artifacts.plugins[a.qualified];
+        // Merge plugin-declared MCP servers and skills into root defaults (additive).
+        // All incoming IDs are qualified (post-canonicalization at composition time),
+        // so we deduplicate on qualified IDs.
+        const mcpQualSet = new Set(root?.default_mcp_servers ?? []);
+        const skillQualSet = new Set(root?.default_skills ?? []);
+        for (const plugin of Object.values(plugins)) {
+            if (plugin.mcp_servers) {
+                for (const id of plugin.mcp_servers)
+                    mcpQualSet.add(id);
+            }
+            if (plugin.skills) {
+                for (const id of plugin.skills)
+                    skillQualSet.add(id);
+            }
+        }
+        const mcpActivations = this.resolveActivations(artifacts.mcp, [...mcpQualSet], "MCP server");
+        const skillActivations = this.resolveActivations(artifacts.skills, [...skillQualSet], "skill");
+        const mcpServers = {};
+        for (const a of mcpActivations)
+            mcpServers[a.short] = artifacts.mcp[a.qualified];
+        const mcpConfig = this.translateMcpServersByShort(mcpServers);
+        const pluginConfigs = pluginActivations.map((a) => this.translatePlugin(a.short, artifacts.plugins[a.qualified]));
+        const skillPaths = skillActivations.map((a) => artifacts.skills[a.qualified].path);
+        return {
+            agent: "codex",
+            mcpConfig,
+            pluginConfigs,
+            skillPaths,
+            env: {},
+        };
+    }
+    buildStartCommand(config) {
+        // Codex auto-discovers `.codex/config.toml`, `.codex/hooks/`, and
+        // `.agents/skills/` relative to its working root (trusted projects only).
+        // Pointing the working root at the prepared directory loads everything;
+        // no extra flags are required.
+        return {
+            command: "codex",
+            args: [],
+            env: config.env,
+            cwd: config.workDir,
+        };
+    }
+    /**
+     * Prepare a working directory for an OpenAI Codex CLI session.
+     *
+     * Writes `.codex/config.toml` (MCP servers under `[mcp_servers.*]` and hook
+     * registrations under `[hooks.*]`), injects skills + references into
+     * `.agents/skills/<name>/`, copies path-based hooks into `.codex/hooks/<name>/`,
+     * and returns the start command.
+     *
+     * Inputs to activation lists (root defaults, overrides, plugin-declared
+     * primitives) are accepted as either qualified (`@scope/id`) or short form;
+     * ambiguous short forms are rejected. Filesystem materialization uses
+     * shortnames — Codex's `config.toml`, `.agents/skills/`, `.codex/hooks/`,
+     * and the manifest are scope-naive. Two activated qualified IDs that share
+     * a shortname hard-fail with a clear "add one to exclude" message.
+     *
+     * NOTE: `configFiles` is intentionally returned empty. Codex's config is
+     * TOML, which is outside AIR's JSON-based transform/validation pipeline.
+     * Whole-value, same-named secret references (`${VAR}`) in MCP env/headers are
+     * mapped to Codex-native host-env forwarding (`env_vars`, `env_http_headers`)
+     * at translation time. Renamed or partial refs that can't be forwarded fall
+     * through to the literal table and emit a warning (see `warnUnforwardableSecret`),
+     * since the TOML never passes through the `${VAR}` transform pipeline.
+     */
+    async prepareSession(artifacts, targetDir, options) {
+        const root = options?.root;
+        const skillPaths = [];
+        const hookPaths = [];
+        const prevManifest = loadManifest(targetDir);
+        // 1. Resolve which artifacts to activate (overrides take precedence over root defaults)
+        let mcpServerIds = options?.mcpServerOverrides ?? root?.default_mcp_servers ?? undefined;
+        let skillIds = options?.skillOverrides ?? root?.default_skills ?? [];
+        let hookIds = options?.hookOverrides ?? root?.default_hooks ?? [];
+        // 1b. Merge subagent roots' artifacts if applicable.
+        const subagentRoots = this.resolveSubagentRoots(root, artifacts, options);
+        if (subagentRoots.length > 0) {
+            const merged = this.mergeSubagentArtifacts(subagentRoots, mcpServerIds, skillIds);
+            if (!options?.mcpServerOverrides) {
+                mcpServerIds = merged.mcpServerIds;
+            }
+            if (!options?.skillOverrides) {
+                skillIds = merged.skillIds;
+            }
+        }
+        // 1c. Resolve plugins and merge their declared artifacts (additive)
+        const pluginIds = options?.pluginOverrides ?? root?.default_plugins ?? undefined;
+        const pluginActivations = pluginIds?.length
+            ? this.resolveActivations(artifacts.plugins, pluginIds, "plugin")
+            : [];
+        const plugins = {};
+        for (const a of pluginActivations)
+            plugins[a.qualified] = artifacts.plugins[a.qualified];
+        const mcpSet = new Set(mcpServerIds ?? []);
+        const skillSet = new Set(skillIds);
+        const hookSet = new Set(hookIds);
+        for (const plugin of Object.values(plugins)) {
+            if (plugin.mcp_servers)
+                for (const id of plugin.mcp_servers)
+                    mcpSet.add(id);
+            if (plugin.skills)
+                for (const id of plugin.skills)
+                    skillSet.add(id);
+            if (plugin.hooks)
+                for (const id of plugin.hooks)
+                    hookSet.add(id);
+        }
+        if (mcpSet.size > 0 || mcpServerIds !== undefined)
+            mcpServerIds = [...mcpSet];
+        skillIds = [...skillSet];
+        hookIds = [...hookSet];
+        // 2. Resolve activations: qualified ID + shortname per artifact.
+        //    Throws on unknown IDs, ambiguous shortnames, and shortname collisions.
+        const skillActs = this.resolveActivations(artifacts.skills, skillIds, "skill");
+        const mcpActs = mcpServerIds
+            ? this.resolveActivations(artifacts.mcp, mcpServerIds, "MCP server")
+            : [];
+        const hookActs = this.resolveActivations(artifacts.hooks, hookIds, "hook");
+        const skillShortIds = skillActs.map((a) => a.short);
+        const hookShortIds = hookActs.map((a) => a.short);
+        const mcpShortIds = mcpActs.map((a) => a.short);
+        // 3. Reconcile against prior manifest using shortnames — those are the keys
+        //    used for filesystem materialization and stored in the manifest.
+        const diff = diffManifest(prevManifest, {
+            skills: skillShortIds,
+            hooks: hookShortIds,
+            mcpServers: mcpShortIds,
+        });
+        for (const staleSkillId of diff.staleSkills) {
+            const staleDir = join(targetDir, ".agents", "skills", staleSkillId);
+            if (existsSync(staleDir)) {
+                rmSync(staleDir, { recursive: true, force: true });
+            }
+        }
+        for (const staleHookId of diff.staleHooks) {
+            const staleDir = join(targetDir, ".codex", "hooks", staleHookId);
+            if (existsSync(staleDir)) {
+                rmSync(staleDir, { recursive: true, force: true });
+            }
+        }
+        // 4. Inject skills + references into .agents/skills/<short>/
+        const materializedSkillShortIds = [];
+        for (const a of skillActs) {
+            const skill = artifacts.skills[a.qualified];
+            const skillTargetDir = join(targetDir, ".agents", "skills", a.short);
+            if (existsSync(skillTargetDir)) {
+                materializedSkillShortIds.push(a.short);
+                continue;
+            }
+            const skillSourceDir = skill.path;
+            if (!existsSync(skillSourceDir)) {
+                console.warn(this.missingSourceDirMessage("skill", a.qualified, skillSourceDir));
+                continue;
+            }
+            this.copyDirRecursive(skillSourceDir, skillTargetDir);
+            skillPaths.push(skillTargetDir);
+            materializedSkillShortIds.push(a.short);
+            if (skill.references && skill.references.length > 0) {
+                this.copyReferences(skill.references, skillTargetDir, artifacts);
+            }
+        }
+        // 5. Validate and inject path-based hooks into .codex/hooks/<short>/.
+        const prevHookIds = new Set(prevManifest?.hooks ?? []);
+        const registeredHookShortIds = [];
+        const registeredHookActivations = [];
+        for (const a of hookActs) {
+            const hook = artifacts.hooks[a.qualified];
+            const hookTargetDir = join(targetDir, ".codex", "hooks", a.short);
+            const alreadyExists = existsSync(hookTargetDir);
+            if (alreadyExists && !prevHookIds.has(a.short)) {
+                continue;
+            }
+            if (!alreadyExists) {
+                const hookSourceDir = hook.path;
+                if (!existsSync(hookSourceDir)) {
+                    console.warn(this.missingSourceDirMessage("hook", a.qualified, hookSourceDir));
+                    continue;
+                }
+                this.copyDirRecursive(hookSourceDir, hookTargetDir);
+                if (hook.references && hook.references.length > 0) {
+                    this.copyReferences(hook.references, hookTargetDir, artifacts);
+                }
+            }
+            hookPaths.push(hookTargetDir);
+            registeredHookShortIds.push(a.short);
+            registeredHookActivations.push({ short: a.short, qualified: a.qualified });
+        }
+        // 6. Write `.codex/config.toml`: AIR-managed MCP servers and hook
+        //    registrations, merged into any user-authored config (full replacement
+        //    of AIR-owned keys; user keys preserved; stale AIR keys removed).
+        const translatedServers = {};
+        for (const a of mcpActs)
+            translatedServers[a.short] = artifacts.mcp[a.qualified];
+        const managedHookIds = new Set([
+            ...diff.staleHooks,
+            ...registeredHookShortIds,
+        ]);
+        this.writeCodexConfig(targetDir, this.translateMcpServersByShort(translatedServers), diff.staleMcpServers, hookPaths, managedHookIds);
+        // 7. Persist the updated manifest (shortnames — keyed by filesystem dir).
+        //    Only record skills/hooks that were actually materialized so the manifest
+        //    does not claim ownership of artifacts AIR skipped (e.g. a missing source dir).
+        writeManifest(buildManifest(targetDir, {
+            adapter: this.name,
+            skills: materializedSkillShortIds,
+            hooks: registeredHookShortIds,
+            mcpServers: mcpShortIds,
+        }));
+        // 8. Generate ephemeral subagent context for the session.
+        //    Codex has no `--append-system-prompt` equivalent, so this is surfaced
+        //    to the caller via `subagentContext` rather than the start command.
+        let subagentContext;
+        if (subagentRoots.length > 0) {
+            subagentContext = this.buildSubagentContext(subagentRoots);
+        }
+        // 9. Build start command (working root = prepared directory).
+        const config = this.generateConfig(artifacts, undefined, targetDir);
+        const startCommand = this.buildStartCommand({
+            ...config,
+            workDir: targetDir,
+        });
+        return {
+            // Empty by design — see method doc: Codex's TOML config is outside AIR's
+            // JSON transform pipeline, and whole-value `${VAR}` references are mapped
+            // to Codex-native env forwarding at translation time, so there is nothing
+            // for the pipeline to transform or validate. (Unforwardable renamed/partial
+            // refs warn at translation time.) The `.codex/config.toml` we wrote above
+            // is deliberately not surfaced as a config file.
+            configFiles: [],
+            skillPaths,
+            hookPaths,
+            hookActivations: registeredHookActivations,
+            startCommand,
+            subagentContext,
+        };
+    }
+    /**
+     * Enumerate skills checked into `<targetDir>/.agents/skills/`. Codex loads
+     * these directly from the filesystem regardless of AIR's involvement, so
+     * they're always active and must not be overwritten or removed. The TUI uses
+     * this list to surface them as read-only entries.
+     */
+    async listLocalArtifacts(targetDir) {
+        return { skills: scanLocalSkills(targetDir) };
+    }
+    /**
+     * Remove every artifact AIR has previously written into `targetDir`.
+     *
+     * Reads the per-target manifest, deletes each tracked skill / hook
+     * directory, and removes tracked MCP server keys + AIR-managed hook entries
+     * from `.codex/config.toml`. When every category is cleaned, the manifest
+     * itself is deleted; partial cleans (any `keep*` flag set) update the
+     * manifest with the kept entries so future runs continue to track them.
+     *
+     * Items in the manifest that no longer exist on disk are silently skipped
+     * — the manifest can drift if a user removed files manually between runs.
+     */
+    async cleanSession(targetDir, options) {
+        const dryRun = options?.dryRun ?? false;
+        const cleanSkills = !(options?.keepSkills ?? false);
+        const cleanHooks = !(options?.keepHooks ?? false);
+        const cleanMcpServers = !(options?.keepMcpServers ?? false);
+        const fullClean = cleanSkills && cleanHooks && cleanMcpServers;
+        const manifestPath = getManifestPath(targetDir);
+        const manifestFileExists = existsSync(manifestPath);
+        const manifest = loadManifest(targetDir);
+        if (!manifest) {
+            let corruptManifestRemoved = false;
+            if (manifestFileExists && fullClean && !dryRun) {
+                corruptManifestRemoved = deleteManifest(targetDir);
+            }
+            return {
+                removedSkills: [],
+                removedHooks: [],
+                removedMcpServers: [],
+                mcpConfigPath: null,
+                settingsPath: null,
+                manifestPath,
+                manifestExisted: manifestFileExists,
+                manifestRemoved: corruptManifestRemoved,
+            };
+        }
+        const configPath = join(targetDir, ".codex", "config.toml");
+        const removedSkills = [];
+        if (cleanSkills) {
+            for (const id of manifest.skills) {
+                const dir = join(targetDir, ".agents", "skills", id);
+                if (!existsSync(dir))
+                    continue;
+                if (!dryRun)
+                    rmSync(dir, { recursive: true, force: true });
+                removedSkills.push(id);
+            }
+        }
+        const removedHooks = [];
+        if (cleanHooks) {
+            for (const id of manifest.hooks) {
+                const dir = join(targetDir, ".codex", "hooks", id);
+                if (!existsSync(dir))
+                    continue;
+                if (!dryRun)
+                    rmSync(dir, { recursive: true, force: true });
+                removedHooks.push(id);
+            }
+        }
+        // Both MCP servers and hooks live in `.codex/config.toml`. Prune AIR-owned
+        // entries in a single read/modify/write, preserving user-authored keys.
+        const removedMcpServers = [];
+        let mcpConfigPath = null;
+        if ((cleanMcpServers && manifest.mcpServers.length > 0) ||
+            (cleanHooks && manifest.hooks.length > 0)) {
+            if (existsSync(configPath)) {
+                const presentMcpIds = cleanMcpServers
+                    ? this.mcpServerIdsPresent(configPath, manifest.mcpServers)
+                    : [];
+                const willTouch = presentMcpIds.length > 0 || (cleanHooks && manifest.hooks.length > 0);
+                if (willTouch) {
+                    if (!dryRun) {
+                        mcpConfigPath = this.pruneCodexConfig(configPath, cleanMcpServers ? presentMcpIds : [], cleanHooks ? new Set(manifest.hooks) : new Set());
+                    }
+                    else {
+                        mcpConfigPath = configPath;
+                    }
+                    for (const id of presentMcpIds)
+                        removedMcpServers.push(id);
+                }
+            }
+        }
+        let manifestRemoved = false;
+        if (fullClean) {
+            if (!dryRun) {
+                manifestRemoved = deleteManifest(targetDir);
+            }
+            else {
+                manifestRemoved = manifestFileExists;
+            }
+        }
+        else if (!dryRun) {
+            writeManifest(buildManifest(targetDir, {
+                adapter: manifest.adapter ?? this.name,
+                skills: cleanSkills ? [] : manifest.skills,
+                hooks: cleanHooks ? [] : manifest.hooks,
+                mcpServers: cleanMcpServers ? [] : manifest.mcpServers,
+            }));
+        }
+        return {
+            removedSkills,
+            removedHooks,
+            removedMcpServers,
+            // `.codex/config.toml` carries both MCP servers and hooks; report it as
+            // the MCP config path. `settingsPath` stays null — Codex has no separate
+            // settings file.
+            mcpConfigPath,
+            settingsPath: null,
+            manifestPath,
+            manifestExisted: true,
+            manifestRemoved,
+        };
+    }
+    /**
+     * Read `.codex/config.toml` and return the subset of `ids` whose key is
+     * actually present under `[mcp_servers]`. Returns an empty list if the file
+     * can't be parsed — we'd rather under-report than claim to have removed
+     * entries we never touched.
+     */
+    mcpServerIdsPresent(configPath, ids) {
+        const existing = this.readToml(configPath);
+        const servers = existing.mcp_servers ?? {};
+        return ids.filter((id) => Object.prototype.hasOwnProperty.call(servers, id));
+    }
+    /**
+     * Resolve subagent roots from the root's default_subagent_roots.
+     * IDs are already qualified after composition-time canonicalization.
+     */
+    resolveSubagentRoots(root, artifacts, options) {
+        if (options?.skipSubagentMerge)
+            return [];
+        if (!root?.default_subagent_roots?.length)
+            return [];
+        const resolved = [];
+        for (const id of root.default_subagent_roots) {
+            const res = resolveReference(artifacts.roots, id, undefined);
+            if (res.status === "ok") {
+                resolved.push(artifacts.roots[res.qualified]);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Merge subagent roots' default_mcp_servers and default_skills into the
+     * parent's activated sets (union, preserving order with parent first).
+     */
+    mergeSubagentArtifacts(subagentRoots, parentMcpServerIds, parentSkillIds) {
+        const mcpSet = new Set(parentMcpServerIds ?? []);
+        const skillSet = new Set(parentSkillIds);
+        for (const sub of subagentRoots) {
+            if (sub.default_mcp_servers) {
+                for (const id of sub.default_mcp_servers)
+                    mcpSet.add(id);
+            }
+            if (sub.default_skills) {
+                for (const id of sub.default_skills)
+                    skillSet.add(id);
+            }
+        }
+        return {
+            mcpServerIds: parentMcpServerIds !== undefined || mcpSet.size > 0 ? [...mcpSet] : undefined,
+            skillIds: [...skillSet],
+        };
+    }
+    /**
+     * Build a system prompt section describing the subagent root dependencies.
+     */
+    buildSubagentContext(subagentRoots) {
+        const lines = [
+            "## Subagent Root Dependencies",
+            "",
+            "This session includes capabilities from the following subagent roots.",
+            "Their skills and MCP servers have been merged into your session.",
+            "",
+        ];
+        for (const sub of subagentRoots) {
+            lines.push(`### ${sub.display_name || "Subagent"}`);
+            lines.push("");
+            lines.push(`**Description**: ${sub.description}`);
+            if (sub.default_mcp_servers?.length) {
+                lines.push(`**MCP Servers**: ${sub.default_mcp_servers.join(", ")}`);
+            }
+            if (sub.default_skills?.length) {
+                lines.push(`**Skills**: ${sub.default_skills.join(", ")}`);
+            }
+            if (sub.subdirectory) {
+                lines.push(`**Subdirectory**: ${sub.subdirectory}`);
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Translate a shortname-keyed MCP server map into Codex's `[mcp_servers.*]`
+     * shape (as a plain object ready for TOML serialization). Callers convert
+     * qualified IDs to shortnames before invoking this — Codex's config is
+     * scope-naive.
+     *
+     * Secret handling is Codex-native: an env value that is exactly `${VAR}`
+     * and whose key matches `VAR` becomes an `env_vars` forward (Codex injects
+     * the host's `VAR` at launch); any other value is written literally into the
+     * `[mcp_servers.<name>.env]` table. For remote servers, a header value of
+     * `${VAR}` becomes an `env_http_headers` entry; other header values are
+     * written into `http_headers`.
+     *
+     * Codex's native forwarding only expresses *whole-value* refs: `env_vars`
+     * forwards a host var to an env key of the same name, and `env_http_headers`
+     * forwards a host var as a whole header value. A *renamed* whole-value ref
+     * (`KEY = "${OTHER}"`) or a *partial* value (`"Bearer ${TOKEN}"`) can't be
+     * expressed either way, so it falls through to the literal table — and since
+     * the TOML never passes through AIR's `${VAR}` transform pipeline, Codex
+     * would inject the literal `${…}` string at runtime. We warn loudly in that
+     * case rather than silently shipping a broken secret.
+     */
+    translateMcpServersByShort(servers) {
+        const out = {};
+        for (const [name, server] of Object.entries(servers)) {
+            out[name] = this.translateMcpServer(name, server);
+        }
+        return out;
+    }
+    translateMcpServer(name, server) {
+        if (server.type === "stdio") {
+            const out = { command: server.command };
+            if (server.args && server.args.length > 0)
+                out.args = server.args;
+            const envTable = {};
+            const envVars = [];
+            for (const [key, value] of Object.entries(server.env ?? {})) {
+                const m = WHOLE_VAR_RE.exec(value);
+                if (m && m[1] === key) {
+                    // `${KEY}` referencing the host var of the same name → forward it.
+                    envVars.push(key);
+                }
+                else {
+                    if (CONTAINS_VAR_RE.test(value)) {
+                        this.warnUnforwardableSecret(name, `env["${key}"]`, value);
+                    }
+                    envTable[key] = value;
+                }
+            }
+            if (envVars.length > 0)
+                out.env_vars = envVars;
+            if (Object.keys(envTable).length > 0)
+                out.env = envTable;
+            return out;
+        }
+        // Remote server (sse or streamable-http). Codex models both as a URL-based
+        // streamable HTTP server and auto-detects the transport from the URL.
+        const out = { url: server.url };
+        const httpHeaders = {};
+        const envHttpHeaders = {};
+        for (const [key, value] of Object.entries(server.headers ?? {})) {
+            const m = WHOLE_VAR_RE.exec(value);
+            if (m) {
+                envHttpHeaders[key] = m[1];
+            }
+            else {
+                if (CONTAINS_VAR_RE.test(value)) {
+                    this.warnUnforwardableSecret(name, `headers["${key}"]`, value);
+                }
+                httpHeaders[key] = value;
+            }
+        }
+        if (Object.keys(httpHeaders).length > 0)
+            out.http_headers = httpHeaders;
+        if (Object.keys(envHttpHeaders).length > 0)
+            out.env_http_headers = envHttpHeaders;
+        // NOTE: AIR's detailed OAuth config (clientId/scopes/redirectUri/…) has no
+        // static Codex equivalent — Codex performs interactive OAuth via
+        // `codex mcp login <name>`. The gap is documented in the adapter README.
+        return out;
+    }
+    /**
+     * Warn that a secret reference can't be expressed via Codex's native host-env
+     * forwarding and will be written to `.codex/config.toml` as a literal `${…}`
+     * string. Codex would then inject that literal text at runtime — a silently
+     * broken secret. Only whole-value, same-named refs forward cleanly; renamed
+     * (`KEY = "${OTHER}"`) and partial (`"Bearer ${TOKEN}"`) refs land here.
+     */
+    warnUnforwardableSecret(serverName, field, value) {
+        console.warn(`[air-adapter-codex] MCP server "${serverName}" ${field} = "${value}" contains a ` +
+            `\${VAR} reference that Codex cannot forward natively. Codex's env_vars / ` +
+            `env_http_headers only express whole-value refs to a host var of the same name, ` +
+            `so this value is written to .codex/config.toml verbatim and Codex will inject the ` +
+            `literal "\${…}" string at runtime. Rewrite it as a whole-value, same-named ref ` +
+            `(e.g. ${field.includes("headers") ? `Authorization = "\${AUTHORIZATION}"` : `KEY = "\${KEY}"`}) ` +
+            `or set the value directly.`);
+    }
+    /**
+     * Translate an AIR plugin to a Codex-facing descriptor.
+     *
+     * Codex's marketplace plugins are remote-installed (`codex plugin add`) and
+     * have no local package file an adapter can materialize. AIR therefore treats
+     * plugins as composition sugar: a plugin's declared MCP servers / skills /
+     * hooks are expanded into the activation set and materialized as their
+     * underlying Codex-native artifacts. This descriptor is informational only.
+     */
+    translatePlugin(shortId, plugin) {
+        return {
+            name: shortId,
+            description: plugin.description,
+            ...(plugin.version && { version: plugin.version }),
+        };
+    }
+    /**
+     * Resolve a list of activation IDs (each qualified or short) into qualified
+     * IDs paired with shortnames suitable for filesystem materialization.
+     *
+     * Throws on:
+     *   - unknown IDs (after attempting both qualified and short-form lookup)
+     *   - ambiguous short references (multiple scopes contribute the shortname)
+     *   - shortname collisions in the activation set itself (two qualified IDs
+     *     with the same shortname can't share a single materialization dir)
+     */
+    resolveActivations(pool, ids, artifactType) {
+        const acts = [];
+        const errors = [];
+        const shortToQualified = new Map();
+        for (const id of ids) {
+            const res = resolveReference(pool, id, undefined);
+            if (res.status === "missing") {
+                errors.push(`Unknown ${artifactType} ID "${id}". Available: ${this.formatPoolKeys(pool)}.`);
+                continue;
+            }
+            if (res.status === "ambiguous") {
+                errors.push(`${artifactType} reference "${id}" is ambiguous — candidates: ` +
+                    `${res.candidates.join(", ")}. Use the qualified form to disambiguate.`);
+                continue;
+            }
+            const qualified = res.qualified;
+            const { id: short } = parseQualifiedId(qualified);
+            const prior = shortToQualified.get(short);
+            if (prior !== undefined && prior !== qualified) {
+                errors.push(`${artifactType} shortname collision: both "${prior}" and "${qualified}" ` +
+                    `are activated and would write to the same target name "${short}". ` +
+                    `Add one to air.json#exclude or activate only one of them.`);
+                continue;
+            }
+            if (prior === qualified)
+                continue; // dedup
+            shortToQualified.set(short, qualified);
+            acts.push({ qualified, short });
+        }
+        if (errors.length > 0) {
+            throw new Error(errors.length === 1 ? errors[0] : `Activation errors:\n  - ${errors.join("\n  - ")}`);
+        }
+        return acts;
+    }
+    /**
+     * Build the warning emitted when a registered artifact's `path` does not
+     * exist on disk at materialization time. The qualified ID encodes the
+     * declaring catalog's scope, so a reviewer can trace the offending entry
+     * back to its index file. Materialization is skipped for this artifact and
+     * the rest of the session proceeds.
+     */
+    missingSourceDirMessage(artifactType, qualified, resolvedPath) {
+        return (`warning: ${artifactType} "${qualified}" declares path "${resolvedPath}" but that directory does not exist — skipping. ` +
+            `The catalog that contributed "${qualified}" registered a path AIR cannot materialize. ` +
+            `Fix the \`path\` field in the catalog's index file (or exclude the artifact in air.json) to restore the ${artifactType}.`);
+    }
+    formatPoolKeys(pool) {
+        const keys = Object.keys(pool);
+        if (keys.length === 0)
+            return "(none)";
+        if (keys.length > 8) {
+            return `${keys.slice(0, 8).join(", ")}, … (${keys.length} total)`;
+        }
+        return keys.join(", ");
+    }
+    /**
+     * Copy referenced documents into a references/ subdirectory of the target.
+     * `refIds` are qualified IDs (post-canonicalization).
+     */
+    copyReferences(refIds, targetDir, artifacts) {
+        const refsTargetDir = join(targetDir, "references");
+        for (const refId of refIds) {
+            const ref = artifacts.references[refId];
+            if (!ref)
+                continue;
+            const refSourcePath = ref.path;
+            if (existsSync(refSourcePath)) {
+                const refTargetPath = join(refsTargetDir, ref.path.split("/").pop() || ref.path);
+                mkdirSync(dirname(refTargetPath), { recursive: true });
+                copyFileSync(refSourcePath, refTargetPath);
+            }
+        }
+    }
+    // ============================================================
+    // `.codex/config.toml` read / merge / write
+    // ============================================================
+    /** Parse an existing `config.toml`, returning `{}` when absent/unparseable. */
+    readToml(path) {
+        if (!existsSync(path))
+            return {};
+        try {
+            return parseToml(readFileSync(path, "utf-8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Merge AIR-managed MCP servers and hook registrations into
+     * `.codex/config.toml`, preserving any user-authored config.
+     *
+     * - MCP: keys in `staleMcpIds` are removed; keys in `translatedServers`
+     *   are set/replaced; other servers and top-level keys pass through.
+     * - Hooks: AIR-owned entries (tagged with `_air_hook_id`) whose ID is in
+     *   `managedHookIds` are pruned, then the current selection is registered.
+     *
+     * Returns the path written.
+     */
+    writeCodexConfig(targetDir, translatedServers, staleMcpIds, newHookPaths, managedHookIds) {
+        const configPath = join(targetDir, ".codex", "config.toml");
+        const config = this.readToml(configPath);
+        // --- MCP servers ---
+        const servers = config.mcp_servers ?? {};
+        for (const id of staleMcpIds)
+            delete servers[id];
+        for (const [id, cfg] of Object.entries(translatedServers))
+            servers[id] = cfg;
+        if (Object.keys(servers).length > 0) {
+            config.mcp_servers = servers;
+        }
+        else {
+            delete config.mcp_servers;
+        }
+        // --- Hooks ---
+        this.reconcileConfigHooks(config, targetDir, newHookPaths, managedHookIds);
+        // Nothing to persist: don't leave an empty `.codex/config.toml` behind, and
+        // remove a now-empty one if a prior run (or user edit) emptied it out.
+        if (Object.keys(config).length === 0) {
+            if (existsSync(configPath))
+                rmSync(configPath, { force: true });
+            return configPath;
+        }
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, stringifyToml(config) + "\n");
+        return configPath;
+    }
+    /**
+     * Reconcile the `[hooks.*]` tables on the in-memory config object.
+     *
+     * Codex represents hooks as `hooks.<Event> = [ { matcher, hooks: [ {type,
+     * command, timeout?, statusMessage?} ] } ]`. AIR-owned matcher groups are
+     * identified by an `_air_hook_id` marker on the inner hook entry (Codex
+     * ignores unrecognized keys unless `--strict-config` is set). Groups whose ID
+     * is in `managedHookIds` are removed, then the current `newHookPaths` are
+     * registered for their mapped events.
+     */
+    reconcileConfigHooks(config, targetDir, newHookPaths, managedHookIds) {
+        const hooks = config.hooks ?? {};
+        for (const event of Object.keys(hooks)) {
+            const matcherGroups = hooks[event];
+            if (!Array.isArray(matcherGroups))
+                continue;
+            const prunedGroups = [];
+            for (const group of matcherGroups) {
+                if (!group || typeof group !== "object") {
+                    prunedGroups.push(group);
+                    continue;
+                }
+                const g = group;
+                const inner = Array.isArray(g.hooks) ? g.hooks : [];
+                const keptInner = inner.filter((h) => !this.isManagedHookEntry(h, managedHookIds));
+                if (keptInner.length === 0)
+                    continue;
+                prunedGroups.push({ ...g, hooks: keptInner });
+            }
+            if (prunedGroups.length === 0) {
+                delete hooks[event];
+            }
+            else {
+                hooks[event] = prunedGroups;
+            }
+        }
+        for (const hookPath of newHookPaths) {
+            const hookJsonPath = join(hookPath, "HOOK.json");
+            if (!existsSync(hookJsonPath))
+                continue;
+            let hookJson;
+            try {
+                hookJson = JSON.parse(readFileSync(hookJsonPath, "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            const hookId = hookPath.split(/[\\/]/).filter(Boolean).pop() || "";
+            const rawEvent = hookJson.event;
+            const codexEvent = typeof rawEvent === "string"
+                ? CodexAdapter.AIR_TO_CODEX_EVENT[rawEvent]
+                : undefined;
+            if (!codexEvent) {
+                if (rawEvent !== undefined) {
+                    console.warn(`warning: hook "${hookId}" declares unrecognized event "${String(rawEvent)}" — skipping registration in .codex/config.toml. ` +
+                        `Supported events: ${this.supportedEventList()}.`);
+                }
+                continue;
+            }
+            if (!hookJson.command)
+                continue;
+            const hookRelDir = relative(targetDir, hookPath);
+            const command = this.buildHookCommand(hookRelDir, hookPath, hookJson.command, hookJson.args);
+            const hookEntry = {
+                type: "command",
+                command,
+                _air_hook_id: hookId,
+            };
+            if (hookJson.timeout_seconds != null) {
+                hookEntry.timeout = hookJson.timeout_seconds;
+            }
+            const matcherGroup = {
+                matcher: hookJson.matcher ?? "",
+                hooks: [hookEntry],
+            };
+            if (!hooks[codexEvent]) {
+                hooks[codexEvent] = [];
+            }
+            hooks[codexEvent].push(matcherGroup);
+        }
+        if (Object.keys(hooks).length > 0) {
+            config.hooks = hooks;
+        }
+        else {
+            delete config.hooks;
+        }
+    }
+    isManagedHookEntry(entry, managedHookIds) {
+        if (!entry || typeof entry !== "object")
+            return false;
+        const id = entry._air_hook_id;
+        if (typeof id !== "string")
+            return false;
+        return managedHookIds.has(id);
+    }
+    /**
+     * Remove `mcpIds` from `[mcp_servers]` and AIR-managed hook entries (matched
+     * by `_air_hook_id` ∈ `managedHookIds`) from `[hooks.*]` in
+     * `.codex/config.toml`, preserving user-authored entries and other top-level
+     * fields. Returns the path of the file that was rewritten, or null if the
+     * file became empty and was deleted.
+     */
+    pruneCodexConfig(configPath, mcpIds, managedHookIds) {
+        const config = this.readToml(configPath);
+        const servers = config.mcp_servers ?? {};
+        for (const id of mcpIds)
+            delete servers[id];
+        if (Object.keys(servers).length > 0) {
+            config.mcp_servers = servers;
+        }
+        else {
+            delete config.mcp_servers;
+        }
+        if (managedHookIds.size > 0) {
+            this.reconcileConfigHooks(config, dirname(dirname(configPath)), [], managedHookIds);
+        }
+        if (Object.keys(config).length === 0) {
+            rmSync(configPath, { force: true });
+            return null;
+        }
+        writeFileSync(configPath, stringifyToml(config) + "\n");
+        return configPath;
+    }
+    /**
+     * Build a shell command string from HOOK.json's command and args fields.
+     *
+     * Hook authors write paths relative to their own hook directory. Codex
+     * invokes hooks with a working directory that is not guaranteed to be the
+     * project root, so hook-relative paths are anchored to the repository root
+     * via `"$(git rev-parse --show-toplevel)/.codex/hooks/<id>/<path>"` — the
+     * idiom used in Codex's own hook documentation. The double quotes keep the
+     * path safe for project directories with spaces.
+     *
+     *   - `command` is anchored if it starts with `./` (explicit hook-relative).
+     *   - Each `args` entry is anchored if it looks like a path AND the file
+     *     exists under the hook's installed directory.
+     *
+     * Args that are not rewritten and contain shell metacharacters are
+     * single-quoted for safety.
+     */
+    buildHookCommand(hookRelDir, hookAbsDir, command, args) {
+        let cmd;
+        if (command.startsWith("./")) {
+            cmd = this.anchorHookPath(join(hookRelDir, command.slice(2)));
+        }
+        else {
+            cmd = command;
+        }
+        if (args && args.length > 0) {
+            const rewritten = args.map((a) => this.rewriteHookArgPath(a, hookRelDir, hookAbsDir));
+            const escaped = rewritten.map((r) => r.anchored
+                ? this.anchorHookPath(r.value)
+                : /[\s;&|`$"'\\]/.test(r.value)
+                    ? `'${r.value.replace(/'/g, "'\\''")}'`
+                    : r.value);
+            cmd += " " + escaped.join(" ");
+        }
+        return cmd;
+    }
+    /**
+     * Wrap a project-root-relative path in `"$(git rev-parse --show-toplevel)/..."`
+     * so the resolved path is independent of the cwd at hook invocation. Double
+     * quotes are required so the command substitution runs; characters that are
+     * special inside double quotes (`$`, `` ` ``, `"`, `\`) are escaped in the
+     * path component so an unusual hook ID or filename can't break out of the
+     * quoting.
+     */
+    anchorHookPath(projectRelPath) {
+        const safe = projectRelPath.replace(/[\\"$`]/g, "\\$&");
+        return `"$(git rev-parse --show-toplevel)/${safe}"`;
+    }
+    /**
+     * If `arg` is a hook-relative path that points at a real file under the
+     * hook's installed directory, return its project-root-relative form
+     * (`.codex/hooks/<id>/<path>`) flagged as anchored so the caller can wrap it.
+     * Otherwise return `arg` unchanged with `anchored: false`.
+     */
+    rewriteHookArgPath(arg, hookRelDir, hookAbsDir) {
+        if (!arg)
+            return { value: arg, anchored: false };
+        if (arg.startsWith("-") || arg.startsWith("/") || arg.startsWith("~")) {
+            return { value: arg, anchored: false };
+        }
+        const hasExplicitPrefix = arg.startsWith("./");
+        const candidate = hasExplicitPrefix ? arg.slice(2) : arg;
+        if (!hasExplicitPrefix && !candidate.includes("/")) {
+            return { value: arg, anchored: false };
+        }
+        if (!existsSync(join(hookAbsDir, candidate))) {
+            return { value: arg, anchored: false };
+        }
+        return { value: join(hookRelDir, candidate), anchored: true };
+    }
+    /** Human-readable list of the supported AIR hook event names (snake_case only). */
+    supportedEventList() {
+        const seen = new Set();
+        const names = [];
+        for (const [key, value] of Object.entries(CodexAdapter.AIR_TO_CODEX_EVENT)) {
+            if (key === value)
+                continue; // skip PascalCase identity entries
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            names.push(key);
+        }
+        return names.join(", ");
+    }
+    copyDirRecursive(src, dest) {
+        mkdirSync(dest, { recursive: true });
+        for (const entry of readdirSync(src)) {
+            const srcPath = join(src, entry);
+            const destPath = join(dest, entry);
+            if (statSync(srcPath).isDirectory()) {
+                this.copyDirRecursive(srcPath, destPath);
+            }
+            else {
+                copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=codex-adapter.js.map