@cleocode/adapters 2026.4.31 → 2026.4.36

package/dist/index.js

@@ -2273,6 +2273,638 @@ var init_opencode = __esm({
   }
 });
 
+// packages/adapters/src/providers/pi/hooks.ts
+var PROVIDER_ID4, PI_EVENT_MAP, PiHookProvider;
+var init_hooks4 = __esm({
+  "packages/adapters/src/providers/pi/hooks.ts"() {
+    "use strict";
+    PROVIDER_ID4 = "pi";
+    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"
+    };
+    PiHookProvider = class {
+      /** 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_ID4);
+        } 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_ID4) ?? 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_ID4);
+        } catch {
+          const entry = Object.entries(PI_EVENT_MAP).find(([, v]) => v === canonical);
+          return entry?.[0] ?? null;
+        }
+      }
+    };
+  }
+});
+
+// packages/adapters/src/providers/pi/install.ts
+import { existsSync as existsSync15, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "node:fs";
+import { homedir as homedir11 } from "node:os";
+import { join as join22 } from "node:path";
+function getPiAgentDir() {
+  const env = process.env["PI_CODING_AGENT_DIR"];
+  if (env !== void 0 && env.length > 0) {
+    if (env === "~") return homedir11();
+    if (env.startsWith("~/")) return join22(homedir11(), env.slice(2));
+    return env;
+  }
+  const piHome = process.env["PI_HOME"];
+  if (piHome !== void 0 && piHome.length > 0) {
+    return join22(piHome, "agent");
+  }
+  return join22(homedir11(), ".pi", "agent");
+}
+var INSTRUCTION_REFERENCES7, PiInstallProvider;
+var init_install4 = __esm({
+  "packages/adapters/src/providers/pi/install.ts"() {
+    "use strict";
+    INSTRUCTION_REFERENCES7 = ["@~/.cleo/templates/CLEO-INJECTION.md", "@.cleo/memory-bridge.md"];
+    PiInstallProvider = class {
+      /**
+       * Install CLEO into a Pi coding agent project.
+       *
+       * @param options - Installation options including project directory
+       * @returns Result describing what was installed
+       */
+      async install(options) {
+        const { projectDir } = options;
+        const installedAt = (/* @__PURE__ */ new Date()).toISOString();
+        const details = {};
+        const projectUpdated = this.updateInstructionFile(projectDir, "AGENTS.md");
+        if (projectUpdated) {
+          details.instructionFile = join22(projectDir, "AGENTS.md");
+        }
+        let globalUpdated = false;
+        try {
+          const globalDir = getPiAgentDir();
+          globalUpdated = this.updateInstructionFile(globalDir, "AGENTS.md");
+          if (globalUpdated) {
+            details.globalInstructionFile = join22(globalDir, "AGENTS.md");
+          }
+        } catch {
+        }
+        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() {
+      }
+      /**
+       * Check whether CLEO is installed in the current environment.
+       *
+       * Checks for CLEO references in the project AGENTS.md.
+       */
+      async isInstalled() {
+        const agentsMdPath = join22(process.cwd(), "AGENTS.md");
+        if (existsSync15(agentsMdPath)) {
+          try {
+            const content = readFileSync9(agentsMdPath, "utf-8");
+            if (INSTRUCTION_REFERENCES7.some((ref) => content.includes(ref))) {
+              return true;
+            }
+          } catch {
+          }
+        }
+        try {
+          const globalPath = join22(getPiAgentDir(), "AGENTS.md");
+          if (existsSync15(globalPath)) {
+            const content = readFileSync9(globalPath, "utf-8");
+            if (INSTRUCTION_REFERENCES7.some((ref) => content.includes(ref))) {
+              return true;
+            }
+          }
+        } catch {
+        }
+        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) {
+        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
+       */
+      updateInstructionFile(dir, filename) {
+        const filePath = join22(dir, filename);
+        let content = "";
+        let existed = false;
+        if (existsSync15(filePath)) {
+          content = readFileSync9(filePath, "utf-8");
+          existed = true;
+        }
+        const missingRefs = INSTRUCTION_REFERENCES7.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 {
+          mkdirSync3(dir, { recursive: true });
+          content = refsBlock + "\n";
+        }
+        writeFileSync8(filePath, content, "utf-8");
+        return true;
+      }
+    };
+  }
+});
+
+// packages/adapters/src/providers/pi/spawn.ts
+import { exec as exec8, spawn as nodeSpawn3 } from "node:child_process";
+import { unlink as unlink2, writeFile as writeFile3 } from "node:fs/promises";
+import { promisify as promisify8 } from "node:util";
+function getPiCliPath() {
+  return process.env["PI_CLI_PATH"] ?? "pi";
+}
+var execAsync8, PiSpawnProvider;
+var init_spawn3 = __esm({
+  "packages/adapters/src/providers/pi/spawn.ts"() {
+    "use strict";
+    init_src();
+    execAsync8 = promisify8(exec8);
+    PiSpawnProvider = class {
+      /** Map of instance IDs to tracked process info. */
+      processMap = /* @__PURE__ */ new Map();
+      /**
+       * Check if the Pi CLI is available.
+       *
+       * Checks `PI_CLI_PATH` env var first, then tries `which pi`.
+       *
+       * @returns true if the Pi CLI is accessible
+       */
+      async canSpawn() {
+        const cliPath = getPiCliPath();
+        try {
+          if (cliPath !== "pi") {
+            const { stdout } = await execAsync8(`test -x "${cliPath}" && echo ok`);
+            return stdout.trim() === "ok";
+          }
+          await execAsync8("which pi");
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      /**
+       * Spawn a subagent via Pi CLI.
+       *
+       * Writes the prompt to a temporary file and spawns a detached Pi
+       * process. The process runs independently of the parent.
+       *
+       * @param context - Spawn context with taskId, prompt, and options
+       * @returns Spawn result with instance ID and status
+       */
+      async spawn(context) {
+        const instanceId = `pi-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+        const startTime = (/* @__PURE__ */ new Date()).toISOString();
+        let tmpFile;
+        try {
+          tmpFile = `/tmp/pi-spawn-${instanceId}.txt`;
+          await writeFile3(tmpFile, context.prompt, "utf-8");
+          const cliPath = getPiCliPath();
+          const args = [tmpFile];
+          const spawnOpts = {
+            detached: true,
+            stdio: "ignore"
+          };
+          if (context.workingDirectory) {
+            spawnOpts.cwd = context.workingDirectory;
+          }
+          const child = nodeSpawn3(cliPath, args, spawnOpts);
+          child.unref();
+          if (child.pid) {
+            this.processMap.set(instanceId, {
+              pid: child.pid,
+              taskId: context.taskId,
+              startTime
+            });
+          }
+          const capturedTmpFile = tmpFile;
+          child.on("exit", async () => {
+            this.processMap.delete(instanceId);
+            try {
+              await unlink2(capturedTmpFile);
+            } catch {
+            }
+          });
+          return {
+            instanceId,
+            taskId: context.taskId,
+            providerId: "pi",
+            status: "running",
+            startTime
+          };
+        } catch (error) {
+          console.error(`[PiSpawnProvider] Failed to spawn: ${getErrorMessage(error)}`);
+          if (tmpFile) {
+            try {
+              await unlink2(tmpFile);
+            } catch {
+            }
+          }
+          return {
+            instanceId,
+            taskId: context.taskId,
+            providerId: "pi",
+            status: "failed",
+            startTime,
+            endTime: (/* @__PURE__ */ new Date()).toISOString(),
+            error: getErrorMessage(error)
+          };
+        }
+      }
+      /**
+       * List currently running Pi subagent processes.
+       *
+       * Checks each tracked process via kill(pid, 0) to verify it is still alive.
+       * Dead processes are automatically cleaned from the tracking map.
+       *
+       * @returns Array of spawn results for running processes
+       */
+      async listRunning() {
+        const running = [];
+        for (const [instanceId, tracked] of this.processMap.entries()) {
+          try {
+            process.kill(tracked.pid, 0);
+            running.push({
+              instanceId,
+              taskId: tracked.taskId,
+              providerId: "pi",
+              status: "running",
+              startTime: tracked.startTime
+            });
+          } catch {
+            this.processMap.delete(instanceId);
+          }
+        }
+        return running;
+      }
+      /**
+       * Terminate a running spawn by instance ID.
+       *
+       * Sends SIGTERM to the tracked process. If the process is not found
+       * or has already exited, this is a no-op.
+       *
+       * @param instanceId - ID of the spawn instance to terminate
+       */
+      async terminate(instanceId) {
+        const tracked = this.processMap.get(instanceId);
+        if (!tracked) return;
+        try {
+          process.kill(tracked.pid, "SIGTERM");
+        } catch {
+        }
+        this.processMap.delete(instanceId);
+      }
+    };
+  }
+});
+
+// packages/adapters/src/providers/pi/adapter.ts
+import { exec as exec9 } from "node:child_process";
+import { existsSync as existsSync16 } from "node:fs";
+import { homedir as homedir12 } from "node:os";
+import { join as join23 } from "node:path";
+import { promisify as promisify9 } from "node:util";
+function getPiAgentDir2() {
+  const env = process.env["PI_CODING_AGENT_DIR"];
+  if (env !== void 0 && env.length > 0) {
+    if (env === "~") return homedir12();
+    if (env.startsWith("~/")) return join23(homedir12(), env.slice(2));
+    return env;
+  }
+  const piHome = process.env["PI_HOME"];
+  if (piHome !== void 0 && piHome.length > 0) {
+    return join23(piHome, "agent");
+  }
+  return join23(homedir12(), ".pi", "agent");
+}
+var execAsync9, PiAdapter;
+var init_adapter4 = __esm({
+  "packages/adapters/src/providers/pi/adapter.ts"() {
+    "use strict";
+    init_hooks4();
+    init_install4();
+    init_spawn3();
+    execAsync9 = promisify9(exec9);
+    PiAdapter = class {
+      /** 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" }
+          };
+        }
+        let cliAvailable = false;
+        const cliPath = process.env["PI_CLI_PATH"] ?? "pi";
+        try {
+          if (cliPath !== "pi") {
+            const { stdout } = await execAsync9(`test -x "${cliPath}" && echo ok`);
+            cliAvailable = stdout.trim() === "ok";
+            details.cliPath = cliPath;
+          } else {
+            const { stdout } = await execAsync9("which pi");
+            cliAvailable = stdout.trim().length > 0;
+            details.cliPath = stdout.trim();
+          }
+        } catch {
+          details.cliAvailable = false;
+        }
+        const agentDir = getPiAgentDir2();
+        const agentDirExists = existsSync16(agentDir);
+        details.agentDirExists = agentDirExists;
+        details.agentDir = agentDir;
+        if (this.projectDir) {
+          const projectPiDir = join23(this.projectDir, ".pi");
+          details.projectPiDirExists = existsSync16(projectPiDir);
+        }
+        details.piCodingAgentDirSet = process.env["PI_CODING_AGENT_DIR"] !== void 0;
+        details.piHomeSet = process.env["PI_HOME"] !== void 0;
+        details.piCliPathSet = process.env["PI_CLI_PATH"] !== void 0;
+        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;
+      }
+    };
+  }
+});
+
+// packages/adapters/src/providers/pi/index.ts
+var pi_exports = {};
+__export(pi_exports, {
+  PiAdapter: () => PiAdapter,
+  PiHookProvider: () => PiHookProvider,
+  PiInstallProvider: () => PiInstallProvider,
+  PiSpawnProvider: () => PiSpawnProvider,
+  createAdapter: () => createAdapter7,
+  default: () => pi_default
+});
+function createAdapter7() {
+  return new PiAdapter();
+}
+var pi_default;
+var init_pi = __esm({
+  "packages/adapters/src/providers/pi/index.ts"() {
+    "use strict";
+    init_adapter4();
+    init_adapter4();
+    init_hooks4();
+    init_install4();
+    init_spawn3();
+    pi_default = PiAdapter;
+  }
+});
+
 // packages/adapters/src/index.ts
 init_claude_code();
 
@@ -3216,17 +3848,17 @@ function createAdapter5() {
 init_opencode();
 
 // packages/adapters/src/registry.ts
-import { readFileSync as readFileSync9 } from "node:fs";
-import { dirname as dirname3, join as join22, resolve } from "node:path";
+import { readFileSync as readFileSync10 } from "node:fs";
+import { dirname as dirname3, join as join24, resolve } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var PROVIDER_IDS = ["claude-code", "opencode", "cursor"];
+var PROVIDER_IDS = ["claude-code", "opencode", "cursor", "pi"];
 function getProviderManifests() {
   const manifests = [];
   const baseDir = resolve(dirname3(fileURLToPath2(import.meta.url)), "providers");
   for (const providerId of PROVIDER_IDS) {
     try {
-      const manifestPath = join22(baseDir, providerId, "manifest.json");
-      const raw = readFileSync9(manifestPath, "utf-8");
+      const manifestPath = join24(baseDir, providerId, "manifest.json");
+      const raw = readFileSync10(manifestPath, "utf-8");
       manifests.push(JSON.parse(raw));
     } catch {
     }
@@ -3247,6 +3879,10 @@ async function discoverProviders() {
     const { CursorAdapter: CursorAdapter2 } = await Promise.resolve().then(() => (init_cursor(), cursor_exports));
     return new CursorAdapter2();
   });
+  providers.set("pi", async () => {
+    const { PiAdapter: PiAdapter2 } = await Promise.resolve().then(() => (init_pi(), pi_exports));
+    return new PiAdapter2();
+  });
   return providers;
 }
 export {