@buihongduc132/pi-acp-agents 0.3.1

package/src/adapters/acpx.ts

@@ -0,0 +1,215 @@
+/**
+ * pi-acp-agents — ACPX CLI adapter.
+ *
+ * Delegates ACP agent interaction to the `acpx` CLI instead of managing
+ * a subprocess directly. Session lifecycle is handled via CLI commands:
+ *   - spawn  → acpx sessions create
+ *   - prompt → acpx sessions prompt
+ *   - cancel → acpx sessions cancel
+ *   - dispose → acpx sessions close
+ */
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+import type { AcpAdapterOptions, AcpPromptResult } from "../config/types.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TIMEOUT_SEC = 3600; // 1 hour
+const ACX_BINARY = "acpx";
+
+/**
+ * Escape a string for safe use as a cmd.exe argument on Windows.
+ * When shell:true is used, cmd.exe interprets metacharacters like & | < > ^ %.
+ * This wraps the arg in double quotes and escapes internal quotes and carets.
+ */
+function escapeWindowsArg(arg: string): string {
+	// cmd.exe metacharacters: & | < > ^ % ( ) "
+	// Wrap in quotes and escape internal quotes with ^"
+	const escaped = arg.replace(/"/g, '""');
+	return `"${escaped}"`;
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+interface AcpxSessionState {
+	sessionId: string | null;
+	connected: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+export class AcpxAdapter {
+	public readonly name = "acpx";
+	private state: AcpxSessionState = { sessionId: null, connected: false };
+	private cwd: string;
+	private agentName: string;
+
+	constructor(opts: AcpAdapterOptions) {
+		this.cwd = opts.cwd ?? process.cwd();
+		this.agentName = opts.agentName ?? (opts.config.command
+			? opts.config.command.split("/").pop() ?? "acpx"
+			: "acpx");
+	}
+
+	// -----------------------------------------------------------------------
+	// Public API — matches AcpAgentAdapter surface
+	// -----------------------------------------------------------------------
+
+	async spawn(): Promise<void> {
+		let result: ReturnType<typeof spawnSync>;
+		try {
+			result = this._runAcpx(["sessions", "create", this.agentName, "--format", "json"]);
+		} catch (err: unknown) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`AcpxAdapter spawn failed: ${msg}`);
+		}
+		if (result.error) {
+			throw new Error(`AcpxAdapter spawn failed: ${result.error.message}`);
+		}
+		if (result.status !== 0) {
+			const err = String(result.stderr ?? "").trim() || "acpx sessions create failed";
+			throw new Error(`AcpxAdapter spawn failed: ${err}`);
+		}
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(String(result.stdout));
+		} catch {
+			throw new Error(`AcpxAdapter spawn failed: invalid JSON response`);
+		}
+		const sessionId = parsed["sessionId"];
+		this.state.sessionId = typeof sessionId === "string" ? sessionId : null;
+		this.state.connected = true;
+	}
+
+	async initialize(): Promise<void> {
+		// acpx manages its own init; no separate handshake needed
+		if (!this.state.connected) {
+			throw new Error("Not spawned — call spawn() first");
+		}
+	}
+
+	async newSession(_cwd?: string): Promise<string> {
+		if (!this.state.connected) throw new Error("Not spawned");
+		// acpx creates a new session per spawn; return current ID
+		if (!this.state.sessionId) {
+			throw new Error("No session ID after spawn");
+		}
+		return this.state.sessionId;
+	}
+
+	async prompt(message: string): Promise<AcpPromptResult> {
+		if (!this.state.connected) throw new Error("Not spawned — call spawn() first");
+		if (!this.state.sessionId) throw new Error("No session ID");
+
+		const timeout = DEFAULT_TIMEOUT_SEC;
+		const args = [
+			"sessions", "prompt",
+			"--session", this.state.sessionId,
+			"--format", "json",
+			"--approve-all",
+			"--timeout", String(timeout),
+			"--",
+			message,
+		];
+		let result: ReturnType<typeof spawnSync>;
+		try {
+			result = this._runAcpx(args);
+		} catch (err: unknown) {
+			const msg = err instanceof Error ? err.message : String(err);
+			throw new Error(`AcpxAdapter prompt failed: ${msg}`);
+		}
+		if (result.error) {
+			throw new Error(`AcpxAdapter prompt failed: ${result.error.message}`);
+		}
+		if (result.status !== 0) {
+			const err = String(result.stderr ?? "").trim() || "acpx prompt failed";
+			throw new Error(`AcpxAdapter prompt failed: ${err}`);
+		}
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(String(result.stdout));
+		} catch {
+			throw new Error(`AcpxAdapter prompt failed: invalid JSON response`);
+		}
+		const text = typeof parsed["text"] === "string" ? parsed["text"] : "";
+		const stopReason = typeof parsed["stopReason"] === "string"
+			? parsed["stopReason"]
+			: typeof parsed["stop_reason"] === "string" ? parsed["stop_reason"] : "end_turn";
+		const sessionId = typeof parsed["sessionId"] === "string"
+			? parsed["sessionId"]
+			: typeof parsed["session_id"] === "string" ? parsed["session_id"] : this.state.sessionId!;
+		return {
+			text,
+			stopReason,
+			sessionId,
+		};
+	}
+
+	async cancel(): Promise<void> {
+		if (!this.state.sessionId) return;
+		try {
+			this._runAcpx(["sessions", "cancel", "--session", this.state.sessionId]);
+		} catch {
+			// best-effort — cancel must not throw
+		}
+	}
+
+	async loadSession(sessionId: string): Promise<string> {
+		this.state.sessionId = sessionId;
+		this.state.connected = true;
+		return sessionId;
+	}
+
+	async setModel(_modelId: string): Promise<void> {
+		// acpx doesn't support per-session model switching via CLI
+		// Model is configured at the acpx profile level
+	}
+
+	async setMode(_modeId: string): Promise<void> {
+		// acpx doesn't support per-session mode switching via CLI
+	}
+
+	getSessionId(): string | null {
+		return this.state.sessionId;
+	}
+
+	get connected(): boolean {
+		return this.state.connected;
+	}
+
+	dispose(): void {
+		if (this.state.sessionId) {
+			try {
+				this._runAcpx(["sessions", "close", this.state.sessionId]);
+			} catch {
+				// best-effort — dispose must not throw
+			}
+		}
+		this.state.sessionId = null;
+		this.state.connected = false;
+	}
+
+	// -----------------------------------------------------------------------
+	// Internal
+	// -----------------------------------------------------------------------
+
+	private _runAcpx(args: string[]) {
+		const isWindows = platform() === "win32";
+		// When shell:true on Windows, cmd.exe interprets metacharacters (&, |, <, >, ^, %).
+		// Escape args that may contain user-controlled content (e.g. prompt messages).
+		const safeArgs = isWindows ? args.map(escapeWindowsArg) : args;
+		return spawnSync(ACX_BINARY, safeArgs, {
+			cwd: this.cwd,
+			encoding: "utf-8",
+			timeout: 120_000, // 2 min for CLI itself; prompt timeout is passed to acpx
+			maxBuffer: 10 * 1024 * 1024, // 10 MB
+			shell: isWindows,
+		});
+	}
+}

