@cleocode/adapters 2026.3.72 → 2026.3.73

package/src/providers/cursor/hooks.ts

@@ -1,43 +1,116 @@
 /**
  * Cursor Hook Provider
  *
- * Cursor does not have a native hook/event system for external tools.
- * This provider returns null for all event mappings and marks hooks
- * as unsupported. It exists to satisfy the AdapterHookProvider contract
- * so the adapter can be used uniformly by the AdapterManager.
+ * Maps Cursor's native hook events to CAAMP canonical hook events.
+ * Cursor supports 10 of 16 canonical events through its config-based hook system.
  *
- * @task T5240
+ * Event translation uses CAAMP normalizer APIs:
+ * - `toCanonical(nativeName, 'cursor')` for runtime event name resolution
+ * - `getSupportedEvents('cursor')` to enumerate supported canonical events
+ * - `getProviderHookProfile('cursor')` for the full provider profile
+ *
+ * Cursor uses camelCase native event names (e.g. `sessionStart`, `preToolUse`).
+ * Hooks are configured via `.cursor/hooks.json`. Supported handler types:
+ * command, prompt.
+ *
+ * Unsupported events: PermissionRequest, PreModel, PostModel, PostCompact,
+ * Notification, ConfigChange.
+ *
+ * @task T165
+ * @epic T134
  */
 
 import type { AdapterHookProvider } from '@cleocode/contracts';
 
