@agentplugins/adapter-codex 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @agentplugins/adapter-codex
+
+> AgentPlugins platform adapter for [OpenAI Codex CLI](https://developers.openai.com/codex/plugins).
+
+Compiles a universal `PluginManifest` into OpenAI Codex's native plugin layout: `plugin.json` manifest and `hooks.json` hook wiring (inline handlers are wrapped as Node scripts that receive JSON on stdin and respond on stdout).
+
+## Installation
+
+```bash
+npm install @agentplugins/adapter-codex
+```
+
+Typically installed transitively via [`@agentplugins/cli`](https://www.npmjs.com/package/@agentplugins/cli).
+
+## Usage
+
+```typescript
+import { createCodexAdapter } from '@agentplugins/adapter-codex';
+
+const adapter = createCodexAdapter();
+const output = await adapter.compile(manifest);
+```
+
+Or via the CLI:
+
+```bash
+npx agentplugins build --target codex
+```
+
+## Output shape
+
+A successful build writes to `dist/codex/`:
+
+```
+dist/codex/
+├── .codex-plugin/
+│   └── plugin.json
+└── hooks/
+    └── hooks.json
+```
+
+Install with: `cp -r dist/codex ~/.codex/plugins/`
+
+## Hook protocol
+
+Codex invokes hooks with a JSON event on **stdin** and expects a JSON response on **stdout**. Exit code `0` = allow, `2` = block (for `Stop` / `SubagentStop`).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,103 @@
+import { PlatformAdapter, TargetPlatform, UniversalHookName, HandlerType, PluginManifest, ValidationIssue, AdapterOutput } from '@agentplugins/core';
+
+/**
+ * @agentplugins/adapter-codex
+ *
+ * Platform adapter for OpenAI Codex CLI.
+ *
+ * Codex plugins use a JSON stdin/stdout protocol where:
+ * - Hooks receive JSON events via stdin
+ * - Hooks output JSON responses to stdout
+ * - Exit code 0 = success / allow
+ * - Exit code 2 = block (for Stop / SubagentStop hooks)
+ *
+ * Supported hooks (10):
+ *   SessionStart, SubagentStart, PreToolUse, PermissionRequest,
+ *   PostToolUse, PreCompact, PostCompact, UserPromptSubmit,
+ *   SubagentStop, Stop
+ *
+ * Handler types:
+ *   - command only (stdin/stdout JSON protocol)
+ *
+ * Manifest:
+ *   - .codex-plugin/plugin.json
+ *
+ * Skills:
+ *   - skills/<name>/SKILL.md
+ *
+ * MCP:
+ *   - .mcp.json
+ *
+ * Environment variables:
+ *   - PLUGIN_ROOT  – absolute path to the plugin directory
+ *   - PLUGIN_DATA  – path to a writable data directory
+ */
+
+declare const PLATFORM_NAME: TargetPlatform;
+declare const DISPLAY_NAME = "OpenAI Codex CLI";
+/** Hooks that Codex natively supports. */
+declare const SUPPORTED_HOOKS: readonly UniversalHookName[];
+/** Only command handlers (stdin/stdout JSON protocol) are supported on Codex. */
+declare const SUPPORTED_HANDLERS: readonly HandlerType[];
+declare const MANIFEST_PATH = ".codex-plugin/plugin.json";
+declare const MANIFEST_FORMAT: "json";
+declare const EXIT_CODE_BLOCK = 2;
+declare const EXIT_CODE_SUCCESS = 0;
+/** Mapping from universal hook names to Codex event names. */
+declare const HOOK_NAME_MAP: Partial<Record<(typeof SUPPORTED_HOOKS)[number], string>>;
+/**
+ * AgentPlugins platform adapter for OpenAI Codex CLI.
+ *
+ * Implements the {@link PlatformAdapter} interface to compile
+ * cross-platform AgentPlugins plugins into Codex-compatible plugin
+ * bundles with JSON stdin/stdout command handlers.
+ */
+declare class CodexPlatformAdapter implements PlatformAdapter {
+    readonly name: TargetPlatform;
+    readonly displayName: string;
+    readonly supportedHooks: readonly UniversalHookName[];
+    readonly supportedHandlers: readonly HandlerType[];
+    readonly manifestPath: string;
+    readonly manifestFormat: "json" | "toml";
+    /**
+     * Validate a plugin manifest for Codex compatibility.
+     *
+     * Checks that:
+     * - Only supported hooks are used
+     * - Only "command" handler types are specified
+     * - Inline handlers have either a command or script
+     * - Skills have valid names and non-empty instructions
+     *
+     * @param plugin - The plugin manifest to validate
+     * @returns Array of validation issues (errors and warnings)
+     */
+    validate(plugin: PluginManifest): ValidationIssue[];
+    /**
+     * Compile a plugin manifest into Codex-compatible output files.
+     *
+     * Produces:
+     *   - .codex-plugin/plugin.json  – main manifest
+     *   - skills/<name>/SKILL.md     – skill documentation files
+     *   - .mcp.json                  – MCP server configuration (if any)
+     *   - hooks/<hook-name>.js       – wrapped inline handler scripts
+     *
+     * @param plugin - The plugin manifest to compile
+     * @returns {@link AdapterOutput} with files, manifest, warnings, and post-install notes
+     */
+    compile(plugin: PluginManifest): AdapterOutput;
+}
+/**
+ * Factory function that creates a new {@link CodexPlatformAdapter} instance.
+ *
+ * @example
+ * ```ts
+ * import { createCodexAdapter } from "@agentplugins/adapter-codex";
+ *
+ * const adapter = createCodexAdapter();
+ * const issues = adapter.validate(manifest);
+ * const output = adapter.compile(manifest);
+ * ```
+ */
+declare function createCodexAdapter(): CodexPlatformAdapter;
+
+export { CodexPlatformAdapter, DISPLAY_NAME, EXIT_CODE_BLOCK, EXIT_CODE_SUCCESS, HOOK_NAME_MAP, MANIFEST_FORMAT, MANIFEST_PATH, PLATFORM_NAME, SUPPORTED_HANDLERS, SUPPORTED_HOOKS, createCodexAdapter, createCodexAdapter as default };

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { PlatformAdapter, TargetPlatform, UniversalHookName, HandlerType, PluginManifest, ValidationIssue, AdapterOutput } from '@agentplugins/core';
+
+/**
+ * @agentplugins/adapter-codex
+ *
+ * Platform adapter for OpenAI Codex CLI.
+ *
+ * Codex plugins use a JSON stdin/stdout protocol where:
+ * - Hooks receive JSON events via stdin
+ * - Hooks output JSON responses to stdout
+ * - Exit code 0 = success / allow
+ * - Exit code 2 = block (for Stop / SubagentStop hooks)
+ *
+ * Supported hooks (10):
+ *   SessionStart, SubagentStart, PreToolUse, PermissionRequest,
+ *   PostToolUse, PreCompact, PostCompact, UserPromptSubmit,
+ *   SubagentStop, Stop
+ *
+ * Handler types:
+ *   - command only (stdin/stdout JSON protocol)
+ *
+ * Manifest:
+ *   - .codex-plugin/plugin.json
+ *
+ * Skills:
+ *   - skills/<name>/SKILL.md
+ *
+ * MCP:
+ *   - .mcp.json
+ *
+ * Environment variables:
+ *   - PLUGIN_ROOT  – absolute path to the plugin directory
+ *   - PLUGIN_DATA  – path to a writable data directory
+ */
+
+declare const PLATFORM_NAME: TargetPlatform;
+declare const DISPLAY_NAME = "OpenAI Codex CLI";
+/** Hooks that Codex natively supports. */
+declare const SUPPORTED_HOOKS: readonly UniversalHookName[];
+/** Only command handlers (stdin/stdout JSON protocol) are supported on Codex. */
+declare const SUPPORTED_HANDLERS: readonly HandlerType[];
+declare const MANIFEST_PATH = ".codex-plugin/plugin.json";
+declare const MANIFEST_FORMAT: "json";
+declare const EXIT_CODE_BLOCK = 2;
+declare const EXIT_CODE_SUCCESS = 0;
+/** Mapping from universal hook names to Codex event names. */
+declare const HOOK_NAME_MAP: Partial<Record<(typeof SUPPORTED_HOOKS)[number], string>>;
+/**
+ * AgentPlugins platform adapter for OpenAI Codex CLI.
+ *
+ * Implements the {@link PlatformAdapter} interface to compile
+ * cross-platform AgentPlugins plugins into Codex-compatible plugin
+ * bundles with JSON stdin/stdout command handlers.
+ */
+declare class CodexPlatformAdapter implements PlatformAdapter {
+    readonly name: TargetPlatform;
+    readonly displayName: string;
+    readonly supportedHooks: readonly UniversalHookName[];
+    readonly supportedHandlers: readonly HandlerType[];
+    readonly manifestPath: string;
+    readonly manifestFormat: "json" | "toml";
+    /**
+     * Validate a plugin manifest for Codex compatibility.
+     *
+     * Checks that:
+     * - Only supported hooks are used
+     * - Only "command" handler types are specified
+     * - Inline handlers have either a command or script
+     * - Skills have valid names and non-empty instructions
+     *
+     * @param plugin - The plugin manifest to validate
+     * @returns Array of validation issues (errors and warnings)
+     */
+    validate(plugin: PluginManifest): ValidationIssue[];
+    /**
+     * Compile a plugin manifest into Codex-compatible output files.
+     *
+     * Produces:
+     *   - .codex-plugin/plugin.json  – main manifest
+     *   - skills/<name>/SKILL.md     – skill documentation files
+     *   - .mcp.json                  – MCP server configuration (if any)
+     *   - hooks/<hook-name>.js       – wrapped inline handler scripts
+     *
+     * @param plugin - The plugin manifest to compile
+     * @returns {@link AdapterOutput} with files, manifest, warnings, and post-install notes
+     */
+    compile(plugin: PluginManifest): AdapterOutput;
+}
+/**
+ * Factory function that creates a new {@link CodexPlatformAdapter} instance.
+ *
+ * @example
+ * ```ts
+ * import { createCodexAdapter } from "@agentplugins/adapter-codex";
+ *
+ * const adapter = createCodexAdapter();
+ * const issues = adapter.validate(manifest);
+ * const output = adapter.compile(manifest);
+ * ```
+ */
+declare function createCodexAdapter(): CodexPlatformAdapter;
+
+export { CodexPlatformAdapter, DISPLAY_NAME, EXIT_CODE_BLOCK, EXIT_CODE_SUCCESS, HOOK_NAME_MAP, MANIFEST_FORMAT, MANIFEST_PATH, PLATFORM_NAME, SUPPORTED_HANDLERS, SUPPORTED_HOOKS, createCodexAdapter, createCodexAdapter as default };

package/dist/index.js

@@ -0,0 +1,311 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CodexPlatformAdapter: () => CodexPlatformAdapter,
+  DISPLAY_NAME: () => DISPLAY_NAME,
+  EXIT_CODE_BLOCK: () => EXIT_CODE_BLOCK,
+  EXIT_CODE_SUCCESS: () => EXIT_CODE_SUCCESS,
+  HOOK_NAME_MAP: () => HOOK_NAME_MAP,
+  MANIFEST_FORMAT: () => MANIFEST_FORMAT,
+  MANIFEST_PATH: () => MANIFEST_PATH,
+  PLATFORM_NAME: () => PLATFORM_NAME,
+  SUPPORTED_HANDLERS: () => SUPPORTED_HANDLERS,
+  SUPPORTED_HOOKS: () => SUPPORTED_HOOKS,
+  createCodexAdapter: () => createCodexAdapter,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@agentplugins/core");
+var PLATFORM_NAME = "codex";
+var DISPLAY_NAME = "OpenAI Codex CLI";
+var SUPPORTED_HOOKS = [
+  "sessionStart",
+  "subagentStart",
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "userPromptSubmit",
+  "subagentStop",
+  "stop"
+];
+var SUPPORTED_HANDLERS = ["command"];
+var MANIFEST_PATH = ".codex-plugin/plugin.json";
+var MANIFEST_FORMAT = "json";
+var EXIT_CODE_BLOCK = 2;
+var EXIT_CODE_SUCCESS = 0;
+var HOOK_NAME_MAP = {
+  sessionStart: "SessionStart",
+  subagentStart: "SubagentStart",
+  preToolUse: "PreToolUse",
+  permissionRequest: "PermissionRequest",
+  postToolUse: "PostToolUse",
+  preCompact: "PreCompact",
+  postCompact: "PostCompact",
+  userPromptSubmit: "UserPromptSubmit",
+  subagentStop: "SubagentStop",
+  stop: "Stop"
+};
+var TOOL_MATCHED_HOOKS = [
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse"
+];
+function validateHook(hookName, hook) {
+  const issues = [];
+  const codexEvent = HOOK_NAME_MAP[hookName];
+  if (!codexEvent) {
+    issues.push({
+      severity: import_core.Severity.ERROR,
+      message: `Hook "${hookName}" is not supported by Codex. Supported hooks: ${SUPPORTED_HOOKS.join(", ")}.`,
+      field: `hooks.${hookName}`,
+      suggestion: `Remove this hook or use a command handler instead.`
+    });
+    return issues;
+  }
+  if (hook.handler && hook.handler.type !== "command") {
+    issues.push({
+      severity: import_core.Severity.ERROR,
+      message: `Codex only supports "command" handlers. Hook "${hookName}" specifies type "${hook.handler.type}".`,
+      field: `hooks.${hookName}.handler.type`,
+      suggestion: `Use a command handler instead of an inline handler.`
+    });
+  }
+  return issues;
+}
+function validateSkill(skill, index) {
+  const issues = [];
+  if (!skill.name || skill.name.trim().length === 0) {
+    issues.push({
+      severity: import_core.Severity.ERROR,
+      message: `Skill at index ${index} must have a non-empty name.`,
+      field: `skills[${index}].name`
+    });
+  }
+  if (!skill.content || skill.content.trim().length === 0) {
+    issues.push({
+      severity: import_core.Severity.WARNING,
+      message: `Skill "${skill.name}" has empty content.`,
+      field: `skills[${index}].content`
+    });
+  }
+  return issues;
+}
+function buildCodexHookEntry(hookName, hook) {
+  const codexEvent = HOOK_NAME_MAP[hookName];
+  const entry = {
+    event: codexEvent
+  };
+  if (TOOL_MATCHED_HOOKS.includes(codexEvent)) {
+    entry.matcher = hook.matcher ?? "*";
+  }
+  if (hook.handler.type === "command") {
+    entry.command = hook.handler.command;
+  }
+  return entry;
+}
+function buildManifest(plugin, hookEntries) {
+  return {
+    name: plugin.name,
+    version: plugin.version,
+    description: plugin.description,
+    hooks: hookEntries,
+    environment: {
+      PLUGIN_ROOT: "${PLUGIN_ROOT}",
+      PLUGIN_DATA: "${PLUGIN_DATA}"
+    }
+  };
+}
+function buildMcpManifest(plugin) {
+  if (!plugin.mcpServers || Object.keys(plugin.mcpServers).length === 0) {
+    return null;
+  }
+  const servers = {};
+  for (const [name, server] of Object.entries(plugin.mcpServers)) {
+    servers[name] = {
+      command: server.command,
+      ...server.args && server.args.length > 0 ? { args: server.args } : {},
+      ...server.env ? { env: server.env } : {}
+    };
+  }
+  return { servers };
+}
+function buildSkillFile(skill) {
+  const parts = [];
+  parts.push(`# ${skill.name}`);
+  parts.push("");
+  if (skill.description) {
+    parts.push(skill.description);
+    parts.push("");
+  }
+  if (skill.content) {
+    parts.push(skill.content);
+  }
+  return parts.join("\n");
+}
+var CodexPlatformAdapter = class {
+  name = PLATFORM_NAME;
+  displayName = DISPLAY_NAME;
+  supportedHooks = SUPPORTED_HOOKS;
+  supportedHandlers = SUPPORTED_HANDLERS;
+  manifestPath = MANIFEST_PATH;
+  manifestFormat = MANIFEST_FORMAT;
+  /**
+   * Validate a plugin manifest for Codex compatibility.
+   *
+   * Checks that:
+   * - Only supported hooks are used
+   * - Only "command" handler types are specified
+   * - Inline handlers have either a command or script
+   * - Skills have valid names and non-empty instructions
+   *
+   * @param plugin - The plugin manifest to validate
+   * @returns Array of validation issues (errors and warnings)
+   */
+  validate(plugin) {
+    const issues = [];
+    if (plugin.hooks) {
+      for (const [hookName, hookDef] of Object.entries(plugin.hooks)) {
+        issues.push(...validateHook(hookName, hookDef));
+      }
+    }
+    if (plugin.skills) {
+      for (let i = 0; i < plugin.skills.length; i++) {
+        issues.push(...validateSkill(plugin.skills[i], i));
+      }
+    }
+    return issues;
+  }
+  /**
+   * Compile a plugin manifest into Codex-compatible output files.
+   *
+   * Produces:
+   *   - .codex-plugin/plugin.json  – main manifest
+   *   - skills/<name>/SKILL.md     – skill documentation files
+   *   - .mcp.json                  – MCP server configuration (if any)
+   *   - hooks/<hook-name>.js       – wrapped inline handler scripts
+   *
+   * @param plugin - The plugin manifest to compile
+   * @returns {@link AdapterOutput} with files, manifest, warnings, and post-install notes
+   */
+  compile(plugin) {
+    const files = [];
+    const warnings = [];
+    const hookEntries = [];
+    if (plugin.hooks) {
+      for (const [hookName, hookDef] of Object.entries(plugin.hooks)) {
+        const codexEvent = HOOK_NAME_MAP[hookName];
+        if (!codexEvent) {
+          warnings.push(
+            `Skipping unsupported hook "${hookName}" \u2013 not included in compiled output.`
+          );
+          continue;
+        }
+        const entry = buildCodexHookEntry(hookName, hookDef);
+        if (hookDef.handler.type === "command") {
+          entry.command = hookDef.handler.command;
+          hookEntries.push(entry);
+        } else {
+          warnings.push(
+            `Hook "${hookName}": inline handlers are not supported on Codex. Use command handlers instead.`
+          );
+        }
+      }
+    }
+    if (plugin.skills) {
+      for (const skill of plugin.skills) {
+        const skillPath = `skills/${skill.name}/SKILL.md`;
+        const skillContent = buildSkillFile(skill);
+        files.push({
+          path: skillPath,
+          content: skillContent
+        });
+      }
+    }
+    const manifest = buildManifest(plugin, hookEntries);
+    files.push({
+      path: MANIFEST_PATH,
+      content: JSON.stringify(manifest, null, 2)
+    });
+    const mcpManifest = buildMcpManifest(plugin);
+    if (mcpManifest) {
+      files.push({
+        path: ".mcp.json",
+        content: JSON.stringify(mcpManifest, null, 2)
+      });
+    }
+    const postInstall = [
+      "OpenAI Codex Plugin",
+      "===================",
+      "",
+      `Plugin "${plugin.name}" v${plugin.version} compiled for Codex.`,
+      "",
+      "Install:",
+      `  1. Copy the generated files into your project root (or a sub-directory).`,
+      `  2. Ensure the hook scripts under hooks/ are executable:`,
+      `       chmod +x hooks/*.js`,
+      `  3. Set environment variables:`,
+      `       export PLUGIN_ROOT=/path/to/plugin`,
+      `       export PLUGIN_DATA=/path/to/plugin/data`,
+      `  4. Codex will auto-discover .codex-plugin/plugin.json when running`,
+      `     in the project directory.`,
+      "",
+      "Hook protocol:",
+      "  - Codex sends JSON events to each hook via stdin.",
+      "  - Hooks respond with JSON on stdout.",
+      "  - Exit code 0 = success / allow the operation.",
+      `  - Exit code ${EXIT_CODE_BLOCK} = block (for Stop / SubagentStop hooks).`,
+      "",
+      "Output formats:",
+      '  SessionStart        \u2192 { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "..." } }',
+      '  PreToolUse          \u2192 { "systemMessage": "Warning message" }',
+      '  Stop / SubagentStop \u2192 { "decision": "block", "reason": "..." } (or exit 2)',
+      ""
+    ];
+    return {
+      files,
+      manifest,
+      warnings,
+      issues: [],
+      postInstall
+    };
+  }
+};
+function createCodexAdapter() {
+  return new CodexPlatformAdapter();
+}
+var index_default = createCodexAdapter;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CodexPlatformAdapter,
+  DISPLAY_NAME,
+  EXIT_CODE_BLOCK,
+  EXIT_CODE_SUCCESS,
+  HOOK_NAME_MAP,
+  MANIFEST_FORMAT,
+  MANIFEST_PATH,
+  PLATFORM_NAME,
+  SUPPORTED_HANDLERS,
+  SUPPORTED_HOOKS,
+  createCodexAdapter
+});

