@buihongduc132/pi-acp-agents 0.3.1

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@buihongduc132/pi-acp-agents",
+  "version": "0.3.1",
+  "description": "Pi extension: ACP agent client — spawn and control ACP-compatible agents (Gemini CLI, etc.) from within pi",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "acp",
+    "agent-client-protocol",
+    "multi-agent",
+    "pi",
+    "pi-coding-agent"
+  ],
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./src/public-api.ts",
+  "exports": {
+    ".": {
+      "types": "./src/public-api.ts",
+      "import": "./index.ts"
+    },
+    "./api": {
+      "types": "./src/public-api.ts",
+      "import": "./src/public-api.ts"
+    }
+  },
+  "license": "MIT",
+  "author": "buihongduc132",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/buihongduc132/pi-acp-agents.git"
+  },
+  "homepage": "https://github.com/buihongduc132/pi-acp-agents#readme",
+  "bugs": {
+    "url": "https://github.com/buihongduc132/pi-acp-agents/issues"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.21.0",
+    "pi-acp-types": "workspace:*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "typebox": "^1.1.37",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run test:ci",
+    "prepack": "node scripts/prepack.mjs",
+    "postpack": "node scripts/postpack.mjs",
+    "version": "node scripts/version-sync.mjs",
+    "release:patch": "npm version patch -m 'release: v%s'",
+    "release:minor": "npm version minor -m 'release: v%s'",
+    "release:major": "npm version major -m 'release: v%s'",
+    "release:beta": "npm version prerelease --preid=beta -m 'release: v%s'",
+    "publish:beta": "npm publish --tag beta --access public",
+    "publish:next": "npm publish --tag next --access public",
+    "publish:dry": "npm publish --dry-run --access public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/skills/pi-acp-agents/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: pi-acp-agents
+description: Use when working with the pi-acp-agents package, its ACP tool surface, ACP agent session lifecycle, or ACP configuration and runtime behavior inside pi.
+---
+
+# pi-acp-agents
+
+ACP agent client for pi — spawn and control ACP-compatible agents from within pi.
+
+## What it does
+
+This pi extension registers tools that let the pi LLM communicate with external ACP (Agent Client Protocol) compatible agents like Gemini CLI, Claude, or any custom command that speaks ACP over stdio JSON-RPC.
+
+## Tools
+
+| Tool                    | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `acp_prompt`            | Send a prompt to an ACP agent, get the text response           |
+| `acp_status`            | Show configured agents, active sessions, circuit breaker state |
+| `acp_session_new`       | Create a new isolated session with an agent                    |
+| `acp_session_load`      | Load an existing session by ID                                 |
+| `acp_session_set_model` | Change the model for an active session                         |
+| `acp_session_set_mode`  | Change the mode (thinking level) for an active session         |
+| `acp_cancel`            | Cancel an ongoing prompt                                       |
+| `acp_delegate`          | Delegate a task (short-lived session, auto-disposed)           |
+| `acp_broadcast`         | Send same prompt to multiple agents in parallel                |
+| `acp_compare`           | Get responses from multiple agents and compare them            |
+
+## Configuration
+
+Config file: `~/.pi/acp-agents/config.json`
+
+```json
+{
+  "agent_servers": {
+    "gemini": {
+      "command": "gemini",
+      "args": ["--acp"],
+      "default_model": "gemini-2.5-pro"
+    }
+  },
+  "defaultAgent": "gemini"
+}
+```
+
+### Fields
+
+| Field                       | Default             | Description                               |
+| --------------------------- | ------------------- | ----------------------------------------- |
+| `agent_servers`             | `{ gemini: {...} }` | Map of agent name → config                |
+| `defaultAgent`              | `"gemini"`          | Agent used when not specified             |
+| `staleTimeoutMs`            | `3600000` (1 hour)  | Session auto-close timeout for stalled-no-response and completed-idle |
+| `healthCheckIntervalMs`     | `30000` (30s)       | Background health polling interval        |
+| `circuitBreakerMaxFailures` | `3`                 | Consecutive failures before circuit opens |
+| `circuitBreakerResetMs`     | `60000` (60s)       | Time before circuit half-opens            |
+| `stallTimeoutMs`            | `3600000` (1 hour)  | Per-operation timeout                     |
+
+### Per-agent config
+
+| Field          | Required | Description                   |
+| -------------- | -------- | ----------------------------- |
+| `command`      | **yes**  | Executable to spawn           |
+| `args`         | no       | Arguments (e.g., `["--acp"]`) |
+| `env`          | no       | Extra environment variables   |
+| `cwd`          | no       | Working directory override    |
+| `default_model` | no      | Default model ID              |
+
+## Resilience
+
+- **Circuit breaker**: Opens after N consecutive failures, auto-recovers after timeout
+- **Stall timeout**: Prompts that receive no activity are auto-cancelled
+- **Health polling**: Background monitor enforces separate `lastResponseAt` and `completedAt` 1-hour auto-close policies
+- **Busy mutex**: Prevents concurrent prompts on same session
+- **Process safeguards**: SIGTERM → SIGKILL escalation, EPIPE error handlers
+- **Non-blocking**: All tool errors return as tool error results, never throw
+
+## Architecture
+
+```
+Adapter pattern:
+  AcpAgentAdapter (abstract base)
+  ├── GeminiAcpAdapter  — gemini --acp defaults
+  └── CustomAcpAdapter  — any user-defined ACP command
+
+Client layer:
+  AcpClient — wraps @agentclientprotocol/sdk ClientSideConnection
+
+Resilience:
+  AcpCircuitBreaker — wraps all tool execute calls
+  HealthMonitor — background session health polling
+
+Coordination:
+  AgentCoordinator — multi-agent delegate/broadcast/compare
+```
+
+## Logs
+
+Central logs: `~/.pi/acp-agents/logs/`
+
+- `main.log` — general log
+- `session-{id}/trace.jsonl` — per-session JSON-RPC traces
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated: `gemini --version` + `gemini` (login)
+- ACP TypeScript SDK: bundled as dependency
+
+## References
+
+- ACP Protocol: https://agentclientprotocol.com/protocol/overview
+- ACP TypeScript SDK: `@agentclientprotocol/sdk`
+- Gemini ACP docs: https://geminicli.com/docs/cli/acp-mode/

package/src/acp-widget.ts

@@ -0,0 +1,379 @@
+/**
+ * ACP TUI Widget — persistent panel for ACP agent status
+ *
+ * Renders in pi's TUI status area, similar to pi-agent-teams widget.
+ * Shows: header, circuit breaker state, per-session rows, totals, hints.
+ */
+
+import type { Theme, ThemeColor } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export type AcpSessionStatus = "active" | "idle" | "stale" | "error";
+
+export interface AcpWidgetSession {
+	sessionId: string;
+	sessionName?: string;
+	agentName: string;
+	cwd: string;
+	status: AcpSessionStatus;
+	lastActivityAt: Date;
+	createdAt: Date;
+	model?: string;
+}
+
+export interface AcpWidgetDelegation {
+	id: string;
+	agentName: string;
+	phase: string;
+	startedAt: Date;
+	lastActivityAt: Date;
+	text?: string;
+}
+
+export interface AcpDelegationHistoryEntry {
+	agentName: string;
+	status: "completed" | "error";
+	error?: string;
+	sessionId?: string;
+	finishedAt: Date;
+}
+
+export interface AcpWidgetActivity {
+	activeDelegations: number;
+	activeBroadcasts: number;
+	activeCompares: number;
+	delegations: AcpWidgetDelegation[];
+	/** Capped at 20 entries — most recent last. */
+	delegationHistory?: AcpDelegationHistoryEntry[];
+	lastError?: string;
+}
+
+export interface AcpWidgetWorker {
+	name: string;
+	agentName: string;
+	status: string;
+	tokenCountTotal: number;
+	toolCallCount: number;
+	ageSeconds: number;
+	stale: boolean;
+	currentTaskId?: string;
+}
+
+export interface AcpWidgetState {
+	sessions: AcpWidgetSession[];
+	circuitBreakerState: "closed" | "open" | "half-open";
+	configuredAgentNames: string[];
+	configuredAliases?: string[];
+	defaultAgent?: string;
+	activity: AcpWidgetActivity;
+	workers?: AcpWidgetWorker[];
+}
+
+// ── Status styling ──────────────────────────────────────────────────
+
+const STATUS_ICON: Record<AcpSessionStatus, string> = {
+	active: "●",
+	idle: "○",
+	stale: "◻",
+	error: "✕",
+};
+
+const STATUS_COLOR: Record<AcpSessionStatus, ThemeColor> = {
+	active: "success",
+	idle: "muted",
+	stale: "warning",
+	error: "error",
+};
+
+const CB_ICON: Record<string, { icon: string; color: ThemeColor }> = {
+	closed: { icon: "●", color: "success" },
+	open: { icon: "✕", color: "error" },
+	"half-open": { icon: "◐", color: "warning" },
+};
+
+const WORKER_STATUS_ICON: Record<string, { icon: string; color: ThemeColor }> = {
+	online: { icon: "●", color: "success" },
+	idle: { icon: "○", color: "muted" },
+	busy: { icon: "●", color: "accent" },
+	offline: { icon: "✕", color: "dim" },
+};
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+/** Pad a string to a visible width, accounting for ANSI escape codes. */
+function padRight(text: string, width: number): string {
+	const vw = visibleWidth(text);
+	return vw >= width ? text : text + " ".repeat(width - vw);
+}
+
+/** Format token count with K/M suffix. */
+function formatTokens(count: number): string {
+	if (count === 0) return "0";
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}K`;
+	return String(count);
+}
+
+/** Short session ID — first 8 chars. */
+function shortId(id: string): string {
+	return id.length <= 8 ? id : id.slice(0, 8) + "…";
+}
+
+/** Time ago string. */
+function timeAgo(date: Date): string {
+	const ms = Date.now() - date.getTime();
+	if (ms < 5_000) return "just now";
+	if (ms < 60_000) return `${Math.floor(ms / 1_000)}s ago`;
+	if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m ago`;
+	if (ms < 86_400_000) return `${Math.floor(ms / 3_600_000)}h ago`;
+	return `${Math.floor(ms / 86_400_000)}d ago`;
+}
+
+// ── Widget factory ──────────────────────────────────────────────────
+
+export type AcpWidgetDeps = {
+	getState(): AcpWidgetState;
+};
+
+export type AcpWidgetFactory = (
+	tui: unknown,
+	theme: Theme,
+) => Component & { dispose?(): void };
+
+export function createAcpWidget(deps: AcpWidgetDeps): AcpWidgetFactory {
+	return (_tui: unknown, theme: Theme): Component & { dispose?(): void } => {
+		// Refresh every 5s to update "time ago" displays
+		const refreshInterval = setInterval(() => {
+			// No-op; the widget is re-rendered on each TUI paint cycle
+			// via the closure over deps.getState()
+		}, 5_000);
+
+		return {
+			render(width: number): string[] {
+				const state = deps.getState();
+
+				// Hide when nothing to show
+				const hasWorkers = (state.workers?.length ?? 0) > 0;
+				if (
+					state.sessions.length === 0 &&
+					state.configuredAgentNames.length === 0 &&
+					!hasWorkers
+				) {
+					return [];
+				}
+
+				const lines: string[] = [];
+
+				// ── Header ──
+				const header = " " + theme.bold(theme.fg("accent", "ACP Agents"));
+				lines.push(truncateToWidth(header, width));
+
+				// ── Circuit breaker state (only show if not closed) ──
+				if (state.circuitBreakerState !== "closed") {
+					const cb = CB_ICON[state.circuitBreakerState] ?? CB_ICON["open"];
+					const cbLabel =
+						state.circuitBreakerState === "half-open"
+							? "half-open (probing)"
+							: state.circuitBreakerState;
+					lines.push(
+						truncateToWidth(
+							` ${theme.fg(cb.color, `${cb.icon} circuit breaker: ${cbLabel}`)}`,
+							width,
+						),
+					);
+				}
+
+				const totalTransient =
+					state.activity.activeDelegations +
+					state.activity.activeBroadcasts +
+					state.activity.activeCompares;
+				const activitySummary = state.activity.lastError
+					? `error: ${state.activity.lastError}`
+					: totalTransient > 1
+						? `busy (${totalTransient})`
+						: state.activity.activeDelegations > 0
+							? "delegating"
+							: state.activity.activeBroadcasts > 0
+								? "broadcasting"
+								: state.activity.activeCompares > 0
+									? "comparing"
+									: "idle";
+				const activityColor: ThemeColor = state.activity.lastError
+					? "error"
+					: totalTransient > 0
+						? "accent"
+						: "muted";
+				lines.push(
+					truncateToWidth(
+						` ${theme.fg(activityColor, `status: ${activitySummary}`)}`,
+						width,
+					),
+				);
+
+				// ── Delegation rows (when active) ──
+				if (state.activity.delegations && state.activity.delegations.length > 0) {
+					for (const del of state.activity.delegations) {
+						const phaseIcon = del.phase === "prompting" ? "\u27F3" : del.phase === "done" ? "\u2713" : "\u23F3";
+						const delLine = ` ${theme.fg("accent", `${phaseIcon} ${del.agentName}`)} ${theme.fg("dim", del.phase)}`;
+						const delText = del.text ? ` ${theme.fg("dim", truncateToWidth(del.text, 40))}` : "";
+						lines.push(truncateToWidth(`${delLine}${delText}`, width));
+					}
+				}
+
+				// ── Recent delegations (from history) ──
+				if (state.activity.delegationHistory && state.activity.delegationHistory.length > 0) {
+					const recent = state.activity.delegationHistory.slice(-5);
+					lines.push(
+						truncateToWidth(
+							` ${theme.fg("dim", "─ recent ─")}`,
+							width,
+						),
+					);
+					for (const entry of recent) {
+						const icon = entry.status === "completed" ? "\u2713" : "\u2717";
+						const color = entry.status === "completed" ? "success" : "error";
+						const errText = entry.error ? ` ${theme.fg("error", truncateToWidth(entry.error, 40))}` : "";
+						const histLine = `   ${theme.fg(color, `${icon} ${entry.agentName}`)}${errText}`;
+						lines.push(truncateToWidth(histLine, width));
+					}
+				}
+
+				// ── No sessions ──
+				if (state.sessions.length === 0) {
+					const agentList = state.configuredAgentNames.join(", ") || "none";
+					lines.push(
+						truncateToWidth(
+							` ${theme.fg("dim", `(no active sessions)  agents: ${agentList}`)}`,
+							width,
+						),
+					);
+					// Don't return early — workers may still need rendering below
+				}
+
+				// ── Build rows ──
+				// Compute column widths
+				const nameWidth = Math.max(
+					...state.sessions.map((s) => visibleWidth(s.agentName)),
+					8, // minimum
+				);
+				const idWidth = 8; // short session ID
+
+				for (const session of state.sessions) {
+					const icon = theme.fg(
+						STATUS_COLOR[session.status],
+						STATUS_ICON[session.status],
+					);
+					const name = theme.bold(padRight(session.agentName, nameWidth));
+					const id = theme.fg(
+						"dim",
+						shortId(session.sessionId).padEnd(idWidth),
+					);
+					const friendlyName = session.sessionName
+						? ` ${theme.fg("accent", session.sessionName)}`
+						: "";
+					const statusLabel = theme.fg(
+						STATUS_COLOR[session.status],
+						padRight(session.status, 7),
+					);
+					const modelLabel = session.model
+						? ` ${theme.fg("muted", session.model)}`
+						: "";
+					const activity = theme.fg("dim", timeAgo(session.lastActivityAt));
+
+					const row = ` ${icon} ${name}${friendlyName} ${id} ${statusLabel}${modelLabel} · ${activity}`;
+					lines.push(truncateToWidth(row, width));
+				}
+
+				// ── Worker rows (persistent workers) ──
+				if (state.workers && state.workers.length > 0) {
+					lines.push(
+						truncateToWidth(
+							" " + theme.fg("dim", "─ workers ─"),
+							width,
+						),
+					);
+					for (const w of state.workers) {
+						// Resolve status icon — use stale icon for stale workers, otherwise map by status
+						const statusBase = w.status.startsWith("stale") ? "offline" : w.status;
+						const wIcon = WORKER_STATUS_ICON[statusBase] ?? { icon: "○", color: "muted" as ThemeColor };
+						const statusColor: ThemeColor = w.status.startsWith("stale") ? "warning" : wIcon.color;
+						const staleIndicator = w.stale ? theme.fg("warning", " ⚠ stale") : "";
+						const taskInfo = w.currentTaskId ? theme.fg("dim", ` · task=${w.currentTaskId}`) : "";
+						const workerLine = ` ${theme.fg(statusColor, wIcon.icon)} ${theme.bold(w.name)}: ${theme.fg(statusColor, w.status)} · tok=${formatTokens(w.tokenCountTotal)} · tools=${w.toolCallCount} · ${w.ageSeconds}s ago${taskInfo}${staleIndicator}`;
+						lines.push(truncateToWidth(workerLine, width));
+					}
+				}
+
+				// ── Separator + Summary ──
+				lines.push(
+					truncateToWidth(
+						" " + theme.fg("dim", "─".repeat(Math.max(0, width - 2))),
+						width,
+					),
+				);
+
+				const totalActive = state.sessions.filter(
+					(s) => s.status === "active",
+				).length;
+				const totalIdle = state.sessions.filter(
+					(s) => s.status === "idle",
+				).length;
+				const totalStale = state.sessions.filter(
+					(s) => s.status === "stale",
+				).length;
+				const totalSessions = state.sessions.length;
+
+				const summaryParts: string[] = [
+					`${totalSessions} session${totalSessions !== 1 ? "s" : ""}`,
+				];
+				if (totalActive > 0) summaryParts.push(`${totalActive} active`);
+				if (totalIdle > 0) summaryParts.push(`${totalIdle} idle`);
+				if (totalStale > 0) summaryParts.push(`${totalStale} stale`);
+
+				// Worker summary counts
+				const workerCount = (state.workers?.length ?? 0);
+				if (workerCount > 0) {
+					const wBusy = state.workers!.filter((w) => w.status === "busy").length;
+					const wStale = state.workers!.filter((w) => w.stale).length;
+					const wIdle = workerCount - wBusy - wStale - state.workers!.filter((w) => w.status === "offline").length;
+					const wParts: string[] = [`${workerCount} worker${workerCount !== 1 ? "s" : ""}`];
+					if (wBusy > 0) wParts.push(`${wBusy} busy`);
+					if (wIdle > 0) wParts.push(`${wIdle} idle`);
+					if (wStale > 0) wParts.push(`${wStale} stale`);
+					summaryParts.push(wParts.join(" "));
+				}
+
+				const agentsConfigured = state.configuredAgentNames.length;
+				const defaultLabel = state.defaultAgent
+					? ` · default: ${state.defaultAgent}`
+					: "";
+
+				lines.push(
+					truncateToWidth(
+						` ${theme.fg("muted", summaryParts.join(" · "))}  ${theme.fg("dim", `${agentsConfigured} agent${agentsConfigured !== 1 ? "s" : ""} configured${defaultLabel}`)}`,
+						width,
+					),
+				);
+
+				// ── Hints ──
+				lines.push(
+					truncateToWidth(
+						theme.fg("dim", " /acp · /acp-config · acp_status · acp_prompt <msg>"),
+						width,
+					),
+				);
+
+				return lines;
+			},
+
+			invalidate() {},
+
+			dispose() {
+				clearInterval(refreshInterval);
+			},
+		};
+	};
+}

