@cleocode/adapters 2026.4.31 → 2026.4.35

package/dist/providers/pi/adapter.js

@@ -0,0 +1,220 @@
+/**
+ * Pi Adapter
+ *
+ * Main CLEOProviderAdapter implementation for the Pi coding agent
+ * (https://github.com/badlogic/pi-mono). Pi is CAAMP's first-class primary
+ * harness and owns skills, instructions, extensions, and subagent spawning
+ * through native filesystem conventions.
+ *
+ * Pi supports 11 of 16 CAAMP canonical events through its TypeScript extension
+ * system (session_start, session_shutdown, input, turn_end, tool_call,
+ * tool_result, before_agent_start, agent_end, before_provider_request, context).
+ *
+ * Detection: PI_CLI_PATH env var, PI_CODING_AGENT_DIR env var, PI_HOME env var,
+ * or presence of ~/.pi/agent/ directory.
+ *
+ * @task T553
+ */
+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 { PiHookProvider } from './hooks.js';
+import { PiInstallProvider } from './install.js';
+import { PiSpawnProvider } from './spawn.js';
+const execAsync = promisify(exec);
+/**
+ * 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() {
+    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');
+}
+/**
+ * CLEO provider adapter for Pi coding agent.
+ *
+ * Bridges CLEO's adapter system with Pi's native capabilities:
+ * - Hooks: Maps Pi events (session_start, tool_call, etc.) to CAAMP events
+ * - Spawn: Launches subagent processes via the `pi` CLI
+ * - Install: Manages AGENTS.md instruction files and global Pi state root
+ *
+ * @remarks
+ * Pi is CAAMP's first-class primary harness (ADR-035). It supports 11 of 16
+ * canonical hook events through its TypeScript extension system. Extensions
+ * live at `~/.pi/agent/extensions/` (global) or `<projectDir>/.pi/extensions/`
+ * (project scope).
+ *
+ * The session_shutdown event handler in `cleo-cant-bridge.ts` clears module
+ * cache. The adapter's hook mapping ensures that Pi's session lifecycle events
+ * are visible in the CAAMP event stream for downstream listeners (e.g. memory
+ * refresh triggers, backup triggers).
+ *
+ * Detection hierarchy (first match wins):
+ * 1. `PI_CLI_PATH` env var set
+ * 2. `PI_CODING_AGENT_DIR` env var set
+ * 3. `PI_HOME` env var set
+ * 4. `~/.pi/agent/` directory exists
+ * 5. `pi` CLI available in PATH
+ */
+export class PiAdapter {
+    /** Unique provider identifier. */
+    id = 'pi';
+    /** Human-readable provider name. */
+    name = 'Pi';
+    /** Adapter version string. */
+    version = '1.0.0';
+    /** Declared capabilities for this provider. */
+    capabilities = {
+        supportsHooks: true,
+        // 11/16 canonical events — derived from piEventCatalog in CAAMP hook-mappings.json.
+        // ResponseComplete, PostToolUseFailure, PermissionRequest, PostModel, PostCompact,
+        // and ConfigChange are not supported by Pi's extension system.
+        supportedHookEvents: [
+            'SessionStart',
+            'SessionEnd',
+            'PromptSubmit',
+            'Notification',
+            'PreToolUse',
+            'PostToolUse',
+            'SubagentStart',
+            'SubagentStop',
+            'PreModel',
+            'PreCompact',
+        ],
+        supportsSpawn: true,
+        supportsInstall: true,
+        supportsInstructionFiles: true,
+        instructionFilePattern: 'AGENTS.md',
+        supportsContextMonitor: false,
+        supportsStatusline: false,
+        supportsProviderPaths: true,
+        supportsTransport: false,
+        supportsTaskSync: false,
+    };
+    /** Hook provider for CAAMP event mapping and registration. */
+    hooks;
+    /** Spawn provider for launching subagent processes via `pi` CLI. */
+    spawn;
+    /** Install provider for managing AGENTS.md instruction files. */
+    install;
+    /** Project directory this adapter was initialized with, or null. */
+    projectDir = null;
+    /** Whether {@link initialize} has been called. */
+    initialized = false;
+    constructor() {
+        this.hooks = new PiHookProvider();
+        this.spawn = new PiSpawnProvider();
+        this.install = new PiInstallProvider();
+    }
+    /**
+     * Initialize the adapter for a given project directory.
+     *
+     * Validates the environment by checking for the Pi CLI and Pi state root.
+     *
+     * @param projectDir - Root directory of the project
+     */
+    async initialize(projectDir) {
+        this.projectDir = projectDir;
+        this.initialized = true;
+    }
+    /**
+     * Dispose the adapter and clean up resources.
+     *
+     * Unregisters hooks and releases any tracked state.
+     */
+    async dispose() {
+        if (this.hooks.isRegistered()) {
+            await this.hooks.unregisterNativeHooks();
+        }
+        this.initialized = false;
+        this.projectDir = null;
+    }
+    /**
+     * Run a health check to verify Pi is accessible.
+     *
+     * Checks:
+     * 1. Adapter has been initialized
+     * 2. Pi CLI is available (via PI_CLI_PATH or `which pi`)
+     * 3. Pi global state root (~/.pi/agent/ or PI_CODING_AGENT_DIR) exists
+     *
+     * @returns Health status with details about each check
+     */
+    async healthCheck() {
+        const details = {};
+        if (!this.initialized) {
+            return {
+                healthy: false,
+                provider: this.id,
+                details: { error: 'Adapter not initialized' },
+            };
+        }
+        // Check Pi CLI availability
+        let cliAvailable = false;
+        const cliPath = process.env['PI_CLI_PATH'] ?? 'pi';
+        try {
+            if (cliPath !== 'pi') {
+                const { stdout } = await execAsync(`test -x "${cliPath}" && echo ok`);
+                cliAvailable = stdout.trim() === 'ok';
+                details.cliPath = cliPath;
+            }
+            else {
+                const { stdout } = await execAsync('which pi');
+                cliAvailable = stdout.trim().length > 0;
+                details.cliPath = stdout.trim();
+            }
+        }
+        catch {
+            details.cliAvailable = false;
+        }
+        // Check for Pi global state root
+        const agentDir = getPiAgentDir();
+        const agentDirExists = existsSync(agentDir);
+        details.agentDirExists = agentDirExists;
+        details.agentDir = agentDir;
+        // Check for project-level .pi/ directory
+        if (this.projectDir) {
+            const projectPiDir = join(this.projectDir, '.pi');
+            details.projectPiDirExists = existsSync(projectPiDir);
+        }
+        // Check detection env vars
+        details.piCodingAgentDirSet = process.env['PI_CODING_AGENT_DIR'] !== undefined;
+        details.piHomeSet = process.env['PI_HOME'] !== undefined;
+        details.piCliPathSet = process.env['PI_CLI_PATH'] !== undefined;
+        // Healthy if either CLI is available or global state root exists
+        const healthy = cliAvailable || agentDirExists;
+        details.cliAvailable = cliAvailable;
+        return {
+            healthy,
+            provider: this.id,
+            details,
+        };
+    }
+    /**
+     * Check whether the adapter has been initialized.
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get the project directory this adapter was initialized with.
+     */
+    getProjectDir() {
+        return this.projectDir;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/pi/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/providers/pi/adapter.ts"],"names":[],"mappings":"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"}

package/dist/providers/pi/hooks.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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';
+/**
+ * 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 declare class PiHookProvider implements AdapterHookProvider {
+    /** Whether hooks have been registered for the current session. */
+    private registered;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    registerNativeHooks(_projectDir: string): Promise<void>;
+    /**
+     * 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
+     */
+    unregisterNativeHooks(): Promise<void>;
+    /**
+     * Check whether hooks have been registered via `registerNativeHooks`.
+     */
+    isRegistered(): boolean;
+    /**
+     * 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>>;
+    /**
+     * 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
+     */
+    getSupportedCanonicalEvents(): Promise<string[]>;
+    /**
+     * 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
+     */
+    getProviderProfile(): Promise<unknown | 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
+     */
+    toNativeEvent(canonical: string): Promise<string | null>;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/providers/pi/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/providers/pi/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AA2C/D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,cAAe,YAAW,mBAAmB;IACxD,kEAAkE;IAClE,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAItD;;;;;;;;;;;;OAYG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;;;;;OAOG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;;;;;;;OAQG;IACH,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI/C;;;;;;;;;OASG;IACG,2BAA2B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAStD;;;;;;;;;OASG;IACG,kBAAkB,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IASnD;;;;;;;;;OASG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAU/D"}

package/dist/providers/pi/hooks.js

@@ -0,0 +1,223 @@
+/**
+ * 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
+ */
+/** CAAMP provider identifier for Pi. */
+const PROVIDER_ID = 'pi';
+/**
+ * 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 = {
+    // 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 {
+    /** Whether hooks have been registered for the current session. */
+    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) {
+        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) {
+        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() {
+        this.registered = false;
+    }
+    /**
+     * Check whether hooks have been registered via `registerNativeHooks`.
+     */
+    isRegistered() {
+        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() {
+        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() {
+        try {
+            const { getSupportedEvents } = await import('@cleocode/caamp');
+            return getSupportedEvents(PROVIDER_ID);
+        }
+        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() {
+        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) {
+        try {
+            const { toNative } = await import('@cleocode/caamp');
+            return toNative(canonical, 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;
+        }
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/providers/pi/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/providers/pi/hooks.ts"],"names":[],"mappings":"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"}

package/dist/providers/pi/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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 declare function createAdapter(): PiAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/pi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/pi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAe,SAAS,CAAC;AAEzB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAEzC"}