@cleocode/adapters 2026.3.72 → 2026.3.73

package/src/providers/codex/adapter.ts

@@ -0,0 +1,154 @@
+/**
+ * Codex CLI Adapter
+ *
+ * Main CLEOProviderAdapter implementation for OpenAI Codex CLI.
+ * Provides hooks and install capabilities for CLEO integration.
+ *
+ * @task T162
+ * @epic T134
+ */
+
+import { exec } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import type {
+  AdapterCapabilities,
+  AdapterHealthStatus,
+  CLEOProviderAdapter,
+} from '@cleocode/contracts';
+import { CodexHookProvider } from './hooks.js';
+import { CodexInstallProvider } from './install.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * CLEO provider adapter for OpenAI Codex CLI.
+ *
+ * Bridges CLEO's adapter system with Codex CLI's native capabilities:
+ * - Hooks: Maps Codex events (SessionStart, PromptSubmit, ResponseComplete) to CAAMP events
+ * - Install: Registers MCP server in ~/.codex/config.json and ensures AGENTS.md references
+ *
+ * @task T162
+ * @epic T134
+ */
+export class CodexAdapter implements CLEOProviderAdapter {
+  readonly id = 'codex';
+  readonly name = 'Codex';
+  readonly version = '1.0.0';
+
+  capabilities: AdapterCapabilities = {
+    supportsHooks: true,
+    supportedHookEvents: ['SessionStart', 'UserPromptSubmit', 'Stop'],
+    supportsSpawn: false,
+    supportsInstall: true,
+    supportsMcp: true,
+    supportsInstructionFiles: false,
+    supportsContextMonitor: false,
+    supportsStatusline: false,
+    supportsProviderPaths: false,
+    supportsTransport: false,
+    supportsTaskSync: false,
+  };
+
+  hooks: CodexHookProvider;
+  install: CodexInstallProvider;
+
+  private projectDir: string | null = null;
+  private initialized = false;
+
+  constructor() {
+    this.hooks = new CodexHookProvider();
+    this.install = new CodexInstallProvider();
+  }
+
+  /**
+   * Initialize the adapter for a given project directory.
+   *
+   * @param projectDir - Root directory of the project
+   * @task T162
+   */
+  async initialize(projectDir: string): Promise<void> {
+    this.projectDir = projectDir;
+    this.initialized = true;
+  }
+
+  /**
+   * Dispose the adapter and clean up resources.
+   *
+   * Unregisters hooks and releases any tracked state.
+   * @task T162
+   */
+  async dispose(): Promise<void> {
+    if (this.hooks.isRegistered()) {
+      await this.hooks.unregisterNativeHooks();
+    }
+    this.initialized = false;
+    this.projectDir = null;
+  }
+
+  /**
+   * Run a health check to verify Codex CLI is accessible.
+   *
+   * Checks:
+   * 1. Adapter has been initialized
+   * 2. Codex CLI binary is available in PATH
+   * 3. ~/.codex/ configuration directory exists
+   *
+   * @returns Health status with details about each check
+   * @task T162
+   */
+  async healthCheck(): Promise<AdapterHealthStatus> {
+    const details: Record<string, unknown> = {};
+
+    if (!this.initialized) {
+      return {
+        healthy: false,
+        provider: this.id,
+        details: { error: 'Adapter not initialized' },
+      };
+    }
+
+    // Check Codex CLI availability
+    let cliAvailable = false;
+    try {
+      const { stdout } = await execAsync('which codex');
+      cliAvailable = stdout.trim().length > 0;
+      details.cliPath = stdout.trim();
+    } catch {
+      details.cliAvailable = false;
+    }
+
+    // Check for Codex CLI config directory
+    const codexConfigDir = join(homedir(), '.codex');
+    const configExists = existsSync(codexConfigDir);
+    details.configDirExists = configExists;
+
+    // Healthy if CLI is available (primary requirement)
+    const healthy = cliAvailable;
+    details.cliAvailable = cliAvailable;
+
+    return {
+      healthy,
+      provider: this.id,
+      details,
+    };
+  }
+
+  /**
+   * Check whether the adapter has been initialized.
+   * @task T162
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get the project directory this adapter was initialized with.
+   * @task T162
+   */
+  getProjectDir(): string | null {
+    return this.projectDir;
+  }
+}

package/src/providers/codex/hooks.ts