package/src/adapter-factory.ts

@@ -0,0 +1,55 @@
+/**
+ * pi-acp-agents — Adapter factory with mode-based routing.
+ *
+ * Routing priority:
+ * 1. mode === 'acpx' → AcpxAdapter (CLI delegation)
+ * 2. mode === 'direct' or undefined → name-based routing to dedicated adapters
+ */
+
+import type { AcpAgentAdapter } from "./adapters/base.js";
+import { AcpxAdapter } from "./adapters/acpx.js";
+import { CodexAcpAdapter } from "./adapters/codex.js";
+import { CustomAcpAdapter } from "./adapters/custom.js";
+import { GeminiAcpAdapter } from "./adapters/gemini.js";
+import { OpenCodeAcpAdapter } from "./adapters/opencode.js";
+import type { AcpAgentConfig, AcpConfig } from "./config/types.js";
+
+/** Known adapter names that map to dedicated adapter classes */
+const KNOWN_ADAPTERS = new Set(["gemini", "opencode", "codex"]);
+
+export function createAdapter(
+	agentName: string,
+	agentConfig: AcpAgentConfig,
+	_globalConfig: AcpConfig,
+	cwd?: string,
+	adapterOpts?: { onActivity?: (sessionId: string) => void; onSessionUpdate?: (sessionId: string, update: import("@agentclientprotocol/sdk").SessionUpdate) => void },
+): AcpAgentAdapter {
+	const sharedOpts = { onActivity: adapterOpts?.onActivity, onSessionUpdate: adapterOpts?.onSessionUpdate };
+
+	// Mode-based routing: acpx mode always routes to AcpxAdapter
+	if (agentConfig.mode === "acpx") {
+		return new AcpxAdapter({ config: agentConfig, cwd, agentName, ...sharedOpts }) as unknown as AcpAgentAdapter;
+	}
+
+	// Direct mode (or undefined/default) → name-based routing
+	switch (agentName) {
+		case "gemini":
+			return new GeminiAcpAdapter({ config: agentConfig, cwd, ...sharedOpts });
+		case "opencode":
+			return new OpenCodeAcpAdapter({ config: agentConfig, cwd, ...sharedOpts });
+		case "codex":
+			return new CodexAcpAdapter({ config: agentConfig, cwd, ...sharedOpts });
+		default:
+			return new CustomAcpAdapter({
+				config: agentConfig,
+				agentName,
+				cwd,
+				...sharedOpts,
+			});
+	}
+}
+
+/** Check if an agent name has a dedicated adapter */
+export function isKnownAdapter(name: string): boolean {
+	return KNOWN_ADAPTERS.has(name);
+}