clawmatrix 0.2.6 → 0.2.8

package/src/acp-proxy.ts

@@ -8,7 +8,7 @@ import {
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig } from "./config.ts";
 import type { GatewayInfo } from "./tool-proxy.ts";
-import { spawnProcess, readFileText } from "./compat.ts";
+import { spawnProcess, readFileText, readFileHead, readFileTail } from "./compat.ts";
 import { debug } from "./debug.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -57,6 +57,29 @@ const DEFAULT_SESSION_TTL = 1_800_000;
 const DEFAULT_MAX_SESSIONS = 5;
 const CLEANUP_INTERVAL = 120_000;
 const SESSION_INIT_TIMEOUT = 60_000; // 60s timeout for ACP agent initialization
+const REUSE_POOL_TTL = 60_000; // keep oneshot sessions alive for 60s for reuse
+const PREWARM_DELAY = 5_000; // delay before prewarming after a session is used
+const DAEMON_IDLE_TTL = 300_000; // kill daemon after 5 min idle
+
+// ── Agent Daemon: long-lived process per agent type ─────────────
+
+/**
+ * A long-lived ACP agent process that stays alive across multiple sessions.
+ * Instead of spawning a new process per session, we reuse the same initialized
+ * connection and call newSession() which takes milliseconds vs seconds for a cold spawn.
+ */
+interface AgentDaemon {
+  agent: string;
+  cwd: string;
+  conn: ClientSideConnection;
+  proc: { kill: () => void; exited: Promise<number> };
+  /** Per-session stream callbacks keyed by ACP session ID */
+  streamCallbacks: Map<string, ((delta: string, event?: string) => void) | null>;
+  lastActiveAt: number;
+  idleTimer: ReturnType<typeof setTimeout>;
+  /** Set to true when process has exited */
+  dead: boolean;
+}
 
 // ── Session state on receiver side ───────────────────────────────
 
@@ -124,6 +147,17 @@ export class AcpProxy {
   private cleanupTimer: ReturnType<typeof setInterval> | null = null;
   // Multi-device sync: track which nodes are watching each session
   private sessionWatchers = new Map<string, Set<string>>();
+  // Session reuse pool: oneshot sessions kept alive briefly for reuse
+  private reusePool = new Map<string, { session: AcpSession; timer: ReturnType<typeof setTimeout> }>();
+  // Prewarm pool: pre-initialized ACP connections ready for immediate use
+  private warmPool = new Map<string, AcpSession[]>();
+  // Track pending prewarm timers so they can be cancelled on dispose
+  private prewarmTimers = new Set<ReturnType<typeof setTimeout>>();
+  private disposed = false;
+  // Agent daemon pool: long-lived process per agent type, reused across sessions
+  private daemons = new Map<string, AgentDaemon>();
+  // In-flight daemon acquisition: prevents multiple concurrent spawns for same agent
+  private daemonStarting = new Map<string, Promise<AgentDaemon>>();
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, openclawConfig?: Record<string, unknown>, gatewayInfo?: GatewayInfo) {
     this.config = config;
@@ -577,7 +611,7 @@ export class AcpProxy {
               });
             }
             if (mode === "oneshot" && task) {
-              this.destroySession(newSession);
+              this.returnToReusePool(newSession, cwd ?? process.cwd());
             }
           } else {
             // Re-create native session
@@ -637,7 +671,7 @@ export class AcpProxy {
             });
           }
           if (mode === "oneshot" && task) {
-            this.destroySession(session);
+            this.returnToReusePool(session, cwd ?? process.cwd());
           }
         } else {
           // Create new native OpenClaw session
@@ -871,6 +905,15 @@ export class AcpProxy {
       return;
     }
 
+    if (session.kind !== "acp") {
+      this.peerManager.sendTo(from, {
+        type: "acp_set_mode_res", id, from: this.config.nodeId, to: from,
+        timestamp: Date.now(),
+        payload: { success: false, error: "Mode switching not supported for native sessions" },
+      } satisfies AcpSetModeResponse);
+      return;
+    }
+
     try {
       await session.conn.setSessionMode({
         sessionId: session.acpSessionId,
@@ -910,8 +953,8 @@ export class AcpProxy {
       timestamp: Date.now(),
       payload: {
         success: true,
-        modes: session.availableModes,
-        currentModeId: session.currentModeId,
+        modes: session.kind === "acp" ? session.availableModes : undefined,
+        currentModeId: session.kind === "acp" ? session.currentModeId : undefined,
       },
     } satisfies AcpGetModesResponse);
   }
@@ -1022,17 +1065,17 @@ export class AcpProxy {
               const sessionsDir = join(agentsDir, agentId, "sessions");
               if (entry.sessionFile) {
                 const candidate = join(sessionsDir, entry.sessionFile);
-                try { await readFileText(candidate); return candidate; } catch { /* try default */ }
+                try { await access(candidate); return candidate; } catch { /* try default */ }
               }
               const candidate = join(sessionsDir, `${sessionId}.jsonl`);
-              try { await readFileText(candidate); return candidate; } catch { /* continue */ }
+              try { await access(candidate); return candidate; } catch { /* continue */ }
             }
           }
         } catch { /* store unreadable */ }
 
         // Fallback: try direct file path
         const candidate = join(agentsDir, agentId, "sessions", `${sessionId}.jsonl`);