@@ -0,0 +1,163 @@
+/**
+ * Codex CLI Hook Provider
+ *
+ * Maps Codex CLI's native hook events to CAAMP canonical hook events.
+ * Codex CLI supports 3 canonical events through its hook system.
+ *
+ * Codex CLI event mapping:
+ * - SessionStart      -> SessionStart
+ * - PromptSubmit      -> UserPromptSubmit
+ * - ResponseComplete  -> Stop
+ *
+ * @task T162
+ * @epic T134
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { AdapterHookProvider } from '@cleocode/contracts';
+
+/**
+ * Mapping from Codex CLI native event names to CAAMP canonical event names.
+ */
+const CODEX_EVENT_MAP: Record<string, string> = {
+  SessionStart: 'SessionStart',
+  PromptSubmit: 'UserPromptSubmit',
+  ResponseComplete: 'Stop',
+};
+
+/**
+ * Hook provider for Codex CLI.
+ *
+ * Codex CLI registers hooks via its configuration system at
+ * ~/.codex/. Hook handlers are shell commands or script paths that
+ * execute when the corresponding event fires.
+ *
+ * Since hooks are registered through the config system (managed by
+ * the install provider), registerNativeHooks and unregisterNativeHooks
+ * track registration state without performing filesystem operations.
+ *
+ * @task T162
+ * @epic T134
+ */
+export class CodexHookProvider implements AdapterHookProvider {
+  private registered = false;
+
+  /**
+   * Map a Codex CLI native event name to a CAAMP hook event name.
+   *
+   * @param providerEvent - Codex CLI event name (e.g. "SessionStart", "PromptSubmit")
+   * @returns CAAMP event name or null if unmapped
+   * @task T162
+   */
+  mapProviderEvent(providerEvent: string): string | null {
+    return CODEX_EVENT_MAP[providerEvent] ?? null;
+  }
+
+  /**
+   * Register native hooks for a project.
+   *
+   * For Codex CLI, hooks are registered via the config system
+   * (~/.codex/), which is handled by the install provider.
+   * This method marks hooks as registered without performing
+   * filesystem operations.
+   *
+   * @param _projectDir - Project directory (unused; hooks are global)
+   * @task T162
+   */
+  async registerNativeHooks(_projectDir: string): Promise<void> {
+    this.registered = true;
+  }
+
+  /**
+   * Unregister native hooks.
+   *
+   * For Codex CLI, this is a no-op since hooks are managed through
+   * the config system. Unregistration happens via the install
+   * provider's uninstall method.
+   * @task T162
+   */
+  async unregisterNativeHooks(): Promise<void> {
+    this.registered = false;
+  }
+
+  /**
+   * Check whether hooks have been registered via registerNativeHooks.
+   * @task T162
+   */
+  isRegistered(): boolean {
+    return this.registered;
+  }
+
+  /**
+   * Get the full event mapping for introspection/debugging.
+   * @task T162
+   */
+  getEventMap(): Readonly<Record<string, string>> {
+    return { ...CODEX_EVENT_MAP };
+  }
+
+  /**
+   * Extract a plain-text transcript from Codex CLI session data.
+   *
+   * Reads the most recent session file under ~/.codex/ and extracts
+   * turn text into a flat string for brain observation extraction.
+   *
+   * Returns null when no session data is found or on any read error.
+   *
+   * @param _sessionId - CLEO session ID (unused; reads the most recent file)
+   * @param _projectDir - Project directory (unused; Codex CLI uses global paths)
+   * @task T162 @epic T134
+   */
+  async getTranscript(_sessionId: string, _projectDir: string): Promise<string | null> {
+    try {
+      const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? '/root';
+      const codexDir = join(homeDir, '.codex');
+
+      let allFiles: string[] = [];
+      try {
+        const entries = await readdir(codexDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isFile()) continue;
+          const name = entry.name;
+          if (name.endsWith('.json') || name.endsWith('.jsonl')) {
+            allFiles.push(join(codexDir, name));
+          }
+        }
+      } catch {
+        return null;
+      }
+
+      if (allFiles.length === 0) return null;
+
+      // Sort descending by filename (timestamps in filenames sort naturally)
+      allFiles = allFiles.sort((a, b) => b.localeCompare(a));
+      const mostRecent = allFiles[0];
+      if (!mostRecent) return null;
+
+      const raw = await readFile(mostRecent, 'utf-8');
+      const turns: string[] = [];
+
+      // Support both JSONL (one JSON per line) and JSON array formats
+      const lines = raw.split('\n').filter((l) => l.trim());
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line) as Record<string, unknown>;
+          const role = entry.role as string | undefined;
+          const content = entry.content;
+          if (role === 'assistant' && typeof content === 'string') {
+            turns.push(`assistant: ${content}`);
+          } else if (role === 'user' && typeof content === 'string') {
+            turns.push(`user: ${content}`);
+          }
+        } catch {
+          // Skip malformed lines
+        }
+      }
+
+      return turns.length > 0 ? turns.join('\n') : null;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/providers/codex/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Codex CLI provider adapter.
+ *
+ * CLEO provider adapter for OpenAI Codex CLI.
+ * Default export is the adapter class for dynamic loading by AdapterManager.
+ *
+ * @task T162
+ * @epic T134
+ */
+
+import { CodexAdapter } from './adapter.js';
+
+export { CodexAdapter } from './adapter.js';
+export { CodexHookProvider } from './hooks.js';
+export { CodexInstallProvider } from './install.js';
+
+export default CodexAdapter;
+
+/**
+ * Factory function for creating adapter instances.
+ * Used by AdapterManager's dynamic import fallback.
+ *
+ * @task T162
+ */
+export function createAdapter(): CodexAdapter {
+  return new CodexAdapter();
+}