package/src/adapters/base.ts

@@ -0,0 +1,117 @@
+/**
+ * Base ACP Agent Adapter — abstract class for all ACP agent adapters.
+ *
+ * Subclasses provide agent-specific defaults via applyDefaults() and get name().
+ * The base class handles the ACP lifecycle via AcpClient.
+ */
+import { AcpClient, type AcpClientOptions } from "../core/client.js";
+import type { AcpAgentConfig, AcpAdapterOptions, AcpPromptResult } from "../config/types.js";
+import type { Logger } from "../logger.js";
+import { createNoopLogger } from "../logger.js";
+
+export type { AcpAdapterOptions };
+
+export abstract class AcpAgentAdapter {
+  protected config: AcpAgentConfig;
+  protected clientInfo: { name: string; version: string };
+  protected logger: Logger;
+  protected cwd: string;
+  protected client: AcpClient | null = null;
+  protected onActivity?: (sessionId: string) => void;
+  protected onSessionUpdate?: (sessionId: string, update: import("@agentclientprotocol/sdk").SessionUpdate) => void;
+
+  constructor(opts: AcpAdapterOptions) {
+    this.config = this.applyDefaults(opts.config);
+    this.clientInfo = opts.clientInfo ?? { name: "pi-acp-agents", version: "0.1.0" };
+    this.logger = opts.logger ?? createNoopLogger();
+    this.cwd = opts.cwd ?? process.cwd();
+    this.onActivity = opts.onActivity;
+    this.onSessionUpdate = opts.onSessionUpdate;
+  }
+
+  /** Subclasses override to provide agent-specific default config values */
+  protected applyDefaults(config: AcpAgentConfig): AcpAgentConfig {
+    return { ...config };
+  }
+
+  /** Adapter name (e.g., "gemini", "custom") */
+  abstract get name(): string;
+
+  /** Spawn the agent process and establish ACP connection */
+  async spawn(): Promise<void> {
+    const client = new AcpClient({
+      agentName: this.name,
+      config: this.config,
+      cwd: this.cwd,
+      clientInfo: this.clientInfo,
+      onActivity: this.onActivity,
+      onSessionUpdate: this.onSessionUpdate,
+    });
+    await client.connect();
+    // Only assign after successful connect
+    this.client = client;
+  }
+
+  /** ACP initialize handshake */
+  async initialize(): Promise<void> {
+    if (!this.client) throw new Error("Not spawned — call spawn() first");
+    await this.client.initialize();
+  }
+
+  /** Create a new session, returns sessionId */
+  async newSession(_cwd?: string): Promise<string> {
+    if (!this.client) throw new Error("Not spawned");
+    return this.client.newSession();
+  }
+
+  /** Send a prompt and get the result */
+  async prompt(message: string): Promise<AcpPromptResult> {
+    if (!this.client) throw new Error("Not spawned");
+    return this.client.quickPrompt(message);
+  }
+
+  /** Cancel ongoing prompt */
+  async cancel(): Promise<void> {
+    await this.client?.cancel();
+  }
+
+  /** Load an existing session by ID */
+  async loadSession(sessionId: string): Promise<string> {
+    if (!this.client) throw new Error("Not spawned");
+    return this.client.loadSession(sessionId);
+  }
+
+  /** Set the model for the current session */
+  async setModel(modelId: string): Promise<void> {
+    if (!this.client) throw new Error("Not spawned");
+    await this.client.setModel(modelId);
+  }
+
+  /** Set the mode (thinking level) for the current session */
+  async setMode(modeId: string): Promise<void> {
+    if (!this.client) throw new Error("Not spawned");
+    await this.client.setMode(modeId);
+  }
+
+  /** Get current session ID */
+  getSessionId(): string | null {
+    return this.client?.sessionId ?? null;
+  }
+
+  /** Check if connected */
+  get connected(): boolean {
+    return this.client?.connected ?? false;
+  }
+
+  /** Clean up — kill process and release resources */
+  dispose(): void {
+    if (this.client) {
+      try {
+        this.client.dispose();
+      } catch {
+        // best-effort — dispose must not throw
+      }
+      this.client = null;
+    }
+  }
+}