package/dist/index.mjs

@@ -0,0 +1,276 @@
+// src/index.ts
+import { Severity } from "@agentplugins/core";
+var PLATFORM_NAME = "codex";
+var DISPLAY_NAME = "OpenAI Codex CLI";
+var SUPPORTED_HOOKS = [
+  "sessionStart",
+  "subagentStart",
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "userPromptSubmit",
+  "subagentStop",
+  "stop"
+];
+var SUPPORTED_HANDLERS = ["command"];
+var MANIFEST_PATH = ".codex-plugin/plugin.json";
+var MANIFEST_FORMAT = "json";
+var EXIT_CODE_BLOCK = 2;
+var EXIT_CODE_SUCCESS = 0;
+var HOOK_NAME_MAP = {
+  sessionStart: "SessionStart",
+  subagentStart: "SubagentStart",
+  preToolUse: "PreToolUse",
+  permissionRequest: "PermissionRequest",
+  postToolUse: "PostToolUse",
+  preCompact: "PreCompact",
+  postCompact: "PostCompact",
+  userPromptSubmit: "UserPromptSubmit",
+  subagentStop: "SubagentStop",
+  stop: "Stop"
+};
+var TOOL_MATCHED_HOOKS = [
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse"
+];
+function validateHook(hookName, hook) {
+  const issues = [];
+  const codexEvent = HOOK_NAME_MAP[hookName];
+  if (!codexEvent) {
+    issues.push({
+      severity: Severity.ERROR,
+      message: `Hook "${hookName}" is not supported by Codex. Supported hooks: ${SUPPORTED_HOOKS.join(", ")}.`,
+      field: `hooks.${hookName}`,
+      suggestion: `Remove this hook or use a command handler instead.`
+    });
+    return issues;
+  }
+  if (hook.handler && hook.handler.type !== "command") {
+    issues.push({
+      severity: Severity.ERROR,
+      message: `Codex only supports "command" handlers. Hook "${hookName}" specifies type "${hook.handler.type}".`,
+      field: `hooks.${hookName}.handler.type`,
+      suggestion: `Use a command handler instead of an inline handler.`
+    });
+  }
+  return issues;
+}
+function validateSkill(skill, index) {
+  const issues = [];
+  if (!skill.name || skill.name.trim().length === 0) {
+    issues.push({
+      severity: Severity.ERROR,
+      message: `Skill at index ${index} must have a non-empty name.`,
+      field: `skills[${index}].name`
+    });
+  }
+  if (!skill.content || skill.content.trim().length === 0) {
+    issues.push({
+      severity: Severity.WARNING,
+      message: `Skill "${skill.name}" has empty content.`,
+      field: `skills[${index}].content`
+    });
+  }
+  return issues;
+}
+function buildCodexHookEntry(hookName, hook) {
+  const codexEvent = HOOK_NAME_MAP[hookName];
+  const entry = {
+    event: codexEvent
+  };
+  if (TOOL_MATCHED_HOOKS.includes(codexEvent)) {
+    entry.matcher = hook.matcher ?? "*";
+  }
+  if (hook.handler.type === "command") {
+    entry.command = hook.handler.command;
+  }
+  return entry;
+}
+function buildManifest(plugin, hookEntries) {
+  return {
+    name: plugin.name,
+    version: plugin.version,
+    description: plugin.description,
+    hooks: hookEntries,
+    environment: {
+      PLUGIN_ROOT: "${PLUGIN_ROOT}",
+      PLUGIN_DATA: "${PLUGIN_DATA}"
+    }
+  };
+}
+function buildMcpManifest(plugin) {
+  if (!plugin.mcpServers || Object.keys(plugin.mcpServers).length === 0) {
+    return null;
+  }
+  const servers = {};
+  for (const [name, server] of Object.entries(plugin.mcpServers)) {
+    servers[name] = {
+      command: server.command,
+      ...server.args && server.args.length > 0 ? { args: server.args } : {},
+      ...server.env ? { env: server.env } : {}
+    };
+  }
+  return { servers };
+}
+function buildSkillFile(skill) {
+  const parts = [];
+  parts.push(`# ${skill.name}`);
+  parts.push("");
+  if (skill.description) {
+    parts.push(skill.description);
+    parts.push("");
+  }
+  if (skill.content) {
+    parts.push(skill.content);
+  }
+  return parts.join("\n");
+}
+var CodexPlatformAdapter = class {
+  name = PLATFORM_NAME;
+  displayName = DISPLAY_NAME;
+  supportedHooks = SUPPORTED_HOOKS;
+  supportedHandlers = SUPPORTED_HANDLERS;
+  manifestPath = MANIFEST_PATH;
+  manifestFormat = MANIFEST_FORMAT;
+  /**
+   * Validate a plugin manifest for Codex compatibility.
+   *
+   * Checks that:
+   * - Only supported hooks are used
+   * - Only "command" handler types are specified
+   * - Inline handlers have either a command or script
+   * - Skills have valid names and non-empty instructions
+   *
+   * @param plugin - The plugin manifest to validate
+   * @returns Array of validation issues (errors and warnings)
+   */
+  validate(plugin) {
+    const issues = [];
+    if (plugin.hooks) {
+      for (const [hookName, hookDef] of Object.entries(plugin.hooks)) {
+        issues.push(...validateHook(hookName, hookDef));
+      }
+    }
+    if (plugin.skills) {
+      for (let i = 0; i < plugin.skills.length; i++) {
+        issues.push(...validateSkill(plugin.skills[i], i));
+      }
+    }
+    return issues;
+  }
+  /**
+   * Compile a plugin manifest into Codex-compatible output files.
+   *
+   * Produces:
+   *   - .codex-plugin/plugin.json  – main manifest
+   *   - skills/<name>/SKILL.md     – skill documentation files
+   *   - .mcp.json                  – MCP server configuration (if any)
+   *   - hooks/<hook-name>.js       – wrapped inline handler scripts
+   *
+   * @param plugin - The plugin manifest to compile
+   * @returns {@link AdapterOutput} with files, manifest, warnings, and post-install notes
+   */
+  compile(plugin) {
+    const files = [];
+    const warnings = [];
+    const hookEntries = [];
+    if (plugin.hooks) {
+      for (const [hookName, hookDef] of Object.entries(plugin.hooks)) {
+        const codexEvent = HOOK_NAME_MAP[hookName];
+        if (!codexEvent) {
+          warnings.push(
+            `Skipping unsupported hook "${hookName}" \u2013 not included in compiled output.`
+          );
+          continue;
+        }
+        const entry = buildCodexHookEntry(hookName, hookDef);
+        if (hookDef.handler.type === "command") {
+          entry.command = hookDef.handler.command;
+          hookEntries.push(entry);
+        } else {
+          warnings.push(
+            `Hook "${hookName}": inline handlers are not supported on Codex. Use command handlers instead.`
+          );
+        }
+      }
+    }
+    if (plugin.skills) {
+      for (const skill of plugin.skills) {
+        const skillPath = `skills/${skill.name}/SKILL.md`;
+        const skillContent = buildSkillFile(skill);
+        files.push({
+          path: skillPath,
+          content: skillContent
+        });
+      }
+    }
+    const manifest = buildManifest(plugin, hookEntries);
+    files.push({
+      path: MANIFEST_PATH,
+      content: JSON.stringify(manifest, null, 2)
+    });
+    const mcpManifest = buildMcpManifest(plugin);
+    if (mcpManifest) {
+      files.push({
+        path: ".mcp.json",
+        content: JSON.stringify(mcpManifest, null, 2)
+      });
+    }
+    const postInstall = [
+      "OpenAI Codex Plugin",
+      "===================",
+      "",
+      `Plugin "${plugin.name}" v${plugin.version} compiled for Codex.`,
+      "",
+      "Install:",
+      `  1. Copy the generated files into your project root (or a sub-directory).`,
+      `  2. Ensure the hook scripts under hooks/ are executable:`,
+      `       chmod +x hooks/*.js`,
+      `  3. Set environment variables:`,
+      `       export PLUGIN_ROOT=/path/to/plugin`,
+      `       export PLUGIN_DATA=/path/to/plugin/data`,
+      `  4. Codex will auto-discover .codex-plugin/plugin.json when running`,
+      `     in the project directory.`,
+      "",
+      "Hook protocol:",
+      "  - Codex sends JSON events to each hook via stdin.",
+      "  - Hooks respond with JSON on stdout.",
+      "  - Exit code 0 = success / allow the operation.",
+      `  - Exit code ${EXIT_CODE_BLOCK} = block (for Stop / SubagentStop hooks).`,
+      "",
+      "Output formats:",
+      '  SessionStart        \u2192 { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "..." } }',
+      '  PreToolUse          \u2192 { "systemMessage": "Warning message" }',
+      '  Stop / SubagentStop \u2192 { "decision": "block", "reason": "..." } (or exit 2)',
+      ""
+    ];
+    return {
+      files,
+      manifest,
+      warnings,
+      issues: [],
+      postInstall
+    };
+  }
+};
+function createCodexAdapter() {
+  return new CodexPlatformAdapter();
+}
+var index_default = createCodexAdapter;
+export {
+  CodexPlatformAdapter,
+  DISPLAY_NAME,
+  EXIT_CODE_BLOCK,
+  EXIT_CODE_SUCCESS,
+  HOOK_NAME_MAP,
+  MANIFEST_FORMAT,
+  MANIFEST_PATH,
+  PLATFORM_NAME,
+  SUPPORTED_HANDLERS,
+  SUPPORTED_HOOKS,
+  createCodexAdapter,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@agentplugins/adapter-codex",
+  "version": "0.1.0",
+  "description": "AgentPlugins platform adapter for OpenAI Codex CLI",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/**/*.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@agentplugins/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@agentplugins/core": "^0.1.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/espetro/agentplugins.git",
+    "directory": "packages/adapter-codex"
+  },
+  "keywords": [
+    "agentplugins",
+    "codex",
+    "openai",
+    "cli",
+    "adapter"
+  ]
+}