package/src/providers/codex/install.ts

@@ -0,0 +1,203 @@
+/**
+ * Codex CLI Install Provider
+ *
+ * Handles CLEO installation into Codex CLI environments:
+ * - Registers CLEO MCP server in ~/.codex/config.json
+ * - Ensures AGENTS.md has CLEO @-references
+ *
+ * @task T162
+ * @epic T134
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+
+/** Lines that should appear in AGENTS.md to reference CLEO. */
+const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+
+/** MCP server registration key used in Codex CLI config. */
+const MCP_SERVER_KEY = 'cleo';
+
+/**
+ * Install provider for Codex CLI.
+ *
+ * Manages CLEO's integration with Codex CLI by:
+ * 1. Registering the CLEO MCP server in ~/.codex/config.json
+ * 2. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ *
+ * @task T162
+ * @epic T134
+ */
+export class CodexInstallProvider implements AdapterInstallProvider {
+  /**
+   * Install CLEO into a Codex CLI environment.
+   *
+   * @param options - Installation options including project directory and MCP server path
+   * @returns Result describing what was installed
+   * @task T162
+   */
+  async install(options: InstallOptions): Promise<InstallResult> {
+    const { projectDir, mcpServerPath } = options;
+    const installedAt = new Date().toISOString();
+    let instructionFileUpdated = false;
+    let mcpRegistered = false;
+    const details: Record<string, unknown> = {};
+
+    // Step 1: Register MCP server in ~/.codex/config.json
+    if (mcpServerPath) {
+      mcpRegistered = this.registerMcpServer(mcpServerPath);
+      if (mcpRegistered) {
+        details.mcpConfigPath = join(homedir(), '.codex', 'config.json');
+      }
+    }
+
+    // Step 2: Ensure AGENTS.md has @-references
+    instructionFileUpdated = this.updateInstructionFile(projectDir);
+    if (instructionFileUpdated) {
+      details.instructionFile = join(projectDir, 'AGENTS.md');
+    }
+
+    return {
+      success: true,
+      installedAt,
+      instructionFileUpdated,
+      mcpRegistered,
+      details,
+    };
+  }
+
+  /**
+   * Uninstall CLEO from the Codex CLI environment.
+   *
+   * Removes the MCP server registration from ~/.codex/config.json.
+   * Does not remove AGENTS.md references (they are harmless if CLEO is not present).
+   * @task T162
+   */
+  async uninstall(): Promise<void> {
+    const configPath = join(homedir(), '.codex', 'config.json');
+    if (existsSync(configPath)) {
+      try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const config = JSON.parse(raw) as Record<string, unknown>;
+        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
+        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
+          delete mcpServers[MCP_SERVER_KEY];
+          writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        }
+      } catch {
+        // Ignore errors during uninstall
+      }
+    }
+  }
+
+  /**
+   * Check whether CLEO is installed in the Codex CLI environment.
+   *
+   * Checks for MCP server registered in ~/.codex/config.json.
+   * Returns true if the CLEO MCP server entry is found.
+   * @task T162
+   */
+  async isInstalled(): Promise<boolean> {
+    const configPath = join(homedir(), '.codex', 'config.json');
+    if (existsSync(configPath)) {
+      try {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
+        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
+          return true;
+        }
+      } catch {
+        // Fall through
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Ensure AGENTS.md contains @-references to CLEO instruction files.
+   *
+   * Creates AGENTS.md if it does not exist. Appends any missing references.
+   *
+   * @param projectDir - Project root directory
+   * @task T162
+   */
+  async ensureInstructionReferences(projectDir: string): Promise<void> {
+    this.updateInstructionFile(projectDir);
+  }
+
+  /**
+   * Register the CLEO MCP server in ~/.codex/config.json.
+   *
+   * Codex CLI stores its MCP server configuration in ~/.codex/config.json
+   * under the mcpServers key.
+   *
+   * @param mcpServerPath - Absolute path to the MCP server entry point
+   * @returns true if registration was performed or updated
+   */
+  private registerMcpServer(mcpServerPath: string): boolean {
+    const codexDir = join(homedir(), '.codex');
+    const configPath = join(codexDir, 'config.json');
+    let config: Record<string, unknown> = {};
+
+    mkdirSync(codexDir, { recursive: true });
+
+    if (existsSync(configPath)) {
+      try {
+        config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      } catch {
+        // Start fresh on parse error
+      }
+    }
+
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+      config.mcpServers = {};
+    }
+
+    const mcpServers = config.mcpServers as Record<string, unknown>;
+    mcpServers[MCP_SERVER_KEY] = {
+      command: 'node',
+      args: [mcpServerPath],
+    };
+
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return true;
+  }
+
+  /**
+   * Update AGENTS.md with CLEO @-references.
+   *
+   * @param projectDir - Project root directory
+   * @returns true if the file was created or modified
+   */
+  private updateInstructionFile(projectDir: string): boolean {
+    const agentsMdPath = join(projectDir, 'AGENTS.md');
+    let content = '';
+    let existed = false;
+
+    if (existsSync(agentsMdPath)) {
+      content = readFileSync(agentsMdPath, 'utf-8');
+      existed = true;
+    }
+
+    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
+
+    if (missingRefs.length === 0) {
+      return false;
+    }
+
+    const refsBlock = missingRefs.join('\n');
+
+    if (existed) {
+      const separator = content.endsWith('\n') ? '' : '\n';
+      content = content + separator + refsBlock + '\n';
+    } else {
+      content = refsBlock + '\n';
+    }
+
+    writeFileSync(agentsMdPath, content, 'utf-8');
+    return true;
+  }
+}