package/src/adapters/codex.ts

@@ -0,0 +1,77 @@
+/**
+ * pi-acp-agents — Codex ACP adapter
+ *
+ * Protocol: stdio nd-JSON, standard ACP.
+ * Uses the third-party codex-acp bridge (cola-io/codex-acp) which wraps
+ * the OpenAI Codex runtime with ACP protocol.
+ *
+ * No provider-specific features — pure ACP protocol compliance.
+ */
+import { AcpAgentAdapter } from "./base.js";
+import type { AcpAgentConfig } from "../config/types.js";
+import type { Logger } from "../logger.js";
+import { createNoopLogger } from "../logger.js";
+import { execSync } from "node:child_process";
+
+const log = createNoopLogger();
+
+export interface CodexAdapterOptions {
+	config?: Partial<AcpAgentConfig>;
+	clientInfo?: { name: string; version: string };
+	logger?: Logger;
+	cwd?: string;
+}
+
+export class CodexAcpAdapter extends AcpAgentAdapter {
+	constructor(opts: Partial<CodexAdapterOptions> = {}) {
+		super({
+			config: {
+				command: "codex-acp",
+				args: [],
+				...opts.config,
+			} as AcpAgentConfig,
+			clientInfo: opts.clientInfo,
+			logger: opts.logger,
+			cwd: opts.cwd,
+		});
+	}
+
+	get name(): string {
+		return "codex";
+	}
+
+	protected applyDefaults(config: AcpAgentConfig): AcpAgentConfig {
+		return {
+			...config,
+			command: config.command || "codex-acp",
+			args: config.args ?? [],
+		};
+	}
+
+	/** Check if codex-acp binary is available */
+	static isAvailable(): boolean {
+		try {
+			execSync("which codex-acp", { stdio: "pipe" });
+			return true;
+		} catch (e) {
+			// codex-acp binary not found on PATH
+			log.debug("codex-acp not found", e);
+			return false;
+		}
+	}
+
+	/** Get codex-acp version */
+	static getVersion(): string | null {
+		try {
+			const output = execSync("codex-acp --version", {
+				encoding: "utf-8",
+				stdio: "pipe",
+			});
+			return output.trim();
+		} catch (e) {
+			// codex-acp version check failed
+			log.debug("codex-acp version check failed", e);
+			return null;
+		}
+	}
+}

