@buihongduc132/pi-acp-agents 0.3.1

package/src/core/health-monitor.ts

@@ -0,0 +1,200 @@
+/**
+ * Health monitor — tracks ACP session lifecycle auto-close policies, polls periodically.
+ *
+ * Two detection layers:
+ * 1. Idle/stale detection (existing): disposes sessions with no activity after staleTimeoutMs.
+ * 2. Prompt stall detection (new): detects active prompts with no streaming chunks,
+ *    emits needs-attention notification, then auto-interrupts if still idle.
+ */
+
+import { getSessionAutoCloseReason } from "./session-lifecycle.js";
+
+export interface HealthMonitorable {
+  sessionId: string;
+  lastActivityAt: Date;
+  lastResponseAt?: Date;
+  completedAt?: Date;
+  busy?: boolean;
+  disposed: boolean;
+  /** True while a prompt() call is in-flight */
+  isPrompting?: boolean;
+  /** Timestamp when the current prompt started */
+  promptStartedAt?: Date;
+}
+
+/** Prompt stall reason — activity-based, separate from idle auto-close */
+export type PromptStallReason = "slow-prompt" | "stalled-prompt";
+
+export interface HealthMonitorOptions {
+  intervalMs: number;
+  staleTimeoutMs: number;
+  /** Idle threshold (ms) before emitting needs-attention for active prompts. Default: 60_000 */
+  needsAttentionMs?: number;
+  /** Idle threshold (ms) before auto-interrupting stalled prompts. Default: 300_000, 0 = disabled */
+  autoInterruptMs?: number;
+  /** Grace period (ms) after cancel before force-kill. Default: 10_000 */
+  interruptGraceMs?: number;
+  onStale?: (sessionId: string) => void | Promise<void>;
+  /** Called when a prompt has been idle > needsAttentionMs but < autoInterruptMs. Notification only. */
+  onNeedsAttention?: (sessionId: string) => void | Promise<void>;
+  /** Called when a prompt is auto-interrupted (stalled-prompt). index.ts handles cancel → kill. */
+  onInterrupt?: (sessionId: string) => void | Promise<void>;
+}
+
+interface TrackedEntry {
+  session: HealthMonitorable;
+  /** Track whether we already notified for this stall cycle (reset on next touch) */
+  attentionNotified: boolean;
+}
+
+export class HealthMonitor {
+  private entries = new Map<string, TrackedEntry>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private _running = false;
+  private opts: HealthMonitorOptions;
+
+  constructor(opts: HealthMonitorOptions) {
+    this.opts = opts;
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  get running(): boolean {
+    return this._running;
+  }
+
+  register(session: HealthMonitorable): void {
+    this.entries.set(session.sessionId, { session, attentionNotified: false });
+  }
+
+  unregister(sessionId: string): void {
+    this.entries.delete(sessionId);
+  }
+
+  isStale(sessionId: string): boolean {
+    const entry = this.entries.get(sessionId);
+    if (!entry) return false;
+    return this.getStaleReason(entry.session) !== undefined;
+  }
+
+  touch(sessionId: string): void {
+    const entry = this.entries.get(sessionId);
+    if (entry) {
+      entry.session.lastActivityAt = new Date();
+      entry.attentionNotified = false;
+    }
+  }
+
+  /** Mark that a prompt() call has started for this session */
+  markPromptStart(sessionId: string): void {
+    const entry = this.entries.get(sessionId);
+    if (entry) {
+      entry.session.isPrompting = true;
+      entry.session.promptStartedAt = new Date();
+      entry.attentionNotified = false;
+    }
+  }
+
+  /** Mark that the prompt() call has ended (completed or threw) */
+  markPromptEnd(sessionId: string): void {
+    const entry = this.entries.get(sessionId);
+    if (entry) {
+      entry.session.isPrompting = false;
+    }
+  }
+
+  start(): void {
+    if (this._running) return;
+    this._running = true;
+    this.timer = setInterval(async () => {
+      const staleIds = await this.check();
+      if (this.opts.onStale) {
+        for (const id of staleIds) {
+          try {
+            await this.opts.onStale(id);
+          } catch (err) {
+            console.error("[acp-health] onStale callback error:", err);
+          }
+        }
+      }
+    }, this.opts.intervalMs);
+  }
+
+  stop(): void {
+    this._running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  async check(): Promise<string[]> {
+    const staleIds: string[] = [];
+    const toRemove: string[] = [];
+
+    for (const [id, entry] of this.entries) {
+      if (entry.session.disposed) {
+        toRemove.push(id);
+        continue;
+      }
+
+      // Check idle/stale detection (existing)
+      if (this.getStaleReason(entry.session)) {
+        staleIds.push(id);
+        continue;
+      }
+
+      // Check prompt stall detection (new) — only for active prompts
+      const stallReason = this.getPromptStallReason(entry.session);
+      if (stallReason === "slow-prompt") {
+        // Emit notification once per stall cycle (reset on touch)
+        if (!entry.attentionNotified && this.opts.onNeedsAttention) {
+          entry.attentionNotified = true;
+          try {
+            await this.opts.onNeedsAttention(id);
+          } catch (err) {
+            console.error("[acp-health] onNeedsAttention callback error:", err);
+          }
+        }
+        // Don't add to staleIds — this is notification only
+        continue;
+      }
+      if (stallReason === "stalled-prompt") {
+        staleIds.push(id);
+        continue;
+      }
+    }
+
+    for (const id of toRemove) {
+      this.entries.delete(id);
+    }
+
+    return staleIds;
+  }
+
+  private getStaleReason(session: HealthMonitorable): "stalled-no-response" | "completed-idle" | undefined {
+    return getSessionAutoCloseReason(session, this.opts.staleTimeoutMs);
+  }
+
+  /**
+   * Check if an active prompt has been idle too long.
+   * Uses lastActivityAt (updated by touch() via onActivity callback) as the activity signal.
+   */
+  private getPromptStallReason(session: HealthMonitorable): PromptStallReason | undefined {
+    const autoInterruptMs = this.opts.autoInterruptMs ?? 300_000;
+    if (autoInterruptMs === 0) return undefined; // disabled
+    if (!session.isPrompting) return undefined;
+
+    const now = Date.now();
+    const idleMs = now - session.lastActivityAt.getTime();
+
+    if (idleMs > autoInterruptMs) return "stalled-prompt";
+
+    const needsAttentionMs = this.opts.needsAttentionMs ?? 60_000;
+    if (idleMs > needsAttentionMs) return "slow-prompt";
+
+    return undefined;
+  }
+}

package/src/core/protocol-validator.ts

@@ -0,0 +1,259 @@
+/**
+ * ACP Protocol Validation — behavior-based detection of non-ACP agents.
+ *
+ * Validates that an agent actually speaks the Agent Client Protocol by checking
+ * response shapes at runtime. Does NOT judge by command name.
+ *
+ * When a mismatch is detected, throws `AcpProtocolError` with an actionable message
+ * explaining what went wrong and how to fix it.
+ */
+
+/** Thrown when an agent's behavior doesn't match ACP protocol */
+export class AcpProtocolError extends Error {
+	readonly agentName: string;
+	readonly command: string;
+	readonly phase: AcpPhase;
+	readonly cause_detail: string;
+
+	constructor(opts: {
+		agentName: string;
+		command: string;
+		phase: AcpPhase;
+		message: string;
+		cause: string;
+	}) {
+		super(
+			`[ACP Protocol Mismatch] Agent "${opts.agentName}" (${opts.command}) failed at ${opts.phase}:\n` +
+			`  ${opts.message}\n` +
+			`  Cause: ${opts.cause}\n` +
+			`  Fix: verify the command speaks ACP over stdio (nd-JSON). ` +
+			`For Zed/JetBrains-style config, use: { "command": "<agent>", "args": ["acp"] }`,
+		);
+		this.name = "AcpProtocolError";
+		this.agentName = opts.agentName;
+		this.command = opts.command;
+		this.phase = opts.phase;
+		this.cause_detail = opts.cause;
+	}
+}
+
+/** Phases of ACP protocol where mismatches can occur */
+export type AcpPhase =
+	| "spawn"
+	| "connect"
+	| "initialize"
+	| "newSession"
+	| "prompt"
+	| "response_shape";
+
+/**
+ * Validate the `initialize` response has the minimum ACP shape.
+ *
+ * Per ACP spec, initialize MUST return:
+ * - protocolVersion: string
+ *
+ * And SHOULD return (may be absent in older agents):
+ * - agentCapabilities: object
+ * - agentInfo: { name?: string, version?: string }
+ */
+export function validateInitializeResponse(
+	resp: unknown,
+	agentName: string,
+	command: string,
+): void {
+	if (!resp || typeof resp !== "object") {
+		throw new AcpProtocolError({
+			agentName,
+			command,
+			phase: "initialize",
+			message: `Response is ${resp === null ? "null" : typeof resp}, expected an object.`,
+			cause: "The agent did not return a valid JSON-RPC response to the 'initialize' method. " +
+				"This usually means the command does not speak ACP, or it printed non-JSON output to stdout.",
+		});
+	}
+
+	const r = resp as Record<string, unknown>;
+
+	if (!("protocolVersion" in r)) {
+		throw new AcpProtocolError({
+			agentName,
+			command,
+			phase: "initialize",
+			message: "Missing 'protocolVersion' field.",
+			cause: "The response does not look like an ACP InitializeResponse. " +
+				"The command may speak a different protocol or returned an error. " +
+				"Got keys: " + Object.keys(r).join(", "),
+		});
+	}
+
+	// Warn but don't fail on missing optional fields
+	if (!("agentCapabilities" in r) && !("capabilities" in r)) {
+		// Log but don't throw — agentCapabilities is optional in the spec
+	}
+}
+
+/**
+ * Validate the `newSession` response has the minimum ACP shape.
+ *
+ * Per ACP spec, newSession MUST return:
+ * - sessionId: string
+ */
+export function validateNewSessionResponse(
+	resp: unknown,
+	agentName: string,
+	command: string,
+): void {
+	if (!resp || typeof resp !== "object") {
+		throw new AcpProtocolError({
+			agentName,
+			command,
+			phase: "newSession",
+			message: `Response is ${resp === null ? "null" : typeof resp}, expected an object.`,
+			cause: "The agent did not return a valid response to the 'session/new' method.",
+		});
+	}
+
+	const r = resp as Record<string, unknown>;
+
+	if (!("sessionId" in r) || typeof r.sessionId !== "string" || !r.sessionId) {
+		throw new AcpProtocolError({
+			agentName,
+			command,
+			phase: "newSession",
+			message: "Missing or invalid 'sessionId' field.",
+			cause: "ACP requires a 'sessionId' string in the newSession response. " +
+				"Got keys: " + Object.keys(r).join(", "),
+		});
+	}
+}
+
+/**
+ * Validate the `prompt` response has the minimum ACP shape.
+ *
+ * Per ACP spec, prompt MUST return:
+ * - stopReason: string
+ */
+export function validatePromptResponse(
+	resp: unknown,
+	agentName: string,
+	command: string,
+): void {
+	if (!resp || typeof resp !== "object") {
+		throw new AcpProtocolError({
+			agentName,
+			command,
+			phase: "prompt",
+			message: `Response is ${resp === null ? "null" : typeof resp}, expected an object.`,
+			cause: "The agent did not return a valid response to the 'prompt' method.",
+		});
+	}
+
+	const r = resp as Record<string, unknown>;
+
+	if (!("stopReason" in r)) {
+		throw new AcpProtocolError({
+			agentName,
+			command,
+			phase: "prompt",
+			message: "Missing 'stopReason' field.",
+			cause: "ACP requires 'stopReason' in the prompt response. " +
+				"Got keys: " + Object.keys(r).join(", "),
+		});
+	}
+}
+
+/**
+ * Classify an error from the ACP connection phase.
+ * Returns an AcpProtocolError if the error indicates a protocol mismatch,
+ * or the original error if it's something else (network, timeout, etc).
+ */
+export function classifyConnectionError(
+	err: unknown,
+	agentName: string,
+	command: string,
+	stderr?: string,
+): Error {
+	if (err instanceof AcpProtocolError) return err;
+
+	const msg = err instanceof Error ? err.message : String(err);
+	const code = (err as { code?: string } | null)?.code ?? "";
+
+	// Method not found (agent doesn't implement ACP) — check BEFORE ENOENT
+	if (msg.includes("Method not found") || msg.includes("-32601")) {
+		return new AcpProtocolError({
+			agentName,
+			command,
+			phase: "initialize",
+			message: "Agent does not implement the ACP 'initialize' method.",
+			cause: "The command exists but doesn't speak ACP. " +
+				"Ensure it's an ACP-compatible agent or you're passing the correct args (e.g., 'acp' or '--acp').",
+		});
+	}
+
+	// Binary missing (ENOENT) or spawn-level failure
+	if (msg.includes("ENOENT") || msg.includes("spawn")) {
+		return new AcpProtocolError({
+			agentName,
+			command,
+			phase: "spawn",
+			message: `Command "${command}" could not be spawned.`,
+			cause: msg + (stderr ? `\nStderr: ${stderr.slice(0, 500)}` : ""),
+		});
+	}
+
+	// Broken pipe / connection reset while talking to the child — the child
+	// exited before the ACP handshake completed (GAP-2). Common when the binary
+	// EXISTS but crashes / has wrong args and dies immediately (e.g. `false`,
+	// missing '--acp' flag). The process writes its initialize request, the
+	// already-dead child's pipe returns EPIPE. Surface as a fast, classified,
+	// spawn-phase rejection instead of hanging to an RPC timeout.
+	if (
+		code === "EPIPE" || code === "ECONNRESET" ||
+		msg.includes("EPIPE") || msg.includes("ECONNRESET") ||
+		msg.includes("ERR_STREAM_WRITE_AFTER_END")
+	) {
+		return new AcpProtocolError({
+			agentName,
+			command,
+			phase: "spawn",
+			message: `Command "${command}" exited immediately before completing the ACP handshake.`,
+			cause:
+				"The process started but exited before speaking ACP — the binary " +
+				"may be missing the ACP flag (e.g. '--acp' or 'acp') or crashed on " +
+				"startup. Original error: " + msg +
+					(stderr ? `\nStderr: ${stderr.slice(0, 500)}` : ""),
+		});
+	}
+
+	// JSON parse errors (agent wrote non-JSON to stdout)
+	if (msg.includes("JSON") || msg.includes("parse") || msg.includes("Unexpected token")) {
+		return new AcpProtocolError({
+			agentName,
+			command,
+			phase: "connect",
+			message: "Agent output is not valid JSON-RPC.",
+			cause: msg + (stderr ? `\nStderr: ${stderr.slice(0, 500)}` : ""),
+		});
+	}
+
+	// Auth errors — NOT a protocol mismatch, just needs setup
+	if (msg.includes("auth") || msg.includes("Auth") || msg.includes("401") || msg.includes("403")) {
+		return err instanceof Error ? err : new Error(msg);
+	}
+
+	// Timeout — agent hung without responding
+	if (msg.includes("timeout") || msg.includes("Timeout") || msg.includes("timed out")) {
+		return new AcpProtocolError({
+			agentName,
+			command,
+			phase: "connect",
+			message: "Agent did not respond within timeout.",
+			cause: "The process started but never sent a valid ACP response. " +
+				"It may be waiting for interactive input, or the command doesn't speak ACP." +
+				(stderr ? `\nStderr: ${stderr.slice(0, 500)}` : ""),
+		});
+	}
+
+	// Unknown error — pass through as-is
+	return err instanceof Error ? err : new Error(msg);
+}

package/src/core/session-lifecycle.ts

@@ -0,0 +1,46 @@
+import type { AcpSessionHandle } from "../config/types.js";
+import type { HealthMonitorable } from "./health-monitor.js";
+
+export type SessionAutoCloseReason = "stalled-no-response" | "completed-idle";
+
+export interface SessionLifecycleState {
+  disposed: boolean;
+  busy?: boolean;
+  lastResponseAt?: Date;
+  completedAt?: Date;
+}
+
+export function getSessionAutoCloseReason(
+  session: SessionLifecycleState,
+  timeoutMs: number,
+  now = Date.now(),
+): SessionAutoCloseReason | undefined {
+  if (session.busy) {
+    if (!session.lastResponseAt) return undefined;
+    return now - session.lastResponseAt.getTime() > timeoutMs
+      ? "stalled-no-response"
+      : undefined;
+  }
+
+  if (!session.completedAt) return undefined;
+  return now - session.completedAt.getTime() > timeoutMs
+    ? "completed-idle"
+    : undefined;
+}
+
+export function isSessionAutoClosable(
+  session: SessionLifecycleState,
+  timeoutMs: number,
+  now = Date.now(),
+): boolean {
+  return getSessionAutoCloseReason(session, timeoutMs, now) !== undefined;
+}
+
+export function getSessionPruneReason(
+  session: Pick<AcpSessionHandle | HealthMonitorable, "disposed" | "busy" | "lastResponseAt" | "completedAt">,
+  timeoutMs: number,
+  now = Date.now(),
+): "disposed" | SessionAutoCloseReason | undefined {
+  if (session.disposed) return "disposed";
+  return getSessionAutoCloseReason(session, timeoutMs, now);
+}

package/src/core/session-manager.ts

@@ -0,0 +1,64 @@
+/**
+ * pi-acp-agents — Session manager
+ *
+ * Simple add/get/remove/list/disposeAll for AcpSessionHandle objects.
+ */
+import type { AcpSessionHandle } from "../config/types.js";
+import { getSessionPruneReason } from "./session-lifecycle.js";
+
+export interface SessionPruneResult {
+  removedSessionIds: string[];
+}
+
+export class SessionManager {
+  private sessions = new Map<string, AcpSessionHandle>();
+
+  add(handle: AcpSessionHandle): void {
+    this.sessions.set(handle.sessionId, handle);
+  }
+
+  get(sessionId: string): AcpSessionHandle | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  list(): AcpSessionHandle[] {
+    return Array.from(this.sessions.values());
+  }
+
+  listByAgent(agentName?: string): AcpSessionHandle[] {
+    return this.list().filter((session) => !agentName || session.agentName === agentName);
+  }
+
+  async remove(sessionId: string): Promise<void> {
+    const handle = this.sessions.get(sessionId);
+    if (handle) {
+      try {
+        await handle.dispose();
+      } catch (err) {
+        console.error("[acp] dispose error:", err);
+      }
+      this.sessions.delete(sessionId);
+    }
+  }
+
+  async disposeAll(): Promise<void> {
+    const ids = Array.from(this.sessions.keys());
+    for (const id of ids) {
+      await this.remove(id);
+    }
+  }
+
+  async pruneStale(maxIdleMs: number, now = Date.now()): Promise<SessionPruneResult> {
+    const removedSessionIds: string[] = [];
+    for (const session of this.list()) {
+      if (!getSessionPruneReason(session, maxIdleMs, now)) continue;
+      removedSessionIds.push(session.sessionId);
+      await this.remove(session.sessionId);
+    }
+    return { removedSessionIds };
+  }
+
+  get size(): number {
+    return this.sessions.size;
+  }
+}