@pulsemcp/air-adapter-codex 0.5.0

package/README.md

@@ -0,0 +1,83 @@
+# @pulsemcp/air-adapter-codex
+
+AIR adapter extension for the [OpenAI Codex CLI](https://github.com/openai/codex). Translates AIR artifacts into Codex's native formats and prepares working directories for agent sessions.
+
+## Installation
+
+```bash
+npm install @pulsemcp/air-adapter-codex
+```
+
+## Usage
+
+### With the AIR CLI
+
+```bash
+# Install the adapter globally alongside the CLI
+npm install -g @pulsemcp/air-cli @pulsemcp/air-adapter-codex
+
+# Start a Codex session
+air start codex --root web-app
+```
+
+### Programmatic
+
+```typescript
+import { resolveArtifacts } from "@pulsemcp/air-core";
+import { CodexAdapter } from "@pulsemcp/air-adapter-codex";
+
+const artifacts = await resolveArtifacts("./air.json");
+const adapter = new CodexAdapter();
+
+// Prepare a working directory for a Codex session
+const session = await adapter.prepareSession(artifacts, "./my-project", {
+  root: artifacts.roots["web-app"],
+});
+
+// session.configFiles  — [] (Codex config is TOML, see "Secrets" below)
+// session.skillPaths   — skill dirs created in .agents/skills/
+// session.hookPaths    — hook dirs created in .codex/hooks/
+// session.startCommand — { command: "codex", args: [], cwd: "..." }
+```
+
+## What `prepareSession()` does
+
+1. **Writes `.codex/config.toml`** — translates AIR MCP server configs into `[mcp_servers.*]` tables and registers path-based hooks under `[[hooks.<Event>]]`. User-authored servers, hooks, and top-level keys are preserved; only AIR-owned keys are replaced.
+2. **Injects skills** — copies `SKILL.md` files and associated content into `.agents/skills/{name}/`, where Codex discovers them.
+3. **Injects hooks** — copies hook directories into `.codex/hooks/{name}/` and registers their command in `config.toml`, anchored to the repo root.
+4. **Copies references** — attaches referenced documents into `{artifact}/references/`.
+5. **Respects local priority** — if a skill or hook directory already exists in the target, it is not overwritten.
+
+## Translation Details
+
+| AIR Format | Codex Format |
+|------------|--------------|
+| `mcp.json` (flat map with `type`, `title`, `description`) | `[mcp_servers.<name>]` tables in `.codex/config.toml` (metadata stripped) |
+| `stdio` servers | `{ command, args, env, env_vars }` |
+| `sse` / `streamable-http` servers | `{ url, http_headers, env_http_headers }` (Codex auto-detects transport from the URL) |
+| MCP `env` value `${VAR}` where key == `VAR` | `env_vars = ["VAR"]` (host env forwarding) |
+| MCP `env` value `${OTHER}` (renamed) or literal | left in the `env` table |
+| Header value `${VAR}` | `env_http_headers = { Header = "VAR" }` |
+| Skills (`SKILL.md` + content) | `.agents/skills/{name}/` |
+| Hooks (`HOOK.json` + scripts) | `.codex/hooks/{name}/` + `[[hooks.<Event>]]` registration |
+| Hook events `session_start`, `pre_tool_call`, `post_tool_call`, `user_prompt_submit`, `stop` | Codex `SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop` |
+| References | `{artifact}/references/` |
+
+## Secrets
+
+Codex's config is TOML, which is outside AIR's JSON-based transform/validation pipeline. Instead of writing `${VAR}` placeholders, the adapter maps secret references to Codex's **native host-env forwarding** at translation time:
+
+- `env: { GITHUB_TOKEN: "${GITHUB_TOKEN}" }` → `env_vars = ["GITHUB_TOKEN"]` — Codex injects the host's `GITHUB_TOKEN` at launch.
+- `headers: { Authorization: "${API_TOKEN}" }` → `env_http_headers = { Authorization = "API_TOKEN" }`.
+
+As a result, `prepareSession()` returns an **empty `configFiles` array** — there is no JSON config for secret transforms to post-process.
+
+**Limitation — only whole-value, same-named refs forward.** Codex's `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 ref (`KEY = "${OTHER}"`) or a partial value (`"Bearer ${TOKEN}"`) can't be expressed either way, so it falls through to the literal `env` / `http_headers` table. Because the TOML never passes through AIR's `${VAR}` transform pipeline, Codex would inject the literal `${…}` string at runtime — so the adapter emits a `console.warn` for each such value instead of silently shipping a broken secret. Rewrite these as whole-value, same-named refs (or set the value directly).
+
+## Known gaps
+
+These AIR features have no static Codex equivalent and are handled out of band:
+
+- **OAuth MCP servers** — AIR's detailed OAuth config (`clientId`/`scopes`/`redirectUri`/…) has no static `config.toml` form. Codex performs interactive OAuth via `codex mcp login <name>`.
+- **Plugins** — Codex's marketplace plugins are remote-installed (`codex plugin add`). AIR 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.
+- **Subagent context** — Codex has no `--append-system-prompt` flag, so subagent-root context is returned to the caller via `PreparedSession.subagentContext` rather than passed to the CLI.

package/dist/codex-adapter.d.ts

@@ -0,0 +1,226 @@
+import type { AgentAdapter, AgentSessionConfig, StartCommand, ResolvedArtifacts, RootEntry, McpServerEntry, PluginEntry, PrepareSessionOptions, PreparedSession, CleanSessionOptions, CleanSessionResult, LocalArtifacts } from "@pulsemcp/air-core";
+export declare class CodexAdapter implements AgentAdapter {
+    name: string;
+    displayName: string;
+    /**
+     * 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).
+     */
+    private static readonly AIR_TO_CODEX_EVENT;
+    isAvailable(): Promise<boolean>;
+    generateConfig(artifacts: ResolvedArtifacts, root?: RootEntry, _workDir?: string): AgentSessionConfig;
+    buildStartCommand(config: AgentSessionConfig): StartCommand;
+    /**
+     * 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.
+     */
+    prepareSession(artifacts: ResolvedArtifacts, targetDir: string, options?: PrepareSessionOptions): Promise<PreparedSession>;
+    /**
+     * 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.
+     */
+    listLocalArtifacts(targetDir: string): Promise<LocalArtifacts>;
+    /**
+     * 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.
+     */
+    cleanSession(targetDir: string, options?: CleanSessionOptions): Promise<CleanSessionResult>;
+    /**
+     * 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.
+     */
+    private mcpServerIdsPresent;
+    /**
+     * Resolve subagent roots from the root's default_subagent_roots.
+     * IDs are already qualified after composition-time canonicalization.
+     */
+    private resolveSubagentRoots;
+    /**
+     * Merge subagent roots' default_mcp_servers and default_skills into the
+     * parent's activated sets (union, preserving order with parent first).
+     */
+    private mergeSubagentArtifacts;
+    /**
+     * Build a system prompt section describing the subagent root dependencies.
+     */
+    private buildSubagentContext;
+    /**
+     * 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: Record<string, McpServerEntry>): Record<string, Record<string, unknown>>;
+    private translateMcpServer;
+    /**
+     * 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.
+     */
+    private warnUnforwardableSecret;
+    /**
+     * 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: string, plugin: PluginEntry): Record<string, unknown>;
+    /**
+     * 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)
+     */
+    private resolveActivations;
+    /**
+     * 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.
+     */
+    private missingSourceDirMessage;
+    private formatPoolKeys;
+    /**
+     * Copy referenced documents into a references/ subdirectory of the target.
+     * `refIds` are qualified IDs (post-canonicalization).
+     */
+    private copyReferences;
+    /** Parse an existing `config.toml`, returning `{}` when absent/unparseable. */
+    private readToml;
+    /**
+     * 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.
+     */
+    private writeCodexConfig;
+    /**
+     * 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.
+     */
+    private reconcileConfigHooks;
+    private isManagedHookEntry;
+    /**
+     * 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.
+     */
+    private pruneCodexConfig;
+    /**
+     * 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.
+     */
+    private buildHookCommand;
+    /**
+     * 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.
+     */
+    private anchorHookPath;
+    /**
+     * 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`.
+     */
+    private rewriteHookArgPath;
+    /** Human-readable list of the supported AIR hook event names (snake_case only). */
+    private supportedEventList;
+    private copyDirRecursive;
+}
+//# sourceMappingURL=codex-adapter.d.ts.map

package/dist/codex-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-adapter.d.ts","sourceRoot":"","sources":["../src/codex-adapter.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EAEf,MAAM,oBAAoB,CAAC;AA4B5B,qBAAa,YAAa,YAAW,YAAY;IAC/C,IAAI,SAAW;IACf,WAAW,SAAkB;IAE7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAexC;IAEI,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC,cAAc,CACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,CAAC,EAAE,SAAS,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,kBAAkB;IAmDrB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY;IAa3D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,cAAc,CAClB,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAqM3B;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAIpE;;;;;;;;;;;OAWG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA6G9B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BAA0B,CACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAQ1C,OAAO,CAAC,kBAAkB;IAgD1B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAY/B;;;;;;;;OAQG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ9E;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAgD1B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,cAAc;IAStB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAyBtB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ;IAShB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IAmCxB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAgG5B,OAAO,CAAC,kBAAkB;IAO1B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAKtB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAoB1B,mFAAmF;IACnF,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,gBAAgB;CAYzB"}