package/src/adapters/custom.ts

@@ -0,0 +1,14 @@
+/**
+ * pi-acp-agents — Custom ACP adapter for user-defined commands
+ */
+import { AcpAgentAdapter, type AcpAdapterOptions } from "./base.js";
+
+export class CustomAcpAdapter extends AcpAgentAdapter {
+  get name(): string {
+    return "custom";
+  }
+
+  constructor(opts: AcpAdapterOptions) {
+    super(opts);
+  }
+}

package/src/adapters/gemini.ts

@@ -0,0 +1,66 @@
+/**
+ * pi-acp-agents — Gemini-specific ACP adapter
+ */
+import { AcpAgentAdapter } from "./base.js";
+import type { AcpAgentConfig } from "../config/types.js";
+import type { Logger } from "../logger.js";
+import { createNoopLogger } from "../logger.js";
+import { execSync } from "node:child_process";
+
+export interface GeminiAdapterOptions {
+  config?: Partial<AcpAgentConfig>;
+  clientInfo?: { name: string; version: string };
+  logger?: Logger;
+  cwd?: string;
+}
+
+export class GeminiAcpAdapter extends AcpAgentAdapter {
+  constructor(opts: Partial<GeminiAdapterOptions> = {}) {
+    super({
+      config: {
+        command: "gemini",
+        args: ["--acp"],
+        ...opts.config,
+      } as AcpAgentConfig,
+      clientInfo: opts.clientInfo,
+      logger: opts.logger,
+      cwd: opts.cwd,
+    });
+  }
+
+  get name(): string {
+    return "gemini";
+  }
+
+  protected applyDefaults(config: AcpAgentConfig): AcpAgentConfig {
+    return {
+      ...config,
+      command: config.command || "gemini",
+      args: config.args ?? ["--acp"],
+    };
+  }
+
+  /** Check if gemini CLI is available */
+  static isAvailable(): boolean {
+    try {
+      execSync("which gemini", { stdio: "pipe" });
+      return true;
+    } catch (err) {
+      // gemini CLI not found on PATH
+      createNoopLogger().debug("gemini not available", err);
+      return false;
+    }
+  }
+
+  /** Get gemini CLI version */
+  static getVersion(): string | null {
+    try {
+      const output = execSync("gemini --version", { encoding: "utf-8", stdio: "pipe" });
+      return output.trim();
+    } catch (err) {
+      // gemini version check failed
+      createNoopLogger().debug("gemini version check failed", err);
+      return null;
+    }
+  }
+}