-        try { await readFileText(candidate); return candidate; } catch { /* next agent */ }
+        try { await access(candidate); return candidate; } catch { /* next agent */ }
       }
     } catch { /* no agents directory */ }
 
@@ -1049,16 +1092,282 @@ export class AcpProxy {
     return null;
   }
 
+  // ── Internal: agent daemon pool ─────────────────────────────────
+
+  /**
+   * Get or create a long-lived daemon for the given agent.
+   * The daemon process stays alive and its initialized connection is reused
+   * for all subsequent newSession() calls — eliminating spawn+init overhead.
+   */
+  private async getOrCreateDaemon(agent: string, cwd: string): Promise<AgentDaemon> {
+    const key = `${agent}:${cwd}`;
+    // Return existing healthy daemon for this agent+cwd
+    const existing = this.daemons.get(key);
+    if (existing && !existing.dead) {
+      existing.lastActiveAt = Date.now();
+      this.resetDaemonIdleTimer(existing);
+      return existing;
+    }
+
+    // Prevent concurrent spawns for the same agent+cwd
+    const inflight = this.daemonStarting.get(key);
+    if (inflight) return inflight;
+
+    const promise = this.spawnDaemon(agent, cwd);
+    this.daemonStarting.set(key, promise);
+    try {
+      const daemon = await promise;
+      return daemon;
+    } finally {
+      this.daemonStarting.delete(key);
+    }
+  }
+
+  private async spawnDaemon(agent: string, cwd: string): Promise<AgentDaemon> {
+    const streamCallbacks = new Map<string, ((delta: string, event?: string) => void) | null>();
+
+    const { conn, proc } = await this.spawnAndInit(agent, cwd, "spawnDaemon", (params) => {
+      const acpSessionId = (params as unknown as { sessionId?: string }).sessionId;
+      if (!acpSessionId) {
+        debug("acp", `[${agent}:daemon] sessionUpdate missing sessionId, cannot route`);
+        return null;
+      }
+      return streamCallbacks.get(acpSessionId) ?? null;
+    });
+
+    debug("acp", `[${agent}] daemon initialized`);
+
+    const key = `${agent}:${cwd}`;
+    const daemon: AgentDaemon = {
+      agent,
+      cwd,
+      conn,
+      proc,
+      streamCallbacks,
+      lastActiveAt: Date.now(),
+      idleTimer: setTimeout(() => {}, 0), // placeholder, reset below
+      dead: false,
+    };
+
+    // Monitor process exit — clean up daemon and any sessions using its connection
+    const onDaemonExit = () => {
+      daemon.dead = true;
+      // Only remove from map if this daemon hasn't been replaced by a new one
+      if (this.daemons.get(key) === daemon) this.daemons.delete(key);
+      // Clean up sessions that were using this daemon's connection
+      for (const [sid, s] of this.sessions) {
+        if (s.kind === "acp" && s.conn === daemon.conn) {
+          this.sessions.delete(sid);
+          debug("acp", `daemon exited: cleaned up session ${sid} (agent=${daemon.agent})`);
+        }
+      }
+    };
+    proc.exited.then(onDaemonExit).catch(onDaemonExit);
+
+    this.resetDaemonIdleTimer(daemon);
+    this.daemons.set(key, daemon);
+    return daemon;
+  }
+
+  private resetDaemonIdleTimer(daemon: AgentDaemon) {
+    clearTimeout(daemon.idleTimer);
+    daemon.idleTimer = setTimeout(() => {
+      if (daemon.dead) return;
+      // Only kill if no active sessions are using this daemon
+      const hasActiveSessions = [...this.sessions.values()].some(
+        (s) => s.kind === "acp" && s.agent === daemon.agent && s.conn === daemon.conn,
+      );
+      if (!hasActiveSessions) {
+        debug("acp", `daemon idle timeout: killing ${daemon.agent} (cwd=${daemon.cwd})`);
+        daemon.dead = true;
+        this.daemons.delete(`${daemon.agent}:${daemon.cwd}`);
+        try { daemon.proc.kill(); } catch { /* best effort */ }
+      } else {
+        // Sessions still active, reschedule
+        this.resetDaemonIdleTimer(daemon);
+      }
+    }, DAEMON_IDLE_TTL);
+  }
+
+  /**
+   * Create a new ACP session using the daemon's long-lived connection.
+   * Falls back to spawnAndConnect if daemon is unavailable.
+   */
+  private async createSessionViaDaemon(
+    agent: string,
+    cwd: string,
+    from: string,
+  ): Promise<AcpSession> {
+    const daemon = await this.getOrCreateDaemon(agent, cwd);
+
+    const response = await daemon.conn.newSession({ cwd, mcpServers: [] });
+    debug("acp", `[${agent}] daemon session created: ${response.sessionId}`);
+
+    const availableModes: AcpModeInfo[] | undefined = response.modes?.availableModes?.map(
+      (m) => ({ id: m.id, name: m.name, description: m.description ?? undefined }),
+    );
+
+    const session: AcpSession = {
+      kind: "acp",
+      sessionId: crypto.randomUUID(),
+      agent,
+      acpSessionId: response.sessionId,
+      conn: daemon.conn,
+      proc: daemon.proc,
+      lastActiveAt: Date.now(),
+      from,
+      setStreamCallback: (cb) => {
+        daemon.streamCallbacks.set(response.sessionId, cb);
+      },
+      availableModes,
+      currentModeId: response.modes?.currentModeId,
+    };
+
+    return session;
+  }
+
+  // ── Internal: session reuse & prewarming ─────────────────────────
+
+  /** Try to grab a reusable session from the reuse pool (same agent, same cwd). */
+  private takeFromReusePool(agent: string, cwd: string): AcpSession | null {
+    const key = `${agent}:${cwd}`;
+    const entry = this.reusePool.get(key);
+    if (!entry) return null;
+    this.reusePool.delete(key);
+    clearTimeout(entry.timer);
+    debug("acp", `reuse pool hit: agent=${agent} cwd=${cwd} sessionId=${entry.session.sessionId}`);
+    return entry.session;
+  }
+
+  /** Find the daemon that owns this session's connection (if any). */
+  private findDaemonByConn(session: AcpSession): AgentDaemon | null {
+    // Fast path: check the exact agent+cwd key
+    for (const daemon of this.daemons.values()) {
+      if (daemon.conn === session.conn) return daemon;
+    }
+    return null;
+  }
+
+  /** Return a completed oneshot session to the reuse pool instead of destroying it. */
+  private returnToReusePool(session: AcpSession, cwd: string) {
+    // Daemon-backed sessions don't need reuse pool — the daemon stays alive
+    const daemon = this.findDaemonByConn(session);
+    if (daemon) {
+      daemon.streamCallbacks.delete(session.acpSessionId);
+      debug("acp", `daemon-backed oneshot done: agent=${session.agent} (daemon stays alive)`);
+      return;
+    }
+
+    const key = `${session.agent}:${cwd}`;
+    // Evict any existing entry for the same key
+    const existing = this.reusePool.get(key);
+    if (existing) {
+      clearTimeout(existing.timer);
+      this.destroySession(existing.session);
+    }
+    const timer = setTimeout(() => {
+      const entry = this.reusePool.get(key);
+      if (entry?.session.sessionId === session.sessionId) {
+        this.reusePool.delete(key);
+        this.destroySession(session);
+        debug("acp", `reuse pool expired: agent=${session.agent} cwd=${cwd}`);
+      }
+    }, REUSE_POOL_TTL);
+    this.reusePool.set(key, { session, timer });
+    debug("acp", `reuse pool stored: agent=${session.agent} cwd=${cwd} ttl=${REUSE_POOL_TTL / 1000}s`);
+  }
+
+  /** Try to grab a pre-warmed session from the warm pool (same agent + cwd). */
+  private takeFromWarmPool(agent: string, cwd: string): AcpSession | null {
+    const key = `${agent}:${cwd}`;
+    const pool = this.warmPool.get(key);
+    if (!pool || pool.length === 0) return null;
+    const session = pool.shift()!;
+    debug("acp", `warm pool hit: agent=${agent} cwd=${cwd} sessionId=${session.sessionId}`);
+    return session;
+  }
+
+  /** Schedule a prewarm for the given agent after a short delay. */
+  private schedulePrewarm(agent: string, cwd: string) {
+    const timer = setTimeout(async () => {
+      this.prewarmTimers.delete(timer);
+      if (this.disposed) return;
+      // Only prewarm if the warm pool is empty for this agent+cwd
+      const key = `${agent}:${cwd}`;
+      const pool = this.warmPool.get(key);
+      if (pool && pool.length > 0) return;
+      try {
+        debug("acp", `prewarming agent=${agent} cwd=${cwd}`);
+        const session = await this.spawnAndInitSession(agent, cwd, "prewarm");
+        if (this.disposed) { this.destroySession(session); return; }
+        if (!this.warmPool.has(key)) this.warmPool.set(key, []);
+        this.warmPool.get(key)!.push(session);
+        debug("acp", `warm pool ready: agent=${agent} sessionId=${session.sessionId}`);
+      } catch (err) {
+        debug("acp", `prewarm failed: agent=${agent} error=${errorMessage(err)}`);
+      }
+    }, PREWARM_DELAY);
+    this.prewarmTimers.add(timer);
+  }
+
   // ── Internal: ACP session management (receiver) ────────────────
 
   private async createSession(agent: string, cwd: string | undefined, from: string): Promise<AcpSession> {
-    const cmd = this.resolveCommand(agent);
     const effectiveCwd = cwd ?? process.cwd();
 
-    debug("acp", `createSession: spawning ${cmd.join(" ")} in ${effectiveCwd} (for ${from})`);
+    // 1. Try daemon pool first (long-lived process, instant newSession)
+    try {
+      return await this.createSessionViaDaemon(agent, effectiveCwd, from);
+    } catch (err) {
+      debug("acp", `daemon session failed for ${agent}: ${errorMessage(err)}, falling back`);
+    }
+
+    // 2. Check reuse pool (same agent + cwd, still alive)
+    const reused = this.takeFromReusePool(agent, effectiveCwd);
+    if (reused) {
+      reused.from = from;
+      reused.lastActiveAt = Date.now();
+      reused.sessionId = crypto.randomUUID();
+      this.monitorProcess(reused);
+      return reused;
+    }
+
+    // 3. Check warm pool (pre-initialized, same agent + cwd)
+    const warm = this.takeFromWarmPool(agent, effectiveCwd);
+    if (warm) {
+      warm.from = from;
+      warm.lastActiveAt = Date.now();
+      warm.sessionId = crypto.randomUUID();
+      this.monitorProcess(warm);
+      this.schedulePrewarm(agent, effectiveCwd);
+      return warm;
+    }
+
+    // 4. Cold start: spawn + initialize (last resort)
+    const session = await this.spawnAndInitSession(agent, effectiveCwd, from);
+    this.schedulePrewarm(agent, effectiveCwd);
+    return session;
+  }
+
+  /**
+   * Spawn an ACP agent process, set up NDJSON/stdio, and initialize the ACP connection.
+   * Returns the initialized connection and process handle.
+   * Shared by spawnDaemon (daemon pool) and spawnAndConnect (per-session).
+   *
+   * @param resolveStreamCb Called on each sessionUpdate to resolve the stream callback.
+   *   For daemons this routes by ACP session ID; for per-session it returns a closure variable.
+   */
+  private async spawnAndInit(
+    agent: string,
+    cwd: string,
+    label: string,
+    resolveStreamCb: (params: SessionNotification) => ((delta: string, event?: string) => void) | null | undefined,
+  ): Promise<{ conn: ClientSideConnection; proc: { kill: () => void; exited: Promise<number> } }> {
+    const cmd = this.resolveCommand(agent);
+    debug("acp", `${label}: spawning ${cmd.join(" ")} in ${cwd}`);
 
     const proc = spawnProcess(cmd, {
-      cwd: effectiveCwd,
+      cwd,
       stdout: "pipe",
       stderr: "pipe",
       stdin: "pipe",
@@ -1069,7 +1378,7 @@ export class AcpProxy {
       throw new Error(`Failed to spawn ACP agent "${agent}": no stdio streams`);
     }
 
-    // Capture stderr for diagnostics (agent errors, missing API keys, etc.)
+    // Capture stderr for diagnostics
     if (proc.stderr) {
       const reader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
       const decoder = new TextDecoder();
@@ -1085,19 +1394,14 @@ export class AcpProxy {
       })();
     }
 
-    // Detect early process exit (e.g., npx not found, package install failure)
     let earlyExit = false;
     const earlyExitPromise = proc.exited.then((code) => {
       earlyExit = true;
       throw new Error(`ACP agent "${agent}" exited during init with code ${code}`);
     });
 
-    // Build ACP connection over NDJSON/stdio
     const stream = ndJsonStream(proc.stdin, proc.stdout);
 
-    // Accumulated text for streaming back — set per-prompt via closure
-    let streamCallback: ((delta: string, event?: string) => void) | null = null;
-
     const conn = new ClientSideConnection(
       (_agentRef) => ({
         requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
@@ -1106,23 +1410,21 @@ export class AcpProxy {
         sessionUpdate: async (params: SessionNotification): Promise<void> => {
           const update = params.update as Record<string, unknown>;
           const updateType = update.sessionUpdate as string;
-
-          // Extract text delta from content chunks
+          const cb = resolveStreamCb(params);
           if (updateType === "agent_message_chunk" || updateType === "agent_thought_chunk") {
             const content = (update as { content?: { type?: string; text?: string } }).content;
             if (content?.type === "text" && content.text) {
-              streamCallback?.(content.text, updateType);
+              cb?.(content.text, updateType);
             }
           } else if (updateType === "tool_call") {
             const toolName = (update as { title?: string }).title
               || (update as { toolCallId?: string }).toolCallId
               || "unknown";
-            debug("acp", `tool_call update: title=${JSON.stringify((update as any).title)} toolCallId=${JSON.stringify((update as any).toolCallId)} keys=${Object.keys(update).join(",")}`);
-            streamCallback?.(`\n[tool_call: ${toolName}]\n`, updateType);
+            cb?.(`\n[tool_call: ${toolName}]\n`, updateType);
           } else if (updateType === "tool_call_update") {
             const status = (update as { status?: string }).status;
             if (status === "completed" || status === "error") {
-              streamCallback?.("", "tool_result");
+              cb?.("", "tool_result");
             }
           }
         },
@@ -1130,74 +1432,86 @@ export class AcpProxy {
       stream,
     );
 
-    // Initialize with timeout — prevents hanging if agent process is stuck
+    let initTimer: ReturnType<typeof setTimeout>;
     const initTimeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error(
+      initTimer = setTimeout(() => reject(new Error(
         `ACP agent "${agent}" initialization timed out after ${SESSION_INIT_TIMEOUT / 1000}s`,
       )), SESSION_INIT_TIMEOUT);
     });
 
-    const initAndSession = async () => {
-      // Initialize the ACP connection
-      debug("acp", `[${agent}] initializing ACP connection...`);
-      await conn.initialize({
-        protocolVersion: 1,
-        clientInfo: { name: "ClawMatrix", version: "0.1.0" },
-        clientCapabilities: {},
-      });
-      debug("acp", `[${agent}] ACP connection initialized, creating session...`);
-
-      // Create a new session
-      return conn.newSession({
-        cwd: effectiveCwd,
-        mcpServers: [],
-      });
-    };
-
-    let sessionResponse: Awaited<ReturnType<typeof conn.newSession>>;
     try {
-      sessionResponse = await Promise.race([
-        initAndSession(),
+      await Promise.race([
+        conn.initialize({
+          protocolVersion: 1,
+          clientInfo: { name: "ClawMatrix", version: "0.1.0" },
+          clientCapabilities: {},
+        }),
         initTimeout,
         earlyExitPromise as Promise<never>,
       ]);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : (typeof err === "string" ? err : JSON.stringify(err));
-      debug("acp", `[${agent}] init failed: ${msg}`);
-      // Kill the process if init failed
       if (!earlyExit) proc.kill();
-      throw new Error(`ACP agent "${agent}" init failed: ${msg}`);
+      throw err;
+    } finally {
+      clearTimeout(initTimer!);
+    }
+
+    return { conn, proc };
+  }
+
+  /**
+   * Spawn an ACP agent, initialize, then call `sessionFactory` to create/resume the session.
+   * Used for per-session (non-daemon) spawns.
+   */
+  private async spawnAndConnect(
+    agent: string,
+    cwd: string,
+    from: string,
+    label: string,
+    sessionFactory: (conn: ClientSideConnection, cwd: string) => Promise<{ sessionId: string; modes?: { availableModes?: Array<{ id: string; name: string; description?: string }>; currentModeId?: string } }>,
+  ): Promise<AcpSession> {
+    let streamCallback: ((delta: string, event?: string) => void) | null = null;
+
+    const { conn, proc } = await this.spawnAndInit(agent, cwd, label, () => streamCallback);
+
+    let response: Awaited<ReturnType<typeof sessionFactory>>;
+    try {
+      response = await sessionFactory(conn, cwd);
+    } catch (err) {
+      proc.kill();
+      throw err;
     }
-    debug("acp", `[${agent}] session created: ${sessionResponse.sessionId}`);
+    debug("acp", `[${agent}] session ready: ${response.sessionId}`);
 
-    // Extract available modes from session response
-    const availableModes: AcpModeInfo[] | undefined = sessionResponse.modes?.availableModes?.map(
+    const availableModes: AcpModeInfo[] | undefined = response.modes?.availableModes?.map(
       (m) => ({ id: m.id, name: m.name, description: m.description ?? undefined }),
     );
-    const currentModeId = sessionResponse.modes?.currentModeId;
-
-    const sessionId = crypto.randomUUID();
 
     const session: AcpSession = {
       kind: "acp",
-      sessionId,
+      sessionId: crypto.randomUUID(),
       agent,
-      acpSessionId: sessionResponse.sessionId,
+      acpSessionId: response.sessionId,
       conn,
       proc,
       lastActiveAt: Date.now(),
       from,
       setStreamCallback: (cb) => { streamCallback = cb; },
       availableModes,
-      currentModeId,
+      currentModeId: response.modes?.currentModeId,
     };
 
-    // Monitor process exit — clean up dead sessions proactively
     this.monitorProcess(session);
-
     return session;
   }
 
+  /** Spawn a new ACP agent process, initialize ACP connection, and create a session. */
+  private spawnAndInitSession(agent: string, cwd: string, from: string): Promise<AcpSession> {
+    return this.spawnAndConnect(agent, cwd, from, "spawnAndInitSession", (conn, effectiveCwd) =>
+      conn.newSession({ cwd: effectiveCwd, mcpServers: [] }),
+    );
+  }
+
   /** Watch for unexpected process exit and clean up the session. */
   private monitorProcess(session: AcpSession) {
     session.proc.exited.then(() => {
@@ -1386,7 +1700,7 @@ export class AcpProxy {
 
     const reader = body.getReader();
     const decoder = new TextDecoder();
-    let full = "";
+    const chunks: string[] = [];
     let buffer = "";
 
     try {
@@ -1407,7 +1721,7 @@ export class AcpProxy {
             const parsed = JSON.parse(data);
             const delta = parsed.choices?.[0]?.delta?.content;
             if (delta) {
-              full += delta;
+              chunks.push(delta);
               const streamFrame: AcpStreamChunk = {
                 type: "acp_stream",
                 id: requestId,
@@ -1428,141 +1742,19 @@ export class AcpProxy {
       reader.releaseLock();
     }
 
-    return full;
+    return chunks.join("");
   }
 
   /** Create a session by resuming an existing ACP session ID. */
-  private async createSessionWithResume(
+  private createSessionWithResume(
     agent: string,
     acpSessionId: string,
     cwd: string,
     from: string,
   ): Promise<AcpSession> {
-    const cmd = this.resolveCommand(agent);
-    debug("acp", `createSessionWithResume: spawning ${cmd.join(" ")} in ${cwd} (resume ${acpSessionId.slice(0, 8)}...)`);
-
-    const proc = spawnProcess(cmd, {
-      cwd,
-      stdout: "pipe",
-      stderr: "pipe",
-      stdin: "pipe",
-    });
-
-    if (!proc.stdin || !proc.stdout) {
-      proc.kill();
-      throw new Error(`Failed to spawn ACP agent "${agent}": no stdio streams`);
-    }
-
-    // Capture stderr for diagnostics
-    if (proc.stderr) {
-      const reader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
-      const decoder = new TextDecoder();
-      (async () => {
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            const text = decoder.decode(value, { stream: true }).trim();
-            if (text) debug("acp", `[${agent}:stderr] ${text}`);
-          }
-        } catch { /* stream closed */ }
-      })();
-    }
-
-    let earlyExit = false;
-    const earlyExitPromise = proc.exited.then((code) => {
-      earlyExit = true;
-      throw new Error(`ACP agent "${agent}" exited during resume init with code ${code}`);
-    });
-
-    const stream = ndJsonStream(proc.stdin, proc.stdout);
-    let streamCallback: ((delta: string, event?: string) => void) | null = null;
-
-    const conn = new ClientSideConnection(
-      (_agentRef) => ({
-        requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
-          return this.resolvePermission(params);
-        },
-        sessionUpdate: async (params: SessionNotification): Promise<void> => {
-          const update = params.update as Record<string, unknown>;
-          const updateType = update.sessionUpdate as string;
-          if (updateType === "agent_message_chunk" || updateType === "agent_thought_chunk") {
-            const content = (update as { content?: { type?: string; text?: string } }).content;
-            if (content?.type === "text" && content.text) {
-              streamCallback?.(content.text, updateType);
-            }
-          } else if (updateType === "tool_call") {
-            const toolName = (update as { title?: string }).title
-              || (update as { toolCallId?: string }).toolCallId
-              || "unknown";
-            debug("acp", `tool_call update: title=${JSON.stringify((update as any).title)} toolCallId=${JSON.stringify((update as any).toolCallId)} keys=${Object.keys(update).join(",")}`);
-            streamCallback?.(`\n[tool_call: ${toolName}]\n`, updateType);
-          } else if (updateType === "tool_call_update") {
-            const status = (update as { status?: string }).status;
-            if (status === "completed" || status === "error") {
-              streamCallback?.("", "tool_result");
-            }
-          }
-        },
-      }),
-      stream,
+    return this.spawnAndConnect(agent, cwd, from, "createSessionWithResume", (conn) =>
+      conn.unstable_resumeSession({ sessionId: acpSessionId, cwd }),
     );
-
-    const initTimeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error(
-        `ACP agent "${agent}" resume initialization timed out after ${SESSION_INIT_TIMEOUT / 1000}s`,
-      )), SESSION_INIT_TIMEOUT);
-    });
-
-    const initAndResume = async () => {
-      await conn.initialize({
-        protocolVersion: 1,
-        clientInfo: { name: "ClawMatrix", version: "0.1.0" },
-        clientCapabilities: {},
-      });
-
-      // Resume the existing ACP session instead of creating a new one
-      return conn.unstable_resumeSession({
-        sessionId: acpSessionId,
-        cwd,
-      });
-    };
-
-    let resumeResponse: Awaited<ReturnType<typeof conn.unstable_resumeSession>>;
-    try {
-      resumeResponse = await Promise.race([
-        initAndResume(),
-        initTimeout,
-        earlyExitPromise as Promise<never>,
-      ]);
-    } catch (err) {
-      if (!earlyExit) proc.kill();
-      throw err;
-    }
-
-    const availableModes: AcpModeInfo[] | undefined = resumeResponse.modes?.availableModes?.map(
-      (m) => ({ id: m.id, name: m.name, description: m.description ?? undefined }),
-    );
-    const currentModeId = resumeResponse.modes?.currentModeId;
-
-    const sessionId = crypto.randomUUID();
-
-    const session: AcpSession = {
-      kind: "acp",
-      sessionId,
-      agent,
-      acpSessionId,
-      conn,
-      proc,
-      lastActiveAt: Date.now(),
-      from,
-      setStreamCallback: (cb) => { streamCallback = cb; },
-      availableModes,
-      currentModeId,
-    };
-
-    this.monitorProcess(session);
-    return session;
   }
 
   /** Read all session stores from disk (OpenClaw + Claude Code). */
@@ -1571,7 +1763,16 @@ export class AcpProxy {
   }
 
   private destroySession(session: AnySession) {
+    invalidateSessionListCache();
     if (session.kind === "acp") {
+      // Clean up daemon stream callback
+      const daemon = this.findDaemonByConn(session);
+      if (daemon) {
+        daemon.streamCallbacks.delete(session.acpSessionId);
+        // Don't kill — process is shared by the daemon
+        return;
+      }
+      // Not a daemon-backed session — kill the process
       try {
         session.proc.kill();
       } catch {
@@ -1614,7 +1815,7 @@ export class AcpProxy {
   }
 
   /** Built-in ACP agent commands (same as OpenClaw's acpx backend). */
-  private static readonly BUILTIN_ACP_COMMANDS: Record<string, string[]> = {
+  static readonly BUILTIN_ACP_COMMANDS: Record<string, string[]> = {
     claude: ["npx", "-y", "@zed-industries/claude-agent-acp"],
     codex: ["npx", "-y", "@zed-industries/codex-acp"],
     gemini: ["gemini"],
@@ -1622,6 +1823,69 @@ export class AcpProxy {
     pi: ["npx", "-y", "pi-acp"],
   };
 
+  /** Human-readable descriptions for built-in ACP agents. */
+  private static readonly BUILTIN_ACP_DESCRIPTIONS: Record<string, string> = {
+    claude: "Claude Code",
+    codex: "OpenAI Codex CLI",
+    gemini: "Gemini CLI",
+    opencode: "OpenCode",
+    pi: "Pi",
+  };
+
+  /** Binary names to check for each agent (may differ from agent id). */
+  private static readonly AGENT_BINARY_NAMES: Record<string, string> = {
+    claude: "claude",
+    codex: "codex",
+    gemini: "gemini",
+    opencode: "opencode",
+    pi: "pi",
+  };
+
+  /**
+   * Auto-detect which ACP agents are installed by checking if their binaries
+   * exist in PATH. Also checks config-defined custom commands.
+   */
+  static async detectAvailableAgents(
+    configCommands?: Record<string, string[]>,
+  ): Promise<import("./types.ts").AcpAgentInfo[]> {
+    const detected: import("./types.ts").AcpAgentInfo[] = [];
+    const whichCmd = process.platform === "win32" ? "where.exe" : "which";
+
+    // Check built-in agents
+    const checks = Object.keys(AcpProxy.BUILTIN_ACP_COMMANDS).map(async (agent) => {
+      const binary = AcpProxy.AGENT_BINARY_NAMES[agent] ?? agent;
+      try {
+        const proc = spawnProcess([whichCmd, binary], { stdout: "ignore", stderr: "ignore" });
+        const code = await proc.exited;
+        if (code === 0) {
+          detected.push({
+            id: agent,
+            description: AcpProxy.BUILTIN_ACP_DESCRIPTIONS[agent] ?? agent,
+          });
+        }
+      } catch { /* binary not found */ }
+    });
+
+    // Check custom config commands
+    if (configCommands) {
+      for (const [agent, cmd] of Object.entries(configCommands)) {
+        if (agent in AcpProxy.BUILTIN_ACP_COMMANDS) continue; // already checked above
+        checks.push((async () => {
+          try {
+            const proc = spawnProcess([whichCmd, cmd[0]!], { stdout: "ignore", stderr: "ignore" });
+            const code = await proc.exited;
+            if (code === 0) {
+              detected.push({ id: agent, description: agent });
+            }
+          } catch { /* binary not found */ }
+        })());
+      }
+    }
+
+    await Promise.all(checks);
+    return detected;
+  }
+
   private resolveCommand(agent: string): string[] {
     // Check config overrides first
     const commands = this.config.acp?.commands;
@@ -1781,6 +2045,36 @@ export class AcpProxy {
     }
     this.sessions.clear();
     this.sessionWatchers.clear();
+
+    this.disposed = true;
+
+    // Cancel pending prewarm timers
+    for (const timer of this.prewarmTimers) clearTimeout(timer);
+    this.prewarmTimers.clear();
+
+    // Clean up reuse pool
+    for (const [, entry] of this.reusePool) {
+      clearTimeout(entry.timer);
+      this.destroySession(entry.session);
+    }
+    this.reusePool.clear();
+
+    // Clean up warm pool
+    for (const [, pool] of this.warmPool) {
+      for (const session of pool) {
+        this.destroySession(session);
+      }
+    }
+    this.warmPool.clear();
+
+    // Clean up daemons
+    for (const [, daemon] of this.daemons) {
+      clearTimeout(daemon.idleTimer);
+      daemon.dead = true;
+      try { daemon.proc.kill(); } catch { /* best effort */ }
+    }
+    this.daemons.clear();
+    this.daemonStarting.clear();
   }
 }
 
@@ -1792,9 +2086,7 @@ const TRANSCRIPT_MAX_LINES = 20;
 /** Read the first user message from a session transcript JSONL file. */
 async function readFirstUserMessageFromTranscript(transcriptPath: string): Promise<string | null> {
   try {
-    const content = await readFileText(transcriptPath);
-    // Only scan the head to avoid reading large transcripts
-    const head = content.slice(0, TRANSCRIPT_HEAD_BYTES);
+    const head = await readFileHead(transcriptPath, TRANSCRIPT_HEAD_BYTES);
     const lines = head.split("\n").slice(0, TRANSCRIPT_MAX_LINES);
     for (const line of lines) {
       if (!line.trim()) continue;
@@ -1820,8 +2112,56 @@ async function readFirstUserMessageFromTranscript(transcriptPath: string): Promi
   return null;
 }
 
+// ── Session list cache (stale-while-revalidate) ─────────────────────
+const SESSION_LIST_CACHE_TTL = 30_000; // 30 seconds fresh
+const SESSION_LIST_STALE_TTL = 120_000; // serve stale up to 2 min while refreshing
+let sessionListCache: { result: AcpSessionInfo[]; expiresAt: number; staleAt: number } | null = null;
+let sessionListRefreshing = false;
+
+/** Invalidate the session list cache so the next call re-reads from disk. */
+export function invalidateSessionListCache() {
+  sessionListCache = null;
+}
+
+/** Refresh session list in background (stale-while-revalidate). */
+async function refreshSessionListInBackground() {
+  if (sessionListRefreshing) return;
+  sessionListRefreshing = true;
+  try {
+    const result = await fetchSessionListFromDisk();
+    const now = Date.now();
+    sessionListCache = { result, expiresAt: now + SESSION_LIST_CACHE_TTL, staleAt: now + SESSION_LIST_STALE_TTL };
+  } catch {
+    // Background refresh failed — keep stale data
+  } finally {
+    sessionListRefreshing = false;
+  }
+}
+
 /** Read all ACP session stores from disk (OpenClaw + Claude Code). Can be used without an AcpProxy instance. */
 export async function readAllSessionStoresFromDisk(): Promise<AcpSessionInfo[]> {
+  const now = Date.now();
+  if (sessionListCache) {
+    if (now < sessionListCache.expiresAt) {
+      // Fresh cache — return immediately
+      return sessionListCache.result;
+    }
+    if (now < sessionListCache.staleAt) {
+      // Stale but within grace period — return stale data, refresh in background
+      refreshSessionListInBackground();
+      return sessionListCache.result;
+    }
+  }
+
+  // Cache miss or expired — fetch from disk and cache
+  const results = await fetchSessionListFromDisk();
+  const ts = Date.now();
+  sessionListCache = { result: results, expiresAt: ts + SESSION_LIST_CACHE_TTL, staleAt: ts + SESSION_LIST_STALE_TTL };
+  return results;
+}
+
+/** Fetch session list from disk (no caching). */
+async function fetchSessionListFromDisk(): Promise<AcpSessionInfo[]> {
   const results: AcpSessionInfo[] = [];
 
   // 1. OpenClaw agent session stores (ACP-backed + native OpenClaw sessions)
@@ -1835,20 +2175,22 @@ export async function readAllSessionStoresFromDisk(): Promise<AcpSessionInfo[]>
       try {
         const content = await readFileText(storePath);
         const entries: Record<string, { sessionId?: string; updatedAt?: number; displayName?: string; subject?: string; label?: string; acp?: { agent?: string } }> = JSON.parse(content);
-        for (const [key, entry] of Object.entries(entries)) {
-          if (!entry.sessionId) continue;
-          // Use the OpenClaw agent directory name, not the ACP backend agent.
-          // A cron/handoff session using Claude Code as backend is still an OpenClaw session.
-          // Pure Claude Code sessions are read separately from ~/.claude/history.jsonl.
-          const agent = agentId;
-          // Try to read the first user message from the transcript for description
-          const transcriptPath = join(sessionsDir, `${entry.sessionId}.jsonl`);
-          const firstMessage = await readFirstUserMessageFromTranscript(transcriptPath);
+        const agent = agentId;
+        // Read all transcripts in parallel instead of sequentially
+        const entryList = Object.entries(entries).filter(([, e]) => e.sessionId);
+        const transcriptResults = await Promise.all(
+          entryList.map(([, entry]) => {
+            const transcriptPath = join(sessionsDir, `${entry.sessionId!}.jsonl`);
+            return readFirstUserMessageFromTranscript(transcriptPath);
+          }),
+        );
+        for (let i = 0; i < entryList.length; i++) {
+          const [key, entry] = entryList[i]!;
           results.push({
-            sessionId: entry.sessionId,
+            sessionId: entry.sessionId!,
             cwd: key,
             title: entry.displayName ?? entry.subject ?? entry.label ?? undefined,
-            description: firstMessage ?? undefined,
+            description: transcriptResults[i] ?? undefined,
             updatedAt: entry.updatedAt ? new Date(entry.updatedAt).toISOString() : undefined,
             agent,
           });
@@ -1862,9 +2204,11 @@ export async function readAllSessionStoresFromDisk(): Promise<AcpSessionInfo[]>
   }
 
   // 2. Claude Code session history (~/.claude/history.jsonl)
+  // Only read the last 512KB — newer entries are appended at the end,
+  // so the tail contains the most recent sessions.
   try {
     const historyPath = join(homedir(), ".claude", "history.jsonl");
-    const content = await readFileText(historyPath);
+    const content = await readFileTail(historyPath, 512 * 1024);
     const sessions = new Map<string, { title: string; updatedAt: number; cwd: string }>();
 
     for (const line of content.split("\n")) {