@buihongduc132/pi-acp-agents 0.3.1

package/src/config/config.ts

@@ -0,0 +1,312 @@
+/**
+ * pi-acp-agents — Config loading and validation
+ *
+ * Config shape mirrors Zed's `agent_servers` pattern.
+ * Back-compat: auto-migrates old `agents` key to `agent_servers`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import type { AcpAgentConfig, AcpAliasConfig, AcpConfig, LegacyAcpConfig } from "./types.js";
+import { createNoopLogger } from "../logger.js";
+
+const log = createNoopLogger();
+
+const CONFIG_PATH = join(homedir(), ".pi", "acp-agents", "config.json");
+
+export const DEFAULT_CONFIG: AcpConfig = {
+	agent_servers: {},
+	staleTimeoutMs: 3_600_000,
+	healthCheckIntervalMs: 30_000,
+	circuitBreakerMaxFailures: 3,
+	circuitBreakerResetMs: 60_000,
+	stallTimeoutMs: 3_600_000, // 1 hour default stall timeout
+	workerAutoClaim: true,
+	workerClaimIntervalMs: 5_000,
+	workerShutdownTimeoutMs: 30_000,
+	workerOnlineMs: 60_000,
+	workerStaleMs: 60_000,
+	modelPolicy: {
+		allowedModels: [],
+		blockedModels: [],
+		requireProviderPrefix: false,
+	},
+};
+
+/** Known agent presets with auto-detected commands */
+export const AGENT_PRESETS: Record<string, () => AcpAgentConfig | null> = {
+	gemini: () => {
+		try {
+			execSync("which gemini", { stdio: "pipe" });
+			return { command: "gemini", args: ["--acp"] };
+		} catch (e) { /* gemini not found on PATH */ log.debug("gemini preset not found", e); return null; }
+	},
+	opencode: () => {
+		for (const cmd of ["opencode", "ocxo"]) {
+			try {
+				execSync(`which ${cmd}`, { stdio: "pipe" });
+				return { command: cmd, args: ["acp"] };
+			} catch (e) { /* binary not found on PATH */ log.debug(`opencode preset '${cmd}' not found`, e); continue; }
+		}
+		return null;
+	},
+	codex: () => {
+		try {
+			execSync("which codex-acp", { stdio: "pipe" });
+			return { command: "codex-acp", args: [] };
+		} catch (e) { /* codex-acp not found on PATH */ log.debug("codex-acp preset not found", e); return null; }
+	},
+};
+
+export function resolveConfigPath(): string {
+	return CONFIG_PATH;
+}
+
+/**
+ * Migrate old `agents` key to `agent_servers`.
+ * Returns normalized partial config with `agent_servers` (never `agents`).
+ */
+function migrateLegacyConfig(raw: Record<string, unknown>): Partial<AcpConfig> {
+	if ("agents" in raw && !("agent_servers" in raw)) {
+		raw.agent_servers = raw.agents;
+		delete raw.agents;
+	}
+	return raw as Partial<AcpConfig>;
+}
+
+/** Validate a partial config. Throws on invalid. Returns full config with defaults merged. */
+export function validateConfig(partial: Partial<AcpConfig>): AcpConfig {
+	if (!partial.agent_servers || typeof partial.agent_servers !== "object") {
+		throw new Error('Config must have an "agent_servers" object');
+	}
+
+	const entries = Object.entries(partial.agent_servers);
+	// Allow empty agent_servers (relaxed validation for CRUD operations)
+	// Still validate individual entries if present
+
+	const agent_servers: Record<string, AcpAgentConfig> = {};
+	for (const [name, agent] of entries) {
+		// EC-16: Validate agent name is non-empty
+		if (!name || name.trim() === "") {
+			throw new Error("Agent name must be a non-empty string");
+		}
+
+		if (!agent || typeof agent !== "object") {
+			throw new Error(`Invalid agent config for "${name}": must be an object`);
+		}
+		// Command is required unless mode is 'acpx' (acpx derives command from its own binary)
+		const isAcpxMode = (agent as Record<string, unknown>).mode === "acpx";
+		if (
+			!isAcpxMode &&
+			(!("command" in agent) ||
+				typeof agent.command !== "string" ||
+				!agent.command)
+		) {
+			throw new Error(
+				`Invalid agent config for "${name}": "command" is required (or set mode: "acpx")`,
+			);
+		}
+		agent_servers[name] = {
+			...agent,
+			args: agent.args ?? [],
+			env: agent.env ?? {},
+		};
+	}
+
+	// Clamp stallTimeoutMs to minimum 60_000 (1 minute)
+	const rawStallTimeout = partial.stallTimeoutMs ?? DEFAULT_CONFIG.stallTimeoutMs!;
+	const stallTimeoutMs = Math.max(rawStallTimeout, 60_000);
+
+	const resolved: AcpConfig = {
+		...DEFAULT_CONFIG,
+		...partial,
+		agent_servers,
+		stallTimeoutMs,
+		staleTimeoutMs: partial.staleTimeoutMs ?? DEFAULT_CONFIG.staleTimeoutMs,
+		healthCheckIntervalMs:
+			partial.healthCheckIntervalMs ?? DEFAULT_CONFIG.healthCheckIntervalMs,
+		circuitBreakerMaxFailures:
+			partial.circuitBreakerMaxFailures ??
+			DEFAULT_CONFIG.circuitBreakerMaxFailures,
+		circuitBreakerResetMs:
+			partial.circuitBreakerResetMs ?? DEFAULT_CONFIG.circuitBreakerResetMs,
+		modelPolicy: {
+			...DEFAULT_CONFIG.modelPolicy,
+			...partial.modelPolicy,
+		},
+		toolTimeouts: partial.toolTimeouts
+			? { ...partial.toolTimeouts }
+			: undefined,
+	};
+
+	// EC-20: Validate numeric fields are non-negative
+	validateNumericFields(resolved);
+	// EC-21: Validate healthCheckIntervalMs <= staleTimeoutMs
+	validateTimeoutOrder(resolved);
+	// EC-22: Validate agent_aliases if present
+	if (resolved.agent_aliases) {
+		validateAgentAliases(resolved.agent_aliases, resolved.agent_servers);
+	}
+
+	return resolved;
+}
+
+/** Validate numeric timeout fields are non-negative (EC-20) */
+function validateNumericFields(resolved: AcpConfig): void {
+	const numericFields: Array<[string, number | undefined]> = [
+		["staleTimeoutMs", resolved.staleTimeoutMs],
+		["healthCheckIntervalMs", resolved.healthCheckIntervalMs],
+		["circuitBreakerResetMs", resolved.circuitBreakerResetMs],
+	];
+	for (const [field, val] of numericFields) {
+		if (val !== undefined && val < 0) {
+			throw new Error(`Config field "${field}" must be non-negative`);
+		}
+	}
+	if (
+		resolved.circuitBreakerMaxFailures !== undefined &&
+		resolved.circuitBreakerMaxFailures < 0
+	) {
+		throw new Error(
+			'Config field "circuitBreakerMaxFailures" must be non-negative',
+		);
+	}
+}
+
+/** Validate healthCheckIntervalMs <= staleTimeoutMs (EC-21) */
+function validateTimeoutOrder(resolved: AcpConfig): void {
+	if (resolved.healthCheckIntervalMs! > resolved.staleTimeoutMs!) {
+		throw new Error("healthCheckIntervalMs must be <= staleTimeoutMs");
+	}
+}
+
+/** Validate agent_aliases entries (EC-22) */
+function validateAgentAliases(
+	aliases: Record<string, AcpAliasConfig>,
+	agent_servers: Record<string, AcpAgentConfig>,
+): void {
+	for (const [aliasName, alias] of Object.entries(aliases)) {
+		if (!aliasName || aliasName.trim() === "") {
+			throw new Error("Alias name must be a non-empty string");
+		}
+		if (!alias.agents || !Array.isArray(alias.agents) || alias.agents.length === 0) {
+			throw new Error(`Alias "${aliasName}" must have a non-empty agents array`);
+		}
+		if (alias.strategy !== "failover" && alias.strategy !== "race") {
+			throw new Error(`Alias "${aliasName}" strategy must be "failover" or "race", got "${alias.strategy}"`);
+		}
+		for (const agentName of alias.agents) {
+			if (!agent_servers[agentName]) {
+				throw new Error(`Alias "${aliasName}" references unknown agent "${agentName}"`);
+			}
+		}
+	}
+}
+
+/** Load config from disk, falling back to defaults. Auto-migrates old `agents` key. */
+export function loadConfig(configPath?: string): AcpConfig {
+	const path = configPath ?? CONFIG_PATH;
+	if (!existsSync(path)) {
+		return structuredClone(DEFAULT_CONFIG);
+	}
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+		const needsMigration = "agents" in raw && !("agent_servers" in raw);
+		const migrated = migrateLegacyConfig(raw);
+
+		// Auto-save migrated config back to disk
+		if (needsMigration) {
+			try {
+				writeFileSync(path, JSON.stringify(migrated, null, 2) + "\n");
+			} catch (e) { log.debug("config migration write failed", e); /* best-effort */ }
+		}
+
+		return validateConfig(migrated);
+	} catch (e) {
+		// Config file corrupt or unreadable — fall back to defaults
+		log.debug("config load failed, using defaults", e);
+		return structuredClone(DEFAULT_CONFIG);
+	}
+}
+
+/** Save config to disk at the given path (or default path) */
+export function saveConfig(config: AcpConfig, configPath?: string): void {
+	const path = configPath ?? CONFIG_PATH;
+	const dir = dirname(path);
+	try {
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+		}
+		const data = JSON.stringify(config, null, 2) + "\n";
+		writeFileSync(path, data, "utf-8");
+	} catch (e) {
+		// EACCES or other FS error — silently degrade. Config changes are non-critical.
+		log.debug("config save failed", e);
+	}
+}
+
+/** Add or update an agent server entry. Returns a new config (does not mutate original). */
+export function upsertAgentServer(config: AcpConfig, name: string, agent: Partial<AcpAgentConfig> & { command: string }): AcpConfig {
+	if (!name || name.trim() === "") {
+		throw new Error("Agent name must be a non-empty string");
+	}
+	if (!agent.command || agent.command.trim() === "") {
+		throw new Error('Agent "command" is required');
+	}
+	const cloned = structuredClone(config);
+	cloned.agent_servers[name] = {
+		command: agent.command,
+		args: agent.args ?? [],
+		env: agent.env ?? {},
+		...(agent.default_model ? { default_model: agent.default_model } : {}),
+		...(agent.default_mode ? { default_mode: agent.default_mode } : {}),
+	};
+	return cloned;
+}
+
+/** Remove an agent server entry. Returns a new config (does not mutate original). Clears defaultAgent if it was the removed agent. */
+export function removeAgentServer(config: AcpConfig, name: string): AcpConfig {
+	const cloned = structuredClone(config);
+	delete cloned.agent_servers[name];
+	if (cloned.defaultAgent === name) {
+		delete cloned.defaultAgent;
+	}
+	return cloned;
+}
+
+/** Set the default agent. Returns a new config (does not mutate original). Throws if agent not found. */
+export function setDefaultAgent(config: AcpConfig, name: string): AcpConfig {
+	if (!config.agent_servers[name]) {
+		throw new Error(`Agent "${name}" not found`);
+	}
+	const cloned = structuredClone(config);
+	cloned.defaultAgent = name;
+	return cloned;
+}
+
+/** Detect available agent presets from the system PATH. */
+export function detectAvailablePresets(): Array<{ name: string; config: AcpAgentConfig }> {
+	const results: Array<{ name: string; config: AcpAgentConfig }> = [];
+	for (const [name, factory] of Object.entries(AGENT_PRESETS)) {
+		const config = factory();
+		if (config) {
+			results.push({ name, config });
+		}
+	}
+	return results;
+}
+
+/** Get a specific agent config, throwing if not found */
+export function getAgentConfig(
+	config: AcpConfig,
+	name: string,
+): AcpAgentConfig {
+	const agent = config.agent_servers[name];
+	if (!agent) {
+		const available = Object.keys(config.agent_servers).join(", ");
+		throw new Error(`Agent "${name}" not found. Available: ${available}`);
+	}
+	return agent;
+}