package/src/adapters/opencode.ts

@@ -0,0 +1,101 @@
+/**
+ * pi-acp-agents — OpenCode ACP adapter
+ *
+ * Protocol: stdio nd-JSON, standard ACP.
+ * Command: `opencode acp` (or `ocxo acp` when installed via alias)
+ *
+ * No provider-specific features — pure ACP protocol compliance.
+ */
+import { AcpAgentAdapter } from "./base.js";
+import type { AcpAgentConfig } from "../config/types.js";
+import type { Logger } from "../logger.js";
+import { createNoopLogger } from "../logger.js";
+import { execSync } from "node:child_process";
+
+const log = createNoopLogger();
+
+export interface OpenCodeAdapterOptions {
+	config?: Partial<AcpAgentConfig>;
+	clientInfo?: { name: string; version: string };
+	logger?: Logger;
+	cwd?: string;
+}
+
+export class OpenCodeAcpAdapter extends AcpAgentAdapter {
+	constructor(opts: Partial<OpenCodeAdapterOptions> = {}) {
+		// Auto-resolve binary: prefer explicit config, then ocxo, then opencode
+		const resolvedBinary = opts.config?.command || OpenCodeAcpAdapter.resolveBinary() || "opencode";
+		super({
+			config: {
+				command: resolvedBinary,
+				args: ["acp"],
+				...opts.config,
+			} as AcpAgentConfig,
+			clientInfo: opts.clientInfo,
+			logger: opts.logger,
+			cwd: opts.cwd,
+		});
+	}
+
+	get name(): string {
+		return "opencode";
+	}
+
+	protected applyDefaults(config: AcpAgentConfig): AcpAgentConfig {
+		return {
+			...config,
+			command: config.command || "opencode",
+			args: config.args ?? ["acp"],
+		};
+	}
+
+	/** Check if opencode CLI is available (checks opencode, ocxo) */
+	static isAvailable(binary?: string): boolean {
+		const candidates = binary ? [binary] : ["opencode", "ocxo"];
+		for (const cmd of candidates) {
+			try {
+				execSync(`which ${cmd}`, { stdio: "pipe" });
+				return true;
+			} catch (e) {
+				// Binary not found on PATH
+				log.debug(`opencode '${cmd}' not found`, e);
+				continue;
+			}
+		}
+		return false;
+	}
+
+	/** Get CLI version */
+	static getVersion(binary?: string): string | null {
+		const candidates = binary ? [binary] : ["opencode", "ocxo"];
+		for (const cmd of candidates) {
+			try {
+				const output = execSync(`${cmd} --version`, {
+					encoding: "utf-8",
+					stdio: "pipe",
+				});
+				return `${cmd}: ${output.trim()}`;
+			} catch (e) {
+				// Version check failed for this binary
+				log.debug(`opencode '${cmd}' version check failed`, e);
+				continue;
+			}
+		}
+		return null;
+	}
+
+	/** Resolve the actual binary name to use */
+	static resolveBinary(): string | null {
+		for (const cmd of ["opencode", "ocxo"]) {
+			try {
+				execSync(`which ${cmd}`, { stdio: "pipe" });
+				return cmd;
+			} catch (e) {
+				// Binary not found on PATH
+				log.debug(`opencode '${cmd}' resolve failed`, e);
+				continue;
+			}
+		}
+		return null;
+	}
+}