@cleocode/adapters 2026.4.30 → 2026.4.35

package/dist/providers/shared/transcript-reader.js

@@ -0,0 +1,124 @@
+/**
+ * Shared transcript-reading utility for provider hook adapters.
+ *
+ * Several providers (Gemini CLI, Codex CLI) store session data in a
+ * flat directory of JSON/JSONL files using the same role/content schema.
+ * This module centralises the "find most-recent file, parse turns"
+ * logic to avoid duplicating it in each hook provider.
+ *
+ * Usage:
+ * ```ts
+ * import { readLatestTranscript } from '../shared/transcript-reader.js';
+ *
+ * async getTranscript(_sessionId: string, _projectDir: string) {
+ *   return readLatestTranscript(join(homedir(), '.gemini'));
+ * }
+ * ```
+ *
+ * @task T161
+ * @epic T134
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a raw JSONL or JSON session file into an array of transcript turns.
+ *
+ * Lines that are not valid JSON, or that lack a string `role` and string
+ * `content`, are silently skipped.
+ *
+ * @param raw - Raw file contents (UTF-8 string).
+ * @returns Array of `{ role, content }` pairs, in file order.
+ */
+function parseTranscriptLines(raw) {
+    const turns = [];
+    const lines = raw.split('\n').filter((l) => l.trim());
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            const role = entry.role;
+            const content = entry.content;
+            if (typeof role === 'string' && typeof content === 'string') {
+                turns.push({ role, content });
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return turns;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read the most recent JSON or JSONL session file from `providerDir` and
+ * return its contents as a flat transcript string.
+ *
+ * Files are sorted in descending order by filename — this works naturally
+ * for providers that embed timestamps in filenames. The most recently named
+ * file is read first.
+ *
+ * Returns `null` when:
+ * - `providerDir` does not exist or cannot be read
+ * - No JSON/JSONL files are present
+ * - The most recent file contains no parseable turns
+ *
+ * @remarks
+ * This utility is shared by Gemini CLI and Codex CLI hook providers which
+ * both store session data in the same flat JSON/JSONL format. Only the
+ * most recent file is read to keep memory usage bounded.
+ *
+ * @param providerDir - Absolute path to the provider's session directory
+ *   (e.g. `~/.gemini` or `~/.codex`).
+ * @returns A plain-text transcript with lines of the form `role: content`,
+ *   or `null` if no transcript could be extracted.
+ *
+ * @example
+ * ```typescript
+ * import { readLatestTranscript } from '../shared/transcript-reader.js';
+ *
+ * const transcript = await readLatestTranscript('/home/user/.gemini');
+ * if (transcript) {
+ *   console.log(transcript);
+ * }
+ * ```
+ *
+ * @task T161
+ * @epic T134
+ */
+export async function readLatestTranscript(providerDir) {
+    let allFiles = [];
+    try {
+        const entries = await readdir(providerDir, { 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(providerDir, name));
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    if (allFiles.length === 0)
+        return null;
+    // Sort descending — timestamps in filenames sort naturally
+    allFiles = allFiles.sort((a, b) => b.localeCompare(a));
+    const mostRecent = allFiles[0];
+    if (!mostRecent)
+        return null;
+    try {
+        const raw = await readFile(mostRecent, 'utf-8');
+        const turns = parseTranscriptLines(raw);
+        return turns.length > 0 ? turns.map((t) => `${t.role}: ${t.content}`).join('\n') : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=transcript-reader.js.map

package/dist/providers/shared/transcript-reader.js.map

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

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,8DAA8D;IAC9D,iBAAiB,EAAE,KAAK,CAAC;QACvB,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,sCAAsC;QACtC,OAAO,EAAE,MAAM,CAAC;QAChB,yDAAyD;QACzD,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,EAAE,CAexD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAmBtF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,8DAA8D;IAC9D,iBAAiB,EAAE,KAAK,CAAC;QACvB,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,sCAAsC;QACtC,OAAO,EAAE,MAAM,CAAC;QAChB,yDAAyD;QACzD,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,EAAE,CAexD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAwBtF"}

package/dist/registry.js

@@ -0,0 +1,92 @@
+/**
+ * Adapter registry — discovers and provides access to provider manifests.
+ *
+ * Scans the providers/ directory for manifest.json files and returns
+ * the discovered adapter manifests for use by AdapterManager.
+ *
+ * @task T5240
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Known provider IDs bundled with @cleocode/adapters. */
+const PROVIDER_IDS = ['claude-code', 'opencode', 'cursor', 'pi'];
+/**
+ * Get the manifests for all bundled provider adapters.
+ *
+ * @remarks
+ * Scans the known provider directories for `manifest.json` files.
+ * Providers whose manifests cannot be loaded (missing or malformed)
+ * are silently skipped.
+ *
+ * @returns Array of adapter manifests for successfully loaded providers
+ *
+ * @example
+ * ```typescript
+ * import { getProviderManifests } from '@cleocode/adapters';
+ *
+ * const manifests = getProviderManifests();
+ * for (const m of manifests) {
+ *   console.log(`${m.id}: ${m.name} v${m.version}`);
+ * }
+ * ```
+ */
+export function getProviderManifests() {
+    const manifests = [];
+    const baseDir = resolve(dirname(fileURLToPath(import.meta.url)), 'providers');
+    for (const providerId of PROVIDER_IDS) {
+        try {
+            const manifestPath = join(baseDir, providerId, 'manifest.json');
+            const raw = readFileSync(manifestPath, 'utf-8');
+            manifests.push(JSON.parse(raw));
+        }
+        catch {
+            // Skip providers whose manifests cannot be loaded
+        }
+    }
+    return manifests;
+}
+/**
+ * Discover all available provider adapters.
+ *
+ * Returns a map of provider ID to adapter factory function.
+ *
+ * @remarks
+ * Each factory lazily imports the provider module and constructs a new
+ * adapter instance. This avoids loading all provider code upfront and
+ * keeps startup fast.
+ *
+ * @returns Map of provider ID to async factory function that creates an adapter instance
+ *
+ * @example
+ * ```typescript
+ * import { discoverProviders } from '@cleocode/adapters';
+ *
+ * const providers = await discoverProviders();
+ * const factory = providers.get('claude-code');
+ * if (factory) {
+ *   const adapter = await factory();
+ * }
+ * ```
+ */
+export async function discoverProviders() {
+    const providers = new Map();
+    providers.set('claude-code', async () => {
+        const { ClaudeCodeAdapter } = await import('./providers/claude-code/index.js');
+        return new ClaudeCodeAdapter();
+    });
+    providers.set('opencode', async () => {
+        const { OpenCodeAdapter } = await import('./providers/opencode/index.js');
+        return new OpenCodeAdapter();
+    });
+    providers.set('cursor', async () => {
+        const { CursorAdapter } = await import('./providers/cursor/index.js');
+        return new CursorAdapter();
+    });
+    providers.set('pi', async () => {
+        const { PiAdapter } = await import('./providers/pi/index.js');
+        return new PiAdapter();
+    });
+    return providers;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAqCzC,0DAA0D;AAC1D,MAAM,YAAY,GAAG,CAAC,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAU,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,SAAS,GAAsB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAE9E,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;YAChE,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YAChD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkC,CAAC;IAE5D,SAAS,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;QACtC,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,kCAAkC,CAAC,CAAC;QAC/E,OAAO,IAAI,iBAAiB,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE;QACnC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;QAC1E,OAAO,IAAI,eAAe,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QACjC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;QACtE,OAAO,IAAI,aAAa,EAAE,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QAC7B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QAC9D,OAAO,IAAI,SAAS,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.4.30",
+  "version": "2026.4.35",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -12,8 +12,8 @@
     }
   },
   "dependencies": {
-    "@cleocode/caamp": "2026.4.30",
-    "@cleocode/contracts": "2026.4.30"
+    "@cleocode/caamp": "2026.4.35",
+    "@cleocode/contracts": "2026.4.35"
   },
   "license": "MIT",
   "engines": {

package/src/providers/pi/adapter.ts

@@ -0,0 +1,240 @@
+/**
+ * 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 type {
+  AdapterCapabilities,
+  AdapterHealthStatus,
+  CLEOProviderAdapter,
+} from '@cleocode/contracts';
+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(): 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');
+}
+
+/**
+ * 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 implements CLEOProviderAdapter {
+  /** Unique provider identifier. */
+  readonly id = 'pi';
+  /** Human-readable provider name. */
+  readonly name = 'Pi';
+  /** Adapter version string. */
+  readonly version = '1.0.0';
+
+  /** Declared capabilities for this provider. */
+  capabilities: AdapterCapabilities = {
+    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: PiHookProvider;
+  /** Spawn provider for launching subagent processes via `pi` CLI. */
+  spawn: PiSpawnProvider;
+  /** Install provider for managing AGENTS.md instruction files. */
+  install: PiInstallProvider;
+
+  /** Project directory this adapter was initialized with, or null. */
+  private projectDir: string | null = null;
+  /** Whether {@link initialize} has been called. */
+  private 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: string): Promise<void> {
+    this.projectDir = projectDir;
+    this.initialized = true;
+  }
+
+  /**
+   * Dispose the adapter and clean up resources.
+   *
+   * Unregisters hooks and releases any tracked state.
+   */
+  async dispose(): Promise<void> {
+    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(): Promise<AdapterHealthStatus> {
+    const details: Record<string, unknown> = {};
+
+    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(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get the project directory this adapter was initialized with.
+   */
+  getProjectDir(): string | null {
+    return this.projectDir;
+  }
+}