package/src/providers/codex/manifest.json

@@ -0,0 +1,28 @@
+{
+  "id": "codex",
+  "name": "Codex Adapter",
+  "version": "1.0.0",
+  "description": "CLEO adapter for OpenAI Codex CLI",
+  "provider": "codex",
+  "entryPoint": "src/index.ts",
+  "capabilities": {
+    "supportsHooks": true,
+    "supportedHookEvents": [
+      "SessionStart",
+      "UserPromptSubmit",
+      "Stop"
+    ],
+    "supportsSpawn": false,
+    "supportsInstall": true,
+    "supportsMcp": true,
+    "supportsInstructionFiles": false,
+    "supportsContextMonitor": false,
+    "supportsStatusline": false,
+    "supportsProviderPaths": false,
+    "supportsTransport": false
+  },
+  "detectionPatterns": [
+    { "type": "cli", "pattern": "codex", "description": "Codex CLI binary available in PATH" },
+    { "type": "directory", "pattern": "~/.codex", "description": "Codex CLI config directory" }
+  ]
+}

package/src/providers/cursor/adapter.ts

@@ -33,8 +33,22 @@ export class CursorAdapter implements CLEOProviderAdapter {
   readonly version = '1.0.0';
 
   capabilities: AdapterCapabilities = {
-    supportsHooks: false,
-    supportedHookEvents: [],
+    supportsHooks: true,
+    // 10/16 canonical events — derived from getProviderHookProfile('cursor') in CAAMP 1.9.1.
+    // PermissionRequest, PreModel, PostModel, PostCompact, Notification, ConfigChange are
+    // not supported by Cursor's hook system.
+    supportedHookEvents: [
+      'SessionStart',
+      'SessionEnd',
+      'PromptSubmit',
+      'ResponseComplete',
+      'PreToolUse',
+      'PostToolUse',
+      'PostToolUseFailure',
+      'SubagentStart',
+      'SubagentStop',
+      'PreCompact',
+    ],
     supportsSpawn: false,
     supportsInstall: true,
     supportsMcp: true,