@cleocode/adapters 2026.4.31 → 2026.4.35

package/src/providers/pi/hooks.ts

@@ -0,0 +1,232 @@
+/**
+ * Pi Hook Provider
+ *
+ * Maps Pi coding agent native event names to CAAMP canonical hook events.
+ * Pi supports 11 of 16 canonical events through its extension/event system.
+ *
+ * Event translation uses CAAMP normalizer APIs:
+ * - `toCanonical(nativeName, 'pi')` for runtime event name resolution
+ * - `getSupportedEvents('pi')` to enumerate supported canonical events
+ * - `getProviderHookProfile('pi')` for the full provider profile
+ *
+ * A static map derived from CAAMP hook-mappings.json piEventCatalog is
+ * maintained as a fallback for environments where CAAMP's runtime
+ * resolution is unavailable.
+ *
+ * Mappings (11/16 supported):
+ *   session_start          → SessionStart
+ *   session_shutdown       → SessionEnd
+ *   input                  → PromptSubmit
+ *   turn_end               → Notification  (assistant turn complete)
+ *   tool_call              → PreToolUse
+ *   tool_result            → PostToolUse
+ *   before_agent_start     → SubagentStart
+ *   agent_end              → SubagentStop
+ *   before_provider_request → PreModel
+ *   context                → PreCompact    (context assembly = pre-compaction proxy)
+ *
+ * Unsupported (5/16):
+ *   ResponseComplete, PostToolUseFailure, PermissionRequest,
+ *   PostModel, PostCompact, ConfigChange
+ *
+ * @task T553
+ */
+
+import type { AdapterHookProvider } from '@cleocode/contracts';
+
+/** CAAMP provider identifier for Pi. */
+const PROVIDER_ID = 'pi' as const;
+
+/**
+ * Fallback map from Pi native event names to CAAMP canonical names.
+ *
+ * Derived from the `piEventCatalog` block in CAAMP hook-mappings.json.
+ * Covers all 11 supported events. ResponseComplete, PostToolUseFailure,
+ * PermissionRequest, PostModel, PostCompact, and ConfigChange are not
+ * supported by Pi and are absent from this map.
+ *
+ * Used as fallback when CAAMP runtime is unavailable, and as the
+ * synchronous implementation of `mapProviderEvent()`.
+ */
+const PI_EVENT_MAP: Record<string, string> = {
+  // piEventCatalog: session_start → SessionStart
+  session_start: 'SessionStart',
+  // piEventCatalog: session_shutdown → SessionEnd
+  session_shutdown: 'SessionEnd',
+  // piEventCatalog: input → PromptSubmit
+  input: 'PromptSubmit',
+  // piEventCatalog: turn_end → Notification (assistant turn complete)
+  turn_end: 'Notification',
+  // piEventCatalog: tool_call → PreToolUse
+  tool_call: 'PreToolUse',
+  // piEventCatalog: tool_execution_start → PreToolUse (duplicate path)
+  tool_execution_start: 'PreToolUse',
+  // piEventCatalog: tool_result → PostToolUse
+  tool_result: 'PostToolUse',
+  // piEventCatalog: tool_execution_end → PostToolUse (duplicate path)
+  tool_execution_end: 'PostToolUse',
+  // piEventCatalog: before_agent_start → SubagentStart
+  before_agent_start: 'SubagentStart',
+  // piEventCatalog: agent_end → SubagentStop
+  agent_end: 'SubagentStop',
+  // piEventCatalog: before_provider_request → PreModel
+  before_provider_request: 'PreModel',
+  // piEventCatalog: context → PreCompact (context assembly is the pre-compaction proxy for Pi)
+  context: 'PreCompact',
+};
+
+/**
+ * Hook provider for Pi coding agent.
+ *
+ * Pi registers hooks via its TypeScript extension system. Extensions are
+ * loaded from `~/.pi/agent/extensions/*.ts` (global) or
+ * `<projectDir>/.pi/extensions/*.ts` (project scope).
+ *
+ * Event mapping is based on the `piEventCatalog` block in CAAMP
+ * hook-mappings.json. Async accessors (`getSupportedCanonicalEvents`,
+ * `getProviderProfile`) call CAAMP directly when available.
+ *
+ * Since hooks are registered through the extension system (managed by the
+ * install provider), `registerNativeHooks` and `unregisterNativeHooks`
+ * track registration state without performing filesystem operations.
+ *
+ * @remarks
+ * Pi is CAAMP's first-class primary harness (ADR-035). Its native events
+ * use snake_case (e.g. `session_start`, `tool_call`) unlike the PascalCase
+ * CAAMP canonical names. The static event map covers all 11 supported events.
+ * Async CAAMP accessors fall back to the static map when CAAMP is unavailable.
+ *
+ * Pi does NOT support ResponseComplete, PostToolUseFailure, PermissionRequest,
+ * PostModel, PostCompact, or ConfigChange canonical events.
+ *
+ * All hook dispatch is best-effort — hooks MUST never block or crash Pi.
+ *
+ * @task T553
+ */
+export class PiHookProvider implements AdapterHookProvider {
+  /** Whether hooks have been registered for the current session. */
+  private registered = false;
+
+  /**
+   * Map a Pi native event name to a CAAMP canonical hook event name.
+   *
+   * Looks up the native event name in the map derived from the
+   * `piEventCatalog` block in CAAMP hook-mappings.json.
+   * Returns null for unrecognised or unsupported events.
+   *
+   * @param providerEvent - Pi native event (e.g. "session_start", "tool_call")
+   * @returns CAAMP canonical event name, or null if unmapped
+   * @task T553
+   */
+  mapProviderEvent(providerEvent: string): string | null {
+    return PI_EVENT_MAP[providerEvent] ?? null;
+  }
+
+  /**
+   * Register native hooks for a project.
+   *
+   * For Pi, hooks are registered via the extension system, 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 11 supported hooks.
+   *
+   * @param _projectDir - Project directory (unused; Pi uses extension system)
+   * @task T553
+   */
+  async registerNativeHooks(_projectDir: string): Promise<void> {
+    this.registered = true;
+  }
+
+  /**
+   * Unregister native hooks.
+   *
+   * For Pi, this is a no-op since hooks are managed through the extension
+   * system. Unregistration happens via the install provider's uninstall method.
+   *
+   * @task T553
+   */
+  async unregisterNativeHooks(): Promise<void> {
+    this.registered = false;
+  }
+
+  /**
+   * 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 the `piEventCatalog` block in CAAMP
+   * hook-mappings.json. 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 { ...PI_EVENT_MAP };
+  }
+
+  /**
+   * Enumerate supported canonical events via CAAMP's `getSupportedEvents()`.
+   *
+   * Calls `getSupportedEvents('pi')` from the CAAMP normalizer to get the
+   * authoritative list. Pi supports 11 of 16 canonical events. Falls back
+   * to the unique values of the static event map when CAAMP is unavailable.
+   *
+   * @returns Array of CAAMP canonical event names supported by Pi
+   * @task T553
+   */
+  async getSupportedCanonicalEvents(): Promise<string[]> {
+    try {
+      const { getSupportedEvents } = await import('@cleocode/caamp');
+      return getSupportedEvents(PROVIDER_ID) as string[];
+    } catch {
+      return [...new Set(Object.values(PI_EVENT_MAP))];
+    }
+  }
+
+  /**
+   * Retrieve the full provider hook profile from CAAMP.
+   *
+   * Calls `getProviderHookProfile('pi')` from the CAAMP normalizer to get
+   * the complete profile including hook system type, config path, handler
+   * types, and all event mappings. Returns null when CAAMP is unavailable.
+   *
+   * @returns Provider hook profile or null if CAAMP is unavailable
+   * @task T553
+   */
+  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 Pi native name via CAAMP.
+   *
+   * Calls `toNative(canonical, 'pi')` from the CAAMP normalizer.
+   * Returns null for unsupported events or when CAAMP is unavailable.
+   *
+   * @param canonical - CAAMP canonical event name (e.g. "PreToolUse")
+   * @returns Pi native event name or null
+   * @task T553
+   */
+  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 — return the first match
+      const entry = Object.entries(PI_EVENT_MAP).find(([, v]) => v === canonical);
+      return entry?.[0] ?? null;
+    }
+  }
+}