package/src/config/types.ts

@@ -0,0 +1,203 @@
+/**
+ * pi-acp-agents — Shared types
+ *
+ * Config shape mirrors Zed's `agent_servers` pattern:
+ * flat map of name → server config. No provider-specific fields.
+ * All customization goes through args/env.
+ */
+
+/** Configuration for a single agent alias with fallback chain */
+export interface AcpAliasConfig {
+	agents: string[];
+	strategy: "failover" | "race";
+}
+
+/** Per-agent server configuration (matches Zed's agent_servers entry) */
+export interface AcpAgentConfig {
+	/** How to connect to this agent: 'direct' (subprocess) or 'acpx' (CLI delegation). Default: 'direct'. */
+	mode?: "direct" | "acpx";
+	/** Required for 'direct' mode. Command to spawn the agent subprocess. */
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	/** Default model for sessions created with this agent */
+	default_model?: string;
+	/** Default mode for sessions created with this agent */
+	default_mode?: string;
+	/** Allow passthrough of unknown fields for forward compat */
+	[key: string]: unknown;
+}
+
+/** Top-level config stored at ~/.pi/acp-agents/config.json */
+export interface AcpConfig {
+	/** Agent server definitions. Key = alias name. Matches Zed's agent_servers. */
+	agent_servers: Record<string, AcpAgentConfig>;
+	defaultAgent?: string;
+	logsDir?: string;
+	staleTimeoutMs?: number;
+	healthCheckIntervalMs?: number;
+	circuitBreakerMaxFailures?: number;
+	circuitBreakerResetMs?: number;
+	/** Stall timeout in milliseconds (default: 3_600_000 = 1 hour) */
+	stallTimeoutMs?: number;
+	/** Per-tool timeout overrides in milliseconds. Falls back to stallTimeoutMs. */
+	toolTimeouts?: {
+		prompt?: number;
+		delegate?: number;
+		broadcast?: number;
+		compare?: number;
+	};
+	/** Worker lifecycle config */
+	workerAutoClaim?: boolean;           // default: true
+	workerClaimIntervalMs?: number;      // default: 5000
+	workerShutdownTimeoutMs?: number;     // default: 30000
+	workerOnlineMs?: number;              // default: 60000
+	workerStaleMs?: number;               // default: 60000
+	/** Activity-based stall detection for persistent sessions (ms) */
+	needsAttentionMs?: number;     // default: 60_000
+	autoInterruptMs?: number;      // default: 300_000, 0 = disabled
+	interruptGraceMs?: number;     // default: 10_000
+	/** Agent alias definitions for fallback chains */
+	agent_aliases?: Record<string, AcpAliasConfig>;
+	/** Timeout for race strategy in ms (default: 30_000 = 30s) */
+	raceTimeoutMs?: number;
+	runtimeDir?: string;
+	modelPolicy?: {
+		allowedModels?: string[];
+		blockedModels?: string[];
+		requireProviderPrefix?: boolean;
+	};
+}
+
+/**
+ * Back-compat: old configs may use `agents` instead of `agent_servers`.
+ * This legacy type is only used during migration.
+ */
+export interface LegacyAcpConfig {
+	agents?: Record<string, AcpAgentConfig>;
+	agent_servers?: Record<string, AcpAgentConfig>;
+	[key: string]: unknown;
+}
+
+/** Alias used by some tests */
+export type AcpAgentsConfig = AcpConfig;
+
+/** Result of a prompt call */
+export interface AcpPromptResult {
+	text: string;
+	stopReason: string;
+	sessionId: string;
+	stalled?: boolean;
+}
+
+/** Tracked session info */
+export interface AcpSessionInfo {
+	sessionId: string;
+	sessionName?: string;
+	agentName: string;
+	cwd: string;
+	model?: string;
+	mode?: string;
+	createdAt: Date;
+}
+
+/** Archived runtime metadata used to reopen ACP sessions after auto-close. */
+export interface AcpArchivedSessionMetadata {
+	sessionId: string;
+	sessionName?: string;
+	agentName: string;
+	cwd: string;
+	createdAt: Date;
+	lastActivityAt: Date;
+	lastResponseAt?: Date;
+	completedAt?: Date;
+	disposed: boolean;
+	autoClosed?: boolean;
+	closeReason?: string;
+	model?: string;
+	mode?: string;
+	/** Loadability tracking — whether this archived session can be successfully resumed */
+	loadStatus?: "loadable" | "unloadable" | "unknown";
+	lastLoadAttemptAt?: string;
+	lastLoadError?: string;
+	loadAttemptCount?: number;
+}
+
+/** Internal handle kept by SessionManager. Also satisfies HealthMonitorable. */
+export interface AcpSessionHandle extends AcpArchivedSessionMetadata {
+	accumulatedText: string;
+	busy?: boolean;
+	/** True while a prompt() call is in-flight */
+	isPrompting?: boolean;
+	/** Timestamp when the current prompt started */
+	promptStartedAt?: Date;
+	planStatus?: "none" | "pending" | "approved" | "rejected";
+	dispose: () => Promise<void>;
+}
+
+/** Circuit breaker states */
+export type CircuitState = "closed" | "open" | "half-open";
+
+/** Adapter options */
+export interface AcpAdapterOptions {
+	config: AcpAgentConfig;
+	clientInfo?: { name: string; version: string };
+	logger?: Logger;
+	cwd?: string;
+	agentName?: string;
+	/** Activity callback — called on every session/update notification from the agent */
+	onActivity?: (sessionId: string) => void;
+	/** Session update callback — called on every session/update with full update data */
+	onSessionUpdate?: (sessionId: string, update: import("@agentclientprotocol/sdk").SessionUpdate) => void;
+}
+
+// --- Worker types (M6) ---
+
+export type AcpWorkerStatus = "online" | "idle" | "busy" | "streaming" | "offline";
+
+export interface AcpWorkerRecord {
+	name: string;
+	sessionId: string;
+	agentName: string;
+	status: AcpWorkerStatus;
+	currentTaskId?: string;
+	spawnedAt: string;
+	lastActivityAt: string;
+	/** Last heartbeat timestamp (ISO 8601), updated on every session/update event */
+	lastHeartbeatAt?: string;
+	/** Cumulative token count (tokensIn + tokensOut) from session/update deltas */
+	tokenCountTotal?: number;
+	/** Count of tool calls observed from session/update events */
+	toolCallCount?: number;
+	metadata: Record<string, unknown>;
+}
+
+// --- Task priority (M3, M5) ---
+
+export type AcpTaskPriority = "urgent" | "high" | "normal" | "low";
+
+// --- Async run types (M1) ---
+
+export type AcpAsyncRunState = "pending" | "running" | "completed" | "failed";
+
+export interface AcpAsyncRunRecord {
+	runId: string;
+	agentName: string;
+	message: string;
+	cwd?: string;
+	state: AcpAsyncRunState;
+	sessionId?: string;
+	result?: string;
+	error?: string;
+	createdAt: string;
+	startedAt?: string;
+	completedAt?: string;
+}
+
+/** Logger interface */
+export interface Logger {
+	info(msg: string, data?: unknown): void;
+	error(msg: string, data?: unknown): void;
+	debug(msg: string, data?: unknown): void;
+}