+/** CAAMP provider identifier for Cursor. */
+const PROVIDER_ID = 'cursor' as const;
+
+/**
+ * Fallback map from Cursor native event names to CAAMP canonical names.
+ *
+ * Derived from `getProviderHookProfile('cursor').mappings` in CAAMP 1.9.1.
+ * Covers all 10 supported events. PermissionRequest, PreModel, PostModel,
+ * PostCompact, Notification, and ConfigChange are not supported by Cursor.
+ *
+ * Cursor uses camelCase names while CAAMP canonical names are PascalCase.
+ */
+const CURSOR_EVENT_MAP: Record<string, string> = {
+  // CAAMP: toNative('SessionStart',       'cursor') = 'sessionStart'
+  sessionStart: 'SessionStart',
+  // CAAMP: toNative('SessionEnd',         'cursor') = 'sessionEnd'
+  sessionEnd: 'SessionEnd',
+  // CAAMP: toNative('PromptSubmit',       'cursor') = 'beforeSubmitPrompt'
+  beforeSubmitPrompt: 'PromptSubmit',
+  // CAAMP: toNative('ResponseComplete',   'cursor') = 'stop'
+  stop: 'ResponseComplete',
+  // CAAMP: toNative('PreToolUse',         'cursor') = 'preToolUse'
+  preToolUse: 'PreToolUse',
+  // CAAMP: toNative('PostToolUse',        'cursor') = 'postToolUse'
+  postToolUse: 'PostToolUse',
+  // CAAMP: toNative('PostToolUseFailure', 'cursor') = 'postToolUseFailure'
+  postToolUseFailure: 'PostToolUseFailure',
+  // CAAMP: toNative('SubagentStart',      'cursor') = 'subagentStart'
+  subagentStart: 'SubagentStart',
+  // CAAMP: toNative('SubagentStop',       'cursor') = 'subagentStop'
+  subagentStop: 'SubagentStop',
+  // CAAMP: toNative('PreCompact',         'cursor') = 'preCompact'
+  preCompact: 'PreCompact',
+};
+
 /**
- * Hook provider for Cursor (stub).
+ * Hook provider for Cursor.
+ *
+ * Cursor registers hooks via its config system at `.cursor/hooks.json`.
+ * Supported handler types: command, prompt.
  *
- * Cursor lacks a hook-based lifecycle event system. All mapping
- * operations return null. Registration is a no-op.
+ * CAAMP 1.9.1 reveals Cursor supports 10 of 16 canonical events. Previously
+ * this provider was a no-op stub. It now provides full event mapping and CAAMP
+ * normalizer integration.
+ *
+ * Event mapping is based on `getProviderHookProfile('cursor')` from CAAMP 1.9.1.
+ * Async accessors (`getSupportedCanonicalEvents`, `getProviderProfile`) call
+ * CAAMP directly when available.
+ *
+ * Since hooks are registered through the config system (managed by the install
+ * provider), `registerNativeHooks` and `unregisterNativeHooks` track registration
+ * state without performing filesystem operations.
+ *
+ * @task T165
+ * @epic T134
  */
 export class CursorHookProvider implements AdapterHookProvider {
   private registered = false;
 
   /**
-   * Map a provider event name to a CAAMP hook event name.
+   * Map a Cursor native event name to a CAAMP canonical hook event name.
    *
-   * Always returns null since Cursor does not emit hook events.
+   * Looks up the native event name in the map derived from
+   * `getProviderHookProfile('cursor').mappings` (CAAMP 1.9.1). Cursor uses
+   * camelCase names (e.g. "preToolUse", "sessionStart").
    *
-   * @param _providerEvent - Ignored; Cursor has no hook events
-   * @returns null (no mapping available)
+   * Returns null for unsupported events (PermissionRequest, PreModel,
+   * PostModel, PostCompact, Notification, ConfigChange).
+   *
+   * @param providerEvent - Cursor native event name (e.g. "preToolUse", "sessionStart")
+   * @returns CAAMP canonical event name, or null if unmapped
+   * @task T165
    */
-  mapProviderEvent(_providerEvent: string): string | null {
-    return null;
+  mapProviderEvent(providerEvent: string): string | null {
+    return CURSOR_EVENT_MAP[providerEvent] ?? null;
   }
 
   /**
    * Register native hooks for a project.
    *
-   * No-op for Cursor since it has no hook system.
+   * For Cursor, hooks are registered via the config system
+   * (`.cursor/hooks.json`), managed by the install provider.
+   * This method marks hooks as registered without performing filesystem operations.
+   *
+   * Iterating supported events is handled at install time using
+   * `getSupportedCanonicalEvents()` to enumerate all 10 supported hooks.
    *
-   * @param _projectDir - Ignored
+   * @param _projectDir - Project directory (unused; Cursor config manages registration)
+   * @task T165
    */
   async registerNativeHooks(_projectDir: string): Promise<void> {
     this.registered = true;
@@ -46,16 +119,92 @@ export class CursorHookProvider implements AdapterHookProvider {
   /**
    * Unregister native hooks.
    *
-   * No-op for Cursor since it has no hook system.
+   * For Cursor, this is a no-op since hooks are managed through the config
+   * system. Unregistration happens via the install provider's uninstall method.
+   *
+   * @task T165
    */
   async unregisterNativeHooks(): Promise<void> {
     this.registered = false;
   }
 
   /**
-   * Check whether hooks have been registered.
+   * Check whether hooks have been registered via `registerNativeHooks`.
    */
   isRegistered(): boolean {
     return this.registered;
   }
+
+  /**
+   * Get the native→canonical event mapping for introspection and debugging.
+   *
+   * Returns the map derived from `getProviderHookProfile('cursor').mappings`
+   * (CAAMP 1.9.1). Use `getSupportedCanonicalEvents()` to enumerate canonical
+   * names via live CAAMP APIs.
+   *
+   * @returns Immutable record of native event name → canonical event name
+   */
+  getEventMap(): Readonly<Record<string, string>> {
+    return { ...CURSOR_EVENT_MAP };
+  }
+
+  /**
+   * Enumerate supported canonical events via CAAMP's `getSupportedEvents()`.
+   *
+   * Calls `getSupportedEvents('cursor')` from the CAAMP normalizer to get the
+   * authoritative list. Cursor supports 10 of 16 canonical events. Falls back
+   * to the values of the static event map when CAAMP is unavailable at runtime.
+   *
+   * @returns Array of CAAMP canonical event names supported by Cursor
+   * @task T165
+   */
+  async getSupportedCanonicalEvents(): Promise<string[]> {
+    try {
+      const { getSupportedEvents } = await import('@cleocode/caamp');
+      return getSupportedEvents(PROVIDER_ID) as string[];
+    } catch {
+      return [...new Set(Object.values(CURSOR_EVENT_MAP))];
+    }
+  }
+
+  /**
+   * Retrieve the full provider hook profile from CAAMP.
+   *
+   * Calls `getProviderHookProfile('cursor')` from the CAAMP normalizer to
+   * get the complete profile: hook system type (`config`), config path
+   * (`.cursor/hooks.json`), handler types (command, prompt), and all event
+   * mappings. Returns null when CAAMP is unavailable at runtime.
+   *
+   * @returns Provider hook profile or null if CAAMP is unavailable
+   * @task T165
+   */
+  async getProviderProfile(): Promise<unknown | null> {
+    try {
+      const { getProviderHookProfile } = await import('@cleocode/caamp');
+      return getProviderHookProfile(PROVIDER_ID) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Translate a CAAMP canonical event to its Cursor native name via CAAMP.
+   *
+   * Calls `toNative(canonical, 'cursor')` from the CAAMP normalizer.
+   * Returns null for unsupported events or when CAAMP is unavailable.
+   *
+   * @param canonical - CAAMP canonical event name (e.g. "PreToolUse")
+   * @returns Cursor native event name (e.g. "preToolUse") or null
+   * @task T165
+   */
+  async toNativeEvent(canonical: string): Promise<string | null> {
+    try {
+      const { toNative } = await import('@cleocode/caamp');
+      return toNative(canonical as Parameters<typeof toNative>[0], PROVIDER_ID);
+    } catch {
+      // Invert the static map as fallback
+      const entry = Object.entries(CURSOR_EVENT_MAP).find(([, v]) => v === canonical);
+      return entry?.[0] ?? null;
+    }
+  }
 }

package/src/providers/gemini-cli/adapter.ts

@@ -0,0 +1,165 @@
+/**
+ * Gemini CLI Adapter
+ *
+ * Main CLEOProviderAdapter implementation for Google Gemini CLI.
+ * Provides hooks and install capabilities for CLEO integration.
+ *
+ * @task T161
+ * @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 { GeminiCliHookProvider } from './hooks.js';
+import { GeminiCliInstallProvider } from './install.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * CLEO provider adapter for Google Gemini CLI.
+ *
+ * Bridges CLEO's adapter system with Gemini CLI's native capabilities:
+ * - Hooks: Maps Gemini CLI events (SessionStart, PreToolUse, etc.) to CAAMP events
+ * - Install: Registers MCP server in ~/.gemini/settings.json and ensures AGENTS.md references
+ *
+ * @task T161
+ * @epic T134
+ */
+export class GeminiCliAdapter implements CLEOProviderAdapter {
+  readonly id = 'gemini-cli';
+  readonly name = 'Gemini CLI';
+  readonly version = '1.0.0';
+
+  capabilities: AdapterCapabilities = {
+    supportsHooks: true,
+    supportedHookEvents: [
+      'SessionStart',
+      'SessionEnd',
+      'BeforeAgent',
+      'AfterAgent',
+      'BeforeTool',
+      'AfterTool',
+      'BeforeModel',
+      'AfterModel',
+      'PreCompress',
+      'Notification',
+    ],
+    supportsSpawn: false,
+    supportsInstall: true,
+    supportsMcp: true,
+    supportsInstructionFiles: false,
+    supportsContextMonitor: false,
+    supportsStatusline: false,
+    supportsProviderPaths: false,
+    supportsTransport: false,
+    supportsTaskSync: false,
+  };
+
+  hooks: GeminiCliHookProvider;
+  install: GeminiCliInstallProvider;
+
+  private projectDir: string | null = null;
+  private initialized = false;
+
+  constructor() {
+    this.hooks = new GeminiCliHookProvider();
+    this.install = new GeminiCliInstallProvider();
+  }
+
+  /**
+   * Initialize the adapter for a given project directory.
+   *
+   * @param projectDir - Root directory of the project
+   * @task T161
+   */
+  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 T161
+   */
+  async dispose(): Promise<void> {
+    if (this.hooks.isRegistered()) {
+      await this.hooks.unregisterNativeHooks();
+    }
+    this.initialized = false;
+    this.projectDir = null;
+  }
+
+  /**
+   * Run a health check to verify Gemini CLI is accessible.
+   *
+   * Checks:
+   * 1. Adapter has been initialized
+   * 2. Gemini CLI binary is available in PATH
+   * 3. ~/.gemini/ configuration directory exists
+   *
+   * @returns Health status with details about each check
+   * @task T161
+   */
+  async healthCheck(): Promise<AdapterHealthStatus> {
+    const details: Record<string, unknown> = {};
+
+    if (!this.initialized) {
+      return {
+        healthy: false,
+        provider: this.id,
+        details: { error: 'Adapter not initialized' },
+      };
+    }
+
+    // Check Gemini CLI availability
+    let cliAvailable = false;
+    try {
+      const { stdout } = await execAsync('which gemini');
+      cliAvailable = stdout.trim().length > 0;
+      details.cliPath = stdout.trim();
+    } catch {
+      details.cliAvailable = false;
+    }
+
+    // Check for Gemini CLI config directory
+    const geminiConfigDir = join(homedir(), '.gemini');
+    const configExists = existsSync(geminiConfigDir);
+    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 T161
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get the project directory this adapter was initialized with.
+   * @task T161
+   */
+  getProjectDir(): string | null {
+    return this.projectDir;
+  }
+}

package/src/providers/gemini-cli/hooks.ts

@@ -0,0 +1,177 @@
+/**
+ * Gemini CLI Hook Provider
+ *
+ * Maps Gemini CLI's native hook events to CAAMP canonical hook events.
+ * Gemini CLI supports 11 canonical events through its hook system.
+ *
+ * Gemini CLI event mapping:
+ * - SessionStart        -> SessionStart
+ * - SessionEnd          -> SessionEnd
+ * - PromptSubmit        -> BeforeAgent
+ * - ResponseComplete    -> AfterAgent
+ * - PreToolUse          -> BeforeTool
+ * - PostToolUse         -> AfterTool
+ * - PreModel            -> BeforeModel
+ * - PostModel           -> AfterModel
+ * - PreCompact          -> PreCompress
+ * - Notification        -> Notification
+ *
+ * @task T161
+ * @epic T134
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { AdapterHookProvider } from '@cleocode/contracts';
+
+/**
+ * Mapping from Gemini CLI native event names to CAAMP canonical event names.
+ */
+const GEMINI_CLI_EVENT_MAP: Record<string, string> = {
+  SessionStart: 'SessionStart',
+  SessionEnd: 'SessionEnd',
+  PromptSubmit: 'BeforeAgent',
+  ResponseComplete: 'AfterAgent',
+  PreToolUse: 'BeforeTool',
+  PostToolUse: 'AfterTool',
+  PreModel: 'BeforeModel',
+  PostModel: 'AfterModel',
+  PreCompact: 'PreCompress',
+  Notification: 'Notification',
+};
+
+/**
+ * Hook provider for Gemini CLI.
+ *
+ * Gemini CLI registers hooks via its configuration system at
+ * ~/.gemini/. Hook handlers are shell scripts or commands 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 T161
+ * @epic T134
+ */
+export class GeminiCliHookProvider implements AdapterHookProvider {
+  private registered = false;
+
+  /**
+   * Map a Gemini CLI native event name to a CAAMP hook event name.
+   *
+   * @param providerEvent - Gemini CLI event name (e.g. "SessionStart", "PreToolUse")
+   * @returns CAAMP event name or null if unmapped
+   * @task T161
+   */
+  mapProviderEvent(providerEvent: string): string | null {
+    return GEMINI_CLI_EVENT_MAP[providerEvent] ?? null;
+  }
+
+  /**
+   * Register native hooks for a project.
+   *
+   * For Gemini CLI, hooks are registered via the config system
+   * (~/.gemini/), 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 T161
+   */
+  async registerNativeHooks(_projectDir: string): Promise<void> {
+    this.registered = true;
+  }
+
+  /**
+   * Unregister native hooks.
+   *
+   * For Gemini CLI, this is a no-op since hooks are managed through
+   * the config system. Unregistration happens via the install
+   * provider's uninstall method.
+   * @task T161
+   */
+  async unregisterNativeHooks(): Promise<void> {
+    this.registered = false;
+  }
+
+  /**
+   * Check whether hooks have been registered via registerNativeHooks.
+   * @task T161
+   */
+  isRegistered(): boolean {
+    return this.registered;
+  }
+
+  /**
+   * Get the full event mapping for introspection/debugging.
+   * @task T161
+   */
+  getEventMap(): Readonly<Record<string, string>> {
+    return { ...GEMINI_CLI_EVENT_MAP };
+  }
+
+  /**
+   * Extract a plain-text transcript from Gemini CLI session data.
+   *
+   * Reads the most recent session file under ~/.gemini/ 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; Gemini CLI uses global paths)
+   * @task T161 @epic T134
+   */
+  async getTranscript(_sessionId: string, _projectDir: string): Promise<string | null> {
+    try {
+      const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? '/root';
+      const geminiDir = join(homeDir, '.gemini');
+
+      let allFiles: string[] = [];
+      try {
+        const entries = await readdir(geminiDir, { 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(geminiDir, 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/gemini-cli/index.ts

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