package/src/providers/pi/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ *
+ * CLEO provider adapter for Pi coding agent (https://github.com/badlogic/pi-mono).
+ * Pi is CAAMP's first-class primary harness with 11/16 canonical hook events.
+ * Default export is the adapter class for dynamic loading by AdapterManager.
+ *
+ * @task T553
+ */
+
+import { PiAdapter } from './adapter.js';
+
+export { PiAdapter } from './adapter.js';
+export { PiHookProvider } from './hooks.js';
+export { PiInstallProvider } from './install.js';
+export { PiSpawnProvider } from './spawn.js';
+
+export default PiAdapter;
+
+/**
+ * Factory function for creating Pi adapter instances.
+ * Used by AdapterManager's dynamic import fallback.
+ *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the pi provider
+ * via its import-based discovery mechanism.
+ *
+ * @returns A new {@link PiAdapter} instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/pi';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
+ */
+export function createAdapter(): PiAdapter {
+  return new PiAdapter();
+}

package/src/providers/pi/install.ts

@@ -0,0 +1,189 @@
+/**
+ * Pi Install Provider
+ *
+ * Handles CLEO installation into Pi coding agent environments:
+ * - Ensures AGENTS.md has CLEO @-references (project and global scope)
+ * - Manages Pi settings.json to register CLEO extension path
+ *
+ * Pi uses AGENTS.md (not CLAUDE.md) as its instruction file. The global
+ * instruction file lives at `~/.pi/agent/AGENTS.md`; the project-level
+ * file lives at `<projectDir>/AGENTS.md`.
+ *
+ * Detection: Pi is detected by the `PI_CODING_AGENT_DIR` or `PI_HOME`
+ * environment variables, or by presence of `~/.pi/agent/` directory.
+ *
+ * @task T553
+ */
+
+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'];
+
+/**
+ * Resolve the Pi global state root directory.
+ *
+ * Honours `PI_CODING_AGENT_DIR` env var when set (with `~` expansion),
+ * then `PI_HOME`, then falls back to `~/.pi/agent`.
+ */
+function getPiAgentDir(): string {
+  const env = process.env['PI_CODING_AGENT_DIR'];
+  if (env !== undefined && env.length > 0) {
+    if (env === '~') return homedir();
+    if (env.startsWith('~/')) return join(homedir(), env.slice(2));
+    return env;
+  }
+  const piHome = process.env['PI_HOME'];
+  if (piHome !== undefined && piHome.length > 0) {
+    return join(piHome, 'agent');
+  }
+  return join(homedir(), '.pi', 'agent');
+}
+
+/**
+ * Install provider for Pi coding agent.
+ *
+ * Manages CLEO's integration with Pi by:
+ * 1. Ensuring project AGENTS.md contains @-references to CLEO instruction files
+ * 2. Ensuring global AGENTS.md (~/.pi/agent/AGENTS.md) contains @-references
+ *
+ * @remarks
+ * Installation is idempotent — running install multiple times on the same
+ * project produces the same result. Pi's AGENTS.md is auto-discovered from
+ * the working directory upwards, so project-level injection is the primary
+ * mechanism. Global injection ensures fresh sessions always load CLEO context.
+ */
+export class PiInstallProvider implements AdapterInstallProvider {
+  /**
+   * Install CLEO into a Pi coding agent project.
+   *
+   * @param options - Installation options including project directory
+   * @returns Result describing what was installed
+   */
+  async install(options: InstallOptions): Promise<InstallResult> {
+    const { projectDir } = options;
+    const installedAt = new Date().toISOString();
+    const details: Record<string, unknown> = {};
+
+    // Step 1: Ensure project AGENTS.md has @-references
+    const projectUpdated = this.updateInstructionFile(projectDir, 'AGENTS.md');
+    if (projectUpdated) {
+      details.instructionFile = join(projectDir, 'AGENTS.md');
+    }
+
+    // Step 2: Ensure global AGENTS.md has @-references (best-effort)
+    let globalUpdated = false;
+    try {
+      const globalDir = getPiAgentDir();
+      globalUpdated = this.updateInstructionFile(globalDir, 'AGENTS.md');
+      if (globalUpdated) {
+        details.globalInstructionFile = join(globalDir, 'AGENTS.md');
+      }
+    } catch {
+      // Global install is best-effort — never block project install
+    }
+
+    const instructionFileUpdated = projectUpdated || globalUpdated;
+
+    return {
+      success: true,
+      installedAt,
+      instructionFileUpdated,
+      details,
+    };
+  }
+
+  /**
+   * Uninstall CLEO from the current Pi project.
+   *
+   * Does not remove AGENTS.md references (they are harmless if CLEO is not present).
+   */
+  async uninstall(): Promise<void> {}
+
+  /**
+   * Check whether CLEO is installed in the current environment.
+   *
+   * Checks for CLEO references in the project AGENTS.md.
+   */
+  async isInstalled(): Promise<boolean> {
+    const agentsMdPath = join(process.cwd(), 'AGENTS.md');
+    if (existsSync(agentsMdPath)) {
+      try {
+        const content = readFileSync(agentsMdPath, 'utf-8');
+        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
+          return true;
+        }
+      } catch {
+        // Fall through
+      }
+    }
+
+    // Also check global AGENTS.md
+    try {
+      const globalPath = join(getPiAgentDir(), 'AGENTS.md');
+      if (existsSync(globalPath)) {
+        const content = readFileSync(globalPath, 'utf-8');
+        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
+          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
+   */
+  async ensureInstructionReferences(projectDir: string): Promise<void> {
+    this.updateInstructionFile(projectDir, 'AGENTS.md');
+  }
+
+  /**
+   * Update an instruction file with CLEO @-references.
+   *
+   * @param dir - Directory containing the instruction file
+   * @param filename - Name of the instruction file (e.g. "AGENTS.md")
+   * @returns true if the file was created or modified
+   */
+  private updateInstructionFile(dir: string, filename: string): boolean {
+    const filePath = join(dir, filename);
+    let content = '';
+    let existed = false;
+
+    if (existsSync(filePath)) {
+      content = readFileSync(filePath, '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) {
+      // Append missing references
+      const separator = content.endsWith('\n') ? '' : '\n';
+      content = content + separator + refsBlock + '\n';
+    } else {
+      // Create new file with references — ensure parent dir exists
+      mkdirSync(dir, { recursive: true });
+      content = refsBlock + '\n';
+    }
+
+    writeFileSync(filePath, content, 'utf-8');
+    return true;
+  }
+}

package/src/providers/pi/manifest.json

@@ -0,0 +1,40 @@
+{
+  "id": "pi",
+  "name": "Pi Adapter",
+  "version": "1.0.0",
+  "description": "CLEO adapter for Pi coding agent — CAAMP's first-class primary harness",
+  "provider": "pi",
+  "entryPoint": "src/index.ts",
+  "capabilities": {
+    "supportsHooks": true,
+    "supportedHookEvents": [
+      "SessionStart",
+      "SessionEnd",
+      "PromptSubmit",
+      "Notification",
+      "PreToolUse",
+      "PostToolUse",
+      "SubagentStart",
+      "SubagentStop",
+      "PreModel",
+      "PreCompact"
+    ],
+    "supportsSpawn": true,
+    "supportsInstall": true,
+    "supportsMcp": false,
+    "supportsInstructionFiles": true,
+    "instructionFilePattern": "AGENTS.md",
+    "supportsContextMonitor": false,
+    "supportsStatusline": false,
+    "supportsProviderPaths": true,
+    "supportsTransport": false,
+    "supportsTaskSync": false
+  },
+  "detectionPatterns": [
+    { "type": "env", "pattern": "PI_CLI_PATH", "description": "Custom Pi CLI path" },
+    { "type": "env", "pattern": "PI_CODING_AGENT_DIR", "description": "Pi global state root directory" },
+    { "type": "env", "pattern": "PI_HOME", "description": "Pi home directory" },
+    { "type": "file", "pattern": ".pi/settings.json", "description": "Pi project config directory" },
+    { "type": "cli", "pattern": "pi", "description": "Pi CLI available in PATH" }
+  ]
+}